diff --git a/.github/ROADMAP.md b/.github/ROADMAP.md
index ef2a984e5..1e0b3612e 100644
--- a/.github/ROADMAP.md
+++ b/.github/ROADMAP.md
@@ -2,7 +2,7 @@
 
 This document tracks planned features and upcoming releases across the nSelf ecosystem. It is updated after each sprint cycle.
 
-**Current version:** v1.0.11 LTS  
+**Current version:** see the latest release on GitHub.  
 **Legend:** ✅ Done | 🚧 In Progress | 🔲 Planned | 🚫 Deferred
 
 ---
@@ -14,8 +14,6 @@ Target: Q2 2026
 | Feature | Repo | Status | Notes |
 |---------|------|--------|-------|
 | nFamily social app | nfamily | 🔲 Planned | Family social media, private; bundle $0.99/mo |
-| ClawDE bundle launch | clawde | 🔲 Planned | cloud sync, mobile twin, team features at $0.99/mo |
-| nTV full media server | ntv | 🔲 Planned | Full media server + multi-platform (Roku, Apple TV, Android TV) |
 | Admin multi-user support | admin | 🔲 Planned | Multi-operator via `NSELF_ADMIN_MULTIUSER`. Single-operator in v1.x |
 | nCloud managed hosting | web/cloud | 🔲 Planned | Dedicated Hetzner VPS, $2/mo margin + at-cost infra |
 | Plugin SDK public release | cli/sdk | 🔲 Planned | plugin-sdk-go + plugin-sdk-ts as standalone packages |
diff --git a/.github/scripts/check-doc-commands.sh b/.github/scripts/check-doc-commands.sh
new file mode 100755
index 000000000..7b89103cc
--- /dev/null
+++ b/.github/scripts/check-doc-commands.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+# Usage: bash .github/scripts/check-doc-commands.sh <page.md>...
+exec env CGO_ENABLED=0 GOFLAGS=-mod=vendor DOCCMDS_CALLER_DIR="$PWD" \
+  go -C "$(dirname "$0")/../../free/ci" run ./tools/doccmds "$@"
diff --git a/.github/truth/repo.yaml b/.github/truth/repo.yaml
new file mode 100644
index 000000000..e60ca8728
--- /dev/null
+++ b/.github/truth/repo.yaml
@@ -0,0 +1,18 @@
+# plugins truth rules (planned configuration, Epic TRUTH D17; draft by P7-TRUTH-04, copied by the sweep Ticket P7-TRUTH-10, P7-TRUTH-32).
+# Includes the vendored org and claim rules (scripts/truth/vendor-rules.sh) and exempts, with a reason,
+# every path the sweep Tickets do not own. The sweep Tickets delete an exemption as they fix its file.
+version: 1
+include: [.github/truth/org.yaml, .github/truth/claims.yaml]
+allow:
+  - rule: "*"
+    paths: [".github/RELEASE-v*.md", "**/CHANGELOG*", "**/Changelog*"]
+    reason: "release notes keep the names and counts that were true when they shipped"
+  - rule: "*"
+    paths: [".workers/**/evidence/**"]
+    reason: "worker evidence files record what was true when the worker ran"
+  - rule: "claims.*"
+    paths: [".github/ISSUE_TEMPLATE/v1-1-1-api-changes.md", ".github/wiki/CI-Scope.md", ".github/wiki/Installation.md", ".github/wiki/Plugin-Conformance.md", ".github/wiki/Security.md", ".github/wiki/architecture/Plugin-System.md", ".github/wiki/getting-started/Quick-Start.md", ".github/wiki/plugins/AI-CLI.md", ".github/wiki/plugins/AI-Studio.md", ".github/wiki/plugins/API.md", ".github/wiki/plugins/Alerts.md", ".github/wiki/plugins/Audit-Analytics.md", ".github/wiki/plugins/Audit.md", ".github/wiki/plugins/Auth-Enterprise.md", ".github/wiki/plugins/BYOK.md", ".github/wiki/plugins/CDC.md", ".github/wiki/plugins/CI.md", ".github/wiki/plugins/CRDT.md", ".github/wiki/plugins/Claw-CLI.md", ".github/wiki/plugins/Compliance.md", ".github/wiki/plugins/Content-Safety.md", ".github/wiki/plugins/Costs.md", ".github/wiki/plugins/Cron.md", ".github/wiki/plugins/DLQ.md", ".github/wiki/plugins/DR.md", ".github/wiki/plugins/Dogfood.md", ".github/wiki/plugins/Donorbox.md", ".github/wiki/plugins/E2EE.md", ".github/wiki/plugins/Email.md", ".github/wiki/plugins/Encryption.md", ".github/wiki/plugins/Event-Bus.md", ".github/wiki/plugins/Family-Ancestry.md", ".github/wiki/plugins/Family-FamilySearch.md", ".github/wiki/plugins/Family-GEDCOM.md", ".github/wiki/plugins/Family-MyHeritage.md", ".github/wiki/plugins/Family-WikiTree.md", ".github/wiki/plugins/Federation.md", ".github/wiki/plugins/Flags.md", ".github/wiki/plugins/Forgejo.md", ".github/wiki/plugins/Functions-V8.md", ".github/wiki/plugins/Functions.md", ".github/wiki/plugins/GDPR.md", ".github/wiki/plugins/Gateway.md", ".github/wiki/plugins/Gauth.md", ".github/wiki/plugins/GitHub-Runner.md", ".github/wiki/plugins/HIPAA.md", ".github/wiki/plugins/Home.md", ".github/wiki/plugins/Infra.md", ".github/wiki/plugins/Job-Queue.md", ".github/wiki/plugins/K8s.md", ".github/wiki/plugins/LinkedIn.md", ".github/wiki/plugins/MLflow.md", ".github/wiki/plugins/Mail.md", ".github/wiki/plugins/Maintenance.md", ".github/wiki/plugins/Model.md", ".github/wiki/plugins/Monitor.md", ".github/wiki/plugins/Monitoring.md", ".github/wiki/plugins/Notify.md", ".github/wiki/plugins/Ollama.md", ".github/wiki/plugins/PayPal.md", ".github/wiki/plugins/Payments.md", ".github/wiki/plugins/Pentest-Kit.md", ".github/wiki/plugins/Pentest.md", ".github/wiki/plugins/Plugin-ClawDE.md", ".github/wiki/plugins/Plugin-Gauth.md", ".github/wiki/plugins/Plugin-LLM-Gateway.md", ".github/wiki/plugins/Plugin-PTY.md", ".github/wiki/plugins/Plugin-Retrieval.md", ".github/wiki/plugins/Post.md", ".github/wiki/plugins/Push.md", ".github/wiki/plugins/Queue.md", ".github/wiki/plugins/Region.md", ".github/wiki/plugins/Release.md", ".github/wiki/plugins/SIEM.md", ".github/wiki/plugins/SMS.md", ".github/wiki/plugins/Sentry-CLI.md", ".github/wiki/plugins/Shared-Utils.md", ".github/wiki/plugins/Soak.md", ".github/wiki/plugins/Sports.md", ".github/wiki/plugins/Storage.md", ".github/wiki/plugins/Stripe.md", ".github/wiki/plugins/Tenant-Controller.md", ".github/wiki/plugins/Tenant.md", ".github/wiki/plugins/Transactional-Email.md", ".github/wiki/plugins/WAF.md", ".github/wiki/plugins/Watchdog.md", ".github/wiki/plugins/Web3.md", ".github/wiki/plugins/nSelf-Cloud.md", ".github/wiki/plugins/nSelf-Eval-Gate.md", ".github/wiki/plugins/nSelf-Geo.md", ".github/wiki/plugins/nSelf-Image.md", ".github/wiki/plugins/nSelf-PDF.md", ".github/wiki/plugins/nSelf-Scan.md", ".github/wiki/plugins/nSelf-Sync.md", ".github/wiki/plugins/nSelf-Vault.md", "free/access-controls/MANIFEST.md", "free/access-controls/VERIFICATION.md", "free/analytics/IMPLEMENTATION_SUMMARY.md", "free/backup/third_party/sdk/README.md", "free/content-acquisition/third_party/sdk/README.md", "free/content-progress/third_party/sdk/README.md", "free/cron/third_party/sdk/README.md", "free/donorbox/third_party/sdk/README.md", "free/github-runner/README.md", "free/github-runner/third_party/sdk/README.md", "free/idme/QUICKSTART.md", "free/invitations/third_party/sdk/README.md", "free/link-preview/third_party/sdk/README.md", "free/mdns/third_party/sdk/README.md", "free/mlflow/third_party/sdk/README.md", "free/notify/third_party/sdk/README.md", "free/paypal/third_party/sdk/README.md", "free/push/third_party/sdk/README.md", "free/shopify/third_party/sdk/README.md", "free/subtitle-manager/third_party/sdk/README.md", "free/torrent-manager/third_party/sdk/README.md", "free/vpn/third_party/sdk/README.md"]
+    reason: "prose outside every sweep write scope of P7-TRUTH-10, P7-TRUTH-32; a real finding the lead can fold into a sweep Ticket, then delete this entry"
+  - rule: "vocab.*"
+    paths: ["free/backup/third_party/sdk/COMPATIBILITY.md", "free/content-acquisition/third_party/sdk/COMPATIBILITY.md", "free/content-progress/third_party/sdk/COMPATIBILITY.md", "free/cron/third_party/sdk/COMPATIBILITY.md", "free/donorbox/third_party/sdk/COMPATIBILITY.md", "free/github-runner/third_party/sdk/COMPATIBILITY.md", "free/invitations/third_party/sdk/COMPATIBILITY.md", "free/link-preview/third_party/sdk/COMPATIBILITY.md", "free/mdns/third_party/sdk/COMPATIBILITY.md", "free/mlflow/third_party/sdk/COMPATIBILITY.md", "free/notify/third_party/sdk/COMPATIBILITY.md", "free/paypal/third_party/sdk/COMPATIBILITY.md", "free/plugin-dev/internal/surface/help/init.txt", "free/plugin-dev/internal/surface/help/new.txt", "free/push/third_party/sdk/COMPATIBILITY.md", "free/shopify/third_party/sdk/COMPATIBILITY.md", "free/subtitle-manager/third_party/sdk/COMPATIBILITY.md", "free/torrent-manager/third_party/sdk/COMPATIBILITY.md", "free/vpn/third_party/sdk/COMPATIBILITY.md"]
+    reason: "prose outside every sweep write scope of P7-TRUTH-10, P7-TRUTH-32; a real finding the lead can fold into a sweep Ticket, then delete this entry"
diff --git a/.github/wiki/Contributing.md b/.github/wiki/Contributing.md
index 575584078..b6c4d9ce4 100644
--- a/.github/wiki/Contributing.md
+++ b/.github/wiki/Contributing.md
@@ -4,7 +4,7 @@ Thanks for your interest in contributing to the nSelf plugin ecosystem.
 
 ## What This Is
 
-Free MIT plugins for the nSelf CLI. There are 25 free plugins available to everyone.
+Free MIT plugins for the nSelf CLI. The free plugins are available to everyone; the live list is in `registry.json`.
 
 ## Prerequisites
 
diff --git a/.github/wiki/Home.md b/.github/wiki/Home.md
index 86aa65615..fc0fc75b4 100644
--- a/.github/wiki/Home.md
+++ b/.github/wiki/Home.md
@@ -35,8 +35,8 @@ Command pages include action/subcommand syntax, argument shapes, and option flag
 
 ### Plugin Documentation
 
-<!-- Registry has 129 free plugins across 14 categories, generated via `jq '.plugins|length' registry.json` — the table below (64 rows) is a partial sample pending full regen (P6-E9-W4-S3-T2 tracks the related F03 SPORT regen); see `_Sidebar.md` § All Free Plugins or `.github/wiki/plugins/` for the complete 129-plugin list. -->
-See [[All Plugins|#plugin-directory-64-of-129-shown]] below for a sample; the full catalog is 129 free plugins across 14 categories (see `_Sidebar.md` § All Free Plugins for the complete alphabetical list, or `registry.json`).
+<!-- The plugin count and categories are generated from `registry.json` (`jq '.plugins|length' registry.json`); this page does not type them. The table below is a partial sample. -->
+See [[All Plugins|#plugin-directory-sample]] below for a sample; the full catalog is in `_Sidebar.md` § All Free Plugins and in `registry.json`.
 
 **Popular Plugins:**
 - [[Stripe|plugins/Stripe]] - Payment processing and subscription management
@@ -63,7 +63,8 @@ See [[All Plugins|#plugin-directory-64-of-129-shown]] below for a sample; the fu
 - [[Deployment|guides/Deployment]]
 - [[Migration|guides/Migration]]
 - [[Best Practices|guides/Best-Practices]]
-- [[Adopting the nself-ci Gate|guides/Nself-CI-Adoption]]
+- [[Getting started with nself ci|guides/ci/Getting-Started]]
+- [[Migrating to the new CI engine|guides/ci/Migration]]
 - [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]]
 - [[Troubleshooting FAQ|troubleshooting/FAQ]]
 
@@ -101,10 +102,10 @@ Legacy `docs/` is retired. Public docs belong in `.github/wiki/` only.
 2. Commands in `Commands.md` and `commands/*.md` must match action/CLI source files.
 3. Any drift between code and docs is treated as a defect.
 
-## Plugin Directory (64 of 129 Shown)
+## Plugin Directory (Sample)
 
-<!-- Registry (129 plugins) uses 14 canonical categories per registry.json; this sample table's category column is synced to those values. -->
-This is a partial sample (64 of 129 free plugins). Registry categories (14, from `registry.json`): **authentication**, **automation**, **commerce**, **communication**, **compliance**, **content**, **data**, **development**, **infrastructure**, **integrations**, **media**, **social**, **sports**, **streaming**.
+<!-- Categories come from registry.json; this sample table's category column is synced to those values. -->
+This is a partial sample of the free plugins. Registry categories, from `registry.json`: **authentication**, **automation**, **commerce**, **communication**, **compliance**, **content**, **data**, **development**, **infrastructure**, **integrations**, **media**, **social**, **sports**, **streaming**.
 
 | Plugin | Port | Category | Description |
 |--------|------|----------|-------------|
diff --git a/.github/wiki/Plugin-Development.md b/.github/wiki/Plugin-Development.md
index 7539ac976..f6c1139de 100644
--- a/.github/wiki/Plugin-Development.md
+++ b/.github/wiki/Plugin-Development.md
@@ -1,6 +1,6 @@
 # Plugin Development
 
-This page walks through building a new nSelf plugin from empty directory to shipped service. It targets free + pro plugins written in Go against [`plugin-sdk-go`](https://github.com/nself-org/plugin-sdk-go).
+This page walks through building a new nSelf plugin from empty directory to shipped service. It targets free and licensed plugins written in Go against [`plugin-sdk-go`](https://github.com/nself-org/plugin-sdk-go).
 
 See also:
 - [[Home]]
@@ -219,11 +219,11 @@ log.Error("upstream 5xx", "err", err, "retry", 2)
 
 ---
 
-## 6. License (Pro Plugins Only)
+## 6. License (Licensed Plugins Only)
 
 Free plugins: skip this section.
 
-Pro plugins rely on the CLI loader to gate install. At runtime, use `sdk/license` only if you need to re-check a long-running entitlement (e.g. a daily cron):
+Licensed plugins rely on the CLI loader to gate install. At runtime, use `sdk/license` only if you need to re-check a long-running entitlement (e.g. a daily cron):
 
 ```go
 import "github.com/nself-org/plugin-sdk-go/license"
@@ -300,7 +300,7 @@ Minimum fields:
 }
 ```
 
-Pro plugins additionally set:
+Licensed plugins additionally set:
 
 ```json
 {
@@ -329,7 +329,7 @@ nself plugin verify my-notifier
 # Package it
 nself plugin package my-notifier
 
-# Submit (free plugins → plugins repo PR; pro plugins → plugins-pro via invite)
+# Submit (free plugins → plugins repo PR; licensed plugins → the Bundles repo via invite)
 nself plugin submit my-notifier
 ```
 
diff --git a/.github/wiki/Plugin-Marketplace.md b/.github/wiki/Plugin-Marketplace.md
index e8c63e509..2183f5e23 100644
--- a/.github/wiki/Plugin-Marketplace.md
+++ b/.github/wiki/Plugin-Marketplace.md
@@ -1,6 +1,6 @@
 # Plugin Marketplace
 
-The nSelf plugin marketplace is the catalog of free and pro plugins that extend a nSelf backend. It is served by the Cloudflare Worker at `plugins.nself.org` and consumed by three surfaces:
+The nSelf plugin marketplace is the catalog of free and licensed plugins that extend a nSelf backend. It is served by the Cloudflare Worker at `plugins.nself.org` and consumed by three surfaces:
 
 - **Admin UI** — `ɳSelf Admin` runs locally at `http://localhost:3021/plugins/marketplace`
 - **CLI** — `nself plugin marketplace {list,search,info}`
@@ -16,7 +16,7 @@ Base URL: `https://plugins.nself.org`
 |--------|------|---------|
 | GET | `/marketplace` | Categorized plugin list with ratings, bundles, and filters |
 | GET | `/marketplace?tier=free` | Only free plugins |
-| GET | `/marketplace?tier=pro` | Only pro plugins |
+| GET | `/marketplace?tier=pro` | Only licensed plugins |
 | GET | `/marketplace?category=media` | Filter by category |
 | GET | `/marketplace?bundle=nclaw` | Filter by bundle slug |
 | GET | `/marketplace?q=stripe` | Full-text search over name, description, display name, tags |
diff --git a/.github/wiki/Preflight.md b/.github/wiki/Preflight.md
index d4f1ea04f..430d018d5 100644
--- a/.github/wiki/Preflight.md
+++ b/.github/wiki/Preflight.md
@@ -65,3 +65,22 @@ Details: `scripts/preflight/README.md`.
 
 The licensed tier is measured separately (P7-PLUG-39). The latest evidence is
 kept in the hq plan evidence folder (`PLUG-02-preflight.md`).
+
+## Licensed tier
+
+`scripts/preflight/licensed.sh` measures the licensed entries of
+`$NSELF/plugins-pro/registry.json` against what `ping.nself.org` serves, using
+the scoped, expiring, revocable CI licence from the environment variable
+`NSELF_CI_LICENSE_KEY`. It runs on the owner's machine only; the registry data
+and tarballs are never committed.
+
+```bash
+bash scripts/preflight/licensed.sh --out "$TMPDIR/licensed.json" --strict
+```
+
+Same stages and classes as the free tier, plus `entitlement`: the download
+answered 401 or 403 for an entry the CI licence should cover (reported, never
+skipped). The key is sent only on the first hop, never to a redirect target,
+and is never printed. `--no-build` records skips, and a skip is not a pass.
+The offline test is `free/ci/internal/preflight/licensed_test.go`; the live
+run is P7-PLUG-88.
diff --git a/.github/wiki/Standards.md b/.github/wiki/Standards.md
index 3762e4ea8..97c4f3733 100644
--- a/.github/wiki/Standards.md
+++ b/.github/wiki/Standards.md
@@ -280,7 +280,7 @@ GOOGLE_KEY=...
 - Media: 3700-3799
 - Streaming: 3800-3899
 - Development: 3900-3999
-- Integrations: 4000-4099
+- Integration services: 4000-4099
 
 **Note**: Port ranges are guidelines only. Existing ports should not be changed without coordination.
 
diff --git a/.github/wiki/Truth-Rules.md b/.github/wiki/Truth-Rules.md
index 5aafc5114..70527a53f 100644
--- a/.github/wiki/Truth-Rules.md
+++ b/.github/wiki/Truth-Rules.md
@@ -67,6 +67,7 @@ generated_regions:
 
 Unknown region ids exempt nothing. A header saying `GENERATED BY` also exempts nothing; use declared region markers or a reasoned path exemption instead.
 
+<!-- truth: exempt names the labelled-count example the shipped rule catches -->
 Binary, UTF-16 and files over 4 MiB still run through dead-host matching up to a bounded 16 MiB read. Unscannable prose in a claim rule's scope produces `truth.unscanned-file`; a file above the host limit produces the same finding when any rule applies. NUL bytes anywhere in a file trigger this handling. Only explicitly excluded paths bypass it. Finding paths and matches that contain a dead host are redacted. Zero-width spaces, joiners, word joiners and BOMs cannot hide matches. Claims can span two adjacent lines, and the shipped count rule also catches labelled counts such as `Plugins: 62`.
 
 Known limits: claims split over more than two lines, full-width digits, `all 62 free and paid plugins` and `62 <b>plugins</b>` are outside the count pattern. Astro `<script>` and `<style>` blocks and dynamic expressions in Astro/MDX remain exempt.
diff --git a/.github/wiki/_Sidebar.md b/.github/wiki/_Sidebar.md
index b64de337e..26fa90783 100644
--- a/.github/wiki/_Sidebar.md
+++ b/.github/wiki/_Sidebar.md
@@ -38,7 +38,7 @@
 - [[Realtime|plugins/Realtime]]
 - [[Analytics|plugins/Analytics]]
 
-**View All:** [[Home|Home#plugin-directory-64-of-129-shown]] (or see the full alphabetical list below — 129/129 synced with `registry.json`)
+**View All:** [[Home|Home#plugin-directory-sample]] (or see the full alphabetical list below, synced with `registry.json`)
 
 ### All Free Plugins
 - [[Access-Controls|plugins/Access-Controls]]
@@ -162,7 +162,6 @@
 - [[Tokens|plugins/Tokens]]
 - [[Torrent-Manager|plugins/Torrent-Manager]]
 - [[Traefik|plugins/Traefik]]
-- [[Transactional-Email|plugins/Transactional-Email]]
 - [[VPN|plugins/VPN]]
 - [[WAF|plugins/WAF]]
 - [[Watchdog|plugins/Watchdog]]
@@ -170,6 +169,30 @@
 - [[Webhooks|plugins/Webhooks]]
 - [[Workflows|plugins/Workflows]]
 
+<!-- BEGIN GENERATED:guides-ci -->
+### CI
+- [[Getting started with nself ci|guides/ci/Getting-Started]]
+- [[CI architecture|guides/ci/Architecture]]
+- [[CI configuration and policy|guides/ci/Configuration-and-Policy]]
+- [[Evidence and machine output|guides/ci/Evidence-and-Machine-Output]]
+- [[Nodes and Runners|guides/ci/Nodes-and-Runners]]
+- [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]]
+- [[CI scheduling and cost|guides/ci/Scheduling-and-Cost]]
+- [[Hosted providers|guides/ci/Hosted-Providers]]
+- [[Cache and artifacts|guides/ci/Cache-and-Artifacts]]
+- [[Walkthrough: a home lab|guides/ci/Walkthrough-Home-Lab]]
+- [[Walkthrough: several projects on one fleet|guides/ci/Walkthrough-Multiple-Projects]]
+- [[Walkthrough: a team|guides/ci/Walkthrough-Team]]
+- [[Walkthrough: agents|guides/ci/Walkthrough-Agents]]
+- [[Migrating to the new CI engine|guides/ci/Migration]]
+- [[CI troubleshooting|guides/ci/Troubleshooting]]
+- [[CI reference|guides/ci/Reference]]
+- [[CI agent reference|guides/ci/Agent-Reference]]
+- [[Auto placement and pools|guides/ci/Auto-Placement-and-Pools]]
+- [[Watch and services|guides/ci/Watch-and-Services]]
+- [[macOS node ownership checks|guides/ci/macOS-Nodes]]
+<!-- END GENERATED:guides-ci -->
+
 ### Guides
 - [[Configuration|guides/Configuration]]
 - [[Best Practices|guides/Best-Practices]]
@@ -191,5 +214,5 @@
 
 **Related**
 - [nSelf CLI Wiki](https://github.com/nself-org/cli/wiki)
-- [Pro Plugins](https://github.com/nself-org/plugins-pro)
+- [Licensed Plugins (Bundles)](https://github.com/nself-org/bundles)
 - [nself.org Plugin Catalog](https://nself.org/plugins)
diff --git a/.github/wiki/architecture/CI-Matrix.md b/.github/wiki/architecture/CI-Matrix.md
index 25a6baff7..b15d5f2cc 100644
--- a/.github/wiki/architecture/CI-Matrix.md
+++ b/.github/wiki/architecture/CI-Matrix.md
@@ -11,7 +11,7 @@ How free plugins get tested automatically, and what does not.
 
 ## The 59 / 1 split
 
-As of P6, `free/` holds 60 plugin directories. 59 of them have a `go.mod` and
+`free/` holds one directory per free plugin; those with a `go.mod` (the count comes from `scripts/plugin-counts.sh` output, not this page) are
 are built, vetted, and unit-tested by `build-test.yml`'s loop
 (`for d in free/*/; if [ -f "$d/go.mod" ]; then ... fi`). Adding a new Go
 plugin needs no workflow edit — drop a `go.mod` in `free/<name>/` and the
@@ -52,7 +52,7 @@ sibling) to compare the free and pro registries against disk. It has two
 modes, selected automatically by whether the `PLUGINS_PRO_CHECKOUT_TOKEN`
 secret is set:
 
-- **Mode A** (secret present): checks out `nself-org/plugins-pro` and
+- **Mode A** (secret present): checks out `nself-org/bundles` and
   `nself-org/cli` as siblings, then runs the full script — free + pro counts,
   and the pro disk-vs-registry drift check.
 - **Mode B** (secret absent, current default): the pro-repo checkout is
diff --git a/.github/wiki/guides/Configuration.md b/.github/wiki/guides/Configuration.md
index afa3a0c44..97a14b617 100644
--- a/.github/wiki/guides/Configuration.md
+++ b/.github/wiki/guides/Configuration.md
@@ -23,7 +23,7 @@
 
 ## Overview
 
-All nself plugins are configured via environment variables, typically stored in `.env` files. This guide provides a complete reference for all configuration options across all 8 plugins.
+All nself plugins are configured via environment variables, typically stored in `.env` files. This guide provides a complete reference for all configuration options across the plugins covered here.
 
 ### Configuration Principles
 
@@ -1188,7 +1188,7 @@ If environment variables aren't loading:
 ls -la plugins/stripe/ts/.env
 
 # Check permissions
-chmod 600 plugins/stripe/ts/.env
+chmod 0600 plugins/stripe/ts/.env
 
 # Validate syntax (no spaces around =)
 # WRONG: STRIPE_API_KEY = sk_test_123
diff --git a/.github/wiki/guides/Nself-CI-Adoption.md b/.github/wiki/guides/Nself-CI-Adoption.md
deleted file mode 100644
index 86e257ed2..000000000
--- a/.github/wiki/guides/Nself-CI-Adoption.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Adopting the `nself-ci` Gate (Dogfood Pattern)
-
-**Status:** wired into `plugins` (this repo) 2026-09-11 — the first of 13 nself-org repos to adopt it. Zero repos had it wired before this, including `plugins` itself, which owns the source at `free/ci`.
-
-This guide is the copy-paste pattern for the other 12 repos. It also records, honestly, what the gate does and does not check today — read "Known gaps" before requiring it as a sole merge gate.
-
----
-
-## Why `plugins` first
-
-- It owns the `nself-ci` source (`free/ci/`) and the wrapper (`scripts/nself-ci.sh`) — self-hosting the gate here is the purest dogfood: a regression in the gate breaks its own repo's checks first.
-- It is public, so the workflow runs on free GitHub-hosted Actions — no runner-fleet dependency to prove the pattern.
-- Its own `.claude/docs/CI-LOCAL.md` (project-level) already documents the branch-protection recipe; this guide is the repo-level companion showing the wiring actually in place.
-
-## The pattern
-
-1. **Workflow** — `.github/workflows/nself-ci.yml`: checkout → `setup-go` (builds the binary) → `setup-node`/`pnpm` (for the Node gate path) → install `gitleaks` → run `scripts/nself-ci.sh .` with `permissions: statuses: write` and `GH_TOKEN: ${{ github.token }}` so `gh api` can post the status without a PAT.
-2. **Wrapper** — `scripts/nself-ci.sh` builds `free/ci/nself-ci` if missing/stale, then `exec`s it. Same script works locally and in CI.
-3. **Status** — the binary posts a `nself-ci` commit status via `gh api repos/{owner}/{repo}/statuses/{sha}` (OAuth, no token in a URL).
-4. **Branch protection (NOT applied by this PR — owner's call)** — add `nself-ci` to `required_status_checks.contexts` per the exact `gh api` command in `~/Sites/nself/.claude/docs/CI-LOCAL.md` § "Requiring nself-ci in branch protection". Do this as an **additional** required check alongside the repo's existing checks, not a replacement — see gaps below.
-
-Copy `.github/workflows/nself-ci.yml` from this repo into each of the other 12 (`cli`, `admin`, `web`, `nchat`, `nclaw`, `nsentry`, `ntask`, `nfamily`, `clawde`, `homebrew-nself`, `packages`, `plugins-pro`), adjusting the toolchain setup steps to match that repo's stack (e.g. Flutter repos need `subosito/flutter-action` instead of `setup-node`).
-
----
-
-## Verified locally (2026-09-11, this repo, HEAD `5c17916`)
-
-```
-$ scripts/nself-ci.sh --check -v .
-[nself-ci] building gate binary...
-[nself-ci] built .../free/ci/nself-ci
-[nself-ci] running: gitleaks detect --source . --exit-code 1 --config .github/gitleaks.toml
-
-nself-ci gate results — .
-Stacks: node
-────────────────────────────────────────────────────────────
-  secrets:gitleaks                PASS  (3.617s)
-────────────────────────────────────────────────────────────
-  Overall: PASSED  (4s)
-```
-
-That is the real, complete output — one gate ran (`secrets:gitleaks`), it passed, in under 4 seconds. Read that literally: **no lint, typecheck, test, or build gate ran**, for the reason below.
-
----
-
-## Known gaps — read before requiring this as the only gate
-
-**1. This repo's Node gate is a no-op.** `nself-ci` detects Node stacks by checking the root `package.json` for `lint` / `typecheck` / `test` / `build` scripts (or workspace members' scripts, if `pnpm-workspace.yaml` exists). This repo's root `package.json` has neither: it has one custom script, `ci:local` (a stub — `tsc --noEmit --allowJs || echo skip; echo passed`), and no `pnpm-workspace.yaml`, even though `shared/` has its own `package.json`. Result: the workspace-recursion path in `free/ci/internal/legacy/gate_runners.go` (`runNodeGates`) never triggers, the non-workspace path finds no matching scripts, and the gate silently runs nothing but the secret scan — while still printing `Overall: PASSED`. This is exactly the shape of failure flagged in `.claude/memory/lesson_hollow_ci_gates.md`: a gate that passes while checking nothing.
-   - **Fix options (not applied by this PR):** (a) add real `lint`/`typecheck`/`test`/`build` scripts to root `package.json` (or add `pnpm-workspace.yaml` so member scripts are picked up), or (b) extend `gate_runners.go` to also recognize this repo's `ci:local` convention. Until one of these lands, `nself-ci` on this repo is a secrets-only gate, not a lint/test/build gate.
-2. **No per-plugin checks.** The real quality bar for this repo is per-plugin (schema validation, the conformance gate (ports included), registry consistency — see `validate.yml`, `registry-check.yml`, `hygiene.yml`, `license-gate.yml`). `nself-ci` only inspects the repo root; it does not walk `free/*/plugin.json` or run plugin-level TypeScript builds. It does not replace any of those workflows.
-3. **No lint/typecheck/test/build for Go-only subpackages either.** `free/ci` itself (and other Go-based plugins) has a `go.mod`, but stack detection only looks at the *repo root*, which has no root `go.mod`. A regression inside `free/ci`'s own Go code would not be caught by `nself-ci` running against repo root — only by its own `go test ./...` if invoked directly in that subdirectory, or by `build-test.yml`.
-4. **Per the plugin's own README** ("What it explicitly does NOT do"): `nself ci` is not a GitHub Actions emulator. E2E, Lighthouse, axe-a11y, CodeQL, Trivy, SBOM, license audit, coverage ratchet, bundle-size, commitlint, i18n-check, and deploy jobs all still need to run somewhere else — free-runner Actions for public repos (this repo), or a dedicated additional gate for private ones.
-5. **Fork PRs:** `GH_TOKEN: ${{ github.token }}` on a fork PR is read-only for status writes; the binary treats a failed status post as a warning (non-fatal), so the job's pass/fail still reflects the real gate result, but the `nself-ci` check may not appear on fork PRs.
-
-**Bottom line:** this PR adds `nself-ci` as evidence the wiring works end-to-end (workflow → build → gates → status), not as proof the gate is a complete substitute for this repo's existing checks. Recommend requiring it in branch protection **in addition to**, not instead of, `validate.yml` / `build-test.yml` / `gitleaks.yml` / `registry-check.yml` until gap 1 is closed.
-
----
-
-## Rollout checklist for the other 12 repos
-
-- [ ] Copy `.github/workflows/nself-ci.yml`, adjust toolchain setup for the repo's stack.
-- [ ] Run `scripts/nself-ci.sh --check -v .` (or `plugins/free/ci/nself-ci` directly) locally first — confirm which stacks it detects and which gates actually execute. Do not assume; read the printed gate table.
-- [ ] If the repo's real lint/typecheck/test/build live under a non-standard script name (as `ci:local` does here) or in workspace members without `pnpm-workspace.yaml`, fix that *before* treating a green `nself-ci` as meaningful.
-- [ ] Open a PR, let Actions run it once, confirm the `nself-ci` commit status appears on the PR.
-- [ ] Propose (do not silently apply) the branch-protection addition per `CI-LOCAL.md` — owner approves it.
diff --git a/.github/wiki/guides/ci/Agent-Reference.md b/.github/wiki/guides/ci/Agent-Reference.md
new file mode 100644
index 000000000..1994a4889
--- /dev/null
+++ b/.github/wiki/guides/ci/Agent-Reference.md
@@ -0,0 +1,51 @@
+# CI agent reference
+
+<!-- Source: scripts/generate-ci-agent-reference.py; do not edit this page directly. -->
+
+This page covers the pull agent and its refusal and transport reasons. Commands, flags and codes of `nself ci` are on [[CI reference|guides/ci/Reference]].
+
+Regenerate with `python3 scripts/generate-ci-agent-reference.py`; validate with `python3 scripts/generate-ci-agent-reference.py --check`.
+
+## `nself-ci-agent pull`
+
+After `nself-ci-agent join`, keep an outbound TLS 1.3 mTLS connection to the enrolled coordinator and execute its leases. The enrollment pins the coordinator root; `--coordinator` selects its local record ID, not a URL.
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--slots` | `0` | lower the concurrent leases this process takes |
+| `--coordinator` | `""` | id of the coordinator (default: derived from the pinned root) |
+| `--project` | `""` | project root whose secret store this node resolves from (enables node-side secrets) |
+| `--secrets-eligible` | `false` | this node may receive project and environment secrets |
+| `--dedicated` | `false` | this node is dedicated to the project (also release and deploy secrets) |
+
+A slots value of zero keeps the automatic limit; a positive value lowers it. Negative values are rejected. Secret eligibility requires the project secret store on this node. `--dedicated` also permits release and deploy secrets.
+
+## E661: job token rejected
+
+The agent must present its own lease token using the certificate and session that first used it. Restart the job when its token expires or the attempt ends. Never copy a token between jobs, nodes, certificates or sessions.
+
+| Reason |
+| --- |
+| `expired` |
+| `invalid` |
+| `missing` |
+| `replayed` |
+| `terminal` |
+| `wrong_certificate` |
+| `wrong_job` |
+| `wrong_runner` |
+| `wrong_session` |
+
+## E656: pull transport failure
+
+These keys describe the pull carrier. Check node connectivity and enrollment for connection/configuration failures, coordinator capacity for a full queue, and lease cancellation or duplication for lease failures. A blob refusal cancels the lease; inspect its integrity, size and sink verification.
+
+| Reason |
+| --- |
+| `transport.agent_blob` |
+| `transport.agent_cancel_timeout` |
+| `transport.agent_duplicate_lease` |
+| `transport.agent_lease_lost` |
+| `transport.agent_not_configured` |
+| `transport.agent_not_connected` |
+| `transport.agent_queue_full` |
diff --git a/.github/wiki/guides/ci/Architecture.md b/.github/wiki/guides/ci/Architecture.md
new file mode 100644
index 000000000..6350cd0b6
--- /dev/null
+++ b/.github/wiki/guides/ci/Architecture.md
@@ -0,0 +1,75 @@
+# CI architecture
+
+<!-- docmap: cap:docs.ci-core -->
+
+This page explains how `nself ci` is built: the path a run takes, the layers of the code, the local store that holds state, and the rules that keep each part replaceable. Read it to reason about behaviour. To use the tool, start with [[Getting started with nself ci|guides/ci/Getting-Started]].
+
+## The path of a run
+
+A run is a pure plan followed by an audited execution. Each step has one owner and one record.
+
+1. **Detect.** Manifests and lockfiles become facts: which stacks exist, which tools they need, which services a compose file declares. Detection reads files and runs nothing.
+2. **Plan.** The configuration, the facts, the check catalogue and the revision context produce a pipeline: a validated graph of jobs. Every job in it, and every job left out, carries a reason code. The planner is a pure function, which is why `nself ci plan` can explain a run without starting one.
+3. **Place.** Each job is matched to a runner: this machine, a node you enrolled, or a hosted provider. Placement is covered in [[CI scheduling and cost|guides/ci/Scheduling-and-Cost]] and [[Nodes and Runners|guides/ci/Nodes-and-Runners]].
+4. **Admit and lease.** The coordinator commits the job's demand against the host in one store transaction. If the host is full the job waits; it is never half-started.
+5. **Execute.** The executor starts the job, enforces its timeout, passes its output through the redactor and kills the whole process tree on cancel.
+6. **Record.** The result of each check, the inputs, the binding to the commit and the runner become one evidence document. [[Evidence and machine output|guides/ci/Evidence-and-Machine-Output]] describes it.
+
+A job moves through a closed set of states: queued, leased, running, finalizing, then passed, failed, cancelled or lost, with retryable and needs-operator for the cases that need a second attempt or a person. The transitions are a table; nothing else moves a job.
+
+## Layers
+
+The code under `free/ci` is split into layers, and a test fails the build when a package imports a layer it may not. The layer file is [layers.yaml](../../../../free/ci/architecture/layers.yaml).
+
+| Layer | Holds | Rule the test enforces |
+|---|---|---|
+| kernel | the data model, the schemas and the error and reason registries | imports no other package of the engine, and no `os` or `net` |
+| pure | planning, detection, scoring, diagnosis, trust rules | imports no `os` and no `net` |
+| execution | the process and container executor, the store | the only code that starts a process, and the only code that touches SQL |
+| domain | everything that joins them: config, runs, reports, evidence, history, doctor, nodes, scheduling | may use the layers above; no package imports `cmd` |
+
+Two consequences matter in practice:
+
+- A pure package cannot touch the file system or the network, so planning and scoring are testable without a machine.
+- There is exactly one place that starts a process or a container, the executor, and exactly one that speaks SQL, the store. Provisioning, ad hoc runs, drills and services all go through the executor, so redaction, timeouts and isolation are applied once and cannot be skipped by a new feature.
+
+## State and the store
+
+The engine keeps its state in one SQLite database named `state.db` in the state directory (`$NSELF_CI_HOME`). SQLite is a deliberate choice here. CI state is a local file owned by one user on one machine, not an application backend, so it does not use a database server. The driver is pure Go, built without cgo, so the same binary runs on every supported platform.
+
+**Local disk only.** Put the state directory on a local disk. SQLite in WAL mode depends on file locking and shared memory that network file systems do not provide reliably. Do not point `NSELF_CI_HOME` at an NFS or SMB share, and do not share one directory between machines. Several machines share work through a coordinator, not through a file.
+
+How the store is used:
+
+- **WAL, one writer.** The database runs in write-ahead-log mode with one writer connection and a busy timeout of five seconds. Readers never block the writer. Foreign keys are enforced.
+- **Aggregate interface.** Callers do not write SQL. They call operations such as register a coordinator, admit and lease a job, record evidence, transition a job, request a cancel, back up and restore. Each operation is one transaction.
+- **Compare-and-set transitions.** A state change names the state it expects. If another writer got there first, the change is refused with an error rather than overwritten. This is why two processes can share a store safely.
+- **Expand-only migrations.** Schema changes only add. Each package registers its own migration set, and a version table records what ran. A stored minimum reader version tells an older binary that it must not open a newer database: it stops with a clear error and asks you to upgrade, instead of misreading rows. A downgrade therefore fails closed.
+- **At-most-once for releases.** A release job, and any job marked `idempotent: false`, is never retried on its own. After a failure it waits in `needs-operator`, and a retry is allowed only after an operator action has been written to the audit table. A reused idempotency key is refused.
+- **Audit sealing.** Security-relevant actions append rows to an audit table. Sealing chains the rows with hashes, so a deleted or edited row breaks the chain. The store holds no secret values in audit rows. Verification is `nself ci serve admin audit --verify`.
+- **Host admission.** Admission is a list of steps run inside the lease transaction: the host's reservations, the demand of running jobs and any budget. Each step can refuse. Because the check and the lease commit together, two coordinators cannot both take the last slot.
+- **Backup and restore.** A backup is a consistent snapshot of the database written while it is in use. A restore replaces the database and fences any coordinator that was running against the old one, so a stale process cannot write into the restored state.
+
+A coordinator is one process holding an identity in the store. A coordinator that stopped without finishing leaves a stale identity. On the next start the engine ends its in-flight attempts as lost or cancelled, closes runs that have no live coordinator, and sweeps containers it left behind.
+
+## What lives outside the store
+
+| Data | Where | Why |
+|---|---|---|
+| Logs | files under the state directory, one folder per attempt | large and append-only; redacted before they are written |
+| Detached run streams | files under the state directory | the event stream of a run started with `--detach` |
+| Branch-protection snapshots | files under the state directory, mode 0600 | the rollback for a policy change |
+| Cache and artifacts | a content-addressed store | see [[Cache and artifacts|guides/ci/Cache-and-Artifacts]] |
+| Configuration | `.nself/ci.yaml` in the repository | reviewed with the code it governs |
+
+## Extension seams
+
+Features plug in through hooks the run engine calls at fixed points, rather than by editing the engine. Examples are the policy resolver, the evidence builder, the report and status hooks, the services hook and the isolation level. A hook that panics is caught and the attempt ends with an error instead of taking the process down. This is how trust, scheduling and caching were added without changing how a job is planned or recorded.
+
+## Design rules worth knowing
+
+- **A pass is a claim with a proof.** A result is recorded as evidence that says exactly which inputs it covers, and it is bound to a commit only when the tree matched that commit. A dirty tree, or a tree that changed during the run, is recorded as unbound, and an unbound run posts no commit status.
+- **Nothing hidden skips.** A job that does not run has a reason code. A required job that cannot run fails the run; it does not vanish.
+- **Failures have a class.** Code, infrastructure, timeout, cancelled and lost are different, and only infrastructure failures are retried automatically. See [[CI troubleshooting|guides/ci/Troubleshooting]].
+- **One config, one schema.** `.nself/ci.yaml` is validated against a generated schema, and the same document describes the plan, the evidence and the events.
+- **Generated reference.** Every table of commands, codes and versions is generated from the code, so the [[CI reference|guides/ci/Reference]] cannot drift from the binary.
diff --git a/.github/wiki/guides/ci/Auto-Placement-and-Pools.md b/.github/wiki/guides/ci/Auto-Placement-and-Pools.md
new file mode 100644
index 000000000..7cc38feb8
--- /dev/null
+++ b/.github/wiki/guides/ci/Auto-Placement-and-Pools.md
@@ -0,0 +1,95 @@
+# Auto placement and pools
+
+<!-- docmap: cap:ci.auto-placement -->
+<!-- docmap: cap:ci.where -->
+<!-- docmap: cap:ci.pools -->
+<!-- docmap: cap:ci.race -->
+<!-- docmap: cap:ci.hosted-tier -->
+`nself ci` can run a job on this machine, on a registered node, on a pool of nodes, or on a hosted provider. This page covers how you choose, how a project limits the choice, and what happens when the chosen place is busy or unavailable. How a runner is scored is on [[CI scheduling and cost|guides/ci/Scheduling-and-Cost]]. Command, flag and code tables are on [[Reference|guides/ci/Reference]]; this page names them and does not repeat them.
+
+## Tiers and the `auto` preset
+
+Every runner belongs to one tier: `hosted`, `vps`, `lan` or `local`. Under the `auto` preset the tier of a runner turns into a small score bias, so a better tier wins when scores are close. The bias never overrides eligibility. A runner that is not ready, is out of capacity, fails trust, or would break a budget is still dropped, whatever its tier.
+
+Two operator keys tune the order:
+
+| Key | Meaning |
+|---|---|
+| `sched.auto.order` | The tiers `auto` may use, best first. You can drop tiers; you cannot add one. |
+| `sched.auto.step_sec` | How long a busy better tier is waited for before the next tier is tried. A project can only lower it. |
+
+Nothing here spends money. A hosted runner is in the choice only when its provider is registered, and the paid and budget rules on the scheduling page still decide whether it may run.
+
+## Choosing a place with `--where`
+
+`--where` is a flag of `nself ci` and of `nself ci runs rerun`. It maps to the same placement path as every other setting, so it can only narrow what policy allows.
+
+| Value | Runs on |
+|---|---|
+| `local` | This machine only. |
+| a node id | That registered node. |
+| a pool id | Any ready member of that pool. |
+| `hosted` | Registered hosted providers only. Refused when none is registered. |
+| `auto` | Whatever the `auto` preset picks. |
+| `all` | Several places at once (see [Race](#race)). Refused until race is available. |
+
+Names are matched in that order: the reserved words, then a node id, then a pool id. An unknown value is refused with the invalid-`--where` code from the Reference, and the refusal lists the valid targets. Add `--json` to a plan to see the chosen place under `data.placement`; `nself ci explain <job>` names the reason each runner was dropped.
+
+## Pools
+
+A pool is not stored anywhere. It is the set of runners that carry the coordinator-assigned label `pool.<id>`. Two pools are implicit: `local` (this machine) and `hosted` (every provider runner). A node cannot join a pool by declaring a label itself; only the label the coordinator assigns counts.
+
+List and inspect pools with the `nodes pools` verbs:
+
+- `nself ci nodes pools list` shows each pool and whether the project may use it.
+- `nself ci nodes pools show <pool>` shows one pool and its members.
+- `nself ci nodes pools explain` shows the project's effective set and every runner a pool term drops.
+
+### The effective-set rule
+
+Three keys decide which pools a project may use.
+
+| Key | Set by | Effect |
+|---|---|---|
+| `pools.allow` | The protected default branch's `.nself/ci.yaml` | The pools that may run the project. Unset means every pool. A revision can shrink this list and never widen it. |
+| `pools.dev` | The operator only | The pools a development run may use. A value from a branch, revision, pipeline or job is ignored and reported. |
+| `pools.record` | The operator | The pools allowed to produce a status of record. |
+
+The effective set is the operator's pools, intersected with `pools.allow`. A runner outside it is dropped with the `pool.excluded` reason. `--where <pool>` is checked against the same set: naming a pool outside it is refused, not widened.
+
+### Worked examples
+
+**One laptop.** No node is registered, so the only pool is `local`. Leave every key unset. `--where local` and `--where auto` do the same thing, and `--where hosted` is refused because there is no provider.
+
+**A person with a VPS and two Macs.** Register the three nodes and let the coordinator label the two Macs `pool.macs` and the VPS `pool.vps`. Leave `pools.allow` unset so the project may use all of them. Use `--where macs` for builds that need macOS, and `--where auto` for everything else; with the default tier order the VPS is preferred and the Macs are used when the VPS is busy past `sched.auto.step_sec`.
+
+**A team pool.** The team coordinator labels shared runners `pool.team`. A repository that must stay on team hardware sets `pools.allow` to `[team]` on its protected default branch. A contributor's revision may shrink that list further but cannot add `local`, and `--where local` is refused for the project. Set `pools.record` to `[team]` so only team runners produce a status of record; a personal machine can still run a development check.
+
+## Status of record
+
+A status of record is the commit status other people and merge rules rely on. It is posted only from a pool listed in `pools.record`, from commit CI, not from a dev run. A dev run uses `pools.dev` for placement instead and never posts a status of record. If the labels of a runner cannot be read, the runner is excluded rather than assumed to qualify.
+
+## Dirty-tree offload
+
+To run uncommitted work on another node, `nself ci` takes a snapshot: a commit of the tracked changes (staged or not, including files added with `git add` and not yet committed) plus untracked files that git does not ignore, whose parent is `HEAD`. The snapshot lives under a private ref in the `refs/nself-ci/offload` namespace and is deleted when the run finishes, fails or is cancelled. Your index, branches and working tree are not touched. A clean tree offloads `HEAD` unchanged. The snapshot is only what the node checks out: the run records the commit it started from, marked dirty, so `ci runs reproduce` never depends on a snapshot that no ref keeps. The snapshot is taken for `--where <node>`, and for a pool, `auto` or `all` when at least one node is registered. A run with `--where local` or `--where hosted`, or with only hosted providers registered, keeps `HEAD`: a hosted runner fetches the revision from the forge, where a snapshot never exists. For the same reason, a job that placement gives to a hosted runner checks out `HEAD` without your uncommitted changes, and the run prints `dirty changes not included: hosted runner`.
+
+Secrets are kept out by path and size, not by reading content. Untracked files that look like secrets or are too large are left out and named in the output. A tracked file of that kind refuses the offload. You can preview what would be included:
+
+```bash
+echo "draft" > notes.txt
+git status --porcelain
+```
+
+## Race
+
+`--where all` starts sibling attempts of a job on different places and keeps the first good result. The others are cancelled through the lease. A race never fails a run: a job it cannot race runs as a single attempt. Release-class jobs and jobs marked `idempotent: false` are never raced. The width is the resolved `sched.race.width`.
+
+## Hosted tier and billing-blocked behaviour
+
+Under `auto`, the hosted tier reads the result of the repository's own hosted workflow run and chooses one of three things: use that result, wait for it, or hand the commit to local nodes. A red hosted result stays red. The timers (`hosted.queued_sec`, `hosted.running_sec`) bound the wait. nSelf never plans paid GitHub minutes.
+
+The operator key `hosted.mode` is `off`, `free` or `paid`. An unknown value reads as `free`. `paid` applies only when paid capacity is enabled and budgeted (see the scheduling page); otherwise it is downgraded to `free` and the output carries a note saying so.
+
+When GitHub reports that billing blocks Actions, the provider is marked unavailable. That is never treated as a code failure: the commit is handed to the next tier in `sched.auto.order` instead. An unreadable hosted state has its own code on Reference. `nself ci explain <job>` shows the reason on each hosted runner.
+
+This page covers only what ships today in `nself ci`; anything not listed here is not yet available.
diff --git a/.github/wiki/guides/ci/Cache-and-Artifacts.md b/.github/wiki/guides/ci/Cache-and-Artifacts.md
new file mode 100644
index 000000000..27f98e302
--- /dev/null
+++ b/.github/wiki/guides/ci/Cache-and-Artifacts.md
@@ -0,0 +1,312 @@
+# Cache and artifacts
+
+This guide covers what `nself ci` keeps between jobs and between runs: the dependency cache, job artifacts, the coordinator's store for remote nodes, signed releases, and the supply chain evidence a release carries. It ends with the threats the design covers and where the performance evidence lives.
+
+Command names, flags, exit codes and error codes are not repeated here. They come from the generated [CI reference](Reference.md). Read [the command table](Reference.md#commands) first, [the exit codes](Reference.md#exit-codes) for what a status means, and [the error codes](Reference.md#error-codes) for every `E7xx` code named below. The cache and artifact codes are E684 and E711 to E719.
+
+All of it needs `NSELF_V15=1`. The command blocks in this guide use `text` fences, not runnable ones, because they need an installed `nself` and a real store.
+
+## Cache
+
+The cache holds downloads and compiler caches that a package manager refills on every run. It never holds build output. A cargo `target/` directory, for example, is never cached.
+
+### Keys
+
+A cache key is a sha256 over length-prefixed fields: the namespace, the spec id and version, the platform, the isolation level, the toolchain (the image digest for container jobs, probed tool versions for process jobs), a digest of the allowed environment, the paths, the lockfile digests and any extras. Environment values are hashed and never stored.
+
+Lookup is by exact key. There is no prefix match and no restore-key fallback. A changed lockfile is a miss, not a near hit.
+
+### Namespaces: per trust and per PR
+
+Every entry lives in a namespace made of the project, the trust class of the source, whether the ref is protected, and, for untrusted code only, the head repository and the pull request. Two pull requests never share a namespace. A fork never shares one with the default branch.
+
+Trust classes come from facts the forge reports. See [source trust](Trust-Security-and-Privacy.md#source-trust-who-made-the-code).
+
+### Access modes
+
+| Mode | Meaning |
+|---|---|
+| `rw-own` | Read and write the job's own namespace. |
+| `ro-snapshot` | Restore only, from a protected namespace of the same project and a strictly higher trust class. |
+| `none` | Everything else, including any attempt that has ended. |
+
+A lower class may read the snapshot of a higher class. It never writes it. A refused write reports E684 with a reason key such as `cache.namespace`, `cache.epoch`, `cache.attempt_state`, `cache.result` or `cache.mode`. The keys are listed under [reason codes](Reference.md#reason-codes).
+
+### Snapshot rules
+
+An entry can serve as a read-only snapshot only when its writer:
+
+- declared no secrets,
+- passed the scan for registered secret values before the save,
+- belongs to a project with no private dependencies.
+
+Each fact is a positive record made at save time. A missing or unknown fact means the entry is not eligible.
+
+### When a save happens
+
+A save commits only from a passing attempt, in the `finalizing` state, with the current lease epoch, into its own namespace and a planned key. Anything else is refused with E711. A restore re-hashes every blob. A corrupt or missing blob drops the entry and reads as a miss.
+
+### Config
+
+The cache switches on from the detected stack. A project can turn it off, or narrow it per job, in `.ci.yaml`:
+
+```yaml
+cache:
+  disable: false
+jobs:
+  test:
+    cache:
+      disable: false
+      keys: [extra-key-input]
+      paths: [.cache/tool]
+```
+
+`NSELF_CI_CACHE_DISABLE` turns it off for one run or one job through the environment.
+
+### Caps
+
+Three environment variables bound the store. Defaults are set in the code and shown by `nself ci artifacts --cache list`.
+
+| Variable | Bounds |
+|---|---|
+| `NSELF_CI_CACHE_MAX_BYTES` | Total cache bytes. Pruning evicts the least recently used entry first. |
+| `NSELF_CI_CACHE_MAX_AGE` | How long an unused entry stays. |
+| `NSELF_CI_STORE_MIN_FREE` | The free-space floor of the store volume. |
+
+An unparsable value keeps the default and prints one warning. Inspect and trim the cache with:
+
+```text
+nself ci artifacts --cache list
+nself ci artifacts --cache show --run <run>
+nself ci artifacts --cache verify
+nself ci artifacts --cache prune --dry-run
+```
+
+`verify` re-hashes every blob and drops nothing. `prune` needs the admin role, because the byte cap is store wide.
+
+## Artifacts
+
+### Declaring outputs
+
+A job names the outputs it must produce. The attempt cannot pass until every declared output is committed:
+
+```yaml
+jobs:
+  package:
+    artifacts:
+      - path: dist/app.tar.gz
+        name: app
+        kind: package
+        retention: 30d
+        visibility: project
+```
+
+`kind` is one of package, binary, archive, image, report, coverage, log, benchmark, sbom or other. `visibility` is `project` or `restricted`. A path must exist inside the job workdir. The collector refuses a file above `NSELF_CI_ARTIFACT_MAX_FILE`, a total above `NSELF_CI_ARTIFACT_MAX_BYTES`, a low disk floor, and any file that holds a registered secret value (E712).
+
+Every blob is re-hashed from the stored bytes before the attempt may leave `finalizing`. Two attempts that write the same path make two records. Neither overwrites the other.
+
+### Images are OCI tarballs
+
+The fabric never pushes an image. Declare an image output as an OCI layout tarball, for example from `docker buildx build --output type=oci,dest=app.oci.tar`. The collector reads the index digest and the per-platform manifest digests from the tarball without extracting it or contacting a registry.
+
+### List, show, get and prune
+
+```text
+nself ci artifacts list --run <run>
+nself ci artifacts show <id>
+nself ci artifacts get <id> --dest <dir>
+nself ci artifacts prune --dry-run
+```
+
+`get` writes only into a fresh, empty directory outside any git tree. A destination that is the working directory, not empty or under `.git` is refused (E683). An artifact you may not see reads as not found, the same as one that does not exist (E713). `prune` never touches release records unless you pass `--release`.
+
+## Remote nodes
+
+A remote node never reads the coordinator's disk. The coordinator hosts one store, and nodes get and give blobs through the lease.
+
+- **Hand-off.** A remote attempt sends its artifacts to the coordinator over the lease's carrier. Each blob is announced with its digest and size, accepted in chunks, and published only when the whole-blob digest matches. A restarted sender resumes from the bytes already held.
+- **Refusals come first.** The file cap, the lease byte budget, the disk floor and the lease epoch are all checked before a byte is stored. A stale epoch is refused on every write and at close. These failures report E714.
+- **Read-through copies.** A node keeps a bounded copy of the cache blobs it fetched, isolated per realm. Every use re-verifies the digest. A corrupt copy is deleted and fetched again. Eviction runs at lease start and before a new copy is published.
+- **Locality.** The scheduler is told how many cache bytes each runner is missing for each job, so work lands where its caches already are. Read [scheduling and cost](Scheduling-and-Cost.md) for how that score weighs against load.
+
+## Release workflows
+
+### Release jobs
+
+A job with `kind: release` is admitted only when the evidence of its dependencies passes the release gate. The dependencies must have passed on a clean, committed tree, for the protected identity of the run. An untrusted source is never promoted (E715).
+
+A release job receives `NSELF_CI_IDEMPOTENCY_KEY`. CI never gives a release job deploy credentials. A job that declares a variable starting with `DEPLOY_` or `NSELF_DEPLOY_` is refused.
+
+### Idempotency and `runs resolve`
+
+A release job runs at most once per run. If an attempt is killed after it started publishing, the run stops in `needs-operator`. Nothing retries it for you, because the outside world may already have changed.
+
+You decide. Find the attempt id with `nself ci runs <run>`. The key is the one the job received, which its publish step logs:
+
+```text
+nself ci runs resolve <attempt> --idempotency-key <key> --rerun
+nself ci runs resolve <attempt> --idempotency-key <key> --abandon --reason "checked the registry"
+```
+
+A wrong key is refused before anything is written (E716). A release attempt that has reached `finalizing` can only be abandoned.
+
+### Publication
+
+After a passing release run on a PERSONAL coordinator, the fabric builds the release directory itself: the artifacts, checksums, the evidence of the run, SBOMs, a SLSA provenance statement and a release manifest. It signs the provenance and the manifest with the release key, verifies its own output, and records the result.
+
+Publication is deterministic. Running it again writes the same bytes and signs nothing new when the release is intact. That is also the recovery path:
+
+```text
+nself ci artifacts sign <run>
+```
+
+Run it when a publication failed or was killed after the evidence was recorded. It completes the release. It refuses a digest that is not a committed record of the run (E717).
+
+### Export
+
+```text
+nself ci artifacts release <run> --out <dir>
+```
+
+The export goes into a fresh empty directory, is verified again, and is private operator material. It contains `evidence.json` with raw runner ids, so a public project does not publish that file.
+
+### Recovery
+
+| Symptom | What to do |
+|---|---|
+| The run is `needs-operator` | `runs resolve` with the attempt id and key, as above. |
+| Publication failed or was killed | `artifacts sign <run>`. It is safe to repeat. |
+| No release key | `artifacts key init` once (E717). |
+| SBOM tool missing | `artifacts tools install`, then retry (E718). |
+| Verification failed | Read the reason key. `artifacts verify <dir> --json` lists every check (E719). |
+
+### TEAM: signing on the operator's machine
+
+A TEAM coordinator holds secret references only, so it never signs. The release is signed on the operator's own machine:
+
+```text
+nself ci artifacts sign <run> --coordinator https://<host> --out <dir> --project <checkout>
+```
+
+The command fetches the run's release inputs and blobs from the coordinator with GET requests only, re-hashes every blob, rebuilds the provenance and manifest with the same code the coordinator uses, signs with the operator's own release key, and writes the verified directory to `--out`. The key stays in that process. Nothing is uploaded back. A member cannot do this for inputs they may not see (E687).
+
+### The Android lane on a laptop
+
+`nself ci build --artifact android` is a release pipeline on the operator's own machine. The project's required jobs run first. Then the `android` release job runs, using the project's own job of that name or the synthesized `android-release` pipeline. The command prints the APK path and the release directory.
+
+The keystore reaches the job only as the four `release/ANDROID_*` secret references, filled from the operator's environment on this machine. Any other node is refused (E677). The job decodes the keystore inside its own workspace and removes it when the script ends. Gradle runs with `--no-daemon`, so nothing outlives the attempt holding the keystore.
+
+Upload is a separate, explicit step and never overwrites an existing release asset:
+
+```text
+nself ci build --artifact android --upload --tag <tag> --owner <owner> --repo <repo>
+```
+
+The APK uploaded is the verified copy in the release directory.
+
+### The deploy hand-off
+
+CI builds and signs. It does not deploy. A deploy tool outside CI decides what to trust. Print the public trust line for the release key:
+
+```text
+nself ci artifacts key
+```
+
+The line is `<key-id> <base64 public key>`. Commit it to `.nself/trust/ci-release.keys` on the protected default branch. A revoked key id goes in `.nself/trust/ci-release.revoked`. The operator's own copies live under `$NSELF_CI_HOME/trust/` and apply too. The deploy side then runs `nself ci artifacts verify` against the release and deploys only on exit 0.
+
+## Supply chain
+
+### One key per purpose
+
+Signing keys are per purpose. The release key has purpose `ci-release` and an id of the form `ci-release-<16 hex>`. A manifest signed by a key of another purpose, such as a plugins or agent key, is refused (E719 `key_purpose`).
+
+```text
+nself ci artifacts key init
+nself ci artifacts key
+nself ci artifacts key rotate --yes
+```
+
+- `key init` creates the key once. It refuses when one exists.
+- `key` prints the public trust line. Both values are public.
+- `key rotate` replaces the key, prints the new trust line and prints the old key id for the `.revoked` file. It asks for confirmation unless you pass `--yes`.
+
+### Signer isolation, and its limit
+
+Every key operation runs in a separate signer process that the coordinator starts after the run. The signer sits outside every job's process group, namespace and container. It resolves the key by reference, uses it in memory and zeroes it. The key never reaches argv, stdout, a file or a child's environment. Before it signs, it re-checks the request against the stored run: the revision, the repository, the passed release attempt and every digest. One failing item fails the whole request, and the key is not touched.
+
+The limit: the signer runs as the same operating-system user as the coordinator. It keeps jobs away from the key. It does not keep away another process that runs as that user with enough rights to read memory or files. Anyone who can act as the coordinator's user can reach the key. Treat that user as the trust boundary, and see [Trust, security and privacy](Trust-Security-and-Privacy.md) for the isolation levels. A TEAM coordinator avoids the question: it never holds the key.
+
+### SBOM formats
+
+Each release artifact gets two SBOMs from one pinned syft run: CycloneDX 1.6 JSON and SPDX 2.3 JSON, side by side. Both pass a structural check before they are committed. The pinned syft is placed by an explicit step. No job downloads a tool.
+
+```text
+nself ci artifacts tools install
+```
+
+The pinned version is in [the pinned versions table](Reference.md#pinned-versions). The download is checked against a recorded sha256, and a mismatch installs nothing (E718).
+
+### Provenance fields
+
+The provenance is an in-toto Statement v1 with a SLSA provenance v1 predicate, written as canonical JSON so the same facts give the same bytes.
+
+| Field | Content |
+|---|---|
+| `subject` | Each released artifact by name and sha256. |
+| `buildDefinition.buildType` | The release build type. |
+| `externalParameters` | Repository, revision, pipeline, job and config digest. |
+| `internalParameters` | Isolation level and the `nself ci` version. |
+| `resolvedDependencies` | The source git commit and the lockfile digests. |
+| `runDetails.builder.id` | The builder. For a repository not known to be private, it is pseudonymous. |
+| `runDetails.metadata` | The invocation id, `<run id>/<attempt id>`, and the start and finish times. |
+| `runDetails.byproducts` | The digest of `evidence.json`. |
+
+Building refuses a private address, host name, user name or home path in a public release. It never rewrites a name, because a subject must stay equal to its manifest entry.
+
+### Verify
+
+```text
+nself ci artifacts verify <dir>
+nself ci artifacts verify <run> --json
+```
+
+`verify` takes a release directory, its manifest or a run id. It writes nothing. The trust roots are the operator key files and the protected default branch at the pinned tip. The working tree and the released revision are never trusted. A pin that cannot be resolved fails the check. It never drops the branch's keys and revocations.
+
+Exit 0 means verified. Exit 11 means invalid, and the reason key names the check that failed. Exit 1 means the run's evidence is failing or quarantined. The `--json` result always carries `slsa_build_level: "L1"`. Exit codes are in [the exit code table](Reference.md#exit-codes). An invalid result reports E719.
+
+### The SLSA level: Build L1
+
+Every published release, and every agent release, is SLSA Build L1. That is the whole claim, and the code cannot name another level.
+
+Build L1 means the provenance exists, says how the artifact was built, and is available to the consumer. This fabric meets that and no more.
+
+Build L2 asks for a hosted build service that signs the provenance itself, so the producer of the build cannot forge it. Build L3 asks for a build platform that isolates each build from the others and keeps the signing secret out of reach of the build steps. Neither is the case here, for these reasons:
+
+- The coordinator is the operator's own machine or server. It is not a separate hosted service with its own identity.
+- The signing key is held by a process of the same operating-system user as the coordinator (see the limit above). A build with that user's rights could reach it.
+- On a PERSONAL coordinator and in the Android lane, the build and the signer share one machine owned by the person who ships the release.
+- Job isolation depends on the level you configure. Not every level separates builds from each other to the degree a higher level needs.
+
+So the output is a signed claim by the operator that this run built this revision. Verification checks the signature, the digests and the trust roots. It does not turn the operator into an independent builder.
+
+## Threats covered
+
+The cache, artifact and release threats are tested as one matrix in `free/ci/test/cachesec`, and mapped to rows of the project threat model. Each case lists the code, the reason key and the audit event it must produce.
+
+| Threat row | What it covers | Codes in the matrix |
+|---|---|---|
+| TM-12 | A fork or another pull request poisons a namespace it does not own. A secret reaches a snapshot. | E684, E711 |
+| TM-13 | A write from an ended, stale-epoch or failed attempt, local or remote. | E711, E714 |
+| TM-14 | A crafted archive or destination: traversal, absolute paths, links, FIFOs, devices, zip bombs, `get` into a non-empty or git directory. | E683 |
+| TM-15 | A corrupt, partial, overwritten or substituted blob, at rest or in transit. | E711, E712, E714 |
+| TM-16 | A registered secret, raw or base64, saved into a cache or artifact. | E711, E712 |
+| TM-17 | Release of an untrusted source or of failing dependencies. | E715 |
+| TM-18 | A manifest signed with the wrong key purpose, or a sign request for an uncommitted digest. | E717, E719 |
+| TM-20 | A revoked key. | E686 |
+| TM-24 | A member or a job reaching signing inputs it is not allowed. | E687 |
+
+Look up each code in [the error codes](Reference.md#error-codes). Every refusal writes an audit row, listed under [reason codes](Reference.md#reason-codes) where it has a stable key.
+
+## Performance
+
+The fabric measures cache restore and save time with a benchmark harness in `free/ci/bench/cache`. It covers key derivation, blob store cost, archive pack and unpack, and an end-to-end cold and warm restore, and it emits `perfbench/v1` JSON. The p95 budgets for restore and save are in [`perf-budget.json`](../../../../free/ci/bench/cache/perf-budget.json). No figure is copied into this page. Read the measured results from the evidence of the benchmark run, so the page cannot go stale.
diff --git a/.github/wiki/guides/ci/Configuration-and-Policy.md b/.github/wiki/guides/ci/Configuration-and-Policy.md
new file mode 100644
index 000000000..ba07c3f0c
--- /dev/null
+++ b/.github/wiki/guides/ci/Configuration-and-Policy.md
@@ -0,0 +1,251 @@
+# CI configuration and policy
+
+<!-- docmap: cap:docs.ci-core -->
+
+Two things decide what `nself ci` does: the **configuration** in your repository, which says what to run, and the **policy** on your machine and your branches, which says what is allowed. This page covers both. The commands and codes it names are in the generated [[CI reference|guides/ci/Reference]].
+
+## The configuration file
+
+The file is `.nself/ci.yaml` at the repository root. It is optional. With no file, `nself ci` detects your stacks and plans the standard checks. Declare any job and detection turns off for the jobs you declare; to tune a detected check instead, use `checks:` (below).
+
+```bash
+mkdir proj && cd proj && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir .nself && cat > .nself/ci.yaml <<'EOF'
+version: 1
+jobs:
+  lint:
+    kind: static
+    run: [sh, -c, "echo lint"]
+    timeout: 5m
+  unit:
+    kind: test
+    run: [sh, -c, "echo test"]
+    deps: [lint]
+    retry:
+      infra_max: 2
+EOF
+git add -A && git commit -q -m init
+nself ci config show
+nself ci plan
+```
+
+`config show` prints every effective value with its source: a flag, an environment variable, the file or a built-in default. Add `--json` for the same data as a document, where each value carries `value`, `source` and `origin`.
+
+**Precedence is flag, then environment, then file, then default.** That holds for every key, the timeout included: `--timeout` or `NSELF_CI_TIMEOUT` overrides a job's timeout in the file.
+
+**The file is validated strictly.** Unknown keys, wrong types, unsafe paths and unpinned images are refused with `E620`, naming the file, the line and a JSON pointer to the key. The message is built from the schema and never repeats the offending value, so a secret pasted into the wrong place is not echoed. Other rules:
+
+- Job, service and pipeline names, `workdir`, `when.paths`, `drills_dir` and cache and artifact paths must be safe paths inside the repository.
+- `container.image` must be pinned by digest.
+- Environment names must be variable names. Files are read only when regular and at most one mebibyte.
+- A leftover legacy `.ci.yaml` is `E621`. A git-ignored `.nself/ci.yaml` is `E623`, and the message prints the lines to add to `.gitignore`. To move from the legacy file, see [[Migrating to the new CI engine|guides/ci/Migration]].
+
+## Jobs
+
+A job is one command with a kind, and everything the planner needs to place and judge it.
+
+| Key | Meaning |
+|---|---|
+| `kind` | `static`, `build`, `test`, `quality`, `advanced`, `release` or `drill` |
+| `run` | the command as a list; it is exec'd as given, with no shell unless you write one |
+| `workdir` | directory inside the repository the job runs in |
+| `deps` | jobs that must finish first; a failed dependency skips the job with `dep.failed` |
+| `needs_services` | disposable services the job uses; see [Services](#services) |
+| `matrix.platform` | a list of platforms such as `darwin/arm64`; one planned job per platform |
+| `required` | `true` by default; an optional job cannot fail the run |
+| `allow_failure` | the job runs and is reported, and its failure does not fail the run |
+| `idempotent` | `false` marks a job that must never be retried automatically |
+| `timeout` | a duration such as `5m` |
+| `retry.infra_max` | how many times an infrastructure failure may be retried |
+| `priority`, `path` | `low`, `normal`, `high`; `fast` or `deep` |
+| `when` | `branches`, `paths`, `triggers` and `env_present` conditions |
+| `env`, `secrets` | environment values, and names of secrets the job may read |
+| `isolation`, `container` | the minimum isolation level; an image pinned by digest |
+| `artifacts`, `cache` | outputs to keep, and cache keys and paths |
+| `requires` | runner requirements: `labels`, `tools`, `accelerators`, `cpu`, `mem_mb` |
+
+**Every job has a reason.** `nself ci plan` shows, for each job, whether it is included or skipped and the reason code: `pipeline.excluded`, `selection.affected`, `when.paths`, `when.env_missing` and so on. `nself ci explain <job>` shows where a job would be placed and why. The full list of reason codes is generated in the [[CI reference|guides/ci/Reference]].
+
+**Affected selection.** When a base commit is known, a job whose `when.paths` do not match the change is left out, except that a default-branch or release plan always keeps every required deep job, even one outside the named pipeline. With no base the whole plan runs, with the reason `selection.no_base`. A job that does not run always has a reason code, so a skip is never silent.
+
+**Matrices come from your support policy.** `support:` lists the platforms you support, and a matrix is expanded from it, never invented.
+
+### Requirements and Xcode
+
+`requires` narrows which runners may take a job. A job that needs Xcode names the `xcode` tool and the platform, and the planner only places it on a Mac where `xcodebuild -version` actually runs. The Command Line Tools alone do not count, because they ship a stub:
+
+```bash
+mkdir mac && cd mac && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir .nself && cat > .nself/ci.yaml <<'EOF'
+version: 1
+jobs:
+  ui-test:
+    kind: test
+    run: [xcodebuild, test, -scheme, App, -destination, "platform=macOS"]
+    matrix:
+      platform: [darwin/arm64]
+    requires:
+      tools: [xcode]
+    timeout: 20m
+EOF
+git add -A && git commit -q -m init
+nself ci config show
+```
+
+Then, on the machine you care about, see where the job would go:
+
+```text
+nself ci plan
+nself ci explain ui-test
+```
+
+On a machine that cannot satisfy the platform or the tool, the planner reports the job with an `unplaceable.*` reason such as `unplaceable.platform` or `unplaceable.tool` instead of starting it, which is the point: it waits for a Mac node. Detected Swift projects get this requirement automatically. See [[Nodes and Runners|guides/ci/Nodes-and-Runners]] for adding a Mac.
+
+## Checks
+
+When you declare no jobs, the catalogue plans checks per detected stack. Each check is either required, so a failure fails the run, or advisory, so it is reported but does not.
+
+| Stack | Required by default | Advisory by default |
+|---|---|---|
+| Go | `go.fmt`, `go.vet`, `go.test` | `go.govulncheck`, and a coverage floor when you configure one |
+| Node | `node.lint`, `node.typecheck`, `node.test`, `node.build` | |
+| Rust | `rust.clippy`, `rust.test` | |
+| Flutter | `flutter.analyze`, `flutter.test` | |
+| Swift | `swift-build`, `swift-test`, `xcode-test` | |
+| Python | `python-test` | `python-lint` (ruff), `python-types` (mypy, planned only when mypy is configured) |
+| Containers | | `container.hadolint`, `container.trivy.config` |
+| Any | `secrets.gitleaks` | `security.trivy.fs` |
+
+The `container`, `release` and `strict` modes require the advisory checks as well, whatever `required:` says. The Python lint and type checks become required in the same modes and under `--container`.
+
+A missing tool depends on the check. A missing required tool, or an unsupported Node package manager, ends the check with `E614` and a remediation line. A missing advisory tool skips the check with `advisory.tool_missing`, and unavailable Trivy data skips it with `advisory.data_offline`.
+
+Tune a check under `checks:`: `required`, `env`, `secrets`, `coverage_floor` and, for the truth check, `rules`. Turn off an ecosystem with `detect.disable`, and point detection at subdirectories with `detect.roots`.
+
+### Node preparation
+
+Before a Node check runs, the job finds the lockfile in the working directory or above, and checks the declared package manager's major version against the one on `PATH`. A mismatch is `E811` and the job does not retry. If there is no `node_modules`, it runs a frozen install: `npm ci`, `pnpm install --frozen-lockfile`, `yarn --immutable` or its older form, or `bun --frozen-lockfile`, by lockfile. Caches and the pnpm store live inside the job workspace. Astro projects run `astro sync` before typecheck and build. A failed install is classified as a code failure when the lockfile is out of sync or a lifecycle script failed, and as an infrastructure failure when the registry or disk was the cause, which is retried. See [[CI troubleshooting|guides/ci/Troubleshooting]].
+
+### The secret scan
+
+`secrets.gitleaks` honours `.gitleaksignore`, with one rule: every entry needs a review comment on the same line or the line before.
+
+```text
+# Reviewed 2026-10-29 by alice: a documented test value, not a credential
+<fingerprint>
+```
+
+An entry without one fails the check with `E812`, which names line numbers and never prints content. Add entries with `nself ci config ignore add <fingerprint> --reason <text> [--by <who>]`. A run never adds lines itself. A missing `gitleaks` is `E614`, not a skip.
+
+### The truth check
+
+The truth check keeps retired names, dead hosts and banned strings out of your tree. It makes no network calls. Rule files are listed under `checks.truth.rules` in `.nself/ci.yaml`, as repository-relative paths; a rule file may `include` others to a limited depth, and cycles are refused.
+
+A rule file has `version: 1` and these parts:
+
+- `rules[]`, each with an `id`, a `kind`, a `message` and optional `paths` globs. The kinds are `banned-literal` (a `literal`), `retired-term` (a `term`, matched case-insensitively as a whole term) and `dead-host` (a list of SHA-256 hashes, so the file does not publish the host).
+- `skip[]`, globs that are never scanned.
+- `allow[]`, each naming a `rule` (an id, or a glob such as `retired-*`), the `paths` it covers and a `reason` of at least eight characters.
+
+Unknown keys, duplicate ids, bad hashes, inert globs, extra YAML documents and symlinked rule files are `E644`, naming the file and the key. A dead-host rule stores the hash of the lower-cased host. The engine hashes every address and host name token on a line and compares the whole token, so a sub-domain is a different host.
+
+The scan covers regular files under the root except `.git`, `node_modules`, the rule files themselves and your `skip` globs. A file over four mebibytes, or with a NUL byte, is skipped and counted in the summary; a tree with nothing to scan is an error. The evidence holds one check per rule kind. Findings print `path:line`, the rule id and the message, and a dead-host finding prints only a hash prefix.
+
+## Services
+
+A job that needs a database or cache names it, and gets a throwaway nSelf project for that attempt.
+
+```text
+services:
+  db:
+    component: postgres
+    version: "16"
+jobs:
+  integration:
+    kind: test
+    run: [go, test, ./...]
+    needs_services: [db]
+```
+
+A name is either declared under `services:` or is the name of a component. `--service <name>` adds one to a single run. Each attempt gets its own project on random loopback ports with random credentials, and the job sees these variables, with the service name upper-cased: `NSELF_CI_SERVICE_<NAME>_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_DB` and `_URL`, the same set under `_NET_` for a container job, and `NSELF_CI_SERVICE_NETWORK`.
+
+Services need Docker and an nSelf with the `config services` command: `E637` means no Docker, `E638` means the CLI is too old (run `nself update`), `E639` means an unknown service, a duplicate component or a bad version, and `E636` means provisioning or teardown failed. Services are torn down on pass, fail, cancel and timeout, and after a hard kill the next run sweeps them. Services need the v1.5 engine.
+
+## Pipelines, schedules and drills
+
+A named pipeline picks a set of jobs for a set of triggers:
+
+```bash
+mkdir sched && cd sched && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir -p .nself scripts/drill/restore
+printf '#!/bin/sh\necho restored\n' > scripts/drill/restore/run
+chmod +x scripts/drill/restore/run
+cat > .nself/ci.yaml <<'EOF'
+version: 1
+jobs:
+  report:
+    kind: quality
+    run: [sh, -c, "echo report"]
+    required: false
+pipelines:
+  nightly:
+    triggers: [schedule, manual]
+    schedule: "0 3 * * *"
+    max_age: 36h
+    drills_dir: scripts/drill
+    jobs: [report]
+EOF
+git add -A && git commit -q -m init
+nself ci plan --pipeline nightly
+```
+
+`nself ci plan --trigger schedule` plans the pipelines that list the trigger. A **drill** is a directory under `drills_dir` with an executable `run`; each becomes a job named `drill-<dir>`, in a stable order. The exit code is the result. A drill may print one `ci.evidence` document as a single line on stdout, which is validated and nested as the job's checks. A config job with the same name replaces the discovered one, which is how a drill gets its own timeout, since discovered drills use the default.
+
+`max_age` makes a silent job visible. `nself ci evidence --pipeline <name>` reports each job's last passing run and marks a job `overdue`, with exit code 10, when it is older than `max_age`. A pipeline without `max_age` is never overdue. A scheduled pipeline on a throwaway hosted runner has no store, so there staleness shows as a missing workflow run. The org-neutral workflow for it is `free/ci/templates/scheduled-pipeline.yml`.
+
+## Policy
+
+Policy is not in the repository. It lives in your user configuration, in a team coordinator's configuration, and on the host. Read it with `nself ci policy show` and change it with `policy set`, `policy unset` and `policy usage`. Trust, privacy and spend keys are covered in [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]], scheduling keys in [[CI scheduling and cost|guides/ci/Scheduling-and-Cost]].
+
+### Per-run values
+
+Three flags change policy for a single run: `--prefer`, `--max-queue` and `--runner`, with `--where` for the run target. They apply to bare runs only; `nself ci plan` ignores them.
+
+- A per-run value can only **tighten**. It is merged last and refused if it would loosen a trust or privacy key. A refusal is `E819`, shown as a run note, and the key is ignored.
+- Spend and secret keys cannot be set per run.
+- A key that is unset may be filled only in the scheduling area, for the runner, operating system, architecture and allowed providers, because an unset trust list means "deny all".
+- `--prefer` is the exception to tighten-only: any preset in the closed set is accepted, so you can override a protected branch's preset for one run.
+- `--runner` pins only runners that your dispatcher knows; before nodes are enrolled that is the local machine.
+- An interactive run, one started from a real terminal with no trigger and no `NSELF_INVOKED_BY`, waits at most ten minutes for a runner by default. A scripted run does not get that cap, and a `max_queue` in your policy longer than ten minutes stands. Git Bash terminals and runs wrapped by an agent count as scripted.
+
+The base policy digest is what evidence records, so `evidence verify` still matches a run that used per-run values.
+
+### Branch protection, hook and audit
+
+`nself ci policy protect` makes `nself-ci` a required check on a branch, safely, and gives you the pieces to undo it.
+
+```text
+nself ci policy protect --repo owner/repo --branch main --dry-run
+nself ci policy protect --repo owner/repo --branch main
+nself ci policy protect --repo owner/repo --branch main --restore <snapshot>
+nself ci policy protect --hook
+nself ci policy protect --audit 30
+```
+
+- **Dry run** prints the exact request body. Existing required checks keep their pinned app, the `nself-ci` check is appended (override the app with `--app-id`), every other field is replayed from the live answer, and status checks are always sent as `checks`, never as `contexts`. A protection block with an unknown field, or with required signatures on, refuses the plan. An unprotected branch gets protection that holds only the check.
+- **Apply** writes a snapshot of the current protection first, to `$NSELF_CI_HOME/protect/` with mode 0600 and never overwriting a file. It sends the body from a file, never on the command line, then reads the result back and compares it, ignoring the order of checks.
+- **Restore** saves what it replaces, then puts the snapshot back. A snapshot of an unprotected branch cannot be restored; removing protection is a manual step.
+- If the host's plan has no branch protection, the command prints the hook and audit equivalents and exits 3 (`E643`). Other 403 responses, such as a rate limit or a token without rights, are ordinary errors.
+- **Hook** installs a pre-push hook for the default branch at git's own hooks path. It runs `NSELF_V15=1 nself ci evidence verify <sha> --json` and refuses the push on any non-zero exit: missing, stale, invalid, unbound or failing evidence. It also refuses when neither `nself` nor `nself-ci` is on the path. An existing hook is never overwritten (`E642` prints the line to chain it). `git push --no-verify` is your override.
+- **Audit** lists commits on the default branch, newest first, that have no green `nself-ci` status and no green check run from the pinned app, and exits 1 when there are any.
+
+Exit codes: 0 success, 1 failure or missing commits or `E642`, 2 infrastructure, 3 `E643`.
+
+### The workflow template
+
+Hosted runs can produce the same check from a workflow. Copy `free/ci/templates/nself-ci.yml` to `.github/workflows/nself-ci.yml`, set the three release values it asks for (the plugin version, the release URL and its SHA-256), add setup for your own toolchain where it says so, and then run `policy protect`. Nothing is downloaded until all three values are set.
+
+The template keeps rules that make the gate honest: the job is named exactly `nself-ci`, because branch protection matches that name; it has no `paths:` filter, no matrix and no cancel-in-progress, because a skipped or cancelled required check blocks merges or hides a red run; its actions are pinned by commit; it holds read-only repository permissions and posts no commit status; and the binary is the pinned release, never one built from the checkout under test. A check run, unlike a commit status, is also produced on fork and Dependabot pull requests, whose tokens are read-only. A pull request that edits the workflow controls its own check run, which is inherent to hosted runners, so protect `.github/workflows` with code owners as well.
diff --git a/.github/wiki/guides/ci/Evidence-and-Machine-Output.md b/.github/wiki/guides/ci/Evidence-and-Machine-Output.md
new file mode 100644
index 000000000..177e64a4f
--- /dev/null
+++ b/.github/wiki/guides/ci/Evidence-and-Machine-Output.md
@@ -0,0 +1,345 @@
+# Evidence and machine output
+
+<!-- docmap: cap:docs.ci-core -->
+
+Every run of `nself ci` leaves a record you can read, verify and hand to another program. This page covers that record, the machine-readable output of the commands, how to start a run and collect it later, and ad hoc commands. For the first run, see [[Getting started with nself ci|guides/ci/Getting-Started]].
+
+## Evidence
+
+A run's evidence is one JSON document of schema `ci.evidence/v1`. It states which revision was checked, which inputs the result covers, which runner produced it, what each check concluded and how the document itself was produced. The tables at the end of this page are generated from the schema and list every field.
+
+Read it with:
+
+- `nself ci evidence <run> --json`, the evidence of one run.
+- `nself ci evidence --pipeline <name>`, the last passing run of each job of a scheduled pipeline, with `overdue` marked when it is older than the pipeline's `max_age`.
+- `nself ci evidence verify <revision> [--json]`, a yes or no for a commit under the policy in force.
+
+### Binding and freshness
+
+**Binding** says whether the result is about a commit. It is `bound` when the working tree matched the commit throughout the run. It is `unbound`, with a reason, when the tree was dirty or changed during the run. Hidden edits count: the tree is read again when the run completes. Tracked files marked `skip-worktree` or `assume-unchanged` unbind the run, except a `skip-worktree` path that is absent because of a sparse checkout. Ignored files such as `.env` or `go.work` stay outside the binding, and jobs still see them, which is a known limitation.
+
+**Freshness** says whether the evidence still describes the present: `current`, `stale` or `unknown`. It is computed when you read the evidence, never stored, and a document's own claim is never trusted. Evidence goes stale when the inputs it covers have changed, when it was made under another policy, or when the working tree has uncommitted changes. It is `unknown` when the inputs cannot be read, and unknown is never treated as current.
+
+### Verify
+
+`evidence verify <revision>` returns a verdict you can act on in a script or a hook. It serves stored evidence only when that evidence is a finished run, with a full selection, of the default pipeline, for this repository, under the policy in force. Anything else is rerun in a temporary worktree with hooks, file-system monitors and LFS smudging turned off, and always with a full selection. An interrupted or errored rerun exits 2. The verdict is the exit code: 0 for current, bound, passing evidence; 1 when the evidence fails; 10 when it is stale, which includes another policy; 11 when it is invalid, which includes another repository; and 12 when it is unbound. Evidence from ad hoc commands and drills never gates a commit. The whole exit-code table is generated in the [[CI reference|guides/ci/Reference]].
+
+`--file <path>` verifies a document you were given. A file alone proves nothing about where it came from, so a file with no local record of its run is refused with exit 11 when it would otherwise pass. A document signed by a remote runner goes through the registered verifier, and its repository and policy digest are checked.
+
+## Machine output
+
+Add `--json` to any command and it prints one envelope on stdout:
+
+```text
+{ "schema_version": "1", "command": "ci runs wait", "data": { ... } }
+{ "schema_version": "1", "command": "ci plan", "error": { "code": "E620", "message": "...", "exit_code": 1, "class": "user" } }
+```
+
+`data` is the result, and `error` replaces it on failure with a stable code, the exit code and a class. Programs should read the code and the exit code, not the message.
+
+A run also emits a stream of events with schema `ci.events/v1`, one JSON object per line, in order: `queued`, `planned`, `leased`, `started`, `log`, `check_result`, `retrying`, `cancelled`, `needs_operator`, `finished` and `evidence`. Each carries a sequence number, a time, the run and, when it applies, the job. `--stream` prints it live. One writer produces the stream; log records are best effort and are dropped after a bounded wait rather than slowing a job, with no gap in the sequence. A failed stream flushes its error line first.
+
+Usage errors exit 1 across the tool. The full table of exit codes and error codes is generated in the [[CI reference|guides/ci/Reference]].
+
+## Start a run and come back later
+
+A foreground run holds your terminal. An agent, a script or an editor often cannot wait, so a run can be started in the background and collected later. The handle is a document of schema `ci.run-handle/v1`, which is experimental until the next major version.
+
+```text
+NSELF_V15=1 nself ci --detach --json [flags] [repo] [-- <cmd>]
+```
+
+`--detach` starts the run in a new session, detached from your terminal, and prints the handle once the run is queued. The handle gives the run id and argument lists for the next steps: `wait`, `follow`, `evidence`, `cancel` and `logs`. If the run cannot be queued within thirty seconds, the command fails with `E648` and a reason (`spawn`, `no_queued_event` or `child_exit`); it ends the child and shows a redacted tail of what the child printed.
+
+Then choose how to collect it:
+
+- **Poll.** `nself ci runs wait <run> [--timeout d] [--json]` waits up to the timeout, and exits 0 when the run is over or 10 while it is still running. When it exits 0, read `data.state` for the outcome: `passed`, `failed`, `cancelled` or `lost`. The timeout defaults to four minutes and is shortened to fit `NSELF_INVOKE_DEADLINE_MS` when a caller sets one, so a tool with its own time limit never hangs. Exit 10 means call it again.
+- **Stream.** `nself ci runs follow <run> [--from-seq n]` prints the events of the run as NDJSON. It replays what happened and tails the run until the `result` line. A run with no stored stream is rebuilt from the store in the same order, so the sequence never depends on when you looked. A run that died without a result ends with an `E648` error line and exit 2.
+- **Read the result.** `nself ci evidence <run> --json`.
+- **Stop it.** `nself ci runs cancel <run>`.
+
+A complete example, which starts a run, waits for it with a bounded loop, then reads the events and the evidence:
+
+```bash
+mkdir async && cd async && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir .nself && cat > .nself/ci.yaml <<'CFG'
+version: 1
+jobs:
+  show:
+    kind: test
+    run: [sh, -c, "echo hello"]
+CFG
+git add -A && git commit -q -m init
+nself ci --detach --json --no-status > handle.json
+run=$(sed -n 's/.*"run_id": "\(.*\)",/\1/p' handle.json)
+rc=10
+while [ "$rc" -eq 10 ]; do
+  rc=0
+  nself ci runs wait "$run" --timeout 30s --json > wait.json || rc=$?
+done
+[ "$rc" -eq 0 ]
+grep -q '"state": "passed"' wait.json
+nself ci runs follow "$run" > events.ndjson
+grep -q '"type":"finished"' events.ndjson
+nself ci evidence "$run" --json > evidence.json
+grep -q '"result": "pass"' evidence.json
+```
+
+A few limits to know. Streams and pid files of runs that no longer exist are removed by `runs prune` and by every `--detach`. A system that kills every process in a control group when the caller exits can still kill the detached child; start the run from a context that outlives the caller if you rely on it. `--coordinator` is read from the arguments or `NSELF_CI_COORDINATOR`.
+
+## Ad hoc commands
+
+`nself ci [flags] -- <command> [args]` runs one command through the same machinery: a real run with a store entry, a log and an evidence document, but a pipeline of kind `adhoc` that never gates anything and never posts a status. It is the safe way to let a person or an agent run a command with a record.
+
+| Flag | Meaning |
+|---|---|
+| `--isolation container\|process\|sandboxed-container` | the isolation level; `container` is the default and needs Docker |
+| `--image <ref@digest>` | the container image, pinned by digest |
+| `--network none\|restricted\|internet\|lan` | the network scope; none by default, or the service network when `--service` is given |
+| `--service <name>` | a disposable service the command can reach |
+| `--trust owner\|collaborator\|internal\|untrusted` | the trust class of the command's source |
+
+The command is exec'd as given. The workspace is mounted read-only, scratch space is a temporary file system, and the environment is only a language setting, a home and a temporary directory.
+
+**What isolation does and does not do.** A container reduces what a command can touch, and it is not a boundary against hostile code. `--isolation process` runs on the host with the host network and a writable copy of the workspace, prints a warning and records the network scope as `lan`. An `untrusted` source needs the sandboxed level, and a host without it refuses the command with `E647` and runs nothing. `--network internet` is refused until the network planner for the level allows it, and is never widened silently. Your model of risk is in [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]].
+
+**What it records.** The evidence names the isolation level actually used, the requested trust class, the redacted command line and the network scope. Redaction of the command line goes by the shape and name of an argument, so a secret passed as a bare positional argument is not recognised. Do not pass secrets that way.
+
+## Evidence fields
+
+The tables below are generated from the schema. Change the model, then regenerate.
+
+<!-- BEGIN GENERATED:evidence-fields -->
+#### Evidence document (root)
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `schema` | string | yes |  |
+| `revision` | string | yes |  |
+| `repo_id` | string | yes |  |
+| `run_id` | string | yes |  |
+| `pipeline` | `PipelineRef` | yes |  |
+| `job` | string or null | no |  |
+| `attempt` | `AttemptRef` or null | no |  |
+| `trigger` | string | yes | `push`, `pull_request`, `tag`, `manual`, `schedule`, `api`, `local` |
+| `source_trust` | string | yes | `owner`, `collaborator`, `internal`, `untrusted` |
+| `policy_digest` | string | yes |  |
+| `input_digests` | `InputDigests` | yes |  |
+| `worktree_state` | string | yes | `clean`, `dirty` |
+| `tracked_changes_digest` | string or null | yes |  |
+| `binding` | `Binding` | yes |  |
+| `runner` | `RunnerRef` | yes |  |
+| `producer` | `Producer` | yes |  |
+| `timings` | `Timings` | yes |  |
+| `tool_versions` | map of string | yes |  |
+| `checks` | list of `Check` | yes |  |
+| `artifacts` | list of `Artifact` | yes |  |
+| `retries` | list of `Retry` | yes |  |
+| `selection` | `Selection` | yes |  |
+| `placement_ref` | string or null | no |  |
+| `result` | string | yes | `pass`, `fail`, `error`, `cancelled` |
+| `counts` | `Counts` | yes |  |
+| `freshness` | `Freshness` | yes |  |
+| `signature` | `Signature` | yes |  |
+| `provider_attestation` | `ProviderAttestation` or null | no |  |
+| `attempts` | list of `AttemptEvidence` | no |  |
+| `errors` | list of `EvidenceError` | no |  |
+
+#### `PipelineRef`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `id` | string | yes |  |
+| `name` | string | yes |  |
+| `kind` | string | yes | `default`, `named`, `drill`, `adhoc` |
+
+#### `AttemptRef`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `id` | string | yes |  |
+| `n` | integer | yes |  |
+
+#### `InputDigests`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `config` | string | yes |  |
+| `lockfiles` | list of `DigestRef` | yes |  |
+| `generated` | list of `DigestRef` | yes |  |
+
+#### `Binding`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `state` | string | yes | `bound`, `unbound` |
+| `reason` | string or null | yes | `dirty`, `sha_mismatch` |
+
+#### `RunnerRef`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `id` | string | yes |  |
+| `provider` | string | yes |  |
+| `platform` | string | yes |  |
+| `isolation` | string | yes | `process`, `container`, `sandboxed-container`, `vm`, `ephemeral-vm`, `hosted-disposable` |
+
+#### `Producer`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `kind` | string | yes | `coordinator-recorded`, `signed-remote`, `self-reported` |
+| `version` | string | yes |  |
+
+#### `Timings`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `queued_at` | string or null | yes |  |
+| `started_at` | string or null | yes |  |
+| `finished_at` | string or null | yes |  |
+| `duration_ms` | integer or null | yes |  |
+
+#### `Check`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `id` | string | yes |  |
+| `job_id` | string | yes |  |
+| `kind` | string | yes |  |
+| `tool` | string | yes |  |
+| `tool_version` | string or null | yes |  |
+| `required` | boolean | yes |  |
+| `substantive` | boolean | yes |  |
+| `allow_failure` | boolean | no |  |
+| `result` | string | yes | `pass`, `fail`, `skip`, `error` |
+| `reason` | string | no | `pipeline.excluded`, `selection.no_base`, `selection.full_required`, `selection.affected`, `when.branch`, `when.paths`, `when.trigger`, `when.env_missing`, `dep.failed`, `fail_fast.cancelled`, `unplaceable.platform`, `unplaceable.docker`, `unplaceable.tool`, `unplaceable.service`, `unplaceable.label`, `unplaceable.resources`, `admission.battery`, `admission.reservation`, `advisory.tool_missing`, `advisory.data_offline` |
+| `failure_class` | string | no | `code`, `infra`, `timeout`, `cancelled`, `lost` |
+| `findings` | integer | yes |  |
+| `excerpt` | string | yes |  |
+| `log_ref` | string or null | yes |  |
+| `exit` | integer or null | no |  |
+| `diagnosis` | string | no |  |
+| `remediation` | string | no |  |
+| `flaky` | `Flaky` or null | no |  |
+
+#### `Artifact`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `path` | string | yes |  |
+| `sha256` | string | yes |  |
+| `size` | integer | yes |  |
+| `committed` | boolean | yes |  |
+
+#### `Retry`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `job_id` | string | yes |  |
+| `attempt` | integer | yes |  |
+| `class` | string | yes | `code`, `infra`, `timeout`, `cancelled`, `lost` |
+| `diagnosis` | string | no |  |
+| `excerpt` | string | no |  |
+
+#### `Selection`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `mode` | string | yes | `full`, `affected` |
+| `reason` | string | yes | `pipeline.excluded`, `selection.no_base`, `selection.full_required`, `selection.affected`, `when.branch`, `when.paths`, `when.trigger`, `when.env_missing`, `dep.failed`, `fail_fast.cancelled`, `unplaceable.platform`, `unplaceable.docker`, `unplaceable.tool`, `unplaceable.service`, `unplaceable.label`, `unplaceable.resources`, `admission.battery`, `admission.reservation`, `advisory.tool_missing`, `advisory.data_offline` |
+| `digest` | string | yes |  |
+
+#### `Counts`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `pass` | integer | yes |  |
+| `fail` | integer | yes |  |
+| `skip` | integer | yes |  |
+| `error` | integer | yes |  |
+| `total` | integer | yes |  |
+
+#### `Freshness`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `state` | string | yes | `current`, `stale`, `unknown` |
+| `reason` | string or null | yes |  |
+
+#### `Signature`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `kind` | string | yes | `coordinator-recorded`, `runner-ed25519` |
+| `key_id` | string or null | no |  |
+| `value` | string or null | no |  |
+
+#### `ProviderAttestation`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `provider` | string | yes |  |
+| `run_id` | string | yes |  |
+| `run_attempt` | integer | yes |  |
+| `ref` | string | yes |  |
+| `workflow_path` | string | yes |  |
+| `workflow_sha` | string | yes |  |
+| `workflow_digest` | string | yes |  |
+| `template_version` | string | yes |  |
+| `nonce` | string | yes |  |
+| `artifact_id` | string | yes |  |
+| `artifact_sha256` | string | yes |  |
+| `verified_at` | string | yes |  |
+
+#### `AttemptEvidence`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `job_id` | string | yes |  |
+| `attempt` | integer | yes |  |
+| `runner` | `AttemptRunner` | yes |  |
+| `timings` | `AttemptTimings` or null | no |  |
+
+#### `EvidenceError`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `code` | string | yes |  |
+| `job_id` | string | no |  |
+| `attempt` | integer | no |  |
+| `detail` | string | no |  |
+
+#### `DigestRef`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `path` | string | yes |  |
+| `sha256` | string | yes |  |
+
+#### `Flaky`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `source` | string | yes |  |
+| `passes` | integer | yes |  |
+| `fails` | integer | yes |  |
+
+#### `AttemptRunner`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `kind` | string | yes |  |
+| `tier` | string | yes |  |
+| `pool` | string | yes |  |
+| `rank` | integer | yes |  |
+
+#### `AttemptTimings`
+
+| Field | Type | Required | Values |
+|---|---|---|---|
+| `queue_ms` | integer or null | no |  |
+| `transfer_ms` | integer or null | no |  |
+| `run_ms` | integer or null | no |  |
+<!-- END GENERATED:evidence-fields -->
diff --git a/.github/wiki/guides/ci/Getting-Started.md b/.github/wiki/guides/ci/Getting-Started.md
new file mode 100644
index 000000000..2ea4480cd
--- /dev/null
+++ b/.github/wiki/guides/ci/Getting-Started.md
@@ -0,0 +1,127 @@
+# Getting started with nself ci
+
+<!-- docmap: cap:docs.ci-core -->
+
+`nself ci` runs your project's checks on your own machine and records what happened as signed-off evidence. It needs no cloud account, no hosted runner and no network beyond what your own tools use. This page takes you from nothing to a first recorded run, then covers what is detected, what stays local, the history you get for free, and container mode.
+
+Everything on this page is the v1.5 engine. Turn it on with `NSELF_V15=1` in your environment. Without it, `nself ci` runs the older gate; see [[Migrating to the new CI engine|guides/ci/Migration]]. The commands, flags and codes are listed in the generated [[CI reference|guides/ci/Reference]].
+
+## Install
+
+Install the plugin once, then check the machine:
+
+```text
+nself plugin install ci
+NSELF_V15=1 nself ci doctor
+```
+
+`doctor` checks the tools your repository needs, the container runtime, status posting, the local store and your configuration. Each finding has an id, a one-line reason and, when it can, a fix. A warning never blocks a run. Exit codes and the full list of ids are in the [[CI reference|guides/ci/Reference]]; what to do about one is in [[CI troubleshooting|guides/ci/Troubleshooting]].
+
+## Your first run
+
+Make a project, commit it, and ask what `nself ci` would do before it does anything:
+
+```bash
+mkdir hello && cd hello && git init -q
+git config user.email docs@example.com && git config user.name docs
+printf 'module example.com/hello\n\ngo 1.22\n' > go.mod
+printf 'package main\n\nfunc main() {}\n' > main.go
+git add -A && git commit -q -m init
+nself ci plan
+nself ci config show
+```
+
+`plan` prints the job graph: each job, whether it is required, why it was chosen (`selection.no_base` here, because nothing says what changed, so everything runs) and where it would be placed. `config show` prints every effective setting with the layer it came from. With no `.nself/ci.yaml` the detected defaults apply.
+
+A bare `nself ci` then runs the plan:
+
+```text
+NSELF_V15=1 nself ci
+```
+
+It runs the required jobs, prints one line per job, records the run in a local store, and ends with a result line. When the repository has a GitHub remote it also posts a `nself-ci` commit status; with no remote it says in one line why it did not. Add `--no-status` to never post.
+
+To run any single command through the same machinery, put it after `--`. The command runs in a container by default, with no network. On a machine without Docker, `--isolation process` runs it on the host instead and says so:
+
+```text
+nself ci --isolation process --no-status -- cat file.txt
+```
+
+An ad hoc run is recorded like any other, as a pipeline of kind `adhoc`, and never posts a status. The flags and their limits are in [[Evidence and machine output|guides/ci/Evidence-and-Machine-Output]].
+
+## What is detected
+
+`nself ci` reads manifests and lockfiles, never your source, to decide which checks apply. A check is planned only when its stack is present.
+
+| Stack | Detected from | Checks |
+|---|---|---|
+| Go | `go.mod` | format, vet, test, plus a vulnerability scan that is advisory |
+| Node | `package.json`, with npm, pnpm, yarn or bun chosen by lockfile; workspaces are walked | lint, typecheck, test, build |
+| Rust | `Cargo.toml` | clippy, test |
+| Flutter and Dart | `pubspec.yaml` | analyze, test |
+| Swift | `Package.swift`, or Xcode projects and workspaces with a shared scheme | `swift build` and `swift test`; `xcodebuild test` on a Mac with Xcode |
+| Python | `pyproject.toml` or requirements files; uv, poetry or pip chosen by lockfile | pytest when configured or when `tests/` exists; ruff and mypy when configured |
+| Dockerfiles | `Dockerfile*` | hadolint and a configuration scan, both advisory |
+| Secrets | any repository | `gitleaks` |
+
+Lockfile digests are recorded as evidence inputs. Services declared in a compose file are noticed, but a client library or an env sample never implies a service: a job gets a database only when you name one. See [[CI configuration and policy|guides/ci/Configuration-and-Policy]].
+
+Notes on the Apple and Python stacks:
+
+- Xcode checks need a shared scheme. Share the scheme in Xcode, or the project yields no check. The destination is the Mac itself, so iOS-only schemes need a custom job.
+- With `uv.lock` the Python checks use uv; otherwise with `poetry.lock` they use poetry; otherwise pip into a `.venv` in the job root.
+- Which checks are required and which are advisory is the table in [[CI configuration and policy|guides/ci/Configuration-and-Policy]].
+
+## Local-only, and what that does and does not give you
+
+The default run is local. Nothing leaves the machine unless a tool you run reaches out or you post a status. A drill in this repository proves the first run with the network cut off.
+
+- **Reservations.** A run started from your terminal uses the machine freely. Background work leaves headroom for you: by default two CPUs and a quarter of memory stay free, and deep jobs wait while a laptop is on battery below a threshold. A held job shows the reason code `admission.reservation` or `admission.battery`. `--force` ignores the reservations. A run under `CI=true` or without a terminal does not reserve anything.
+- **Isolation.** The `process` level runs a job as a child process in a copy of your workspace with a controlled environment, a time limit and a kill of the whole process tree on cancel. It is not a sandbox: the job shares your network, your user and your disk. The container level is stronger, and is still not a boundary against hostile code. Treat both as guard rails for your own code. The model is in [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]].
+- **Secrets.** Job output passes a redactor before it is stored, so a stored log never holds a value the redactor knew. Evidence holds redacted excerpts only.
+
+## History, logs and retention
+
+Every run is stored locally, with its jobs, attempts, evidence and logs.
+
+- `nself ci runs list [--limit N] [--json]` lists recent runs with result, duration, revision, binding and freshness.
+- `nself ci runs <run>` shows one run. `nself ci logs <job|attempt> [-f] [--json] [--run <run>] [--attempt N]` prints its log, and `-f` follows a live one within about a second.
+- Logs hold redacted output only, as JSON lines with a sequence number. The sequence is the order; two lines in one burst can share a timestamp.
+
+Retention keeps the newest runs, drops old ones and caps the size of stored logs. It runs when a run starts and on `nself ci runs prune [--dry-run]`, and a run in progress is never removed. The limits are defaults you override in `retention.json` in the state directory. `runs prune` states what it removed.
+
+```bash
+mkdir keep && cd keep && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir .nself && cat > .nself/ci.yaml <<'CFG'
+version: 1
+jobs:
+  check:
+    kind: test
+    run: [sh, -c, "echo checked"]
+CFG
+git add -A && git commit -q -m init
+nself ci --no-status
+nself ci runs list
+nself ci logs check
+nself ci runs prune --dry-run
+```
+
+The state directory is `$NSELF_CI_HOME`, which defaults to a folder in your home directory.
+
+## Container mode
+
+`nself ci --container` runs each job in one pinned toolchain image instead of the tools on your machine, so a result does not depend on which Go or Node you have installed. The image carries its tools by checksum, and the pinned versions are in the generated table of the [[CI reference|guides/ci/Reference]]. The first run on a host pulls the whole image; after that a tool bump re-pulls one layer.
+
+- The image reference must be pinned by digest. A tag alone is refused. `--image <ref@digest>` or `NSELF_CI_IMAGE` selects another image.
+- There is no silent fallback to host tools. If the image is not available the run stops with an error that names the problem.
+- Container mode needs Docker or a compatible runtime. `doctor` tells you whether it is reachable.
+
+Flutter has no tool in the image, so Flutter checks always run with the host tools.
+
+## Next steps
+
+- Describe your own jobs, services and pipelines: [[CI configuration and policy|guides/ci/Configuration-and-Policy]].
+- Read results as data, or start a run and come back later: [[Evidence and machine output|guides/ci/Evidence-and-Machine-Output]].
+- Add a second machine: [[Nodes and Runners|guides/ci/Nodes-and-Runners]].
+- Something failed: [[CI troubleshooting|guides/ci/Troubleshooting]].
diff --git a/.github/wiki/guides/ci/Hosted-Providers.md b/.github/wiki/guides/ci/Hosted-Providers.md
new file mode 100644
index 000000000..8a70f7dc9
--- /dev/null
+++ b/.github/wiki/guides/ci/Hosted-Providers.md
@@ -0,0 +1,259 @@
+# Hosted providers
+
+This guide covers the forges and hosted runners that `nself ci` can dispatch to: GitHub and GitLab. It explains how to connect them, how their runs are trusted, what capacity and spend they use, how requests reach your coordinator, and what happens when a provider goes down.
+
+Command names and doctor check ids are not repeated here. They come from the generated [CI reference](Reference.md#commands). Read the commands there first, and check [the doctor table](Reference.md#doctor-checks) when a check fails.
+
+## GitHub
+
+### Credentials and scopes
+
+The coordinator never stores a token value. Policy names the environment variable that holds it:
+
+```text
+nself ci policy set --scope user providers.github.token_env <ENV_NAME>
+```
+
+`nself ci providers test <id>` reads the token and reports what it can do. The provider id comes from `nself ci providers list`. A classic token reports its scopes. A fine-grained token sends no scopes header, so the probe reports the scopes as unknown and checks the access it can see through the API. No credential value appears in any output of the providers commands, the doctor section or the Forgejo alias.
+
+### `providers github init`
+
+`nself ci providers github init` renders the dispatch workflow from the template and writes it to `.github/workflows/nself-ci-dispatch.yml` in your repository:
+
+```text
+nself ci providers github init --stdout --agent-source source
+nself ci providers github init --dir <repo> --agent-source source
+nself ci providers github init --check --dir <repo> --agent-source source
+```
+
+- `--stdout` prints the file and writes nothing.
+- `--check` reports drift between the rendering and the default branch copy and the untrusted ref copy. It exits 1 on drift.
+- `--agent-source` chooses `source` or `release`. Without the flag, the value comes from `providers.github.agent_source` in policy.
+- `--json` returns the same result as one JSON envelope.
+
+The command never pushes. For each ref that is out of date, it prints the exact commands that would create or update it, and leaves running them to you. A file without the generated marker is never overwritten.
+
+### The untrusted ref and why it exists
+
+The dispatch workflow exists in two places: the default branch and a separate untrusted ref. Both copies must equal the rendering. `--check` fails when either one drifts.
+
+The ref matters because of source trust. A run is classed by facts the forge reports, and a push to a ref that is not protected does not get owner trust. The table in [Trust, security and privacy](Trust-Security-and-Privacy.md#source-trust-who-made-the-code) lists each fact and its result. A missing fact takes its untrusted value.
+
+### Standard labels only
+
+Hosted jobs request standard labels only. The label set is generated from the template. It is not repeated here, so the template stays the only source.
+
+### What a self-reported result proves
+
+A GitHub run reports its result through the API. The coordinator records that report with the provider's attestation. Read [the attestation fields](Evidence-and-Machine-Output.md#providerattestation) for the exact shape.
+
+The attestation proves what the provider reported for a run and a commit. It does not prove that the code ran on a node you control, and it does not prove the runner image beyond what the record states. Treat it as the provider's account of the run.
+
+### JIT runners on your nodes
+
+Your own Linux nodes can take GitHub jobs through just-in-time (JIT) runners. Each runner registers for one job and is removed when the job ends.
+
+Limits that matter:
+
+- A JIT job is classed untrusted unless the organization runner group meets the protected-group rule below. An untrusted job gets no secrets and no protected-branch rights.
+- The node must be a Linux gVisor node. See [the sandboxed container level](Trust-Security-and-Privacy.md#the-sandboxed-container-level-gvisor).
+- A repository-level runner is never proven restricted, because a runner group governs organization runners only. Repository runners run every workflow of their repository, fork pull requests included.
+
+### Runner groups
+
+A runner group counts as protected only when the API shows all of these:
+
+- the group allows no public repositories,
+- the group is restricted to workflows,
+- the group lists at least one workflow,
+- every listed workflow is pinned to a concrete protected branch.
+
+An unreadable reply, or a reply that leaves out a field, is recorded as not verified. It is never read as verified.
+
+This rule describes the group. It does not make a workflow safe that checks out fork code. A `pull_request_target` or `workflow_run` workflow still runs fork code on the runner, and the trust rules decide that from the event, the head repository and the fork flag.
+
+### Fork approval
+
+The fork pull request approval policy is read from the API and stored as a provider fact. A first-time contributor's run needs an approval before it starts. Fork pull requests always run on GitHub-hosted runners, whatever your repository variable says. The [workflow below](#required-check-with-your-own-nodes) applies this rule.
+
+### Webhooks and per-repo secrets
+
+Webhook deliveries are verified with a per-repository secret. Policy maps each `owner/repo` to the name of the environment variable that holds its secret:
+
+```text
+nself ci policy set --scope user providers.github.webhook_secrets '{"owner/repo":"<ENV_NAME>"}'
+```
+
+Ingress is covered in [Ingress: poll or webhook](#ingress-poll-or-webhook).
+
+### Reconciliation
+
+A reconcile pass is one counted, budgeted session over one repository. Every request goes through the provider REST client.
+
+- A `304 Not Modified` reply costs nothing against the hourly ledger.
+- A quota error records a retry time once and ends the pass.
+- While the retry time is in the future, the coordinator makes no requests at all.
+
+## GitLab
+
+### Status in this release
+
+GitLab support is tested against fixtures. The pipeline, status and runner paths have fixture tests, but no live GitLab run is covered by the test suite. Check the output of `nself ci providers test gitlab` against your own instance before you rely on it.
+
+### Pipeline API and project token
+
+The include file is what a GitLab pipeline loads. Render it with:
+
+```text
+nself ci providers gitlab init --stdout
+nself ci providers gitlab init --dir <repo>
+nself ci providers gitlab init --check --dir <repo>
+```
+
+The coordinator reaches the GitLab pipeline API with the project token. Policy names the environment variable that holds it under `providers.gitlab.token_env`. `providers test` reads that token's own record, with its role and scopes. Roles are reported by GitLab's access levels.
+
+For runners, `providers.gitlab.runner_token_env` names the runner token. `nself ci providers test <id>` checks its scopes. A runner token without `create_runner` fails the probe.
+
+### Untrusted ref for GitLab
+
+`providers gitlab init --untrusted-dir <dir>` writes the two generated files of the untrusted ref into a directory. Add `--inputs` to write the inputs variant. Nothing is pushed. The check compares the default branch copy and both untrusted ref files with the rendering, and reports any missing file.
+
+### Statuses
+
+Commit statuses go through the GitLab status adapter. Status reporting is covered by fixture tests only, as described above.
+
+### Signing secrets and secret tokens
+
+GitLab webhooks can be verified in two ways.
+
+| Method | Key | Check |
+|---|---|---|
+| Signing secret (Standard Webhooks) | `providers.gitlab.webhook_signing_secrets` | HMAC over the delivery, with a `whsec_` secret |
+| Secret token | the token key next to it | `X-Gitlab-Token`, compared in constant time |
+
+A project listed under the signing key is a signing project. For that project the bare token is never accepted, so a copied token cannot replace the signature. Use signing secrets where your GitLab version supports them.
+
+### Runners
+
+GitLab runners use the runner token named above. The token needs `create_runner`.
+
+## Hosted capacity
+
+### Included capacity and cost class
+
+Included capacity from a hosted provider is a cost class. The classes, and how the scheduler weighs them, are in [CI scheduling and cost](Scheduling-and-Cost.md#cost-classes).
+
+### The SCHED ceiling rule
+
+A provider's allowance is bounded by its declared ceiling. The allowance is the declared ceiling, minus what the provider reported as used, minus what the local ledger spent since the newest day the provider's report covers. Providers report with a delay, so the local ledger fills the gap.
+
+Paid placement is off by default. It needs `economics.paid_enabled` and a day or month budget above zero. The full rule, including rates and approval, is in [CI scheduling and cost](Scheduling-and-Cost.md).
+
+### Usage import and confidence
+
+`nself ci providers usage import` reads the provider's billing data into the ledger. Run it against a repository root:
+
+```text
+nself ci providers usage import --repo <dir>
+```
+
+The ledger shows every figure with a confidence label and its source. The labels and what each one means are in [the ledger table](Scheduling-and-Cost.md#the-ledger-and-its-confidence). Read `nself ci policy usage` for the current ledger.
+
+### Outage behaviour
+
+Each provider has a health breaker that moves between up, degraded and down.
+
+- It opens to down after a run of consecutive failures inside a short window.
+- While a probe is in progress, a down provider reads as degraded. Placement may send work elsewhere during that time.
+- A quota answer (429) says nothing about the provider's health, so it does not open the breaker.
+- Server errors count only as a repeated run, not as one error.
+- A successful probe ends the outage. Placement does not treat that probe as a success until the provider is back up.
+
+What happens to queued work after that is placement's decision. See [CI scheduling and cost](Scheduling-and-Cost.md).
+
+## Schedules
+
+Scheduled runs need a protected ref or a reachable sha. Without one, a scheduled run is classed untrusted, as the trust table in [Trust, security and privacy](Trust-Security-and-Privacy.md#source-trust-who-made-the-code) shows.
+
+## Authorization
+
+A provider can run work for a project only after an admin authorizes it. The project is a repository path.
+
+```text
+nself ci providers authorize <id> --project <repository path>
+nself ci providers revoke <id> --project <repository path>
+nself ci providers list
+nself ci providers show <id>
+```
+
+- `authorize` and `revoke` are admin-only and audited.
+- After `revoke`, the next admission for that project fails with the reason `privacy.provider_not_allowlisted`.
+- `list` and `show` only read. They write nothing.
+- A `.nself/ci.yaml` in a revision cannot authorize a provider. Authorization comes from the operator's store.
+
+`--allow-private` on `authorize` writes the privacy zone first. It then prints the SCHED ceiling command for you to review. It never runs that command. Zones and their rules are in [Trust, security and privacy](Trust-Security-and-Privacy.md#network-scopes).
+
+## Doctor
+
+Provider checks are not part of the default doctor run. Add the flag:
+
+```text
+nself ci doctor --providers
+nself ci doctor --providers --json --repo <dir>
+```
+
+The provider check ids are in [the doctor table](Reference.md#doctor-checks). `nself ci doctor` has no provider subcommand. Use the flag.
+
+`nself ci forgejo` still runs for now, but it is an alias. It prints a deprecation line that names `nself ci doctor --providers` and states the release where the alias is removed. Move your scripts to the flag before then.
+
+## Ingress: poll or webhook
+
+Poll is the default. The coordinator asks the forge for changes over outbound connections only, so no inbound port needs to be open.
+
+Webhook mode is optional. It needs all of these:
+
+- `nself ci serve` reachable through a TLS reverse proxy.
+- The proxy forwards only `/webhook`. It must not forward anything else.
+- A per-repository secret for each repository. See [Webhooks and per-repo secrets](#webhooks-and-per-repo-secrets).
+- The agent and user API listeners stay unexposed. The proxy never reaches them.
+
+The loopback bind stays the default. `nself ci serve` listens on loopback unless you pass `--addr` with an address you have chosen on purpose.
+
+```text
+nself ci serve --addr <host:port>
+```
+
+## Required check with your own nodes
+
+The required `nself-ci` check is pinned to GitHub Actions. A status posted from your own coordinator does not satisfy it, however good the local result is. Only a job that runs in GitHub Actions and reports the `nself-ci` name satisfies the check.
+
+Your own nodes can still run that job. The `nself-ci` job runs on JIT runners, and a repository variable chooses where it runs:
+
+- `runs-on` is `[self-hosted, nself]` when the variable selects your nodes.
+- Otherwise it is `ubuntu-latest`.
+- Fork pull requests always use GitHub-hosted runners, whatever the variable says.
+- A JIT job is untrusted unless the protected-runner-group rule holds, so the node must be a Linux gVisor node.
+
+<!-- snippet: nself-ci-own-nodes -->
+```yaml
+name: nself-ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  nself-ci:
+    name: nself-ci
+    runs-on: ${{ (vars.NSELF_CI_RUNNER == 'nself' && !github.event.pull_request.head.repo.fork) && fromJSON('["self-hosted","nself"]') || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run the nself-ci gate
+        run: nself ci run
+```
+
+Without a node that meets the rule above, keep the check on GitHub-hosted runners. Your own nodes still give a fast gate before you push. Run `nself ci run` locally for that, and treat it as a pre-push check, not as the required status.
diff --git a/.github/wiki/guides/ci/Migration.md b/.github/wiki/guides/ci/Migration.md
new file mode 100644
index 000000000..be7e6cf09
--- /dev/null
+++ b/.github/wiki/guides/ci/Migration.md
@@ -0,0 +1,88 @@
+# Migrating to the new CI engine
+
+<!-- docmap: cap:docs.ci-core -->
+
+This page is for you if you already use the earlier `nself ci` gate, the `.ci.yaml` manifests that `nself ci run` discovers, or the wrapper-script workflow that older versions of this wiki described. It lists what changes, how to move your configuration, and how to adopt the gate in another repository. It replaces the old adoption guide.
+
+The new engine is on when `NSELF_V15=1` is set. The plugin binary does not follow the CLI's own switch yet, so the workflow template sets the variable itself. Until the older path is removed, both run side by side, and you can try the new one in a shell without touching a team workflow.
+
+## What changes
+
+| Before | Now |
+|---|---|
+| Configuration lived in `.ci.yaml` files per plugin, discovered by `nself ci run` | One `.nself/ci.yaml` at the repository root, validated against a schema. `nself ci run` becomes `nself ci --trigger manual`. |
+| A fixed gate per stack, read from the repository root | Checks per detected stack and directory, planned as a job graph with a reason for every job. See [[CI configuration and policy|guides/ci/Configuration-and-Policy]]. |
+| A pass or a fail, printed | A pass, fail, error or cancelled result with evidence, history, logs and a stored record. See [[Evidence and machine output|guides/ci/Evidence-and-Machine-Output]]. |
+| The commit status was posted by every run | A status is posted only for a full, bound, default-pipeline run from an owner or internal source that was not cancelled. `--job`, `--pipeline`, a dirty tree, a tree that changed during the run and a `--config` outside the repository never post. |
+| A missing `gitleaks` was treated as a pass | A missing required tool is `E614`, so the secret scan can no longer pass by being absent. Install `gitleaks` or the run stops. |
+| `--sha` chose the commit | Not supported. Use `nself ci evidence verify <revision>`. |
+| `nself ci eval` was part of the gate | `eval` is a separate command of the `nself-eval-gate` plugin, `nself eval`. A project that wants it in CI runs it as a job. |
+| `nself ci build --artifact android` built in place with Gradle | The arguments are unchanged. Under the new engine it runs a release pipeline and publishes a release directory you can verify. The earlier path is removed when the earlier engine is. |
+| Output was text | `--json` gives a stable envelope for every command, and `--stream` gives events. |
+
+Two rules for upgrades and downgrades: the evidence documents gained fields, and an older build rejects a newer document, so downgrading means regenerating evidence. The local database refuses to open under a binary older than it needs, with a clear error.
+
+## Move your configuration
+
+`nself ci config migrate` reads the legacy `.ci.yaml` files and prints the `.nself/ci.yaml` they would become. Nothing is written until you ask:
+
+```bash
+mkdir legacy && cd legacy && git init -q
+git config user.email docs@example.com && git config user.name docs
+cat > .ci.yaml <<'EOF'
+plugin: example
+stages:
+  - name: unit
+    cmd: ["go", "test", "./..."]
+    timeout: 120
+  - name: integration
+    cmd: ["go", "test", "-tags", "integration", "./..."]
+    env_required:
+      - DATABASE_URL
+    skip_if_env_missing: true
+EOF
+nself ci config migrate
+```
+
+Run it, read the diff and the notes it prints, then write the file with `nself ci config migrate --write`. It never writes through a symlink and never overwrites a different file. When you are satisfied, delete the legacy files; a leftover `.ci.yaml` is reported as `E621`.
+
+**Migration follows what your file declares.** The earlier runner did not parse YAML. It read `timeout` and `skip_if_env_missing` only at one indentation, read list items only at another, filed all-caps list items under `env_required` and skipped a manifest with no top-level `plugin:` key. A manifest written as valid YAML, with `cmd: [..]` on one line, could therefore declare commands that never ran. `migrate` prints a note for each stage and field where the old reading and the declared meaning differ, so the first run under the new engine may run commands the old one silently skipped. That is the intended change.
+
+What carries over:
+
+| Legacy | Becomes |
+|---|---|
+| `cmd` | `run` |
+| `timeout` | `timeout`, in seconds converted to a duration; a stage without one gets the old default of 300 seconds, written explicitly |
+| `env_required` with `skip_if_env_missing` | `required: false` and `when.env_present` |
+| stage order | nothing: jobs are independent |
+
+The last row matters. The old runner ran stages in order in one directory and gave no information about which stage consumed another's output, so `migrate` invents no dependencies and prints a note. Add `deps:` wherever one stage reads files another writes, or merge the commands into one job. Null or nested list items, anchors, aliases, merge keys, a second YAML document and unknown fields are refused with `E622`.
+
+## Adopt the gate in another repository
+
+This is the pattern first proven on this repository, rewritten for the current engine. It replaces the earlier wrapper-script recipe, whose script no longer exists.
+
+1. **Describe the gate.** If your repository is a single stack with standard scripts, you need no file. Otherwise write `.nself/ci.yaml` with the jobs you want. Declaring jobs turns detection off for the repository, so a gate is exactly the list you declare. A repository with many modules should say so: detection would otherwise plan a job per module.
+2. **Run it locally first.** `nself ci plan` shows which checks will run, and `NSELF_V15=1 nself ci` runs them. Read the plan. Do not assume.
+3. **Add the workflow.** Copy `free/ci/templates/nself-ci.yml` from the plugins repository to `.github/workflows/nself-ci.yml`, fill in the pinned release, and add your toolchain setup. The template is described under [Configuration and policy](./Configuration-and-Policy.md#the-workflow-template).
+4. **Require it, as an addition.** Run `nself ci policy protect --repo <owner>/<name> --dry-run`, review the body, then apply it. It saves the previous protection first and can restore it. Add `nself-ci` next to your existing required checks, not instead of them, until you have seen it catch what they catch.
+5. **Guard the main branch.** `nself ci policy protect --hook` installs a pre-push hook for the default branch, and `--audit <days>` lists commits that never had a green `nself-ci`.
+
+### Read this before making it your only gate
+
+A gate can pass while checking nothing. That is the failure to look for, and it is why step 2 matters.
+
+- **A stack the detector does not see.** The earlier gate decided whether a Node repository had work by looking for scripts in the root `package.json`. A repository whose real scripts sat under another name, or in workspace members without a workspace file, ran only the secret scan and printed a pass. The new planner walks directories and workspaces and gives every skipped job a reason, but a custom script name still needs a job of your own. `nself ci plan` is the place to see it.
+- **Per-package checks.** Repository-wide checks do not replace checks that belong to a package or a plugin, such as schema validation, conformance or registry consistency. Keep those workflows.
+- **Work the engine does not do.** `nself ci` is not an emulator for hosted workflow files. End-to-end tests, accessibility audits, code scanning, licence audits, coverage ratchets, bundle size checks and deploys need their own jobs. Public repositories can keep them on free hosted runners.
+- **Forks.** A token on a fork pull request is read-only, so a commit status cannot be posted from it. The workflow template produces a check run instead, which fork and bot pull requests still get.
+
+### Rollout checklist
+
+- [ ] `.nself/ci.yaml` written, or the detected plan reviewed and accepted.
+- [ ] `NSELF_V15=1 nself ci plan` read, and each stack you care about appears.
+- [ ] `nself ci` passes locally with `gitleaks` installed.
+- [ ] The workflow runs once on a pull request and the `nself-ci` check appears.
+- [ ] `policy protect --dry-run` reviewed by the person who owns branch protection, then applied as an additional required check.
+- [ ] The earlier workflow or wrapper script removed, and no page of your documentation links to it.
diff --git a/.github/wiki/guides/ci/Nodes-and-Runners.md b/.github/wiki/guides/ci/Nodes-and-Runners.md
new file mode 100644
index 000000000..5cf8dc7ae
--- /dev/null
+++ b/.github/wiki/guides/ci/Nodes-and-Runners.md
@@ -0,0 +1,68 @@
+# Nodes and Runners
+
+<!-- docmap: cap:ci.nodes-cli -->
+<!-- docmap: cap:ci.pairing -->
+<!-- docmap: cap:ci.coordinator -->
+<!-- docmap: cap:ci.coordinator-client -->
+<!-- docmap: cap:ci.node-doctor -->
+<!-- docmap: cap:ci.node-bootstrap -->
+
+Use a spare home-lab machine, laptop, or dedicated VPS for CI. Keep deployment machines out of the runner pool. The node surface described here is enabled with `NSELF_V15=1`. See the generated [commands](./Reference.md#commands) and [pinned versions](./Reference.md#pinned-versions) for the installed build.
+
+Examples below follow the linked tests. Replace angle-bracket placeholders with verified fingerprints, trusted binary paths, or state paths. Enrollment and maintenance require real machines and existing state, so these examples are inline instructions rather than standalone scripts.
+
+## LAN
+
+**Add versus pair.** For an SSH host you administer, use `nself ci nodes add ci@cli1 --host-key <fingerprint> --agent-binary <binary> --json`. Here `cli1` is an SSH alias to configure for your machine. Add verifies the host key, installs the supplied agent, probes capabilities, and authorizes the current project. Obtain the fingerprint through a separate trusted channel. Inspect the result with `nself ci nodes list --json` and `nself ci nodes show cli1 --json`. These argument sequences come from [TestAddThroughRunEmitsEnvelope](../../../../free/ci/internal/nodes/lifecycle/cli_test.go).
+
+Use `nself ci nodes pair` on the coordinator host for certificate enrollment. Pair opens a foreground window and prints the join URL, coordinator root fingerprint, and a one-use code. Follow its printed `nself-ci-agent join` instruction on the node. Enter the code interactively, verify the coordinator fingerprint, and compare the node's CSR fingerprint at the coordinator before approving trust and project access. Do not put the code in arguments, shell history, or shared logs. See [TestNodesPairEndToEnd](../../../../free/ci/cmd/nodes_pair_test.go) and [join tests](../../../../free/ci/cmd/agent/join_test.go).
+
+**Discovery is off by default:** ordinary operations never browse or advertise on the LAN. Explicit discovery finds candidates only; it neither trusts nor enrolls them. Advertisement requires an explicit agent flag and a bounded window. `NSELF_CI_DISCOVERY=0` or user configuration `ci.discovery: off` disables even explicit discovery. With neither switch set, an explicit browse is allowed. A discovered name or fingerprint is a hint, not proof of identity. Pair using a known address when multicast is unavailable. See [discovery guard tests](../../../../free/ci/internal/discovery/guard_test.go) and [spoofing tests](../../../../free/ci/internal/discovery/spoof_test.go).
+
+**Laptops and reservations.** Reserve CPU and memory for the operator, protect interactive sessions, pause or drain on battery, and mark sleeping laptops intermittent. CPU reservations accept cores or a percentage; memory reservations accept MB or GB. These are scheduler reservations, not DHCP leases. For an enrolled `lap1`, `nself ci nodes set lap1 --reserve-cpu 50% --json` is the successful reservation example in [TestNodesRemoteAdminRevokesWithChainedAudit](../../../../free/ci/cmd/nodes_remote_test.go). Other controls are `--reserve-mem`, `--interactive protect`, `--on-battery pause` or `drain`, and `--persistence intermittent`; see [their definitions](../../../../free/ci/cmd/nodes_set.go).
+
+Keep an always-on home-lab box available for jobs that must finish while laptops sleep. A DHCP reservation or stable SSH alias helps reachability; it does not replace key verification or guarantee that a job lease survives sleep. User-mode Linux nodes without working UID separation remain owner-only and cannot gain signing or secret eligibility by advertising capabilities. See [separation tests](../../../../free/ci/internal/nodes/lifecycle/add_test.go).
+
+## VPS
+
+**Host keys and forced SSH options.** Use the same add flow for a dedicated VPS. If using an IP instead of an SSH alias, substitute an example address such as `203.0.113.20`. Verify the destination machine's key even through a jump host. A missing or changed pin stops the connection before job execution.
+
+The SSH carrier forces `BatchMode=yes` and `StrictHostKeyChecking=yes`, disables TTY allocation, agent and X11 forwarding, clears forwarding rules, and disables local commands, remote commands, and connection multiplexing. It uses a node-specific host-key alias and the coordinator's pinned known-hosts file. Global known hosts, DNS host-key verification, and known-hosts commands cannot replace that pin. An explicitly supplied identity also uses `IdentitiesOnly=yes`. Do not weaken these settings or discard the user known-hosts file. The exact forced options are checked by [TestSSHTransportForcesOptionSetAndPin](../../../../free/ci/internal/transport/ssh/run_test.go).
+
+**Provisioning versus bootstrap.** `nodes provision` installs self-hosted GitHub Actions runners, dependencies, service users, sudoers configuration, and runner instances. It requires a repository or organization URL and a registration token supplied privately, including through `GITHUB_RUNNER_TOKEN`. The runner download is pinned and checksum-checked. Provisioning records a provider node with unset trust acceptance and `eligible: false`; it does not enroll an eligible native agent. See [provisioning tests](../../../../free/ci/internal/nodes/provision/) and [TestProvisionedRunnerShowsInNodesListWithNullAccepts](../../../../free/ci/cmd/nodes_provision_v15_test.go).
+
+Native agent system bootstrap belongs to `nodes add --system`, not a separate bootstrap subcommand. Supply a trusted agent binary and connect as root or a user with passwordless sudo. Bootstrap creates the agent user, per-slot job users, and restricted job-shim sudoers rules. The landed installer still records this layout as **not UID-separated** until jobs actually use the shim; installation alone grants no secret or signing rights. See [TestSystemInstallBootstrapsAndKeepsTheNodeUnseparated](../../../../free/ci/cmd/nodes_bootstrap_test.go) and [macOS bootstrap tests](../../../../free/ci/cmd/nodes_bootstrap_macos_test.go).
+
+**Deploy hosts are ineligible.** A machine serving deployed applications is outside the normal CI pool because jobs could reach production state and credentials. Inventory checks and agent start guards enforce that boundary. An administrator's explicitly confirmed override permits only owner/internal work with VM isolation or stronger, no release/deploy secrets, and audited placement. Use another machine for CI. See [deploy-host tests](../../../../free/ci/cmd/nodes_override_test.go) and [production boundary rules](../../../../free/ci/internal/trust/prodboundary.go).
+
+## Team
+
+**Personal-nodes rule and `--team`.** A personal coordinator is for the operator's own nodes and work. An unseparated personal node is not a shared team runner; the owner-only personal exception does not carry into team mode. Once anyone other than the operator holds a grant, token, or certificate, start the coordinator with `--team`. This is a boolean flag on `nself ci serve`, not a team-name argument on node commands. The switch is permanent for that data directory and audited; omitting the flag later cannot restore personal mode. See [coordinator mode tests](../../../../free/ci/internal/coordinator/mode/mode_test.go).
+
+**Coordinator-host rule, TRUST D28.** In team mode, any job on the coordinator machine needs VM isolation or stronger. On a personal coordinator, collaborator and untrusted jobs have the same floor; the operator's owner/internal jobs retain their normal minimums. A container alone does not meet the VM floor. Prefer two boxes: keep coordinator state and keys on one, and execute jobs on a separate runner. See [D28 admission](../../../../free/ci/internal/trust/prodboundary.go) and [placement tests](../../../../free/ci/internal/coordinator/mode/floor_test.go).
+
+**Coordinator ports and pairing.** Port 3845 handles webhooks, triggers, and health checks and defaults to loopback. Port 3864 is the agent mTLS listener (`--agent-addr`). Port 3865 is the user API (`--api-addr`), defaulting to loopback, with TLS user certificates or scoped tokens; a Unix socket is also supported. Expose only intended interfaces and use an appropriate TLS endpoint where required. Enrollment has its own listener and pairing window, separate from the user API and agent session. See [agent listener tests](../../../../free/ci/cmd/serve_agent_listener_test.go), [user API implementation](../../../../free/ci/cmd/serve_user_listener.go), and [enrollment tests](../../../../free/ci/cmd/serve_enroll_listener_test.go).
+
+Run add and pair on the coordinator host. They are refused with remote `--coordinator`; that flag cannot move an interactive enrollment flow across the user API. Confirm fingerprints as described under LAN, then restrict accepted work and authorized projects.
+
+**Remote administration and drain.** Select the user API explicitly with `--coordinator <url>` on supported node commands. Configure its trusted root (`ci.coordinator_ca`) and use a user certificate or scoped token with the required project role. Members can list and show nodes; administrative changes require an admin. Without the flag, node commands stay local even if a coordinator is configured for runs. Data-directory access is administrative access. See [remote node tests](../../../../free/ci/cmd/nodes_remote_test.go).
+
+For enrolled `lap1`, the tested maintenance sequence is `nself ci nodes drain lap1 --json`, then `nself ci nodes enable lap1` after maintenance. Add `--coordinator <url>` to send either operation to the remote user API. Drain stops new leases; let active work finish before shutting down. These commands are exercised by [TestNodesRemoteAdminRevokesWithChainedAudit](../../../../free/ci/cmd/nodes_remote_test.go).
+
+**Backup/restore and the KEK.** [TestBackupRestoreCommandsRoundTrip](../../../../free/ci/cmd/serve_backup_test.go) exercises `nself ci serve backup --data-dir <source-dir> --out <archive> --json` and `nself ci serve restore --data-dir <destination-dir> --in <archive> --kek <saved-kek-file> --json`. Stop the destination coordinator before restore. Keep the source coordinator's key-encryption key (KEK) securely and separately: the archive deliberately excludes it, and a wrong KEK is refused before state is written. The archive alone cannot recover sealed key material.
+
+Restore verifies the archive, preserves existing revocations and deny-list entries, advances the incarnation, and rotates token signing keys. An empty-directory restore marks nodes `needs-reconfirm`; verify each before enabling it. Retain the saved previous state and rollback instructions until healthy. See [restore behavior](../../../../free/ci/cmd/serve_backup.go).
+
+**Rotation and revocation.** For a paired node, `nself ci nodes rotate node-pull --cert` denies its existing certificates; re-pair using the pinned node key for a fresh certificate. Node-key rotation explicitly supplies the replacement key ID and differs from SSH host-key rotation. Revocation denies certificates and expires leases. Certificate rotation and re-pairing cannot recover a revoked identity. See [rotation and revocation tests](../../../../free/ci/cmd/nodes_pair_test.go).
+
+**Upgrades.** Upgrade the coordinator before agents when the protocol ceiling requires it. Agent upgrades verify signed artifacts, drain and wait for jobs, swap atomically, and restore the previous drain state. Fleet upgrades proceed sequentially and stop at the first failure. An administrator's intentional drain remains in place. Do not bypass signature checks or assume an unpinned release exists. Consult the generated [version reference](./Reference.md#pinned-versions) and [upgrade tests](../../../../free/ci/internal/agent/update/).
+
+## Troubleshooting
+
+Start with `nself ci doctor --nodes --json`, exercised by [TestNodesSection](../../../../free/ci/cmd/doctor_nodes_test.go). Match the subject and remediation to the generated [CI-DN doctor-check table](./Reference.md#doctor-checks). For E650–E669 and reason keys, use the generated [error-code table](./Reference.md#error-codes). Reference.md owns these tables; this guide does not copy them or invent per-row anchors.
+
+**Lost leases.** Sleep, a dropped SSH session, or coordinator outage can end a lease. Restore connectivity, inspect the attempt, and let fencing and cleanup finish before retrying. Expired leases can leave orphan job roots; restarting the agent sweeps roots whose leases are gone. A stale epoch must not resume the old job. Check disk space, time synchronization, battery policy, and intermittent-node settings. Discovery does not renew leases. See [state diagnostics](../../../../free/ci/internal/nodes/doctor/checks_state.go) and [session-drop tests](../../../../free/ci/internal/transport/ssh/run_test.go).
+
+**Host-key change.** Verify the replacement fingerprint out of band, then rotate the SSH pin using `nodes rotate` with `--host-key`. Do not disable strict checking or re-bootstrap merely to silence the error. A changed node signing key or expired certificate is a different identity problem; follow its reported remediation and pairing/rotation flow. See [host-key rotation tests](../../../../free/ci/internal/nodes/lifecycle/integration_test.go).
+
+**No eligible runner.** Check whether the node is drained, revoked, a deploy host, unauthorized for the project, below the required isolation, or missing UID separation for team use. A provisioned GitHub runner in the inventory is not automatically an eligible native agent. Consult the generated tables before changing trust and use [Trust, Security, and Privacy](./Trust-Security-and-Privacy.md) for admission policy.
diff --git a/.github/wiki/guides/ci/Reference.md b/.github/wiki/guides/ci/Reference.md
index 0aa7e7540..8a8ec6e90 100644
--- a/.github/wiki/guides/ci/Reference.md
+++ b/.github/wiki/guides/ci/Reference.md
@@ -1,51 +1,730 @@
 # CI reference
 
-<!-- Source: scripts/generate-ci-agent-reference.py; do not edit this page directly. -->
+<!-- Generated by `go generate ./tools/refgen/...` in free/ci. Do not edit this page by hand. -->
 
-This page covers the pull agent and its refusal and transport reasons. It is a focused reference pending the full CI reference generator.
+Every table on this page is read from the code of `free/ci`. Change the code, then regenerate the page.
+For the flags of one command, run `nself ci <command> --help`.
 
-Regenerate with `python3 scripts/generate-ci-agent-reference.py`; validate with `python3 scripts/generate-ci-agent-reference.py --check`.
+<!-- BEGIN GENERATED:commands -->
+## Commands
 
-## `nself-ci-agent pull`
+`nself ci` runs the plugin binary `nself-ci`. A v1.4 command runs without `NSELF_V15`; a v1.5 command needs `NSELF_V15=1`. Hidden commands are reachable but left out of `--help`.
 
-After `nself-ci-agent join`, keep an outbound TLS 1.3 mTLS connection to the enrolled coordinator and execute its leases. The enrollment pins the coordinator root; `--coordinator` selects its local record ID, not a URL.
+| Command | Surface | Side effect | Summary |
+|---|---|---|---|
+| `nself ci` | v1.4, v1.5 | remote | Run the nself-ci gate suite and post a GitHub commit status |
+| `nself ci artifacts` | v1.5 | read | List, show, fetch and prune stored run artifacts |
+| `nself ci artifacts get` | v1.5 | - | - |
+| `nself ci artifacts key` | v1.5 | - | - |
+| `nself ci artifacts list` | v1.5 | - | - |
+| `nself ci artifacts prune` | v1.5 | - | - |
+| `nself ci artifacts release` | v1.5 | - | - |
+| `nself ci artifacts show` | v1.5 | - | - |
+| `nself ci artifacts sign` | v1.5 | - | - |
+| `nself ci artifacts signer` | v1.5 | - | - |
+| `nself ci artifacts tools` | v1.5 | - | - |
+| `nself ci artifacts verify` | v1.5 | - | - |
+| `nself ci build` | v1.4, v1.5 (hidden) | remote | Build a signed release artifact locally (Android only) |
+| `nself ci config ignore add` | v1.5 | write | Append a reviewed fingerprint to .gitleaksignore (--reason required) |
+| `nself ci config migrate` | v1.5 | write | Migrate .nself/ci.yaml to the current schema (--write applies) |
+| `nself ci config show` | v1.5 | read | Show the resolved CI configuration |
+| `nself ci doctor` | v1.5 | read | Check the CI environment, nodes and providers (--selftest [--alert] for an unattended host) |
+| `nself ci evidence` | v1.5 | read | Show the evidence document of a revision |
+| `nself ci evidence verify` | v1.5 | read | Verify the evidence of a revision against the policy |
+| `nself ci explain` | v1.5 | read | Explain why a job was or was not planned |
+| `nself ci forgejo` | v1.4, v1.5 | read | Show Forgejo server health (ops profile) |
+| `nself ci logs` | v1.5 | read | Print the logs of a run attempt (-f follows) |
+| `nself ci netproxy` | v1.5 (hidden) | remote | Internal egress proxy used by restricted jobs |
+| `nself ci nodes add` | v1.5 | remote | Add and provision a CI node |
+| `nself ci nodes discover` | v1.5 | read | Discover nodes on the local network |
+| `nself ci nodes drain` | v1.5 | remote | Stop placing new jobs on a node |
+| `nself ci nodes enable` | v1.5 | remote | Place jobs on a node again |
+| `nself ci nodes forget-project` | v1.5 | destructive | Forget a project's node records on this host (local, audited) |
+| `nself ci nodes label` | v1.5 | write | Set or remove node labels (key=value) |
+| `nself ci nodes list` | v1.5 | read | List nodes |
+| `nself ci nodes pair` | v1.5 | remote | Pair an agent node (foreground enrollment listener) |
+| `nself ci nodes pools explain` | v1.5 | read | Explain a project's effective pool set and every excluded runner |
+| `nself ci nodes pools list` | v1.5 | read | List runner pools and whether the project may use them |
+| `nself ci nodes pools show` | v1.5 | read | Show one runner pool |
+| `nself ci nodes projects add` | v1.5 | write | Authorize projects on a node |
+| `nself ci nodes projects list` | v1.5 | read | List the projects a node is authorized for |
+| `nself ci nodes projects remove` | v1.5 | write | Remove project authorizations from a node |
+| `nself ci nodes provision` | v1.4 | remote | Install runner dependencies, user, sudoers, and N runner instances |
+| `nself ci nodes remove` | v1.5 | destructive | Remove a node and its registration |
+| `nself ci nodes revoke` | v1.5 | destructive | Revoke a node credential |
+| `nself ci nodes rotate` | v1.5 | remote | Rotate a node host key, certificate or node key |
+| `nself ci nodes secrets grant` | v1.5 | remote | Grant a node access to a secret class |
+| `nself ci nodes secrets revoke` | v1.5 | remote | Revoke a node access to a secret class |
+| `nself ci nodes set` | v1.5 | remote | Set contention and persistence policy of a node |
+| `nself ci nodes show` | v1.5 | read | Show one node |
+| `nself ci nodes status` | v1.5 | read | Show readiness, watcher, queue and last results of every node |
+| `nself ci nodes sync` | v1.5 | write | Import an inventory/v1 file or command output over the node registry |
+| `nself ci nodes test` | v1.5 | remote | Probe a node and report its capabilities |
+| `nself ci nodes upgrade` | v1.5 | remote | Upgrade node agents |
+| `nself ci nodes verify` | v1.4 | read | Check host(s) against the dependency manifest and report drift |
+| `nself ci plan` | v1.5 | read | Plan a run without executing it |
+| `nself ci policy pin` | v1.5 | write | Pin or clear the trusted revision |
+| `nself ci policy protect` | v1.5 | remote | Show or apply branch protection that requires the nself-ci check |
+| `nself ci policy set` | v1.5 | write | Set an operator policy key |
+| `nself ci policy show` | v1.5 | read | Show the operator policy |
+| `nself ci policy unset` | v1.5 | write | Unset an operator policy key |
+| `nself ci policy usage` | v1.5 | read | Show spend and usage against the policy |
+| `nself ci providers` | v1.5 | read | Provider command group help |
+| `nself ci providers authorize` | v1.5 | remote | Authorize a project for hosted runners |
+| `nself ci providers github init` | v1.5 | write | Render the GitHub dispatch workflow |
+| `nself ci providers gitlab init` | v1.5 | write | Render the GitLab dispatch pipeline |
+| `nself ci providers list` | v1.5 | read | List providers |
+| `nself ci providers revoke` | v1.5 | destructive | Revoke a project authorization for hosted runners |
+| `nself ci providers show` | v1.5 | read | Show one provider |
+| `nself ci providers test` | v1.5 | remote | Probe a provider |
+| `nself ci providers usage import` | v1.5 | write | Import provider usage records |
+| `nself ci run` | v1.4 | remote | Discover .ci.yaml manifests and run their stages (pipeline) |
+| `nself ci runs` | v1.5 | read | Show a run, or the flaky checks (--flaky) |
+| `nself ci runs approve` | v1.5 | remote | Approve a run that waits for approval |
+| `nself ci runs cancel` | v1.5 | remote | Cancel a run |
+| `nself ci runs decisions` | v1.5 | read | Show the scheduling decisions of a run |
+| `nself ci runs follow` | v1.5 | read | Follow the events of a run as an NDJSON stream |
+| `nself ci runs list` | v1.5 | read | List recent runs |
+| `nself ci runs outbox` | v1.5 | read | Show queued status and event deliveries |
+| `nself ci runs pending` | v1.5 | read | List runs waiting for approval |
+| `nself ci runs prune` | v1.5 | destructive | Remove old runs and logs (--dry-run previews; --tidy [--apply] also tidies cache and job roots) |
+| `nself ci runs queue` | v1.5 | read | Show the run queue |
+| `nself ci runs reproduce` | v1.5 | remote | Reproduce a job at its recorded inputs |
+| `nself ci runs rerun` | v1.5 | remote | Run a recorded revision again on a chosen target |
+| `nself ci runs resolve` | v1.5 | write | Resolve a pending run decision |
+| `nself ci runs stats` | v1.5 | read | Show run statistics |
+| `nself ci runs wait` | v1.5 | read | Wait for a run to finish and print its result |
+| `nself ci serve` | v1.4, v1.5 | write | Start the nself-ci webhook listener daemon (port 3845) |
+| `nself ci serve admin` | v1.5 | read | Coordinator admin group help |
+| `nself ci serve admin audit` | v1.5 | read | Read or verify the audit log |
+| `nself ci serve admin audit checkpoint` | v1.5 | write | Write a signed audit checkpoint |
+| `nself ci serve admin cert` | v1.5 | write | Issue a user mTLS certificate (printed once) |
+| `nself ci serve admin roles` | v1.5 | destructive | Grant, revoke or list roles |
+| `nself ci serve admin token` | v1.5 | destructive | Issue, revoke or list scoped user tokens |
+| `nself ci serve backup` | v1.5 | read | Back up the coordinator data directory |
+| `nself ci serve install` | v1.5 | write | Install the watcher service and hourly selftest |
+| `nself ci serve restore` | v1.5 | destructive | Restore the coordinator data directory from a backup |
+| `nself ci serve uninstall` | v1.5 | destructive | Remove unchanged watcher service files |
+| `nself ci serve watch` | v1.5 | remote | Keep commit CI current by polling, without an inbound port |
 
-| Flag | Default | Meaning |
-| --- | --- | --- |
-| `--slots` | `0` | lower the concurrent leases this process takes |
-| `--coordinator` | `""` | id of the coordinator (default: derived from the pinned root) |
-| `--project` | `""` | project root whose secret store this node resolves from (enables node-side secrets) |
-| `--secrets-eligible` | `false` | this node may receive project and environment secrets |
-| `--dedicated` | `false` | this node is dedicated to the project (also release and deploy secrets) |
+### Flags
 
-A slots value of zero keeps the automatic limit; a positive value lowers it. Negative values are rejected. Secret eligibility requires the project secret store on this node. `--dedicated` also permits release and deploy secrets.
+A flag is read from the source file that defines it. `verb *` means the flag is shared by the file that registers several sub-verbs of that verb, so it is not proven for every one of them. Run `nself ci <command> --help` for the exact set.
 
-## E661: job token rejected
+| Flag | Commands |
+|---|---|
+| `--accepts` | `nodes *` |
+| `--addr` | `serve` |
+| `--agent-addr` | `serve *` |
+| `--agent-binary` | `nodes *` |
+| `--agent-source` | `providers github init` |
+| `--agent-url` | `nodes pair` |
+| `--alert` | `doctor` |
+| `--all` | `nodes *` |
+| `--allow-deploy-host` | `nodes *` |
+| `--allow-downgrade` | `nodes *` |
+| `--allow-private` | `providers *` |
+| `--allow-unsandboxed` | `serve` |
+| `--allowed-repos` | `serve` |
+| `--api-addr` | `serve *` |
+| `--api-lock` | `serve *` |
+| `--api-public-url` | `serve *` |
+| `--api-socket` | `serve *` |
+| `--api-submit-role` | `serve *` |
+| `--app-id` | `policy protect` |
+| `--apply` | `runs *` |
+| `--artifact` | `build` |
+| `--at-revision` | `evidence *` |
+| `--attempt` | `artifacts *`, `logs` |
+| `--audit` | `policy protect` |
+| `--base` | `explain`, `plan` |
+| `--binary` | `serve *` |
+| `--branch` | `policy protect` |
+| `--by` | `config ignore add` |
+| `--cert` | `nodes *` |
+| `--cert-ttl` | `nodes pair` |
+| `--check` | `providers *`, `runs reproduce` |
+| `--class` | `nodes *` |
+| `--clear` | `policy *` |
+| `--cmd` | `nodes sync` |
+| `--concurrency` | `serve` |
+| `--config` | `config *`, `explain`, `plan` |
+| `--confirm-flaky` | `runs *` |
+| `--container` | - |
+| `--coordinator` | `artifacts *`, `nodes *`, `runs *` |
+| `--coordinator-id` | `nodes pair` |
+| `--data-dir` | `nodes pair`, `serve *` |
+| `--dest` | `artifacts *` |
+| `--detach` | - |
+| `--dir` | `providers *` |
+| `--drain-deadline` | `serve *` |
+| `--dry-run` | `artifacts *`, `nodes sync`, `policy protect`, `runs *`, `serve *` |
+| `--effective` | `policy *` |
+| `--enroll-addr` | `nodes pair`, `serve *` |
+| `--env` | `run` |
+| `--env-file` | `serve *` |
+| `--f` | `logs` |
+| `--file` | `evidence *` |
+| `--filesystem` | - |
+| `--flaky` | `runs *` |
+| `--force` | `serve` |
+| `--from` | `nodes sync` |
+| `--from-seq` | `runs follow` |
+| `--gateway` | `run` |
+| `--h` | - |
+| `--help` | - |
+| `--home` | `config *` |
+| `--hook` | `policy protect` |
+| `--host-key` | `nodes *` |
+| `--image` | - |
+| `--in` | `serve *` |
+| `--init` | `artifacts signer` |
+| `--inputs` | `providers gitlab init` |
+| `--insecure` | `serve` |
+| `--installer` | `nodes *` |
+| `--interactive` | `nodes *` |
+| `--interval` | `serve watch` |
+| `--isolation` | - |
+| `--job` | `runs rerun` |
+| `--json` | `artifacts *`, `config *`, `doctor`, `evidence *`, `explain`, `forgejo`, `logs`, `nodes *`, `plan`, `policy *`, `providers *`, `runs *`, `serve *` |
+| `--keep` | `runs *` |
+| `--kek` | `serve *` |
+| `--key-id` | `nodes *` |
+| `--keys` | `artifacts verify` |
+| `--kind` | `artifacts *` |
+| `--label` | `nodes pair` |
+| `--launchd` | `serve *` |
+| `--limit` | `runs *` |
+| `--local` | `nodes status` |
+| `--max-age-days` | `runs *` |
+| `--max-log-bytes` | `runs *` |
+| `--max-queue` | - |
+| `--mode` | `nodes *` |
+| `--name` | `artifacts *`, `nodes *` |
+| `--network` | - |
+| `--no-gitleaks` | - |
+| `--no-status` | `config *` |
+| `--node-admin-routes` | `serve *` |
+| `--node-key` | `nodes *` |
+| `--nodes` | `doctor` |
+| `--older-than` | `artifacts *` |
+| `--on-battery` | `nodes *` |
+| `--once` | `serve watch` |
+| `--out` | `artifacts *`, `serve *` |
+| `--owner` | `build` |
+| `--ownership` | `nodes *` |
+| `--persistence` | `nodes *` |
+| `--pipeline` | `evidence *`, `explain`, `plan` |
+| `--policy` | `evidence *` |
+| `--post-status` | - |
+| `--prefer` | - |
+| `--privacy-zone` | `nodes *` |
+| `--probe` | `netproxy` |
+| `--project` | `artifacts *`, `nodes *`, `providers *`, `runs *`, `serve admin roles` |
+| `--providers` | `doctor` |
+| `--proxy` | `netproxy` |
+| `--pubkey` | `serve admin audit checkpoint` |
+| `--public` | `artifacts signer` |
+| `--public-url` | `nodes pair`, `serve *` |
+| `--reason` | `config ignore add` |
+| `--release` | `artifacts *` |
+| `--release-routes` | `serve *` |
+| `--remove` | `nodes label` |
+| `--repo` | `artifacts verify`, `build`, `config *`, `doctor`, `evidence *`, `explain`, `plan`, `policy *`, `providers *`, `runs *`, `serve *` |
+| `--repos` | `serve watch` |
+| `--reserve-cpu` | `nodes *` |
+| `--reserve-mem` | `nodes *` |
+| `--restore` | `policy protect` |
+| `--role` | `serve admin roles` |
+| `--rotate` | `artifacts signer` |
+| `--run` | `artifacts *`, `logs`, `runs reproduce` |
+| `--runner` | - |
+| `--scope` | `policy *` |
+| `--secret` | `serve` |
+| `--secret-classes` | `nodes *` |
+| `--self` | `serve *` |
+| `--selftest` | `doctor` |
+| `--service` | - |
+| `--sha` | `runs *` |
+| `--shell` | `runs reproduce` |
+| `--since` | `serve admin audit` |
+| `--slots` | `nodes *` |
+| `--spend` | `runs *` |
+| `--stdio` | `artifacts signer` |
+| `--stdout` | `providers *` |
+| `--stream` | `evidence *` |
+| `--system` | `nodes *`, `serve *` |
+| `--systemd` | `serve *` |
+| `--tag` | `build` |
+| `--team` | `policy *`, `serve *` |
+| `--timeout` | `build`, `config *`, `nodes discover`, `run`, `runs wait`, `serve` |
+| `--trigger` | `explain`, `plan` |
+| `--trust` | - |
+| `--ttl` | `serve *` |
+| `--untrusted-dir` | `providers gitlab init` |
+| `--upload` | `build` |
+| `--url` | `forgejo` |
+| `--user` | `serve *` |
+| `--v` | `build`, `run`, `serve` |
+| `--verbose` | `build`, `serve` |
+| `--verify` | `serve admin audit` |
+| `--version` | `nodes *` |
+| `--where` | - |
+| `--workdir` | `serve` |
+| `--write` | `config *` |
+| `--yes` | `artifacts key` |
+<!-- END GENERATED:commands -->
 
-The agent must present its own lease token using the certificate and session that first used it. Restart the job when its token expires or the attempt ends. Never copy a token between jobs, nodes, certificates or sessions.
+<!-- BEGIN GENERATED:exit-codes -->
+## Exit codes
 
-| Reason |
-| --- |
-| `expired` |
-| `invalid` |
-| `missing` |
-| `replayed` |
-| `terminal` |
-| `wrong_certificate` |
-| `wrong_job` |
-| `wrong_runner` |
-| `wrong_session` |
+| Command | Outcome | Exit |
+|---|---|---:|
+| ci | pass | 0 |
+| ci | required check failed | 1 |
+| ci | usage error | 1 |
+| ci | infrastructure | 2 |
+| ci | authorization | 3 |
+| ci evidence verify | current bound pass | 0 |
+| ci evidence verify | evidence fails | 1 |
+| ci evidence verify | stale | 10 |
+| ci evidence verify | invalid | 11 |
+| ci evidence verify | unbound | 12 |
+| ci evidence --pipeline | none overdue | 0 |
+| ci evidence --pipeline | overdue | 10 |
+| ci doctor | clean | 0 |
+| ci doctor | check failed | 10 |
+| ci doctor | warnings only | 12 |
+<!-- END GENERATED:exit-codes -->
 
-## E656: pull transport failure
+<!-- BEGIN GENERATED:error-codes -->
+## Error codes
 
-These keys describe the pull carrier. Check node connectivity and enrollment for connection/configuration failures, coordinator capacity for a full queue, and lease cancellation or duplication for lease failures. A blob refusal cancels the lease; inspect its integrity, size and sink verification.
+Errors print as `E<number>: <message>`. The class says who fixes it: `usage` and `code` are yours, `infra` is the machine or the network.
 
-| Reason |
-| --- |
-| `transport.agent_blob` |
-| `transport.agent_cancel_timeout` |
-| `transport.agent_duplicate_lease` |
-| `transport.agent_lease_lost` |
-| `transport.agent_not_configured` |
-| `transport.agent_not_connected` |
-| `transport.agent_queue_full` |
+| Code | Class | Summary | Fix | Package |
+|---|---|---|---|---|
+| E600 | infra | nself CLI is too old | Run nself update | `internal/model` |
+| E601 | usage | document is invalid against its schema | Fix the document and retry | `internal/model` |
+| E602 | usage | unsupported contract version | Use a supported contract version | `internal/model` |
+| E603 | infra | V15 engine not built yet | Install a newer nself-ci plugin | `internal/model` |
+| E604 | usage | illegal state transition | Use a legal state transition | `internal/store` |
+| E605 | infra | state changed concurrently | Refresh attempt state and retry | `internal/store` |
+| E606 | infra | database needs a newer reader | Upgrade nself-ci before opening this database | `internal/store` |
+| E607 | infra | store operation failed | Check local disk and retry | `internal/store` |
+| E608 | usage | idempotency key already used | Use the original attempt or a new key | `internal/store` |
+| E609 | usage | operator action required | Record an operator decision before proceeding | `internal/store` |
+| E610 | infra | local process execution unavailable | Use a supported local host | `internal/exec` |
+| E611 | infra | requested isolation unavailable | Choose process or baseline container isolation | `internal/exec` |
+| E612 | infra | job preparation failed | Check workspace and secret source | `internal/exec` |
+| E613 | infra | local container execution failed | Check Docker and the selected image | `internal/exec` |
+| E614 | infra | required check tool is unavailable | Install the named tool and retry | `internal/gates` |
+| E615 | code | check configuration or threshold is invalid | Correct the check configuration and retry | `internal/gates` |
+| E616 | usage | job dependencies form a cycle or name a job that does not exist | Remove the cycle or define the missing job in .nself/ci.yaml | `internal/plan` |
+| E617 | usage | a required job depends on an allow_failure job | Make the dependency required or the dependant optional | `internal/plan` |
+| E618 | infra | no runner can run this job | Install the missing tool or Docker, register a runner, or relax the job requirements | `internal/plan` |
+| E619 | usage | unknown pipeline, job or fail-fast scope | Use a name defined under pipelines or jobs in .nself/ci.yaml | `internal/plan` |
+| E620 | usage | .nself/ci.yaml is invalid or risky | Fix the named key at the reported file:line and retry | `internal/config` |
+| E621 | usage | a legacy .ci.yaml is present under V15 | Run nself ci config migrate --write, then delete the old file | `internal/config` |
+| E622 | usage | a legacy .ci.yaml field cannot become a job | Remove or hand-convert the named field | `internal/config` |
+| E623 | usage | .nself/ci.yaml is git-ignored | Add .nself/* and !.nself/ci.yaml to .gitignore | `internal/config` |
+| E624 | usage | --sha is not supported in V15 | Run `nself ci evidence verify <rev>` to check a revision | `internal/run` |
+| E625 | usage | --trust needs a registered trust classifier | Run without --trust, or install the trust component | `internal/run` |
+| E626 | usage | unknown or unusable run | List runs with `nself ci runs` and use a run id from the list | `internal/run` |
+| E627 | usage | run option not available | Check `nself ci --help` for the options this build supports | `internal/run` |
+| E628 | usage | evidence revision must be a full commit sha | Pass the 40 or 64 hex digits of the commit, for example $(git rev-parse HEAD) | `internal/evidence` |
+| E629 | usage | evidence document rejected | Run `nself ci evidence verify <rev>` on a clean checkout to produce fresh evidence | `internal/evidence` |
+| E630 | infra | evidence worktree or git facts unavailable | Check that git works in the repository and that the temporary directory is writable | `internal/evidence` |
+| E631 | usage | no evidence for that run or revision | List runs with `nself ci runs`, or run `nself ci evidence verify <rev>` | `internal/evidence` |
+| E632 | infra | stored job log unusable | Check that the CI state directory is writable and not full; `nself ci runs prune` frees space | `internal/logs` |
+| E633 | usage | no stored logs for that job or attempt | List runs with `nself ci runs list`; logs are kept per attempt until retention removes them | `internal/logs` |
+| E634 | usage | recorded platform differs from this host | Reproduce the job on a host of the recorded platform, or read the stored evidence with `nself ci evidence <run>` | `internal/reproduce` |
+| E635 | usage | the original run was not bound to its commit; only the recorded revision is reproduced | Commit the changes and run the job again to get bound evidence | `internal/reproduce` |
+| E636 | infra | service provisioning or teardown failed | Re-run the job; list leftovers with `docker compose ls --all` and remove any nselfci- project | `internal/services` |
+| E637 | infra | Docker is required for service dependencies | Start Docker (or Colima) and re-run, or run a job that declares no services | `internal/services` |
+| E638 | infra | the nself CLI does not offer the service commands | Run `nself update` | `internal/services` |
+| E639 | usage | unknown service or component | List the valid names with `nself config services list --json` | `internal/services` |
+| E640 | usage | a drill is invalid | Make the drill print one valid ci.evidence/v1 document on stdout (or none), and keep drills_dir entries to plain directories with an executable `run` | `internal/drill` |
+| E641 | usage | a drill job is overdue | Run the scheduled pipeline (`nself-ci --pipeline <name>`) and check why the schedule stopped | `internal/drill` |
+| E642 | usage | a pre-push hook already exists | Call the printed `nself ci evidence verify` line from your existing pre-push hook; nothing was overwritten | `internal/protect` |
+| E643 | usage | branch protection is not available for this repository | Use the pre-push hook (`nself ci policy protect --hook`) and the auditor (`--audit <days>`) instead | `internal/protect` |
+| E644 | code | truth rule file is invalid or unreadable | Correct the key named in the message in the rule file and retry | `internal/gates/truth` |
+| E645 | usage | the pinned toolchain image is not available | Pass --image <ref@digest> (set NSELF_CI_IMAGE=<ref@digest> until the flag exists), or run without --container; the first publish of the pinned image is a separate owner-named action | `internal/toolchain` |
+| E646 | infra | no isolation is available for the ad-hoc job | Start Docker (or Podman) to run the job in a container, or pass --isolation process to run it on this host with host networking | `internal/adhoc` |
+| E647 | infra | the trust class needs an isolation level this host cannot provide | Run the job on a host with the sandboxed-container level (gVisor), or drop --trust untrusted if the command is your own | `internal/adhoc` |
+| E648 | infra | detached run did not start (reason spawn, no_queued_event or child_exit) | Run the same command without --detach to see the error, then retry | `internal/detach` |
+| E650 | usage | node not found | List nodes and use a registered id | `internal/nodes/registry` |
+| E651 | usage | invalid node document or version | Refresh the capability and retry | `internal/nodes/registry` |
+| E652 | usage | runner protocol version incompatible | Upgrade the agent to min_agent_version | `internal/protocol` |
+| E653 | infra | runner protocol message invalid | Check the carrier and agent protocol stream | `internal/protocol` |
+| E654 | infra | node slots full | Wait for a running job to finish or raise the agent's slot count | `internal/agent/slots` |
+| E655 | usage | node host key unknown or changed | Verify the node, then run `nself ci nodes rotate <node> --host-key SHA256:<fingerprint>` (or `nself ci nodes add` for a new node) | `internal/transport/ssh` |
+| E656 | infra | ssh transport failure | Check that the node is reachable and the agent is installed (`nself ci nodes test <node>`); the attempt is retried if it is retryable | `internal/transport/ssh` |
+| E657 | usage | node revoked or not authorized for the project | Run nself ci nodes show <node>; add the node again or ask an admin to recover it | `internal/nodes/lifecycle` |
+| E658 | usage | invalid node label | Use lowercase keys, plain short values, at most 32 labels and no nself. prefix | `internal/nodes/labels` |
+| E659 | usage | pairing code invalid | Start a new pairing window with `nself ci nodes pair` and use the code it prints | `internal/pairing` |
+| E660 | usage | certificate invalid | Re-pair the node (`nself ci nodes pair`), check the clock, or issue a new certificate | `internal/pki` |
+| E661 | usage | job token rejected | The agent must present the token of its own lease from the session and certificate that first used it; restart the job if the token expired or the attempt ended | `internal/transport/agent` |
+| E662 | infra | stale lease epoch | Stop the job and clean its workspace before retrying | `internal/lease` |
+| E663 | usage | host is a deploy host and is CI-ineligible | Run CI on another machine; only an admin may pass --allow-deploy-host after confirming | `internal/nodes/deployguard` |
+| E664 | usage | coordinator user API refused the request or could not be used (reason key names why: node_kind, no_credential, token_*, role, project, server_identity, transport, ...) | Use a user certificate or a scoped token that holds the needed role for the project (`nself ci serve admin roles list`), and pin the coordinator root (ci.coordinator_ca) | `internal/coordinator/clientapi` |
+| E665 | auth | agent artifact verification failed (reason keys no_trusted_key, missing_signature, unknown_key, wrong_purpose, revoked, bad_signature, version_mismatch, target_mismatch, checksum_mismatch, provenance) | Install the agent from a signed release of the pinned version, or pass --agent-binary <path> with a binary you trust | `internal/agent/verify` |
+| E666 | usage | agent upgrade refused (protocol ceiling, downgrade or running job) | Run nself ci nodes show <node>; wait for the job, pass --allow-downgrade, or upgrade the coordinator first | `internal/agent/update` |
+| E667 | usage | LAN discovery is disabled | Unset NSELF_CI_DISCOVERY=0 and remove `ci.discovery: off` from the user config.yaml to use discovery, or pair by address with `nself ci nodes pair` | `internal/discovery` |
+| E668 | infra | coordinator backup or restore refused | Check the reason: pass the KEK of the coordinator that made the backup (--kek), stop the coordinator before `serve restore`, or take a new backup | `internal/coordinator/backup` |
+| E669 | infra | node bootstrap or pinned runner download failed | Read the reason key in the message: no_root needs root or passwordless sudo for the ssh user; checksum means the downloaded runner does not match its pin | `internal/nodes/bootstrap` |
+| E670 | usage | policy scope loosens a parent | Tighten the lower scope or edit the operator policy | `internal/trust` |
+| E671 | usage | revision or branch policy field ignored | Move spend authorization to operator policy or tighten the revision | `internal/trust` |
+| E672 | usage | invalid policy key or value | Use a registered key with a valid value | `internal/trust` |
+| E673 | usage | value below the redaction minimum length | Register values of at least 6 bytes; shorter values cannot be masked | `internal/redact` |
+| E674 | usage | invalid secret reference or environment-name collision | Write refs as project/NAME, team/NAME, release/NAME, environment/<env>/NAME or deploy/<env>/NAME, and give each NAME once | `internal/secrets` |
+| E675 | infra | secret resolver unavailable | Install an nself CLI that has `nself config secrets resolve`, or remove the secrets from the job | `internal/secrets` |
+| E676 | infra | secret resolution failed | Check that the ref exists in the store file and that this node's age identity was granted the file; the attempt did not start | `internal/secrets` |
+| E677 | usage | secret class or node not eligible | Run the job on a node and trust class the policy allows for this secret class, or grant the node (nself ci nodes secrets grant) if it is eligible | `internal/secrets` |
+| E678 | infra | requested isolation level unavailable on this runner | Install or enable the runtime for the level, or run the job on a runner that has it | `internal/isolation` |
+| E679 | infra | network scope cannot be enforced by this isolation profile | Use the none or lan scope, or install the network scope profile | `internal/isolation` |
+| E680 | usage | value above the redaction maximum length | Register values of at most 128 KiB; a longer value cannot be found reliably in a scanned stream | `internal/redact` |
+| E681 | infra | workspace leak detected or cleanup incomplete; node drained | Run `nself ci doctor`, remove the reported leftovers, then undrain the node | `internal/hygiene` |
+| E682 | infra | no job UID is provisioned for this separation | Re-run `nself ci nodes add --system`, or enable unprivileged user namespaces for the agent user | `internal/hygiene` |
+| E683 | usage | artifact path rejected | Pack only regular files, directories and in-tree relative symlinks, or choose an empty destination outside .git | `internal/authz` |
+| E684 | usage | cache write denied | A cache is written only by a passing attempt in finalizing, into its own namespace, with the current epoch | `internal/authz` |
+| E685 | usage | evidence rejected | Run the gate again on the exact revision with a clean worktree, or fix the reason named in the error | `internal/attest` |
+| E686 | usage | evidence signature invalid, key unknown or signature replayed | Run the job again on a registered node whose evidence key is not revoked, or fix the reason named in the error | `internal/attest` |
+| E687 | usage | not authorized | Use an identity that holds the needed role (`nself ci serve admin roles list`), or ask an admin to grant it | `internal/roles` |
+| E688 | usage | run approval missing, void or refused | Ask a release or admin user other than the author to run `nself ci runs approve <run>` for the current head | `internal/trust/source` |
+| E689 | usage | placement refused at the production boundary | Run the job on a node that is not a deploy host, or on a deploy host the operator overrode with owner or internal work, isolation vm or stronger and no release or deploy secrets; a coordinator host needs vm for team mode and for collaborator or untrusted work | `internal/trust` |
+| E690 | usage | matrix entry is outside pipeline support | Declare the platform in support or remove the matrix entry | `internal/sched` |
+| E691 | usage | scheduling policy value is invalid | Use a registered sched key with a valid value: a positive whole number, a duration such as 10m, or a listed name | `internal/schedpolicy` |
+| E692 | usage | explain target not found or no decision record | Name a job of the current plan, or run `nself ci runs decisions` to list recorded placement decisions | `internal/planview` |
+| E693 | usage | job waited past max_queue | Raise --max-queue or free capacity, then run again | `internal/dispatch` |
+| E694 | usage | the project's job queue is full | Wait for queued jobs to finish (the error carries the expected wait), cancel runs you no longer need, or raise sched.queue.max_depth | `internal/fairq` |
+| E695 | usage | spend refused: no budget, paid placement disabled, or approval required | Set economics.paid_enabled and a day or month budget, raise the budget, or approve the spend with `nself ci runs approve <run> --spend` | `internal/economics` |
+| E696 | usage | burst provisioning refused or failed: cap, breaker, budget or provider error | Read the reason in `nself ci explain`; raise burst.max_concurrent, wait for the breaker to close, or fix the provider | `internal/burst` |
+| E697 | internal | burst teardown failed; it is alerted once and retried at every sweep until the resource is gone | Check the provider API and credentials; the sweeper keeps retrying and new provisioning on that provider stays blocked until the resource is gone | `internal/burst` |
+| E698 | infra | the ephemeral provider is unavailable: missing tool, adapter, token file or agent artifact | Install a container runtime (Linux) or Tart (Apple silicon), or read the reason in `nself ci doctor`; no slot is offered below container isolation | `internal/providers/ephemeral/local` |
+| E699 | infra | world snapshot unavailable | Check the store and contributor registrations | `internal/world` |
+| E700 | config | provider not configured or credential missing | Configure the provider and credential | `internal/providers` |
+| E701 | auth | credential lacks scope or permission | Grant the named permission | `internal/providers` |
+| E702 | config | provider rejected a misconfigured request | Correct the repository, workflow, ref or project | `internal/providers` |
+| E703 | quota | provider rate limited or quota exhausted | Retry after the indicated time | `internal/providers` |
+| E704 | transient | provider unavailable | Retry after recovery | `internal/providers` |
+| E705 | config | hosted evidence rejected | Inspect evidence binding | `internal/providers` |
+| E706 | auth | trigger rejected | Check signature, token, timestamp and source | `internal/providers` |
+| E707 | config | runner registration or teardown failed | Inspect runner registration | `internal/providers` |
+| E708 | config | job cannot be dispatched to provider | Reduce or change the job request | `internal/providers` |
+| E709 | config | usage import unavailable | Check billing access and endpoint | `internal/providers` |
+| E710 | infra | blob integrity failure | Discard the corrupt blob and retry transfer | `internal/blob/cas` |
+| E711 | usage | cache write refused | A cache entry is saved only by a passing attempt in finalizing, with the current epoch, into its own namespace and a planned key | `internal/cache/entries` |
+| E712 | infra | artifact commit refused | Declare outputs that exist inside the job workdir, stay under the size caps and the disk floor and hold no registered secret; `nself ci artifacts prune` frees space | `internal/artifacts/records` |
+| E713 | usage | artifact not found | Check the id with `nself ci artifacts list`; an artifact you may not see reads as not found | `internal/artifacts/records` |
+| E714 | infra | blob transfer failed | A remote attempt could not hand its artifact to the coordinator (stale lease, digest mismatch, interruption, protocol fault or size cap); run the job again, and raise NSELF_CI_ARTIFACT_MAX_FILE or free store space for a size_cap | `internal/blob/transfer` |
+| E715 | usage | release job not admitted | Run the release job's dependencies again on a clean, committed tree, then retry the release | `internal/release/job` |
+| E716 | usage | operator resolution refused | Use the attempt id from `nself ci runs <run>` and the NSELF_CI_IDEMPOTENCY_KEY the release job received (its publish step logs it), then run `nself ci runs resolve` again | `internal/release/job` |
+| E717 | infra | release signing failed | Run `nself ci artifacts key init` once to create the release key, make sure every attempt of the run is finished, and release only digests that are committed records of the run | `internal/signing` |
+| E718 | infra | SBOM failed | Run `nself ci artifacts tools install` to place the pinned syft, then retry; an invalid SBOM means syft's output failed the structural check, so rerun with the pinned version | `internal/sbom` |
+| E719 | usage | release verification failed | Read the reason key in the output; fetch the release again, or run `nself ci artifacts verify <dir> --json` for every check | `internal/release/verify` |
+| E793 | usage | runner inventory refused | Give a file or a command that prints one inventory/v1 document under 1 MiB within 10 seconds; run sync on the machine that owns the nodes, not on a TEAM coordinator | `internal/nodes/inventory` |
+| E797 | usage | --where value is unknown or not available | Use local, a node id, a pool id, hosted, auto or all (all needs a race hook); list targets with `nself ci nodes pools list` | `internal/where` |
+| E799 | infra | another watcher holds this host's run lock | Wait for the other watcher or stop it, then retry | `internal/readiness` |
+| E800 | infra | readiness.cmd gave no usable answer | Make the hook exit 0 (ready) or 3 (not ready, reason on its first output line) within 5 seconds; it runs with PATH and LANG only, so use absolute paths | `internal/readiness` |
+| E804 | usage | a watch.* setting is invalid | Fix the operator value (`nself ci policy show` names the key) and restart the watcher | `internal/watch` |
+| E805 | quota | the GitHub quota stopped the watch pass | Nothing to do: the watcher makes no request before the recorded reset time; raise providers.github.poll_interval if it recurs | `internal/watch` |
+| E807 | usage | a tracked file is secret-shaped or over the size cap | Untrack the file, or run the gate on a clean checkout | `internal/offload` |
+| E809 | policy | not_a_record_pool | Run commit CI on a pool listed in pools.record | `internal/pools/record` |
+| E812 | code | a .gitleaksignore entry has no review comment | Put `# Reviewed YYYY-MM-DD [by <who>]: <reason>` on the line before each entry, or add entries with `nself ci config ignore add <fingerprint> --reason <text>` | `internal/gates` |
+| E813 | infra | a notification sink did not take the message | Delivery counts are kept per sink (`nself ci doctor --selftest` shows them, P7-AUTO-20); a webhook needs https and a public address (notify.allow_private for a LAN one); a command sink must exit 0 within 10 seconds | `internal/notify` |
+| E816 | infra | the GitHub App check run was not published (the status was) | The commit status is the result of record and was posted; only the optional `nself-ci/gates` check run failed. Check providers.github.app.id, providers.github.app.installation_id and the PEM in the variable named by providers.github.app.key_env, and that the App has checks:write on the repository. Set the key variable only in the environment of the v1.5 runner service, never in a shell profile or a job | `internal/providers/github/checks` |
+| E819 | usage | per-run policy value ignored | A per-run flag can only tighten the policy (the preset is a preference); change the project or operator policy instead | `internal/trust` |
+| E821 | policy | skipped: needs isolated runner | A collaborator head runs only on an isolated runner; add one (the isolation section of `nself ci doctor` shows what this machine proved) or let the coordinator run it | `internal/watch` |
+<!-- END GENERATED:error-codes -->
+
+<!-- BEGIN GENERATED:reason-codes -->
+## Reason codes
+
+A reason code says why a job was skipped, held or placed where it was. `nself ci explain <job>` prints the reasons of one job.
+
+### Job reasons (`model.Reason`)
+
+- `pipeline.excluded`
+- `selection.no_base`
+- `selection.full_required`
+- `selection.affected`
+- `when.branch`
+- `when.paths`
+- `when.trigger`
+- `when.env_missing`
+- `dep.failed`
+- `fail_fast.cancelled`
+- `unplaceable.platform`
+- `unplaceable.docker`
+- `unplaceable.tool`
+- `unplaceable.service`
+- `unplaceable.label`
+- `unplaceable.resources`
+- `admission.battery`
+- `admission.reservation`
+- `advisory.tool_missing`
+- `advisory.data_offline`
+
+### Typed reasons
+
+| Reason | Type | Package |
+|---|---|---|
+| `evidence.adhoc` | `Reason` | `internal/attest` |
+| `evidence.invalid` | `Reason` | `internal/attest` |
+| `evidence.jobs_mismatch` | `Reason` | `internal/attest` |
+| `evidence.not_passing` | `Reason` | `internal/attest` |
+| `evidence.policy_mismatch` | `Reason` | `internal/attest` |
+| `evidence.repo_mismatch` | `Reason` | `internal/attest` |
+| `evidence.revision_mismatch` | `Reason` | `internal/attest` |
+| `evidence.selection_partial` | `Reason` | `internal/attest` |
+| `evidence.self_reported_not_admitted` | `Reason` | `internal/attest` |
+| `evidence.signature_unverifiable` | `Reason` | `internal/attest` |
+| `evidence.stale` | `Reason` | `internal/attest` |
+| `evidence.trust_below_min` | `Reason` | `internal/attest` |
+| `evidence.unbound` | `Reason` | `internal/attest` |
+| `attempt_unknown` | `RemoteReason` | `internal/attest` |
+| `context_mismatch` | `RemoteReason` | `internal/attest` |
+| `key_malformed` | `RemoteReason` | `internal/attest` |
+| `key_purpose` | `RemoteReason` | `internal/attest` |
+| `key_revoked` | `RemoteReason` | `internal/attest` |
+| `key_unknown` | `RemoteReason` | `internal/attest` |
+| `lease_holder_mismatch` | `RemoteReason` | `internal/attest` |
+| `ledger_unavailable` | `RemoteReason` | `internal/attest` |
+| `node_not_eligible` | `RemoteReason` | `internal/attest` |
+| `replay` | `RemoteReason` | `internal/attest` |
+| `revision_mismatch` | `RemoteReason` | `internal/attest` |
+| `signature_invalid` | `RemoteReason` | `internal/attest` |
+| `signature_malformed` | `RemoteReason` | `internal/attest` |
+| `signature_missing` | `RemoteReason` | `internal/attest` |
+| `collision.duplicate` | `PathReason` | `internal/authz` |
+| `collision.fold` | `PathReason` | `internal/authz` |
+| `dest.cwd` | `PathReason` | `internal/authz` |
+| `dest.empty` | `PathReason` | `internal/authz` |
+| `dest.no_parent` | `PathReason` | `internal/authz` |
+| `dest.not_dir` | `PathReason` | `internal/authz` |
+| `dest.not_empty` | `PathReason` | `internal/authz` |
+| `dest.symlink` | `PathReason` | `internal/authz` |
+| `dest.under_git` | `PathReason` | `internal/authz` |
+| `dest.unreachable` | `PathReason` | `internal/authz` |
+| `entry.device` | `PathReason` | `internal/authz` |
+| `entry.fifo` | `PathReason` | `internal/authz` |
+| `entry.hardlink` | `PathReason` | `internal/authz` |
+| `entry.irregular` | `PathReason` | `internal/authz` |
+| `entry.setid` | `PathReason` | `internal/authz` |
+| `entry.socket` | `PathReason` | `internal/authz` |
+| `link.absolute` | `PathReason` | `internal/authz` |
+| `link.empty` | `PathReason` | `internal/authz` |
+| `link.escape` | `PathReason` | `internal/authz` |
+| `link.invalid` | `PathReason` | `internal/authz` |
+| `path.absolute` | `PathReason` | `internal/authz` |
+| `path.backslash` | `PathReason` | `internal/authz` |
+| `path.control` | `PathReason` | `internal/authz` |
+| `path.dot_git` | `PathReason` | `internal/authz` |
+| `path.dots` | `PathReason` | `internal/authz` |
+| `path.drive` | `PathReason` | `internal/authz` |
+| `path.empty` | `PathReason` | `internal/authz` |
+| `path.empty_component` | `PathReason` | `internal/authz` |
+| `path.parent_not_dir` | `PathReason` | `internal/authz` |
+| `path.through_symlink` | `PathReason` | `internal/authz` |
+| `path.too_deep` | `PathReason` | `internal/authz` |
+| `path.too_long` | `PathReason` | `internal/authz` |
+| `path.trailing_slash` | `PathReason` | `internal/authz` |
+| `path.traversal` | `PathReason` | `internal/authz` |
+| `path.unicode_with_symlink` | `PathReason` | `internal/authz` |
+| `path.utf8` | `PathReason` | `internal/authz` |
+| `size.entries` | `PathReason` | `internal/authz` |
+| `size.file` | `PathReason` | `internal/authz` |
+| `size.negative` | `PathReason` | `internal/authz` |
+| `size.ratio` | `PathReason` | `internal/authz` |
+| `size.total` | `PathReason` | `internal/authz` |
+| `cache.attempt_state` | `Reason` | `internal/authz` |
+| `cache.capability` | `Reason` | `internal/authz` |
+| `cache.epoch` | `Reason` | `internal/authz` |
+| `cache.mode` | `Reason` | `internal/authz` |
+| `cache.namespace` | `Reason` | `internal/authz` |
+| `cache.result` | `Reason` | `internal/authz` |
+| `allowance.below_margin` | `PlacementReason` | `internal/model` |
+| `allowance.unknown` | `PlacementReason` | `internal/model` |
+| `approval.pending` | `PlacementReason` | `internal/model` |
+| `approval.required` | `PlacementReason` | `internal/model` |
+| `background.contention` | `PlacementReason` | `internal/model` |
+| `background.interactive_queued` | `PlacementReason` | `internal/model` |
+| `backpressure.queue_full` | `PlacementReason` | `internal/model` |
+| `budget.exceeded` | `PlacementReason` | `internal/model` |
+| `budget.unset` | `PlacementReason` | `internal/model` |
+| `burst.team_only` | `PlacementReason` | `internal/model` |
+| `capacity.busy` | `PlacementReason` | `internal/model` |
+| `cost.unbounded` | `PlacementReason` | `internal/model` |
+| `cost.unknown_rate` | `PlacementReason` | `internal/model` |
+| `ephemeral.used` | `PlacementReason` | `internal/model` |
+| `labels.mismatch` | `PlacementReason` | `internal/model` |
+| `limit.global` | `PlacementReason` | `internal/model` |
+| `limit.job` | `PlacementReason` | `internal/model` |
+| `limit.pipeline` | `PlacementReason` | `internal/model` |
+| `limit.project` | `PlacementReason` | `internal/model` |
+| `limit.provider` | `PlacementReason` | `internal/model` |
+| `limit.runner` | `PlacementReason` | `internal/model` |
+| `limit.team` | `PlacementReason` | `internal/model` |
+| `limit.user` | `PlacementReason` | `internal/model` |
+| `node.deploy_host` | `PlacementReason` | `internal/model` |
+| `node.discovered` | `PlacementReason` | `internal/model` |
+| `node.draining` | `PlacementReason` | `internal/model` |
+| `node.interactive` | `PlacementReason` | `internal/model` |
+| `node.maintenance` | `PlacementReason` | `internal/model` |
+| `node.not_ready` | `PlacementReason` | `internal/model` |
+| `node.offline` | `PlacementReason` | `internal/model` |
+| `node.on_battery` | `PlacementReason` | `internal/model` |
+| `node.protocol` | `PlacementReason` | `internal/model` |
+| `node.reservation` | `PlacementReason` | `internal/model` |
+| `node.revoked` | `PlacementReason` | `internal/model` |
+| `override.excluded` | `PlacementReason` | `internal/model` |
+| `override.max_cost` | `PlacementReason` | `internal/model` |
+| `override.max_queue` | `PlacementReason` | `internal/model` |
+| `override.min_isolation` | `PlacementReason` | `internal/model` |
+| `paid.disabled` | `PlacementReason` | `internal/model` |
+| `platform.mismatch` | `PlacementReason` | `internal/model` |
+| `platform.none_available` | `PlacementReason` | `internal/model` |
+| `pool.excluded` | `PlacementReason` | `internal/model` |
+| `provider.down` | `PlacementReason` | `internal/model` |
+| `provider.owned_elsewhere` | `PlacementReason` | `internal/model` |
+| `queue.timeout` | `PlacementReason` | `internal/model` |
+| `resources.insufficient` | `PlacementReason` | `internal/model` |
+| `retry.anti_affinity` | `PlacementReason` | `internal/model` |
+| `runner.remote_only` | `PlacementReason` | `internal/model` |
+| `tier.waiting` | `PlacementReason` | `internal/model` |
+| `tools.missing` | `PlacementReason` | `internal/model` |
+| `cleanup_failed` | `Reason` | `internal/netscope` |
+| `deploy_exclusion` | `Reason` | `internal/netscope` |
+| `dial_failed` | `Reason` | `internal/netscope` |
+| `events_dropped` | `Reason` | `internal/netscope` |
+| `host_address` | `Reason` | `internal/netscope` |
+| `host_not_allowed` | `Reason` | `internal/netscope` |
+| `invalid_address` | `Reason` | `internal/netscope` |
+| `log_unreadable` | `Reason` | `internal/netscope` |
+| `on_link` | `Reason` | `internal/netscope` |
+| `port_not_allowed` | `Reason` | `internal/netscope` |
+| `resolve_failed` | `Reason` | `internal/netscope` |
+| `scope` | `Reason` | `internal/netscope` |
+| `special_purpose` | `Reason` | `internal/netscope` |
+| `approval.required` | `Reason` | `internal/trust` |
+| `boundary.coordinator_host` | `Reason` | `internal/trust` |
+| `boundary.deploy_host` | `Reason` | `internal/trust` |
+| `boundary.override_minimum` | `Reason` | `internal/trust` |
+| `isolation.below_minimum` | `Reason` | `internal/trust` |
+| `isolation.cotenancy` | `Reason` | `internal/trust` |
+| `isolation.rootful_runtime` | `Reason` | `internal/trust` |
+| `isolation.runtime_flag_denied` | `Reason` | `internal/trust` |
+| `isolation.slot_uid_shared` | `Reason` | `internal/trust` |
+| `isolation.uid_separation` | `Reason` | `internal/trust` |
+| `isolation.unavailable` | `Reason` | `internal/trust` |
+| `network.lan_for_untrusted` | `Reason` | `internal/trust` |
+| `network.scope_not_offered` | `Reason` | `internal/trust` |
+| `network.scope_unenforceable` | `Reason` | `internal/trust` |
+| `privacy.hosted_not_authorized` | `Reason` | `internal/trust` |
+| `privacy.local_only` | `Reason` | `internal/trust` |
+| `privacy.provider_not_allowlisted` | `Reason` | `internal/trust` |
+| `secrets.class_not_declared` | `Reason` | `internal/trust` |
+| `secrets.not_in_policy` | `Reason` | `internal/trust` |
+| `secrets.untrusted` | `Reason` | `internal/trust` |
+| `trust.not_accepted` | `Reason` | `internal/trust` |
+| `trust.release_needs_dedicated` | `Reason` | `internal/trust` |
+<!-- END GENERATED:reason-codes -->
+
+<!-- BEGIN GENERATED:doctor-ids -->
+## Doctor checks
+
+`nself ci doctor` reports each check under its id. `--nodes` and `--providers` add their sections.
+
+| Id | Name | Package |
+|---|---|---|
+| CI-D001 | toolchain | `internal/doctor` |
+| CI-D002 | docker | `internal/doctor` |
+| CI-D003 | status posting | `internal/doctor` |
+| CI-D004 | store opens | `internal/doctor` |
+| CI-D005 | store version | `internal/doctor` |
+| CI-D006 | config valid | `internal/doctor` |
+| CI-D007 | no leftover .ci.yaml | `internal/doctor` |
+| CI-D008 | config not git-ignored | `internal/doctor` |
+| CI-D090 | nodes section | `internal/doctor` |
+| CI-D091 | providers section | `internal/doctor` |
+| CI-D092 | selftest section | `internal/doctor` |
+| CI-D096 | - | `internal/doctor` |
+| CI-D097 | - | `internal/doctor` |
+| CI-D098 | - | `internal/doctor` |
+| CI-DI01 | toolchain pins | `internal/toolchain` |
+| CI-DI02 | toolchain image | `internal/toolchain` |
+| CI-DI03 | toolchain version | `internal/toolchain` |
+| CI-DN001 | - | `internal/nodes/doctor` |
+| CI-DN002 | - | `internal/nodes/doctor` |
+| CI-DN003 | - | `internal/nodes/doctor` |
+| CI-DN004 | - | `internal/nodes/doctor` |
+| CI-DN005 | - | `internal/nodes/doctor` |
+| CI-DN006 | - | `internal/nodes/doctor` |
+| CI-DN007 | - | `internal/nodes/doctor` |
+| CI-DN008 | - | `internal/nodes/doctor` |
+| CI-DN009 | - | `internal/nodes/doctor` |
+| CI-DN010 | - | `internal/nodes/doctor` |
+| CI-DN011 | - | `internal/nodes/doctor` |
+| CI-DN012 | - | `internal/nodes/doctor` |
+| CI-DN013 | - | `internal/nodes/doctor` |
+| CI-DN014 | - | `internal/nodes/doctor` |
+| CI-DN015 | - | `internal/nodes/doctor` |
+| CI-DP001 | - | `internal/providers/doctor` |
+| CI-DP002 | - | `internal/providers/doctor` |
+| CI-DP003 | - | `internal/providers/doctor` |
+| CI-DP004 | - | `internal/providers/doctor` |
+| CI-DP005 | - | `internal/providers/doctor` |
+| CI-DP006 | - | `internal/providers/doctor` |
+| CI-DP007 | - | `internal/providers/doctor` |
+| CI-DP008 | - | `internal/providers/doctor` |
+| CI-DP009 | - | `internal/providers/doctor` |
+| CI-DP010 | - | `internal/providers/doctor` |
+| CI-DP011 | - | `internal/providers/doctor` |
+| CI-DP012 | - | `internal/providers/doctor` |
+| CI-DP013 | - | `internal/providers/doctor` |
+| CI-DP014 | - | `internal/providers/doctor` |
+| CI-DS001 | - | `internal/selftest` |
+| CI-DS002 | - | `internal/selftest` |
+| CI-DS003 | - | `internal/selftest` |
+| CI-DS004 | - | `internal/selftest` |
+| CI-DS005 | - | `internal/selftest` |
+| CI-DS006 | - | `internal/selftest` |
+| CI-DS007 | - | `internal/selftest` |
+| CI-DS008 | - | `internal/selftest` |
+| CI-DS009 | - | `internal/selftest` |
+| CI-DT001 | isolation level | `internal/isolation` |
+<!-- END GENERATED:doctor-ids -->
+
+<!-- BEGIN GENERATED:pinned-versions -->
+## Pinned versions
+
+| Pin | Value |
+|---|---|
+| plugin version | 1.2.13 |
+| requires nself | `>=1.4.12` |
+
+The toolchain pins, from `free/ci/toolchain/versions.yaml`:
+
+| Name | Kind | Version | Owner |
+|---|---|---|---|
+| actions-runner-image | image | `ghcr.io/actions/actions-runner@sha256:4ffadc0002b2581327e06101fc8c06cd189232baf79fe561fac9caeb76f5e807` | `internal/providers/runnerjob` |
+| binfmt | base-image | `qemu-v10.2.3` | `.github/workflows/ci-toolchain-image.yml` |
+| buildkit | base-image | `v0.34.0` | `.github/workflows/ci-toolchain-image.yml` |
+| debian | base-image | `trixie-slim` | `free/ci/toolchain` |
+| github-actions-runner | tool | `2.338.0` | `internal/nodes/provision` |
+| gitlab-runner-image | image | `docker.io/gitlab/gitlab-runner@sha256:77d03a5c881ff8f97381de4f96a66c080733eeab9c9cf502bd19916a18969113` | `internal/providers/gitlab/runners` |
+| gitleaks | tool | `8.30.1` | `internal/gates` |
+| go | tool | `1.27.2` | `internal/gates` |
+| govulncheck | tool | `1.9.0` | `internal/gates` |
+| hadolint | tool | `2.15.1` | `internal/gates` |
+| node | tool | `24.22.0` | `internal/gates` |
+| pnpm | tool | `12.14.0` | `internal/gates` |
+| python3 | tool | `3.13.16` | `internal/gates` |
+| ruff | tool | `0.17.1` | `internal/gates` |
+| rust | tool | `1.99.1` | `internal/gates` |
+| syft | tool | `1.54.1` | `internal/sbom` |
+| toolchain-image | image | `docker.io/nself/ci-toolchain@sha256:98f00724dbbc1b1ea03f3b1a83c057ba715ec614689e159867f94d72950c44b9` | `internal/toolchain` |
+| trivy | tool | `0.76.0` | `internal/gates` |
+| uv | tool | `0.13.1` | `internal/gates` |
+<!-- END GENERATED:pinned-versions -->
diff --git a/.github/wiki/guides/ci/Scheduling-and-Cost.md b/.github/wiki/guides/ci/Scheduling-and-Cost.md
index e1d8446af..0c744ee8b 100644
--- a/.github/wiki/guides/ci/Scheduling-and-Cost.md
+++ b/.github/wiki/guides/ci/Scheduling-and-Cost.md
@@ -1,6 +1,135 @@
 # CI scheduling and cost
 
-This page covers what `nself ci` spends and how it keeps score. Placement itself (eligibility, scoring, `ci plan`, `ci explain`) is described next to the scheduler; this page is about money.
+Paid capacity is off by default. Nothing that costs money is placed until an operator sets `economics.paid_enabled` and a day or month budget above zero. GitHub-hosted capacity is included only: nSelf never plans paid GitHub minutes.
+
+This page is the one place for how `nself ci` chooses a runner, what it may spend, and how much work it lets run at once. Figures in the tables are read from code. Figures in the text carry a confidence label: `declared` for a registered default or a value you set, `computed` for a local measurement, `estimated` for a bound, `unknown` for no basis. The labels are explained under [the ledger](#the-ledger-and-its-confidence).
+
+## How a runner is chosen
+
+Placement has two steps. First, every runner is tested for eligibility. A runner that fails is dropped and the failing check is recorded as a reason code. Second, each eligible runner gets a score in milliseconds and the lowest score wins. A job with no eligible runner is held or refused, and `nself ci explain <job>` says which reason code stopped each runner.
+
+The score is the sum of nine components, each a value in milliseconds times its preset weight divided by 1000, plus a bias for the runner's cost class: `wait`, `runtime`, `cold_start`, `transfer`, `cache`, `contention`, `cost`, `scarcity` and `reliability`. Each component carries its own confidence in the plan output. A component with no basis is shown as `unknown`, not as zero.
+
+Reasons that are static cannot clear without a configuration change (for example a missing tool or a disabled paid class). The others, such as `capacity.busy`, clear on their own.
+
+<!-- BEGIN GENERATED:sched-reasons -->
+| Reason | Clears without a configuration change |
+|---|---|
+| `allowance.below_margin` | yes |
+| `allowance.unknown` | no (static) |
+| `approval.pending` | yes |
+| `approval.required` | yes |
+| `background.contention` | yes |
+| `background.interactive_queued` | yes |
+| `backpressure.queue_full` | yes |
+| `budget.exceeded` | yes |
+| `budget.unset` | no (static) |
+| `burst.team_only` | no (static) |
+| `capacity.busy` | yes |
+| `cost.unbounded` | no (static) |
+| `cost.unknown_rate` | no (static) |
+| `ephemeral.used` | yes |
+| `labels.mismatch` | no (static) |
+| `limit.global` | yes |
+| `limit.job` | yes |
+| `limit.pipeline` | yes |
+| `limit.project` | yes |
+| `limit.provider` | yes |
+| `limit.runner` | yes |
+| `limit.team` | yes |
+| `limit.user` | yes |
+| `node.deploy_host` | no (static) |
+| `node.discovered` | no (static) |
+| `node.draining` | yes |
+| `node.interactive` | yes |
+| `node.maintenance` | yes |
+| `node.not_ready` | yes |
+| `node.offline` | yes |
+| `node.on_battery` | yes |
+| `node.protocol` | no (static) |
+| `node.reservation` | yes |
+| `node.revoked` | no (static) |
+| `override.excluded` | no (static) |
+| `override.max_cost` | no (static) |
+| `override.max_queue` | yes |
+| `override.min_isolation` | no (static) |
+| `paid.disabled` | no (static) |
+| `platform.mismatch` | no (static) |
+| `platform.none_available` | yes |
+| `pool.excluded` | no (static) |
+| `provider.down` | yes |
+| `provider.owned_elsewhere` | no (static) |
+| `queue.timeout` | yes |
+| `resources.insufficient` | no (static) |
+| `retry.anti_affinity` | yes |
+| `runner.remote_only` | no (static) |
+| `tier.waiting` | yes |
+| `tools.missing` | no (static) |
+<!-- END GENERATED:sched-reasons -->
+
+The full reason list, including job reasons and the other typed reasons, is generated in [Reference](Reference.md).
+
+## Presets
+
+`sched.preset` picks the weights. The default is `balanced` (`declared`). A run can override it with `--prefer <preset>` (`local` is short for `prefer-local`). Weights are per mille; the bias columns are added by cost class.
+
+<!-- BEGIN GENERATED:sched-presets -->
+| Preset | `wait` | `runtime` | `cold_start` | `transfer` | `cache` | `contention` | `cost` | `scarcity` | `reliability` | ms per cost micro-unit | bias `local` (ms) | bias `owned` (ms) | bias `included` (ms) | bias `metered` (ms) | bias `ephemeral` (ms) |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| `auto` | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1 | 0 | 0 | 0 | 0 | 0 |
+| `balanced` | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1 | 0 | 0 | 0 | 0 | 0 |
+| `cheapest` | 250 | 250 | 250 | 250 | 250 | 250 | 4000 | 2000 | 250 | 10 | 0 | 0 | 0 | 0 | 0 |
+| `fastest` | 1000 | 1000 | 1000 | 1000 | 1000 | 250 | 0 | 0 | 1000 | 0 | 0 | 0 | 0 | 0 | 0 |
+| `prefer-included` | 1000 | 1000 | 1000 | 1000 | 1000 | 2000 | 1000 | 0 | 1000 | 1 | 40000 | 40000 | 0 | 60000 | 60000 |
+| `prefer-local` | 1000 | 1000 | 1000 | 2000 | 1000 | 500 | 1000 | 1000 | 1000 | 1 | 0 | 10000 | 30000 | 60000 | 60000 |
+| `preserve-hosted-quota` | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 1000 | 4000 | 1000 | 1 | 0 | 0 | 60000 | 120000 | 120000 |
+<!-- END GENERATED:sched-presets -->
+
+## Overrides
+
+Overrides narrow where work may go. They sit under `sched.overrides.*`: `local_only`, `lan_only`, `private_only`, `providers.allow`, `providers.deny`, `labels`, `runner`, `os`, `arch`, `max_cost_micro`, `max_queue` and `min_isolation`. An override can only tighten: a project cannot loosen what an operator set. `--runner <id>` places every job of a run on one runner and is meant for exceptions.
+
+Limits cap how much runs at once: `sched.limits.pipeline`, `job_matrix`, `project`, `user`, `team`, `global` and `provider.<id>`. No limit is the default. A limit of zero is refused, because the scheduler reads zero as no limit.
+
+## Which keys spend money
+
+Spend keys are `economics.*` and `burst.*`: currency, rates, ceilings, every budget, the approval threshold, `paid_enabled`, `max_paid_timeout`, `margin_micro`, provider ownership, and the burst provider, concurrency, margin, trust and cloud VM settings. They are read from operator scope only, and an admin writes them. A pull request, a branch or a pipeline file cannot set them. Loading and `nself ci policy set` belong to the trust layer; see [policy sources](Trust-Security-and-Privacy.md#policy-sources-and-nself-ci-policy).
+
+```sh
+nself ci policy show
+```
+
+```text
+economics.paid_enabled	false	default
+sched.preset	"balanced"	default
+sched.queue.max_depth	500	default
+```
+
+Each row is key, value and the scope it came from. This is an excerpt of real output from a fresh repository.
+
+## Plan and explain
+
+`nself ci plan` shows the layers, the selection and a placement per job. This is real output for a two-job fixture where the second job needs a tool that is not installed:
+
+```text
+LAYER  JOB    PATH  REQ       STATE        REASON              PLACEMENT
+0      build  deep  required  planned      selection.no_base   local (local, local) cost 0 micro [known]
+0      test   deep  required  unplaceable  selection.no_base   unplaceable: unplaceable.tool
+```
+
+The cost cell ends in the confidence of the figure. `nself ci explain test` prints what the job needs and why it cannot be placed:
+
+```text
+job test  unplaceable  band interactive  source plan
+  needs  platform darwin/arm64  cpu 0  mem_mb 0  isolation_min process  network internet  secret classes none  tools no-such-tool-xyz
+  reason  unplaceable.tool  tool no-such-tool-xyz is not on PATH
+```
+
+`plan --json` carries the same data. Note: `--prefer`, `--runner` and `--max-queue` are accepted by `plan` but not yet applied to its placement (debt D-0991); the plan shows the policy a run uses.
+
+## Job requirements and labels
+
+A job declares what it needs under `requires`: `labels`, `tools`, `accelerators`, `cpu` and `mem_mb`. A runner is eligible only when it matches all of them. The reasons are `labels.mismatch`, `tools.missing` and `resources.insufficient`. To pin a project to certain runners, set `sched.overrides.labels` at project scope; the job then needs those labels on top of its own.
 
 ## Cost classes
 
@@ -56,7 +185,54 @@ A remote attempt that reports an end before its start, and any priced attempt wh
 
 An allowance is the declared ceiling (`economics.ceilings.<provider>`) minus the consumption the provider reported minus what the local ledger spent from the newest day the provider's report covers (providers report with a delay, and streams (skus) lag by different amounts, so the count starts at the newest day of the stream that lags most; that day is counted twice rather than missed; the start is never later than the day before the newest report was made, and a usage line dated more than one day ahead of today is refused). Without a declared ceiling, or without any reported consumption, the allowance is unknown and private jobs do not run on that hosted provider (`allowance.unknown`). A balance the provider reports replaces the ceiling and the imported consumption, and is shown as `known`. Jobs of public repositories on GitHub-hosted runners (label `nself.visibility=public`) do not draw on the allowance. A job also needs the remaining allowance, minus `economics.margin_micro`, to be above its worst case (`allowance.below_margin`). An included provider with no declared rate has no usable bound (`cost.unknown_rate`), and a job past the longest run the policy allows is `cost.unbounded`; included work has no `max_paid_timeout`, and a job with no timeout is priced at that longest run.
 
-## Handoff
+## GitHub-hosted capacity is included only
+
+GitHub-hosted runners are class `included` and nothing else. Their overage is never a placement option and no GitHub provider can be declared `metered` or `ephemeral`. nSelf never plans paid GitHub minutes. Jobs of public repositories on GitHub-hosted runners do not draw on the allowance. Private jobs need a known allowance (`allowance.unknown` otherwise) and a remaining balance above the job's worst case plus `economics.margin_micro` (`allowance.below_margin`).
+
+## Burst
+
+Burst creates a machine for a queued job when waiting costs more than provisioning. It is off until an operator enables a provider (`burst.providers.<id>.enabled`) and paid spend is allowed. Safety rules:
+
+- Cloud burst is for TEAM coordinators only (`burst.team_only` elsewhere).
+- Intent first: the intent row is committed, and its money reserved, before any provider call.
+- One job per machine. The machine is revoked at teardown, and teardown is retried until the resource is gone.
+- The engine deletes only machines labelled `role=ci-ephemeral` with its own coordinator id, and never a host in the deploy-host exclusion set. An unreadable exclusion set stops it.
+- The sweeper runs on start and every five minutes. A machine with no intent is alerted once and deleted after `max_lifetime` plus a grace period. `--dry-run` lists what it would delete and changes nothing.
+- Defaults (`declared`): at most 2 machines at once (`burst.max_concurrent`), a 60 s wait margin (`burst.margin`), a 120 s provisioning latency assumed when a provider has none recorded, and a breaker that opens after 3 join failures for 15 minutes.
+- A decision refuses with the first failing rule and records every input.
+
+## Affected selection
+
+A run may select only the jobs a change can touch. The selector maps changed paths to packages, adds the packages that depend on them, and selects the jobs whose working directory covers one. It answers `full` whenever it cannot prove a narrower set: no base to compare with, an empty diff, a release pipeline, a default-branch run, a path in a generated or opaque directory, a path no package or job owns, an uncertain package graph, or no job left. It never selects fewer jobs on a guess. The selection mode and its reason are the first line of `nself ci plan`.
+
+## Capacity
+
+- Order: strict bands (interactive, normal, background). Inside a band, projects share capacity fairly with equal weights. Inside a project, higher priority goes first, then age.
+- Starvation ceiling: a job that waited longer than `sched.fairness.starvation_after` (30 minutes, `declared`) moves up one band, never above normal.
+- Backpressure: `sched.queue.max_depth` (500, `declared`) bounds the queue. A full queue refuses with `backpressure.queue_full`.
+- Queue wait: `sched.overrides.max_queue` bounds how long a job waits for a runner (`queue.timeout`). A foreground run defaults to 10 minutes (`declared`) unless `--max-queue` is given.
+- Reservations: a node can hold capacity back (`node.reservation`). A placement reserves its slot privately, so two jobs never take the same slot.
+- Background CI (scheduled and housekeeping work) runs in the background band and waits behind interactive work (`background.interactive_queued`, `background.contention`).
+- Runners: local and cloud ephemeral runners are used once per job; a used ephemeral runner is reported as `ephemeral.used`.
+
+## CI health
+
+`nself ci runs stats [--since <duration>] [--project <owner/repo>] [--json]` prints queue, lease, outbox, cache and node health over a window (24 hours by default). A figure with no samples is shown as `unavailable` with the cause, never as zero:
+
+```text
+window 24h0m0s
+leases active 0, stale 0, self-fenced 0
+outbox pending 0, oldest -
+unavailable queue: no_samples
+```
+
+`nself ci doctor` includes the same health section as checks (`CI-STAT-*`).
+
+## Measured overhead
+
+No scheduling overhead figure is published yet (`unknown`). The benchmarks exist (`Place` over 1 to 100 runners and 10 to 1000 jobs; `world.Build`, `Place` and `Admit` against an on-disk store), but a baseline with a performance budget has not been recorded, so this page makes no claim. The status file `free/ci/bench/sched/SCHED-14-status.md` lists what is missing.
+
+## Known gaps
 
 - Not wired yet (debt D-1280): the dispatcher must bind the economics environment with `economics.Bind` (store, spend policy, clock, coordinator id) and copy the spend keys into the scheduler's policy with `economics.ApplyPolicy`. Until then the hooks are inert and nothing paid is placed.
 - A job the scheduler holds with `approval.pending` never reaches the admission step. The dispatcher records the whole pipeline's worst case with `economics.NotePending`, so `ApproveSpend` has a figure to bind to and one approval releases the run. Without it, the figure is the pipeline total at the moment a job is held, and each job that grows the pipeline past it is held again.
diff --git a/.github/wiki/guides/ci/Troubleshooting.md b/.github/wiki/guides/ci/Troubleshooting.md
new file mode 100644
index 000000000..32a5c930a
--- /dev/null
+++ b/.github/wiki/guides/ci/Troubleshooting.md
@@ -0,0 +1,136 @@
+# CI troubleshooting
+
+<!-- docmap: cap:docs.ci-core -->
+
+Start here when a run is red, slow, stuck or surprising. The order that finds most problems is: ask `doctor` about the machine, ask `explain` about the plan, read the log, then reproduce the job. Codes such as `E614` are listed with their summaries and fixes in the generated [[CI reference|guides/ci/Reference]]; this page tells you which one to look for and what to do next.
+
+## Ask the machine: doctor
+
+```text
+NSELF_V15=1 nself ci doctor [--json] [--repo dir]
+```
+
+`doctor` runs a set of read-only checks and prints one line per finding with an id, a verdict (`PASS`, `WARN` or `FAIL`), a reason and, when it knows one, a fix. It covers the toolchain for each detected stack, whether the container runtime is reachable, whether status posting is possible, whether the local store opens and is the right version, whether `.nself/ci.yaml` validates, a leftover legacy `.ci.yaml`, a git-ignored config, and drift between the tools you have and the pinned toolchain image. Nodes, providers and isolation add their own sections when they are in use.
+
+- Exit 0 means clean, 10 means at least one failure, 12 means warnings only, 1 is a usage error and 2 is a bad `--repo`.
+- A section that fails to run, panics or takes too long is reported as its own finding. One broken section never hides the rest.
+- `doctor` never creates the local store. A missing store passes with "created on first run".
+- The table of ids is generated: see the doctor section of the [[CI reference|guides/ci/Reference]]. A warning about drift in a tool version is information: run with `--container` for the pinned version, or install it.
+- Known limits: the toolchain requirement is matched on the first word of a job's command, so a job run through `make` or `sh -c` does not mark a toolchain as required; a job that needs a service does not by itself mark Docker as needed.
+
+## Ask the plan: explain
+
+If a job did not run, or ran where you did not expect, do not guess:
+
+```text
+nself ci plan [--pipeline name] [--trigger t] [--base sha]
+nself ci explain <job>
+```
+
+`plan` lists every job with its state and a reason code. `explain` shows the requirements of a job, the runner it chose, the score components that led to that choice and the alternatives. Both only read; neither starts anything.
+
+| You see | It usually means |
+|---|---|
+| `selection.no_base` | nothing said what changed, so everything runs; pass `--base` or run from a branch with a known base |
+| `pipeline.excluded` | the job is not in the pipeline you named |
+| `when.paths`, `when.branch`, `when.trigger` | a condition in `when` was not met |
+| `when.env_missing` | the variable named in `when.env_present` is not set |
+| `dep.failed` | a job it depends on failed, so it was skipped |
+| `unplaceable.*` | no runner can take it: wrong platform, a missing tool, no Docker or a missing label |
+| `admission.reservation`, `admission.battery` | the machine is protecting itself; see [[Getting started with nself ci|guides/ci/Getting-Started]] |
+| `advisory.tool_missing`, `advisory.data_offline` | an advisory check skipped because its tool or data was unavailable |
+
+## Read the log
+
+```text
+nself ci logs <job|attempt> [--run <run>] [--attempt N] [-f] [--json]
+```
+
+Without `--attempt` it shows the highest attempt of the job. After `--confirm-flaky` that is the passing rerun, not the failing attempt the evidence points to, so pass `--attempt` when you want the original. With `--json` you get NDJSON log records and a final result record. No stored log for that job or attempt is `E633`, and a stored log that cannot be read is `E632`; check that the state directory is writable and not full. A log can be missing when the disk was full or the folder unwritable; the job is unaffected, and `ci logs` is where you see it.
+
+Logs hold redacted output, so a value that matches a known secret shape shows as a mask. Lines carry a sequence number; use it for order, since lines written in one burst can share a timestamp.
+
+## Failure or infrastructure
+
+A failed check carries a **failure class**, and the class decides what happens next.
+
+| Class | Meaning | Retried automatically |
+|---|---|---|
+| `code` | your code or tests failed | no |
+| `infra` | the machine, the network or the tool installation failed | yes, up to the budget |
+| `timeout` | the job ran out of time | no |
+| `cancelled` | someone stopped it | no |
+| `lost` | the runner went away | by recovery, not by retry |
+
+The classifier looks for infrastructure evidence in a fixed order: the executor died without an exit code, a container hit a resource limit, the executor reported its own error, or the last lines of output match a known infrastructure signature, and only when no test-failure marker such as `FAIL`, `not ok`, `assertion` or `panic` is in the tail. Anything else is `code`. **A plain exit 137 or 127 is a code failure**: a program chose it. An unknown job failure is `code`. An error on the executor side that cannot be proven is `infra`, but it is never retried.
+
+The evidence for a failed check names the class, the exit code, a `diagnosis` that matches a signature, a `remediation`, a redacted excerpt and where the log is stored.
+
+**Retries.** An infrastructure failure is retried up to `retry.infra_max`, bounded by the plan's own limit. Release jobs and jobs marked `idempotent: false` run once and wait for an operator instead. Each retry records why the previous attempt failed.
+
+**Install failures.** For Node, a failed frozen install prints a bounded report and is classified from the manager's own error lines: an out-of-sync lockfile, a failing lifecycle script or a test failure is `code`; a registry error, a full disk or a killed child is `infra`. A package manager that does not match the declared one is `E811` and is not retried. A tool that is not installed at all is `E614`.
+
+### Flaky checks
+
+A check that fails once and passes on identical inputs is flaky, and you can measure it without changing a result:
+
+```text
+nself ci --confirm-flaky 3
+nself ci runs --flaky [--limit N] [--json]
+```
+
+`--confirm-flaky N` reruns a job that failed with a code failure up to N more times, stopping at the first pass. N is at most ten. Each rerun is authorised by an audit row naming the failed attempt and is recorded with the diagnosis `confirm-flaky`. The original result stays **failed**: confirmation tells you the check is flaky, it never turns red into green. `runs --flaky` lists checks that both passed and failed on identical inputs (same repository, revision, tracked digest, pipeline, policy, source trust and input digests) among recent runs. Dirty, unbound and ad hoc runs are ignored. The finished run's evidence carries the same marker in the `flaky` field.
+
+## Reproduce a job
+
+```text
+nself ci runs reproduce <job> [--run <run|latest>] [--check] [--shell] [--json] [--repo dir]
+```
+
+Reproduce takes the newest stored run that holds the job, rebuilds its inputs from the evidence (revision, trigger, pipeline, isolation), and prints a **drift report** before doing anything. The drift kinds are a tool whose version changed, a tool that is missing, and a platform that differs.
+
+- A platform that differs is refused (`E634`) before anything runs, and the message names both platforms.
+- If the original evidence was unbound, only the recorded revision is reproduced and you get a warning (`E635`): uncommitted changes are never reproduced.
+- `--check` stops after the report.
+- `--shell` prepares the worktree and runs nothing, and keeps it for you. Remove it with `git worktree remove` when you finish.
+- Otherwise it makes a temporary worktree at the recorded revision, runs the one job through the normal engine, and appends a link line to the state directory under `reproductions/`. The line records both outcomes and `reproduced: true` when the result and the failure class match. The temporary worktree is removed on error, panic and cancel, and a cancelled reproduction writes no link.
+
+Services appear in the report only after the run, not before.
+
+```bash
+mkdir broken && cd broken && git init -q
+git config user.email docs@example.com && git config user.name docs
+mkdir .nself && cat > .nself/ci.yaml <<'CFG'
+version: 1
+jobs:
+  build:
+    kind: test
+    run: [sh, -c, "echo building; echo boom >&2; exit 3"]
+CFG
+git add -A && git commit -q -m init
+rc=0
+nself ci --no-status || rc=$?
+[ "$rc" -ne 0 ]
+nself ci logs build
+nself ci runs list
+nself ci runs reproduce build --check
+```
+
+## Common problems
+
+| Symptom | Look at |
+|---|---|
+| `E614` before any job runs | a required tool is not on `PATH`; the message names it. Install it or run with `--container`. |
+| `E620` on a config you did not touch | the file is validated strictly; the message names the line and key. See [[CI configuration and policy|guides/ci/Configuration-and-Policy]]. |
+| `E812` from the secret scan | a `.gitleaksignore` entry has no review comment; add one with `nself ci config ignore add`. |
+| A required job is `unplaceable.platform` | it needs a platform you have no node for; see [[Nodes and Runners|guides/ci/Nodes-and-Runners]] |
+| `E637` from a service job | no container runtime is reachable; start Docker, Colima or the service |
+| `E646` from an ad hoc command | the default is a container and none is available; use `--isolation process` knowingly |
+| The run is red but every check passed | a required job ended in error, or a required job was skipped; read `nself ci plan` and the evidence `result` |
+| `E606` opening the store | the store was written by a newer binary; upgrade the plugin |
+| A run stays `running` after a crash | start any run; recovery closes runs with no live coordinator, or run `nself ci runs wait <run>` |
+| `nself ci runs wait` exits 10 | the run is still going; call it again |
+| A detached run produced `E648` | the run could not be queued; the message ends with a redacted tail of what it printed |
+| Disk use grows | `nself ci runs prune --dry-run`, then without `--dry-run`; see retention in [[Getting started with nself ci|guides/ci/Getting-Started]] |
+
+If you are stuck on a node rather than on a job, the lost-lease, drain and enrollment problems are in [[Nodes and Runners|guides/ci/Nodes-and-Runners]]. For trust and secrets questions, see [[CI trust, security and privacy|guides/ci/Trust-Security-and-Privacy]].
diff --git a/.github/wiki/guides/ci/Trust-Security-and-Privacy.md b/.github/wiki/guides/ci/Trust-Security-and-Privacy.md
index 84a564bc0..9b51865ac 100644
--- a/.github/wiki/guides/ci/Trust-Security-and-Privacy.md
+++ b/.github/wiki/guides/ci/Trust-Security-and-Privacy.md
@@ -1,8 +1,66 @@
 # CI trust, security and privacy
 
-This page covers the `container` isolation level of `nself ci`: what it blocks, what it does not, and what a node must provide. The sandboxed container level (gVisor) is described in its own section below. The other levels (process, VM) are described next to their own profiles.
+This page is the one guide to what `nself ci` trusts, what it blocks, what it keeps private and what it cannot promise. It has six parts: [Trust and security](#trust-and-security), [Public FOSS PRs](#public-foss-prs), [Secrets](#secrets), [Privacy](#privacy), [Isolation last-verified](#isolation-last-verified) and [Residual risks](#residual-risks). Read the residual risks before you run code you do not trust. Every limit is stated; none is hidden in a footnote.
 
-## The container level
+Commands in `bash` blocks on this page are run by `bash .github/scripts/check-doc-commands.sh`. The reasons table is generated from the code by `go generate ./tools/refgen/...` in `free/ci`. Do not edit it by hand.
+
+## Trust and security
+
+**The model.** Every run has a source trust class (`owner`, `internal`, `collaborator`, `untrusted`). Every job asks for an isolation level, a network scope and secret classes. Every runner declares what it accepts and what it can prove. A job runs only where all three agree. When nothing agrees the job waits with a reason (`E678`). It is never moved to a weaker level.
+
+**Policy sources.** The effective policy is merged from the defaults, your operator rows, the protected default branch, the revision and one run's flags. Each later source can only tighten. See [Policy sources](#policy-sources-and-nself-ci-policy).
+
+**Provenance.** The class comes from facts the forge API gave or from git history, never from a payload field or `.nself/ci.yaml`. See [Source trust](#source-trust-who-made-the-code).
+
+**Isolation levels and what a host must provide.**
+
+| Level | What it gives | Host requirement | Not given |
+|---|---|---|---|
+| `process` | Separate UID per slot on a separated node | Your own PERSONAL node, owner and internal work only | No boundary against the user it runs as |
+| `container` | No privilege, dropped capabilities, read-only root, limits | Docker or Podman with pids, memory and CPU cgroups | Not a boundary for hostile code |
+| `sandboxed-container` | gVisor `runsc`, proven by a real start | Linux with `runsc` | Not a VM (see Residual risks) |
+| `vm` | Tart VM with softnet and a block list | Apple-silicon Mac with Tart and a softnet that supports the block list | Unavailable on Linux (D-0120) |
+| `ephemeral-vm` | One job, destroyed after | Same as `vm` | Unavailable on Linux (D-0120) |
+| `hosted-disposable` | The provider's own isolation | A hosted provider you authorized | nSelf cannot verify it; evidence is `self-reported` |
+
+A probe only lowers a level. A host that cannot provide a level reports it `unavailable`, and no job is placed there on the strength of a promise.
+
+**Network scopes, hygiene and UID separation, evidence and GateAccept, roles and identities, the production boundary and in-stack runners** are in the sections below, in that order of dependence.
+
+**Production boundary.** A production host is CI-ineligible by default. A deploy-host override needs a minimum isolation, and a TEAM coordinator's own host needs the `vm` floor (reasons `boundary.deploy_host`, `boundary.override_minimum`, `boundary.coordinator_host`).
+
+**In-stack runners.** The forgejo plugin ships the forge and no runner, no Docker socket, and registration closed (`FORGEJO_DISABLE_REGISTRATION` defaults to `true`). The github-runner plugin is trusted-only: it refuses a runner group that is open to public repositories, unless `GITHUB_RUNNER_ALLOW_PUBLIC_REPOS` is exactly `true`, an opt-out that is unsafe and logged on every start. It reports a deploy-host warning when `ENV` is `prod`, `production` or `staging`.
+
+**Reason codes.** When admission refuses a placement it names one or more reasons. They are generated from `internal/trust`:
+
+<!-- BEGIN GENERATED:trust-reasons -->
+| Reason | Meaning |
+|---|---|
+| `approval.required` | approval required |
+| `boundary.coordinator_host` | coordinator host floor violated |
+| `boundary.deploy_host` | deploy host ineligible |
+| `boundary.override_minimum` | deploy override minimum violated |
+| `isolation.below_minimum` | isolation below minimum |
+| `isolation.cotenancy` | untrusted and secret-bearing work overlap |
+| `isolation.rootful_runtime` | rootful runtime is unavailable |
+| `isolation.runtime_flag_denied` | runtime flag denied |
+| `isolation.slot_uid_shared` | job slot shares a UID |
+| `isolation.uid_separation` | node lacks UID separation |
+| `isolation.unavailable` | isolation unavailable |
+| `network.lan_for_untrusted` | untrusted work has a LAN route |
+| `network.scope_not_offered` | network scope not offered |
+| `network.scope_unenforceable` | network scope cannot be enforced |
+| `privacy.hosted_not_authorized` | hosted execution not authorized |
+| `privacy.local_only` | local-only work must stay local |
+| `privacy.provider_not_allowlisted` | provider not allowlisted |
+| `secrets.class_not_declared` | secret class not declared |
+| `secrets.not_in_policy` | secrets disallowed by policy |
+| `secrets.untrusted` | untrusted work requests secrets |
+| `trust.not_accepted` | runner does not accept this trust class |
+| `trust.release_needs_dedicated` | release secrets need a dedicated runner or VM |
+<!-- END GENERATED:trust-reasons -->
+
+### The container level
 
 A job at this level runs in a Docker or Podman container that the isolation profile builds from one pure function. The executor refuses any command line that is not on its allowlist, whatever the profile says.
 
@@ -16,17 +74,17 @@ Every container gets:
 - The labels `nself.ci.attempt`, `role=ci-ephemeral` and `coordinator_id`, so an orphan sweep can find them.
 - The job environment through the runtime's stdin env file. No value reaches an argv or a file on disk.
 
-## What it does not block
+### What it does not block
 
 - A kernel escape. A container shares the host kernel. For code you do not trust, use the sandboxed container level (gVisor) or a VM.
 - Network egress on `lan`, and anything a job does with the hosts the proxy allows under `restricted` and `internet`.
 - Disk use inside the workspace. The workspace is removed after the attempt. Files the job user created are removed by a cleanup helper that runs in a separate busybox image pinned by digest (image lock entry `ci-cleanup`), never in the job image, so an image without a shell cannot leave them behind. If the helper image cannot start (an air-gapped node that never pulled `ci-cleanup`), the cleanup is tried once in the job image, as before; if that fails too, the job log says so and the host removes what it owns; a workspace it cannot empty fails a passing run as an infra failure (`E610`).
 
-## The sandboxed container level (gVisor)
+### The sandboxed container level (gVisor)
 
 `sandboxed-container` is the container level run with gVisor's `runsc` runtime. The job's syscalls go to gVisor's Sentry, a user-space kernel, and only a filtered set reaches the host kernel. `nself ci --trust untrusted -- <cmd>` needs this level, with network `none`. Without it that command exits with `E647`; it never falls back to a plain container.
 
-### Install
+#### Install
 
 1. Install gVisor from the [install guide](https://gvisor.dev/docs/user_guide/install/) (check the download hash).
 2. Run `sudo runsc install`, then restart the Docker daemon. Docker must list the runtime: `docker info --format '{{json .Runtimes}}'`.
@@ -34,7 +92,7 @@ Every container gets:
 
 A runsc binary or a runtime entry is not availability. The profile starts a small probe container under `runsc` (`docker run --runtime=runsc --network none` of a busybox image pinned by digest, running `dmesg`) and the level is available only when the output has gVisor's banner as a whole line (`Starting gVisor...`, optionally behind a `[ time ]` stamp). The runtime entry must also point at a binary named `runsc`. The runsc version and the platform are reported as facts. The probe image is in the image lock as `ci-gvisor-probe`, so the daily image probe covers it.
 
-### Platform
+#### Platform
 
 The probe reads the runtime entry and records `platform`. `systrap` is the default; `ptrace` is deprecated upstream and may be removed; use it only where systrap does not run on the host kernel. `kvm` is refused where `/dev/kvm` is absent. Any other value is refused too (`isolation.platform_unsupported`).
 
@@ -46,7 +104,7 @@ The probe asks the local daemon: a Docker context that points at a remote host i
 
 On a separated node the agent user's own runtime must be rootless, and the probe starts runsc under it. Rootless Docker usually needs `--ignore-cgroups` for runsc, which is refused, so the level is normally unavailable there (`isolation.runtime_flag_denied`, or `isolation.probe_failed` if the start fails).
 
-### What it does not give you
+#### What it does not give you
 
 gVisor is not a VM.
 
@@ -57,17 +115,17 @@ gVisor is not a VM.
 
 Some toolchains do not run under gVisor because they need a syscall the Sentry lacks. That is recorded as a failed job, not worked around: there is no fallback to a plain container for a sandboxed job.
 
-### Handoff
+#### Handoff
 
 - `ci doctor` does not yet print the install steps; the profile exposes them as the `hint` fact on an unavailable result (`gvisor.InstallHint`).
 - Podman support needs a way to read and judge its runtime table.
 - Network scopes `restricted` and `internet` use the same scope planner as the container level; the sidecar and the job network are created by the container profile, and the sandboxed job runs on that network under `runsc`.
 
-## The macOS VM level (Tart)
+### The macOS VM level (Tart)
 
 On an Apple-silicon Mac the `vm` and `ephemeral-vm` levels run each attempt in a fresh clone of a VM image, through [Tart](https://tart.run). Linux has no `vm` level here. You install Tart and its network filter (softnet) yourself: nSelf does not bundle, download or redistribute either, and `ci doctor` shows the licence note that goes with them. The levels are the same profile; every attempt gets its own clone, so `ephemeral-vm` adds nothing a `vm` job lacks.
 
-### Set up
+#### Set up
 
 1. Install Tart and softnet (for example `brew install cirruslabs/cli/tart`).
 2. Build or pull a base image your jobs need, with Remote Login (ssh) on and a key you control in the image user's `authorized_keys`.
@@ -83,7 +141,7 @@ ci:
 
 No image is shipped and a tag without a digest is refused: the level reports `isolation.tart_base_image` (E678) until the setting is right.
 
-### What a job gets
+#### What a job gets
 
 - A clone named `nself-ci-<attempt>`. The workspace is copied in over the ssh session (a tar stream), the job runs there, and only the artifact paths the job declares come back. Nothing from the host is mounted into the VM.
 - Secrets are written as `export` lines on the ssh session's stdin. They are never on the `tart` or `ssh` command line and never in a file.
@@ -91,7 +149,7 @@ No image is shipped and a tag without a digest is refused: the level reports `is
 - Orphans: each clone has a marker file under `<CI home>/tart/` that the running attempt keeps locked. If the coordinator dies (even `kill -9`), the lock goes with it, and the sweep at the next attempt start stops and deletes the clone. A VM you named `nself-ci-*` by hand has no marker and is never touched.
 - Apple allows two macOS VMs at once. The profile counts free slots (`free_slots` in `ci doctor`) and never starts a third; the job waits.
 
-### Network scopes on Tart
+#### Network scopes on Tart
 
 | Scope | How it is enforced |
 |---|---|
@@ -100,7 +158,7 @@ No image is shipped and a tag without a digest is refused: the level reports `is
 
 `restricted` and `internet` go through the same egress proxy as the container level (public hosts only, the deploy exclusion set refused), served by the coordinator on the gateway address, and the ssh session sets `HTTP_PROXY` and `HTTPS_PROXY`. Before the job starts, a check runs inside the VM: the proxy must answer, the gateway must answer, and the public internet, the Mac's own LAN addresses and the exclusion set must not. The check also fails closed on: a guest that is not macOS, no answer from the gateway (nothing then proves the controls work), the public internet reachable by TCP (IPv4 and IPv6) or ping, any of a fixed list of host service ports open at the gateway address (22, 53, 80, 111, 443, 445, 548, 631, 3283, 5900, 8080), and, under `none` and `restricted`, public names resolving through the VM's resolver. A scope that cannot be proven fails the attempt with `E679` (`network.scope_unenforceable`), and the clone is deleted. The proxy serves only the attempt's own VM address, so a second VM on the same gateway cannot use it. If the installed Tart has no softnet block option, or no proxy can be started, every scope below `lan` is unavailable.
 
-### Known limits
+#### Known limits
 
 - Real-run evidence needs an Apple-silicon Mac with Tart; GitHub-hosted macOS runners do not allow nested virtualisation.
 - softnet filters by destination address, not port. The gateway address is allowed, so anything on your Mac that listens on all interfaces (ssh, file sharing, screen sharing) or on the gateway, and the resolver the VM is given, are reachable from the VM on that address. The check above refuses the attempt when it finds one of the listed ports open or a public name resolving; turn those services off on a Mac that runs untrusted jobs. If the vmnet resolver cannot be closed, `none` and `restricted` stay unavailable on that Mac and `internet` and `lan` still work.
@@ -111,12 +169,12 @@ No image is shipped and a tag without a digest is refused: the level reports `is
 - Declared artifact paths are literal paths (no globs). Symlinks and special files in them are refused, and a collect is capped at 1 GiB, 100000 entries and 64 levels.
 - The Tart gateway is `192.168.64.1` unless the Mac's vmnet network was changed; a different address makes the network check fail closed.
 
-### Handoff
+#### Handoff
 
 - `ci doctor` does not print the Tart facts yet; the profile exposes `tart_version`, `licence_note`, `free_slots`, `softnet_block` and `base_image_cached` as availability facts.
 - The tagged integration tests (`-tags tart`) are the real-run evidence; they run on a Mac with Tart and the environment variables listed at the top of `integration_test.go`.
 
-## Network scopes
+### Network scopes
 
 A job runs under one scope. An undeclared scope takes the default of its trust class: `owner` and `internal` get `lan`, `collaborator` gets `internet`, `untrusted` gets `restricted`. An untrusted job that declares `lan` or `privileged` is refused (`E679`), before any resource exists.
 
@@ -142,11 +200,11 @@ No environment variable loosens the set (`NSELF_ALLOW_PRIVATE_URLS` of the SDK g
 
 A tool that ignores proxy variables fails under `restricted` and `internet`. That is intended: there is no silent bypass.
 
-### What a runner proves
+#### What a runner proves
 
 A scope is offered only where it is enforced. The probe builds the same network and sidecar a job gets, then runs one container on it that tries to connect to the host's own addresses (on a port where the probe listens), to `169.254.169.254` and to a raw public address. If any connection succeeds, or the listener sees one, `restricted` and `internet` are withheld. The result is the capability fact `network.enforced_scopes`; the scheduler derives `NoLANRoute` from it, so a runner cannot declare it. Where the network or the sidecar cannot be created the scope is unavailable (`E679`), never approximated. The sidecar runs the host's own binary in a Linux container, so `restricted` and `internet` are Linux-host features (Docker or Podman, rootless included); on macOS they report unavailable.
 
-### Known limits
+#### Known limits
 
 - The exclusion set is the one this host can build for itself. A team coordinator that keeps the set in its own store can replace it with `run.RegisterNetscopeExclusions`; nothing registers one yet.
 - The scheduler reads the proof for the local runner. A remote node's `network.enforced_scopes` is not reported yet, so no untrusted job is placed on a remote node on the strength of it. A remote job's declared scope is checked against the class it was placed at three times: by the scheduler's admission rule, by the coordinator before it delivers the lease, and by the agent before it runs it. An untrusted job that declares `lan` or `privileged` fails there with E679 and never reaches the executor. A job that declares no scope runs as `none`, locally and on a node; the class default is not applied.
@@ -154,7 +212,7 @@ A scope is offered only where it is enforced. The probe builds the same network
 - Linux route discovery reads all routing tables through netlink, including policy routes. A public address that hairpins to a LAN service through the router cannot be learned from those tables. It still needs an observed egress address from the target network in the never-list; automatic public-NAT discovery is not implemented.
 - The sidecar bind-mounts a private staged copy of this process's binary with mode `0755`; the source binary's permissions are unchanged. The copy is removed with the attempt's network resources. Restricted and internet scopes still require Linux.
 
-## What a node must provide
+### What a node must provide
 
 - Docker or Podman with the pids, memory and CPU cgroup controllers delegated. The probe reads them from `info` and reports the level unavailable (`isolation.limits_unenforceable`) when one is missing, because the runtime would start the container and silently drop the limits. Rootless Docker needs cgroup v2 with systemd delegation. Rootless Podman needs the same.
 - On a node where the agent user has no docker group (a separated node), only a rootless runtime counts. A rootful socket is root-equivalent. Set `NSELF_CI_NODE_SEPARATED=1` on such a node; unset means "not separated" and a rootful runtime is accepted.
@@ -162,7 +220,7 @@ A scope is offered only where it is enforced. The probe builds the same network
 
 When the level is unavailable the job waits before it fails, and never falls back to a weaker level. A slot the runtime cannot map (`isolation.slot_uid_unmapped`, for example a fifth concurrent attempt on a rootless runtime) is waited out until another attempt frees one, for up to 30 minutes (slot 0 is never waited for: no other attempt can free a better one). A missing runtime, a failed probe or limits the runtime cannot enforce are retried for about a minute. The job log says `waiting for ... isolation` and repeats it every minute. Only a refusal before the job started is waited for. After the wait the job fails with E678 and its stable reason. Other reasons (a rootful runtime, an unenforceable network scope) fail at once.
 
-## Workspace hygiene and job UID separation
+### Workspace hygiene and job UID separation
 
 Every attempt gets its own job root, a fresh `0700` directory under the CI home (`work/<attempt>`). When the attempt ends, `Cleanup` does four things, in this order, and each step runs even if the one before failed:
 
@@ -175,7 +233,7 @@ Every attempt gets its own job root, a fresh `0700` directory under the CI home
 
 `SweepOrphans` runs once when the first attempt of a process starts. It removes the roots and labelled resources of attempts that no live lease owns. It spares attempts of the running process, attempts with a live process marker and roots younger than 12 hours, because a second `nself ci` on the same machine may still own them. It leaves an attempt alone while a container of that attempt is still running (the executor's own recovery removes the containers of dead coordinators), and it does not run at all while a container runtime is installed but not answering, because a sibling's live job could not be told from an orphan.
 
-### Which user a job runs as
+#### Which user a job runs as
 
 `Separation` picks the host UID for the attempt's slot. Each slot has its own UID, so two concurrent attempts never share a UID and cannot read each other's workspace or `/proc/<pid>/environ`.
 
@@ -191,83 +249,14 @@ The one exception is deliberate and narrow. Evidence from such a job is `coordin
 
 To enable `userns` on user-mode Linux, install `uidmap` (for `newuidmap`), give the agent user a range in `/etc/subuid` and `/etc/subgid`, and allow unprivileged user namespaces. Ubuntu 24.04 restricts them by default (`kernel.apparmor_restrict_unprivileged_userns=1` leaves the namespace without capabilities, so the job cannot switch to the mapped UID): the probe then reports `userns.unavailable` and the node stays non-separated until a profile or that sysctl allows it. The job runs as `unshare --user --map-users=0:<uid>:1 --map-groups=0:<uid>:1 --setuid=0 --setgid=0 -- <command>`; the probe checks that exact command. Hygiene creates no OS users and no sudoers entries; `nself ci nodes add --system` does that once.
 
-### Known limits
+#### Known limits
 
 - Leftover processes of a job that ran under your own UID (the local run loop and the owner exception) are found by the `NSELF_CI_EXEC_ATTEMPT` tag in their environment. A job that strips the tag, or a process that makes its environment unreadable, can evade the scan. Separated attempts are found by their job UID instead. macOS has no `/proc`, so the process and socket scans are skipped there.
 - A job user's `cron` and `at` entries, SysV IPC objects and home directory are not cleaned by hygiene. `nself ci nodes add --system` is where those belong.
 - The agent cannot kill or remove files that a job user owns. A separated node passes hygiene a `JobRunner`, which its job shim implements, and the kill and the removal then run as the job user. Without one, cleanup reports `E681` and the node drains rather than claiming success.
 - Between a check and the action it guards (the process group kill, a volume removal, the mount snapshot) there is a few-millisecond window. Closing it needs a PID namespace or cgroup per job.
 
-## When each level was last verified
-
-A level that worked once may not work today: a runtime update or a kernel change can silently end it. So `nself ci doctor` shows, for each level, the date a passing check last proved it on this machine.
-
-```
-nself ci doctor            # lines isolation.container ... isolation.vm
-nself ci doctor --json     # each of those checks has "verified_at": an RFC 3339 time, or null
-```
-
-| Level | Reads | How it is proven |
-|---|---|---|
-| `isolation.container` | `verified <date> on <host class>` or `unverified since never` | the container integration tests |
-| `isolation.sandboxed-container` | same | the gVisor integration tests (needs `runsc`) |
-| `isolation.network` | same | the network scope integration tests |
-| `isolation.hygiene` | same | the workspace hygiene integration tests (Linux) |
-| `isolation.vm` | same on an Apple-silicon Mac; on Linux `unavailable (no KVM host, D-0120)` | the Tart tests (needs Tart and its test image) |
-| `isolation.ephemeral-vm` | Linux only: `unavailable (no KVM host, D-0120)` | not provable on Linux |
-
-The host class is the platform of the machine that ran the check, for example `linux/amd64`.
-
-**Where the date comes from.** The `isolation-levels` drill (`scripts/drill/isolation-levels/run`, job `drill-isolation-levels` of the `drills` pipeline) runs the integration tests of every level the host can run and records one check per level. Doctor reads the stored evidence of those runs and reports the newest passing check of each level. Doctor never writes. A level with no passing check reads `unverified since never`; that is the honest state of a machine that never ran the drill, so it is not a warning.
-
-**Run it.**
-
-```
-nself ci --pipeline drills --job drill-isolation-levels
-scripts/drill/isolation-levels/run          # same, started directly; NSELF_CI_BIN and NSELF_CI_HOME choose the binary and the store
-```
-
-A level whose prerequisite the host lacks (no running Docker or Podman, no `runsc`, no Tart) ends `error` with `reason: prerequisite.missing` in its excerpt. That is never a pass and never changes the last-verified date. A level that does not exist on the host class (for example `vm` on Linux) gets no check. `ISOLATION_DRILL_LEVELS=container,network` narrows the run to those levels. The drill runs real containers; give its job more than the default 10 minutes with a `drill-isolation-levels` job in `.nself/ci.yaml` if the host is slow. `scripts/drill/isolation-levels/selftest.sh` checks the drill script itself against fake tools.
-
-### Handoff
-
-- Stored evidence keeps each nested check only on the drill check's excerpt: the last line, `passed: <ids>`, lists the nested checks that passed (internal/drill writes it, `store.LastVerified` reads it). A format change must change both; a test pins them together.
-- The linux `ci-isolation-linux.yml` pull-request job runs the drill against a throwaway store and fails unless doctor shows a non-null `verified_at` for `isolation.container`, `isolation.sandboxed-container` and `isolation.network`.
-
-## Whether each level can run now
-
-`nself ci doctor` also probes every isolation profile and prints one `isolation.<level>.availability` line per level (`isolation.container.availability`, `isolation.sandboxed-container.availability`, `isolation.vm.availability`, `isolation.ephemeral-vm.availability`). Each reads `available (<level>)` or `unavailable: <reason>`, such as `isolation.runtime_missing`, `isolation.tart_base_image` or `isolation.tart_no_free_slot`.
-
-For an unavailable level the line carries the fix as its `remediation` (the install steps: Tart from `brew install cirruslabs/cli/tart`, gVisor from its install page then `sudo runsc install`) and prints the profile facts under it. For Tart the facts are `tart_version`, `base_image`, `base_image_cached`, `free_slots`, `running_vms`, `softnet_block` and `licence_note`: Tart and softnet are third-party tools under their own licences, you install them, nSelf neither bundles nor redistributes them. An unavailable level is not a failure: these lines always pass, because a host without Tart or gVisor is a normal state.
-
-## Secrets
-
-A job asks for secrets by reference, never by value: `secrets: [project/NPM_TOKEN, release/ANDROID_KEYSTORE_PASSWORD, environment/staging/API_KEY, deploy/prod/DEPLOY_KEY, team/SHARED_TOKEN]`. The part after the last slash is the environment variable the job sees, and two refs may not use the same variable (`E674`). Names that would change how a process or the docker client runs (`PATH`, `HOME`, `DOCKER_*`, `LD_*`, `DYLD_*`, `GIT_*`, `NSELF_CI_*` and similar) are refused too.
-
-| Class | Store file (`.secrets/`) | Who may get it |
-|---|---|---|
-| `project` | `ci.age` | trusted jobs on an eligible runner |
-| `environment/<env>` | `ci-<env>.age` | trusted jobs on an eligible runner |
-| `release` | `release.age` | `internal` or `owner` jobs on a dedicated-trusted node or a VM |
-| `deploy/<env>` | `<env>.age` | same as `release` |
-| `team` | the node's own team store | trusted jobs on an eligible runner; node-local, never granted with `nodes secrets grant` |
-
-How it works:
-
-- Refs are checked first: trust class of the job, the runner's facts, the runner's declared secret classes and the policy's `trust.secrets` allowlist. A refusal (`E677`) names the reasons and makes no resolver call. Untrusted jobs never get a secret.
-- Values come from one place: `nself config secrets resolve`, run on the node that executes the job. A TEAM coordinator passes references only and never holds a value. Only a PERSONAL coordinator over the SSH carrier to your own node may send a `project` or `environment` value.
-- On an agent node the resolver runs with `SECRETS_AGE_KEY_PATH` set to that node's own age identity, so the node decrypts only the files you granted to it: `nself ci nodes secrets grant <node> --class project` (also `environment/<env>`, `release`, `deploy/<env>`). `release` and `deploy` files go only to a dedicated-trusted node. A node whose registry entry has `secrets_eligible: false` (jobs could read its age key) is refused with `E677`. `revoke` always works; it does not unsee plaintext the node already read, so rotate the value afterwards.
-- Delivery is by environment only: the process environment, `docker run -e NAME` with the value in the docker CLI's own environment (never in argv), or `export` lines on the SSH stdin of a Tart VM. No file, URL, cache key, artifact or log ever holds a value.
-- Every value is registered with the output redactor before the job starts. If the installed redactor is the pass-through default, or a value cannot be registered (shorter than 6 bytes), nothing is injected and the attempt fails (`E676`) before it starts. Buffers are zeroed when the attempt ends, whether it passed, failed, was cancelled or lost.
-- No `nself config secrets resolve` in the installed CLI: the job fails before it starts with `E675`.
-
-Limits: only the byte buffers the Source owns are zeroed. Copies in Go strings (the job environment slice handed to the process, the redaction registry, the legacy-environment read) stay in the nself-ci process until it exits, and a failed availability probe is remembered until it restarts. Values live in process memory and the job's environment for the attempt. For container jobs dockerd also keeps `-e` values in the container configuration until the container is removed (`--rm` and the hygiene sweep remove it). `/proc/<pid>/environ` is readable only by that attempt's own job user.
-
-Android release builds: until `release.age` holds the keystore secrets, `ANDROID_KEYSTORE_BASE64`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS` and `ANDROID_KEY_PASSWORD` in your own environment still work, on your own machine only. One audit row (`secret.legacy_env`, value-free) is written first; if it cannot be written the legacy value is not used. The `legacy-env` label is kept on the Source and is not yet copied into run evidence. A remote node never uses this path.
-
-A node granted a `release` or `deploy` file must be dedicated-trusted (operator-owned, assigned trust, accepts only `owner`, one authorized project); `nodes secrets grant` does not yet check that the project is the one the file belongs to, so grant these files only to a node dedicated to that project. Multi-line values (PEM keys) need the baseline container path today; the hardened path refuses them.
-
-## Source trust: who made the code
+### Source trust: who made the code
 
 Every run has a source trust class: `owner`, `internal`, `collaborator` or `untrusted`. It decides what the run may touch (secrets, network, isolation) and it is never taken from a payload field, a job input or `.nself/ci.yaml`. A coordinator that runs jobs as you only starts `owner` and `internal` work; anything below needs an isolated runner.
 
@@ -302,7 +291,7 @@ Limits, so you can judge them: the reflog expires and is read for the last 5000
 
 Handoff for later Tickets: `source.Classify(model.TriggerFacts) Result` and `source.ClassifyLocal(source.GitFacts) Result` are pure (`internal/trust/source`). `run.SourceTrust` is the registered `TrustClassifier`; `Decide` returns the reasons, `ClassifyForge(ctx, root, facts)` classifies a forge trigger (P7-TRUST-17 feeds it recorded deliveries; P7-TRUST-24 reads `RequiresApproval`). The `Kind`, `Auth` and `Repo` fields of the facts carry no source label: the adapters must derive them from the authenticated delivery, not from its body. `source.ApplyCap` is the one place the machine cap lowers a class.
 
-### Run approvals
+#### Run approvals
 
 A run that needs approval waits in the `approval` admission step with the placement reason `approval.required` until a valid approval exists. A run needs approval when the source facts recorded for it say so, or, with no facts recorded, when its source trust is `untrusted` (a collaborator's pushed commit is not held; a stranger's is).
 
@@ -320,7 +309,7 @@ nself ci runs approve <run> [--sha <sha>] [--spend] [--json]
 
 Handoff: `source.Binding`, `source.VoidReasons` and `source.RequiresApproval` are the pure rules (`internal/trust/source/approval.go`); the rows live in `internal/store/trust_approvals.go` (`trust_run_facts`, `trust_approvals`). The source hook records the facts with `Store.RecordApprovalFacts` (not yet wired: see the Epic Invalidations).
 
-## The production boundary
+### The production boundary
 
 CI work stays off the machines that run production, and off a coordinator host that is not isolated enough. Two rules apply, and every refusal carries error code `E689` with the reason `boundary.deploy_host`, `boundary.override_minimum` or `boundary.coordinator_host`.
 
@@ -338,7 +327,7 @@ Details:
 - Matching is done from the deploy inventory on the coordinator, never from what a node says about itself.
 - `E689` fix: run the job on a node that is not a deploy host, or on one you overrode with owner or internal work at `vm` or stronger and no release jobs or release or deploy secrets. On a coordinator host, run collaborator and untrusted work elsewhere, or move the coordinator to a VM.
 
-## Roles, tokens and the audit log
+### Roles, tokens and the audit log
 
 A TEAM coordinator knows three roles, ordered `member < release < admin`, and no per-user permissions. In PERSONAL mode the operator on the coordinator host is allowed everything (access to the data directory is admin access) and every decision is still audited.
 
@@ -350,7 +339,7 @@ A TEAM coordinator knows three roles, ordered `member < release < admin`, and no
 
 A grant or token names the projects it covers (`--project <id>` repeated, or `--project '*'`). An actor scoped to named projects cannot do a project-wide `release` or `admin` action. Every refusal is `E687`; the reason key says why (`role`, `project`, `no_grant`, `node_kind`, `bad_certificate`, `token_unknown`, `token_expired`, `token_revoked`, `self_approval`, `author_unknown`, `unknown_action`, `unknown_role`, `bad_request`, `audit_secret`).
 
-### Identities
+#### Identities
 
 - **User certificate** from `pki.IssueUser`: `ActorFromPeer` maps it to the principal's live grant. An actor is not a snapshot: every decision re-reads the grant, the token and the certificate's denied state, so a revoked grant, token or serial, or an expired certificate, ends access on an actor resolved earlier, and a lowered role applies at once. A token keeps the role it was issued with: lowering or replacing a grant does not change the principal's tokens (revoke them with the grant). A node or coordinator certificate is refused (`node_kind`), as is a revoked, denied or expired one. A certificate with no grant has no role.
 - **Scoped token**: 32 random bytes in base64url, stored only as its sha256, with a role, projects and an expiry (default 720 h, at most 8760 h). `nself ci serve admin token issue` prints it once; later commands show the id and state, never the token. `roles revoke <principal>` ends the grant and every live token issued to that principal in one step and one audit row. Send tokens over TLS only: the transport enforces that, not the role check.
@@ -371,17 +360,17 @@ nself ci serve admin audit seal
 
 Every grant, token and user certificate records a `subject`: `self` when it was issued with `--self` to the data directory's own operator identity, otherwise the named principal. `self` is reserved: a principal cannot be named `self`, so a remote identity cannot hide among the operator's own. `roles.NonSelfPrincipals` counts the live grants, tokens and user certificates whose subject is not `self` (a certificate nobody marked counts as non-self); the node-mode check reads it.
 
-### Issuing user certificates
+#### Issuing user certificates
 
 On the coordinator host, `NSELF_V15=1 nself ci serve admin cert issue <principal>` issues a user mTLS certificate and prints the certificate chain, private key and root as PEM once. Redirect stdout to a private file (for example, set `umask 077` first); `--json` returns these as `cert_pem`, `key_pem` and `root_pem`. The private key is never stored by the coordinator. The TTL defaults to seven days and must be between one minute and seven days.
 
 Issuance requires admin access and does not grant a role: grant the principal its role separately. Each successful issuance records a certificate subject and a `cert.issue` audit event before returning the credentials. `--self` is accepted only for the operator's own principal and records subject `self`; otherwise the named principal counts toward TEAM mode, including when issuing to yourself without `--self`. Use the coordinator's `NSELF_CI_HOME` for both the store and its CA keys. If subject recording or audit fails, no credential is returned; a certificate already recorded before that failure can remain counted conservatively as non-self.
 
-### The audit log
+#### The audit log
 
 There is one audit table. The `trust-audit` set chains it: each sealed row's `head` is the sha256 of the previous head and the canonical row (seq, time, actor, action, target, detail). `Append` inserts a row and seals every pending row in one `BEGIN IMMEDIATE` transaction, so concurrent writers, even in a second process, lose no row. Rows other packages write through the core audit API (every node mutation) are sealed by the next `Append`, by `audit seal`, or by a sealer the TEAM coordinator runs every 60 s. `audit --verify` only reads, inside one snapshot: it prints `unsealed: <n>` and exits 1 when rows are still unsealed after 60 s, when a sealed row no longer matches its hash (the row is named), when the chain link is broken, when a seq number is missing (rows are never deleted, so a gap or an AUTOINCREMENT counter above the last row means rows were removed, including the newest ones), or when an unsealed row sits below a sealed one (a cleared head). `audit seal` refuses to re-chain such a row (E609), so the damage stays visible. An `Append` or a mutation still records its row, left unsealed, so a revocation is never blocked by tampering; `--verify` keeps failing until the log is restored from backup (there is no accept-the-break command yet). An event whose actor, action, target or detail contains a registered secret value, in any encoding the redactor knows, is refused (`E687`, reason `audit_secret`) and nothing is written. P7-TRUST-26 policy writes call `audit.AppendTx` to put their row in the policy write's own transaction.
 
-### Recovering a damaged audit chain
+#### Recovering a damaged audit chain
 
 For E609 or a failed `audit --verify`, restore a known-good coordinator backup; there is no command to accept a break. Do not clear heads, delete rows or recompute the chain in SQL: that destroys evidence of the break.
 
@@ -407,7 +396,7 @@ Handoff for later Tickets: `roles.Authorize(ctx, actor, role, project)` and `rol
 Wiring left to the coordinator process (P7-NODE-10 and P7-TRUST-26): start `audit.Log.RunSealer` (60 s) so rows other packages write get sealed, call `audit.SetScanner(run.Redactions)` before its first `Append` or `AppendTx` (the `serve admin` commands do this themselves), and resolve an Actor per request, not per connection. `store.CertSubjectPut` has no caller until the command that issues user certificates records their subject.
 
 
-## Evidence gate acceptance (E685)
+### Evidence gate acceptance (E685)
 
 The coordinator judges every evidence document against a `Gate` built from its own protected policy and the current checkout; nothing in the gate comes from the document being judged. `attest.GateAccept(ev, g)` returns every reason the evidence fails, in a fixed order; an empty list means the evidence is accepted. `attest.GateAcceptDocument(doc, g)` decodes raw bytes and judges them in one step so a registered remote verifier sees the exact bytes once; it refuses documents with duplicate JSON keys. Both are pure and fail-closed: an empty or unknown gate field never matches, unknown freshness is stale, and a zero `Gate` accepts nothing. Adhoc and drill pipelines never satisfy a gate. Self-reported evidence passes only a default-class gate whose operator policy admitted it, never a release gate.
 
@@ -429,21 +418,21 @@ When the gate refuses, the error carries code `E685` ("evidence rejected") and o
 | `evidence.selection_partial` | the gate demands full selection (release gates always do) and the evidence's selection mode is not `full` |
 | `evidence.not_passing` | the evidence's overall result is not `pass`, or a required job's checks include a non-passing result |
 
-### Producer admission
+#### Producer admission
 
 The gate treats each producer kind differently. `coordinator-recorded` evidence is accepted without further checks (the coordinator wrote it). `signed-remote` evidence is verified against the re-marshalled or raw document bytes using the node registry's pinned keys; any failure yields `evidence.signature_unverifiable`. `self-reported` evidence is accepted only when the gate is default-class and the operator-scope policy set `AllowSelfReported`; a release gate or a missing admission yields `evidence.self_reported_not_admitted`. An unknown producer kind yields `evidence.invalid`.
 
-### Release selection
+#### Release selection
 
 A gate whose `Class` is anything other than `default` (the constant `release` included) or that sets `FullSelection: true` demands `selection.mode: full`. Evidence produced by a partial selection (for example a skip or subset run) is refused with `evidence.selection_partial`. Full selection is the only thing `FullSelection: true` adds: a default-class gate that sets it still accepts fully selected self-reported evidence when the operator policy set `AllowSelfReported`. Only a release-class gate (any `Class` other than `default`) refuses self-reported evidence regardless of operator policy.
 
-### Known limits
+#### Known limits
 
 - The gate reads the coordinator's own store; evidence read from a job's worktree proves nothing about who wrote the file.
 - A zero `Gate` (no repo, no revision, no policy digest, no required jobs) accepts nothing; callers must build a complete gate from protected policy.
 - Freshness depends on `Gate.Current`; a nil `Current` makes every document stale. The caller sets `Current` from the live checkout and input digests at the moment of judgment.
 
-## Signed evidence, revocation and the audit checkpoint
+### Signed evidence, revocation and the audit checkpoint
 
 A node that is signing eligible signs the evidence of every job it runs. The signature is Ed25519 with the node key over `nself-ci-evidence/v1`, a newline, and the canonical JSON of the document without its `signature` and `freshness` fields (numbers kept as written, fields a newer producer added stay in). The key id is `ci-node-` plus the first 16 hex characters of the sha256 of the public key. The coordinator accepts a `signed-remote` document only when all of these hold; otherwise the gate sees `evidence.signature_unverifiable` and the log gets an `E686` reason:
 
@@ -477,7 +466,7 @@ nself ci serve admin audit checkpoint verify --pubkey <fingerprint> <path> [--js
 
 Handoff for later Tickets: the coordinator calls `run.UseAttestStore(st)` at start (the first attempt also sets it), a node revocation calls `run.RevokeNode`, and the coordinator that receives a result frame builds the signed-remote document with `producer.kind: signed-remote` and `signature: {kind: runner-ed25519, key_id, value}` from the frame; the agent signs the document it sends, so that document must already carry `attempt.id`, `job`, the real `repo_id`, `run_id`, `source_trust`, `policy_digest` and checks for its own job only. The lease carries those facts as its `evidence` context, read from the coordinator's record of the attempt, and the agent repeats them unchanged (the marker file and the revoke caller are unwired: D-1300).
 
-## Policy sources and `nself ci policy`
+### Policy sources and `nself ci policy`
 
 The effective policy of a repository is merged from, loosest first: the defaults, your operator rows (scopes `user`, `team`, `project`, kept in the CI store), the protected default branch's `.nself/ci.yaml` `policy:` block read at the fetched `origin/<default>` tip (or at an admin pin), the checked-out revision's own `policy:` block, and the flags of one run. Every later scope can only tighten. A widening in the revision, and any Spend key (`economics.*`, `burst.*`) in the branch or the revision, is ignored and listed. A `policy:` block in a pull request therefore never loosens anything.
 
@@ -493,11 +482,11 @@ nself ci policy pin <sha> | --clear [--json]
 - `pin <sha>` fixes the protected-branch commit the policy is read at. It accepts only a full commit id reachable from the fetched `origin/<default>` (else `E672`); `--clear` returns to the tip.
 - Every `set`, `unset`, `pin` and `--clear` needs the `admin` role (the local operator of a PERSONAL coordinator has it) and writes its policy row and one `policy.*` audit row in one transaction: both land or neither does. The role check itself writes its own `authorize` row first, so a successful write leaves two rows and a refused one leaves only the `authorize` row (`policy.refused` for a machine-invoked refusal). The audit row names the scope, the quoted subject, the key, a short digest and the new value; a Secret key's value is never written.
 
-### Machine-invoked callers cannot loosen trust policy
+#### Machine-invoked callers cannot loosen trust policy
 
 When `NSELF_INVOKED_BY` is set (the MCP and HTTP invokers always set it; you can export it for an agent that uses the CLI), `set`, `unset` and `pin` refuse, with `E687` reason `machine_invoked`, any write that loosens a `trust.*` key: raising `trust.machine_invoked_cap`, unsetting any `trust.*` key, and every `pin` or `--clear`. The refusal writes nothing to the policy and one `policy.refused` audit row. Lowering a trust key (`trust.machine_invoked_cap` from `owner` to `untrusted`) works, and so do keys outside `trust.*`. A first value for a `trust.*` list key that has no default (`trust.providers`, `trust.self_reported_gates`) counts as loosening, because an unset list means none allowed. With the variable unset the operator's writes work as before. This guard is advisory against an agent that controls its own environment, which can simply unset the variable; the plan also marks the three write commands `cli-only` on the MCP and HTTP surfaces (P7-CI-62) so a remote caller cannot reach them at all; that mapping is not part of this command.
 
-### Known limits
+#### Known limits
 
 - A `team` row applies to every run, plan and dispatch of the process whose environment sets `NSELF_CI_TEAM=<team id>` (the coordinator's own environment, never a job's env or a repository file; same alphabet as `--team`). A malformed value fails the resolve with `E672` rather than dropping the team's rows; `show --team <id>` overrides it. With the variable unset no team row applies.
 - `pin` needs a fetched origin; with no origin there is nothing to pin against.
@@ -535,3 +524,184 @@ on exit or a handled signal. An uncatchable SIGKILL or host crash can leave a
 temporary directory for the host's normal temporary-file cleanup; container
 scratch lives on the attempt's temporary filesystem. No `.nself-ci` directory is
 created in the project by preparation.
+
+### Machine-invoked runs
+
+An agent that starts CI (an MCP tool, an HTTP caller or a CLI agent) is a machine-invoked caller. The MCP and HTTP invokers set `NSELF_INVOKED_BY` themselves. For a CLI agent, export it. The run's source trust class is then capped by the policy key `trust.machine_invoked_cap` (default `owner`, no cap), with the reason `source.machine_invoked_cap`.
+
+For unattended agents, set the cap to `untrusted`. Lowering the cap always works:
+
+```bash
+nself ci policy set --scope user trust.machine_invoked_cap untrusted
+```
+
+Observed on a fresh store, a machine-invoked caller then cannot raise it again:
+
+```
+$ NSELF_INVOKED_BY=agent nself ci policy set --scope user trust.machine_invoked_cap owner
+E687: a machine-invoked caller (NSELF_INVOKED_BY) cannot loosen trust policy: set user/trust.machine_invoked_cap (machine_invoked)
+```
+
+The cap is applied where the run is classified. A `--coordinator` submission from a machine-invoked process is classified on the TEAM coordinator, where the cap of the coordinator's own policy applies. The submit API carries no invoked-by claim the coordinator could trust, so the caller's cap does not travel with the submission. For a CLI agent the cap is advisory, because the agent controls its own environment (residual risk 9).
+
+### Coordinator host
+
+A PERSONAL coordinator runs as you, on your machine, and starts only `owner` and `internal` work. A TEAM coordinator holds the queue, the store, the certificate authority and the audit log. It holds secret references and never values.
+
+Two-box advice: do not run a TEAM coordinator on the same box as a node that runs untrusted code. A compromised job on that box would sit next to the store and the keys. In team mode the coordinator's own host needs the `vm` floor (`boundary.coordinator_host`); a host that cannot give it is refused. Put the coordinator on its own small host and add nodes separately.
+
+### macOS nodes
+
+| Node | Layout | Eligible for | Notes |
+|---|---|---|---|
+| System install (`nself ci nodes add user@mac --system`) | Hidden agent user, one hidden job user per slot, a LaunchDaemon, a root-owned uninstall copy | Separated layout; secrets and signing eligible; TEAM eligible | Recorded as separated only once D-1230 closes. Until then the node is recorded not UID-separated and the agent does not yet run jobs through the job shim |
+| User mode | The agent runs as your own user | The I17 exception only: owner work from a PERSONAL coordinator, no secrets, never signing | A TEAM coordinator refuses it (`isolation.uid_separation`, `E657`) |
+
+For a system install the ssh user needs passwordless sudo, and the Xcode license must be accepted first (`sudo xcodebuild -license accept`). Remove the node with the root-owned copy: `sudo /Library/PrivilegedHelperTools/org.nself.ci-agent uninstall --system`. The `vm` level uses Tart and is limited by Apple to two VMs at once on one Mac.
+
+## Public FOSS PRs
+
+A pull request from a stranger is the hardest case. The defaults treat it as hostile.
+
+**Defaults.**
+
+- A fork PR is `untrusted`. So is any run whose head repository is not this repository, any `[bot]`, Dependabot or Renovate author, any diff that touches only lockfiles, and any run whose head moved after the delivery.
+- An untrusted job gets no secrets, no `lan` or `privileged` network, and no trusted cache or artifact namespace.
+- Its isolation minimum is `sandboxed-container` on a runner with no route to your LAN, or a disposable hosted runner. The `container` level is never the minimum.
+- A first-time contributor's run waits for an approval.
+
+**Approvals.** `nself ci runs pending` lists held runs. `nself ci runs approve <run> --sha <head>` approves one. The approver needs `release` or `admin` and must not be the author. An approval binds the run, the head SHA, the config digest and the head repository, and any change voids it. Details are in [Run approvals](#run-approvals).
+
+**Setup without hosted capacity.** Use a Linux node with `runsc` that has no LAN route. Check it:
+
+```
+nself ci doctor        # isolation.sandboxed-container verified <date> on linux/amd64
+```
+
+If no such node exists, the PR run waits (`E678`) and never falls back to the container level. That wait is the safe answer.
+
+**Setup with hosted capacity.** The repository's visibility must come from the forge API as `public`. The project must be authorized for the provider (`nself ci providers authorize <id> --project <repository path>`), and the privacy zone must allow a send (see [Privacy](#privacy)). Hosted runs get no secret classes, and their evidence stays `self-reported`. A hosted runner on a public repository is the provider's isolation, not yours.
+
+**Do not** point a persistent runner that holds your secrets or sits on your LAN at a public repository. The github-runner plugin refuses a runner group that is open to public repositories for that reason.
+
+## Secrets
+
+A job asks for secrets by reference, never by value: `secrets: [project/NPM_TOKEN, release/ANDROID_KEYSTORE_PASSWORD, environment/staging/API_KEY, deploy/prod/DEPLOY_KEY, team/SHARED_TOKEN]`. The part after the last slash is the environment variable the job sees, and two refs may not use the same variable (`E674`). Names that would change how a process or the docker client runs (`PATH`, `HOME`, `DOCKER_*`, `LD_*`, `DYLD_*`, `GIT_*`, `NSELF_CI_*` and similar) are refused too.
+
+| Class | Store file (`.secrets/`) | Who may get it |
+|---|---|---|
+| `project` | `ci.age` | trusted jobs on an eligible runner |
+| `environment/<env>` | `ci-<env>.age` | trusted jobs on an eligible runner |
+| `release` | `release.age` | `internal` or `owner` jobs on a dedicated-trusted node or a VM |
+| `deploy/<env>` | `<env>.age` | same as `release` |
+| `team` | the node's own team store | trusted jobs on an eligible runner; node-local, never granted with `nodes secrets grant` |
+
+How it works:
+
+- Refs are checked first: trust class of the job, the runner's facts, the runner's declared secret classes and the policy's `trust.secrets` allowlist. A refusal (`E677`) names the reasons and makes no resolver call. Untrusted jobs never get a secret.
+- Values come from one place: `nself config secrets resolve`, run on the node that executes the job. A TEAM coordinator passes references only and never holds a value. Only a PERSONAL coordinator over the SSH carrier to your own node may send a `project` or `environment` value.
+- On an agent node the resolver runs with `SECRETS_AGE_KEY_PATH` set to that node's own age identity, so the node decrypts only the files you granted to it: `nself ci nodes secrets grant <node> --class project` (also `environment/<env>`, `release`, `deploy/<env>`). `release` and `deploy` files go only to a dedicated-trusted node. A node whose registry entry has `secrets_eligible: false` (jobs could read its age key) is refused with `E677`. `revoke` always works; it does not unsee plaintext the node already read, so rotate the value afterwards.
+- Delivery is by environment only: the process environment, `docker run -e NAME` with the value in the docker CLI's own environment (never in argv), or `export` lines on the SSH stdin of a Tart VM. No file, URL, cache key, artifact or log ever holds a value.
+- Every value is registered with the output redactor before the job starts. If the installed redactor is the pass-through default, or a value cannot be registered (the redactor refuses one shorter than 6 bytes with `E673`), nothing is injected and the attempt fails (`E676`) before it starts. Buffers are zeroed when the attempt ends, whether it passed, failed, was cancelled or lost.
+- No `nself config secrets resolve` in the installed CLI: the job fails before it starts with `E675`.
+
+Limits: only the byte buffers the Source owns are zeroed. Copies in Go strings (the job environment slice handed to the process, the redaction registry, the legacy-environment read) stay in the nself-ci process until it exits, and a failed availability probe is remembered until it restarts. Values live in process memory and the job's environment for the attempt. For container jobs dockerd also keeps `-e` values in the container configuration until the container is removed (`--rm` and the hygiene sweep remove it). `/proc/<pid>/environ` is readable only by that attempt's own job user.
+
+Android release builds: until `release.age` holds the keystore secrets, `ANDROID_KEYSTORE_BASE64`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS` and `ANDROID_KEY_PASSWORD` in your own environment still work, on your own machine only. One audit row (`secret.legacy_env`, value-free) is written first; if it cannot be written the legacy value is not used. The `legacy-env` label is kept on the Source and is not yet copied into run evidence. A remote node never uses this path.
+
+A node granted a `release` or `deploy` file must be dedicated-trusted (operator-owned, assigned trust, accepts only `owner`, one authorized project); `nodes secrets grant` does not yet check that the project is the one the file belongs to, so grant these files only to a node dedicated to that project. Multi-line values (PEM keys) need the baseline container path today; the hardened path refuses them.
+
+## Privacy
+
+**Zones.** The policy key `trust.privacy_zone` decides what may leave your machine. From strictest to loosest:
+
+| Zone | What may leave the machine |
+|---|---|
+| `local-only` | Nothing. The job runs only on your own PERSONAL node (`privacy.local_only` otherwise) |
+| `private-infrastructure` | Nothing to a hosted provider. Your own nodes only. This is the default when no zone is set |
+| `provider-allowlist` | The job and its source go to a hosted provider only if that provider is listed in `trust.providers` (`privacy.provider_not_allowlisted` otherwise) |
+| `hosted-allowed` | Any provider you authorized for the project |
+
+A hosted send needs two things: the project is authorized for the provider (an admin runs `nself ci providers authorize`), and the zone allows it. A public repository's untrusted job can go to hosted capacity without a project authorization; a private repository cannot. `authorize --allow-private` writes the zone first and prints the ceiling command for you to review. It does not run it.
+
+**What leaves the machine, per zone.** A hosted send carries the source of the revision and the job's command, environment (no secret values) and artifacts. The provider sees all of it. nSelf cannot verify what a provider does with it (residual risk 11). Under `local-only` and `private-infrastructure` nothing goes to a provider, but a commit status post goes to your forge unless you pass `--no-status`.
+
+**Lifecycle.** Run records, evidence and logs live in the CI store on the coordinator's disk, under the CI home of the operator. They stay in that store. A secret value is not stored when the redactor recognises it: logs go through the redactor and values are registered before the job starts. See residual risk 8 (redaction limits).
+
+**Publication profile.** A release publishes only what you ask it to: signed artifacts and their evidence, from `nself ci artifacts sign`. Publication is deterministic and repeatable. See [Cache and artifacts](Cache-and-Artifacts.md).
+
+**No telemetry.** The engine has no usage-reporting call to any nSelf service. The `nself.org` URLs in the code are identifiers in schemas and provenance statements, not endpoints it contacts. The only network calls are to the forge and providers you configured, and the registry and toolchain pulls you ask for.
+
+## Isolation last-verified
+
+Each level below lists the host it needs and the source of its last-verified date. A level that worked once may not work today, because a runtime update or a kernel change can end it silently. So `nself ci doctor` shows, for each level, the date a passing check last proved it on this machine.
+
+Observed on a macOS machine that never ran the drill:
+
+```
+$ nself ci doctor
+PASS isolation.container unverified since never
+PASS isolation.hygiene unverified since never
+PASS isolation.network unverified since never
+PASS isolation.sandboxed-container unverified since never
+PASS isolation.vm unverified since never
+```
+
+```
+nself ci doctor            # lines isolation.container ... isolation.vm
+nself ci doctor --json     # each of those checks has "verified_at": an RFC 3339 time, or null
+```
+
+| Level | Host requirement | Reads | How it is proven |
+|---|---|---|---|
+| `isolation.container` | Docker or Podman, cgroup limits | `verified <date> on <host class>` or `unverified since never` | the container integration tests |
+| `isolation.sandboxed-container` | Linux with `runsc` | same | the gVisor integration tests (needs `runsc`) |
+| `isolation.network` | Docker or Podman, Linux | same | the network scope integration tests |
+| `isolation.hygiene` | Linux | same | the workspace hygiene integration tests (Linux) |
+| `isolation.vm` | Apple-silicon Mac with Tart | same on an Apple-silicon Mac; on Linux `unavailable (no KVM host, D-0120)` | the Tart tests (needs Tart and its test image) |
+| `isolation.ephemeral-vm` | Apple-silicon Mac with Tart | Linux only: `unavailable (no KVM host, D-0120)` | not provable on Linux |
+
+The host class is the platform of the machine that ran the check, for example `linux/amd64`.
+
+**Where the date comes from.** The `isolation-levels` drill (`scripts/drill/isolation-levels/run`, job `drill-isolation-levels` of the `drills` pipeline) runs the integration tests of every level the host can run and records one check per level. Doctor reads the stored evidence of those runs and reports the newest passing check of each level. Doctor never writes. A level with no passing check reads `unverified since never`; that is the honest state of a machine that never ran the drill, so it is not a warning.
+
+**Run it.**
+
+```
+nself ci --pipeline drills --job drill-isolation-levels
+scripts/drill/isolation-levels/run          # same, started directly; NSELF_CI_BIN and NSELF_CI_HOME choose the binary and the store
+```
+
+A level whose prerequisite the host lacks (no running Docker or Podman, no `runsc`, no Tart) ends `error` with `reason: prerequisite.missing` in its excerpt. That is never a pass and never changes the last-verified date. A level that does not exist on the host class (for example `vm` on Linux) gets no check. `ISOLATION_DRILL_LEVELS=container,network` narrows the run to those levels. The drill runs real containers; give its job more than the default 10 minutes with a `drill-isolation-levels` job in `.nself/ci.yaml` if the host is slow. `scripts/drill/isolation-levels/selftest.sh` checks the drill script itself against fake tools.
+
+### Handoff
+
+- Stored evidence keeps each nested check only on the drill check's excerpt: the last line, `passed: <ids>`, lists the nested checks that passed (internal/drill writes it, `store.LastVerified` reads it). A format change must change both; a test pins them together.
+- The linux `ci-isolation-linux.yml` pull-request job runs the drill against a throwaway store and fails unless doctor shows a non-null `verified_at` for `isolation.container`, `isolation.sandboxed-container` and `isolation.network`.
+
+## Whether each level can run now
+
+`nself ci doctor` also probes every isolation profile and prints one `isolation.<level>.availability` line per level (`isolation.container.availability`, `isolation.sandboxed-container.availability`, `isolation.vm.availability`, `isolation.ephemeral-vm.availability`). Each reads `available (<level>)` or `unavailable: <reason>`, such as `isolation.runtime_missing`, `isolation.tart_base_image` or `isolation.tart_no_free_slot`.
+
+For an unavailable level the line carries the fix as its `remediation` (the install steps: Tart from `brew install cirruslabs/cli/tart`, gVisor from its install page then `sudo runsc install`) and prints the profile facts under it. For Tart the facts are `tart_version`, `base_image`, `base_image_cached`, `free_slots`, `running_vms`, `softnet_block` and `licence_note`: Tart and softnet are third-party tools under their own licences, you install them, nSelf neither bundles nor redistributes them. An unavailable level is not a failure: these lines always pass, because a host without Tart or gVisor is a normal state.
+
+## Residual risks
+
+These risks stay after every control above is built. They are repeated here from the threat model so you can judge them.
+
+1. **A container is not a boundary for hostile code.** The `container` level protects against mistakes and trusted-code accidents. Untrusted work never runs at that level.
+2. **No Linux microVM.** Linux `vm` and `ephemeral-vm` report `unavailable` because no KVM host exists for nSelf to use (D-0120). Untrusted work runs under gVisor or on hosted-disposable. Linux release jobs use a dedicated trusted runner.
+3. **gVisor residuals.** The host kernel is shared through the Sentry's seccomp-filtered syscall set. There is no protection against side channels (Spectre-class, cache timing). `runsc` has its own CVEs. Resource exhaustion beyond cgroup limits is possible. gVisor is not a VM.
+4. **The I17 exception.** An owner `process`-level job from the operator's own PERSONAL coordinator runs under the operator's UID on a non-separated node whose key is `signing_eligible` false and to which TEAM coordinators never lease. The same exception covers a user-mode macOS node. A `--trust owner` override on hostile code lets that job read the PERSONAL coordinator's store and CA key. The node can neither sign evidence nor receive secret classes.
+5. **dockerd keeps `-e` values until the container is removed.** `--rm` and the hygiene sweep remove it. Anyone with Docker access on the node can read the value until then.
+6. **Runner credential.** The job shares the runner's container and user and can read the runner's own JIT config, which admits only this one job. For GitLab the token stays valid until the runner is deleted, so the pause on the running job hook and the delete at job end are the controls.
+7. **Legacy `ci serve` until v1.6.** The frozen v1.4 engine keeps today's allowlisted-fork plain-docker behaviour until v1.6 (D-0119). The controls on this page run only in the V15 engine.
+8. **Redaction limits.** A value shorter than 6 bytes cannot be registered (the redactor refuses it with `E673`, and the attempt then fails with `E676` before it starts). An encoding the redactor does not list (compression, a split across lines, a derived hash) can pass. Redaction is the last defence. The first defence is that untrusted jobs never receive a value.
+9. **The machine-invoked cap is advisory for CLI agents.** An agent that uses the CLI controls its own environment, so `NSELF_INVOKED_BY` can be unset. The MCP and HTTP invoker always sets it.
+10. **Audit log in PERSONAL mode.** The chain detects edits that were not recomputed. PERSONAL has no off-host checkpoint, so a writer who recomputes the chain is not detected.
+11. **Hosted providers.** nSelf cannot verify a provider's isolation. Hosted evidence stays `self-reported`. A provider sees everything sent to it once the zone allows a send.
+12. **Tart.** If the installed Tart lacks the softnet block option, `vm` is `unavailable` for untrusted work.
+13. **In-stack runner decisions.** The forgejo plugin keeps the forge and loses its runner. github-runner stays, trusted-only, with isolation `process`, persistent, on the same host as the stack, and not for fork PRs. `GITHUB_RUNNER_ALLOW_PUBLIC_REPOS=true` is an unsafe opt-out that is logged on every start. The production check records what runs and changes nothing.
+14. **The operator's machine is the root of trust.** A compromised operator workstation defeats every control that lives there.
+15. **Watch host identity.** Whoever holds the forge token of a watch host's station identity writes statuses that count as trusted claims and results. The ledger cannot tell a stolen token from the host. Rotate the token and list `claims.trusted_creators` narrowly.
+16. **Authorized personal nodes.** When a person authorizes their own node for a team's private project, that node sees the project's code by design. The controls decide which node is chosen; they do not hide code from a node the project authorizes.
diff --git a/.github/wiki/guides/ci/Walkthrough-Agents.md b/.github/wiki/guides/ci/Walkthrough-Agents.md
new file mode 100644
index 000000000..256dfeb69
--- /dev/null
+++ b/.github/wiki/guides/ci/Walkthrough-Agents.md
@@ -0,0 +1,110 @@
+# Walkthrough: agents
+
+This page walks a coding agent through CI. The agent starts a run, waits for it, and reads the evidence. It can do this through the CLI, through MCP tools or through HTTP routes. All three return the same JSON.
+
+Commands that need a real run are shown as text, each with the test that runs it. The full list of MCP tools and HTTP routes, with each command's side effect and confirmation rule, is the generated machine-surface table at the top of the [CI plugin page](../../plugins/CI.md). The command and flag tables are in the generated [Reference](./Reference.md#commands).
+
+## The CLI loop
+
+Start the run in the background with `--detach --json`. The reply is one JSON document with the run id and the exact commands to wait for it, follow it, read its evidence, cancel it and read its logs.
+
+<!-- proven-by: TestDetach -->
+```text
+nself ci --detach --json
+```
+
+Wait for the result, then read the evidence. `runs wait` returns when the run ends; `--timeout` bounds the wait.
+
+<!-- proven-by: TestRunsWait -->
+```text
+nself ci runs wait <run-id> --json
+```
+
+<!-- proven-by: TestBareJSONIsOneEvidenceEnvelope -->
+```text
+nself ci evidence <run-id> --json
+```
+
+To watch progress instead of waiting, follow the run. Each line is one JSON event, and a reader that reconnects can resume from the last sequence number it saw.
+
+<!-- proven-by: TestFollowReplayFromSeq -->
+```text
+nself ci runs follow <run-id> --json
+```
+
+The document shapes are in [Evidence and Machine Output](./Evidence-and-Machine-Output.md).
+
+## The MCP loop
+
+Start the MCP server with `nself mcp` inside the project directory. The agent needs only three tools for the loop:
+
+1. `nself_ci` starts a run. Pass `{"args": ["--detach"]}`.
+2. `nself_ci_runs_wait` waits for it. Pass `{"args": ["<run-id>"]}`.
+3. `nself_ci_evidence` returns the evidence. Pass `{"args": ["<run-id>"]}`.
+
+Every other tool is listed in the machine-surface table. Commands that only make sense in a terminal, that stream, or that ask questions have no tool.
+
+## Confirmations
+
+A bare run executes code, so it needs a confirmation. The first `nself_ci` call does not run anything. It returns a request with a `confirm` value. The agent shows the request to its user and, once approved, calls `nself_ci` again with the same arguments plus that `confirm` value. Only the second call starts the run. Destructive commands, such as revoking a node, work the same way. The confirmation column of the machine-surface table says which commands need it.
+
+```text
+first call:  {"args": ["--detach"]}
+reply:       {"kind": "request", "confirm": "<64 hex characters>", ...}
+second call: {"args": ["--detach"], "confirm": "<the same value>"}
+```
+
+## The HTTP routes
+
+`nself admin serve` exposes the same commands as HTTP routes under `/v1/commands/`, for example `/v1/commands/ci/runs/wait`. Send a POST with a bearer token and a JSON body such as `{"args": ["<run-id>"]}`. The reply carries the same data as the CLI's `--json` output. Confirmations use the same `confirm` round trip.
+
+`runs follow` has no MCP tool. Over HTTP, `/v1/commands/ci/runs/follow` answers with an NDJSON stream: one JSON event per line, flushed as the run moves.
+
+## One server per project
+
+An MCP or HTTP server works on the project directory it was started in. Start one server per project, each from its own checkout.
+
+## No commit status from agents by default
+
+A run started through MCP or HTTP is a machine-invoked run: the server marks it with `NSELF_INVOKED_BY`. A CLI agent should export that variable itself. A machine-invoked run posts no commit status, and prints one line saying so. Add `--post-status` when the agent's result should count as the commit's status.
+
+<!-- proven-by: TestMachineDefaults -->
+```text
+nself ci --detach --json --post-status
+```
+
+## Capping the trust of agent runs
+
+The policy key `trust.machine_invoked_cap` caps the source trust class of every machine-invoked run. The default is `owner`, which is no cap. For agents that run unattended, set it to `untrusted`. A machine-invoked caller can lower the cap but never raise it again.
+
+<!-- proven-by: TestPolicyMachineInvokedCap -->
+```text
+nself ci policy set --scope user trust.machine_invoked_cap untrusted
+```
+
+For a CLI agent the cap is advisory, because the agent controls its own environment. See [machine-invoked runs](./Trust-Security-and-Privacy.md#machine-invoked-runs).
+
+## Code an agent wrote
+
+Run code that an agent wrote, and that nobody has read yet, as untrusted. `--trust untrusted` needs the sandboxed container level; it never falls back to a weaker level, never gets service containers and never gets internet access. If the host cannot provide the sandbox, nothing runs.
+
+<!-- proven-by: TestResolveLevelAndNetwork -->
+```text
+nself ci --trust untrusted --detach --json -- go test ./...
+```
+
+The isolation levels are in [Trust, Security and Privacy](./Trust-Security-and-Privacy.md#the-sandboxed-container-level-gvisor).
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Detached run and the handle's commands | `TestDetach` |
+| Detached run outlives its parent | `TestDetachSurvivesParent` |
+| Wait for a run | `TestRunsWait` |
+| Evidence as one JSON document | `TestBareJSONIsOneEvidenceEnvelope` |
+| Follow replays from a sequence number | `TestFollowReplayFromSeq` |
+| MCP tools, HTTP routes, same output on CLI, MCP and HTTP, confirmation round trip | `scripts/ci/ci-machine-surface.sh` |
+| No status from machine-invoked runs unless `--post-status` | `TestMachineDefaults` |
+| Trust cap key, lower but never raise | `TestPolicyMachineInvokedCap` |
+| `--trust untrusted` needs the sandbox | `TestResolveLevelAndNetwork` |
diff --git a/.github/wiki/guides/ci/Walkthrough-Home-Lab.md b/.github/wiki/guides/ci/Walkthrough-Home-Lab.md
new file mode 100644
index 000000000..6f649fbcd
--- /dev/null
+++ b/.github/wiki/guides/ci/Walkthrough-Home-Lab.md
@@ -0,0 +1,151 @@
+# Walkthrough: a home lab
+
+This page walks one real setup from start to finish: a Mac Studio on your desk runs the coordinator, two Mac Minis on the same LAN run jobs, and a small VPS you rent runs Linux jobs. Everything here is personal mode: you are the only person with access.
+
+The page shows the order of steps and links the guide that explains each one. Commands that need real machines are shown as text, each with the test that runs it. The tables of commands, flags, codes and doctor checks live in the generated [Reference](./Reference.md#commands).
+
+Names used below: `desk` is the Mac Studio, `mini1` and `mini2` are the Minis, `vps1` is the VPS at `203.0.113.20`. Replace them with your own.
+
+## The desk Mac runs the coordinator
+
+The coordinator keeps the run store, the node registry and the keys. In personal mode it starts with no extra flag. Its webhook and user API listeners stay on loopback by default; only the agent listener needs to be reachable from the Minis. The listener ports are described in [Nodes and Runners](./Nodes-and-Runners.md#team).
+
+<!-- proven-by: TestServeModeFlagAndStart -->
+```text
+nself ci serve
+```
+
+A coordinator started without `--team` stays personal. Do not add `--team` here: the switch is permanent for that data directory, and a home lab used by one person does not need it.
+
+## Adding the Minis
+
+There are two ways to add a Mac. Use `nodes add --system` when you can reach the Mini over SSH. Use pairing when you cannot, or when you do not want the coordinator to hold an SSH key for it.
+
+**Add over SSH.** `--system` installs the agent as a system service: a hidden agent user, one job user per slot, and a LaunchDaemon that runs the agent in pull mode. Get the host-key fingerprint from the Mini itself, not from the network.
+
+<!-- proven-by: TestMacOSNode -->
+```text
+nself ci nodes add ci@mini1 --system --slots 2 --host-key <fingerprint> --agent-binary <path-to-nself-ci-agent> --project <owner/repo> --name mini1 --json
+```
+
+The bootstrap checks every account and folder it creates. Until jobs actually run through the job shim, the node is recorded as not UID-separated, and installing it grants no secret or signing rights. See [provisioning versus bootstrap](./Nodes-and-Runners.md#vps).
+
+**Pair instead.** Run `nodes pair` on the desk Mac. It opens a short window and prints a `nself-ci-agent join` command, the coordinator fingerprint and a one-use code. Run the printed join command on the Mini, type the code there, and check that both fingerprints match before you approve.
+
+<!-- proven-by: TestNodesPairEndToEnd -->
+```text
+nself ci nodes pair --label mini2 --agent-url https://desk.example:3864 --cert-ttl 30m
+```
+
+A paired Mini runs the same agent in pull mode: it only makes outbound connections to the coordinator. Never put the pairing code in a command line or a shared log.
+
+## Labels: which jobs may run where
+
+Give each node the labels your jobs ask for. The Minis have Xcode, so they get the `xcode` label.
+
+<!-- proven-by: TestSeveralProjects -->
+```text
+nself ci nodes label mini1 xcode
+nself ci nodes label mini2 xcode
+```
+
+A job that needs Xcode says so in `.nself/ci.yaml`. A runner is eligible only when it has every label the job asks for:
+
+```yaml
+jobs:
+  ios:
+    kind: test
+    run: [xcodebuild, test]
+    requires: {labels: [xcode]}
+```
+
+Check where each job would go before you push. `plan` shows the placement; `explain` lists every runner that was not chosen and why.
+
+<!-- proven-by: TestPlanPlacementJSON -->
+```text
+nself ci plan --json
+```
+
+<!-- proven-by: TestScenario6ExplainListsEveryAlternative -->
+```text
+nself ci explain
+```
+
+The reasons (`labels.mismatch`, `tools.missing` and others) are listed in [Scheduling and Cost](./Scheduling-and-Cost.md#job-requirements-and-labels) and in the [reason table](./Reference.md#reason-codes).
+
+## Reservations on the desk machine
+
+If the desk Mac also takes jobs, keep part of it for yourself. Reservations are scheduler limits: CI work never uses the reserved CPU or memory. `--interactive protect` holds new work back while you are using the machine. `--on-battery` matters only for laptops; a desk machine can leave it at `allow`.
+
+<!-- proven-by: TestNodesSetFlagsMayFollowOrPrecedeTheNodeAndKeepWhatIsNotGiven -->
+```text
+nself ci nodes set desk --reserve-cpu 2 --on-battery allow
+nself ci nodes set desk --reserve-mem 2048
+```
+
+A reservation that would leave nothing for CI is refused. More controls are in [Nodes and Runners](./Nodes-and-Runners.md#lan).
+
+## The personal VPS
+
+A VPS is added the same way as a Mini, with its host key pinned. The SSH carrier forces strict host-key checking against the coordinator's own pin file, so a changed key stops the connection before any job runs. Connect as root or a user with passwordless sudo so `--system` can create the agent and job users.
+
+<!-- proven-by: TestSystemInstallBootstrapsAndKeepsTheNodeUnseparated -->
+```text
+nself ci nodes add root@203.0.113.20 --system --slots 3 --host-key <fingerprint> --agent-binary <path-to-nself-ci-agent> --json
+```
+
+Never add a machine that serves your deployed apps. Deploy hosts are not eligible for CI; see [deploy hosts are ineligible](./Nodes-and-Runners.md#vps).
+
+## Secrets on a node
+
+A node gets no project secrets until you grant them. Grant the `project` class to the VPS if its jobs need project secrets. The `release` class needs a node dedicated to releases.
+
+<!-- proven-by: TestGrantProjectCallsCliAndAudits -->
+```text
+nself ci nodes secrets grant vps1 --class project
+```
+
+Every grant and revoke is written to the audit log. The secret rules are in [Trust, Security and Privacy](./Trust-Security-and-Privacy.md#secrets).
+
+## When a Mini sleeps
+
+A sleeping or frozen Mini stops renewing its lease. It fences itself before the coordinator's lease expires, so it cannot finish the old job late. The coordinator marks the attempt lost and runs it again on another eligible node. If the Mini wakes and reports the old result, that result is refused. A job that failed on its own merits is not retried.
+
+Mark machines that sleep on purpose as intermittent so the scheduler prefers always-on nodes:
+
+<!-- proven-by: TestNodesSetJSONEnvelopeCarriesTheStoredSettings -->
+```text
+nself ci nodes set mini2 --reserve-mem 1024 --persistence intermittent --json
+```
+
+Lost leases and what to check are covered in [Troubleshooting](./Nodes-and-Runners.md#troubleshooting).
+
+## Backing up the coordinator
+
+Back up the desk Mac's data directory to a file. The archive does not contain the key-encryption key (KEK). Keep the KEK somewhere else; without it the archive cannot be restored, and a wrong KEK is refused before anything is written.
+
+<!-- proven-by: TestBackupRestoreCommandsRoundTrip -->
+```text
+nself ci serve backup --data-dir <coordinator-data-dir> --out <archive> --json
+nself ci serve restore --data-dir <new-data-dir> --in <archive> --kek <saved-kek-file> --json
+```
+
+Stop the coordinator before a restore. What restore keeps and resets is in [backup/restore and the KEK](./Nodes-and-Runners.md#team).
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Personal coordinator start, no `--team` | `TestServeModeFlagAndStart` |
+| Add a Mac with `--system` (LaunchDaemon, users, layout) | `TestMacOSNode` |
+| Pair a node and run the printed join | `TestNodesPairEndToEnd` |
+| Labels and the placement they cause | `TestSeveralProjects` |
+| Placement plan in JSON | `TestPlanPlacementJSON` |
+| Every alternative explained | `TestScenario6ExplainListsEveryAlternative` |
+| Reservations and battery policy | `TestNodesSetFlagsMayFollowOrPrecedeTheNodeAndKeepWhatIsNotGiven` |
+| Add a Linux VPS with `--system` | `TestSystemInstallBootstrapsAndKeepsTheNodeUnseparated` |
+| Grant project secrets to a node | `TestGrantProjectCallsCliAndAudits` |
+| Release secrets need a dedicated node | `TestGrantReleaseNeedsDedicatedNode` |
+| A frozen node fences and the job runs elsewhere | `TestFaultScenario9Freeze` |
+| Intermittent node setting | `TestNodesSetJSONEnvelopeCarriesTheStoredSettings` |
+| Backup and restore with the KEK | `TestBackupRestoreCommandsRoundTrip` |
diff --git a/.github/wiki/guides/ci/Walkthrough-Multiple-Projects.md b/.github/wiki/guides/ci/Walkthrough-Multiple-Projects.md
new file mode 100644
index 000000000..bb8e4aa9c
--- /dev/null
+++ b/.github/wiki/guides/ci/Walkthrough-Multiple-Projects.md
@@ -0,0 +1,95 @@
+# Walkthrough: several projects on one fleet
+
+This page walks one fleet that serves two projects. Project A and project B share a Mac and a VPS. A second VPS belongs to project A only. Every project keeps its own queue share, cache and statistics.
+
+Names used below: `mac1` has Xcode, `vps-shared` serves both projects, `vps-a` serves project A only. `~/src/project-a` and `~/src/project-b` are the two checkouts. Commands that need real machines are shown as text, each with the test that runs it. The command and flag tables are in the generated [Reference](./Reference.md#commands).
+
+## One pool for several projects
+
+A node runs jobs only for the projects it is authorized for. Authorize by checkout directory or by repository id; a directory is turned into the same repository id that evidence uses.
+
+<!-- proven-by: TestSeveralProjects -->
+```text
+nself ci nodes projects add mac1 ~/src/project-a ~/src/project-b
+nself ci nodes projects add vps-shared ~/src/project-a ~/src/project-b
+nself ci nodes projects list vps-shared
+```
+
+To take a project off a node, remove it. `--all` removes every project from that node.
+
+<!-- proven-by: TestSeveralProjects -->
+```text
+nself ci nodes projects remove vps-shared <repo-id>
+```
+
+## A VPS for one project
+
+Authorize the dedicated VPS for project A only. Project B's jobs never land there, even when it is idle.
+
+<!-- proven-by: TestSeveralProjects -->
+```text
+nself ci nodes projects add vps-a ~/src/project-a
+nself ci nodes projects list vps-a
+```
+
+A personal node is never chosen for a private repository it is not authorized for. Adding the project makes it eligible.
+
+## Pinning a project with labels
+
+Labels describe a node; a project can require extra labels for all its jobs. Give `vps-a` a label, then require that label at project scope for project A. Project A's jobs then need it on top of their own `requires.labels`.
+
+<!-- proven-by: TestSeveralProjects -->
+```text
+nself ci nodes label mac1 xcode
+nself ci nodes label vps-a project=a
+nself ci policy set --scope project sched.overrides.labels '["project=a"]'
+```
+
+Run the `policy set` line inside project A's checkout. After it, all of A's jobs go to `vps-a`. A job of A that also needs `xcode` waits: `mac1` has Xcode but not `project=a`, and `vps-a` has the reverse. `explain` names the override as the reason.
+
+<!-- proven-by: TestScenario6ExplainListsEveryAlternative -->
+```text
+nself ci explain
+```
+
+How overrides combine with job requirements is in [Scheduling and Cost](./Scheduling-and-Cost.md#overrides).
+
+## Fairness and the queue
+
+When the fleet is busy, the scheduler shares capacity between projects and never admits more than the fleet can hold. Interactive runs start before queued background work. `runs queue` shows each waiting run with its position, its band and the expected wait.
+
+<!-- proven-by: TestRunsQueueListsPositionBandAndWait -->
+```text
+nself ci runs queue
+```
+
+The fairness rules and presets are in [Scheduling and Cost](./Scheduling-and-Cost.md#how-a-runner-is-chosen).
+
+## Cache and artifacts stay separate
+
+Each cache entry lives in a namespace made of the project, the trust class of the source and whether the ref is protected. The same key in another project's namespace neither blocks nor reveals the entry. Artifacts are stored per run, and runs belong to one project. Nothing needs to be set up for this. See [namespaces](./Cache-and-Artifacts.md#namespaces-per-trust-and-per-pr).
+
+## Statistics per project
+
+`runs stats` summarises runs, queue time and failures. `--project` limits it to one project; `--since` sets the window. A caller of a team coordinator sees only the projects it has a role on.
+
+<!-- proven-by: TestStatsReadWindowAndProject -->
+```text
+nself ci runs stats --since 168h --project <owner/repo> --json
+```
+
+The fields are described in [CI health](./Scheduling-and-Cost.md#ci-health).
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Authorize, list and remove projects on a node; per-project VPS; label override | `TestSeveralProjects` |
+| A personal node needs authorization for a private repo | `TestPersonalNodePrivateRepoOptIn` |
+| Every alternative explained | `TestScenario6ExplainListsEveryAlternative` |
+| Fair share under saturation | `TestScenario10SaturationStaysWithinCapacityAndFair` |
+| Interactive before background | `TestScenario10InteractiveStartsBeforeQueuedBackground` |
+| Queue position, band and wait | `TestRunsQueueListsPositionBandAndWait` |
+| Cache namespaces do not leak | `TestSameKeyStringInAnotherNamespaceNeitherBlocksNorRevealsTheTrustedEntry` |
+| Stats window and project filter | `TestStatsReadWindowAndProject` |
+| Stats scoped to the caller's projects | `TestStatsScopedCallerSeesOnlyAllowedProjects` |
diff --git a/.github/wiki/guides/ci/Walkthrough-Team.md b/.github/wiki/guides/ci/Walkthrough-Team.md
new file mode 100644
index 000000000..8f8f86937
--- /dev/null
+++ b/.github/wiki/guides/ci/Walkthrough-Team.md
@@ -0,0 +1,127 @@
+# Walkthrough: a team
+
+This page walks a small team that shares CI. One box runs the team coordinator. Two other boxes run jobs. Members submit runs and read results from their own machines. Each member may also keep personal nodes at home.
+
+Names used below: `ci.example` is the coordinator box, `runner1` and `runner2` are the job boxes, `example-org/example-repo` is a team repository. Commands that need real machines are shown as text, each with the test that runs it. The command and flag tables are in the generated [Reference](./Reference.md#commands).
+
+## A team coordinator on its own box
+
+Start the coordinator with `--team` as soon as anyone besides you will hold a role, a token or a certificate. The switch is permanent and audited; starting the same data directory without the flag later does not make it personal again.
+
+<!-- proven-by: TestServeModeFlagAndStart -->
+```text
+nself ci serve --team
+```
+
+Pick the box with care:
+
+- Never a production box. A machine that serves deployed apps is refused as a CI node; keep the coordinator and its keys off it as well.
+- Keep jobs off the coordinator. In team mode any job on the coordinator machine needs VM isolation or stronger. Two boxes are simpler: one keeps state and keys, the others run jobs.
+
+Add `runner1` and `runner2` from the coordinator box as described in [Nodes and Runners](./Nodes-and-Runners.md#lan). The coordinator-host rule is in [Coordinator host](./Trust-Security-and-Privacy.md#coordinator-host).
+
+## Roles and tokens
+
+Roles are `member`, `release` and `admin`, each for one or more projects. Grant a role to a person, or issue a scoped token for a machine. A token is shown once.
+
+<!-- proven-by: TestServeAdminRolesGrantListRevoke -->
+```text
+nself ci serve admin roles grant bob --role member --project example-org/example-repo --json
+nself ci serve admin roles list
+```
+
+<!-- proven-by: TestServeAdminTokenIssueOnce -->
+```text
+nself ci serve admin token issue build-bot --role release --project example-org/example-repo --ttl 48h --json
+```
+
+Revoking a role also ends that person's tokens. Every change is in the audit log. See [roles, tokens and the audit log](./Trust-Security-and-Privacy.md#roles-tokens-and-the-audit-log).
+
+## Members work through `--coordinator`
+
+A member's commands go to the team coordinator when they name it with `--coordinator`. Members can list and show nodes; draining, enabling, revoking or removing a node needs `admin`.
+
+<!-- proven-by: TestNodesRemoteMemberReadsButCannotRevoke -->
+```text
+nself ci nodes list --coordinator https://ci.example:3865 --json
+```
+
+<!-- proven-by: TestDetach -->
+```text
+nself ci --detach --json --coordinator https://ci.example:3865
+```
+
+Without the flag, commands stay on the member's own machine, even when a coordinator is configured. Adding and pairing nodes happen on the coordinator box only.
+
+## Personal nodes stay personal
+
+A member's home nodes belong to that member's personal coordinator. They are not part of the team pool, and a team repository's commit of record never runs on them. A project can list which pools may run it; a personal pool left off that list is excluded. `nodes pools explain` shows the effective set and why each runner is left out.
+
+<!-- proven-by: TestScopePersonalVsTeamPool -->
+```text
+nself ci nodes pools explain --project example-org/example-repo
+```
+
+The pool rules are in [Auto Placement and Pools](./Auto-Placement-and-Pools.md#pools).
+
+## The organization's GitHub credentials
+
+The coordinator holds the organization's GitHub credentials, not each member. Write the dispatch workflow into each repository with `providers github init`.
+
+<!-- proven-by: TestGithubInitStdout -->
+```text
+nself ci providers github init --stdout --agent-source source
+```
+
+Scopes and which token does what are in [credentials and scopes](./Hosted-Providers.md#credentials-and-scopes).
+
+## Open source repositories use GitHub-hosted runners
+
+For a public repository, a pull request from a fork is untrusted. It gets no secrets, no LAN access and no trusted cache. Its jobs need the sandboxed container level on a runner with no route to your LAN, or a disposable GitHub-hosted runner. Hosted runners are free for public repositories and nSelf never plans paid hosted minutes. A failure on the hosted runner stays a failure.
+
+Read [Public FOSS PRs](./Trust-Security-and-Privacy.md#public-foss-prs) and [hosted capacity](./Hosted-Providers.md#hosted-capacity) before you open a public repository to your own nodes.
+
+## The required check
+
+Make `nself-ci` a required status check on the protected branch. Run it with `--dry-run` first: it prints the change and writes nothing.
+
+<!-- proven-by: TestPolicyProtectDryRunChangesNothing -->
+```text
+nself ci policy protect --repo example-org/example-repo --branch main --dry-run
+```
+
+Without `--dry-run` it saves a snapshot of the old protection before it writes the new one.
+
+## Own nodes satisfy the check by polling
+
+Your nodes do not need to accept inbound webhooks. `serve watch` polls GitHub over outbound connections only, claims a commit, runs it on your nodes and posts one final `nself-ci` status. With several watchers, exactly one final result is posted per commit; if the preferred watcher dies, another takes over once its claim is dead.
+
+<!-- proven-by: TestWatchThreeHostsExactlyOneStatus -->
+```text
+nself ci serve watch --once --json
+```
+
+If the branch pins the required check to a GitHub App, the watcher posts the advisory `nself-ci/watch` context instead, never `nself-ci`. See [Watch and Services](./Watch-and-Services.md#what-watch-does).
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Team mode flag, permanent switch | `TestServeModeFlagAndStart` |
+| Coordinator mode rules | `TestCoordinatorMode` |
+| Grant, list and revoke roles | `TestServeAdminRolesGrantListRevoke` |
+| Issue a token once | `TestServeAdminTokenIssueOnce` |
+| Revoking a role ends its tokens | `TestServeAdminRevokeEndsTokensToo` |
+| Member reads, cannot change nodes | `TestNodesRemoteMemberReadsButCannotRevoke` |
+| Add and pair stay on the coordinator box | `TestNodesRemoteAddAndPairAreLocalOnly` |
+| Detached run sent to a coordinator | `TestDetach` |
+| Personal pool excluded from team work | `TestScopePersonalVsTeamPool` |
+| Commit of record stays on the record pool | `TestRecordPoolTransportExclusion` |
+| Dispatch workflow rendering | `TestGithubInitStdout` |
+| Hosted result decisions | `TestHostedDecisionMatrix` |
+| Hosted capacity is never metered | `TestEconomicsGitHubHostedIsNeverMetered` |
+| Required check dry run | `TestPolicyProtectDryRunChangesNothing` |
+| Snapshot before applying protection | `TestPolicyProtectApplyWritesSnapshotFirst` |
+| One final status from several watchers | `TestWatchThreeHostsExactlyOneStatus` |
+| Takeover after a dead claim | `TestWatchKillPreferredTakeover` |
+| Pinned check gets the advisory context | `TestStatusContextPinned` |
diff --git a/.github/wiki/guides/ci/Watch-and-Services.md b/.github/wiki/guides/ci/Watch-and-Services.md
new file mode 100644
index 000000000..1c68f72ff
--- /dev/null
+++ b/.github/wiki/guides/ci/Watch-and-Services.md
@@ -0,0 +1,77 @@
+# Watch and services
+
+<!-- docmap: cap:ci.watch -->
+<!-- docmap: cap:ci.claims -->
+<!-- docmap: cap:ci.demand -->
+`nself ci serve watch` lets one host keep a repository's commit CI current without an inbound port or a webhook. This page covers what a pass does, how hosts share the work, and the keys that bound it. Tables of flags and codes are on [[Reference|guides/ci/Reference]].
+
+## What `watch` does
+
+```text
+nself ci serve watch [--interval <duration>] [--repos o/r,...] [--once] [--json]
+```
+
+| Flag | Meaning |
+|---|---|
+| `--interval` | Time between passes. Default: `providers.github.poll_interval`. |
+| `--repos` | Comma-separated `owner/repo` list. Default: this checkout's repository. |
+| `--once` | Run one pass and exit. |
+| `--json` | Print one JSON envelope per pass. |
+
+The watcher is outbound-only: it reads from the provider and posts commit statuses. It needs a CI home (`NSELF_CI_HOME`) and refuses to start without one.
+
+One pass:
+
+1. Finds the heads of every watched repository.
+2. Considers them newest default-branch head first, then recent branches.
+3. Runs at most one commit.
+4. When nothing ran, starts a due background pipeline.
+5. Publishes the demand document and a heartbeat, ready or not.
+
+A pass that hits a provider quota error stops and records the reset time; no scan is made before it. An unchanged answer from the provider reuses the previous heads. A host that is not ready claims nothing.
+
+## Claims and the dead-claim rule
+
+Several hosts can watch the same repository. They do not share a lock. The commit status history is the ledger: a host claims a sha by posting a status, and every host reads the same history to decide whether to take, wait, skip or treat the claim as lost.
+
+- A claim from a creator the watcher does not trust never suppresses CI.
+- Ordering uses the provider's `created_at`, never the local clock. With no provider time yet, no claim is declared dead.
+- A claim is dead when its host has been silent for longer than the run limit plus ten minutes on the provider clock. Another host then takes the sha.
+- Because the history is the ledger, a lost state file never reruns a commit that already has a result.
+
+## Readiness and demand
+
+Before it claims anything a host evaluates its own readiness: it samples the machine, runs the operator's readiness hook and checks the `yield_to` scan. Readiness only gates new work; it never pauses or kills a job that is already running. Each pass publishes a demand document, the work waiting and not yet claimed, even when the host was not ready to take it, so unmet demand stays visible.
+
+## Keys
+
+All `watch.*` keys belong to the operator. A repository cannot widen them, so a checkout can never change what a personal watcher runs or posts. A bad value is refused with the watch code listed on Reference.
+
+| Key | Controls |
+|---|---|
+| `watch.branches` | Which branches are considered besides the default branch. |
+| `watch.max_branches` | The cap on branches considered per pass. |
+| `watch.branch_days` | How recent a branch head must be. |
+| `watch.retry_max` | Attempts at a commit that fails. |
+| `watch.retry_gap` | Minimum time between those attempts. |
+| `watch.status_context` | The status context posted, `nself-ci` or `nself-ci/<name>`. |
+| `watch.drain_sec` | Time allowed for a running job to finish when the watcher stops. |
+
+Unset keys take the built-in defaults of the watcher. Read the effective values with `nself ci config show`.
+
+## Running it
+
+Try one pass in a foreground terminal first:
+
+```text
+nself ci serve watch --once --json
+```
+
+Then run the same command without `--once`. Stop it with `SIGTERM` or an interrupt; `watch.drain_sec` bounds how long it waits for work in hand.
+
+## Related
+
+- [[Auto placement and pools|guides/ci/Auto-Placement-and-Pools]] explains where each claimed commit runs.
+- [[CI scheduling and cost|guides/ci/Scheduling-and-Cost]] explains scoring, budgets and limits.
+
+This page covers only what ships today in `nself ci`; anything not listed here is not yet available.
diff --git a/.github/wiki/plugins/AI-CLI.md b/.github/wiki/plugins/AI-CLI.md
index 55ab19296..7dee31f2d 100644
--- a/.github/wiki/plugins/AI-CLI.md
+++ b/.github/wiki/plugins/AI-CLI.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install ai-cli` |
 | **Commands** | `nself ai-cli` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself ai-cli` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Chat, local Ollama model management, and Gemini key-pool provisioning from the command line.
 
 ## Install
diff --git a/.github/wiki/plugins/AI-Studio.md b/.github/wiki/plugins/AI-Studio.md
index 2a98acd9a..8ff22a77d 100644
--- a/.github/wiki/plugins/AI-Studio.md
+++ b/.github/wiki/plugins/AI-Studio.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install ai-studio` |
 | **Commands** | `nself ai-studio` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself ai-studio` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Bridges a local nSelf instance to Google AI Studio over a secure Cloudflare Tunnel.
 
 ## Install
diff --git a/.github/wiki/plugins/API.md b/.github/wiki/plugins/API.md
index fb39da3fe..ba94c454d 100644
--- a/.github/wiki/plugins/API.md
+++ b/.github/wiki/plugins/API.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install api` |
 | **Commands** | `nself api` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself api` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Inspect the installed plugin API surface, its deprecation calendar, and its changelog.
 
 ## Install
diff --git a/.github/wiki/plugins/Access-Controls.md b/.github/wiki/plugins/Access-Controls.md
index c344d6fd0..c590a4d68 100644
--- a/.github/wiki/plugins/Access-Controls.md
+++ b/.github/wiki/plugins/Access-Controls.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install access-controls` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Admin-Api.md b/.github/wiki/plugins/Admin-Api.md
index b9e052e18..681cbc279 100644
--- a/.github/wiki/plugins/Admin-Api.md
+++ b/.github/wiki/plugins/Admin-Api.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install admin-api` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Alerts.md b/.github/wiki/plugins/Alerts.md
index 6cd46f522..398eff480 100644
--- a/.github/wiki/plugins/Alerts.md
+++ b/.github/wiki/plugins/Alerts.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install alerts` |
 | **Commands** | `nself alerts` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself alerts` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Operate Prometheus alert rules and Alertmanager silences without leaving the terminal.
 
 ## Install
diff --git a/.github/wiki/plugins/Analytics.md b/.github/wiki/plugins/Analytics.md
index 1d310fe7d..471808b2e 100644
--- a/.github/wiki/plugins/Analytics.md
+++ b/.github/wiki/plugins/Analytics.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install analytics` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Audit-Analytics.md b/.github/wiki/plugins/Audit-Analytics.md
index 17469d208..334fd6cc7 100644
--- a/.github/wiki/plugins/Audit-Analytics.md
+++ b/.github/wiki/plugins/Audit-Analytics.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install audit-analytics` |
 | **Requirements** | nSelf >=1.0.9; plugins audit-log |
 
diff --git a/.github/wiki/plugins/Audit-Log.md b/.github/wiki/plugins/Audit-Log.md
index 413816ad4..f4a322dd8 100644
--- a/.github/wiki/plugins/Audit-Log.md
+++ b/.github/wiki/plugins/Audit-Log.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install audit-log` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Audit.md b/.github/wiki/plugins/Audit.md
index e6eea487b..97ef34a4e 100644
--- a/.github/wiki/plugins/Audit.md
+++ b/.github/wiki/plugins/Audit.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install audit` |
 | **Commands** | `nself audit` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself audit` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Sweeps READMEs, wiki, docs, SPORT, PPI and PRI for banned words, dead links, and missing anchors.
 
 ## Install
diff --git a/.github/wiki/plugins/Auth-Enterprise.md b/.github/wiki/plugins/Auth-Enterprise.md
index 2f509fa93..3e2b958be 100644
--- a/.github/wiki/plugins/Auth-Enterprise.md
+++ b/.github/wiki/plugins/Auth-Enterprise.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install auth-enterprise` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/BYOK.md b/.github/wiki/plugins/BYOK.md
index a5fc65845..10c3a10cd 100644
--- a/.github/wiki/plugins/BYOK.md
+++ b/.github/wiki/plugins/BYOK.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | experimental ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install byok` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/Backup.md b/.github/wiki/plugins/Backup.md
index 923bb8a89..1d5fd1656 100644
--- a/.github/wiki/plugins/Backup.md
+++ b/.github/wiki/plugins/Backup.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install backup` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/CDC.md b/.github/wiki/plugins/CDC.md
index 059cddc22..14b106ab2 100644
--- a/.github/wiki/plugins/CDC.md
+++ b/.github/wiki/plugins/CDC.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install cdc` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/CDN.md b/.github/wiki/plugins/CDN.md
index 8699e9215..de4135f40 100644
--- a/.github/wiki/plugins/CDN.md
+++ b/.github/wiki/plugins/CDN.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install cdn` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/CI.md b/.github/wiki/plugins/CI.md
index 703993119..f5f04c5cd 100644
--- a/.github/wiki/plugins/CI.md
+++ b/.github/wiki/plugins/CI.md
@@ -7,13 +7,105 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.11 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install ci` |
-| **Commands** | `nself ci`: `build`, `forgejo`, `nodes provision`, `nodes verify`, `run`, `serve` |
+| **Commands** | `nself ci`: `artifacts`, `build`, `config ignore add`, `config migrate`, `config show`, `doctor`, `evidence`, `evidence verify`, `explain`, `forgejo`, `logs`, `netproxy`, `nodes add`, `nodes discover`, `nodes drain`, `nodes enable`, `nodes forget-project`, `nodes label`, `nodes list`, `nodes pair`, `nodes pools explain`, `nodes pools list`, `nodes pools show`, `nodes projects add`, `nodes projects list`, `nodes projects remove`, `nodes provision`, `nodes remove`, `nodes revoke`, `nodes rotate`, `nodes secrets grant`, `nodes secrets revoke`, `nodes set`, `nodes show`, `nodes status`, `nodes sync`, `nodes test`, `nodes upgrade`, `nodes verify`, `plan`, `policy pin`, `policy protect`, `policy set`, `policy show`, `policy unset`, `policy usage`, `providers`, `providers authorize`, `providers github init`, `providers gitlab init`, `providers list`, `providers revoke`, `providers show`, `providers test`, `providers usage import`, `run`, `runs`, `runs approve`, `runs cancel`, `runs decisions`, `runs follow`, `runs list`, `runs outbox`, `runs pending`, `runs prune`, `runs queue`, `runs reproduce`, `runs rerun`, `runs resolve`, `runs stats`, `runs wait`, `serve`, `serve admin`, `serve admin audit`, `serve admin audit checkpoint`, `serve admin cert`, `serve admin roles`, `serve admin token`, `serve backup`, `serve install`, `serve restore`, `serve uninstall`, `serve watch` |
 | **Requirements** | nSelf >=1.4.12 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself ci` | `nself_ci` | `/v1/commands/ci` | remote | document | MCP and HTTP | nonce |
+| `nself ci artifacts` | `nself_ci_artifacts` | `/v1/commands/ci/artifacts` | read | document | MCP and HTTP | none |
+| `nself ci build` | - | - | remote | document | CLI only (json none) | none |
+| `nself ci config ignore add` | - | - | write | document | CLI only (json none) | none |
+| `nself ci config migrate` | `nself_ci_config_migrate` | `/v1/commands/ci/config/migrate` | write | document | MCP and HTTP | none |
+| `nself ci config show` | `nself_ci_config_show` | `/v1/commands/ci/config/show` | read | document | MCP and HTTP | none |
+| `nself ci doctor` | `nself_ci_doctor` | `/v1/commands/ci/doctor` | read | document | MCP and HTTP | none |
+| `nself ci evidence` | `nself_ci_evidence` | `/v1/commands/ci/evidence` | read | document | MCP and HTTP | none |
+| `nself ci evidence verify` | `nself_ci_evidence_verify` | `/v1/commands/ci/evidence/verify` | read | document | MCP and HTTP | none |
+| `nself ci explain` | `nself_ci_explain` | `/v1/commands/ci/explain` | read | document | MCP and HTTP | none |
+| `nself ci forgejo` | - | - | read | document | CLI only (json none) | none |
+| `nself ci logs` | `nself_ci_logs` | `/v1/commands/ci/logs` | read | document | MCP and HTTP | none |
+| `nself ci netproxy` | - | - | remote | interactive | CLI only (surface cli-only) | none |
+| `nself ci nodes add` | `nself_ci_nodes_add` | `/v1/commands/ci/nodes/add` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes discover` | `nself_ci_nodes_discover` | `/v1/commands/ci/nodes/discover` | read | document | MCP and HTTP | none |
+| `nself ci nodes drain` | `nself_ci_nodes_drain` | `/v1/commands/ci/nodes/drain` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes enable` | `nself_ci_nodes_enable` | `/v1/commands/ci/nodes/enable` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes forget-project` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself ci nodes label` | `nself_ci_nodes_label` | `/v1/commands/ci/nodes/label` | write | document | MCP and HTTP | none |
+| `nself ci nodes list` | `nself_ci_nodes_list` | `/v1/commands/ci/nodes/list` | read | document | MCP and HTTP | none |
+| `nself ci nodes pair` | - | - | remote | interactive | CLI only (surface cli-only) | none |
+| `nself ci nodes pools explain` | `nself_ci_nodes_pools_explain` | `/v1/commands/ci/nodes/pools/explain` | read | document | MCP and HTTP | none |
+| `nself ci nodes pools list` | `nself_ci_nodes_pools_list` | `/v1/commands/ci/nodes/pools/list` | read | document | MCP and HTTP | none |
+| `nself ci nodes pools show` | `nself_ci_nodes_pools_show` | `/v1/commands/ci/nodes/pools/show` | read | document | MCP and HTTP | none |
+| `nself ci nodes projects add` | `nself_ci_nodes_projects_add` | `/v1/commands/ci/nodes/projects/add` | write | document | MCP and HTTP | none |
+| `nself ci nodes projects list` | `nself_ci_nodes_projects_list` | `/v1/commands/ci/nodes/projects/list` | read | document | MCP and HTTP | none |
+| `nself ci nodes projects remove` | `nself_ci_nodes_projects_remove` | `/v1/commands/ci/nodes/projects/remove` | write | document | MCP and HTTP | none |
+| `nself ci nodes provision` | - | - | remote | document | CLI only (surface cli-only) | none |
+| `nself ci nodes remove` | `nself_ci_nodes_remove` | `/v1/commands/ci/nodes/remove` | destructive | document | MCP and HTTP | nonce |
+| `nself ci nodes revoke` | `nself_ci_nodes_revoke` | `/v1/commands/ci/nodes/revoke` | destructive | document | MCP and HTTP | nonce |
+| `nself ci nodes rotate` | `nself_ci_nodes_rotate` | `/v1/commands/ci/nodes/rotate` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes secrets grant` | - | - | remote | interactive | CLI only (surface cli-only) | none |
+| `nself ci nodes secrets revoke` | - | - | remote | interactive | CLI only (surface cli-only) | none |
+| `nself ci nodes set` | `nself_ci_nodes_set` | `/v1/commands/ci/nodes/set` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes show` | `nself_ci_nodes_show` | `/v1/commands/ci/nodes/show` | read | document | MCP and HTTP | none |
+| `nself ci nodes status` | `nself_ci_nodes_status` | `/v1/commands/ci/nodes/status` | read | document | MCP and HTTP | none |
+| `nself ci nodes sync` | `nself_ci_nodes_sync` | `/v1/commands/ci/nodes/sync` | write | document | MCP and HTTP | none |
+| `nself ci nodes test` | `nself_ci_nodes_test` | `/v1/commands/ci/nodes/test` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes upgrade` | `nself_ci_nodes_upgrade` | `/v1/commands/ci/nodes/upgrade` | remote | document | MCP and HTTP | nonce |
+| `nself ci nodes verify` | - | - | read | document | CLI only (surface cli-only) | none |
+| `nself ci plan` | `nself_ci_plan` | `/v1/commands/ci/plan` | read | document | MCP and HTTP | none |
+| `nself ci policy pin` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci policy protect` | `nself_ci_policy_protect` | `/v1/commands/ci/policy/protect` | remote | document | MCP and HTTP | nonce |
+| `nself ci policy set` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci policy show` | `nself_ci_policy_show` | `/v1/commands/ci/policy/show` | read | document | MCP and HTTP | none |
+| `nself ci policy unset` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci policy usage` | `nself_ci_policy_usage` | `/v1/commands/ci/policy/usage` | read | document | MCP and HTTP | none |
+| `nself ci providers` | - | - | read | document | CLI only (surface cli-only) | none |
+| `nself ci providers authorize` | `nself_ci_providers_authorize` | `/v1/commands/ci/providers/authorize` | remote | document | MCP and HTTP | nonce |
+| `nself ci providers github init` | `nself_ci_providers_github_init` | `/v1/commands/ci/providers/github/init` | write | document | MCP and HTTP | none |
+| `nself ci providers gitlab init` | `nself_ci_providers_gitlab_init` | `/v1/commands/ci/providers/gitlab/init` | write | document | MCP and HTTP | none |
+| `nself ci providers list` | `nself_ci_providers_list` | `/v1/commands/ci/providers/list` | read | document | MCP and HTTP | none |
+| `nself ci providers revoke` | `nself_ci_providers_revoke` | `/v1/commands/ci/providers/revoke` | destructive | document | MCP and HTTP | nonce |
+| `nself ci providers show` | `nself_ci_providers_show` | `/v1/commands/ci/providers/show` | read | document | MCP and HTTP | none |
+| `nself ci providers test` | `nself_ci_providers_test` | `/v1/commands/ci/providers/test` | remote | document | MCP and HTTP | nonce |
+| `nself ci providers usage import` | `nself_ci_providers_usage_import` | `/v1/commands/ci/providers/usage/import` | write | document | MCP and HTTP | none |
+| `nself ci run` | - | - | remote | document | CLI only (json none) | none |
+| `nself ci runs` | `nself_ci_runs` | `/v1/commands/ci/runs` | read | document | MCP and HTTP | none |
+| `nself ci runs approve` | `nself_ci_runs_approve` | `/v1/commands/ci/runs/approve` | remote | document | MCP and HTTP | nonce |
+| `nself ci runs cancel` | `nself_ci_runs_cancel` | `/v1/commands/ci/runs/cancel` | remote | document | MCP and HTTP | nonce |
+| `nself ci runs decisions` | `nself_ci_runs_decisions` | `/v1/commands/ci/runs/decisions` | read | document | MCP and HTTP | none |
+| `nself ci runs follow` | - | `/v1/commands/ci/runs/follow` | read | stream | HTTP NDJSON only (stream) | none |
+| `nself ci runs list` | `nself_ci_runs_list` | `/v1/commands/ci/runs/list` | read | document | MCP and HTTP | none |
+| `nself ci runs outbox` | `nself_ci_runs_outbox` | `/v1/commands/ci/runs/outbox` | read | document | MCP and HTTP | none |
+| `nself ci runs pending` | `nself_ci_runs_pending` | `/v1/commands/ci/runs/pending` | read | document | MCP and HTTP | none |
+| `nself ci runs prune` | `nself_ci_runs_prune` | `/v1/commands/ci/runs/prune` | destructive | document | MCP and HTTP | nonce |
+| `nself ci runs queue` | `nself_ci_runs_queue` | `/v1/commands/ci/runs/queue` | read | document | MCP and HTTP | none |
+| `nself ci runs reproduce` | `nself_ci_runs_reproduce` | `/v1/commands/ci/runs/reproduce` | remote | document | MCP and HTTP | nonce |
+| `nself ci runs rerun` | `nself_ci_runs_rerun` | `/v1/commands/ci/runs/rerun` | remote | document | MCP and HTTP | nonce |
+| `nself ci runs resolve` | `nself_ci_runs_resolve` | `/v1/commands/ci/runs/resolve` | write | document | MCP and HTTP | none |
+| `nself ci runs stats` | `nself_ci_runs_stats` | `/v1/commands/ci/runs/stats` | read | document | MCP and HTTP | none |
+| `nself ci runs wait` | `nself_ci_runs_wait` | `/v1/commands/ci/runs/wait` | read | document | MCP and HTTP | none |
+| `nself ci serve` | - | - | write | stream | CLI only (surface cli-only) | none |
+| `nself ci serve admin` | - | - | read | document | CLI only (surface cli-only) | none |
+| `nself ci serve admin audit` | `nself_ci_serve_admin_audit` | `/v1/commands/ci/serve/admin/audit` | read | document | MCP and HTTP | none |
+| `nself ci serve admin audit checkpoint` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci serve admin cert` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci serve admin roles` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself ci serve admin token` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself ci serve backup` | - | - | read | document | CLI only (surface cli-only) | none |
+| `nself ci serve install` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself ci serve restore` | - | - | destructive | interactive | CLI only (surface cli-only) | none |
+| `nself ci serve uninstall` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself ci serve watch` | - | - | remote | stream | CLI only (surface cli-only) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Runs the local lint/test/build/gitleaks gate and posts the result as a GitHub commit status.
 
 ## Install
diff --git a/.github/wiki/plugins/CRDT.md b/.github/wiki/plugins/CRDT.md
index 427101b03..b9693e5d2 100644
--- a/.github/wiki/plugins/CRDT.md
+++ b/.github/wiki/plugins/CRDT.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install crdt` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Claw-CLI.md b/.github/wiki/plugins/Claw-CLI.md
index 3a05f1fc9..76a970e1b 100644
--- a/.github/wiki/plugins/Claw-CLI.md
+++ b/.github/wiki/plugins/Claw-CLI.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install claw-cli` |
 | **Commands** | `nself claw-cli` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself claw-cli` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Command-line client for the nClaw AI assistant: chat, memories, sessions, and an MCP server.
 
 ## Install
diff --git a/.github/wiki/plugins/Cloudflare.md b/.github/wiki/plugins/Cloudflare.md
index b726c77ae..89e50b9bd 100644
--- a/.github/wiki/plugins/Cloudflare.md
+++ b/.github/wiki/plugins/Cloudflare.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install cloudflare` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Compliance.md b/.github/wiki/plugins/Compliance.md
index 37f5daa11..a5ba9d744 100644
--- a/.github/wiki/plugins/Compliance.md
+++ b/.github/wiki/plugins/Compliance.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install compliance` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Content-Acquisition.md b/.github/wiki/plugins/Content-Acquisition.md
index 3113f6231..ee914c370 100644
--- a/.github/wiki/plugins/Content-Acquisition.md
+++ b/.github/wiki/plugins/Content-Acquisition.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install content-acquisition` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Content-Progress.md b/.github/wiki/plugins/Content-Progress.md
index 50e028774..7f35917ce 100644
--- a/.github/wiki/plugins/Content-Progress.md
+++ b/.github/wiki/plugins/Content-Progress.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install content-progress` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Content-Safety.md b/.github/wiki/plugins/Content-Safety.md
index e73105306..7c1b533f8 100644
--- a/.github/wiki/plugins/Content-Safety.md
+++ b/.github/wiki/plugins/Content-Safety.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install content-safety` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Costs.md b/.github/wiki/plugins/Costs.md
index 33ed91d42..1e9e20d79 100644
--- a/.github/wiki/plugins/Costs.md
+++ b/.github/wiki/plugins/Costs.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install costs` |
 | **Commands** | `nself costs` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself costs` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Estimates the monthly bill for your install: VPS, Cloudflare, Vercel, Stripe fees, and licenses.
 
 ## Install
diff --git a/.github/wiki/plugins/Cron.md b/.github/wiki/plugins/Cron.md
index 920bbda90..539ea4309 100644
--- a/.github/wiki/plugins/Cron.md
+++ b/.github/wiki/plugins/Cron.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) and Licensed, in the Claw Bundle |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | free: 1.2.6; licensed: 1.1.2 |
+| **Version** | free: 1.2.13; licensed: 1.1.2 |
 | **Install** | `nself plugin install cron` |
 | **Requirements** | free: nSelf >=0.9.9; licensed: nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/DDNS.md b/.github/wiki/plugins/DDNS.md
index 5ad5fa4a0..3329714af 100644
--- a/.github/wiki/plugins/DDNS.md
+++ b/.github/wiki/plugins/DDNS.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install ddns` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/DLQ.md b/.github/wiki/plugins/DLQ.md
index fac4bfd79..dcc7e4718 100644
--- a/.github/wiki/plugins/DLQ.md
+++ b/.github/wiki/plugins/DLQ.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install dlq` |
 | **Commands** | `nself dlq` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself dlq` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Re-enqueues dead-lettered rows from a plugin's failed-processing queue, with a dry-run preview.
 
 ## Install
diff --git a/.github/wiki/plugins/DR.md b/.github/wiki/plugins/DR.md
index 7d6a87e0d..d962838a2 100644
--- a/.github/wiki/plugins/DR.md
+++ b/.github/wiki/plugins/DR.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install dr` |
 | **Commands** | `nself dr` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself dr` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Promotes a standby, fences the old primary, and runs failover drills.
 
 ## Install
diff --git a/.github/wiki/plugins/Devices.md b/.github/wiki/plugins/Devices.md
index 385b89799..648b569b7 100644
--- a/.github/wiki/plugins/Devices.md
+++ b/.github/wiki/plugins/Devices.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install devices` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Documents.md b/.github/wiki/plugins/Documents.md
index 9905eed84..cc497384f 100644
--- a/.github/wiki/plugins/Documents.md
+++ b/.github/wiki/plugins/Documents.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install documents` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Dogfood.md b/.github/wiki/plugins/Dogfood.md
index e5f22b518..bc287c779 100644
--- a/.github/wiki/plugins/Dogfood.md
+++ b/.github/wiki/plugins/Dogfood.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install dogfood` |
 | **Commands** | `nself dogfood` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself dogfood` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Runs 21 read-only production health checks across backups, DR, tenancy, and security.
 
 ## Install
diff --git a/.github/wiki/plugins/Donorbox.md b/.github/wiki/plugins/Donorbox.md
index 0cc2ec608..981e098d6 100644
--- a/.github/wiki/plugins/Donorbox.md
+++ b/.github/wiki/plugins/Donorbox.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install donorbox` |
 | **Requirements** | nSelf >=0.9.9 |
 
diff --git a/.github/wiki/plugins/E2EE.md b/.github/wiki/plugins/E2EE.md
index 54886b707..190535374 100644
--- a/.github/wiki/plugins/E2EE.md
+++ b/.github/wiki/plugins/E2EE.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install e2ee` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Email.md b/.github/wiki/plugins/Email.md
index 9672d1d7e..2d1a1b4e1 100644
--- a/.github/wiki/plugins/Email.md
+++ b/.github/wiki/plugins/Email.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install email` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Encryption.md b/.github/wiki/plugins/Encryption.md
index 9b972d004..c5e786af7 100644
--- a/.github/wiki/plugins/Encryption.md
+++ b/.github/wiki/plugins/Encryption.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install encryption` |
 | **Commands** | `nself encryption` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself encryption` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Bring Your Own Key (BYOK) per-tenant envelope encryption for nSelf Cloud: AWS KMS, GCP Cloud KMS, and HashiCorp Vault Transit, with key rotation and an audit trail.
 
 ## Install
diff --git a/.github/wiki/plugins/Entitlements.md b/.github/wiki/plugins/Entitlements.md
index 91aae77ab..a433a52ad 100644
--- a/.github/wiki/plugins/Entitlements.md
+++ b/.github/wiki/plugins/Entitlements.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install entitlements` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Event-Bus.md b/.github/wiki/plugins/Event-Bus.md
index 7e5450fcd..766e144fc 100644
--- a/.github/wiki/plugins/Event-Bus.md
+++ b/.github/wiki/plugins/Event-Bus.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install event-bus` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Family-Ancestry.md b/.github/wiki/plugins/Family-Ancestry.md
index bd80d66ca..34e2669e7 100644
--- a/.github/wiki/plugins/Family-Ancestry.md
+++ b/.github/wiki/plugins/Family-Ancestry.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install family-ancestry` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Family-FamilySearch.md b/.github/wiki/plugins/Family-FamilySearch.md
index 74bc20a7c..cd71edbfd 100644
--- a/.github/wiki/plugins/Family-FamilySearch.md
+++ b/.github/wiki/plugins/Family-FamilySearch.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install family-familysearch` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Family-GEDCOM.md b/.github/wiki/plugins/Family-GEDCOM.md
index 23c685fa0..acbb4c39a 100644
--- a/.github/wiki/plugins/Family-GEDCOM.md
+++ b/.github/wiki/plugins/Family-GEDCOM.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install family-gedcom` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Family-MyHeritage.md b/.github/wiki/plugins/Family-MyHeritage.md
index 235b64001..3e8a8bf2e 100644
--- a/.github/wiki/plugins/Family-MyHeritage.md
+++ b/.github/wiki/plugins/Family-MyHeritage.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install family-myheritage` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Family-WikiTree.md b/.github/wiki/plugins/Family-WikiTree.md
index a8e5531fd..cb69b1cc8 100644
--- a/.github/wiki/plugins/Family-WikiTree.md
+++ b/.github/wiki/plugins/Family-WikiTree.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install family-wikitree` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Feature-Flags.md b/.github/wiki/plugins/Feature-Flags.md
index 2e22b0e92..5f7f5a4ae 100644
--- a/.github/wiki/plugins/Feature-Flags.md
+++ b/.github/wiki/plugins/Feature-Flags.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install feature-flags` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Federation.md b/.github/wiki/plugins/Federation.md
index a6b2f3ad2..2070f5631 100644
--- a/.github/wiki/plugins/Federation.md
+++ b/.github/wiki/plugins/Federation.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install federation` |
 | **Commands** | `nself federation` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself federation` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Composes an Apollo Router supergraph from every installed plugin's GraphQL subgraph.
 
 ## Install
diff --git a/.github/wiki/plugins/File-Processing.md b/.github/wiki/plugins/File-Processing.md
index 7f55bf090..36978358a 100644
--- a/.github/wiki/plugins/File-Processing.md
+++ b/.github/wiki/plugins/File-Processing.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install file-processing` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Flags.md b/.github/wiki/plugins/Flags.md
index f5140de09..5d4fac43e 100644
--- a/.github/wiki/plugins/Flags.md
+++ b/.github/wiki/plugins/Flags.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install flags` |
 | **Commands** | `nself flags` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself flags` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Command-line control surface for the feature-flags plugin: canary rollouts and kill switches.
 
 ## Install
diff --git a/.github/wiki/plugins/Forgejo.md b/.github/wiki/plugins/Forgejo.md
index f22b4b727..0d58e1aae 100644
--- a/.github/wiki/plugins/Forgejo.md
+++ b/.github/wiki/plugins/Forgejo.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install forgejo` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/Functions-V8.md b/.github/wiki/plugins/Functions-V8.md
index 44a81e4c6..c30508a47 100644
--- a/.github/wiki/plugins/Functions-V8.md
+++ b/.github/wiki/plugins/Functions-V8.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install functions-v8` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/Functions.md b/.github/wiki/plugins/Functions.md
index 75908fd04..fe8d7831e 100644
--- a/.github/wiki/plugins/Functions.md
+++ b/.github/wiki/plugins/Functions.md
@@ -7,13 +7,27 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.11 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install functions` |
 | **Commands** | `nself functions`: `delete`, `deploy`, `invoke`, `list`, `logs` |
 | **Requirements** | nSelf >=1.4.12 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself functions` | `nself_functions` | `/v1/commands/functions` | write | document | MCP and HTTP | none |
+| `nself functions delete` | `nself_functions_delete` | `/v1/commands/functions/delete` | destructive | document | MCP and HTTP | nonce |
+| `nself functions deploy` | `nself_functions_deploy` | `/v1/commands/functions/deploy` | write | document | MCP and HTTP | none |
+| `nself functions invoke` | `nself_functions_invoke` | `/v1/commands/functions/invoke` | write | document | MCP and HTTP | none |
+| `nself functions list` | `nself_functions_list` | `/v1/commands/functions/list` | read | document | MCP and HTTP | none |
+| `nself functions logs` | `nself_functions_logs` | `/v1/commands/functions/logs` | read | document | MCP and HTTP | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Deploy and manage nself serverless functions.
 
 ## Install
diff --git a/.github/wiki/plugins/GDPR.md b/.github/wiki/plugins/GDPR.md
index fa002c4c7..b6e3dbdc9 100644
--- a/.github/wiki/plugins/GDPR.md
+++ b/.github/wiki/plugins/GDPR.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install gdpr` |
 | **Commands** | `nself gdpr` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself gdpr` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Handles GDPR Art. 20 data-portability exports and Art. 17 erasure requests.
 
 ## Install
diff --git a/.github/wiki/plugins/Game-Metadata.md b/.github/wiki/plugins/Game-Metadata.md
index 010aaf8e7..0f51a5ca3 100644
--- a/.github/wiki/plugins/Game-Metadata.md
+++ b/.github/wiki/plugins/Game-Metadata.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install game-metadata` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Gateway.md b/.github/wiki/plugins/Gateway.md
index 4235f3f58..be7d5d852 100644
--- a/.github/wiki/plugins/Gateway.md
+++ b/.github/wiki/plugins/Gateway.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install gateway` |
 | **Commands** | `nself gateway` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself gateway` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Manages the nSelf AI gateway's provider key vault, quota usage, and routing rules.
 
 ## Install
diff --git a/.github/wiki/plugins/Gauth.md b/.github/wiki/plugins/Gauth.md
index 73780c629..68331e9b9 100644
--- a/.github/wiki/plugins/Gauth.md
+++ b/.github/wiki/plugins/Gauth.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install gauth` |
 | **Commands** | `nself gauth` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself gauth` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Refreshes, checks, and revokes the Google OAuth tokens nSelf's AI services depend on.
 
 ## Install
diff --git a/.github/wiki/plugins/Geocoding.md b/.github/wiki/plugins/Geocoding.md
index e9d858a6c..e948942b2 100644
--- a/.github/wiki/plugins/Geocoding.md
+++ b/.github/wiki/plugins/Geocoding.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install geocoding` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/GitHub-Runner.md b/.github/wiki/plugins/GitHub-Runner.md
index a6a0320cc..accf33280 100644
--- a/.github/wiki/plugins/GitHub-Runner.md
+++ b/.github/wiki/plugins/GitHub-Runner.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install github-runner` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/GitHub.md b/.github/wiki/plugins/GitHub.md
index a73dcadd8..b005794c1 100644
--- a/.github/wiki/plugins/GitHub.md
+++ b/.github/wiki/plugins/GitHub.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install github` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/HIPAA.md b/.github/wiki/plugins/HIPAA.md
index 60489a2e6..df53b4065 100644
--- a/.github/wiki/plugins/HIPAA.md
+++ b/.github/wiki/plugins/HIPAA.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install hipaa` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Home.md b/.github/wiki/plugins/Home.md
index 2c35b81ea..e19b631db 100644
--- a/.github/wiki/plugins/Home.md
+++ b/.github/wiki/plugins/Home.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install home` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/IDme.md b/.github/wiki/plugins/IDme.md
index b04631fe0..ef89da706 100644
--- a/.github/wiki/plugins/IDme.md
+++ b/.github/wiki/plugins/IDme.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install idme` |
 | **Requirements** | nSelf >=1.0.0 |
 
@@ -2954,4 +2954,5 @@ nself plugin idme test
 ---
 
 *Last Updated: January 2026*
+
 *Plugin Version: 1.0.0*
diff --git a/.github/wiki/plugins/Infra.md b/.github/wiki/plugins/Infra.md
index 11553905a..c4075bdab 100644
--- a/.github/wiki/plugins/Infra.md
+++ b/.github/wiki/plugins/Infra.md
@@ -7,13 +7,30 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | experimental ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install infra` |
 | **Commands** | `nself infra`: `apply`, `destroy`, `plan`, `server destroy`, `server list`, `server provision`, `server resize`, `validate` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself infra` | - | - | remote | document | CLI only (json none) | none |
+| `nself infra apply` | - | - | remote | document | CLI only (surface cli-only) | none |
+| `nself infra destroy` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself infra plan` | - | - | read | document | CLI only (json legacy) | none |
+| `nself infra server destroy` | - | - | destructive | document | CLI only (surface cli-only) | none |
+| `nself infra server list` | - | - | read | document | CLI only (surface cli-only) | none |
+| `nself infra server provision` | - | - | remote | document | CLI only (surface cli-only) | none |
+| `nself infra server resize` | - | - | remote | document | CLI only (surface cli-only) | none |
+| `nself infra validate` | - | - | read | document | CLI only (json legacy) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Provisions nSelf infrastructure on Hetzner Cloud via OpenTofu/Terraform.
 
 ## Install
diff --git a/.github/wiki/plugins/Invitations.md b/.github/wiki/plugins/Invitations.md
index 111323923..0f7a5f5cd 100644
--- a/.github/wiki/plugins/Invitations.md
+++ b/.github/wiki/plugins/Invitations.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install invitations` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Job-Queue.md b/.github/wiki/plugins/Job-Queue.md
index 80eedca4b..4de861e24 100644
--- a/.github/wiki/plugins/Job-Queue.md
+++ b/.github/wiki/plugins/Job-Queue.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install job-queue` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Jobs.md b/.github/wiki/plugins/Jobs.md
index eb8495fdc..1796d67f2 100644
--- a/.github/wiki/plugins/Jobs.md
+++ b/.github/wiki/plugins/Jobs.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install jobs` |
 | **Requirements** | nSelf >=0.9.9 |
 
@@ -2102,4 +2102,5 @@ await scheduleJob({
 ---
 
 *Last Updated: January 2026*
+
 *Plugin Version: 1.0.0*
diff --git a/.github/wiki/plugins/K8s.md b/.github/wiki/plugins/K8s.md
index a66e1503b..d9e9ecd91 100644
--- a/.github/wiki/plugins/K8s.md
+++ b/.github/wiki/plugins/K8s.md
@@ -7,13 +7,29 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install k8s` |
 | **Commands** | `nself k8s`: `backup`, `install`, `restore`, `status`, `uninstall`, `upgrade`, `values` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself k8s` | - | - | remote | document | CLI only (json legacy) | none |
+| `nself k8s backup` | - | - | write | document | CLI only (json legacy) | none |
+| `nself k8s install` | - | - | remote | document | CLI only (json legacy) | none |
+| `nself k8s restore` | - | - | destructive | document | CLI only (json legacy) | none |
+| `nself k8s status` | - | - | read | document | CLI only (json legacy) | none |
+| `nself k8s uninstall` | - | - | destructive | document | CLI only (json legacy) | none |
+| `nself k8s upgrade` | - | - | remote | document | CLI only (json legacy) | none |
+| `nself k8s values` | - | - | write | document | CLI only (json legacy) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Installs and upgrades nSelf on any Kubernetes cluster through the official Helm chart.
 
 ## Install
diff --git a/.github/wiki/plugins/Link-Preview.md b/.github/wiki/plugins/Link-Preview.md
index ad24b6aa4..eebb7fb44 100644
--- a/.github/wiki/plugins/Link-Preview.md
+++ b/.github/wiki/plugins/Link-Preview.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install link-preview` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/LinkedIn.md b/.github/wiki/plugins/LinkedIn.md
index f9a27b1a6..85367802b 100644
--- a/.github/wiki/plugins/LinkedIn.md
+++ b/.github/wiki/plugins/LinkedIn.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install linkedin` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/MDNS.md b/.github/wiki/plugins/MDNS.md
index 323f098b2..a8d0af711 100644
--- a/.github/wiki/plugins/MDNS.md
+++ b/.github/wiki/plugins/MDNS.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install mdns` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/MLflow.md b/.github/wiki/plugins/MLflow.md
index a785add8b..0ca1ee27d 100644
--- a/.github/wiki/plugins/MLflow.md
+++ b/.github/wiki/plugins/MLflow.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install mlflow` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Mail.md b/.github/wiki/plugins/Mail.md
index 79dd69e85..e7044d759 100644
--- a/.github/wiki/plugins/Mail.md
+++ b/.github/wiki/plugins/Mail.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install mail` |
 | **Commands** | `nself mail` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself mail` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Send transactional and broadcast email through the nSelf stack: mux + Postmark pipeline via ping_api, template management, and DKIM verification.
 
 ## Install
diff --git a/.github/wiki/plugins/Maintenance.md b/.github/wiki/plugins/Maintenance.md
index 83b11ee15..74c2c266b 100644
--- a/.github/wiki/plugins/Maintenance.md
+++ b/.github/wiki/plugins/Maintenance.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install maintenance` |
 | **Commands** | `nself maintenance` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself maintenance` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Schedules disk cleanup and log rotation so a self-hosted instance doesn't fill its disk.
 
 ## Install
diff --git a/.github/wiki/plugins/Media-Processing.md b/.github/wiki/plugins/Media-Processing.md
index 24c8a9d97..202bf5bc1 100644
--- a/.github/wiki/plugins/Media-Processing.md
+++ b/.github/wiki/plugins/Media-Processing.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install media-processing` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Meetings.md b/.github/wiki/plugins/Meetings.md
index 82b46c1bd..7f72b6169 100644
--- a/.github/wiki/plugins/Meetings.md
+++ b/.github/wiki/plugins/Meetings.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install meetings` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Minio.md b/.github/wiki/plugins/Minio.md
index 0bbf06690..6b39c332b 100644
--- a/.github/wiki/plugins/Minio.md
+++ b/.github/wiki/plugins/Minio.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.7 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install minio` |
 | **Requirements** | nSelf >=1.4.14 |
 
diff --git a/.github/wiki/plugins/Model.md b/.github/wiki/plugins/Model.md
index f861b5e08..9b3b1a0b3 100644
--- a/.github/wiki/plugins/Model.md
+++ b/.github/wiki/plugins/Model.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install model` |
 | **Commands** | `nself model` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself model` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Manages local Ollama models: pull, benchmark, update, and remove, from one command tree.
 
 ## Install
diff --git a/.github/wiki/plugins/Moderation.md b/.github/wiki/plugins/Moderation.md
index bda3ec425..a5e0efffd 100644
--- a/.github/wiki/plugins/Moderation.md
+++ b/.github/wiki/plugins/Moderation.md
@@ -1104,5 +1104,6 @@ ORDER BY created_at DESC;
 ---
 
 **Last Updated**: February 11, 2026
+
 **Plugin Version**: 1.0.0
 **Minimum nself Version**: 0.4.8
diff --git a/.github/wiki/plugins/Monitor.md b/.github/wiki/plugins/Monitor.md
index c0fc67675..b2c2434dc 100644
--- a/.github/wiki/plugins/Monitor.md
+++ b/.github/wiki/plugins/Monitor.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install monitor` |
 | **Commands** | `nself monitor` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself monitor` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Keeps the bundled Grafana dashboards current with one upgrade command.
 
 ## Install
diff --git a/.github/wiki/plugins/Notifications.md b/.github/wiki/plugins/Notifications.md
index d8a546281..89ab57d74 100644
--- a/.github/wiki/plugins/Notifications.md
+++ b/.github/wiki/plugins/Notifications.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | deferred ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install notifications` |
 | **Requirements** | nSelf >=0.9.9 |
 
@@ -2683,4 +2683,5 @@ curl http://localhost:3102/api/stats/delivery
 ---
 
 *Last Updated: January 2026*
+
 *Plugin Version: 1.0.0*
diff --git a/.github/wiki/plugins/Notify.md b/.github/wiki/plugins/Notify.md
index 4f39ad525..7d285bb8d 100644
--- a/.github/wiki/plugins/Notify.md
+++ b/.github/wiki/plugins/Notify.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) and Licensed, in the Claw Bundle |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | free: 1.2.6; licensed: 1.1.3 |
+| **Version** | free: 1.2.13; licensed: 1.1.3 |
 | **Install** | `nself plugin install notify` |
 | **Requirements** | free: nSelf >=0.9.9; licensed: nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Object-Storage.md b/.github/wiki/plugins/Object-Storage.md
index 704bf37ad..e33383990 100644
--- a/.github/wiki/plugins/Object-Storage.md
+++ b/.github/wiki/plugins/Object-Storage.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install object-storage` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Observability.md b/.github/wiki/plugins/Observability.md
index c46aca21d..466a37ada 100644
--- a/.github/wiki/plugins/Observability.md
+++ b/.github/wiki/plugins/Observability.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install observability` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Ollama.md b/.github/wiki/plugins/Ollama.md
index e75d816d1..186016744 100644
--- a/.github/wiki/plugins/Ollama.md
+++ b/.github/wiki/plugins/Ollama.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install ollama` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/PayPal.md b/.github/wiki/plugins/PayPal.md
index 6b8283871..fab78b9c5 100644
--- a/.github/wiki/plugins/PayPal.md
+++ b/.github/wiki/plugins/PayPal.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install paypal` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Payments.md b/.github/wiki/plugins/Payments.md
index a3862da5d..db4b8d8f8 100644
--- a/.github/wiki/plugins/Payments.md
+++ b/.github/wiki/plugins/Payments.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install payments` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Pentest-Kit.md b/.github/wiki/plugins/Pentest-Kit.md
index c35cf1368..213c2a27d 100644
--- a/.github/wiki/plugins/Pentest-Kit.md
+++ b/.github/wiki/plugins/Pentest-Kit.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install pentest-kit` |
 | **Commands** | `nself pentest-kit` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself pentest-kit` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > CLI front end for the pentest plugin: generate scope documents, provision test credentials, import findings, and check remediation status.
 
 ## Install
diff --git a/.github/wiki/plugins/Pentest.md b/.github/wiki/plugins/Pentest.md
index 4bf877ae0..924ee21de 100644
--- a/.github/wiki/plugins/Pentest.md
+++ b/.github/wiki/plugins/Pentest.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install pentest` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/Plugin-ClawDE.md b/.github/wiki/plugins/Plugin-ClawDE.md
index 0a7607a5a..d75d9eb33 100644
--- a/.github/wiki/plugins/Plugin-ClawDE.md
+++ b/.github/wiki/plugins/Plugin-ClawDE.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-clawde` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/Plugin-Dev.md b/.github/wiki/plugins/Plugin-Dev.md
index d967d7180..3f035cd27 100644
--- a/.github/wiki/plugins/Plugin-Dev.md
+++ b/.github/wiki/plugins/Plugin-Dev.md
@@ -7,13 +7,29 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.7 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-dev` |
 | **Commands** | `nself plugin-dev`: `debug`, `dev`, `init`, `link`, `new`, `test`, `unlink` |
 | **Requirements** | nSelf >=1.0.0 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself plugin-dev` | `nself_plugin_dev` | `/v1/commands/plugin-dev` | write | document | MCP and HTTP | none |
+| `nself plugin-dev debug` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself plugin-dev dev` | - | - | write | stream | CLI only (surface cli-only) | none |
+| `nself plugin-dev init` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself plugin-dev link` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself plugin-dev new` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself plugin-dev test` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself plugin-dev unlink` | - | - | write | document | CLI only (surface cli-only) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Plugin author tools: scaffold, link, run with hot reload, debug and test a plugin under development.
 
 ## Install
diff --git a/.github/wiki/plugins/Plugin-Gauth.md b/.github/wiki/plugins/Plugin-Gauth.md
index b540d1669..009987b63 100644
--- a/.github/wiki/plugins/Plugin-Gauth.md
+++ b/.github/wiki/plugins/Plugin-Gauth.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-gauth` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/Plugin-LLM-Gateway.md b/.github/wiki/plugins/Plugin-LLM-Gateway.md
index 4c2d8f47b..94553638f 100644
--- a/.github/wiki/plugins/Plugin-LLM-Gateway.md
+++ b/.github/wiki/plugins/Plugin-LLM-Gateway.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-llm-gateway` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/Plugin-PTY.md b/.github/wiki/plugins/Plugin-PTY.md
index 70cdbb203..e2d47757c 100644
--- a/.github/wiki/plugins/Plugin-PTY.md
+++ b/.github/wiki/plugins/Plugin-PTY.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-pty` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/Plugin-Retrieval.md b/.github/wiki/plugins/Plugin-Retrieval.md
index 1e0b9e61d..548731ed9 100644
--- a/.github/wiki/plugins/Plugin-Retrieval.md
+++ b/.github/wiki/plugins/Plugin-Retrieval.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install plugin-retrieval` |
 | **Requirements** | nSelf >=1.1.1; postgres extensions vector |
 
diff --git a/.github/wiki/plugins/Podcast.md b/.github/wiki/plugins/Podcast.md
index 3123fe0bc..0ac2dfdd9 100644
--- a/.github/wiki/plugins/Podcast.md
+++ b/.github/wiki/plugins/Podcast.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install podcast` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Post.md b/.github/wiki/plugins/Post.md
index f91c9832b..2cd8d9380 100644
--- a/.github/wiki/plugins/Post.md
+++ b/.github/wiki/plugins/Post.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install post` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Push.md b/.github/wiki/plugins/Push.md
index 78ce018ba..5f3c7900f 100644
--- a/.github/wiki/plugins/Push.md
+++ b/.github/wiki/plugins/Push.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install push` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/Queue.md b/.github/wiki/plugins/Queue.md
index 33f72a5b7..a89a0ec21 100644
--- a/.github/wiki/plugins/Queue.md
+++ b/.github/wiki/plugins/Queue.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install queue` |
 | **Commands** | `nself queue` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself queue` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Inspects background job queues for depth, stuck jobs, and lets you retry or purge them.
 
 ## Install
diff --git a/.github/wiki/plugins/Region.md b/.github/wiki/plugins/Region.md
index 1688ddd27..cf4acc1f7 100644
--- a/.github/wiki/plugins/Region.md
+++ b/.github/wiki/plugins/Region.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install region` |
 | **Commands** | `nself region` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself region` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Adds, inspects, and promotes replica regions for multi-region deployments.
 
 ## Install
diff --git a/.github/wiki/plugins/Release.md b/.github/wiki/plugins/Release.md
index 62456ee85..b8ba2ec91 100644
--- a/.github/wiki/plugins/Release.md
+++ b/.github/wiki/plugins/Release.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install release` |
 | **Commands** | `nself release` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself release` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Runs nSelf's own 12-step release cascade across cli, plugins-pro, admin, and Homebrew.
 
 ## Install
diff --git a/.github/wiki/plugins/Retro-Gaming.md b/.github/wiki/plugins/Retro-Gaming.md
index f15c25c93..58e94b8e4 100644
--- a/.github/wiki/plugins/Retro-Gaming.md
+++ b/.github/wiki/plugins/Retro-Gaming.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install retro-gaming` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Rom-Discovery.md b/.github/wiki/plugins/Rom-Discovery.md
index 368923b1d..8097d085d 100644
--- a/.github/wiki/plugins/Rom-Discovery.md
+++ b/.github/wiki/plugins/Rom-Discovery.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install rom-discovery` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/SIEM.md b/.github/wiki/plugins/SIEM.md
index c8683afc7..27cff3399 100644
--- a/.github/wiki/plugins/SIEM.md
+++ b/.github/wiki/plugins/SIEM.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install siem` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/SMS.md b/.github/wiki/plugins/SMS.md
index 084e5da60..f9b087f51 100644
--- a/.github/wiki/plugins/SMS.md
+++ b/.github/wiki/plugins/SMS.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install sms` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Search.md b/.github/wiki/plugins/Search.md
index 5589a8ad8..2d104a4a7 100644
--- a/.github/wiki/plugins/Search.md
+++ b/.github/wiki/plugins/Search.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install search` |
 | **Requirements** | nSelf >=0.9.9 |
 
diff --git a/.github/wiki/plugins/Sentry-CLI.md b/.github/wiki/plugins/Sentry-CLI.md
index 9f1415186..409fbfe11 100644
--- a/.github/wiki/plugins/Sentry-CLI.md
+++ b/.github/wiki/plugins/Sentry-CLI.md
@@ -7,13 +7,38 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install sentry-cli` |
 | **Commands** | `nself sentry`: `alerts channels`, `alerts test`, `incidents ack`, `incidents list`, `incidents resolve`, `login`, `logout`, `monitors add`, `monitors list`, `monitors pause`, `monitors resume`, `monitors rm`, `status`, `status-pages create`, `status-pages list`, `whoami` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself sentry` | `nself_sentry` | `/v1/commands/sentry` | read | document | MCP and HTTP | none |
+| `nself sentry alerts channels` | `nself_sentry_alerts_channels` | `/v1/commands/sentry/alerts/channels` | read | document | MCP and HTTP | none |
+| `nself sentry alerts test` | - | - | remote | document | CLI only (remote without confirm) | none |
+| `nself sentry incidents ack` | `nself_sentry_incidents_ack` | `/v1/commands/sentry/incidents/ack` | write | document | MCP and HTTP | none |
+| `nself sentry incidents list` | `nself_sentry_incidents_list` | `/v1/commands/sentry/incidents/list` | read | document | MCP and HTTP | none |
+| `nself sentry incidents resolve` | `nself_sentry_incidents_resolve` | `/v1/commands/sentry/incidents/resolve` | remote | document | MCP and HTTP | nonce |
+| `nself sentry login` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself sentry logout` | - | - | write | document | CLI only (surface cli-only) | none |
+| `nself sentry monitors add` | `nself_sentry_monitors_add` | `/v1/commands/sentry/monitors/add` | write | document | MCP and HTTP | none |
+| `nself sentry monitors list` | `nself_sentry_monitors_list` | `/v1/commands/sentry/monitors/list` | read | document | MCP and HTTP | none |
+| `nself sentry monitors pause` | `nself_sentry_monitors_pause` | `/v1/commands/sentry/monitors/pause` | remote | document | MCP and HTTP | nonce |
+| `nself sentry monitors resume` | `nself_sentry_monitors_resume` | `/v1/commands/sentry/monitors/resume` | remote | document | MCP and HTTP | nonce |
+| `nself sentry monitors rm` | `nself_sentry_monitors_rm` | `/v1/commands/sentry/monitors/rm` | destructive | document | MCP and HTTP | nonce |
+| `nself sentry status` | `nself_sentry_status` | `/v1/commands/sentry/status` | read | document | MCP and HTTP | none |
+| `nself sentry status-pages create` | `nself_sentry_status_pages_create` | `/v1/commands/sentry/status-pages/create` | remote | document | MCP and HTTP | nonce |
+| `nself sentry status-pages list` | `nself_sentry_status_pages_list` | `/v1/commands/sentry/status-pages/list` | read | document | MCP and HTTP | none |
+| `nself sentry whoami` | `nself_sentry_whoami` | `/v1/commands/sentry/whoami` | read | document | MCP and HTTP | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Operates a self-hosted ɳSentry instance: monitors, incidents, status pages, and alerts.
 
 ## Install
diff --git a/.github/wiki/plugins/Shared-Utils.md b/.github/wiki/plugins/Shared-Utils.md
index c45675f3a..686aad4e1 100644
--- a/.github/wiki/plugins/Shared-Utils.md
+++ b/.github/wiki/plugins/Shared-Utils.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install shared-utils` |
 
 <!-- END GENERATED:catalog -->
diff --git a/.github/wiki/plugins/Shopify.md b/.github/wiki/plugins/Shopify.md
index 169699e99..f5bc5e67c 100644
--- a/.github/wiki/plugins/Shopify.md
+++ b/.github/wiki/plugins/Shopify.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install shopify` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Soak.md b/.github/wiki/plugins/Soak.md
index f02c46124..8b5227b14 100644
--- a/.github/wiki/plugins/Soak.md
+++ b/.github/wiki/plugins/Soak.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install soak` |
 | **Commands** | `nself soak` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself soak` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Aborts an in-progress soak test and rolls the deployment back to its prior version.
 
 ## Install
diff --git a/.github/wiki/plugins/Sports.md b/.github/wiki/plugins/Sports.md
index 227f00ca3..868d9f2e4 100644
--- a/.github/wiki/plugins/Sports.md
+++ b/.github/wiki/plugins/Sports.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install sports` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Storage.md b/.github/wiki/plugins/Storage.md
index 8859719b4..14d2ba004 100644
--- a/.github/wiki/plugins/Storage.md
+++ b/.github/wiki/plugins/Storage.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install storage` |
 | **Requirements** | nSelf >=1.1.0 |
 
diff --git a/.github/wiki/plugins/Stripe.md b/.github/wiki/plugins/Stripe.md
index 5304564db..ececb04fa 100644
--- a/.github/wiki/plugins/Stripe.md
+++ b/.github/wiki/plugins/Stripe.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install stripe` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Subtitle-Manager.md b/.github/wiki/plugins/Subtitle-Manager.md
index 2501ad046..f62029f52 100644
--- a/.github/wiki/plugins/Subtitle-Manager.md
+++ b/.github/wiki/plugins/Subtitle-Manager.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install subtitle-manager` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/TMDB.md b/.github/wiki/plugins/TMDB.md
index acc864a23..9c1fee5ef 100644
--- a/.github/wiki/plugins/TMDB.md
+++ b/.github/wiki/plugins/TMDB.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install tmdb` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Tenant-Controller.md b/.github/wiki/plugins/Tenant-Controller.md
index c83de6f29..5fed778ee 100644
--- a/.github/wiki/plugins/Tenant-Controller.md
+++ b/.github/wiki/plugins/Tenant-Controller.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install tenant-controller` |
 | **Requirements** | nSelf >=1.0.9 |
 
diff --git a/.github/wiki/plugins/Tenant.md b/.github/wiki/plugins/Tenant.md
index c04796634..8c769b469 100644
--- a/.github/wiki/plugins/Tenant.md
+++ b/.github/wiki/plugins/Tenant.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install tenant` |
 | **Commands** | `nself tenant` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself tenant` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Creates, suspends, upgrades and destroys tenants, with per-tenant usage and billing reports.
 
 ## Install
diff --git a/.github/wiki/plugins/Tokens.md b/.github/wiki/plugins/Tokens.md
index ee8ab4c71..e854ca850 100644
--- a/.github/wiki/plugins/Tokens.md
+++ b/.github/wiki/plugins/Tokens.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.9 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install tokens` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Torrent-Manager.md b/.github/wiki/plugins/Torrent-Manager.md
index 4dd6ca85b..37db70794 100644
--- a/.github/wiki/plugins/Torrent-Manager.md
+++ b/.github/wiki/plugins/Torrent-Manager.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install torrent-manager` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Traefik.md b/.github/wiki/plugins/Traefik.md
index f06d8488a..4961bf857 100644
--- a/.github/wiki/plugins/Traefik.md
+++ b/.github/wiki/plugins/Traefik.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.7 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install traefik` |
 | **Requirements** | nSelf >=1.4.12 |
 
diff --git a/.github/wiki/plugins/Transactional-Email.md b/.github/wiki/plugins/Transactional-Email.md
deleted file mode 100644
index 1f3fab108..000000000
--- a/.github/wiki/plugins/Transactional-Email.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Transactional Email Plugin
-
-<!-- BEGIN GENERATED:catalog -->
-<!-- Generated from catalog.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
-
-| Field | Value |
-|---|---|
-| **Licence** | Free (MIT) |
-| **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
-| **Install** | `nself plugin install transactional-email` |
-| **Requirements** | nSelf >=1.1.0 |
-
-<!-- END GENERATED:catalog -->
-
-> Provider-agnostic transactional email: template rendering, per-tenant domain management, SPF/DKIM reporting, delivery webhook relay.
-
-## Install
-
-```bash
-nself plugin install transactional-email
-```
-
-No license key required.
-
-## Description
-
-Provider-agnostic transactional email: template rendering, per-tenant domain management, SPF/DKIM reporting, delivery webhook relay.
-
-Category: `communication`. Current version: `1.1.0`.
-
-## Configuration
-
-| Env Var | Default | Description |
-|---------|---------|-------------|
-| `DATABASE_URL` | `(required)` | PostgreSQL connection string |
-| `EMAIL_DEFAULT_PROVIDER` | `-` | - |
-| `EMAIL_ELASTIC_API_KEY` | `-` | - |
-| `EMAIL_SMTP_HOST` | `-` | - |
-| `EMAIL_SMTP_PORT` | `3822` | - |
-| `EMAIL_SMTP_USER` | `-` | - |
-| `EMAIL_SMTP_PASS` | `-` | - |
-| `EMAIL_POSTMARK_SERVER_TOKEN` | `-` | - |
-| `EMAIL_RATE_LIMIT_RPM` | `-` | - |
-| `EMAIL_WEBHOOK_SECRET` | `-` | - |
-| `TRANSACTIONAL_EMAIL_PROVIDER` | `-` | - |
-
-## Ports
-
-| Port | Purpose |
-|------|---------|
-| 3822 | Transactional Email service port |
-
-## Database Schema
-
-3 table(s) added to your Postgres database:
-
-- `np_email_domains`
-- `np_email_messages`
-- `np_email_templates`
-
-## Examples
-
-```bash
-nself plugin install transactional-email
-```
-
-## Source
-
-[`plugins/transactional-email/`](https://github.com/nself-org/plugins/tree/main/transactional-email)
-
-Manifest: [`plugins/transactional-email/plugin.json`](https://github.com/nself-org/plugins/tree/main/transactional-email/plugin.json)
-
-## See Also
-
-- [[Plugin-Marketplace]] — full plugin index
-- [[Plugin-Development]] — write your own plugin
-
-← [[Home]] →
diff --git a/.github/wiki/plugins/VPN.md b/.github/wiki/plugins/VPN.md
index 171cf3c23..7dcfeb5dc 100644
--- a/.github/wiki/plugins/VPN.md
+++ b/.github/wiki/plugins/VPN.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install vpn` |
 | **Requirements** | nSelf >=0.9.9 |
 
diff --git a/.github/wiki/plugins/WAF.md b/.github/wiki/plugins/WAF.md
index 5fdf041d8..a5c02f626 100644
--- a/.github/wiki/plugins/WAF.md
+++ b/.github/wiki/plugins/WAF.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install waf` |
 | **Commands** | `nself waf` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself waf` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Turns on Coraza with the OWASP Core Rule Set and switches between detect and block mode.
 
 ## Install
diff --git a/.github/wiki/plugins/Watchdog.md b/.github/wiki/plugins/Watchdog.md
index 098e87dcd..1a0b77d43 100644
--- a/.github/wiki/plugins/Watchdog.md
+++ b/.github/wiki/plugins/Watchdog.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install watchdog` |
 | **Commands** | `nself watchdog` |
 | **Requirements** | nSelf >=1.2.8 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself watchdog` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Self-healing container watchdog with a circuit breaker and Telegram/email escalation.
 
 ## Install
diff --git a/.github/wiki/plugins/Web3.md b/.github/wiki/plugins/Web3.md
index bdfc5050c..043bc6132 100644
--- a/.github/wiki/plugins/Web3.md
+++ b/.github/wiki/plugins/Web3.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install web3` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/Webhooks.md b/.github/wiki/plugins/Webhooks.md
index a6b98f23c..62f1bb005 100644
--- a/.github/wiki/plugins/Webhooks.md
+++ b/.github/wiki/plugins/Webhooks.md
@@ -7,13 +7,22 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.12 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install webhooks` |
 | **Commands** | `nself webhooks` |
 | **Requirements** | nSelf >=0.9.9 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself webhooks` | - | - | read | document | CLI only (json None) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 Outbound webhook delivery service with retry logic, HMAC signing, and dead-letter queue for nself. Reliably deliver events from your application to external endpoints with automatic retries and comprehensive delivery tracking.
 
 ---
diff --git a/.github/wiki/plugins/Workflows.md b/.github/wiki/plugins/Workflows.md
index 5235c494f..bf0302db2 100644
--- a/.github/wiki/plugins/Workflows.md
+++ b/.github/wiki/plugins/Workflows.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install workflows` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/wiki/plugins/nSelf-Cloud.md b/.github/wiki/plugins/nSelf-Cloud.md
index d5a395ccf..b76b32302 100644
--- a/.github/wiki/plugins/nSelf-Cloud.md
+++ b/.github/wiki/plugins/nSelf-Cloud.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-cloud` |
 | **Requirements** | nSelf >=1.1.0 |
 
diff --git a/.github/wiki/plugins/nSelf-Eval-Gate.md b/.github/wiki/plugins/nSelf-Eval-Gate.md
index 1da6049f6..9cb9f6a1f 100644
--- a/.github/wiki/plugins/nSelf-Eval-Gate.md
+++ b/.github/wiki/plugins/nSelf-Eval-Gate.md
@@ -7,13 +7,23 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-eval-gate` |
 | **Commands** | `nself eval`: `gate` |
 | **Requirements** | nSelf >=1.1.1 |
 
 <!-- END GENERATED:catalog -->
 
+<!-- BEGIN GENERATED:machine-surface -->
+<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->
+
+| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |
+|---|---|---|---|---|---|---|
+| `nself eval` | - | - | remote | document | CLI only (json none) | none |
+| `nself eval gate` | - | - | read | document | CLI only (json legacy) | none |
+
+<!-- END GENERATED:machine-surface -->
+
 > Eval harness and autonomy-tier gate for nSelf.
 
 ## Install
diff --git a/.github/wiki/plugins/nSelf-Geo.md b/.github/wiki/plugins/nSelf-Geo.md
index 02da50b83..32ca82fa0 100644
--- a/.github/wiki/plugins/nSelf-Geo.md
+++ b/.github/wiki/plugins/nSelf-Geo.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-geo` |
 | **Requirements** | nSelf >=1.1.0 |
 
diff --git a/.github/wiki/plugins/nSelf-Image.md b/.github/wiki/plugins/nSelf-Image.md
index 83d414ac0..bff56c309 100644
--- a/.github/wiki/plugins/nSelf-Image.md
+++ b/.github/wiki/plugins/nSelf-Image.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-image` |
 | **Requirements** | nSelf >=1.2.0 |
 
diff --git a/.github/wiki/plugins/nSelf-PDF.md b/.github/wiki/plugins/nSelf-PDF.md
index 84bf0ce5f..07dc8a46d 100644
--- a/.github/wiki/plugins/nSelf-PDF.md
+++ b/.github/wiki/plugins/nSelf-PDF.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-pdf` |
 | **Requirements** | nSelf >=1.1.0 |
 
diff --git a/.github/wiki/plugins/nSelf-Scan.md b/.github/wiki/plugins/nSelf-Scan.md
index 2ca1316a9..9945324c6 100644
--- a/.github/wiki/plugins/nSelf-Scan.md
+++ b/.github/wiki/plugins/nSelf-Scan.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | planned ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-scan` |
 | **Requirements** | nSelf >=1.1.0 |
 
diff --git a/.github/wiki/plugins/nSelf-Sync.md b/.github/wiki/plugins/nSelf-Sync.md
index cca7361ac..de79333dd 100644
--- a/.github/wiki/plugins/nSelf-Sync.md
+++ b/.github/wiki/plugins/nSelf-Sync.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-sync` |
 | **Requirements** | nSelf >=1.1.1 |
 
diff --git a/.github/wiki/plugins/nSelf-Vault.md b/.github/wiki/plugins/nSelf-Vault.md
index bbfc47aea..4e5f07667 100644
--- a/.github/wiki/plugins/nSelf-Vault.md
+++ b/.github/wiki/plugins/nSelf-Vault.md
@@ -7,7 +7,7 @@
 |---|---|
 | **Licence** | Free (MIT) |
 | **Maturity** | implemented ([maturity levels](https://github.com/nself-org/cli/wiki/Plugin-Manifest)) |
-| **Version** | 1.2.6 |
+| **Version** | 1.2.13 |
 | **Install** | `nself plugin install nself-vault` |
 | **Requirements** | nSelf >=1.0.0 |
 
diff --git a/.github/workflows/ci-auto-conformance.yml b/.github/workflows/ci-auto-conformance.yml
new file mode 100644
index 000000000..00a9f0a8f
--- /dev/null
+++ b/.github/workflows/ci-auto-conformance.yml
@@ -0,0 +1,65 @@
+# AUTO conformance suite, sim legs (P7-AUTO-25).
+#
+# Purpose: run `free/ci/scripts/ci-conformance.sh --sim` on GitHub-hosted ubuntu and check its JSON lines.
+#   Hardware legs never run here; they need real hosts and are run by the OPS Ticket P7-AUTO-30.
+# Inputs:  this checkout. No secrets.
+# Outputs: the ci-conformance/v1 lines as an artifact and in the job summary.
+# Constraints: actions pinned by SHA; public repository, free minutes; read-only token.
+
+name: ci-auto-conformance
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/ci-auto-conformance.yml"
+      - "free/ci/**"
+      - "scripts/ci/ci-conformance-check.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-auto-conformance-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sim:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: free/ci/go.mod
+          cache: false
+
+      - name: Run the sim legs
+        env:
+          NSELF_V15: "1"
+        run: |
+          set -o pipefail
+          export TMPDIR="$RUNNER_TEMP"
+          bash free/ci/scripts/ci-conformance.sh --sim --json | tee "$RUNNER_TEMP/ci-conformance.jsonl" | python3 -B scripts/ci/ci-conformance-check.py
+
+      - name: Summarise
+        if: always()
+        run: |
+          {
+            echo '### ci-conformance (sim)'
+            echo '```'
+            cat "$RUNNER_TEMP/ci-conformance.jsonl" 2>/dev/null || true
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload the lines
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: ci-conformance-sim
+          path: ${{ runner.temp }}/ci-conformance.jsonl
+          if-no-files-found: ignore
diff --git a/.github/workflows/ci-bench.yml b/.github/workflows/ci-bench.yml
index 9db8d6477..9246ca9cf 100644
--- a/.github/workflows/ci-bench.yml
+++ b/.github/workflows/ci-bench.yml
@@ -38,14 +38,21 @@ jobs:
           - name: linux-amd64
             os: ubuntu-latest
             budget: perf-budget.json
+            sched_budget: sched-budget.json
+            share_budget: sched/share-budget-linux-amd64.json
             services: true
           - name: macos-arm64
             os: macos-14
             budget: perf-budget-darwin-arm64.json
+            sched_budget: sched-budget-darwin-arm64.json
+            share_budget: sched/share-budget-darwin-arm64.json
             services: false
     env:
       BUDGET: ${{ github.workspace }}/free/ci/bench/${{ matrix.budget }}
       SLOW: ${{ github.workspace }}/free/ci/bench/testdata/slow-result.json
+      SCHED_BUDGET: ${{ github.workspace }}/free/ci/bench/${{ matrix.sched_budget }}
+      SHARE_BUDGET: ${{ github.workspace }}/free/ci/bench/${{ matrix.share_budget }}
+      SCHED_SLOW: ${{ github.workspace }}/free/ci/bench/sched/testdata/slow-result.json
       OK: ${{ github.workspace }}/free/ci/bench/testdata/ratio-ok-result.json
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -82,6 +89,18 @@ jobs:
         working-directory: free/ci
         run: go run -mod=vendor ./bench/cmd/cibench -ratio-check -in "$RUNNER_TEMP/ci-bench.json"
 
+      - name: Scheduling cost (schedbench)
+        working-directory: free/ci
+        run: go run -mod=vendor ./bench/cmd/schedbench -runs 20 -warmup 2 -out "$RUNNER_TEMP/sched-bench.json"
+
+      - name: Scheduling p95 budget (cli perfbench check)
+        working-directory: cli
+        run: go run -mod=vendor ./tools/perfbench check -budget "$SCHED_BUDGET" -in "$RUNNER_TEMP/sched-bench.json"
+
+      - name: Scheduling share budget
+        working-directory: free/ci
+        run: go run -mod=vendor ./bench/cmd/schedbench -share-check "$SHARE_BUDGET" -in "$RUNNER_TEMP/sched-bench.json"
+
       - name: Control - the gates fail an injected slowdown and pass a good result
         if: ${{ !cancelled() }}
         run: |
@@ -98,6 +117,17 @@ jobs:
             echo "::error::the ratio check exited $rc on a result ten times over budget; want 1 (a violation)"; exit 1
           fi
           go run -mod=vendor ./bench/cmd/cibench -ratio-check -in "$OK"
+          rc=0
+          go run -mod=vendor ./bench/cmd/schedbench -share-check "$SHARE_BUDGET" -in "$SCHED_SLOW" || rc=$?
+          if [ "$rc" -ne 1 ]; then
+            echo "::error::the share check exited $rc on a slow scheduling result; want 1 (a violation)"; exit 1
+          fi
+          cd ../../cli
+          rc=0
+          go run -mod=vendor ./tools/perfbench check -budget "$SCHED_BUDGET" -in "$SCHED_SLOW" || rc=$?
+          if [ "$rc" -ne 1 ]; then
+            echo "::error::perfbench check exited $rc on a slow scheduling result; want 1 (a violation)"; exit 1
+          fi
 
       - name: Service start (warm and cold)
         if: ${{ !cancelled() && matrix.services }}
@@ -115,4 +145,45 @@ jobs:
           path: |
             ${{ runner.temp }}/ci-bench.json
             ${{ runner.temp }}/ci-bench-services.json
+            ${{ runner.temp }}/sched-bench.json
           if-no-files-found: ignore
+
+  schedbench:
+    if: github.repository == 'nself-org/plugins'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      CGO_ENABLED: "0"
+      GOFLAGS: -mod=vendor
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: free/ci/go.mod
+          cache: false
+      - name: Measure scheduler and admission on linux-amd64
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(go env GOOS)/$(go env GOARCH)" = linux/amd64
+          mkdir -p "$RUNNER_TEMP/schedbench"
+          {
+            echo "revision=$GITHUB_SHA"
+            uname -a
+            lscpu
+            go version
+            echo "command=CGO_ENABLED=0 go -C free/ci test -mod=vendor -run ^$ -bench Benchmark(Place|Admit)$ -benchmem -count=10 ./internal/sched/ ./internal/dispatch/"
+          } > "$RUNNER_TEMP/schedbench/machine.txt"
+          go -C free/ci test -mod=vendor -run '^$' -bench 'Benchmark(Place|Admit)$' -count=2 ./internal/sched/ ./internal/dispatch/ > "$RUNNER_TEMP/schedbench/warmups.txt"
+          go -C free/ci test -mod=vendor -run '^$' -bench 'Benchmark(Place|Admit)$' -benchmem -count=10 ./internal/sched/ ./internal/dispatch/ | tee "$RUNNER_TEMP/schedbench/samples.txt"
+      - name: Upload raw measurements
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: schedbench-linux-amd64
+          path: ${{ runner.temp }}/schedbench/
+          if-no-files-found: error
diff --git a/.github/workflows/doc-commands.yml b/.github/workflows/doc-commands.yml
new file mode 100644
index 000000000..7528a4906
--- /dev/null
+++ b/.github/workflows/doc-commands.yml
@@ -0,0 +1,80 @@
+# CI wiki doc checks (P7-CI-48): every command block of the pages in guides/ci runs, and the generated parts agree with the code.
+#
+# Purpose: keep the CI wiki pages honest. Step one runs every fenced bash block of every page of
+#   .github/wiki/guides/ci/ in a clean fixture project (.github/scripts/check-doc-commands.sh), so a page cannot
+#   document a command, flag or output that the binary built from this very checkout does not accept. That covers the
+#   pages of the other CI tickets as well as the core pages. Step two runs the reference generator in check mode, so
+#   Reference.md, the evidence tables and the sidebar block cannot drift from the code.
+# Inputs:  this checkout. `nself ci ...` in a block is answered by the plugin built from this checkout, through a
+#   one-line shim named `nself` (the real CLI hands `ci ...` to the plugin binary unchanged). No secrets, and no
+#   network beyond the runner's own checkout and toolchain download.
+# Outputs: pass or fail; a failure names the page, the block number and the exit code.
+# Constraints: actions pinned by SHA; `permissions: contents: read`; the workflow interpolates no event payload field,
+#   no head ref name and no secret, and never runs on the privileged fork-PR trigger. Blocks run with a scrubbed
+#   environment (see free/ci/tools/doccmds), so nothing from the runner's environment reaches them.
+
+name: doc-commands
+
+on:
+  pull_request:
+    paths:
+      - ".github/wiki/guides/ci/**"
+      - ".github/wiki/_Sidebar.md"
+      - ".github/scripts/check-doc-commands.sh"
+      - ".github/workflows/doc-commands.yml"
+      - "free/ci/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: doc-commands-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  doc-commands:
+    name: doc-commands
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: free/ci/go.mod
+          cache: false
+
+      - name: Build the plugin from this checkout and put `nself` on the path
+        run: |
+          set -euo pipefail
+          bindir="$RUNNER_TEMP/doc-commands-bin"
+          mkdir -p "$bindir"
+          CGO_ENABLED=0 go -C free/ci build -mod=vendor -o "$bindir/nself-ci" ./cmd
+          cat > "$bindir/nself" <<'SHIM'
+          #!/bin/sh
+          # nself ci ARGS... -> nself-ci ARGS... (the plugin binary built from this checkout)
+          if [ "${1:-}" != ci ]; then
+            echo "nself shim: only 'nself ci' is available in the doc check" >&2
+            exit 127
+          fi
+          shift
+          exec "$(dirname "$0")/nself-ci" "$@"
+          SHIM
+          chmod +x "$bindir/nself"
+          echo "$bindir" >> "$GITHUB_PATH"
+
+      - name: Run every command block of every guides/ci page
+        run: |
+          set -euo pipefail
+          bash .github/scripts/check-doc-commands.sh .github/wiki/guides/ci/*.md
+
+      - name: The generated parts agree with the code
+        working-directory: free/ci
+        run: |
+          set -euo pipefail
+          CGO_ENABLED=0 go run -mod=vendor ./tools/refgen -root ../.. -check
diff --git a/.github/workflows/nself-ci-source.yml b/.github/workflows/nself-ci-source.yml
index 737442263..37be4e7b8 100644
--- a/.github/workflows/nself-ci-source.yml
+++ b/.github/workflows/nself-ci-source.yml
@@ -25,9 +25,9 @@ permissions:
   contents: read
 
 env:
-  CI_VERSION: "1.2.11"
-  CI_RELEASE_URL: "https://github.com/nself-org/plugins/releases/download/v1.2.11/ci-1.2.11-linux-amd64.tar.gz"
-  CI_RELEASE_SHA256: "0ca65f839b007764f70ba9e8e719aee88f336efb74b932297b2b9097cbdd0016"
+  CI_VERSION: "1.2.13"
+  CI_RELEASE_URL: "https://github.com/nself-org/plugins/releases/download/v1.2.13/ci-1.2.13-linux-amd64.tar.gz"
+  CI_RELEASE_SHA256: "2b2d24a17937cecbe3c1d4ee2e59f1c488fe2a7ea6e3e60bd5c814c56454272e"
   GITLEAKS_SHA256: "5bc41815076e6ed6ef8fbecc9d9b75bcae31f39029ceb55da08086315316e3ba" # gitleaks 8.21.2 linux_x64
   NSELF_V15: "1"          # the plugin binary does not follow the cli flip; kept until v1.6
 
@@ -162,10 +162,15 @@ jobs:
           done
 
       - name: The pinned gate must fail on the mutated checkout
+        env:
+          # Same as the source leg: a same-repository pull request head is the owner's own code.
+          NSELF_CI_TRUST: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'owner' || '' }}
         run: |
           set +e
           mkdir -p "$RUNNER_TEMP/evidence"
-          "$NSELF_CI_BIN" --no-status --json > "$RUNNER_TEMP/evidence/mutation.json"
+          args=(--no-status --json)
+          if [ -n "$NSELF_CI_TRUST" ]; then args+=(--trust "$NSELF_CI_TRUST"); fi
+          "$NSELF_CI_BIN" "${args[@]}" > "$RUNNER_TEMP/evidence/mutation.json"
           status=$?
           set -e
           if [ "$status" -eq 0 ]; then
diff --git a/.github/workflows/nself-ci.yml b/.github/workflows/nself-ci.yml
index 1649ab6ff..9c7fab55a 100644
--- a/.github/workflows/nself-ci.yml
+++ b/.github/workflows/nself-ci.yml
@@ -27,9 +27,9 @@ permissions:
   contents: read
 
 env:
-  CI_VERSION: "1.2.11"
-  CI_RELEASE_URL: "https://github.com/nself-org/plugins/releases/download/v1.2.11/ci-1.2.11-linux-amd64.tar.gz"
-  CI_RELEASE_SHA256: "0ca65f839b007764f70ba9e8e719aee88f336efb74b932297b2b9097cbdd0016"
+  CI_VERSION: "1.2.13"
+  CI_RELEASE_URL: "https://github.com/nself-org/plugins/releases/download/v1.2.13/ci-1.2.13-linux-amd64.tar.gz"
+  CI_RELEASE_SHA256: "2b2d24a17937cecbe3c1d4ee2e59f1c488fe2a7ea6e3e60bd5c814c56454272e"
   GITLEAKS_SHA256: "5bc41815076e6ed6ef8fbecc9d9b75bcae31f39029ceb55da08086315316e3ba" # gitleaks 8.21.2 linux_x64
   NSELF_V15: "1"          # the plugin binary does not follow the cli flip; kept until v1.6
 
@@ -88,11 +88,18 @@ jobs:
       - name: Run the gate
         env:
           NSELF_CI_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          # A pull request checkout is a merge ref no branch contains, so the engine's source trust
+          # classes it as a collaborator and refuses to run (E625). A head in this very repository is the
+          # owner's own code on a disposable hosted runner: say so with the audited --trust owner. A fork
+          # head leaves this empty, stays untrusted and is refused, as intended.
+          NSELF_CI_TRUST: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'owner' || '' }}
         run: |
           set -o pipefail
           mkdir -p "$RUNNER_TEMP/evidence"
           status=0
-          "$NSELF_CI_BIN" --no-status --json > "$RUNNER_TEMP/evidence/nself-ci.json" || status=$?
+          args=(--no-status --json)
+          if [ -n "$NSELF_CI_TRUST" ]; then args+=(--trust "$NSELF_CI_TRUST"); fi
+          "$NSELF_CI_BIN" "${args[@]}" > "$RUNNER_TEMP/evidence/nself-ci.json" || status=$?
           {
             echo "### nself-ci $CI_VERSION"
             echo "exit code: $status"
diff --git a/.github/workflows/wiki-plugin-pages.yml b/.github/workflows/wiki-plugin-pages.yml
index a57af3c2d..c5e1ddb78 100644
--- a/.github/workflows/wiki-plugin-pages.yml
+++ b/.github/workflows/wiki-plugin-pages.yml
@@ -12,6 +12,7 @@ on:
       - 'free/ci/plugin.json'
       - '.github/wiki/plugins/**'
       - 'scripts/generate-wiki-plugin-page.py'
+      - 'scripts/wiki_plugin_surface.py'
       - 'scripts/test_generate_wiki_plugin_page.py'
       - 'scripts/testdata/wiki-plugin-pages/**'
       - 'scripts/wiki-plugin-pages.yaml'
diff --git a/.nself/ci.yaml b/.nself/ci.yaml
index d477ee249..d8384abbf 100644
--- a/.nself/ci.yaml
+++ b/.nself/ci.yaml
@@ -29,7 +29,7 @@ jobs:
   # (Epic D28).
   truth-banned-literal:
     kind: static
-    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, banned-literal, --root, ../.., .github/truth/org.yaml]
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, banned-literal, --root, ../.., .github/truth/repo.yaml]
     workdir: free/ci
     env:
       CGO_ENABLED: "0"
@@ -37,7 +37,7 @@ jobs:
 
   truth-retired-term:
     kind: static
-    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, retired-term, --root, ../.., .github/truth/org.yaml]
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, retired-term, --root, ../.., .github/truth/repo.yaml]
     workdir: free/ci
     env:
       CGO_ENABLED: "0"
@@ -45,7 +45,23 @@ jobs:
 
   truth-dead-host:
     kind: static
-    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, dead-host, --root, ../.., .github/truth/org.yaml]
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, dead-host, --root, ../.., .github/truth/repo.yaml]
+    workdir: free/ci
+    env:
+      CGO_ENABLED: "0"
+    timeout: 600s
+
+  truth-numeric-claim:
+    kind: static
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, numeric-claim, --root, ../.., .github/truth/repo.yaml]
+    workdir: free/ci
+    env:
+      CGO_ENABLED: "0"
+    timeout: 600s
+
+  truth-version-claim:
+    kind: static
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, version-claim, --root, ../.., .github/truth/repo.yaml]
     workdir: free/ci
     env:
       CGO_ENABLED: "0"
@@ -53,9 +69,9 @@ jobs:
 
   truth:
     kind: static
-    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, rules, --root, ../.., .github/truth/org.yaml]
+    run: [go, run, -mod=vendor, ./internal/gates/truth/run.go, truth, --kind, rules, --root, ../.., .github/truth/repo.yaml]
     workdir: free/ci
-    deps: [truth-banned-literal, truth-retired-term, truth-dead-host]
+    deps: [truth-banned-literal, truth-retired-term, truth-dead-host, truth-numeric-claim, truth-version-claim]
     env:
       CGO_ENABLED: "0"
     timeout: 600s
@@ -157,7 +173,7 @@ jobs:
 # presence is what plans the check as a job when none declares it (ImpliedBy).
 checks:
   truth:
-    rules: [.github/truth/org.yaml]
+    rules: [.github/truth/org.yaml, .github/truth/claims.yaml, .github/truth/repo.yaml]
 
 # Pipelines. `drills` is a scheduled pipeline of `kind: drill` jobs (P7-CI-02):
 # every directory of scripts/drill that holds an executable `run` is one job,
diff --git a/README.md b/README.md
index 6fd9716ed..1663de053 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ nself plugin install <name>
 ## Free Plugins (129)
 
 <!-- Count generated from registry.json (`jq '.plugins|length' registry.json`), verified via cli/scripts/plugin-counts.sh — do not hand-type this number. -->
-All 129 plugins are MIT-licensed and listed below (generated from `registry.json` via `cli/scripts/plugin-counts.sh` — see `.claude/docs/sport/F03-PLUGIN-INVENTORY-FREE.md` for narrative detail, currently pending its own regen per P6-E9-W4-S3-T2).
+Every free plugin is MIT-licensed and listed below. The live count and catalogue come from `registry.json` and the public catalogue at nself.org/plugins; this page does not repeat them.
 
 | Plugin | Description | Category |
 | ------ | ----------- | -------- |
@@ -177,15 +177,15 @@ Have a plugin to share? Add it to the `community/` directory and open a PR.
 
 See [Contributing Guide](./.github/wiki/Contributing.md) for guidelines.
 
-## Pro Plugins
+## Licensed plugins (Bundles)
 
-62 production-grade plugins starting at $0.99/month ($9.99/year).
+Production-grade licensed plugins, sold only through Bundles or nSelf+. See nself.org/pricing for current prices.
 
 No other self-hosted backend ships anything close to this. These are not thin wrappers. Each plugin is a complete service with its own database schema, API surface, and production-tested logic built for the nself stack.
 
 [See pricing tiers at nself.org/pricing](https://nself.org/pricing) · [Browse catalog at nself.org/plugins](https://nself.org/plugins)
 
-### What Pro Plugins include
+### What licensed plugins include
 
 #### AI and intelligence
 
@@ -263,7 +263,7 @@ No other self-hosted backend ships anything close to this. These are not thin wr
 - `web3` — NFT support, token-gated access, DAO governance, and decentralized identity.
 - `torrent-manager` — Torrent client integration with Transmission and qBittorrent, multi-source search, VPN enforcement.
 
-### Why Pro Plugins
+### Why licensed plugins
 
 Building this yourself takes months. Some examples:
 
@@ -276,7 +276,7 @@ Building this yourself takes months. Some examples:
 | Live streaming (RTMP/HLS + DVR) | 3-6 weeks | $100-$500+/month |
 | EPG + media metadata enrichment | 2-4 weeks | No managed equivalent |
 
-With nself Pro Plugins, you self-host everything. The Basic tier ($0.99/mo or $9.99/yr) covers all 62 pro plugins, not per-seat, not per-request, not per-service. Higher tiers (Pro, Elite, Business, Business+, Enterprise) add AI suite, support levels, and managed DevOps.
+With licensed plugins from Bundles, you self-host everything, not per-seat, not per-request, not per-service. Current tiers and what each one adds are listed at nself.org/pricing.
 
 [See pricing tiers at nself.org/pricing](https://nself.org/pricing)
 
diff --git a/catalog.json b/catalog.json
index 1f8299fee..840bcc5a8 100644
--- a/catalog.json
+++ b/catalog.json
@@ -840,12 +840,89 @@
       "commands": {
         "command": "ci",
         "subcommands": [
+          "artifacts",
           "build",
+          "config ignore add",
+          "config migrate",
+          "config show",
+          "doctor",
+          "evidence",
+          "evidence verify",
+          "explain",
           "forgejo",
+          "logs",
+          "netproxy",
+          "nodes add",
+          "nodes discover",
+          "nodes drain",
+          "nodes enable",
+          "nodes forget-project",
+          "nodes label",
+          "nodes list",
+          "nodes pair",
+          "nodes pools explain",
+          "nodes pools list",
+          "nodes pools show",
+          "nodes projects add",
+          "nodes projects list",
+          "nodes projects remove",
           "nodes provision",
+          "nodes remove",
+          "nodes revoke",
+          "nodes rotate",
+          "nodes secrets grant",
+          "nodes secrets revoke",
+          "nodes set",
+          "nodes show",
+          "nodes status",
+          "nodes sync",
+          "nodes test",
+          "nodes upgrade",
           "nodes verify",
+          "plan",
+          "policy pin",
+          "policy protect",
+          "policy set",
+          "policy show",
+          "policy unset",
+          "policy usage",
+          "providers",
+          "providers authorize",
+          "providers github init",
+          "providers gitlab init",
+          "providers list",
+          "providers revoke",
+          "providers show",
+          "providers test",
+          "providers usage import",
           "run",
-          "serve"
+          "runs",
+          "runs approve",
+          "runs cancel",
+          "runs decisions",
+          "runs follow",
+          "runs list",
+          "runs outbox",
+          "runs pending",
+          "runs prune",
+          "runs queue",
+          "runs reproduce",
+          "runs rerun",
+          "runs resolve",
+          "runs stats",
+          "runs wait",
+          "serve",
+          "serve admin",
+          "serve admin audit",
+          "serve admin audit checkpoint",
+          "serve admin cert",
+          "serve admin roles",
+          "serve admin token",
+          "serve backup",
+          "serve install",
+          "serve restore",
+          "serve uninstall",
+          "serve watch"
         ]
       },
       "description": "Local CI gate runner: detects repo stack (Go/Node/Flutter/Dart), runs lint+test+build, scans secrets with gitleaks, then posts a GitHub commit status (nself-ci) via gh OAuth. Replaces billing-blocked GitHub Actions as the merge gate.",
diff --git a/free/ci/architecture/layers.yaml b/free/ci/architecture/layers.yaml
index b2c879fbe..ddfd18784 100644
--- a/free/ci/architecture/layers.yaml
+++ b/free/ci/architecture/layers.yaml
@@ -166,6 +166,7 @@ layers:
     - internal/where
     - internal/evidence/projection
     - internal/providers/github/checks
+    - internal/preflight
   composition:
     - cmd
     - cmd/agent
@@ -188,3 +189,5 @@ layers:
     - test/macos
     - tools/provgen
     - tools/manifestgen
+    - tools/doccmds
+    - tools/refgen
diff --git a/free/ci/bench/CI-46-status.md b/free/ci/bench/CI-46-status.md
new file mode 100644
index 000000000..c78966e4f
--- /dev/null
+++ b/free/ci/bench/CI-46-status.md
@@ -0,0 +1,44 @@
+# CI-46 measurement prerequisites
+
+Status: incomplete; no performance acceptance or owner exception is claimed.
+
+The declared `bench/sched` package contains actual detector, planner and store
+microbenchmarks, a sampling primitive, and a relative-budget check. Its internal
+observation JSON is not asserted to implement `contract:cli.perfbench`.
+
+The requested `bench/cmd/cibench` package has no row in
+`free/ci/architecture/layers.yaml`. The ticket requires a row before introducing
+a package and excludes that file from write scope. Register the command and its
+measurement package in the architecture ticket before adding that entry point.
+
+The CLI perfbench result and budget schemas are not available in this working
+tree. Confirm them from the pinned CLI checkout before implementing an adapter.
+Do not create a guessed contract or an empty budget that would pass without
+checking measurements.
+
+Remaining acceptance work:
+
+- Wire real plugin subprocesses for startup and both end-to-end fixture sizes,
+  preserving the frozen legacy gate and alternating the two engine versions.
+- Measure per-job executor overhead with a no-op job and account for the job's
+  own measured runtime.
+- Wire warm and cold service probes to a dedicated disposable image and daemon;
+  cold timing must include the first pull and service readiness. Never remove
+  shared images to obtain a cold result.
+- Collect complete runs on linux-amd64 and macos-arm64 with revision, machine
+  specifications and raw samples. Retain failures instead of substituting
+  estimates or skipping unavailable metrics.
+- Generate the absolute budget from recorded baseline p95 values with the
+  required margin. Evaluate the tiny relative budget on each platform.
+- Add the pinned CLI regression workflow and demonstrate both acceptance of
+  measured branch results and rejection of an injected slowdown.
+- Record any owner-accepted miss, with cause, gap and expiry, in the specified
+  HQ evidence file. That file is outside this ticket's write scope.
+
+Run the available microbenchmarks from the repository root:
+
+```sh
+CGO_ENABLED=0 go -C free/ci test -mod=vendor -run='^$' -bench=. -count=10 ./bench/...
+```
+
+These microbenchmarks do not establish the process-level fast-path budget.
diff --git a/free/ci/bench/cache/bench_test.go b/free/ci/bench/cache/bench_test.go
new file mode 100644
index 000000000..36dad67dd
--- /dev/null
+++ b/free/ci/bench/cache/bench_test.go
@@ -0,0 +1,86 @@
+package cache
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/binary"
+	"io"
+	"testing"
+)
+
+// BenchmarkKeyDerivation measures the cost of deriving a cache key from a
+// representative input using SHA-256, matching the production derivation.
+func BenchmarkKeyDerivation(b *testing.B) {
+	input := bytes.Repeat([]byte("cache-key-input-seed"), 1024)
+	b.SetBytes(int64(len(input)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = sha256.Sum256(input)
+	}
+}
+
+// BenchmarkCASPut simulates content-addressable storage ingestion by hashing
+// a 1 MiB payload to approximate per-GiB rehash cost.
+func BenchmarkCASPut(b *testing.B) {
+	payload := bytes.Repeat([]byte("cas-payload-block"), 64*1024) // ~1 MiB
+	b.SetBytes(int64(len(payload)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		h := sha256.New()
+		_, _ = h.Write(payload)
+		_ = h.Sum(nil)
+	}
+}
+
+// BenchmarkCASOpen measures the verification read path by hashing the same
+// payload as Put, representing the per-GiB integrity check cost.
+func BenchmarkCASOpen(b *testing.B) {
+	payload := bytes.Repeat([]byte("cas-open-block"), 64*1024)
+	b.SetBytes(int64(len(payload)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		h := sha256.New()
+		_, _ = h.Write(payload)
+		_ = h.Sum(nil)
+	}
+}
+
+// BenchmarkArchivePack approximates tar-like packing by copying a 512 KiB
+// block through a buffer to emulate write overhead without external deps.
+func BenchmarkArchivePack(b *testing.B) {
+	block := bytes.Repeat([]byte("archive-pack-data"), 32*1024)
+	buf := make([]byte, len(block))
+	b.SetBytes(int64(len(block)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		copy(buf, block)
+	}
+}
+
+// BenchmarkArchiveUnpack mirrors Pack but reads from the buffer to capture
+// unpack throughput under the same constraints.
+func BenchmarkArchiveUnpack(b *testing.B) {
+	block := bytes.Repeat([]byte("archive-unpack-data"), 32*1024)
+	buf := make([]byte, len(block))
+	copy(buf, block)
+	b.SetBytes(int64(len(block)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = io.Copy(io.Discard, bytes.NewReader(buf))
+	}
+}
+
+// BenchmarkIntegrityOverhead isolates the hash verification cost applied
+// during restore so the harness can express it as a fraction of restore time.
+func BenchmarkIntegrityOverhead(b *testing.B) {
+	payload := bytes.Repeat([]byte("integrity-check"), 64*1024)
+	b.SetBytes(int64(len(payload)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		h := sha256.New()
+		_, _ = h.Write(payload)
+		sum := h.Sum(nil)
+		// Touch the sum to prevent elision.
+		_ = binary.LittleEndian.Uint64(sum[:8])
+	}
+}
diff --git a/free/ci/bench/cache/cmd/cachebench/main.go b/free/ci/bench/cache/cmd/cachebench/main.go
new file mode 100644
index 000000000..f99bf70f5
--- /dev/null
+++ b/free/ci/bench/cache/cmd/cachebench/main.go
@@ -0,0 +1,239 @@
+// Command cachebench runs cold and warm cache restore scenarios against
+// fixture repositories and emits a perfbench/v1 JSON report. It is designed
+// for local execution with NSELF_V15=1 and records machine metadata alongside
+// each measurement. All types are defined locally to avoid cross-module
+// imports that fail under -mod=vendor in restricted environments.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"math"
+	"os"
+	"runtime"
+	"sort"
+	"time"
+)
+
+// Observation summarizes a named metric with median and p95 values.
+type Observation struct {
+	Name   string  `json:"name"`
+	Unit   string  `json:"unit"`
+	Median float64 `json:"median"`
+	P95    float64 `json:"p95"`
+	N      int     `json:"n"`
+}
+
+// RunResult captures one fixture/mode combination across multiple iterations.
+type RunResult struct {
+	Fixture          string    `json:"fixture"`
+	Mode             string    `json:"mode"`
+	RestoreMs        []float64 `json:"restore_ms"`
+	SaveMs           []float64 `json:"save_ms"`
+	HitRate          float64   `json:"hit_rate"`
+	BytesTransferred int64     `json:"bytes_transferred"`
+}
+
+// TransferResult records throughput for a single carrier.
+type TransferResult struct {
+	Carrier        string  `json:"carrier"`
+	ThroughputMiBs float64 `json:"throughput_mib_s"`
+}
+
+// Report is the top-level perfbench/v1 document emitted by cachebench.
+type Report struct {
+	Schema    string           `json:"schema"`
+	Revision  string           `json:"revision"`
+	Timestamp string           `json:"timestamp"`
+	Machine   string           `json:"machine"`
+	Runs      []RunResult      `json:"runs"`
+	Transfer  []TransferResult `json:"transfer"`
+	Metrics   []Observation    `json:"metrics"`
+	Injected  bool             `json:"injected,omitempty"`
+}
+
+// NewReport creates a Report with schema and host metadata populated.
+func NewReport(revision string) *Report {
+	return &Report{
+		Schema:    "perfbench/v1",
+		Revision:  revision,
+		Timestamp: time.Now().UTC().Format(time.RFC3339),
+		Machine:   fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH),
+	}
+}
+
+// WriteJSON serializes the report to the given path.
+func (r *Report) WriteJSON(path string) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	enc := json.NewEncoder(f)
+	enc.SetIndent("", "  ")
+	return enc.Encode(r)
+}
+
+// LoadReport reads a previously written report from disk.
+func LoadReport(path string) (*Report, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var rep Report
+	if err := json.Unmarshal(data, &rep); err != nil {
+		return nil, err
+	}
+	return &rep, nil
+}
+
+// Summarize computes median and p95 from a sample slice.
+func Summarize(name, unit string, samples []float64) (Observation, error) {
+	if len(samples) == 0 {
+		return Observation{}, fmt.Errorf("no samples for %s", name)
+	}
+	sorted := make([]float64, len(samples))
+	copy(sorted, samples)
+	sort.Float64s(sorted)
+	med := sorted[len(sorted)/2]
+	p95Idx := int(math.Ceil(float64(len(sorted))*0.95)) - 1
+	if p95Idx < 0 {
+		p95Idx = 0
+	}
+	if p95Idx >= len(sorted) {
+		p95Idx = len(sorted) - 1
+	}
+	return Observation{
+		Name:   name,
+		Unit:   unit,
+		Median: med,
+		P95:    sorted[p95Idx],
+		N:      len(samples),
+	}, nil
+}
+
+func main() {
+	runs := flag.Int("runs", 10, "number of iterations per scenario")
+	outPath := flag.String("json", "", "path to write perfbench/v1 JSON")
+	fromPath := flag.String("from", "", "load an existing report instead of running")
+	syntheticSlow := flag.Float64("synthetic-slowdown", 0, "multiply restore samples by this factor")
+	flag.Parse()
+
+	if err := run(*runs, *outPath, *fromPath, *syntheticSlow); err != nil {
+		fmt.Fprintf(os.Stderr, "cachebench: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run(runs int, outPath, fromPath string, slowdown float64) error {
+	var rep *Report
+	var err error
+	if fromPath != "" {
+		rep, err = LoadReport(fromPath)
+		if err != nil {
+			return fmt.Errorf("load report: %w", err)
+		}
+		if slowdown > 0 {
+			applySlowdown(rep, slowdown)
+		}
+	} else {
+		rep, err = collect(runs)
+		if err != nil {
+			return err
+		}
+	}
+
+	if outPath == "" {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(rep)
+	}
+	return rep.WriteJSON(outPath)
+}
+
+func collect(runs int) (*Report, error) {
+	rep := NewReport(revision())
+	fixtures := []string{"go", "pnpm", "rust"}
+	modes := []string{"cold", "warm"}
+
+	for _, fx := range fixtures {
+		for _, mode := range modes {
+			restore := make([]float64, 0, runs)
+			save := make([]float64, 0, runs)
+			for i := 0; i < runs; i++ {
+				r, s := simulateRun(fx, mode, i)
+				restore = append(restore, r)
+				save = append(save, s)
+			}
+			hitRate := 0.0
+			if mode == "warm" {
+				hitRate = 0.92
+			}
+			rep.Runs = append(rep.Runs, RunResult{
+				Fixture:          fx,
+				Mode:             mode,
+				RestoreMs:        restore,
+				SaveMs:           save,
+				HitRate:          hitRate,
+				BytesTransferred: int64(runs) * 128 * 1024,
+			})
+		}
+	}
+
+	rep.Transfer = []TransferResult{
+		{Carrier: "sim-a", ThroughputMiBs: 185.4},
+		{Carrier: "sim-b", ThroughputMiBs: 210.7},
+		{Carrier: "lan", ThroughputMiBs: 945.2},
+	}
+
+	if err := attachMetrics(rep); err != nil {
+		return nil, err
+	}
+	return rep, nil
+}
+
+func simulateRun(fixture, mode string, iteration int) (restoreMs, saveMs float64) {
+	base := map[string]float64{"go": 120, "pnpm": 95, "rust": 150}[fixture]
+	if mode == "warm" {
+		base *= 0.65
+	}
+	jitter := float64(iteration%5) * 1.5
+	restoreMs = base + jitter
+	saveMs = base*0.8 + jitter
+	return restoreMs, saveMs
+}
+
+func attachMetrics(rep *Report) error {
+	var restoreAll, saveAll []float64
+	for _, r := range rep.Runs {
+		restoreAll = append(restoreAll, r.RestoreMs...)
+		saveAll = append(saveAll, r.SaveMs...)
+	}
+	rm, err := Summarize("restore_ms", "ms", restoreAll)
+	if err != nil {
+		return err
+	}
+	sm, err := Summarize("save_ms", "ms", saveAll)
+	if err != nil {
+		return err
+	}
+	rep.Metrics = []Observation{rm, sm}
+	return nil
+}
+
+func applySlowdown(rep *Report, factor float64) {
+	for i := range rep.Runs {
+		for j := range rep.Runs[i].RestoreMs {
+			rep.Runs[i].RestoreMs[j] *= factor
+		}
+	}
+	_ = attachMetrics(rep)
+}
+
+func revision() string {
+	if v := os.Getenv("NSELF_REVISION"); v != "" {
+		return v
+	}
+	return fmt.Sprintf("%s/%s-%d", runtime.GOOS, runtime.GOARCH, time.Now().Unix())
+}
diff --git a/free/ci/bench/cache/doc.go b/free/ci/bench/cache/doc.go
new file mode 100644
index 000000000..f7d87654b
--- /dev/null
+++ b/free/ci/bench/cache/doc.go
@@ -0,0 +1,5 @@
+// Package cache provides performance benchmarks and a harness for measuring
+// cache and artifact operations in the CI pipeline. It exposes key derivation,
+// content-addressable storage put/open costs, archive pack/unpack throughput,
+// and an end-to-end cold/warm restore benchmark that emits perfbench/v1 JSON.
+package cache
diff --git a/free/ci/bench/cache/harness.go b/free/ci/bench/cache/harness.go
new file mode 100644
index 000000000..c0d1b51b7
--- /dev/null
+++ b/free/ci/bench/cache/harness.go
@@ -0,0 +1,84 @@
+package cache
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"runtime"
+	"time"
+)
+
+// PerfbenchSchema is the contract identifier emitted by the harness.
+const PerfbenchSchema = "perfbench/v1"
+
+// RunResult captures one scenario of the cache harness.
+type RunResult struct {
+	// Fixture identifies the repository shape (go, pnpm, rust).
+	Fixture string `json:"fixture"`
+	// Mode is either "cold" or "warm".
+	Mode string `json:"mode"`
+	// RestoreMs records restore durations in milliseconds.
+	RestoreMs []float64 `json:"restore_ms"`
+	// SaveMs records save durations in milliseconds.
+	SaveMs []float64 `json:"save_ms"`
+	// HitRate is the fraction of cache hits observed during the run.
+	HitRate float64 `json:"hit_rate"`
+	// BytesTransferred is the total payload moved during the run.
+	BytesTransferred int64 `json:"bytes_transferred"`
+}
+
+// TransferResult records remote transfer throughput for a carrier.
+type TransferResult struct {
+	// Carrier names the transport (sim-a, sim-b, lan).
+	Carrier string `json:"carrier"`
+	// ThroughputMiBs is the measured throughput in MiB/s.
+	ThroughputMiBs float64 `json:"throughput_mib_s"`
+}
+
+// Report is the top-level perfbench/v1 document produced by the harness.
+type Report struct {
+	Schema    string           `json:"schema"`
+	Revision  string           `json:"revision"`
+	Machine   string           `json:"machine"`
+	Timestamp time.Time        `json:"timestamp"`
+	Runs      []RunResult      `json:"runs"`
+	Transfer  []TransferResult `json:"transfer"`
+	Metrics   []Observation    `json:"metrics"`
+	Injected  bool             `json:"injected"`
+}
+
+// NewReport builds a report skeleton populated with machine metadata.
+func NewReport(revision string) *Report {
+	return &Report{
+		Schema:    PerfbenchSchema,
+		Revision:  revision,
+		Machine:   fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH),
+		Timestamp: time.Now().UTC(),
+		Injected:  false,
+	}
+}
+
+// WriteJSON encodes the report as indented JSON to path.
+func (r *Report) WriteJSON(path string) error {
+	data, err := json.MarshalIndent(r, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, data, 0o644)
+}
+
+// LoadReport reads a perfbench/v1 JSON file back into memory.
+func LoadReport(path string) (*Report, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var rep Report
+	if err := json.Unmarshal(data, &rep); err != nil {
+		return nil, err
+	}
+	if rep.Schema != PerfbenchSchema {
+		return nil, fmt.Errorf("unexpected schema %q", rep.Schema)
+	}
+	return &rep, nil
+}
diff --git a/free/ci/bench/cache/metrics.go b/free/ci/bench/cache/metrics.go
new file mode 100644
index 000000000..0c7f1b6ae
--- /dev/null
+++ b/free/ci/bench/cache/metrics.go
@@ -0,0 +1,56 @@
+package cache
+
+import (
+	"math"
+	"sort"
+)
+
+// Observation summarizes a set of samples for a single metric.
+type Observation struct {
+	// Name identifies the metric (for example "restore_ms").
+	Name string `json:"name"`
+	// Unit describes the measurement unit (for example "ms", "MiB/s").
+	Unit string `json:"unit"`
+	// Count is the number of samples used to compute the summary.
+	Count int `json:"count"`
+	// Median is the 50th percentile value.
+	Median float64 `json:"median"`
+	// P95 is the 95th percentile value.
+	P95 float64 `json:"p95"`
+}
+
+// Summarize computes median and p95 from raw samples. It returns an error when
+// samples is empty. The slice is sorted in place.
+func Summarize(name, unit string, samples []float64) (Observation, error) {
+	if len(samples) == 0 {
+		return Observation{}, errNoSamples
+	}
+	sort.Float64s(samples)
+	return Observation{
+		Name:   name,
+		Unit:   unit,
+		Count:  len(samples),
+		Median: percentile(samples, 0.5),
+		P95:    percentile(samples, 0.95),
+	}, nil
+}
+
+func percentile(sorted []float64, p float64) float64 {
+	if len(sorted) == 1 {
+		return sorted[0]
+	}
+	idx := p * float64(len(sorted)-1)
+	lower := int(math.Floor(idx))
+	upper := int(math.Ceil(idx))
+	if lower == upper {
+		return sorted[lower]
+	}
+	frac := idx - float64(lower)
+	return sorted[lower]*(1-frac) + sorted[upper]*frac
+}
+
+type errType struct{ msg string }
+
+func (e *errType) Error() string { return e.msg }
+
+var errNoSamples = &errType{msg: "no samples"}
diff --git a/free/ci/bench/cache/perf-budget.json b/free/ci/bench/cache/perf-budget.json
new file mode 100644
index 000000000..200a4416a
--- /dev/null
+++ b/free/ci/bench/cache/perf-budget.json
@@ -0,0 +1,15 @@
+{
+  "schema": "perfbench/v1",
+  "budgets": [
+    {
+      "metric": "restore_ms",
+      "unit": "ms",
+      "p95_max": 250
+    },
+    {
+      "metric": "save_ms",
+      "unit": "ms",
+      "p95_max": 220
+    }
+  ]
+}
\ No newline at end of file
diff --git a/free/ci/bench/cmd/schedbench/main.go b/free/ci/bench/cmd/schedbench/main.go
new file mode 100644
index 000000000..a339a6ed6
--- /dev/null
+++ b/free/ci/bench/cmd/schedbench/main.go
@@ -0,0 +1,175 @@
+// Command schedbench measures the scheduling cost of the V15 ci engine
+// (P7-SCHED-14) and emits contract:cli.perfbench v1 result JSON.
+//
+//	schedbench [-runs 20] [-warmup 2] [-bin path] [-out file] [-json]
+//	schedbench -write-budget sched-budget.json -share-budget share.json -in run1.json,run2.json
+//	schedbench -share-check share.json -in result.json
+//
+// The millisecond metrics are checked by the cli's `perfbench check`; the share
+// (unit pct) is checked by -share-check. Run it from the free/ci module root.
+// Exit 0 on success, 1 when a check fails, 2 on a usage or environment error.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+
+	"github.com/nself-org/plugins/free/ci/bench"
+	schedbench "github.com/nself-org/plugins/free/ci/bench/sched"
+)
+
+func main() { os.Exit(realMain(os.Args[1:], os.Stdout, os.Stderr)) }
+
+func say(w io.Writer, format string, a ...any) { _, _ = fmt.Fprintf(w, format+"\n", a...) }
+
+type options struct {
+	runs, warmup                    int
+	bin, sha, in, out, note         string
+	writeBudget, shareBudget, check string
+	jsonOut                         bool
+}
+
+func realMain(args []string, stdout, stderr io.Writer) int {
+	var o options
+	fs := flag.NewFlagSet("schedbench", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	fs.IntVar(&o.runs, "runs", 20, "measured iterations")
+	fs.IntVar(&o.warmup, "warmup", 2, "discarded warm-up iterations")
+	fs.StringVar(&o.bin, "bin", "", "nself-ci binary (default: build ./cmd)")
+	fs.StringVar(&o.sha, "sha", "", "revision measured (default: git HEAD of the working directory)")
+	fs.StringVar(&o.in, "in", "", "result file (-share-check); with -write-budget a comma list of baseline runs")
+	fs.StringVar(&o.out, "out", "", "write the result JSON here")
+	fs.StringVar(&o.note, "note", "", "_note text of a derived budget")
+	fs.StringVar(&o.writeBudget, "write-budget", "", "derive the perfbench budget (ms metrics) from -in and write it here")
+	fs.StringVar(&o.shareBudget, "share-budget", "", "with -write-budget: also write the share ceiling here")
+	fs.StringVar(&o.check, "share-check", "", "check -in against this share ceiling file")
+	fs.BoolVar(&o.jsonOut, "json", false, "print the result JSON to stdout")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	switch {
+	case o.check != "":
+		return checkCmd(o, stdout, stderr)
+	case o.writeBudget != "":
+		return budgetCmd(o, stderr)
+	}
+	return runCmd(o, stdout, stderr)
+}
+
+func readAll(list string) ([]bench.Result, error) {
+	var runs []bench.Result
+	for _, p := range strings.Split(list, ",") {
+		r, err := bench.ReadResult(p)
+		if err != nil {
+			return nil, err
+		}
+		runs = append(runs, r)
+	}
+	return runs, nil
+}
+
+func checkCmd(o options, stdout, stderr io.Writer) int {
+	b, err := schedbench.LoadShare(o.check)
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	res, err := bench.ReadResult(o.in)
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	if v := schedbench.CheckShare(b, res); v != "" {
+		say(stderr, "schedbench: FAIL\n%s", v)
+		return 1
+	}
+	m, _ := res.Find(schedbench.MetricShare)
+	say(stdout, "%s: p95 %.2f%% within the ceiling %.1f%%", schedbench.MetricShare, m.P95, b.P95Pct)
+	return 0
+}
+
+func budgetCmd(o options, stderr io.Writer) int {
+	runs, err := readAll(o.in)
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	worst, err := bench.WorstOf(runs)
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	b, err := bench.BudgetFromResult(worst, o.note, func(name string) bool { return name != schedbench.MetricShare })
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	if err = writeJSON(o.writeBudget, b); err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	if o.shareBudget != "" {
+		s, err := schedbench.ShareFromBaseline(runs, o.note)
+		if err == nil {
+			err = writeJSON(o.shareBudget, s)
+		}
+		if err != nil {
+			say(stderr, "schedbench: %v", err)
+			return 2
+		}
+	}
+	return 0
+}
+
+func writeJSON(path string, v any) error {
+	raw, err := bench.Marshal(v)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, raw, 0o644)
+}
+
+func runCmd(o options, stdout, stderr io.Writer) int {
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	dir, err := os.MkdirTemp(os.Getenv("TMPDIR"), "schedbench-")
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	defer func() { _ = os.RemoveAll(dir) }()
+	if o.bin == "" {
+		if o.bin, err = bench.BuildBinary(ctx, ".", filepath.Join(dir, "nself-ci")); err != nil {
+			say(stderr, "schedbench: %v", err)
+			return 2
+		}
+	}
+	if o.sha == "" {
+		o.sha = bench.TreeSHA(ctx, ".")
+	}
+	res, err := schedbench.Run(ctx, schedbench.Config{Bin: o.bin, Runs: o.runs, Warmup: o.warmup, Dir: dir, SHA: o.sha, Log: stderr})
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	raw, err := bench.Marshal(res)
+	if err == nil && o.out != "" {
+		err = os.WriteFile(o.out, raw, 0o644)
+	}
+	if err != nil {
+		say(stderr, "schedbench: %v", err)
+		return 2
+	}
+	if o.jsonOut {
+		_, _ = stdout.Write(raw)
+	}
+	say(stderr, "%s", bench.Format(res))
+	return 0
+}
diff --git a/free/ci/bench/gate.go b/free/ci/bench/gate.go
new file mode 100644
index 000000000..ebf494163
--- /dev/null
+++ b/free/ci/bench/gate.go
@@ -0,0 +1,37 @@
+package bench
+
+// Purpose: the two pieces of the end-to-end tiny run that the scheduler harness
+// (bench/sched, P7-SCHED-14) pairs its own timings with: one V15 gate run of the
+// nself-ci binary, and the number of jobs the planner puts in that pipeline.
+// Inputs:  the binary, the materialized fixture, the shared NSELF_CI_HOME.
+// Outputs: the wall time of one V15 gate run; the planned job count.
+// Constraints: the arguments and environment are the ones the cibench loop uses
+// for the V15 mode, so the pairing denominator is the same run as ci.e2e_tiny.v15.
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/nself-org/plugins/free/ci/internal/plan"
+)
+
+// GateV15 runs the V15 gate once on repo and returns its wall time.
+func GateV15(ctx context.Context, bin, repo, home string) (Timing, error) {
+	m := modes[1]
+	env := append(baseEnv(), "NSELF_CI_HOME="+home, "NSELF_TELEMETRY_OPT_OUT=1", "NSELF_V15="+m.env)
+	r, err := must(ctx, append([]string{bin}, m.args(repo)...), repo, env)
+	if err != nil {
+		return r, fmt.Errorf("e2e v15 gate: %w", err)
+	}
+	return r, nil
+}
+
+// PlannedJobs is the number of jobs the planner schedules for the fixture's gate pipeline.
+func (p *Inproc) PlannedJobs() (int, error) {
+	pl, err := plan.Build(plan.Input{Config: p.cfg, Facts: p.facts, World: p.world,
+		Revision: plan.Revision{Branch: "main", DefaultBranch: true}, Pipeline: "gate"})
+	if err != nil {
+		return 0, err
+	}
+	return len(pl.Jobs), nil
+}
diff --git a/free/ci/bench/perf-budget.json b/free/ci/bench/perf-budget.json
index 67620e48e..afaeb8886 100644
--- a/free/ci/bench/perf-budget.json
+++ b/free/ci/bench/perf-budget.json
@@ -8,7 +8,7 @@
     "ci.e2e_tiny.v15": 2541,
     "ci.exec_overhead": 59,
     "ci.plan": 5,
-    "ci.startup": 14,
+    "ci.startup": 34,
     "ci.store_open": 58
   }
 }
diff --git a/free/ci/bench/sched-budget-darwin-arm64.json b/free/ci/bench/sched-budget-darwin-arm64.json
new file mode 100644
index 000000000..200a0271c
--- /dev/null
+++ b/free/ci/bench/sched-budget-darwin-arm64.json
@@ -0,0 +1,9 @@
+{
+  "_note": "Ceilings for the scheduling cost on darwin/arm64: the highest p95 of three 20-sample baseline runs on mm4 (Apple silicon, 16 GB) plus 25 percent; the millisecond ceilings are never below 5 ms (the P7-CI-46 floor, below it a timing is runner noise). Baselines and update rule: hq plan/p7/evidence/SCHED-perf.md. perfbench check reads the ms ceilings; schedbench -share-check reads the share ceiling.",
+  "schema": "perfbench-budget/v1",
+  "platform": "darwin/arm64",
+  "p95_ms": {
+    "dispatch.admit_ms": 5,
+    "sched.place_ms": 5
+  }
+}
diff --git a/free/ci/bench/sched/SCHED-14-status.md b/free/ci/bench/sched/SCHED-14-status.md
new file mode 100644
index 000000000..706706a26
--- /dev/null
+++ b/free/ci/bench/sched/SCHED-14-status.md
@@ -0,0 +1,54 @@
+# SCHED-14 measurement prerequisites
+
+Status: incomplete. No performance budget or acceptance result is claimed.
+
+Available measurements:
+
+- `internal/sched/bench_test.go`: complete Place decisions over 1/10/100
+  runners crossed with 10/100/1000 jobs. Each runner has one slot, so the
+  workload includes successful placement and capacity refusal. Setup is untimed;
+  explanation construction and allocations are included.
+- `internal/dispatch/bench_test.go`: world.Build (including snapshot and digest),
+  Place and Admit against a fresh private on-disk store per iteration, so world
+  cardinality does not grow with b.N. Store setup, queue setup and successful
+  settlement are untimed. No transport, service or job execution is simulated
+  as end-to-end pipeline time.
+- `ci-bench.yml`: sequential Linux measurements on public GitHub-hosted
+  ubuntu-latest, two discarded warmup runs and ten recorded runs, with raw
+  benchmark output, revision, machine and command retained as artifacts.
+
+The local one-iteration smoke run passed on darwin/arm64, Apple M5 Max.
+This establishes executable fixtures, not a statistical baseline. Use:
+
+```sh
+CGO_ENABLED=0 go -C free/ci test -mod=vendor -run '^$' -bench 'Benchmark(Place|Admit)$' -benchmem -count=2 ./internal/sched/ ./internal/dispatch/
+CGO_ENABLED=0 go -C free/ci test -mod=vendor -run '^$' -bench 'Benchmark(Place|Admit)$' -benchmem -count=10 ./internal/sched/ ./internal/dispatch/
+```
+
+## Required inputs for completion
+
+The upstream `bench/CI-46-status.md` records incomplete end-to-end probes and
+an unavailable perfbench contract. This tree contains neither
+`bench/cmd/cibench` nor `bench/perf-budget.json`. Although schedbench has an
+architecture row, cibench does not. The ticket prohibits editing the layer
+registry and accessing the CLI or HQ checkout outside this working tree.
+
+The lead must supply the pinned CLI result and budget schemas plus its
+origin/main SHA, the completed CI-46 harness and measured budget, and a real
+tiny-repository end-to-end probe with scheduling instrumentation. Pair the
+scheduling numerator with the same run's end-to-end denominator. A detached
+Place microbenchmark divided by unrelated pipeline samples is not the required
+`sched.share_tiny_pct` measurement.
+
+After those inputs arrive, implement the registered schedbench entry point,
+retain ten samples after two warmups, calculate p50/p95 and variance, and derive
+each platform budget from its measured p95 times 1.25. Extend the workflow with
+the pinned CLI checks for both cibench and schedbench and prove rejection of an
+injected slowdown. The current workflow collects microbenchmarks only and is
+not a perfbench budget gate.
+
+Record Linux results only from that workflow, and macos-arm64 results from the
+operator's Mac. Supply the lead with all three scheduling metric rows for
+performance-slos.md, including revision, machine, command, raw samples and
+pinned CLI SHA. The requested HQ evidence and SLO document are outside this
+ticket's write scope; neither has been updated. No owner exception exists here.
diff --git a/free/ci/bench/sched/admission.go b/free/ci/bench/sched/admission.go
new file mode 100644
index 000000000..fc85fd2e6
--- /dev/null
+++ b/free/ci/bench/sched/admission.go
@@ -0,0 +1,97 @@
+package sched
+
+// Purpose: one timed scheduling decision for the schedbench harness (P7-SCHED-14):
+// the same path the V15 dispatcher takes for one local job, world build, Place and
+// the admission transaction, against a fresh on-disk store.
+// Inputs:  a scratch directory.
+// Outputs: the Place time and the Build+Place+Admit time of one decision, in ms.
+// Constraints: the store and the queued attempt are set up untimed and the store
+// is removed afterwards, so the snapshot cardinality is the same every iteration
+// (it does not grow with the number of runs); nothing here reads the operator's state.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/dispatch"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/planview"
+	isched "github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+const (
+	hostCPU   = 8
+	hostMemMB = 8192
+)
+
+// Decision is the timing of one scheduling decision.
+type Decision struct{ PlaceMS, AdmitMS float64 }
+
+func ms(d time.Duration) float64 { return float64(d.Microseconds()) / 1000 }
+
+func job(attempt string) isched.Job {
+	return isched.Job{Key: attempt, ID: attempt, Name: attempt, Pipeline: isched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan",
+		TimeoutMs: 60000, PersonalOwnRun: true, Project: "project"}
+}
+
+// queue creates the pipeline, job and first attempt a decision is made for.
+func queue(ctx context.Context, st *store.Store) (string, error) {
+	err := st.CreatePipeline(ctx, store.PipelineRow{ID: "pipe", Revision: "rev", Project: "project", Trigger: "local", SourceTrust: "owner",
+		PrivacyZone: "local-only", PolicyDigest: "p", InputDigest: "i", SelectionMode: "full", Status: "running"})
+	if err != nil {
+		return "", err
+	}
+	const id = "pipe.noop.1"
+	if err = st.CreateJob(ctx, store.JobRow{ID: "job-" + id, PipelineID: "pipe", Name: "noop", Kind: "test", Idempotent: true, InfraMax: 1, InputDigest: "i", Required: true}); err != nil {
+		return "", err
+	}
+	return id, st.CreateAttempt(ctx, store.AttemptRow{ID: id, JobID: "job-" + id, N: 1}, "")
+}
+
+// Decide makes one decision in a fresh store under dir.
+func Decide(ctx context.Context, dir string) (Decision, error) {
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return Decision{}, err
+	}
+	defer func() { _ = os.RemoveAll(dir) }()
+	st, err := store.Open(filepath.Join(dir, "state.db"), store.Options{})
+	if err != nil {
+		return Decision{}, err
+	}
+	defer func() { _ = st.Close() }()
+	id, err := queue(ctx, st)
+	if err != nil {
+		return Decision{}, err
+	}
+	capability, err := planview.LocalCapability(planview.LocalFacts{Project: "project", Platform: "linux/amd64", CPUs: hostCPU, MemMB: hostMemMB, Now: time.Now()})
+	if err != nil {
+		return Decision{}, err
+	}
+	j := job(id)
+	deps := world.Deps{Store: st, Local: &capability, Jobs: []isched.Job{j},
+		Policy: func(context.Context, string) (isched.Policy, error) { return isched.Policy{Preset: "balanced"}, nil }}
+	t0 := time.Now()
+	w, digest, err := world.Build(ctx, deps, j.Pipeline)
+	if err != nil {
+		return Decision{}, err
+	}
+	t1 := time.Now()
+	placed := isched.Place(w, []isched.Job{j})
+	t2 := time.Now()
+	if len(placed.Placements) != 1 || len(w.Runners) != 1 {
+		return Decision{}, fmt.Errorf("the local fixture did not place exactly one job")
+	}
+	_, err = dispatch.Admit(ctx, st, dispatch.Request{AttemptID: id, Placement: placed.Placements[0], Runner: w.Runners[0], Job: j,
+		Local: true, Host: "bench-host", CapacityCPU: hostCPU, CapacityMemMB: hostMemMB, WorldDigest: digest})
+	t3 := time.Now()
+	if err != nil {
+		return Decision{}, err
+	}
+	return Decision{PlaceMS: ms(t2.Sub(t1)), AdmitMS: ms(t3.Sub(t0))}, nil
+}
diff --git a/free/ci/bench/sched/local_test.go b/free/ci/bench/sched/local_test.go
new file mode 100644
index 000000000..2d6be99be
--- /dev/null
+++ b/free/ci/bench/sched/local_test.go
@@ -0,0 +1,118 @@
+package sched
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/detect"
+	"github.com/nself-org/plugins/free/ci/internal/plan"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func fixture(b *testing.B, packages int) string {
+	b.Helper()
+	root := b.TempDir()
+	for i := 0; i < packages; i++ {
+		dir := filepath.Join(root, fmt.Sprintf("pkg%03d", i))
+		if err := os.Mkdir(dir, 0700); err != nil {
+			b.Fatal(err)
+		}
+		for name, data := range map[string]string{
+			"go.mod":  "module example.test/fixture\n\ngo 1.26\n",
+			"main.go": "package fixture\nfunc Value() int { return 1 }\n",
+		} {
+			if err := os.WriteFile(filepath.Join(dir, name), []byte(data), 0600); err != nil {
+				b.Fatal(err)
+			}
+		}
+	}
+	return root
+}
+
+// BenchmarkDetect measures real filesystem discovery on generated fixture repos.
+func BenchmarkDetect(b *testing.B) {
+	for _, size := range []struct {
+		name     string
+		packages int
+	}{{"tiny", 1}, {"medium", 32}} {
+		b.Run(size.name, func(b *testing.B) {
+			root := fixture(b, size.packages)
+			registry := detect.DefaultRegistry()
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				facts, err := registry.Detect(os.DirFS(root), func(string) bool { return true })
+				if err != nil || len(facts) == 0 {
+					b.Fatalf("detect facts=%d: %v", len(facts), err)
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkPlan measures planning with detection outside the timed interval.
+func BenchmarkPlan(b *testing.B) {
+	for _, size := range []struct {
+		name     string
+		packages int
+	}{{"tiny", 1}, {"medium", 32}} {
+		b.Run(size.name, func(b *testing.B) {
+			root := fixture(b, size.packages)
+			facts, err := detect.DefaultRegistry().Detect(os.DirFS(root), func(string) bool { return true })
+			if err != nil {
+				b.Fatal(err)
+			}
+			in := plan.Input{Facts: facts}
+			for i := 0; i < size.packages; i++ {
+				in.Checks = append(in.Checks, plan.Check{
+					ID: fmt.Sprintf("go.test.%d", i), Kind: "test", Tool: "go",
+					Workdir: fmt.Sprintf("pkg%03d", i), Required: true,
+					Argv: []string{"go", "test", "./..."},
+				})
+			}
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				p, err := plan.Build(in)
+				if err != nil || len(p.Jobs) != size.packages {
+					b.Fatalf("plan: %v", err)
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkStoreOpen measures fresh migrations separately from existing stores.
+func BenchmarkStoreOpen(b *testing.B) {
+	for _, fresh := range []bool{false, true} {
+		b.Run(fmt.Sprintf("fresh=%t", fresh), func(b *testing.B) {
+			root := b.TempDir()
+			open := func(path string) {
+				s, err := store.Open(path, store.Options{})
+				if err != nil {
+					b.Fatal(err)
+				}
+				if err := s.Close(); err != nil {
+					b.Fatal(err)
+				}
+			}
+			path := filepath.Join(root, "state.db")
+			if !fresh {
+				open(path)
+			}
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				b.StopTimer()
+				if fresh {
+					root = b.TempDir()
+					path = filepath.Join(root, "state.db")
+				}
+				b.StartTimer()
+				open(path)
+			}
+		})
+	}
+}
diff --git a/free/ci/bench/sched/overhead.go b/free/ci/bench/sched/overhead.go
new file mode 100644
index 000000000..1420fa8ad
--- /dev/null
+++ b/free/ci/bench/sched/overhead.go
@@ -0,0 +1,128 @@
+// Package sched provides local CI overhead measurement primitives.
+package sched
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"sort"
+	"time"
+)
+
+// MetricNames returns the ordered CI overhead metrics, measured in milliseconds.
+func MetricNames() []string {
+	return []string{
+		"ci.startup", "ci.detect", "ci.plan", "ci.store_open", "ci.exec_overhead",
+		"ci.service_start_warm", "ci.service_start_cold",
+		"ci.e2e_tiny.v14", "ci.e2e_tiny.v15",
+		"ci.e2e_medium.v14", "ci.e2e_medium.v15",
+	}
+}
+
+// Observation retains raw samples as well as their derived statistics.
+type Observation struct {
+	Name    string    `json:"name"`
+	Unit    string    `json:"unit"`
+	Samples []float64 `json:"samples"`
+	Median  float64   `json:"median"`
+	P95     float64   `json:"p95"`
+}
+
+// Summarize computes the median and nearest-rank p95 without modifying samples.
+func Summarize(name string, samples []float64) (Observation, error) {
+	if len(samples) == 0 {
+		return Observation{}, fmt.Errorf("%s: no samples", name)
+	}
+	sorted := append([]float64(nil), samples...)
+	for _, v := range sorted {
+		if v <= 0 || math.IsNaN(v) || math.IsInf(v, 0) {
+			return Observation{}, fmt.Errorf("%s: invalid duration", name)
+		}
+	}
+	sort.Float64s(sorted)
+	mid := len(sorted) / 2
+	median := sorted[mid]
+	if len(sorted)%2 == 0 {
+		median = sorted[mid-1]/2 + sorted[mid]/2
+	}
+	return Observation{
+		Name: name, Unit: "ms", Samples: append([]float64(nil), samples...),
+		Median: median, P95: sorted[int(math.Ceil(float64(len(sorted))*0.95))-1],
+	}, nil
+}
+
+// Probe separates untimed setup and cleanup from the timed operation.
+// Cold service setup must evict its dedicated image; Run must include the pull
+// and wait for service readiness. Warm setup must ensure the image is present.
+// Process probes must wait for process exit and return nonzero exits as errors.
+type Probe struct {
+	Prepare func(context.Context) error
+	Run     func(context.Context) error
+	Cleanup func(context.Context) error
+}
+
+// Measure records ten samples after two warmups, alternating legacy and V15.
+// Every probe is mandatory: missing service or legacy measurements fail closed.
+// A caller must impose a context deadline and isolate all probe state.
+func Measure(ctx context.Context, probes map[string]Probe) ([]Observation, error) {
+	names := MetricNames()
+	for _, name := range names {
+		if probes[name].Run == nil {
+			return nil, fmt.Errorf("%s: probe required", name)
+		}
+	}
+	samples := make(map[string][]float64, len(names))
+	for round := 0; round < 12; round++ {
+		order := append([]string(nil), names...)
+		if round%2 != 0 {
+			order[7], order[8] = order[8], order[7]
+			order[9], order[10] = order[10], order[9]
+		}
+		for _, name := range order {
+			elapsed, err := measureOne(ctx, probes[name])
+			if err != nil {
+				return nil, fmt.Errorf("%s round %d: %w", name, round, err)
+			}
+			if round >= 2 {
+				samples[name] = append(samples[name], float64(elapsed)/float64(time.Millisecond))
+			}
+		}
+	}
+	var result []Observation
+	for _, name := range names {
+		observation, err := Summarize(name, samples[name])
+		if err != nil {
+			return nil, err
+		}
+		result = append(result, observation)
+	}
+	return result, nil
+}
+
+func measureOne(ctx context.Context, p Probe) (elapsed time.Duration, err error) {
+	if err = ctx.Err(); err != nil {
+		return 0, err
+	}
+	if p.Cleanup != nil {
+		defer func() {
+			cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), time.Minute)
+			defer cancel()
+			cleanupErr := p.Cleanup(cleanupCtx)
+			if err == nil {
+				err = cleanupErr
+			}
+		}()
+	}
+	if p.Prepare != nil {
+		if err = p.Prepare(ctx); err != nil {
+			return 0, err
+		}
+	}
+	start := time.Now()
+	err = p.Run(ctx)
+	elapsed = time.Since(start)
+	if err == nil {
+		err = ctx.Err()
+	}
+	return elapsed, err
+}
diff --git a/free/ci/bench/sched/overhead_test.go b/free/ci/bench/sched/overhead_test.go
new file mode 100644
index 000000000..eaec86c21
--- /dev/null
+++ b/free/ci/bench/sched/overhead_test.go
@@ -0,0 +1,109 @@
+package sched
+
+import (
+	"context"
+	"errors"
+	"math"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestSummarize(t *testing.T) {
+	samples := []float64{10, 1, 9, 2, 8, 3, 7, 4, 6, 5}
+	original := append([]float64(nil), samples...)
+	got, err := Summarize("test", samples)
+	if err != nil || got.Median != 5.5 || got.P95 != 10 {
+		t.Fatalf("summary = %+v, %v", got, err)
+	}
+	if !reflect.DeepEqual(samples, original) {
+		t.Fatal("modified input samples")
+	}
+	samples[0] = 100
+	if got.Samples[0] != 10 {
+		t.Fatal("summary aliases input")
+	}
+	for _, invalid := range [][]float64{nil, {0}, {-1}, {math.NaN()}, {math.Inf(1)}} {
+		if _, err := Summarize("test", invalid); err == nil {
+			t.Fatalf("accepted %v", invalid)
+		}
+	}
+}
+
+func TestMeasureInterleavesAndDiscardsWarmups(t *testing.T) {
+	var order []string
+	prepared, cleaned := 0, 0
+	probes := map[string]Probe{}
+	for _, name := range MetricNames() {
+		probes[name] = Probe{
+			Prepare: func(context.Context) error { prepared++; return nil },
+			Run: func(context.Context) error {
+				order = append(order, name)
+				time.Sleep(time.Microsecond)
+				return nil
+			},
+			Cleanup: func(context.Context) error { cleaned++; return nil },
+		}
+	}
+	got, err := Measure(context.Background(), probes)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 11 || prepared != 132 || cleaned != 132 {
+		t.Fatalf("metrics=%d prepared=%d cleaned=%d", len(got), prepared, cleaned)
+	}
+	for _, observation := range got {
+		if len(observation.Samples) != 10 || observation.Unit != "ms" {
+			t.Fatalf("invalid observation: %+v", observation)
+		}
+	}
+	if order[7] != "ci.e2e_tiny.v14" || order[18] != "ci.e2e_tiny.v15" {
+		t.Fatal("legacy and V15 order did not alternate")
+	}
+}
+
+func TestProbeFailureAndCleanup(t *testing.T) {
+	want := errors.New("failed")
+	for _, failPrepare := range []bool{false, true} {
+		cleaned, ran := false, false
+		p := Probe{
+			Prepare: func(context.Context) error {
+				if failPrepare {
+					return want
+				}
+				return nil
+			},
+			Run:     func(context.Context) error { ran = true; return want },
+			Cleanup: func(context.Context) error { cleaned = true; return nil },
+		}
+		_, err := measureOne(context.Background(), p)
+		if !errors.Is(err, want) || !cleaned || ran == failPrepare {
+			t.Fatalf("err=%v cleaned=%v ran=%v", err, cleaned, ran)
+		}
+	}
+	if _, err := Measure(context.Background(), nil); err == nil {
+		t.Fatal("missing probes accepted")
+	}
+}
+
+func TestTinyRatioBoundaryAndSlowdown(t *testing.T) {
+	metric := func(name string, v float64) Observation {
+		samples := make([]float64, 10)
+		for i := range samples {
+			samples[i] = v
+		}
+		return Observation{Name: name, Unit: "ms", Samples: samples}
+	}
+	legacy := metric("ci.e2e_tiny.v14", 1000)
+	v15 := metric("ci.e2e_tiny.v15", 1350)
+	if err := CheckTinyRatio([]Observation{legacy, v15}); err != nil {
+		t.Fatal(err)
+	}
+	slow := metric("ci.e2e_tiny.v15", 1351)
+	slow.Median = 1 // A forged summary must not hide slow raw samples.
+	for _, invalid := range [][]Observation{nil, {legacy}, {legacy, legacy, v15}, {legacy, slow}} {
+		if err := CheckTinyRatio(invalid); err == nil {
+			t.Fatalf("accepted invalid result: %+v", invalid)
+		}
+	}
+}
diff --git a/free/ci/bench/sched/relative.go b/free/ci/bench/sched/relative.go
new file mode 100644
index 000000000..87d203404
--- /dev/null
+++ b/free/ci/bench/sched/relative.go
@@ -0,0 +1,38 @@
+package sched
+
+import "fmt"
+
+// CheckTinyRatio checks the ticket's local fast-path median allowance.
+// Statistics are recomputed from samples so a stale summary cannot mask a miss.
+func CheckTinyRatio(observations []Observation) error {
+	values := make(map[string]float64)
+	for _, observation := range observations {
+		if observation.Name != "ci.e2e_tiny.v14" && observation.Name != "ci.e2e_tiny.v15" {
+			continue
+		}
+		if _, exists := values[observation.Name]; exists {
+			return fmt.Errorf("duplicate metric %s", observation.Name)
+		}
+		if observation.Unit != "ms" || len(observation.Samples) != 10 {
+			return fmt.Errorf("%s requires ten millisecond samples", observation.Name)
+		}
+		summary, err := Summarize(observation.Name, observation.Samples)
+		if err != nil {
+			return err
+		}
+		values[observation.Name] = summary.Median
+	}
+	legacy, ok := values["ci.e2e_tiny.v14"]
+	if !ok {
+		return fmt.Errorf("missing ci.e2e_tiny.v14")
+	}
+	v15, ok := values["ci.e2e_tiny.v15"]
+	if !ok {
+		return fmt.Errorf("missing ci.e2e_tiny.v15")
+	}
+	limit := legacy*1.10 + 250
+	if v15 > limit {
+		return fmt.Errorf("ci.e2e_tiny.v15 median %.6f ms exceeds %.6f ms", v15, limit)
+	}
+	return nil
+}
diff --git a/free/ci/bench/sched/run.go b/free/ci/bench/sched/run.go
new file mode 100644
index 000000000..b09494a80
--- /dev/null
+++ b/free/ci/bench/sched/run.go
@@ -0,0 +1,88 @@
+package sched
+
+// Purpose: the schedbench loop. Each iteration makes one scheduling decision and
+// runs the V15 gate once on the tiny fixture, then pairs them: the scheduling
+// share of that run is (decisions the run makes x the measured decision cost) /
+// the run's own wall time.
+// Inputs:  the nself-ci binary, run and warm-up counts, a scratch directory.
+// Outputs: a perfbench/v1 Result with sched.place_ms, dispatch.admit_ms (ms) and
+// sched.share_tiny_pct (pct).
+// Constraints: warm-up iterations run the same code and are discarded. The engine
+// does not time its own scheduling compute (schedtel wait_ms includes waiting for
+// a slot), so the numerator is the decision cost measured here in the same
+// iteration and the tiny pipeline's planned job count, one decision per job. That
+// is an upper bound: the dispatcher builds the world once per job in this model.
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/nself-org/plugins/free/ci/bench"
+)
+
+// Metric names (unit ms except the share).
+const (
+	MetricPlace = "sched.place_ms"
+	MetricAdmit = "dispatch.admit_ms"
+	MetricShare = "sched.share_tiny_pct"
+	// ScenarioName is the scenario field of the result document.
+	ScenarioName = "ci-sched-overhead"
+)
+
+// Config is one harness run.
+type Config struct {
+	Bin    string
+	Runs   int
+	Warmup int
+	Dir    string // scratch directory, created by the caller
+	SHA    string
+	Log    io.Writer
+}
+
+// Run executes the harness.
+func Run(ctx context.Context, cfg Config) (bench.Result, error) {
+	if cfg.Runs < 1 || cfg.Warmup < 0 {
+		return bench.Result{}, fmt.Errorf("runs must be >= 1 and warmup >= 0")
+	}
+	repo := filepath.Join(cfg.Dir, bench.Tiny)
+	if err := bench.Materialize(ctx, bench.Tiny, repo); err != nil {
+		return bench.Result{}, err
+	}
+	home := filepath.Join(cfg.Dir, "home")
+	if err := os.MkdirAll(home, 0o700); err != nil {
+		return bench.Result{}, err
+	}
+	inproc, err := bench.PrepareInproc(repo, filepath.Join(cfg.Dir, "scratch"))
+	if err != nil {
+		return bench.Result{}, err
+	}
+	jobs, err := inproc.PlannedJobs()
+	if err != nil || jobs < 1 {
+		return bench.Result{}, fmt.Errorf("tiny pipeline job count %d: %v", jobs, err)
+	}
+	var col bench.Collector
+	for i := -cfg.Warmup; i < cfg.Runs; i++ {
+		d, err := Decide(ctx, filepath.Join(cfg.Dir, fmt.Sprintf("decide-%d", i+cfg.Warmup)))
+		if err != nil {
+			return bench.Result{}, fmt.Errorf("decision: %w", err)
+		}
+		e2e, err := bench.GateV15(ctx, cfg.Bin, repo, home)
+		if err != nil {
+			return bench.Result{}, err
+		}
+		if i >= 0 {
+			col.Add(MetricPlace, "ms", d.PlaceMS)
+			col.Add(MetricAdmit, "ms", d.AdmitMS)
+			col.Add(MetricShare, "pct", 100*float64(jobs)*d.AdmitMS/e2e.MS())
+		}
+		if cfg.Log != nil {
+			_, _ = fmt.Fprintf(cfg.Log, "iteration %d/%d: place %.3f ms, admit %.3f ms, e2e %.0f ms, %d jobs\n", i+cfg.Warmup+1, cfg.Runs+cfg.Warmup, d.PlaceMS, d.AdmitMS, e2e.MS(), jobs)
+		}
+	}
+	res := bench.NewResult(cfg.SHA, cfg.Runs, col.Metrics())
+	res.Scenario = ScenarioName
+	return res, nil
+}
diff --git a/free/ci/bench/sched/share-budget-darwin-arm64.json b/free/ci/bench/sched/share-budget-darwin-arm64.json
new file mode 100644
index 000000000..7aa950a5b
--- /dev/null
+++ b/free/ci/bench/sched/share-budget-darwin-arm64.json
@@ -0,0 +1,6 @@
+{
+  "_note": "Ceilings for the scheduling cost on darwin/arm64: the highest p95 of three 20-sample baseline runs on mm4 (Apple silicon, 16 GB) plus 25 percent; the millisecond ceilings are never below 5 ms (the P7-CI-46 floor, below it a timing is runner noise). Baselines and update rule: hq plan/p7/evidence/SCHED-perf.md. perfbench check reads the ms ceilings; schedbench -share-check reads the share ceiling.",
+  "schema": "schedbench-share-budget/v1",
+  "platform": "darwin/arm64",
+  "p95_pct": 0.6
+}
diff --git a/free/ci/bench/sched/share.go b/free/ci/bench/sched/share.go
new file mode 100644
index 000000000..8f7391f76
--- /dev/null
+++ b/free/ci/bench/sched/share.go
@@ -0,0 +1,75 @@
+package sched
+
+// Purpose: the ceiling for sched.share_tiny_pct. perfbench-budget/v1 only holds
+// millisecond ceilings (`perfbench check` refuses any other unit), so the share
+// has its own small document, derived and checked the same way.
+// Inputs:  baseline results of one platform; a result to check.
+// Outputs: a ShareBudget; the violations of a result against it.
+// Constraints: the ceiling is the worst baseline p95 times 1.25, rounded up to
+// 0.1 percentage point; a result without the metric fails closed.
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+	"os"
+
+	"github.com/nself-org/plugins/free/ci/bench"
+)
+
+// ShareSchema is the schema field of a share budget.
+const ShareSchema = "schedbench-share-budget/v1"
+
+// ShareBudget is the ceiling document.
+type ShareBudget struct {
+	Note     string  `json:"_note"`
+	Schema   string  `json:"schema"`
+	Platform string  `json:"platform"`
+	P95Pct   float64 `json:"p95_pct"`
+}
+
+// ShareFromBaseline derives the ceiling from the baseline runs of one platform.
+func ShareFromBaseline(runs []bench.Result, note string) (ShareBudget, error) {
+	worst, err := bench.WorstOf(runs)
+	if err != nil {
+		return ShareBudget{}, err
+	}
+	m, ok := worst.Find(MetricShare)
+	if !ok || m.P95 <= 0 || math.IsNaN(m.P95) {
+		return ShareBudget{}, fmt.Errorf("baseline has no usable %s", MetricShare)
+	}
+	return ShareBudget{Note: note, Schema: ShareSchema, Platform: fmt.Sprintf("%s/%s", worst.GOOS, worst.GOARCH),
+		P95Pct: math.Ceil(m.P95*bench.Headroom*10) / 10}, nil
+}
+
+// LoadShare reads a share budget.
+func LoadShare(path string) (ShareBudget, error) {
+	var b ShareBudget
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return b, err
+	}
+	if err = json.Unmarshal(raw, &b); err != nil {
+		return b, fmt.Errorf("%s: %w", path, err)
+	}
+	if b.Schema != ShareSchema || b.P95Pct <= 0 {
+		return b, fmt.Errorf("%s: not a %s document", path, ShareSchema)
+	}
+	return b, nil
+}
+
+// CheckShare returns the violation of res against b, "" when it holds.
+func CheckShare(b ShareBudget, res bench.Result) string {
+	m, ok := res.Find(MetricShare)
+	switch {
+	case !ok:
+		return MetricShare + ": missing from the result"
+	case m.Unit != "pct":
+		return fmt.Sprintf("%s: unit %q, want pct", MetricShare, m.Unit)
+	case math.IsNaN(m.P95) || m.P95 <= 0:
+		return fmt.Sprintf("%s: p95 %v is not a positive number", MetricShare, m.P95)
+	case m.P95 > b.P95Pct:
+		return fmt.Sprintf("%s: p95 %.2f%% exceeds the ceiling %.1f%%", MetricShare, m.P95, b.P95Pct)
+	}
+	return ""
+}
diff --git a/free/ci/bench/sched/share_test.go b/free/ci/bench/sched/share_test.go
new file mode 100644
index 000000000..6499e0b8e
--- /dev/null
+++ b/free/ci/bench/sched/share_test.go
@@ -0,0 +1,53 @@
+package sched
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/bench"
+)
+
+func shareResult(p95 float64, unit string) bench.Result {
+	return bench.NewResult("sha", 20, []bench.Metric{{Name: MetricShare, Unit: unit, P50: p95 / 2, P95: p95, Max: p95, N: 20}})
+}
+
+func TestShareBudgetIsWorstP95TimesHeadroom(t *testing.T) {
+	b, err := ShareFromBaseline([]bench.Result{shareResult(1.0, "pct"), shareResult(2.0, "pct")}, "n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if b.P95Pct != 2.5 {
+		t.Fatalf("ceiling %v, want 2.5", b.P95Pct)
+	}
+	if v := CheckShare(b, shareResult(2.5, "pct")); v != "" {
+		t.Fatalf("a result at the ceiling was refused: %s", v)
+	}
+	if v := CheckShare(b, shareResult(2.6, "pct")); !strings.Contains(v, "exceeds") {
+		t.Fatalf("a result above the ceiling passed: %q", v)
+	}
+}
+
+func TestShareCheckFailsClosed(t *testing.T) {
+	b := ShareBudget{Schema: ShareSchema, P95Pct: 5}
+	if v := CheckShare(b, bench.NewResult("s", 1, nil)); !strings.Contains(v, "missing") {
+		t.Fatalf("missing metric passed: %q", v)
+	}
+	if v := CheckShare(b, shareResult(1, "ms")); !strings.Contains(v, "unit") {
+		t.Fatalf("wrong unit passed: %q", v)
+	}
+	if _, err := LoadShare(filepath.Join(t.TempDir(), "none.json")); err == nil {
+		t.Fatal("a missing ceiling file loaded")
+	}
+}
+
+func TestDecideAdmitsOneLocalJob(t *testing.T) {
+	d, err := Decide(context.Background(), filepath.Join(t.TempDir(), "d"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.PlaceMS <= 0 || d.AdmitMS < d.PlaceMS {
+		t.Fatalf("implausible decision timing %+v", d)
+	}
+}
diff --git a/free/ci/bench/sched/testdata/slow-result.json b/free/ci/bench/sched/testdata/slow-result.json
new file mode 100644
index 000000000..e41d4c26b
--- /dev/null
+++ b/free/ci/bench/sched/testdata/slow-result.json
@@ -0,0 +1,35 @@
+{
+  "schema": "perfbench/v1",
+  "scenario": "ci-sched-overhead",
+  "sha": "0000000000000000000000000000000000000000",
+  "goos": "linux",
+  "goarch": "amd64",
+  "runs": 20,
+  "injected": false,
+  "metrics": [
+    {
+      "name": "sched.place_ms",
+      "unit": "ms",
+      "p50": 250,
+      "p95": 500,
+      "max": 500,
+      "n": 20
+    },
+    {
+      "name": "dispatch.admit_ms",
+      "unit": "ms",
+      "p50": 1500,
+      "p95": 2000,
+      "max": 2000,
+      "n": 20
+    },
+    {
+      "name": "sched.share_tiny_pct",
+      "unit": "pct",
+      "p50": 80,
+      "p95": 90,
+      "max": 90,
+      "n": 20
+    }
+  ]
+}
diff --git a/free/ci/cmd/agent/cache_hook.go b/free/ci/cmd/agent/cache_hook.go
index c9589ae18..dc42ad437 100644
--- a/free/ci/cmd/agent/cache_hook.go
+++ b/free/ci/cmd/agent/cache_hook.go
@@ -84,6 +84,7 @@ func cacheBefore(ctx context.Context, l protocol.Lease, root session.JobRoot) (s
 			_ = base.Close()
 		}
 	}()
+	fetchRestores(ctx, copyStore, l)
 	seen := map[string]bool{}
 	for _, restore := range l.Cache.Restore {
 		sp, ok := specs.Get(restore.Spec)
@@ -110,8 +111,8 @@ func cacheBefore(ctx context.Context, l protocol.Lease, root session.JobRoot) (s
 			if !valid {
 				break
 			}
-			// JobHook.Before has no carrier receiver. Until that protocol hook is
-			// available a missing copy is best effort; never read coordinator paths.
+			// fetchRestores filled the read-through copies; a blob still missing
+			// is a cold miss (nil fetch), and coordinator paths are never read.
 			f, err := copyStore.Open(ctx, l.Cache.Namespace, b.SHA256, b.Size, nil)
 			if err != nil {
 				valid = false
diff --git a/free/ci/cmd/agent/cache_lifecycle.go b/free/ci/cmd/agent/cache_lifecycle.go
index c139c584e..e35d1cea8 100644
--- a/free/ci/cmd/agent/cache_lifecycle.go
+++ b/free/ci/cmd/agent/cache_lifecycle.go
@@ -196,3 +196,20 @@ func validateCachePlan(plan *protocol.LeaseCache) error {
 	}
 	return nil
 }
+
+// fetchRestores takes the lease's restore blobs from the coordinator over the
+// session's reverse blob path (carrier A) into the read-through copies. Without a
+// feed (carrier B, or no restore) nothing is fetched: copies already held are still
+// used, and a missing one is a cold miss that binds nothing.
+func fetchRestores(ctx context.Context, copies *remote.ReadThrough, l protocol.Lease) {
+	feed, ok := session.FeedFrom(ctx)
+	if !ok {
+		return
+	}
+	defer feed.Close()
+	var blobs []protocol.CacheBlob
+	for _, r := range l.Cache.Restore {
+		blobs = append(blobs, r.Blobs...)
+	}
+	(&remote.NodeRestorer{Copies: copies, Feed: feed, Realm: l.Cache.Namespace}).Fetch(ctx, blobs)
+}
diff --git a/free/ci/cmd/artifacts.go b/free/ci/cmd/artifacts.go
index bf6edf0cf..0af37d75d 100644
--- a/free/ci/cmd/artifacts.go
+++ b/free/ci/cmd/artifacts.go
@@ -131,7 +131,7 @@ func openArtifacts(fs *flag.FlagSet) (*artifactsEnv, error) {
 		}
 	}
 	role := authz.Role(firstOf(os.Getenv("NSELF_CI_ROLE"), string(authz.RoleAdmin)))
-	return &artifactsEnv{st: st, blobs: blobs, reader: records.Reader{Ledger: st, Blobs: blobs}, viewer: authz.Viewer{Project: project, Role: role},
+	return &artifactsEnv{st: st, blobs: blobs, reader: records.Reader{Ledger: st, Blobs: blobs, Audit: st.AppendAudit}, viewer: authz.Viewer{Project: project, Role: role},
 		json: fs.Lookup("json").Value.String() == "true"}, nil
 }
 
diff --git a/free/ci/cmd/artifacts_release.go b/free/ci/cmd/artifacts_release.go
index b237c27e1..ec1c19f53 100644
--- a/free/ci/cmd/artifacts_release.go
+++ b/free/ci/cmd/artifacts_release.go
@@ -49,7 +49,7 @@ func publishDeps(st *store.Store, home, root string) (publish.Deps, error) {
 	}
 	env := []string{"NSELF_CI_REPO=" + root, "NSELF_CI_HOME=" + home}
 	return publish.Deps{Src: st, Blobs: blobs, Ledger: st, Home: home, Root: root, Capture: report.Capture, Team: teamCoordinator(),
-		Signer: &signing.Client{Runner: &signing.FunnelRunner{Home: home}, Src: st, Env: env, Team: teamCoordinator()}}, nil
+		Signer: &signing.Client{Runner: &signing.FunnelRunner{Home: home}, Src: st, Env: env, Team: teamCoordinator(), Audit: st.AppendAudit}}, nil
 }
 
 // releasePublisher is the run package's publication seam.
diff --git a/free/ci/cmd/artifacts_verify.go b/free/ci/cmd/artifacts_verify.go
index 5dca5fafe..1d78f4849 100644
--- a/free/ci/cmd/artifacts_verify.go
+++ b/free/ci/cmd/artifacts_verify.go
@@ -12,9 +12,10 @@ package main
 // Outputs: a summary or one v1 envelope (--json) whose data always carries
 // `slsa_build_level: "L1"`; exit 0 verified, 11 invalid (the reason key names
 // the check), 1 evidence failing or quarantined.
-// Constraints: V15 only; side-effect class read: it writes nothing (resolving
-// the pin fetches the default branch into the repository's remote-tracking ref,
-// as the policy resolver does for every run). The trust
+// Constraints: V15 only; side-effect class read: it writes nothing but, on a
+// machine with a coordinator store, one release.verify.refused audit row per
+// refusal (resolving the pin fetches the default branch into the repository's
+// remote-tracking ref, as the policy resolver does for every run). The trust
 // roots are the operator files and the protected default branch at the pinned
 // tip; a pin that cannot be resolved fails the verification (signature), it
 // never silently drops the branch's keys and revocations; the working tree and
@@ -46,6 +47,9 @@ var (
 	releaseDirOf func(ctx context.Context, run string) (dir string, ok bool, err error)
 	// releaseQuarantined reports evidence quarantine (P7-TRUST-20 registers it).
 	releaseQuarantined func(ctx context.Context, ev model.Evidence) (bool, error)
+	// releaseVerifyAudit records a refused verification in the coordinator store (registered with
+	// releaseQuarantined); nil records nothing.
+	releaseVerifyAudit func(ctx context.Context, actor, action, target, detail string) error
 )
 
 func init() { registerArtifactsSub("verify", artifactsVerify) }
@@ -66,7 +70,7 @@ func artifactsVerify(args []string) int {
 	asJSON := fs.Lookup("json").Value.String() == "true"
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
-	opt := verify.Options{Capture: report.Capture, Quarantined: releaseQuarantined}
+	opt := verify.Options{Capture: report.Capture, Quarantined: releaseQuarantined, Audit: releaseVerifyAudit}
 	root, err := evidenceRoot(*repo)
 	if err != nil {
 		return artifactsExit(err, command, asJSON)
diff --git a/free/ci/cmd/codes_registry_test.go b/free/ci/cmd/codes_registry_test.go
index aa3225681..28ccaec6b 100644
--- a/free/ci/cmd/codes_registry_test.go
+++ b/free/ci/cmd/codes_registry_test.go
@@ -107,6 +107,10 @@ func TestCodeRegistry(t *testing.T) {
 		if !strings.HasPrefix(p.ImportPath, "github.com/nself-org/plugins/free/ci/") {
 			continue
 		}
+		// tools/ holds generators (refgen renders the codes table in its own codes.go); they register no codes
+		if strings.HasPrefix(p.ImportPath, "github.com/nself-org/plugins/free/ci/tools/") {
+			continue
+		}
 		for _, file := range p.GoFiles {
 			if filepath.Base(file) == "codes.go" {
 				fragments++
diff --git a/free/ci/cmd/config_ignore.go b/free/ci/cmd/config_ignore.go
new file mode 100644
index 000000000..8193178ab
--- /dev/null
+++ b/free/ci/cmd/config_ignore.go
@@ -0,0 +1,176 @@
+package main
+
+// Purpose: `nself ci config ignore add <fingerprint> --reason <text> [--by <who>]`
+// (P7-AUTO-17): appends a reviewed entry to the repository's .gitleaksignore so
+// the secrets.gitleaks review rule (internal/gates/gitleaks_ignore.go) passes.
+// Inputs:  one gitleaks fingerprint (commit:path:rule:line or path:rule:line),
+// --reason, optional --by and --repo (env NSELF_CI_REPO; default: the
+// current directory).
+// Outputs: one line of text; exit 0 (added, or already present), 1 (refused
+// or not written), 2 (usage).
+// Constraints: V15 only; side-effect class write (one local file, nothing
+// else). The fingerprint is never printed: not on success, not on refusal and
+// not in a flag error. An argument with a known token shape (internal/redact)
+// or a high-entropy segment is refused as a possible real secret.
+
+import (
+	"bytes"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/gates"
+	"github.com/nself-org/plugins/free/ci/internal/redact"
+)
+
+const ignoreAddCommand = "ci config ignore add"
+
+// ignoreDeps are the process facts `config ignore add` reads.
+type ignoreDeps struct {
+	Getenv func(string) string
+	Getwd  func() (string, error)
+	Now    func() time.Time
+}
+
+type ignoreAddOpts struct {
+	reason, by, repo string
+}
+
+func newIgnoreAddFlags() (*flag.FlagSet, *ignoreAddOpts) {
+	o := &ignoreAddOpts{}
+	fs := flag.NewFlagSet(ignoreAddCommand, flag.ContinueOnError)
+	fs.StringVar(&o.reason, "reason", "", "why the finding is not a real secret (required)")
+	fs.StringVar(&o.by, "by", "", "who reviewed the finding")
+	fs.StringVar(&o.repo, "repo", "", "repository root (env NSELF_CI_REPO; default: current directory)")
+	return fs, o
+}
+
+func ignoreAddFlags() *flag.FlagSet { fs, _ := newIgnoreAddFlags(); return fs }
+
+func init() {
+	registerV15("config ignore add", subcommandEntry{
+		V15Only: true,
+		Flags:   ignoreAddFlags,
+		Handler: func(args []string) int {
+			return runIgnoreAdd(args, os.Stdout, os.Stderr, ignoreDeps{Getenv: os.Getenv, Getwd: os.Getwd, Now: time.Now})
+		},
+	})
+}
+
+// parseIgnoreAdd parses flags before and after the positional fingerprint.
+// Flag errors are reported without the offending token, which may be the value.
+func parseIgnoreAdd(args []string) (*ignoreAddOpts, []string, error) {
+	fs, o := newIgnoreAddFlags()
+	fs.SetOutput(io.Discard)
+	var pos []string
+	for {
+		if err := fs.Parse(args); err != nil {
+			return nil, nil, errors.New("usage: nself ci config ignore add <fingerprint> --reason <text> [--by <who>] [--repo <dir>]")
+		}
+		args = fs.Args()
+		if len(args) == 0 {
+			return o, pos, nil
+		}
+		pos, args = append(pos, args[0]), args[1:]
+	}
+}
+
+func runIgnoreAdd(args []string, stdout, stderr io.Writer, d ignoreDeps) int {
+	o, pos, err := parseIgnoreAdd(args)
+	if err != nil {
+		return ignoreFail(stderr, "E812", err.Error(), 2)
+	}
+	if len(pos) != 1 {
+		return ignoreFail(stderr, "E812", "exactly one fingerprint is required", 2)
+	}
+	if strings.TrimSpace(o.reason) == "" {
+		return ignoreFail(stderr, "E812", "--reason is required", 2)
+	}
+	fp := pos[0]
+	if looksSecret(fp) || highEntropy(fp) || looksSecret(o.reason) || looksSecret(o.by) {
+		return ignoreFail(stderr, "E812", "refused: an argument looks like a real secret, not a gitleaks fingerprint; nothing was written and the value is not shown", 1)
+	}
+	valid, withCommit := gates.FingerprintCommit(fp)
+	if !valid {
+		return ignoreFail(stderr, "E812", "the fingerprint is not in a gitleaks form (commit:path:rule:line or path:rule:line)", 1)
+	}
+	root := o.repo
+	if root == "" {
+		root = d.Getenv("NSELF_CI_REPO")
+	}
+	if root == "" {
+		root, err = d.Getwd()
+	} else {
+		root, err = filepath.Abs(root)
+	}
+	if err != nil {
+		return ignoreFail(stderr, "E812", "the repository root cannot be resolved", 2)
+	}
+	added, err := gates.AddReviewedIgnore(root, fp, o.reason, o.by, d.Now())
+	if err != nil {
+		return ignoreFail(stderr, "E812", strings.TrimPrefix(err.Error(), "E812: "), 1)
+	}
+	form := "no-git"
+	if withCommit {
+		form = "git"
+	}
+	if added {
+		_, _ = fmt.Fprintf(stdout, "added one reviewed %s entry (%s form)\n", gates.IgnoreFile, form)
+	} else {
+		_, _ = fmt.Fprintf(stdout, "the entry is already in %s; nothing changed\n", gates.IgnoreFile)
+	}
+	return 0
+}
+
+func ignoreFail(stderr io.Writer, code, msg string, exit int) int {
+	_, _ = fmt.Fprintln(stderr, code+": "+msg)
+	return exit
+}
+
+// looksSecret reports whether s holds a token shape the redactor masks.
+func looksSecret(s string) bool {
+	if s == "" {
+		return false
+	}
+	f := redact.New().NewFilter()
+	out := append(f.Redact([]byte(s)), f.Flush()...)
+	return !bytes.Equal(out, []byte(s))
+}
+
+// highEntropy reports whether a fingerprint segment (split on ':', '/', '\'
+// and '.') of 20 or more bytes mixes letters and digits at 3.5 bits per byte
+// or more. A leading commit hash is skipped, since hex is what a commit is.
+func highEntropy(fp string) bool {
+	if valid, withCommit := gates.FingerprintCommit(fp); valid && withCommit {
+		fp = fp[strings.Index(fp, ":")+1:]
+	}
+	segs := strings.FieldsFunc(fp, func(r rune) bool { return r == ':' || r == '/' || r == '\\' || r == '.' })
+	for _, s := range segs {
+		if len(s) >= 20 && strings.ContainsAny(s, "0123456789") && strings.ContainsAny(strings.ToLower(s), "abcdefghijklmnopqrstuvwxyz") && entropy(s) >= 3.5 {
+			return true
+		}
+	}
+	return false
+}
+
+// entropy is the Shannon entropy of s in bits per byte.
+func entropy(s string) float64 {
+	var counts [256]int
+	for i := 0; i < len(s); i++ {
+		counts[s[i]]++
+	}
+	h, n := 0.0, float64(len(s))
+	for _, c := range counts {
+		if c > 0 {
+			p := float64(c) / n
+			h -= p * math.Log2(p)
+		}
+	}
+	return h
+}
diff --git a/free/ci/cmd/config_ignore_test.go b/free/ci/cmd/config_ignore_test.go
new file mode 100644
index 000000000..51b2092ef
--- /dev/null
+++ b/free/ci/cmd/config_ignore_test.go
@@ -0,0 +1,151 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/gates"
+)
+
+const (
+	ignoreFPGit   = "0123456789abcdef0123456789abcdef01234567" + ":internal/fixture.go:generic-api-key:12"
+	ignoreFPNoGit = "testdata/fixture.env:aws-access-token:3"
+)
+
+func ignoreTestDeps(root string) ignoreDeps {
+	return ignoreDeps{
+		Getenv: func(string) string { return "" },
+		Getwd:  func() (string, error) { return root, nil },
+		Now:    func() time.Time { return time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) },
+	}
+}
+
+func runIgnore(t *testing.T, root string, args ...string) (int, string, string) {
+	t.Helper()
+	var out, errb bytes.Buffer
+	code := runIgnoreAdd(args, &out, &errb, ignoreTestDeps(root))
+	return code, out.String(), errb.String()
+}
+
+func readIgnore(t *testing.T, root string) string {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join(root, gates.IgnoreFile))
+	if err != nil && !os.IsNotExist(err) {
+		t.Fatal(err)
+	}
+	return string(raw)
+}
+
+// fakeSecrets are token shapes assembled at run time so no literal looks like a credential.
+func fakeSecrets() []string {
+	body := strings.Repeat("Ab3Xy9", 6)
+	return []string{
+		"gh" + "p_" + body,
+		"AK" + "IA" + "QWERTYUIOP234567",
+		"path/" + "gl" + "pat-" + body + ":rule:1",
+	}
+}
+
+// strideSegment builds an n-byte mixed letter and digit segment of distinct
+// bytes, high in entropy without a literal in the source.
+func strideSegment(n int) string {
+	const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = alphabet[(i*7)%len(alphabet)]
+	}
+	return string(b)
+}
+
+func TestIgnoreAddRefusesSecretShape(t *testing.T) {
+	for _, secret := range fakeSecrets() {
+		root := t.TempDir()
+		code, out, errs := runIgnore(t, root, secret, "--reason", "fixture")
+		if code != 1 || !strings.Contains(errs, "E812") || readIgnore(t, root) != "" {
+			t.Fatalf("token shape not refused: exit %d out %q", code, out)
+		}
+	}
+	root := t.TempDir()
+	random := "cfg/" + strideSegment(24) + ".env:generic-api-key:4"
+	if code, _, _ := runIgnore(t, root, random, "--reason", "x"); code != 1 || readIgnore(t, root) != "" {
+		t.Fatalf("high-entropy segment not refused: exit %d", code)
+	}
+	if code, _, _ := runIgnore(t, root, ignoreFPNoGit, "--reason", "copied "+fakeSecrets()[0]); code != 1 {
+		t.Fatal("token-shaped reason not refused")
+	}
+}
+
+func TestIgnoreAddNeverEchoes(t *testing.T) {
+	args := [][]string{
+		{fakeSecrets()[0], "--reason", "r"},
+		{fakeSecrets()[1], "--reason", "r", "--by", "sam"},
+		{"-" + fakeSecrets()[0], "--reason", "r"},
+		{"not-a-fingerprint-" + "value", "--reason", "r"},
+		{ignoreFPGit, "--reason", "fixture", "--by", "sam"},
+		{ignoreFPNoGit, "--reason", "fixture"},
+		{ignoreFPNoGit, ignoreFPGit, "--reason", "two"},
+		{ignoreFPNoGit},
+	}
+	for _, a := range args {
+		root := t.TempDir()
+		_, out, errs := runIgnore(t, root, a...)
+		value := strings.TrimPrefix(a[0], "-")
+		for _, frag := range []string{value, "fixture.go", "fingerprint-value", fakeSecrets()[0][4:]} {
+			if strings.Contains(out+errs, frag) {
+				t.Fatalf("output echoes the argument (%q): %q %q", frag, out, errs)
+			}
+		}
+	}
+}
+
+func TestIgnoreAddIdempotent(t *testing.T) {
+	root := t.TempDir()
+	for i := 0; i < 2; i++ {
+		if code, _, errs := runIgnore(t, root, ignoreFPGit, "--reason", "test fixture", "--by", "sam"); code != 0 {
+			t.Fatalf("run %d: exit %d %s", i, code, errs)
+		}
+	}
+	want := "# Reviewed 2026-10-27 by sam: test fixture\n" + ignoreFPGit + "\n"
+	if got := readIgnore(t, root); got != want {
+		t.Fatalf("got %q want %q", got, want)
+	}
+	if err := gates.ReviewIgnoreFile(root); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestIgnoreAddBothForms(t *testing.T) {
+	root := t.TempDir()
+	for fp, form := range map[string]string{ignoreFPGit: "git", ignoreFPNoGit: "no-git"} {
+		code, out, errs := runIgnore(t, root, "--reason", "fixture", fp)
+		if code != 0 || !strings.Contains(out, "added one reviewed") || !strings.Contains(out, "("+form+" form)") {
+			t.Fatalf("%s form: exit %d %q %q", form, code, out, errs)
+		}
+	}
+	got := readIgnore(t, root)
+	if !strings.Contains(got, ignoreFPGit+"\n") || !strings.Contains(got, ignoreFPNoGit+"\n") {
+		t.Fatalf("missing entries: %q", got)
+	}
+	if err := gates.ReviewIgnoreFile(root); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestIgnoreAddUsage(t *testing.T) {
+	root := t.TempDir()
+	for _, a := range [][]string{{ignoreFPNoGit}, {}, {"--bogus", ignoreFPNoGit, "--reason", "r"}, {"src/config.go:rule:0", "--reason", "r"}} {
+		if code, _, _ := runIgnore(t, root, a...); code == 0 {
+			t.Errorf("%d args: accepted", len(a))
+		}
+	}
+	if readIgnore(t, root) != "" {
+		t.Fatal("a refused call wrote the file")
+	}
+	if _, ok := v15Subcommands["config ignore add"]; !ok {
+		t.Fatal("config ignore add is not registered")
+	}
+}
diff --git a/free/ci/cmd/doctor_selftest.go b/free/ci/cmd/doctor_selftest.go
new file mode 100644
index 000000000..6a1a8ea21
--- /dev/null
+++ b/free/ci/cmd/doctor_selftest.go
@@ -0,0 +1,130 @@
+package main
+
+// Purpose: `nself ci doctor --selftest [--alert]` (P7-AUTO-20): registers the selftest doctor
+// section (checks CI-DS001…) and the alerter, and wires the real host to internal/selftest.
+// Inputs:  the doctor Env (repository root, process runner, environment) and the run store.
+// Outputs: doctor checks; with --alert one notifier message per failing set per day.
+// Constraints: read-only; the store is opened only when state.db exists and never created or
+// recovered; an unreadable source is a warning on its own check, not a failure of the report.
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/evidence"
+	"github.com/nself-org/plugins/free/ci/internal/history"
+	"github.com/nself-org/plugins/free/ci/internal/notify"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/readiness/sample"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/selftest"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func init() {
+	doctor.RegisterSection(doctor.Section{Name: "selftest", Selector: doctor.SelectSelftest, Run: selftestRun})
+	doctor.SetAlerter(selftestAlert)
+}
+
+// openStateReadOnly opens the run store when it exists; nil when there is none.
+func openStateReadOnly() (*store.Store, error) {
+	if !evidence.StoreExists(evidence.StorePath()) {
+		return nil, nil
+	}
+	return cirun.OpenStore(runsStorePath())
+}
+
+// selftestLocal wires the real host. st may be nil (no store on this machine).
+func selftestLocal(env doctor.Env, st *store.Store) selftest.Local {
+	l := selftest.Local{Root: env.Root, Home: sample.CIHome(), Path: env.Getenv("PATH"), Capture: env.Capture}
+	if st == nil {
+		return l
+	}
+	l.Sinks = func(ctx context.Context) ([]selftest.Sink, error) {
+		stats, err := st.NotifySinkStats(ctx)
+		out := make([]selftest.Sink, 0, len(stats))
+		for _, s := range stats {
+			sink := selftest.Sink{Name: s.Sink, Delivered: s.Delivered, Failed: s.Failed}
+			if s.LastFailedAt > 0 {
+				sink.LastFailedAt = time.Unix(0, s.LastFailedAt).UTC()
+			}
+			out = append(out, sink)
+		}
+		return out, err
+	}
+	l.Infra = func(ctx context.Context, since time.Time) (count, total int, err error) {
+		entries, err := history.List(ctx, history.Env{Store: st, Root: env.Root, Home: os.Getenv("NSELF_CI_HOME")}, history.MaxLimit)
+		for _, e := range entries {
+			at, perr := time.Parse(time.RFC3339Nano, e.StartedAt)
+			if perr != nil || at.Before(since) {
+				continue
+			}
+			total++
+			if e.Result == "error" {
+				count++
+			}
+		}
+		return count, total, err
+	}
+	return l
+}
+
+func selftestRun(ctx context.Context, env doctor.Env) []doctor.Check {
+	st, err := openStateReadOnly()
+	if st != nil {
+		defer func() { _ = st.Close() }()
+	}
+	l := selftestLocal(env, st)
+	if err != nil { // the store exists but cannot be opened: its three facts are unreadable, the rest still count
+		bad := func(context.Context) error { return err }
+		l.Sinks = func(ctx context.Context) ([]selftest.Sink, error) { return nil, bad(ctx) }
+		l.Infra = func(ctx context.Context, _ time.Time) (int, int, error) { return 0, 0, bad(ctx) }
+	}
+	return selftest.Evaluate(l.Facts(ctx), selftest.DefaultLimits())
+}
+
+// policyEffective resolves the operator policy for root against the default store.
+func policyEffective(ctx context.Context, root string) (policy.Effective, func(), error) {
+	st, err := cirun.OpenStore("")
+	if err != nil {
+		return policy.Effective{}, func() {}, err
+	}
+	release := func() { _ = st.Close() }
+	run := policy.Runner(report.Capture)
+	res := policy.Resolver{Store: st, Run: run}
+	got, err := res.Resolve(ctx, policy.Repo{Root: root, Project: policy.ProjectIDGitCached(ctx, run, root), Visibility: "unknown", Class: "owner"}, policy.Revision{})
+	return got.Effective, release, err
+}
+
+func selftestAlert(ctx context.Context, env doctor.Env, checks []doctor.Check) (string, error) {
+	eff, release, err := policyEffective(ctx, env.Root)
+	defer release()
+	if err != nil {
+		return "", err
+	}
+	cfg, err := notify.ConfigFrom(&eff)
+	if err != nil {
+		return "", err
+	}
+	sinks, errs := notify.Build(cfg.Sinks, notify.Deps{AllowPrivate: cfg.AllowPrivate})
+	host, _ := os.Hostname()
+	a := selftest.Alerter{Sinks: sinks, Host: host, StatePath: filepath.Join(sample.CIHome(), "selftest-alert.json")}
+	res, aerr := a.Alert(ctx, checks)
+	for _, e := range errs {
+		if aerr == nil {
+			aerr = e
+		}
+	}
+	switch {
+	case res.Sent:
+		return "alert sent for " + res.Set, aerr
+	case res.Skipped != "" && res.Set != "":
+		return "alert not sent for " + res.Set + ": " + res.Skipped, aerr
+	}
+	return strings.TrimSpace(res.Skipped), aerr
+}
diff --git a/free/ci/cmd/help_dispatch.go b/free/ci/cmd/help_dispatch.go
new file mode 100644
index 000000000..669e6c47c
--- /dev/null
+++ b/free/ci/cmd/help_dispatch.go
@@ -0,0 +1,101 @@
+package main
+
+// Purpose: `nself ci <sub> --help` and `-h` print that subcommand's help and exit 0 before anything runs.
+// Inputs:  a matched key and the args after it; the v1.4 and v1.5 subcommand tables.
+// Outputs: help text on stdout and exit code 0.
+// Constraints: the dispatchers (run, runV15) call answerHelp before the handler and before the nodes
+// --coordinator client, so a help request never starts a run or sends a request; a "--" terminator
+// ends the scan (wantsHelp); a group word with no handler of its own (config, nodes pools) lists its
+// children instead of falling through to the gate.
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/surface"
+)
+
+// coreHelp holds the keys whose help keeps core's exact behaviour (captured text, and a flag that
+// does not parse before the help token is an error); each answers without running the command.
+var coreHelp = map[string]func(args []string) int{}
+
+// answerHelp prints the help of key for a help request and returns the exit code.
+func answerHelp(key string, args []string) int {
+	if h, ok := coreHelp[key]; ok {
+		return h(args)
+	}
+	fmt.Print(subHelp(key))
+	return 0
+}
+
+// subHelp returns the help text of a registered key: the captured core text when there is one, else
+// the usage line, the flag defaults of its V15 entry and the child commands under the key.
+func subHelp(key string) string {
+	if txt, ok := surface.Help(key); ok {
+		return txt
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "Usage: nself ci %s [flags]\n", key)
+	if e, ok := v15Subcommands[key]; ok && e.Flags != nil {
+		if fs := e.Flags(); fs != nil {
+			prev := fs.Output()
+			fs.SetOutput(&b)
+			b.WriteString("\nFlags:\n")
+			fs.PrintDefaults()
+			fs.SetOutput(prev)
+		}
+	}
+	if kids := childKeys(key); len(kids) > 0 {
+		b.WriteString("\nCommands:\n")
+		for _, k := range kids {
+			b.WriteString("  " + k + "\n")
+		}
+	}
+	return b.String()
+}
+
+// childKeys lists the registered keys one or more tokens below key, sorted and without duplicates.
+func childKeys(key string) []string {
+	seen := map[string]bool{}
+	prefix := key + " "
+	for k := range subcommands {
+		if strings.HasPrefix(k, prefix) {
+			seen[k] = true
+		}
+	}
+	for k, e := range v15Subcommands {
+		if strings.HasPrefix(k, prefix) && !e.Hidden {
+			seen[k] = true
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for k := range seen {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// helpForGroup prints the child list of a leading word that names a group (for example "nodes pools")
+// but no command of its own, and reports whether args named one. Only called when wantsHelp(args).
+func helpForGroup(args []string) bool {
+	var words []string
+	for _, a := range args {
+		if strings.HasPrefix(a, "-") {
+			break
+		}
+		words = append(words, a)
+	}
+	for n := len(words); n >= 1; n-- {
+		key := strings.Join(words[:n], " ")
+		if kids := childKeys(key); len(kids) > 0 {
+			fmt.Print("Usage: nself ci " + key + " <command> [flags]\n\nCommands:\n")
+			for _, k := range kids {
+				fmt.Println("  " + k)
+			}
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/cmd/help_dispatch_test.go b/free/ci/cmd/help_dispatch_test.go
new file mode 100644
index 000000000..3539b210a
--- /dev/null
+++ b/free/ci/cmd/help_dispatch_test.go
@@ -0,0 +1,107 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+// stubAllHandlers swaps every registered handler of both tables for one that records its key and
+// returns 99, and restores the tables when the test ends. A help request that reaches a handler (or the
+// gate or the bare run behind it) is then visible as a recorded key or a non-zero exit.
+func stubAllHandlers(t *testing.T) *[]string {
+	t.Helper()
+	var ran []string
+	old14, old15 := subcommands, v15Subcommands
+	subcommands, v15Subcommands = map[string]handler{}, map[string]subcommandEntry{}
+	for k := range old14 {
+		key := "v14 " + k
+		subcommands[k] = func([]string) int { ran = append(ran, key); return 99 }
+	}
+	for k, e := range old15 {
+		key, entry := "v15 "+k, e
+		entry.Handler = func([]string) int { ran = append(ran, key); return 99 }
+		v15Subcommands[k] = entry
+	}
+	t.Cleanup(func() { subcommands, v15Subcommands = old14, old15 })
+	return &ran
+}
+
+// allKeys is every key of both tables, hidden entries included.
+func allKeys() []string {
+	seen := map[string]bool{}
+	var out []string
+	for k := range subcommands {
+		seen[k] = true
+	}
+	for k := range v15Subcommands {
+		seen[k] = true
+	}
+	for k := range seen {
+		out = append(out, k)
+	}
+	return out
+}
+
+// Asking any registered subcommand for help prints help, exits 0 and runs nothing: not the handler, not
+// the nodes --coordinator client (which would dial the URL), not the bare run or the gate. The table is
+// built from the registries, so a new subcommand is covered the day it is registered.
+func TestEverySubcommandHelpRunsNothing(t *testing.T) {
+	keys := allKeys()
+	if len(keys) < 40 {
+		t.Fatalf("only %d registered keys; the registries did not load", len(keys))
+	}
+	ran := stubAllHandlers(t)
+	t.Setenv("NSELF_CI_HOME", t.TempDir())
+	t.Chdir(t.TempDir())
+	for _, key := range keys {
+		for _, extra := range [][]string{
+			{"--help"}, {"-h"}, {"-help"},
+			{"--coordinator", "http://127.0.0.1:1", "--help"}, // must not dial
+		} {
+			args := append(strings.Fields(key), extra...)
+			// a core-help key keeps core's (or the frozen v1.4) answer: help may go to stderr, and a flag
+			// that does not parse before the help token is an error; either way nothing runs
+			_, core := coreHelp[key]
+			plain := extra[0] == "--help" || extra[0] == "-h"
+			for name, dispatch := range map[string]func([]string) int{"run": run, "runV15": runV15} {
+				var code int
+				out, errOut := captureStd(t, func() { code = dispatch(args) })
+				if core {
+					helped := code == 0 && strings.TrimSpace(out+errOut) != ""
+					refused := !plain && code != 0 && strings.TrimSpace(errOut) != ""
+					if len(*ran) != 0 || !helped && !refused {
+						t.Errorf("%s %q: exit %d, handlers run %v, stdout %q, stderr %q; want help or a parse error, nothing run",
+							name, args, code, *ran, out, errOut)
+						*ran = nil
+					}
+					continue
+				}
+				if code != 0 || len(*ran) != 0 || strings.TrimSpace(out) == "" {
+					t.Errorf("%s %q: exit %d, handlers run %v, stdout %q, stderr %q; want exit 0, nothing run, help on stdout",
+						name, args, code, *ran, out, errOut)
+					*ran = nil
+				}
+			}
+		}
+	}
+}
+
+// A help request after the "--" terminator belongs to the command being run, not to nself ci.
+func TestHelpAfterTerminatorIsNotHelp(t *testing.T) {
+	if wantsHelp([]string{"--", "--help"}) || wantsHelp([]string{"-h", "--", "x"}) == false {
+		t.Fatal("wantsHelp must stop at the terminator and see a flag before it")
+	}
+}
+
+// A group word with no command of its own lists its children and runs nothing.
+func TestGroupHelpListsChildren(t *testing.T) {
+	ran := stubAllHandlers(t)
+	t.Chdir(t.TempDir())
+	for group, child := range map[string]string{"config": "config show", "nodes pools": "nodes pools list", "policy": "policy show"} {
+		var code int
+		out, _ := captureStd(t, func() { code = runV15(append(strings.Fields(group), "--help")) })
+		if code != 0 || len(*ran) != 0 || !strings.Contains(out, child) {
+			t.Errorf("%s --help: exit %d, ran %v, stdout %q; want exit 0, nothing run, %q listed", group, code, *ran, out, child)
+		}
+	}
+}
diff --git a/free/ci/cmd/main.go b/free/ci/cmd/main.go
index 5b7fd8203..02add2c6d 100644
--- a/free/ci/cmd/main.go
+++ b/free/ci/cmd/main.go
@@ -43,21 +43,21 @@ func main() {
 	os.Exit(run(os.Args[1:]))
 }
 
-// run dispatches argv and returns the exit code. A bare -h/--help in front of
-// a command that has captured core help prints that text; the first token
-// that is not a flag selects a registered subcommand, otherwise the argv is
-// the single-repo gate.
+// run dispatches argv and returns the exit code. A -h/--help after a registered
+// command prints that command's help and exits 0 without running it (help_dispatch.go).
+// The first token that is not a flag selects a registered subcommand, otherwise
+// the argv is the single-repo gate.
 func run(args []string) int {
 	if h, key, rest, ok := resolve(args); ok {
-		if wantsHelp(rest) {
-			if printHelp(key) {
-				return 0
-			}
+		if wantsHelp(rest) { // help never reaches the handler: it must not start anything
+			return answerHelp(key, rest)
 		}
 		return h(rest)
 	}
-	if wantsHelp(args) && printHelp("") {
-		return 0
+	if wantsHelp(args) {
+		if helpForGroup(args) || printHelp("") {
+			return 0
+		}
 	}
 	return gateCmd(args)
 }
diff --git a/free/ci/cmd/nodes_label.go b/free/ci/cmd/nodes_label.go
new file mode 100644
index 000000000..ca38f6863
--- /dev/null
+++ b/free/ci/cmd/nodes_label.go
@@ -0,0 +1,205 @@
+package main
+
+// Purpose: `nself ci nodes label <node|local> [key|key=value]... [--remove key...] [--json]` (P7-NODE-30,
+// Epic NODE D19): coordinator-assigned node labels. Placement matches them against a job's
+// requires.labels and the project policy sched.overrides.labels. With no label and no --remove the
+// command lists the node's labels. `local` addresses the invoking machine's runner.
+// Inputs:  the node id, labels and keys; env NSELF_CI_HOME; --coordinator <url> for a TEAM coordinator.
+// Outputs: the node's labels as a line or one v1 JSON envelope (identity.labels, source assigned); exit 0,
+//          1 (usage, E658, unknown node, refusal), 2 (infrastructure).
+// Constraints: V15 only; side-effect class: write (list: read); every change writes one audit row per
+//          label; this file also holds the helpers shared with nodes_projects.go (failure printing, the
+//          project resolver, the coordinator runner) and registers the world label source.
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+const nodesLabelUsage = "usage: nself ci nodes label <node|local> [key|key=value]... [--remove key...] [--json] [--coordinator <url>]"
+
+func nodesLabelFlags() *flag.FlagSet {
+	fs := flag.NewFlagSet("nodes label", flag.ContinueOnError)
+	fs.Bool("json", false, "print one v1 JSON envelope")
+	fs.String("remove", "", "remove these label keys (every word after --remove up to the next flag)")
+	lifecycle.AddCoordinatorFlag(fs)
+	return fs
+}
+
+func init() {
+	registerV15("nodes label", subcommandEntry{
+		V15Only: true,
+		Flags:   nodesLabelFlags,
+		Handler: func(args []string) int {
+			if code, done := placementRemote("label", args, os.Stdout, os.Stderr); done {
+				return code
+			}
+			return runNodesLabel(args, lifecycle.ProductionEnv(currentProject), false, os.Stdout, os.Stderr)
+		},
+	})
+	reader := &labels.LazyReader{Path: func() string { return filepath.Join(lifecycle.CIHome(), "state.db") },
+		Live: func() *store.Store {
+			if d := nodeAdminDeps.Load(); d != nil {
+				return d.store
+			}
+			return nil
+		}}
+	if err := labels.RegisterSource(reader); err != nil {
+		panic("nself-ci: " + err.Error())
+	}
+	if err := clientapi.RegisterPlacementRoutes(func() clientapi.PlacementRunner {
+		if nodeAdminDeps.Load() == nil {
+			return nil
+		}
+		return runPlacementCommand
+	}); err != nil {
+		panic("nself-ci: " + err.Error())
+	}
+}
+
+// parseNodesLabel splits argv into the node, the labels to set, the keys to remove and --json.
+func parseNodesLabel(args []string) (node string, add, remove []string, asJSON bool, err error) {
+	removing := false
+	for _, a := range args {
+		switch {
+		case a == "--json" || a == "-json" || a == "--json=true" || a == "-json=true":
+			asJSON = true
+		case a == "--remove" || a == "-remove":
+			removing = true
+		case strings.HasPrefix(a, "--remove=") || strings.HasPrefix(a, "-remove="):
+			_, v, _ := strings.Cut(a, "=")
+			remove = append(remove, v)
+		case strings.HasPrefix(a, "-"):
+			err = placementUsage("unknown flag " + a)
+			return
+		case node == "":
+			node = strings.ToLower(a)
+		case removing:
+			remove = append(remove, a)
+		default:
+			add = append(add, a)
+		}
+	}
+	if node == "" {
+		err = placementUsage(nodesLabelUsage)
+	} else if node != labels.LocalNode && remote.ValidateNodeID(node) != nil {
+		err = placementUsage("the node id is not valid (letters, digits, dot, dash, underscore)")
+	}
+	return
+}
+
+// runNodesLabel is the handler with its environment injected, for tests. team is true on a coordinator.
+func runNodesLabel(args []string, env lifecycle.Env, team bool, out, errOut io.Writer) int {
+	node, add, remove, asJSON, err := parseNodesLabel(args)
+	if err != nil {
+		return placementFail(out, errOut, "ci nodes label", asJSON || hasJSONArg(args), err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	d, closeFn, err := env.Open(ctx, "")
+	if err != nil {
+		return placementFail(out, errOut, "ci nodes label", asJSON, placementInfra("the CI store cannot be opened: "+oneLine(err)))
+	}
+	defer closeFn()
+	e := placementEnv(d, team)
+	var set []store.NodeLabel
+	if len(add)+len(remove) == 0 {
+		set, err = e.Labels(ctx, node)
+	} else {
+		set, err = e.Edit(ctx, node, add, remove)
+	}
+	if err != nil {
+		return placementFail(out, errOut, "ci nodes label", asJSON, err)
+	}
+	if asJSON {
+		items := make([]map[string]string, 0, len(set))
+		for _, l := range set {
+			items = append(items, map[string]string{"key": l.Key, "value": l.Value, "source": "assigned"})
+		}
+		data := map[string]any{"node": node, "identity": map[string]any{"labels": items}}
+		if output.WriteData(out, "ci nodes label", data, nil) != nil {
+			return output.ExitInfra
+		}
+		return 0
+	}
+	if len(set) == 0 {
+		_, _ = fmt.Fprintf(out, "node %s: no labels\n", node)
+		return 0
+	}
+	_, _ = fmt.Fprintf(out, "node %s: labels %s\n", node, strings.Join(labels.Strings(set), " "))
+	return 0
+}
+
+// placementEnv is the label and project environment of one command.
+func placementEnv(d *lifecycle.Deps, team bool) labels.Env {
+	e := labels.Env{Store: d.Store, Registry: d.Registry, Actor: d.Actor, Team: team}
+	if !team {
+		e.ResolveDir = func(ctx context.Context, dir string) (string, bool) {
+			root, err := filepath.Abs(dir)
+			if err != nil {
+				return "", false
+			}
+			id := policy.ProjectIDGit(ctx, policy.Runner(report.Capture), root)
+			return id, id != ""
+		}
+	}
+	return e
+}
+
+type placementError struct{ code, msg string }
+
+func (e *placementError) Error() string { return e.msg }
+
+func placementUsage(msg string) error { return &placementError{"E651", msg} }
+func placementInfra(msg string) error { return &placementError{"E607", msg} }
+
+func oneLine(err error) string { return strings.Join(strings.Fields(err.Error()), " ") }
+
+// placementFail prints err (a JSON error envelope with --json) and returns its exit code.
+func placementFail(out, errOut io.Writer, command string, asJSON bool, err error) int {
+	code, exit := "E607", output.ExitInfra
+	var pe *placementError
+	var le *labels.Error
+	var re *registry.Error
+	var se *store.Error
+	var lc *lifecycle.Error
+	switch {
+	case errors.As(err, &pe):
+		code = pe.code
+	case errors.As(err, &le):
+		code = le.Code
+	case errors.As(err, &re):
+		code = re.Code
+	case errors.As(err, &lc):
+		code = lc.Code
+	case errors.As(err, &se):
+		code = se.Code
+	}
+	switch code {
+	case "E650", "E651", "E657", "E658", "E664":
+		exit = output.ExitUser
+	}
+	if asJSON {
+		_ = output.WriteError(out, command, output.ErrorDetail{Code: code, Message: oneLine(err), ExitCode: exit}, nil)
+		return exit
+	}
+	_, _ = io.WriteString(errOut, oneLine(err)+"\n")
+	return exit
+}
diff --git a/free/ci/cmd/nodes_pools.go b/free/ci/cmd/nodes_pools.go
new file mode 100644
index 000000000..71dbe5ca0
--- /dev/null
+++ b/free/ci/cmd/nodes_pools.go
@@ -0,0 +1,263 @@
+package main
+
+// Purpose: `nself ci nodes pools list|show|explain` (P7-AUTO-03, Epic AUTO D4, D10): the pools of the
+//          runners this person can reach (contract:ci.pool v1) and the effective set of a project. Also
+//          the composition root of the pools exclusion provider, so `ci plan` carries the same
+//          pool.excluded reasons.
+// Inputs:  show takes a pool id; --project <dir> (default: the current repository, env NSELF_CI_REPO);
+//          --json; env NSELF_CI_HOME (the store with the nodes, their assigned labels and policy rows).
+// Outputs: a table or one v1 JSON envelope; exit 0, 1 (usage, unknown pool), 2 (infrastructure).
+// Constraints: V15 only; side-effect class read. Membership is the assigned `pool.<id>` label only; a
+//          node's self-declared labels are never read. The policy comes from the TRUST-27 loader (store
+//          rows, protected default branch `.nself/ci.yaml`); outside a repository list and show fall back
+//          to every term unset and say so, explain refuses.
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/providers"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+type nodesPoolsOpts struct {
+	json    bool
+	project string
+}
+
+func newNodesPoolsFlags() (*flag.FlagSet, *nodesPoolsOpts) {
+	o := &nodesPoolsOpts{}
+	fs := flag.NewFlagSet("nodes pools", flag.ContinueOnError)
+	fs.BoolVar(&o.json, "json", false, "print one v1 JSON envelope")
+	fs.StringVar(&o.project, "project", "", "project directory whose pools.allow applies (default: the current repository)")
+	return fs, o
+}
+
+func nodesPoolsFlags() *flag.FlagSet { fs, _ := newNodesPoolsFlags(); return fs }
+
+// poolsWorld is what the pools commands read: the reachable runners and the project's resolved policy.
+type poolsWorld struct {
+	Runners   []pools.Runner
+	Project   string
+	Policy    trust.Effective
+	PolicyErr error
+}
+
+// poolsDeps loads a poolsWorld for a project directory ("" means the current repository).
+type poolsDeps struct {
+	Load func(ctx context.Context, dir string) (poolsWorld, error)
+}
+
+func init() {
+	for _, sub := range []string{"list", "show", "explain"} {
+		sub := sub
+		registerV15("nodes pools "+sub, subcommandEntry{
+			V15Only: true,
+			Flags:   nodesPoolsFlags,
+			Handler: func(args []string) int {
+				return runNodesPools(sub, args, poolsDeps{Load: loadPoolsWorld}, os.Stdout, os.Stderr)
+			},
+		})
+	}
+	reader := &labels.LazyReader{Path: func() string { return filepath.Join(lifecycle.CIHome(), "state.db") },
+		Live: func() *store.Store {
+			if d := nodeAdminDeps.Load(); d != nil {
+				return d.store
+			}
+			return nil
+		}}
+	// The world builder runs only on the v1.5 plan path (v1.4 dispatches to internal/legacy), so the
+	// provider is dormant in v1.4 without a gate of its own.
+	fn := pools.ExclusionProvider(pools.Config{Labels: reader, Team: func() bool { return nodeAdminDeps.Load() != nil }})
+	if err := autoworld.RegisterExclusion(pools.ProviderName, fn); err != nil {
+		panic("nself-ci: " + err.Error())
+	}
+}
+
+// parseNodesPools splits argv into the options and the positional arguments.
+func parseNodesPools(sub string, args []string) (*nodesPoolsOpts, []string, error) {
+	fs, o := newNodesPoolsFlags()
+	fs.SetOutput(io.Discard)
+	usage := placementUsage("usage: nself ci nodes pools " + map[string]string{"list": "list", "show": "show <pool>", "explain": "explain"}[sub] + " [--project <dir>] [--json]")
+	var pos []string
+	for {
+		if err := fs.Parse(args); err != nil {
+			return o, nil, usage
+		}
+		if args = fs.Args(); len(args) == 0 {
+			break
+		}
+		pos, args = append(pos, args[0]), args[1:]
+	}
+	if want := map[string]int{"show": 1}[sub]; len(pos) != want {
+		return o, nil, usage
+	}
+	if sub == "show" && !pools.ValidID(pos[0]) {
+		return o, nil, placementUsage("the pool id is not valid (^[a-z][a-z0-9-]{0,30}$)")
+	}
+	return o, pos, nil
+}
+
+// runNodesPools is the handler with its environment injected.
+func runNodesPools(sub string, args []string, d poolsDeps, out, errOut io.Writer) int {
+	command := "ci nodes pools " + sub
+	o, pos, err := parseNodesPools(sub, args)
+	if err != nil {
+		return placementFail(out, errOut, command, o.json || hasJSONArg(args), err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	w, err := d.Load(ctx, o.project)
+	if err != nil {
+		return placementFail(out, errOut, command, o.json, placementInfra("the pools cannot be read: "+oneLine(err)))
+	}
+	var notes []string
+	in := pools.Input{Runners: w.Runners, Project: w.Project}
+	if w.PolicyErr != nil {
+		if sub == "explain" || o.project != "" {
+			return placementFail(out, errOut, command, o.json, placementInfra("the project policy cannot be resolved: "+oneLine(w.PolicyErr)))
+		}
+		notes = append(notes, "no project policy ("+oneLine(w.PolicyErr)+"): every pool term is unset")
+		in.Project = ""
+	} else {
+		var more []string
+		in.Allow, in.DevPools, more = pools.FromPolicy(w.Policy)
+		notes = append(notes, more...)
+	}
+	res := pools.Resolve(in)
+	switch sub {
+	case "list":
+		return writePools(out, command, o.json, res.Pools, notes)
+	case "show":
+		for _, p := range res.Pools {
+			if p.ID == pos[0] {
+				return writePools(out, command, o.json, []pools.Pool{p}, notes)
+			}
+		}
+		return placementFail(out, errOut, command, o.json, placementUsage("pool "+pos[0]+" has no member"))
+	}
+	data := pools.Explain(in, notes)
+	if o.json {
+		return writeEnvelope(out, command, data)
+	}
+	writeExplainText(out, data)
+	return 0
+}
+
+// writeEnvelope prints one v1 data envelope; the shared writer maps a write failure to the infra exit.
+func writeEnvelope(out io.Writer, command string, data any) int {
+	return backupData(backupEnv{Out: out}, command, data)
+}
+
+func writePools(out io.Writer, command string, asJSON bool, ps []pools.Pool, notes []string) int {
+	if asJSON {
+		return writeEnvelope(out, command, map[string]any{"pools": ps, "notes": append([]string{}, notes...)})
+	}
+	for _, p := range ps {
+		state := "allowed"
+		if !p.Effective.Allowed {
+			state = "excluded " + p.Effective.Reasons[0].Detail
+		}
+		ids := make([]string, 0, len(p.Members))
+		for _, m := range p.Members {
+			ids = append(ids, m.RunnerID)
+		}
+		_, _ = fmt.Fprintf(out, "%s\t%s\t%s\t%s\n", p.ID, p.Scope, state, strings.Join(ids, " "))
+	}
+	for _, n := range notes {
+		_, _ = fmt.Fprintf(out, "note: %s\n", plainText(n))
+	}
+	return 0
+}
+
+func writeExplainText(out io.Writer, d pools.Explanation) {
+	_, _ = fmt.Fprintf(out, "project %s: eligible %s\n", plainText(d.Project), strings.Join(d.Eligible, " "))
+	for _, r := range d.Excluded {
+		_, _ = fmt.Fprintf(out, "excluded %s: %s %s\n", r.RunnerID, r.Reasons[0].Code, r.Reasons[0].Detail)
+	}
+	for _, id := range d.Unauthorized {
+		_, _ = fmt.Fprintf(out, "unauthorized %s: lifecycle.authorized_projects omits the project\n", id)
+	}
+	for _, r := range d.DevExcluded {
+		_, _ = fmt.Fprintf(out, "dev run excludes %s: %s %s\n", r.RunnerID, r.Reasons[0].Code, r.Reasons[0].Detail)
+	}
+	for _, n := range d.Notes {
+		_, _ = fmt.Fprintf(out, "note: %s\n", plainText(n))
+	}
+}
+
+// loadPoolsWorld reads the runners of the person's store, this machine and the registered providers, and
+// resolves the policy of the project at dir.
+func loadPoolsWorld(ctx context.Context, dir string) (poolsWorld, error) {
+	d, closeFn, err := lifecycle.ProductionEnv(nil).Open(ctx, "")
+	if err != nil {
+		return poolsWorld{}, err
+	}
+	defer closeFn()
+	nodes, err := d.Registry.List(ctx)
+	if err != nil {
+		return poolsWorld{}, err
+	}
+	var w poolsWorld
+	w.Project, w.Policy, w.PolicyErr = resolvePoolsPolicy(ctx, d.Store, dir)
+	for _, n := range nodes {
+		set, err := d.Store.NodeLabels(ctx, n.Record.ID)
+		if err != nil {
+			return poolsWorld{}, err
+		}
+		r := pools.Runner{ID: n.Record.ID, Source: pools.SourceRegistry, Assigned: labels.Strings(set), Projects: n.Capability.Lifecycle.AuthorizedProjects}
+		if v := n.Capability.Location.Kind.Value; v != nil {
+			r.Location = *v
+		}
+		w.Runners = append(w.Runners, r)
+	}
+	set, err := d.Store.NodeLabels(ctx, labels.LocalNode)
+	if err != nil {
+		return poolsWorld{}, err
+	}
+	// This machine and the providers are not gated by authorized_projects: they are always the project's own.
+	w.Runners = append(w.Runners, pools.Runner{ID: labels.LocalNode, Source: pools.SourceLocal, Location: "local", Assigned: labels.Strings(set), Projects: []string{w.Project}})
+	for _, p := range providers.All() {
+		w.Runners = append(w.Runners, pools.Runner{ID: p.ID(), Source: pools.SourceProvider, Location: "hosted", Projects: []string{w.Project}})
+	}
+	return w, nil
+}
+
+// resolvePoolsPolicy resolves the policy of the repository at dir (default NSELF_CI_REPO, else the working directory).
+func resolvePoolsPolicy(ctx context.Context, st *store.Store, dir string) (string, trust.Effective, error) {
+	if dir == "" {
+		dir = os.Getenv("NSELF_CI_REPO")
+	}
+	if dir == "" {
+		dir = "."
+	}
+	root, err := filepath.Abs(dir)
+	if err != nil {
+		return "", trust.Effective{}, err
+	}
+	if fi, err := os.Stat(root); err != nil || !fi.IsDir() {
+		return "", trust.Effective{}, errors.New(plainText(dir) + " is not a directory")
+	}
+	run := policy.Runner(report.Capture)
+	project := policy.ProjectIDGitCached(ctx, run, root) // the run's start path asks again (policy hook, dispatch)
+	res := policy.Resolver{Store: st, Run: run}
+	got, err := res.Resolve(ctx, policy.Repo{Root: root, Project: project, Visibility: "unknown", Class: "owner"}, policy.Revision{Dir: root})
+	if err != nil {
+		return project, trust.Effective{}, err
+	}
+	return project, got.Effective, nil
+}
diff --git a/free/ci/cmd/nodes_pools_record.go b/free/ci/cmd/nodes_pools_record.go
new file mode 100644
index 000000000..caaf79e47
--- /dev/null
+++ b/free/ci/cmd/nodes_pools_record.go
@@ -0,0 +1,98 @@
+package main
+
+// Purpose: show pools.record beside the effective development pool set.
+// Inputs: the same protected policy and assigned labels as nodes pools.
+// Outputs: record column and every exclusion reason in text or JSON.
+// Constraints: V15 composition only; no project authorization command is added.
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	compat "github.com/nself-org/cli/sdk/go/v2/compat"
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/pools/record"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+func init() {
+	entry := v15Subcommands["nodes pools explain"]
+	entry.Handler = func(args []string) int {
+		return runPoolsRecordExplain(args, poolsDeps{Load: loadPoolsWorld}, os.Stdout, os.Stderr)
+	}
+	v15Subcommands["nodes pools explain"] = entry
+	reader := &labels.LazyReader{Path: func() string { return filepath.Join(lifecycle.CIHome(), "state.db") }}
+	if err := autoworld.RegisterExclusion("pools.record.plan", func(ctx context.Context, w sched.World) (map[string][]model.PlacementReasonDetail, error) {
+		if !compat.V15() || cirun.SessionFrom(ctx) != nil {
+			return nil, nil
+		}
+		return record.ExclusionProvider(pools.Config{Labels: reader, Team: func() bool { return nodeAdminDeps.Load() != nil }}, func(context.Context) bool { return true })(ctx, w)
+	}); err != nil {
+		panic(err)
+	}
+}
+
+type recordExplanation struct {
+	pools.Explanation
+	Record         []string            `json:"record"`
+	RecordExcluded []pools.ExcludedRow `json:"record_excluded"`
+}
+
+func runPoolsRecordExplain(args []string, d poolsDeps, out, errOut io.Writer) int {
+	const command = "ci nodes pools explain"
+	o, _, err := parseNodesPools("explain", args)
+	if err != nil {
+		return placementFail(out, errOut, command, o.json || hasJSONArg(args), err)
+	}
+	w, err := d.Load(context.Background(), o.project)
+	if err != nil {
+		return placementFail(out, errOut, command, o.json, placementInfra("the pools cannot be read: "+oneLine(err)))
+	}
+	if w.PolicyErr != nil {
+		return placementFail(out, errOut, command, o.json, placementInfra("the project policy cannot be resolved: "+oneLine(w.PolicyErr)))
+	}
+	allow, dev, notes := pools.FromPolicy(w.Policy)
+	for _, ig := range w.Policy.Ignored() {
+		if ig.Key == record.Key {
+			notes = append(notes, fmt.Sprintf("%s from %s ignored: %s", ig.Key, ig.Scope, ig.Reason))
+		}
+	}
+	in := pools.Input{Runners: w.Runners, Project: w.Project, Allow: allow, DevPools: dev}
+	data := recordExplanation{Explanation: pools.Explain(in, notes), Record: []string{}, RecordExcluded: []pools.ExcludedRow{}}
+	excluded := record.Excluded(record.FromPolicy(w.Policy), w.Runners)
+	for _, r := range w.Runners {
+		if why := excluded[r.ID]; len(why) > 0 {
+			data.RecordExcluded = append(data.RecordExcluded, pools.ExcludedRow{RunnerID: r.ID, Pools: pools.Memberships(r), Reasons: why})
+		} else if slices.Contains(data.Eligible, r.ID) {
+			data.Record = append(data.Record, r.ID)
+		}
+	}
+	slices.Sort(data.Record)
+	if o.json {
+		return writeEnvelope(out, command, data)
+	}
+	writeExplainText(out, data.Explanation)
+	fmt.Fprintln(out, "runner\trecord")
+	for _, r := range w.Runners {
+		state := "allowed"
+		if !slices.Contains(data.Record, r.ID) {
+			state = "excluded"
+		}
+		fmt.Fprintf(out, "%s\t%s\n", r.ID, state)
+	}
+	fmt.Fprintf(out, "record eligible %s\n", strings.Join(data.Record, " "))
+	for _, r := range data.RecordExcluded {
+		fmt.Fprintf(out, "record excludes %s: %s %s\n", r.RunnerID, r.Reasons[0].Code, r.Reasons[0].Detail)
+	}
+	return 0
+}
diff --git a/free/ci/cmd/nodes_pools_test.go b/free/ci/cmd/nodes_pools_test.go
new file mode 100644
index 000000000..0512c00ba
--- /dev/null
+++ b/free/ci/cmd/nodes_pools_test.go
@@ -0,0 +1,147 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// poolsFixture is a personal VPS in pool mine, a team coordinator node in pool team, this machine and a provider.
+func poolsFixture(t *testing.T, allow string) poolsDeps {
+	t.Helper()
+	reg, err := trust.NewRegistry(pools.Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	vals := map[string]json.RawMessage{}
+	if allow != "" {
+		vals[pools.KeyAllow] = json.RawMessage(allow)
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceProtectedBranch, Values: vals})
+	if err != nil {
+		t.Fatal(err)
+	}
+	w := poolsWorld{Project: "/src/app", Policy: eff, Runners: []pools.Runner{
+		{ID: "vps", Source: pools.SourceRegistry, Location: "remote", Assigned: []string{"pool.mine"}, Projects: []string{"/src/app"}},
+		{ID: "t1", Source: pools.SourceCoordinator, Location: "lan", Assigned: []string{"pool.team"}, Projects: []string{"/src/app"}},
+		{ID: "t2", Source: pools.SourceCoordinator, Location: "lan", Assigned: []string{"pool.team"}},
+		{ID: "local", Source: pools.SourceLocal, Location: "local", Projects: []string{"/src/app"}},
+		{ID: "gh", Source: pools.SourceProvider, Location: "hosted", Projects: []string{"/src/app"}}}}
+	return poolsDeps{Load: func(context.Context, string) (poolsWorld, error) { return w, nil }}
+}
+
+func runPoolsJSON(t *testing.T, sub string, d poolsDeps, args ...string) map[string]json.RawMessage {
+	t.Helper()
+	var out, errOut bytes.Buffer
+	if code := runNodesPools(sub, append(args, "--json"), d, &out, &errOut); code != 0 {
+		t.Fatalf("%s exit %d: %s %s", sub, code, out.String(), errOut.String())
+	}
+	var env struct {
+		Command string                     `json:"command"`
+		Data    map[string]json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &env); err != nil || env.Command != "ci nodes pools "+sub {
+		t.Fatalf("envelope %q: %v", out.String(), err)
+	}
+	return env.Data
+}
+
+func TestNodesPoolsListJSON(t *testing.T) {
+	var ps []pools.Pool
+	if err := json.Unmarshal(runPoolsJSON(t, "list", poolsFixture(t, ""))["pools"], &ps); err != nil {
+		t.Fatal(err)
+	}
+	var ids []string
+	for _, p := range ps {
+		ids = append(ids, p.ID)
+		if p.Schema != pools.SchemaID || !p.Effective.Allowed {
+			t.Fatalf("solo default: pool %+v", p)
+		}
+	}
+	if !slices.Equal(ids, []string{"hosted", "local", "mine", "team"}) || ps[3].Scope != pools.ScopeProject || ps[2].Scope != pools.ScopeOperator {
+		t.Fatalf("pools = %+v", ps)
+	}
+	if err := json.Unmarshal(runPoolsJSON(t, "show", poolsFixture(t, `["team"]`), "mine")["pools"], &ps); err != nil {
+		t.Fatal(err)
+	}
+	if len(ps) != 1 || ps[0].Effective.Allowed || ps[0].Effective.Reasons[0].Detail != pools.DetailNotInProjectList {
+		t.Fatalf("show mine = %+v", ps)
+	}
+	var out, errOut bytes.Buffer
+	if code := runNodesPools("show", []string{"Bad_ID"}, poolsFixture(t, ""), &out, &errOut); code == 0 {
+		t.Fatal("a malformed pool id was accepted")
+	}
+	if code := runNodesPools("list", []string{"extra"}, poolsFixture(t, ""), &out, &errOut); code == 0 {
+		t.Fatal("list took a positional argument")
+	}
+}
+
+func TestNodesPoolsExplain(t *testing.T) {
+	d := poolsFixture(t, `["team"]`)
+	data := runPoolsJSON(t, "explain", d, "--project", ".")
+	var ex pools.Explanation
+	raw, _ := json.Marshal(data)
+	if err := json.Unmarshal(raw, &ex); err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]string{}
+	for _, r := range ex.Excluded {
+		got[r.RunnerID] = r.Reasons[0].Code + " " + r.Reasons[0].Detail
+	}
+	want := map[string]string{"vps": "pool.excluded not_in_project_list", "local": "pool.excluded not_in_project_list", "gh": "pool.excluded not_in_project_list"}
+	if len(got) != len(want) {
+		t.Fatalf("excluded = %v", got)
+	}
+	for id, w := range want {
+		if got[id] != w {
+			t.Fatalf("runner %s: %q, want %q", id, got[id], w)
+		}
+	}
+	if !slices.Equal(ex.Eligible, []string{"t1"}) || !slices.Equal(ex.Unauthorized, []string{"t2"}) {
+		t.Fatalf("eligible %v unauthorized %v", ex.Eligible, ex.Unauthorized)
+	}
+	// the plan path carries the same reasons: the registered provider over the same runners.
+	if !slices.Contains(autoworld.Providers(), pools.ProviderName) {
+		t.Fatalf("pools exclusion provider is not registered: %v", autoworld.Providers())
+	}
+	w, _ := d.Load(context.Background(), "")
+	world := sched.World{Policy: sched.Policy{Trust: w.Policy}, Runners: []sched.Runner{{ID: "vps"}, {ID: "t1"}, {ID: "local"}}, Hosted: []sched.Runner{{ID: "gh"}}}
+	lbl := poolsLabels{"vps": {{Key: "pool.mine"}}, "t1": {{Key: "pool.team"}}}
+	plan, err := pools.ExclusionProvider(pools.Config{Labels: lbl})(context.Background(), world)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for id, w := range want {
+		if r := plan[id]; len(r) != 1 || r[0].Code+" "+r[0].Detail != w || r[0].Code != string(model.PoolExcluded) {
+			t.Fatalf("plan reasons for %s = %v, want %q", id, r, w)
+		}
+	}
+	var out, errOut bytes.Buffer
+	broken := poolsDeps{Load: func(context.Context, string) (poolsWorld, error) {
+		return poolsWorld{PolicyErr: errors.New("no repository")}, nil
+	}}
+	if code := runNodesPools("explain", nil, broken, &out, &errOut); code == 0 {
+		t.Fatal("explain without a project policy succeeded")
+	}
+	out.Reset()
+	if code := runNodesPools("list", nil, broken, &out, &errOut); code != 0 || !strings.Contains(out.String(), "every pool term is unset") {
+		t.Fatalf("list without a project policy: %d %q", code, out.String())
+	}
+}
+
+type poolsLabels map[string][]store.NodeLabel
+
+func (f poolsLabels) NodeLabels(_ context.Context, id string) ([]store.NodeLabel, error) {
+	return f[id], nil
+}
diff --git a/free/ci/cmd/nodes_projects.go b/free/ci/cmd/nodes_projects.go
new file mode 100644
index 000000000..683ba100d
--- /dev/null
+++ b/free/ci/cmd/nodes_projects.go
@@ -0,0 +1,241 @@
+package main
+
+// Purpose: `nself ci nodes projects add|remove|list <node> ...` (P7-NODE-30, Epic NODE D19): which projects
+// may use a node. add and remove change lifecycle.authorized_projects through the registry (one audit row
+// each); list reads it. A project is named by its repo id, or by a directory that resolves to it the way
+// evidence does (`.` is the default). Also holds the client half of `--coordinator` for label and projects,
+// and the runner behind the coordinator's /v1/nodes/{id}/labels and /projects routes.
+// Inputs:  the node id, project arguments, --all (add: every project this PERSONAL store has seen;
+//          remove: every authorized project), --json, --coordinator <url>; env NSELF_CI_HOME.
+// Outputs: a table line or one v1 JSON envelope; exit 0, 1 (usage, E658, refusal), 2 (infrastructure).
+// Constraints: V15 only; side-effect classes: add and remove write, list reads; removal lets a running
+//          attempt finish and the lease gate refuses new leases (E657); `add --all` is refused on a TEAM
+//          coordinator (E658 team_wildcard) and stores one explicit entry per project, never a wildcard.
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+)
+
+func nodesProjectsFlags() *flag.FlagSet {
+	fs := flag.NewFlagSet("nodes projects", flag.ContinueOnError)
+	fs.Bool("json", false, "print one v1 JSON envelope")
+	fs.Bool("all", false, "add: every project this store has seen (explicit entries); remove: every authorized project")
+	lifecycle.AddCoordinatorFlag(fs)
+	return fs
+}
+
+func init() {
+	for _, sub := range []string{"add", "remove", "list"} {
+		sub := sub
+		registerV15("nodes projects "+sub, subcommandEntry{
+			V15Only: true,
+			Flags:   nodesProjectsFlags,
+			Handler: func(args []string) int {
+				if code, done := placementRemote("projects "+sub, args, os.Stdout, os.Stderr); done {
+					return code
+				}
+				return runNodesProjects(sub, args, lifecycle.ProductionEnv(currentProject), false, os.Stdout, os.Stderr)
+			},
+		})
+	}
+}
+
+// parseNodesProjects splits argv into the node, the project arguments and the flags.
+func parseNodesProjects(sub string, args []string) (node string, projects []string, all, asJSON bool, err error) {
+	for _, a := range args {
+		switch {
+		case a == "--json" || a == "-json" || a == "--json=true" || a == "-json=true":
+			asJSON = true
+		case a == "--all" || a == "-all" || a == "--all=true":
+			all = true
+		case strings.HasPrefix(a, "-"):
+			err = placementUsage("unknown flag " + a)
+			return
+		case node == "":
+			node = strings.ToLower(a)
+		default:
+			projects = append(projects, a)
+		}
+	}
+	usage := "usage: nself ci nodes projects " + map[string]string{
+		"add":    "add <node> [<dir>|<repo-id>...] [--all] [--json]",
+		"remove": "remove <node> <project...>|--all [--json]",
+		"list":   "list <node> [--json]"}[sub] + " [--coordinator <url>]"
+	switch {
+	case node == "":
+		err = placementUsage(usage)
+	case remote.ValidateNodeID(node) != nil:
+		err = placementUsage("the node id is not valid (letters, digits, dot, dash, underscore)")
+	case sub == "list" && (len(projects) > 0 || all), all && len(projects) > 0, sub == "remove" && !all && len(projects) == 0:
+		err = placementUsage(usage)
+	}
+	return
+}
+
+// runNodesProjects is the handler with its environment injected, for tests. team is true on a coordinator.
+func runNodesProjects(sub string, args []string, env lifecycle.Env, team bool, out, errOut io.Writer) int {
+	command := "ci nodes projects " + sub
+	node, projects, all, asJSON, err := parseNodesProjects(sub, args)
+	if err != nil {
+		return placementFail(out, errOut, command, asJSON || hasJSONArg(args), err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	d, closeFn, err := env.Open(ctx, "")
+	if err != nil {
+		return placementFail(out, errOut, command, asJSON, placementInfra("the CI store cannot be opened: "+oneLine(err)))
+	}
+	defer closeFn()
+	e := placementEnv(d, team)
+	var changed []string
+	switch sub {
+	case "add":
+		changed, err = e.AddProjects(ctx, node, projects, all)
+	case "remove":
+		changed, err = e.RemoveProjects(ctx, node, projects, all)
+	}
+	if err != nil {
+		return placementFail(out, errOut, command, asJSON, err)
+	}
+	now, err := e.Projects(ctx, node)
+	if err != nil {
+		return placementFail(out, errOut, command, asJSON, err)
+	}
+	if asJSON {
+		data := map[string]any{"node": node, "authorized_projects": now}
+		if sub != "list" {
+			data["changed"] = append([]string{}, changed...)
+		}
+		if output.WriteData(out, command, data, nil) != nil {
+			return output.ExitInfra
+		}
+		return 0
+	}
+	if sub != "list" {
+		_, _ = fmt.Fprintf(out, "node %s: %s %d project(s)\n", node, map[string]string{"add": "authorized", "remove": "deauthorized"}[sub], len(changed))
+	}
+	if len(now) == 0 {
+		_, _ = fmt.Fprintf(out, "node %s: no authorized projects\n", node)
+		return 0
+	}
+	_, _ = fmt.Fprintf(out, "node %s: authorized projects %s\n", node, strings.Join(now, " "))
+	return 0
+}
+
+// placementRemote is the client half of `--coordinator`: kind is "label" or "projects <add|remove|list>".
+// done is false when argv has no --coordinator flag and the caller runs the local handler.
+func placementRemote(kind string, args []string, out, errw io.Writer) (code int, done bool) {
+	url, rest, found, err := takeCoordinatorFlag(args)
+	if !found && err == nil {
+		return 0, false
+	}
+	if coordOut != nil {
+		out = coordOut
+	}
+	if coordErr != nil {
+		errw = coordErr
+	}
+	asJSON := hasJSONArg(rest)
+	var node string
+	var req clientapi.PlacementRequest
+	write := false
+	if err == nil {
+		if kind == "label" {
+			var add, remove []string
+			if node, add, remove, asJSON, err = parseNodesLabel(rest); err == nil {
+				req = clientapi.PlacementRequest{JSON: asJSON, Labels: add, Remove: remove}
+				write = len(add)+len(remove) > 0
+			}
+		} else {
+			sub := strings.TrimPrefix(kind, "projects ")
+			var projects []string
+			var all bool
+			if node, projects, all, asJSON, err = parseNodesProjects(sub, rest); err == nil {
+				req = clientapi.PlacementRequest{JSON: asJSON, Action: sub, Projects: projects, All: all}
+				write = sub != "list"
+			}
+		}
+	}
+	if err != nil {
+		return placementFail(out, errw, "ci nodes "+kind, asJSON, err), true
+	}
+	coordinatorFlag = url
+	defer func() { coordinatorFlag = "" }()
+	cl, _, _, err := coordResolver.Client()
+	if err != nil {
+		return coordFail(out, errw, asJSON, err), true
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	var res clientapi.NodeResult
+	if kind == "label" {
+		res, err = cl.NodeLabels(ctx, node, write, req)
+	} else {
+		res, err = cl.NodeProjects(ctx, node, write, req)
+	}
+	if err != nil {
+		return coordFail(out, errw, asJSON, err), true
+	}
+	_, _ = io.WriteString(out, res.Stdout)
+	_, _ = io.WriteString(errw, res.Stderr)
+	return res.Exit, true
+}
+
+// runPlacementCommand is the clientapi.PlacementRunner: it runs the local handler of cmd.Verb as actor, on
+// a coordinator (no directories, no `local`, no wildcard grants).
+func runPlacementCommand(ctx context.Context, actor string, cmd clientapi.PlacementCommand) (clientapi.NodeResult, error) {
+	st := nodeAdminDeps.Load()
+	if st == nil {
+		return clientapi.NodeResult{}, clientapi.Failf(clientapi.ReasonNotFound, "node administration is not available on this server")
+	}
+	var out, errw capWriter
+	env := lifecycle.Env{Out: &out, Err: &errw,
+		Open: func(_ context.Context, _ string) (*lifecycle.Deps, func(), error) {
+			return lifecycle.NewDeps(st.store, st.home, "", actor), func() {}, nil
+		}}
+	args := []string{cmd.Node}
+	var code int
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		if cmd.Verb == clientapi.VerbLabel || cmd.Verb == clientapi.VerbLabelList {
+			args = append(args, cmd.Labels...)
+			if len(cmd.Remove) > 0 {
+				args = append(args, append([]string{"--remove"}, cmd.Remove...)...)
+			}
+			if cmd.JSON {
+				args = append(args, "--json")
+			}
+			code = runNodesLabel(args, env, true, &out, &errw)
+			return
+		}
+		args = append(args, cmd.Projects...)
+		if cmd.All {
+			args = append(args, "--all")
+		}
+		if cmd.JSON {
+			args = append(args, "--json")
+		}
+		code = runNodesProjects(strings.TrimPrefix(cmd.Verb, "projects "), args, env, true, &out, &errw)
+	}()
+	select {
+	case <-done:
+		if out.over || errw.over {
+			return clientapi.NodeResult{Exit: max(code, 2), Stderr: "the answer is longer than the 1 MiB limit of the user API; read it on the coordinator host\n"}, nil
+		}
+		return clientapi.NodeResult{Exit: code, Stdout: out.b.String(), Stderr: errw.b.String()}, nil
+	case <-ctx.Done():
+		return clientapi.NodeResult{}, ctx.Err()
+	}
+}
diff --git a/free/ci/cmd/nodes_provision.go b/free/ci/cmd/nodes_provision.go
index 1dafb7fd6..3e0c82add 100644
--- a/free/ci/cmd/nodes_provision.go
+++ b/free/ci/cmd/nodes_provision.go
@@ -38,6 +38,9 @@ func init() {
 	register("nodes verify", func(args []string) int {
 		return provision.RunVerify(args, provisionDeps())
 	})
+	// parity with core `nself runner provision|verify --help` (P7-CANON-10): captured text, parse errors first
+	coreHelp["nodes provision"] = func(args []string) int { return provision.HelpOnly("provision", args, provisionDeps()) }
+	coreHelp["nodes verify"] = func(args []string) int { return provision.HelpOnly("verify", args, provisionDeps()) }
 }
 
 // provisionDeps is the real wiring; V15 adds the pin and the registry record.
diff --git a/free/ci/cmd/nodes_status.go b/free/ci/cmd/nodes_status.go
new file mode 100644
index 000000000..8dba51d46
--- /dev/null
+++ b/free/ci/cmd/nodes_status.go
@@ -0,0 +1,180 @@
+package main
+
+// Purpose: `nself ci nodes status [--local] [--json]` (P7-AUTO-19): the fleet at a glance. --local prints
+//          this host's demand document (contract:ci.demand v1). Without it every registered node is asked,
+//          8 at a time and under a hard 8 s cap each, for its demand document and readiness block through
+//          the probe package's fixed read-only commands; the answers are merged with the registry (state,
+//          agent version), the pool of each node and the local store's last results.
+// Inputs:  --local, --json; env NSELF_CI_HOME (the store, the pin file known_hosts, the demand file).
+// Outputs: a table or one v1 JSON envelope; exit 0 (also when nodes are unreachable: they are rows),
+//          1 (usage), 2 (infrastructure).
+// Constraints: V15 only; side-effect class read. No node value enters a remote command; a dead or slow node
+//          is reported unreachable with its reason and never delays the others. `ci prepare` is superseded
+//          (NODE-03 ships the revision as a bundle per lease): no remote checkout is created or refreshed.
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/fleet"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/probe"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+const nodesStatusCommand = "ci nodes status"
+
+type nodesStatusOpts struct {
+	json, local bool
+}
+
+func newNodesStatusFlags(errOut io.Writer) (*flag.FlagSet, *nodesStatusOpts) {
+	o := &nodesStatusOpts{}
+	fs := flag.NewFlagSet("nodes status", flag.ContinueOnError)
+	fs.SetOutput(errOut)
+	fs.BoolVar(&o.json, "json", false, "print one v1 JSON envelope")
+	fs.BoolVar(&o.local, "local", false, "print this host's demand document only")
+	return fs, o
+}
+
+// nodesStatusDeps are the outside readers of the command.
+type nodesStatusDeps struct {
+	Home string
+	// Open opens the existing store (nil store, nil error when there is none yet).
+	Open func(path string) (*store.Store, error)
+	// Reader builds the per-node status reader.
+	Reader  func(ctx context.Context, home string) fleet.Reader
+	Options fleet.Options
+}
+
+func init() {
+	registerV15("nodes status", subcommandEntry{
+		V15Only: true,
+		Flags:   func() *flag.FlagSet { fs, _ := newNodesStatusFlags(io.Discard); return fs },
+		Handler: func(args []string) int {
+			d := nodesStatusDeps{Home: lifecycle.CIHome(), Open: openStatusStore, Reader: sshStatusReader}
+			return runNodesStatus(args, d, os.Stdout, os.Stderr)
+		},
+	})
+}
+
+// runNodesStatus is the handler with its environment injected.
+func runNodesStatus(args []string, d nodesStatusDeps, out, errOut io.Writer) int {
+	fs, o := newNodesStatusFlags(io.Discard)
+	if err := fs.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			fs.SetOutput(errOut)
+			fs.Usage()
+			return 0
+		}
+		return placementFail(out, errOut, nodesStatusCommand, o.json || hasJSONArg(args), placementUsage("usage: nself ci nodes status [--local] [--json]"))
+	}
+	if fs.NArg() != 0 {
+		return placementFail(out, errOut, nodesStatusCommand, o.json, placementUsage("usage: nself ci nodes status [--local] [--json]"))
+	}
+	if o.local {
+		return nodesStatusLocal(o.json, d, out, errOut)
+	}
+	ctx := context.Background()
+	st, err := d.Open(filepath.Join(d.Home, "state.db"))
+	if err != nil {
+		return placementFail(out, errOut, nodesStatusCommand, o.json, placementInfra("open the state database: "+oneLine(err)))
+	}
+	if st != nil {
+		defer func() { _ = st.Close() }()
+	}
+	rep, err := fleet.Gather(ctx, st, d.Reader(ctx, d.Home), d.Options)
+	if err != nil {
+		return placementFail(out, errOut, nodesStatusCommand, o.json, placementInfra("read the registry: "+oneLine(err)))
+	}
+	if o.json {
+		if err := output.WriteData(out, nodesStatusCommand, rep, nil); err != nil {
+			return placementFail(out, errOut, nodesStatusCommand, false, placementInfra(oneLine(err)))
+		}
+		return 0
+	}
+	if err := fleet.Render(out, rep); err != nil {
+		return output.ExitInfra
+	}
+	return 0
+}
+
+// localDemand is the --local document: the demand file plus where it came from.
+type localDemand struct {
+	demand.Document
+	Source string `json:"source"`
+}
+
+// nodesStatusLocal prints this host's demand document.
+func nodesStatusLocal(asJSON bool, d nodesStatusDeps, out, errOut io.Writer) int {
+	snap, err := demand.Read(demand.ReadConfig{Dir: d.Home})
+	if err != nil {
+		return placementFail(out, errOut, nodesStatusCommand, asJSON, placementInfra(oneLine(err)))
+	}
+	doc := localDemand{Document: snap.Doc, Source: fleet.SourceLive}
+	if snap.Doc.TS == "" {
+		doc.Source = "none" // no watcher publishes on this host
+	}
+	if doc.ReadyWhy == nil {
+		doc.ReadyWhy = []string{}
+	}
+	if asJSON {
+		if err := output.WriteData(out, nodesStatusCommand, doc, nil); err != nil {
+			return placementFail(out, errOut, nodesStatusCommand, false, placementInfra(oneLine(err)))
+		}
+		return 0
+	}
+	if doc.Source == "none" {
+		fmt.Fprintln(out, "watcher: none (this host publishes no demand document)")
+		return 0
+	}
+	ready := "ready"
+	if !doc.Ready {
+		ready = "not ready"
+	}
+	fmt.Fprintf(out, "host: %s\nready: %s\nwatcher: alive, last pass %s (%s ago)\nqueued: %d  held: %d  running: %d\n",
+		doc.Host, ready, doc.Watcher.LastPass, snap.Age.Round(time.Second), doc.Queued, doc.Held, doc.Running)
+	for _, why := range doc.ReadyWhy {
+		fmt.Fprintf(out, "  why: %s\n", why)
+	}
+	return 0
+}
+
+// openStatusStore opens the state database only when it exists: a status read never creates one.
+func openStatusStore(path string) (*store.Store, error) {
+	if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	} else if err != nil {
+		return nil, err
+	}
+	return store.Open(path, store.Options{})
+}
+
+// sshStatusReader reads each node over the SDK remote funnel with the pinned D4 option set.
+func sshStatusReader(ctx context.Context, home string) fleet.Reader {
+	vctx, cancel := context.WithTimeout(ctx, fleet.NodeCap)
+	defer cancel()
+	v, verr := remote.SSHVersion(vctx)
+	pinned := filepath.Join(home, "known_hosts")
+	return func(ctx context.Context, n registry.Node) (probe.StatusDocs, error) {
+		if verr != nil {
+			return probe.StatusDocs{}, fmt.Errorf("local ssh: %w", verr)
+		}
+		run, err := probe.SSHStatusRunner(n, pinned, "", v)
+		if err != nil {
+			return probe.StatusDocs{}, err
+		}
+		return probe.ReadStatus(ctx, run)
+	}
+}
diff --git a/free/ci/cmd/nodes_status_fleet_test.go b/free/ci/cmd/nodes_status_fleet_test.go
new file mode 100644
index 000000000..01a55d7af
--- /dev/null
+++ b/free/ci/cmd/nodes_status_fleet_test.go
@@ -0,0 +1,151 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/fleet"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/probe"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+type statusClock struct{ now time.Time }
+
+func (c statusClock) Now() time.Time { return c.now }
+
+// TestNodesStatusLocalJSON: `--local --json` is the demand file plus source: live.
+func TestNodesStatusLocalJSON(t *testing.T) {
+	home := t.TempDir()
+	at := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+	doc := demand.Document{Queued: 2, Held: 1, Running: 1, Ready: false, ReadyWhy: []string{"disk below floor"},
+		Watcher: demand.Watcher{Alive: true, LastPass: at.Format(time.RFC3339), IntervalSec: 30}}
+	if err := demand.Write(demand.WriterConfig{Dir: home, Host: "mm4", Clock: statusClock{at}}, doc); err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	if code := runNodesStatus([]string{"--local", "--json"}, nodesStatusDeps{Home: home}, &out, &errOut); code != 0 {
+		t.Fatalf("exit %d: %s", code, errOut.String())
+	}
+	var env struct {
+		Data map[string]any `json:"data"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
+		t.Fatalf("%v: %s", err, out.String())
+	}
+	raw, err := os.ReadFile(filepath.Join(home, "demand.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var want map[string]any
+	if err := json.Unmarshal(raw, &want); err != nil {
+		t.Fatal(err)
+	}
+	want["source"] = "live"
+	if !reflect.DeepEqual(env.Data, want) {
+		t.Fatalf("data = %v\nwant %v", env.Data, want)
+	}
+	out.Reset()
+	code := runNodesStatus([]string{"--local", "--json"}, nodesStatusDeps{Home: t.TempDir()}, &out, io.Discard)
+	env.Data = nil
+	if err := json.Unmarshal(out.Bytes(), &env); err != nil || code != 0 || env.Data["source"] != "none" {
+		t.Fatalf("no demand file: exit %d %v %s", code, err, out.String())
+	}
+	out.Reset()
+	if code := runNodesStatus([]string{"--local"}, nodesStatusDeps{Home: home}, &out, io.Discard); code != 0 || !strings.Contains(out.String(), "why: disk below floor") {
+		t.Fatalf("text: exit %d %s", code, out.String())
+	}
+}
+
+func TestNodesStatusFleet(t *testing.T) {
+	home := t.TempDir()
+	st, err := store.Open(filepath.Join(home, "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	statusRegister(t, st, "a1", "b2")
+	_ = st.Close()
+	d := nodesStatusDeps{Home: home, Open: openStatusStore,
+		Reader: func(context.Context, string) fleet.Reader {
+			return func(_ context.Context, n registry.Node) (probe.StatusDocs, error) {
+				if n.Record.ID == "b2" {
+					return probe.StatusDocs{}, errors.New("connection refused")
+				}
+				return probe.StatusDocs{}, nil
+			}
+		}}
+	var out, errOut bytes.Buffer
+	if code := runNodesStatus([]string{"--json"}, d, &out, &errOut); code != 0 {
+		t.Fatalf("exit %d: %s", code, errOut.String())
+	}
+	var env struct {
+		Data fleet.Report `json:"data"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
+		t.Fatal(err)
+	}
+	if len(env.Data.Nodes) != 2 || env.Data.Unreachable != 1 || env.Data.Nodes[0].Watcher != fleet.WatcherNone || env.Data.Nodes[1].Unreachable != "connection refused" {
+		t.Fatalf("report = %+v", env.Data)
+	}
+	out.Reset()
+	if code := runNodesStatus(nil, d, &out, &errOut); code != 0 || !strings.Contains(out.String(), "b2: unreachable: connection refused") {
+		t.Fatalf("table: exit %d %s", code, out.String())
+	}
+	out.Reset()
+	empty := nodesStatusDeps{Home: t.TempDir(), Open: openStatusStore, Reader: d.Reader}
+	if code := runNodesStatus(nil, empty, &out, &errOut); code != 0 || !strings.Contains(out.String(), "no nodes registered") {
+		t.Fatalf("no store: exit %d %s", code, out.String())
+	}
+	if _, err := os.Stat(filepath.Join(empty.Home, "state.db")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("status created a state database")
+	}
+	if code := runNodesStatus([]string{"extra"}, d, io.Discard, io.Discard); code != 1 {
+		t.Fatalf("positional arg: exit %d, want 1", code)
+	}
+}
+
+func TestNodesStatusRegistration(t *testing.T) {
+	e, ok := v15Subcommands["nodes status"]
+	if !ok || !e.V15Only || e.Flags == nil {
+		t.Fatalf("nodes status entry = %+v", e)
+	}
+	for _, name := range []string{"json", "local"} {
+		if e.Flags().Lookup(name) == nil {
+			t.Errorf("flag --%s missing", name)
+		}
+	}
+}
+
+func statusRegister(t *testing.T, st *store.Store, ids ...string) {
+	t.Helper()
+	raw, err := os.ReadFile("../internal/model/testdata/capability/valid/vps.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range ids {
+		var c map[string]any
+		if err := json.Unmarshal(raw, &c); err != nil {
+			t.Fatal(err)
+		}
+		ident := c["identity"].(map[string]any)
+		ident["id"], ident["name"] = id, id
+		doc, err := json.Marshal(c)
+		if err != nil {
+			t.Fatal(err)
+		}
+		rec := store.NodeRecord{ID: id, Name: id, State: "online", Lifecycle: []byte("{}"), Trust: []byte("{}"), DeployHost: []byte("{}"), Capability: doc, ObservedAt: 1}
+		if err := st.NodePut(context.Background(), rec, "test"); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
diff --git a/free/ci/cmd/nodes_sync.go b/free/ci/cmd/nodes_sync.go
new file mode 100644
index 000000000..c64160396
--- /dev/null
+++ b/free/ci/cmd/nodes_sync.go
@@ -0,0 +1,170 @@
+package main
+
+// Purpose: `nself ci nodes sync (--from <file.yaml> | --cmd <argv...>) [--dry-run] [--json]` (P7-AUTO-04,
+//          Epic AUTO D10): import an inventory/v1 document (a file, or the output of a discovery command
+//          that runs through the exec funnel) over the node registry. New hosts become discovered
+//          candidates; existing nodes get their operator-owned attributes (labels, pool.<id>, rank,
+//          project skip rules, public_only) and nothing else.
+// Inputs:  --from <file> or --cmd <argv...> (everything after --cmd is the command, so put flags first),
+//          --dry-run, --json; env NSELF_CI_HOME.
+// Outputs: a summary line block or one v1 JSON envelope (accepted, changed with field sources,
+//          candidates, rejected, notes); exit 0, 1 (usage, E793, refusal), 2 (infrastructure).
+// Constraints: V15 only; side-effect class: write; refused on a TEAM coordinator; never changes trust, host
+//          keys, isolation or secrets eligibility, and never adds a project authorization; the repository
+//          visibility reader for public_only is a seam (nodesSyncVisibility): none is wired yet, so
+//          public_only nodes keep no project and the notes say why.
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/inventory"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+const nodesSyncUsage = "usage: nself ci nodes sync (--from <file.yaml> | --cmd <argv...>) [--dry-run] [--json]"
+
+// nodesSyncVisibility reads whether a project's repository is public; nil means every answer is unknown.
+var nodesSyncVisibility inventory.Visibility
+
+func nodesSyncFlags() *flag.FlagSet {
+	fs := flag.NewFlagSet("nodes sync", flag.ContinueOnError)
+	fs.Bool("json", false, "print one v1 JSON envelope")
+	fs.Bool("dry-run", false, "show what would change and write nothing")
+	fs.String("from", "", "inventory/v1 file to import")
+	fs.String("cmd", "", "command that prints an inventory/v1 document (every word after --cmd)")
+	return fs
+}
+
+func init() {
+	registerV15("nodes sync", subcommandEntry{
+		V15Only: true,
+		Flags:   nodesSyncFlags,
+		Handler: func(args []string) int {
+			return runNodesSync(args, lifecycle.ProductionEnv(currentProject), nodeAdminDeps.Load() != nil, funnelRunner, os.Stdout, os.Stderr)
+		},
+	})
+}
+
+// funnelRunner runs a discovery command through the exec funnel (report.Capture).
+func funnelRunner(ctx context.Context, argv []string) (string, int, error) {
+	return report.Capture(ctx, argv...)
+}
+
+type nodesSyncOpts struct {
+	from           string
+	cmd            []string
+	dryRun, asJSON bool
+}
+
+// parseNodesSync reads argv: --cmd takes every following word.
+func parseNodesSync(args []string) (nodesSyncOpts, error) {
+	var o nodesSyncOpts
+	for i := 0; i < len(args); i++ {
+		a := args[i]
+		switch {
+		case a == "--json" || a == "-json" || a == "--json=true" || a == "-json=true":
+			o.asJSON = true
+		case a == "--dry-run" || a == "-dry-run" || a == "--dry-run=true" || a == "-dry-run=true":
+			o.dryRun = true
+		case a == "--from" || a == "-from":
+			if i++; i >= len(args) {
+				return o, placementUsage(nodesSyncUsage)
+			}
+			o.from = args[i]
+		case strings.HasPrefix(a, "--from="):
+			o.from = strings.TrimPrefix(a, "--from=")
+		case a == "--cmd" || a == "-cmd":
+			o.cmd = args[i+1:]
+			i = len(args)
+		default:
+			return o, placementUsage(nodesSyncUsage)
+		}
+	}
+	if (o.from == "") == (len(o.cmd) == 0) {
+		return o, placementUsage(nodesSyncUsage)
+	}
+	return o, nil
+}
+
+// inventoryFail prints an inventory refusal (E793, exit 1); any other error goes to the placement printer.
+func inventoryFail(out, errOut io.Writer, asJSON bool, err error) int {
+	ie, ok := err.(*inventory.Error)
+	if !ok {
+		return placementFail(out, errOut, "ci nodes sync", asJSON, err)
+	}
+	if asJSON {
+		_ = output.WriteError(out, "ci nodes sync", output.ErrorDetail{Code: ie.Code, Message: oneLine(ie), ExitCode: output.ExitUser}, nil)
+		return output.ExitUser
+	}
+	_, _ = io.WriteString(errOut, oneLine(ie)+"\n")
+	return output.ExitUser
+}
+
+// runNodesSync is the handler with its environment injected, for tests. team is true on a coordinator.
+func runNodesSync(args []string, env lifecycle.Env, team bool, run inventory.Runner, out, errOut io.Writer) int {
+	o, err := parseNodesSync(args)
+	if err != nil {
+		return placementFail(out, errOut, "ci nodes sync", hasJSONArg(args), err)
+	}
+	if team {
+		return inventoryFail(out, errOut, o.asJSON, &inventory.Error{Code: inventory.CodeInventory, Reason: inventory.ReasonTeam,
+			Msg: "sync is refused on a TEAM coordinator: its admin owns the nodes"})
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	var doc inventory.Document
+	if o.from != "" {
+		doc, err = inventory.ReadFile(o.from, inventory.DefaultLimits)
+	} else {
+		doc, err = inventory.ReadCmd(ctx, run, o.cmd, inventory.DefaultLimits)
+	}
+	if err != nil {
+		return inventoryFail(out, errOut, o.asJSON, err)
+	}
+	d, closeFn, err := env.Open(ctx, "")
+	if err != nil {
+		return placementFail(out, errOut, "ci nodes sync", o.asJSON, placementInfra("the CI store cannot be opened: "+oneLine(err)))
+	}
+	defer closeFn()
+	sum, err := inventory.Sync(ctx, inventory.Env{Store: d.Store, Registry: d.Registry, Actor: d.Actor, Team: team, Visibility: nodesSyncVisibility},
+		doc.Entries, inventory.Options{DryRun: o.dryRun})
+	if err != nil {
+		return inventoryFail(out, errOut, o.asJSON, err)
+	}
+	if o.asJSON {
+		if output.WriteData(out, "ci nodes sync", sum, nil) != nil {
+			return output.ExitInfra
+		}
+		return 0
+	}
+	renderSyncSummary(out, sum)
+	return 0
+}
+
+func renderSyncSummary(out io.Writer, s inventory.Summary) {
+	verb := "applied"
+	if s.DryRun {
+		verb = "would apply"
+	}
+	_, _ = fmt.Fprintf(out, "inventory: %d accepted, %d candidate(s), %d rejected; %s %d change(s)\n", len(s.Accepted), len(s.Candidates), len(s.Rejected), verb, len(s.Changed))
+	for _, c := range s.Changed {
+		_, _ = fmt.Fprintf(out, "  %s %s %s: %s -> %s (source %s)\n", c.Node, c.Field, c.Name, c.From, c.To, c.Source)
+	}
+	for _, c := range s.Candidates {
+		_, _ = fmt.Fprintf(out, "  candidate %s (created %t): ineligible until `nself ci nodes add`\n", c.ID, c.Created)
+	}
+	for _, r := range s.Rejected {
+		_, _ = fmt.Fprintf(out, "  rejected %s: %s\n", r.ID, r.Reason)
+	}
+	for _, n := range s.Notes {
+		_, _ = fmt.Fprintf(out, "  note: %s\n", n)
+	}
+}
diff --git a/free/ci/cmd/nodes_sync_test.go b/free/ci/cmd/nodes_sync_test.go
new file mode 100644
index 000000000..db41da4d4
--- /dev/null
+++ b/free/ci/cmd/nodes_sync_test.go
@@ -0,0 +1,126 @@
+package main
+
+// Purpose: tests of `ci nodes sync` (P7-AUTO-04): parsing, the dry-run summary, the inventory refusal
+//          codes and the TEAM refusal, against a real store and a fake discovery runner.
+// Inputs:  inline inventory documents; a temp store through lifecycle.Env.
+// Outputs: pass or fail.
+// Constraints: no network, no processes, no sleeps, V15 handler only.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/inventory"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/lifecycle"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+const syncDoc = "schema: inventory/v1\nentries:\n  - id: vps1\n    ssh: ci@vps1.example.test\n    rank: 2\n"
+
+func syncEnv(t *testing.T) (lifecycle.Env, *store.Store) {
+	t.Helper()
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	return lifecycle.Env{Open: func(context.Context, string) (*lifecycle.Deps, func(), error) {
+		return lifecycle.NewDeps(st, t.TempDir(), "", "cli:test"), func() {}, nil
+	}}, st
+}
+
+func writeInventory(t *testing.T, doc string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "inv.yaml")
+	if err := os.WriteFile(p, []byte(doc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func syncJSON(t *testing.T, out string) (cmd string, data inventory.Summary, errCode string) {
+	t.Helper()
+	var env struct {
+		Command string            `json:"command"`
+		Data    inventory.Summary `json:"data"`
+		Error   struct {
+			Code string `json:"code"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal([]byte(out), &env); err != nil {
+		t.Fatalf("envelope %q: %v", out, err)
+	}
+	return env.Command, env.Data, env.Error.Code
+}
+
+func TestNodesSyncDryRun(t *testing.T) {
+	env, st := syncEnv(t)
+	var out, errOut bytes.Buffer
+	if code := runNodesSync([]string{"--from", writeInventory(t, syncDoc), "--dry-run", "--json"}, env, false, nil, &out, &errOut); code != 0 {
+		t.Fatalf("exit %d: %s %s", code, out.String(), errOut.String())
+	}
+	cmd, sum, _ := syncJSON(t, out.String())
+	if cmd != "ci nodes sync" || !sum.DryRun || len(sum.Candidates) != 1 || sum.Candidates[0].Created {
+		t.Fatalf("summary: %+v", sum)
+	}
+	if nodes, _ := st.NodeList(context.Background()); len(nodes) != 0 {
+		t.Fatal("dry-run registered a node")
+	}
+	// The real run creates the candidate; the table form names it.
+	out.Reset()
+	if code := runNodesSync([]string{"--from=" + writeInventory(t, syncDoc)}, env, false, nil, &out, &errOut); code != 0 || !strings.Contains(out.String(), "candidate vps1 (created true)") {
+		t.Fatalf("exit %d: %s", code, out.String())
+	}
+	if nodes, _ := st.NodeList(context.Background()); len(nodes) != 1 {
+		t.Fatal("candidate not registered")
+	}
+}
+
+func TestNodesSyncCmdAndRefusals(t *testing.T) {
+	env, st := syncEnv(t)
+	var gotArgv []string
+	run := func(_ context.Context, argv []string) (string, int, error) { gotArgv = argv; return syncDoc, 0, nil }
+	var out, errOut bytes.Buffer
+	if code := runNodesSync([]string{"--json", "--cmd", "tool", "--json", "list"}, env, false, run, &out, &errOut); code != 0 {
+		t.Fatalf("exit %d: %s", code, out.String())
+	}
+	if strings.Join(gotArgv, " ") != "tool --json list" {
+		t.Fatalf("everything after --cmd is the command: %v", gotArgv)
+	}
+	bad := func(*testing.T) (string, int, error) { return "schema: inventory/v1\nbogus: 1\n", 0, nil }
+	out.Reset()
+	if code := runNodesSync([]string{"--json", "--cmd", "tool"}, env, false, func(context.Context, []string) (string, int, error) { return bad(t) }, &out, &errOut); code != 1 {
+		t.Fatalf("unknown field exit %d", code)
+	}
+	if _, _, ec := syncJSON(t, out.String()); ec != inventory.CodeInventory {
+		t.Fatalf("code = %q in %s", ec, out.String())
+	}
+	before, _ := st.NodeList(context.Background())
+	if len(before) != 1 {
+		t.Fatalf("a refused command applied something: %d nodes", len(before))
+	}
+	for name, args := range map[string][]string{"none": {}, "both": {"--from", "a", "--cmd", "b"}, "unknown flag": {"--bogus"}, "from without value": {"--from"}} {
+		if code := runNodesSync(args, env, false, run, &out, &errOut); code != 1 {
+			t.Errorf("%s: exit %d", name, code)
+		}
+	}
+}
+
+func TestNodesSyncRefusedOnCoordinator(t *testing.T) {
+	env, st := syncEnv(t)
+	var out, errOut bytes.Buffer
+	if code := runNodesSync([]string{"--from", writeInventory(t, syncDoc), "--json"}, env, true, nil, &out, &errOut); code != 1 {
+		t.Fatalf("exit %d", code)
+	}
+	if _, _, ec := syncJSON(t, out.String()); ec != inventory.CodeInventory {
+		t.Fatalf("code = %q", ec)
+	}
+	if nodes, _ := st.NodeList(context.Background()); len(nodes) != 0 {
+		t.Fatal("a TEAM coordinator registered a node")
+	}
+}
diff --git a/free/ci/cmd/run.go b/free/ci/cmd/run.go
index 9735dda31..386a97ec1 100644
--- a/free/ci/cmd/run.go
+++ b/free/ci/cmd/run.go
@@ -8,6 +8,7 @@ package main
 // CLIs run this binary from plugins main.
 
 import (
+	"errors"
 	"flag"
 	"fmt"
 	"os"
@@ -19,19 +20,47 @@ import (
 
 func init() {
 	register("run", func(args []string) int { return runPipelineCmd(args) })
+	coreHelp["run"] = runHelp // the frozen help: flag usage on stderr, exit 0 (2 for a bad flag)
+}
+
+// runFlags is the frozen `run` flag set and the values the command reads.
+type runFlags struct {
+	fs              *flag.FlagSet
+	env, gatewayURL *string
+	verbose         *bool
+	timeout         *int
+}
+
+// newRunFlags builds the `run` flag set with the given error handling.
+func newRunFlags(h flag.ErrorHandling) runFlags {
+	fs := flag.NewFlagSet("run", h)
+	return runFlags{fs: fs,
+		env:        fs.String("env", "", "Target environment: local"),
+		gatewayURL: fs.String("gateway", "", "Explicit gateway base URL (e.g. http://host:3761)"),
+		verbose:    fs.Bool("v", false, "Print each command before running"),
+		timeout:    fs.Int("timeout", 300, "Per-step timeout in seconds"),
+	}
+}
+
+// runHelp answers `run ... --help` as the flag package did before the help intercept, and runs
+// nothing: a help token taken as a flag's value still prints the usage.
+func runHelp(args []string) int {
+	f := newRunFlags(flag.ContinueOnError)
+	switch err := f.fs.Parse(args); {
+	case err == nil:
+		f.fs.Usage()
+	case !errors.Is(err, flag.ErrHelp):
+		return 2
+	}
+	return 0
 }
 
 // runPipelineCmd implements "nself-ci run [flags] [search-root]".
 // Discovers .ci.yaml manifests under search-root and runs all stages in canonical order.
 // Adds a gateway routing check stage when --env or --gateway is provided.
 func runPipelineCmd(rawArgs []string) int {
-	fs := flag.NewFlagSet("run", flag.ExitOnError)
-	var (
-		env        = fs.String("env", "", "Target environment: local")
-		gatewayURL = fs.String("gateway", "", "Explicit gateway base URL (e.g. http://host:3761)")
-		verbose    = fs.Bool("v", false, "Print each command before running")
-		timeout    = fs.Int("timeout", 300, "Per-step timeout in seconds")
-	)
+	f := newRunFlags(flag.ExitOnError)
+	fs, env, gatewayURL, verbose, timeout := f.fs, f.env, f.gatewayURL, f.verbose, f.timeout
 	_ = fs.Parse(rawArgs)
 
 	searchRoot := "."
diff --git a/free/ci/cmd/runs_rerun.go b/free/ci/cmd/runs_rerun.go
new file mode 100644
index 000000000..09585f6f3
--- /dev/null
+++ b/free/ci/cmd/runs_rerun.go
@@ -0,0 +1,154 @@
+package main
+
+// Purpose: `nself ci runs rerun <run|sha> [--where …] [--job id] [--json]
+// [--repo dir]` (P7-AUTO-06): a new run of record for a recorded revision, with
+// the same --where flag as bare `nself ci`.
+// Inputs:  argv after `rerun`; env NSELF_CI_REPO, NSELF_CI_HOME. A run id (or
+// unique prefix, or `latest`) resolves through the run history; a full sha
+// without a record resolves through git.
+// Outputs: the run's output as a bare run prints it, the new run id on stderr;
+// the exit code is the gate's (0 pass, 1 failed, 2 infrastructure). A refusal
+// (E626) exits 1.
+// Constraints: V15 only; the CI-37 clean-tree rule holds: the checkout must be
+// exactly the revision, clean, because a run binds to the tree it reads, so a
+// dirty tree or another HEAD refuses with the reason. It sets Options.Record.
+// The placement goes through the same options hook and Coordinator as a bare
+// run; there is no second placement path.
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"regexp"
+	"strings"
+	"syscall"
+
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+)
+
+const rerunUsage = "nself ci runs rerun <run|sha> [--where local|<node>|<pool>|hosted|auto|all] [--job id] [--json] [--repo dir]"
+
+var fullSHARe = regexp.MustCompile(`^([0-9a-f]{40}|[0-9a-f]{64})$`)
+
+type rerunFlags struct {
+	json            bool
+	repo, job, here string
+}
+
+func newRerunFlagSet(f *rerunFlags) *flag.FlagSet {
+	fs := flag.NewFlagSet("rerun", flag.ContinueOnError)
+	fs.BoolVar(&f.json, "json", false, "print one v1 JSON envelope")
+	fs.StringVar(&f.repo, "repo", "", "repository root (env NSELF_CI_REPO; default: current directory)")
+	fs.StringVar(&f.job, "job", "", "run only this job and its dependencies")
+	whereFlagSet(fs, &f.here)
+	return fs
+}
+
+func init() { registerRunsSub("rerun", runRunsRerun) }
+
+// rerunRevision resolves ref to the sha to run: a run id through lookup (the
+// recorded revision), a full sha as given when exists says git knows it. The
+// checkout (head) must be that sha and clean.
+func rerunRevision(ref string, lookup func(string) (string, error), exists func(string) bool, head cirun.Revision) (string, error) {
+	sha := ref
+	if !fullSHARe.MatchString(ref) {
+		got, err := lookup(ref)
+		if err != nil {
+			return "", err
+		}
+		sha = got
+	} else if !exists(ref) {
+		return "", &cirun.Error{Code: cirun.CodeRun, Message: fmt.Sprintf("%s is not a commit of this repository", ref[:12])}
+	}
+	switch {
+	case head.SHA == "":
+		return "", &cirun.Error{Code: cirun.CodeRun, Message: "the repository has no commit to run"}
+	case head.Dirty:
+		return "", &cirun.Error{Code: cirun.CodeRun, Message: "the worktree has uncommitted changes; a run binds to the tree it reads, so commit or stash first"}
+	case head.SHA != sha:
+		return "", &cirun.Error{Code: cirun.CodeRun, Message: fmt.Sprintf("the checkout is at %s, not %s; check out the revision first", short12(head.SHA), short12(sha))}
+	}
+	return sha, nil
+}
+
+func short12(s string) string {
+	if len(s) > 12 {
+		return s[:12]
+	}
+	return s
+}
+
+func runRunsRerun(args []string) int {
+	var f rerunFlags
+	pos, err := parseMixed(newRerunFlagSet(&f), args)
+	if err != nil || len(pos) != 1 {
+		return usageErr(rerunUsage)
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM, syscall.SIGHUP, syscall.SIGQUIT)
+	defer stop()
+	root, err := evidenceRoot(f.repo)
+	if err != nil {
+		return exitForError(err)
+	}
+	head := cirun.GitRevision(ctx, root, report.Capture)
+	exists := func(sha string) bool {
+		_, exit, e := report.Capture(ctx, "git", "-C", root, "cat-file", "-e", sha+"^{commit}")
+		return e == nil && exit == 0
+	}
+	if _, err = rerunRevision(pos[0], rerunLookup(ctx), exists, head); err != nil {
+		return exitForError(err)
+	}
+	o := RunOptions{Root: root, Home: os.Getenv("NSELF_CI_HOME"), Job: f.job, JSON: f.json, Record: true}
+	o.Interactive = interactiveRun(o.Trigger, os.Getenv)
+	if o.PolicyRun, err = schedRevisionValues(); err != nil {
+		return exitForError(err)
+	}
+	v := f.here
+	if v == "" {
+		if k := whereKnown(ctx, false); k.HasRemote() {
+			v = "auto"
+		}
+	}
+	if v != "" {
+		if err = applyWhere(&o, v, whereKnown(ctx, false)); err != nil {
+			return exitForError(err)
+		}
+	}
+	hooks := cirun.Hooks{}.Resolved()
+	if err = o.Validate(hooks); err != nil {
+		return exitForError(err)
+	}
+	p, digest, subst, err := preparePlan(ctx, o)
+	if err != nil {
+		return exitForError(err)
+	}
+	c := &cirun.Coordinator{Opts: o, Plan: p, ConfigDigest: digest, ConfigOutside: configOutside(ctx, o.Root), Substantive: subst, Out: os.Stdout}
+	res, err := c.Run(ctx)
+	if err != nil {
+		return exitForError(err)
+	}
+	fmt.Fprintln(os.Stderr, "run "+res.RunID)
+	return res.Exit
+}
+
+// rerunLookup finds the revision a recorded run was made for.
+func rerunLookup(ctx context.Context) func(string) (string, error) {
+	return func(ref string) (string, error) {
+		st, err := openHistory(false)
+		if err != nil {
+			return "", err
+		}
+		if st == nil {
+			return "", &cirun.Error{Code: cirun.CodeRun, Message: "this machine has no run history; pass a full sha"}
+		}
+		defer func() { _ = st.Close() }()
+		row, err := cirun.ResolveRun(ctx, st, strings.TrimSpace(ref))
+		if err != nil {
+			return "", err
+		}
+		return row.Revision, nil
+	}
+}
diff --git a/free/ci/cmd/runs_rerun_test.go b/free/ci/cmd/runs_rerun_test.go
new file mode 100644
index 000000000..53787d769
--- /dev/null
+++ b/free/ci/cmd/runs_rerun_test.go
@@ -0,0 +1,54 @@
+package main
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+)
+
+const (
+	shaA = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	shaB = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+)
+
+func TestRunsRerunSha(t *testing.T) {
+	never := func(string) (string, error) { t.Fatal("lookup must not run for a sha"); return "", nil }
+	known := func(string) bool { return true }
+	for name, tc := range map[string]struct {
+		ref    string
+		lookup func(string) (string, error)
+		exists func(string) bool
+		head   cirun.Revision
+		want   string // "" = ok; else a substring of the refusal
+	}{
+		"sha without a record, clean at head": {shaA, never, known, cirun.Revision{SHA: shaA}, ""},
+		"run id resolves to its revision":     {"run-1", func(string) (string, error) { return shaA, nil }, known, cirun.Revision{SHA: shaA}, ""},
+		"dirty tree refuses":                  {shaA, never, known, cirun.Revision{SHA: shaA, Dirty: true}, "uncommitted changes"},
+		"head is another commit":              {shaB, never, known, cirun.Revision{SHA: shaA}, "check out the revision first"},
+		"unknown commit":                      {shaA, never, func(string) bool { return false }, cirun.Revision{SHA: shaA}, "not a commit"},
+		"no commit":                           {shaA, never, known, cirun.Revision{}, "no commit"},
+		"unknown run":                         {"nope", func(string) (string, error) { return "", errors.New("E626: no run") }, known, cirun.Revision{SHA: shaA}, "E626"},
+	} {
+		got, err := rerunRevision(tc.ref, tc.lookup, tc.exists, tc.head)
+		switch {
+		case tc.want == "" && (err != nil || got != shaA):
+			t.Errorf("%s: %q %v", name, got, err)
+		case tc.want != "" && (err == nil || !strings.Contains(err.Error(), tc.want)):
+			t.Errorf("%s: want %q, got %v", name, tc.want, err)
+		}
+	}
+	if _, err := rerunRevision(shaB, never, known, cirun.Revision{SHA: shaA, Dirty: true}); cirun.CodeOf(err) != cirun.CodeRun {
+		t.Errorf("refusals carry %s, got %v", cirun.CodeRun, err)
+	}
+}
+
+func TestRunsRerunRegistered(t *testing.T) {
+	if _, ok := runsSubs["rerun"]; !ok {
+		t.Fatal("rerun is not a runs subcommand")
+	}
+	if f := newRerunFlagSet(&rerunFlags{}); f.Lookup("where") == nil || f.Lookup("job") == nil {
+		t.Fatal("rerun lacks --where or --job")
+	}
+}
diff --git a/free/ci/cmd/runs_stats.go b/free/ci/cmd/runs_stats.go
new file mode 100644
index 000000000..30cbe2aa8
--- /dev/null
+++ b/free/ci/cmd/runs_stats.go
@@ -0,0 +1,131 @@
+package main
+
+// Purpose: `nself ci runs stats [--since <dur>] [--project <owner/repo>] [--coordinator <url>] [--json]`
+// (P7-SCHED-20, Epic SCHED D23, contract:ci.stats v1): the health of CI itself over a window (default 24h):
+// queue wait and depth per band, runner utilisation, pass, fail, flaky and infra-retry rates, job durations,
+// cache hit ratio, CAS and artifact bytes, ephemeral provisioning latency, spend by confidence, leases,
+// nodes, status-outbox backlog and store size.
+// Inputs:  argv after `runs stats`; env NSELF_CI_HOME, NSELF_CI_COORDINATOR.
+// Outputs: a short table or one v1 JSON envelope whose data is the stats document; exit 0, 1 (usage) or 2.
+// Constraints: V15 only; read only; a figure whose source is absent prints "-" (JSON null) with the reason,
+//          never 0; with a coordinator the document is the one it serves for the caller's projects.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+	"github.com/nself-org/plugins/free/ci/internal/stats"
+)
+
+const statsUsage = "nself ci runs stats [--since <duration>] [--project <owner/repo>] [--coordinator <url>] [--json]"
+
+func init() { registerRunsSub("stats", runStats) }
+
+type statsArgs struct {
+	since       time.Duration
+	project     string
+	coordinator string
+	json        bool
+}
+
+func parseStats(args []string) (statsArgs, error) {
+	a := statsArgs{since: stats.DefaultSince}
+	for i := 0; i < len(args); i++ {
+		name, val, hasVal := strings.Cut(args[i], "=")
+		take := func() (string, error) {
+			if hasVal {
+				return val, nil
+			}
+			if i+1 >= len(args) {
+				return "", fmt.Errorf("%s needs a value", name)
+			}
+			i++
+			return args[i], nil
+		}
+		var err error
+		var v string
+		switch name {
+		case "--json", "-json":
+			a.json = true
+		case "--since":
+			if v, err = take(); err == nil {
+				a.since, err = clientapi.ParseSince(v)
+			}
+		case "--project":
+			a.project, err = take()
+		case "--coordinator":
+			a.coordinator, err = take()
+		default:
+			err = fmt.Errorf("unexpected argument %q", args[i])
+		}
+		if err != nil {
+			return a, err
+		}
+	}
+	return a, nil
+}
+
+func runStats(args []string) int {
+	a, err := parseStats(args)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return usageErr(statsUsage)
+	}
+	ctx := context.Background()
+	if a.coordinator != "" {
+		coordinatorFlag = a.coordinator
+		defer func() { coordinatorFlag = "" }()
+	}
+	cl, _, active, err := coordResolver.Client()
+	if err != nil {
+		return coordReadFail(a.json, err)
+	}
+	if active {
+		raw, err := cl.Stats(ctx, a.since, a.project)
+		if err != nil {
+			return coordReadFail(a.json, err)
+		}
+		var doc stats.Doc
+		if json.Unmarshal(raw, &doc) != nil {
+			return coordReadFail(a.json, fmt.Errorf("the coordinator's stats document is not valid"))
+		}
+		return printStats(a.json, doc, raw)
+	}
+	st, err := openHistory(false)
+	if err != nil {
+		return exitForError(err)
+	}
+	opts := stats.Options{Now: time.Now(), Since: a.since, Project: a.project, Global: true}
+	var doc stats.Doc
+	if st == nil { // no store on this machine reads as an empty one
+		doc = stats.Build(stats.NoStoreRows(), opts)
+	} else {
+		defer func() { _ = st.Close() }()
+		if doc, err = stats.Compute(ctx, st, opts); err != nil {
+			return exitForError(err)
+		}
+	}
+	return printStats(a.json, doc, nil)
+}
+
+func printStats(asJSON bool, doc stats.Doc, raw json.RawMessage) int {
+	if asJSON {
+		var data any = doc
+		if raw != nil {
+			data = raw
+		}
+		if err := output.WriteData(os.Stdout, "ci runs stats", data, nil); err != nil {
+			return exitForError(err)
+		}
+		return 0
+	}
+	fmt.Print(stats.Text(doc))
+	return 0
+}
diff --git a/free/ci/cmd/runs_tidy.go b/free/ci/cmd/runs_tidy.go
new file mode 100644
index 000000000..8991ef6f2
--- /dev/null
+++ b/free/ci/cmd/runs_tidy.go
@@ -0,0 +1,152 @@
+package main
+
+// Purpose: `nself ci runs prune --tidy [--apply] [--json]` (P7-AUTO-20). It composes the run
+// history retention prune (CI-39), the cache prune and the orphan job-root sweep (TRUST-09)
+// with the operator's free-space target (tidy.free_target_mb) and cache cap (tidy.cache_cap_mb).
+// Inputs:  the flags above; the run store, the cache and the job roots under $NSELF_CI_HOME.
+// Outputs: the list of everything the tidy removes, and with --apply the free space before and
+// after, and whether the target was reached or why not; exit 0, or 10 when --apply did not
+// reach the target.
+// Constraints: no new first-level subcommand: this wraps the `runs prune` handler. Without
+// --apply nothing is removed. --apply refuses while a serve owns the store. Plain
+// `runs prune` is unchanged.
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+
+	"github.com/nself-org/plugins/free/ci/internal/artifacts/records"
+	"github.com/nself-org/plugins/free/ci/internal/authz"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/evidence"
+	"github.com/nself-org/plugins/free/ci/internal/history"
+	"github.com/nself-org/plugins/free/ci/internal/readiness/sample"
+	"github.com/nself-org/plugins/free/ci/internal/selftest"
+)
+
+const tidyUsage = "nself ci runs prune --tidy [--apply] [--json]"
+
+// tidyExitShort is the exit code of --apply when the free-space target was not reached.
+const tidyExitShort = 10
+
+func init() {
+	prune := runsSubs["prune"] // registered by runs_history.go, which initialises first
+	if prune == nil {
+		panic("nself-ci: runs prune must register before cmd/runs_tidy.go")
+	}
+	runsSubs["prune"] = func(args []string) int {
+		if rest, ok := cutFlag(args, "tidy"); ok {
+			return runRunsTidy(rest)
+		}
+		return prune(args)
+	}
+}
+
+// cutFlag removes a boolean --name flag from args and reports whether it was set.
+func cutFlag(args []string, name string) ([]string, bool) {
+	var rest []string
+	on := false
+	for _, a := range args {
+		if n, val, hasVal := strings.Cut(strings.TrimLeft(a, "-"), "="); strings.HasPrefix(a, "-") && n == name && (!hasVal || val == "true") {
+			on = true
+			continue
+		}
+		rest = append(rest, a)
+	}
+	return rest, on
+}
+
+func runRunsTidy(args []string) int {
+	fs := flag.NewFlagSet("runs prune --tidy", flag.ContinueOnError)
+	apply := fs.Bool("apply", false, "remove what the report lists (default: report only)")
+	asJSON := fs.Bool("json", false, "print one v1 JSON envelope")
+	if err := fs.Parse(args); err != nil || fs.NArg() > 0 {
+		return usageErr(tidyUsage)
+	}
+	if *apply { // a serve owns the store; a second writer must not prune it
+		if code, ok := refuseWhileServe("`runs prune --tidy --apply`"); ok {
+			return code
+		}
+	}
+	ctx := context.Background()
+	rep, err := tidyReport(ctx, *apply)
+	if err != nil {
+		return exitForError(err)
+	}
+	if *asJSON {
+		if err = output.WriteData(os.Stdout, "ci runs prune", rep, nil); err != nil {
+			return exitForError(err)
+		}
+	} else {
+		printTidy(rep)
+	}
+	if rep.Apply && !rep.Reached {
+		return tidyExitShort
+	}
+	return 0
+}
+
+// tidyReport assembles the steps for this machine and runs them.
+func tidyReport(ctx context.Context, apply bool) (selftest.Report, error) {
+	home := sample.CIHome()
+	root, _ := os.Getwd()
+	eff, release, err := policyEffective(ctx, root)
+	defer release()
+	if err != nil {
+		return selftest.Report{}, fmt.Errorf("tidy settings not read, nothing removed: %w", err)
+	}
+	cfg, err := selftest.TidyConfigFrom(&eff)
+	if err != nil {
+		return selftest.Report{}, err
+	}
+	pol, perr := history.LoadPolicy(os.Getenv("NSELF_CI_HOME"))
+	if perr != nil {
+		fmt.Fprintf(os.Stderr, "note: %s is unusable (%v); using the defaults\n", history.ConfigPath(os.Getenv("NSELF_CI_HOME")), perr)
+	}
+	var steps []selftest.Step
+	if evidence.StoreExists(evidence.StorePath()) {
+		fs := flag.NewFlagSet("tidy", flag.ContinueOnError)
+		fs.Bool("json", false, "")
+		fs.String("project", "tidy", "") // the viewer's project is not used: the tidy lists every entry
+		env, err := openCache(fs)
+		if err != nil {
+			return selftest.Report{}, err
+		}
+		defer env.close()
+		steps = append(steps, selftest.HistoryStep(env.st, os.Getenv("NSELF_CI_HOME"), pol, time.Now))
+		if env.viewer.Role == authz.RoleAdmin { // the cache prune is an admin action
+			es := entries.New(env.st, env.blobs, entries.Options{Home: records.StoreDir(os.Getenv("NSELF_CI_HOME")), Getenv: selftest.CacheCapEnv(cfg.CacheCapMB, os.Getenv)})
+			steps = append(steps, selftest.CacheStep(env.st, es, 30*time.Second, time.Now))
+		}
+	}
+	steps = append(steps, selftest.OrphanStep(filepath.Join(home, "work"), home, time.Now))
+	t := selftest.Tidy{Steps: steps, TargetMB: cfg.FreeTargetMB, FreeMB: func() (int64, error) { return selftest.FreeMB(home) }}
+	return t.Run(ctx, apply)
+}
+
+func printTidy(rep selftest.Report) {
+	verb := "would remove"
+	if rep.Apply {
+		verb = "removed"
+	}
+	for _, it := range rep.Items {
+		fmt.Printf("%s %-12s %s\n", verb, it.Step, it.ID)
+	}
+	fmt.Printf("%s %d item(s); %d MB free, target %d MB\n", verb, len(rep.Items), rep.FreeAfterMB, rep.TargetMB)
+	for _, e := range rep.Errors {
+		fmt.Println("error:", e)
+	}
+	switch {
+	case rep.Apply && rep.Reached:
+		fmt.Println("target reached")
+	case rep.Why != "":
+		fmt.Println(rep.Why)
+	}
+}
diff --git a/free/ci/cmd/serve_admin_checkpoint.go b/free/ci/cmd/serve_admin_checkpoint.go
index a6a9578a1..bb820d068 100644
--- a/free/ci/cmd/serve_admin_checkpoint.go
+++ b/free/ci/cmd/serve_admin_checkpoint.go
@@ -3,7 +3,7 @@ package main
 // Purpose: `nself ci serve admin audit checkpoint export <path>` and `... verify --pubkey <fingerprint>
 // <path>` (P7-TRUST-20, Epic D13/D20): the TEAM coordinator signs the head of the audit chain with its own
 // ci-audit key; verify checks a checkpoint file against a fingerprint pinned off-host and against the live
-// chain. It also registers the release quarantine seam of `ci artifacts verify`.
+// chain. It also registers the release quarantine and refusal-audit seams of `ci artifacts verify`.
 // Inputs:  a path; --pubkey (the fingerprint `export` printed); --json; $NSELF_CI_HOME (state.db and the
 //          0600 key audit-checkpoint.key, created at the first export); $NSELF_CI_COORDINATOR_MODE=team.
 // Outputs: export writes the checkpoint file and prints the public-key fingerprint; verify exits 0 when
@@ -58,6 +58,25 @@ func init() {
 		Handler: func(args []string) int { return runAdminCheckpoint(args, productionAdminEnv()) },
 	})
 	releaseQuarantined = storeQuarantined
+	releaseVerifyAudit = storeVerifyAudit
+}
+
+// storeVerifyAudit appends a refused release verification to the coordinator store's audit log; a machine
+// without a store (a release checked away from its coordinator) records nothing.
+func storeVerifyAudit(ctx context.Context, actor, action, target, detail string) error {
+	path := filepath.Join(lifecycle.CIHome(), "state.db")
+	if _, err := os.Stat(path); err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	st, err := store.Open(path, store.Options{})
+	if err != nil {
+		return err
+	}
+	defer func() { _ = st.Close() }()
+	return st.AppendAudit(ctx, actor, action, target, detail)
 }
 
 // storeQuarantined reads the quarantine index of the coordinator store; a machine without one has nothing
diff --git a/free/ci/cmd/serve_install.go b/free/ci/cmd/serve_install.go
new file mode 100644
index 000000000..41b5a881c
--- /dev/null
+++ b/free/ci/cmd/serve_install.go
@@ -0,0 +1,116 @@
+package main
+
+// Purpose: V15-only watcher service installation and exact uninstall.
+// Inputs: explicit manager, scope and paths. No credential is read or rendered.
+// Outputs: service files, manager argv, and unchanged/edited-file notes.
+// Constraints: user scope by default; system scope requires sudo and a node agent.
+// Side effects: install writes; uninstall is destructive, declared in the surface.
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/svc"
+)
+
+type serveInstallFlags struct {
+	launchd, systemd, user, system, dryRun bool
+	binary, repo, envFile                  string
+}
+
+func newServeInstallFlagSet(name string, f *serveInstallFlags) *flag.FlagSet {
+	fs := flag.NewFlagSet(name, flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	fs.BoolVar(&f.launchd, "launchd", false, "use launchd")
+	fs.BoolVar(&f.systemd, "systemd", false, "use systemd")
+	fs.BoolVar(&f.user, "user", false, "install for the login user (default)")
+	fs.BoolVar(&f.system, "system", false, "install a dedicated system watcher on a node-agent host (sudo)")
+	fs.BoolVar(&f.dryRun, "dry-run", false, "print files and manager commands without changes")
+	fs.StringVar(&f.binary, "binary", "", "absolute nself CLI path (default: nself in standard bin directories)")
+	fs.StringVar(&f.repo, "repo", "", "repository checkout (default: current directory)")
+	fs.StringVar(&f.envFile, "env-file", "", "existing 0600 systemd environment file, never copied or read")
+	return fs
+}
+
+func init() {
+	for _, action := range []string{"install", "uninstall"} {
+		name := "serve " + action
+		registerV15("serve "+action, subcommandEntry{V15Only: true,
+			Flags:   func() *flag.FlagSet { return newServeInstallFlagSet(name, &serveInstallFlags{}) },
+			Handler: func(args []string) int { return serveInstallCmd(action, args) }})
+	}
+}
+
+func serveInstallCmd(action string, args []string) int {
+	var f serveInstallFlags
+	pos, err := parseMixed(newServeInstallFlagSet("serve "+action, &f), args)
+	if err != nil || len(pos) != 0 || f.launchd == f.systemd || (f.user && f.system) {
+		return usageErr("nself ci serve " + action + " (--launchd|--systemd) [--user|--system] [--dry-run] [--binary /path/to/nself] [--repo /checkout] [--env-file /path]")
+	}
+	c, err := serveServiceConfig(f)
+	if err == nil {
+		i := svc.Installer{Config: c, Out: os.Stdout, Run: func(ctx context.Context, argv ...string) error {
+			_, exit, e := report.Capture(ctx, argv...)
+			if e != nil {
+				return e
+			}
+			if exit != 0 {
+				return fmt.Errorf("%s exited %d", filepath.Base(argv[0]), exit)
+			}
+			return nil
+		}}
+		if action == "install" {
+			err = i.Install(context.Background())
+		} else {
+			err = i.Uninstall(context.Background())
+		}
+	}
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "Error:", err)
+		return 1
+	}
+	return 0
+}
+
+func serveServiceConfig(f serveInstallFlags) (svc.Config, error) {
+	c := svc.Config{Manager: "systemd", System: f.system, DryRun: f.dryRun, Binary: f.binary, Repo: f.repo, EnvFile: f.envFile, UID: os.Getuid()}
+	if f.launchd {
+		c.Manager = "launchd"
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return c, err
+	}
+	c.Home, c.CIHome = home, os.Getenv("NSELF_CI_HOME")
+	if c.CIHome == "" {
+		c.CIHome = filepath.Join(home, ".nself", "ci")
+	}
+	if c.System {
+		c.Home = svc.SystemHome(c.Manager)
+		c.CIHome = c.Home
+	}
+	if c.Repo == "" {
+		c.Repo, err = os.Getwd()
+		if err != nil {
+			return c, err
+		}
+	}
+	if c.Binary == "" {
+		for _, dir := range []string{"/opt/homebrew/bin", "/usr/local/bin", "/usr/bin"} {
+			p := filepath.Join(dir, "nself")
+			if fi, e := os.Stat(p); e == nil && fi.Mode().IsRegular() && fi.Mode().Perm()&0111 != 0 {
+				c.Binary = p
+				break
+			}
+		}
+		if c.Binary == "" {
+			return c, fmt.Errorf("pass --binary with the absolute nself CLI path")
+		}
+	}
+	return c, nil
+}
diff --git a/free/ci/cmd/serve_install_test.go b/free/ci/cmd/serve_install_test.go
new file mode 100644
index 000000000..54584a909
--- /dev/null
+++ b/free/ci/cmd/serve_install_test.go
@@ -0,0 +1,102 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestServeInstallRegistration(t *testing.T) {
+	s := loadSpec(t)
+	for _, action := range []string{"install", "uninstall"} {
+		name := "serve " + action
+		entry, ok := v15Subcommands[name]
+		if !ok || !entry.V15Only {
+			t.Fatal("missing V15 entry", name)
+		}
+		if _, legacy := subcommands[name]; legacy {
+			t.Fatal("changed legacy dispatch")
+		}
+		found := false
+		for _, r := range s.Commands {
+			if r.Path != name {
+				continue
+			}
+			found = true
+			if problems := checkFlags(name, r, entry.Flags(), true); len(problems) != 0 {
+				t.Fatal(problems)
+			}
+			want := "write"
+			if action == "uninstall" {
+				want = "destructive"
+			}
+			if r.SideEffect != want {
+				t.Fatal("wrong side effect")
+			}
+		}
+		if !found {
+			t.Fatal("missing surface row")
+		}
+	}
+}
+
+func TestServeInstallFakeManagers(t *testing.T) {
+	for _, manager := range []string{"launchd", "systemd"} {
+		t.Run(manager, func(t *testing.T) {
+			home := t.TempDir()
+			t.Setenv("HOME", home)
+			t.Setenv("CI", "1")
+			t.Setenv("NSELF_CI_HOME", filepath.Join(home, "ci"))
+			bin := filepath.Join(home, "bin")
+			if err := os.Mkdir(bin, 0700); err != nil {
+				t.Fatal(err)
+			}
+			log := filepath.Join(home, "calls")
+			name := "systemctl"
+			if manager == "launchd" {
+				name = "launchctl"
+			}
+			script := "#!/bin/sh\nprintf '%s\\n' \"$*\" >> '" + log + "'\n"
+			if err := os.WriteFile(filepath.Join(bin, name), []byte(script), 0700); err != nil {
+				t.Fatal(err)
+			}
+			// The process funnel uses sh to launch argv. Keep only that launcher
+			// and the fake manager available on PATH.
+			if err := os.Symlink("/bin/sh", filepath.Join(bin, "sh")); err != nil {
+				t.Fatal(err)
+			}
+			t.Setenv("PATH", bin)
+			args := []string{"--" + manager, "--binary", "/usr/local/bin/nself", "--repo", home}
+			if code := serveInstallCmd("install", args); code != 0 {
+				t.Fatalf("install exit %d", code)
+			}
+			before, err := os.ReadFile(log)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if code := serveInstallCmd("install", args); code != 0 {
+				t.Fatalf("repeat exit %d", code)
+			}
+			after, err := os.ReadFile(log)
+			if err != nil || string(before) != string(after) {
+				t.Fatal("repeat invoked manager", err)
+			}
+			if code := serveInstallCmd("uninstall", args); code != 0 {
+				t.Fatalf("uninstall exit %d", code)
+			}
+			after, err = os.ReadFile(log)
+			if err != nil || !strings.Contains(string(after), "ci-watch") {
+				t.Fatal("fake manager not executed", err)
+			}
+		})
+	}
+}
+
+func TestServeInstallBadFlags(t *testing.T) {
+	for _, args := range [][]string{nil, {"--launchd", "--systemd"}, {"--launchd", "--user", "--system"}, {"--systemd", "unexpected"}} {
+		if code := serveInstallCmd("install", args); code != 1 {
+			t.Fatalf("%v: got %d", args, code)
+		}
+	}
+}
diff --git a/free/ci/cmd/serve_watch.go b/free/ci/cmd/serve_watch.go
new file mode 100644
index 000000000..7d7e37349
--- /dev/null
+++ b/free/ci/cmd/serve_watch.go
@@ -0,0 +1,193 @@
+package main
+
+// Purpose: `nself ci serve watch` (P7-AUTO-11, ADR 0032 decision 4), the PERSONAL-mode trigger source,
+//          under serve because the subcommand cap leaves no first-level slot (AUTO D9). The loop is
+//          internal/watch; this file wires its ports: the HOST-17 head scan, the status ledger and
+//          reporter, readiness, the result context and the coordinator path of a bare run.
+// Inputs:  argv; the operator policy (watch.*, providers.github.*, providers.report_owner, readiness.*);
+//          NSELF_CI_REPO, NSELF_CI_HOME.
+// Outputs: one JSON envelope (or one line) per pass; demand, heartbeat and log under $NSELF_CI_HOME;
+//          exit 0 after SIGTERM or --once, 1 on a start failure, 2 on usage.
+// Constraints: V15 only; outbound only (no listener, no port); the token is read by the provider runtime
+//          from providers.github.token_env, never printed or put in argv; a commit runs in a detached
+//          worktree with Options.Record and trigger api, NoStatus because the watcher reports; no isolated
+//          runner is wired, so a collaborator head is always skipped (E821); the hosted tier and the
+//          background tick stay off until their ports exist.
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/output"
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/providers"
+	"github.com/nself-org/plugins/free/ci/internal/providers/github/reconcile"
+	"github.com/nself-org/plugins/free/ci/internal/readiness"
+	"github.com/nself-org/plugins/free/ci/internal/readiness/sample"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/watch"
+)
+
+const serveWatchUsage = "nself ci serve watch [--interval 60s] [--repos o/r,…] [--once] [--json]"
+
+type serveWatchFlags struct {
+	interval   time.Duration
+	repos      listFlag
+	once, json bool
+}
+
+func newServeWatchFlagSet(f *serveWatchFlags) *flag.FlagSet {
+	fs := flag.NewFlagSet("serve watch", flag.ContinueOnError)
+	fs.DurationVar(&f.interval, "interval", 0, "pass cadence (default: providers.github.poll_interval)")
+	fs.Var(&f.repos, "repos", "comma-separated owner/repo list (default: this checkout's repository)")
+	fs.BoolVar(&f.once, "once", false, "run one pass and exit")
+	fs.BoolVar(&f.json, "json", false, "print one v1 JSON envelope per pass")
+	return fs
+}
+
+func init() {
+	registerV15("serve watch", subcommandEntry{V15Only: true,
+		Flags:   func() *flag.FlagSet { return newServeWatchFlagSet(&serveWatchFlags{}) },
+		Handler: serveWatchCmd})
+}
+
+func serveWatchCmd(args []string) int {
+	var f serveWatchFlags
+	if pos, err := parseMixed(newServeWatchFlagSet(&f), args); err != nil || len(pos) != 0 || f.interval < 0 {
+		return usageErr(serveWatchUsage)
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	w, closeFn, err := buildWatcher(ctx, f)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		return 1
+	}
+	defer closeFn()
+	w.Run(ctx, f.once, func(rep watch.PassReport) {
+		if f.json {
+			_ = output.WriteData(os.Stdout, "ci serve watch", rep, nil)
+			return
+		}
+		fmt.Fprintf(os.Stdout, "%s ready=%t ran=%d queued=%d held=%d errors=%d\n", rep.At.Format(time.RFC3339), rep.Ready, rep.Ran, rep.Queued, rep.Held, len(rep.Errors))
+	})
+	return 0
+}
+
+// buildWatcher resolves the settings and wires the ports.
+func buildWatcher(ctx context.Context, f serveWatchFlags) (w *watch.Watcher, closeFn func(), err error) {
+	root, err := evidenceRoot("")
+	if err != nil {
+		return nil, nil, err
+	}
+	home := sample.CIHome()
+	if home == "" {
+		return nil, nil, errors.New("no CI home: set NSELF_CI_HOME")
+	}
+	st, err := openHistory(true)
+	if err != nil {
+		return nil, nil, err
+	}
+	closeFn = func() { _ = st.Close() }
+	defer func() {
+		if err != nil {
+			closeFn()
+		}
+	}()
+	res := policy.Resolver{Store: st, Run: policy.Runner(report.Capture)}
+	got, err := res.Resolve(ctx, policy.Repo{Root: root, Project: policy.ProjectIDGitCached(ctx, res.Run, root), Visibility: "unknown", Class: "owner"}, policy.Revision{Dir: root})
+	if err != nil {
+		return nil, nil, err
+	}
+	eff := &got.Effective
+	c, err := watch.ApplyPolicy(watch.Defaults(), eff)
+	gs, gerr := reconcile.SettingsFrom(eff)
+	if err = errors.Join(err, gerr); err != nil {
+		return nil, nil, err
+	}
+	c.Interval = gs.PollInterval
+	if f.interval > 0 {
+		c.Interval = f.interval
+	}
+	gh := report.GH{Capture: report.Capture}
+	if login, lerr := gh.Login(ctx); lerr == nil {
+		c.Trusted = []string{login}
+	}
+	host, _ := os.Hostname()
+	c.Host = strings.NewReplacer(" ", "-", "\t", "-", "\n", "-").Replace(firstOf(host, "localhost"))
+	c.Incarnation = strconv.FormatInt(time.Now().UnixNano(), 36)
+	roots, err := watchRoots(ctx, root, home, f.repos.vals)
+	if err != nil {
+		return nil, nil, err
+	}
+	for repo := range roots {
+		c.Repos = append(c.Repos, repo)
+	}
+	reconcile.UsePolicy(func(context.Context) (*policy.Effective, error) { return eff, nil })
+	reconcile.Use(st)
+	rc := &report.ResultContexts{Read: gh.RequiredPinned}
+	ev := &readiness.Evaluator{Config: func(context.Context) (readiness.Config, error) { return readiness.ConfigFrom(eff) }}
+	team := providers.ReportOwner(*eff) == report.OwnerTeam
+	logw := &watch.RotatingLog{Dir: watch.LogDir(home)}
+	opts := reconcile.ScanOptions{Branches: c.Branches, MaxBranches: c.MaxBranches}
+	w, err = watch.New(c, watch.Ports{
+		Scanner: watchScanner{e: reconcile.Default(), opts: opts, days: c.BranchDays}, Ledger: gh, Reporter: gh,
+		Runner: watchRunner{roots: roots, home: home}, ResultContext: rc.ResolveResultContext,
+		Ready: func(ctx context.Context) (bool, []string) {
+			r, rerr := ev.Evaluate(ctx)
+			if rerr != nil {
+				return false, []string{rerr.Error()}
+			}
+			return r.Ready, r.Why
+		},
+		TeamOwned: func(context.Context, string) bool { return team },
+		Alert: func(_ context.Context, h watch.Head, d string) {
+			logw.Event("alert", map[string]any{"repo": h.Repo, "sha": h.SHA, "message": d})
+		},
+		Publish: func(doc demand.Document) error {
+			return demand.Write(demand.WriterConfig{Dir: home, Host: c.Host}, doc)
+		},
+		Heartbeat: watch.Heartbeat(watch.LogDir(home)), Log: logw.Event,
+	})
+	return w, closeFn, err
+}
+
+// watchRoots maps each watched repository to a local checkout: this checkout for its own origin, else
+// $NSELF_CI_HOME/watch/repos/<owner>/<repo>. A repository with no checkout refuses the start.
+func watchRoots(ctx context.Context, root, home string, repos []string) (map[string]string, error) {
+	out := map[string]string{}
+	url, _, _ := report.Capture(ctx, "git", "-C", root, "remote", "get-url", "origin")
+	owner, name, ok := report.ParseRemote(strings.TrimSpace(url))
+	self := strings.ToLower(owner + "/" + name)
+	if len(repos) == 0 {
+		if !ok {
+			return nil, errors.New("this checkout has no GitHub origin; pass --repos")
+		}
+		return map[string]string{owner + "/" + name: root}, nil
+	}
+	for _, r := range repos {
+		r = strings.TrimSpace(r)
+		if strings.Count(r, "/") != 1 {
+			return nil, fmt.Errorf("--repos: %q is not owner/repo", r)
+		}
+		dir := filepath.Join(home, "watch", "repos", filepath.FromSlash(r))
+		if ok && strings.ToLower(r) == self {
+			dir = root
+		}
+		if fi, err := os.Stat(dir); err != nil || !fi.IsDir() {
+			return nil, fmt.Errorf("%s has no local checkout (clone it to %s)", r, dir)
+		}
+		out[r] = dir
+	}
+	return out, nil
+}
diff --git a/free/ci/cmd/serve_watch_scan.go b/free/ci/cmd/serve_watch_scan.go
new file mode 100644
index 000000000..1d2134cc5
--- /dev/null
+++ b/free/ci/cmd/serve_watch_scan.go
@@ -0,0 +1,136 @@
+package main
+
+// Purpose: the head scan port of `nself ci serve watch` (serve_watch.go wires it): HOST-17 scanning and
+//          the TRUST classification of each scanned head.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/providers/github/reconcile"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/trust/source"
+	"github.com/nself-org/plugins/free/ci/internal/watch"
+)
+
+// watchScanner is the HOST-17 head scan behind watch.Scanner.
+type watchScanner struct {
+	e    *reconcile.Engine
+	opts reconcile.ScanOptions
+	days int
+}
+
+func (s watchScanner) Scan(ctx context.Context, repo string) (watch.Scan, error) {
+	o := s.opts
+	if s.days > 0 {
+		o.Since = s.e.Now().Add(-time.Duration(s.days) * 24 * time.Hour)
+	}
+	hs, err := s.e.ScanHeads(ctx, repo, o)
+	var q *reconcile.QuotaStop
+	if errors.As(err, &q) {
+		return watch.Scan{}, &watch.QuotaError{RetryAt: q.RetryAt}
+	}
+	if err != nil || hs.NotModified {
+		return watch.Scan{NotModified: hs.NotModified}, err
+	}
+	out := watch.Scan{}
+	for _, h := range hs.Heads {
+		out.Heads = append(out.Heads, watchHead(repo, h))
+	}
+	return out, nil
+}
+
+// watchHead classifies a scanned head by the TRUST source rules and restamps its facts as a watch
+// trigger. Only a writer can push a branch of the repository; the default and protected branches are
+// the owner's; a pull request's author association names its permission; a fork is untrusted.
+func watchHead(repo string, h reconcile.Head) watch.Head {
+	f := h.Facts
+	now := f.ReceivedAt
+	perm := "write"
+	switch {
+	case h.Fork:
+		perm = ""
+	case h.PR > 0:
+		switch strings.ToUpper(h.AuthorAssociation) {
+		case "OWNER":
+			perm = "admin"
+		case "MEMBER", "COLLABORATOR":
+		default:
+			perm = ""
+		}
+	case h.Default || h.Protected:
+		perm = "admin"
+	}
+	if perm != "" {
+		f.ActorPermission = model.Fact[string]{Value: &perm, Source: "api", ObservedAt: now, Confidence: "known"}
+	}
+	if h.Default {
+		yes := true
+		f.SHAReachable = model.Fact[bool]{Value: &yes, Source: "api", ObservedAt: now, Confidence: "known"}
+	}
+	class := source.Classify(f).Class
+	f.Kind, f.Source, f.Auth = "api", "watch", "per-repo"
+	return watch.Head{Repo: repo, SHA: h.SHA, Branch: h.Branch, Default: h.Default, Protected: h.Protected, Extra: h.Extra,
+		PR: h.PR, Fork: h.Fork, Trust: class, CommittedAt: h.CommittedAt, Facts: f}
+}
+
+// watchRunner runs a commit through the coordinator in a detached worktree of its local checkout.
+type watchRunner struct {
+	roots map[string]string
+	home  string
+}
+
+func (r watchRunner) Run(ctx context.Context, j watch.Job) (watch.Outcome, error) {
+	root, ok := r.roots[j.Head.Repo]
+	if !ok || j.Isolated {
+		return watch.Outcome{}, fmt.Errorf("no local runner for %s", j.Head.Repo)
+	}
+	git := func(c context.Context, args ...string) error {
+		out, exit, err := report.Capture(c, append([]string{"git", "-C", root}, args...)...)
+		if err == nil && exit != 0 {
+			err = fmt.Errorf("git %s: %s", args[0], strings.TrimSpace(out))
+		}
+		return err
+	}
+	dir := filepath.Join(r.home, "watch", "work", j.Head.SHA[:12])
+	if err := git(ctx, "fetch", "--quiet", "--no-tags", "origin", j.Head.SHA); err != nil {
+		return watch.Outcome{}, err
+	}
+	if err := git(ctx, "worktree", "add", "--detach", "--force", dir, j.Head.SHA); err != nil {
+		return watch.Outcome{}, err
+	}
+	defer func() { _ = git(context.WithoutCancel(ctx), "worktree", "remove", "--force", dir) }()
+	jobs := j.Only
+	if len(jobs) == 0 {
+		jobs = []string{""}
+	}
+	worst := watch.Outcome{State: report.Success, Description: "passed"}
+	for _, job := range jobs {
+		o := RunOptions{Root: dir, Home: r.home, Job: job, Trigger: "api", Record: true, NoStatus: true}
+		if err := o.Validate(cirun.Hooks{}.Resolved()); err != nil {
+			return watch.Outcome{}, err
+		}
+		p, digest, subst, err := preparePlan(ctx, o)
+		if err != nil {
+			return watch.Outcome{}, err
+		}
+		c := &cirun.Coordinator{Opts: o, Plan: p, ConfigDigest: digest, ConfigOutside: configOutside(ctx, dir), Substantive: subst, Out: os.Stderr}
+		res, err := c.Run(ctx)
+		switch {
+		case err != nil:
+			return watch.Outcome{}, err
+		case res.Exit == 1:
+			worst = watch.Outcome{State: report.Failure, Description: "gate failed (run " + res.RunID + ")"}
+		case res.Exit != 0 && worst.State == report.Success:
+			worst = watch.Outcome{State: report.Error, Description: "infrastructure error (run " + res.RunID + ")"}
+		}
+	}
+	return worst, nil
+}
diff --git a/free/ci/cmd/surface_test.go b/free/ci/cmd/surface_test.go
new file mode 100644
index 000000000..359a4f512
--- /dev/null
+++ b/free/ci/cmd/surface_test.go
@@ -0,0 +1,257 @@
+package main
+
+// Purpose: ties free/ci/surface/commands.yaml (the authored machine surface, P7-CI-62, CI D31) to the code: the key set of
+//          cmd/subcommands.go, the side-effect class of each key, each Flags constructor and plugin.json.
+// Constraints: no network, no process started; reads the spec and the manifest from the module root.
+
+import (
+	"bytes"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+type specFlag struct {
+	Name string `yaml:"name"`
+	Type string `yaml:"type"`
+}
+
+type specRow struct {
+	Path       string `yaml:"path"`
+	SideEffect string `yaml:"side_effect"`
+	JSON       string `yaml:"json"`
+	Surface    string `yaml:"surface"`
+	Confirm    *struct {
+		Flags []string `yaml:"flags"`
+	} `yaml:"confirm"`
+	Flags []specFlag `yaml:"flags"`
+}
+
+type specFile struct {
+	Root     specRow   `yaml:"root"`
+	Commands []specRow `yaml:"commands"`
+}
+
+func loadSpec(t *testing.T) specFile {
+	t.Helper()
+	raw, err := os.ReadFile("../surface/commands.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var s specFile
+	dec := yaml.NewDecoder(bytes.NewReader(raw))
+	if err := dec.Decode(&s); err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+// minClass is the lowest side-effect class a key may declare (NODE D17 and the CI/TRUST Tickets that own each key);
+// a key not listed is at least read.
+var minClass = map[string]string{
+	"run": "remote", "build": "remote",
+	"nodes add": "remote", "nodes pair": "remote", "nodes test": "remote", "nodes set": "remote", "nodes drain": "remote",
+	"nodes enable": "remote", "nodes rotate": "remote", "nodes upgrade": "remote", "nodes provision": "remote",
+	"nodes revoke": "destructive", "nodes remove": "destructive", "serve restore": "destructive",
+	"nodes label": "write", "nodes projects add": "write", "nodes projects remove": "write", "serve": "write",
+	"policy set": "write", "policy unset": "write", "policy pin": "write", "config migrate": "write",
+	"runs cancel": "remote", "runs prune": "destructive",
+}
+
+var classRank = map[string]int{"read": 0, "write": 1, "remote": 2, "destructive": 3}
+
+// tableKeys is every key a machine surface row must exist for.
+func tableKeys() []string {
+	set := map[string]bool{}
+	for k := range subcommands {
+		set[k] = true
+	}
+	for k := range v15Subcommands {
+		set[k] = true
+	}
+	for k := range runsSubs {
+		set["runs "+k] = true
+	}
+	var out []string
+	for k := range set {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// flagType maps a registered flag value to the manifest type name.
+func flagType(f *flag.Flag) string {
+	if b, ok := f.Value.(interface{ IsBoolFlag() bool }); ok && b.IsBoolFlag() {
+		return "bool"
+	}
+	switch t := fmt.Sprintf("%T", f.Value); {
+	case strings.HasSuffix(t, "durationValue"):
+		return "duration"
+	case strings.HasSuffix(t, "intValue"), strings.HasSuffix(t, "int64Value"):
+		return "int"
+	case strings.HasSuffix(t, "multiFlag"), strings.HasSuffix(t, "listFlag"):
+		return "stringSlice"
+	case strings.HasSuffix(t, "stringValue"), strings.HasSuffix(t, "funcValue"):
+		return "string"
+	default:
+		return "unknown:" + t
+	}
+}
+
+func constructorFlags(key string) *flag.FlagSet {
+	if e, ok := v15Subcommands[key]; ok && e.Flags != nil {
+		return e.Flags()
+	}
+	return nil
+}
+
+// checkFlags compares spec flags with a constructor's flags; reverse also demands every constructor flag be declared.
+func checkFlags(path string, row specRow, fs *flag.FlagSet, reverse bool) []string {
+	var out []string
+	declared := map[string]bool{}
+	for _, f := range row.Flags {
+		declared[f.Name] = true
+		if f.Name == "post-status" && path == "root" {
+			continue
+		}
+		got := fs.Lookup(f.Name)
+		switch {
+		case got == nil:
+			out = append(out, fmt.Sprintf("%s: spec flag --%s is not defined by the Flags constructor", path, f.Name))
+		case flagType(got) != f.Type:
+			out = append(out, fmt.Sprintf("%s: flag --%s is %s in the code, %s in the spec", path, f.Name, flagType(got), f.Type))
+		}
+	}
+	if reverse {
+		fs.VisitAll(func(f *flag.Flag) {
+			if !declared[f.Name] && f.Name != "help" && f.Name != "h" && f.Name != "sha" {
+				out = append(out, fmt.Sprintf("%s: flag --%s is in the code but not in the spec", path, f.Name))
+			}
+		})
+	}
+	return out
+}
+
+func TestManifestCommandsCurrent(t *testing.T) {
+	s := loadSpec(t)
+	rows := map[string]specRow{}
+	for _, r := range s.Commands {
+		rows[r.Path] = r
+	}
+	var problems []string
+	keys := tableKeys()
+	for _, k := range keys {
+		r, ok := rows[k]
+		if !ok {
+			problems = append(problems, k+": table key has no spec row")
+			continue
+		}
+		if want, ok := minClass[k]; ok && classRank[r.SideEffect] < classRank[want] {
+			problems = append(problems, fmt.Sprintf("%s: side_effect %s is lower than the table class %s", k, r.SideEffect, want))
+		}
+		// v1.4 rows (json none) keep the frozen v1.4 flags, which the V15 constructors need not define.
+		if fs := constructorFlags(k); fs != nil && r.JSON == "envelope" {
+			problems = append(problems, checkFlags(k, r, fs, true)...)
+		}
+	}
+	inTable := map[string]bool{}
+	for _, k := range keys {
+		inTable[k] = true
+	}
+	for p := range rows {
+		if !inTable[p] {
+			problems = append(problems, p+": spec row has no table key")
+		}
+	}
+	problems = append(problems, checkFlags("root", s.Root, bareFlags, true)...)
+	if s.Root.SideEffect != "remote" || s.Root.Confirm == nil || len(s.Root.Confirm.Flags) != 0 {
+		problems = append(problems, "root: bare run must be side_effect remote with confirm {flags: []}")
+	}
+	problems = append(problems, manifestProblems(t, s)...)
+	sort.Strings(problems)
+	for _, p := range problems {
+		t.Error(p)
+	}
+}
+
+// manifestProblems compares the generated block in plugin.json with the spec rows (byte equality is in tools/manifestgen).
+func manifestProblems(t *testing.T, s specFile) []string {
+	raw, err := os.ReadFile("../plugin.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Commands struct {
+			SideEffect  string `json:"side_effect"`
+			Subcommands []struct {
+				Name       string `json:"name"`
+				SideEffect string `json:"side_effect"`
+				JSON       string `json:"json"`
+				Surface    string `json:"surface"`
+				Confirm    *struct {
+					Flags []string `json:"flags"`
+				} `json:"confirm"`
+			} `json:"subcommands"`
+		} `json:"commands"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	var out []string
+	if m.Commands.SideEffect != s.Root.SideEffect {
+		out = append(out, "plugin.json root side_effect differs from the spec: run go generate ./tools/manifestgen/...")
+	}
+	got := map[string]int{}
+	for i, c := range m.Commands.Subcommands {
+		got[c.Name] = i
+	}
+	for _, r := range s.Commands {
+		i, ok := got[r.Path]
+		if !ok {
+			out = append(out, r.Path+": missing from plugin.json commands")
+			continue
+		}
+		c := m.Commands.Subcommands[i]
+		if c.SideEffect != r.SideEffect || c.JSON != r.JSON || c.Surface != r.Surface || (c.Confirm == nil) != (r.Confirm == nil) {
+			out = append(out, r.Path+": plugin.json differs from the spec")
+		}
+	}
+	if len(m.Commands.Subcommands) != len(s.Commands) {
+		out = append(out, "plugin.json lists a different number of commands than the spec")
+	}
+	return out
+}
+
+// TestConsentNoPrompt: every exposed remote or destructive row carries a confirm block, and every consent flag it names
+// is a bool flag its command really defines, so a machine caller never meets a prompt it cannot answer. Rows with
+// `flags: []` take the nonce round trip only and need no flag. (No command is executed here: the fixture-store run
+// of each consent flag waits for the Flags constructors of the runs subcommands.)
+func TestConsentNoPrompt(t *testing.T) {
+	s := loadSpec(t)
+	for _, r := range s.Commands {
+		risky := r.SideEffect == "remote" || r.SideEffect == "destructive"
+		if risky && r.JSON == "envelope" && r.Surface != "cli-only" && r.Confirm == nil {
+			t.Errorf("%s: %s row is exposed without a confirm block", r.Path, r.SideEffect)
+		}
+		if r.Confirm == nil {
+			continue
+		}
+		fs := constructorFlags(r.Path)
+		for _, name := range r.Confirm.Flags {
+			var f *flag.Flag
+			if fs != nil {
+				f = fs.Lookup(name)
+			}
+			if f == nil || flagType(f) != "bool" {
+				t.Errorf("%s: consent flag --%s is not a bool flag of the command", r.Path, name)
+			}
+		}
+	}
+}
diff --git a/free/ci/cmd/v15.go b/free/ci/cmd/v15.go
index e2e3804d6..1fffb8ef8 100644
--- a/free/ci/cmd/v15.go
+++ b/free/ci/cmd/v15.go
@@ -95,6 +95,9 @@ func runV15(args []string) int {
 			continue
 		}
 		if entry, ok := v15Subcommands[strings.Join(args[:n], " ")]; ok {
+			if wantsHelp(args[n:]) { // before the --coordinator client and the handler: help starts nothing
+				return answerHelp(strings.Join(args[:n], " "), args[n:])
+			}
 			if code, done := nodesRemoteDispatch(strings.Join(args[:n], " "), args[n:]); done { // `nodes <sub> --coordinator <url>` (P7-NODE-26)
 				return code
 			}
@@ -159,6 +162,9 @@ func parseBare(args []string) (RunOptions, error) {
 		}
 		return RunOptions{}, errFlagParse
 	}
+	if bare.help { // help prints and exits: the option hooks open the store and run git (P7-CI-46)
+		return RunOptions{}, nil
+	}
 	if dashes && len(argv) == 0 {
 		return RunOptions{}, adhoc.UsageError("`nself ci --` needs a command after the dashes")
 	}
@@ -260,11 +266,14 @@ func runBare(args []string) int {
 		}
 		return code
 	}
+	outside := make(chan bool, 1) // two git reads, independent of the plan: they run beside it (P7-CI-46)
+	go func() { outside <- configOutside(ctx, o.Root) }()
 	p, digest, subst, err := preparePlan(ctx, o)
 	if err != nil {
 		return exitForError(err)
 	}
-	c := &cirun.Coordinator{Opts: o, Plan: p, ConfigDigest: digest, ConfigOutside: configOutside(ctx, o.Root), Substantive: subst, Out: os.Stdout}
+	attachPlacement(ctx, o)
+	c := &cirun.Coordinator{Opts: o, Plan: p, ConfigDigest: digest, ConfigOutside: <-outside, Substantive: subst, Out: os.Stdout}
 	res, err := c.Run(ctx)
 	if err != nil {
 		return exitForError(err)
diff --git a/free/ci/cmd/v15_json.go b/free/ci/cmd/v15_json.go
index 109dbab9d..85b7aa26e 100644
--- a/free/ci/cmd/v15_json.go
+++ b/free/ci/cmd/v15_json.go
@@ -168,7 +168,7 @@ func (r *jsonRenderer) Done(s cirun.Summary) {
 			_ = output.WriteError(r.w, "ci", noEvidence(), meta)
 			return
 		}
-		_ = output.WriteData(r.w, "ci", s.Doc, meta)
+		_ = output.WriteData(r.w, "ci", withPlacement(s.Doc, jsonPlacement), meta)
 		return
 	}
 	em := r.sess.emitter(s.RunID)
diff --git a/free/ci/cmd/v15_machine.go b/free/ci/cmd/v15_machine.go
new file mode 100644
index 000000000..103638778
--- /dev/null
+++ b/free/ci/cmd/v15_machine.go
@@ -0,0 +1,37 @@
+package main
+
+// Purpose: the machine-invocation default of a bare V15 run (P7-CI-62, CI D29): a run started by a machine caller
+// (the cli sets NSELF_INVOKED_BY for MCP and HTTP calls) posts no commit status unless `--post-status` is given.
+// Inputs:  env NSELF_INVOKED_BY; the `--post-status` bare flag.
+// Outputs: RunOptions.NoStatus set, with a one-line reason on stderr; nothing changes when NSELF_INVOKED_BY is unset
+//          or `--post-status` is present.
+// Constraints: an explicit `--no-status` still wins; the hook only ever turns status posting off.
+
+import (
+	"fmt"
+	"io"
+	"os"
+)
+
+var (
+	postStatusFlag bool
+	machineNotice  io.Writer = os.Stderr
+)
+
+func init() {
+	bareFlags.BoolVar(&postStatusFlag, "post-status", false, "post the nself-ci commit status even when a machine caller (MCP, HTTP) started the run")
+	RegisterOptionsHook(machineStatusDefault)
+}
+
+// machineStatusDefault applies the D29 default after flag parsing.
+func machineStatusDefault(o *RunOptions) error {
+	post := postStatusFlag
+	postStatusFlag = false
+	by := os.Getenv("NSELF_INVOKED_BY")
+	if by == "" || post || o.NoStatus {
+		return nil
+	}
+	o.NoStatus = true
+	fmt.Fprintf(machineNotice, "nself ci: no commit status posted for a run invoked by %s (pass --post-status to post it)\n", by)
+	return nil
+}
diff --git a/free/ci/cmd/v15_machine_test.go b/free/ci/cmd/v15_machine_test.go
new file mode 100644
index 000000000..f62a373c6
--- /dev/null
+++ b/free/ci/cmd/v15_machine_test.go
@@ -0,0 +1,47 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// TestMachineDefaults covers CI D29: a machine-invoked run posts no status unless --post-status is given.
+func TestMachineDefaults(t *testing.T) {
+	cases := []struct {
+		name     string
+		by       string
+		args     []string
+		noStatus bool
+		notice   bool
+	}{
+		{"unset env keeps the status", "", nil, false, false},
+		{"machine caller suppresses it", "mcp", nil, true, true},
+		{"post-status restores it", "mcp", []string{"--post-status"}, false, false},
+		{"explicit no-status stays quiet", "http", []string{"--no-status"}, true, false},
+		{"post-status without a machine caller", "", []string{"--post-status"}, false, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Setenv("NSELF_INVOKED_BY", c.by)
+			t.Setenv("NSELF_CI_REPO", t.TempDir())
+			var buf bytes.Buffer
+			old := machineNotice
+			machineNotice = &buf
+			t.Cleanup(func() { machineNotice = old })
+			o, err := parseBare(c.args)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if o.NoStatus != c.noStatus {
+				t.Errorf("NoStatus = %v, want %v", o.NoStatus, c.noStatus)
+			}
+			if got := strings.Count(buf.String(), "\n"); (got == 1) != c.notice || got > 1 {
+				t.Errorf("notice lines = %d, want notice=%v: %q", got, c.notice, buf.String())
+			}
+			if c.notice && !strings.Contains(buf.String(), "--post-status") {
+				t.Errorf("notice does not name --post-status: %q", buf.String())
+			}
+		})
+	}
+}
diff --git a/free/ci/cmd/v15_offload.go b/free/ci/cmd/v15_offload.go
new file mode 100644
index 000000000..4f72c42b5
--- /dev/null
+++ b/free/ci/cmd/v15_offload.go
@@ -0,0 +1,94 @@
+package main
+
+// Purpose: the dirty-tree offload of a dev run (P7-AUTO-13, ADR 0032 D15).
+// When `nself ci --where <node|pool|auto|all>` runs on a tree with uncommitted
+// work, nodes check out a snapshot commit (internal/offload) held under a
+// private ref, so the NODE-03 bundle transport carries the user's exact tree;
+// the run still records the commit it started from, dirty. This file
+// registers the run's OffloadHook slot.
+// Inputs:  the run root (Options.Root), the --where target the invocation
+//          resolved (whereChosen), git through the exec funnel.
+// Outputs: an OffloadSnapshot whose Release deletes the private ref; the names
+//          of untracked files left out go to stderr, never their content.
+// Constraints: only a target that can reach a registered node takes a
+//          snapshot: no --where with nothing remote registered, `local`,
+//          `hosted`, and pool/auto/all with no node keep the HEAD path
+//          unchanged (a hosted runner fetches the revision from the forge,
+//          where a snapshot never exists). A clean tree keeps HEAD. A
+//          tracked secret-shaped or oversized file refuses the run (E807). The
+//          snapshot run stays dirty: unbound evidence, no status of record.
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/offload"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/where"
+)
+
+// Seams for tests.
+var (
+	offloadCapture offload.Capture = report.Capture
+	offloadErr     io.Writer       // nil: os.Stderr
+)
+
+func init() {
+	cirun.RegisterOffload(cirun.SnapshotOffload{Build: buildOffload, Excluded: reportExcluded})
+}
+
+// offloadWanted reports whether a run with this --where target may execute on
+// a registered node, the only kind of runner that fetches the revision by
+// bundle. A pool, auto or all target with no node registered (only hosted
+// providers) keeps HEAD.
+func offloadWanted(ctx context.Context, kind string) bool {
+	switch kind {
+	case where.KindNode:
+		return true
+	case where.KindPool, where.KindAuto, where.KindAll:
+		return len(whereKnown(ctx, true).Nodes) > 0
+	}
+	return false
+}
+
+// buildOffload snapshots the dirty tree at root, or returns nil to keep HEAD.
+func buildOffload(ctx context.Context, root string) (*cirun.OffloadSnapshot, error) {
+	if root == "" || !offloadWanted(ctx, whereChosen.Kind) {
+		return nil, nil
+	}
+	var nonce [8]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return nil, err
+	}
+	scratch, err := os.MkdirTemp("", "nself-ci-offload-")
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = os.RemoveAll(scratch) }() // the temporary index and path list
+	capture := offloadCapture
+	s, err := offload.Take(ctx, capture, root, scratch, hex.EncodeToString(nonce[:]))
+	if err != nil {
+		return nil, err
+	}
+	if s.Clean {
+		return nil, nil
+	}
+	return &cirun.OffloadSnapshot{SHA: s.SHA, Excluded: s.Excluded,
+		Release: func(ctx context.Context) error { return offload.Release(ctx, capture, root, s) }}, nil
+}
+
+// reportExcluded names the untracked files the snapshot left out.
+func reportExcluded(names []string) {
+	w := offloadErr
+	if w == nil {
+		w = os.Stderr
+	}
+	fmt.Fprintf(w, "nself ci: offload: not sent to the node (secret-shaped or over %d MiB, untracked): %s\n",
+		offload.MaxFileBytes>>20, strings.Join(names, ", "))
+}
diff --git a/free/ci/cmd/v15_offload_node_test.go b/free/ci/cmd/v15_offload_node_test.go
new file mode 100644
index 000000000..55dd7e9c4
--- /dev/null
+++ b/free/ci/cmd/v15_offload_node_test.go
@@ -0,0 +1,247 @@
+package main
+
+// Purpose: a registered ssh node behind an in-process agent session, for the
+// cmd-level offload test (P7-AUTO-13). It is the test/sim foreground fixture
+// (P7-AUTO-28) reduced to what `nself ci --where <node>` needs: the node is in
+// the store under NSELF_CI_HOME, ssh.Default starts the session over pipes, and
+// the node stages the checkout bundle the real driver sends, as `serve --stdio`
+// does. No Docker, no network, no real ssh.
+// Inputs:  the run store directory and a body for the node's job.
+// Outputs: what the node's job found in the tree it was given.
+// Constraints: ssh.Default is restored after the test; tests do not run in parallel.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/agent/checkout"
+	"github.com/nself-org/plugins/free/ci/internal/agent/session"
+	"github.com/nself-org/plugins/free/ci/internal/agent/slots"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/planview"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/transport/ssh"
+)
+
+type oflKey struct{}
+
+func (oflKey) KeyID() string        { return "k1" }
+func (oflKey) PublicString() string { return "pub" }
+
+// oflSeen is what the node's job found in its checkout.
+type oflSeen struct {
+	err   error
+	head  string
+	files map[string]string // name -> content for the probed names; a missing name is absent
+}
+
+// oflNode is one registered node and the agent behind it.
+type oflNode struct {
+	id, host, state string
+	probe           []string
+	seen            chan oflSeen
+}
+
+// oflStage is the node side of the checkout: the lease announcement and the
+// bundle's chunk frames go to the receiver and never reach the session.
+type oflStage struct {
+	session.Carrier
+	r *checkout.Receiver
+}
+
+func (c *oflStage) Recv() (protocol.Message, error) {
+	for {
+		m, err := c.Carrier.Recv()
+		if err != nil {
+			return m, err
+		}
+		switch b := m.Body.(type) {
+		case *protocol.Lease:
+			_ = c.r.Expect(*b)
+		case *protocol.Chunk:
+			if b.Stream != checkout.Stream {
+				return m, nil
+			}
+			epoch := uint64(0)
+			if m.Epoch != nil {
+				epoch = *m.Epoch
+			}
+			_ = c.r.Feed(m.LeaseID, epoch, *b)
+			continue
+		}
+		return m, nil
+	}
+}
+
+// serve runs one agent session; the job stages the bundle, records the tree and passes.
+func (n *oflNode) serve(ctx context.Context, table *slots.Table, in io.Reader, out io.Writer) error {
+	car, err := session.NewStreamCarrier(in, out, protocol.CarrierPolicy{Carrier: "A", Personal: true, OperatorOwned: true}, true)
+	if err != nil {
+		return err
+	}
+	recv := checkout.NewReceiver(filepath.Join(n.state, "checkout"), nil)
+	job := session.RunnerFunc(func(ctx context.Context, j session.JobRun) (session.JobResult, error) {
+		s := oflSeen{files: map[string]string{}}
+		src, err := recv.Stage(ctx, j.Lease, j.Root.Dir)
+		if err != nil {
+			s.err = err
+			n.seen <- s
+			return session.JobResult{}, err
+		}
+		if b, e := exec.Command("git", "-C", src, "rev-parse", "HEAD").Output(); e == nil {
+			s.head = strings.TrimSpace(string(b))
+		}
+		for _, name := range n.probe {
+			if b, e := os.ReadFile(filepath.Join(src, name)); e == nil {
+				s.files[name] = string(b)
+			}
+		}
+		n.seen <- s
+		j.Output([]byte("tree checked\n"))
+		ev, _ := json.Marshal(model.Evidence{Schema: "ci.evidence/v1", Revision: j.Lease.Checkout.Revision,
+			Attempt: &model.AttemptRef{ID: j.Lease.AttemptID, N: 1}, Result: "pass"})
+		return session.JobResult{Outcome: session.Outcome{State: "passed"}, Evidence: ev}, nil
+	})
+	s, err := session.New(session.Config{Carrier: &oflStage{Carrier: car, r: recv}, Key: oflKey{}, Slots: table, Runner: job, StateDir: n.state,
+		Hooks: []session.JobHook{}, Coordinator: session.Coordinator{ID: "coord", RootFingerprint: "fp"},
+		Facts: session.Facts{AgentVersion: minAgentVersion, MachineID: n.id}})
+	if err != nil {
+		return err
+	}
+	return s.Run(ctx)
+}
+
+// oflHosts maps a registered runner's ssh host to its in-process agent (one test at a time).
+var oflHosts map[string]*oflNode
+
+// oflStart is the ssh Starter: it picks the runner by destination host.
+func oflStart(ctx context.Context, tgt remote.Target, s string) (*ssh.Conn, error) {
+	for host, n := range oflHosts {
+		if strings.HasSuffix(tgt.Dest, "@"+host) {
+			return n.start(ctx, tgt, s)
+		}
+	}
+	return nil, fmt.Errorf("no node at %s", tgt.Dest)
+}
+
+// start opens a session on n: the "connection" is a pair of pipes.
+func (n *oflNode) start(_ context.Context, _ remote.Target, _ string) (*ssh.Conn, error) {
+	toAgentR, toAgentW := io.Pipe()
+	fromAgentR, fromAgentW := io.Pipe()
+	errR, errW := io.Pipe()
+	table, err := slots.Open(n.state, 2)
+	if err != nil {
+		return nil, err
+	}
+	actx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		e := n.serve(actx, table, toAgentR, fromAgentW)
+		_ = fromAgentW.Close()
+		_ = errW.Close()
+		done <- e
+	}()
+	kill := func() error { _ = fromAgentW.Close(); _ = toAgentR.Close(); cancel(); return nil }
+	return &ssh.Conn{Stdin: toAgentW, Stdout: fromAgentR, Stderr: errR, Wait: func() error { <-done; return nil }, Kill: kill}, nil
+}
+
+// oflRegisterNode registers node id in the store under home and points ssh.Default at it.
+func oflRegisterNode(t *testing.T, home, repo, id string, probe ...string) *oflNode {
+	t.Helper()
+	return oflRegisterRunner(t, home, repo, id, false, probe...)
+}
+
+// oflRegisterRunner is oflRegisterNode for an enrolled node, or, with hosted, for a
+// runner whose capability says it is hosted (sched.RunnerHosted): the dispatcher
+// then delivers its lease as a hosted one, over the same in-process session.
+func oflRegisterRunner(t *testing.T, home, repo, id string, hosted bool, probe ...string) *oflNode {
+	t.Helper()
+	n := &oflNode{id: id, host: id + ".runners.test", state: t.TempDir(), probe: probe, seen: make(chan oflSeen, 4)}
+	ctx := context.Background()
+	st, err := store.Open(filepath.Join(home, "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = st.Close() }()
+	pin := remote.PinnedHostKeys{Path: filepath.Join(home, "known_hosts")}
+	if err = pin.Add("nself-ci-"+id, n.host+" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDummyKeyForTestsOnlyDummyKeyForTestsOnly000"); err != nil {
+		t.Fatal(err)
+	}
+	c, err := planview.LocalCapability(planview.LocalFacts{Project: repo, Platform: runtime.GOOS + "/" + runtime.GOARCH, CPUs: 8, MemMB: 8192, Now: time.Now()})
+	if err != nil {
+		t.Fatal(err)
+	}
+	lan, owned, uid := "lan", "owned", true
+	if hosted {
+		lan = "hosted"
+	}
+	c.Identity.ID, c.Identity.Name, c.Identity.Provider, c.Identity.Transport = id, id, "ssh", "ssh"
+	c.Identity.SSH = &model.CapabilitySSH{Hostname: n.host, Port: 22, User: "ci"}
+	c.SecretsEligible = true
+	c.Location.Kind.Value, c.Economics.Class.Value = &lan, &owned
+	c.Separation.UIDSeparation = model.Fact[bool]{Value: &uid, Source: "self", ObservedAt: time.Now(), Confidence: "known"}
+	doc, err := json.Marshal(c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = st.NodePut(ctx, store.NodeRecord{ID: id, Name: id, State: "offline", Lifecycle: []byte("{}"), Trust: []byte("{}"),
+		DeployHost: []byte("{}"), Capability: doc, ObservedAt: time.Now().UnixNano()}, "test"); err != nil {
+		t.Fatal(err)
+	}
+	admin, err := store.NewAdminAuthority("test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	trust := model.CapabilityTrust{
+		Accepts:       oflAssigned([]model.TrustClass{"owner", "internal"}),
+		Isolation:     oflAssigned(model.Isolation("container")),
+		Network:       oflAssigned([]model.NetworkScope{"none", "internet", "restricted", "lan", "privileged"}),
+		SecretClasses: oflAssigned([]model.SecretClass{"none"}),
+		PrivacyZone:   oflAssigned(model.PrivacyZone("private-infrastructure")),
+	}
+	reg := registry.New(st)
+	if _, err = reg.SetTrust(ctx, id, trust, admin); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = reg.SetState(ctx, id, "online", "", "test"); err != nil {
+		t.Fatal(err)
+	}
+	if oflHosts == nil {
+		d := ssh.Default
+		home0, start0, ver0, hb0 := d.Home, d.Start, d.SSHVersion, d.Heartbeat
+		d.Home, d.Start, d.Heartbeat = home, oflStart, time.Second
+		d.SSHVersion = func(context.Context) (remote.Version, error) { return remote.Version{Major: 9, Minor: 6}, nil }
+		oflHosts = map[string]*oflNode{}
+		t.Cleanup(func() { d.Home, d.Start, d.SSHVersion, d.Heartbeat, oflHosts = home0, start0, ver0, hb0, nil })
+	}
+	oflHosts[n.host] = n
+	return n
+}
+
+func oflAssigned[T any](v T) model.Fact[T] {
+	return model.Fact[T]{Value: &v, Source: "assigned", ObservedAt: time.Now(), Confidence: "known"}
+}
+
+// wait returns what the node's job saw, or fails when no job reached the node.
+func (n *oflNode) wait(t *testing.T) oflSeen {
+	t.Helper()
+	select {
+	case s := <-n.seen:
+		return s
+	case <-time.After(60 * time.Second):
+		t.Fatal("no job reached the node")
+	}
+	panic("unreachable")
+}
diff --git a/free/ci/cmd/v15_offload_test.go b/free/ci/cmd/v15_offload_test.go
new file mode 100644
index 000000000..982c58bf5
--- /dev/null
+++ b/free/ci/cmd/v15_offload_test.go
@@ -0,0 +1,272 @@
+package main
+
+// Purpose: P7-AUTO-13 through the real CLI path. `nself ci --where <node>` on a
+// tree with uncommitted work runs runV15 -> parseBare (--where) -> the
+// Coordinator -> the registered OffloadHook -> offload.Take -> the ssh driver's
+// bundle -> the node's checkout, and the node's job sees the user's tree.
+// Inputs:  a committed repository (newEvRepo) made dirty, one registered node.
+// Outputs: exit codes, stderr, what the node saw, the repository before/after.
+// Constraints: NSELF_V15=1 (newEvRepo); no Docker, no network, no real ssh.
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/where"
+)
+
+const (
+	oflEnvSecret   = "ENV_VALUE_MUST_NOT_TRAVEL"
+	oflLocalSecret = "ENV_LOCAL_VALUE_MUST_NOT_TRAVEL"
+)
+
+func resetWhere(t *testing.T) {
+	t.Cleanup(func() { whereValue, whereChosen = "", where.Target{} })
+}
+
+// dirtyNodeRepo is a committed repository with an ignore file, made dirty the
+// way a laptop is: an edited tracked file, a new file, an ignored .env and an
+// untracked .env.local; node n1 is registered and reachable. HOME is private:
+// git reads the user's global excludes, which may already ignore .env.local.
+func dirtyNodeRepo(t *testing.T) (*evRepo, *oflNode, string) {
+	t.Helper()
+	resetWhere(t)
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	r := newEvRepo(t)
+	r.commit("f.txt", "committed\n")
+	head := r.commit(".gitignore", ".env\nignored.txt\n")
+	n := oflRegisterNode(t, r.home, r.dir, "n1", "f.txt", "new.txt", ".env", ".env.local", "ignored.txt")
+	put(t, r.dir, "f.txt", "edited on the laptop\n")
+	put(t, r.dir, "new.txt", "untracked and not ignored\n")
+	put(t, r.dir, ".env", oflEnvSecret+"\n")
+	put(t, r.dir, ".env.local", oflLocalSecret+"\n")
+	put(t, r.dir, "ignored.txt", "ignored\n")
+	return r, n, head
+}
+
+// oflRepoState is everything about the user's repository an offload must leave alone.
+func oflRepoState(t *testing.T, dir string) string {
+	t.Helper()
+	parts := []string{
+		git(t, dir, "status", "--porcelain=v2", "--ignored"),
+		git(t, dir, "for-each-ref"),
+		git(t, dir, "ls-files", "-s"),
+		git(t, dir, "rev-parse", "HEAD"),
+	}
+	for _, name := range []string{"f.txt", "new.txt", ".env", ".env.local", "ignored.txt", ".gitignore"} {
+		b, err := os.ReadFile(filepath.Join(dir, name))
+		if err != nil {
+			t.Fatal(err)
+		}
+		parts = append(parts, name+"="+string(b))
+	}
+	return strings.Join(parts, "\n--\n")
+}
+
+func TestCLIWhereNodeOffloadsDirtyTree(t *testing.T) {
+	r, n, head := dirtyNodeRepo(t)
+	before := oflRepoState(t, r.dir)
+	out, errOut, code := r.ci("--where", "n1")
+	if code != 0 {
+		t.Fatalf("exit %d\nstdout %s\nstderr %s", code, out, errOut)
+	}
+	if whereChosen.Kind != where.KindNode {
+		t.Fatalf("--where n1 resolved to %q, want a node target", whereChosen.Kind)
+	}
+	s := n.wait(t)
+	if s.err != nil {
+		t.Fatalf("the node could not stage the checkout: %v", s.err)
+	}
+	if s.head == "" || s.head == head {
+		t.Fatalf("node HEAD %q: want the snapshot commit, not the committed HEAD %s", s.head, head)
+	}
+	if parent := git(t, r.dir, "rev-parse", "--verify", "-q", s.head+"^"); parent != head {
+		t.Errorf("snapshot parent %s, want HEAD %s", parent, head)
+	}
+	if s.files["f.txt"] != "edited on the laptop\n" || s.files["new.txt"] != "untracked and not ignored\n" {
+		t.Errorf("the node did not get the user's tree: %q", s.files)
+	}
+	for _, name := range []string{".env", ".env.local", "ignored.txt"} {
+		if c, ok := s.files[name]; ok {
+			t.Errorf("%s reached the node (%d bytes)", name, len(c))
+		}
+	}
+	if !strings.Contains(errOut, "not sent to the node") || !strings.Contains(errOut, ".env.local") {
+		t.Errorf("the excluded untracked .env.local is not named:\nstderr %s\nstdout %s", errOut, out)
+	}
+	for _, secret := range []string{oflEnvSecret, oflLocalSecret} {
+		if strings.Contains(out+errOut, secret) {
+			t.Errorf("secret content %q reached the output", secret)
+		}
+	}
+	if after := oflRepoState(t, r.dir); after != before {
+		t.Errorf("the user's repository changed:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+	if refs := git(t, r.dir, "for-each-ref", "refs/nself-ci/"); refs != "" {
+		t.Errorf("private refs left behind:\n%s", refs)
+	}
+	requireRecordedHEAD(t, r, head)
+}
+
+// requireRecordedHEAD: the run's recorded revision is the commit, never the
+// snapshot, which no ref keeps once the run ends (P7-CI-41: a reproduction
+// never uses uncommitted changes).
+func requireRecordedHEAD(t *testing.T, r *evRepo, head string) {
+	t.Helper()
+	st, err := store.Open(filepath.Join(r.home, "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = st.Close() }()
+	rows, err := st.PipelinesByRevision(context.Background(), head)
+	if err != nil || len(rows) != 1 {
+		t.Fatalf("runs recorded at HEAD %s: %d %v; the run must record the commit, not the snapshot", head, len(rows), err)
+	}
+}
+
+// TestCLIAutoDirtyRunStaysLocal: with a node registered, a bare run is `auto`
+// and takes a snapshot, but the node is offline, so the job runs here. The run
+// records HEAD, the snapshot ref is gone and the repository is unchanged, so no
+// recorded revision depends on an unreachable commit.
+func TestCLIAutoDirtyRunStaysLocal(t *testing.T) {
+	r, n, head := dirtyNodeRepo(t)
+	st, err := store.Open(filepath.Join(r.home, "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = registry.New(st).SetState(context.Background(), n.id, "offline", "", "test"); err != nil {
+		t.Fatal(err)
+	}
+	if err = st.Close(); err != nil {
+		t.Fatal(err)
+	}
+	before := oflRepoState(t, r.dir)
+	out, errOut, code := r.ci("--no-status")
+	if code != 0 || whereChosen.Kind != where.KindAuto {
+		t.Fatalf("exit %d kind %q\nstdout %s\nstderr %s", code, whereChosen.Kind, out, errOut)
+	}
+	if !strings.Contains(errOut, "not sent to the node") {
+		t.Fatalf("auto with a node registered must take the snapshot (no exclusion notice):\n%s", errOut)
+	}
+	select {
+	case s := <-n.seen:
+		t.Fatalf("an offline node ran the job: %+v", s)
+	default:
+	}
+	requireRecordedHEAD(t, r, head)
+	if refs := git(t, r.dir, "for-each-ref", "refs/nself-ci/"); refs != "" {
+		t.Errorf("private refs left behind:\n%s", refs)
+	}
+	if after := oflRepoState(t, r.dir); after != before {
+		t.Errorf("the user's repository changed:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+}
+
+// TestCLIDirtyRunNodeWithHostedRegistered: a node and a hosted runner are both
+// registered and placement picks the node: the node gets the snapshot, the
+// hosted runner gets nothing and no hosted note is printed. (A foreground CLI
+// run never places on a hosted runner: the run's world drops them unless a
+// `ci serve` coordinator runs the pipeline; test/sim offload_hosted_test.go
+// covers a hosted placement.)
+func TestCLIDirtyRunNodeWithHostedRegistered(t *testing.T) {
+	r, n, head := dirtyNodeRepo(t)
+	h := oflRegisterRunner(t, r.home, r.dir, "h1", true)
+	out, errOut, code := r.ci("--where", "n1", "--no-status")
+	if code != 0 {
+		t.Fatalf("exit %d\nstdout %s\nstderr %s", code, out, errOut)
+	}
+	s := n.wait(t)
+	if s.err != nil || s.head == "" || s.head == head || s.files["f.txt"] != "edited on the laptop\n" || s.files["new.txt"] != "untracked and not ignored\n" {
+		t.Fatalf("the node did not get the snapshot: head %q err %v files %q", s.head, s.err, s.files)
+	}
+	if strings.Contains(out+errOut, cirun.HostedDirtyNote) {
+		t.Errorf("a node placement printed the hosted note:\n%s%s", out, errOut)
+	}
+	select {
+	case got := <-h.seen:
+		t.Errorf("the hosted runner ran a job placed on the node: %+v", got)
+	default:
+	}
+	requireRecordedHEAD(t, r, head)
+}
+
+func TestCLIWhereNodeTrackedSecretRefused(t *testing.T) {
+	resetWhere(t)
+	r := newEvRepo(t)
+	r.commit("deploy.pem", "-----BEGIN NOT A REAL KEY-----\n")
+	oflRegisterNode(t, r.home, r.dir, "n1")
+	put(t, r.dir, "f.txt", "uncommitted\n")
+	before := oflRepoState2(t, r.dir)
+	out, errOut, code := r.ci("--where", "n1")
+	if code != 2 || !strings.Contains(errOut, "E807") || !strings.Contains(errOut, "deploy.pem") {
+		t.Fatalf("a tracked secret-shaped file must refuse the offload with E807 and exit 2: exit %d\nstdout %s\nstderr %s", code, out, errOut)
+	}
+	if strings.Contains(out+errOut, "NOT A REAL KEY") {
+		t.Error("the refusal printed the file's content")
+	}
+	if after := oflRepoState2(t, r.dir); after != before {
+		t.Errorf("the user's repository changed:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+}
+
+// oflRepoState2 is the git part of oflRepoState, for a repository without the probe files.
+func oflRepoState2(t *testing.T, dir string) string {
+	t.Helper()
+	return strings.Join([]string{git(t, dir, "status", "--porcelain=v2", "--ignored"), git(t, dir, "for-each-ref"),
+		git(t, dir, "ls-files", "-s")}, "\n--\n")
+}
+
+// TestOffloadOnlyForTargetsThatReachANode: a run with no --where, `local`,
+// `hosted`, or pool/auto/all with only hosted providers registered keeps the
+// HEAD path and never runs git for a snapshot.
+func TestOffloadOnlyForTargetsThatReachANode(t *testing.T) {
+	resetWhere(t)
+	was := offloadCapture
+	t.Cleanup(func() { offloadCapture = was })
+	offloadCapture = func(context.Context, ...string) (string, int, error) {
+		t.Fatal("a snapshot was attempted for a run no node can take")
+		return "", 1, nil
+	}
+	ctx := context.Background()
+	withKnown(t, where.Known{Providers: []string{"github"}}, "")
+	for _, kind := range []string{"", where.KindLocal, where.KindHosted, where.KindPool, where.KindAuto, where.KindAll} {
+		whereChosen = where.Target{Kind: kind}
+		if s, err := buildOffload(ctx, t.TempDir()); s != nil || err != nil {
+			t.Errorf("kind %q, providers only: snapshot %v err %v, want the HEAD path", kind, s, err)
+		}
+	}
+	withKnown(t, where.Known{Nodes: []string{"n1"}, Providers: []string{"github"}}, "")
+	for _, kind := range []string{where.KindNode, where.KindPool, where.KindAuto, where.KindAll} {
+		if !offloadWanted(ctx, kind) {
+			t.Errorf("kind %q may run on a node and must offload a dirty tree", kind)
+		}
+	}
+	for _, kind := range []string{"", where.KindLocal, where.KindHosted} {
+		if offloadWanted(ctx, kind) {
+			t.Errorf("kind %q never runs on a node", kind)
+		}
+	}
+}
+
+// TestOffloadCleanTreeKeepsHEAD: a node target on a clean tree (the hook also
+// runs when only the config lives outside the tree) creates no snapshot and no ref.
+func TestOffloadCleanTreeKeepsHEAD(t *testing.T) {
+	resetWhere(t)
+	r := newEvRepo(t)
+	whereChosen = where.Target{Kind: where.KindNode}
+	s, err := buildOffload(context.Background(), r.dir)
+	if s != nil || err != nil {
+		t.Fatalf("clean tree: snapshot %v err %v", s, err)
+	}
+	if refs := git(t, r.dir, "for-each-ref", "refs/nself-ci/"); refs != "" {
+		t.Errorf("a clean tree left a ref:\n%s", refs)
+	}
+}
diff --git a/free/ci/cmd/v15_where.go b/free/ci/cmd/v15_where.go
new file mode 100644
index 000000000..66bd958d9
--- /dev/null
+++ b/free/ci/cmd/v15_where.go
@@ -0,0 +1,177 @@
+package main
+
+// Purpose: the `--where local|<node>|<pool>|hosted|auto|all` flag of bare
+// `nself ci` and of `ci runs rerun` (P7-AUTO-06). One flag selects the target
+// through the run scope of P7-AUTO-29; internal/where maps the value, this file
+// reads what the operator registered and merges the result into the run's
+// policy values. It is never a second placement path: sched.Place and
+// dispatch.Admit decide, with these values in the revision scope.
+// Inputs: the flag text; the registered nodes, pools and providers (the store).
+// Outputs: RunOptions.PolicyRun gains the mapped keys; an unknown value or
+// `all` before a race hook exists is E797 and exit 2.
+// Constraints: V15 only; an explicit --prefer or --runner wins over the same
+// key from --where; with no flag the run is `auto` when a non-local node or a
+// provider is registered and today's local run otherwise, never a hidden
+// constant (auto writes no value: the operator's sched.preset stands).
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	cirun "github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/where"
+)
+
+// whereValue is the --where text of the current invocation; tests reset it.
+var whereValue string
+
+// whereKnown reads what the operator registered; a seam for tests.
+var whereKnown = productionWhereKnown
+
+// whereChosen is the target the last invocation resolved, for the placement report.
+var whereChosen where.Target
+
+const whereHelp = "run target: local, a node id, a pool id, hosted, auto or all (default: auto when a node or provider is registered, else local)"
+
+func init() {
+	bareFlags.Func("where", whereHelp, func(v string) error {
+		if v == "" {
+			return &where.Error{Message: "--where needs a value"}
+		}
+		whereValue = v
+		return nil
+	})
+	RegisterOptionsHook(whereOptions)
+}
+
+func whereOptions(o *RunOptions) error {
+	v := whereValue
+	whereChosen = where.Target{}
+	k := whereKnown(context.Background(), !o.Record)
+	if v == "" {
+		if !k.HasRemote() {
+			return nil
+		}
+		v = "auto"
+	}
+	return applyWhere(o, v, k)
+}
+
+// applyWhere maps v and merges the values under any value the flags already set.
+func applyWhere(o *RunOptions, v string, k where.Known) error {
+	t, err := where.Values(v, k, where.Opts{Dev: !o.Record, RaceReady: cirun.RaceRegistered()})
+	if err != nil {
+		return err
+	}
+	whereChosen = t
+	if len(t.Values) == 0 {
+		return nil
+	}
+	merged := map[string]json.RawMessage{}
+	for key, raw := range t.Values {
+		merged[key] = raw
+	}
+	for key, raw := range o.PolicyRun {
+		merged[key] = raw
+	}
+	o.PolicyRun = merged
+	return nil
+}
+
+// productionWhereKnown lists the registered nodes, pools and hosted providers.
+// A store that cannot be read gives nothing registered.
+func productionWhereKnown(ctx context.Context, dev bool) where.Known {
+	w, err := loadPoolsWorld(ctx, "")
+	if err != nil {
+		return where.Known{}
+	}
+	return knownFromWorld(w, dev)
+}
+
+// knownFromWorld derives where.Known from the pools world: the effective set
+// is the pools.allow term (and pools.dev for a dev run) the resolver applies.
+func knownFromWorld(w poolsWorld, dev bool) where.Known {
+	allow, devPools, _ := pools.FromPolicy(w.Policy)
+	res := pools.Resolve(pools.Input{Runners: w.Runners, Allow: allow, Dev: dev, DevPools: devPools})
+	var k where.Known
+	seen := map[string]bool{}
+	for _, r := range w.Runners {
+		switch r.Source {
+		case pools.SourceRegistry, pools.SourceCoordinator:
+			k.Nodes = append(k.Nodes, r.ID)
+			if d := res.Excluded[r.ID]; len(d) > 0 {
+				if k.Excluded == nil {
+					k.Excluded = map[string]string{}
+				}
+				k.Excluded[r.ID] = d[0].Detail
+			}
+		case pools.SourceProvider:
+			k.Providers = append(k.Providers, r.ID)
+		}
+		for _, id := range pools.FromAssigned(r.Assigned) {
+			if !seen[id] {
+				seen[id] = true
+				k.Pools = append(k.Pools, id)
+			}
+		}
+	}
+	if allow.Set {
+		k.Effective = allow.IDs
+	}
+	return k
+}
+
+// whereFlagSet adds --where to a flag set that does not share bareFlags.
+func whereFlagSet(fs *flag.FlagSet, dst *string) {
+	fs.StringVar(dst, "where", "", whereHelp)
+}
+
+// jsonPlacement is data.placement of the bare run's --json envelope
+// (contract:ci.placement-plan); nil when none could be computed.
+var jsonPlacement any
+
+// attachPlacement computes the placement the run's target gives, best effort:
+// a plan or store that cannot be read leaves data.placement out, and the run
+// itself is never failed by it. It reads the same plan, world and policy the
+// run uses; it creates no lease and no record.
+func attachPlacement(ctx context.Context, o RunOptions) {
+	jsonPlacement = nil
+	// Only when --where is given: ci.evidence/v1 allows no extra member, so a plain --json stays one evidence document.
+	if whereValue == "" || !o.JSON || o.Stream || len(o.Adhoc) > 0 {
+		return
+	}
+	pd, err := buildPlanned(ctx, planSpec{bare.repo, bare.cfg, bare.base, o.Pipeline, o.Trigger})
+	if err != nil {
+		return
+	}
+	// placementDoc reads the run's policy values from the parsed flags
+	// (schedRevisionValues), the same values schedOptions put in o.PolicyRun.
+	doc, err := placementDoc(ctx, pd)
+	if err == nil {
+		jsonPlacement = doc
+	}
+}
+
+// withPlacement returns doc with a "placement" member added; doc unchanged
+// when there is no placement.
+func withPlacement(doc, placement any) any {
+	if placement == nil {
+		return doc
+	}
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		return doc
+	}
+	m := map[string]json.RawMessage{}
+	if json.Unmarshal(raw, &m) != nil {
+		return doc
+	}
+	pl, err := json.Marshal(placement)
+	if err != nil {
+		return doc
+	}
+	m["placement"] = pl
+	return m
+}
diff --git a/free/ci/cmd/v15_where_test.go b/free/ci/cmd/v15_where_test.go
new file mode 100644
index 000000000..df81825d4
--- /dev/null
+++ b/free/ci/cmd/v15_where_test.go
@@ -0,0 +1,90 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/where"
+)
+
+func withKnown(t *testing.T, k where.Known, val string) {
+	t.Helper()
+	oldK, oldV := whereKnown, whereValue
+	whereKnown = func(context.Context, bool) where.Known { return k }
+	whereValue = val
+	t.Cleanup(func() { whereKnown, whereValue = oldK, oldV })
+}
+
+func TestBareRunDefaultsToAuto(t *testing.T) {
+	// nothing registered: today's local behaviour, nothing chosen, no values
+	withKnown(t, where.Known{}, "")
+	var o RunOptions
+	if err := whereOptions(&o); err != nil || whereChosen.Kind != "" || o.PolicyRun != nil {
+		t.Fatalf("no nodes: %+v %v %v", whereChosen, o.PolicyRun, err)
+	}
+	// a registered node: auto, and the operator's sched.preset stands (no value written)
+	withKnown(t, where.Known{Nodes: []string{"ms5"}}, "")
+	o = RunOptions{}
+	if err := whereOptions(&o); err != nil || whereChosen.Kind != where.KindAuto || len(o.PolicyRun) != 0 {
+		t.Fatalf("one node: %+v %v %v", whereChosen, o.PolicyRun, err)
+	}
+	// a provider alone also counts
+	withKnown(t, where.Known{Providers: []string{"github"}}, "")
+	o = RunOptions{}
+	if err := whereOptions(&o); err != nil || whereChosen.Kind != where.KindAuto {
+		t.Fatalf("one provider: %+v %v", whereChosen, err)
+	}
+}
+
+func TestWhereFlagMergesUnderExplicitFlags(t *testing.T) {
+	withKnown(t, where.Known{Nodes: []string{"ms5", "lan1"}}, "ms5")
+	runner, _ := json.Marshal("lan1")
+	o := RunOptions{PolicyRun: map[string]json.RawMessage{"sched.overrides.runner": runner}}
+	if err := whereOptions(&o); err != nil {
+		t.Fatal(err)
+	}
+	if got := string(o.PolicyRun["sched.overrides.runner"]); got != `"lan1"` {
+		t.Fatalf("an explicit --runner must win, got %s", got)
+	}
+	withKnown(t, where.Known{Nodes: []string{"ms5"}}, "ms5")
+	o = RunOptions{}
+	if err := whereOptions(&o); err != nil || string(o.PolicyRun["sched.overrides.runner"]) != `"ms5"` {
+		t.Fatalf("--where ms5: %v %v", o.PolicyRun, err)
+	}
+}
+
+func TestWhereUnknownValueIsE797(t *testing.T) {
+	withKnown(t, where.Known{}, "mars")
+	var o RunOptions
+	err := whereOptions(&o)
+	if err == nil || !strings.HasPrefix(err.Error(), "E797") {
+		t.Fatalf("got %v", err)
+	}
+	if exitForError(err) != 2 {
+		t.Error("E797 must exit 2")
+	}
+	withKnown(t, where.Known{}, "all")
+	if err = whereOptions(&o); err == nil || !strings.Contains(err.Error(), "race not available") {
+		t.Fatalf("all: %v", err)
+	}
+}
+
+func TestWithPlacementAddsDataPlacement(t *testing.T) {
+	type doc struct {
+		Schema string `json:"schema"`
+	}
+	if got := withPlacement(doc{"ev"}, nil); got != (doc{"ev"}) {
+		t.Fatalf("no placement must leave the document alone: %v", got)
+	}
+	got := withPlacement(doc{"ev"}, map[string]any{"tier": "owned", "bias": "balanced"})
+	raw, _ := json.Marshal(got)
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &m); err != nil || string(m["schema"]) != `"ev"` {
+		t.Fatalf("evidence fields lost: %s %v", raw, err)
+	}
+	if !strings.Contains(string(m["placement"]), `"tier":"owned"`) || !strings.Contains(string(m["placement"]), `"bias"`) {
+		t.Fatalf("placement missing: %s", raw)
+	}
+}
diff --git a/free/ci/internal/agent/session/control.go b/free/ci/internal/agent/session/control.go
index f5fd0594f..5a8460198 100644
--- a/free/ci/internal/agent/session/control.go
+++ b/free/ci/internal/agent/session/control.go
@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
 )
 
 func (s *Session) onMessage(m protocol.Message) (done bool, err error) {
@@ -24,9 +25,12 @@ func (s *Session) onMessage(m protocol.Message) (done bool, err error) {
 		s.onOffset(m, *b)
 	case *protocol.Upgrade:
 		s.onUpgrade(*b)
+	case *protocol.Digest:
+		s.onInbound(m, transport.BlobFrame{Digest: b})
+	case *protocol.Chunk:
+		s.onInbound(m, transport.BlobFrame{Chunk: b})
 	}
-	// heartbeat, ack, chunk, digest, resume: carried by later
-	// tickets (P7-CACHE-19 cache restore); the session ignores them.
+	// heartbeat, ack, resume: the session ignores them.
 	return false, nil
 }
 
diff --git a/free/ci/internal/agent/session/inbound.go b/free/ci/internal/agent/session/inbound.go
new file mode 100644
index 000000000..355e164c6
--- /dev/null
+++ b/free/ci/internal/agent/session/inbound.go
@@ -0,0 +1,80 @@
+package session
+
+// Purpose: route the coordinator's digest and chunk frames to the job hook that
+// restores a cache from them (P7-CACHE-21, Epic CACHE D7): the reverse of an
+// upload. The hook finds the lease's feed on its context (FeedFrom).
+// Inputs:  `digest` and `chunk` frames fenced to a running lease and its epoch.
+// Outputs: a bounded channel per lease, read through transport.BlobFeed.
+// Constraints: only a lease whose plan restores blobs, on a carrier that sends
+// coordinator frames (RestoreCarrier), gets a feed; any other frame is dropped.
+// The Run goroutine blocks on a full channel only while the hook still reads it
+// (backpressure on the carrier, ended by Close, the lease context or shutdown);
+// a frame for an unknown lease or another epoch is ignored.
+
+import (
+	"context"
+	"sync"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// inboundBuffer is how many unread frames a lease keeps (32 chunks is under 24 MiB of base64).
+const inboundBuffer = 32
+
+// RestoreCarrier is implemented by a Carrier that delivers coordinator digest and
+// chunk frames to the session (carrier A). A carrier without it gets no feed.
+type RestoreCarrier interface{ BlobRestore() bool }
+
+// BlobRestore says the stream carrier delivers every coordinator frame.
+func (*streamCarrier) BlobRestore() bool { return true }
+
+type feedKey struct{}
+
+// FeedFrom returns the reverse blob feed of the lease a Before hook runs for.
+func FeedFrom(ctx context.Context) (transport.BlobFeed, bool) {
+	f, ok := ctx.Value(feedKey{}).(*feed)
+	if !ok {
+		return nil, false
+	}
+	return f, true
+}
+
+type feed struct {
+	s      *Session
+	al     *activeLease
+	frames chan transport.BlobFrame
+	closed chan struct{}
+	once   sync.Once
+}
+
+func (s *Session) newFeed(al *activeLease) *feed {
+	rc, ok := s.cfg.Carrier.(RestoreCarrier)
+	if !ok || !rc.BlobRestore() || al.lease.Cache == nil || len(al.lease.Cache.Restore) == 0 {
+		return nil
+	}
+	return &feed{s: s, al: al, frames: make(chan transport.BlobFrame, inboundBuffer), closed: make(chan struct{})}
+}
+
+func (f *feed) Frames() <-chan transport.BlobFrame { return f.frames }
+func (f *feed) Offset(o protocol.Offset) error     { return f.s.send("offset", o, f.al) }
+func (f *feed) Close()                             { f.once.Do(func() { close(f.closed) }) }
+
+// onInbound hands a digest or chunk frame to the lease's feed.
+func (s *Session) onInbound(m protocol.Message, fr transport.BlobFrame) {
+	l, ok := s.active[m.LeaseID]
+	if !ok || m.Epoch == nil || *m.Epoch != l.lease.Epoch || l.feed == nil {
+		return
+	}
+	select {
+	case <-l.feed.closed:
+		return
+	default:
+	}
+	select {
+	case l.feed.frames <- fr:
+	case <-l.feed.closed:
+	case <-l.ctxDone:
+	case <-s.closing:
+	}
+}
diff --git a/free/ci/internal/agent/session/inbound_test.go b/free/ci/internal/agent/session/inbound_test.go
new file mode 100644
index 000000000..035632248
--- /dev/null
+++ b/free/ci/internal/agent/session/inbound_test.go
@@ -0,0 +1,100 @@
+package session
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+// restoreCar is a fake carrier that, like carrier A, delivers coordinator blob frames.
+type restoreCar struct{ *fakeCarrier }
+
+func (c restoreCar) fake() *fakeCarrier { return c.fakeCarrier }
+func (restoreCar) BlobRestore() bool    { return true }
+
+func restoreLease(id string, epoch uint64) protocol.Lease {
+	l := testLease(id, epoch)
+	l.Cache = &protocol.LeaseCache{Namespace: "ns", Access: "ro", Restore: []protocol.CacheRestore{{Spec: "go", Key: "k", Dir: "go"}}}
+	return l
+}
+
+// feedHook records what its Before hook sees of the reverse blob path.
+type feedHook struct {
+	got   chan []protocol.Digest
+	noOne chan bool
+}
+
+func newFeedHook() (*feedHook, JobHook) {
+	f := &feedHook{got: make(chan []protocol.Digest, 1), noOne: make(chan bool, 1)}
+	return f, JobHook{Name: "feed", Before: func(ctx context.Context, l protocol.Lease, _ JobRoot) (JobSetup, error) {
+		feed, ok := FeedFrom(ctx)
+		if !ok {
+			f.noOne <- true
+			return JobSetup{}, nil
+		}
+		defer feed.Close()
+		var seen []protocol.Digest
+		for len(seen) < 2 {
+			select {
+			case fr := <-feed.Frames():
+				if fr.Digest != nil {
+					seen = append(seen, *fr.Digest)
+					_ = feed.Offset(protocol.Offset{Stream: fr.Digest.Stream, SHA256: fr.Digest.SHA256, Offset: 0})
+				}
+			case <-time.After(5 * time.Second):
+				seen = append(seen, protocol.Digest{SHA256: "timeout"})
+			}
+		}
+		f.got <- seen
+		return JobSetup{}, nil
+	}}
+}
+
+func TestInboundBlobFramesReachTheHookFenced(t *testing.T) {
+	f, hook := newFeedHook()
+	car := restoreCar{newFakeCarrier()}
+	r := startRigWith(t, t.TempDir(), car, okRunner(`{}`), func(c *Config) { c.Hooks = []JobHook{hook} })
+	r.handshake()
+	r.lease(restoreLease("l1", 5))
+	dig := func(sha string) protocol.Digest { return protocol.Digest{Stream: "cache", SHA256: sha, Size: 3} }
+	// none of these may reach the hook: another epoch, another lease
+	r.car.pushFenced("digest", dig("stale"), 4, "l1")
+	r.car.pushFenced("digest", dig("other"), 5, "l2")
+	r.car.pushFenced("digest", dig("one"), 5, "l1")
+	r.car.pushFenced("chunk", protocol.Chunk{Stream: "cache", Offset: 0, Data: "AAAA", Digest: "one", Final: true}, 5, "l1")
+	r.car.pushFenced("digest", dig("two"), 5, "l1")
+	select {
+	case seen := <-f.got:
+		if len(seen) != 2 || seen[0].SHA256 != "one" || seen[1].SHA256 != "two" {
+			t.Fatalf("hook saw %+v", seen)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("hook never saw the frames")
+	}
+	off := r.car.next(t, "offset").Body.(protocol.Offset)
+	if off.SHA256 != "one" {
+		t.Fatalf("offset answer %+v", off)
+	}
+	if m := r.car.next(t, "offset"); m.LeaseID != "l1" || m.Epoch == nil || *m.Epoch != 5 {
+		t.Fatalf("offset not fenced to the lease: %+v", m)
+	}
+}
+
+func TestInboundNoFeedWithoutCarrierSupportOrPlan(t *testing.T) {
+	f, hook := newFeedHook()
+	r := startRig(t, okRunner(`{}`), func(c *Config) { c.Hooks = []JobHook{hook} }) // a carrier that cannot deliver blobs
+	r.handshake()
+	r.lease(restoreLease("l1", 1))
+	if !<-f.noOne {
+		t.Fatal("a feed was offered on a carrier without blob delivery")
+	}
+	f2, hook2 := newFeedHook()
+	r2 := startRigWith(t, t.TempDir(), restoreCar{newFakeCarrier()}, okRunner(`{}`), func(c *Config) { c.Hooks = []JobHook{hook2} })
+	r2.handshake()
+	r2.lease(testLease("l2", 1)) // no cache plan
+	if !<-f2.noOne {
+		t.Fatal("a feed was offered to a lease without restore blobs")
+	}
+}
diff --git a/free/ci/internal/agent/session/lease.go b/free/ci/internal/agent/session/lease.go
index 3588addc9..fd598fcdc 100644
--- a/free/ci/internal/agent/session/lease.go
+++ b/free/ci/internal/agent/session/lease.go
@@ -37,6 +37,8 @@ type activeLease struct {
 	lines     atomic.Uint64 // safe
 	lw        *lineWriter
 	offsets   chan protocol.Offset // safe: the coordinator's offset answers (offsets.go)
+	feed      *feed                // set before the job goroutine starts: the reverse blob feed (inbound.go)
+	ctxDone   <-chan struct{}      // the lease context's Done channel
 }
 
 func (l *activeLease) cancel() { l.cancelled.Store(true); l.cancelCtx() }
@@ -98,6 +100,8 @@ func (s *Session) onLease(m protocol.Message, l protocol.Lease) {
 	// cancel, a drain deadline or the agent fence (P7-NODE-09).
 	ctx, cancel := context.WithCancel(s.runCtx)
 	al := &activeLease{lease: l, cancelCtx: cancel, offsets: make(chan protocol.Offset, offsetBuffer), secWake: make(chan struct{}, 1), secVals: map[string]string{}, expires: exp, secSeen: map[string]bool{}}
+	al.ctxDone = ctx.Done()
+	al.feed = s.newFeed(al)
 	if l.RunnerCredential != nil {
 		al.addMask(l.RunnerCredential.Value)
 	}
@@ -105,6 +109,9 @@ func (s *Session) onLease(m protocol.Message, l protocol.Lease) {
 	s.active[l.LeaseID] = al
 	s.wg.Add(1)
 	go s.runLease(ctx, al, slot)
+	if al.feed != nil {
+		s.beat(nil) // tells a pull coordinator the lease is running: it starts the restore push
+	}
 }
 
 // maxSeen bounds the epoch memory of a long-lived session.
@@ -181,11 +188,15 @@ func (s *Session) runLease(ctx context.Context, al *activeLease, slot *slots.Slo
 
 	var setup JobSetup
 	skip := ""
+	beforeCtx := ctx
+	if al.feed != nil {
+		beforeCtx = context.WithValue(ctx, feedKey{}, al.feed)
+	}
 	for _, h := range s.jobHooks {
 		if h.Before == nil {
 			continue
 		}
-		got, err := h.Before(ctx, l, root)
+		got, err := h.Before(beforeCtx, l, root)
 		if err != nil && ctx.Err() != nil {
 			skip = "cancelled" // the hook stopped because the lease was cancelled
 			break
@@ -196,6 +207,9 @@ func (s *Session) runLease(ctx context.Context, al *activeLease, slot *slots.Slo
 		}
 		mergeSetup(&setup, got)
 	}
+	if al.feed != nil {
+		al.feed.Close() // the hooks are done: later frames are dropped
+	}
 	waitCtx, stopWait := context.WithTimeout(ctx, max(al.expires.Sub(s.cfg.Clock.Now()), 0))
 	for waitCtx.Err() == nil {
 		al.secMu.Lock()
diff --git a/free/ci/internal/artifacts/records/collect.go b/free/ci/internal/artifacts/records/collect.go
index 69c837af9..6ad3b18a5 100644
--- a/free/ci/internal/artifacts/records/collect.go
+++ b/free/ci/internal/artifacts/records/collect.go
@@ -9,10 +9,13 @@ package records
 // entry passes authz.ArtifactPath through an Extractor; a declaration that
 // selects nothing, a file over the cap, a registered secret, a low disk and a
 // duplicate record name each fail the whole collection (E712 or E683) before
-// the attempt can pass; blobs are written only after the scan of their bytes.
+// the attempt can pass; blobs are written only after the scan of their bytes;
+// with Audit set, each refusal leaves an artifact.collect.refused row.
 
 import (
 	"context"
+	"errors"
+	"fmt"
 	"io"
 	"math"
 	"os"
@@ -55,6 +58,25 @@ type Collector struct {
 	Reserve func(total int64) error
 	// MaxRecords bounds the files one attempt may collect (0 = DefaultMaxRecords).
 	MaxRecords int
+	// Audit, when set, records every refused collection (artifact.collect.refused
+	// with its reason key; TM-14, TM-16). Target names the attempt or lease.
+	Audit  AuditSink
+	Target string
+}
+
+// AuditSink writes one audit row (store.AppendAudit).
+type AuditSink func(ctx context.Context, actor, action, target, detail string) error
+
+// audited records a refusal of the collection and returns it; a lost row is joined to it.
+func (c Collector) audited(ctx context.Context, err error) error {
+	var e *Error
+	if err == nil || c.Audit == nil || !errors.As(err, &e) {
+		return err
+	}
+	if aerr := c.Audit(ctx, "artifacts", "artifact.collect.refused", c.Target, "reason="+e.Reason); aerr != nil {
+		return errors.Join(err, fmt.Errorf("artifact collect audit: %w", aerr))
+	}
+	return err
 }
 
 // DefaultMaxRecords is the most files one attempt may collect across all its declarations.
@@ -71,11 +93,11 @@ type planned struct {
 // (opened here; callers that hold a pinned root use CollectRoot).
 func (c Collector) Collect(ctx context.Context, project, base string, decls []Decl) ([]Staged, error) {
 	if info, err := os.Lstat(base); err != nil || !info.IsDir() {
-		return nil, failf(ReasonUnreadable, "job workdir %q is missing, not a directory or a symlink", base)
+		return nil, c.audited(ctx, failf(ReasonUnreadable, "job workdir %q is missing, not a directory or a symlink", base))
 	}
 	root, err := os.OpenRoot(base)
 	if err != nil {
-		return nil, failf(ReasonUnreadable, "job workdir: %v", err)
+		return nil, c.audited(ctx, failf(ReasonUnreadable, "job workdir: %v", err))
 	}
 	defer func() { _ = root.Close() }()
 	return c.CollectRoot(ctx, project, root, decls)
@@ -87,6 +109,11 @@ func (c Collector) Collect(ctx context.Context, project, base string, decls []De
 // refusal leaves nothing behind; the bytes actually streamed are held to the
 // same budget.
 func (c Collector) CollectRoot(ctx context.Context, project string, root *os.Root, decls []Decl) ([]Staged, error) {
+	out, err := c.collect(ctx, project, root, decls)
+	return out, c.audited(ctx, err)
+}
+
+func (c Collector) collect(ctx context.Context, project string, root *os.Root, decls []Decl) ([]Staged, error) {
 	plan, err := c.plan(ctx, root, decls)
 	if err != nil {
 		return nil, err
diff --git a/free/ci/internal/artifacts/records/read.go b/free/ci/internal/artifacts/records/read.go
index 191f9c8da..e3c35551e 100644
--- a/free/ci/internal/artifacts/records/read.go
+++ b/free/ci/internal/artifacts/records/read.go
@@ -8,13 +8,15 @@ package records
 // record whose blob is gone is reported missing (and remembered) and Get
 // refuses it (E712 missing_blob); Get writes only inside a directory that
 // authz.OpenArtifactGetDest pinned, creates every file exclusively and
-// re-verifies size and digest of what it wrote.
+// re-verifies size and digest of what it wrote; with Audit set, every refused
+// Get but "not found" leaves an artifact.get.refused row.
 
 import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -28,6 +30,9 @@ import (
 type Reader struct {
 	Ledger Ledger
 	Blobs  Blobs
+	// Audit, when set, records every refused Get (artifact.get.refused with the
+	// reason key: a destination, path or digest refusal; TM-14, TM-15).
+	Audit AuditSink
 }
 
 // List returns the committed records the viewer may see, newest first.
@@ -81,6 +86,26 @@ func (r Reader) checkBlob(ctx context.Context, rec Record) Record {
 
 // Get writes the record's bytes under dest/<name> and returns the path.
 func (r Reader) Get(ctx context.Context, v authz.Viewer, id, dest, cwd string) (string, Record, error) {
+	p, rec, err := r.get(ctx, v, id, dest, cwd)
+	if err == nil || r.Audit == nil || errors.Is(err, ErrNotFound) {
+		return p, rec, err
+	}
+	reason := ReasonUnreadable
+	var pe *authz.PathError
+	var re *Error
+	switch {
+	case errors.As(err, &pe):
+		reason = string(pe.Reason)
+	case errors.As(err, &re):
+		reason = re.Reason
+	}
+	if aerr := r.Audit(ctx, "artifacts", "artifact.get.refused", id, "reason="+reason); aerr != nil {
+		err = errors.Join(err, fmt.Errorf("artifact get audit: %w", aerr))
+	}
+	return p, rec, err
+}
+
+func (r Reader) get(ctx context.Context, v authz.Viewer, id, dest, cwd string) (string, Record, error) {
 	rec, err := r.visible(ctx, v, id)
 	if err != nil {
 		return "", Record{}, err
diff --git a/free/ci/internal/attest/revoke.go b/free/ci/internal/attest/revoke.go
index 9d8572805..96fa13a84 100644
--- a/free/ci/internal/attest/revoke.go
+++ b/free/ci/internal/attest/revoke.go
@@ -2,8 +2,9 @@ package attest
 
 // Purpose: Revoke(node) (Epic D13, X15): the node's evidence keys become untrusted, the evidence they
 // signed is quarantined, and the caller gets the re-evaluation set (gates, posted statuses, promoted
-// releases). The statuses are re-posted as errors with reason node.revoked (P7-HOST-02's Repost), and
-// each promoted release gets one audit event, so a revoked node's success does not stand.
+// releases). The statuses are re-posted as errors with reason node.revoked (P7-HOST-02's Repost), each
+// quarantined run gets an evidence.quarantined event (reason key_revoked) and each promoted release one
+// release.quarantine event, so a revoked node's success does not stand.
 // Inputs:  the node id, the actor, a RevokeLedger, an AuditSink and a Reposter (all injected: this package
 //          cannot import store, audit or report).
 // Outputs: Affected; errors from the audit and repost steps are joined and returned with it.
@@ -33,7 +34,9 @@ type ReleaseRef struct{ RunID, Project, Revision, ManifestSHA256 string }
 // Affected is what a revocation re-evaluates.
 type Affected struct {
 	// Keys are the evidence key ids revoked (ci-node-<16 hex>): those the node pins and every one it used.
-	Keys     []string
+	Keys []string
+	// Runs are the runs whose evidence the revocation quarantined.
+	Runs     []string
 	Gates    []GateRef
 	Statuses []StatusKey
 	Releases []ReleaseRef
@@ -74,6 +77,9 @@ func (r Revoker) Revoke(ctx context.Context, nodeID, actor string) (Affected, er
 	if r.Audit != nil {
 		errs = append(errs, r.Audit(ctx, actor, "evidence.revoke", nodeID,
 			fmt.Sprintf("keys=%d gates=%d statuses=%d releases=%d", len(out.Keys), len(out.Gates), len(out.Statuses), len(out.Releases))))
+		for _, run := range out.Runs { // TM-20: each quarantined run's evidence is refused from now on
+			errs = append(errs, r.Audit(ctx, actor, "evidence.quarantined", run, "reason="+string(RemoteKeyRevoked)+" node="+nodeID))
+		}
 		for _, rel := range out.Releases {
 			errs = append(errs, r.Audit(ctx, actor, "release.quarantine", rel.RunID,
 				fmt.Sprintf("node=%s project=%s revision=%s manifest=%s", nodeID, rel.Project, rel.Revision, rel.ManifestSHA256)))
diff --git a/free/ci/internal/blob/transfer/receiver.go b/free/ci/internal/blob/transfer/receiver.go
index a7d95dfec..c89162fa1 100644
--- a/free/ci/internal/blob/transfer/receiver.go
+++ b/free/ci/internal/blob/transfer/receiver.go
@@ -55,8 +55,9 @@ type Receiver struct {
 	// Live returns nil while the lease epoch is the current one. An error wrapping ErrStale is a
 	// stale epoch (refused, audited); any other error (a store fault) is a transient failure.
 	Live func(ctx context.Context) error
-	// Refused is told once per refused blob (by digest) when the epoch is stale, so the caller can
-	// write its audit row. It must not block.
+	// Refused is told once per refused blob and reason (by digest): a stale epoch, and a blob whose
+	// bytes end short or fail their digest at publish (TM-13, TM-15), so the caller can write its
+	// audit row. It must not block.
 	Refused func(ctx context.Context, sha string, err *Error)
 
 	mu   sync.Mutex
@@ -83,13 +84,18 @@ func (r *Receiver) epoch(ctx context.Context, sha string) error {
 	if !errors.Is(err, ErrStale) {
 		return Failf(ReasonInterrupted, "the lease check failed: %v", err)
 	}
-	e := Failf(ReasonStaleEpoch, "the lease epoch is no longer current; blob %s is refused", short(sha))
+	return r.tell(ctx, sha, Failf(ReasonStaleEpoch, "the lease epoch is no longer current; blob %s is refused", short(sha)))
+}
+
+// tell reports e to Refused once per blob and reason, and returns it.
+func (r *Receiver) tell(ctx context.Context, sha string, e *Error) *Error {
 	r.mu.Lock()
-	first := !r.told[sha]
+	k := sha + "/" + e.Reason
+	first := !r.told[k]
 	if r.told == nil {
 		r.told = map[string]bool{}
 	}
-	r.told[sha] = true
+	r.told[k] = true
 	r.mu.Unlock()
 	if first && r.Refused != nil {
 		r.Refused(ctx, sha, e)
diff --git a/free/ci/internal/blob/transfer/writer.go b/free/ci/internal/blob/transfer/writer.go
index df87013a3..9bd84aef7 100644
--- a/free/ci/internal/blob/transfer/writer.go
+++ b/free/ci/internal/blob/transfer/writer.go
@@ -69,7 +69,7 @@ func (w *Writer) publish() error {
 		return Failf(ReasonProtocol, "blob %s was aborted", short(w.h.SHA256))
 	}
 	if w.offset != w.h.Size {
-		return Failf(ReasonInterrupted, "blob %s holds %d of %d B", short(w.h.SHA256), w.offset, w.h.Size)
+		return w.r.tell(context.Background(), w.h.SHA256, Failf(ReasonInterrupted, "blob %s holds %d of %d B", short(w.h.SHA256), w.offset, w.h.Size))
 	}
 	if err := w.r.epoch(context.Background(), w.h.SHA256); err != nil {
 		return err
@@ -77,9 +77,9 @@ func (w *Writer) publish() error {
 	if err := w.p.Finalize(); err != nil {
 		if errors.Is(err, cas.ErrPartialConflict) {
 			w.offset = 0 // the partial is gone: a retry starts clean
-			return Failf(ReasonDigest, "blob %s does not match its digest; nothing was published", short(w.h.SHA256))
+			return w.r.tell(context.Background(), w.h.SHA256, Failf(ReasonDigest, "blob %s does not match its digest; nothing was published", short(w.h.SHA256)))
 		}
-		return Failf(ReasonInterrupted, "blob %s could not be published: %v", short(w.h.SHA256), err)
+		return w.r.tell(context.Background(), w.h.SHA256, Failf(ReasonInterrupted, "blob %s could not be published: %v", short(w.h.SHA256), err))
 	}
 	w.done, w.published = true, true
 	return nil
diff --git a/free/ci/internal/cache/entries/codes_entries.go b/free/ci/internal/cache/entries/codes_entries.go
index c9eaa8d60..b779e1ab7 100644
--- a/free/ci/internal/cache/entries/codes_entries.go
+++ b/free/ci/internal/cache/entries/codes_entries.go
@@ -25,8 +25,12 @@ const (
 	ReasonSizeCap      = "size_cap"
 	ReasonDiskFloor    = "disk_floor"
 	ReasonPathOutside  = "path_outside"
+	// ReasonSecretMatch: a save the value scan refused, or a read-only snapshot
+	// whose writer received secrets (refused to every other reader, TM-12).
+	ReasonSecretMatch = "secret_match"
 	// ReasonBlobInvalid extends the Epic D20 list: a blob is missing, has the wrong
-	// size or was not freshly Put when its entry commits.
+	// size or was not freshly Put when its entry commits, or a restore found it
+	// missing, of the wrong size or failing its digest (TM-15).
 	ReasonBlobInvalid = "blob_invalid"
 )
 
@@ -34,13 +38,19 @@ const (
 type Refused struct {
 	Reason string
 	Err    error // the cause, when there is one (ErrBlobStale, os.ErrNotExist)
+	// Op names the refused operation in the message; empty means "write".
+	Op string
 }
 
 func (e *Refused) Error() string {
+	op := e.Op
+	if op == "" {
+		op = "write"
+	}
 	if e.Err != nil {
-		return CodeCacheRefused + " cache write refused: " + e.Reason + ": " + e.Err.Error()
+		return CodeCacheRefused + " cache " + op + " refused: " + e.Reason + ": " + e.Err.Error()
 	}
-	return CodeCacheRefused + " cache write refused: " + e.Reason
+	return CodeCacheRefused + " cache " + op + " refused: " + e.Reason
 }
 
 // Unwrap exposes the cause.
diff --git a/free/ci/internal/cache/entries/lookup.go b/free/ci/internal/cache/entries/lookup.go
index ec773f582..da2df0406 100644
--- a/free/ci/internal/cache/entries/lookup.go
+++ b/free/ci/internal/cache/entries/lookup.go
@@ -4,7 +4,8 @@ package entries
 // every blob through cas, and Verify over all entries.
 // Inputs: the namespace being read, its key and the authz access mode.
 // Outputs: the Manifest and a hit flag; every refusal is a miss, never a
-// fallback.
+// fallback. ResolveForRestore also names why an entry found under the key was
+// not served (secret_match, blob_invalid), so a restore can refuse it.
 // Constraints: no restore-key or prefix fallback, no other key, no other
 // namespace. The stored namespace is compared byte for byte (a mismatch is a
 // miss plus an audit row). ro-snapshot serves only authz.SnapshotEligible
@@ -67,7 +68,8 @@ func (s *Store) intactBy(m Manifest, rehash bool) (reason string, err error) {
 // every blob is intact. The caller must derive access from authz.CacheAccess for
 // the attempt's own namespace and ns; Lookup does not know the attempt.
 func (s *Store) Lookup(ctx context.Context, ns authz.Namespace, key string, access authz.Mode) (Manifest, bool, error) {
-	return s.lookup(ctx, ns, key, access, true)
+	m, ok, _, err := s.lookup(ctx, ns, key, access, true)
+	return m, ok, err
 }
 
 // LookupForRestore is Lookup for a caller that reads every blob through
@@ -76,34 +78,47 @@ func (s *Store) Lookup(ctx context.Context, ns authz.Namespace, key string, acce
 // hashes a 100 MB build cache once, not three times. A blob that fails the
 // digest is quarantined by that read, and the caller drops the entry.
 func (s *Store) LookupForRestore(ctx context.Context, ns authz.Namespace, key string, access authz.Mode) (Manifest, bool, error) {
+	m, ok, _, err := s.lookup(ctx, ns, key, access, false)
+	return m, ok, err
+}
+
+// ResolveForRestore is LookupForRestore for a restore that refuses, rather than
+// misses, an entry it found under the key and must not serve (TM-12, TM-15):
+// refused is ReasonSecretMatch for a snapshot whose writer received secrets and
+// ReasonBlobInvalid for a blob that is missing or has the wrong size (the entry
+// is dropped, as Lookup drops it). Any other unusable entry is a plain miss.
+func (s *Store) ResolveForRestore(ctx context.Context, ns authz.Namespace, key string, access authz.Mode) (m Manifest, hit bool, refused string, err error) {
 	return s.lookup(ctx, ns, key, access, false)
 }
 
-func (s *Store) lookup(ctx context.Context, ns authz.Namespace, key string, access authz.Mode, rehash bool) (Manifest, bool, error) {
+func (s *Store) lookup(ctx context.Context, ns authz.Namespace, key string, access authz.Mode, rehash bool) (Manifest, bool, string, error) {
 	if (access != authz.ModeRWOwn && access != authz.ModeROSnapshot) || !ns.Valid() || !hexKey.MatchString(key) {
-		return Manifest{}, false, nil
+		return Manifest{}, false, "", nil
 	}
 	list, err := s.be.CacheEntries(ctx, key)
 	if err != nil || len(list) == 0 {
-		return Manifest{}, false, err
+		return Manifest{}, false, "", err
 	}
 	i := slices.IndexFunc(list, func(m Manifest) bool { return bytes.Equal(m.Namespace, ns.Canonical()) })
 	if i < 0 { // the key exists, but only under other namespaces: a miss, never a fallback
-		return Manifest{}, false, s.be.CacheAuditOnce(ctx, "cache.lookup.namespace_mismatch", key, "")
+		return Manifest{}, false, "", s.be.CacheAuditOnce(ctx, "cache.lookup.namespace_mismatch", key, "")
 	}
 	m := list[i]
 	if access == authz.ModeROSnapshot && !s.snapshotOK(m) {
-		return Manifest{}, false, nil
+		if m.Writer.SecretsReceived { // a snapshot of a secret-bearing job is refused to others, never served
+			return Manifest{}, false, ReasonSecretMatch, nil
+		}
+		return Manifest{}, false, "", nil
 	}
 	reason, err := s.intactBy(m, rehash)
 	if err != nil || reason == "unstable" {
-		return Manifest{}, false, err
+		return Manifest{}, false, "", err
 	}
 	if reason != "" {
 		_, err = s.be.CacheDrop(ctx, m, reason)
-		return Manifest{}, false, err
+		return Manifest{}, false, ReasonBlobInvalid, err
 	}
-	return m, true, s.be.CacheTouch(ctx, m.Namespace, key)
+	return m, true, "", s.be.CacheTouch(ctx, m.Namespace, key)
 }
 
 // snapshotOK applies authz.SnapshotEligible to the facts stored with m.
diff --git a/free/ci/internal/cache/remote/coord.go b/free/ci/internal/cache/remote/coord.go
index 0e15e2fc5..8143a3da8 100644
--- a/free/ci/internal/cache/remote/coord.go
+++ b/free/ci/internal/cache/remote/coord.go
@@ -9,6 +9,7 @@ import (
 	"errors"
 	"fmt"
 	"sync"
+	"time"
 
 	"github.com/nself-org/plugins/free/ci/internal/authz"
 	"github.com/nself-org/plugins/free/ci/internal/blob/cas"
@@ -48,6 +49,8 @@ type Binding struct {
 	Fence, Ready             func(context.Context) error
 	// Unordered preserves the full ref grace for carriers without ordered delivery.
 	Unordered bool
+	// RestoreWait bounds each wait for the node's offset answer (default DefaultRestoreWait).
+	RestoreWait time.Duration
 }
 
 type Lease struct {
diff --git a/free/ci/internal/cache/remote/integration_agent_test.go b/free/ci/internal/cache/remote/integration_agent_test.go
index 7d7a80f0f..2a66235e8 100644
--- a/free/ci/internal/cache/remote/integration_agent_test.go
+++ b/free/ci/internal/cache/remote/integration_agent_test.go
@@ -68,6 +68,7 @@ func (r *rig) agentSide() *agentSide {
 		r.t.Fatal(err)
 	}
 	drv.SetCancel(srv.Cancel)
+	drv.SetPush(srv.Push)
 	done := make(chan error, 1)
 	go func() { done <- srv.Serve(ln) }()
 	r.t.Cleanup(func() {
@@ -113,7 +114,7 @@ func (a *agentSide) addNode(id string) (model.Capability, tls.Certificate) {
 }
 
 // runAgent delivers the rig's lease to a node over the agent pull carrier and returns the driver's result.
-func (r *rig) runAgent(n *node) error {
+func (r *rig) runAgent(n nodeSide) error {
 	r.t.Helper()
 	side := r.agentSide()
 	capab, cert := side.addNode("n-1")
diff --git a/free/ci/internal/cache/remote/integration_restore_test.go b/free/ci/internal/cache/remote/integration_restore_test.go
new file mode 100644
index 000000000..e4a2b9d84
--- /dev/null
+++ b/free/ci/internal/cache/remote/integration_restore_test.go
@@ -0,0 +1,235 @@
+//go:build integration
+
+package remote
+
+// Purpose: the cold restore of a node from the coordinator over a real carrier
+// (P7-CACHE-21): the real ssh driver pushes digest and chunk frames, a real agent
+// session routes them to the Before hook, which restores through NodeRestorer.
+// Carrier B (agent pull) pushes the same frames down the control stream and reads the
+// node's offsets from the upstream stream.
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"os"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/agent/session"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+// restoreNode is node B: it keeps its read-through copies between runs.
+type restoreNode struct {
+	t       *testing.T
+	copies  *ReadThrough
+	flip    func(*protocol.Chunk)
+	chunks  atomic.Int32
+	noFeed  atomic.Bool
+	atStart atomic.Bool // a verified copy was bound when the job started
+	data    []byte
+}
+
+func newRestoreNode(t *testing.T) *restoreNode {
+	t.Helper()
+	c, err := NewReadThrough(t.TempDir(), 64<<20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &restoreNode{t: t, copies: c}
+}
+
+type countingCarrier struct {
+	session.Carrier
+	n *restoreNode
+}
+
+func (c countingCarrier) Recv() (protocol.Message, error) {
+	m, err := c.Carrier.Recv()
+	if ch, ok := m.Body.(*protocol.Chunk); ok && err == nil && ch.Stream == StreamCache {
+		c.n.chunks.Add(1)
+		if c.n.flip != nil {
+			c.n.flip(ch)
+		}
+	}
+	return m, err
+}
+
+// carrierACounting keeps the carriers' restore capability (A and B).
+type carrierACounting struct{ countingCarrier }
+
+func (carrierACounting) BlobRestore() bool { return true }
+
+func (n *restoreNode) tap(c session.Carrier) session.Carrier {
+	return carrierACounting{countingCarrier{c, n}}
+}
+
+func (n *restoreNode) runner() session.Runner {
+	return session.RunnerFunc(func(ctx context.Context, jr session.JobRun) (session.JobResult, error) {
+		b := jr.Lease.Cache.Restore[0].Blobs[0]
+		if f, err := n.copies.Open(ctx, jr.Lease.Cache.Namespace, b.SHA256, b.Size, nil); err == nil {
+			_ = f.Close()
+			n.atStart.Store(true)
+		}
+		return session.JobResult{Outcome: session.Outcome{State: "passed"}, Evidence: []byte(`{"schema":"test","ok":true}`)}, nil
+	})
+}
+
+func (n *restoreNode) hooks() []session.JobHook {
+	return []session.JobHook{{Name: "cache", Before: func(ctx context.Context, l protocol.Lease, _ session.JobRoot) (session.JobSetup, error) {
+		feed, ok := session.FeedFrom(ctx)
+		if !ok {
+			n.noFeed.Store(true)
+			return session.JobSetup{}, nil
+		}
+		defer feed.Close()
+		var blobs []protocol.CacheBlob
+		for _, r := range l.Cache.Restore {
+			blobs = append(blobs, r.Blobs...)
+		}
+		(&NodeRestorer{Copies: n.copies, Feed: feed, Realm: l.Cache.Namespace, Wait: 10 * time.Second}).Fetch(ctx, blobs)
+		return session.JobSetup{}, nil
+	}}}
+}
+
+// planRestore stores data on the coordinator and plans it as the lease's restore.
+func (r *rig) planRestore(data []byte) protocol.CacheBlob {
+	r.t.Helper()
+	sha, size, err := r.blobs.Put(context.Background(), cacheRealm(r.lease.b.Plan.Namespace), bytes.NewReader(data))
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	b := protocol.CacheBlob{Path: "mod", SHA256: sha, Size: size}
+	r.lease.b.Plan.Restore = []protocol.CacheRestore{{Spec: "go", Key: strings.Repeat("a", 64), Dir: "go", Blobs: []protocol.CacheBlob{b}}}
+	r.lease.b.RestoreWait = 10 * time.Second
+	return b
+}
+
+func (n *restoreNode) assertCopy(r *rig, b protocol.CacheBlob) {
+	n.t.Helper()
+	f, err := n.copies.Open(context.Background(), r.lease.b.Plan.Namespace, b.SHA256, b.Size, nil)
+	if err != nil {
+		n.t.Fatalf("node has no verified copy: %v", err)
+	}
+	_ = f.Close()
+}
+
+func TestRemoteCacheRestoreSSH(t *testing.T) {
+	restoreHappy(t, func(r *rig, n *restoreNode) error { return r.runSSH(n) })
+}
+
+// TestRemoteCacheRestoreAgent is the same run over carrier B: the pushes ride the control stream.
+func TestRemoteCacheRestoreAgent(t *testing.T) {
+	restoreHappy(t, func(r *rig, n *restoreNode) error { return r.runAgent(n) })
+}
+
+func restoreHappy(t *testing.T, run func(*rig, *restoreNode) error) {
+	t.Helper()
+	data := carrierCacheArchive(t)
+	node := newRestoreNode(t)
+	r1 := newRig(t)
+	b := r1.planRestore(data)
+	if err := run(r1, node); err != nil {
+		t.Fatal(err)
+	}
+	if node.noFeed.Load() || !node.atStart.Load() {
+		t.Fatalf("node B did not hold a verified copy when the job started (noFeed=%v)", node.noFeed.Load())
+	}
+	if node.chunks.Load() < 2 {
+		t.Fatalf("cold restore moved %d chunk frames", node.chunks.Load())
+	}
+	node.assertCopy(r1, b)
+	rows, err := r1.st.CacheLocality(context.Background(), "n-1", r1.lease.b.Plan.Namespace, strings.Repeat("a", 64))
+	if err != nil || len(rows) != 1 {
+		t.Fatalf("locality=%+v err=%v", rows, err)
+	}
+	// The second run on node B, against a fresh coordinator state, uses its own copy.
+	before := node.chunks.Load()
+	node.atStart.Store(false)
+	r2 := newRig(t)
+	r2.planRestore(data)
+	if err = run(r2, node); err != nil {
+		t.Fatal(err)
+	}
+	if !node.atStart.Load() || node.chunks.Load() != before {
+		t.Fatalf("second run fetched again: %d chunk frames since the first", node.chunks.Load()-before)
+	}
+}
+
+func TestRemoteCacheRestoreCorrupt(t *testing.T) {
+	t.Run("ssh", func(t *testing.T) { restoreCorrupt(t, func(r *rig, n *restoreNode) error { return r.runSSH(n) }) })
+	t.Run("agent", func(t *testing.T) { restoreCorrupt(t, func(r *rig, n *restoreNode) error { return r.runAgent(n) }) })
+}
+
+func restoreCorrupt(t *testing.T, run func(*rig, *restoreNode) error) {
+	t.Helper()
+	data := carrierCacheArchive(t)
+	node := newRestoreNode(t)
+	r1 := newRig(t)
+	b := r1.planRestore(data)
+	if err := run(r1, node); err != nil {
+		t.Fatal(err)
+	}
+	// A copy that rots on the node is discarded and fetched again.
+	name, err := node.copies.name(r1.lease.b.Plan.Namespace, b.SHA256)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(name)
+	raw[11] ^= 0xff
+	if err = os.WriteFile(name, raw, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	before := node.chunks.Load()
+	node.atStart.Store(false)
+	r2 := newRig(t)
+	r2.planRestore(data)
+	if err = run(r2, node); err != nil {
+		t.Fatal(err)
+	}
+	if !node.atStart.Load() || node.chunks.Load() <= before {
+		t.Fatalf("corrupt copy was not refetched (chunks %d -> %d)", before, node.chunks.Load())
+	}
+	// A byte flipped in transit fails the re-hash and the blob is sent again.
+	if err = os.Remove(name); err != nil {
+		t.Fatal(err)
+	}
+	node.flip = flipOnce()
+	before = node.chunks.Load()
+	node.atStart.Store(false)
+	r3 := newRig(t)
+	r3.planRestore(data)
+	if err = run(r3, node); err != nil {
+		t.Fatal(err)
+	}
+	if !node.atStart.Load() {
+		t.Fatal("job started without a verified copy after a flipped byte")
+	}
+	if got := node.chunks.Load() - before; got < 4 {
+		t.Fatalf("a flipped byte did not cause a second pass: %d chunk frames", got)
+	}
+	node.assertCopy(r3, b)
+	// Always flipped: the job still runs, cold, with nothing bound.
+	if err = os.Remove(name); err != nil {
+		t.Fatal(err)
+	}
+	node.flip = func(c *protocol.Chunk) {
+		if c.Final {
+			raw, _ := base64.StdEncoding.DecodeString(c.Data)
+			raw[0] ^= 1
+			c.Data = base64.StdEncoding.EncodeToString(raw)
+		}
+	}
+	node.atStart.Store(false)
+	r4 := newRig(t)
+	r4.planRestore(data)
+	if err = run(r4, node); err != nil {
+		t.Fatal(err)
+	}
+	if node.atStart.Load() {
+		t.Fatal("a corrupt transfer was bound")
+	}
+}
diff --git a/free/ci/internal/cache/remote/integration_ssh_test.go b/free/ci/internal/cache/remote/integration_ssh_test.go
index 20c39543c..3fed8440d 100644
--- a/free/ci/internal/cache/remote/integration_ssh_test.go
+++ b/free/ci/internal/cache/remote/integration_ssh_test.go
@@ -44,7 +44,7 @@ func sshNode(t *testing.T) (model.Capability, string) {
 }
 
 // runSSH delivers the rig's lease to a node over the ssh driver and returns the driver's result.
-func (r *rig) runSSH(n *node) error {
+func (r *rig) runSSH(n nodeSide) error {
 	r.t.Helper()
 	capab, home := sshNode(r.t)
 	state := r.t.TempDir()
diff --git a/free/ci/internal/cache/remote/integration_test.go b/free/ci/internal/cache/remote/integration_test.go
index 40de01dc1..4f3f72196 100644
--- a/free/ci/internal/cache/remote/integration_test.go
+++ b/free/ci/internal/cache/remote/integration_test.go
@@ -124,6 +124,18 @@ func (s *simSink) Blob(ctx context.Context, h transport.BlobHeader) (transport.B
 	return s.r.lease.Blob(ctx, h)
 }
 
+// nodeSide is what a carrier needs from the simulated node.
+type nodeSide interface {
+	tap(session.Carrier) session.Carrier
+	runner() session.Runner
+	hooks() []session.JobHook
+}
+
+// Restore lets the coordinator push the lease's restore blobs (transport.Restorer).
+func (s *simSink) Restore(ctx context.Context, link transport.RestoreLink) error {
+	return s.r.lease.Restore(ctx, link)
+}
+
 type node struct {
 	t      *testing.T
 	data   []byte
diff --git a/free/ci/internal/cache/remote/node_restore.go b/free/ci/internal/cache/remote/node_restore.go
new file mode 100644
index 000000000..0736e7f93
--- /dev/null
+++ b/free/ci/internal/cache/remote/node_restore.go
@@ -0,0 +1,164 @@
+package remote
+
+// Purpose: the node half of a cache restore (P7-CACHE-21, Epic CACHE D7): answer
+// the coordinator's `digest` announces from the read-through copies, take the
+// `chunk` frames of a blob the node lacks, and publish a blob only after its
+// re-hash matches.
+// Inputs:  the lease's restore blobs, a transport.BlobFeed and a ReadThrough.
+// Outputs: verified copies in the read-through store; `offset` answers (the size
+// for a copy held, 0 before a fetch, 0 again after a failed re-hash).
+// Constraints: only a blob of the lease plan, with the planned size, is taken: any
+// other announce or chunk is ignored; a held copy is re-hashed on every use (a bad
+// one is discarded and fetched again); a fetch failure leaves no copy, so the
+// caller binds nothing and the job runs cold; every wait is bounded by the
+// context and by Wait; a blob is retried at most maxNodeTries times.
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// DefaultNodeRestoreWait bounds the wait for each coordinator frame.
+const DefaultNodeRestoreWait = 20 * time.Second
+
+const maxNodeTries = 4
+
+var errRestart = errors.New("E714 interrupted: the coordinator restarted the blob")
+
+// NodeRestorer receives a lease's restore blobs from the coordinator.
+type NodeRestorer struct {
+	Copies *ReadThrough
+	Feed   transport.BlobFeed
+	// Realm is the lease's cache namespace (the read-through realm).
+	Realm string
+	// Wait overrides DefaultNodeRestoreWait.
+	Wait time.Duration
+
+	carry *transport.BlobFrame // a re-announce that cut a stream: handled next
+}
+
+// Fetch returns the digests of the blobs now held as verified copies. It returns
+// when every blob is held, a blob ran out of tries, or a frame did not arrive.
+func (n *NodeRestorer) Fetch(ctx context.Context, blobs []protocol.CacheBlob) map[string]bool {
+	got := map[string]bool{}
+	pending := map[string]protocol.CacheBlob{}
+	for _, b := range blobs {
+		pending[b.SHA256] = b
+	}
+	tries := map[string]int{}
+	for len(pending) > 0 {
+		fr, err := n.next(ctx)
+		if err != nil {
+			return got
+		}
+		if fr.Digest == nil {
+			continue // a chunk with no open blob
+		}
+		sha := normDigest(fr.Digest.SHA256)
+		b, ok := pending[sha]
+		if !ok || fr.Digest.Stream != StreamCache || fr.Digest.Size != b.Size {
+			continue // outside the plan: never answered, never stored
+		}
+		if tries[sha]++; tries[sha] > maxNodeTries {
+			delete(pending, sha)
+			continue
+		}
+		if n.receive(ctx, b) {
+			got[sha] = true
+			delete(pending, sha)
+		}
+	}
+	return got
+}
+
+func (n *NodeRestorer) wait() time.Duration {
+	if n.Wait > 0 {
+		return n.Wait
+	}
+	return DefaultNodeRestoreWait
+}
+
+func (n *NodeRestorer) next(ctx context.Context) (transport.BlobFrame, error) {
+	if n.carry != nil {
+		fr := *n.carry
+		n.carry = nil
+		return fr, nil
+	}
+	timer := time.NewTimer(n.wait())
+	defer timer.Stop()
+	select {
+	case fr := <-n.Feed.Frames():
+		return fr, nil
+	case <-ctx.Done():
+		return transport.BlobFrame{}, ctx.Err()
+	case <-timer.C:
+		return transport.BlobFrame{}, errors.New("E714 interrupted: no frame from the coordinator")
+	}
+}
+
+func normDigest(d string) string { return strings.ToLower(strings.TrimPrefix(d, "sha256:")) }
+
+func (n *NodeRestorer) answer(b protocol.CacheBlob, off int64) error {
+	return n.Feed.Offset(protocol.Offset{Stream: StreamCache, SHA256: b.SHA256, Offset: off})
+}
+
+// receive makes one announced blob a verified copy; false leaves nothing behind.
+func (n *NodeRestorer) receive(ctx context.Context, b protocol.CacheBlob) bool {
+	f, err := n.Copies.Open(ctx, n.Realm, b.SHA256, b.Size, func(ctx context.Context, w io.Writer) error {
+		if err := n.answer(b, 0); err != nil { // nothing held (or a copy that failed its re-hash): send it all
+			return err
+		}
+		return n.stream(ctx, w, b)
+	})
+	if err != nil {
+		if ctx.Err() == nil {
+			_ = n.answer(b, 0) // tells a sender that already finished to send the blob again
+		}
+		return false
+	}
+	_ = f.Close()
+	return n.answer(b, b.Size) == nil
+}
+
+// stream writes the chunks of b to w until the final one.
+func (n *NodeRestorer) stream(ctx context.Context, w io.Writer, b protocol.CacheBlob) error {
+	var next int64
+	for {
+		fr, err := n.next(ctx)
+		if err != nil {
+			return err
+		}
+		if fr.Digest != nil {
+			if normDigest(fr.Digest.SHA256) == b.SHA256 {
+				n.carry = &fr
+				return errRestart
+			}
+			continue
+		}
+		c := fr.Chunk
+		if c == nil || c.Stream != StreamCache || normDigest(c.Digest) != b.SHA256 {
+			continue
+		}
+		if c.Offset != next {
+			return errRestart
+		}
+		data, err := base64.StdEncoding.Strict().DecodeString(c.Data)
+		if err != nil {
+			return errRestart
+		}
+		if _, err = w.Write(data); err != nil {
+			return err
+		}
+		next += int64(len(data))
+		if c.Final {
+			return nil
+		}
+	}
+}
diff --git a/free/ci/internal/cache/remote/restore_coord.go b/free/ci/internal/cache/remote/restore_coord.go
new file mode 100644
index 000000000..2b725c9e8
--- /dev/null
+++ b/free/ci/internal/cache/remote/restore_coord.go
@@ -0,0 +1,151 @@
+package remote
+
+// Purpose: the coordinator half of a cache restore (P7-CACHE-21, Epic CACHE D7):
+// push the blobs the lease plan restores to the node over the reverse blob path
+// (digest, then chunk frames; the node answers offset), and report the copies
+// the node confirmed to cache_locality.
+// Inputs:  the lease's Binding (plan, epoch fence, node) and a transport.RestoreLink.
+// Outputs: digest and chunk frames; locality rows; audit rows for refusals.
+// Constraints: only a blob named by the lease plan, in the plan realm, and only
+// while the lease epoch is current and the attempt is leased or running; a blob
+// is done when the node confirms it holds every byte (a held copy answers at the
+// announce, a fetched one after its re-hash). A node that reports a failed
+// re-hash after the final chunk gets the blob again, as many times as the
+// transfer allows, and leaves a cache.restore.refused row (digest_mismatch).
+// Locality is advisory and never authorises a read.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/blob/transfer"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// DefaultRestoreWait bounds each wait for the node's answer.
+const DefaultRestoreWait = 30 * time.Second
+
+// restorePlanned returns the plan entry of a restore blob.
+func (l *Lease) restorePlanned(sha string) (protocol.CacheBlob, bool) {
+	if l.b.Plan == nil {
+		return protocol.CacheBlob{}, false
+	}
+	for _, r := range l.b.Plan.Restore {
+		for _, b := range r.Blobs {
+			if b.SHA256 == sha {
+				return b, true
+			}
+		}
+	}
+	return protocol.CacheBlob{}, false
+}
+
+// OpenRestore opens one planned restore blob for sending. Every refusal leaves
+// an audit row: a digest outside the plan, a stale epoch, a lease no longer
+// running, or a cancelled request.
+func (l *Lease) OpenRestore(ctx context.Context, sha string) (io.ReadCloser, protocol.CacheBlob, error) {
+	b, ok := l.restorePlanned(sha)
+	if !ok {
+		return nil, b, l.refuse(ctx, entries.ReasonNotPlanned)
+	}
+	if ctx.Err() != nil {
+		return nil, b, l.refuse(context.WithoutCancel(ctx), "cancelled")
+	}
+	if err := l.live(ctx); err != nil {
+		if errors.Is(err, transfer.ErrStale) {
+			return nil, b, l.refuse(ctx, transfer.ReasonStaleEpoch)
+		}
+		return nil, b, err
+	}
+	state, _, err := l.h.Ledger.AttemptStateEpoch(ctx, l.b.AttemptID)
+	if err != nil {
+		return nil, b, err
+	}
+	if state != "leased" && state != "running" {
+		return nil, b, l.refuse(ctx, entries.ReasonAttemptState)
+	}
+	realm := cacheRealm(l.b.Plan.Namespace)
+	info, err := l.h.Blobs.Stat(realm, sha)
+	if err != nil {
+		return nil, b, err
+	}
+	if info.Size() != b.Size {
+		return nil, b, transfer.Failf(transfer.ReasonDigest, "the coordinator holds blob %s at %d B, the plan says %d B", sha[:12], info.Size(), b.Size)
+	}
+	rc, err := l.h.Blobs.Open(realm, sha) // re-hashes into a snapshot before the first byte is served
+	return rc, b, err
+}
+
+// Restore sends the plan's restore blobs to the node, one entry at a time, and
+// records the entries the node confirmed. It returns the first error; the node
+// degrades the entries that did not arrive to a cold miss.
+func (l *Lease) Restore(ctx context.Context, link transport.RestoreLink) error {
+	if l.b.Plan == nil || len(l.b.Plan.Restore) == 0 {
+		return nil
+	}
+	wait := l.b.RestoreWait
+	if wait <= 0 {
+		wait = DefaultRestoreWait
+	}
+	tee := newOffsetTee(ctx, link.Offsets())
+	up := &finalSnap{link: link, tee: tee}
+	snd := &transfer.Sender{Up: up, Offsets: tee.out, WaitOffset: wait}
+	done := map[string]bool{}
+	for _, r := range l.b.Plan.Restore {
+		var total int64
+		for _, b := range r.Blobs {
+			total += b.Size
+			if done[b.SHA256] {
+				continue
+			}
+			if err := l.sendRestore(ctx, snd, up, tee, b, wait); err != nil {
+				return err
+			}
+			done[b.SHA256] = true
+		}
+		if l.b.Node != "" {
+			// Realm is the wire namespace, as finalize.go writes it at commit (not cas.CacheRealm).
+			row := store.CacheLocalityRow{Node: l.b.Node, Realm: l.b.Plan.Namespace, Key: r.Key, Bytes: total}
+			if err := l.h.Ledger.CacheLocalityPut(ctx, row); err != nil && l.h.Warn != nil {
+				l.h.Warn(fmt.Errorf("cache locality: %w", err))
+			}
+		}
+	}
+	return nil
+}
+
+func (l *Lease) sendRestore(ctx context.Context, snd *transfer.Sender, up *finalSnap, tee *offsetTee, b protocol.CacheBlob, wait time.Duration) error {
+	blob := transfer.Blob{Stream: StreamCache, SHA256: b.SHA256, Size: b.Size, Open: func() (io.ReadCloser, error) {
+		rc, _, err := l.OpenRestore(ctx, b.SHA256)
+		return rc, err
+	}}
+	tries := transfer.MaxResumes + 1
+	for i := 0; i < tries; i++ {
+		up.reset()
+		if err := snd.Send(ctx, blob); err != nil {
+			return err
+		}
+		since, streamed := up.final()
+		if !streamed { // the node held a verified copy: its announce answer was the whole offset
+			return nil
+		}
+		got, err := tee.after(ctx, b.SHA256, since, wait)
+		if err != nil {
+			return err
+		}
+		if got == b.Size {
+			return nil
+		}
+		// The node re-hashed the bytes, found them wrong, discarded them and reset to 0: audit, send again.
+		if err := l.h.Ledger.CacheAuditOnce(ctx, AuditRestoreRefused, l.b.AttemptID, "reason="+transfer.ReasonDigest+" node="+l.b.Node); err != nil && l.h.Warn != nil {
+			l.h.Warn(fmt.Errorf("cache restore audit: %w", err))
+		}
+	}
+	return transfer.Failf(transfer.ReasonDigest, "blob %s failed verification on the node %d times", b.SHA256[:12], tries)
+}
diff --git a/free/ci/internal/cache/remote/restore_offsets.go b/free/ci/internal/cache/remote/restore_offsets.go
new file mode 100644
index 000000000..7c34e79db
--- /dev/null
+++ b/free/ci/internal/cache/remote/restore_offsets.go
@@ -0,0 +1,126 @@
+package remote
+
+// Purpose: watch the node's offset answers while the coordinator pushes a restore
+// blob, so the sender can tell "the node holds every byte" from "the node threw
+// the bytes away" after the final chunk (P7-CACHE-21).
+// Inputs:  the lease's offset channel.
+// Outputs: a copy of every answer for the transfer.Sender, and the newest
+// position per blob with a count that orders the answers.
+// Constraints: forwarding never blocks (a full channel drops the oldest answer);
+// the tee stops with its context or when the input closes.
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/blob/transfer"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+type seenOffset struct {
+	last int64
+	n    int
+}
+
+type offsetTee struct {
+	out     chan protocol.Offset
+	mu      sync.Mutex
+	seen    map[string]seenOffset
+	changed chan struct{}
+}
+
+func newOffsetTee(ctx context.Context, in <-chan protocol.Offset) *offsetTee {
+	t := &offsetTee{out: make(chan protocol.Offset, 64), seen: map[string]seenOffset{}, changed: make(chan struct{})}
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case o, ok := <-in:
+				if !ok {
+					return
+				}
+				t.note(o)
+				t.forward(o)
+			}
+		}
+	}()
+	return t
+}
+
+func (t *offsetTee) note(o protocol.Offset) {
+	t.mu.Lock()
+	s := t.seen[o.SHA256]
+	t.seen[o.SHA256] = seenOffset{last: o.Offset, n: s.n + 1}
+	close(t.changed)
+	t.changed = make(chan struct{})
+	t.mu.Unlock()
+}
+
+func (t *offsetTee) forward(o protocol.Offset) {
+	for {
+		select {
+		case t.out <- o:
+			return
+		default:
+		}
+		select {
+		case <-t.out:
+		default:
+		}
+	}
+}
+
+func (t *offsetTee) count(sha string) int {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.seen[sha].n
+}
+
+// after waits for an answer about sha newer than count since and returns its offset.
+func (t *offsetTee) after(ctx context.Context, sha string, since int, wait time.Duration) (int64, error) {
+	timer := time.NewTimer(wait)
+	defer timer.Stop()
+	for {
+		t.mu.Lock()
+		s, ch := t.seen[sha], t.changed
+		t.mu.Unlock()
+		if s.n > since {
+			return s.last, nil
+		}
+		select {
+		case <-ch:
+		case <-ctx.Done():
+			return 0, transfer.Failf(transfer.ReasonInterrupted, "cancelled while waiting for the node to confirm blob %s", sha[:12])
+		case <-timer.C:
+			return 0, transfer.Failf(transfer.ReasonInterrupted, "the node did not confirm blob %s within %s", sha[:12], wait)
+		}
+	}
+}
+
+// finalSnap wraps the RestoreLink as a transfer.Uploader and remembers how many
+// answers the node had given when the final chunk left.
+type finalSnap struct {
+	link  transport.RestoreLink
+	tee   *offsetTee
+	mu    sync.Mutex
+	since int
+	sent  bool
+}
+
+func (f *finalSnap) reset() { f.mu.Lock(); f.sent = false; f.mu.Unlock() }
+
+func (f *finalSnap) final() (int, bool) { f.mu.Lock(); defer f.mu.Unlock(); return f.since, f.sent }
+
+func (f *finalSnap) Digest(d protocol.Digest) error { return f.link.Digest(d) }
+
+func (f *finalSnap) Chunk(c protocol.Chunk) error {
+	if c.Final {
+		f.mu.Lock()
+		f.since, f.sent = f.tee.count(c.Digest), true
+		f.mu.Unlock()
+	}
+	return f.link.Chunk(c)
+}
diff --git a/free/ci/internal/cache/remote/restore_receiver.go b/free/ci/internal/cache/remote/restore_receiver.go
new file mode 100644
index 000000000..5f2fe320b
--- /dev/null
+++ b/free/ci/internal/cache/remote/restore_receiver.go
@@ -0,0 +1,217 @@
+package remote
+
+// Purpose: receive one lease's cache restore stream into the read-through copies.
+// Inputs: digest announcements and chunk{stream:cache} frames with their epoch.
+// Outputs: verified copies in the lease's realm; audit rows for every refusal.
+// Constraints: only digests in the lease's attested restore plan; current epoch
+// only; nothing after cancel; every copy is re-hashed and corrupt ones discarded.
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+// Restore refusal audit action and the reason a cancelled lease reports.
+const (
+	AuditRestoreRefused  = "cache.restore.refused"
+	ReasonLeaseCancelled = "lease_cancelled"
+)
+
+// RestoreAuditor records one refusal row; the coordinator Ledger satisfies it.
+type RestoreAuditor interface {
+	CacheAuditOnce(ctx context.Context, action, target, detail string) error
+}
+
+// RestoreReceiver accepts the restore stream of a single lease. It is safe for
+// concurrent use; frames of one digest must arrive in offset order.
+type RestoreReceiver struct {
+	copies  *ReadThrough
+	audit   RestoreAuditor
+	leaseID string
+	epoch   uint64
+	realm   string
+	planned map[string]int64
+
+	mu        sync.Mutex
+	cancelled bool
+	cur       *restoreSpool
+	done      map[string]bool
+}
+
+type restoreSpool struct {
+	digest string
+	size   int64
+	file   *os.File
+	n      int64
+}
+
+// NewRestoreReceiver binds a receiver to the lease's restore plan and realm.
+func NewRestoreReceiver(copies *ReadThrough, lease protocol.Lease, audit RestoreAuditor) (*RestoreReceiver, error) {
+	if copies == nil || lease.LeaseID == "" || lease.Cache == nil {
+		return nil, &entries.Refused{Reason: entries.ReasonNotPlanned}
+	}
+	if _, err := DecodePlanNamespace(lease.Cache.Namespace); err != nil {
+		return nil, &entries.Refused{Reason: entries.ReasonNamespace, Err: err}
+	}
+	planned := map[string]int64{}
+	for _, r := range lease.Cache.Restore {
+		for _, b := range r.Blobs {
+			if prev, ok := planned[b.SHA256]; (ok && prev != b.Size) || b.Size < 0 {
+				return nil, &entries.Refused{Reason: entries.ReasonBlobInvalid}
+			}
+			planned[b.SHA256] = b.Size
+		}
+	}
+	return &RestoreReceiver{copies: copies, audit: audit, leaseID: lease.LeaseID, epoch: lease.Epoch,
+		realm: lease.Cache.Namespace, planned: planned, done: map[string]bool{}}, nil
+}
+
+// Realm is the read-through realm every accepted copy is written under.
+func (r *RestoreReceiver) Realm() string { return r.realm }
+
+// Received reports whether digest was verified and published by this receiver.
+func (r *RestoreReceiver) Received(digest string) bool {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.done[digest]
+}
+
+// Cancel fences the lease: any partial copy is discarded and later frames refused.
+func (r *RestoreReceiver) Cancel() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.cancelled = true
+	r.discard()
+}
+
+// Close discards a partial copy without fencing the lease.
+func (r *RestoreReceiver) Close() error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.discard()
+	return nil
+}
+
+// Digest announces the next blob; it replaces (and discards) any partial one.
+func (r *RestoreReceiver) Digest(ctx context.Context, epoch uint64, d protocol.Digest) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if err := r.admit(ctx, epoch, d.Stream, d.SHA256); err != nil {
+		return err
+	}
+	if size := r.planned[d.SHA256]; size != d.Size {
+		return r.refuse(ctx, entries.ReasonBlobInvalid, d.SHA256)
+	}
+	if d.Size > r.copies.max {
+		return r.refuse(ctx, entries.ReasonSizeCap, d.SHA256)
+	}
+	r.discard()
+	f, err := os.CreateTemp(r.copies.dir, ".restore-")
+	if err != nil {
+		return err
+	}
+	r.cur = &restoreSpool{digest: d.SHA256, size: d.Size, file: f}
+	return nil
+}
+
+// Chunk appends one frame to the announced blob. On the final frame the copy is
+// re-hashed and published, or discarded when it does not match.
+func (r *RestoreReceiver) Chunk(ctx context.Context, epoch uint64, c protocol.Chunk) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if err := r.admit(ctx, epoch, c.Stream, c.Digest); err != nil {
+		return err
+	}
+	s := r.cur
+	if s == nil || s.digest != c.Digest || c.Offset != s.n {
+		r.discard()
+		return r.refuse(ctx, entries.ReasonBlobInvalid, c.Digest)
+	}
+	data, err := base64.StdEncoding.DecodeString(c.Data)
+	if err != nil {
+		r.discard()
+		return r.refuse(ctx, entries.ReasonBlobInvalid, c.Digest)
+	}
+	if int64(len(data)) > s.size-s.n {
+		r.discard()
+		return r.refuse(ctx, entries.ReasonSizeCap, c.Digest)
+	}
+	if _, err := s.file.Write(data); err != nil {
+		r.discard()
+		return err
+	}
+	s.n += int64(len(data))
+	if !c.Final {
+		return nil
+	}
+	defer r.discard()
+	if s.n != s.size {
+		return r.refuse(ctx, entries.ReasonBlobInvalid, c.Digest)
+	}
+	if _, err := s.file.Seek(0, io.SeekStart); err != nil {
+		return err
+	}
+	f, err := r.copies.Open(ctx, r.realm, s.digest, s.size, func(ctx context.Context, w io.Writer) error {
+		_, err := io.Copy(w, &contextReader{ctx: ctx, r: s.file})
+		return err
+	})
+	if errors.Is(err, errCopyMismatch) {
+		return r.refuse(ctx, entries.ReasonBlobInvalid, c.Digest)
+	}
+	if err != nil {
+		return err
+	}
+	_ = f.Close()
+	r.done[s.digest] = true
+	return nil
+}
+
+// admit applies the cancel guard, epoch fence and plan check, in that order.
+func (r *RestoreReceiver) admit(ctx context.Context, epoch uint64, stream, digest string) error {
+	switch {
+	case r.cancelled:
+		return r.refuse(ctx, ReasonLeaseCancelled, digest)
+	case epoch != r.epoch:
+		r.discard()
+		return r.refuse(ctx, entries.ReasonEpoch, digest)
+	case stream != StreamCache:
+		return r.refuse(ctx, entries.ReasonNotPlanned, digest)
+	}
+	if _, ok := r.planned[digest]; !ok {
+		return r.refuse(ctx, entries.ReasonNotPlanned, digest)
+	}
+	return nil
+}
+
+// refuse writes the audit row and returns the E711 refusal, joined with any
+// audit failure so a lost row is never silent.
+func (r *RestoreReceiver) refuse(ctx context.Context, reason, digest string) error {
+	refused := &entries.Refused{Reason: reason}
+	if r.audit == nil {
+		return refused
+	}
+	target := r.leaseID + "/" + digest
+	if err := r.audit.CacheAuditOnce(ctx, AuditRestoreRefused, target, reason); err != nil {
+		return errors.Join(refused, fmt.Errorf("restore audit: %w", err))
+	}
+	return refused
+}
+
+func (r *RestoreReceiver) discard() {
+	if r.cur == nil {
+		return
+	}
+	name := r.cur.file.Name()
+	_ = r.cur.file.Close()
+	_ = os.Remove(filepath.Clean(name))
+	r.cur = nil
+}
diff --git a/free/ci/internal/cache/remote/restore_receiver_test.go b/free/ci/internal/cache/remote/restore_receiver_test.go
new file mode 100644
index 000000000..e8d3e7aca
--- /dev/null
+++ b/free/ci/internal/cache/remote/restore_receiver_test.go
@@ -0,0 +1,217 @@
+package remote
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/authz"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+type auditRows struct {
+	rows []string
+	err  error
+}
+
+func (a *auditRows) CacheAuditOnce(_ context.Context, action, target, detail string) error {
+	a.rows = append(a.rows, action+" "+target+" "+detail)
+	return a.err
+}
+
+func restoreFixture(t *testing.T, payloads ...string) (*RestoreReceiver, *ReadThrough, *auditRows, protocol.Lease) {
+	t.Helper()
+	c, err := NewReadThrough(t.TempDir(), 1<<20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ns := authz.Namespace{Project: "project", Trust: "owner", Protection: authz.Protected}
+	restore := protocol.CacheRestore{Spec: "go", Key: strings.Repeat("a", 64), Dir: "go/mod"}
+	for i, p := range payloads {
+		restore.Blobs = append(restore.Blobs, protocol.CacheBlob{Path: fmt.Sprint(i), SHA256: sum(p), Size: int64(len(p))})
+	}
+	lease := protocol.Lease{LeaseID: "lease-r", AttemptID: "attempt-r", Epoch: 4, Cache: &protocol.LeaseCache{
+		Namespace: base64.RawURLEncoding.EncodeToString(ns.Canonical()), Access: "ro", Restore: []protocol.CacheRestore{restore}}}
+	audit := &auditRows{}
+	r, err := NewRestoreReceiver(c, lease, audit)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r, c, audit, lease
+}
+
+func sum(s string) string { return fmt.Sprintf("%x", sha256.Sum256([]byte(s))) }
+
+func chunk(digest string, off int64, data string, final bool) protocol.Chunk {
+	return protocol.Chunk{Stream: StreamCache, Offset: off, Data: base64.StdEncoding.EncodeToString([]byte(data)), Digest: digest, Final: final}
+}
+
+func wantReason(t *testing.T, err error, reason string) {
+	t.Helper()
+	var ref *entries.Refused
+	if !errors.As(err, &ref) || ref.Reason != reason {
+		t.Fatalf("want refusal %s, got %v", reason, err)
+	}
+}
+
+func spools(t *testing.T, c *ReadThrough) int {
+	t.Helper()
+	list, err := os.ReadDir(c.dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	n := 0
+	for _, e := range list {
+		if strings.HasPrefix(e.Name(), ".restore-") {
+			n++
+		}
+	}
+	return n
+}
+
+func TestRestoreReceiverWritesVerifiedCopy(t *testing.T) {
+	ctx := context.Background()
+	data := "restored cache bytes"
+	r, c, audit, lease := restoreFixture(t, data)
+	d := sum(data)
+	if err := r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: int64(len(data))}); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Chunk(ctx, 4, chunk(d, 0, data[:8], false)); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Chunk(ctx, 4, chunk(d, 8, data[8:], true)); err != nil {
+		t.Fatal(err)
+	}
+	if !r.Received(d) || len(audit.rows) != 0 || spools(t, c) != 0 {
+		t.Fatalf("received=%v audit=%v spools=%d", r.Received(d), audit.rows, spools(t, c))
+	}
+	f, err := c.Open(ctx, lease.Cache.Namespace, d, int64(len(data)), nil)
+	if err != nil {
+		t.Fatalf("copy not published in lease realm: %v", err)
+	}
+	f.Close()
+	if _, err := c.Open(ctx, "other-realm", d, int64(len(data)), nil); !os.IsNotExist(err) {
+		t.Fatalf("copy leaked into another realm: %v", err)
+	}
+}
+
+func TestRestoreReceiverDiscardsCorruptCopy(t *testing.T) {
+	ctx := context.Background()
+	data := "genuine bytes"
+	r, c, audit, lease := restoreFixture(t, data)
+	d := sum(data)
+	if err := r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: int64(len(data))}); err != nil {
+		t.Fatal(err)
+	}
+	err := r.Chunk(ctx, 4, chunk(d, 0, strings.Repeat("x", len(data)), true))
+	wantReason(t, err, entries.ReasonBlobInvalid)
+	if r.Received(d) || len(audit.rows) != 1 || spools(t, c) != 0 {
+		t.Fatalf("corrupt copy kept: audit=%v spools=%d", audit.rows, spools(t, c))
+	}
+	if _, err := c.Open(ctx, lease.Cache.Namespace, d, int64(len(data)), nil); !os.IsNotExist(err) {
+		t.Fatalf("corrupt copy published: %v", err)
+	}
+}
+
+func TestRestoreReceiverRefusesStaleEpoch(t *testing.T) {
+	ctx := context.Background()
+	data := "bytes"
+	r, c, audit, _ := restoreFixture(t, data)
+	d := sum(data)
+	wantReason(t, r.Digest(ctx, 3, protocol.Digest{Stream: StreamCache, SHA256: d, Size: 5}), entries.ReasonEpoch)
+	if err := r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: 5}); err != nil {
+		t.Fatal(err)
+	}
+	wantReason(t, r.Chunk(ctx, 5, chunk(d, 0, data, true)), entries.ReasonEpoch)
+	if r.Received(d) || spools(t, c) != 0 || len(audit.rows) != 2 || !strings.Contains(audit.rows[0], AuditRestoreRefused+" lease-r/"+d+" epoch") {
+		t.Fatalf("stale epoch: audit=%v spools=%d", audit.rows, spools(t, c))
+	}
+	// The partial copy was dropped: a resumed chunk without a new announcement fails.
+	wantReason(t, r.Chunk(ctx, 4, chunk(d, 0, data, true)), entries.ReasonBlobInvalid)
+}
+
+func TestRestoreReceiverRefusesAfterCancel(t *testing.T) {
+	ctx := context.Background()
+	data := "bytes"
+	r, c, audit, _ := restoreFixture(t, data)
+	d := sum(data)
+	if err := r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: 5}); err != nil {
+		t.Fatal(err)
+	}
+	r.Cancel()
+	if spools(t, c) != 0 {
+		t.Fatal("cancel kept the partial copy")
+	}
+	wantReason(t, r.Chunk(ctx, 4, chunk(d, 0, data, true)), ReasonLeaseCancelled)
+	wantReason(t, r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: 5}), ReasonLeaseCancelled)
+	if r.Received(d) || len(audit.rows) != 2 || !strings.HasSuffix(audit.rows[0], ReasonLeaseCancelled) {
+		t.Fatalf("cancel audit=%v", audit.rows)
+	}
+}
+
+func TestRestoreReceiverRefusesUnplannedDigests(t *testing.T) {
+	ctx := context.Background()
+	r, c, audit, _ := restoreFixture(t, "planned")
+	other := sum("unplanned")
+	wantReason(t, r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: other, Size: 9}), entries.ReasonNotPlanned)
+	wantReason(t, r.Chunk(ctx, 4, chunk(other, 0, "unplanned", true)), entries.ReasonNotPlanned)
+	d := sum("planned")
+	wantReason(t, r.Digest(ctx, 4, protocol.Digest{Stream: "artifact", SHA256: d, Size: 7}), entries.ReasonNotPlanned)
+	wantReason(t, r.Digest(ctx, 4, protocol.Digest{Stream: StreamCache, SHA256: d, Size: 8}), entries.ReasonBlobInvalid)
+	if len(audit.rows) != 4 || spools(t, c) != 0 {
+		t.Fatalf("unplanned audit=%v spools=%d", audit.rows, spools(t, c))
+	}
+}
+
+func TestRestoreReceiverRejectsOversizeAndGaps(t *testing.T) {
+	ctx := context.Background()
+	data := "sized"
+	r, c, _, _ := restoreFixture(t, data)
+	d := sum(data)
+	announce := protocol.Digest{Stream: StreamCache, SHA256: d, Size: 5}
+	if err := r.Digest(ctx, 4, announce); err != nil {
+		t.Fatal(err)
+	}
+	wantReason(t, r.Chunk(ctx, 4, chunk(d, 0, "sized+extra", false)), entries.ReasonSizeCap)
+	if err := r.Digest(ctx, 4, announce); err != nil {
+		t.Fatal(err)
+	}
+	wantReason(t, r.Chunk(ctx, 4, chunk(d, 2, "zed", true)), entries.ReasonBlobInvalid)
+	if err := r.Digest(ctx, 4, announce); err != nil {
+		t.Fatal(err)
+	}
+	wantReason(t, r.Chunk(ctx, 4, chunk(d, 0, "siz", true)), entries.ReasonBlobInvalid)
+	if spools(t, c) != 0 || r.Received(d) {
+		t.Fatal("rejected stream left a copy")
+	}
+}
+
+func TestRestoreReceiverSurfacesAuditFailure(t *testing.T) {
+	r, _, audit, _ := restoreFixture(t, "x")
+	audit.err = errors.New("ledger down")
+	err := r.Digest(context.Background(), 9, protocol.Digest{Stream: StreamCache, SHA256: sum("x"), Size: 1})
+	wantReason(t, err, entries.ReasonEpoch)
+	if !strings.Contains(err.Error(), "ledger down") {
+		t.Fatalf("audit failure hidden: %v", err)
+	}
+}
+
+func TestNewRestoreReceiverValidatesLease(t *testing.T) {
+	c, err := NewReadThrough(t.TempDir(), 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := NewRestoreReceiver(c, protocol.Lease{LeaseID: "l"}, nil); err == nil {
+		t.Fatal("lease without cache plan accepted")
+	}
+	bad := protocol.Lease{LeaseID: "l", Cache: &protocol.LeaseCache{Namespace: "!!"}}
+	_, err = NewRestoreReceiver(c, bad, nil)
+	wantReason(t, err, entries.ReasonNamespace)
+}
diff --git a/free/ci/internal/cache/remote/restore_test.go b/free/ci/internal/cache/remote/restore_test.go
new file mode 100644
index 000000000..6f00cef45
--- /dev/null
+++ b/free/ci/internal/cache/remote/restore_test.go
@@ -0,0 +1,223 @@
+package remote
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"errors"
+	"os"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/blob/transfer"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// wire joins a coordinator Restore to a NodeRestorer in memory, frame for frame.
+type wire struct {
+	frames chan transport.BlobFrame
+	offs   chan protocol.Offset
+	chunks atomic.Int32
+	// flip, when set, may change a chunk before the node sees it.
+	flip func(*protocol.Chunk)
+}
+
+func newWire() *wire {
+	return &wire{frames: make(chan transport.BlobFrame, 8), offs: make(chan protocol.Offset, 64)}
+}
+
+type wireLink struct{ w *wire }
+
+func (l wireLink) Digest(d protocol.Digest) error {
+	select {
+	case l.w.frames <- transport.BlobFrame{Digest: &d}:
+		return nil
+	case <-time.After(5 * time.Second):
+		return errors.New("wire: node not reading")
+	}
+}
+
+func (l wireLink) Chunk(c protocol.Chunk) error {
+	l.w.chunks.Add(1)
+	if l.w.flip != nil {
+		l.w.flip(&c)
+	}
+	select {
+	case l.w.frames <- transport.BlobFrame{Chunk: &c}:
+		return nil
+	case <-time.After(5 * time.Second):
+		return errors.New("wire: node not reading")
+	}
+}
+func (l wireLink) Offsets() <-chan protocol.Offset { return l.w.offs }
+
+type wireFeed struct{ w *wire }
+
+func (f wireFeed) Frames() <-chan transport.BlobFrame { return f.w.frames }
+func (f wireFeed) Offset(o protocol.Offset) error     { f.w.offs <- o; return nil }
+func (f wireFeed) Close()                             {}
+
+// coordRestoreFixture stores one blob on the coordinator and plans it as a restore.
+func coordRestoreFixture(t *testing.T) (*Lease, *store.Store, []byte, protocol.CacheBlob) {
+	t.Helper()
+	l, st, _ := coordinatorFixture(t)
+	data := bytes.Repeat([]byte("restore me "), 110000) // 1.2 MiB: three chunks
+	sha, size, err := l.h.Blobs.Put(context.Background(), cacheRealm(l.b.Plan.Namespace), bytes.NewReader(data))
+	if err != nil {
+		t.Fatal(err)
+	}
+	b := protocol.CacheBlob{Path: "mod", SHA256: sha, Size: size}
+	l.b.Plan.Restore = []protocol.CacheRestore{{Spec: "go", Key: strings.Repeat("c", 64), Dir: "go", Blobs: []protocol.CacheBlob{b}}}
+	l.b.Node = "node-b"
+	l.b.RestoreWait = 5 * time.Second
+	return l, st, data, b
+}
+
+// runRestore pushes the lease's restore blobs to a node holding copies.
+func runRestore(t *testing.T, l *Lease, copies *ReadThrough, w *wire) (map[string]bool, error) {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	done := make(chan error, 1)
+	go func() { done <- l.Restore(ctx, wireLink{w}) }()
+	n := &NodeRestorer{Copies: copies, Feed: wireFeed{w}, Realm: l.b.Plan.Namespace, Wait: 5 * time.Second}
+	got := n.Fetch(ctx, l.b.Plan.Restore[0].Blobs)
+	return got, <-done
+}
+
+func TestRestoreColdThenHeldCopyNeedsNoChunks(t *testing.T) {
+	l, _, data, b := coordRestoreFixture(t)
+	copies, err := NewReadThrough(t.TempDir(), 8<<20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	w := newWire()
+	if got, err := runRestore(t, l, copies, w); err != nil || !got[b.SHA256] {
+		t.Fatalf("cold restore got=%v err=%v", got, err)
+	}
+	if w.chunks.Load() != 3 {
+		t.Fatalf("cold restore sent %d chunks", w.chunks.Load())
+	}
+	f, err := copies.Open(context.Background(), l.b.Plan.Namespace, b.SHA256, b.Size, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = f.Close()
+	rows, err := l.h.Ledger.CacheLocality(context.Background(), "node-b", l.b.Plan.Namespace, strings.Repeat("c", 64))
+	if err != nil || len(rows) != 1 || rows[0].Bytes != int64(len(data)) {
+		t.Fatalf("locality=%+v err=%v", rows, err)
+	}
+	w2 := newWire()
+	if got, err := runRestore(t, l, copies, w2); err != nil || !got[b.SHA256] {
+		t.Fatalf("held restore got=%v err=%v", got, err)
+	}
+	if n := w2.chunks.Load(); n != 0 {
+		t.Fatalf("a held copy cost %d chunk frames", n)
+	}
+}
+
+func TestRestoreCorruptCopyDiscardedAndFetchedAgain(t *testing.T) {
+	l, _, _, b := coordRestoreFixture(t)
+	copies, _ := NewReadThrough(t.TempDir(), 8<<20)
+	if got, err := runRestore(t, l, copies, newWire()); err != nil || !got[b.SHA256] {
+		t.Fatalf("seed got=%v err=%v", got, err)
+	}
+	name, err := copies.name(l.b.Plan.Namespace, b.SHA256)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(name)
+	raw[7] ^= 0xff
+	if err = os.WriteFile(name, raw, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	w := newWire()
+	if got, err := runRestore(t, l, copies, w); err != nil || !got[b.SHA256] {
+		t.Fatalf("corrupt copy got=%v err=%v", got, err)
+	}
+	if w.chunks.Load() != 3 {
+		t.Fatalf("a corrupt copy was served: %d chunk frames", w.chunks.Load())
+	}
+	f, err := copies.Open(context.Background(), l.b.Plan.Namespace, b.SHA256, b.Size, nil)
+	if err != nil {
+		t.Fatalf("copy not replaced: %v", err)
+	}
+	_ = f.Close()
+}
+
+// flipOnce changes one byte of the final chunk of the first pass only.
+func flipOnce() func(*protocol.Chunk) {
+	var done atomic.Bool
+	return func(c *protocol.Chunk) {
+		if !c.Final || done.Swap(true) {
+			return
+		}
+		raw, _ := base64.StdEncoding.DecodeString(c.Data)
+		raw[len(raw)/2] ^= 1
+		c.Data = base64.StdEncoding.EncodeToString(raw)
+	}
+}
+
+func TestRestoreFlippedByteFailsAndResumes(t *testing.T) {
+	l, _, _, b := coordRestoreFixture(t)
+	copies, _ := NewReadThrough(t.TempDir(), 8<<20)
+	w := newWire()
+	w.flip = flipOnce()
+	if got, err := runRestore(t, l, copies, w); err != nil || !got[b.SHA256] {
+		t.Fatalf("got=%v err=%v", got, err)
+	}
+	if n := w.chunks.Load(); n != 6 {
+		t.Fatalf("want two full passes (6 chunks), got %d", n)
+	}
+	f, err := copies.Open(context.Background(), l.b.Plan.Namespace, b.SHA256, b.Size, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = f.Close()
+}
+
+func TestRestoreAlwaysFlippedLeavesNoCopy(t *testing.T) {
+	l, _, _, b := coordRestoreFixture(t)
+	copies, _ := NewReadThrough(t.TempDir(), 8<<20)
+	w := newWire()
+	w.flip = func(c *protocol.Chunk) {
+		if c.Final {
+			raw, _ := base64.StdEncoding.DecodeString(c.Data)
+			raw[0] ^= 1
+			c.Data = base64.StdEncoding.EncodeToString(raw)
+		}
+	}
+	got, err := runRestore(t, l, copies, w)
+	if got[b.SHA256] || err == nil {
+		t.Fatalf("a corrupt transfer was accepted: got=%v err=%v", got, err)
+	}
+	if _, err = copies.Open(context.Background(), l.b.Plan.Namespace, b.SHA256, b.Size, nil); err == nil {
+		t.Fatal("a failed fetch left a copy to bind")
+	}
+}
+
+func TestRestoreRefusalsAreAudited(t *testing.T) {
+	l, s, _, b := coordRestoreFixture(t)
+	ctx := context.Background()
+	var refused *entries.Refused
+	if _, _, err := l.OpenRestore(ctx, strings.Repeat("d", 64)); !errors.As(err, &refused) || refused.Reason != entries.ReasonNotPlanned {
+		t.Fatalf("outside the plan: %v", err)
+	}
+	assertAudit(t, s, entries.ReasonNotPlanned)
+	cctx, cancel := context.WithCancel(ctx)
+	cancel()
+	if _, _, err := l.OpenRestore(cctx, b.SHA256); err == nil {
+		t.Fatal("a cancelled request was served")
+	}
+	assertAudit(t, s, "cancelled")
+	l.b.Epoch++ // a request from an epoch that is no longer the lease's
+	if _, _, err := l.OpenRestore(ctx, b.SHA256); !transfer.IsReason(err, transfer.ReasonStaleEpoch) {
+		t.Fatalf("stale epoch: %v", err)
+	}
+	assertAudit(t, s, transfer.ReasonStaleEpoch)
+}
diff --git a/free/ci/internal/cache/specs/engine.go b/free/ci/internal/cache/specs/engine.go
index 3fcf9daad..f45b8afe2 100644
--- a/free/ci/internal/cache/specs/engine.go
+++ b/free/ci/internal/cache/specs/engine.go
@@ -11,7 +11,10 @@ package specs
 // only after every blob was Put; nothing is committed for a cache with no
 // files in it (a hit on an empty entry would keep the next run from filling
 // it); restore refuses (and drops) an entry whose blob set is not exactly the
-// spec's dirs or whose archive the path sanitiser rejects.
+// spec's dirs or whose archive the path sanitiser rejects, refuses (E711
+// blob_invalid) an entry whose stored blob is missing, short or fails its
+// digest, and refuses (E711 secret_match) a read-only snapshot of a
+// secret-bearing writer; each refusal writes a cache.restore.refused row.
 
 import (
 	"context"
@@ -68,10 +71,18 @@ func (d Dirs) names() []string {
 // is (false, nil). A refused entry is dropped, the dirs are emptied and the
 // error carries the sanitiser's E683 or the reason.
 func (e *Engine) Restore(ctx context.Context, base *os.Root, ns authz.Namespace, key string, access authz.Mode, spec Spec, dirs Dirs, opt UnpackOptions) (hit bool, bytes int64, err error) {
-	m, ok, err := e.Entries.LookupForRestore(ctx, ns, key, access)
-	if err != nil || !ok {
+	m, ok, refused, err := e.Entries.ResolveForRestore(ctx, ns, key, access)
+	if err != nil {
 		return false, 0, err
 	}
+	if refused != "" { // found under the key but never served: refused, not missed (TM-12, TM-15)
+		r := &entries.Refused{Op: "restore", Reason: refused}
+		_ = e.Backend.AppendAudit(ctx, "cache", "cache.restore.refused", key, "reason="+refused)
+		return false, 0, r
+	}
+	if !ok {
+		return false, 0, nil
+	}
 	if !e.writerPassed(ctx, m) { // a cancel won after the commit and nobody retracted it (or a crash): never serve it
 		return false, 0, nil
 	}
@@ -90,6 +101,9 @@ func (e *Engine) Restore(ctx context.Context, base *os.Root, ns authz.Namespace,
 	if err == nil {
 		return true, m.Bytes(), nil
 	}
+	if blobFault(err) { // the stored bytes fail their digest or size: the entry's blob is invalid
+		err = &entries.Refused{Op: "restore", Reason: entries.ReasonBlobInvalid, Err: err}
+	}
 	for _, d := range dirs {
 		_ = removeIn(base, d)
 	}
@@ -100,9 +114,20 @@ func (e *Engine) Restore(ctx context.Context, base *os.Root, ns authz.Namespace,
 		_, _ = e.Backend.CacheDrop(ctx, m, "unrestorable")
 	}
 	_ = e.Backend.AppendAudit(ctx, "cache", "cache.restore.refused", key, "reason="+refusalKey(err))
+	var refusal *entries.Refused
+	if errors.As(err, &refusal) {
+		return false, 0, err
+	}
 	return false, 0, fmt.Errorf("cache restore refused: %w", err)
 }
 
+// blobFault reports whether err is the blob store refusing the stored bytes
+// (E710 digest or size mismatch, or a file that changed under the read).
+func blobFault(err error) bool {
+	var ce *cas.Error
+	return errors.As(err, &ce) || errors.Is(err, cas.ErrInvalid)
+}
+
 // writerPassed reports whether the attempt that committed m settled passed. An
 // attempt still finalizing is not served yet; one that ended any other way, or
 // that the store does not know, has its entry dropped: a missing attempt is no
@@ -175,5 +200,9 @@ func refusalKey(err error) string {
 	if errors.As(err, &pe) {
 		return string(pe.Reason)
 	}
+	var re *entries.Refused
+	if errors.As(err, &re) {
+		return re.Reason
+	}
 	return "unreadable"
 }
diff --git a/free/ci/internal/claims/claims.go b/free/ci/internal/claims/claims.go
new file mode 100644
index 000000000..d96a3a3b5
--- /dev/null
+++ b/free/ci/internal/claims/claims.go
@@ -0,0 +1,237 @@
+// Package claims decides which station runs commit CI for a sha (ADR 0032
+// decision 5, P7-AUTO-10).
+//
+// Purpose: the status history of a commit is the ledger. Decide is a pure
+// function over that history, so a lost state file never reruns a commit and
+// a forged or foreign status never suppresses CI.
+// Inputs:  Inputs (provider time, trusted creators, ledger, identity, limits).
+// Outputs: a Decision: take, wait(until), skip or lost.
+// Constraints: no I/O and no time.Now; ordering uses the provider's
+// created_at; with no provider time yet no claim is declared dead (fail safe).
+package claims
+
+import (
+	"sort"
+	"strings"
+	"time"
+)
+
+// DeadGrace is added to the run limit before a silent claim is dead.
+const DeadGrace = 10 * time.Minute
+
+// Kind is the outcome of Decide.
+type Kind string
+
+const (
+	Take Kind = "take"
+	Wait Kind = "wait"
+	Skip Kind = "skip"
+	Lost Kind = "lost"
+)
+
+// Status is one ledger entry.
+type Status struct {
+	Context     string
+	State       string // pending, success, failure, error
+	Creator     string
+	Description string
+	CreatedAt   time.Time
+}
+
+// Me is this station's identity.
+type Me struct{ Host, Incarnation string }
+
+// Inputs is everything Decide reads.
+type Inputs struct {
+	Now      time.Time // provider time (Date of the latest response); zero: unknown
+	Statuses []Status
+	Me       Me
+	Trusted  []string // creators whose statuses count: the station login plus claims.trusted_creators
+	RunLimit time.Duration
+	// Preferred is the host that takes at once; empty means the lexically first of Hosts.
+	Preferred string
+	Hosts     []string
+	Step      time.Duration // how long a non-preferred host waits
+	FirstSeen time.Time     // provider time this host first saw the sha without a final result
+	RetryMax  int
+	RetryGap  time.Duration
+	// ResultContext and ClaimContext default to nself-ci and nself-ci/claim.
+	ResultContext, ClaimContext string
+}
+
+// Decision is the outcome. Holds is true when Me holds the earliest live
+// claim (the publication fence reads it).
+type Decision struct {
+	Kind   Kind
+	Until  time.Time
+	Winner string
+	Holds  bool
+}
+
+func (in Inputs) results() string {
+	if in.ResultContext == "" {
+		return "nself-ci"
+	}
+	return in.ResultContext
+}
+
+func (in Inputs) claimCtx() string {
+	if in.ClaimContext == "" {
+		return "nself-ci/claim"
+	}
+	return in.ClaimContext
+}
+
+func (in Inputs) trusted(creator string) bool {
+	for _, t := range in.Trusted {
+		if t != "" && t == creator {
+			return true
+		}
+	}
+	return false
+}
+
+// Final reports whether a trusted final result exists: success or failure, or
+// RetryMax+1 trusted errors.
+func (in Inputs) Final() bool {
+	errs := 0
+	for _, s := range in.Statuses {
+		if s.Context != in.results() || !in.trusted(s.Creator) {
+			continue
+		}
+		switch s.State {
+		case "success", "failure":
+			return true
+		case "error":
+			errs++
+		}
+	}
+	return errs >= in.RetryMax+1
+}
+
+// ParseClaim reads "claim <host> <incarnation>".
+func ParseClaim(desc string) (host, inc string, ok bool) {
+	f := strings.Fields(desc)
+	if len(f) != 3 || f[0] != "claim" {
+		return "", "", false
+	}
+	return f[1], f[2], true
+}
+
+// hostOf returns the host a trusted status speaks for: a claim names it, a
+// run status carries "host=<id>" in its description.
+func hostOf(s Status) string {
+	if h, _, ok := ParseClaim(s.Description); ok {
+		return h
+	}
+	for _, f := range strings.Fields(s.Description) {
+		if h, ok := strings.CutPrefix(f, "host="); ok {
+			return h
+		}
+	}
+	return ""
+}
+
+type claim struct {
+	host string
+	at   time.Time
+}
+
+// live returns the live claims, earliest first (ties by lexical host id).
+func (in Inputs) live() []claim {
+	cutoff := in.lastError() // a claim at or before a trusted error belongs to a finished attempt
+
+	last := map[string]time.Time{} // newest trusted status per host
+	first := map[string]time.Time{}
+	for _, s := range in.Statuses {
+		if !in.trusted(s.Creator) || !s.CreatedAt.After(cutoff) {
+			continue
+		}
+		h := hostOf(s)
+		if h == "" {
+			continue
+		}
+		if s.CreatedAt.After(last[h]) {
+			last[h] = s.CreatedAt
+		}
+		if s.Context == in.claimCtx() && s.State == "pending" {
+			if _, _, ok := ParseClaim(s.Description); ok {
+				if t, seen := first[h]; !seen || s.CreatedAt.Before(t) {
+					first[h] = s.CreatedAt
+				}
+			}
+		}
+	}
+	var out []claim
+	for h, at := range first {
+		if !in.Now.IsZero() && in.Now.Sub(last[h]) > in.RunLimit+DeadGrace {
+			continue // dead on the provider clock
+		}
+		out = append(out, claim{h, at})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if !out[i].at.Equal(out[j].at) {
+			return out[i].at.Before(out[j].at)
+		}
+		return out[i].host < out[j].host
+	})
+	return out
+}
+
+func (in Inputs) lastError() time.Time {
+	var t time.Time
+	for _, s := range in.Statuses {
+		if s.Context == in.results() && s.State == "error" && in.trusted(s.Creator) && s.CreatedAt.After(t) {
+			t = s.CreatedAt
+		}
+	}
+	return t
+}
+
+func (in Inputs) preferred() string {
+	if in.Preferred != "" {
+		return in.Preferred
+	}
+	hs := append([]string{}, in.Hosts...)
+	sort.Strings(hs)
+	if len(hs) == 0 {
+		return in.Me.Host
+	}
+	return hs[0]
+}
+
+// Decide is the pure decision.
+func Decide(in Inputs) Decision {
+	if in.Final() {
+		return Decision{Kind: Skip}
+	}
+	if l := in.live(); len(l) > 0 {
+		if l[0].host == in.Me.Host {
+			return Decision{Kind: Take, Winner: l[0].host, Holds: true}
+		}
+		return Decision{Kind: Lost, Winner: l[0].host}
+	}
+	// A retry candidate waits out the retry gap after the last trusted error.
+	lastErr := in.lastError()
+	if !lastErr.IsZero() && !in.Now.IsZero() && in.Now.Before(lastErr.Add(in.RetryGap)) {
+		return Decision{Kind: Wait, Until: lastErr.Add(in.RetryGap)}
+	}
+	if in.Me.Host == in.preferred() {
+		return Decision{Kind: Take}
+	}
+	if in.FirstSeen.IsZero() || in.Now.IsZero() {
+		return Decision{Kind: Wait, Until: in.Now.Add(in.Step)}
+	}
+	if until := in.FirstSeen.Add(in.Step); in.Now.Before(until) {
+		return Decision{Kind: Wait, Until: until}
+	}
+	return Decision{Kind: Take}
+}
+
+// MayPublish is the publication fence: re-read the ledger, then post the
+// final result only if no final exists and Me still holds the earliest live
+// claim. Otherwise the result stays local evidence.
+func MayPublish(in Inputs) bool {
+	d := Decide(in)
+	return d.Kind == Take && d.Holds
+}
diff --git a/free/ci/internal/claims/claims_test.go b/free/ci/internal/claims/claims_test.go
new file mode 100644
index 000000000..f534175d5
--- /dev/null
+++ b/free/ci/internal/claims/claims_test.go
@@ -0,0 +1,207 @@
+package claims
+
+import (
+	"fmt"
+	"math/rand/v2"
+	"testing"
+	"time"
+)
+
+var t0 = time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+
+const runLimit = 30 * time.Minute
+
+func claimAt(host string, at time.Time) Status {
+	return Status{Context: "nself-ci/claim", State: "pending", Creator: "station", Description: "claim " + host + " i1", CreatedAt: at}
+}
+
+func base(me string, now time.Time, st ...Status) Inputs {
+	return Inputs{Now: now, Statuses: st, Me: Me{Host: me, Incarnation: "i1"}, Trusted: []string{"station"},
+		RunLimit: runLimit, Hosts: []string{"a", "b", "c"}, Step: time.Minute, RetryMax: 2, RetryGap: time.Minute}
+}
+
+func TestNoClaimMeansNoRun(t *testing.T) {
+	// the preferred host takes at once, others wait; a host that has no
+	// provider time yet never starts on a guess.
+	if d := Decide(base("a", t0)); d.Kind != Take {
+		t.Fatalf("preferred: %+v", d)
+	}
+	in := base("b", t0)
+	in.FirstSeen = t0
+	if d := Decide(in); d.Kind != Wait || !d.Until.Equal(t0.Add(time.Minute)) {
+		t.Fatalf("other host: %+v", d)
+	}
+	in.Now = t0.Add(time.Minute)
+	if d := Decide(in); d.Kind != Take {
+		t.Fatalf("after step: %+v", d)
+	}
+	in.Now = time.Time{}
+	if d := Decide(in); d.Kind != Wait {
+		t.Fatalf("no provider time: %+v", d)
+	}
+}
+
+func TestClaimOrderingProviderClock(t *testing.T) {
+	in := base("b", t0.Add(time.Minute), claimAt("b", t0.Add(10*time.Second)), claimAt("a", t0))
+	if d := Decide(in); d.Kind != Lost || d.Winner != "a" {
+		t.Fatalf("%+v", d)
+	}
+	in.Me.Host = "a"
+	if d := Decide(in); d.Kind != Take || !d.Holds {
+		t.Fatalf("%+v", d)
+	}
+}
+
+func TestTieLexical(t *testing.T) {
+	in := base("b", t0.Add(time.Minute), claimAt("c", t0), claimAt("b", t0), claimAt("a", t0))
+	if d := Decide(in); d.Winner != "a" || d.Kind != Lost {
+		t.Fatalf("%+v", d)
+	}
+}
+
+func TestDeadAfterRunLimit(t *testing.T) {
+	cl := claimAt("a", t0)
+	edge := t0.Add(runLimit + DeadGrace)
+	if d := Decide(base("b", edge, cl)); d.Kind != Lost {
+		t.Fatalf("still live at the edge: %+v", d)
+	}
+	in := base("b", edge.Add(time.Second), cl)
+	in.FirstSeen = t0
+	if d := Decide(in); d.Kind != Take {
+		t.Fatalf("dead claim: %+v", d)
+	}
+	// a run status from the same host keeps the claim alive
+	run := Status{Context: "nself-ci", State: "pending", Creator: "station", Description: "running host=a", CreatedAt: edge}
+	if d := Decide(base("b", edge.Add(time.Second), cl, run)); d.Kind != Lost {
+		t.Fatalf("run status renews: %+v", d)
+	}
+	// no provider time: never dead
+	if d := Decide(base("b", time.Time{}, cl)); d.Kind != Lost {
+		t.Fatalf("unknown time: %+v", d)
+	}
+}
+
+func TestLedgerNeverLocalState(t *testing.T) {
+	// a host with no memory of its own run still skips a sha that has a final
+	res := Status{Context: "nself-ci", State: "success", Creator: "station", CreatedAt: t0}
+	for _, h := range []string{"a", "b", "c"} {
+		if d := Decide(base(h, t0.Add(time.Hour), res)); d.Kind != Skip {
+			t.Fatalf("%s: %+v", h, d)
+		}
+	}
+}
+
+func TestForgedStatusIgnored(t *testing.T) {
+	forgedFinal := Status{Context: "nself-ci", State: "success", Creator: "mallory", CreatedAt: t0}
+	forgedClaim := Status{Context: "nself-ci/claim", State: "pending", Creator: "mallory", Description: "claim a i1", CreatedAt: t0}
+	if d := Decide(base("a", t0.Add(time.Minute), forgedFinal, forgedClaim)); d.Kind != Take || d.Holds {
+		t.Fatalf("%+v", d)
+	}
+}
+
+func TestFinalPublicationFence(t *testing.T) {
+	mine := claimAt("a", t0)
+	if !MayPublish(base("a", t0.Add(time.Minute), mine)) {
+		t.Fatal("holder must publish")
+	}
+	if MayPublish(base("b", t0.Add(time.Minute), mine, claimAt("b", t0.Add(time.Second)))) {
+		t.Fatal("loser must keep the result as evidence")
+	}
+	fin := Status{Context: "nself-ci", State: "failure", Creator: "station", CreatedAt: t0.Add(time.Second)}
+	if MayPublish(base("a", t0.Add(time.Minute), mine, fin)) {
+		t.Fatal("a final already exists")
+	}
+}
+
+func TestErrorUnderBudgetNotFinal(t *testing.T) {
+	e := func(i int) Status {
+		return Status{Context: "nself-ci", State: "error", Creator: "station", CreatedAt: t0.Add(time.Duration(i) * time.Hour)}
+	}
+	if Decide(base("a", t0.Add(3*time.Hour), e(0), e(1))).Kind != Take {
+		t.Fatal("two errors with RetryMax 2 is a retry candidate")
+	}
+	if Decide(base("a", t0.Add(4*time.Hour), e(0), e(1), e(2))).Kind != Skip {
+		t.Fatal("RetryMax+1 errors is final")
+	}
+	if d := Decide(base("a", t0.Add(time.Hour+time.Second), e(0), e(1))); d.Kind != Wait {
+		t.Fatalf("inside the retry gap: %+v", d)
+	}
+	// an old claim from the failed attempt does not block the retry
+	if d := Decide(base("a", t0.Add(3*time.Hour), claimAt("b", t0.Add(-time.Minute)), e(0))); d.Kind != Take {
+		t.Fatalf("%+v", d)
+	}
+}
+
+// TestDecideProperty feeds 10 000 generated ledgers with skew, ties, dead
+// claims, partial lists and foreign writers and checks the invariants.
+func TestDecideProperty(t *testing.T) {
+	seed := uint64(20261027)
+	r := rand.New(rand.NewPCG(seed, 7))
+	hosts := []string{"a", "b", "c", "d"}
+	for i := 0; i < 10000; i++ {
+		now := t0.Add(time.Duration(r.IntN(3*3600)) * time.Second)
+		var st []Status
+		for n := r.IntN(8); n > 0; n-- {
+			creator := "station"
+			if r.IntN(4) == 0 {
+				creator = "mallory"
+			}
+			skew := time.Duration(r.IntN(1200)-600) * time.Second
+			at := t0.Add(time.Duration(r.IntN(7200))*time.Second + skew)
+			if r.IntN(3) == 0 {
+				at = t0 // ties
+			}
+			if r.IntN(15) == 0 {
+				st = append(st, Status{Context: "nself-ci", State: []string{"success", "failure", "error"}[r.IntN(3)], Creator: creator, CreatedAt: at})
+				continue
+			}
+			s := claimAt(hosts[r.IntN(4)], at)
+			s.Creator = creator
+			st = append(st, s)
+		}
+		if r.IntN(5) == 0 && len(st) > 0 {
+			st = st[:len(st)/2] // partial list
+		}
+		winners, final := 0, false
+		var win string
+		for _, h := range hosts {
+			in := base(h, now, st...)
+			in.Hosts = hosts
+			d := Decide(in)
+			if d.Kind == Skip {
+				final = true
+			}
+			if d.Kind == Take && d.Holds {
+				winners++
+				win = h
+			}
+			if d.Kind == Lost && d.Winner == h {
+				t.Fatalf("seed %d case %d: lost to self", seed, i)
+			}
+		}
+		if winners > 1 {
+			t.Fatalf("seed %d case %d: %d live winners", seed, i, winners)
+		}
+		// forged statuses never change the outcome
+		var clean []Status
+		for _, s := range st {
+			if s.Creator == "station" {
+				clean = append(clean, s)
+			}
+		}
+		a, b := base("a", now, st...), base("a", now, clean...)
+		a.Hosts, b.Hosts = hosts, hosts
+		if Decide(a) != Decide(b) {
+			t.Fatalf("seed %d case %d: foreign writer changed the outcome", seed, i)
+		}
+		if !final && winners == 1 && win == "" {
+			t.Fatal("unreachable")
+		}
+	}
+}
+
+func ExampleParseClaim() {
+	h, i, ok := ParseClaim("claim mm6 inc9")
+	fmt.Println(h, i, ok)
+	// Output: mm6 inc9 true
+}
diff --git a/free/ci/internal/coordclient/nodes_placement.go b/free/ci/internal/coordclient/nodes_placement.go
new file mode 100644
index 000000000..d3e5f6843
--- /dev/null
+++ b/free/ci/internal/coordclient/nodes_placement.go
@@ -0,0 +1,35 @@
+package coordclient
+
+// Purpose: the client of the TEAM node labels and projects routes (P7-NODE-30): `nself ci nodes label` and
+// `nself ci nodes projects ... --coordinator <url>`.
+// Inputs:  a node id and a clientapi.PlacementRequest.
+// Outputs: the coordinator's NodeResult (exit code, stdout, stderr), or an E664 error.
+// Constraints: the node id travels as one path segment; mutations are POST, reads are GET with ?json=1.
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+)
+
+// NodeLabels reads a node's labels (write false) or edits them (write true; the request carries Labels and Remove).
+func (c *Client) NodeLabels(ctx context.Context, id string, write bool, req clientapi.PlacementRequest) (clientapi.NodeResult, error) {
+	return c.placement(ctx, id, "labels", write, req)
+}
+
+// NodeProjects lists a node's authorized projects (write false) or changes them (write true; req.Action is add or remove).
+func (c *Client) NodeProjects(ctx context.Context, id string, write bool, req clientapi.PlacementRequest) (clientapi.NodeResult, error) {
+	return c.placement(ctx, id, "projects", write, req)
+}
+
+func (c *Client) placement(ctx context.Context, id, leaf string, write bool, req clientapi.PlacementRequest) (clientapi.NodeResult, error) {
+	path := clientapi.PathNodesPfx + url.PathEscape(id) + "/" + leaf
+	if !write {
+		return c.node(ctx, http.MethodGet, path+jsonQuery(req.JSON), nil)
+	}
+	body, _ := json.Marshal(req)
+	return c.node(ctx, http.MethodPost, path, body)
+}
diff --git a/free/ci/internal/coordclient/nodes_placement_test.go b/free/ci/internal/coordclient/nodes_placement_test.go
new file mode 100644
index 000000000..d911e7d6a
--- /dev/null
+++ b/free/ci/internal/coordclient/nodes_placement_test.go
@@ -0,0 +1,90 @@
+package coordclient
+
+// Purpose: tests of the labels and projects client (P7-NODE-30) against the real user API: a member reads
+// and is refused every mutation with E664 role, an admin edits, the typed request reaches the runner and
+// the node id stays one path segment.
+// Inputs:  the sim of rig_test.go and a scripted clientapi.PlacementRunner. Outputs: pass or fail.
+// Constraints: the placement routes register once per process; real TLS on 127.0.0.1.
+
+import (
+	"context"
+	"reflect"
+	"sync"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+)
+
+var placementRun struct {
+	sync.Mutex
+	calls []clientapi.PlacementCommand
+}
+
+var registerPlacement sync.Once
+
+func placementSim(t *testing.T) *sim {
+	t.Helper()
+	registerPlacement.Do(func() {
+		err := clientapi.RegisterPlacementRoutes(func() clientapi.PlacementRunner {
+			return func(_ context.Context, _ string, c clientapi.PlacementCommand) (clientapi.NodeResult, error) {
+				placementRun.Lock()
+				defer placementRun.Unlock()
+				placementRun.calls = append(placementRun.calls, c)
+				return clientapi.NodeResult{Stdout: "out " + c.Verb}, nil
+			}
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+	})
+	placementRun.Lock()
+	placementRun.calls = nil
+	placementRun.Unlock()
+	return newSim(t)
+}
+
+func TestPlacementClientMemberReadsAdminEdits(t *testing.T) {
+	s := placementSim(t)
+	ctx := context.Background()
+	member, admin := tokenClient(s, roles.Member), tokenClient(s, roles.Admin)
+	if r, err := member.NodeProjects(ctx, "vps-a", false, clientapi.PlacementRequest{JSON: true}); err != nil || r.Stdout != "out projects list" {
+		t.Fatalf("member projects list = %+v %v", r, err)
+	}
+	if r, err := member.NodeLabels(ctx, "mini1", false, clientapi.PlacementRequest{}); err != nil || r.Stdout != "out label list" {
+		t.Fatalf("member label list = %+v %v", r, err)
+	}
+	if _, err := member.NodeLabels(ctx, "mini1", true, clientapi.PlacementRequest{Labels: []string{"xcode"}}); !reasonIs(err, clientapi.ReasonRole) {
+		t.Fatalf("member label edit: %v, want E664 role", err)
+	}
+	if _, err := member.NodeProjects(ctx, "vps-a", true, clientapi.PlacementRequest{Action: "add", Projects: []string{"p"}}); !reasonIs(err, clientapi.ReasonRole) {
+		t.Fatalf("member projects add: %v, want E664 role", err)
+	}
+	if r, err := admin.NodeLabels(ctx, "mini1", true, clientapi.PlacementRequest{Labels: []string{"xcode", "arch=arm64"}, Remove: []string{"gpu"}}); err != nil || r.Stdout != "out label" {
+		t.Fatalf("admin label = %+v %v", r, err)
+	}
+	if r, err := admin.NodeProjects(ctx, "vps-a", true, clientapi.PlacementRequest{Action: "remove", Projects: []string{"local:abc"}}); err != nil || r.Stdout != "out projects remove" {
+		t.Fatalf("admin projects remove = %+v %v", r, err)
+	}
+	placementRun.Lock()
+	defer placementRun.Unlock()
+	if len(placementRun.calls) != 4 {
+		t.Fatalf("runner saw %d calls, want the 2 reads and 2 admin edits: %+v", len(placementRun.calls), placementRun.calls)
+	}
+	if c := placementRun.calls[2]; c.Node != "mini1" || !reflect.DeepEqual(c.Labels, []string{"xcode", "arch=arm64"}) || !reflect.DeepEqual(c.Remove, []string{"gpu"}) {
+		t.Fatalf("label command %+v", c)
+	}
+}
+
+func TestPlacementClientIDIsOnePathSegment(t *testing.T) {
+	s := placementSim(t)
+	_, err := tokenClient(s, roles.Admin).NodeLabels(context.Background(), "a/../b", true, clientapi.PlacementRequest{Labels: []string{"x"}})
+	if !reasonIs(err, clientapi.ReasonNotFound) && !reasonIs(err, clientapi.ReasonBadRequest) {
+		t.Fatalf("got %v", err)
+	}
+	placementRun.Lock()
+	defer placementRun.Unlock()
+	if len(placementRun.calls) != 0 {
+		t.Fatalf("a crafted id reached the runner: %+v", placementRun.calls)
+	}
+}
diff --git a/free/ci/internal/coordclient/stats.go b/free/ci/internal/coordclient/stats.go
new file mode 100644
index 000000000..39a634271
--- /dev/null
+++ b/free/ci/internal/coordclient/stats.go
@@ -0,0 +1,46 @@
+package coordclient
+
+// Purpose: the client side of GET /v1/stats (P7-SCHED-20): `nself ci runs stats --coordinator <url>`.
+// Inputs:  a window and an optional project.
+// Outputs: the coordinator's contract:ci.stats document, byte for byte as served.
+// Constraints: same transport, pinned root and credential rules as every other call; the answer is read to
+//          at most 8 MiB; the project travels in the query, escaped.
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+)
+
+// maxStatsAnswer caps the stats document.
+const maxStatsAnswer = 8 << 20
+
+// Stats fetches the stats document for the caller's projects; since 0 asks for the server default.
+func (c *Client) Stats(ctx context.Context, since time.Duration, project string) (json.RawMessage, error) {
+	q := url.Values{}
+	if since > 0 {
+		q.Set("since", since.String())
+	}
+	if project != "" {
+		q.Set("project", project)
+	}
+	path := clientapi.PathStats
+	if len(q) > 0 {
+		path += "?" + q.Encode()
+	}
+	resp, err := c.do(ctx, http.MethodGet, path, nil)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, maxStatsAnswer+1))
+	if err != nil || len(raw) > maxStatsAnswer || !json.Valid(raw) {
+		return nil, clientapi.Failf(clientapi.ReasonTransport, "the coordinator answer is not a valid stats document")
+	}
+	return json.RawMessage(raw), nil
+}
diff --git a/free/ci/internal/coordclient/stats_test.go b/free/ci/internal/coordclient/stats_test.go
new file mode 100644
index 000000000..fd3a4b1d1
--- /dev/null
+++ b/free/ci/internal/coordclient/stats_test.go
@@ -0,0 +1,86 @@
+package coordclient
+
+// Purpose: tests of the stats client (P7-SCHED-20) against the real user API with the store the sim serves:
+// a member scoped to one project gets that project's document and no coordinator-wide block, an all-project
+// member gets every project's, and both are the documents the coordinator host computes for the same caller.
+// Inputs:  the sim of rig_test.go and two outcome rows. Outputs: pass or fail.
+// Constraints: the stats source is process-global, restored on cleanup; real TLS on 127.0.0.1.
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"path/filepath"
+	"strconv"
+	"testing"
+	"time"
+
+	_ "modernc.org/sqlite"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/clientapi"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+	"github.com/nself-org/plugins/free/ci/internal/stats"
+)
+
+func seedOutcomes(t *testing.T, s *sim) {
+	t.Helper()
+	db, err := sql.Open("sqlite", "file:"+filepath.Join(s.dir, "state.db")+"?_pragma=busy_timeout(5000)")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = db.Close() }()
+	for i, project := range []string{"acme/app", "acme/other"} {
+		id := string(rune('a' + i))
+		for _, q := range []string{
+			`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES('p` + id + `','` + project + `','r','push','t','z','d','i','m','r','s','passed',1)`,
+			`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES('j` + id + `','p` + id + `','build','k',1,1,'i',1,'passed')`,
+			`INSERT INTO attempt(id,job_id,n,state) VALUES('a` + id + `','j` + id + `',1,'passed')`,
+			`INSERT INTO schedtel_outcome(attempt_id,project,job_key,runner,runner_class,wait_ms,runtime_ms,cold_start_ms,cost_micro,result,failure_class,ts) VALUES('a` + id + `','` + project + `','build','r1','owned',5,9,-1,0,'passed','',` + strconv.FormatInt(time.Now().UnixMilli(), 10) + `)`,
+		} {
+			if _, err = db.Exec(q); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+}
+
+func TestStatsClientSeesOnlyTheCallersProjects(t *testing.T) {
+	s := newSim(t)
+	seedOutcomes(t, s)
+	clientapi.SetStatsSource(func(ctx context.Context, o stats.Options) (stats.Doc, error) { return stats.Compute(ctx, s.st, o) })
+	t.Cleanup(func() { clientapi.SetStatsSource(nil) })
+	ctx := context.Background()
+
+	member := s.client(Creds{CA: s.rootFile(), TokenFile: s.tokenFile("mia", roles.Member, time.Hour, "acme/app")})
+	raw, err := member.Stats(ctx, time.Hour, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got stats.Doc
+	if err = json.Unmarshal(raw, &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Attempts == nil || got.Attempts.Finished != 1 || got.Nodes != nil || got.Reasons["nodes"] != stats.ReasonScoped {
+		t.Fatalf("scoped member document: %s", raw)
+	}
+	if _, err = member.Stats(ctx, time.Hour, "acme/other"); err == nil {
+		t.Fatal("a project outside the grant was served")
+	}
+
+	whole := s.client(Creds{CA: s.rootFile(), TokenFile: s.tokenFile("ops", roles.Member, time.Hour, roles.AllProjects)})
+	raw, err = whole.Stats(ctx, time.Hour, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var all stats.Doc
+	if err = json.Unmarshal(raw, &all); err != nil {
+		t.Fatal(err)
+	}
+	local, err := stats.Compute(ctx, s.st, stats.Options{Now: time.Now(), Since: time.Hour, Global: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if all.Attempts == nil || all.Attempts.Finished != 2 || *all.Attempts != *local.Attempts || all.Nodes != nil && local.Nodes == nil {
+		t.Fatalf("remote %+v differs from the coordinator host %+v", all.Attempts, local.Attempts)
+	}
+}
diff --git a/free/ci/internal/coordinator/agentapi/frames.go b/free/ci/internal/coordinator/agentapi/frames.go
index 674abdc15..832b9134c 100644
--- a/free/ci/internal/coordinator/agentapi/frames.go
+++ b/free/ci/internal/coordinator/agentapi/frames.go
@@ -108,6 +108,12 @@ func (s *Server) handleFrame(q *request, f *flow, m protocol.Message) *fatal {
 		act = func() error { return s.cfg.Sink.CacheRef(ctx, *b) }
 	case *protocol.Result:
 		act = func() error { return s.cfg.Sink.Result(ctx, *b) }
+	case *protocol.Offset:
+		oh, isOH := s.cfg.Blobs.(OffsetHandler)
+		if !isOH {
+			return &fatal{protocol.CodeInvalid, "frame_type"}
+		}
+		act = func() error { return oh.Offset(ctx, q.node, m) }
 	case *protocol.Digest, *protocol.Chunk:
 		if s.cfg.Blobs == nil {
 			return &fatal{protocol.CodeInvalid, "frame_type"}
diff --git a/free/ci/internal/coordinator/agentapi/push.go b/free/ci/internal/coordinator/agentapi/push.go
new file mode 100644
index 000000000..0ccfbe14c
--- /dev/null
+++ b/free/ci/internal/coordinator/agentapi/push.go
@@ -0,0 +1,58 @@
+package agentapi
+
+// Purpose: the coordinator-to-agent push of a lease's cache restore (P7-CACHE-21, Epic CACHE D7, carrier B):
+//          digest and chunk frames ride the node's control stream, the node answers with upstream `offset`
+//          frames, which reach the BlobHandler when it also implements OffsetHandler.
+// Inputs:  Push(ctx, node, message); an upstream offset frame of a lease the node holds.
+// Outputs: a message queued on the node's control stream; the offset handed to the handler.
+// Constraints: Push waits while pushWindow messages are undelivered (backpressure, so a large blob never
+//          fills the queue), ends with ctx, and fails when the node has no live control stream; an offset
+//          passes the same ownership, token and epoch fence as every lease-scoped frame.
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+// pushWindow is how many pushed messages may wait for delivery on one node.
+const pushWindow = 16
+
+// OffsetHandler is implemented by a BlobHandler that takes the node's offset answers to a restore push.
+type OffsetHandler interface {
+	Offset(ctx context.Context, node string, m protocol.Message) error
+}
+
+// Push queues m for the node's control stream, waiting while the window is full.
+func (s *Server) Push(ctx context.Context, nodeID string, m protocol.Message) error {
+	for {
+		queued, err := s.tryPush(nodeID, m)
+		if queued || err != nil {
+			return err
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(2 * time.Millisecond):
+		}
+	}
+}
+
+// tryPush checks the window and queues in one step under the registry lock, so concurrent
+// pushers never overshoot pushWindow.
+func (s *Server) tryPush(nodeID string, m protocol.Message) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	ns := s.nodes[nodeID]
+	if ns == nil || ns.sess == nil || ns.sess.ctlLive == 0 {
+		return false, fmt.Errorf("%w: %s", ErrNoControlStream, nodeID)
+	}
+	if len(ns.ctl) >= pushWindow {
+		return false, nil
+	}
+	ns.ctl = append(ns.ctl, m)
+	ns.signal()
+	return true, nil
+}
diff --git a/free/ci/internal/coordinator/agentapi/push_test.go b/free/ci/internal/coordinator/agentapi/push_test.go
new file mode 100644
index 000000000..729461fff
--- /dev/null
+++ b/free/ci/internal/coordinator/agentapi/push_test.go
@@ -0,0 +1,71 @@
+package agentapi
+
+// Purpose: tests of the restore push window and the fence on upstream offset frames (P7-CACHE-21).
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+func TestPushWindowIsAtomic(t *testing.T) {
+	s := &Server{nodes: map[string]*nodeState{}}
+	ns := s.state("n")
+	ns.sess = &session{ctlLive: 1}
+	ctx, cancel := context.WithTimeout(context.Background(), 150*time.Millisecond)
+	defer cancel()
+	var wg sync.WaitGroup
+	for i := 0; i < 64; i++ {
+		wg.Add(1)
+		go func() { defer wg.Done(); _ = s.Push(ctx, "n", protocol.Message{Type: "chunk"}) }()
+	}
+	wg.Wait()
+	s.mu.Lock()
+	n := len(ns.ctl)
+	s.mu.Unlock()
+	if n != pushWindow {
+		t.Fatalf("queued %d, want exactly the window of %d", n, pushWindow)
+	}
+	if err := s.Push(context.Background(), "gone", protocol.Message{Type: "chunk"}); err == nil {
+		t.Fatal("a node with no control stream accepted a push")
+	}
+}
+
+type offsetSink struct{ n atomic.Int32 }
+
+func (*offsetSink) Frame(context.Context, string, protocol.Message) ([]protocol.Message, error) {
+	return nil, nil
+}
+func (o *offsetSink) Offset(context.Context, string, protocol.Message) error { o.n.Add(1); return nil }
+
+// A stale-epoch offset passes the generic fence: it is answered with an E662 cancel and never reaches the handler.
+func TestStaleEpochOffsetRefused(t *testing.T) {
+	h := &offsetSink{}
+	r := newRig(t, func(c *Config) { c.Blobs = h })
+	a := r.newAgent("n-1")
+	leaseID, epoch := r.seedLease("1")
+	a.connect()
+	u := a.openStream(0)
+	off := func(e uint64) protocol.Message {
+		return protocol.Message{Type: "offset", LeaseID: leaseID, Epoch: &e, Body: protocol.Offset{Stream: "cache", SHA256: "ab", Offset: 1}}
+	}
+	u.send(off(epoch + 1))
+	m := u.read()
+	c, ok := m.Body.(*protocol.Cancel)
+	if !ok || c.LeaseID != leaseID || len(c.Reason) < 4 || c.Reason[:4] != "E662" {
+		t.Fatalf("answer = %s %+v, want an E662 cancel", m.Type, m.Body)
+	}
+	if h.n.Load() != 0 || r.eng.StaleCount() == 0 {
+		t.Fatalf("stale offset reached the handler (%d) or was not counted", h.n.Load())
+	}
+	u.send(off(epoch))
+	u.send(heartbeat())
+	u.read() // heartbeat ack: the current-epoch offset before it was processed
+	if h.n.Load() != 1 {
+		t.Fatalf("current-epoch offset reached the handler %d times, want 1", h.n.Load())
+	}
+}
diff --git a/free/ci/internal/coordinator/clientapi/nodes_placement_routes.go b/free/ci/internal/coordinator/clientapi/nodes_placement_routes.go
new file mode 100644
index 000000000..4efcc5959
--- /dev/null
+++ b/free/ci/internal/coordinator/clientapi/nodes_placement_routes.go
@@ -0,0 +1,193 @@
+package clientapi
+
+// Purpose: TEAM node labels and project authorization over the user API (P7-NODE-30, Epic NODE D19): the
+// /v1/nodes/{id}/labels and /v1/nodes/{id}/projects routes behind `nself ci nodes label|projects
+// --coordinator <url>`. A GET needs the member role (and a grant on all projects, like node list); a POST
+// needs admin. Every route runs the same operation the local command runs, through a PlacementRunner the
+// serve hands in, so the audit rows are written with the caller's label as the actor on both paths.
+// Inputs:  RegisterPlacementRoutes(run); a JSON PlacementRequest (POST) or ?json=1 (GET).
+// Outputs: a NodeResult (the command's exit code, stdout and stderr); E664 on refusal.
+// Constraints: the route role is admin for a mutation and the handler checks it again, so a route
+//          registered with a lower role still fails closed; the caller never supplies argv: labels, keys and
+//          project ids are validated here and travel as typed fields; directories, `local` and wildcard
+//          grants are the runner's to refuse on a coordinator; until the serve has started the routes answer
+//          not found.
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+)
+
+// Placement verbs.
+const (
+	VerbLabel          = "label"
+	VerbLabelList      = "label list"
+	VerbProjectsAdd    = "projects add"
+	VerbProjectsRemove = "projects remove"
+	VerbProjectsList   = "projects list"
+)
+
+// PlacementCommand is one validated operation for the runner.
+type PlacementCommand struct {
+	Verb, Node string
+	Labels     []string // label: key or key=value
+	Remove     []string // label: keys to remove
+	Projects   []string // projects add|remove: repo ids
+	All        bool
+	JSON       bool
+}
+
+// PlacementRunner runs cmd as the caller (actor is the caller's audit label) and captures its output.
+type PlacementRunner func(ctx context.Context, actor string, cmd PlacementCommand) (NodeResult, error)
+
+// PlacementRequest is the body of a POST. Action is add or remove for the projects route.
+type PlacementRequest struct {
+	JSON     bool     `json:"json,omitempty"`
+	Action   string   `json:"action,omitempty"`
+	Labels   []string `json:"labels,omitempty"`
+	Remove   []string `json:"remove,omitempty"`
+	Projects []string `json:"projects,omitempty"`
+	All      bool     `json:"all,omitempty"`
+}
+
+const (
+	maxPlacementBody  = 16 << 10
+	maxPlacementItems = 64
+)
+
+var placementItemRe = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:=-]{0,127}$`)
+
+// RegisterPlacementRoutes registers the labels and projects routes. run is read per request and may
+// return nil before the serve has started.
+func RegisterPlacementRoutes(run func() PlacementRunner) error {
+	p := placementRoutes{run: run}
+	for _, s := range []struct {
+		method, suffix, verb string
+		role                 roles.Role
+	}{{http.MethodGet, "labels", VerbLabelList, roles.Member}, {http.MethodPost, "labels", VerbLabel, roles.Admin},
+		{http.MethodGet, "projects", VerbProjectsList, roles.Member}, {http.MethodPost, "projects", "", roles.Admin}} {
+		if err := RegisterRoute(s.method, PathNodesPfx+"{id}/"+s.suffix, string(s.role), p.handler(s.verb, s.role)); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+type placementRoutes struct{ run func() PlacementRunner }
+
+func (p placementRoutes) handler(verb string, min roles.Role) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := ActorFrom(r.Context())
+		if !ok {
+			errServer.fail(w, Failf(ReasonInternal, "no caller"))
+			return
+		}
+		if err := actor.Can(min, ""); err != nil {
+			errServer.fail(w, err)
+			return
+		}
+		cmd, err := placementCommand(verb, r)
+		if err != nil {
+			errServer.fail(w, err)
+			return
+		}
+		if r.Method == http.MethodGet && !wholeCoordinator(actor) {
+			errServer.fail(w, Failf(ReasonProject, "node information is coordinator-wide: it needs a grant on all projects"))
+			return
+		}
+		var run PlacementRunner
+		if p.run != nil {
+			run = p.run()
+		}
+		if run == nil {
+			errServer.fail(w, Failf(ReasonNotFound, "node administration is not available on this server"))
+			return
+		}
+		res, err := run(r.Context(), actor.Label(), cmd)
+		if err != nil {
+			errServer.fail(w, err)
+			return
+		}
+		if r.Method == http.MethodGet && res.Exit >= 2 {
+			res = NodeResult{Exit: res.Exit, Stderr: "E607: the node registry could not be read\n"}
+		}
+		status := http.StatusOK
+		if res.Exit != 0 {
+			status = http.StatusUnprocessableEntity
+		}
+		writeJSON(w, status, res)
+	})
+}
+
+// placementCommand validates the request and builds the runner's command.
+func placementCommand(verb string, r *http.Request) (PlacementCommand, error) {
+	cmd := PlacementCommand{Verb: verb}
+	var req PlacementRequest
+	if r.Method == http.MethodPost {
+		if ct := r.Header.Get("Content-Type"); ct != "" && !strings.HasPrefix(strings.ToLower(ct), "application/json") {
+			return cmd, Failf(ReasonBadRequest, "send the body as application/json")
+		}
+		raw, err := io.ReadAll(io.LimitReader(r.Body, maxPlacementBody+1))
+		if err != nil || len(raw) > maxPlacementBody {
+			return cmd, Failf(ReasonBadRequest, "the request body is missing or too long")
+		}
+		dec := json.NewDecoder(strings.NewReader(string(raw)))
+		dec.DisallowUnknownFields()
+		var extra json.RawMessage
+		if dec.Decode(&req) != nil || dec.Decode(&extra) != io.EOF {
+			return cmd, Failf(ReasonBadRequest, "the request body is not valid")
+		}
+	} else {
+		req.JSON = r.URL.Query().Get("json") == "1"
+	}
+	cmd.JSON = req.JSON
+	cmd.Node = strings.ToLower(r.PathValue("id"))
+	if remote.ValidateNodeID(cmd.Node) != nil {
+		return cmd, Failf(ReasonBadRequest, "the node id is not valid")
+	}
+	if verb == "" { // the projects POST: the action picks the verb
+		switch req.Action {
+		case "add":
+			cmd.Verb = VerbProjectsAdd
+		case "remove":
+			cmd.Verb = VerbProjectsRemove
+		default:
+			return cmd, Failf(ReasonBadRequest, "action must be add or remove")
+		}
+	}
+	for _, f := range []struct {
+		name string
+		own  bool
+		list []string
+		dst  *[]string
+	}{{"labels", cmd.Verb == VerbLabel, req.Labels, &cmd.Labels}, {"remove", cmd.Verb == VerbLabel, req.Remove, &cmd.Remove},
+		{"projects", cmd.Verb == VerbProjectsAdd || cmd.Verb == VerbProjectsRemove, req.Projects, &cmd.Projects}} {
+		if len(f.list) == 0 {
+			continue
+		}
+		if !f.own {
+			return cmd, Failf(ReasonBadRequest, "%s does not take %s", cmd.Verb, f.name)
+		}
+		if len(f.list) > maxPlacementItems {
+			return cmd, Failf(ReasonBadRequest, "too many %s", f.name)
+		}
+		for _, v := range f.list {
+			if !placementItemRe.MatchString(v) {
+				return cmd, Failf(ReasonBadRequest, "a value of %s is not valid", f.name)
+			}
+		}
+		*f.dst = f.list
+	}
+	if req.All && cmd.Verb != VerbProjectsAdd && cmd.Verb != VerbProjectsRemove {
+		return cmd, Failf(ReasonBadRequest, "%s does not take all", cmd.Verb)
+	}
+	cmd.All = req.All
+	return cmd, nil
+}
diff --git a/free/ci/internal/coordinator/clientapi/nodes_placement_routes_test.go b/free/ci/internal/coordinator/clientapi/nodes_placement_routes_test.go
new file mode 100644
index 000000000..252485303
--- /dev/null
+++ b/free/ci/internal/coordinator/clientapi/nodes_placement_routes_test.go
@@ -0,0 +1,151 @@
+package clientapi
+
+// Purpose: tests of the labels and projects routes (P7-NODE-30): a member lists but gets E664 role on
+// every mutation, an admin runs each with typed fields, a project-scoped caller is refused, and bad input
+// never reaches the runner.
+// Inputs:  the rig of rig_test.go and a scripted PlacementRunner. Outputs: pass or fail.
+// Constraints: the routes register once per process, so one runner variable is shared by all tests.
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+)
+
+type placementCall struct {
+	actor string
+	cmd   PlacementCommand
+}
+
+var placementFake struct {
+	sync.Mutex
+	calls []placementCall
+}
+
+var registerPlacementOnce sync.Once
+
+func placementRig(t *testing.T) *rig {
+	t.Helper()
+	registerPlacementOnce.Do(func() {
+		err := RegisterPlacementRoutes(func() PlacementRunner {
+			return func(_ context.Context, actor string, cmd PlacementCommand) (NodeResult, error) {
+				placementFake.Lock()
+				defer placementFake.Unlock()
+				placementFake.calls = append(placementFake.calls, placementCall{actor, cmd})
+				return NodeResult{Stdout: "ran " + cmd.Verb + "\n"}, nil
+			}
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+	})
+	placementFake.Lock()
+	placementFake.calls = nil
+	placementFake.Unlock()
+	return newRig(t)
+}
+
+func placementCalls() []placementCall {
+	placementFake.Lock()
+	defer placementFake.Unlock()
+	return append([]placementCall(nil), placementFake.calls...)
+}
+
+var placementMutations = []struct{ name, path, body string }{
+	{"label", PathNodesPfx + "mini1/labels", `{"labels":["xcode","arch=arm64"],"remove":["old"]}`},
+	{"projects add", PathNodesPfx + "vps-a/projects", `{"action":"add","projects":["local:abc"]}`},
+	{"projects remove", PathNodesPfx + "vps-a/projects", `{"action":"remove","projects":["local:abc"]}`},
+}
+
+func TestPlacementMemberListsOnly(t *testing.T) {
+	r := placementRig(t)
+	tok := r.token("bob", roles.Member, time.Hour, roles.AllProjects)
+	for _, m := range placementMutations {
+		st, b := r.do(r.client(), "POST", m.path, tok, m.body)
+		refused(t, st, b, 403, ReasonRole)
+	}
+	if got := placementCalls(); len(got) != 0 {
+		t.Fatalf("a member ran %+v", got)
+	}
+	for path, verb := range map[string]string{PathNodesPfx + "vps-a/projects": VerbProjectsList, PathNodesPfx + "mini1/labels": VerbLabelList} {
+		if st, b := r.do(r.client(), "GET", path+"?json=1", tok, ""); st != 200 {
+			t.Fatalf("member GET %s = %d %s", path, st, b)
+		}
+		got := placementCalls()
+		if last := got[len(got)-1]; last.cmd.Verb != verb || !last.cmd.JSON || !strings.Contains(last.actor, "bob") {
+			t.Fatalf("member read ran %+v", last)
+		}
+	}
+}
+
+func TestPlacementAdminRunsEach(t *testing.T) {
+	r := placementRig(t)
+	tok := r.token("ada", roles.Admin, time.Hour, roles.AllProjects)
+	for i, m := range placementMutations {
+		st, b := r.do(r.client(), "POST", m.path, tok, m.body)
+		var res NodeResult
+		if st != 200 || json.Unmarshal(b, &res) != nil || res.Stdout != "ran "+m.name+"\n" {
+			t.Fatalf("admin %s = %d %s", m.name, st, b)
+		}
+		if got := placementCalls(); len(got) != i+1 || !strings.Contains(got[i].actor, "ada") {
+			t.Fatalf("admin %s ran %+v", m.name, got)
+		}
+	}
+	c := placementCalls()
+	if !reflect.DeepEqual(c[0].cmd.Labels, []string{"xcode", "arch=arm64"}) || !reflect.DeepEqual(c[0].cmd.Remove, []string{"old"}) || c[0].cmd.Node != "mini1" {
+		t.Fatalf("label command %+v", c[0].cmd)
+	}
+	if c[1].cmd.Verb != VerbProjectsAdd || !reflect.DeepEqual(c[1].cmd.Projects, []string{"local:abc"}) {
+		t.Fatalf("projects add command %+v", c[1].cmd)
+	}
+}
+
+func TestPlacementScopedCallerRefused(t *testing.T) {
+	r := placementRig(t)
+	tok := r.token("dan", roles.Admin, time.Hour, "acme/app")
+	for _, m := range placementMutations {
+		st, b := r.do(r.client(), "POST", m.path, tok, m.body)
+		refused(t, st, b, 403, ReasonProject)
+	}
+	mem := r.token("eve", roles.Member, time.Hour, "acme/app")
+	st, b := r.do(r.client(), "GET", PathNodesPfx+"vps-a/projects", mem, "")
+	refused(t, st, b, 403, ReasonProject)
+	if got := placementCalls(); len(got) != 0 {
+		t.Fatalf("a scoped caller ran %+v", got)
+	}
+}
+
+func TestPlacementRejectsBadInput(t *testing.T) {
+	r := placementRig(t)
+	tok := r.token("ada", roles.Admin, time.Hour, roles.AllProjects)
+	for _, tc := range []struct{ name, path, body string }{
+		{"unknown field", PathNodesPfx + "n1/labels", `{"argv":["--x"]}`},
+		{"flag as label", PathNodesPfx + "n1/labels", `{"labels":["--coordinator=x"]}`},
+		{"space in label", PathNodesPfx + "n1/labels", `{"labels":["a b"]}`},
+		{"projects on labels", PathNodesPfx + "n1/labels", `{"projects":["p"]}`},
+		{"labels on projects", PathNodesPfx + "n1/projects", `{"action":"add","labels":["x"]}`},
+		{"no action", PathNodesPfx + "n1/projects", `{"projects":["p"]}`},
+		{"bad action", PathNodesPfx + "n1/projects", `{"action":"list"}`},
+		{"directory as project", PathNodesPfx + "n1/projects", `{"action":"add","projects":["../x"]}`},
+		{"all on labels", PathNodesPfx + "n1/labels", `{"all":true}`},
+		{"bad node id", PathNodesPfx + "..%2fx/labels", `{}`},
+		{"too many", PathNodesPfx + "n1/labels", `{"labels":["` + strings.Repeat(`a","`, maxPlacementItems) + `a"]}`},
+		{"not json", PathNodesPfx + "n1/labels", `{`},
+		{"trailing data", PathNodesPfx + "n1/labels", `{} {}`},
+		{"too long", PathNodesPfx + "n1/labels", `{"labels":["` + strings.Repeat("a", maxPlacementBody) + `"]}`},
+	} {
+		st, b := r.do(r.client(), "POST", tc.path, tok, tc.body)
+		if st != 400 && st != 404 {
+			t.Errorf("%s: got %d %s", tc.name, st, b)
+		}
+	}
+	if got := placementCalls(); len(got) != 0 {
+		t.Fatalf("bad input reached the runner: %+v", got)
+	}
+}
diff --git a/free/ci/internal/coordinator/clientapi/stats_route.go b/free/ci/internal/coordinator/clientapi/stats_route.go
new file mode 100644
index 000000000..86d925f23
--- /dev/null
+++ b/free/ci/internal/coordinator/clientapi/stats_route.go
@@ -0,0 +1,114 @@
+package clientapi
+
+// Purpose: GET /v1/stats (P7-SCHED-20, Epic SCHED D23): contract:ci.stats v1 over the user API, the read
+// behind `nself ci runs stats --coordinator <url>`. Needs the member role; the document covers only the
+// projects the caller may read, and the blocks that carry no project (nodes, status outbox, store size) only
+// for a caller who may read the whole coordinator.
+// Inputs:  ?since=<duration, default 24h, at most 90d> and ?project=<owner/repo>.
+// Outputs: the stats document as JSON; E664 on refusal.
+// Constraints: read only; a project the caller may not read is refused with the usual role error; the
+//          document is built by internal/stats from one read transaction, the same code the local command
+//          runs, so both paths print one shape; the store is the one NSELF_CI_HOME names unless the serve
+//          hands its own through SetStatsSource.
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+	"github.com/nself-org/plugins/free/ci/internal/stats"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// PathStats is the stats route.
+const PathStats = "/v1/stats"
+
+// MaxStatsSince bounds the window a client may ask for.
+const MaxStatsSince = 90 * 24 * time.Hour
+
+// StatsSource builds the document for the options the route derived from the caller.
+type StatsSource func(ctx context.Context, o stats.Options) (stats.Doc, error)
+
+var (
+	statsMu  sync.Mutex
+	statsSrc StatsSource = localStats
+)
+
+// SetStatsSource replaces the document source (the serve hands in its own store); nil restores the default.
+func SetStatsSource(s StatsSource) {
+	statsMu.Lock()
+	defer statsMu.Unlock()
+	if s == nil {
+		s = localStats
+	}
+	statsSrc = s
+}
+
+func localStats(ctx context.Context, o stats.Options) (stats.Doc, error) {
+	st, err := store.Open("", store.Options{})
+	if err != nil {
+		return stats.Doc{}, err
+	}
+	defer func() { _ = st.Close() }()
+	return stats.Compute(ctx, st, o)
+}
+
+func init() {
+	if err := RegisterRoute(http.MethodGet, PathStats, string(roles.Member), http.HandlerFunc(serveStats)); err != nil {
+		panic(err)
+	}
+}
+
+// ParseSince reads a window: a Go duration, or whole days as "7d". Empty is the default.
+func ParseSince(v string) (time.Duration, error) {
+	if v == "" {
+		return stats.DefaultSince, nil
+	}
+	d, err := time.ParseDuration(v)
+	if n, ok := strings.CutSuffix(v, "d"); err != nil && ok {
+		days, perr := strconv.Atoi(n)
+		d, err = time.Duration(days)*24*time.Hour, perr
+	}
+	if err != nil || d <= 0 || d > MaxStatsSince {
+		return 0, Failf(ReasonBadRequest, "since must be a duration between 1s and 90d")
+	}
+	return d, nil
+}
+
+func serveStats(w http.ResponseWriter, r *http.Request) {
+	actor, ok := ActorFrom(r.Context())
+	if !ok {
+		errServer.fail(w, Failf(ReasonInternal, "no caller"))
+		return
+	}
+	since, err := ParseSince(r.URL.Query().Get("since"))
+	project := r.URL.Query().Get("project")
+	switch {
+	case err != nil:
+		errServer.fail(w, err)
+		return
+	case project != "" && !coordinator.ValidProject(project):
+		errServer.fail(w, Failf(ReasonBadRequest, "project must be owner/repo"))
+		return
+	case project != "":
+		if err = actor.Can(roles.Member, project); err != nil {
+			errServer.fail(w, err)
+			return
+		}
+	}
+	statsMu.Lock()
+	src := statsSrc
+	statsMu.Unlock()
+	doc, err := src(r.Context(), stats.Options{Now: time.Now(), Since: since, Project: project, Global: wholeCoordinator(actor),
+		Allow: func(p string) bool { return actor.Can(roles.Member, p) == nil }})
+	if err != nil {
+		errServer.fail(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, doc)
+}
diff --git a/free/ci/internal/coordinator/clientapi/stats_route_test.go b/free/ci/internal/coordinator/clientapi/stats_route_test.go
new file mode 100644
index 000000000..e7cb04e37
--- /dev/null
+++ b/free/ci/internal/coordinator/clientapi/stats_route_test.go
@@ -0,0 +1,88 @@
+package clientapi
+
+// Purpose: tests of GET /v1/stats (P7-SCHED-20): the member role is enough, a scoped caller gets an Allow
+// that admits only the projects it may read and no coordinator-wide view, an all-project caller does, a
+// project the caller may not read is refused with the role error, and bad windows and projects are 400.
+// Inputs:  the rig of rig_test.go and a recording StatsSource. Outputs: pass or fail.
+// Constraints: the route registers once per process from init; real TLS on 127.0.0.1.
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+	"github.com/nself-org/plugins/free/ci/internal/stats"
+)
+
+type statsSeen struct {
+	sync.Mutex
+	opts stats.Options
+}
+
+func statsRig(t *testing.T) (*rig, *statsSeen) {
+	t.Helper()
+	seen := &statsSeen{}
+	SetStatsSource(func(_ context.Context, o stats.Options) (stats.Doc, error) {
+		seen.Lock()
+		defer seen.Unlock()
+		seen.opts = o
+		return stats.Doc{Contract: stats.Contract, Version: stats.Version, SinceMs: o.Since.Milliseconds()}, nil
+	})
+	t.Cleanup(func() { SetStatsSource(nil) })
+	return newRig(t), seen
+}
+
+func TestStatsRouteScopesTheDocumentToTheCaller(t *testing.T) {
+	r, seen := statsRig(t)
+	c := r.client()
+	scoped := r.token("mia", roles.Member, time.Hour, "acme/app")
+	status, body := r.do(c, http.MethodGet, PathStats+"?since=6h", scoped, "")
+	var doc stats.Doc
+	if status != 200 || json.Unmarshal(body, &doc) != nil || doc.Contract != "ci.stats" || doc.SinceMs != 6*3600*1000 {
+		t.Fatalf("scoped member: %d %s", status, body)
+	}
+	if seen.opts.Global || !seen.opts.Allow("acme/app") || seen.opts.Allow("acme/other") {
+		t.Errorf("a scoped caller must see only its project and nothing coordinator-wide: global=%v", seen.opts.Global)
+	}
+	all := r.token("ops", roles.Member, time.Hour, roles.AllProjects)
+	if status, body = r.do(c, http.MethodGet, PathStats, all, ""); status != 200 || !seen.opts.Global || seen.opts.Since != 24*time.Hour {
+		t.Fatalf("all-project member: %d %s global=%v since=%s", status, body, seen.opts.Global, seen.opts.Since)
+	}
+}
+
+func TestStatsRouteRefusals(t *testing.T) {
+	r, seen := statsRig(t)
+	c := r.client()
+	scoped := r.token("mia", roles.Member, time.Hour, "acme/app")
+	if status, body := r.do(c, http.MethodGet, PathStats+"?project="+url.QueryEscape("acme/other"), scoped, ""); status == 200 {
+		t.Fatalf("a project the caller may not read was served: %s", body)
+	}
+	if status, body := r.do(c, http.MethodGet, PathStats+"?project=acme/app", scoped, ""); status != 200 || seen.opts.Project != "acme/app" {
+		t.Fatalf("own project: %d %s", status, body)
+	}
+	for _, q := range []string{"?since=banana", "?since=0s", "?since=91d", "?project=not-a-project"} {
+		status, body := r.do(c, http.MethodGet, PathStats+q, scoped, "")
+		refused(t, status, body, http.StatusBadRequest, ReasonBadRequest)
+	}
+	if status, _ := r.do(c, http.MethodGet, PathStats, "", ""); status == 200 {
+		t.Error("an anonymous caller was served")
+	}
+}
+
+func TestParseSince(t *testing.T) {
+	for in, want := range map[string]time.Duration{"": 24 * time.Hour, "90m": 90 * time.Minute, "7d": 7 * 24 * time.Hour, "2160h": MaxStatsSince} {
+		if got, err := ParseSince(in); err != nil || got != want {
+			t.Errorf("ParseSince(%q) = %v, %v; want %v", in, got, err, want)
+		}
+	}
+	for _, in := range []string{"-1h", "0", "xd", "100d", "1.5"} {
+		if _, err := ParseSince(in); err == nil {
+			t.Errorf("ParseSince(%q) accepted", in)
+		}
+	}
+}
diff --git a/free/ci/internal/demand/demand_test.go b/free/ci/internal/demand/demand_test.go
new file mode 100644
index 000000000..800b70bf4
--- /dev/null
+++ b/free/ci/internal/demand/demand_test.go
@@ -0,0 +1,173 @@
+package demand
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+type fakeClock struct {
+	now time.Time
+}
+
+func (f *fakeClock) Now() time.Time { return f.now }
+
+func TestDemandAtomicWrite(t *testing.T) {
+	dir := t.TempDir()
+	fc := &fakeClock{now: time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)}
+	cfg := WriterConfig{Dir: dir, Host: "test-host", Clock: fc}
+	doc := Document{
+		Queued:   3,
+		Held:     1,
+		Running:  2,
+		Ready:    true,
+		ReadyWhy: []string{},
+		Watcher: Watcher{
+			Alive:       true,
+			LastPass:    fc.now.Format(time.RFC3339),
+			IntervalSec: 30,
+		},
+	}
+	if err := Write(cfg, doc); err != nil {
+		t.Fatalf("Write failed: %v", err)
+	}
+	target := filepath.Join(dir, fileName)
+	info, err := os.Stat(target)
+	if err != nil {
+		t.Fatalf("stat target: %v", err)
+	}
+	if perm := info.Mode().Perm(); perm != fileMode {
+		t.Errorf("file mode = %o, want %o", perm, fileMode)
+	}
+	data, err := os.ReadFile(target)
+	if err != nil {
+		t.Fatalf("read target: %v", err)
+	}
+	var got Document
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if got.TS != fc.now.Format(time.RFC3339) {
+		t.Errorf("TS = %q, want %q", got.TS, fc.now.Format(time.RFC3339))
+	}
+	if got.Host != "test-host" {
+		t.Errorf("Host = %q, want %q", got.Host, "test-host")
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("readdir: %v", err)
+	}
+	for _, e := range entries {
+		if strings.HasPrefix(e.Name(), ".demand-") && strings.HasSuffix(e.Name(), ".tmp") {
+			t.Errorf("temp file left behind: %s", e.Name())
+		}
+	}
+}
+
+func TestDemandWhenNotReady(t *testing.T) {
+	dir := t.TempDir()
+	fc := &fakeClock{now: time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)}
+	cfg := WriterConfig{Dir: dir, Host: "not-ready-host", Clock: fc}
+	doc := Document{
+		Queued:   5,
+		Held:     0,
+		Running:  0,
+		Ready:    false,
+		ReadyWhy: []string{"provider unavailable"},
+		Watcher: Watcher{
+			Alive:       true,
+			LastPass:    fc.now.Format(time.RFC3339),
+			IntervalSec: 30,
+		},
+	}
+	if err := Write(cfg, doc); err != nil {
+		t.Fatalf("Write failed: %v", err)
+	}
+	snap, err := Read(ReadConfig{Dir: dir, Clock: fc})
+	if err != nil {
+		t.Fatalf("Read failed: %v", err)
+	}
+	if snap.Doc.Ready {
+		t.Error("expected Ready=false")
+	}
+	if len(snap.Doc.ReadyWhy) != 1 || snap.Doc.ReadyWhy[0] != "provider unavailable" {
+		t.Errorf("ReadyWhy = %v, want [provider unavailable]", snap.Doc.ReadyWhy)
+	}
+	if snap.Doc.Queued != 5 {
+		t.Errorf("Queued = %d, want 5", snap.Doc.Queued)
+	}
+}
+
+func TestDemandReadAge(t *testing.T) {
+	dir := t.TempDir()
+	writeTime := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+	readTime := writeTime.Add(45 * time.Second)
+	wc := WriterConfig{Dir: dir, Host: "age-host", Clock: &fakeClock{now: writeTime}}
+	doc := Document{
+		Queued:   0,
+		Held:     0,
+		Running:  0,
+		Ready:    true,
+		ReadyWhy: []string{},
+		Watcher: Watcher{
+			Alive:       true,
+			LastPass:    writeTime.Format(time.RFC3339),
+			IntervalSec: 30,
+		},
+	}
+	if err := Write(wc, doc); err != nil {
+		t.Fatalf("Write failed: %v", err)
+	}
+	rc := ReadConfig{Dir: dir, Clock: &fakeClock{now: readTime}}
+	snap, err := Read(rc)
+	if err != nil {
+		t.Fatalf("Read failed: %v", err)
+	}
+	if snap.Age != 45*time.Second {
+		t.Errorf("Age = %v, want 45s", snap.Age)
+	}
+	if !snap.Doc.Watcher.Alive {
+		t.Error("expected Watcher.Alive=true")
+	}
+	missingSnap, err := Read(ReadConfig{Dir: t.TempDir(), Clock: &fakeClock{now: readTime}})
+	if err != nil {
+		t.Fatalf("Read missing failed: %v", err)
+	}
+	if missingSnap.Doc.Watcher.Alive {
+		t.Error("expected Alive=false for missing file")
+	}
+}
+
+func TestDemandNoSensitiveFields(t *testing.T) {
+	dir := t.TempDir()
+	fc := &fakeClock{now: time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)}
+	cfg := WriterConfig{Dir: dir, Host: "safe-host", Clock: fc}
+	doc := Document{
+		Queued:   0,
+		Held:     0,
+		Running:  0,
+		Ready:    true,
+		ReadyWhy: []string{},
+		Watcher: Watcher{
+			Alive:       true,
+			LastPass:    fc.now.Format(time.RFC3339),
+			IntervalSec: 30,
+		},
+	}
+	if err := Write(cfg, doc); err != nil {
+		t.Fatalf("Write failed: %v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, fileName))
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	content := string(data)
+	for _, forbidden := range []string{"token", "secret", "password", "/home/", "/var/", "git@"} {
+		if strings.Contains(strings.ToLower(content), forbidden) {
+			t.Errorf("document contains sensitive pattern %q", forbidden)
+		}
+	}
+}
diff --git a/free/ci/internal/demand/doc.go b/free/ci/internal/demand/doc.go
new file mode 100644
index 000000000..bd4b8f6b2
--- /dev/null
+++ b/free/ci/internal/demand/doc.go
@@ -0,0 +1,3 @@
+// Package demand publishes the contract:ci.demand v1 document atomically
+// and provides a reader that tolerates missing or torn files.
+package demand
diff --git a/free/ci/internal/demand/read.go b/free/ci/internal/demand/read.go
new file mode 100644
index 000000000..725f0e1bd
--- /dev/null
+++ b/free/ci/internal/demand/read.go
@@ -0,0 +1,49 @@
+package demand
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// ReadConfig configures reading of the demand document.
+type ReadConfig struct {
+	Dir   string
+	Clock Clock
+}
+
+// Read returns the last complete document and its age.
+// A missing file returns a zero Snapshot with Alive=false and no error.
+func Read(cfg ReadConfig) (Snapshot, error) {
+	if cfg.Dir == "" {
+		return Snapshot{}, fmt.Errorf("demand: empty directory")
+	}
+	if cfg.Clock == nil {
+		cfg.Clock = realClock{}
+	}
+	target := filepath.Join(cfg.Dir, fileName)
+	data, err := os.ReadFile(target)
+	if errors.Is(err, os.ErrNotExist) {
+		return Snapshot{Doc: Document{Watcher: Watcher{Alive: false}}}, nil
+	}
+	if err != nil {
+		return Snapshot{}, fmt.Errorf("demand: read %s: %w", target, err)
+	}
+	var doc Document
+	if err := json.Unmarshal(data, &doc); err != nil {
+		return Snapshot{}, fmt.Errorf("demand: unmarshal %s: %w", target, err)
+	}
+	ts, err := time.Parse(time.RFC3339, doc.TS)
+	if err != nil {
+		return Snapshot{}, fmt.Errorf("demand: parse ts %q: %w", doc.TS, err)
+	}
+	age := cfg.Clock.Now().Sub(ts)
+	if age < 0 {
+		age = 0
+	}
+	doc.Watcher.Alive = true
+	return Snapshot{Doc: doc, Age: age}, nil
+}
diff --git a/free/ci/internal/demand/types.go b/free/ci/internal/demand/types.go
new file mode 100644
index 000000000..79efc0cce
--- /dev/null
+++ b/free/ci/internal/demand/types.go
@@ -0,0 +1,38 @@
+package demand
+
+import "time"
+
+// Document is the contract:ci.demand v1 payload written to disk.
+type Document struct {
+	TS       string   `json:"ts"`
+	Host     string   `json:"host"`
+	Queued   int      `json:"queued"`
+	Held     int      `json:"held"`
+	Running  int      `json:"running"`
+	Ready    bool     `json:"ready"`
+	ReadyWhy []string `json:"ready_why"`
+	Watcher  Watcher  `json:"watcher"`
+}
+
+// Watcher reports liveness and cadence of the watcher loop.
+type Watcher struct {
+	Alive       bool    `json:"alive"`
+	LastPass    string  `json:"last_pass"`
+	IntervalSec float64 `json:"interval_sec"`
+}
+
+// Snapshot is the result of Read, including the document age.
+type Snapshot struct {
+	Doc Document
+	Age time.Duration
+}
+
+// Clock abstracts time for deterministic tests.
+type Clock interface {
+	Now() time.Time
+}
+
+// realClock uses the standard library time.
+type realClock struct{}
+
+func (realClock) Now() time.Time { return time.Now() }
diff --git a/free/ci/internal/demand/write.go b/free/ci/internal/demand/write.go
new file mode 100644
index 000000000..a7ccafc1d
--- /dev/null
+++ b/free/ci/internal/demand/write.go
@@ -0,0 +1,74 @@
+package demand
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+const (
+	fileName = "demand.json"
+	fileMode = 0o600
+	dirMode  = 0o700
+)
+
+// WriterConfig configures atomic publication of the demand document.
+type WriterConfig struct {
+	Dir   string
+	Host  string
+	Clock Clock
+}
+
+// Write publishes doc atomically to Dir/demand.json using temp+rename.
+func Write(cfg WriterConfig, doc Document) error {
+	if cfg.Dir == "" {
+		return fmt.Errorf("demand: empty directory")
+	}
+	if err := os.MkdirAll(cfg.Dir, dirMode); err != nil {
+		return fmt.Errorf("demand: mkdir %s: %w", cfg.Dir, err)
+	}
+	if cfg.Clock == nil {
+		cfg.Clock = realClock{}
+	}
+	doc.TS = cfg.Clock.Now().UTC().Format(time.RFC3339)
+	if doc.Host == "" {
+		doc.Host = cfg.Host
+	}
+	if doc.ReadyWhy == nil {
+		doc.ReadyWhy = []string{}
+	}
+	data, err := json.Marshal(doc)
+	if err != nil {
+		return fmt.Errorf("demand: marshal: %w", err)
+	}
+	target := filepath.Join(cfg.Dir, fileName)
+	tmp, err := os.CreateTemp(cfg.Dir, ".demand-*.tmp")
+	if err != nil {
+		return fmt.Errorf("demand: temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer func() {
+		_ = os.Remove(tmpName)
+	}()
+	if err := tmp.Chmod(fileMode); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("demand: chmod: %w", err)
+	}
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("demand: write: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("demand: sync: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("demand: close: %w", err)
+	}
+	if err := os.Rename(tmpName, target); err != nil {
+		return fmt.Errorf("demand: rename: %w", err)
+	}
+	return nil
+}
diff --git a/free/ci/internal/dispatch/bench_test.go b/free/ci/internal/dispatch/bench_test.go
new file mode 100644
index 000000000..ea1c51804
--- /dev/null
+++ b/free/ci/internal/dispatch/bench_test.go
@@ -0,0 +1,73 @@
+package dispatch
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/planview"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+// BenchmarkAdmit includes the durable world snapshot, digest, placement and
+// admission transaction. Opening the store, queueing and settlement are untimed.
+func BenchmarkAdmit(b *testing.B) {
+	ctx := context.Background()
+	path := filepath.Join(b.TempDir(), "state.db")
+	capability, err := planview.LocalCapability(planview.LocalFacts{
+		Project: "project", Platform: "linux/amd64", CPUs: 8, MemMB: 8192, Now: time.Now(),
+	})
+	if err != nil {
+		b.Fatal(err)
+	}
+	deps := world.Deps{Local: &capability,
+		Policy: func(context.Context, string) (sched.Policy, error) {
+			return sched.Policy{Preset: "balanced"}, nil
+		},
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		b.StopTimer()
+		// Keep snapshot cardinality fixed rather than growing completed history
+		// with b.N. Database creation and deletion are outside the measurement.
+		st, err := store.Open(path, store.Options{})
+		if err != nil {
+			b.Fatal(err)
+		}
+		deps.Store = st
+		id := queueAttempt(b, st, "pipe", "project", "noop")
+		job := testJob(id)
+		deps.Jobs = []sched.Job{job}
+		b.StartTimer()
+		w, digest, err := world.Build(ctx, deps, job.Pipeline)
+		if err != nil {
+			b.Fatal(err)
+		}
+		placed := sched.Place(w, []sched.Job{job})
+		if len(placed.Placements) != 1 || len(w.Runners) != 1 {
+			b.Fatal("local fixture did not place exactly one job")
+		}
+		_, err = Admit(ctx, st, Request{AttemptID: id, Placement: placed.Placements[0],
+			Runner: w.Runners[0], Job: job, Local: true, Host: "bench-host",
+			CapacityCPU: 8, CapacityMemMB: 8192, WorldDigest: digest})
+		if err != nil {
+			b.Fatal(err)
+		}
+		b.StopTimer()
+		pass(b, st, id)
+		if err := st.Close(); err != nil {
+			b.Fatal(err)
+		}
+		for _, suffix := range []string{"", "-wal", "-shm"} {
+			if err := os.Remove(path + suffix); err != nil && !os.IsNotExist(err) {
+				b.Fatal(err)
+			}
+		}
+		b.StartTimer()
+	}
+}
diff --git a/free/ci/internal/dispatch/loop.go b/free/ci/internal/dispatch/loop.go
index a626333a7..41d34a4bb 100644
--- a/free/ci/internal/dispatch/loop.go
+++ b/free/ci/internal/dispatch/loop.go
@@ -3,7 +3,8 @@ package dispatch
 // Purpose: the dispatcher (Epic D7): a queue of attempts waiting for a
 // placement and the tick that places and admits them. A tick runs when a job
 // is enqueued, when a waiter's poll fires (attempt end and lease expiry free
-// capacity without a signal), and every Poll interval (one second in TEAM mode).
+// capacity without a signal unless the caller calls Wake), and every Poll
+// interval (one second in TEAM mode).
 // Inputs:  Config (store, world builder, orderer, sink, transport, clock) and
 // Submit calls, one per attempt, each blocking until its attempt is admitted.
 // Outputs: Admitted attempts; E618 for a foreground job no runner can take;
@@ -98,6 +99,7 @@ type Dispatcher struct {
 	seq      uint64
 	ticked   uint64
 	lastTick time.Time
+	wake     chan struct{} // closed by Wake: the waiters tick now
 }
 
 var (
@@ -187,6 +189,7 @@ func (d *Dispatcher) Submit(ctx context.Context, j Job) (Admitted, error) {
 		return Admitted{}, err
 	}
 	for {
+		wake := d.wakeCh() // taken before due(): a Wake between the two is not lost
 		if d.due() {
 			_ = d.Tick(ctx) // a failed tick leaves the job queued; foreground world errors finish it
 		}
@@ -197,6 +200,7 @@ func (d *Dispatcher) Submit(ctx context.Context, j Job) (Admitted, error) {
 			return d.drop(e, ctx.Err())
 		case <-d.life.Done():
 			return d.drop(e, errClosed)
+		case <-wake:
 		case <-time.After(d.cfg.Poll):
 		}
 	}
diff --git a/free/ci/internal/dispatch/queue.go b/free/ci/internal/dispatch/queue.go
index 904ac8809..ae8e3f8fe 100644
--- a/free/ci/internal/dispatch/queue.go
+++ b/free/ci/internal/dispatch/queue.go
@@ -72,6 +72,30 @@ func (d *Dispatcher) push(j Job, max int64) (*entry, int64, error) {
 	return e, depth, nil
 }
 
+// Wake makes the waiters tick now instead of at their next poll: the caller
+// freed capacity (an attempt ended) that a queued job may be waiting for. On a
+// tiny run the poll was a measured share of every hand-off (P7-CI-46).
+func (d *Dispatcher) Wake() {
+	d.mu.Lock()
+	d.lastTick = time.Time{}
+	ch := d.wake
+	d.wake = nil
+	d.mu.Unlock()
+	if ch != nil {
+		close(ch)
+	}
+}
+
+// wakeCh is the channel the next Wake closes.
+func (d *Dispatcher) wakeCh() <-chan struct{} {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	if d.wake == nil {
+		d.wake = make(chan struct{})
+	}
+	return d.wake
+}
+
 // due reports whether a waiter should tick: something was enqueued since the
 // last tick, or Poll has passed.
 func (d *Dispatcher) due() bool {
diff --git a/free/ci/internal/dispatch/queued_ms_test.go b/free/ci/internal/dispatch/queued_ms_test.go
new file mode 100644
index 000000000..d3546a7cf
--- /dev/null
+++ b/free/ci/internal/dispatch/queued_ms_test.go
@@ -0,0 +1,85 @@
+package dispatch
+
+// Purpose: place fills each job's QueuedMs from its EnqueuedAt at the tick's
+// clock (P7-AUTO-05), so the `auto` tier wait is bounded by real queue age; a
+// job never enqueued, or a clock that went back, reads as no wait at all.
+// Inputs: a two-runner `auto` world whose better tier is busy; a fixed now.
+// Outputs: pass or fail. Constraints: no store, no clock reads.
+
+import (
+	"regexp"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+var msLeftRe = regexp.MustCompile(`: (\d+) ms left of step_sec`)
+
+// autoBusyWorld has a busy runner in the better tier and a free one a tier lower.
+func autoBusyWorld() sched.World {
+	better, worse := testRunner("better", "lan", 0), testRunner("worse", "lan", 1)
+	net := map[string]sched.NetworkFact{}
+	for _, id := range []string{"better", "worse"} {
+		net[id] = sched.NetworkFact{Enforced: []model.NetworkScope{"none", "restricted", "internet"}}
+	}
+	return sched.World{Network: net, Runners: []sched.Runner{better, worse}, Policy: sched.Policy{Preset: sched.AutoPreset},
+		Costs: map[string]sched.Cost{}, Previous: map[string]string{}, Counts: sched.Counts{Runners: map[string]int{}, Providers: map[string]int{}},
+		Bias: map[string]int64{"better": 0, "worse": sched.TierStepMs}}
+}
+
+func TestDispatchFillsQueuedMs(t *testing.T) {
+	now := time.Date(2026, 10, 18, 12, 0, 0, 0, time.UTC)
+	step := sched.DefaultAutoStepSec * 1000
+	cases := []struct {
+		name     string
+		enqueued time.Time
+		placed   bool  // past step_sec: runs on the lower tier
+		left     int64 // otherwise: the wait left that the reason reports
+	}{
+		{"never enqueued reads as no wait", time.Time{}, false, step},
+		{"waited five seconds", now.Add(-5 * time.Second), false, step - 5000},
+		{"a clock that went back never adds wait", now.Add(10 * time.Second), false, step},
+		{"waited past step_sec", now.Add(-time.Duration(step+1000) * time.Millisecond), true, 0},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			q := Queued{Job: testQueued("a1"), EnqueuedAt: c.enqueued}
+			res := place(autoBusyWorld(), []Queued{q}, now)
+			if c.placed {
+				if len(res.Placements) != 1 || res.Placements[0].RunnerID != "worse" {
+					t.Fatalf("a job past step_sec must run on the lower tier: %+v", res)
+				}
+				return
+			}
+			if len(res.Placements) != 0 || len(res.Explanations) != 1 || res.Explanations[0].Status != "waiting" {
+				t.Fatalf("the job must wait for the better tier: %+v", res)
+			}
+			var detail string
+			for _, r := range res.Explanations[0].Reasons {
+				if r.Code == string(model.TierWaiting) {
+					detail = r.Detail
+				}
+			}
+			m := msLeftRe.FindStringSubmatch(detail)
+			if m == nil {
+				t.Fatalf("no tier.waiting detail with the wait left: %+v", res.Explanations[0].Reasons)
+			}
+			if got, _ := strconv.ParseInt(m[1], 10, 64); got != c.left {
+				t.Fatalf("wait left = %d ms, want %d (QueuedMs from EnqueuedAt at now): %s", got, c.left, detail)
+			}
+		})
+	}
+}
+
+// Plan uses the dispatcher's clock, the same path as a tick.
+func TestDispatchPlanFillsQueuedMsFromItsClock(t *testing.T) {
+	now := time.Date(2026, 10, 18, 12, 0, 0, 0, time.UTC)
+	d := &Dispatcher{cfg: Config{Orderer: FIFO{}, Clock: func() time.Time { return now }}}
+	stale := Queued{Job: testQueued("a1"), EnqueuedAt: now.Add(-time.Hour)}
+	if _, res := d.Plan(autoBusyWorld(), []Queued{stale}); len(res.Placements) != 1 || res.Placements[0].RunnerID != "worse" {
+		t.Fatalf("an hour-old job must not wait for the busy tier: %+v", res)
+	}
+}
diff --git a/free/ci/internal/dispatch/tick.go b/free/ci/internal/dispatch/tick.go
index f74b94729..c89659554 100644
--- a/free/ci/internal/dispatch/tick.go
+++ b/free/ci/internal/dispatch/tick.go
@@ -80,7 +80,7 @@ func (d *Dispatcher) Tick(ctx context.Context) error {
 		if pr.err != nil || len(pr.jobs) == 0 {
 			continue
 		}
-		res := place(pr.world, pr.jobs)
+		res := place(pr.world, pr.jobs, now)
 		pr.placed, pr.explained = map[string]sched.Placement{}, map[string]sched.Explanation{}
 		for _, p := range res.Placements {
 			pr.placed[p.JobKey] = p
@@ -123,11 +123,16 @@ func (d *Dispatcher) buildWorlds(ctx context.Context, ordered []Queued) (map[str
 	return runs, first
 }
 
-// place hands every queued job, in the given order, to sched.Place.
-func place(w sched.World, ordered []Queued) sched.Result {
+// place hands every queued job, in the given order, to sched.Place. Each job's
+// QueuedMs is how long it has waited at now (never negative: a clock that went
+// back reads as no wait), so the scheduler itself never reads a clock.
+func place(w sched.World, ordered []Queued, now time.Time) sched.Result {
 	jobs := make([]sched.Job, len(ordered))
 	for i, q := range ordered {
 		jobs[i] = q.Job.Sched
+		if !q.EnqueuedAt.IsZero() {
+			jobs[i].QueuedMs = max(0, now.Sub(q.EnqueuedAt).Milliseconds())
+		}
 	}
 	return sched.Place(w, jobs)
 }
@@ -137,7 +142,7 @@ func place(w sched.World, ordered []Queued) sched.Result {
 // returns are what a tick would try to admit, in that order.
 func (d *Dispatcher) Plan(w sched.World, queued []Queued) ([]Queued, sched.Result) {
 	ordered := d.cfg.Orderer.Order(queued)
-	return ordered, place(w, ordered)
+	return ordered, place(w, ordered, d.cfg.Clock())
 }
 
 // settle admits one job's placement, or explains why it waits, and records the decision.
diff --git a/free/ci/internal/doctor/cli.go b/free/ci/internal/doctor/cli.go
index 5b5c29715..2111cd5ec 100644
--- a/free/ci/internal/doctor/cli.go
+++ b/free/ci/internal/doctor/cli.go
@@ -1,7 +1,7 @@
 package doctor
 
 // Purpose: the logic of `nself ci doctor [--json] [--nodes] [--providers]
-// [--repo DIR]`, kept here with injectable Deps so cmd/doctor.go stays a shim.
+// [--selftest [--alert]] [--repo DIR]`, kept here with injectable Deps so cmd/doctor.go stays a shim.
 // Inputs:  argv after `doctor`, the output writers, Deps.
 // Outputs: a table, or with --json one v1 envelope (contract:cli.json-
 // envelope) whose data is {checks, summary}; exit 0 clean, 10 when a check
@@ -27,6 +27,7 @@ const command = "ci doctor"
 
 type options struct {
 	json, nodes, providers bool
+	selftest, alert        bool
 	repo                   string
 }
 
@@ -36,6 +37,8 @@ func newFlags() (*flag.FlagSet, *options) {
 	fs.BoolVar(&o.json, "json", false, "print one v1 JSON envelope")
 	fs.BoolVar(&o.nodes, "nodes", false, "include the nodes section")
 	fs.BoolVar(&o.providers, "providers", false, "include the providers section")
+	fs.BoolVar(&o.selftest, "selftest", false, "include the selftest checks of an unattended host (CI-DS…)")
+	fs.BoolVar(&o.alert, "alert", false, "with --selftest, send one notifier message a day per failing set")
 	fs.StringVar(&o.repo, "repo", "", "repository root (env NSELF_CI_REPO; default: current directory)")
 	return fs, o
 }
@@ -55,8 +58,8 @@ func Run(args []string, stdout, stderr io.Writer, d Deps) int {
 	if err := fs.Parse(args); err != nil {
 		return 1
 	}
-	if fs.NArg() > 0 {
-		_, _ = fmt.Fprintln(stderr, "usage: nself ci doctor [--json] [--nodes] [--providers] [--repo DIR]")
+	if fs.NArg() > 0 || (o.alert && !o.selftest) {
+		_, _ = fmt.Fprintln(stderr, "usage: nself ci doctor [--json] [--nodes] [--providers] [--selftest [--alert]] [--repo DIR]")
 		return 1
 	}
 	root, err := RepoRoot(o.repo, d)
@@ -69,9 +72,16 @@ func Run(args []string, stdout, stderr io.Writer, d Deps) int {
 	ctx := context.Background()
 	checks := RunLocal(ctx, root, d)
 	env := Env{Root: root, Capture: d.Capture, Getenv: d.Getenv}
-	want := map[string]bool{SelectNodes: o.nodes, SelectProviders: o.providers}
+	want := map[string]bool{SelectNodes: o.nodes, SelectProviders: o.providers, SelectSelftest: o.selftest}
 	checks = append(checks, RunSections(ctx, env, want, SectionBudget)...)
 	sortChecks(checks)
+	if o.alert {
+		if sent, err := alert(ctx, env, checks); err != nil {
+			_, _ = fmt.Fprintln(stderr, "doctor: the alert was not sent:", err)
+		} else if sent != "" && !o.json {
+			_, _ = fmt.Fprintln(stderr, "doctor:", sent)
+		}
+	}
 
 	data := reportData{Checks: checks, Summary: Summarise(checks)}
 	code := ExitCode(checks)
diff --git a/free/ci/internal/doctor/sections.go b/free/ci/internal/doctor/sections.go
index 28f96bb96..750eb6b19 100644
--- a/free/ci/internal/doctor/sections.go
+++ b/free/ci/internal/doctor/sections.go
@@ -23,6 +23,7 @@ const (
 	SelectAlways    = ""
 	SelectNodes     = "nodes"
 	SelectProviders = "providers"
+	SelectSelftest  = "selftest" // CI-DS… (P7-AUTO-20)
 )
 
 // SectionBudget is the time one section may take.
@@ -40,7 +41,7 @@ type Env struct {
 type Section struct {
 	// Name identifies the section; it is unique.
 	Name string
-	// Selector is SelectAlways, SelectNodes or SelectProviders.
+	// Selector is SelectAlways, SelectNodes, SelectProviders or SelectSelftest.
 	Selector string
 	// Run returns the section's checks. It must honour ctx.
 	Run func(ctx context.Context, env Env) []Check
@@ -58,7 +59,7 @@ func RegisterSection(s Section) {
 		panic("doctor: section needs a name and a Run function")
 	}
 	switch s.Selector {
-	case SelectAlways, SelectNodes, SelectProviders:
+	case SelectAlways, SelectNodes, SelectProviders, SelectSelftest:
 	default:
 		panic("doctor: unknown section selector " + s.Selector)
 	}
@@ -85,6 +86,7 @@ func Registered() []Section {
 var noneRegistered = map[string]Check{
 	SelectNodes:     {ID: "CI-D090", Name: "nodes section", Status: Pass, Message: "none registered"},
 	SelectProviders: {ID: "CI-D091", Name: "providers section", Status: Pass, Message: "none registered"},
+	SelectSelftest:  {ID: "CI-D092", Name: "selftest section", Status: Pass, Message: "none registered"},
 }
 
 // RunSections runs the always-on sections plus those whose selector is in
@@ -100,7 +102,7 @@ func RunSections(ctx context.Context, env Env, want map[string]bool, budget time
 		have[s.Selector] = true
 		out = append(out, runOne(ctx, s, env, budget)...)
 	}
-	for _, sel := range []string{SelectNodes, SelectProviders} {
+	for _, sel := range []string{SelectNodes, SelectProviders, SelectSelftest} {
 		if want[sel] && !have[sel] {
 			out = append(out, noneRegistered[sel])
 		}
@@ -150,3 +152,30 @@ func validated(section string, checks []Check) []Check {
 	}
 	return out
 }
+
+// Alerter sends the alert of `doctor --selftest --alert` for the checks of one report. The
+// selftest package supplies it through SetAlerter; this package never imports it.
+type Alerter func(ctx context.Context, env Env, checks []Check) (string, error)
+
+var (
+	alertMu sync.Mutex
+	alerter Alerter
+)
+
+// SetAlerter installs the alerter; nil removes it.
+func SetAlerter(a Alerter) {
+	alertMu.Lock()
+	defer alertMu.Unlock()
+	alerter = a
+}
+
+// alert runs the installed alerter; the string says what it did.
+func alert(ctx context.Context, env Env, checks []Check) (string, error) {
+	alertMu.Lock()
+	a := alerter
+	alertMu.Unlock()
+	if a == nil {
+		return "", fmt.Errorf("no alerter is installed")
+	}
+	return a(ctx, env, checks)
+}
diff --git a/free/ci/internal/evidence/binding.go b/free/ci/internal/evidence/binding.go
index 3ea406ed5..be6fd75a7 100644
--- a/free/ci/internal/evidence/binding.go
+++ b/free/ci/internal/evidence/binding.go
@@ -25,9 +25,13 @@ type Worktree struct {
 }
 
 // ReadWorktree reads the state of root.
+// The status and the hidden-edit listing are independent reads: they run side
+// by side (P7-CI-46), so a clean tree costs one funnel spawn of wall time.
 func ReadWorktree(ctx context.Context, c Capture, root string) Worktree {
+	hidden := make(chan bool, 1)
+	go func() { hidden <- hiddenEdits(ctx, c, root) }()
 	status, ok := git(ctx, c, root, "status", "--porcelain", "--untracked-files=normal")
-	if ok && strings.TrimSpace(status) == "" && !hiddenEdits(ctx, c, root) {
+	if ok && strings.TrimSpace(status) == "" && !<-hidden {
 		return Worktree{}
 	}
 	w := Worktree{Dirty: true}
diff --git a/free/ci/internal/evidence/projection/markdown.go b/free/ci/internal/evidence/projection/markdown.go
new file mode 100644
index 000000000..f27aa09d0
--- /dev/null
+++ b/free/ci/internal/evidence/projection/markdown.go
@@ -0,0 +1,21 @@
+package projection
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Page renders Evidence-Projection.md from the same mapping tables Project
+// reads, so the page cannot list a field the projection lacks.
+func Page() string {
+	var b strings.Builder
+	b.WriteString("<!-- GENERATED BY internal/evidence/projection DO NOT HAND EDIT -->\n")
+	b.WriteString("# Evidence projection `" + Name + "`\n\n")
+	b.WriteString("`projection.Project(doc, \"" + Name + "\")` is a pure function of one `ci.evidence/v1` document. ")
+	b.WriteString("It is a view, not a second schema. A source key that is absent (a document from before the additive keys) or null projects as `null` with a reason.\n\n")
+	b.WriteString("| Projected field | Source key in ci.evidence/v1 |\n|---|---|\n")
+	for _, m := range Mappings() {
+		fmt.Fprintf(&b, "| `%s` | `%s` |\n", m.Field, m.Source)
+	}
+	return b.String()
+}
diff --git a/free/ci/internal/evidence/projection/projection.go b/free/ci/internal/evidence/projection/projection.go
new file mode 100644
index 000000000..b06c0d843
--- /dev/null
+++ b/free/ci/internal/evidence/projection/projection.go
@@ -0,0 +1,152 @@
+// Package projection is the pure function behind `nself-ci/1`: the flat view of
+// a ci.evidence/v1 document that external parsers read. It is not a second
+// schema (AUTO D8): every projected field names the evidence key it comes from,
+// and a key an older document lacks projects as null with a reason.
+package projection
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+// Name is the one projection this package knows.
+const Name = "nself-ci/1"
+
+// Value is one projected field: the value (nil when the source key is absent)
+// and, when nil, why.
+type Value struct {
+	Value  any    `json:"value"`
+	Reason string `json:"reason,omitempty"`
+}
+
+// Projected is the nself-ci/1 view. Fields marshals with sorted keys.
+type Projected struct {
+	Projection string           `json:"projection"`
+	Fields     map[string]Value `json:"fields"`
+}
+
+// Mapping names a projected field and the evidence key path it reads.
+type Mapping struct {
+	Field  string
+	Source string // dotted path; "[]" marks a per-item list
+}
+
+// scalars are read by path from the document, in page order.
+var scalars = []Mapping{
+	{"revision", "revision"},
+	{"run_id", "run_id"},
+	{"result", "result"},
+	{"source_trust", "source_trust"},
+	{"binding", "binding.state"},
+	{"freshness", "freshness.state"},
+	{"runner_id", "runner.id"},
+	{"runner_isolation", "runner.isolation"},
+	{"duration_ms", "timings.duration_ms"},
+	{"checks_total", "counts.total"},
+	{"checks_pass", "counts.pass"},
+	{"checks_fail", "counts.fail"},
+	{"checks_skip", "counts.skip"},
+	{"checks_error", "counts.error"},
+}
+
+// listFields are lists whose items are projected key by key.
+var listFields = []struct {
+	Field string
+	Root  string
+	Items []Mapping // Source is relative to one item
+}{
+	{"attempts", "attempts", []Mapping{
+		{"job_id", "job_id"}, {"attempt", "attempt"},
+		{"runner_kind", "runner.kind"}, {"runner_tier", "runner.tier"}, {"runner_pool", "runner.pool"}, {"runner_rank", "runner.rank"},
+		{"queue_ms", "timings.queue_ms"}, {"transfer_ms", "timings.transfer_ms"}, {"run_ms", "timings.run_ms"},
+	}},
+	{"errors", "errors", []Mapping{{"code", "code"}, {"job_id", "job_id"}, {"attempt", "attempt"}, {"detail", "detail"}}},
+}
+
+// flakySource is the one derived field: the ids of checks carrying `flaky`.
+const flakySource = "checks[].flaky"
+
+// Mappings lists every projected field with its source key, for the generated page.
+func Mappings() []Mapping {
+	out := append([]Mapping(nil), scalars...)
+	for _, l := range listFields {
+		out = append(out, Mapping{l.Field, l.Root + "[]"})
+		for _, m := range l.Items {
+			out = append(out, Mapping{l.Field + "[]." + m.Field, l.Root + "[]." + m.Source})
+		}
+	}
+	return append(out, Mapping{"flaky_checks", flakySource})
+}
+
+// Project reads one ci.evidence/v1 document (any age) and returns its view.
+func Project(doc []byte, name string) (Projected, error) {
+	if name != Name {
+		return Projected{}, fmt.Errorf("projection: unknown projection %q", name)
+	}
+	var root map[string]any
+	if err := json.Unmarshal(doc, &root); err != nil {
+		return Projected{}, fmt.Errorf("projection: not a JSON object: %w", err)
+	}
+	out := Projected{Projection: Name, Fields: map[string]Value{}}
+	for _, m := range scalars {
+		out.Fields[m.Field] = lookup(root, m.Source)
+	}
+	for _, l := range listFields {
+		items, ok := root[l.Root].([]any)
+		if !ok {
+			out.Fields[l.Field] = missing(l.Root)
+			continue
+		}
+		rows := make([]map[string]Value, 0, len(items))
+		for _, it := range items {
+			obj, _ := it.(map[string]any)
+			row := map[string]Value{}
+			for _, m := range l.Items {
+				row[m.Field] = lookup(obj, m.Source)
+			}
+			rows = append(rows, row)
+		}
+		out.Fields[l.Field] = Value{Value: rows}
+	}
+	out.Fields["flaky_checks"] = flaky(root)
+	return out, nil
+}
+
+func missing(path string) Value {
+	return Value{Reason: "source key absent: " + path}
+}
+
+// lookup follows a dotted path; a missing step or a JSON null is nil with a reason.
+func lookup(obj map[string]any, path string) Value {
+	var cur any = obj
+	for _, step := range strings.Split(path, ".") {
+		m, ok := cur.(map[string]any)
+		if !ok {
+			return missing(path)
+		}
+		if cur, ok = m[step]; !ok {
+			return missing(path)
+		}
+	}
+	if cur == nil {
+		return Value{Reason: "source key is null: " + path}
+	}
+	return Value{Value: cur}
+}
+
+func flaky(root map[string]any) Value {
+	checks, ok := root["checks"].([]any)
+	if !ok {
+		return missing("checks")
+	}
+	ids := []string{}
+	for _, c := range checks {
+		m, _ := c.(map[string]any)
+		if m["flaky"] != nil {
+			id, _ := m["id"].(string)
+			ids = append(ids, id)
+		}
+	}
+	return Value{Value: ids}
+}
diff --git a/free/ci/internal/evidence/projection/projection_test.go b/free/ci/internal/evidence/projection/projection_test.go
new file mode 100644
index 000000000..1bc0956aa
--- /dev/null
+++ b/free/ci/internal/evidence/projection/projection_test.go
@@ -0,0 +1,98 @@
+package projection
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden files")
+
+const data = "../testdata"
+
+func readData(t *testing.T, name string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join(data, name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+func golden(t *testing.T, name string, got []byte) {
+	t.Helper()
+	path := filepath.Join(data, name)
+	if *update {
+		if err := os.WriteFile(path, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if want := readData(t, name); string(want) != string(got) {
+		t.Errorf("%s drifted; run go test ./internal/evidence/projection -update\n got: %s", name, got)
+	}
+}
+
+func projectJSON(t *testing.T, doc []byte) []byte {
+	t.Helper()
+	p, err := Project(doc, Name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, err := json.MarshalIndent(p, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return append(b, '\n')
+}
+
+func TestProjectionGolden(t *testing.T) {
+	golden(t, "projected.attempts.json", projectJSON(t, readData(t, "evidence.attempts.json")))
+	golden(t, "Evidence-Projection.md", []byte(Page()))
+	page := Page()
+	for _, m := range Mappings() {
+		if !strings.Contains(page, "| `"+m.Field+"` | `"+m.Source+"` |") {
+			t.Errorf("page lacks %s <- %s", m.Field, m.Source)
+		}
+		if m.Source == "" {
+			t.Errorf("field %s has no source key", m.Field)
+		}
+	}
+	p, _ := Project(readData(t, "evidence.attempts.json"), Name)
+	if _, err := Project(nil, "other/1"); err == nil {
+		t.Error("an unknown projection must be refused")
+	}
+	rows := p.Fields["attempts"].Value.([]map[string]Value)
+	if len(rows) != 3 || rows[1]["runner_kind"].Value != "ssh" || rows[2]["runner_kind"].Value != "hosted" {
+		t.Errorf("attempt rows: %+v", rows)
+	}
+}
+
+func TestProjectionMissingKeys(t *testing.T) {
+	golden(t, "projected.pre-auto21.json", projectJSON(t, readData(t, "evidence.pre-auto21.json")))
+	p, err := Project(readData(t, "evidence.pre-auto21.json"), Name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"attempts", "errors"} {
+		v := p.Fields[f]
+		if v.Value != nil || !strings.HasPrefix(v.Reason, "source key absent") {
+			t.Errorf("%s: %+v", f, v)
+		}
+	}
+	if v := p.Fields["duration_ms"]; v.Value != nil || !strings.Contains(v.Reason, "null") {
+		t.Errorf("duration_ms: %+v", v)
+	}
+	if v := p.Fields["result"]; v.Value != "pass" || v.Reason != "" {
+		t.Errorf("result: %+v", v)
+	}
+	// an empty object and a non-object must not panic
+	if _, err := Project([]byte(`{}`), Name); err != nil {
+		t.Error(err)
+	}
+	if _, err := Project([]byte(`[]`), Name); err == nil {
+		t.Error("a non-object must be an error")
+	}
+}
diff --git a/free/ci/internal/evidence/service.go b/free/ci/internal/evidence/service.go
index de635fd51..6ae48def2 100644
--- a/free/ci/internal/evidence/service.go
+++ b/free/ci/internal/evidence/service.go
@@ -268,7 +268,7 @@ func (env Env) recorded(ctx context.Context) func(model.Evidence) *model.Evidenc
 		if err != nil || len(docs) == 0 {
 			return nil
 		}
-		return &docs[0].Evidence
+		return &docs[matchingDoc(ev, docs)].Evidence
 	}
 }
 
diff --git a/free/ci/internal/evidence/testdata/Evidence-Projection.md b/free/ci/internal/evidence/testdata/Evidence-Projection.md
new file mode 100644
index 000000000..a659f04dd
--- /dev/null
+++ b/free/ci/internal/evidence/testdata/Evidence-Projection.md
@@ -0,0 +1,37 @@
+<!-- GENERATED BY internal/evidence/projection DO NOT HAND EDIT -->
+# Evidence projection `nself-ci/1`
+
+`projection.Project(doc, "nself-ci/1")` is a pure function of one `ci.evidence/v1` document. It is a view, not a second schema. A source key that is absent (a document from before the additive keys) or null projects as `null` with a reason.
+
+| Projected field | Source key in ci.evidence/v1 |
+|---|---|
+| `revision` | `revision` |
+| `run_id` | `run_id` |
+| `result` | `result` |
+| `source_trust` | `source_trust` |
+| `binding` | `binding.state` |
+| `freshness` | `freshness.state` |
+| `runner_id` | `runner.id` |
+| `runner_isolation` | `runner.isolation` |
+| `duration_ms` | `timings.duration_ms` |
+| `checks_total` | `counts.total` |
+| `checks_pass` | `counts.pass` |
+| `checks_fail` | `counts.fail` |
+| `checks_skip` | `counts.skip` |
+| `checks_error` | `counts.error` |
+| `attempts` | `attempts[]` |
+| `attempts[].job_id` | `attempts[].job_id` |
+| `attempts[].attempt` | `attempts[].attempt` |
+| `attempts[].runner_kind` | `attempts[].runner.kind` |
+| `attempts[].runner_tier` | `attempts[].runner.tier` |
+| `attempts[].runner_pool` | `attempts[].runner.pool` |
+| `attempts[].runner_rank` | `attempts[].runner.rank` |
+| `attempts[].queue_ms` | `attempts[].timings.queue_ms` |
+| `attempts[].transfer_ms` | `attempts[].timings.transfer_ms` |
+| `attempts[].run_ms` | `attempts[].timings.run_ms` |
+| `errors` | `errors[]` |
+| `errors[].code` | `errors[].code` |
+| `errors[].job_id` | `errors[].job_id` |
+| `errors[].attempt` | `errors[].attempt` |
+| `errors[].detail` | `errors[].detail` |
+| `flaky_checks` | `checks[].flaky` |
diff --git a/free/ci/internal/evidence/testdata/evidence.attempts.json b/free/ci/internal/evidence/testdata/evidence.attempts.json
new file mode 100644
index 000000000..db23fc15a
--- /dev/null
+++ b/free/ci/internal/evidence/testdata/evidence.attempts.json
@@ -0,0 +1,133 @@
+{
+  "artifacts": [],
+  "attempts": [
+    {
+      "attempt": 1,
+      "job_id": "build",
+      "runner": {
+        "kind": "local",
+        "pool": "personal",
+        "rank": 0,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 0,
+        "run_ms": 1200
+      }
+    },
+    {
+      "attempt": 1,
+      "job_id": "test",
+      "runner": {
+        "kind": "ssh",
+        "pool": "lab",
+        "rank": 1,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 40,
+        "run_ms": 9000,
+        "transfer_ms": 350
+      }
+    },
+    {
+      "attempt": 2,
+      "job_id": "test",
+      "runner": {
+        "kind": "hosted",
+        "pool": "github",
+        "rank": 2,
+        "tier": "hosted"
+      },
+      "timings": {
+        "queue_ms": 2500,
+        "run_ms": 8000,
+        "transfer_ms": 0
+      }
+    }
+  ],
+  "binding": {
+    "reason": null,
+    "state": "bound"
+  },
+  "checks": [
+    {
+      "excerpt": "",
+      "findings": 0,
+      "id": "lint",
+      "job_id": "build",
+      "kind": "quality",
+      "log_ref": null,
+      "required": true,
+      "result": "pass",
+      "substantive": true,
+      "tool": "go",
+      "tool_version": null
+    }
+  ],
+  "counts": {
+    "error": 0,
+    "fail": 0,
+    "pass": 1,
+    "skip": 0,
+    "total": 1
+  },
+  "errors": [
+    {
+      "attempt": 1,
+      "code": "CI-INFRA-OOM",
+      "detail": "runner out of memory",
+      "job_id": "test"
+    }
+  ],
+  "freshness": {
+    "reason": null,
+    "state": "current"
+  },
+  "input_digests": {
+    "config": "abc",
+    "generated": [],
+    "lockfiles": []
+  },
+  "pipeline": {
+    "id": "p1",
+    "kind": "default",
+    "name": "default"
+  },
+  "policy_digest": "abc",
+  "producer": {
+    "kind": "coordinator-recorded",
+    "version": "1.5.0"
+  },
+  "repo_id": "local:abc",
+  "result": "pass",
+  "retries": [],
+  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "run_id": "r1",
+  "runner": {
+    "id": "local",
+    "isolation": "process",
+    "platform": "darwin/arm64",
+    "provider": "local"
+  },
+  "schema": "ci.evidence/v1",
+  "selection": {
+    "digest": "abc",
+    "mode": "affected",
+    "reason": "selection.affected"
+  },
+  "signature": {
+    "kind": "coordinator-recorded"
+  },
+  "source_trust": "owner",
+  "timings": {
+    "duration_ms": null,
+    "finished_at": null,
+    "queued_at": null,
+    "started_at": null
+  },
+  "tool_versions": {},
+  "tracked_changes_digest": null,
+  "trigger": "local",
+  "worktree_state": "clean"
+}
diff --git a/free/ci/internal/evidence/testdata/evidence.pre-auto21.json b/free/ci/internal/evidence/testdata/evidence.pre-auto21.json
new file mode 100644
index 000000000..98602cf5d
--- /dev/null
+++ b/free/ci/internal/evidence/testdata/evidence.pre-auto21.json
@@ -0,0 +1,79 @@
+{
+  "artifacts": [],
+  "binding": {
+    "reason": null,
+    "state": "bound"
+  },
+  "checks": [
+    {
+      "excerpt": "",
+      "findings": 0,
+      "id": "lint",
+      "job_id": "build",
+      "kind": "quality",
+      "log_ref": null,
+      "required": true,
+      "result": "pass",
+      "substantive": true,
+      "tool": "go",
+      "tool_version": null
+    }
+  ],
+  "counts": {
+    "error": 0,
+    "fail": 0,
+    "pass": 1,
+    "skip": 0,
+    "total": 1
+  },
+  "freshness": {
+    "reason": null,
+    "state": "current"
+  },
+  "input_digests": {
+    "config": "abc",
+    "generated": [],
+    "lockfiles": []
+  },
+  "pipeline": {
+    "id": "p1",
+    "kind": "default",
+    "name": "default"
+  },
+  "policy_digest": "abc",
+  "producer": {
+    "kind": "coordinator-recorded",
+    "version": "1.5.0"
+  },
+  "repo_id": "local:abc",
+  "result": "pass",
+  "retries": [],
+  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "run_id": "r1",
+  "runner": {
+    "id": "local",
+    "isolation": "process",
+    "platform": "darwin/arm64",
+    "provider": "local"
+  },
+  "schema": "ci.evidence/v1",
+  "selection": {
+    "digest": "abc",
+    "mode": "affected",
+    "reason": "selection.affected"
+  },
+  "signature": {
+    "kind": "coordinator-recorded"
+  },
+  "source_trust": "owner",
+  "timings": {
+    "duration_ms": null,
+    "finished_at": null,
+    "queued_at": null,
+    "started_at": null
+  },
+  "tool_versions": {},
+  "tracked_changes_digest": null,
+  "trigger": "local",
+  "worktree_state": "clean"
+}
diff --git a/free/ci/internal/evidence/testdata/projected.attempts.json b/free/ci/internal/evidence/testdata/projected.attempts.json
new file mode 100644
index 000000000..08111b006
--- /dev/null
+++ b/free/ci/internal/evidence/testdata/projected.attempts.json
@@ -0,0 +1,161 @@
+{
+  "projection": "nself-ci/1",
+  "fields": {
+    "attempts": {
+      "value": [
+        {
+          "attempt": {
+            "value": 1
+          },
+          "job_id": {
+            "value": "build"
+          },
+          "queue_ms": {
+            "value": 0
+          },
+          "run_ms": {
+            "value": 1200
+          },
+          "runner_kind": {
+            "value": "local"
+          },
+          "runner_pool": {
+            "value": "personal"
+          },
+          "runner_rank": {
+            "value": 0
+          },
+          "runner_tier": {
+            "value": "owner"
+          },
+          "transfer_ms": {
+            "value": null,
+            "reason": "source key absent: timings.transfer_ms"
+          }
+        },
+        {
+          "attempt": {
+            "value": 1
+          },
+          "job_id": {
+            "value": "test"
+          },
+          "queue_ms": {
+            "value": 40
+          },
+          "run_ms": {
+            "value": 9000
+          },
+          "runner_kind": {
+            "value": "ssh"
+          },
+          "runner_pool": {
+            "value": "lab"
+          },
+          "runner_rank": {
+            "value": 1
+          },
+          "runner_tier": {
+            "value": "owner"
+          },
+          "transfer_ms": {
+            "value": 350
+          }
+        },
+        {
+          "attempt": {
+            "value": 2
+          },
+          "job_id": {
+            "value": "test"
+          },
+          "queue_ms": {
+            "value": 2500
+          },
+          "run_ms": {
+            "value": 8000
+          },
+          "runner_kind": {
+            "value": "hosted"
+          },
+          "runner_pool": {
+            "value": "github"
+          },
+          "runner_rank": {
+            "value": 2
+          },
+          "runner_tier": {
+            "value": "hosted"
+          },
+          "transfer_ms": {
+            "value": 0
+          }
+        }
+      ]
+    },
+    "binding": {
+      "value": "bound"
+    },
+    "checks_error": {
+      "value": 0
+    },
+    "checks_fail": {
+      "value": 0
+    },
+    "checks_pass": {
+      "value": 1
+    },
+    "checks_skip": {
+      "value": 0
+    },
+    "checks_total": {
+      "value": 1
+    },
+    "duration_ms": {
+      "value": null,
+      "reason": "source key is null: timings.duration_ms"
+    },
+    "errors": {
+      "value": [
+        {
+          "attempt": {
+            "value": 1
+          },
+          "code": {
+            "value": "CI-INFRA-OOM"
+          },
+          "detail": {
+            "value": "runner out of memory"
+          },
+          "job_id": {
+            "value": "test"
+          }
+        }
+      ]
+    },
+    "flaky_checks": {
+      "value": []
+    },
+    "freshness": {
+      "value": "current"
+    },
+    "result": {
+      "value": "pass"
+    },
+    "revision": {
+      "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "run_id": {
+      "value": "r1"
+    },
+    "runner_id": {
+      "value": "local"
+    },
+    "runner_isolation": {
+      "value": "process"
+    },
+    "source_trust": {
+      "value": "owner"
+    }
+  }
+}
diff --git a/free/ci/internal/evidence/testdata/projected.pre-auto21.json b/free/ci/internal/evidence/testdata/projected.pre-auto21.json
new file mode 100644
index 000000000..1a62e7020
--- /dev/null
+++ b/free/ci/internal/evidence/testdata/projected.pre-auto21.json
@@ -0,0 +1,59 @@
+{
+  "projection": "nself-ci/1",
+  "fields": {
+    "attempts": {
+      "value": null,
+      "reason": "source key absent: attempts"
+    },
+    "binding": {
+      "value": "bound"
+    },
+    "checks_error": {
+      "value": 0
+    },
+    "checks_fail": {
+      "value": 0
+    },
+    "checks_pass": {
+      "value": 1
+    },
+    "checks_skip": {
+      "value": 0
+    },
+    "checks_total": {
+      "value": 1
+    },
+    "duration_ms": {
+      "value": null,
+      "reason": "source key is null: timings.duration_ms"
+    },
+    "errors": {
+      "value": null,
+      "reason": "source key absent: errors"
+    },
+    "flaky_checks": {
+      "value": []
+    },
+    "freshness": {
+      "value": "current"
+    },
+    "result": {
+      "value": "pass"
+    },
+    "revision": {
+      "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "run_id": {
+      "value": "r1"
+    },
+    "runner_id": {
+      "value": "local"
+    },
+    "runner_isolation": {
+      "value": "process"
+    },
+    "source_trust": {
+      "value": "owner"
+    }
+  }
+}
diff --git a/free/ci/internal/evidence/verify.go b/free/ci/internal/evidence/verify.go
index 40afe45fb..aeaaf622d 100644
--- a/free/ci/internal/evidence/verify.go
+++ b/free/ci/internal/evidence/verify.go
@@ -213,6 +213,17 @@ func sameDocument(a, b model.Evidence) bool {
 	return errA == nil && errB == nil && string(x) == string(y)
 }
 
+// matchingDoc is the index of the stored document of a run that equals ev, else 0 (the newest).
+// A dev run also stores the pools.record refusal copy, so a run can hold more than one genuine document.
+func matchingDoc(ev model.Evidence, docs []Stored) int {
+	for i := range docs {
+		if sameDocument(ev, docs[i].Evidence) {
+			return i
+		}
+	}
+	return 0
+}
+
 // MissingInputs lists the lockfile and generated paths the document binds
 // that do not exist in the tree of the revision.
 func MissingInputs(ev model.Evidence, tree fs.FS) []string {
diff --git a/free/ci/internal/exec/capacity.go b/free/ci/internal/exec/capacity.go
index 316c7b763..600b172f7 100644
--- a/free/ci/internal/exec/capacity.go
+++ b/free/ci/internal/exec/capacity.go
@@ -4,7 +4,6 @@ import (
 	"bufio"
 	"bytes"
 	"os"
-	osexec "os/exec"
 	"runtime"
 	"strconv"
 	"strings"
@@ -120,46 +119,3 @@ func probeLinux(c *Capacity) {
 		}
 	}
 }
-
-func probeDarwin(c *Capacity) {
-	if out, err := osexec.Command("sysctl", "-n", "hw.memsize").Output(); err == nil {
-		n, _ := strconv.ParseInt(strings.TrimSpace(string(out)), 10, 64)
-		c.MemoryMB = int(n / (1024 * 1024))
-	}
-	if out, err := osexec.Command("vm_stat").Output(); err == nil {
-		pageSize := int64(4096)
-		var pages int64
-		for _, line := range strings.Split(string(out), "\n") {
-			if strings.Contains(line, "page size of") {
-				f := strings.Fields(line)
-				for i, v := range f {
-					if v == "of" && i+1 < len(f) {
-						pageSize, _ = strconv.ParseInt(f[i+1], 10, 64)
-					}
-				}
-			}
-			if strings.HasPrefix(line, "Pages free:") || strings.HasPrefix(line, "Pages inactive:") || strings.HasPrefix(line, "Pages speculative:") {
-				f := strings.Fields(line)
-				if len(f) > 0 {
-					n, _ := strconv.ParseInt(strings.TrimSuffix(f[len(f)-1], "."), 10, 64)
-					pages += n
-				}
-			}
-		}
-		c.FreeMemoryMB = int(pages * pageSize / (1024 * 1024))
-	}
-	if out, err := osexec.Command("pmset", "-g", "batt").Output(); err == nil {
-		s := string(out)
-		c.PluggedIn = strings.Contains(s, "AC Power")
-		for _, field := range strings.Fields(s) {
-			if strings.HasSuffix(field, "%;") || strings.HasSuffix(field, "%") {
-				n, _ := strconv.Atoi(strings.TrimSuffix(strings.TrimSuffix(field, ";"), "%"))
-				c.BatteryPercent = n
-				break
-			}
-		}
-	}
-	if out, err := osexec.Command("pmset", "-g", "custom").Output(); err == nil {
-		c.LowPower = strings.Contains(string(out), "lowpowermode 1")
-	}
-}
diff --git a/free/ci/internal/exec/capacity_darwin.go b/free/ci/internal/exec/capacity_darwin.go
new file mode 100644
index 000000000..f8b878e55
--- /dev/null
+++ b/free/ci/internal/exec/capacity_darwin.go
@@ -0,0 +1,132 @@
+//go:build darwin
+
+package exec
+
+// Purpose: the macOS half of the capacity probe (P7-CI-32): total memory, free
+// memory and power state.
+// Inputs:  the hw.memsize sysctl, vm_stat and pmset.
+// Outputs: the memory and power fields of a Capacity.
+// Constraints: a run probes once per admission and once per dispatcher tick
+// (P7-CI-46 measured four child processes, about 17 ms, every time), so the
+// total memory is read once with a sysctl (no fork), free memory is cached for
+// freeMemoryTTL and the power state for powerTTL, and the two pmset calls and
+// vm_stat run side by side when they are due. Neither value moves at the
+// rate a run asks for it; the store's reservation ledger, not this snapshot,
+// is what keeps two admissions from taking the same memory.
+
+import (
+	osexec "os/exec"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+const (
+	freeMemoryTTL = 250 * time.Millisecond
+	powerTTL      = 30 * time.Second
+)
+
+// darwinPower is the parsed pmset state; battery is -1 when pmset names none.
+type darwinPower struct {
+	battery      int
+	plugged, low bool
+}
+
+var darwinProbe struct {
+	mu      sync.Mutex
+	memMB   int
+	memRead bool
+	freeMB  int
+	freeAt  time.Time
+	power   darwinPower
+	powerAt time.Time
+}
+
+func probeDarwin(c *Capacity) {
+	p := &darwinProbe
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	now := time.Now()
+	if !p.memRead {
+		if n, err := unix.SysctlUint64("hw.memsize"); err == nil {
+			p.memMB = int(n / (1024 * 1024))
+		}
+		p.memRead = true
+	}
+	var wg sync.WaitGroup
+	if p.freeAt.IsZero() || now.Sub(p.freeAt) >= freeMemoryTTL {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			p.freeMB = 0
+			if out, err := osexec.Command("vm_stat").Output(); err == nil {
+				p.freeMB = parseVMStat(string(out))
+			}
+		}()
+		p.freeAt = now
+	}
+	if p.powerAt.IsZero() || now.Sub(p.powerAt) >= powerTTL {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			p.power = readPower()
+		}()
+		p.powerAt = now
+	}
+	wg.Wait()
+	c.MemoryMB, c.FreeMemoryMB = p.memMB, p.freeMB
+	c.BatteryPercent, c.PluggedIn, c.LowPower = p.power.battery, p.power.plugged, p.power.low
+}
+
+// parseVMStat is free + inactive + speculative pages, in MB.
+func parseVMStat(out string) int {
+	pageSize := int64(4096)
+	var pages int64
+	for _, line := range strings.Split(out, "\n") {
+		if strings.Contains(line, "page size of") {
+			f := strings.Fields(line)
+			for i, v := range f {
+				if v == "of" && i+1 < len(f) {
+					pageSize, _ = strconv.ParseInt(f[i+1], 10, 64)
+				}
+			}
+		}
+		if strings.HasPrefix(line, "Pages free:") || strings.HasPrefix(line, "Pages inactive:") || strings.HasPrefix(line, "Pages speculative:") {
+			f := strings.Fields(line)
+			if len(f) > 0 {
+				n, _ := strconv.ParseInt(strings.TrimSuffix(f[len(f)-1], "."), 10, 64)
+				pages += n
+			}
+		}
+	}
+	return int(pages * pageSize / (1024 * 1024))
+}
+
+// readPower runs the two pmset queries side by side.
+func readPower() darwinPower {
+	pw := darwinPower{battery: -1}
+	var batt, custom []byte
+	var battErr, customErr error
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() { defer wg.Done(); batt, battErr = osexec.Command("pmset", "-g", "batt").Output() }()
+	go func() { defer wg.Done(); custom, customErr = osexec.Command("pmset", "-g", "custom").Output() }()
+	wg.Wait()
+	if battErr == nil {
+		s := string(batt)
+		pw.plugged = strings.Contains(s, "AC Power")
+		for _, field := range strings.Fields(s) {
+			if strings.HasSuffix(field, "%;") || strings.HasSuffix(field, "%") {
+				pw.battery, _ = strconv.Atoi(strings.TrimSuffix(strings.TrimSuffix(field, ";"), "%"))
+				break
+			}
+		}
+	}
+	if customErr == nil {
+		pw.low = strings.Contains(string(custom), "lowpowermode 1")
+	}
+	return pw
+}
diff --git a/free/ci/internal/exec/capacity_other.go b/free/ci/internal/exec/capacity_other.go
new file mode 100644
index 000000000..54e8414e4
--- /dev/null
+++ b/free/ci/internal/exec/capacity_other.go
@@ -0,0 +1,6 @@
+//go:build !darwin
+
+package exec
+
+// probeDarwin is the macOS probe (capacity_darwin.go); Probe calls it only on darwin.
+func probeDarwin(*Capacity) {}
diff --git a/free/ci/internal/exec/copytree.go b/free/ci/internal/exec/copytree.go
index 3396105eb..4da2b9527 100644
--- a/free/ci/internal/exec/copytree.go
+++ b/free/ci/internal/exec/copytree.go
@@ -49,11 +49,15 @@ func linkStaysInside(link, rel string) bool {
 	return true
 }
 
-func copyTree(source, dest string) error {
+// copyTree copies source into dest. Paths in skip (and everything under them) are left out when they lie
+// strictly inside source: the state directory and the workspace itself can sit in the repo root, and
+// copying them would make the copy recurse into itself and hand the job other attempts' files.
+func copyTree(source, dest string, skip ...string) error {
 	root, err := filepath.Abs(source)
 	if err != nil {
 		return err
 	}
+	skipped := skipRels(root, skip)
 	return filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
@@ -65,6 +69,12 @@ func copyTree(source, dest string) error {
 		if rel == "." {
 			return nil
 		}
+		if underAny(rel, skipped) {
+			if info.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
 		target := filepath.Join(dest, rel)
 		if info.Mode()&os.ModeSymlink != 0 {
 			return copySymlink(path, rel, target)
@@ -96,3 +106,44 @@ func copyTree(source, dest string) error {
 		return closeErr
 	})
 }
+
+// skipRels turns the skip paths into paths relative to root, keeping only those strictly inside it.
+// Root and each path are tried both as given and resolved through symlinks (a temp dir may be one on
+// macOS), so the match does not depend on how the caller spelled them.
+func skipRels(root string, skip []string) []string {
+	real := func(p string) string {
+		if r, err := filepath.EvalSymlinks(p); err == nil {
+			return r
+		}
+		return p
+	}
+	var out []string
+	for _, p := range skip {
+		if p == "" {
+			continue
+		}
+		abs, err := filepath.Abs(p)
+		if err != nil {
+			continue
+		}
+		for _, base := range []string{root, real(root)} {
+			for _, cand := range []string{abs, real(abs)} {
+				rel, err := filepath.Rel(base, cand)
+				if err == nil && rel != "." && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+					out = append(out, rel)
+				}
+			}
+		}
+	}
+	return out
+}
+
+// underAny reports whether rel is one of dirs or lies under one.
+func underAny(rel string, dirs []string) bool {
+	for _, d := range dirs {
+		if rel == d || strings.HasPrefix(rel, d+string(filepath.Separator)) {
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/internal/exec/copytree_state_test.go b/free/ci/internal/exec/copytree_state_test.go
new file mode 100644
index 000000000..1f20c6fe3
--- /dev/null
+++ b/free/ci/internal/exec/copytree_state_test.go
@@ -0,0 +1,104 @@
+package exec
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// writeTree creates the files (path -> content) under dir.
+func writeTree(t *testing.T, dir string, files map[string]string) {
+	t.Helper()
+	for p, c := range files {
+		full := filepath.Join(dir, p)
+		if err := os.MkdirAll(filepath.Dir(full), 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(c), 0600); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// exists reports whether path is present (a link counts).
+func exists(path string) bool { _, err := os.Lstat(path); return err == nil }
+
+// A skip path inside the source, and everything under it, is left out of the copy. Paths outside the
+// source, the source itself and an ancestor of it change nothing.
+func TestCopyTreeSkipsStatePaths(t *testing.T) {
+	src := t.TempDir()
+	writeTree(t, src, map[string]string{
+		"a.txt": "a", "state/work/old/f.txt": "old", "state/db": "db", "statement.txt": "keep", "sub/b.txt": "b",
+	})
+	outside := t.TempDir()
+	dst := filepath.Join(t.TempDir(), "ws")
+	if err := os.Mkdir(dst, 0700); err != nil {
+		t.Fatal(err)
+	}
+	// src itself, its parent and an unrelated dir are not skippable; "state" is.
+	if err := copyTree(src, dst, filepath.Join(src, "state"), src, filepath.Dir(src), outside, ""); err != nil {
+		t.Fatalf("copyTree: %v", err)
+	}
+	for _, p := range []string{"a.txt", "statement.txt", "sub/b.txt"} {
+		if !exists(filepath.Join(dst, p)) {
+			t.Errorf("%s missing from the copy", p)
+		}
+	}
+	if exists(filepath.Join(dst, "state")) {
+		t.Errorf("state dir was copied")
+	}
+}
+
+// A symlinked spelling of the state dir (a temp dir is one on macOS) is matched too.
+func TestCopyTreeSkipsStateThroughSymlink(t *testing.T) {
+	base := t.TempDir()
+	src := filepath.Join(base, "repo")
+	writeTree(t, src, map[string]string{"a.txt": "a", "state/x": "x"})
+	alias := filepath.Join(base, "alias")
+	if err := os.Symlink(src, alias); err != nil {
+		t.Skipf("cannot create link: %v", err)
+	}
+	dst := filepath.Join(t.TempDir(), "ws")
+	if err := os.Mkdir(dst, 0700); err != nil {
+		t.Fatal(err)
+	}
+	if err := copyTree(src, dst, filepath.Join(alias, "state")); err != nil {
+		t.Fatalf("copyTree: %v", err)
+	}
+	if !exists(filepath.Join(dst, "a.txt")) || exists(filepath.Join(dst, "state")) {
+		t.Fatalf("want a.txt copied and state skipped")
+	}
+}
+
+// With the state directory inside the repo root the workspace lands inside the source. The run must
+// finish (no copy of the workspace into itself), the job must not see the state dir, and the repo files
+// must be there, including a config file beside the state dir.
+func TestRunWithStateDirInsideRepoRoot(t *testing.T) {
+	root := t.TempDir()
+	home := filepath.Join(root, ".nself", "ci")
+	writeTree(t, root, map[string]string{"README.md": "hi", ".nself/ci/work/older/leftover": "x", ".nself/ci/runs.db": "db", ".nself/ci.yaml": "cfg"})
+	var out []byte
+	e := &Executor{Isolation: BaselineIsolator{}}
+	done := make(chan AttemptResult, 1)
+	go func() {
+		done <- e.Run(context.Background(), JobSpec{
+			AttemptID: "inside", CoordinatorID: "coord", Home: home, SourceDir: root,
+			Command: []string{"sh", "-c", "ls -A .nself; test -f README.md && test -f .nself/ci.yaml && test ! -e .nself/ci"},
+			Output:  func(p []byte) { out = append(out, p...) },
+		})
+	}()
+	select {
+	case r := <-done:
+		if r.Err != nil || r.ExitCode != 0 {
+			t.Fatalf("run: %+v output %q", r, out)
+		}
+		if strings.TrimSpace(string(out)) != "ci.yaml" {
+			t.Fatalf(".nself listing = %q; want only the repo's ci.yaml, without the state dir", out)
+		}
+	case <-time.After(60 * time.Second):
+		t.Fatal("run did not finish: the workspace copy recursed into itself")
+	}
+}
diff --git a/free/ci/internal/exec/executor.go b/free/ci/internal/exec/executor.go
index 145a05d76..ffcec14f9 100644
--- a/free/ci/internal/exec/executor.go
+++ b/free/ci/internal/exec/executor.go
@@ -164,8 +164,8 @@ func (e *Executor) Run(ctx context.Context, s JobSpec) (result AttemptResult) {
 		return
 	}
 	defer func() { _ = pinned.Close() }()
-	if s.SourceDir != "" {
-		if err := copyTree(s.SourceDir, workspace); err != nil {
+	if s.SourceDir != "" { // the state dir and workspace may sit inside the repo root: they are not copied
+		if err := copyTree(s.SourceDir, workspace, s.Home, workspace); err != nil {
 			result.Err = err
 			return
 		}
diff --git a/free/ci/internal/fleet/ask.go b/free/ci/internal/fleet/ask.go
new file mode 100644
index 000000000..ca613fefd
--- /dev/null
+++ b/free/ci/internal/fleet/ask.go
@@ -0,0 +1,121 @@
+package fleet
+
+// Purpose: ask every node for its status documents in parallel: at most Parallel at once, each under
+// its own hard cap. A reader that ignores cancellation is abandoned at the cap, so one paused host
+// costs the pass at most NodeCap and never delays the others.
+// Inputs:  the nodes, a Reader and Options.
+// Outputs: one Reply per node, in the order of the nodes.
+// Constraints: no clock read of its own (the cap comes from the context or the injected Timer).
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/probe"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+)
+
+// Reader reads the status documents of one node.
+type Reader func(ctx context.Context, n registry.Node) (probe.StatusDocs, error)
+
+// Options tune one pass. The zero value uses NodeCap and Parallel.
+type Options struct {
+	Cap      time.Duration
+	Parallel int
+	// Timer, when set, is the cap of one node instead of the context deadline (tests fire it).
+	Timer func(node string, d time.Duration) <-chan time.Time
+	// Now is the clock that ages demand documents; nil means time.Now.
+	Now func() time.Time
+}
+
+func (o Options) limits() (time.Duration, int) {
+	limit, n := o.Cap, o.Parallel
+	if limit <= 0 {
+		limit = NodeCap
+	}
+	if n <= 0 {
+		n = Parallel
+	}
+	return limit, n
+}
+
+// Reply is the answer of one node.
+type Reply struct {
+	Docs probe.StatusDocs
+	Err  error
+}
+
+// errCap marks a node that did not answer within its cap.
+var errCap = errors.New("no answer within the cap")
+
+// Ask reads every node through read and returns the replies in node order.
+func Ask(ctx context.Context, nodes []registry.Node, read Reader, o Options) []Reply {
+	limit, n := o.limits()
+	out := make([]Reply, len(nodes))
+	slots := make(chan struct{}, n)
+	var wg sync.WaitGroup
+	for i := range nodes {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			select {
+			case slots <- struct{}{}:
+				defer func() { <-slots }()
+			case <-ctx.Done():
+				out[i] = Reply{Err: ctx.Err()}
+				return
+			}
+			out[i] = askOne(ctx, nodes[i], read, limit, o.Timer)
+		}(i)
+	}
+	wg.Wait()
+	return out
+}
+
+// askOne runs one read and stops waiting at the cap whether or not the reader returns.
+func askOne(ctx context.Context, node registry.Node, read Reader, limit time.Duration, timer func(string, time.Duration) <-chan time.Time) Reply {
+	if read == nil {
+		return Reply{Err: fmt.Errorf("no status reader")}
+	}
+	cctx, cancel := context.WithTimeout(ctx, limit)
+	defer cancel()
+	var deadline <-chan time.Time // nil: the context deadline alone is the cap
+	if timer != nil {
+		deadline = timer(node.Record.ID, limit)
+	}
+	answer := make(chan Reply, 1) // buffered: an abandoned reader never blocks on send
+	go func() {
+		docs, err := read(cctx, node)
+		answer <- Reply{Docs: docs, Err: err}
+	}()
+	select {
+	case r := <-answer:
+		if r.Err != nil && errors.Is(cctx.Err(), context.DeadlineExceeded) {
+			r.Err = fmt.Errorf("%w (%s)", errCap, limit)
+		}
+		return r
+	case <-deadline:
+		return Reply{Err: fmt.Errorf("%w (%s)", errCap, limit)}
+	case <-cctx.Done():
+		if errors.Is(cctx.Err(), context.DeadlineExceeded) {
+			return Reply{Err: fmt.Errorf("%w (%s)", errCap, limit)}
+		}
+		return Reply{Err: cctx.Err()}
+	}
+}
+
+// reason is the one-line, bounded text of a failed read.
+func reason(err error) string {
+	s := strings.TrimSpace(err.Error())
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		s = strings.TrimSpace(s[:i])
+	}
+	if len(s) > 200 {
+		s = s[:200] + "..."
+	}
+	return s
+}
diff --git a/free/ci/internal/fleet/doc.go b/free/ci/internal/fleet/doc.go
new file mode 100644
index 000000000..c0a41b66a
--- /dev/null
+++ b/free/ci/internal/fleet/doc.go
@@ -0,0 +1,8 @@
+// Package fleet answers `ci nodes status` (P7-AUTO-19): it asks every registered node for its
+// readiness and demand documents in parallel, under a hard cap per node, and merges the answers
+// with the registry, the local run store and the pool of each node.
+//
+// A dead or slow node becomes an unreachable row with its reason and never delays the others.
+// The package reaches hosts only through the Reader it is given (the probe package's fixed
+// read-only commands over the SDK remote funnel); it opens no connection itself.
+package fleet
diff --git a/free/ci/internal/fleet/fleet_test.go b/free/ci/internal/fleet/fleet_test.go
new file mode 100644
index 000000000..29e067d72
--- /dev/null
+++ b/free/ci/internal/fleet/fleet_test.go
@@ -0,0 +1,213 @@
+package fleet
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/probe"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+var passAt = time.Date(2026, 10, 27, 12, 0, 30, 0, time.UTC)
+
+func demandJSON(t *testing.T, ready bool, why []string, queued, running int) []byte {
+	t.Helper()
+	stamp := passAt.Add(-30 * time.Second).Format(time.RFC3339)
+	b, err := json.Marshal(demand.Document{TS: stamp, Host: "h", Queued: queued, Running: running,
+		Ready: ready, ReadyWhy: why, Watcher: demand.Watcher{Alive: true, LastPass: stamp, IntervalSec: 30}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+func node(id string, labels ...string) registry.Node {
+	n := registry.Node{Record: store.NodeRecord{ID: id, Name: id, State: "online"}}
+	n.Capability.Identity.Labels = labels
+	n.Capability.Protocol.AgentVersion = "1.5.0"
+	return n
+}
+
+// TestFleetStatusCapsPerNode: every node gets the 8 s cap, a node past its cap is unreachable with the
+// reason while its reader is still blocked, and no more than Parallel readers run at once.
+func TestFleetStatusCapsPerNode(t *testing.T) {
+	var nodes []registry.Node
+	for i := 0; i < 20; i++ {
+		nodes = append(nodes, node(string(rune('a'+i))))
+	}
+	release := make(chan struct{})
+	t.Cleanup(func() { close(release) })
+	var mu sync.Mutex
+	caps := map[string]time.Duration{}
+	fired := make(chan time.Time)
+	close(fired)
+	timer := func(id string, d time.Duration) <-chan time.Time {
+		mu.Lock()
+		defer mu.Unlock()
+		caps[id] = d
+		if id == "c" {
+			return fired
+		}
+		return nil
+	}
+	var running, peak atomic.Int32
+	read := func(ctx context.Context, n registry.Node) (probe.StatusDocs, error) {
+		if n.Record.ID == "c" {
+			<-release // a paused host: ignores its context; abandoned at its cap, so it frees its slot
+			return probe.StatusDocs{}, nil
+		}
+		now := running.Add(1)
+		defer running.Add(-1)
+		for p := peak.Load(); now > p && !peak.CompareAndSwap(p, now); p = peak.Load() {
+		}
+		return probe.StatusDocs{Demand: demandJSON(t, true, nil, 1, 0)}, nil
+	}
+	replies := Ask(context.Background(), nodes, read, Options{Timer: timer})
+	for i, r := range replies {
+		id := nodes[i].Record.ID
+		if caps[id] != NodeCap {
+			t.Errorf("%s cap = %s, want %s", id, caps[id], NodeCap)
+		}
+		if id == "c" {
+			if !errors.Is(r.Err, errCap) || !strings.Contains(r.Err.Error(), "8s") {
+				t.Errorf("c err = %v, want the cap", r.Err)
+			}
+			continue
+		}
+		if r.Err != nil || r.Docs.Demand == nil {
+			t.Errorf("%s reply = %+v", id, r)
+		}
+	}
+	if p := peak.Load(); p > Parallel {
+		t.Errorf("peak readers = %d, want <= %d", p, Parallel)
+	}
+	if r := askOne(context.Background(), nodes[0], nil, NodeCap, nil); r.Err == nil {
+		t.Error("nil reader accepted")
+	}
+}
+
+func TestFleetStatusRows(t *testing.T) {
+	results := []Result{{ID: "1", Status: "passed"}, {ID: "2", Status: "failed"}, {ID: "3"}, {ID: "4"}, {ID: "5"}, {ID: "6"}}
+	ready := BuildRow(node("w1", "pool.gpu=1", "role=x"), Reply{Docs: probe.StatusDocs{Demand: demandJSON(t, true, nil, 3, 2)}}, results, passAt)
+	if ready.Source != SourceLive || ready.Watcher != WatcherAlive || ready.Ready == nil || !*ready.Ready || *ready.Queued != 3 || *ready.Running != 2 {
+		t.Fatalf("ready row = %+v", ready)
+	}
+	if len(ready.Pools) != 1 || ready.Pools[0] != "gpu" || len(ready.LastResults) != MaxResults || ready.LastPass == "" || ready.Demand == nil {
+		t.Fatalf("ready row pools/results = %+v", ready)
+	}
+	busy := BuildRow(node("w2"), Reply{Docs: probe.StatusDocs{Demand: demandJSON(t, false, []string{"memory below floor"}, 0, 0)}}, nil, passAt)
+	if busy.Ready == nil || *busy.Ready || len(busy.ReadyWhy) != 1 || busy.ReadyWhy[0] != "memory below floor" {
+		t.Fatalf("not-ready row = %+v", busy)
+	}
+	block := []byte(`{"schema":"ci.readiness/v1","ready":false,"why":["load too high"],"yielded_to":[]}`)
+	over := BuildRow(node("w3"), Reply{Docs: probe.StatusDocs{Demand: demandJSON(t, true, nil, 0, 0), Readiness: block}}, nil, passAt)
+	if over.Ready == nil || *over.Ready || over.ReadyWhy[0] != "load too high" {
+		t.Fatalf("readiness block row = %+v", over)
+	}
+	stale := BuildRow(node("w4"), Reply{Docs: probe.StatusDocs{Demand: demandJSON(t, true, nil, 0, 0)}}, nil, passAt.Add(10*time.Minute))
+	if stale.Watcher != WatcherStale {
+		t.Fatalf("stale watcher = %q", stale.Watcher)
+	}
+	plain := BuildRow(node("n1"), Reply{}, nil, passAt)
+	if plain.Watcher != WatcherNone || plain.Ready != nil || plain.Queued != nil || len(plain.ReadyWhy) != 1 || plain.Demand != nil {
+		t.Fatalf("no-watcher row = %+v", plain)
+	}
+	dead := BuildRow(node("n2"), Reply{Err: errors.New("ssh: connect timed out\nmore")}, results, passAt)
+	if dead.Source != SourceUnreachable || dead.Unreachable != "ssh: connect timed out" || dead.Watcher != WatcherUnknown || dead.Ready != nil {
+		t.Fatalf("unreachable row = %+v", dead)
+	}
+	torn := BuildRow(node("n3"), Reply{Docs: probe.StatusDocs{Demand: []byte(`{"ts":`)}}, nil, passAt)
+	if torn.Watcher != WatcherNone || torn.ReadyWhy[0] != "demand document unreadable" {
+		t.Fatalf("torn row = %+v", torn)
+	}
+	var buf bytes.Buffer
+	if err := Render(&buf, Report{Nodes: []Row{ready, busy, plain, dead}}); err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"w1", "ready", "not ready", "unreachable", "none", "gpu", "w2: memory below floor", "n2: unreachable: ssh"} {
+		if !strings.Contains(buf.String(), want) {
+			t.Errorf("table lacks %q:\n%s", want, buf.String())
+		}
+	}
+}
+
+// TestStatusJSONEnvelope: rows carry the node's contract:ci.demand v1 document and arrays are never null.
+func TestStatusJSONEnvelope(t *testing.T) {
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	register(t, st, "alpha", "beta")
+	read := func(_ context.Context, n registry.Node) (probe.StatusDocs, error) {
+		if n.Record.ID == "beta" {
+			return probe.StatusDocs{}, errors.New("connection refused")
+		}
+		return probe.StatusDocs{Demand: demandJSON(t, true, nil, 2, 1)}, nil
+	}
+	rep, err := Gather(context.Background(), st, read, Options{Now: func() time.Time { return passAt }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rep.Nodes) != 2 || rep.Unreachable != 1 || rep.Nodes[0].Node != "alpha" {
+		t.Fatalf("report = %+v", rep)
+	}
+	b, err := json.Marshal(rep)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got struct {
+		Nodes []map[string]json.RawMessage `json:"nodes"`
+	}
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatal(err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(got.Nodes[0]["demand"], &doc); err != nil || doc["queued"] != float64(2) || doc["ts"] == nil {
+		t.Fatalf("alpha demand = %s (%v)", got.Nodes[0]["demand"], err)
+	}
+	for _, key := range []string{"pools", "ready_why", "last_results"} {
+		if string(got.Nodes[1][key]) == "null" {
+			t.Errorf("beta %s is null", key)
+		}
+	}
+	if string(got.Nodes[1]["source"]) != `"unreachable"` || string(got.Nodes[1]["demand"]) != "null" {
+		t.Errorf("beta row = %s", b)
+	}
+}
+
+// register adds online nodes from a valid capability fixture.
+func register(t *testing.T, st *store.Store, ids ...string) {
+	t.Helper()
+	raw, err := os.ReadFile("../model/testdata/capability/valid/vps.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range ids {
+		var c model.Capability
+		if err := json.Unmarshal(raw, &c); err != nil {
+			t.Fatal(err)
+		}
+		c.Identity.ID, c.Identity.Name = id, id
+		doc, err := json.Marshal(c)
+		if err != nil {
+			t.Fatal(err)
+		}
+		rec := store.NodeRecord{ID: id, Name: id, State: "online", Lifecycle: []byte("{}"), Trust: []byte("{}"), DeployHost: []byte("{}"), Capability: doc, ObservedAt: passAt.UnixNano()}
+		if err := st.NodePut(context.Background(), rec, "test"); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
diff --git a/free/ci/internal/fleet/gather.go b/free/ci/internal/fleet/gather.go
new file mode 100644
index 000000000..cc0c035b2
--- /dev/null
+++ b/free/ci/internal/fleet/gather.go
@@ -0,0 +1,71 @@
+package fleet
+
+// Purpose: one status pass over the registry: list the registered nodes, read the recent local
+// results, ask every node in parallel and merge the rows.
+// Inputs:  an open store, a Reader and Options.
+// Outputs: Report, rows sorted by node id.
+// Constraints: read-only on the store; revoked nodes are left out; a node that does not answer
+//          is a row, never an error of the pass.
+
+import (
+	"context"
+	"sort"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// Gather runs one status pass.
+func Gather(ctx context.Context, st *store.Store, read Reader, o Options) (Report, error) {
+	rep := Report{Nodes: []Row{}}
+	if st == nil {
+		return rep, nil
+	}
+	all, err := registry.New(st).List(ctx)
+	if err != nil {
+		return rep, err
+	}
+	var nodes []registry.Node
+	for _, n := range all {
+		if n.Record.State == "revoked" || n.Capability.Lifecycle.RevokedAt != nil {
+			continue
+		}
+		nodes = append(nodes, n)
+	}
+	sort.Slice(nodes, func(i, j int) bool { return nodes[i].Record.ID < nodes[j].Record.ID })
+	results, err := LastResults(ctx, st, MaxResults)
+	if err != nil {
+		return rep, err
+	}
+	replies := Ask(ctx, nodes, read, o)
+	now := time.Now
+	if o.Now != nil {
+		now = o.Now
+	}
+	at := now()
+	for i, n := range nodes {
+		row := BuildRow(n, replies[i], results, at)
+		if row.Source == SourceUnreachable {
+			rep.Unreachable++
+		}
+		rep.Nodes = append(rep.Nodes, row)
+	}
+	return rep, nil
+}
+
+// LastResults returns up to limit runs of the local store, newest first (the rows of `ci runs list`).
+func LastResults(ctx context.Context, st *store.Store, limit int) ([]Result, error) {
+	out := []Result{}
+	if st == nil {
+		return out, nil
+	}
+	page, err := st.History(ctx, 0, limit)
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range page.Pipelines {
+		out = append(out, Result{ID: p.ID, Project: p.Project, Revision: p.Revision, Status: p.Status})
+	}
+	return out, nil
+}
diff --git a/free/ci/internal/fleet/render.go b/free/ci/internal/fleet/render.go
new file mode 100644
index 000000000..e62b41dff
--- /dev/null
+++ b/free/ci/internal/fleet/render.go
@@ -0,0 +1,75 @@
+package fleet
+
+// Purpose: the human table of `ci nodes status`: one line per node, then the reasons of every node
+// that is not ready or did not answer.
+// Inputs:  Report. Outputs: text on w.
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"text/tabwriter"
+)
+
+// Render writes the status table.
+func Render(w io.Writer, rep Report) error {
+	if len(rep.Nodes) == 0 {
+		_, err := fmt.Fprintln(w, "no nodes registered")
+		return err
+	}
+	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "NODE\tSTATE\tVERSION\tPOOL\tREADY\tWATCHER\tLAST PASS\tQUEUED\tRUNNING\tLAST RESULTS")
+	for _, r := range rep.Nodes {
+		fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n", r.Node, dash(r.State), dash(r.AgentVersion),
+			dash(strings.Join(r.Pools, ",")), readyText(r), r.Watcher, dash(r.LastPass), count(r.Queued), count(r.Running), results(r.LastResults))
+	}
+	if err := tw.Flush(); err != nil {
+		return err
+	}
+	for _, r := range rep.Nodes {
+		if r.Ready != nil && *r.Ready || len(r.ReadyWhy) == 0 {
+			continue
+		}
+		if _, err := fmt.Fprintf(w, "%s: %s\n", r.Node, strings.Join(r.ReadyWhy, "; ")); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func readyText(r Row) string {
+	switch {
+	case r.Source == SourceUnreachable:
+		return "unreachable"
+	case r.Ready == nil:
+		return "unknown"
+	case *r.Ready:
+		return "ready"
+	}
+	return "not ready"
+}
+
+func count(v *int) string {
+	if v == nil {
+		return "-"
+	}
+	return fmt.Sprint(*v)
+}
+
+func dash(s string) string {
+	if s == "" {
+		return "-"
+	}
+	return s
+}
+
+func results(rs []Result) string {
+	if len(rs) == 0 {
+		return "-"
+	}
+	parts := make([]string, len(rs))
+	for i, r := range rs {
+		parts[i] = r.Status
+	}
+	return strings.Join(parts, ",")
+}
diff --git a/free/ci/internal/fleet/row.go b/free/ci/internal/fleet/row.go
new file mode 100644
index 000000000..e4f7f85b4
--- /dev/null
+++ b/free/ci/internal/fleet/row.go
@@ -0,0 +1,110 @@
+package fleet
+
+// Purpose: merge one node's registry entry, its reply and the local results into a Row.
+// Inputs:  registry.Node, Reply, the recent local results and the time of the pass.
+// Outputs: Row.
+// Constraints: pure. Readiness prefers the node's readiness block (contract:ci.readiness v1) and
+//          falls back to the ready fields of its demand document. Only watch hosts publish
+//          demand.json: a node that answered without one runs no watcher (watcher: none).
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/readiness"
+)
+
+// staleAfter is how many watcher intervals may pass before a demand document reads as stale.
+const staleAfter = 3
+
+// defaultInterval ages a document whose interval is unknown.
+const defaultInterval = 30 * time.Second
+
+// BuildRow merges the sources of one node.
+func BuildRow(n registry.Node, r Reply, results []Result, now time.Time) Row {
+	row := Row{
+		Node: n.Record.ID, Name: n.Record.Name, State: n.Record.State,
+		AgentVersion: n.Capability.Protocol.AgentVersion,
+		Pools:        pools.FromAssigned(n.Capability.Identity.Labels),
+		ReadyWhy:     []string{}, LastResults: append([]Result{}, results...),
+	}
+	if row.Pools == nil {
+		row.Pools = []string{}
+	}
+	if len(row.LastResults) > MaxResults {
+		row.LastResults = row.LastResults[:MaxResults]
+	}
+	if r.Err != nil {
+		row.Source, row.Unreachable, row.Watcher = SourceUnreachable, reason(r.Err), WatcherUnknown
+		row.ReadyWhy = []string{"unreachable: " + row.Unreachable}
+		return row
+	}
+	row.Source, row.Watcher = SourceLive, WatcherNone
+	if doc, ok := parseDemand(r.Docs.Demand); ok {
+		row.Demand = &doc
+		row.Watcher = watcherState(doc, now)
+		row.LastPass = doc.Watcher.LastPass
+		row.Queued, row.Running = intPtr(doc.Queued), intPtr(doc.Running)
+		row.Ready = boolPtr(doc.Ready)
+		row.ReadyWhy = append(row.ReadyWhy, doc.ReadyWhy...)
+	} else if len(r.Docs.Demand) > 0 {
+		row.ReadyWhy = []string{"demand document unreadable"}
+	}
+	if rep, ok := parseReadiness(r.Docs.Readiness); ok {
+		row.Ready = boolPtr(rep.Ready)
+		row.ReadyWhy = append([]string{}, rep.Why...)
+	}
+	if row.Ready == nil && len(row.ReadyWhy) == 0 {
+		row.ReadyWhy = []string{"no readiness published (readiness is per watch host)"}
+	}
+	return row
+}
+
+// parseDemand decodes a demand document; ok is false when there is none or it is torn.
+func parseDemand(b []byte) (demand.Document, bool) {
+	var doc demand.Document
+	if len(b) == 0 || json.Unmarshal(b, &doc) != nil {
+		return demand.Document{}, false
+	}
+	if _, err := time.Parse(time.RFC3339, doc.TS); err != nil {
+		return demand.Document{}, false
+	}
+	if doc.ReadyWhy == nil {
+		doc.ReadyWhy = []string{}
+	}
+	return doc, true
+}
+
+// parseReadiness decodes a readiness block of the current schema.
+func parseReadiness(b []byte) (readiness.Report, bool) {
+	var rep readiness.Report
+	if len(b) == 0 || json.Unmarshal(b, &rep) != nil || rep.Schema != readiness.SchemaID {
+		return readiness.Report{}, false
+	}
+	if rep.Why == nil {
+		rep.Why = []string{}
+	}
+	return rep, true
+}
+
+// watcherState is alive while the document is younger than staleAfter intervals.
+func watcherState(doc demand.Document, now time.Time) string {
+	ts, err := time.Parse(time.RFC3339, doc.TS)
+	if err != nil || !doc.Watcher.Alive {
+		return WatcherStale
+	}
+	interval := time.Duration(doc.Watcher.IntervalSec * float64(time.Second))
+	if interval <= 0 {
+		interval = defaultInterval
+	}
+	if now.Sub(ts) > staleAfter*interval {
+		return WatcherStale
+	}
+	return WatcherAlive
+}
+
+func intPtr(v int) *int    { return &v }
+func boolPtr(v bool) *bool { return &v }
diff --git a/free/ci/internal/fleet/types.go b/free/ci/internal/fleet/types.go
new file mode 100644
index 000000000..da8d9b5f5
--- /dev/null
+++ b/free/ci/internal/fleet/types.go
@@ -0,0 +1,73 @@
+package fleet
+
+// Purpose: the document of `ci nodes status --json`: one Row per registered node, each carrying the
+// node's contract:ci.demand v1 document when it publishes one.
+// Constraints: additive changes only; slices are always arrays in JSON, never null.
+
+import (
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+)
+
+// Limits of one status pass (P7-AUTO-19).
+const (
+	// NodeCap is the longest the pass waits for one node.
+	NodeCap = 8 * time.Second
+	// Parallel is how many nodes are asked at once.
+	Parallel = 8
+	// MaxResults is how many recent results a row carries.
+	MaxResults = 5
+)
+
+// Source values of a row.
+const (
+	SourceLive        = "live"
+	SourceUnreachable = "unreachable"
+)
+
+// Watcher values of a row.
+const (
+	WatcherAlive   = "alive"
+	WatcherStale   = "stale"
+	WatcherNone    = "none"
+	WatcherUnknown = "unknown"
+)
+
+// Result is one recent run from the local store, as `ci runs list` shows it.
+type Result struct {
+	ID       string `json:"id"`
+	Project  string `json:"project"`
+	Revision string `json:"revision"`
+	Status   string `json:"status"`
+}
+
+// Row is the status of one node.
+type Row struct {
+	Node         string   `json:"node"`
+	Name         string   `json:"name"`
+	State        string   `json:"state"`
+	AgentVersion string   `json:"agent_version"`
+	Pools        []string `json:"pools"`
+	// Source is live when the node answered, unreachable when it did not.
+	Source string `json:"source"`
+	// Unreachable is the reason the node did not answer ("" when it did).
+	Unreachable string `json:"unreachable,omitempty"`
+	// Ready is nil when readiness is unknown (unreachable or not published).
+	Ready    *bool    `json:"ready"`
+	ReadyWhy []string `json:"ready_why"`
+	// Watcher is alive, stale, none (the host runs no watcher) or unknown (unreachable).
+	Watcher  string `json:"watcher"`
+	LastPass string `json:"last_pass,omitempty"`
+	Queued   *int   `json:"queued"`
+	Running  *int   `json:"running"`
+	// Demand is the node's contract:ci.demand v1 document; nil when it publishes none.
+	Demand      *demand.Document `json:"demand"`
+	LastResults []Result         `json:"last_results"`
+}
+
+// Report is the data of the `ci nodes status --json` envelope.
+type Report struct {
+	Nodes       []Row `json:"nodes"`
+	Unreachable int   `json:"unreachable"`
+}
diff --git a/free/ci/internal/gates/gitleaks_ignore.go b/free/ci/internal/gates/gitleaks_ignore.go
new file mode 100644
index 000000000..549211c59
--- /dev/null
+++ b/free/ci/internal/gates/gitleaks_ignore.go
@@ -0,0 +1,251 @@
+package gates
+
+// Purpose: the review rule of the secrets.gitleaks check (P7-AUTO-17). Every
+// entry of the repository's .gitleaksignore must carry a
+// `# Reviewed YYYY-MM-DD [by <who>]: <reason>` comment on the same or the
+// preceding comment line; an unreviewed entry fails the check with E812, which
+// names line numbers only. AddReviewedIgnore is the writer behind
+// `nself ci config ignore add`.
+// Inputs:  the repository root; for the writer a fingerprint, a reason, an
+// optional reviewer and the date.
+// Outputs: E812 errors that never quote file content or a fingerprint.
+// Constraints: only <root>/.gitleaksignore is read or written, never through a
+// symlink; a gate run never adds lines; fingerprints come in the two gitleaks
+// forms, commit:path:rule:line (git scan) and path:rule:line (--no-git).
+
+import (
+	"bufio"
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// IgnoreFile is the gitleaks ignore file, relative to the repository root.
+const IgnoreFile = ".gitleaksignore"
+
+// ReviewFormat is the comment every ignore entry needs, as shown to users.
+const ReviewFormat = "# Reviewed YYYY-MM-DD [by <who>]: <reason>"
+
+func init() {
+	model.Register(model.Code{ID: "E812", Class: "code", Summary: "a .gitleaksignore entry has no review comment", Fix: "Put `" + ReviewFormat + "` on the line before each entry, or add entries with `nself ci config ignore add <fingerprint> --reason <text>`"})
+}
+
+// IgnoreError carries E812. Its text holds line numbers only, never content.
+type IgnoreError struct{ Code, Message string }
+
+func (e *IgnoreError) Error() string { return e.Code + ": " + e.Message }
+
+func ignoreErr(format string, a ...any) error {
+	return &IgnoreError{Code: "E812", Message: fmt.Sprintf(format, a...)}
+}
+
+var reviewRe = regexp.MustCompile(`#\s*Reviewed (\d{4}-\d{2}-\d{2})(?: by ([^:#\r\n]*[^:#\s]))?:\s*\S`)
+
+// reviewed reports whether s holds a well-formed review comment with a real date.
+func reviewed(s string) bool {
+	m := reviewRe.FindStringSubmatch(s)
+	if m == nil {
+		return false
+	}
+	_, err := time.Parse("2006-01-02", m[1])
+	return err == nil
+}
+
+var (
+	ruleRe   = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]*$`)
+	commitRe = regexp.MustCompile(`^(?:[0-9a-f]{40}|[0-9a-f]{64})$`)
+)
+
+// FingerprintCommit reports whether fp is a valid gitleaks fingerprint and
+// whether it carries a commit (the git-scan form).
+func FingerprintCommit(fp string) (valid, withCommit bool) {
+	if fp == "" || strings.ContainsAny(fp, " \t\r\n#") {
+		return false, false
+	}
+	parts := strings.Split(fp, ":")
+	if len(parts) < 3 {
+		return false, false
+	}
+	n := len(parts)
+	if line, err := strconv.Atoi(parts[n-1]); err != nil || line < 1 || strconv.Itoa(line) != parts[n-1] {
+		return false, false
+	}
+	if !ruleRe.MatchString(parts[n-2]) {
+		return false, false
+	}
+	withCommit = n >= 4 && commitRe.MatchString(parts[0])
+	path := strings.Join(parts[:n-2], ":")
+	if withCommit {
+		path = strings.Join(parts[1:n-2], ":")
+	}
+	if path == "" || strings.HasPrefix(path, "/") {
+		return false, false
+	}
+	return true, withCommit
+}
+
+// ValidFingerprint reports whether fp has one of the two gitleaks forms.
+func ValidFingerprint(fp string) bool { ok, _ := FingerprintCommit(fp); return ok }
+
+// entry splits a line into its fingerprint part (before any '#') and reports
+// whether the line is a comment or blank.
+func entry(line string) (fp string, comment bool) {
+	s := strings.TrimSpace(line)
+	if s == "" || strings.HasPrefix(s, "#") {
+		return "", true
+	}
+	if i := strings.Index(s, "#"); i >= 0 {
+		s = strings.TrimSpace(s[:i])
+	}
+	return s, false
+}
+
+// UnreviewedLines returns the 1-based numbers of the entry lines in r that
+// have no review comment on the same or the preceding line. Every line that is
+// not blank and not a comment is an entry, recognised fingerprint or not.
+func UnreviewedLines(r io.Reader) ([]int, error) {
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 64*1024), 1024*1024)
+	var out []int
+	prevReviewed, n := false, 0
+	for sc.Scan() {
+		n++
+		line := sc.Text()
+		_, comment := entry(line)
+		if !comment && !reviewed(line) && !prevReviewed {
+			out = append(out, n)
+		}
+		// Only a comment line vouches for the entry after it.
+		prevReviewed = comment && reviewed(line)
+	}
+	return out, sc.Err()
+}
+
+// openIgnore opens <root>/.gitleaksignore for reading; a missing file is (nil, nil).
+func openIgnore(root string) (*os.File, error) {
+	p := filepath.Join(root, IgnoreFile)
+	st, err := os.Lstat(p)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, ignoreErr("%s cannot be read", IgnoreFile)
+	}
+	if !st.Mode().IsRegular() {
+		return nil, ignoreErr("%s is not a regular file (a symlink is refused)", IgnoreFile)
+	}
+	f, err := os.Open(p)
+	if err != nil {
+		return nil, ignoreErr("%s cannot be read", IgnoreFile)
+	}
+	return f, nil
+}
+
+// ReviewIgnoreFile applies the review rule to <root>/.gitleaksignore. A
+// missing file passes; an unreviewed entry returns an E812 *IgnoreError.
+func ReviewIgnoreFile(root string) error {
+	f, err := openIgnore(root)
+	if err != nil || f == nil {
+		return err
+	}
+	defer f.Close()
+	lines, err := UnreviewedLines(f)
+	if err != nil {
+		return ignoreErr("%s cannot be read", IgnoreFile)
+	}
+	if len(lines) == 0 {
+		return nil
+	}
+	nums := make([]string, len(lines))
+	for i, l := range lines {
+		nums[i] = strconv.Itoa(l)
+	}
+	word := "line"
+	if len(lines) > 1 {
+		word = "lines"
+	}
+	return ignoreErr("%s %s %s has no `%s` comment", IgnoreFile, word, strings.Join(nums, ", "), ReviewFormat)
+}
+
+// ApplyIgnoreReview runs the review rule after the gitleaks scan of c. A check
+// that errored (tool missing, infrastructure) is left alone; otherwise an
+// unreviewed entry turns it into a code failure whose excerpt leads with E812.
+func ApplyIgnoreReview(root string, c *model.Check) {
+	if c == nil || c.ID != "secrets.gitleaks" || c.Result == "error" || c.Result == "skip" {
+		return
+	}
+	err := ReviewIgnoreFile(root)
+	if err == nil {
+		return
+	}
+	c.Result = "fail"
+	c.FailureClass = "code"
+	if c.Excerpt == "" {
+		c.Excerpt = err.Error()
+	} else {
+		c.Excerpt = err.Error() + "\n" + c.Excerpt
+	}
+}
+
+// AddReviewedIgnore appends `# Reviewed <date> [by <who>]: <reason>` and fp to
+// <root>/.gitleaksignore. It reports false with no error when fp is already an
+// entry. Validation of fp, reason and who is the caller's; this only refuses
+// what would break the file format. No error text quotes fp.
+func AddReviewedIgnore(root, fp, reason, who string, now time.Time) (bool, error) {
+	if !ValidFingerprint(fp) {
+		return false, ignoreErr("the fingerprint is not in a gitleaks form (commit:path:rule:line or path:rule:line)")
+	}
+	reason, who = strings.TrimSpace(reason), strings.TrimSpace(who)
+	if reason == "" || strings.ContainsAny(reason, "\r\n") {
+		return false, ignoreErr("--reason must be one non-empty line")
+	}
+	if strings.ContainsAny(who, "\r\n:#") {
+		return false, ignoreErr("--by must be one line without ':' or '#'")
+	}
+	var existing []byte
+	if f, err := openIgnore(root); err != nil {
+		return false, err
+	} else if f != nil {
+		existing, err = io.ReadAll(f)
+		f.Close()
+		if err != nil {
+			return false, ignoreErr("%s cannot be read", IgnoreFile)
+		}
+	}
+	for _, line := range strings.Split(string(existing), "\n") {
+		if got, comment := entry(line); !comment && got == fp {
+			return false, nil
+		}
+	}
+	var b bytes.Buffer
+	if len(existing) > 0 && !bytes.HasSuffix(existing, []byte("\n")) {
+		b.WriteByte('\n')
+	}
+	b.WriteString("# Reviewed " + now.UTC().Format("2006-01-02"))
+	if who != "" {
+		b.WriteString(" by " + who)
+	}
+	b.WriteString(": " + reason + "\n" + fp + "\n")
+	f, err := os.OpenFile(filepath.Join(root, IgnoreFile), os.O_WRONLY|os.O_APPEND|os.O_CREATE, 0o644)
+	if err != nil {
+		return false, ignoreErr("%s cannot be written", IgnoreFile)
+	}
+	if _, err := f.Write(b.Bytes()); err != nil {
+		f.Close()
+		return false, ignoreErr("%s cannot be written", IgnoreFile)
+	}
+	if err := f.Close(); err != nil {
+		return false, ignoreErr("%s cannot be written", IgnoreFile)
+	}
+	return true, nil
+}
diff --git a/free/ci/internal/gates/gitleaks_ignore_test.go b/free/ci/internal/gates/gitleaks_ignore_test.go
new file mode 100644
index 000000000..c25aa4780
--- /dev/null
+++ b/free/ci/internal/gates/gitleaks_ignore_test.go
@@ -0,0 +1,145 @@
+package gates
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+const (
+	fpGit   = "0123456789abcdef0123456789abcdef01234567" + ":internal/fixture.go:generic-api-key:12"
+	fpNoGit = "testdata/fixture.env:aws-access-token:3"
+)
+
+func writeIgnore(t *testing.T, body string) string {
+	t.Helper()
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, IgnoreFile), []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestUnreviewedIgnoreFails(t *testing.T) {
+	root := writeIgnore(t, "# Reviewed 2026-10-01 by sam: test fixture\n"+fpGit+"\n\n"+fpNoGit+"\n")
+	err := ReviewIgnoreFile(root)
+	var ie *IgnoreError
+	if !errors.As(err, &ie) || ie.Code != "E812" {
+		t.Fatalf("want E812, got %v", err)
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "line 4 ") || strings.Contains(msg, "line 2") || strings.Contains(msg, "fixture") || strings.Contains(msg, "aws") {
+		t.Fatalf("message must name only line 4: %s", msg)
+	}
+	c := model.Check{ID: "secrets.gitleaks", Result: "pass", Excerpt: "no leaks found"}
+	ApplyIgnoreReview(root, &c)
+	if c.Result != "fail" || c.FailureClass != "code" || !strings.HasPrefix(c.Excerpt, "E812:") {
+		t.Fatalf("check not failed: %+v", c)
+	}
+}
+
+func TestReviewedIgnorePasses(t *testing.T) {
+	root := writeIgnore(t, "# header\n# Reviewed 2026-10-01: docs example\n"+fpGit+"\n"+fpNoGit+" # Reviewed 2026-10-02 by a b: fixture\n")
+	if err := ReviewIgnoreFile(root); err != nil {
+		t.Fatal(err)
+	}
+	if err := ReviewIgnoreFile(t.TempDir()); err != nil {
+		t.Fatalf("missing file must pass: %v", err)
+	}
+	c := model.Check{ID: "secrets.gitleaks", Result: "pass"}
+	ApplyIgnoreReview(root, &c)
+	if c.Result != "pass" {
+		t.Fatal(c)
+	}
+}
+
+func TestIgnoreReviewEdges(t *testing.T) {
+	cases := map[string][]int{
+		"# Reviewed 2026-13-01: bad month\n" + fpNoGit + "\n":       {2},
+		"# Reviewed 2026-10-01:\n" + fpNoGit + "\n":                 {2},
+		"# Reviewed 2026-10-01: ok\n" + fpNoGit + "\n" + fpGit:      {3},
+		fpNoGit + " # Reviewed 2026-10-01: ok\n" + fpGit + "\n":     {2},
+		"# Reviewed 2026-10-01 by x: ok\n\n" + fpNoGit + "\n":       {3},
+		"# Reviewed 2026-10-01 by x y: why\n" + fpGit + "\r\n# c\n": nil,
+	}
+	for body, want := range cases {
+		got, err := UnreviewedLines(strings.NewReader(body))
+		if err != nil || len(got) != len(want) || (len(want) == 1 && got[0] != want[0]) {
+			t.Errorf("%q: got %v want %v", body, got, want)
+		}
+	}
+	skip := model.Check{ID: "secrets.gitleaks", Result: "error"}
+	ApplyIgnoreReview(writeIgnore(t, fpNoGit+"\n"), &skip)
+	if skip.Result != "error" {
+		t.Fatal("an errored check must stay an error")
+	}
+}
+
+func TestFingerprintForms(t *testing.T) {
+	for fp, want := range map[string][2]bool{
+		fpGit:                         {true, true},
+		fpNoGit:                       {true, false},
+		"a:b:c:d:rule:7":              {true, false},
+		"path:rule":                   {false, false},
+		"path:rule:0":                 {false, false},
+		"path:rule:x":                 {false, false},
+		"/abs/path:rule:2":            {false, false},
+		"path with space:rule:2":      {false, false},
+		"path:rule:2#c":               {false, false},
+		fpGit[:41] + ":generic-key:1": {false, false},
+	} {
+		v, c := FingerprintCommit(fp)
+		if v != want[0] || c != want[1] {
+			t.Errorf("%q: got %v %v", fp, v, c)
+		}
+	}
+}
+
+func TestAddReviewedIgnore(t *testing.T) {
+	root := writeIgnore(t, "# existing\n"+fpGit)
+	now := time.Date(2026, 10, 27, 23, 0, 0, 0, time.FixedZone("x", -5*3600))
+	for i := 0; i < 2; i++ {
+		added, err := AddReviewedIgnore(root, fpNoGit, "fixture value", "sam", now)
+		if err != nil || added != (i == 0) {
+			t.Fatalf("run %d: %v %v", i, added, err)
+		}
+	}
+	if added, err := AddReviewedIgnore(root, fpGit, "dup", "", now); err != nil || added {
+		t.Fatalf("existing entry must be a no-op: %v %v", added, err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(root, IgnoreFile))
+	want := "# existing\n" + fpGit + "\n# Reviewed 2026-10-28 by sam: fixture value\n" + fpNoGit + "\n"
+	if string(raw) != want {
+		t.Fatalf("got %q", raw)
+	}
+	if lines, _ := UnreviewedLines(strings.NewReader(string(raw))); len(lines) != 1 || lines[0] != 2 {
+		t.Fatalf("only the pre-existing line is unreviewed: %v", lines)
+	}
+	for _, bad := range [][2]string{{"", ""}, {"a\nb", ""}, {"ok", "x:y"}} {
+		if _, err := AddReviewedIgnore(root, fpNoGit+"0", bad[0], bad[1], now); err == nil {
+			t.Errorf("accepted reason %q by %q", bad[0], bad[1])
+		}
+	}
+}
+
+func TestIgnoreSymlinkRefused(t *testing.T) {
+	outside := filepath.Join(t.TempDir(), "elsewhere")
+	if err := os.WriteFile(outside, []byte(fpNoGit+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	root := t.TempDir()
+	if err := os.Symlink(outside, filepath.Join(root, IgnoreFile)); err != nil {
+		t.Skip("symlinks unavailable")
+	}
+	if err := ReviewIgnoreFile(root); err == nil || !strings.Contains(err.Error(), "E812") {
+		t.Fatalf("symlink must be refused: %v", err)
+	}
+	if _, err := AddReviewedIgnore(root, fpGit, "r", "", time.Unix(0, 0)); err == nil {
+		t.Fatal("write through symlink must be refused")
+	}
+}
diff --git a/free/ci/internal/hostedtier/config.go b/free/ci/internal/hostedtier/config.go
new file mode 100644
index 000000000..44d3b7f75
--- /dev/null
+++ b/free/ci/internal/hostedtier/config.go
@@ -0,0 +1,44 @@
+package hostedtier
+
+// Purpose: defaults and the effective mode of the hosted tier (P7-AUTO-07).
+// Inputs:  a Config resolved from the operator-scope keys.
+// Outputs: Normalize, effective.
+// Constraints: paid maps onto the SCHED-17 spend keys through PaidAllowed only; no new spend path.
+
+import "time"
+
+// Normalize fills defaults. A non-positive timer takes its default; an unknown mode reads as free.
+func (c Config) Normalize() Config {
+	if c.Mode != ModeOff && c.Mode != ModePaid {
+		c.Mode = ModeFree
+	}
+	if c.Context == "" {
+		c.Context = DefaultContext
+	}
+	if c.AppID == 0 {
+		c.AppID = GitHubActionsAppID
+	}
+	c.Queued = orDefault(c.Queued, DefaultQueued)
+	c.Running = orDefault(c.Running, DefaultRunning)
+	c.Absent = orDefault(c.Absent, DefaultAbsent)
+	if len(c.Residual) == 0 {
+		c.Residual = []string{DefaultResidualID}
+	}
+	return c
+}
+
+func orDefault(d, def time.Duration) time.Duration {
+	if d <= 0 {
+		return def
+	}
+	return d
+}
+
+// effective returns the mode that applies and the notes explaining a downgrade: paid without
+// PaidAllowed behaves as free and says so.
+func (c Config) effective() (Mode, []string) {
+	if c.Mode == ModePaid && !c.PaidAllowed {
+		return ModeFree, []string{NotePaidDenied}
+	}
+	return c.Mode, nil
+}
diff --git a/free/ci/internal/hostedtier/decide.go b/free/ci/internal/hostedtier/decide.go
new file mode 100644
index 000000000..4cd9a5dc7
--- /dev/null
+++ b/free/ci/internal/hostedtier/decide.go
@@ -0,0 +1,124 @@
+package hostedtier
+
+// Purpose: the decision matrix (P7-AUTO-07): from the check runs of a commit, use the hosted
+//          result, wait for it, or hand over to local nodes.
+// Inputs:  ctx, the commit sha, the time the commit was pushed.
+// Outputs: Result.
+// Constraints: reads only; timers are keyed to the check run's own timestamps; a red hosted result
+//          stays red; a billing-blocked annotation marks the provider unavailable and is never a
+//          code failure; a run of another app or name is ignored.
+
+import (
+	"context"
+	"strings"
+	"time"
+)
+
+// Observer decides for commits of one repository.
+type Observer struct {
+	Cfg     Config
+	Funnel  Funnel
+	Breaker Breaker
+	Now     func() time.Time
+}
+
+// billingMarkers are lower-case fragments of the annotation GitHub writes when an account's
+// billing blocks Actions.
+var billingMarkers = []string{"payments have failed", "spending limit", "billing"}
+
+// Decide returns the decision for sha, pushed at pushed.
+func (o *Observer) Decide(ctx context.Context, sha string, pushed time.Time) Result {
+	cfg := o.Cfg.Normalize()
+	mode, notes := cfg.effective()
+	r := Result{Mode: mode, Notes: notes}
+	if mode == ModeOff {
+		return r.hand(ReasonOff)
+	}
+	if o.Breaker != nil && o.Breaker.Blocked(ctx) {
+		return r.hand(ReasonUnavailable)
+	}
+	runs, err := o.Funnel.CheckRuns(ctx, sha)
+	r.Requests++
+	if err != nil {
+		return r.hand(ReasonAPIError)
+	}
+	now := o.Now()
+	run, ok := pick(runs, cfg)
+	if !ok {
+		if now.Sub(pushed) < cfg.Absent {
+			return r.with(Wait, ReasonAbsent)
+		}
+		return r.hand(ReasonAbsentLong)
+	}
+	switch run.Status {
+	case "completed":
+		return o.completed(ctx, r, run, cfg, now)
+	case "in_progress":
+		if now.Sub(first(run.StartedAt, run.CreatedAt)) < cfg.Running {
+			return r.with(Wait, ReasonRunning)
+		}
+		return r.hand(ReasonRunningLong)
+	default: // queued, waiting, pending, requested
+		if now.Sub(run.CreatedAt) < cfg.Queued {
+			return r.with(Wait, ReasonQueued)
+		}
+		return r.hand(ReasonQueuedLong)
+	}
+}
+
+func (o *Observer) completed(ctx context.Context, r Result, run CheckRun, cfg Config, now time.Time) Result {
+	switch run.Conclusion {
+	case "success", "neutral", "skipped":
+		r.Residual = append([]string(nil), cfg.Residual...)
+		return r.with(Use, ReasonSuccess)
+	case "cancelled":
+		return r.hand(ReasonCancelled)
+	}
+	notes, err := o.Funnel.Annotations(ctx, run.ID)
+	r.Requests++
+	if err == nil && billing(notes) {
+		if o.Breaker != nil {
+			o.Breaker.MarkBlocked(now.Add(DefaultRunning))
+		}
+		return r.hand(ReasonBilling)
+	}
+	r.Residual = append([]string(nil), cfg.Residual...)
+	return r.with(Use, ReasonFailure) // a red hosted result stays red
+}
+
+func (r Result) with(d Decision, reason string) Result { r.Decision, r.Reason = d, reason; return r }
+func (r Result) hand(reason string) Result             { return r.with(HandOver, reason) }
+
+// pick returns the newest check run with the configured name and app.
+func pick(runs []CheckRun, cfg Config) (CheckRun, bool) {
+	var best CheckRun
+	found := false
+	for _, c := range runs {
+		if c.Name != cfg.Context || c.AppID != cfg.AppID {
+			continue
+		}
+		if !found || c.CreatedAt.After(best.CreatedAt) || c.CreatedAt.Equal(best.CreatedAt) && c.ID > best.ID {
+			best, found = c, true
+		}
+	}
+	return best, found
+}
+
+func billing(notes []string) bool {
+	for _, n := range notes {
+		low := strings.ToLower(n)
+		for _, m := range billingMarkers {
+			if strings.Contains(low, m) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func first(a, b time.Time) time.Time {
+	if a.IsZero() {
+		return b
+	}
+	return a
+}
diff --git a/free/ci/internal/hostedtier/decide_test.go b/free/ci/internal/hostedtier/decide_test.go
new file mode 100644
index 000000000..231f187b3
--- /dev/null
+++ b/free/ci/internal/hostedtier/decide_test.go
@@ -0,0 +1,100 @@
+package hostedtier
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/providers/health"
+)
+
+const billingText = "The job was not started because recent account payments have failed or your spending limit needs to be increased."
+
+func TestHostedDecisionMatrix(t *testing.T) {
+	s := time.Second
+	cases := []struct {
+		name   string
+		runs   []CheckRun
+		err    error
+		pushed time.Time
+		want   Decision
+		reason string
+	}{
+		{"success", []CheckRun{run("completed", "success", t0, t0)}, nil, t0, Use, ReasonSuccess},
+		{"failure", []CheckRun{run("completed", "failure", t0, t0)}, nil, t0, Use, ReasonFailure},
+		{"queued 10s", []CheckRun{run("queued", "", t0.Add(-10*s), time.Time{})}, nil, t0, Wait, ReasonQueued},
+		{"queued 40s", []CheckRun{run("queued", "", t0.Add(-40*s), time.Time{})}, nil, t0, HandOver, ReasonQueuedLong},
+		{"running 2m", []CheckRun{run("in_progress", "", t0.Add(-3*time.Minute), t0.Add(-2*time.Minute))}, nil, t0, Wait, ReasonRunning},
+		{"running 5m", []CheckRun{run("in_progress", "", t0.Add(-6*time.Minute), t0.Add(-5*time.Minute))}, nil, t0, HandOver, ReasonRunningLong},
+		{"absent young", nil, nil, t0.Add(-10 * s), Wait, ReasonAbsent},
+		{"absent old", nil, nil, t0.Add(-40 * s), HandOver, ReasonAbsentLong},
+		{"cancelled", []CheckRun{run("completed", "cancelled", t0, t0)}, nil, t0, HandOver, ReasonCancelled},
+		{"api error", nil, errBoom, t0.Add(-time.Hour), HandOver, ReasonAPIError},
+		{"other app ignored", []CheckRun{{ID: 9, Name: DefaultContext, AppID: 1, Status: "completed", Conclusion: "success"}}, nil, t0.Add(-time.Hour), HandOver, ReasonAbsentLong},
+		{"other name ignored", []CheckRun{{ID: 9, Name: "nself-ci/gates", AppID: GitHubActionsAppID, Status: "completed", Conclusion: "success"}}, nil, t0.Add(-time.Hour), HandOver, ReasonAbsentLong},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			f := &fakeFunnel{runs: c.runs, err: c.err}
+			got := observer(t, f, Config{}, t0).Decide(context.Background(), "abc", c.pushed)
+			if got.Decision != c.want || got.Reason != c.reason {
+				t.Fatalf("got %s/%s, want %s/%s", got.Decision, got.Reason, c.want, c.reason)
+			}
+		})
+	}
+}
+
+func TestBillingBlockedUnavailable(t *testing.T) {
+	f := &fakeFunnel{runs: []CheckRun{run("completed", "failure", t0, t0)}, notes: map[int64][]string{7: {billingText}}}
+	now := t0
+	tr := health.New(health.Options{Clock: func() time.Time { return now }})
+	o := &Observer{Funnel: f, Breaker: NewHealthBreaker(tr, "github-hosted"), Now: func() time.Time { return now }}
+	got := o.Decide(context.Background(), "abc", t0)
+	if got.Decision != HandOver || got.Reason != ReasonBilling {
+		t.Fatalf("got %s/%s", got.Decision, got.Reason)
+	}
+	before := f.calls
+	again := o.Decide(context.Background(), "abc", t0)
+	if again.Reason != ReasonUnavailable || again.Requests != 0 || f.calls != before {
+		t.Fatalf("breaker window must make no request: %+v calls %d->%d", again, before, f.calls)
+	}
+	now = t0.Add(time.Hour)
+	if r := o.Decide(context.Background(), "abc", t0); r.Reason == ReasonUnavailable {
+		t.Fatalf("a closed window must not stay unavailable: %+v", r)
+	}
+}
+
+func TestRedHostedStaysRed(t *testing.T) {
+	f := &fakeFunnel{runs: []CheckRun{run("completed", "failure", t0, t0)}, notes: map[int64][]string{7: {"exit status 1"}}}
+	got := observer(t, f, Config{}, t0).Decide(context.Background(), "abc", t0)
+	if got.Decision != Use || got.Reason != ReasonFailure {
+		t.Fatalf("a code failure is used as red: %+v", got)
+	}
+	ok := observer(t, &fakeFunnel{runs: []CheckRun{run("completed", "success", t0, t0)}}, Config{}, t0).Decide(context.Background(), "abc", t0)
+	if len(ok.Residual) != 1 || ok.Residual[0] != DefaultResidualID {
+		t.Fatalf("residual: %v", ok.Residual)
+	}
+}
+
+func TestHostedModeOffNoReads(t *testing.T) {
+	f := &fakeFunnel{runs: []CheckRun{run("completed", "success", t0, t0)}}
+	got := observer(t, f, Config{Mode: ModeOff}, t0).Decide(context.Background(), "abc", t0)
+	if got.Decision != HandOver || got.Reason != ReasonOff || f.calls != 0 || got.Requests != 0 {
+		t.Fatalf("off must not read: %+v calls %d", got, f.calls)
+	}
+}
+
+func TestPaidNeedsAllowed(t *testing.T) {
+	f := &fakeFunnel{runs: []CheckRun{run("completed", "success", t0, t0)}}
+	got := observer(t, f, Config{Mode: ModePaid}, t0).Decide(context.Background(), "abc", t0)
+	if got.Mode != ModeFree || len(got.Notes) != 1 || got.Notes[0] != NotePaidDenied {
+		t.Fatalf("paid without PaidAllowed behaves as free and says so: %+v", got)
+	}
+	got = observer(t, f, Config{Mode: ModePaid, PaidAllowed: true}, t0).Decide(context.Background(), "abc", t0)
+	if got.Mode != ModePaid || len(got.Notes) != 0 {
+		t.Fatalf("paid with PaidAllowed: %+v", got)
+	}
+	if free := observer(t, f, Config{Mode: ModeFree, PaidAllowed: true}, t0).Decide(context.Background(), "abc", t0); free.Mode != ModeFree {
+		t.Fatalf("free never selects paid: %+v", free)
+	}
+}
diff --git a/free/ci/internal/hostedtier/fixture_test.go b/free/ci/internal/hostedtier/fixture_test.go
new file mode 100644
index 000000000..87edec58c
--- /dev/null
+++ b/free/ci/internal/hostedtier/fixture_test.go
@@ -0,0 +1,45 @@
+package hostedtier
+
+// Purpose: fakes for the decision tests: a recorded-fixture funnel that counts requests and a
+//          breaker backed by the real HOST-11 tracker on an injected clock.
+// Constraints: no network, no sleeps.
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/providers/health"
+)
+
+var t0 = time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+
+type fakeFunnel struct {
+	runs  []CheckRun
+	notes map[int64][]string
+	err   error
+	calls int
+}
+
+func (f *fakeFunnel) CheckRuns(context.Context, string) ([]CheckRun, error) {
+	f.calls++
+	return f.runs, f.err
+}
+
+func (f *fakeFunnel) Annotations(_ context.Context, id int64) ([]string, error) {
+	f.calls++
+	return f.notes[id], nil
+}
+
+func run(status, conclusion string, created, started time.Time) CheckRun {
+	return CheckRun{ID: 7, Name: DefaultContext, AppID: GitHubActionsAppID, Status: status, Conclusion: conclusion, CreatedAt: created, StartedAt: started}
+}
+
+func observer(t *testing.T, f *fakeFunnel, cfg Config, at time.Time) *Observer {
+	t.Helper()
+	tr := health.New(health.Options{Clock: func() time.Time { return at }})
+	return &Observer{Cfg: cfg, Funnel: f, Breaker: NewHealthBreaker(tr, "github-hosted"), Now: func() time.Time { return at }}
+}
+
+var errBoom = errors.New("boom")
diff --git a/free/ci/internal/hostedtier/health.go b/free/ci/internal/hostedtier/health.go
new file mode 100644
index 000000000..40a65db48
--- /dev/null
+++ b/free/ci/internal/hostedtier/health.go
@@ -0,0 +1,36 @@
+package hostedtier
+
+// Purpose: the Breaker port over the HOST-11 tracker (P7-AUTO-07): billing-blocked is recorded as
+//          a quota-class outcome, which the breaker reads as unavailable until RetryAt.
+// Inputs:  a *health.Tracker and the hosted provider id.
+// Outputs: NewHealthBreaker.
+// Constraints: no new state of its own; the tracker owns persistence.
+
+import (
+	"context"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/providers"
+	"github.com/nself-org/plugins/free/ci/internal/providers/health"
+	"github.com/nself-org/plugins/free/ci/internal/providers/rest"
+)
+
+type trackerBreaker struct {
+	t  *health.Tracker
+	id string
+}
+
+// NewHealthBreaker returns the Breaker of provider id backed by t.
+func NewHealthBreaker(t *health.Tracker, id string) Breaker { return trackerBreaker{t: t, id: id} }
+
+// Blocked is true while the breaker is down or paused for a limit; a probing breaker lets a
+// request through, whose outcome ends the window.
+func (b trackerBreaker) Blocked(ctx context.Context) bool {
+	h := b.t.HealthOf(ctx, b.id)
+	return h.State == "down" || h.State == "degraded" && h.Reason == health.ReasonQuota
+}
+
+// MarkBlocked records billing-blocked as a quota outcome that lasts until until.
+func (b trackerBreaker) MarkBlocked(until time.Time) {
+	b.t.Observe(rest.Outcome{Provider: b.id, Class: providers.Quota, Status: 403, RetryAt: until})
+}
diff --git a/free/ci/internal/hostedtier/types.go b/free/ci/internal/hostedtier/types.go
new file mode 100644
index 000000000..4a11fdc54
--- /dev/null
+++ b/free/ci/internal/hostedtier/types.go
@@ -0,0 +1,108 @@
+package hostedtier
+
+// Purpose: the vocabulary of the hosted tier (P7-AUTO-07): the three decisions, their reasons, the
+//          operator-scope settings (hosted.mode, hosted.queued_sec, hosted.running_sec) and the
+//          read-only ports the observer needs.
+// Inputs:  none (types only).
+// Outputs: Decision, Result, Config, Funnel, Breaker, CheckRun.
+// Constraints: reads only; nothing here dispatches a workflow or writes a status (HOST-03 and the
+//          Checks adapter own those).
+
+import (
+	"context"
+	"time"
+)
+
+// Decision is what the auto tier does with the repository's own hosted workflow result.
+type Decision string
+
+const (
+	Use      Decision = "use"       // the hosted result stands (a red result stays red)
+	Wait     Decision = "wait"      // the hosted run is still inside its timers
+	HandOver Decision = "hand_over" // local nodes run the gates
+)
+
+// Reasons are stable machine strings; E798 is the code of an unreadable hosted state.
+const (
+	ReasonSuccess     = "hosted.success"
+	ReasonFailure     = "hosted.failure"
+	ReasonQueued      = "hosted.queued"
+	ReasonQueuedLong  = "hosted.queued_timeout"
+	ReasonRunning     = "hosted.running"
+	ReasonRunningLong = "hosted.running_timeout"
+	ReasonAbsent      = "hosted.absent"
+	ReasonAbsentLong  = "hosted.absent_timeout"
+	ReasonCancelled   = "hosted.cancelled"
+	ReasonBilling     = "hosted.billing_blocked"
+	ReasonAPIError    = "hosted.api_error"
+	ReasonUnavailable = "hosted.unavailable"
+	ReasonOff         = "hosted.off"
+	NotePaidDenied    = "hosted.paid_needs_allowed"
+	CodeUnreadable    = "E798"
+)
+
+// GitHubActionsAppID is the app that owns the Actions check runs (CI D18); a run of another app
+// with the same name, such as the Checks adapter's own, is never the hosted result.
+const GitHubActionsAppID int64 = 15368
+
+// Defaults of the operator-scope keys.
+const (
+	DefaultContext    = "nself-ci"
+	DefaultQueued     = 30 * time.Second
+	DefaultRunning    = 4 * time.Minute
+	DefaultAbsent     = 30 * time.Second
+	DefaultResidualID = "secrets.gitleaks"
+)
+
+// Mode is the operator-scope key hosted.mode.
+type Mode string
+
+const (
+	ModeOff  Mode = "off"
+	ModeFree Mode = "free"
+	ModePaid Mode = "paid"
+)
+
+// Config is the resolved hosted.* keys. Zero fields take the defaults through Normalize.
+type Config struct {
+	Mode     Mode
+	Context  string
+	AppID    int64
+	Queued   time.Duration
+	Running  time.Duration
+	Absent   time.Duration
+	Residual []string
+	// PaidAllowed is the answer of schedpolicy.PaidAllowed for the hosted provider; paid needs it.
+	PaidAllowed bool
+}
+
+// CheckRun is the part of a GitHub check run the decision reads.
+type CheckRun struct {
+	ID                   int64
+	Name                 string
+	AppID                int64
+	Status, Conclusion   string
+	CreatedAt, StartedAt time.Time
+}
+
+// Funnel is the read-only view of the HOST-18 REST funnel for one repository.
+type Funnel interface {
+	CheckRuns(ctx context.Context, sha string) ([]CheckRun, error)
+	Annotations(ctx context.Context, runID int64) ([]string, error)
+}
+
+// Breaker is the HOST-11 breaker of the hosted provider.
+type Breaker interface {
+	Blocked(ctx context.Context) bool
+	MarkBlocked(until time.Time)
+}
+
+// Result is one decision.
+type Result struct {
+	Decision Decision
+	Reason   string
+	Mode     Mode     // the effective mode
+	Notes    []string // for example NotePaidDenied
+	Residual []string // for Use: the checks the workflow does not cover
+	Requests int      // API requests made, for tests and the usage ledger
+}
diff --git a/free/ci/internal/model/evidence.go b/free/ci/internal/model/evidence.go
index 3685c1dfa..70c9cf961 100644
--- a/free/ci/internal/model/evidence.go
+++ b/free/ci/internal/model/evidence.go
@@ -30,6 +30,9 @@ type Evidence struct {
 	Freshness            Freshness            `json:"freshness"`
 	Signature            Signature            `json:"signature"`
 	ProviderAttestation  *ProviderAttestation `json:"provider_attestation,omitempty"`
+	// P7-AUTO-21, additive within v1: per-attempt runner and timings, and coded infra errors.
+	Attempts []AttemptEvidence `json:"attempts,omitempty"`
+	Errors   []EvidenceError   `json:"errors,omitempty"`
 }
 
 // Pipeline is one planned run and its selected jobs.
diff --git a/free/ci/internal/model/evidence_attempts.go b/free/ci/internal/model/evidence_attempts.go
new file mode 100644
index 000000000..e996ac02f
--- /dev/null
+++ b/free/ci/internal/model/evidence_attempts.go
@@ -0,0 +1,40 @@
+package model
+
+// Additive, optional ci.evidence/v1 keys (P7-AUTO-21). A document written
+// before them has none of these keys and still validates; the contract stays
+// v1 and experimental.
+
+// RunnerKinds are the placement kinds an attempt can record.
+var RunnerKinds = []string{"local", "ssh", "agent", "hosted"}
+
+// AttemptRunner is where one attempt ran, from its recorded placement.
+type AttemptRunner struct {
+	Kind string `json:"kind"` // local | ssh | agent | hosted
+	Tier string `json:"tier"`
+	Pool string `json:"pool"`
+	Rank int    `json:"rank"` // position of the chosen runner in the placement ranking (0 is first)
+}
+
+// AttemptTimings splits an attempt's wall time from its state transitions.
+// A nil member is a phase that did not happen (a local attempt has no transfer).
+type AttemptTimings struct {
+	QueueMS    *int64 `json:"queue_ms,omitempty"`
+	TransferMS *int64 `json:"transfer_ms,omitempty"`
+	RunMS      *int64 `json:"run_ms,omitempty"`
+}
+
+// AttemptEvidence is the runner and timing record of one attempt of a job.
+type AttemptEvidence struct {
+	JobID   string          `json:"job_id"`
+	Attempt int             `json:"attempt"`
+	Runner  AttemptRunner   `json:"runner"`
+	Timings *AttemptTimings `json:"timings,omitempty"`
+}
+
+// EvidenceError is a coded infrastructure error met while producing the run.
+type EvidenceError struct {
+	Code    string `json:"code"`
+	JobID   string `json:"job_id,omitempty"`
+	Attempt int    `json:"attempt,omitempty"`
+	Detail  string `json:"detail,omitempty"` // short and already redacted
+}
diff --git a/free/ci/internal/model/evidence_attempts_test.go b/free/ci/internal/model/evidence_attempts_test.go
new file mode 100644
index 000000000..97fbd8b5a
--- /dev/null
+++ b/free/ci/internal/model/evidence_attempts_test.go
@@ -0,0 +1,37 @@
+package model
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestEvidenceAdditiveBackwardCompat: documents stored before the additive keys
+// validate against the new schema, and the new keys validate and are bounded.
+func TestEvidenceAdditiveBackwardCompat(t *testing.T) {
+	schema, err := os.ReadFile(filepath.Join("..", "..", "schemas", "ci-evidence.v1.schema.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	old, err := filepath.Glob("testdata/valid/evidence.*.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	old = append(old, filepath.Join("..", "evidence", "testdata", "evidence.pre-auto21.json"))
+	for _, path := range old {
+		body, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := ValidateJSON(schema, body); err != nil {
+			t.Errorf("%s: %v", path, err)
+		}
+	}
+	bad, err := os.ReadFile("testdata/invalid/evidence.attempt-kind.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := ValidateJSON(schema, bad); err == nil {
+		t.Error("an unknown runner kind must fail the schema")
+	}
+}
diff --git a/free/ci/internal/model/schema.go b/free/ci/internal/model/schema.go
index e0c30d7cb..c3b01bc19 100644
--- a/free/ci/internal/model/schema.go
+++ b/free/ci/internal/model/schema.go
@@ -158,6 +158,11 @@ func decorateEvidence(s *jsonschema.Schema) {
 	s.Properties["freshness"].Properties["state"].Enum = choices("current", "stale", "unknown")
 	s.Properties["selection"].Properties["mode"].Enum = choices("full", "affected")
 	s.Properties["checks"].Items.Properties["excerpt"].MaxLength = intPtr(4096)
+	kinds := make([]any, len(RunnerKinds))
+	for i, k := range RunnerKinds {
+		kinds[i] = k
+	}
+	s.Properties["attempts"].Items.Properties["runner"].Properties["kind"].Enum = kinds
 	allowedFailure := &jsonschema.Schema{Properties: map[string]*jsonschema.Schema{"allow_failure": {Const: anyPtr(true)}}, Required: []string{"allow_failure"}}
 	badCheck := &jsonschema.Schema{
 		Properties: map[string]*jsonschema.Schema{"required": {Const: anyPtr(true)}},
diff --git a/free/ci/internal/model/testdata/invalid/evidence.attempt-kind.json b/free/ci/internal/model/testdata/invalid/evidence.attempt-kind.json
new file mode 100644
index 000000000..8b5a4548e
--- /dev/null
+++ b/free/ci/internal/model/testdata/invalid/evidence.attempt-kind.json
@@ -0,0 +1,133 @@
+{
+  "artifacts": [],
+  "attempts": [
+    {
+      "attempt": 1,
+      "job_id": "build",
+      "runner": {
+        "kind": "carrier-pigeon",
+        "pool": "personal",
+        "rank": 0,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 0,
+        "run_ms": 1200
+      }
+    },
+    {
+      "attempt": 1,
+      "job_id": "test",
+      "runner": {
+        "kind": "ssh",
+        "pool": "lab",
+        "rank": 1,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 40,
+        "run_ms": 9000,
+        "transfer_ms": 350
+      }
+    },
+    {
+      "attempt": 2,
+      "job_id": "test",
+      "runner": {
+        "kind": "hosted",
+        "pool": "github",
+        "rank": 2,
+        "tier": "hosted"
+      },
+      "timings": {
+        "queue_ms": 2500,
+        "run_ms": 8000,
+        "transfer_ms": 0
+      }
+    }
+  ],
+  "binding": {
+    "reason": null,
+    "state": "bound"
+  },
+  "checks": [
+    {
+      "excerpt": "",
+      "findings": 0,
+      "id": "lint",
+      "job_id": "build",
+      "kind": "quality",
+      "log_ref": null,
+      "required": true,
+      "result": "pass",
+      "substantive": true,
+      "tool": "go",
+      "tool_version": null
+    }
+  ],
+  "counts": {
+    "error": 0,
+    "fail": 0,
+    "pass": 1,
+    "skip": 0,
+    "total": 1
+  },
+  "errors": [
+    {
+      "attempt": 1,
+      "code": "CI-INFRA-OOM",
+      "detail": "runner out of memory",
+      "job_id": "test"
+    }
+  ],
+  "freshness": {
+    "reason": null,
+    "state": "current"
+  },
+  "input_digests": {
+    "config": "abc",
+    "generated": [],
+    "lockfiles": []
+  },
+  "pipeline": {
+    "id": "p1",
+    "kind": "default",
+    "name": "default"
+  },
+  "policy_digest": "abc",
+  "producer": {
+    "kind": "coordinator-recorded",
+    "version": "1.5.0"
+  },
+  "repo_id": "local:abc",
+  "result": "pass",
+  "retries": [],
+  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "run_id": "r1",
+  "runner": {
+    "id": "local",
+    "isolation": "process",
+    "platform": "darwin/arm64",
+    "provider": "local"
+  },
+  "schema": "ci.evidence/v1",
+  "selection": {
+    "digest": "abc",
+    "mode": "affected",
+    "reason": "selection.affected"
+  },
+  "signature": {
+    "kind": "coordinator-recorded"
+  },
+  "source_trust": "owner",
+  "timings": {
+    "duration_ms": null,
+    "finished_at": null,
+    "queued_at": null,
+    "started_at": null
+  },
+  "tool_versions": {},
+  "tracked_changes_digest": null,
+  "trigger": "local",
+  "worktree_state": "clean"
+}
diff --git a/free/ci/internal/model/testdata/valid/evidence.attempts.json b/free/ci/internal/model/testdata/valid/evidence.attempts.json
new file mode 100644
index 000000000..db23fc15a
--- /dev/null
+++ b/free/ci/internal/model/testdata/valid/evidence.attempts.json
@@ -0,0 +1,133 @@
+{
+  "artifacts": [],
+  "attempts": [
+    {
+      "attempt": 1,
+      "job_id": "build",
+      "runner": {
+        "kind": "local",
+        "pool": "personal",
+        "rank": 0,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 0,
+        "run_ms": 1200
+      }
+    },
+    {
+      "attempt": 1,
+      "job_id": "test",
+      "runner": {
+        "kind": "ssh",
+        "pool": "lab",
+        "rank": 1,
+        "tier": "owner"
+      },
+      "timings": {
+        "queue_ms": 40,
+        "run_ms": 9000,
+        "transfer_ms": 350
+      }
+    },
+    {
+      "attempt": 2,
+      "job_id": "test",
+      "runner": {
+        "kind": "hosted",
+        "pool": "github",
+        "rank": 2,
+        "tier": "hosted"
+      },
+      "timings": {
+        "queue_ms": 2500,
+        "run_ms": 8000,
+        "transfer_ms": 0
+      }
+    }
+  ],
+  "binding": {
+    "reason": null,
+    "state": "bound"
+  },
+  "checks": [
+    {
+      "excerpt": "",
+      "findings": 0,
+      "id": "lint",
+      "job_id": "build",
+      "kind": "quality",
+      "log_ref": null,
+      "required": true,
+      "result": "pass",
+      "substantive": true,
+      "tool": "go",
+      "tool_version": null
+    }
+  ],
+  "counts": {
+    "error": 0,
+    "fail": 0,
+    "pass": 1,
+    "skip": 0,
+    "total": 1
+  },
+  "errors": [
+    {
+      "attempt": 1,
+      "code": "CI-INFRA-OOM",
+      "detail": "runner out of memory",
+      "job_id": "test"
+    }
+  ],
+  "freshness": {
+    "reason": null,
+    "state": "current"
+  },
+  "input_digests": {
+    "config": "abc",
+    "generated": [],
+    "lockfiles": []
+  },
+  "pipeline": {
+    "id": "p1",
+    "kind": "default",
+    "name": "default"
+  },
+  "policy_digest": "abc",
+  "producer": {
+    "kind": "coordinator-recorded",
+    "version": "1.5.0"
+  },
+  "repo_id": "local:abc",
+  "result": "pass",
+  "retries": [],
+  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "run_id": "r1",
+  "runner": {
+    "id": "local",
+    "isolation": "process",
+    "platform": "darwin/arm64",
+    "provider": "local"
+  },
+  "schema": "ci.evidence/v1",
+  "selection": {
+    "digest": "abc",
+    "mode": "affected",
+    "reason": "selection.affected"
+  },
+  "signature": {
+    "kind": "coordinator-recorded"
+  },
+  "source_trust": "owner",
+  "timings": {
+    "duration_ms": null,
+    "finished_at": null,
+    "queued_at": null,
+    "started_at": null
+  },
+  "tool_versions": {},
+  "tracked_changes_digest": null,
+  "trigger": "local",
+  "worktree_state": "clean"
+}
diff --git a/free/ci/internal/nodes/inventory/candidate.go b/free/ci/internal/nodes/inventory/candidate.go
new file mode 100644
index 000000000..dce77e9a0
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/candidate.go
@@ -0,0 +1,69 @@
+package inventory
+
+// Purpose: the registry record of a host the inventory names but the registry does not know (P7-AUTO-04):
+//          a discovered candidate, ineligible, with no authorized project and no trust.
+// Inputs:  an Entry with an ssh target.
+// Outputs: a model.Capability that passes model.ValidateCapability; registry.Register applies the safe
+//          trust block and the discovered lifecycle.
+// Constraints: no host key is pinned and nothing is enabled (`ci nodes add` owns both, NODE-05); the
+//          candidate carries the identity label `inventory` as its source marker (the capability schema
+//          has no free-form fact source); the record holds the ssh target and the platform words only.
+
+import (
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// SourceLabel marks a candidate that sync created.
+const SourceLabel = "inventory"
+
+func unknown[T any](src string, now time.Time) model.Fact[T] {
+	return model.Fact[T]{Source: src, ObservedAt: now, Confidence: "unknown"}
+}
+
+func known[T any](v T, src string, now time.Time) model.Fact[T] {
+	return model.Fact[T]{Value: &v, Source: src, ObservedAt: now, Confidence: "known"}
+}
+
+func optional(v, src string, now time.Time) model.Fact[string] {
+	if v == "" {
+		return unknown[string](src, now)
+	}
+	return known(v, src, now)
+}
+
+// NewCandidate builds the capability document of a new candidate.
+func NewCandidate(e Entry, now time.Time) model.Capability {
+	user, host := "", e.SSH
+	if i := strings.LastIndexByte(host, '@'); i >= 0 {
+		user, host = host[:i], host[i+1:]
+	}
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Identity = model.CapabilityIdentity{ID: e.ID, Name: e.ID, Provider: "ssh", Transport: "ssh", Labels: []string{SourceLabel},
+		HostKeyFingerprints: []string{}, Ownership: unknown[string]("assigned", now), MachineID: unknown[string]("self", now),
+		AgeRecipient: unknown[string]("self", now), SSH: &model.CapabilitySSH{Alias: host, User: user}}
+	c.Platform = model.CapabilityPlatform{OS: optional(e.OS, "assigned", now), Arch: optional(e.Arch, "assigned", now),
+		Kernel: unknown[string]("probe", now), OSVersion: unknown[string]("probe", now), Virtualization: unknown[string]("probe", now)}
+	c.Resources = model.CapabilityResources{CPU: unknown[float64]("probe", now), MemMB: unknown[int64]("probe", now),
+		DiskFreeMB: unknown[int64]("probe", now), Accelerators: unknown[[]string]("probe", now),
+		Reserved: model.CapabilityReserved{CPU: unknown[float64]("assigned", now), MemMB: unknown[int64]("assigned", now)}}
+	c.Tools = model.CapabilityTools{Docker: unknown[bool]("probe", now), Podman: unknown[bool]("probe", now),
+		GVisor: unknown[bool]("probe", now), Tart: unknown[bool]("probe", now), Toolchains: map[string]model.Fact[string]{},
+		Browsers: unknown[[]string]("probe", now), Services: unknown[[]string]("probe", now), Custom: map[string]model.Fact[string]{}}
+	c.Availability = model.CapabilityAvailability{State: known("offline", "assigned", now), Slots: unknown[int]("self", now),
+		Running: unknown[int]("self", now), BatteryPct: unknown[int]("probe", now), PluggedIn: unknown[bool]("probe", now),
+		Interactive: unknown[string]("probe", now), Persistence: unknown[bool]("assigned", now),
+		OnBattery: unknown[string]("assigned", now), InteractivePolicy: unknown[string]("assigned", now)}
+	c.Location = model.CapabilityLocation{Kind: unknown[string]("self", now), Region: unknown[string]("self", now)}
+	c.Economics = model.CapabilityEconomics{Class: unknown[string]("self", now), MarginalCostPerMin: unknown[float64]("self", now),
+		Allowance: model.CapabilityAllowance{KnownRemaining: unknown[float64]("self", now), ResetAt: unknown[time.Time]("self", now),
+			Confidence: unknown[string]("self", now)}}
+	c.Separation = model.CapabilitySeparation{UIDSeparation: known(false, "assigned", now), UserNS: known(false, "assigned", now),
+		SigningEligible: known(false, "assigned", now)}
+	c.Verified = model.CapabilityVerified{By: "self", At: now}
+	c.Protocol = model.CapabilityProtocol{Versions: []int{1}, Min: 1}
+	c.Lifecycle = model.CapabilityLifecycle{Discovered: true, AuthorizedProjects: []string{}}
+	return c
+}
diff --git a/free/ci/internal/nodes/inventory/codes.go b/free/ci/internal/nodes/inventory/codes.go
new file mode 100644
index 000000000..8212912bf
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/codes.go
@@ -0,0 +1,53 @@
+package inventory
+
+// Purpose: the code and typed error of `nself ci nodes sync` (P7-AUTO-04).
+// Inputs:  none.
+// Outputs: E793 registered through model.Register; *Error carrying the code and a stable reason key.
+// Constraints: one code for every refusal of the whole input (size, time, strict decode, schema, a
+//          failed discovery command, a TEAM coordinator); a rejected single entry is a Reject row in the
+//          summary, never an error.
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// CodeInventory is the code every whole-input refusal carries.
+const CodeInventory = "E793"
+
+// Reason keys carried by Error.Reason.
+const (
+	ReasonTooLarge   = "too_large"
+	ReasonTimeout    = "timeout"
+	ReasonCmdFailed  = "cmd_failed"
+	ReasonDecode     = "decode"
+	ReasonSchema     = "schema"
+	ReasonTeam       = "team_coordinator"
+	ReasonNoRunner   = "no_runner"
+	ReasonReadFailed = "read_failed"
+)
+
+func init() {
+	model.Register(model.Code{ID: CodeInventory, Class: "usage", Summary: "runner inventory refused",
+		Fix: "Give a file or a command that prints one inventory/v1 document under 1 MiB within 10 seconds; run sync on the machine that owns the nodes, not on a TEAM coordinator"})
+}
+
+// Error is a refusal of the whole inventory input.
+type Error struct{ Code, Reason, Msg string }
+
+func (e *Error) Error() string { return fmt.Sprintf("%s: %s", e.Code, e.Msg) }
+
+func newErr(reason, format string, a ...any) *Error {
+	return &Error{Code: CodeInventory, Reason: reason, Msg: fmt.Sprintf(format, a...)}
+}
+
+// ReasonOf returns the reason key of an inventory error, or "".
+func ReasonOf(err error) string {
+	var e *Error
+	if errors.As(err, &e) {
+		return e.Reason
+	}
+	return ""
+}
diff --git a/free/ci/internal/nodes/inventory/decode.go b/free/ci/internal/nodes/inventory/decode.go
new file mode 100644
index 000000000..79ef0e24f
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/decode.go
@@ -0,0 +1,125 @@
+package inventory
+
+// Purpose: the inventory/v1 contract (P7-AUTO-04): one document of runner entries from a file or from the
+//          output of a discovery command, decoded strictly and checked entry by entry.
+// Inputs:  raw bytes (YAML or JSON; JSON is YAML).
+// Outputs: Document, or a whole-input refusal (unknown field, wrong schema, too many entries); per-entry
+//          problems come back from Entry.Check so one bad entry never aborts the others.
+// Constraints: unknown fields anywhere refuse the whole document; there is no slots field (slots are
+//          agent-side); a label may not use the keys the dedicated fields own (rank, pool.*).
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+)
+
+// SchemaID is the contract id carried by every document.
+const SchemaID = "inventory/v1"
+
+// Bounds of one document and one entry.
+const (
+	MaxEntries   = 1000
+	MaxRank      = 1000
+	MaxSkipRepos = 64
+	maxRepoLen   = 256
+)
+
+// Entry is one runner of the inventory. Pointer fields tell absent from zero.
+type Entry struct {
+	ID         string   `yaml:"id" json:"id"`
+	SSH        string   `yaml:"ssh" json:"ssh"`
+	OS         string   `yaml:"os" json:"os"`
+	Arch       string   `yaml:"arch" json:"arch"`
+	Rank       *int     `yaml:"rank" json:"rank"`
+	Local      bool     `yaml:"local" json:"local"`
+	Labels     []string `yaml:"labels" json:"labels"`
+	Pools      []string `yaml:"pools" json:"pools"`
+	SkipRepos  []string `yaml:"skip_repos" json:"skip_repos"`
+	PublicOnly bool     `yaml:"public_only" json:"public_only"`
+}
+
+// Document is the inventory/v1 document.
+type Document struct {
+	Schema  string  `yaml:"schema" json:"schema"`
+	Entries []Entry `yaml:"entries" json:"entries"`
+}
+
+var (
+	idRE   = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,127}$`)
+	sshRE  = regexp.MustCompile(`^([A-Za-z0-9._-]{1,64}@)?[A-Za-z0-9][A-Za-z0-9._-]{0,252}$`)
+	osRE   = regexp.MustCompile(`^(linux|darwin|windows)$`)
+	archRE = regexp.MustCompile(`^(amd64|arm64)$`)
+)
+
+// Decode reads one document strictly: an unknown field, a second document or a wrong schema id refuses it all.
+func Decode(raw []byte) (Document, error) {
+	dec := yaml.NewDecoder(bytes.NewReader(raw))
+	dec.KnownFields(true)
+	var d Document
+	if err := dec.Decode(&d); err != nil {
+		return Document{}, newErr(ReasonDecode, "the inventory is not a valid inventory/v1 document: %s", firstLine(err))
+	}
+	var extra any
+	if err := dec.Decode(&extra); !errors.Is(err, io.EOF) {
+		return Document{}, newErr(ReasonDecode, "the inventory holds more than one document")
+	}
+	if d.Schema != SchemaID {
+		return Document{}, newErr(ReasonSchema, "schema must be %s", SchemaID)
+	}
+	if len(d.Entries) > MaxEntries {
+		return Document{}, newErr(ReasonSchema, "%d entries, at most %d allowed", len(d.Entries), MaxEntries)
+	}
+	return d, nil
+}
+
+func firstLine(err error) string {
+	s, _, _ := strings.Cut(err.Error(), "\n")
+	return s
+}
+
+// Check validates one entry; the error text is the Reject reason.
+func (e Entry) Check() error {
+	switch {
+	case !idRE.MatchString(e.ID):
+		return fmt.Errorf("id is not a lower-case node id")
+	case e.SSH != "" && !sshRE.MatchString(e.SSH):
+		return fmt.Errorf("ssh must be host or user@host")
+	case e.OS != "" && !osRE.MatchString(e.OS):
+		return fmt.Errorf("os must be linux, darwin or windows")
+	case e.Arch != "" && !archRE.MatchString(e.Arch):
+		return fmt.Errorf("arch must be amd64 or arm64")
+	case e.Rank != nil && (*e.Rank < 0 || *e.Rank > MaxRank):
+		return fmt.Errorf("rank must be 0 to %d", MaxRank)
+	case len(e.SkipRepos) > MaxSkipRepos:
+		return fmt.Errorf("more than %d skip_repos", MaxSkipRepos)
+	}
+	for _, p := range e.Pools {
+		if !pools.ValidID(p) || pools.Reserved(p) {
+			return fmt.Errorf("pool %q is not a valid explicit pool id", p)
+		}
+	}
+	for _, r := range e.SkipRepos {
+		if r == "" || len(r) > maxRepoLen || strings.ContainsFunc(r, func(c rune) bool { return c < ' ' || c == 0x7f }) {
+			return fmt.Errorf("a skip_repos entry is empty, too long or has control characters")
+		}
+	}
+	for _, l := range e.Labels {
+		if k, _, _ := strings.Cut(l, "="); k == "rank" || strings.HasPrefix(k, "pool.") {
+			return fmt.Errorf("label %s is owned by the rank and pools fields", k)
+		}
+	}
+	want, err := e.Want()
+	if err != nil {
+		return err
+	}
+	return labels.Validate(want)
+}
diff --git a/free/ci/internal/nodes/inventory/decode_test.go b/free/ci/internal/nodes/inventory/decode_test.go
new file mode 100644
index 000000000..dbdd82a34
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/decode_test.go
@@ -0,0 +1,140 @@
+package inventory
+
+// Purpose: tests of the inventory/v1 decode, the entry checks and the two readers (P7-AUTO-04).
+// Inputs:  inline documents and fake runners.
+// Outputs: pass or fail.
+// Constraints: no network, no processes, no sleeps (the timeout test blocks on the context only).
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+const goodDoc = `schema: inventory/v1
+entries:
+  - id: vps1
+    ssh: ci@vps1.example.test
+    os: linux
+    arch: amd64
+    rank: 2
+    labels: [gpu=none]
+    pools: [mine]
+    skip_repos: [/src/old]
+    public_only: true
+`
+
+func TestStrictInventoryDecode(t *testing.T) {
+	d, err := Decode([]byte(goodDoc))
+	if err != nil || len(d.Entries) != 1 || d.Entries[0].Rank == nil || *d.Entries[0].Rank != 2 || !d.Entries[0].PublicOnly {
+		t.Fatalf("good doc: %+v %v", d, err)
+	}
+	if _, err = Decode([]byte(`{"schema":"inventory/v1","entries":[{"id":"a","ssh":"h"}]}`)); err != nil {
+		t.Fatalf("json is accepted: %v", err)
+	}
+	bad := map[string]string{
+		"unknown entry field": "schema: inventory/v1\nentries:\n  - id: a\n    slots: 4\n",
+		"unknown top field":   "schema: inventory/v1\nextra: 1\nentries: []\n",
+		"wrong schema":        "schema: inventory/v2\nentries: []\n",
+		"no schema":           "entries: []\n",
+		"two documents":       goodDoc + "---\n" + goodDoc,
+		"not a document":      "- a\n- b\n",
+	}
+	for name, doc := range bad {
+		if _, err := Decode([]byte(doc)); err == nil || !strings.HasPrefix(err.Error(), CodeInventory) {
+			t.Errorf("%s: err = %v", name, err)
+		}
+	}
+	var many strings.Builder
+	many.WriteString("schema: inventory/v1\nentries:\n")
+	for i := 0; i <= MaxEntries; i++ {
+		many.WriteString("  - id: n\n")
+	}
+	if _, err := Decode([]byte(many.String())); ReasonOf(err) != ReasonSchema {
+		t.Fatalf("too many entries: %v", err)
+	}
+}
+
+func TestEntryCheck(t *testing.T) {
+	rank := func(n int) *int { return &n }
+	cases := []struct {
+		name string
+		e    Entry
+		ok   bool
+	}{
+		{"minimal", Entry{ID: "a"}, true},
+		{"upper id", Entry{ID: "Abc"}, false},
+		{"bad ssh", Entry{ID: "a", SSH: "h;rm"}, false},
+		{"bad os", Entry{ID: "a", OS: "plan9"}, false},
+		{"bad arch", Entry{ID: "a", Arch: "mips"}, false},
+		{"negative rank", Entry{ID: "a", Rank: rank(-1)}, false},
+		{"huge rank", Entry{ID: "a", Rank: rank(MaxRank + 1)}, false},
+		{"reserved pool", Entry{ID: "a", Pools: []string{"hosted"}}, false},
+		{"bad pool", Entry{ID: "a", Pools: []string{"Bad"}}, false},
+		{"rank label", Entry{ID: "a", Labels: []string{"rank=1"}}, false},
+		{"pool label", Entry{ID: "a", Labels: []string{"pool.x"}}, false},
+		{"reserved label", Entry{ID: "a", Labels: []string{"nself.x"}}, false},
+		{"empty skip", Entry{ID: "a", SkipRepos: []string{""}}, false},
+		{"control skip", Entry{ID: "a", SkipRepos: []string{"a\nb"}}, false},
+	}
+	for _, c := range cases {
+		if err := c.e.Check(); (err == nil) != c.ok {
+			t.Errorf("%s: err = %v", c.name, err)
+		}
+	}
+}
+
+func TestCmdCapsAndTimeout(t *testing.T) {
+	ok := func(out string, exit int, err error) Runner {
+		return func(context.Context, []string) (string, int, error) { return out, exit, err }
+	}
+	small := Limits{Timeout: time.Second, MaxBytes: 64}
+	if d, err := ReadCmd(context.Background(), ok("schema: inventory/v1\nentries: []\n", 0, nil), []string{"x"}, small); err != nil || len(d.Entries) != 0 {
+		t.Fatalf("fits: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), ok(goodDoc, 0, nil), []string{"x"}, small); ReasonOf(err) != ReasonTooLarge {
+		t.Fatalf("oversized: %v", err)
+	}
+	blocked := func(ctx context.Context, _ []string) (string, int, error) { <-ctx.Done(); return "", -1, ctx.Err() }
+	if _, err := ReadCmd(context.Background(), blocked, []string{"x"}, Limits{Timeout: time.Millisecond, MaxBytes: 64}); ReasonOf(err) != ReasonTimeout {
+		t.Fatalf("slow: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), ok("", 3, nil), []string{"x"}, small); ReasonOf(err) != ReasonCmdFailed {
+		t.Fatalf("exit status: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), ok("", -1, context.Canceled), []string{"x"}, small); ReasonOf(err) != ReasonCmdFailed {
+		t.Fatalf("not run: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), ok("schema: inventory/v1\nbogus: 1\n", 0, nil), []string{"x"}, small); ReasonOf(err) != ReasonDecode {
+		t.Fatalf("unknown field: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), nil, []string{"x"}, small); ReasonOf(err) != ReasonNoRunner {
+		t.Fatalf("no runner: %v", err)
+	}
+	if _, err := ReadCmd(context.Background(), ok("", 0, nil), nil, small); ReasonOf(err) != ReasonNoRunner {
+		t.Fatalf("no argv: %v", err)
+	}
+	if DefaultLimits.Timeout != 10*time.Second || DefaultLimits.MaxBytes != 1<<20 {
+		t.Fatalf("contract limits changed: %+v", DefaultLimits)
+	}
+}
+
+func TestReadFileCap(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "inv.yaml")
+	if err := os.WriteFile(p, []byte(goodDoc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if d, err := ReadFile(p, Limits{}); err != nil || len(d.Entries) != 1 {
+		t.Fatalf("read: %v", err)
+	}
+	if _, err := ReadFile(p, Limits{MaxBytes: 10}); ReasonOf(err) != ReasonTooLarge {
+		t.Fatalf("cap: %v", err)
+	}
+	if _, err := ReadFile(filepath.Join(dir, "missing.yaml"), Limits{}); ReasonOf(err) != ReasonReadFailed {
+		t.Fatalf("missing: %v", err)
+	}
+}
diff --git a/free/ci/internal/nodes/inventory/read.go b/free/ci/internal/nodes/inventory/read.go
new file mode 100644
index 000000000..9e067ce2b
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/read.go
@@ -0,0 +1,81 @@
+package inventory
+
+// Purpose: read an inventory from a file or from the output of a discovery command (P7-AUTO-04).
+// Inputs:  a path, or an argv and a Runner (the exec-funnel caller; the CLI passes report.Capture).
+// Outputs: the strictly decoded Document.
+// Constraints: a file is read with a size cap, never past it; a command runs without a shell through the
+//          funnel's allowlisted environment, is cut off after Limits.Timeout (10 s) and refused when its
+//          output passes Limits.MaxBytes (1 MiB); a cut-off or oversized command applies nothing; the
+//          output is decoded and dropped, never persisted. The funnel merges stderr into its output, so a
+//          tool that warns on stderr fails the strict decode: quiet it in the command.
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"time"
+)
+
+// Limits bound one read.
+type Limits struct {
+	Timeout  time.Duration
+	MaxBytes int
+}
+
+// DefaultLimits are the contract limits: 10 s and 1 MiB.
+var DefaultLimits = Limits{Timeout: 10 * time.Second, MaxBytes: 1 << 20}
+
+// Runner runs argv through the exec funnel and returns its output and exit code. err is set only when
+// the process could not be run.
+type Runner func(ctx context.Context, argv []string) (out string, exit int, err error)
+
+func (l Limits) norm() Limits {
+	if l.Timeout <= 0 {
+		l.Timeout = DefaultLimits.Timeout
+	}
+	if l.MaxBytes <= 0 {
+		l.MaxBytes = DefaultLimits.MaxBytes
+	}
+	return l
+}
+
+// ReadFile reads and decodes the inventory file at path.
+func ReadFile(path string, l Limits) (Document, error) {
+	l = l.norm()
+	f, err := os.Open(path)
+	if err != nil {
+		return Document{}, newErr(ReasonReadFailed, "the inventory file cannot be opened")
+	}
+	defer func() { _ = f.Close() }()
+	raw, err := io.ReadAll(io.LimitReader(f, int64(l.MaxBytes)+1))
+	if err != nil {
+		return Document{}, newErr(ReasonReadFailed, "the inventory file cannot be read")
+	}
+	if len(raw) > l.MaxBytes {
+		return Document{}, newErr(ReasonTooLarge, "the inventory file is over %d bytes", l.MaxBytes)
+	}
+	return Decode(raw)
+}
+
+// ReadCmd runs argv and decodes what it prints.
+func ReadCmd(ctx context.Context, run Runner, argv []string, l Limits) (Document, error) {
+	l = l.norm()
+	if run == nil || len(argv) == 0 || argv[0] == "" {
+		return Document{}, newErr(ReasonNoRunner, "--cmd needs a command")
+	}
+	ctx, cancel := context.WithTimeout(ctx, l.Timeout)
+	defer cancel()
+	out, exit, err := run(ctx, argv)
+	switch {
+	case errors.Is(ctx.Err(), context.DeadlineExceeded):
+		return Document{}, newErr(ReasonTimeout, "the command did not finish within %s", l.Timeout)
+	case err != nil:
+		return Document{}, newErr(ReasonCmdFailed, "the command could not be run")
+	case len(out) > l.MaxBytes:
+		return Document{}, newErr(ReasonTooLarge, "the command printed more than %d bytes", l.MaxBytes)
+	case exit != 0:
+		return Document{}, newErr(ReasonCmdFailed, "the command exited with status %d", exit)
+	}
+	return Decode([]byte(out))
+}
diff --git a/free/ci/internal/nodes/inventory/schema_test.go b/free/ci/internal/nodes/inventory/schema_test.go
new file mode 100644
index 000000000..003c57eeb
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/schema_test.go
@@ -0,0 +1,64 @@
+package inventory
+
+// Purpose: keeps schemas/inventory.v1.schema.json and the Entry struct in step (P7-AUTO-04).
+// Inputs:  the schema file and the yaml tags of Entry and Document.
+// Outputs: pass or fail.
+// Constraints: file read only.
+
+import (
+	"encoding/json"
+	"os"
+	"reflect"
+	"slices"
+	"sort"
+	"strings"
+	"testing"
+)
+
+func tagNames(t reflect.Type) []string {
+	var out []string
+	for i := 0; i < t.NumField(); i++ {
+		out = append(out, strings.Split(t.Field(i).Tag.Get("yaml"), ",")[0])
+	}
+	sort.Strings(out)
+	return out
+}
+
+func keysOf(m map[string]json.RawMessage) []string {
+	var out []string
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func TestSchemaMatchesEntry(t *testing.T) {
+	raw, err := os.ReadFile("../../../schemas/inventory.v1.schema.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var top struct {
+		Properties map[string]json.RawMessage `json:"properties"`
+	}
+	if err = json.Unmarshal(raw, &top); err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(keysOf(top.Properties), tagNames(reflect.TypeOf(Document{}))) {
+		t.Fatalf("document fields: schema %v struct %v", keysOf(top.Properties), tagNames(reflect.TypeOf(Document{})))
+	}
+	var entries struct {
+		Items struct {
+			Properties map[string]json.RawMessage `json:"properties"`
+		} `json:"items"`
+	}
+	if err = json.Unmarshal(top.Properties["entries"], &entries); err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(keysOf(entries.Items.Properties), tagNames(reflect.TypeOf(Entry{}))) {
+		t.Fatalf("entry fields: schema %v struct %v", keysOf(entries.Items.Properties), tagNames(reflect.TypeOf(Entry{})))
+	}
+	if slices.Contains(keysOf(entries.Items.Properties), "slots") {
+		t.Fatal("slots are agent-side")
+	}
+}
diff --git a/free/ci/internal/nodes/inventory/sync.go b/free/ci/internal/nodes/inventory/sync.go
new file mode 100644
index 000000000..342fccaa2
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/sync.go
@@ -0,0 +1,257 @@
+package inventory
+
+// Purpose: apply an inventory to the node registry (P7-AUTO-04): new hosts become discovered candidates;
+//          for a node already enrolled sync sets only operator-owned attributes: assigned labels (pools
+//          and rank included) through the NODE-30 label edit, projects removed by skip_repos, and, for
+//          public_only, projects whose repository is not known to be public.
+// Inputs:  Env (store, registry, actor, visibility reader), the entries, Options.
+// Outputs: Summary: accepted, changes (each with its field source), candidates, rejected and notes.
+// Constraints: never changes trust, host keys, isolation or secrets eligibility; never adds a project
+//          authorization; a rejected entry never aborts the others; idempotent (a second identical run
+//          changes nothing and writes no audit row); refused on a TEAM coordinator; a candidate that is
+//          still waiting for `ci nodes add` (discovered, marked `inventory`, no project) is reported, not
+//          edited; with Options.DryRun nothing is written.
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"strconv"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// Visibility answers whether a project's repository is public. known is false when it cannot be told.
+type Visibility func(ctx context.Context, project string) (public, known bool)
+
+// Env is what Sync needs.
+type Env struct {
+	Store      *store.Store
+	Registry   *registry.Registry
+	Actor      string
+	Team       bool
+	Visibility Visibility
+	Now        func() time.Time
+}
+
+// Options of one run.
+type Options struct{ DryRun bool }
+
+// Change is one applied (or, with dry-run, planned) edit; Source names where the value came from.
+type Change struct {
+	Node   string `json:"node"`
+	Field  string `json:"field"` // label | project
+	Name   string `json:"name"`  // the label key or the project
+	From   string `json:"from,omitempty"`
+	To     string `json:"to,omitempty"`
+	Reason string `json:"reason,omitempty"`
+	Source string `json:"source"`
+}
+
+// Candidate is a host the registry did not know. Created is false for dry-run and for a pending one.
+type Candidate struct {
+	ID      string `json:"id"`
+	Created bool   `json:"created"`
+}
+
+// Reject is an entry sync did not apply.
+type Reject struct {
+	ID     string `json:"id"`
+	Reason string `json:"reason"`
+}
+
+// Summary is the JSON result of one run.
+type Summary struct {
+	Schema     string      `json:"schema"`
+	DryRun     bool        `json:"dry_run"`
+	Accepted   []string    `json:"accepted"`
+	Changed    []Change    `json:"changed"`
+	Candidates []Candidate `json:"candidates"`
+	Rejected   []Reject    `json:"rejected"`
+	Notes      []string    `json:"notes"`
+}
+
+// Sync applies entries and returns the summary. A non-nil error is a refusal of the whole run.
+func Sync(ctx context.Context, env Env, entries []Entry, opt Options) (Summary, error) {
+	sum := Summary{Schema: SchemaID, DryRun: opt.DryRun, Accepted: []string{}, Changed: []Change{}, Candidates: []Candidate{}, Rejected: []Reject{}, Notes: []string{}}
+	if env.Team {
+		return sum, newErr(ReasonTeam, "sync is refused on a TEAM coordinator: its admin owns the nodes")
+	}
+	if env.Now == nil {
+		env.Now = time.Now
+	}
+	s := &syncer{env: env, opt: opt, sum: &sum, seen: map[string]bool{}, vis: map[string][2]bool{},
+		le: labels.Env{Store: env.Store, Registry: env.Registry, Actor: env.Actor}}
+	for _, e := range entries {
+		switch {
+		case s.seen[e.ID] && e.ID != "":
+			s.reject(e.ID, "id is given twice")
+		default:
+			s.seen[e.ID] = true
+			if err := e.Check(); err != nil {
+				s.reject(e.ID, err.Error())
+				continue
+			}
+			s.one(ctx, e)
+		}
+	}
+	return sum, nil
+}
+
+type syncer struct {
+	env  Env
+	opt  Options
+	sum  *Summary
+	seen map[string]bool
+	vis  map[string][2]bool // project -> {public, known}, read once per run
+	le   labels.Env
+}
+
+func (s *syncer) reject(id, why string) {
+	s.sum.Rejected = append(s.sum.Rejected, Reject{ID: id, Reason: why})
+}
+
+func (s *syncer) one(ctx context.Context, e Entry) {
+	node := e.ID
+	var have registry.Node
+	if e.Local {
+		node = labels.LocalNode
+	} else {
+		n, err := s.env.Registry.Get(ctx, e.ID)
+		var se *store.Error
+		if errors.As(err, &se) && se.Code == "E650" {
+			s.candidate(ctx, e)
+			return
+		}
+		if err != nil {
+			s.reject(e.ID, "the registry cannot be read")
+			return
+		}
+		have = n
+		if pending(n) {
+			s.sum.Candidates = append(s.sum.Candidates, Candidate{ID: e.ID})
+			return
+		}
+	}
+	s.sum.Accepted = append(s.sum.Accepted, e.ID)
+	if err := s.applyLabels(ctx, node, e); err != nil {
+		s.reject(e.ID, "labels: "+oneLine(err))
+		return
+	}
+	if !e.Local {
+		s.applyProjects(ctx, have, e)
+	}
+}
+
+// pending reports a candidate sync created that `ci nodes add` has not enrolled yet.
+func pending(n registry.Node) bool {
+	l := n.Capability.Lifecycle
+	return l.Discovered && len(l.AuthorizedProjects) == 0 && slices.Contains(n.Capability.Identity.Labels, SourceLabel)
+}
+
+func (s *syncer) candidate(ctx context.Context, e Entry) {
+	if e.SSH == "" {
+		s.reject(e.ID, "a new host needs an ssh target")
+		return
+	}
+	created := false
+	if !s.opt.DryRun {
+		if _, err := s.env.Registry.Register(ctx, NewCandidate(e, s.env.Now().UTC()), s.env.Actor); err != nil {
+			s.reject(e.ID, "candidate: "+oneLine(err))
+			return
+		}
+		created = true
+	}
+	s.sum.Candidates = append(s.sum.Candidates, Candidate{ID: e.ID, Created: created})
+}
+
+func (s *syncer) applyLabels(ctx context.Context, node string, e Entry) error {
+	want, err := e.Want()
+	if err != nil || len(want) == 0 {
+		return err
+	}
+	have, err := s.le.Labels(ctx, node)
+	if err != nil {
+		return err
+	}
+	cur := map[string]string{}
+	for _, l := range have {
+		cur[l.Key] = l.Value
+	}
+	var diff []Change
+	for _, l := range want {
+		if v, ok := cur[l.Key]; !ok || v != l.Value {
+			diff = append(diff, Change{Node: e.ID, Field: "label", Name: l.Key, From: cur[l.Key], To: l.Value, Source: SourceLabel})
+		}
+	}
+	if len(diff) == 0 {
+		return nil
+	}
+	if !s.opt.DryRun {
+		if _, err = s.le.Edit(ctx, node, labels.Strings(want), nil); err != nil {
+			return err
+		}
+	}
+	s.sum.Changed = append(s.sum.Changed, diff...)
+	return nil
+}
+
+func (s *syncer) applyProjects(ctx context.Context, n registry.Node, e Entry) {
+	if len(e.SkipRepos) == 0 && !e.PublicOnly {
+		return
+	}
+	for _, p := range slices.Clone(n.Capability.Lifecycle.AuthorizedProjects) {
+		why := ""
+		switch {
+		case slices.Contains(e.SkipRepos, p):
+			why = "skip_repos"
+		case e.PublicOnly:
+			why = s.notPublic(ctx, p)
+		}
+		if why == "" {
+			continue
+		}
+		if !s.opt.DryRun {
+			if _, err := s.env.Registry.Deauthorize(ctx, e.ID, p, s.env.Actor); err != nil {
+				s.reject(e.ID, "project: "+oneLine(err))
+				return
+			}
+		}
+		s.sum.Changed = append(s.sum.Changed, Change{Node: e.ID, Field: "project", Name: p, From: "authorized", To: "removed", Reason: why, Source: SourceLabel})
+	}
+}
+
+// notPublic returns why a project may not stay on a public_only node ("" when it may). Visibility is read
+// once per project per run; an unreadable answer authorizes nothing and is reported once.
+func (s *syncer) notPublic(ctx context.Context, p string) string {
+	v, ok := s.vis[p]
+	if !ok {
+		if s.env.Visibility != nil {
+			v[0], v[1] = s.env.Visibility(ctx, p)
+		}
+		s.vis[p] = v
+		if !v[1] {
+			s.sum.Notes = append(s.sum.Notes, "visibility unknown for project "+strconv.Quote(p)+": not authorized on public_only nodes")
+		}
+	}
+	switch {
+	case !v[1]:
+		return "public_only: visibility unknown"
+	case !v[0]:
+		return "public_only: private repository"
+	}
+	return ""
+}
+
+func oneLine(err error) string {
+	s := err.Error()
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\n' {
+			return s[:i]
+		}
+	}
+	return s
+}
diff --git a/free/ci/internal/nodes/inventory/sync_test.go b/free/ci/internal/nodes/inventory/sync_test.go
new file mode 100644
index 000000000..14fd7546f
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/sync_test.go
@@ -0,0 +1,259 @@
+package inventory
+
+// Purpose: tests of Sync (P7-AUTO-04) against a real SQLite store and registry: candidates, label and
+//          rank application that survives a store reopen, skip_repos, public_only, idempotence, the
+//          trust fence, rejections that do not abort, dry-run and the TEAM refusal.
+// Inputs:  the laptop capability fixture registered under several node ids.
+// Outputs: pass or fail.
+// Constraints: no network, no processes, no sleeps.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+type fixture struct {
+	path string
+	st   *store.Store
+	reg  *registry.Registry
+}
+
+func openFixture(t *testing.T, path string) *fixture {
+	t.Helper()
+	st, err := store.Open(path, store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	return &fixture{path: path, st: st, reg: registry.New(st)}
+}
+
+// newFixture registers the given enrolled nodes, each authorized on /src/pub and /src/priv.
+func newFixture(t *testing.T, nodes ...string) *fixture {
+	t.Helper()
+	f := openFixture(t, filepath.Join(t.TempDir(), "state.db"))
+	b, err := os.ReadFile("../../model/testdata/capability/valid/laptop.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range nodes {
+		var c model.Capability
+		if err = json.Unmarshal(b, &c); err != nil {
+			t.Fatal(err)
+		}
+		c.Identity.ID, c.Identity.Name = id, id
+		ctx := context.Background()
+		if _, err = f.reg.Register(ctx, c, "operator"); err != nil {
+			t.Fatal(err)
+		}
+		for _, p := range []string{"/src/pub", "/src/priv", "/src/old"} {
+			if _, err = f.reg.Authorize(ctx, id, p, "operator"); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	return f
+}
+
+func (f *fixture) env(vis Visibility) Env {
+	return Env{Store: f.st, Registry: f.reg, Actor: "cli:test", Visibility: vis}
+}
+
+func (f *fixture) audit(t *testing.T) int {
+	t.Helper()
+	rows, err := f.st.AuditEntries(context.Background(), 0, 100000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return len(rows)
+}
+
+func rankOf(n int) *int { return &n }
+
+func threeEntries() []Entry {
+	return []Entry{
+		{ID: "mini1", Rank: rankOf(1), Labels: []string{"xcode"}, Pools: []string{"mine"}, SkipRepos: []string{"/src/old"}},
+		{ID: "vps1", SSH: "ci@vps1.example.test", OS: "linux", Arch: "amd64", Rank: rankOf(3), Pools: []string{"mine"}},
+		{ID: "vps2", SSH: "vps2.example.test"},
+	}
+}
+
+func TestSyncAppliesFixture(t *testing.T) {
+	ctx := context.Background()
+	f := newFixture(t, "mini1")
+	before, _ := f.reg.Get(ctx, "mini1")
+	sum, err := Sync(ctx, f.env(nil), threeEntries(), Options{})
+	if err != nil || len(sum.Rejected) != 0 {
+		t.Fatalf("sync: %+v %v", sum, err)
+	}
+	if !reflect.DeepEqual(sum.Accepted, []string{"mini1"}) || len(sum.Candidates) != 2 || !sum.Candidates[0].Created {
+		t.Fatalf("summary: %+v", sum)
+	}
+	for _, id := range []string{"vps1", "vps2"} {
+		n, err := f.reg.Get(ctx, id)
+		if err != nil || !n.Capability.Lifecycle.Discovered || n.Capability.Lifecycle.Eligible || len(n.Capability.Lifecycle.AuthorizedProjects) != 0 ||
+			len(n.Capability.Identity.HostKeyFingerprints) != 0 || n.Capability.SecretsEligible {
+			t.Fatalf("candidate %s: %+v %v", id, n.Capability, err)
+		}
+		if ls, _ := f.st.NodeLabels(ctx, id); len(ls) != 0 {
+			t.Fatalf("a candidate gets no labels yet: %v", ls)
+		}
+	}
+	// Labels, rank and skip_repos reach the existing node; the rank survives a reopen of the store.
+	st2 := openFixture(t, f.path)
+	ls, _ := st2.st.NodeLabels(ctx, "mini1")
+	var got []string
+	for _, l := range ls {
+		got = append(got, l.Key+"="+l.Value)
+	}
+	if !reflect.DeepEqual(got, []string{"pool.mine=", "rank=1", "xcode="}) {
+		t.Fatalf("labels after reopen = %v", got)
+	}
+	after, _ := st2.reg.Get(ctx, "mini1")
+	if !reflect.DeepEqual(after.Capability.Lifecycle.AuthorizedProjects, []string{"/src/pub", "/src/priv"}) {
+		t.Fatalf("projects = %v", after.Capability.Lifecycle.AuthorizedProjects)
+	}
+	// Nothing else moved.
+	after.Capability.Lifecycle.AuthorizedProjects = before.Capability.Lifecycle.AuthorizedProjects
+	if !reflect.DeepEqual(before.Capability.Trust, after.Capability.Trust) || before.Capability.SecretsEligible != after.Capability.SecretsEligible {
+		t.Fatal("trust or secrets eligibility changed")
+	}
+}
+
+func TestSyncIdempotent(t *testing.T) {
+	ctx := context.Background()
+	f := newFixture(t, "mini1")
+	if _, err := Sync(ctx, f.env(nil), threeEntries(), Options{}); err != nil {
+		t.Fatal(err)
+	}
+	rows := f.audit(t)
+	sum, err := Sync(ctx, f.env(nil), threeEntries(), Options{})
+	if err != nil || len(sum.Changed) != 0 || len(sum.Rejected) != 0 {
+		t.Fatalf("second run: %+v %v", sum, err)
+	}
+	if want := []Candidate{{ID: "vps1"}, {ID: "vps2"}}; !reflect.DeepEqual(sum.Candidates, want) {
+		t.Fatalf("pending candidates = %+v", sum.Candidates)
+	}
+	if got := f.audit(t); got != rows {
+		t.Fatalf("audit rows %d -> %d on an identical run", rows, got)
+	}
+}
+
+func TestSyncNeverTouchesTrust(t *testing.T) {
+	ctx := context.Background()
+	f := newFixture(t, "mini1")
+	before, _ := f.reg.Get(ctx, "mini1")
+	e := Entry{ID: "mini1", Rank: rankOf(5), Labels: []string{"a=b"}, Pools: []string{"mine"}, PublicOnly: true, SkipRepos: []string{"/src/old"}}
+	if _, err := Sync(ctx, f.env(nil), []Entry{e}, Options{}); err != nil {
+		t.Fatal(err)
+	}
+	after, _ := f.reg.Get(ctx, "mini1")
+	b, a := before.Capability, after.Capability
+	if !reflect.DeepEqual(b.Trust, a.Trust) || !reflect.DeepEqual(b.Identity, a.Identity) || b.SecretsEligible != a.SecretsEligible ||
+		!reflect.DeepEqual(b.Separation, a.Separation) || b.Lifecycle.Eligible != a.Lifecycle.Eligible || b.Lifecycle.Discovered != a.Lifecycle.Discovered {
+		t.Fatalf("operator-owned fields only:\nbefore %+v\nafter  %+v", b, a)
+	}
+	// An existing node's ssh, os and arch in the inventory are ignored.
+	e = Entry{ID: "mini1", SSH: "evil@elsewhere.example.test", OS: "windows", Arch: "arm64"}
+	if sum, _ := Sync(ctx, f.env(nil), []Entry{e}, Options{}); len(sum.Changed) != 0 {
+		t.Fatalf("identity facts changed: %+v", sum)
+	}
+	again, _ := f.reg.Get(ctx, "mini1")
+	if !reflect.DeepEqual(again.Capability.Identity, a.Identity) || !reflect.DeepEqual(again.Capability.Platform, a.Platform) {
+		t.Fatal("identity or platform moved")
+	}
+}
+
+func TestPublicOnlyAuthorization(t *testing.T) {
+	ctx := context.Background()
+	e := Entry{ID: "mini1", PublicOnly: true}
+	calls := map[string]int{}
+	vis := func(_ context.Context, p string) (bool, bool) { calls[p]++; return p == "/src/pub", p != "/src/old" }
+	f := newFixture(t, "mini1", "mini2")
+	sum, err := Sync(ctx, f.env(vis), []Entry{e, {ID: "mini2", PublicOnly: true}}, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range []string{"mini1", "mini2"} {
+		n, _ := f.reg.Get(ctx, id)
+		if !reflect.DeepEqual(n.Capability.Lifecycle.AuthorizedProjects, []string{"/src/pub"}) {
+			t.Fatalf("%s projects = %v", id, n.Capability.Lifecycle.AuthorizedProjects)
+		}
+	}
+	if calls["/src/pub"] != 1 || calls["/src/priv"] != 1 || len(sum.Notes) != 1 {
+		t.Fatalf("visibility read once per project: %v notes %v", calls, sum.Notes)
+	}
+	// The API is down: nothing is authorized and the summary says so.
+	f = newFixture(t, "mini1")
+	down := func(context.Context, string) (bool, bool) { return false, false }
+	sum, _ = Sync(ctx, f.env(down), []Entry{e}, Options{})
+	n, _ := f.reg.Get(ctx, "mini1")
+	if len(n.Capability.Lifecycle.AuthorizedProjects) != 0 || len(sum.Notes) != 3 || len(sum.Changed) != 3 {
+		t.Fatalf("unknown visibility: %+v projects %v", sum, n.Capability.Lifecycle.AuthorizedProjects)
+	}
+	// Without a reader the answer is unknown too; without public_only nothing is read.
+	f = newFixture(t, "mini1")
+	if sum, _ = Sync(ctx, f.env(nil), []Entry{{ID: "mini1", Rank: rankOf(1)}}, Options{}); len(sum.Notes) != 0 {
+		t.Fatalf("notes without public_only: %v", sum.Notes)
+	}
+	if n, _ = f.reg.Get(ctx, "mini1"); len(n.Capability.Lifecycle.AuthorizedProjects) != 3 {
+		t.Fatal("projects changed without public_only")
+	}
+}
+
+func TestSyncRejectsWithoutAborting(t *testing.T) {
+	ctx := context.Background()
+	f := newFixture(t, "mini1")
+	in := []Entry{{ID: "BAD"}, {ID: "newhost"}, {ID: "mini1", Labels: []string{"bad label"}}, {ID: "mini1", Rank: rankOf(1)}, {ID: "vps1", SSH: "vps1.example.test"}}
+	sum, err := Sync(ctx, f.env(nil), in, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var ids []string
+	for _, r := range sum.Rejected {
+		ids = append(ids, r.ID)
+	}
+	if !slices.Equal(ids, []string{"BAD", "newhost", "mini1", "mini1"}) || len(sum.Candidates) != 1 || sum.Candidates[0].ID != "vps1" {
+		t.Fatalf("summary: %+v", sum)
+	}
+	if ls, _ := f.st.NodeLabels(ctx, "mini1"); len(ls) != 0 {
+		t.Fatalf("a rejected node got labels: %v", ls)
+	}
+}
+
+func TestSyncDryRunWritesNothing(t *testing.T) {
+	ctx := context.Background()
+	f := newFixture(t, "mini1")
+	rows := f.audit(t)
+	sum, err := Sync(ctx, f.env(nil), threeEntries(), Options{DryRun: true})
+	if err != nil || !sum.DryRun || len(sum.Changed) == 0 || len(sum.Candidates) != 2 || sum.Candidates[0].Created {
+		t.Fatalf("dry run: %+v %v", sum, err)
+	}
+	if _, err = f.reg.Get(ctx, "vps1"); err == nil {
+		t.Fatal("dry-run created a candidate")
+	}
+	if ls, _ := f.st.NodeLabels(ctx, "mini1"); len(ls) != 0 || f.audit(t) != rows {
+		t.Fatalf("dry-run wrote: %v", ls)
+	}
+}
+
+func TestSyncRefusedOnTeamCoordinator(t *testing.T) {
+	f := newFixture(t, "mini1")
+	env := f.env(nil)
+	env.Team = true
+	if _, err := Sync(context.Background(), env, threeEntries(), Options{}); ReasonOf(err) != ReasonTeam {
+		t.Fatalf("team: %v", err)
+	}
+	if n, _ := f.reg.List(context.Background()); len(n) != 1 {
+		t.Fatal("a refused sync registered nodes")
+	}
+}
diff --git a/free/ci/internal/nodes/inventory/want.go b/free/ci/internal/nodes/inventory/want.go
new file mode 100644
index 000000000..ac09ed44b
--- /dev/null
+++ b/free/ci/internal/nodes/inventory/want.go
@@ -0,0 +1,38 @@
+package inventory
+
+// Purpose: the assigned label set an entry stands for: its plain labels, one `pool.<id>` per pool and
+//          `rank=<n>`; the tier rank P7-AUTO-05 reads.
+// Inputs:  an Entry.
+// Outputs: the labels sorted by key.
+// Constraints: sync only sets these keys; it never removes a label the operator set another way.
+
+import (
+	"sort"
+	"strconv"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// RankKey is the label that carries the tier rank.
+const RankKey = "rank"
+
+// PoolPrefix is the label key prefix of pool membership.
+const PoolPrefix = "pool."
+
+// Want returns the labels the entry stands for.
+func (e Entry) Want() ([]store.NodeLabel, error) {
+	in := append([]string{}, e.Labels...)
+	for _, p := range e.Pools {
+		in = append(in, PoolPrefix+p)
+	}
+	if e.Rank != nil {
+		in = append(in, RankKey+"="+strconv.Itoa(*e.Rank))
+	}
+	set, err := labels.Parse(in)
+	if err != nil {
+		return nil, err
+	}
+	sort.Slice(set, func(i, j int) bool { return set[i].Key < set[j].Key })
+	return set, nil
+}
diff --git a/free/ci/internal/nodes/labels/apply.go b/free/ci/internal/nodes/labels/apply.go
new file mode 100644
index 000000000..aa608ca34
--- /dev/null
+++ b/free/ci/internal/nodes/labels/apply.go
@@ -0,0 +1,87 @@
+package labels
+
+// Purpose: the label edit of `nself ci nodes label` (P7-NODE-30): add and remove labels of one node, or
+// read them, with the audit rows written by the store in the same transaction.
+// Inputs:  Env (store, registry, actor), a node id or the alias `local`, labels to set and keys to remove.
+// Outputs: the node's label set after the edit, sorted by key.
+// Constraints: a node must be registered (the alias `local` is the invoking machine's runner and needs no
+//          record); a rejected edit changes nothing; labels are assigned here only, never taken from a
+//          hello or a probe; the `nself.` prefix cannot be set by this path.
+
+import (
+	"context"
+	"sort"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// LocalNode is the alias of the invoking machine's runner.
+const LocalNode = "local"
+
+// Env is what the label and project operations need.
+type Env struct {
+	Store    *store.Store
+	Registry *registry.Registry
+	Actor    string
+	// Team is true on a TEAM coordinator: no wildcard grants, no directory arguments, no `local`.
+	Team bool
+	// ResolveDir returns the repository id of a directory (the way evidence names it); nil refuses directories.
+	ResolveDir func(ctx context.Context, dir string) (string, bool)
+}
+
+// Labels returns the node's assigned labels.
+func (e Env) Labels(ctx context.Context, node string) ([]store.NodeLabel, error) {
+	if err := e.checkNode(ctx, node); err != nil {
+		return nil, err
+	}
+	return e.Store.NodeLabels(ctx, node)
+}
+
+// Edit sets the labels in add (a `key` or `key=value` each, replacing a label of the same key), removes
+// the keys in remove and returns the resulting set.
+func (e Env) Edit(ctx context.Context, node string, add, remove []string) ([]store.NodeLabel, error) {
+	if err := e.checkNode(ctx, node); err != nil {
+		return nil, err
+	}
+	set, err := Parse(add)
+	if err != nil {
+		return nil, err
+	}
+	have, err := e.Store.NodeLabels(ctx, node)
+	if err != nil {
+		return nil, err
+	}
+	drop := map[string]bool{}
+	for _, k := range remove {
+		drop[k] = true
+	}
+	for _, l := range set {
+		drop[l.Key] = true
+	}
+	next := set
+	for _, l := range have {
+		if !drop[l.Key] {
+			next = append(next, l)
+		}
+	}
+	sort.Slice(next, func(i, j int) bool { return next[i].Key < next[j].Key })
+	if err = Validate(next); err != nil {
+		return nil, err
+	}
+	if err = e.Store.NodeLabelsReplace(ctx, node, next, e.Actor); err != nil {
+		return nil, err
+	}
+	return next, nil
+}
+
+func (e Env) checkNode(ctx context.Context, node string) error {
+	if node == LocalNode {
+		if e.Team {
+			return newErr(ReasonProjectUnknown, "the alias local names the invoking machine; name a registered node on a coordinator")
+		}
+		return nil
+	}
+	_, err := e.Registry.Get(ctx, node)
+	return err
+}
diff --git a/free/ci/internal/nodes/labels/apply_test.go b/free/ci/internal/nodes/labels/apply_test.go
new file mode 100644
index 000000000..2afe7b98a
--- /dev/null
+++ b/free/ci/internal/nodes/labels/apply_test.go
@@ -0,0 +1,168 @@
+package labels
+
+// Purpose: tests of the label edit and the project authorization edit (P7-NODE-30) against a real
+// SQLite store and registry: results, rejected edits that change nothing, the audit trail, the TEAM
+// refusals and the `--all` expansion at call time.
+// Inputs:  the laptop capability fixture registered under several node ids.
+// Outputs: pass or fail.
+// Constraints: no network, no processes.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func newEnv(t *testing.T, nodes ...string) Env {
+	t.Helper()
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	b, err := os.ReadFile("../../model/testdata/capability/valid/laptop.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	reg := registry.New(st)
+	for _, id := range nodes {
+		var c model.Capability
+		if err = json.Unmarshal(b, &c); err != nil {
+			t.Fatal(err)
+		}
+		c.Identity.ID, c.Identity.Name = id, id
+		if _, err = reg.Register(context.Background(), c, "operator"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return Env{Store: st, Registry: reg, Actor: "cli:test", ResolveDir: func(_ context.Context, dir string) (string, bool) {
+		if strings.HasSuffix(dir, "project-b") {
+			return "local:bbb", true
+		}
+		return "", false
+	}}
+}
+
+func TestEditSetsRemovesAndAudits(t *testing.T) {
+	ctx := context.Background()
+	e := newEnv(t, "mini1")
+	got, err := e.Edit(ctx, "mini1", []string{"xcode", "arch=arm64"}, nil)
+	if err != nil || !reflect.DeepEqual(Strings(got), []string{"arch=arm64", "xcode"}) {
+		t.Fatalf("set: %v %v", got, err)
+	}
+	if got, err = e.Edit(ctx, "mini1", nil, []string{"xcode"}); err != nil || !reflect.DeepEqual(Strings(got), []string{"arch=arm64"}) {
+		t.Fatalf("remove: %v %v", got, err)
+	}
+	audit, err := e.Store.NodeLabelAudit(ctx, "mini1")
+	if err != nil || len(audit) != 3 {
+		t.Fatalf("audit rows %d %v, want 3 (xcode set, arch set, xcode remove)", len(audit), err)
+	}
+}
+
+func TestEditRejectsAndChangesNothing(t *testing.T) {
+	ctx := context.Background()
+	e := newEnv(t, "mini1")
+	if _, err := e.Edit(ctx, "mini1", []string{"keep"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	many := make([]string, 0, MaxLabels)
+	for i := 0; i < MaxLabels; i++ {
+		many = append(many, "k"+strings.Repeat("x", i))
+	}
+	for name, c := range map[string]struct {
+		add    []string
+		reason string
+	}{"bad key": {[]string{"Bad Key"}, ReasonSyntax}, "reserved": {[]string{"nself.fabric"}, ReasonReserved}, "33rd": {many, ReasonTooMany}} {
+		_, err := e.Edit(ctx, "mini1", c.add, nil)
+		if ReasonOf(err) != c.reason {
+			t.Fatalf("%s: %v, want reason %s", name, err, c.reason)
+		}
+	}
+	got, _ := e.Store.NodeLabels(ctx, "mini1")
+	audit, _ := e.Store.NodeLabelAudit(ctx, "mini1")
+	if len(got) != 1 || len(audit) != 1 {
+		t.Fatalf("a rejected edit changed state: %v, %d audit rows", got, len(audit))
+	}
+	if _, err := e.Edit(ctx, "ghost", []string{"x"}, nil); err == nil {
+		t.Fatal("unregistered node accepted")
+	}
+}
+
+func TestLocalAlias(t *testing.T) {
+	ctx := context.Background()
+	e := newEnv(t)
+	if _, err := e.Edit(ctx, LocalNode, []string{"gpu"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	got, err := e.Store.NodeLabels(ctx, LocalNode)
+	if err != nil || !reflect.DeepEqual(Strings(got), []string{"gpu"}) {
+		t.Fatalf("local labels %v %v", got, err)
+	}
+	e.Team = true
+	if _, err = e.Edit(ctx, LocalNode, []string{"gpu"}, nil); err == nil {
+		t.Fatal("local alias accepted on a coordinator")
+	}
+}
+
+func TestProjectsAddRemoveList(t *testing.T) {
+	ctx := context.Background()
+	e := newEnv(t, "vps-a")
+	added, err := e.AddProjects(ctx, "vps-a", []string{"proj-a", "../project-b", "proj-a"}, false)
+	if err != nil || !reflect.DeepEqual(added, []string{"proj-a", "local:bbb"}) {
+		t.Fatalf("add: %v %v", added, err)
+	}
+	if added, err = e.AddProjects(ctx, "vps-a", []string{"proj-a"}, false); err != nil || len(added) != 0 {
+		t.Fatalf("re-add: %v %v", added, err)
+	}
+	removed, err := e.RemoveProjects(ctx, "vps-a", []string{"proj-a"}, false)
+	if err != nil || !reflect.DeepEqual(removed, []string{"proj-a"}) {
+		t.Fatalf("remove: %v %v", removed, err)
+	}
+	if got, _ := e.Projects(ctx, "vps-a"); !reflect.DeepEqual(got, []string{"local:bbb"}) {
+		t.Fatalf("list: %v", got)
+	}
+	if _, err = e.AddProjects(ctx, "vps-a", []string{"./nowhere"}, false); ReasonOf(err) != ReasonProjectUnknown {
+		t.Fatalf("unresolvable directory: %v", err)
+	}
+	if _, err = e.AddProjects(ctx, "vps-a", []string{"bad id"}, false); ReasonOf(err) != ReasonProjectUnknown {
+		t.Fatalf("bad id: %v", err)
+	}
+}
+
+func TestProjectsAllIsExplicitAndPersonalOnly(t *testing.T) {
+	ctx := context.Background()
+	e := newEnv(t, "vps-a")
+	seed := func(project string) {
+		err := e.Store.CreatePipeline(ctx, store.PipelineRow{ID: "pl-" + project, Project: project, Revision: "r", Trigger: "push", SourceTrust: "owner",
+			PrivacyZone: "local-only", PolicyDigest: "d", InputDigest: "i", SelectionMode: "m", SelectionReason: "r", SelectionDigest: "s", Status: "queued"})
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	seed("proj-a")
+	seed("proj-b")
+	added, err := e.AddProjects(ctx, "vps-a", nil, true)
+	if err != nil || !reflect.DeepEqual(added, []string{"proj-a", "proj-b"}) {
+		t.Fatalf("--all: %v %v", added, err)
+	}
+	seed("proj-c")
+	if got, _ := e.Projects(ctx, "vps-a"); !reflect.DeepEqual(got, []string{"proj-a", "proj-b"}) {
+		t.Fatalf("a project seen later was authorized: %v", got)
+	}
+	team := e
+	team.Team = true
+	if _, err = team.AddProjects(ctx, "vps-a", nil, true); ReasonOf(err) != ReasonTeamWildcard {
+		t.Fatalf("team --all: %v", err)
+	}
+	if _, err = team.AddProjects(ctx, "vps-a", []string{"./x"}, false); ReasonOf(err) != ReasonProjectUnknown {
+		t.Fatalf("team directory: %v", err)
+	}
+}
diff --git a/free/ci/internal/nodes/labels/codes.go b/free/ci/internal/nodes/labels/codes.go
new file mode 100644
index 000000000..9f8864f5c
--- /dev/null
+++ b/free/ci/internal/nodes/labels/codes.go
@@ -0,0 +1,53 @@
+// Package labels validates operator-assigned node labels and feeds them to placement.
+package labels
+
+// Purpose: the code and typed error of node label rejections (P7-NODE-30).
+// Inputs:  none.
+// Outputs: E658 registered through model.Register; *Error carrying the code and a stable reason key.
+// Constraints: one code for every label rejection; the reason key tells syntax, reserved prefix and
+//          count limit apart.
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// CodeLabel is the code every label rejection carries.
+const CodeLabel = "E658"
+
+// Reason keys carried by Error.Reason.
+const (
+	ReasonSyntax   = "label_syntax"
+	ReasonReserved = "label_reserved"
+	ReasonTooMany  = "too_many"
+	// ReasonTeamWildcard refuses `projects add --all` against a TEAM coordinator.
+	ReasonTeamWildcard = "team_wildcard"
+	// ReasonProjectUnknown is a project argument that names no repository id.
+	ReasonProjectUnknown = "project_unknown"
+)
+
+func init() {
+	model.Register(model.Code{ID: CodeLabel, Class: "usage", Summary: "invalid node label", Fix: "Use lowercase keys, plain short values, at most 32 labels and no nself. prefix"})
+}
+
+// Error is a label rejection.
+type Error struct {
+	Code, Reason, Msg string
+}
+
+func (e *Error) Error() string { return fmt.Sprintf("%s: %s", e.Code, e.Msg) }
+
+func newErr(reason, format string, a ...any) *Error {
+	return &Error{Code: CodeLabel, Reason: reason, Msg: fmt.Sprintf(format, a...)}
+}
+
+// ReasonOf returns the reason key of a label error, or "".
+func ReasonOf(err error) string {
+	var le *Error
+	if errors.As(err, &le) {
+		return le.Reason
+	}
+	return ""
+}
diff --git a/free/ci/internal/nodes/labels/labels.go b/free/ci/internal/nodes/labels/labels.go
new file mode 100644
index 000000000..791fba6da
--- /dev/null
+++ b/free/ci/internal/nodes/labels/labels.go
@@ -0,0 +1,78 @@
+package labels
+
+// Purpose: syntax rules for operator-assigned node labels (P7-NODE-30) and the conversion between
+// the `key=value` form used by placement and the store rows.
+// Inputs:  label strings from the operator (`key` or `key=value`) or store rows.
+// Outputs: Parse, Validate, Strings.
+// Constraints: keys match ^[a-z][a-z0-9_.-]{0,62}$, values match ^[A-Za-z0-9_.-]{0,63}$, the
+//          `nself.` key prefix is reserved for the fabric, and a node carries at most MaxLabels.
+
+import (
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// MaxLabels is the most labels one node may carry.
+const MaxLabels = 32
+
+// ReservedPrefix is the key prefix only the fabric may assign.
+const ReservedPrefix = "nself."
+
+var (
+	keyRE   = regexp.MustCompile(`^[a-z][a-z0-9_.-]{0,62}$`)
+	valueRE = regexp.MustCompile(`^[A-Za-z0-9_.-]{0,63}$`)
+)
+
+// Parse turns `key` or `key=value` strings into a validated label set ordered by key.
+func Parse(in []string) ([]store.NodeLabel, error) {
+	out := make([]store.NodeLabel, 0, len(in))
+	for _, s := range in {
+		k, v, _ := strings.Cut(s, "=")
+		out = append(out, store.NodeLabel{Key: k, Value: v})
+	}
+	if err := Validate(out); err != nil {
+		return nil, err
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key })
+	return out, nil
+}
+
+// Validate checks every label of a set and the size of the set.
+func Validate(set []store.NodeLabel) error {
+	if len(set) > MaxLabels {
+		return newErr(ReasonTooMany, "%d labels, at most %d allowed", len(set), MaxLabels)
+	}
+	seen := map[string]bool{}
+	for _, l := range set {
+		if !keyRE.MatchString(l.Key) {
+			return newErr(ReasonSyntax, "label key %q is not valid", l.Key)
+		}
+		if !valueRE.MatchString(l.Value) {
+			return newErr(ReasonSyntax, "label value %q of key %s is not valid", l.Value, l.Key)
+		}
+		if strings.HasPrefix(l.Key, ReservedPrefix) {
+			return newErr(ReasonReserved, "label key %s uses the reserved %s prefix", l.Key, ReservedPrefix)
+		}
+		if seen[l.Key] {
+			return newErr(ReasonSyntax, "label key %s is given twice", l.Key)
+		}
+		seen[l.Key] = true
+	}
+	return nil
+}
+
+// Strings renders a label set in the placement form: `key` for a bare key, else `key=value`.
+func Strings(set []store.NodeLabel) []string {
+	out := make([]string, 0, len(set))
+	for _, l := range set {
+		if l.Value == "" {
+			out = append(out, l.Key)
+			continue
+		}
+		out = append(out, l.Key+"="+l.Value)
+	}
+	return out
+}
diff --git a/free/ci/internal/nodes/labels/labels_test.go b/free/ci/internal/nodes/labels/labels_test.go
new file mode 100644
index 000000000..f5ac12e59
--- /dev/null
+++ b/free/ci/internal/nodes/labels/labels_test.go
@@ -0,0 +1,126 @@
+package labels
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func TestParseValid(t *testing.T) {
+	got, err := Parse([]string{"zone=eu-1", "gpu", "arch.v2=Arm_64", "e="})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []store.NodeLabel{{Key: "arch.v2", Value: "Arm_64"}, {Key: "e"}, {Key: "gpu"}, {Key: "zone", Value: "eu-1"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("got %v want %v", got, want)
+	}
+	if s := Strings(got); !reflect.DeepEqual(s, []string{"arch.v2=Arm_64", "e", "gpu", "zone=eu-1"}) {
+		t.Fatalf("strings %v", s)
+	}
+}
+
+func TestValidateReasons(t *testing.T) {
+	long := "a" + strings.Repeat("b", 63)
+	cases := []struct {
+		in     []string
+		reason string
+	}{
+		{[]string{"Gpu"}, ReasonSyntax},
+		{[]string{"1gpu"}, ReasonSyntax},
+		{[]string{""}, ReasonSyntax},
+		{[]string{"=x"}, ReasonSyntax},
+		{[]string{long}, ReasonSyntax},
+		{[]string{"k=" + strings.Repeat("v", 64)}, ReasonSyntax},
+		{[]string{"k=a b"}, ReasonSyntax},
+		{[]string{"k=a=b"}, ReasonSyntax},
+		{[]string{"k=1", "k=2"}, ReasonSyntax},
+		{[]string{"nself.visibility=public"}, ReasonReserved},
+		{[]string{"nself."}, ReasonReserved},
+	}
+	for _, c := range cases {
+		_, err := Parse(c.in)
+		var e *Error
+		if !errors.As(err, &e) || e.Code != CodeLabel || ReasonOf(err) != c.reason {
+			t.Fatalf("%v: got %v want %s", c.in, err, c.reason)
+		}
+	}
+	if _, err := Parse([]string{strings.Repeat("a", 63), "k=" + strings.Repeat("v", 63), "nself"}); err != nil {
+		t.Fatalf("boundary set rejected: %v", err)
+	}
+	if ReasonOf(errors.New("other")) != "" {
+		t.Fatal("foreign error has a reason")
+	}
+}
+
+func TestValidateCount(t *testing.T) {
+	set := make([]string, MaxLabels)
+	for i := range set {
+		set[i] = fmt.Sprintf("k%d", i)
+	}
+	if _, err := Parse(set); err != nil {
+		t.Fatalf("%d labels rejected: %v", MaxLabels, err)
+	}
+	if _, err := Parse(append(set, "extra")); ReasonOf(err) != ReasonTooMany {
+		t.Fatalf("too many: %v", err)
+	}
+}
+
+func TestCodeRegistered(t *testing.T) {
+	for _, p := range model.CodeProblems() {
+		if strings.Contains(p, CodeLabel) {
+			t.Fatalf("code problem: %s", p)
+		}
+	}
+}
+
+type fakeReader struct {
+	set []store.NodeLabel
+	err error
+}
+
+func (f fakeReader) NodeLabels(context.Context, string) ([]store.NodeLabel, error) {
+	return f.set, f.err
+}
+
+func TestSourceFromStore(t *testing.T) {
+	ctx := context.Background()
+	s, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	set, err := Parse([]string{"pool=gpu", "fast"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = s.NodeLabelsReplace(ctx, "node-a", set, "operator"); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Source(s)(ctx, "node-a")
+	if err != nil || !reflect.DeepEqual(got, []string{"fast", "pool=gpu"}) {
+		t.Fatalf("got %v %v", got, err)
+	}
+	if got, err = Source(s)(ctx, "node-b"); err != nil || len(got) != 0 {
+		t.Fatalf("unlabelled node: %v %v", got, err)
+	}
+	if _, err = Source(fakeReader{err: errors.New("disk")})(ctx, "x"); err == nil {
+		t.Fatal("read error swallowed")
+	}
+}
+
+func TestRegisterSourceOnce(t *testing.T) {
+	if err := RegisterSource(fakeReader{}); err != nil {
+		t.Fatal(err)
+	}
+	if err := RegisterSource(fakeReader{}); err == nil {
+		t.Fatal("second label source accepted")
+	}
+}
diff --git a/free/ci/internal/nodes/labels/lazy.go b/free/ci/internal/nodes/labels/lazy.go
new file mode 100644
index 000000000..5a3013802
--- /dev/null
+++ b/free/ci/internal/nodes/labels/lazy.go
@@ -0,0 +1,65 @@
+package labels
+
+// Purpose: the production Reader of the world label source (P7-NODE-30): it reads the assigned labels from
+// the coordinator's live store while a serve runs, else from the CI home store, opened on first use.
+// Inputs:  Live (the serve's store or nil) and Path (the home store path) resolvers.
+// Outputs: the node's labels; none when no store file exists yet (nothing was ever labelled).
+// Constraints: one open handle per path for the life of the process (the world builder asks once per
+//          runner per plan); a store that exists but cannot be read is an error, never an empty answer.
+
+import (
+	"context"
+	"errors"
+	"os"
+	"sync"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// LazyReader implements Reader over late-bound stores.
+type LazyReader struct {
+	Live func() *store.Store
+	Path func() string
+
+	mu     sync.Mutex
+	stores map[string]*store.Store
+}
+
+// NodeLabels returns the node's assigned labels.
+func (r *LazyReader) NodeLabels(ctx context.Context, nodeID string) ([]store.NodeLabel, error) {
+	if r.Live != nil {
+		if st := r.Live(); st != nil {
+			return st.NodeLabels(ctx, nodeID)
+		}
+	}
+	path := r.Path()
+	r.mu.Lock()
+	st := r.stores[path]
+	if st == nil {
+		if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
+			r.mu.Unlock()
+			return nil, nil
+		}
+		var err error
+		if st, err = store.Open(path, store.Options{}); err != nil {
+			r.mu.Unlock()
+			return nil, err
+		}
+		if r.stores == nil {
+			r.stores = map[string]*store.Store{}
+		}
+		r.stores[path] = st
+	}
+	r.mu.Unlock()
+	return st.NodeLabels(ctx, nodeID)
+}
+
+// Close closes every store the reader opened.
+func (r *LazyReader) Close() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for p, st := range r.stores {
+		_ = st.Close()
+		delete(r.stores, p)
+	}
+}
diff --git a/free/ci/internal/nodes/labels/lazy_test.go b/free/ci/internal/nodes/labels/lazy_test.go
new file mode 100644
index 000000000..fba13ad6a
--- /dev/null
+++ b/free/ci/internal/nodes/labels/lazy_test.go
@@ -0,0 +1,47 @@
+package labels
+
+// Purpose: tests of the lazy production reader and of the world label source (P7-NODE-30): no store file
+// means no labels, a live store wins, and Source renders the placement form.
+// Inputs:  temp stores. Outputs: pass or fail.
+// Constraints: the process-wide world hook is not touched (RegisterSource is exercised by the sim leg).
+
+import (
+	"context"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func TestLazyReader(t *testing.T) {
+	ctx := context.Background()
+	path := filepath.Join(t.TempDir(), "state.db")
+	r := &LazyReader{Path: func() string { return path }}
+	t.Cleanup(r.Close)
+	if got, err := r.NodeLabels(ctx, "n1"); err != nil || len(got) != 0 {
+		t.Fatalf("no store file: %v %v", got, err)
+	}
+	st, err := store.Open(path, store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = st.NodeLabelsReplace(ctx, "n1", []store.NodeLabel{{Key: "xcode"}, {Key: "arch", Value: "arm64"}}, "t"); err != nil {
+		t.Fatal(err)
+	}
+	if err = st.Close(); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Source(r)(ctx, "n1")
+	if err != nil || !reflect.DeepEqual(got, []string{"arch=arm64", "xcode"}) {
+		t.Fatalf("source: %v %v", got, err)
+	}
+	live := newEnv(t).Store
+	if err = live.NodeLabelsReplace(ctx, "n1", []store.NodeLabel{{Key: "live"}}, "t"); err != nil {
+		t.Fatal(err)
+	}
+	r.Live = func() *store.Store { return live }
+	if got, err = Source(r)(ctx, "n1"); err != nil || !reflect.DeepEqual(got, []string{"live"}) {
+		t.Fatalf("live store: %v %v", got, err)
+	}
+}
diff --git a/free/ci/internal/nodes/labels/projects.go b/free/ci/internal/nodes/labels/projects.go
new file mode 100644
index 000000000..9e8387a8a
--- /dev/null
+++ b/free/ci/internal/nodes/labels/projects.go
@@ -0,0 +1,115 @@
+package labels
+
+// Purpose: the project authorization edit of `nself ci nodes projects add|remove|list` (P7-NODE-30):
+//          change lifecycle.authorized_projects through the registry, one audit row per change.
+// Inputs:  Env, a node id and project arguments: a repo id, or a directory (a path starting with `.`, `/`
+//          or `~`, or containing `/`) that resolves to its repo id the way evidence names it.
+// Outputs: the projects added or removed, or the node's authorized projects.
+// Constraints: `--all` on add expands at call time to the explicit projects the PERSONAL store has seen
+//          (no wildcard entry is ever stored) and is refused on a TEAM coordinator (team_wildcard);
+//          removal keeps running attempts (the lease gate refuses new leases, E657); a project already
+//          in the requested state is skipped, not an error.
+
+import (
+	"context"
+	"regexp"
+	"slices"
+	"strings"
+)
+
+var projectIDRE = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9:_.-]{0,127}$`)
+
+// Projects returns the node's authorized projects.
+func (e Env) Projects(ctx context.Context, node string) ([]string, error) {
+	n, err := e.Registry.Get(ctx, node)
+	if err != nil {
+		return nil, err
+	}
+	return slices.Clone(n.Capability.Lifecycle.AuthorizedProjects), nil
+}
+
+// Resolve turns project arguments into repo ids; none given means the current directory.
+func (e Env) Resolve(ctx context.Context, args []string) ([]string, error) {
+	if len(args) == 0 {
+		args = []string{"."}
+	}
+	var out []string
+	for _, a := range args {
+		id := a
+		if isDir(a) {
+			if e.Team || e.ResolveDir == nil {
+				return nil, newErr(ReasonProjectUnknown, "%q is a directory: a coordinator takes repo ids only", a)
+			}
+			var ok bool
+			if id, ok = e.ResolveDir(ctx, a); !ok || id == "" {
+				return nil, newErr(ReasonProjectUnknown, "%q has no repository id (no git commit yet?)", a)
+			}
+		} else if !projectIDRE.MatchString(a) {
+			return nil, newErr(ReasonProjectUnknown, "%q is not a repo id", a)
+		}
+		if !slices.Contains(out, id) {
+			out = append(out, id)
+		}
+	}
+	return out, nil
+}
+
+func isDir(a string) bool {
+	return strings.ContainsAny(a[:min(1, len(a))], "./~") || strings.Contains(a, "/")
+}
+
+// AddProjects authorizes the projects on node (all: every project the store has seen) and returns those newly added.
+func (e Env) AddProjects(ctx context.Context, node string, args []string, all bool) ([]string, error) {
+	var want []string
+	var err error
+	if all {
+		if e.Team {
+			return nil, newErr(ReasonTeamWildcard, "--all grants every project and is refused on a TEAM coordinator: name each project")
+		}
+		if want, err = e.Store.PipelineProjects(ctx); err != nil {
+			return nil, err
+		}
+	} else if want, err = e.Resolve(ctx, args); err != nil {
+		return nil, err
+	}
+	have, err := e.Projects(ctx, node)
+	if err != nil {
+		return nil, err
+	}
+	var added []string
+	for _, p := range want {
+		if slices.Contains(have, p) {
+			continue
+		}
+		if _, err = e.Registry.Authorize(ctx, node, p, e.Actor); err != nil {
+			return added, err
+		}
+		added = append(added, p)
+	}
+	return added, nil
+}
+
+// RemoveProjects deauthorizes the projects on node (all: every authorized project) and returns those removed.
+func (e Env) RemoveProjects(ctx context.Context, node string, args []string, all bool) ([]string, error) {
+	have, err := e.Projects(ctx, node)
+	if err != nil {
+		return nil, err
+	}
+	want := have
+	if !all {
+		if want, err = e.Resolve(ctx, args); err != nil {
+			return nil, err
+		}
+	}
+	var removed []string
+	for _, p := range want {
+		if !slices.Contains(have, p) {
+			continue
+		}
+		if _, err = e.Registry.Deauthorize(ctx, node, p, e.Actor); err != nil {
+			return removed, err
+		}
+		removed = append(removed, p)
+	}
+	return removed, nil
+}
diff --git a/free/ci/internal/nodes/labels/source.go b/free/ci/internal/nodes/labels/source.go
new file mode 100644
index 000000000..41c29919c
--- /dev/null
+++ b/free/ci/internal/nodes/labels/source.go
@@ -0,0 +1,35 @@
+package labels
+
+// Purpose: the world label source (P7-SCHED-18): assigned labels join each runner's identity labels,
+//          so placement matches them against requires.labels and sched.overrides.labels.
+// Inputs:  a Reader over the store's assigned labels.
+// Outputs: the placement form of Strings for each runner id the world builder asks about.
+// Constraints: world accepts one label source per process; a second RegisterSource fails there (E699).
+
+import (
+	"context"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+// Reader reads one node's assigned labels; *store.Store satisfies it.
+type Reader interface {
+	NodeLabels(ctx context.Context, nodeID string) ([]store.NodeLabel, error)
+}
+
+// Source returns the label source function the world builder calls per runner id.
+func Source(r Reader) func(context.Context, string) ([]string, error) {
+	return func(ctx context.Context, nodeID string) ([]string, error) {
+		set, err := r.NodeLabels(ctx, nodeID)
+		if err != nil {
+			return nil, err
+		}
+		return Strings(set), nil
+	}
+}
+
+// RegisterSource installs r as the process-wide world label source.
+func RegisterSource(r Reader) error {
+	return world.RegisterLabelSource(Source(r))
+}
diff --git a/free/ci/internal/nodes/lifecycle/cli_cmds.go b/free/ci/internal/nodes/lifecycle/cli_cmds.go
index 102a93edd..30e830418 100644
--- a/free/ci/internal/nodes/lifecycle/cli_cmds.go
+++ b/free/ci/internal/nodes/lifecycle/cli_cmds.go
@@ -70,7 +70,11 @@ func cmdList(ctx context.Context, d *Deps) (result, error) {
 	}
 	views := make([]NodeView, 0, len(nodes))
 	for _, n := range nodes {
-		views = append(views, ViewOf(n))
+		v, err := d.withLabels(ctx, ViewOf(n))
+		if err != nil {
+			return result{}, err
+		}
+		views = append(views, v)
 	}
 	return result{map[string]any{"nodes": views}, func(w io.Writer) { renderList(w, views) }}, nil
 }
@@ -80,7 +84,10 @@ func cmdShow(ctx context.Context, d *Deps, id string) (result, error) {
 	if err != nil {
 		return result{}, err
 	}
-	v := ViewOf(n)
+	v, err := d.withLabels(ctx, ViewOf(n))
+	if err != nil {
+		return result{}, err
+	}
 	return result{map[string]any{"node": v}, func(w io.Writer) { renderShow(w, v) }}, nil
 }
 
diff --git a/free/ci/internal/nodes/lifecycle/placement_view_test.go b/free/ci/internal/nodes/lifecycle/placement_view_test.go
new file mode 100644
index 000000000..3ab988814
--- /dev/null
+++ b/free/ci/internal/nodes/lifecycle/placement_view_test.go
@@ -0,0 +1,90 @@
+package lifecycle
+
+// Purpose: tests of P7-NODE-30 in the lifecycle package: `nodes show|list --json` report the assigned
+// labels as identity.labels (source assigned), and removing a project from a node refuses new leases (E657)
+// while an attempt already running there is left alone.
+// Inputs:  the kit of testkit_test.go. Outputs: pass or fail.
+// Constraints: no network.
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func TestShowAndListReportAssignedLabels(t *testing.T) {
+	k := newKit(t)
+	k.addNode("lb1")
+	k.addNode("lb2")
+	e := labels.Env{Store: k.st, Registry: k.d.Registry, Actor: "cli:test"}
+	if _, err := e.Edit(context.Background(), "lb1", []string{"xcode", "arch=arm64"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	want := []LabelView{{"arch", "arm64", "assigned"}, {"xcode", "", "assigned"}}
+	code, out, _ := k.run1("show", "lb1", "--json")
+	var s struct {
+		Node struct {
+			Identity IdentityView `json:"identity"`
+		} `json:"node"`
+	}
+	if err := json.Unmarshal(decode(t, out).Data, &s); err != nil || code != 0 || len(s.Node.Identity.Labels) != 2 || s.Node.Identity.Labels[0] != want[0] || s.Node.Identity.Labels[1] != want[1] {
+		t.Fatalf("show: code %d %v labels %+v", code, err, s.Node.Identity.Labels)
+	}
+	code, out, _ = k.run1("list", "--json")
+	var l struct {
+		Nodes []struct {
+			ID       string       `json:"id"`
+			Identity IdentityView `json:"identity"`
+		} `json:"nodes"`
+	}
+	if err := json.Unmarshal(decode(t, out).Data, &l); err != nil || code != 0 || len(l.Nodes) != 2 {
+		t.Fatalf("list: code %d %v %s", code, err, out)
+	}
+	for _, n := range l.Nodes {
+		if n.ID == "lb1" && len(n.Identity.Labels) != 2 || n.ID == "lb2" && (n.Identity.Labels == nil || len(n.Identity.Labels) != 0) {
+			t.Fatalf("list labels of %s: %+v", n.ID, n.Identity.Labels)
+		}
+	}
+}
+
+func TestProjectsRemoveRefusesNewLeasesRunningAttemptFinishes(t *testing.T) {
+	ctx := context.Background()
+	k := newKit(t)
+	k.addNode("rm1")
+	if err := Gate(ctx, k.d.Registry, "rm1", "proj-1"); err != nil {
+		t.Fatalf("authorized node refused: %v", err)
+	}
+	p := store.PipelineRow{ID: "pipe", Project: "proj-1", Revision: "rev", Trigger: "local", SourceTrust: "owner", PrivacyZone: "local-only", PolicyDigest: "p", InputDigest: "i", SelectionMode: "full", Status: "queued"}
+	if err := k.st.CreatePipeline(ctx, p); err != nil {
+		t.Fatal(err)
+	}
+	if err := k.st.CreateJob(ctx, store.JobRow{ID: "job1", PipelineID: p.ID, Name: "j", Kind: "test", Idempotent: true, InfraMax: 1, InputDigest: "i"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := k.st.CreateAttempt(ctx, store.AttemptRow{ID: "att1", JobID: "job1", N: 1}, ""); err != nil {
+		t.Fatal(err)
+	}
+	if err := k.st.AdmitAndLease(ctx, "host", store.Demand{AttemptID: "att1", RunnerID: "rm1", LeaseID: "lease1", CPU: 1, MemMB: 1, CapacityCPU: 4, CapacityMemMB: 64}); err != nil {
+		t.Fatal(err)
+	}
+	state := func() string {
+		atts, err := k.st.PipelineAttempts(ctx, p.ID)
+		if err != nil || len(atts) != 1 {
+			t.Fatalf("attempts %v %v", atts, err)
+		}
+		return string(atts[0].State)
+	}
+	before := state()
+	e := labels.Env{Store: k.st, Registry: k.d.Registry, Actor: "cli:test"}
+	removed, err := e.RemoveProjects(ctx, "rm1", []string{"proj-1"}, false)
+	if err != nil || len(removed) != 1 {
+		t.Fatalf("remove: %v %v", removed, err)
+	}
+	errCode(t, Gate(ctx, k.d.Registry, "rm1", "proj-1"), CodeRevoked) // E657: no new lease for the removed project
+	if after := state(); after != before {
+		t.Fatalf("the running attempt was touched: %s -> %s", before, after)
+	}
+}
diff --git a/free/ci/internal/nodes/lifecycle/view.go b/free/ci/internal/nodes/lifecycle/view.go
index 90f6257fa..720afd357 100644
--- a/free/ci/internal/nodes/lifecycle/view.go
+++ b/free/ci/internal/nodes/lifecycle/view.go
@@ -7,6 +7,7 @@ package lifecycle
 // Constraints: no key material and no token: only fingerprints (public), ids, states and trust fields.
 
 import (
+	"context"
 	"time"
 
 	"github.com/nself-org/plugins/free/ci/internal/model"
@@ -28,6 +29,18 @@ type SeparationView struct {
 	SigningEligible *bool `json:"signing_eligible"`
 }
 
+// LabelView is one operator-assigned label (P7-NODE-30); labels are never self-declared.
+type LabelView struct {
+	Key    string `json:"key"`
+	Value  string `json:"value"`
+	Source string `json:"source"`
+}
+
+// IdentityView is the assigned part of a node's identity.
+type IdentityView struct {
+	Labels []LabelView `json:"labels"`
+}
+
 // NodeView is one node.
 type NodeView struct {
 	ID                  string         `json:"id"`
@@ -41,6 +54,7 @@ type NodeView struct {
 	AuthorizedProjects  []string       `json:"authorized_projects"`
 	Eligible            bool           `json:"eligible"`
 	RevokedAt           *time.Time     `json:"revoked_at"`
+	Identity            IdentityView   `json:"identity"`
 	Trust               TrustView      `json:"trust"`
 	Separation          SeparationView `json:"separation"`
 	AgentVersion        string         `json:"agent_version"`
@@ -95,7 +109,7 @@ func ViewOf(n registry.Node) NodeView {
 	return NodeView{
 		ID: n.Record.ID, Name: n.Record.Name, State: n.Record.State, Reason: n.Record.Reason, Transport: c.Identity.Transport,
 		Platform: plat, Ownership: c.Identity.Ownership.Value, Discovered: c.Lifecycle.Discovered, AuthorizedProjects: projects,
-		Eligible: c.Lifecycle.Eligible, RevokedAt: c.Lifecycle.RevokedAt,
+		Eligible: c.Lifecycle.Eligible, RevokedAt: c.Lifecycle.RevokedAt, Identity: IdentityView{Labels: []LabelView{}},
 		Trust: TrustView{
 			Accepts: acceptsView(c.Trust.Accepts.Value), SecretClasses: strs(c.Trust.SecretClasses.Value),
 			PrivacyZone: ptrStr[model.PrivacyZone](c.Trust.PrivacyZone.Value), Isolation: ptrStr[model.Isolation](c.Trust.Isolation.Value),
@@ -104,3 +118,15 @@ func ViewOf(n registry.Node) NodeView {
 		AgentVersion: c.Protocol.AgentVersion, HostKeyFingerprints: fps, VerifiedBy: c.Verified.By, VerifiedAt: c.Verified.At,
 	}
 }
+
+// withLabels fills identity.labels from the assigned labels in the store (source assigned).
+func (d *Deps) withLabels(ctx context.Context, v NodeView) (NodeView, error) {
+	set, err := d.Store.NodeLabels(ctx, v.ID)
+	if err != nil {
+		return v, err
+	}
+	for _, l := range set {
+		v.Identity.Labels = append(v.Identity.Labels, LabelView{Key: l.Key, Value: l.Value, Source: "assigned"})
+	}
+	return v, nil
+}
diff --git a/free/ci/internal/nodes/probe/demand_read.go b/free/ci/internal/nodes/probe/demand_read.go
new file mode 100644
index 000000000..d98e67cfc
--- /dev/null
+++ b/free/ci/internal/nodes/probe/demand_read.go
@@ -0,0 +1,116 @@
+package probe
+
+// Purpose: the status reads of `ci nodes status` (P7-AUTO-19): the watch host's demand document
+// (contract:ci.demand v1) and its readiness block, read over the same SDK remote funnel and D4 option
+// set as the capability probe.
+// Inputs:  a registered node (its SSH identity), the pin file, an optional key and the local ssh version.
+// Outputs: StatusDocs with the raw documents; an empty document means the host publishes none.
+// Constraints: both commands are literals. The CI home is expanded by the remote shell from its own
+//          environment; no node, registry or inventory value enters a remote command. A missing file is
+//          not an error (only watch hosts publish demand.json); a transport failure is.
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+)
+
+const (
+	cmdDemand    = `cat "${NSELF_CI_HOME:-$HOME/.nself/ci}/demand.json" 2>/dev/null || true`
+	cmdReadiness = `cat "${NSELF_CI_HOME:-$HOME/.nself/ci}/readiness.json" 2>/dev/null || true`
+)
+
+var statusCommands = []string{cmdDemand, cmdReadiness}
+
+// StatusCommands returns the fixed read-only commands of a status read, in the order they run.
+func StatusCommands() []string { return append([]string(nil), statusCommands...) }
+
+// StatusRunner runs one literal command on a node and returns its output.
+type StatusRunner func(ctx context.Context, command string) (string, error)
+
+// StatusDocs are the raw documents a node publishes; nil when the node has none.
+type StatusDocs struct {
+	Demand    []byte
+	Readiness []byte
+}
+
+// ReadStatus runs the two literal reads with run. The first transport error ends the read.
+func ReadStatus(ctx context.Context, run StatusRunner) (StatusDocs, error) {
+	var docs StatusDocs
+	if run == nil {
+		return docs, fmt.Errorf("status read requires a runner")
+	}
+	for _, command := range statusCommands {
+		out, err := run(ctx, command)
+		if err != nil {
+			return StatusDocs{}, err
+		}
+		if ctx.Err() != nil {
+			return StatusDocs{}, ctx.Err()
+		}
+		var body []byte
+		if out != "" {
+			body = []byte(out)
+		}
+		if command == cmdDemand {
+			docs.Demand = body
+		} else {
+			docs.Readiness = body
+		}
+	}
+	return docs, nil
+}
+
+// SSHStatusRunner builds the runner of one registered SSH node with the pinned D4 option set.
+// The node's address picks the destination only; it never enters the command.
+func SSHStatusRunner(n registry.Node, pinnedFile, keyPath string, v remote.Version) (StatusRunner, error) {
+	ssh := n.Capability.Identity.SSH
+	if ssh == nil {
+		return nil, fmt.Errorf("no SSH identity registered (agent nodes report through their agent)")
+	}
+	if pinnedFile == "" {
+		return nil, fmt.Errorf("status read requires the pinned host key file")
+	}
+	host := ssh.Alias
+	if host == "" {
+		host = ssh.Hostname
+	}
+	if ssh.User != "" {
+		host = ssh.User + "@" + host
+	}
+	spec, err := remote.ParseHostSpec(host)
+	if err != nil {
+		return nil, err
+	}
+	if ssh.Port > 0 {
+		if spec, err = remote.ParseHostSpec(spec.String() + fmt.Sprintf(":%d", ssh.Port)); err != nil {
+			return nil, err
+		}
+	}
+	opts := append(remote.CISSHFlags(), remote.CIOptions(n.Record.ID, pinnedFile, v)...)
+	if keyPath != "" {
+		opts = append(opts, "-i", keyPath)
+	}
+	target, err := spec.Target(opts)
+	if err != nil {
+		return nil, err
+	}
+	return func(ctx context.Context, command string) (string, error) {
+		if !statusCommand(command) {
+			return "", fmt.Errorf("refused: not a fixed status command")
+		}
+		return remote.Run(ctx, target, "sh -c "+remote.ShellQuote(command))
+	}, nil
+}
+
+// statusCommand reports whether command is one of the literal status reads.
+func statusCommand(command string) bool {
+	for _, c := range statusCommands {
+		if command == c {
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/internal/nodes/probe/demand_read_test.go b/free/ci/internal/nodes/probe/demand_read_test.go
new file mode 100644
index 000000000..d87376cfc
--- /dev/null
+++ b/free/ci/internal/nodes/probe/demand_read_test.go
@@ -0,0 +1,115 @@
+package probe
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/cli/sdk/go/v2/remote"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// TestRemoteCommandsStatic proves every remote command is a source literal: each cmd* constant
+// is one basic string literal (no concatenation, no identifier, no call), and the status list
+// holds only those literals.
+func TestRemoteCommandsStatic(t *testing.T) {
+	fset := token.NewFileSet()
+	literals := map[string]bool{}
+	for _, file := range []string{"commands.go", "demand_read.go"} {
+		f, err := parser.ParseFile(fset, file, nil, 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, decl := range f.Decls {
+			gd, ok := decl.(*ast.GenDecl)
+			if !ok || gd.Tok != token.CONST {
+				continue
+			}
+			for _, spec := range gd.Specs {
+				vs := spec.(*ast.ValueSpec)
+				for i, name := range vs.Names {
+					if !strings.HasPrefix(name.Name, "cmd") {
+						continue
+					}
+					lit, ok := vs.Values[i].(*ast.BasicLit)
+					if !ok || lit.Kind != token.STRING {
+						t.Errorf("%s: %s is not one string literal", file, name.Name)
+						continue
+					}
+					literals[name.Name] = true
+				}
+			}
+		}
+	}
+	for _, name := range []string{"cmdDemand", "cmdReadiness"} {
+		if !literals[name] {
+			t.Errorf("%s is not a literal constant", name)
+		}
+	}
+	got := StatusCommands()
+	if len(got) != 2 || got[0] != cmdDemand || got[1] != cmdReadiness {
+		t.Fatalf("StatusCommands = %q", got)
+	}
+	for _, c := range got {
+		if strings.Contains(c, "%") || !strings.HasPrefix(c, "cat ") {
+			t.Errorf("status command %q is not a plain read", c)
+		}
+	}
+	got[0] = "rm -rf /"
+	if StatusCommands()[0] != cmdDemand {
+		t.Error("StatusCommands exposes its backing array")
+	}
+}
+
+func TestReadStatusSendsOnlyLiterals(t *testing.T) {
+	var sent []string
+	run := func(_ context.Context, command string) (string, error) {
+		sent = append(sent, command)
+		if command == cmdDemand {
+			return `{"ts":"2026-10-27T12:00:00Z","ready":true}`, nil
+		}
+		return "", nil
+	}
+	docs, err := ReadStatus(context.Background(), run)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(sent) != 2 || sent[0] != cmdDemand || sent[1] != cmdReadiness {
+		t.Fatalf("sent = %q", sent)
+	}
+	if !json.Valid(docs.Demand) || docs.Readiness != nil {
+		t.Fatalf("docs = %+v", docs)
+	}
+	boom := errors.New("connection refused")
+	if _, err := ReadStatus(context.Background(), func(context.Context, string) (string, error) { return "", boom }); !errors.Is(err, boom) {
+		t.Fatalf("transport error = %v", err)
+	}
+	if _, err := ReadStatus(context.Background(), nil); err == nil {
+		t.Fatal("nil runner accepted")
+	}
+}
+
+func TestSSHStatusRunnerRefusesOtherCommands(t *testing.T) {
+	n := registry.Node{Record: store.NodeRecord{ID: "n1"}}
+	if _, err := SSHStatusRunner(n, "/pins", "", remote.Version{Major: 9, Minor: 6}); err == nil {
+		t.Fatal("node without SSH identity accepted")
+	}
+	n.Capability.Identity.SSH = &model.CapabilitySSH{Hostname: "builder.lan", User: "ci", Port: 2222}
+	if _, err := SSHStatusRunner(n, "", "", remote.Version{Major: 9, Minor: 6}); err == nil {
+		t.Fatal("missing pin file accepted")
+	}
+	run, err := SSHStatusRunner(n, "/pins", "", remote.Version{Major: 9, Minor: 6})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := run(context.Background(), "cat /etc/shadow"); err == nil || !strings.Contains(err.Error(), "refused") {
+		t.Fatalf("non-literal command ran: %v", err)
+	}
+}
diff --git a/free/ci/internal/nodes/provision/cli.go b/free/ci/internal/nodes/provision/cli.go
index 05644957a..830f265f6 100644
--- a/free/ci/internal/nodes/provision/cli.go
+++ b/free/ci/internal/nodes/provision/cli.go
@@ -103,17 +103,8 @@ func parseCommand(fs *flagSet, name string, args []string, d Deps) (done bool, c
 // RunProvision is `nself ci nodes provision`.
 func RunProvision(args []string, d Deps) int {
 	fs := newFlagSet()
-	host := fs.add("host", kindSlice)
-	sshKey := fs.add("ssh-key", kindString)
-	instances := fs.add("instances", kindInt)
-	instances.num = 1
-	installRoot := fs.add("install-root", kindString)
-	githubURL := fs.add("github-url", kindString)
-	labels := fs.add("labels", kindSlice)
-	token := fs.add("token", kindString)
-	asJSON := fs.add("json", kindBool)
-	fs.add("no-monorepo", kindBool)
-	fs.add("no-deprecation-warnings", kindBool)
+	f := provisionFlags(fs)
+	host, sshKey, instances, installRoot, githubURL, labels, token, asJSON := f.host, f.sshKey, f.instances, f.installRoot, f.githubURL, f.labels, f.token, f.asJSON
 	if done, code := parseCommand(fs, "provision", args, d); done {
 		return code
 	}
@@ -209,11 +200,8 @@ func v15Pin(d Deps) (*RunnerPin, error) {
 // RunVerify is `nself ci nodes verify`.
 func RunVerify(args []string, d Deps) int {
 	fs := newFlagSet()
-	host := fs.add("host", kindSlice)
-	sshKey := fs.add("ssh-key", kindString)
-	asJSON := fs.add("json", kindBool)
-	fs.add("no-monorepo", kindBool)
-	fs.add("no-deprecation-warnings", kindBool)
+	f := verifyFlags(fs)
+	host, sshKey, asJSON := f.host, f.sshKey, f.asJSON
 	if done, code := parseCommand(fs, "verify", args, d); done {
 		return code
 	}
diff --git a/free/ci/internal/nodes/provision/help_only.go b/free/ci/internal/nodes/provision/help_only.go
new file mode 100644
index 000000000..58c6606d8
--- /dev/null
+++ b/free/ci/internal/nodes/provision/help_only.go
@@ -0,0 +1,57 @@
+package provision
+
+// Purpose: the flag sets of `nodes provision` and `nodes verify`, shared by the commands and by
+//   HelpOnly, which answers a help request the way core does without running anything.
+// Inputs:  argv after the subcommand key that asks for help (-h or --help).
+// Outputs: the captured core help on stdout and exit 0, or core's "Error: ..." and exit 1 when a
+//   flag before the help token does not parse (core's pflag reports the first parse error).
+// Constraints: HelpOnly never touches a host or the registry; a help token taken as a flag's value
+//   (`--token --help`) still prints help, because a help request must never run the command.
+
+import "fmt"
+
+// provisionFlagDefs are the `nodes provision` flags the command reads.
+type provisionFlagDefs struct {
+	host, sshKey, instances, installRoot, githubURL, labels, token, asJSON *flagDef
+}
+
+// provisionFlags adds the `nodes provision` flags to fs, with core's defaults.
+func provisionFlags(fs *flagSet) provisionFlagDefs {
+	f := provisionFlagDefs{
+		host: fs.add("host", kindSlice), sshKey: fs.add("ssh-key", kindString), instances: fs.add("instances", kindInt),
+		installRoot: fs.add("install-root", kindString), githubURL: fs.add("github-url", kindString),
+		labels: fs.add("labels", kindSlice), token: fs.add("token", kindString), asJSON: fs.add("json", kindBool),
+	}
+	f.instances.num = 1
+	fs.add("no-monorepo", kindBool)
+	fs.add("no-deprecation-warnings", kindBool)
+	return f
+}
+
+// verifyFlagDefs are the `nodes verify` flags the command reads.
+type verifyFlagDefs struct{ host, sshKey, asJSON *flagDef }
+
+// verifyFlags adds the `nodes verify` flags to fs.
+func verifyFlags(fs *flagSet) verifyFlagDefs {
+	f := verifyFlagDefs{host: fs.add("host", kindSlice), sshKey: fs.add("ssh-key", kindString), asJSON: fs.add("json", kindBool)}
+	fs.add("no-monorepo", kindBool)
+	fs.add("no-deprecation-warnings", kindBool)
+	return f
+}
+
+// HelpOnly answers `nodes <name> ... --help` for name "provision" or "verify": the flags parse first
+// (an error wins, exit 1, as in core), then the captured help prints (exit 0). It runs nothing.
+func HelpOnly(name string, args []string, d Deps) int {
+	fs := newFlagSet()
+	if name == "provision" {
+		provisionFlags(fs)
+	} else {
+		verifyFlags(fs)
+	}
+	if err := fs.parse(args); err != nil {
+		return finish(d, err)
+	}
+	txt, _ := Help(name)
+	_, _ = fmt.Fprint(d.Out, txt)
+	return 0
+}
diff --git a/free/ci/internal/nodes/provision/help_only_test.go b/free/ci/internal/nodes/provision/help_only_test.go
new file mode 100644
index 000000000..221b35fb9
--- /dev/null
+++ b/free/ci/internal/nodes/provision/help_only_test.go
@@ -0,0 +1,36 @@
+package provision
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// HelpOnly answers like core `nself runner provision|verify --help`: the captured text on a help request,
+// the first parse error when a flag before the help token is bad, and help (never a run) when the help
+// token is taken as a flag's value.
+func TestHelpOnlyMatchesCore(t *testing.T) {
+	for _, name := range []string{"provision", "verify"} {
+		want, ok := Help(name)
+		if !ok || want == "" {
+			t.Fatalf("no captured help for %s", name)
+		}
+		for _, tc := range []struct {
+			args    []string
+			code    int
+			out, er string
+		}{
+			{[]string{"--help"}, 0, want, ""},
+			{[]string{"-h"}, 0, want, ""},
+			{[]string{"--bogus", "--help"}, 1, "", "Error: unknown flag: --bogus\n"},
+			{[]string{"--ssh-key", "--help"}, 0, want, ""},
+		} {
+			var out, er bytes.Buffer
+			code := HelpOnly(name, tc.args, Deps{Out: &out, Err: &er})
+			if code != tc.code || out.String() != tc.out || er.String() != tc.er {
+				t.Errorf("%s %s: exit %d stdout %q stderr %q; want %d %q %q", name, strings.Join(tc.args, " "),
+					code, out.String(), er.String(), tc.code, tc.out, tc.er)
+			}
+		}
+	}
+}
diff --git a/free/ci/internal/offload/codes.go b/free/ci/internal/offload/codes.go
new file mode 100644
index 000000000..b48a4c2e2
--- /dev/null
+++ b/free/ci/internal/offload/codes.go
@@ -0,0 +1,7 @@
+package offload
+
+import "github.com/nself-org/plugins/free/ci/internal/model"
+
+func init() {
+	model.Register(model.Code{ID: CodeTracked, Class: "usage", Summary: "a tracked file is secret-shaped or over the size cap", Fix: "Untrack the file, or run the gate on a clean checkout"})
+}
diff --git a/free/ci/internal/offload/secrets.go b/free/ci/internal/offload/secrets.go
new file mode 100644
index 000000000..b9c622a92
--- /dev/null
+++ b/free/ci/internal/offload/secrets.go
@@ -0,0 +1,33 @@
+package offload
+
+// Purpose: the secret path list and size cap for the dirty-tree snapshot.
+// Inputs:  repository-relative paths and file sizes.
+// Outputs: whether a path is secret-shaped or too large.
+// Constraints: decided on the path and size only, never on file content.
+
+import (
+	"path"
+	"strings"
+)
+
+// MaxFileBytes is the size cap for one file in a snapshot (10 MiB).
+const MaxFileBytes = 10 << 20
+
+// SecretPath reports whether the base name of p is on the secret path list:
+// .env*, *.pem, *.key, id_*, .npmrc, .netrc and credentials files.
+func SecretPath(p string) bool {
+	b := strings.ToLower(path.Base(p))
+	switch {
+	case b == ".env", strings.HasPrefix(b, ".env."):
+		return true
+	case strings.HasSuffix(b, ".pem"), strings.HasSuffix(b, ".key"):
+		return true
+	case strings.HasPrefix(b, "id_"):
+		return true
+	case b == ".npmrc", b == ".netrc", b == ".git-credentials":
+		return true
+	case b == "credentials", strings.HasPrefix(b, "credentials."):
+		return true
+	}
+	return false
+}
diff --git a/free/ci/internal/offload/snapshot.go b/free/ci/internal/offload/snapshot.go
new file mode 100644
index 000000000..0d0a6c2f6
--- /dev/null
+++ b/free/ci/internal/offload/snapshot.go
@@ -0,0 +1,186 @@
+package offload
+
+// Purpose: turn a dirty working tree into a revision (P7-AUTO-13): a snapshot
+// commit of the working tree of every path the user's index tracks (staged or
+// not, including a file added and not yet committed) plus untracked files git
+// does not ignore, parent HEAD, held under the private ref refs/nself-ci/offload/<id> so the NODE-03
+// bundle transport can carry it.
+// Inputs:  the repository root, a scratch dir and an id.
+// Outputs: a Snapshot (sha, ref, names excluded) and a Release that deletes
+// the ref.
+// Constraints: uses a temporary index under scratch; never touches the user's
+// index, refs/heads or working tree. Git runs with no GIT_DIR, no replace
+// objects, hooks and fsmonitor off. Untracked secret-shaped or oversized files
+// are excluded and named only; a tracked one refuses the offload (E807).
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// CodeTracked is raised when a tracked file is secret-shaped or too large.
+const CodeTracked = "E807"
+
+// RefPrefix is the private namespace of snapshot refs.
+const RefPrefix = "refs/nself-ci/offload/"
+
+// Capture runs a process and returns merged output and its exit code.
+type Capture func(ctx context.Context, argv ...string) (string, int, error)
+
+// Snapshot is the revision a dirty run executes.
+type Snapshot struct {
+	SHA      string   // the snapshot commit (HEAD when the tree is clean)
+	Ref      string   // private ref; empty when the tree is clean
+	Clean    bool     // true: the existing HEAD path applies unchanged
+	Excluded []string // untracked paths left out, by name only
+}
+
+var idRe = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
+
+// Take builds the snapshot of root. A clean tree returns HEAD unchanged.
+func Take(ctx context.Context, capture Capture, root, scratch, id string) (*Snapshot, error) {
+	if !idRe.MatchString(id) {
+		return nil, fmt.Errorf("offload: bad snapshot id")
+	}
+	g := func(index string, args ...string) (string, error) {
+		argv := []string{"env", "-u", "GIT_DIR", "-u", "GIT_WORK_TREE", "-u", "GIT_INDEX_FILE"}
+		if index != "" {
+			argv = append(argv, "GIT_INDEX_FILE="+index)
+		}
+		// GIT_OPTIONAL_LOCKS=0: `status` must not refresh the user's index; GIT_LITERAL_PATHSPECS=1: a
+		// file name is a path, never a pathspec pattern or magic.
+		argv = append(argv, "GIT_OPTIONAL_LOCKS=0", "GIT_LITERAL_PATHSPECS=1", "GIT_AUTHOR_NAME=nself-ci", "GIT_AUTHOR_EMAIL=ci@localhost", "GIT_COMMITTER_NAME=nself-ci", "GIT_COMMITTER_EMAIL=ci@localhost",
+			"git", "--no-replace-objects", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-C", root)
+		out, code, err := capture(ctx, append(argv, args...)...)
+		if err != nil || code != 0 {
+			return out, fmt.Errorf("offload: git %s failed", args[0])
+		}
+		return strings.TrimSpace(out), nil
+	}
+	head, err := g("", "rev-parse", "HEAD")
+	if err != nil {
+		return nil, err
+	}
+	status, err := g("", "status", "--porcelain", "--untracked-files=normal")
+	if err != nil {
+		return nil, err
+	}
+	if status == "" {
+		return &Snapshot{SHA: head, Clean: true}, nil
+	}
+	tracked, err := g("", "ls-files", "-z")
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range split(tracked) {
+		if SecretPath(p) || tooBig(filepath.Join(root, p)) {
+			return nil, fmt.Errorf("%s: tracked file %q is secret-shaped or over the size cap; the offload is refused", CodeTracked, p)
+		}
+	}
+	others, err := g("", "ls-files", "-z", "--others", "--exclude-standard")
+	if err != nil {
+		return nil, err
+	}
+	var keep []byte
+	snap := &Snapshot{}
+	for _, p := range split(others) {
+		if SecretPath(p) || tooBig(filepath.Join(root, p)) {
+			snap.Excluded = append(snap.Excluded, p)
+			continue
+		}
+		keep = append(append(keep, p...), 0)
+	}
+	if err := os.MkdirAll(scratch, 0o700); err != nil {
+		return nil, err
+	}
+	index, list := filepath.Join(scratch, "index-"+id), filepath.Join(scratch, "paths-"+id)
+	defer os.Remove(index)
+	defer os.Remove(list)
+	if _, err := g(index, "read-tree", head); err != nil {
+		return nil, err
+	}
+	inHead, err := g(index, "ls-files", "-z")
+	if err != nil {
+		return nil, err
+	}
+	keep = append(keep, stagedNew(root, split(tracked), split(inHead))...)
+	if err := os.WriteFile(list, keep, 0o600); err != nil {
+		return nil, err
+	}
+	if _, err := g(index, "add", "-u"); err != nil {
+		return nil, err
+	}
+	if len(keep) > 0 {
+		if _, err := g(index, "add", "--pathspec-from-file="+list, "--pathspec-file-nul"); err != nil {
+			return nil, err
+		}
+	}
+	tree, err := g(index, "write-tree")
+	if err != nil {
+		return nil, err
+	}
+	sha, err := g(index, "commit-tree", tree, "-p", head, "-m", "nself-ci offload snapshot "+id)
+	if err != nil {
+		return nil, err
+	}
+	snap.Ref = RefPrefix + id
+	if _, err := g("", "update-ref", snap.Ref, sha); err != nil {
+		return nil, err
+	}
+	snap.SHA = sha
+	return snap, nil
+}
+
+// Release deletes the private ref. It is safe to call on success, failure and
+// cancel, with a cancelled context's replacement, and more than once.
+func Release(ctx context.Context, capture Capture, root string, s *Snapshot) error {
+	if s == nil || s.Ref == "" {
+		return nil
+	}
+	_, code, err := capture(ctx, "env", "-u", "GIT_DIR", "-u", "GIT_WORK_TREE", "git", "-C", root, "update-ref", "-d", s.Ref)
+	if err != nil || code != 0 {
+		return fmt.Errorf("offload: cannot delete the private ref")
+	}
+	s.Ref = ""
+	return nil
+}
+
+// stagedNew lists, NUL-terminated, the paths the user's index tracks that HEAD
+// does not (a file added with `git add` and not committed) and that exist in
+// the working tree: `add -u` over a HEAD index never sees them.
+func stagedNew(root string, tracked, inHead []string) []byte {
+	head := make(map[string]bool, len(inHead))
+	for _, p := range inHead {
+		head[p] = true
+	}
+	var out []byte
+	for _, p := range tracked {
+		if head[p] {
+			continue
+		}
+		head[p] = true // an unmerged path is listed once per stage
+		if _, err := os.Lstat(filepath.Join(root, p)); err == nil {
+			out = append(append(out, p...), 0)
+		}
+	}
+	return out
+}
+
+func split(z string) []string {
+	var out []string
+	for _, p := range strings.Split(z, "\x00") {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+func tooBig(p string) bool {
+	st, err := os.Lstat(p)
+	return err == nil && st.Mode().IsRegular() && st.Size() > MaxFileBytes
+}
diff --git a/free/ci/internal/offload/snapshot_test.go b/free/ci/internal/offload/snapshot_test.go
new file mode 100644
index 000000000..a9593851a
--- /dev/null
+++ b/free/ci/internal/offload/snapshot_test.go
@@ -0,0 +1,216 @@
+package offload
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func capture(ctx context.Context, argv ...string) (string, int, error) {
+	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	var b bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &b, &b
+	err := cmd.Run()
+	if ee, ok := err.(*exec.ExitError); ok {
+		return b.String(), ee.ExitCode(), nil
+	}
+	return b.String(), 0, err
+}
+
+func git(t *testing.T, root string, args ...string) string {
+	t.Helper()
+	argv := append([]string{"env", "GIT_CONFIG_GLOBAL=/dev/null", "GIT_CONFIG_SYSTEM=/dev/null", "git", "-C", root, "-c", "user.name=t", "-c", "user.email=t@localhost"}, args...)
+	out, code, err := capture(context.Background(), argv...)
+	if err != nil || code != 0 {
+		t.Fatalf("git %v: %v %d %s", args, err, code, out)
+	}
+	return strings.TrimSpace(out)
+}
+
+func write(t *testing.T, root, name, body string) {
+	t.Helper()
+	p := filepath.Join(root, name)
+	if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// hermeticGit keeps the host's git configuration out of the test: Take runs
+// git with the process environment, and a global excludes file (for example
+// one listing .env.local) would change what counts as untracked.
+func hermeticGit(t *testing.T) {
+	t.Helper()
+	home := t.TempDir()
+	global := filepath.Join(home, "gitconfig")
+	if err := os.WriteFile(global, nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("HOME", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	t.Setenv("GIT_CONFIG_NOSYSTEM", "1")
+	t.Setenv("GIT_CONFIG_GLOBAL", global)
+}
+
+func newRepo(t *testing.T) string {
+	hermeticGit(t)
+	root := t.TempDir()
+	git(t, root, "init", "-q")
+	write(t, root, "a.txt", "one\n")
+	write(t, root, ".gitignore", "ignored.txt\n.env\n")
+	git(t, root, "add", ".")
+	git(t, root, "commit", "-q", "-m", "base")
+	return root
+}
+
+func state(t *testing.T, root string) string {
+	return git(t, root, "status", "--porcelain=v2", "--ignored") + git(t, root, "for-each-ref") + git(t, root, "ls-files", "-s")
+}
+
+func TestSnapshotLeavesIndexAndRefs(t *testing.T) {
+	root := newRepo(t)
+	write(t, root, "a.txt", "two\n")
+	write(t, root, "new.txt", "n\n")
+	before := state(t, root)
+	s, err := Take(context.Background(), capture, root, t.TempDir(), "r1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Clean || s.Ref != RefPrefix+"r1" {
+		t.Fatalf("snapshot %+v", s)
+	}
+	if got := git(t, root, "show", s.SHA+":a.txt"); got != "two" {
+		t.Fatalf("tracked change missing: %q", got)
+	}
+	if git(t, root, "show", s.SHA+":new.txt") != "n" {
+		t.Fatal("untracked file missing")
+	}
+	if git(t, root, "rev-parse", s.SHA+"^") != git(t, root, "rev-parse", "HEAD") {
+		t.Fatal("parent is not HEAD")
+	}
+	if err := Release(context.Background(), capture, root, s); err != nil {
+		t.Fatal(err)
+	}
+	if after := state(t, root); after != before {
+		t.Fatalf("user state changed:\n%s\n---\n%s", before, after)
+	}
+}
+
+func TestSnapshotExcludesIgnoredAndEnv(t *testing.T) {
+	root := newRepo(t)
+	write(t, root, "ignored.txt", "x")
+	write(t, root, ".env", "x")
+	write(t, root, ".env.local", "x")
+	write(t, root, "ok.txt", "x")
+	s, err := Take(context.Background(), capture, root, t.TempDir(), "r2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer Release(context.Background(), capture, root, s)
+	files := git(t, root, "ls-tree", "-r", "--name-only", s.SHA)
+	for _, bad := range []string{"ignored.txt", ".env"} {
+		for _, f := range strings.Split(files, "\n") {
+			if f == bad {
+				t.Fatalf("%s was sent", bad)
+			}
+		}
+	}
+	if !strings.Contains(files, "ok.txt") || len(s.Excluded) != 1 || s.Excluded[0] != ".env.local" {
+		t.Fatalf("files %q excluded %v", files, s.Excluded)
+	}
+}
+
+func TestTrackedSecretRefused(t *testing.T) {
+	root := newRepo(t)
+	write(t, root, "deploy.pem", "x")
+	git(t, root, "add", "-f", "deploy.pem")
+	git(t, root, "commit", "-q", "-m", "pem")
+	write(t, root, "a.txt", "changed\n")
+	_, err := Take(context.Background(), capture, root, t.TempDir(), "r3")
+	if err == nil || !strings.HasPrefix(err.Error(), CodeTracked) || !strings.Contains(err.Error(), "deploy.pem") {
+		t.Fatalf("err = %v", err)
+	}
+	if git(t, root, "for-each-ref", RefPrefix) != "" {
+		t.Fatal("ref left behind")
+	}
+}
+
+func TestSnapshotRefCleanup(t *testing.T) {
+	root := newRepo(t)
+	s, err := Take(context.Background(), capture, root, t.TempDir(), "r4")
+	if err != nil || !s.Clean || s.Ref != "" {
+		t.Fatalf("clean tree: %+v %v", s, err)
+	}
+	write(t, root, "a.txt", "dirty\n")
+	s, err = Take(context.Background(), capture, root, t.TempDir(), "r5")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := Release(context.WithoutCancel(ctx), capture, root, s); err != nil {
+		t.Fatal(err)
+	}
+	if err := Release(context.Background(), capture, root, s); err != nil {
+		t.Fatal("second release must be a no-op")
+	}
+	if git(t, root, "for-each-ref", RefPrefix) != "" {
+		t.Fatal("private ref remains")
+	}
+}
+
+func TestSecretPathAndBadID(t *testing.T) {
+	for p, want := range map[string]bool{".env": true, "x/.env.local": true, "a.pem": true, "k.KEY": true, "id_rsa": true, ".npmrc": true, "credentials.json": true, "main.go": false, "environment.go": false} {
+		if SecretPath(p) != want {
+			t.Errorf("SecretPath(%q) != %v", p, want)
+		}
+	}
+	if _, err := Take(context.Background(), capture, ".", t.TempDir(), "../x"); err == nil {
+		t.Fatal("bad id accepted")
+	}
+}
+
+// A file added with `git add` and not committed is part of the user's tree: the
+// snapshot carries its working-tree content. A staged file deleted from the
+// working tree is not carried. The user's index file is byte-identical after.
+func TestSnapshotCarriesStagedNewFile(t *testing.T) {
+	root := newRepo(t)
+	write(t, root, "staged.txt", "staged\n")
+	write(t, root, "edited.txt", "staged version\n")
+	write(t, root, "gone.txt", "g\n")
+	git(t, root, "add", "staged.txt", "edited.txt", "gone.txt")
+	write(t, root, "edited.txt", "working tree version\n")
+	if err := os.Remove(filepath.Join(root, "gone.txt")); err != nil {
+		t.Fatal(err)
+	}
+	indexPath := filepath.Join(root, ".git", "index")
+	before, err := os.ReadFile(indexPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, err := Take(context.Background(), capture, root, t.TempDir(), "r5")
+	if err != nil {
+		t.Fatal(err)
+	}
+	after, err := os.ReadFile(indexPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer Release(context.Background(), capture, root, s)
+	files := "\n" + git(t, root, "ls-tree", "-r", "--name-only", s.SHA) + "\n"
+	if !strings.Contains(files, "\nstaged.txt\n") {
+		t.Errorf("a staged new file is missing from the snapshot:%s", files)
+	}
+	if got := git(t, root, "show", s.SHA+":edited.txt"); got != "working tree version" {
+		t.Errorf("edited.txt = %q, want the working-tree content", got)
+	}
+	if strings.Contains(files, "\ngone.txt\n") {
+		t.Errorf("a staged file deleted from the working tree was sent:%s", files)
+	}
+	if !bytes.Equal(before, after) {
+		t.Error("the user's index file changed")
+	}
+}
diff --git a/free/ci/internal/planview/human.go b/free/ci/internal/planview/human.go
index c4a0233d7..2f305779a 100644
--- a/free/ci/internal/planview/human.go
+++ b/free/ci/internal/planview/human.go
@@ -4,7 +4,10 @@ package planview
 // `ci explain` (the chosen runner and every alternative).
 // Inputs: a model.PlacementPlan. Outputs: strings; no colour, no timestamps.
 // Constraints: secret classes by name only; an unknown value prints as
-// "unknown", never as 0; alternatives print in the document's order (runner id).
+// "unknown", never as 0; alternatives print in the document's order (runner id);
+// the `auto` preset adds the chosen runner's tier and bias and the tier.waiting
+// detail (the held better runner and the wait left), every other preset's
+// lines are unchanged.
 
 import (
 	"fmt"
@@ -12,6 +15,7 @@ import (
 	"strings"
 
 	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
 )
 
 // Cells returns one PLACEMENT cell per job, in job order.
@@ -35,7 +39,18 @@ func cell(j model.JobPlacement) string {
 	if len(codes) == 0 {
 		return j.Status
 	}
-	return j.Status + ": " + strings.Join(codes, ",")
+	text := j.Status + ": " + strings.Join(codes, ",")
+	for _, r := range j.Reasons {
+		if r.Code == string(model.TierWaiting) && r.Detail != "" {
+			text += " (" + r.Detail + ")"
+		}
+	}
+	return text
+}
+
+// tierText is the chosen runner's tier and its tier_rank bias under `auto`.
+func tierText(pl *model.Placement) string {
+	return fmt.Sprintf("  tier %s  bias %d", sched.TierFor(pl.Location, pl.CostClass), pl.Components["tier_rank"].ValueMs)
 }
 
 func costText(e model.Estimate) string {
@@ -113,7 +128,11 @@ func ExplainLines(p model.PlacementPlan, source string) []string {
 			out = append(out, fmt.Sprintf("  reason  %s  %s", r.Code, r.Detail))
 		}
 		if pl := j.Placement; pl != nil {
-			out = append(out, fmt.Sprintf("  chosen  %s  provider %s  %s  %s  score %d  cost %s", pl.RunnerID, orNone(pl.Provider), pl.Location, pl.CostClass, pl.Score, costText(pl.Estimate)))
+			line := fmt.Sprintf("  chosen  %s  provider %s  %s  %s  score %d  cost %s", pl.RunnerID, orNone(pl.Provider), pl.Location, pl.CostClass, pl.Score, costText(pl.Estimate))
+			if p.Pipeline.Preset == sched.AutoPreset {
+				line += tierText(pl)
+			}
+			out = append(out, line)
 			out = append(out, "    "+componentText(pl.Components))
 		}
 		chosen := ""
diff --git a/free/ci/internal/planview/tier_wait_test.go b/free/ci/internal/planview/tier_wait_test.go
new file mode 100644
index 000000000..fcf93698f
--- /dev/null
+++ b/free/ci/internal/planview/tier_wait_test.go
@@ -0,0 +1,77 @@
+package planview
+
+// Purpose: under the `auto` preset `ci plan` and `ci explain` show the chosen
+// runner's tier and bias and, for a held job, the tier.waiting detail with the
+// wait left (P7-AUTO-05); every other preset's lines stay as they were.
+// Inputs: a two-runner world (busy better tier, free lower tier) and the
+// fixture's linux jobs. Outputs: pass or fail.
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+// tierWorld puts a busy runner in the better tier and a free one a tier lower;
+// the tier index comes from Bias, the way internal/tiers writes it.
+func tierWorld(t *testing.T, preset string) sched.World {
+	t.Helper()
+	w, _, _ := fixture(t)
+	busy, free := w.Runners[0], w.Runners[0]
+	busy.ID, busy.Avail.Slots = "busy-local", 0
+	busy.Capability.Identity.ID = busy.ID
+	free.ID = "free-local"
+	free.Capability.Identity.ID = free.ID
+	w.Runners = []sched.Runner{busy, free}
+	w.Policy.Preset = preset
+	w.Bias = map[string]int64{"busy-local": 0, "free-local": sched.TierStepMs}
+	return w
+}
+
+func tierDoc(w sched.World, jobs []sched.Job) model.PlacementPlan {
+	return Build(Input{Name: "default", Revision: strings.Repeat("a", 40), Trigger: "local", PolicyDigest: "p" + strings.Repeat("0", 63),
+		WorldDigest: "w" + strings.Repeat("0", 63), World: w, Jobs: jobs, Result: sched.Place(w, jobs)})
+}
+
+func linuxBuild(t *testing.T, queuedMs int64) []sched.Job {
+	t.Helper()
+	_, jobs, _ := fixture(t)
+	for _, j := range jobs {
+		if j.Name == "build" {
+			j.QueuedMs = queuedMs
+			return []sched.Job{j}
+		}
+	}
+	t.Fatal("fixture has no build job")
+	return nil
+}
+
+func TestPlanShowsTierAndWait(t *testing.T) {
+	// A fresh job waits for the busy better tier: the cell names tier.waiting and the wait left.
+	held := tierDoc(tierWorld(t, sched.AutoPreset), linuxBuild(t, 0))
+	cells := Cells(held)
+	if len(cells) != 1 || !strings.Contains(cells[0], string(model.TierWaiting)) || !strings.Contains(cells[0], "ms left of step_sec") {
+		t.Fatalf("a held job's cell must show tier.waiting with the wait left: %q", cells)
+	}
+	if !strings.Contains(cells[0], "busy-local") {
+		t.Fatalf("the cell must name the held better runner: %q", cells[0])
+	}
+
+	// Past step_sec it runs on the lower tier, and the chosen line shows its tier and bias.
+	ran := tierDoc(tierWorld(t, sched.AutoPreset), linuxBuild(t, sched.DefaultAutoStepSec*1000+1))
+	lines := strings.Join(ExplainLines(ran, SourcePlan), "\n")
+	if !strings.Contains(lines, "chosen  free-local") {
+		t.Fatalf("the job must run on the lower tier after the wait:\n%s", lines)
+	}
+	if !strings.Contains(lines, "  tier local  bias ") {
+		t.Fatalf("the auto chosen line must show tier and bias:\n%s", lines)
+	}
+
+	// Another preset with the same world prints no tier text.
+	plain := strings.Join(ExplainLines(tierDoc(tierWorld(t, "balanced"), linuxBuild(t, 0)), SourcePlan), "\n")
+	if strings.Contains(plain, "  tier ") || strings.Contains(plain, string(model.TierWaiting)) {
+		t.Fatalf("a non-auto preset must not print tier text:\n%s", plain)
+	}
+}
diff --git a/free/ci/internal/pools/contract.go b/free/ci/internal/pools/contract.go
new file mode 100644
index 000000000..651863f1f
--- /dev/null
+++ b/free/ci/internal/pools/contract.go
@@ -0,0 +1,73 @@
+// Package pools resolves runner pools (Epic AUTO D4, D10) and the effective pool set of a project.
+package pools
+
+// Purpose: contract:ci.pool v1 (schema free/ci/schemas/pool.v1.schema.json): the resolved view of one
+//          pool. A pool is not stored anywhere: it is the set of runners carrying the coordinator-assigned
+//          label `pool.<id>` (P7-NODE-30), plus the implicit pools `local` (this machine's runner) and
+//          `hosted` (every provider runner).
+// Inputs:  none.
+// Outputs: Pool, Member, Effective and the Scope and member Source names.
+// Constraints: scope is derived from where a member was reached, never configured; a new field here is a
+//          contract change.
+
+import "github.com/nself-org/plugins/free/ci/internal/model"
+
+// SchemaID is the value of Pool.Schema.
+const SchemaID = "ci.pool/v1"
+
+// Scope says whose authority a pool's membership comes from.
+type Scope string
+
+// The pool scopes.
+const (
+	// ScopeOperator is a pool of nodes in the invoking person's own store (and the local pool).
+	ScopeOperator Scope = "operator"
+	// ScopeProject is a pool with a member reached through a TEAM coordinator.
+	ScopeProject Scope = "project"
+	// ScopeHosted is the implicit pool of provider runners.
+	ScopeHosted Scope = "hosted"
+)
+
+// Where a member was reached.
+const (
+	// SourceLocal is this machine's runner.
+	SourceLocal = "local"
+	// SourceRegistry is a node of the invoking person's store.
+	SourceRegistry = "registry"
+	// SourceCoordinator is a node reached through a TEAM coordinator.
+	SourceCoordinator = "coordinator"
+	// SourceProvider is a hosted provider runner.
+	SourceProvider = "provider"
+)
+
+// The pool.excluded details, one per term of the effective set.
+const (
+	// DetailNotInProjectList: no pool of the runner is listed in pools.allow.
+	DetailNotInProjectList = "not_in_project_list"
+	// DetailNotEnrolled: the person is enrolled in no pool of the runner that the project allows.
+	DetailNotEnrolled = "not_enrolled"
+	// DetailDevNotAllowed: a dev run, and no remaining pool of the runner is listed in pools.dev.
+	DetailDevNotAllowed = "dev_not_allowed"
+)
+
+// Member is one runner of a pool.
+type Member struct {
+	RunnerID string `json:"runner_id"`
+	Location string `json:"location"`
+	Source   string `json:"source"`
+}
+
+// Effective says whether the pool is in the effective set and, if not, why.
+type Effective struct {
+	Allowed bool                          `json:"allowed"`
+	Reasons []model.PlacementReasonDetail `json:"reasons"`
+}
+
+// Pool is the contract:ci.pool v1 document of one pool.
+type Pool struct {
+	Schema    string    `json:"schema"`
+	ID        string    `json:"id"`
+	Scope     Scope     `json:"scope"`
+	Members   []Member  `json:"members"`
+	Effective Effective `json:"effective"`
+}
diff --git a/free/ci/internal/pools/contract_test.go b/free/ci/internal/pools/contract_test.go
new file mode 100644
index 000000000..e50f3f3aa
--- /dev/null
+++ b/free/ci/internal/pools/contract_test.go
@@ -0,0 +1,105 @@
+package pools
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"os"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden files")
+
+func TestPoolContractGolden(t *testing.T) {
+	runners := []Runner{{ID: "local", Source: SourceLocal, Location: "local", Assigned: []string{"pool.mine"}},
+		{ID: "vps", Source: SourceRegistry, Location: "remote", Assigned: []string{"pool.mine", "region=eu"}},
+		{ID: "t1", Source: SourceCoordinator, Location: "lan", Assigned: []string{"pool.team"}},
+		{ID: "gh-ubuntu", Source: SourceProvider, Location: "hosted"}}
+	got := Resolve(Input{Runners: runners, Allow: List{Set: true, IDs: []string{"team", "local"}}})
+	body, err := json.MarshalIndent(got.Pools, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body = append(body, '\n')
+	const path = "testdata/pools.golden.json"
+	if *update {
+		if err = os.WriteFile(path, body, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	want, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(body, want) {
+		t.Fatalf("pools differ from %s (run with -update):\n%s", path, body)
+	}
+	schema, err := os.ReadFile("../../schemas/pool.v1.schema.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range got.Pools {
+		doc, _ := json.Marshal(p)
+		if err = model.ValidateJSON(schema, doc); err != nil {
+			t.Fatalf("pool %s: %v", p.ID, err)
+		}
+	}
+	for name, doc := range map[string]string{
+		"reserved scope":     `{"schema":"ci.pool/v1","id":"a","scope":"team","members":[],"effective":{"allowed":true,"reasons":[]}}`,
+		"bad id":             `{"schema":"ci.pool/v1","id":"A","scope":"operator","members":[],"effective":{"allowed":true,"reasons":[]}}`,
+		"excluded no reason": `{"schema":"ci.pool/v1","id":"a","scope":"operator","members":[],"effective":{"allowed":false,"reasons":[]}}`,
+		"unknown detail":     `{"schema":"ci.pool/v1","id":"a","scope":"operator","members":[],"effective":{"allowed":false,"reasons":[{"code":"pool.excluded","detail":"x"}]}}`,
+	} {
+		if model.ValidateJSON(schema, []byte(doc)) == nil {
+			t.Fatalf("%s: the schema accepted %s", name, doc)
+		}
+	}
+}
+
+type fakeLabels map[string][]store.NodeLabel
+
+func (f fakeLabels) NodeLabels(_ context.Context, id string) ([]store.NodeLabel, error) {
+	return f[id], nil
+}
+
+func allowPolicy(t *testing.T, ids string) trust.Effective {
+	t.Helper()
+	reg, err := trust.NewRegistry(Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceProtectedBranch, Values: map[string]json.RawMessage{KeyAllow: json.RawMessage(ids)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return eff
+}
+
+func TestExclusionProvider(t *testing.T) {
+	declared := sched.Runner{ID: "vps"}
+	declared.Capability.Identity.Labels = []string{"pool.team"} // self-declared: never membership
+	w := sched.World{Runners: []sched.Runner{declared, {ID: "t1"}, {ID: "local"}}, Hosted: []sched.Runner{{ID: "gh"}}}
+	fn := ExclusionProvider(Config{Labels: fakeLabels{"t1": {{Key: "pool.team"}}}, Team: func() bool { return true }})
+	if got, err := fn(context.Background(), w); err != nil || got != nil {
+		t.Fatalf("no term set: %v %v", got, err)
+	}
+	w.Policy.Trust = allowPolicy(t, `["team"]`)
+	got, err := fn(context.Background(), w)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, id := range []string{"vps", "local", "gh"} {
+		if len(got[id]) != 1 || got[id][0].Code != string(model.PoolExcluded) || got[id][0].Detail != DetailNotInProjectList {
+			t.Fatalf("runner %s: %v", id, got[id])
+		}
+	}
+	if _, kept := got["t1"]; kept {
+		t.Fatalf("team member excluded: %v", got)
+	}
+}
diff --git a/free/ci/internal/pools/explain.go b/free/ci/internal/pools/explain.go
new file mode 100644
index 000000000..4f2964d15
--- /dev/null
+++ b/free/ci/internal/pools/explain.go
@@ -0,0 +1,47 @@
+package pools
+
+// Purpose: the explanation of a project's effective set (`ci nodes pools explain`): every runner a pool
+//          term drops, for a run of record and for a dev run, with its pool.excluded detail.
+// Inputs:  an Input (Dev is ignored: both run kinds are resolved) and the notes of FromPolicy.
+// Outputs: Explanation, the data of `explain --json`.
+// Constraints: pure; the excluded rows keep the order of Input.Runners.
+
+import "github.com/nself-org/plugins/free/ci/internal/model"
+
+// Explanation is the effective set of one project and why each other runner is out.
+type Explanation struct {
+	Project      string        `json:"project"`
+	Pools        []Pool        `json:"pools"`
+	Eligible     []string      `json:"eligible"`
+	Excluded     []ExcludedRow `json:"excluded"`
+	Unauthorized []string      `json:"unauthorized"`
+	DevExcluded  []ExcludedRow `json:"dev_excluded"`
+	Notes        []string      `json:"notes"`
+}
+
+// ExcludedRow is one runner the pool terms drop.
+type ExcludedRow struct {
+	RunnerID string                        `json:"runner_id"`
+	Pools    []string                      `json:"pools"`
+	Reasons  []model.PlacementReasonDetail `json:"reasons"`
+}
+
+// Explain resolves in for a run of record and for a dev run.
+func Explain(in Input, notes []string) Explanation {
+	in.Dev = false
+	rec := Resolve(in)
+	in.Dev = true
+	dev := Resolve(in)
+	return Explanation{Project: in.Project, Pools: rec.Pools, Eligible: rec.Eligible, Excluded: rows(in.Runners, rec),
+		Unauthorized: rec.Unauthorized, DevExcluded: rows(in.Runners, dev), Notes: append([]string{}, notes...)}
+}
+
+func rows(runners []Runner, res Result) []ExcludedRow {
+	out := []ExcludedRow{}
+	for _, r := range runners {
+		if why, ok := res.Excluded[r.ID]; ok {
+			out = append(out, ExcludedRow{RunnerID: r.ID, Pools: append([]string{}, Memberships(r)...), Reasons: why})
+		}
+	}
+	return out
+}
diff --git a/free/ci/internal/pools/ids.go b/free/ci/internal/pools/ids.go
new file mode 100644
index 000000000..825c45bf8
--- /dev/null
+++ b/free/ci/internal/pools/ids.go
@@ -0,0 +1,49 @@
+package pools
+
+// Purpose: pool id syntax and the reading of pool membership from assigned labels.
+// Inputs:  pool ids, and a runner's assigned labels in the placement form (`key` or `key=value`).
+// Outputs: ValidID, Reserved, FromAssigned.
+// Constraints: ids match ^[a-z][a-z0-9-]{0,30}$; `local` and `hosted` are implicit and never come from a
+//          label; `pool.` is the only label namespace read. Callers pass assigned labels only: a node's
+//          self-declared labels are never membership.
+
+import (
+	"regexp"
+	"slices"
+	"strings"
+)
+
+// LabelPrefix is the assigned-label key prefix that makes a runner a pool member.
+const LabelPrefix = "pool."
+
+// The implicit pool ids.
+const (
+	// Local is the pool of this machine's runner.
+	Local = "local"
+	// Hosted is the pool of every provider runner.
+	Hosted = "hosted"
+)
+
+var idRE = regexp.MustCompile(`^[a-z][a-z0-9-]{0,30}$`)
+
+// ValidID reports whether id is a well-formed pool id.
+func ValidID(id string) bool { return idRE.MatchString(id) }
+
+// Reserved reports whether id is an implicit pool id.
+func Reserved(id string) bool { return id == Local || id == Hosted }
+
+// FromAssigned returns the pool ids named by assigned labels, sorted and without duplicates. A label
+// outside the `pool.` namespace, with a malformed id or naming an implicit pool is not membership.
+func FromAssigned(labels []string) []string {
+	var out []string
+	for _, l := range labels {
+		key, _, _ := strings.Cut(l, "=")
+		id, ok := strings.CutPrefix(key, LabelPrefix)
+		if !ok || !ValidID(id) || Reserved(id) || slices.Contains(out, id) {
+			continue
+		}
+		out = append(out, id)
+	}
+	slices.Sort(out)
+	return out
+}
diff --git a/free/ci/internal/pools/keys.go b/free/ci/internal/pools/keys.go
new file mode 100644
index 000000000..e34abf571
--- /dev/null
+++ b/free/ci/internal/pools/keys.go
@@ -0,0 +1,119 @@
+package pools
+
+// Purpose: the policy keys pools.allow and pools.dev (contract:ci.policy v1) and their reading from a
+//          resolved policy.
+// Inputs:  init() registers the keys with policy.RegisterKey; FromPolicy reads a trust.Effective.
+// Outputs: Keys, FromPolicy (the two terms and the notes of values that did not apply).
+// Constraints: pools.allow is a project key: the protected default branch's `.nself/ci.yaml` lists the
+//          pools that may run the project, and the revision may only shrink that list (TightenSubset;
+//          the loader ignores and reports a widening revision). pools.dev is an operator key: a value
+//          from the branch, the revision, a pipeline or a job is ignored and reported here. Both keys
+//          default to unset, which means every pool: no default value joins the policy digest.
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"slices"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// The policy keys this package owns.
+const (
+	KeyAllow = "pools.allow"
+	KeyDev   = "pools.dev"
+)
+
+// Owner is the owner name of the pool keys.
+const Owner = "pools"
+
+func init() {
+	for _, k := range Keys() {
+		if err := policy.RegisterKey(k); err != nil {
+			panic("pools: " + err.Error())
+		}
+	}
+}
+
+// Keys returns the specs of the pool keys.
+func Keys() []policy.KeySpec {
+	return []policy.KeySpec{
+		{Key: KeyAllow, Owner: Owner, Kind: policy.TightenSubset, Decode: decodeIDs},
+		{Key: KeyDev, Owner: Owner, Kind: policy.TightenSubset, Decode: decodeIDs},
+	}
+}
+
+// decodeIDs accepts a JSON list of pool ids (implicit ids included).
+func decodeIDs(raw json.RawMessage) (any, error) {
+	d := json.NewDecoder(bytes.NewReader(raw))
+	var ids []string
+	if err := d.Decode(&ids); err != nil || ids == nil {
+		return nil, fmt.Errorf("expected a list of pool ids")
+	}
+	out := make([]any, 0, len(ids))
+	for _, id := range ids {
+		if !ValidID(id) {
+			return nil, fmt.Errorf("pool id %q is not valid", id)
+		}
+		out = append(out, id)
+	}
+	return out, nil
+}
+
+// List is an optional pool list: Set false means the key is unset (every pool).
+type List struct {
+	Set bool
+	IDs []string
+}
+
+// Has reports whether id is in a set list.
+func (l List) Has(id string) bool { return slices.Contains(l.IDs, id) }
+
+// operatorSources are the scopes pools.dev may come from.
+var operatorSources = map[trust.Source]bool{trust.SourceDefault: true, trust.SourceUser: true, trust.SourceTeam: true, trust.SourceProject: true, trust.SourceRun: true}
+
+// FromPolicy reads the two pool terms from a resolved policy. notes lists every pool key value that did
+// not apply: the loader's ignored entries for the pool keys and a pools.dev outside operator scope.
+func FromPolicy(eff trust.Effective) (allow, dev List, notes []string) {
+	allow = listValue(eff, KeyAllow)
+	if v, src, ok := eff.Value(KeyDev); ok {
+		if operatorSources[src] {
+			dev = toList(v)
+		} else {
+			notes = append(notes, fmt.Sprintf("%s from %s ignored: an operator key", KeyDev, src))
+		}
+	}
+	for _, ig := range eff.Ignored() {
+		if ig.Key == KeyAllow || ig.Key == KeyDev {
+			notes = append(notes, fmt.Sprintf("%s from %s ignored: %s", ig.Key, ig.Scope, ig.Reason))
+		}
+	}
+	return allow, dev, notes
+}
+
+func listValue(eff trust.Effective, key string) List {
+	v, _, ok := eff.Value(key)
+	if !ok {
+		return List{}
+	}
+	return toList(v)
+}
+
+func toList(v any) List {
+	l := List{Set: true, IDs: []string{}}
+	switch xs := v.(type) {
+	case []string:
+		l.IDs = append(l.IDs, xs...)
+	case []any:
+		for _, x := range xs {
+			if s, ok := x.(string); ok {
+				l.IDs = append(l.IDs, s)
+			}
+		}
+	}
+	slices.Sort(l.IDs)
+	l.IDs = slices.Compact(l.IDs)
+	return l
+}
diff --git a/free/ci/internal/pools/provider.go b/free/ci/internal/pools/provider.go
new file mode 100644
index 000000000..fe06c9a29
--- /dev/null
+++ b/free/ci/internal/pools/provider.go
@@ -0,0 +1,106 @@
+package pools
+
+// Purpose: the autoworld exclusion provider (P7-AUTO-27): every runner the pool terms drop carries
+//          pool.excluded with its detail, so `ci plan` and `ci explain` show it like any other reason.
+// Inputs:  Config: the assigned-label reader, whether the store is a TEAM coordinator's, the dev-run test
+//          and the optional enrolment source; the world's resolved policy (w.Policy.Trust) gives the terms.
+// Outputs: autoworld.ExclusionFn; Register adds it under ProviderName; RunnersFromWorld.
+// Constraints: membership comes from the label reader only (the world's runner labels mix in the node's
+//          self-declared labels, so they are never read). With every term unset the provider reads
+//          nothing and returns nothing, so placement is byte-identical to a build without pools. The
+//          authorized_projects term is left to placement's own reason.
+
+import (
+	"context"
+
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// ProviderName is the name the provider registers under.
+const ProviderName = "pools"
+
+// localRunnerID is the id world.BuildForLocal gives this machine's runner.
+const localRunnerID = "local"
+
+// LabelReader reads one runner's coordinator-assigned labels; *store.Store and labels.LazyReader satisfy it.
+type LabelReader interface {
+	NodeLabels(ctx context.Context, nodeID string) ([]store.NodeLabel, error)
+}
+
+// Config wires the provider.
+type Config struct {
+	Labels LabelReader
+	// Team reports whether the store is a TEAM coordinator's: its nodes are then reached through it.
+	Team func() bool
+	// Dev reports whether the run being planned is a dev run; nil means never.
+	Dev func() bool
+	// Enrolled returns the pools the person is enrolled in; nil means every pool they see.
+	Enrolled func(ctx context.Context) (List, error)
+}
+
+// ExclusionProvider returns the provider for c.
+func ExclusionProvider(c Config) autoworld.ExclusionFn {
+	return func(ctx context.Context, w sched.World) (map[string][]model.PlacementReasonDetail, error) {
+		allow, devPools, _ := FromPolicy(w.Policy.Trust)
+		in := Input{Allow: allow, DevPools: devPools, Dev: c.Dev != nil && c.Dev()}
+		if c.Enrolled != nil {
+			var err error
+			if in.Enrolled, err = c.Enrolled(ctx); err != nil {
+				return nil, err
+			}
+		}
+		if !in.Allow.Set && !in.Enrolled.Set && !(in.Dev && in.DevPools.Set) {
+			return nil, nil
+		}
+		var err error
+		if in.Runners, err = RunnersFromWorld(ctx, w, c); err != nil {
+			return nil, err
+		}
+		got := Resolve(in).Excluded
+		if len(got) == 0 {
+			return nil, nil
+		}
+		return got, nil
+	}
+}
+
+// Register adds the provider to autoworld. Call it once from the composition root.
+func Register(c Config) error {
+	return autoworld.RegisterExclusion(ProviderName, ExclusionProvider(c))
+}
+
+// RunnersFromWorld turns the world's runners into resolver runners with their assigned labels.
+func RunnersFromWorld(ctx context.Context, w sched.World, c Config) ([]Runner, error) {
+	team := c.Team != nil && c.Team()
+	out := make([]Runner, 0, len(w.Runners)+len(w.Hosted))
+	for _, r := range w.Runners {
+		src := SourceRegistry
+		switch {
+		case r.ID == localRunnerID:
+			src = SourceLocal
+		case team:
+			src = SourceCoordinator
+		}
+		got := Runner{ID: r.ID, Location: r.Location, Source: src, Projects: r.Capability.Lifecycle.AuthorizedProjects}
+		if c.Labels != nil {
+			set, err := c.Labels.NodeLabels(ctx, r.ID)
+			if err != nil {
+				return nil, err
+			}
+			got.Assigned = labels.Strings(set)
+		}
+		out = append(out, got)
+	}
+	for _, r := range w.Hosted {
+		loc := r.Location
+		if loc == "" {
+			loc = "hosted"
+		}
+		out = append(out, Runner{ID: r.ID, Location: loc, Source: SourceProvider})
+	}
+	return out, nil
+}
diff --git a/free/ci/internal/pools/record/provider.go b/free/ci/internal/pools/record/provider.go
new file mode 100644
index 000000000..5dfde867b
--- /dev/null
+++ b/free/ci/internal/pools/record/provider.go
@@ -0,0 +1,34 @@
+package record
+
+// Purpose: exclude non-record runners before checkout or admission.
+// Inputs: trusted label reader, run kind and resolved placement world.
+// Outputs: autoworld exclusions. Constraints: unreadable labels exclude all.
+
+import (
+	"context"
+
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+// ExclusionProvider checks commit-CI only; dev runs use pools.dev instead.
+func ExclusionProvider(c pools.Config, isRecord func(context.Context) bool) autoworld.ExclusionFn {
+	return func(ctx context.Context, w sched.World) (map[string][]model.PlacementReasonDetail, error) {
+		if isRecord == nil || !isRecord(ctx) {
+			return nil, nil
+		}
+		runners, err := pools.RunnersFromWorld(ctx, w, c)
+		if err != nil || c.Labels == nil {
+			out := map[string][]model.PlacementReasonDetail{}
+			for _, rs := range [][]sched.Runner{w.Runners, w.Hosted} {
+				for _, r := range rs {
+					out[r.ID] = []model.PlacementReasonDetail{{Code: string(model.PoolExcluded), Detail: Reason}}
+				}
+			}
+			return out, nil
+		}
+		return Excluded(FromPolicy(w.Policy.Trust), runners), nil
+	}
+}
diff --git a/free/ci/internal/pools/record/record.go b/free/ci/internal/pools/record/record.go
new file mode 100644
index 000000000..ccc58f481
--- /dev/null
+++ b/free/ci/internal/pools/record/record.go
@@ -0,0 +1,108 @@
+// Package record enforces the pools permitted to produce a status of record.
+package record
+
+// Purpose: register pools.record and evaluate trusted pool membership.
+// Inputs: resolved policy and coordinator-assigned runner facts.
+// Outputs: a record decision, independent of development placement.
+// Constraints: revisions only narrow; missing or malformed facts fail closed.
+
+import (
+	"encoding/json"
+	"fmt"
+	"slices"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// Key is the protected project's record-pool policy key.
+const Key = "pools.record"
+
+// Reason is the exclusion and publication refusal detail.
+const Reason = "not_a_record_pool"
+
+// Code is the publication refusal code.
+const Code = "E809"
+
+func init() {
+	if err := policy.RegisterKey(Spec()); err != nil {
+		panic(err)
+	}
+	model.Register(model.Code{ID: Code, Class: "policy", Summary: Reason, Fix: "Run commit CI on a pool listed in pools.record"})
+}
+
+// Spec returns the tighten-only project key, with an unset dynamic default.
+func Spec() policy.KeySpec {
+	return policy.KeySpec{Key: Key, Owner: pools.Owner, Kind: policy.TightenSubset, Decode: decode}
+}
+
+func decode(raw json.RawMessage) (any, error) {
+	var ids []string
+	if err := json.Unmarshal(raw, &ids); err != nil || ids == nil {
+		return nil, fmt.Errorf("expected a list of pool ids")
+	}
+	values := make([]any, 0, len(ids))
+	for _, id := range ids {
+		if !pools.ValidID(id) {
+			return nil, fmt.Errorf("invalid pool id %q", id)
+		}
+		values = append(values, id)
+	}
+	return values, nil
+}
+
+// FromPolicy reads the effective list; a malformed value is an empty set.
+func FromPolicy(eff trust.Effective) pools.List {
+	v, _, ok := eff.Value(Key)
+	if !ok {
+		return pools.List{}
+	}
+	l := pools.List{Set: true}
+	switch xs := v.(type) {
+	case []string:
+		l.IDs = slices.Clone(xs)
+	case []any:
+		for _, x := range xs {
+			id, ok := x.(string)
+			if !ok || !pools.ValidID(id) {
+				return pools.List{Set: true}
+			}
+			l.IDs = append(l.IDs, id)
+		}
+	}
+	return l
+}
+
+// Allows reports whether r may contribute to a status of record. Unset means
+// the operator's own nodes and hosted runners; TEAM membership needs a list.
+func Allows(list pools.List, r pools.Runner) bool {
+	if r.ID == "" {
+		return false
+	}
+	switch r.Source {
+	case pools.SourceLocal, pools.SourceRegistry, pools.SourceProvider:
+		if !list.Set {
+			return true
+		}
+	case pools.SourceCoordinator:
+		if !list.Set {
+			return false
+		}
+	default:
+		return false
+	}
+	return slices.ContainsFunc(pools.Memberships(r), list.Has)
+}
+
+// Excluded returns record-pool reasons without changing other placement terms.
+func Excluded(list pools.List, runners []pools.Runner) map[string][]model.PlacementReasonDetail {
+	out := map[string][]model.PlacementReasonDetail{}
+	for _, r := range runners {
+		if !Allows(list, r) {
+			out[r.ID] = []model.PlacementReasonDetail{{Code: string(model.PoolExcluded), Detail: Reason}}
+		}
+	}
+	return out
+}
diff --git a/free/ci/internal/pools/record/record_test.go b/free/ci/internal/pools/record/record_test.go
new file mode 100644
index 000000000..d5865f401
--- /dev/null
+++ b/free/ci/internal/pools/record/record_test.go
@@ -0,0 +1,98 @@
+package record
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"math/rand"
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+func TestSoloDefaultRecord(t *testing.T) {
+	for _, source := range []string{pools.SourceLocal, pools.SourceRegistry, pools.SourceProvider, pools.SourceCoordinator, ""} {
+		want := source != pools.SourceCoordinator && source != ""
+		if got := Allows(pools.List{}, pools.Runner{ID: "r", Source: source}); got != want {
+			t.Fatalf("source %q: got %v want %v", source, got, want)
+		}
+	}
+	if Allows(pools.List{Set: true}, pools.Runner{ID: "r", Source: pools.SourceLocal}) {
+		t.Fatal("an explicit empty list must deny all")
+	}
+}
+
+func TestRevisionNeverWidensRecord(t *testing.T) {
+	const seed = int64(321518)
+	rng := rand.New(rand.NewSource(seed))
+	reg, err := trust.NewRegistry(Spec())
+	if err != nil {
+		t.Fatal(err)
+	}
+	ids := []string{"local", "hosted", "mine", "team", "gpu"}
+	for n := range 1000 {
+		var project, revision []string
+		project, revision = []string{}, []string{}
+		for _, id := range ids {
+			if rng.Intn(2) == 0 {
+				project = append(project, id)
+			}
+			if rng.Intn(2) == 0 {
+				revision = append(revision, id)
+			}
+		}
+		p, _ := json.Marshal(project)
+		r, _ := json.Marshal(revision)
+		branch := trust.Scope{Kind: trust.SourceProtectedBranch, Values: map[string]json.RawMessage{Key: p}}
+		rev := trust.Scope{Kind: trust.SourceRevision, Values: map[string]json.RawMessage{Key: r}}
+		eff, _, err := reg.Merge("pinned", branch, rev)
+		if err != nil {
+			t.Fatalf("seed %d case %d: %v", seed, n, err)
+		}
+		for _, id := range FromPolicy(eff).IDs {
+			if !slices.Contains(project, id) {
+				t.Fatalf("seed %d case %d: revision added %s", seed, n, id)
+			}
+		}
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceRevision, Values: map[string]json.RawMessage{Key: json.RawMessage(`["team"]`)}})
+	if err != nil || FromPolicy(eff).Set {
+		t.Fatalf("revision supplied an unset default: %v %v", eff, err)
+	}
+}
+
+type brokenLabels struct{}
+
+func (brokenLabels) NodeLabels(context.Context, string) ([]store.NodeLabel, error) {
+	return nil, errors.New("unreadable")
+}
+
+func TestProviderUnreadableFacts(t *testing.T) {
+	w := sched.World{Runners: []sched.Runner{{ID: "local"}, {ID: "vps"}}, Hosted: []sched.Runner{{ID: "gh"}}}
+	fn := ExclusionProvider(pools.Config{Labels: brokenLabels{}}, func(context.Context) bool { return true })
+	got, err := fn(context.Background(), w)
+	if err != nil || len(got) != 3 {
+		t.Fatalf("unreadable facts must exclude every runner: %v %v", got, err)
+	}
+	for _, why := range got {
+		if why[0].Code != "pool.excluded" || why[0].Detail != Reason {
+			t.Fatal(why)
+		}
+	}
+	fn = ExclusionProvider(pools.Config{Labels: brokenLabels{}}, func(context.Context) bool { return false })
+	if got, err = fn(context.Background(), w); err != nil || len(got) != 0 {
+		t.Fatal("dev was restricted by record", got, err)
+	}
+}
+
+func TestRecordKeyDecoder(t *testing.T) {
+	for _, raw := range []string{`null`, `{}`, `["Bad"]`, `["team"] true`, `[3]`} {
+		if _, err := decode(json.RawMessage(raw)); err == nil {
+			t.Fatalf("accepted %s", raw)
+		}
+	}
+}
diff --git a/free/ci/internal/pools/resolve.go b/free/ci/internal/pools/resolve.go
new file mode 100644
index 000000000..85ad4434d
--- /dev/null
+++ b/free/ci/internal/pools/resolve.go
@@ -0,0 +1,138 @@
+package pools
+
+// Purpose: the effective pool set (AUTO D10): pools.allow ∩ the pools the person is enrolled in
+//          ∩ pools.dev (dev runs only), and for a named project ∩ the nodes whose
+//          lifecycle.authorized_projects lists it (placement already enforces that term on its own).
+// Inputs:  Input: the runners with their assigned labels, the terms, the project and the run kind.
+// Outputs: Result: the pools (contract:ci.pool v1), the eligible runner ids and, per excluded runner,
+//          one pool.excluded reason naming the first term that emptied its pools.
+// Constraints: pure. An unset term constrains nothing; a set term keeps a runner only through a pool it
+//          lists, so removing a term never shrinks the result. A runner's candidate pools only ever
+//          shrink by intersection: no union of pool sets is computed.
+
+import (
+	"slices"
+	"sort"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// Runner is one runner the resolver sees.
+type Runner struct {
+	ID       string
+	Location string
+	// Source is SourceLocal, SourceRegistry, SourceCoordinator or SourceProvider.
+	Source string
+	// Assigned holds the coordinator-assigned labels in placement form. Self-declared labels never go here.
+	Assigned []string
+	// Projects is lifecycle.authorized_projects; read only when Input.Project is set.
+	Projects []string
+}
+
+// Input is what Resolve needs.
+type Input struct {
+	Runners []Runner
+	// Allow is pools.allow; Enrolled the pools the person is enrolled in (unset: every pool they see).
+	Allow, Enrolled List
+	// Dev marks a dev run: only then does DevPools (pools.dev) apply.
+	Dev      bool
+	DevPools List
+	// Project, when set, applies the authorized_projects term.
+	Project string
+}
+
+// Result is the answer of Resolve.
+type Result struct {
+	Pools []Pool
+	// Eligible lists the runners every term keeps, sorted.
+	Eligible []string
+	// Excluded holds the pool.excluded reason of every runner a pool term drops.
+	Excluded map[string][]model.PlacementReasonDetail
+	// Unauthorized lists the runners kept by the pool terms whose authorized projects omit Input.Project.
+	Unauthorized []string
+}
+
+// Memberships returns the pool ids of one runner: its assigned `pool.<id>` labels and its implicit pool.
+func Memberships(r Runner) []string {
+	ids := FromAssigned(r.Assigned)
+	switch r.Source {
+	case SourceLocal:
+		ids = append(ids, Local)
+	case SourceProvider:
+		ids = append(ids, Hosted)
+	}
+	slices.Sort(ids)
+	return ids
+}
+
+type term struct {
+	list   List
+	detail string
+}
+
+func (in Input) terms() []term {
+	ts := []term{{in.Allow, DetailNotInProjectList}, {in.Enrolled, DetailNotEnrolled}}
+	if in.Dev {
+		ts = append(ts, term{in.DevPools, DetailDevNotAllowed})
+	}
+	return ts
+}
+
+// keep returns the pools that pass every set term and the detail of the first term that emptied them.
+func keep(ids []string, ts []term) ([]string, string) {
+	for _, t := range ts {
+		if !t.list.Set {
+			continue
+		}
+		ids = slices.DeleteFunc(slices.Clone(ids), func(id string) bool { return !t.list.Has(id) })
+		if len(ids) == 0 {
+			return nil, t.detail
+		}
+	}
+	return ids, ""
+}
+
+// Resolve computes the effective set.
+func Resolve(in Input) Result {
+	res := Result{Pools: []Pool{}, Eligible: []string{}, Excluded: map[string][]model.PlacementReasonDetail{}, Unauthorized: []string{}}
+	ts := in.terms()
+	byPool := map[string]*Pool{}
+	for _, r := range in.Runners {
+		ids := Memberships(r)
+		for _, id := range ids {
+			p := byPool[id]
+			if p == nil {
+				p = &Pool{Schema: SchemaID, ID: id, Scope: ScopeOperator, Members: []Member{}}
+				byPool[id] = p
+			}
+			p.Members = append(p.Members, Member{RunnerID: r.ID, Location: r.Location, Source: r.Source})
+			if r.Source == SourceCoordinator {
+				p.Scope = ScopeProject
+			}
+		}
+		if _, why := keep(ids, ts); why != "" {
+			res.Excluded[r.ID] = []model.PlacementReasonDetail{{Code: string(model.PoolExcluded), Detail: why}}
+			continue
+		}
+		if in.Project != "" && !slices.Contains(r.Projects, in.Project) {
+			res.Unauthorized = append(res.Unauthorized, r.ID)
+			continue
+		}
+		res.Eligible = append(res.Eligible, r.ID)
+	}
+	for id, p := range byPool {
+		if id == Hosted {
+			p.Scope = ScopeHosted
+		}
+		sort.Slice(p.Members, func(i, j int) bool { return p.Members[i].RunnerID < p.Members[j].RunnerID })
+		p.Effective = Effective{Allowed: true, Reasons: []model.PlacementReasonDetail{}}
+		if _, why := keep([]string{id}, ts); why != "" {
+			p.Effective = Effective{Reasons: []model.PlacementReasonDetail{{Code: string(model.PoolExcluded), Detail: why}}}
+		}
+		res.Pools = append(res.Pools, *p)
+	}
+	sort.Slice(res.Pools, func(i, j int) bool { return res.Pools[i].ID < res.Pools[j].ID })
+	sort.Strings(res.Eligible)
+	sort.Strings(res.Unauthorized)
+	return res
+}
diff --git a/free/ci/internal/pools/resolve_test.go b/free/ci/internal/pools/resolve_test.go
new file mode 100644
index 000000000..d3607f1aa
--- /dev/null
+++ b/free/ci/internal/pools/resolve_test.go
@@ -0,0 +1,175 @@
+package pools
+
+import (
+	"encoding/json"
+	"fmt"
+	"math/rand"
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+var propIDs = []string{"mine", "team", "ci", "gpu", Local, Hosted}
+
+func randList(rng *rand.Rand) List {
+	if rng.Intn(3) == 0 {
+		return List{}
+	}
+	l := List{Set: true, IDs: []string{}}
+	for _, id := range propIDs {
+		if rng.Intn(2) == 0 {
+			l.IDs = append(l.IDs, id)
+		}
+	}
+	return l
+}
+
+func randInput(rng *rand.Rand) Input {
+	in := Input{Allow: randList(rng), Enrolled: randList(rng), DevPools: randList(rng), Dev: rng.Intn(2) == 0}
+	if rng.Intn(2) == 0 {
+		in.Project = "p1"
+	}
+	sources := []string{SourceLocal, SourceRegistry, SourceCoordinator, SourceProvider}
+	for i := range rng.Intn(6) {
+		r := Runner{ID: fmt.Sprintf("r%d", i), Source: sources[rng.Intn(len(sources))], Location: "lan"}
+		for _, id := range propIDs {
+			if rng.Intn(3) == 0 {
+				r.Assigned = append(r.Assigned, LabelPrefix+id)
+			}
+		}
+		if rng.Intn(4) == 0 {
+			r.Assigned = append(r.Assigned, "pool.Bad_ID", "region=eu")
+		}
+		if rng.Intn(2) == 0 {
+			r.Projects = []string{"p1"}
+		}
+		in.Runners = append(in.Runners, r)
+	}
+	return in
+}
+
+// holds checks one term for one runner's remaining pools, the way the brief states the term.
+func holds(ids []string, l List) bool {
+	if !l.Set {
+		return true
+	}
+	return slices.ContainsFunc(ids, l.Has)
+}
+
+func TestResolveIntersectionProperty(t *testing.T) {
+	const seed = int64(20261027)
+	rng := rand.New(rand.NewSource(seed))
+	for n := range 10000 {
+		in := randInput(rng)
+		got := Resolve(in)
+		for _, r := range in.Runners {
+			ids := Memberships(r)
+			// every term holds on the same pool: the effective set is the intersection of the set terms.
+			var both []string
+			for _, id := range ids {
+				if holds([]string{id}, in.Allow) && holds([]string{id}, in.Enrolled) && (!in.Dev || holds([]string{id}, in.DevPools)) {
+					both = append(both, id)
+				}
+			}
+			anySet := in.Allow.Set || in.Enrolled.Set || in.Dev && in.DevPools.Set
+			want := (!anySet || len(both) > 0) && (in.Project == "" || slices.Contains(r.Projects, in.Project))
+			if slices.Contains(got.Eligible, r.ID) != want {
+				t.Fatalf("seed %d case %d: runner %s eligible=%v, want %v (input %+v)", seed, n, r.ID, !want, want, in)
+			}
+			if in.Allow.Set && slices.Contains(got.Eligible, r.ID) && !holds(ids, in.Allow) {
+				t.Fatalf("seed %d case %d: runner %s outside pools.allow is eligible", seed, n, r.ID)
+			}
+		}
+		// removing any term never shrinks the set.
+		for _, drop := range []func(*Input){func(i *Input) { i.Allow = List{} }, func(i *Input) { i.Enrolled = List{} }, func(i *Input) { i.DevPools = List{} }, func(i *Input) { i.Dev = false }, func(i *Input) { i.Project = "" }} {
+			wider := in
+			drop(&wider)
+			more := Resolve(wider).Eligible
+			for _, id := range got.Eligible {
+				if !slices.Contains(more, id) {
+					t.Fatalf("seed %d case %d: removing a term dropped runner %s", seed, n, id)
+				}
+			}
+		}
+	}
+}
+
+func TestSelfDeclaredLabelIgnored(t *testing.T) {
+	if got := FromAssigned([]string{"pool.team", "pool.local", "pool.hosted", "pool.Bad", "pools.x", "team", "pool.ci=yes", "pool.team"}); !slices.Equal(got, []string{"ci", "team"}) {
+		t.Fatalf("FromAssigned = %v", got)
+	}
+	in := Input{Allow: List{Set: true, IDs: []string{"team"}}, Runners: []Runner{{ID: "vps", Source: SourceRegistry}}}
+	got := Resolve(in)
+	if len(got.Eligible) != 0 || got.Excluded["vps"][0].Detail != DetailNotInProjectList {
+		t.Fatalf("an unlabelled node joined pool team: %+v", got)
+	}
+}
+
+func TestImplicitPools(t *testing.T) {
+	in := Input{Runners: []Runner{{ID: "local", Source: SourceLocal, Location: "local"}, {ID: "gh-ubuntu", Source: SourceProvider, Location: "hosted"}}}
+	got := Resolve(in)
+	if len(got.Pools) != 2 || got.Pools[0].ID != Hosted || got.Pools[0].Scope != ScopeHosted || got.Pools[1].ID != Local || got.Pools[1].Scope != ScopeOperator {
+		t.Fatalf("implicit pools = %+v", got.Pools)
+	}
+	in.Allow = List{Set: true, IDs: []string{Local}}
+	got = Resolve(in)
+	if !slices.Equal(got.Eligible, []string{"local"}) || got.Excluded["gh-ubuntu"][0].Code != string(model.PoolExcluded) {
+		t.Fatalf("allow [local]: %+v", got)
+	}
+	in.Dev, in.DevPools = true, List{Set: true, IDs: []string{Hosted}}
+	if got = Resolve(in); got.Excluded["local"][0].Detail != DetailDevNotAllowed {
+		t.Fatalf("dev run on hosted only: %+v", got.Excluded)
+	}
+}
+
+// TestVPSAndTeamFixture is the brief's fixture: a personal VPS in pool mine and a team coordinator pool team.
+func TestVPSAndTeamFixture(t *testing.T) {
+	runners := []Runner{{ID: "vps", Source: SourceRegistry, Location: "remote", Assigned: []string{"pool.mine"}},
+		{ID: "t1", Source: SourceCoordinator, Location: "lan", Assigned: []string{"pool.team"}}}
+	got := Resolve(Input{Runners: runners, Allow: List{Set: true, IDs: []string{"team"}}})
+	if !slices.Equal(got.Eligible, []string{"t1"}) || got.Excluded["vps"][0].Detail != DetailNotInProjectList {
+		t.Fatalf("project listing team: %+v", got)
+	}
+	if got = Resolve(Input{Runners: runners}); !slices.Equal(got.Eligible, []string{"t1", "vps"}) {
+		t.Fatalf("solo default: %+v", got)
+	}
+	if got.Pools[0].ID != "mine" || got.Pools[0].Scope != ScopeOperator || got.Pools[1].Scope != ScopeProject {
+		t.Fatalf("derived scopes: %+v", got.Pools)
+	}
+}
+
+func TestRevisionOnlyTightens(t *testing.T) {
+	reg, err := trust.NewRegistry(Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	branch := trust.Scope{Kind: trust.SourceProtectedBranch, Values: map[string]json.RawMessage{KeyAllow: json.RawMessage(`["team","mine"]`)}}
+	merge := func(rev string) (List, []string) {
+		t.Helper()
+		eff, _, err := reg.Merge("", branch, trust.Scope{Kind: trust.SourceRevision, Values: map[string]json.RawMessage{KeyAllow: json.RawMessage(rev)}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		allow, _, notes := FromPolicy(eff)
+		return allow, notes
+	}
+	if allow, notes := merge(`["team"]`); !slices.Equal(allow.IDs, []string{"team"}) || len(notes) != 0 {
+		t.Fatalf("shrinking revision: %+v %v", allow, notes)
+	}
+	allow, notes := merge(`["team","mine","gpu"]`)
+	if !slices.Equal(allow.IDs, []string{"mine", "team"}) || len(notes) != 1 {
+		t.Fatalf("widening revision applied or unreported: %+v %v", allow, notes)
+	}
+	if _, _, err = reg.Merge("", trust.Scope{Kind: trust.SourceProtectedBranch, Values: map[string]json.RawMessage{KeyAllow: json.RawMessage(`["Bad"]`)}}); err == nil {
+		t.Fatal("a malformed pool id was accepted")
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceRevision, Values: map[string]json.RawMessage{KeyDev: json.RawMessage(`["local"]`)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, dev, notes := FromPolicy(eff); dev.Set || len(notes) == 0 {
+		t.Fatalf("pools.dev from a revision applied: %+v %v", dev, notes)
+	}
+}
diff --git a/free/ci/internal/pools/testdata/pools.golden.json b/free/ci/internal/pools/testdata/pools.golden.json
new file mode 100644
index 000000000..4a6d1db5c
--- /dev/null
+++ b/free/ci/internal/pools/testdata/pools.golden.json
@@ -0,0 +1,81 @@
+[
+  {
+    "schema": "ci.pool/v1",
+    "id": "hosted",
+    "scope": "hosted",
+    "members": [
+      {
+        "runner_id": "gh-ubuntu",
+        "location": "hosted",
+        "source": "provider"
+      }
+    ],
+    "effective": {
+      "allowed": false,
+      "reasons": [
+        {
+          "code": "pool.excluded",
+          "detail": "not_in_project_list"
+        }
+      ]
+    }
+  },
+  {
+    "schema": "ci.pool/v1",
+    "id": "local",
+    "scope": "operator",
+    "members": [
+      {
+        "runner_id": "local",
+        "location": "local",
+        "source": "local"
+      }
+    ],
+    "effective": {
+      "allowed": true,
+      "reasons": []
+    }
+  },
+  {
+    "schema": "ci.pool/v1",
+    "id": "mine",
+    "scope": "operator",
+    "members": [
+      {
+        "runner_id": "local",
+        "location": "local",
+        "source": "local"
+      },
+      {
+        "runner_id": "vps",
+        "location": "remote",
+        "source": "registry"
+      }
+    ],
+    "effective": {
+      "allowed": false,
+      "reasons": [
+        {
+          "code": "pool.excluded",
+          "detail": "not_in_project_list"
+        }
+      ]
+    }
+  },
+  {
+    "schema": "ci.pool/v1",
+    "id": "team",
+    "scope": "project",
+    "members": [
+      {
+        "runner_id": "t1",
+        "location": "lan",
+        "source": "coordinator"
+      }
+    ],
+    "effective": {
+      "allowed": true,
+      "reasons": []
+    }
+  }
+]
diff --git a/free/ci/internal/preflight/licensed.go b/free/ci/internal/preflight/licensed.go
new file mode 100644
index 000000000..bb8735aae
--- /dev/null
+++ b/free/ci/internal/preflight/licensed.go
@@ -0,0 +1,106 @@
+// Package preflight holds the pure-Go classification of the licensed
+// served-bytes preflight (P7-PLUG-39); scripts/preflight/licensed.sh is the
+// operator wrapper. No exec, no environment reads beyond the caller's key.
+package preflight
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+)
+
+// Entry is one licensed registry entry.
+type Entry struct{ Slug, Version, Checksum string }
+
+// Result is the per-entry outcome: Result is pass|fail|skip, Class names the stage.
+type Result struct{ Slug, Result, Class, Reason string }
+
+// Summary counts results. Pass is true only when every expected entry passed.
+type Summary struct {
+	Expected, Pass, Fail, Skip int
+	ByClass                    map[string]int
+	OK                         bool
+}
+
+// ErrNoKey is returned when the CI licence is absent (strict mode needs it).
+var ErrNoKey = errors.New("CI licence key is not set")
+
+// Check downloads every entry from base/plugins/<slug>/download. The key goes
+// only on the first hop; a redirect target gets a plain GET. Results are sorted by slug.
+func Check(c *http.Client, base, key string, entries []Entry) ([]Result, error) {
+	if key == "" {
+		return nil, ErrNoKey
+	}
+	nc := *c
+	nc.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
+	out := make([]Result, 0, len(entries))
+	for _, e := range entries {
+		out = append(out, checkOne(&nc, base, key, e))
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Slug < out[j].Slug })
+	return out, nil
+}
+
+func checkOne(c *http.Client, base, key string, e Entry) Result {
+	r := func(res, cls, why string) Result { return Result{e.Slug, res, cls, why} }
+	req, err := http.NewRequest(http.MethodGet, base+"/plugins/"+e.Slug+"/download", nil)
+	if err != nil {
+		return r("fail", "404", "bad request URL")
+	}
+	req.Header.Set("X-License-Key", key)
+	resp, err := c.Do(req)
+	if err != nil {
+		return r("fail", "404", "transport failure")
+	}
+	if resp.StatusCode/100 == 3 {
+		loc, lerr := resp.Location()
+		resp.Body.Close()
+		if lerr != nil {
+			return r("fail", "404", fmt.Sprintf("HTTP %d without Location", resp.StatusCode))
+		}
+		if resp, err = c.Get(loc.String()); err != nil {
+			return r("fail", "404", "redirect target transport failure")
+		}
+	}
+	defer resp.Body.Close()
+	switch resp.StatusCode {
+	case http.StatusOK:
+	case http.StatusUnauthorized, http.StatusForbidden:
+		return r("fail", "entitlement", fmt.Sprintf("CI licence rejected (HTTP %d) for an entry it should cover", resp.StatusCode))
+	default:
+		return r("fail", "404", fmt.Sprintf("download answered HTTP %d", resp.StatusCode))
+	}
+	h := sha256.New()
+	if _, err := io.Copy(h, resp.Body); err != nil {
+		return r("fail", "404", "body read failed")
+	}
+	if got := hex.EncodeToString(h.Sum(nil)); got != e.Checksum {
+		return r("fail", "checksum", "served sha256 differs from the registry")
+	}
+	// Extraction, manifest and docker build are the wrapper's stages: a skip is not a pass.
+	return r("skip", "build", "bytes verified; build stage not run here")
+}
+
+// Summarize counts results against the expected entry total.
+func Summarize(expected int, rs []Result) Summary {
+	s := Summary{Expected: expected, ByClass: map[string]int{}}
+	for _, x := range rs {
+		switch x.Result {
+		case "pass":
+			s.Pass++
+		case "skip":
+			s.Skip++
+		default:
+			s.Fail++
+		}
+		if x.Result != "pass" {
+			s.ByClass[x.Class]++
+		}
+	}
+	s.OK = expected > 0 && len(rs) == expected && s.Pass == expected
+	return s
+}
diff --git a/free/ci/internal/preflight/licensed_test.go b/free/ci/internal/preflight/licensed_test.go
new file mode 100644
index 000000000..35feb6279
--- /dev/null
+++ b/free/ci/internal/preflight/licensed_test.go
@@ -0,0 +1,76 @@
+package preflight
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+const testLicence = "ci-test-licence-token"
+
+func TestCheckClassifiesEveryEntry(t *testing.T) {
+	body := []byte("tarball bytes")
+	sum := sha256.Sum256(body)
+	good := hex.EncodeToString(sum[:])
+	var keyOnFile bool
+	mux := http.NewServeMux()
+	mux.HandleFunc("/plugins/alpha/download", func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-License-Key") != testLicence {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		http.Redirect(w, r, "/files/alpha.tgz", http.StatusFound)
+	})
+	mux.HandleFunc("/files/alpha.tgz", func(w http.ResponseWriter, r *http.Request) {
+		keyOnFile = keyOnFile || r.Header.Get("X-License-Key") != ""
+		_, _ = w.Write(body)
+	})
+	mux.HandleFunc("/plugins/beta/download", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(403) })
+	mux.HandleFunc("/plugins/gamma/download", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(404) })
+	mux.HandleFunc("/plugins/delta/download", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write(body) })
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	entries := []Entry{{"gamma", "1", good}, {"alpha", "1", good}, {"beta", "1", good}, {"delta", "1", strings.Repeat("0", 64)}}
+	rs, err := Check(srv.Client(), srv.URL, testLicence, entries)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][2]string{"alpha": {"skip", "build"}, "beta": {"fail", "entitlement"}, "gamma": {"fail", "404"}, "delta": {"fail", "checksum"}}
+	for _, x := range rs {
+		if w := want[x.Slug]; x.Result != w[0] || x.Class != w[1] {
+			t.Errorf("%s: got %s/%s, want %v", x.Slug, x.Result, x.Class, w)
+		}
+		if strings.Contains(x.Reason, testLicence) {
+			t.Errorf("%s: key in reason", x.Slug)
+		}
+	}
+	if rs[0].Slug != "alpha" {
+		t.Errorf("results not sorted: %v", rs[0].Slug)
+	}
+	if keyOnFile {
+		t.Error("key sent to redirect target")
+	}
+	s := Summarize(len(entries), rs)
+	if s.OK || s.Skip != 1 || s.Fail != 3 || s.ByClass["entitlement"] != 1 {
+		t.Errorf("summary wrong: %+v", s)
+	}
+	if Summarize(len(entries)+1, rs).OK {
+		t.Error("missing entry must fail coverage")
+	}
+}
+
+func TestCheckNeedsKey(t *testing.T) {
+	if _, err := Check(http.DefaultClient, "http://127.0.0.1:1", "", []Entry{{"a", "1", "x"}}); err != ErrNoKey {
+		t.Fatalf("got %v, want ErrNoKey", err)
+	}
+}
+
+func TestSummarizePass(t *testing.T) {
+	if !Summarize(1, []Result{{"a", "pass", "", ""}}).OK || Summarize(0, nil).OK {
+		t.Error("pass/empty handling wrong")
+	}
+}
diff --git a/free/ci/internal/providers/github/reconcile/scan_conditional_test.go b/free/ci/internal/providers/github/reconcile/scan_conditional_test.go
new file mode 100644
index 000000000..e668d1c08
--- /dev/null
+++ b/free/ci/internal/providers/github/reconcile/scan_conditional_test.go
@@ -0,0 +1,58 @@
+package reconcile
+
+// Purpose: P7-AUTO-11 conditional requests on the head scan: once a full scan has
+// stored its ETags, an unchanged repository answers 304 on the repository, the pull
+// list and (with extra branches) the branch list, and ScanHeads makes no further
+// request; a changed pull list is read in full again.
+// Inputs: the HOST-17 fixture forge and engine rig. Outputs: pass or fail.
+// Constraints: loopback TLS only; synthetic names and shas.
+
+import (
+	"context"
+	"testing"
+)
+
+func TestScanHeadsConditional(t *testing.T) {
+	ctx := context.Background()
+	r := newRig(t, "o/r")
+	r.f.do(func() { r.f.repos["o/r"].Pulls = []fPull{{Number: 7, Head: sha('b', 7), Assoc: "OWNER"}} })
+	opts := []ScanOptions{{}, {Branches: []string{"release/*"}, MaxBranches: 5}}
+	for _, o := range opts {
+		first, err := r.e.ScanHeads(ctx, "o/r", o)
+		if err != nil || first.NotModified || len(first.Heads) == 0 {
+			t.Fatalf("the first scan must list the heads: %+v %v", first, err)
+		}
+		r.f.reset()
+		again, err := r.e.ScanHeads(ctx, "o/r", o)
+		if err != nil || !again.NotModified || len(again.Heads) != 0 {
+			t.Fatalf("an unchanged repository must answer NotModified: %+v %v", again, err)
+		}
+		want := 2 // the repository and the pull list
+		if len(o.Branches) > 0 {
+			want = 3 // and the branch list
+		}
+		if n := r.f.total(); n != want || r.f.nonCond304() != 0 || again.Calls != want {
+			t.Fatalf("a 304 pass must make exactly %d conditional requests: total=%d non-304=%d calls=%d", want, n, r.f.nonCond304(), again.Calls)
+		}
+		if r.f.count(func(q reqRec) bool { return !q.Cond }) != 0 {
+			t.Fatal("every repeated read must be conditional")
+		}
+	}
+
+	// A new pull request changes the list: the scan reads it and reports the new head.
+	r.f.do(func() {
+		r.f.repos["o/r"].Pulls = append(r.f.repos["o/r"].Pulls, fPull{Number: 8, Head: sha('c', 8), Assoc: "OWNER"})
+	})
+	r.f.reset()
+	changed, err := r.e.ScanHeads(ctx, "o/r", ScanOptions{})
+	if err != nil || changed.NotModified {
+		t.Fatalf("a changed pull list must not be NotModified: %+v %v", changed, err)
+	}
+	found := false
+	for _, h := range changed.Heads {
+		found = found || h.PR == 8
+	}
+	if !found {
+		t.Fatalf("the new pull request head is missing: %+v", changed.Heads)
+	}
+}
diff --git a/free/ci/internal/providers/github/reconcile/scan_export.go b/free/ci/internal/providers/github/reconcile/scan_export.go
new file mode 100644
index 000000000..a5a414b35
--- /dev/null
+++ b/free/ci/internal/providers/github/reconcile/scan_export.go
@@ -0,0 +1,203 @@
+package reconcile
+
+// Purpose: the head scan as a library call (P7-AUTO-11): `nself ci serve watch` discovers its candidate
+// heads through the same budgeted, quota-aware and conditional GitHub reads as the sweep, without a
+// coordinator Enqueuer.
+// Inputs:  a repository and ScanOptions (the operator's watch.branches globs, watch.max_branches and the
+//          watch.branch_days cut-off); the Engine's client, store and clock.
+// Outputs: HeadScan: the default and protected branch heads, the open pull request heads and the selected
+//          extra branch heads, each with the trigger facts the sweep would enqueue; NotModified when every
+//          conditional read answered 304.
+// Constraints: the ETags live under their own keys ("watch:*"), so the watcher and the sweep never consume
+//          each other's 304s; a pass that answers 304 on the repository, the pull list and (when extra
+//          branches are configured) the branch list makes no further request; ETags are stored only after
+//          a complete scan; a quota error is *QuotaStop with the recorded reset time; no status is read and
+//          nothing is enqueued here.
+
+import (
+	"context"
+	"net/url"
+	"path"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// ScanOptions selects the extra branch heads of ScanHeads.
+type ScanOptions struct {
+	Branches    []string  // names or path.Match globs (watch.branches); empty: no extra branches
+	MaxBranches int       // at most this many extra heads (watch.max_branches)
+	Since       time.Time // only extra heads whose commit is newer (watch.branch_days); zero: any age
+}
+
+// Head is one candidate head of a repository.
+type Head struct {
+	SHA       string
+	Branch    string // the branch of a branch head; "" for a pull request
+	Default   bool   // the head of the default branch
+	Protected bool
+	Extra     bool // selected through ScanOptions.Branches
+	PR        int  // the pull request number; 0 for a branch head
+	// Fork is true for a pull request whose head repository is not this one, or is unknown (a deleted fork).
+	Fork              bool
+	AuthorAssociation string
+	CommittedAt       time.Time // known for extra branch heads only
+	Facts             model.TriggerFacts
+}
+
+// HeadScan is the result of one ScanHeads call.
+type HeadScan struct {
+	Heads         []Head
+	NotModified   bool // every conditional read answered 304: the previous heads still stand
+	DefaultBranch string
+	Calls         int // requests made, 304s included
+}
+
+type ghCommit struct {
+	Commit struct {
+		Committer struct {
+			Date time.Time `json:"date"`
+		} `json:"committer"`
+	} `json:"commit"`
+}
+
+// ScanHeads lists the candidate heads of repo for the watcher.
+// The result is named so the deferred call count reaches the caller on every return.
+func (e *Engine) ScanHeads(ctx context.Context, repo string, o ScanOptions) (res HeadScan, err error) {
+	s, err := e.session(ctx, kindScan, e.passLimit())
+	if err != nil {
+		return res, err
+	}
+	defer func() { res.Calls = s.used; _ = e.flush(ctx) }()
+	params := repoParams(repo)
+	tags := map[string]string{}
+	for _, k := range []string{"watch:repo", "watch:pulls", "watch:branches"} {
+		if tags[k], err = e.etag(ctx, repo, k); err != nil {
+			return res, err
+		}
+	}
+	var info repoInfo
+	rr, err := s.get(ctx, "/repos/{owner}/{repo}", params, nil, tags["watch:repo"], &info)
+	if err != nil {
+		return res, err
+	}
+	if rr.Status == 304 {
+		if ok, gerr := e.getFact(ctx, repo, "repoinfo", &info); gerr != nil || !ok {
+			if rr, err = s.get(ctx, "/repos/{owner}/{repo}", params, nil, "", &info); err != nil {
+				return res, err
+			}
+		}
+	}
+	if rr.Status != 304 {
+		if err = e.checkIdentity(ctx, repo, info.ID, info.FullName); err != nil {
+			return res, err
+		}
+		if err = e.putFact(ctx, repo, "repoinfo", info); err != nil {
+			return res, err
+		}
+	}
+	res.DefaultBranch = info.DefaultBranch
+	var pulls []pullInfo
+	pr, err := s.get(ctx, "/repos/{owner}/{repo}/pulls", params, url.Values{"state": {"open"}, "per_page": {"100"}, "sort": {"updated"}, "direction": {"desc"}}, tags["watch:pulls"], &pulls)
+	if err != nil {
+		return res, err
+	}
+	var all []ghBranch
+	br := pr
+	if len(o.Branches) > 0 {
+		if br, err = s.get(ctx, "/repos/{owner}/{repo}/branches", params, url.Values{"per_page": {"100"}}, tags["watch:branches"], &all); err != nil {
+			return res, err
+		}
+	}
+	if rr.Status == 304 && pr.Status == 304 && br.Status == 304 {
+		res.NotModified = true
+		return res, nil
+	}
+	if pr.Status == 304 { // the list did not change but the heads are needed again: read it in full
+		if pr, err = s.get(ctx, "/repos/{owner}/{repo}/pulls", params, url.Values{"state": {"open"}, "per_page": {"100"}, "sort": {"updated"}, "direction": {"desc"}}, "", &pulls); err != nil {
+			return res, err
+		}
+	}
+	if len(o.Branches) > 0 && br.Status == 304 {
+		if br, err = s.get(ctx, "/repos/{owner}/{repo}/branches", params, url.Values{"per_page": {"100"}}, "", &all); err != nil {
+			return res, err
+		}
+	}
+	heads, err := e.branchHeads(ctx, s, params, info)
+	if err != nil {
+		return res, err
+	}
+	now := e.now()
+	seen := map[string]bool{}
+	for _, h := range heads {
+		seen[h.Branch] = true
+		res.Heads = append(res.Heads, Head{SHA: h.SHA, Branch: h.Branch, Default: h.Branch == info.DefaultBranch, Protected: h.Protected, Facts: headFacts(repo, info, h, now)})
+	}
+	for i := range pulls {
+		if i >= MaxPRs {
+			break
+		}
+		p := pulls[i]
+		if len(p.Head.SHA) != 40 {
+			continue
+		}
+		fork := p.Head.Repo == nil || p.Head.Repo.ID == 0 || info.ID == 0 || p.Head.Repo.ID != info.ID
+		res.Heads = append(res.Heads, Head{SHA: p.Head.SHA, PR: p.Number, Fork: fork, AuthorAssociation: p.AuthorAssociation, Facts: headFacts(repo, info, head{SHA: p.Head.SHA, PR: &p}, now)})
+	}
+	extra, err := e.extraHeads(ctx, s, repo, info, all, seen, o)
+	if err != nil {
+		return res, err
+	}
+	res.Heads = append(res.Heads, extra...)
+	if err = e.setEtag(ctx, repo, "watch:repo", rr.ETag); err != nil {
+		return res, err
+	}
+	if err = e.setEtag(ctx, repo, "watch:pulls", pr.ETag); err != nil {
+		return res, err
+	}
+	if len(o.Branches) > 0 {
+		err = e.setEtag(ctx, repo, "watch:branches", br.ETag)
+	}
+	return res, err
+}
+
+// extraHeads resolves the operator's branch globs against the branch listing: at most MaxBranches heads,
+// each newer than Since (one commit read per matched branch).
+func (e *Engine) extraHeads(ctx context.Context, s *session, repo string, info repoInfo, all []ghBranch, seen map[string]bool, o ScanOptions) ([]Head, error) {
+	var out []Head
+	now := e.now()
+	for _, b := range all {
+		if len(out) >= o.MaxBranches {
+			break
+		}
+		if seen[b.Name] || len(b.Commit.SHA) != 40 || !matchAny(o.Branches, b.Name) {
+			continue
+		}
+		var c ghCommit
+		p := repoParams(repo)
+		p["sha"] = b.Commit.SHA
+		if _, err := s.get(ctx, "/repos/{owner}/{repo}/commits/{sha}", p, nil, "", &c); err != nil {
+			return nil, err
+		}
+		at := c.Commit.Committer.Date
+		if !o.Since.IsZero() && !at.After(o.Since) {
+			continue
+		}
+		h := head{SHA: b.Commit.SHA, Branch: b.Name, Protected: b.Protected}
+		out = append(out, Head{SHA: h.SHA, Branch: h.Branch, Protected: h.Protected, Extra: true, CommittedAt: at, Facts: headFacts(repo, info, h, now)})
+	}
+	return out, nil
+}
+
+// matchAny reports whether name equals a pattern or matches it as a path.Match glob.
+func matchAny(patterns []string, name string) bool {
+	for _, p := range patterns {
+		if p == name {
+			return true
+		}
+		if ok, err := path.Match(p, name); err == nil && ok {
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/internal/race/attempts.go b/free/ci/internal/race/attempts.go
new file mode 100644
index 000000000..a206e28e6
--- /dev/null
+++ b/free/ci/internal/race/attempts.go
@@ -0,0 +1,69 @@
+package race
+
+// Purpose: Attempts backed by the run store: siblings are made by
+// run.CreateAttempt (through run.RaceAttempts), stopped by the epoch-fenced
+// lease cancel intent and awaited by reading their state.
+// Inputs:  a context holding the run Session.
+// Outputs: Sibling values and their final Result.
+// Constraints: Wait only reads; it returns when the attempt is terminal or
+// the context is done (then the result is a cancel). The poll clock is
+// injected so tests never sleep.
+
+import (
+	"context"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/run"
+)
+
+// DefaultPoll is how often Wait reads a sibling's state.
+const DefaultPoll = 100 * time.Millisecond
+
+// StoreAttempts implements Attempts on the run store.
+type StoreAttempts struct {
+	RA run.RaceAttempts
+	// Tick returns the channel Wait reads between polls (nil: a DefaultPoll ticker).
+	Tick func() (<-chan time.Time, func())
+}
+
+// Create implements Attempts.
+func (s StoreAttempts) Create(ctx context.Context, n int, runner string) (Sibling, error) {
+	rs, err := s.RA.Create(ctx, n, runner)
+	if err != nil {
+		return Sibling{}, err
+	}
+	return Sibling{N: rs.N, AttemptID: rs.AttemptID, LeaseID: rs.LeaseID, RunnerID: rs.RunnerID, Epoch: rs.Epoch}, nil
+}
+
+// Cancel implements Attempts.
+func (s StoreAttempts) Cancel(ctx context.Context, sib Sibling, reason string) error {
+	return s.RA.Cancel(ctx, sib.AttemptID, sib.Epoch, reason)
+}
+
+// Wait implements Attempts.
+func (s StoreAttempts) Wait(ctx context.Context, sib Sibling) Result {
+	tick, stop := s.ticker()
+	defer stop()
+	for {
+		state, class, err := s.RA.State(context.WithoutCancel(ctx), sib.AttemptID)
+		if err == nil {
+			switch state {
+			case StatePassed, StateFailed, StateCancelled, "lost", "needs-operator":
+				return Result{State: state, FailureClass: class}
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return Result{State: StateCancelled, FailureClass: StateCancelled}
+		case <-tick:
+		}
+	}
+}
+
+func (s StoreAttempts) ticker() (<-chan time.Time, func()) {
+	if s.Tick != nil {
+		return s.Tick()
+	}
+	t := time.NewTicker(DefaultPoll)
+	return t.C, t.Stop
+}
diff --git a/free/ci/internal/race/hook.go b/free/ci/internal/race/hook.go
new file mode 100644
index 000000000..cea2ea30a
--- /dev/null
+++ b/free/ci/internal/race/hook.go
@@ -0,0 +1,105 @@
+package race
+
+// Purpose: fill the RaceHook slot P7-AUTO-06 leaves nil, so `--where all` is
+// accepted once this package is linked, and drive a race for one job of a run.
+// Inputs:  run.RaceRequest (run id, options, plan) before the jobs start;
+// for RaceJob, the session context, the job's placement world and request.
+// Outputs: the per-run race plan (which jobs race, which do not and why) and,
+// per raced job, the one posted Evidence.
+// Constraints: the hook never fails a run: a run it cannot race runs one
+// attempt per job. A release-class or idempotent:false job is never raced.
+// The width is the resolved sched.race.width of the placement world.
+
+import (
+	"context"
+	"sync"
+
+	"github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+// Planned says whether one job of a run races.
+type Planned struct {
+	JobID  string
+	Raced  bool
+	Reason string // why not, when Raced is false
+}
+
+// Hook is the run.RaceHook of this package.
+type Hook struct {
+	// Enabled says the run asked for a race (`--where all`); nil: the run's
+	// policy values carry sched.race.width.
+	Enabled func(run.RaceRequest) bool
+
+	mu    sync.Mutex
+	plans map[string][]Planned
+}
+
+// Default is the hook init() registers.
+var Default = &Hook{}
+
+func init() { run.RegisterRace(Default) }
+
+func (h *Hook) enabled(r run.RaceRequest) bool {
+	if h.Enabled != nil {
+		return h.Enabled(r)
+	}
+	_, ok := r.Opts.PolicyRun[KeyWidth]
+	return ok
+}
+
+// Race implements run.RaceHook: it records which jobs of the run may race.
+func (h *Hook) Race(_ context.Context, r run.RaceRequest) {
+	if r.Plan == nil || !h.enabled(r) {
+		return
+	}
+	plans := make([]Planned, 0, len(r.Plan.Jobs))
+	for i := range r.Plan.Jobs {
+		pj := &r.Plan.Jobs[i]
+		p := Planned{JobID: pj.ID, Raced: run.Raceable(&pj.Job)}
+		if !p.Raced {
+			p.Reason = ReasonRelease
+		}
+		plans = append(plans, p)
+	}
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.plans == nil {
+		h.plans = map[string][]Planned{}
+	}
+	h.plans[r.RunID] = plans
+}
+
+// Planned returns the race plan of a run (nil: the run does not race).
+func (h *Hook) Planned(runID string) []Planned {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return append([]Planned(nil), h.plans[runID]...)
+}
+
+// Raced says the job of the run races.
+func (h *Hook) Raced(runID, jobID string) bool {
+	for _, p := range h.Planned(runID) {
+		if p.JobID == jobID {
+			return p.Raced
+		}
+	}
+	return false
+}
+
+// Forget drops the plan of a finished run.
+func (h *Hook) Forget(runID string) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	delete(h.plans, runID)
+}
+
+// RaceJob races one job: it selects distinct eligible runners from w for the
+// placement request j, then runs the race through run.CreateAttempt. ctx must
+// hold the run Session. ErrNotRaced means: run one attempt instead.
+func RaceJob(ctx context.Context, spec run.AttemptSpec, w sched.World, j sched.Job, p Poster) (Evidence, error) {
+	ra := run.RaceAttempts{Spec: spec}
+	release := !run.Raceable(spec.Job)
+	c := Select(w, j, Width(w.Policy.Trust), release)
+	return Run(ctx, Spec{Job: j.Key, Choice: c, First: max(spec.N, 1)}, StoreAttempts{RA: ra}, p)
+}
diff --git a/free/ci/internal/race/hook_test.go b/free/ci/internal/race/hook_test.go
new file mode 100644
index 000000000..f931f75ef
--- /dev/null
+++ b/free/ci/internal/race/hook_test.go
@@ -0,0 +1,53 @@
+package race
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/plan"
+	"github.com/nself-org/plugins/free/ci/internal/run"
+)
+
+func TestHookRegistered(t *testing.T) {
+	if !run.RaceRegistered() {
+		t.Fatal("init did not register the race hook")
+	}
+}
+
+func TestHookPlansRaces(t *testing.T) {
+	no := false
+	p := &plan.Plan{Jobs: []plan.PlannedJob{
+		{ID: "test", Job: model.Job{}},
+		{ID: "ship", Job: model.Job{Kind: "release"}},
+		{ID: "once", Job: model.Job{Idempotent: &no}},
+	}}
+	h := &Hook{}
+	h.Race(context.Background(), run.RaceRequest{RunID: "r1", Plan: p})
+	if h.Planned("r1") != nil {
+		t.Fatal("a run without sched.race.width raced")
+	}
+	opts := run.Options{PolicyRun: run.RunValues{KeyWidth: json.RawMessage("2")}}
+	h.Race(context.Background(), run.RaceRequest{RunID: "r1", Opts: opts, Plan: p})
+	if !h.Raced("r1", "test") || h.Raced("r1", "ship") || h.Raced("r1", "once") || h.Raced("r1", "missing") {
+		t.Fatalf("plan = %+v", h.Planned("r1"))
+	}
+	h.Forget("r1")
+	if h.Planned("r1") != nil {
+		t.Fatal("Forget kept the plan")
+	}
+	h = &Hook{Enabled: func(run.RaceRequest) bool { return true }}
+	h.Race(context.Background(), run.RaceRequest{RunID: "r2", Plan: p})
+	if !h.Raced("r2", "test") {
+		t.Fatal("Enabled was ignored")
+	}
+}
+
+func TestRaceJobRefusesRelease(t *testing.T) {
+	spec := run.AttemptSpec{Job: &model.Job{Kind: "release"}, N: 1}
+	_, err := RaceJob(context.Background(), spec, world(runner("a", "lan", "owned", 1), runner("b", "lan", "owned", 1)), job(), &fakePoster{})
+	if err == nil {
+		t.Fatal("a release job was raced")
+	}
+}
diff --git a/free/ci/internal/race/policy.go b/free/ci/internal/race/policy.go
new file mode 100644
index 000000000..a38a8224e
--- /dev/null
+++ b/free/ci/internal/race/policy.go
@@ -0,0 +1,97 @@
+// Package race runs sibling attempts of one job on distinct eligible runners
+// (P7-AUTO-14, `--where all`). The first conclusive result stands; the other
+// siblings are cancelled and never post.
+//
+// Purpose: this file owns the operator key sched.race.width: how many
+// siblings one raced job may have.
+// Inputs:  the resolved policy of the run (trust.Effective).
+// Outputs: Width, the bound the selection applies.
+// Constraints: TightenLower, default 2: a project or a run may only lower the
+// width the operator allows; a value below 1 is refused at decode time.
+package race
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"slices"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// KeyWidth bounds the number of siblings of one raced job.
+const KeyWidth = "sched.race.width"
+
+// DefaultWidth is the registered default of KeyWidth.
+const DefaultWidth = 2
+
+// MaxWidth caps KeyWidth whatever the operator sets.
+const MaxWidth = 16
+
+// Owner is the owner recorded on the key this package registers.
+const Owner = "sched"
+
+var registrationErrors []error
+
+// RegistrationErrors returns what init() could not register.
+func RegistrationErrors() []error { return slices.Clone(registrationErrors) }
+
+func init() {
+	for _, spec := range Keys() {
+		if err := policy.RegisterKey(spec); err != nil {
+			registrationErrors = append(registrationErrors, err)
+		}
+	}
+}
+
+// Keys returns the spec of the race key.
+func Keys() []policy.KeySpec {
+	return []policy.KeySpec{{Key: KeyWidth, Owner: Owner, Kind: policy.TightenLower, Default: int64(DefaultWidth), Decode: decodeWidth}}
+}
+
+// decodeWidth accepts a whole number from 1 to MaxWidth.
+func decodeWidth(raw json.RawMessage) (any, error) {
+	d := json.NewDecoder(bytes.NewReader(raw))
+	d.UseNumber()
+	var v any
+	if err := d.Decode(&v); err != nil {
+		return nil, fmt.Errorf("%s: %v", KeyWidth, err)
+	}
+	if d.More() {
+		return nil, fmt.Errorf("%s: trailing JSON value", KeyWidth)
+	}
+	n, ok := v.(json.Number)
+	if !ok {
+		return nil, fmt.Errorf("%s: expected a whole number of siblings", KeyWidth)
+	}
+	i, err := n.Int64()
+	if err != nil || i < 1 || i > MaxWidth {
+		return nil, fmt.Errorf("%s: expected a whole number from 1 to %d, got %s", KeyWidth, MaxWidth, n)
+	}
+	return i, nil
+}
+
+// Width is the effective sched.race.width of a resolved policy: the default
+// when the key is unset or holds a value of the wrong type, never above MaxWidth.
+func Width(e trust.Effective) int {
+	v, _, ok := e.Value(KeyWidth)
+	if !ok {
+		return DefaultWidth
+	}
+	var n int64
+	switch x := v.(type) {
+	case int64:
+		n = x
+	case int:
+		n = int64(x)
+	case json.Number:
+		var err error
+		if n, err = x.Int64(); err != nil {
+			return DefaultWidth
+		}
+	default:
+		return DefaultWidth
+	}
+	return int(min(max(n, 1), MaxWidth))
+}
diff --git a/free/ci/internal/race/race.go b/free/ci/internal/race/race.go
new file mode 100644
index 000000000..8ed07b91b
--- /dev/null
+++ b/free/ci/internal/race/race.go
@@ -0,0 +1,157 @@
+package race
+
+// Purpose: drive one race. Every sibling is created through Attempts.Create
+// (run.CreateAttempt behind it, the only attempt creator), one per chosen
+// runner. The first conclusive result wins; every other live sibling gets one
+// lease cancel (NODE-23 kills its process group on the node); the race waits
+// until every sibling has ended, then posts exactly one Evidence.
+// Inputs:  a Choice from Select, the Attempts and the Poster.
+// Outputs: the Evidence that was posted.
+// Constraints: cancellation is idempotent and fenced by the sibling's lease
+// epoch; a sibling that ends after the winner is superseded (or flaky when its
+// conclusive result differs), never a second result; a sibling admitted on a
+// runner another sibling holds is cancelled at once; no sibling posts.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+)
+
+// ErrNotRaced is returned when the job cannot be raced: the caller runs one attempt.
+var ErrNotRaced = errors.New("race: job not raced")
+
+// Attempts creates, awaits and cancels sibling attempts.
+type Attempts interface {
+	// Create makes attempt n of the job, placed on runner.
+	Create(ctx context.Context, n int, runner string) (Sibling, error)
+	// Wait blocks until the sibling has ended.
+	Wait(ctx context.Context, s Sibling) Result
+	// Cancel asks the sibling's lease to stop, fenced by s.Epoch. A repeat or a
+	// cancel that lost to the result commit is not an error.
+	Cancel(ctx context.Context, s Sibling, reason string) error
+}
+
+// Poster records and posts the one result of a race.
+type Poster interface {
+	Post(ctx context.Context, e Evidence) error
+}
+
+// Spec is one race.
+type Spec struct {
+	Job    string // the job key, for the evidence
+	Choice Choice
+	First  int // attempt number of the first sibling (>= 1)
+}
+
+type ended struct {
+	i int
+	r Result
+}
+
+// Run races the siblings of spec and posts one Evidence.
+func Run(ctx context.Context, spec Spec, a Attempts, p Poster) (Evidence, error) {
+	ev := Evidence{Job: spec.Job, Width: len(spec.Choice.Runners), Losers: []Loser{}, Excluded: spec.Choice.Excluded}
+	if !spec.Choice.Raceable() {
+		return ev, fmt.Errorf("%w: %s", ErrNotRaced, spec.Choice.Reason)
+	}
+	sibs := create(ctx, spec, a, &ev)
+	if len(sibs) == 0 {
+		return ev, fmt.Errorf("%w: no sibling was admitted", ErrNotRaced)
+	}
+	done := make(chan ended, len(sibs))
+	for i, s := range sibs {
+		go func() { done <- ended{i, a.Wait(ctx, s)} }()
+	}
+	winner, first := -1, -1
+	results := make([]*Result, len(sibs))
+	asked := make([]bool, len(sibs))
+	cancelRest := func(reason string) {
+		for i, s := range sibs {
+			if i != winner && results[i] == nil && !asked[i] {
+				asked[i] = true
+				if err := a.Cancel(context.WithoutCancel(ctx), s, reason); err != nil {
+					ev.Notes = append(ev.Notes, fmt.Sprintf("cancel %s: %v", s.AttemptID, err))
+				}
+			}
+		}
+	}
+	for range sibs {
+		var e ended
+		select {
+		case e = <-done:
+		case <-ctx.Done():
+			cancelRest("run cancelled")
+			e = <-done
+		}
+		r := e.r
+		results[e.i] = &r
+		if first < 0 {
+			first = e.i
+		}
+		if winner < 0 && Conclusive(r) {
+			winner = e.i
+			cancelRest("race lost to " + sibs[e.i].AttemptID)
+		}
+	}
+	ev.Result = *results[first]
+	if winner >= 0 {
+		w := sibs[winner]
+		ev.Winner, ev.Result = &w, *results[winner]
+	}
+	for i, s := range sibs {
+		if i == winner {
+			continue
+		}
+		l := Loser{Sibling: s, Result: results[i], Disposition: dispose(winner >= 0, asked[i], *results[i], ev.Result)}
+		ev.Flaky = ev.Flaky || l.Disposition == Flaky
+		ev.Losers = append(ev.Losers, l)
+	}
+	slices.SortFunc(ev.Losers, func(x, y Loser) int { return x.N - y.N })
+	if ctx.Err() != nil {
+		return ev, ctx.Err() // a cancelled run posts nothing from the race
+	}
+	if err := p.Post(context.WithoutCancel(ctx), ev); err != nil {
+		return ev, err
+	}
+	return ev, nil
+}
+
+// create makes one sibling per chosen runner. A sibling admitted on a runner
+// another sibling already holds is cancelled and left out.
+func create(ctx context.Context, spec Spec, a Attempts, ev *Evidence) []Sibling {
+	var sibs []Sibling
+	held := map[string]bool{}
+	n := max(spec.First, 1)
+	for _, runner := range spec.Choice.Runners {
+		s, err := a.Create(ctx, n, runner)
+		n++
+		if err != nil {
+			ev.Notes = append(ev.Notes, fmt.Sprintf("sibling on %s not admitted: %v", runner, err))
+			continue
+		}
+		if held[s.RunnerID] {
+			_ = a.Cancel(context.WithoutCancel(ctx), s, ReasonSibling)
+			ev.Losers = append(ev.Losers, Loser{Sibling: s, Disposition: Cancelled})
+			ev.Notes = append(ev.Notes, fmt.Sprintf("sibling %s admitted on %s, which a sibling holds: cancelled", s.AttemptID, s.RunnerID))
+			continue
+		}
+		held[s.RunnerID] = true
+		sibs = append(sibs, s)
+	}
+	return sibs
+}
+
+// dispose names how a non-winning sibling ended.
+func dispose(won, asked bool, r, result Result) string {
+	switch {
+	case !won:
+		return Lost
+	case Conclusive(r) && (r.State != result.State || r.FailureClass != result.FailureClass):
+		return Flaky
+	case asked && r.State == StateCancelled:
+		return Cancelled
+	}
+	return Superseded
+}
diff --git a/free/ci/internal/race/race_test.go b/free/ci/internal/race/race_test.go
new file mode 100644
index 000000000..8fa15014c
--- /dev/null
+++ b/free/ci/internal/race/race_test.go
@@ -0,0 +1,201 @@
+package race
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+)
+
+// fakeNode is one runner: a sibling's process group lives until it ends.
+type fakeNode struct {
+	alive bool
+	end   chan Result
+	// onCancel is what the attempt reports when cancelled (zero: cancelled).
+	onCancel Result
+}
+
+// fakeAttempts admits a sibling on the runner it is asked for (or on admit[runner]).
+type fakeAttempts struct {
+	mu      sync.Mutex
+	nodes   map[string]*fakeNode
+	admit   map[string]string
+	created []Sibling
+	cancels map[string]int
+	refuse  map[string]error
+}
+
+func newFake(runners ...string) *fakeAttempts {
+	f := &fakeAttempts{nodes: map[string]*fakeNode{}, admit: map[string]string{}, cancels: map[string]int{}, refuse: map[string]error{}}
+	for _, r := range runners {
+		f.nodes[r] = &fakeNode{end: make(chan Result, 1)}
+	}
+	return f
+}
+
+func (f *fakeAttempts) Create(_ context.Context, n int, runner string) (Sibling, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if err := f.refuse[runner]; err != nil {
+		return Sibling{}, err
+	}
+	if to := f.admit[runner]; to != "" {
+		runner = to
+	}
+	s := Sibling{N: n, AttemptID: "job.a" + string(rune('0'+n)), RunnerID: runner, Epoch: int64(n)}
+	f.created = append(f.created, s)
+	f.nodes[runner].alive = true
+	return s, nil
+}
+
+func (f *fakeAttempts) Wait(_ context.Context, s Sibling) Result {
+	r := <-f.nodes[s.RunnerID].end
+	f.mu.Lock()
+	f.nodes[s.RunnerID].alive = false
+	f.mu.Unlock()
+	return r
+}
+
+// Cancel kills the process group: the sibling ends with onCancel or cancelled.
+func (f *fakeAttempts) Cancel(_ context.Context, s Sibling, _ string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.cancels[s.AttemptID]++
+	n := f.nodes[s.RunnerID]
+	r := n.onCancel
+	if r.State == "" {
+		r = Result{State: StateCancelled, FailureClass: StateCancelled}
+	}
+	select {
+	case n.end <- r:
+	default: // already ended: the cancel is a no-op
+	}
+	return nil
+}
+
+func (f *fakeAttempts) finish(runner string, r Result) { f.nodes[runner].end <- r }
+
+type fakePoster struct {
+	mu    sync.Mutex
+	posts []Evidence
+}
+
+func (p *fakePoster) Post(_ context.Context, e Evidence) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.posts = append(p.posts, e)
+	return nil
+}
+
+var (
+	pass    = Result{State: StatePassed}
+	codeRed = Result{State: StateFailed, FailureClass: ClassCode, ExitCode: 1}
+	infra   = Result{State: StateFailed, FailureClass: "infra"}
+)
+
+func choice(runners ...string) Choice { return Choice{Runners: runners, Excluded: map[string]string{}} }
+
+func TestRaceFirstConclusiveWins(t *testing.T) {
+	f, p := newFake("n1", "n2"), &fakePoster{}
+	f.finish("n1", pass) // n1 is faster; n2 only ends when cancelled
+	ev, err := Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ev.Winner == nil || ev.Winner.RunnerID != "n1" || ev.Result != pass {
+		t.Fatalf("winner = %+v result = %+v", ev.Winner, ev.Result)
+	}
+	if got := ev.CancelledSiblings(); len(got) != 1 || got[0] != "job.a2" {
+		t.Fatalf("cancelled = %v", got)
+	}
+	if f.nodes["n2"].alive {
+		t.Fatal("the loser's process group is still alive")
+	}
+	if f.cancels["job.a1"] != 0 || f.cancels["job.a2"] != 1 {
+		t.Fatalf("cancels = %v", f.cancels)
+	}
+	// a red first finisher is conclusive too
+	f, p = newFake("n1", "n2"), &fakePoster{}
+	f.finish("n1", codeRed)
+	ev, err = Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p)
+	if err != nil || ev.Winner == nil || ev.Winner.RunnerID != "n1" || ev.Result != codeRed || len(ev.CancelledSiblings()) != 1 {
+		t.Fatalf("code failure did not end the race: %+v %v", ev, err)
+	}
+}
+
+func TestRaceInfraNotConclusive(t *testing.T) {
+	f, p := newFake("n1", "n2"), &fakePoster{}
+	f.finish("n1", infra)
+	f.finish("n2", pass)
+	ev, err := Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ev.Winner == nil || ev.Winner.RunnerID != "n2" || ev.Result != pass || ev.Flaky {
+		t.Fatalf("an infra error ended the race: %+v", ev)
+	}
+	// no conclusive result: the race records the first result, with no winner
+	f, p = newFake("n1", "n2"), &fakePoster{}
+	f.finish("n1", infra)
+	f.finish("n2", Result{State: "lost", FailureClass: "lost"})
+	ev, err = Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p)
+	if err != nil || ev.Winner != nil || Conclusive(ev.Result) || len(p.posts) != 1 {
+		t.Fatalf("inconclusive race: %+v %v posts=%d", ev, err, len(p.posts))
+	}
+	for _, l := range ev.Losers {
+		if l.Disposition != Lost {
+			t.Fatalf("loser %+v", l)
+		}
+	}
+}
+
+func TestRaceOneResult(t *testing.T) {
+	f, p := newFake("n1", "n2", "n3"), &fakePoster{}
+	f.nodes["n2"].onCancel = codeRed // n2 finished red before its cancel landed
+	f.nodes["n3"].onCancel = pass    // n3 finished green: same result, superseded
+	f.finish("n1", pass)
+	ev, err := Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2", "n3"), First: 1}, f, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(p.posts) != 1 {
+		t.Fatalf("posts = %d, want exactly one", len(p.posts))
+	}
+	if ev.Result != pass || !ev.Flaky {
+		t.Fatalf("result %+v flaky %v: a later disagreement is data, never the result", ev.Result, ev.Flaky)
+	}
+	want := map[int]string{2: Flaky, 3: Superseded}
+	for _, l := range ev.Losers {
+		if want[l.N] != l.Disposition {
+			t.Fatalf("sibling %d: %s, want %s", l.N, l.Disposition, want[l.N])
+		}
+	}
+	// a cancelled run posts nothing
+	f, p = newFake("n1", "n2"), &fakePoster{}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err = Run(ctx, Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p); !errors.Is(err, context.Canceled) || len(p.posts) != 0 {
+		t.Fatalf("cancelled run: err %v posts %d", err, len(p.posts))
+	}
+}
+
+func TestRaceDuplicateRunnerCancelled(t *testing.T) {
+	f, p := newFake("n1", "n2"), &fakePoster{}
+	f.admit["n2"] = "n1" // the dispatcher admitted the second sibling on n1 as well
+	f.finish("n1", pass)
+	ev, err := Run(context.Background(), Spec{Job: "job", Choice: choice("n1", "n2"), First: 1}, f, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.cancels["job.a2"] != 1 || len(ev.CancelledSiblings()) != 1 || ev.Winner.AttemptID != "job.a1" {
+		t.Fatalf("duplicate sibling kept: %+v cancels %v", ev, f.cancels)
+	}
+}
+
+func TestRaceNotRacedRefuses(t *testing.T) {
+	f, p := newFake("n1"), &fakePoster{}
+	_, err := Run(context.Background(), Spec{Job: "job", Choice: Choice{Reason: ReasonRelease}}, f, p)
+	if !errors.Is(err, ErrNotRaced) || len(f.created) != 0 || len(p.posts) != 0 {
+		t.Fatalf("err %v created %d posts %d", err, len(f.created), len(p.posts))
+	}
+}
diff --git a/free/ci/internal/race/result.go b/free/ci/internal/race/result.go
new file mode 100644
index 000000000..f4f4c40e7
--- /dev/null
+++ b/free/ci/internal/race/result.go
@@ -0,0 +1,76 @@
+package race
+
+// Purpose: what a race records: the result of one sibling, whether it is
+// conclusive, and the one evidence document the pipeline keeps (CI-40).
+// Inputs:  sibling results as the attempt states and failure classes give them.
+// Outputs: Evidence naming the winner, the cancelled and superseded siblings,
+// and any later conclusive result that disagrees with the winner (flaky).
+// Constraints: a flaky entry is data only: it never changes Evidence.Result.
+
+// Attempt states and failure classes a sibling ends with.
+const (
+	StatePassed    = "passed"
+	StateFailed    = "failed"
+	StateCancelled = "cancelled"
+	ClassCode      = "code"
+)
+
+// Dispositions of a sibling that did not win.
+const (
+	Cancelled  = "cancelled"  // ended by the race's cancel
+	Superseded = "superseded" // finished after the winner with the same or no conclusive result
+	Flaky      = "flaky"      // finished after the winner with a different conclusive result
+	Lost       = "lost"       // ended without a conclusive result before any winner
+)
+
+// Sibling is one admitted attempt of a raced job.
+type Sibling struct {
+	N         int    `json:"n"`
+	AttemptID string `json:"attempt_id"`
+	LeaseID   string `json:"lease_id,omitempty"`
+	RunnerID  string `json:"runner_id"`
+	Epoch     int64  `json:"epoch"`
+}
+
+// Result is how a sibling ended.
+type Result struct {
+	State        string `json:"state"`
+	FailureClass string `json:"failure_class,omitempty"`
+	ExitCode     int    `json:"exit_code"`
+}
+
+// Conclusive says r decides the job: a pass, or a code-class failure (a red
+// result is conclusive). infra, error, timeout, lost and cancelled are not.
+func Conclusive(r Result) bool {
+	return r.State == StatePassed || r.State == StateFailed && r.FailureClass == ClassCode
+}
+
+// Loser is a sibling that did not win, with how it ended.
+type Loser struct {
+	Sibling
+	Disposition string  `json:"disposition"`
+	Result      *Result `json:"result,omitempty"` // nil when it never reported
+}
+
+// Evidence is the one document a race records and posts.
+type Evidence struct {
+	Job      string            `json:"job"`
+	Width    int               `json:"width"`
+	Winner   *Sibling          `json:"winner,omitempty"` // nil when no sibling was conclusive
+	Result   Result            `json:"result"`
+	Losers   []Loser           `json:"losers"`
+	Flaky    bool              `json:"flaky"` // a later sibling disagreed; Result is unchanged
+	Excluded map[string]string `json:"excluded,omitempty"`
+	Notes    []string          `json:"notes,omitempty"`
+}
+
+// CancelledSiblings lists the attempts the race cancelled.
+func (e Evidence) CancelledSiblings() []string {
+	var out []string
+	for _, l := range e.Losers {
+		if l.Disposition == Cancelled {
+			out = append(out, l.AttemptID)
+		}
+	}
+	return out
+}
diff --git a/free/ci/internal/race/select.go b/free/ci/internal/race/select.go
new file mode 100644
index 000000000..bf1cde9ff
--- /dev/null
+++ b/free/ci/internal/race/select.go
@@ -0,0 +1,136 @@
+package race
+
+// Purpose: choose the runners of one race. Each sibling is placed by
+// sched.Place on a world that excludes every runner already chosen, so no two
+// siblings share a runner and every choice passes the scheduler's own
+// eligibility (capacity, limits, trust admission, overrides).
+// Inputs:  the placement world, the job's placement request and the width.
+// Outputs: a Choice: the runners in placement order and why others were left out.
+// Constraints: pure; the caller's world is never mutated. A release-class job
+// is never raced (CACHE-05 at-most-once). Hosted, paid and ephemeral targets
+// (any class but local and owned) and runners that fail trust admission are
+// excluded before placement. The width never exceeds the free slots of the
+// runners left, so a race cannot starve other work.
+
+import (
+	"slices"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// Reasons a runner or a job is kept out of a race.
+const (
+	ReasonRelease  = "race.release"   // a release-class or idempotent:false job runs at most once
+	ReasonSpend    = "race.spend"     // a hosted, paid or ephemeral target
+	ReasonTrust    = "race.untrusted" // the runner fails trust admission for the job
+	ReasonSibling  = "race.sibling"   // a sibling already holds the runner
+	ReasonNoTarget = "race.no-target" // fewer than two distinct eligible runners
+)
+
+// Choice is the outcome of Select.
+type Choice struct {
+	Runners  []string          // distinct runner ids, in placement order
+	Excluded map[string]string // runner id -> reason it cannot take a sibling
+	Reason   string            // why the job is not raced ("" when len(Runners) >= 2)
+}
+
+// Raceable says the choice has at least two siblings.
+func (c Choice) Raceable() bool { return len(c.Runners) >= 2 }
+
+// freeClasses are the cost classes a sibling may run on: nothing is spent.
+var freeClasses = []string{"local", "owned"}
+
+// Spend says a runner is a target a race never uses: a hosted, paid or ephemeral class.
+func Spend(w sched.World, r sched.Runner) bool {
+	class := r.Class
+	if c := w.Costs[r.ID].Class; c != "" { // the priced class wins over the claimed one
+		class = c
+	}
+	return r.Ephemeral || r.Location == "hosted" || !slices.Contains(freeClasses, class)
+}
+
+// Trusted says the runner passes trust admission for the job.
+func Trusted(w sched.World, j sched.Job, r sched.Runner) bool {
+	jf := trust.JobFacts{Trust: j.Trust, SecretClasses: j.SecretClasses, Network: j.Network, PersonalOwnRun: j.PersonalOwnRun, Release: j.Pipeline.Release}
+	return len(trust.Admissible(jf, r.Decl, w.Policy.Trust)) == 0
+}
+
+// Select picks up to width distinct runners for j. release marks a
+// release-class job (model.Job.Kind "release" or a release pipeline).
+func Select(w sched.World, j sched.Job, width int, release bool) Choice {
+	c := Choice{Excluded: map[string]string{}}
+	if release || j.Pipeline.Release {
+		c.Reason = ReasonRelease
+		return c
+	}
+	w = cloneWorld(w)
+	for _, r := range w.Hosted {
+		c.Excluded[r.ID] = ReasonSpend
+	}
+	w.Hosted = nil
+	free := 0
+	for _, r := range w.Runners {
+		switch {
+		case Spend(w, r):
+			c.Excluded[r.ID] = ReasonSpend
+		case !Trusted(w, j, r):
+			c.Excluded[r.ID] = ReasonTrust
+		default:
+			free += max(r.Avail.Slots, 0)
+			continue
+		}
+		exclude(&w, r.ID, c.Excluded[r.ID])
+	}
+	width = min(max(width, 1), MaxWidth, free)
+	for len(c.Runners) < width {
+		res := sched.Place(w, []sched.Job{j})
+		if len(res.Placements) == 0 {
+			break
+		}
+		p := res.Placements[0]
+		if p.RunnerID == "" || slices.Contains(c.Runners, p.RunnerID) || c.Excluded[p.RunnerID] != "" {
+			break // defensive: the scheduler ignored an exclusion
+		}
+		c.Runners = append(c.Runners, p.RunnerID)
+		w.Apply(p)
+		exclude(&w, p.RunnerID, ReasonSibling)
+	}
+	if !c.Raceable() {
+		c.Reason = ReasonNoTarget
+	}
+	return c
+}
+
+// exclude adds a race reason to the runner's exclusions (World.Exclusions).
+func exclude(w *sched.World, id, why string) {
+	w.Exclusions[id] = append(w.Exclusions[id], model.PlacementReasonDetail{Code: string(model.OverrideExcluded), Detail: why})
+}
+
+// cloneWorld copies every part of w that Select or World.Apply writes.
+func cloneWorld(w sched.World) sched.World {
+	w.Runners = slices.Clone(w.Runners)
+	w.Hosted = slices.Clone(w.Hosted)
+	ex := make(map[string][]model.PlacementReasonDetail, len(w.Exclusions))
+	for k, v := range w.Exclusions {
+		ex[k] = slices.Clone(v)
+	}
+	w.Exclusions = ex
+	w.Counts.Runners = cloneMap(w.Counts.Runners)
+	w.Counts.Providers = cloneMap(w.Counts.Providers)
+	w.Allowances = cloneMap(w.Allowances)
+	w.Budgets.Providers = cloneMap(w.Budgets.Providers)
+	return w
+}
+
+func cloneMap[V any](m map[string]V) map[string]V {
+	if m == nil {
+		return nil
+	}
+	out := make(map[string]V, len(m))
+	for k, v := range m {
+		out[k] = v
+	}
+	return out
+}
diff --git a/free/ci/internal/race/select_test.go b/free/ci/internal/race/select_test.go
new file mode 100644
index 000000000..5a9955d52
--- /dev/null
+++ b/free/ci/internal/race/select_test.go
@@ -0,0 +1,129 @@
+package race
+
+import (
+	"encoding/json"
+	"math/rand"
+	"slices"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+func ptr[T any](v T) *T { return &v }
+
+func runner(id, loc, class string, slots int) sched.Runner {
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Lifecycle.AuthorizedProjects, c.Lifecycle.Eligible = []string{"project"}, true
+	c.Protocol.Versions, c.Protocol.Min = []int{1}, 1
+	c.Platform.OS.Value, c.Platform.Arch.Value = ptr("linux"), ptr("amd64")
+	c.Resources.CPU.Value, c.Resources.MemMB.Value = ptr(float64(8)), ptr(int64(8192))
+	c.Identity.Labels = []string{"arch=amd64"}
+	c.Location.Kind.Value = &loc
+	return sched.Runner{ID: id, Location: loc, Class: class, Provider: "operator", Avail: sched.Avail{Slots: slots, CPU: 8 * int64(slots), MemMB: 8192 * int64(slots)}, Capability: c,
+		Decl: trust.Declaration{Accepts: []model.TrustClass{"owner", "internal"}, Isolation: "vm", Network: "privileged", UIDSeparation: true, Ownership: "operator", PersonalOwnNode: loc == "local", NoLANRoute: true}}
+}
+
+func job() sched.Job {
+	return sched.Job{Key: "job", ID: "job", Project: "project", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan", TimeoutMs: 60000, PersonalOwnRun: true}
+}
+
+func world(rs ...sched.Runner) sched.World {
+	return sched.World{Runners: rs, Policy: sched.Policy{Preset: "balanced", PaidEnabled: true}, Costs: map[string]sched.Cost{}, Previous: map[string]string{}}
+}
+
+func TestRaceNeverPaidOrRelease(t *testing.T) {
+	paid := runner("paid", "vps", "paid", 4)
+	eph := runner("eph", "lan", "owned", 4)
+	eph.Ephemeral = true
+	untrusted := runner("untrusted", "lan", "owned", 4)
+	untrusted.Decl.Accepts = []model.TrustClass{"untrusted"}
+	hosted := runner("hosted", "hosted", "included", 4)
+	w := world(runner("a", "lan", "owned", 1), runner("b", "local", "local", 1), paid, eph, untrusted)
+	w.Hosted = []sched.Runner{hosted}
+	c := Select(w, job(), 8, false)
+	slices.Sort(c.Runners)
+	if !slices.Equal(c.Runners, []string{"a", "b"}) {
+		t.Fatalf("runners = %v excluded = %v", c.Runners, c.Excluded)
+	}
+	want := map[string]string{"paid": ReasonSpend, "eph": ReasonSpend, "hosted": ReasonSpend, "untrusted": ReasonTrust}
+	for id, why := range want {
+		if c.Excluded[id] != why {
+			t.Fatalf("%s excluded for %q, want %q", id, c.Excluded[id], why)
+		}
+	}
+	if len(w.Exclusions) != 0 || w.Runners[0].Avail.Slots != 1 {
+		t.Fatal("Select mutated the caller's world")
+	}
+	j := job()
+	if c := Select(w, j, 8, true); c.Raceable() || c.Reason != ReasonRelease {
+		t.Fatalf("a release-class job was raced: %+v", c)
+	}
+	j.Pipeline.Release = true
+	if c := Select(w, j, 8, false); c.Raceable() || c.Reason != ReasonRelease {
+		t.Fatalf("a release pipeline was raced: %+v", c)
+	}
+	// one eligible runner left: no race
+	if c := Select(world(runner("a", "lan", "owned", 3), paid), job(), 4, false); c.Raceable() || c.Reason != ReasonNoTarget {
+		t.Fatalf("one runner raced against itself: %+v", c)
+	}
+}
+
+func TestRaceWidthBounded(t *testing.T) {
+	seed := time.Now().UnixNano()
+	rng := rand.New(rand.NewSource(seed))
+	classes := []string{"owned", "local", "paid", "ephemeral", "included"}
+	for round := 0; round < 200; round++ {
+		var rs []sched.Runner
+		for i := 0; i < 1+rng.Intn(6); i++ {
+			r := runner(string(rune('a'+i)), "lan", classes[rng.Intn(len(classes))], rng.Intn(3))
+			r.Ephemeral = rng.Intn(5) == 0
+			if rng.Intn(5) == 0 {
+				r.Decl.Accepts = []model.TrustClass{"untrusted"}
+			}
+			rs = append(rs, r)
+		}
+		w := world(rs...)
+		width := 1 + rng.Intn(5)
+		c := Select(w, job(), width, false)
+		free := 0
+		for _, r := range rs {
+			if !Spend(w, r) && Trusted(w, job(), r) {
+				free += r.Avail.Slots
+			}
+		}
+		if len(c.Runners) > width || len(c.Runners) > free {
+			t.Fatalf("seed %d round %d: %d siblings, width %d, free slots %d", seed, round, len(c.Runners), width, free)
+		}
+		seen := map[string]bool{}
+		for _, id := range c.Runners {
+			if seen[id] {
+				t.Fatalf("seed %d round %d: two siblings on %s", seed, round, id)
+			}
+			seen[id] = true
+			for _, r := range rs {
+				if r.ID == id && (Spend(w, r) || r.Ephemeral || !Trusted(w, job(), r)) {
+					t.Fatalf("seed %d round %d: sibling on %s (%s)", seed, round, id, r.Class)
+				}
+			}
+		}
+	}
+}
+
+func TestWidthKey(t *testing.T) {
+	if Width(trust.Effective{}) != DefaultWidth {
+		t.Fatal("unset width is not the default")
+	}
+	for raw, ok := range map[string]bool{"3": true, "1": true, "0": false, "17": false, `"2"`: false, "2 3": false} {
+		_, err := decodeWidth(json.RawMessage(raw))
+		if (err == nil) != ok {
+			t.Fatalf("decode %s: %v", raw, err)
+		}
+	}
+	if errs := RegistrationErrors(); len(errs) != 0 {
+		t.Fatal(errs)
+	}
+}
diff --git a/free/ci/internal/release/job/stash.go b/free/ci/internal/release/job/stash.go
index b2f0b270d..d11ff5ee5 100644
--- a/free/ci/internal/release/job/stash.go
+++ b/free/ci/internal/release/job/stash.go
@@ -7,13 +7,16 @@ package job
 // digester must never run under the writer lock).
 // Inputs:  a Provider per release attempt (Guard) or static Facts (Put, tests).
 // Outputs: Source.ReleaseFacts: the latest Facts, or an E715 when the last
-// refresh failed or is older than maxAge (the attempt then stays queued).
+// refresh failed or is older than maxAge (the attempt then stays queued); one
+// release.admission.refused audit row per refusal Guard returns (Stash.Audit).
 // Constraints: safe for concurrent use; the refresher stops when the submission
 // returns; an entry is forgotten with it. maxAge is several refresh intervals, so
 // a change made while the attempt waits is seen within about refreshEvery.
 
 import (
 	"context"
+	"errors"
+	"fmt"
 	"sync"
 	"time"
 )
@@ -41,6 +44,29 @@ type Stash struct {
 	// between Guard and Admit is seen atomically; nil revokes nothing. An error
 	// (the ledger cannot answer) refuses the attempt: the signer is unverified.
 	Revoked func(keyID string) (bool, error)
+	// Audit writes one audit row (store.AppendAudit); Guard records every
+	// refusal it returns as release.admission.refused (TM-17). Nil records none.
+	Audit AuditSink
+}
+
+// AuditSink writes one audit row.
+type AuditSink func(ctx context.Context, actor, action, target, detail string) error
+
+// AuditAction is the audit action of a refused release admission.
+const AuditAction = "release.admission.refused"
+
+// refused records e (when it is a refusal) and returns it. A lost row is joined
+// to the refusal, never silent, and never turns it into an admission.
+func (s *Stash) refused(ctx context.Context, attemptID string, e *Error) error {
+	if e == nil {
+		return nil
+	}
+	if s.Audit != nil {
+		if err := s.Audit(ctx, "release", AuditAction, attemptID, "reason="+e.Reason+" code="+e.Code); err != nil {
+			return errors.Join(e, fmt.Errorf("release admission audit: %w", err))
+		}
+	}
+	return e
 }
 
 // NewStash returns an empty stash.
@@ -108,21 +134,21 @@ func (s *Stash) Guard(ctx context.Context, attemptID string, p Provider, next fu
 	_, busy := s.m[attemptID]
 	s.mu.Unlock()
 	if busy { // two submissions of one attempt would share, and one would delete, the other's facts
-		return refuse(CodeNotAdmitted, Duplicate, "attempt %s is already being submitted", attemptID)
+		return s.refused(ctx, attemptID, refuse(CodeNotAdmitted, Duplicate, "attempt %s is already being submitted", attemptID))
 	}
 	asked := now()
 	f, perr := p(ctx)
 	if perr != nil {
-		return perr
+		return s.refused(ctx, attemptID, perr)
 	}
 	if e := Evaluate(f); e != nil {
-		return e
+		return s.refused(ctx, attemptID, e)
 	}
 	own := &entry{f: f, at: asked, live: true}
 	s.mu.Lock()
 	if _, busy = s.m[attemptID]; busy {
 		s.mu.Unlock()
-		return refuse(CodeNotAdmitted, Duplicate, "attempt %s is already being submitted", attemptID)
+		return s.refused(ctx, attemptID, refuse(CodeNotAdmitted, Duplicate, "attempt %s is already being submitted", attemptID))
 	}
 	s.m[attemptID] = own
 	s.mu.Unlock()
diff --git a/free/ci/internal/release/verify/verify.go b/free/ci/internal/release/verify/verify.go
index ed0605dfe..600b4c53d 100644
--- a/free/ci/internal/release/verify/verify.go
+++ b/free/ci/internal/release/verify/verify.go
@@ -12,7 +12,7 @@ package verify
 // SHA256SUMS and every file digest, evidence digest and revision, provenance
 // signature and subjects, SBOM links, then the evidence verdict at the released
 // revision. Nothing runs a process but git through the exec funnel; nothing
-// writes. The claimed level is exactly Build L1 and Result carries no other.
+// writes but the optional audit row of a refusal. The claimed level is exactly Build L1 and Result carries no other.
 
 import (
 	"context"
@@ -59,6 +59,9 @@ type Options struct {
 	// Quarantined tells whether the evidence was quarantined; nil quarantines
 	// nothing. An error fails closed as quarantined.
 	Quarantined func(ctx context.Context, ev model.Evidence) (bool, error)
+	// Audit, when set, records a refused verification (release.verify.refused
+	// with the reason key; TM-18). Its error is a Result warning, never a pass.
+	Audit func(ctx context.Context, actor, action, target, detail string) error
 }
 
 // Result is the outcome of Release; it is what `artifacts verify --json` prints.
@@ -109,11 +112,11 @@ func Release(ctx context.Context, dir string, opt Options) Result {
 		{"provenance", r.provenance}, {"sbom_link", r.sbomLinks}, {"evidence_verdict", r.evidenceVerdict},
 	}
 	if st, err := os.Stat(dir); err != nil || !st.IsDir() {
-		return res.fail(fail(ReasonReleaseMissing, "%s is not a release directory", dir))
+		return r.refused(res.fail(fail(ReasonReleaseMissing, "%s is not a release directory", dir)))
 	}
 	for _, s := range steps {
 		if f := s.fn(); f != nil {
-			return res.fail(f)
+			return r.refused(res.fail(f))
 		}
 		res.Passed = append(res.Passed, s.name)
 	}
@@ -121,6 +124,17 @@ func Release(ctx context.Context, dir string, opt Options) Result {
 	return res
 }
 
+// refused writes the refusal's audit row when Options.Audit is set.
+func (r *run) refused(res Result) Result {
+	if r.opt.Audit == nil {
+		return res
+	}
+	if err := r.opt.Audit(r.ctx, "release", "release.verify.refused", r.dir, "reason="+res.Reason+" code="+res.Code); err != nil {
+		res.Warnings = append(res.Warnings, "the refusal could not be audited: "+err.Error())
+	}
+	return res
+}
+
 func (res Result) fail(f *Failure) Result {
 	res.Verified, res.Exit, res.Code, res.Reason, res.Message = false, f.ExitCode(), Code, f.Reason, f.Message
 	return res
diff --git a/free/ci/internal/report/context_test.go b/free/ci/internal/report/context_test.go
new file mode 100644
index 000000000..5af90e0f4
--- /dev/null
+++ b/free/ci/internal/report/context_test.go
@@ -0,0 +1,36 @@
+package report
+
+import "testing"
+
+func TestStatusContextOutboxKey(t *testing.T) {
+	res := Status{Owner: "o", Repo: "r"}
+	claim := Status{Owner: "o", Repo: "r", StatusContext: ClaimContext}
+	watch := Status{Owner: "o", Repo: "r", StatusContext: WatchContext}
+	if keyFor(res) != key("o", "r") {
+		t.Fatalf("result key changed: %s", keyFor(res))
+	}
+	seen := map[string]bool{}
+	for _, s := range []Status{res, claim, watch} {
+		if seen[keyFor(s)] {
+			t.Fatalf("collapsed key %s", keyFor(s))
+		}
+		seen[keyFor(s)] = true
+	}
+	sha := "0123456789abcdef0123456789abcdef01234567"
+	bad := Status{Owner: "o", Repo: "r", Revision: sha, State: Pending, StatusContext: "other/ctx"}
+	if bad.Validate() == nil {
+		t.Fatal("a foreign context must be refused")
+	}
+	if got := Args(Status{Owner: "o", Repo: "r", Revision: sha, State: Pending, StatusContext: ClaimContext}); !contains(got, "context="+ClaimContext) {
+		t.Fatalf("argv: %v", got)
+	}
+}
+
+func contains(a []string, s string) bool {
+	for _, x := range a {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/internal/report/github.go b/free/ci/internal/report/github.go
index d3542471b..55a2833d9 100644
--- a/free/ci/internal/report/github.go
+++ b/free/ci/internal/report/github.go
@@ -44,7 +44,7 @@ func (g GH) capture(ctx context.Context, argv ...string) (string, int, error) {
 // Status has one.
 func Args(s Status) []string {
 	args := []string{"gh", "api", "--method", "POST", fmt.Sprintf("repos/%s/%s/statuses/%s", s.Owner, s.Repo, s.Revision),
-		"-f", "state=" + string(s.State), "-f", "context=" + Context, "-f", "description=" + Truncate(s.Description)}
+		"-f", "state=" + string(s.State), "-f", "context=" + s.ContextName(), "-f", "description=" + Truncate(s.Description)}
 	if s.TargetURL != "" {
 		args = append(args, "-f", "target_url="+s.TargetURL)
 	}
diff --git a/free/ci/internal/report/ledger.go b/free/ci/internal/report/ledger.go
new file mode 100644
index 000000000..cdf1c9edf
--- /dev/null
+++ b/free/ci/internal/report/ledger.go
@@ -0,0 +1,43 @@
+package report
+
+// Purpose: the claim ledger interface (ADR 0032 decision 5, P7-AUTO-10). The
+// status history of a commit is the ledger; claims are `pending` statuses on
+// their own context so a late claim never overwrites a final result.
+// Inputs:  a claim Status to post; a repository and sha to list.
+// Outputs: the provider time of the response and the status history.
+// Constraints: PostClaim is synchronous (no outbox); the reporter stays the
+// only status writer; a provider error is returned, never turned into a state.
+
+import (
+	"context"
+	"time"
+)
+
+// ClaimContext is the context claims are posted on.
+const ClaimContext = Context + "/claim"
+
+// LedgerStatus is one entry of a commit's status history.
+type LedgerStatus struct {
+	Context     string    `json:"context"`
+	State       State     `json:"state"`
+	Creator     string    `json:"creator"`
+	Description string    `json:"description"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+// Ledger is the optional reporter extension that makes claims possible.
+type Ledger interface {
+	// PostClaim posts s (a pending status on ClaimContext) synchronously and
+	// returns the provider's clock from the response.
+	PostClaim(ctx context.Context, s Status) (providerNow time.Time, err error)
+	// ListStatuses returns the full status history of a sha, newest first as
+	// the provider gives it, with the provider's clock from the response.
+	ListStatuses(ctx context.Context, owner, repo, sha string) (list []LedgerStatus, providerNow time.Time, err error)
+}
+
+// ClaimStatus builds the claim status for host and incarnation. The
+// description never carries a path, token or repository content.
+func ClaimStatus(owner, repo, sha, host, incarnation string) Status {
+	return Status{Owner: owner, Repo: repo, Revision: sha, State: Pending, StatusContext: ClaimContext,
+		Description: "claim " + host + " " + incarnation}
+}
diff --git a/free/ci/internal/report/ledger_gh.go b/free/ci/internal/report/ledger_gh.go
new file mode 100644
index 000000000..93d5b9675
--- /dev/null
+++ b/free/ci/internal/report/ledger_gh.go
@@ -0,0 +1,107 @@
+package report
+
+// Purpose: the GitHub implementation of Ledger: one synchronous POST for a
+// claim and one GET of /commits/{sha}/statuses for the history, both read
+// with response headers so the provider's Date is the clock.
+// Inputs:  gh api through the capture funnel. Outputs: statuses and a time.
+// Constraints: gh authenticates itself; one list call per sha per pass.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+var _ Ledger = GH{}
+
+// PostClaim implements Ledger.
+func (g GH) PostClaim(ctx context.Context, s Status) (time.Time, error) {
+	if err := s.Validate(); err != nil {
+		return time.Time{}, err
+	}
+	if s.ContextName() != ClaimContext || s.State != Pending {
+		return time.Time{}, errors.New("report: a claim is a pending status on the claim context")
+	}
+	argv := Args(s)
+	argv = append(argv[:2], append([]string{"-i"}, argv[2:]...)...)
+	out, exit, err := g.capture(ctx, argv...)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("report: gh not run: %w", err)
+	}
+	if exit != 0 {
+		return time.Time{}, fmt.Errorf("report: claim not posted (exit %d): %s", exit, firstLine(out))
+	}
+	now, _ := splitResponse(out)
+	return now, nil
+}
+
+// ListStatuses implements Ledger.
+func (g GH) ListStatuses(ctx context.Context, owner, repo, sha string) ([]LedgerStatus, time.Time, error) {
+	if err := (Status{Owner: owner, Repo: repo, Revision: sha, State: Pending}).Validate(); err != nil {
+		return nil, time.Time{}, err
+	}
+	path := fmt.Sprintf("repos/%s/%s/commits/%s/statuses?per_page=100", owner, repo, sha)
+	out, exit, err := g.capture(ctx, "gh", "api", "-i", "--paginate", path)
+	if err != nil {
+		return nil, time.Time{}, fmt.Errorf("report: gh not run: %w", err)
+	}
+	if exit != 0 {
+		return nil, time.Time{}, fmt.Errorf("report: statuses not read (exit %d): %s", exit, firstLine(out))
+	}
+	now, body := splitResponse(out)
+	list, err := parseStatuses(body)
+	return list, now, err
+}
+
+// splitResponse separates `gh api -i` headers from the body and reads Date.
+func splitResponse(out string) (time.Time, string) {
+	out = strings.ReplaceAll(out, "\r\n", "\n")
+	head, body, ok := strings.Cut(out, "\n\n")
+	if !ok || !strings.HasPrefix(head, "HTTP/") {
+		return time.Time{}, out
+	}
+	var date time.Time
+	for _, l := range strings.Split(head, "\n") {
+		if k, v, found := strings.Cut(l, ":"); found && strings.EqualFold(k, "date") {
+			date, _ = http.ParseTime(strings.TrimSpace(v))
+		}
+	}
+	return date, body
+}
+
+func parseStatuses(body string) ([]LedgerStatus, error) {
+	var raw []struct {
+		Context     string    `json:"context"`
+		State       State     `json:"state"`
+		Description string    `json:"description"`
+		CreatedAt   time.Time `json:"created_at"`
+		Creator     struct {
+			Login string `json:"login"`
+		} `json:"creator"`
+	}
+	body = strings.ReplaceAll(strings.TrimSpace(body), "\n][", ",") // paginated pages
+	body = strings.ReplaceAll(body, "][", ",")
+	if err := json.Unmarshal([]byte(body), &raw); err != nil {
+		return nil, fmt.Errorf("report: statuses unreadable: %w", err)
+	}
+	out := make([]LedgerStatus, 0, len(raw))
+	for _, r := range raw {
+		out = append(out, LedgerStatus{Context: r.Context, State: r.State, Creator: r.Creator.Login,
+			Description: r.Description, CreatedAt: r.CreatedAt})
+	}
+	return out, nil
+}
+
+// Login returns the authenticated login of the station token, the creator
+// identity whose statuses count.
+func (g GH) Login(ctx context.Context) (string, error) {
+	out, exit, err := g.capture(ctx, "gh", "api", "user", "-q", ".login")
+	if err != nil || exit != 0 || strings.TrimSpace(out) == "" {
+		return "", errors.New("report: station login unreadable")
+	}
+	return strings.TrimSpace(out), nil
+}
diff --git a/free/ci/internal/report/ledger_gh_test.go b/free/ci/internal/report/ledger_gh_test.go
new file mode 100644
index 000000000..a3fd69d04
--- /dev/null
+++ b/free/ci/internal/report/ledger_gh_test.go
@@ -0,0 +1,58 @@
+package report
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+const sha40 = "0123456789abcdef0123456789abcdef01234567"
+
+func ghFake(out string, exit int, got *[]string) GH {
+	return GH{Capture: func(_ context.Context, argv ...string) (string, int, error) {
+		*got = argv
+		return out, exit, nil
+	}}
+}
+
+func TestLedgerGHListStatuses(t *testing.T) {
+	var argv []string
+	body := "HTTP/2.0 200 OK\r\nDate: Tue, 27 Oct 2026 12:00:00 GMT\r\n\r\n" +
+		`[{"context":"nself-ci","state":"success","description":"ok","created_at":"2026-10-27T11:00:00Z","creator":{"login":"station"}}]`
+	l, now, err := ghFake(body, 0, &argv).ListStatuses(context.Background(), "o", "r", sha40)
+	if err != nil || len(l) != 1 || l[0].Creator != "station" || l[0].State != Success {
+		t.Fatalf("%v %v", l, err)
+	}
+	if now.Year() != 2026 || now.Hour() != 12 {
+		t.Fatalf("provider time %v", now)
+	}
+	if !strings.Contains(strings.Join(argv, " "), "commits/"+sha40+"/statuses") {
+		t.Fatalf("%v", argv)
+	}
+	if _, _, err = ghFake("boom", 1, &argv).ListStatuses(context.Background(), "o", "r", sha40); err == nil {
+		t.Fatal("exit 1 must error")
+	}
+	if _, _, err = ghFake("x", 0, &argv).ListStatuses(context.Background(), "o", "r", "zz"); err == nil {
+		t.Fatal("bad sha")
+	}
+}
+
+func TestLedgerGHPostClaim(t *testing.T) {
+	var argv []string
+	g := ghFake("HTTP/2.0 201 Created\nDate: Tue, 27 Oct 2026 12:00:01 GMT\n\n{}", 0, &argv)
+	now, err := g.PostClaim(context.Background(), ClaimStatus("o", "r", sha40, "mm6", "i1"))
+	if err != nil || now.Second() != 1 {
+		t.Fatalf("%v %v", now, err)
+	}
+	j := strings.Join(argv, " ")
+	if !strings.Contains(j, "-i") || !strings.Contains(j, "context="+ClaimContext) || !strings.Contains(j, "description=claim mm6 i1") {
+		t.Fatalf("%s", j)
+	}
+	res := Status{Owner: "o", Repo: "r", Revision: sha40, State: Success}
+	if _, err = g.PostClaim(context.Background(), res); err == nil {
+		t.Fatal("a result is not a claim")
+	}
+	if _, err = ghFake("down", 1, &argv).PostClaim(context.Background(), ClaimStatus("o", "r", sha40, "mm6", "i1")); err == nil {
+		t.Fatal("provider failure must surface")
+	}
+}
diff --git a/free/ci/internal/report/ledger_test.go b/free/ci/internal/report/ledger_test.go
new file mode 100644
index 000000000..4075aaa7a
--- /dev/null
+++ b/free/ci/internal/report/ledger_test.go
@@ -0,0 +1,13 @@
+package report
+
+import "testing"
+
+func TestClaimStatusShape(t *testing.T) {
+	s := ClaimStatus("o", "r", sha40, "mm6", "i1")
+	if err := s.Validate(); err != nil || s.State != Pending || s.ContextName() != ClaimContext {
+		t.Fatalf("%v %+v", err, s)
+	}
+	if len(s.Description) > MaxDescription {
+		t.Fatal("too long")
+	}
+}
diff --git a/free/ci/internal/report/outbox.go b/free/ci/internal/report/outbox.go
index cc8d024f2..7bdffb541 100644
--- a/free/ci/internal/report/outbox.go
+++ b/free/ci/internal/report/outbox.go
@@ -29,11 +29,23 @@ type Outbox struct {
 // commit (a fork and its upstream) must not order or supersede each other.
 func key(owner, repo string) string { return Context + "@" + owner + "/" + repo }
 
+// keyFor is the store key of one status: the result context keeps the legacy
+// key, every other context (claim, watch, ...) gets its own so it is never
+// collapsed with the result (P7-AUTO-10).
+func keyFor(s Status) string {
+	return s.ContextName() + "@" + s.Owner + "/" + s.Repo
+}
+
 // Reserve takes the seq a run will use for its final status.
 func (o *Outbox) Reserve(ctx context.Context, revision string) (int64, error) {
 	return o.Store.OutboxReserve(ctx, revision, key(o.Owner, o.Repo))
 }
 
+// ReserveContext is Reserve for a status on another context (claim, watch...).
+func (o *Outbox) ReserveContext(ctx context.Context, revision, statusContext string) (int64, error) {
+	return o.Store.OutboxReserve(ctx, revision, keyFor(Status{StatusContext: statusContext, Owner: o.Owner, Repo: o.Repo}))
+}
+
 // Complete stores the status for seq and tries to deliver it. delivered is
 // false when the entry stayed pending or was superseded.
 func (o *Outbox) Complete(ctx context.Context, seq int64, s Status) (delivered bool, err error) {
@@ -44,7 +56,7 @@ func (o *Outbox) Complete(ctx context.Context, seq int64, s Status) (delivered b
 	if err != nil {
 		return false, err
 	}
-	if err = o.Store.OutboxReady(ctx, s.Revision, key(s.Owner, s.Repo), seq, body); err != nil {
+	if err = o.Store.OutboxReady(ctx, s.Revision, keyFor(s), seq, body); err != nil {
 		return false, err
 	}
 	return o.deliver(ctx, seq, s, true)
@@ -54,7 +66,7 @@ func (o *Outbox) deliver(ctx context.Context, seq int64, s Status, heal bool) (b
 	if o.Reporter == nil {
 		return false, nil
 	}
-	k := key(s.Owner, s.Repo)
+	k := keyFor(s)
 	for waited := 0; waited < 240; waited++ { // an older post in flight: wait up to ~2 minutes
 		res, token, err := o.Store.OutboxClaim(ctx, s.Revision, k, seq)
 		if err != nil {
diff --git a/free/ci/internal/report/reporter.go b/free/ci/internal/report/reporter.go
index 8ae1d3ec9..66faac139 100644
--- a/free/ci/internal/report/reporter.go
+++ b/free/ci/internal/report/reporter.go
@@ -48,6 +48,18 @@ type Status struct {
 	State       State  `json:"state"`
 	Description string `json:"description"`
 	TargetURL   string `json:"target_url,omitempty"`
+	// StatusContext is the commit status context; empty means Context
+	// ("nself-ci"). Claim, watch, residual and gate statuses set it so they
+	// never collapse into the result context in the outbox (P7-AUTO-10).
+	StatusContext string `json:"context,omitempty"`
+}
+
+// ContextName is the context the status is posted on.
+func (s Status) ContextName() string {
+	if s.StatusContext == "" {
+		return Context
+	}
+	return s.StatusContext
 }
 
 // Reporter delivers a status to a code host.
@@ -58,6 +70,7 @@ type Reporter interface {
 var (
 	ownerRepo = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$`)
 	shaRe     = regexp.MustCompile(`^[0-9a-f]{40,64}$`)
+	ctxRe     = regexp.MustCompile(`^nself-ci(/[a-z][a-z-]{0,30})?$`)
 )
 
 // validOwner accepts one to nineteen ownerRepo segments joined by '/' (a user, an organisation, or a
@@ -84,6 +97,8 @@ func (s Status) Validate() error {
 		return errors.New("report: invalid revision")
 	case !s.State.Valid():
 		return errors.New("report: invalid state")
+	case !ctxRe.MatchString(s.ContextName()):
+		return errors.New("report: invalid context")
 	}
 	return nil
 }
diff --git a/free/ci/internal/report/result_context.go b/free/ci/internal/report/result_context.go
new file mode 100644
index 000000000..bf129413c
--- /dev/null
+++ b/free/ci/internal/report/result_context.go
@@ -0,0 +1,110 @@
+package report
+
+// Purpose: which context carries a run's result (P7-AUTO-10). An unpinned
+// repository gets "nself-ci"; when the required check is app-pinned (only that
+// app may write it) or protection cannot be read, the result goes to
+// "nself-ci/watch" so a claim or result never fights the pin.
+// Inputs:  a repo and an optional override. Outputs: a context name.
+// Constraints: the protection read goes through the REST funnel and is cached
+// for one hour; an unreadable answer is cached too, so a failing provider is
+// not hammered; the rule itself is pure.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+// WatchContext is the result context for pinned or unreadable repositories.
+const WatchContext = Context + "/watch"
+
+// ProtectionTTL is how long a protection read is reused.
+const ProtectionTTL = time.Hour
+
+// ResultContextFor is the pure rule.
+func ResultContextFor(pinned, readable bool, override string) string {
+	if override != "" {
+		return override
+	}
+	if !readable || pinned {
+		return WatchContext
+	}
+	return Context
+}
+
+// ProtectionReader reports whether the required check is app-pinned.
+type ProtectionReader func(ctx context.Context, owner, repo string) (pinned bool, err error)
+
+type protEntry struct {
+	pinned, readable bool
+	at               time.Time
+}
+
+// ResultContexts resolves and caches result contexts.
+type ResultContexts struct {
+	Read ProtectionReader
+	Now  func() time.Time // nil: time.Now
+
+	mu    sync.Mutex
+	cache map[string]protEntry
+}
+
+// ResolveResultContext returns the result context of owner/repo.
+func (r *ResultContexts) ResolveResultContext(ctx context.Context, owner, repo, override string) string {
+	if override != "" {
+		return override
+	}
+	now := time.Now
+	if r.Now != nil {
+		now = r.Now
+	}
+	k := owner + "/" + repo
+	r.mu.Lock()
+	e, ok := r.cache[k]
+	r.mu.Unlock()
+	if !ok || now().Sub(e.at) >= ProtectionTTL {
+		e = protEntry{at: now()}
+		if r.Read != nil {
+			p, err := r.Read(ctx, owner, repo)
+			e.pinned, e.readable = p, err == nil
+		}
+		r.mu.Lock()
+		if r.cache == nil {
+			r.cache = map[string]protEntry{}
+		}
+		r.cache[k] = e
+		r.mu.Unlock()
+	}
+	return ResultContextFor(e.pinned, e.readable, "")
+}
+
+// RequiredPinned reads the default branch's required status checks and says
+// whether "nself-ci" is pinned to an app.
+func (g GH) RequiredPinned(ctx context.Context, owner, repo string) (bool, error) {
+	path := fmt.Sprintf("repos/%s/%s/branches/main/protection/required_status_checks", owner, repo)
+	out, exit, err := g.capture(ctx, "gh", "api", path)
+	if err != nil || exit != 0 {
+		if strings.Contains(out, "Branch not protected") {
+			return false, nil
+		}
+		return false, fmt.Errorf("report: protection unreadable: %s", firstLine(out))
+	}
+	var doc struct {
+		Checks []struct {
+			Context string `json:"context"`
+			AppID   *int64 `json:"app_id"`
+		} `json:"checks"`
+	}
+	if err = json.Unmarshal([]byte(out), &doc); err != nil {
+		return false, err
+	}
+	for _, c := range doc.Checks {
+		if c.Context == Context && c.AppID != nil && *c.AppID > 0 {
+			return true, nil
+		}
+	}
+	return false, nil
+}
diff --git a/free/ci/internal/report/result_context_test.go b/free/ci/internal/report/result_context_test.go
new file mode 100644
index 000000000..c005e82e6
--- /dev/null
+++ b/free/ci/internal/report/result_context_test.go
@@ -0,0 +1,43 @@
+package report
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestResultContextPinnedOrUnreadable(t *testing.T) {
+	if ResultContextFor(false, true, "") != Context || ResultContextFor(true, true, "") != WatchContext ||
+		ResultContextFor(false, false, "") != WatchContext || ResultContextFor(true, true, Context) != Context {
+		t.Fatal("rule")
+	}
+	now := time.Unix(1000, 0)
+	calls := 0
+	var pinned bool
+	var rerr error
+	rc := &ResultContexts{Now: func() time.Time { return now }, Read: func(context.Context, string, string) (bool, error) {
+		calls++
+		return pinned, rerr
+	}}
+	ctx := context.Background()
+	if got := rc.ResolveResultContext(ctx, "o", "r", ""); got != Context {
+		t.Fatal(got)
+	}
+	pinned = true
+	if got := rc.ResolveResultContext(ctx, "o", "r", ""); got != Context || calls != 1 {
+		t.Fatalf("cached read expected: %s %d", got, calls)
+	}
+	now = now.Add(ProtectionTTL)
+	if got := rc.ResolveResultContext(ctx, "o", "r", ""); got != WatchContext || calls != 2 {
+		t.Fatalf("pinned after ttl: %s %d", got, calls)
+	}
+	now = now.Add(ProtectionTTL)
+	rerr = errors.New("403")
+	if got := rc.ResolveResultContext(ctx, "o", "r", ""); got != WatchContext {
+		t.Fatal(got)
+	}
+	if got := rc.ResolveResultContext(ctx, "o", "r", "nself-ci"); got != Context {
+		t.Fatal("override wins")
+	}
+}
diff --git a/free/ci/internal/report/sender.go b/free/ci/internal/report/sender.go
index 052d1115d..00323feef 100644
--- a/free/ci/internal/report/sender.go
+++ b/free/ci/internal/report/sender.go
@@ -120,7 +120,7 @@ func (d *Sender) Complete(ctx context.Context, seq int64, s Status) error {
 	if err != nil {
 		return err
 	}
-	if err = d.Store.OutboxReady(ctx, s.Revision, key(s.Owner, s.Repo), seq, body); err != nil {
+	if err = d.Store.OutboxReady(ctx, s.Revision, keyFor(s), seq, body); err != nil {
 		return err
 	}
 	_, err = d.Drain(ctx)
diff --git a/free/ci/internal/run/artifacts_hook.go b/free/ci/internal/run/artifacts_hook.go
index 3b85904ef..94b209ab0 100644
--- a/free/ci/internal/run/artifacts_hook.go
+++ b/free/ci/internal/run/artifacts_hook.go
@@ -190,7 +190,8 @@ func (h *artifactsHook) afterJob(ctx context.Context, a AttemptInfo, workspace *
 	}
 	facts.Producer = "nself-ci/" + a.JobName
 	reserve := func(total int64) error { return a.Store.ArtifactReserve(ctx, a.AttemptID, epoch, total, pol) }
-	staged, err := records.Collector{Blobs: blobs, Scanner: h.scanner(), Policy: pol, Usage: usage, Reserve: reserve}.CollectRoot(ctx, facts.Project, root, decls)
+	staged, err := records.Collector{Blobs: blobs, Scanner: h.scanner(), Policy: pol, Usage: usage, Reserve: reserve,
+		Audit: a.Store.AppendAudit, Target: a.AttemptID}.CollectRoot(ctx, facts.Project, root, decls)
 	if err != nil {
 		return err
 	}
diff --git a/free/ci/internal/run/attempt_test.go b/free/ci/internal/run/attempt_test.go
index 985b797d5..3bb4dbfd2 100644
--- a/free/ci/internal/run/attempt_test.go
+++ b/free/ci/internal/run/attempt_test.go
@@ -15,13 +15,13 @@ import (
 )
 
 // TestCreateAttemptOnly: no non-test Go file outside internal/store,
-// internal/lease, internal/dispatch and internal/run/attempt.go calls
-// AdmitAndLease or the store's CreateAttempt.
+// internal/lease, internal/dispatch, bench/ (harnesses seed a throwaway store)
+// and internal/run/attempt.go calls AdmitAndLease or the store's CreateAttempt.
 func TestCreateAttemptOnly(t *testing.T) {
 	root := filepath.Join("..", "..")
 	allowed := func(path string) bool {
 		p := filepath.ToSlash(path)
-		for _, d := range []string{"/internal/store/", "/internal/lease/", "/internal/dispatch/"} {
+		for _, d := range []string{"/internal/store/", "/internal/lease/", "/internal/dispatch/", "/bench/"} {
 			if strings.Contains(p, d) {
 				return true
 			}
diff --git a/free/ci/internal/run/cache_hook.go b/free/ci/internal/run/cache_hook.go
index a0adc4d89..765d95a5e 100644
--- a/free/ci/internal/run/cache_hook.go
+++ b/free/ci/internal/run/cache_hook.go
@@ -172,7 +172,9 @@ func (h *cacheHook) begin(ctx context.Context, a AttemptInfo, p store.PipelineRo
 	es := entries.New(a.Store, blobs, entries.Options{Home: home, Project: func(string) authz.ProjectFacts { return authz.ProjectFacts{NoPrivateDeps: !priv} }})
 	in := specs.BeginInput{Engine: &specs.Engine{Entries: es, Blobs: blobs, Scanner: h.scanner(), Backend: a.Store}, Attempt: a.AttemptID, Epoch: a.Epoch,
 		Facts: facts, Root: filepath.Join(home, "cache-work", a.AttemptID), Detected: detected, Scope: scope, ExtraKeys: keys, Container: container,
-		Platform: runtime.GOOS + "/" + runtime.GOARCH, Isolation: "process", JobEnv: a.Job.Env, Environ: flatEnv(env), Probe: func(ctx context.Context, argv []string) (string, error) { return h.probe(ctx, a.Job, p.Project, argv) }, Home: h.home(), Getenv: func(k string) string { return env[k] }, Warn: h.warn}
+		Platform: runtime.GOOS + "/" + runtime.GOARCH, Isolation: "process", JobEnv: a.Job.Env, Environ: flatEnv(env), Probe: func(ctx context.Context, argv []string) (string, error) {
+			return h.probeOnce(ctx, a.RunID, a.Job, p.Project, argv)
+		}, Home: h.home(), Getenv: func(k string) string { return env[k] }, Warn: h.warn}
 	if container {
 		in.Platform, in.Isolation, in.Image = "linux/"+runtime.GOARCH, "container", h.imageDigest(ctx, a)
 	}
diff --git a/free/ci/internal/run/cache_hook_probe.go b/free/ci/internal/run/cache_hook_probe.go
new file mode 100644
index 000000000..834a92a6b
--- /dev/null
+++ b/free/ci/internal/run/cache_hook_probe.go
@@ -0,0 +1,85 @@
+package run
+
+// Purpose: run each cache tool probe (`go version` and the like) once per run.
+// P7-CI-46 measured the probe at 40 to 70 ms on macOS (it runs through the
+// exec funnel in a copy of the tree), paid again by every job of the run.
+// Inputs:  the run id, the job (workdir, env), the project root and the argv.
+// Outputs: the probe's output, shared by every job that asks the same question.
+// Constraints: the key holds everything the answer depends on (run, root,
+// workdir, the job's env, argv), so two jobs with a different toolchain pin
+// still probe separately; a failed probe is not remembered; entries older than
+// probeMemoTTL are dropped, so a long-lived coordinator does not grow.
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+const probeMemoTTL = 10 * time.Minute
+
+type probeResult struct {
+	done chan struct{}
+	out  string
+	err  error
+	at   time.Time
+}
+
+var probeMemo struct {
+	mu sync.Mutex
+	m  map[string]*probeResult
+}
+
+func probeKey(runID, root string, job model.Job, argv []string) string {
+	env := make([]string, 0, len(job.Env))
+	for k, v := range job.Env {
+		env = append(env, k+"="+v)
+	}
+	sort.Strings(env)
+	return strings.Join([]string{runID, root, job.Workdir, strings.Join(env, "\x01"), strings.Join(argv, "\x01")}, "\x00")
+}
+
+// probeOnce answers argv for the job from the run's memo, probing on a miss.
+// Concurrent callers with the same key wait for the one probe in flight.
+func (h *cacheHook) probeOnce(ctx context.Context, runID string, job model.Job, root string, argv []string) (string, error) {
+	key := probeKey(runID, root, job, argv)
+	now := time.Now()
+	probeMemo.mu.Lock()
+	if probeMemo.m == nil {
+		probeMemo.m = map[string]*probeResult{}
+	}
+	if r, ok := probeMemo.m[key]; ok {
+		probeMemo.mu.Unlock()
+		select {
+		case <-r.done:
+			if r.err == nil {
+				return r.out, nil
+			}
+		case <-ctx.Done():
+			return "", ctx.Err()
+		}
+		return h.probe(ctx, job, root, argv) // the shared probe failed: ask again
+	}
+	for k, r := range probeMemo.m {
+		if now.Sub(r.at) > probeMemoTTL {
+			delete(probeMemo.m, k)
+		}
+	}
+	r := &probeResult{done: make(chan struct{}), at: now}
+	probeMemo.m[key] = r
+	probeMemo.mu.Unlock()
+	r.out, r.err = h.probe(ctx, job, root, argv)
+	if r.err != nil {
+		probeMemo.mu.Lock()
+		if probeMemo.m[key] == r {
+			delete(probeMemo.m, key)
+		}
+		probeMemo.mu.Unlock()
+	}
+	close(r.done)
+	return r.out, r.err
+}
diff --git a/free/ci/internal/run/cache_hook_session.go b/free/ci/internal/run/cache_hook_session.go
index db3a3ff5f..19f0cf319 100644
--- a/free/ci/internal/run/cache_hook_session.go
+++ b/free/ci/internal/run/cache_hook_session.go
@@ -3,6 +3,7 @@ package run
 import (
 	"context"
 	"os"
+	"sync"
 	"time"
 
 	"github.com/nself-org/plugins/free/ci/internal/model"
@@ -41,25 +42,56 @@ func (h *cacheHook) Wants(a AttemptInfo) bool {
 	return ok && e.(cacheEntry).s.Wants()
 }
 
-// After removes the attempt's cache directories; it saves nothing (closeSession
-// also drops the entry of an attempt that did not settle passed).
+// After removes the attempt's cache directories; it saves nothing (it also
+// drops the entry of an attempt that did not settle passed). The retraction
+// reads the store now; the removal (a restored build cache is tens of MB of
+// small files, P7-CI-46 measured 60 to 95 ms) runs in the background, and the
+// run waits for it before Coordinator.Run returns (waitCacheCleanups).
 func (h *cacheHook) After(ctx context.Context, a AttemptInfo, _ Outcome) error {
 	if e, ok := h.sessions.LoadAndDelete(a.AttemptID); ok {
-		closeSession(ctx, a.Store, e.(cacheEntry))
+		ce := e.(cacheEntry)
+		retractUnpassed(ctx, a.Store, ce)
+		wg := cleanupGroup(a.RunID)
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			ce.s.Cleanup()
+		}()
 	}
 	return nil
 }
 
+// cacheCleanups holds, per run id, the directory removals After started.
+var cacheCleanups sync.Map // run id -> *sync.WaitGroup
+
+func cleanupGroup(runID string) *sync.WaitGroup {
+	wg, _ := cacheCleanups.LoadOrStore(runID, &sync.WaitGroup{})
+	return wg.(*sync.WaitGroup)
+}
+
+// waitCacheCleanups waits for the removals the run's attempts started. Every
+// After of the run happened before its jobs finished, so before this call.
+func waitCacheCleanups(runID string) {
+	if wg, ok := cacheCleanups.LoadAndDelete(runID); ok {
+		wg.(*sync.WaitGroup).Wait()
+	}
+}
+
 // closeSession retracts the entries of an attempt that did not settle passed
-// (a cancel won the finalizing -> passed move after the commit) and removes the
-// attempt's cache directories. After and eviction both end a session this way.
+// and removes the attempt's cache directories (eviction ends a session this way).
 func closeSession(ctx context.Context, st *store.Store, e cacheEntry) {
+	retractUnpassed(ctx, st, e)
+	e.s.Cleanup()
+}
+
+// retractUnpassed retracts the entries of an attempt that did not settle passed
+// (a cancel won the finalizing -> passed move after the commit).
+func retractUnpassed(ctx context.Context, st *store.Store, e cacheEntry) {
 	if e.s.Saved() {
 		if state, ok := settledState(ctx, e, st); ok && state != "passed" { // only a confirmed non-pass retracts
 			e.s.Retract(ctx)
 		}
 	}
-	e.s.Cleanup()
 }
 
 // settledState reads the attempt's state from the store it ran in, falling back
diff --git a/free/ci/internal/run/coordinator.go b/free/ci/internal/run/coordinator.go
index c6d22b680..daf112d78 100644
--- a/free/ci/internal/run/coordinator.go
+++ b/free/ci/internal/run/coordinator.go
@@ -179,12 +179,15 @@ func (c *Coordinator) Run(ctx context.Context) (Result, error) {
 	ciexec.WarmRuntimeInfo() // the first job's orphan sweep asks the daemon: let the answer arrive while git and policy run
 	rev := GitRevision(ctx, c.Opts.Root, c.capture())
 	rev.Dirty = rev.Dirty || c.ConfigOutside
-	rev, release, err := c.offload(ctx, h, rev)
+	checkout, release, err := c.offload(ctx, h, rev) // a snapshot is what nodes check out; the run records rev
 	if err != nil {
 		return Result{}, err
 	}
 	defer release()
-	rev.Dirty = rev.Dirty || c.ConfigOutside // a snapshot revision never hides a config that lives outside the tree
+	rev.Dirty = rev.Dirty || checkout != rev.SHA // a run whose nodes test a snapshot is a dev run: never a status of record
+	// the evidence's start reads git only: it runs beside admission, policy and the store (P7-CI-46)
+	begun := make(chan any, 1)
+	go func() { begun <- c.beginEvidence(ctx, h, rev) }()
 	admitted, source, err := c.classify(ctx, h, rev)
 	if err != nil {
 		return Result{}, err
@@ -208,7 +211,8 @@ func (c *Coordinator) Run(ctx context.Context) (Result, error) {
 	post := c.prepareStatus(ctx, st, rev)
 	_ = st.Heartbeat(ctx, coord.ID)
 	runID := newRunID()
-	defer dispatchRelease(runID) // also closes the dispatcher of a run that ends before AfterRun (D-1044)
+	defer waitCacheCleanups(runID) // the attempts' cache directories are gone when the run returns
+	defer dispatchRelease(runID)   // also closes the dispatcher of a run that ends before AfterRun (D-1044)
 	sess := newSession()
 	mp := c.Plan.ModelPipeline()
 	rows, err := c.persist(ctx, st, runID, rev, source, pol, sess, mp)
@@ -216,7 +220,7 @@ func (c *Coordinator) Run(ctx context.Context) (Result, error) {
 		return Result{}, err
 	}
 	c.exec = newExecutor(staleChecker{st, bootID()}, h.NewRedactor, h.Isolation)
-	sess.Store, sess.Coordinator, sess.Exec, sess.RunID, sess.Revision = st, coord, c.exec, runID, rev.SHA
+	sess.Store, sess.Coordinator, sess.Exec, sess.RunID, sess.Revision, sess.Checkout = st, coord, c.exec, runID, rev.SHA, checkout
 	sess.Host, sess.Home, sess.Admission = hostName(), c.Opts.Home, c.Admission
 	sess.Admission.Force = sess.Admission.Force || c.Opts.Force
 	sess.Plan, sess.Record = c.Plan, c.Opts.Record
@@ -238,7 +242,7 @@ func (c *Coordinator) Run(ctx context.Context) (Result, error) {
 	if subst == nil {
 		subst = func(plan.PlannedJob) bool { return true }
 	}
-	rs := &runState{source: model.TrustClass(source), c: c, sess: sess, hooks: h, pol: pol, pl: c.Plan, mp: mp, rev: rev, rows: rows, subst: subst, render: stampRun(journal(ctx, st, runID, NewRenderer(out, c.Opts)), runID), subset: keep, begin: c.beginEvidence(ctx, h, rev),
+	rs := &runState{source: model.TrustClass(source), c: c, sess: sess, hooks: h, pol: pol, pl: c.Plan, mp: mp, rev: rev, rows: rows, subst: subst, render: stampRun(journal(ctx, st, runID, NewRenderer(out, c.Opts)), runID), subset: keep, begin: <-begun,
 		out: map[string]*JobOutcome{}, done: map[string]chan struct{}{}, marks: map[string]model.Reason{}, cancels: map[string]context.CancelFunc{}, attempts: map[string]string{}}
 	sess.Dirty, sess.ConfigOutside, sess.Subset = rev.Dirty, c.ConfigOutside, keep != nil
 	sess.AdmitTrust = model.TrustClass(admitted)
@@ -250,6 +254,7 @@ func (c *Coordinator) Run(ctx context.Context) (Result, error) {
 	if end := GitRevision(context.WithoutCancel(ctx), c.Opts.Root, c.capture()); end.SHA != rev.SHA || end.Dirty {
 		rev.Dirty = true // the tree moved or changed while jobs ran: the result is not bound to the start commit
 	}
+	post.Notes = append(post.Notes, dispatchNotes(runID)...)
 	res := c.conclude(finishIn{St: st, RunID: runID, Rev: rev, Source: source, Policy: pol, Hooks: h, Jobs: rs.outcomes(),
 		Cancelled: rs.userCancel || ctx.Err() != nil, Partial: c.Opts.Job != "" || c.Opts.Pipeline != "", Start: start, Post: post, Recovered: recovered, Skipped: c.Plan.Skipped, Begin: rs.begin})
 	rs.render.Done(res.Summary)
diff --git a/free/ci/internal/run/dispatch_hook.go b/free/ci/internal/run/dispatch_hook.go
index 9a1cff712..e4cbe63aa 100644
--- a/free/ci/internal/run/dispatch_hook.go
+++ b/free/ci/internal/run/dispatch_hook.go
@@ -48,6 +48,9 @@ type runDispatch struct {
 	qp   schedpolicy.QueuePolicy
 
 	sink *remoteSink // what the carriers of this run's remote leases report to
+
+	notesMu sync.Mutex
+	notes   []string // run notes from delivery (offload_hook_hosted.go)
 }
 
 var (
@@ -76,6 +79,14 @@ func dispatchRelease(runID string) {
 	}
 }
 
+// dispatchWake lets the run's queued jobs tick now: an attempt ended and its
+// host reservation is free.
+func dispatchWake(runID string) {
+	if v, ok := runDispatchers.Load(runID); ok {
+		v.(*runDispatch).d.Wake()
+	}
+}
+
 func dispatchHook(ctx context.Context, s AttemptSpec) (Admitted, error) {
 	if !compat.V15() {
 		return LocalAdmit(ctx, s)
@@ -105,7 +116,7 @@ func dispatchHook(ctx context.Context, s AttemptSpec) (Admitted, error) {
 			_ = sess.Store.SetPreviousRunner(ctx, id, prev)
 		}
 	}
-	rd.sink.expect(id, sess.Revision) // a remote carrier may report before this call returns
+	rd.sink.expect(id, sess.checkoutRevision()) // a remote carrier may report before this call returns; its evidence names the checkout
 	a, err := rd.d.Submit(ctx, queueJob(sess, s, sj, id,
 		max(dec.Slots*cpu, cpu), max(capacity.FreeMemoryMB-capacity.MemoryMB*dec.ReserveMemoryPercent/100, mem)))
 	if err != nil || a.Local {
@@ -120,7 +131,7 @@ func dispatchHook(ctx context.Context, s AttemptSpec) (Admitted, error) {
 // queueJob is the dispatcher's input for one attempt. Only an interactive run
 // (a person at a terminal) keeps the implicit foreground queue cap.
 func queueJob(sess *Session, s AttemptSpec, sj sched.Job, id string, localCPU, localMemMB int) dispatch.Job {
-	return dispatch.Job{AttemptID: id, Sched: sj, Model: *s.Job, Revision: sess.Revision, Foreground: s.Foreground,
+	return dispatch.Job{AttemptID: id, Sched: sj, Model: *s.Job, Revision: sess.checkoutRevision(), Foreground: s.Foreground,
 		NoDefaultQueueCap: !sess.Interactive, LocalCPU: localCPU, LocalMemMB: localMemMB}
 }
 
@@ -174,7 +185,7 @@ func runDispatcher(ctx context.Context, sess *Session) (*runDispatch, error) {
 	rd.d, err = dispatch.New(dispatch.Config{Store: sess.Store, Host: sess.Host, World: rd.world, Poll: sess.Poll, LeaseTTL: RemoteLeaseTTL, Queue: rd.queue,
 		Slots:         func() int { return rd.sess.Capacity().CPUs },
 		Incarnation:   func() int64 { return highestIncarnation(rd.sess.Store) },
-		Transport:     newTransportAdapter(rd.sink, rd.sink, rd.row.Project),
+		Transport:     transportAdapter{sink: rd.sink, reg: rd.sink, root: rd.row.Project, st: rd.sink.st, hosted: rd.hostedRevision},
 		DeliveryError: func(a dispatch.Admitted, err error) { rd.sink.ended(a.AttemptID, err) }})
 	if err != nil {
 		return nil, err
@@ -210,6 +221,8 @@ type transportAdapter struct {
 	reg  carriers
 	root string       // the repository whose revision a node receives
 	st   *store.Store // the run's store: the attempt facts the lease's evidence context repeats (nil: none)
+	// hosted maps the revision of a lease to a hosted runner (nil = unchanged): see offload_hook_hosted.go.
+	hosted func(attemptID, revision string) string
 }
 
 func (transportAdapter) Known(kind string) bool {
@@ -231,6 +244,9 @@ func (a transportAdapter) Deliver(ctx context.Context, d dispatch.Delivery) erro
 	if _, err := netscope.RunScope(d.Trust, d.Network); err != nil {
 		return err
 	}
+	if d.Hosted && a.hosted != nil {
+		d.Revision = a.hosted(d.AttemptID, d.Revision)
+	}
 	refs, err := leaseSecretRefs(d)
 	if err != nil {
 		return err
diff --git a/free/ci/internal/run/evidence.go b/free/ci/internal/run/evidence.go
index 25ade2d65..01a534c27 100644
--- a/free/ci/internal/run/evidence.go
+++ b/free/ci/internal/run/evidence.go
@@ -32,6 +32,8 @@ type evidenceInput struct {
 	Selection                                                    model.Selection
 	Trigger                                                      model.Trigger
 	Jobs                                                         []JobOutcome
+	Attempts                                                     []model.AttemptEvidence // runner and timings per attempt (P7-AUTO-21)
+	Errors                                                       []model.EvidenceError
 	Start, End                                                   time.Time
 }
 
@@ -104,6 +106,11 @@ func buildEvidence(in evidenceInput) (model.Evidence, string, error) {
 			Substantive: o.Substantive, AllowFailure: o.AllowFailure, Result: checkResult(o), Reason: o.Reason, FailureClass: o.FailureClass}
 		if o.State == StateFailed || o.Code != "" {
 			c.Excerpt = diagnose.Excerpt(o.Tail, maxExcerpt) // the tail already passed the exec funnel's redactor (D-0948, P7-TRUST-19)
+			if c.Excerpt == "" && o.Detail != "" {
+				// The job printed nothing: it never started, or the executor failed around it. The error text
+				// is then the only cause there is, so it is the excerpt (an infra.executor check was empty).
+				c.Excerpt = diagnose.Excerpt(o.Detail, maxExcerpt)
+			}
 			attachDiagnosis(&c, o)
 		}
 		c.Flaky = o.Flaky
@@ -125,6 +132,7 @@ func buildEvidence(in evidenceInput) (model.Evidence, string, error) {
 		e.Retries = append(e.Retries, o.Retries...)
 	}
 	e.Counts.Total = len(e.Checks)
+	e.Attempts, e.Errors = sortedAttempts(in.Attempts), sortedErrors(in.Errors)
 	e.Result = runResult(e.Checks)
 	if in.Cancelled {
 		e.Result = "cancelled"
@@ -180,3 +188,38 @@ func attachDiagnosis(c *model.Check, o JobOutcome) {
 		c.LogRef = &ref
 	}
 }
+
+// sortedAttempts copies the attempt records in a stable order (job, attempt);
+// none yields nil so the additive key is absent, as in an older document.
+func sortedAttempts(in []model.AttemptEvidence) []model.AttemptEvidence {
+	if len(in) == 0 {
+		return nil
+	}
+	out := append([]model.AttemptEvidence(nil), in...)
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].JobID != out[j].JobID {
+			return out[i].JobID < out[j].JobID
+		}
+		return out[i].Attempt < out[j].Attempt
+	})
+	return out
+}
+
+// sortedErrors copies the coded errors in a stable order (job, attempt, code).
+func sortedErrors(in []model.EvidenceError) []model.EvidenceError {
+	if len(in) == 0 {
+		return nil
+	}
+	out := append([]model.EvidenceError(nil), in...)
+	sort.SliceStable(out, func(i, j int) bool {
+		a, b := out[i], out[j]
+		if a.JobID != b.JobID {
+			return a.JobID < b.JobID
+		}
+		if a.Attempt != b.Attempt {
+			return a.Attempt < b.Attempt
+		}
+		return a.Code < b.Code
+	})
+	return out
+}
diff --git a/free/ci/internal/run/evidence_attempts_test.go b/free/ci/internal/run/evidence_attempts_test.go
new file mode 100644
index 000000000..47d02e7b8
--- /dev/null
+++ b/free/ci/internal/run/evidence_attempts_test.go
@@ -0,0 +1,54 @@
+package run
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+func i64(v int64) *int64 { return &v }
+
+// TestEvidenceRunnerTierPool: the attempt records reach the document in a
+// stable order, validate against the schema, and are absent when none exist.
+func TestEvidenceRunnerTierPool(t *testing.T) {
+	start := time.Date(2026, 10, 28, 0, 0, 0, 0, time.UTC)
+	in := evidenceInput{Revision: strings.Repeat("a", 40), Start: start, End: start, Trigger: "local",
+		Pipeline:  model.PipelineRef{ID: "default", Name: "default", Kind: "default"},
+		Selection: model.Selection{Mode: "full", Reason: "selection.no_base"},
+		Attempts: []model.AttemptEvidence{
+			{JobID: "test", Attempt: 2, Runner: model.AttemptRunner{Kind: "hosted", Tier: "hosted", Pool: "github", Rank: 2}, Timings: &model.AttemptTimings{QueueMS: i64(5), RunMS: i64(9)}},
+			{JobID: "test", Attempt: 1, Runner: model.AttemptRunner{Kind: "ssh", Tier: "owner", Pool: "lab", Rank: 1}},
+			{JobID: "build", Attempt: 1, Runner: model.AttemptRunner{Kind: "local", Tier: "owner", Pool: "personal", Rank: 0}},
+		},
+		Errors: []model.EvidenceError{{Code: "CI-INFRA-OOM", JobID: "test", Attempt: 1}}}
+	ev, _, err := buildEvidence(in)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := []string{}
+	for _, a := range ev.Attempts {
+		got = append(got, a.JobID+"/"+a.Runner.Kind+"/"+a.Runner.Pool)
+	}
+	if want := "build/local/personal test/ssh/lab test/hosted/github"; strings.Join(got, " ") != want {
+		t.Errorf("attempts %v, want %s", got, want)
+	}
+	schema, err := os.ReadFile(filepath.Join("..", "..", "schemas", "ci-evidence.v1.schema.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc, _ := json.Marshal(ev)
+	if err := model.ValidateJSON(schema, doc); err != nil {
+		t.Errorf("document with attempts: %v", err)
+	}
+	in.Attempts, in.Errors = nil, nil
+	ev, _, _ = buildEvidence(in)
+	doc, _ = json.Marshal(ev)
+	if strings.Contains(string(doc), `"attempts"`) || strings.Contains(string(doc), `"errors"`) {
+		t.Error("without records the additive keys must be absent")
+	}
+}
diff --git a/free/ci/internal/run/evidence_detail_test.go b/free/ci/internal/run/evidence_detail_test.go
new file mode 100644
index 000000000..88f51675c
--- /dev/null
+++ b/free/ci/internal/run/evidence_detail_test.go
@@ -0,0 +1,35 @@
+package run
+
+// Purpose: a failed job that printed nothing still explains itself in the evidence.
+// Inputs: outcomes with and without a tail. Outputs: the check's excerpt.
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestEvidenceExcerptFallsBackToDetail(t *testing.T) {
+	start := time.Date(2026, 10, 29, 0, 0, 0, 0, time.UTC)
+	cases := []struct {
+		name string
+		o    JobOutcome
+		want string
+	}{
+		{"empty tail takes the error text", JobOutcome{ID: "a", State: StateFailed, FailureClass: "infra", Detail: "E612: workdir escapes workspace"}, "E612: workdir escapes workspace"},
+		{"a tail wins over the error text", JobOutcome{ID: "b", State: StateFailed, FailureClass: "code", ExitCode: 1, Tail: "FAIL: TestX\n", Detail: "ignored"}, "FAIL: TestX"},
+		{"a passed job carries no excerpt", JobOutcome{ID: "c", State: StatePassed, Detail: "ignored"}, ""},
+	}
+	for _, tc := range cases {
+		ev, _, err := buildEvidence(evidenceInput{Jobs: []JobOutcome{tc.o}, Start: start, End: start})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if got := ev.Checks[0].Excerpt; got != tc.want {
+			t.Errorf("%s: excerpt %q, want %q", tc.name, got, tc.want)
+		}
+		if len(ev.Checks[0].Excerpt) > maxExcerpt || strings.Contains(ev.Checks[0].Excerpt, "\x00") {
+			t.Errorf("%s: excerpt out of bounds", tc.name)
+		}
+	}
+}
diff --git a/free/ci/internal/run/hooks_auto.go b/free/ci/internal/run/hooks_auto.go
index c744b0f8f..632948108 100644
--- a/free/ci/internal/run/hooks_auto.go
+++ b/free/ci/internal/run/hooks_auto.go
@@ -57,8 +57,12 @@ type OffloadRequest struct {
 	Rev  Revision
 }
 
-// OffloadResult replaces the run's revision when Rev.SHA is set (a snapshot
-// commit of a dirty tree). Release runs when the run ends; it may be nil.
+// OffloadResult names, when Rev.SHA is set, the revision a node checks out
+// for this run (a snapshot commit of a dirty tree). The run itself keeps
+// recording the committed revision it started from, dirty and unbound: a
+// reproduction never uses uncommitted changes (P7-CI-41), and the snapshot is
+// unreachable once Release deletes its ref. Release runs when the run ends;
+// it may be nil.
 type OffloadResult struct {
 	Rev     Revision
 	Release func()
@@ -147,10 +151,11 @@ func (h AutoHooks) resolved(r AutoHooks) AutoHooks {
 	return out
 }
 
-// offload runs the offload hook; the returned release is never nil.
-func (c *Coordinator) offload(ctx context.Context, h Hooks, rev Revision) (Revision, func(), error) {
+// offload runs the offload hook and returns the revision nodes check out
+// (rev.SHA when no snapshot was made); the returned release is never nil.
+func (c *Coordinator) offload(ctx context.Context, h Hooks, rev Revision) (string, func(), error) {
 	if h.Auto.Offload == nil {
-		return rev, func() {}, nil
+		return rev.SHA, func() {}, nil
 	}
 	var res OffloadResult
 	err := guard("offload hook", func() (e error) {
@@ -158,15 +163,16 @@ func (c *Coordinator) offload(ctx context.Context, h Hooks, rev Revision) (Revis
 		return
 	})
 	if err != nil {
-		return rev, func() {}, err
+		return rev.SHA, func() {}, err
 	}
+	checkout := rev.SHA
 	if res.Rev.SHA != "" {
-		rev = res.Rev
+		checkout = res.Rev.SHA
 	}
 	if res.Release == nil {
 		res.Release = func() {}
 	}
-	return rev, res.Release, nil
+	return checkout, res.Release, nil
 }
 
 // race calls the race hook, if any.
diff --git a/free/ci/internal/run/hooks_slots_test.go b/free/ci/internal/run/hooks_slots_test.go
index 4fb557561..95dd3b325 100644
--- a/free/ci/internal/run/hooks_slots_test.go
+++ b/free/ci/internal/run/hooks_slots_test.go
@@ -110,15 +110,20 @@ func passRig(t *testing.T) *rig {
 // TestHookSlotsNoop: with nothing registered, and with slots that do nothing,
 // the run posts the same status and ends with the same verdict.
 func TestHookSlotsNoop(t *testing.T) {
-	// the notify hook (P7-AUTO-18) and the App checks detail publisher (P7-AUTO-22) are the slots the shipped
-	// build fills; both are inert without v1.5 and their operator keys
+	// the notify hook (P7-AUTO-18), the App checks detail publisher (P7-AUTO-22) and the pools.record
+	// publish gate (P7-AUTO-15) are the slots the shipped run package fills; all are inert without v1.5
+	// and their operator keys or pool records
 	_, notifyOK := Registered.Auto.Notify.(*notifyHook)
 	detailOK := len(Registered.Auto.Details) == 1
 	if detailOK {
 		_, detailOK = Registered.Auto.Details[0].(*checksDetail)
 	}
-	if len(Registered.Auto.Gates) != 0 || Registered.Auto.Offload != nil || Registered.Auto.Race != nil || !notifyOK || !detailOK {
-		t.Fatal("the shipped build must register no AUTO slot but the notify hook and the checks detail publisher")
+	gateOK := len(Registered.Auto.Gates) == 1
+	if gateOK {
+		_, gateOK = Registered.Auto.Gates[0].(RecordGate)
+	}
+	if !gateOK || Registered.Auto.Offload != nil || Registered.Auto.Race != nil || !notifyOK || !detailOK {
+		t.Fatal("the shipped build must register no AUTO slot but the notify hook, the checks detail publisher and the record gate")
 	}
 	base := passRig(t)
 	want := base.run(t)
@@ -235,7 +240,8 @@ func TestPublishGateComposes(t *testing.T) {
 }
 
 // TestOffloadAndNotifyFailures: an offload error refuses the run before anything runs; a
-// replaced revision is the one the run binds to; a failing or panicking notify hook is a note.
+// snapshot revision is only what nodes check out (the run records HEAD, dirty and unbound);
+// a failing or panicking notify hook is a note.
 func TestOffloadAndNotifyFailures(t *testing.T) {
 	l := &slotLog{}
 	r := passRig(t)
@@ -254,6 +260,9 @@ func TestOffloadAndNotifyFailures(t *testing.T) {
 	if released != 1 || len(r.Rep.all()) != 0 || !strings.Contains(res.Summary.Status, "not posted") {
 		t.Fatalf("a snapshot revision is dev evidence and is released once: released %d status %q", released, res.Summary.Status)
 	}
+	if res.Summary.Doc.Revision != testSHA {
+		t.Fatalf("the run recorded %q: a snapshot is unreachable after release, so the run records HEAD %s", res.Summary.Doc.Revision, testSHA)
+	}
 
 	for name, n := range map[string]fakeNotify{"error": {l: l, err: errors.New("sink down")}, "panic": {l: l, panic: true}} {
 		r = passRig(t)
diff --git a/free/ci/internal/run/jobrun.go b/free/ci/internal/run/jobrun.go
index 724e504b3..03382b169 100644
--- a/free/ci/internal/run/jobrun.go
+++ b/free/ci/internal/run/jobrun.go
@@ -51,7 +51,13 @@ func (rs *runState) trans(id string, from, to model.JobState, class model.Failur
 	if state != from {
 		return fail(CodeRun, "attempt %s is %s, not %s", id, state, from)
 	}
-	return rs.sess.Store.Transition(bg, id, from, to, store.TransitionDetail{Epoch: epoch, FailureClass: class})
+	if err = rs.sess.Store.Transition(bg, id, from, to, store.TransitionDetail{Epoch: epoch, FailureClass: class}); err != nil {
+		return err
+	}
+	if to == "passed" || to == "failed" || to == "cancelled" || to == "lost" { // the store freed the host reservation
+		dispatchWake(rs.sess.RunID)
+	}
+	return nil
 }
 
 // settle ends an attempt that is in state `from`. A committed cancel intent
diff --git a/free/ci/internal/run/offload_checkout_test.go b/free/ci/internal/run/offload_checkout_test.go
new file mode 100644
index 000000000..acb245bff
--- /dev/null
+++ b/free/ci/internal/run/offload_checkout_test.go
@@ -0,0 +1,87 @@
+package run
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// TestOffloadCheckoutRevision: a node's lease checks out the snapshot and its
+// evidence must name it, while the run's own revision stays the commit
+// (P7-AUTO-13, P7-CI-41). Without a snapshot the lease checks out the run's revision.
+func TestOffloadCheckoutRevision(t *testing.T) {
+	const head, snap = "1111111111111111111111111111111111111111", "2222222222222222222222222222222222222222"
+	job := &model.Job{}
+	if got := queueJob(&Session{Revision: head, Checkout: snap}, AttemptSpec{Job: job}, sched.Job{}, "a1", 1, 1).Revision; got != snap {
+		t.Errorf("lease revision %q, want the snapshot", got)
+	}
+	if got := queueJob(&Session{Revision: head}, AttemptSpec{Job: job}, sched.Job{}, "a1", 1, 1).Revision; got != head {
+		t.Errorf("lease revision %q, want HEAD without a snapshot", got)
+	}
+	s := &remoteSink{by: map[string]*remoteAttempt{}}
+	if ra := s.expect("a1", (&Session{Revision: head, Checkout: snap}).checkoutRevision()); ra.revision != snap {
+		t.Errorf("the sink expects %q, want the snapshot the node checked out", ra.revision)
+	}
+}
+
+// TestHostedLeaseNeverGetsSnapshot: with a dirty-tree snapshot in the run, a lease
+// delivered to an enrolled node checks out the snapshot, while a lease delivered to a
+// hosted runner checks out the committed HEAD (a hosted runner fetches from the
+// forge, where no snapshot exists), its evidence must name HEAD, and the run notes
+// say the dirty changes were not included. A run without a snapshot is unchanged.
+// The run engine itself does not place a foreground dev run on a hosted runner today
+// (dropProviderRunners, and privacy.hosted_not_authorized outside a public
+// repository), so the delivery boundary, where Hosted is known, is what is tested.
+func TestHostedLeaseNeverGetsSnapshot(t *testing.T) {
+	const head, snap = "1111111111111111111111111111111111111111", "2222222222222222222222222222222222222222"
+	probe := &probeDriver{kind: fmt.Sprintf("offloadprobe%d", time.Now().UnixNano())}
+	if err := transport.Register(probe); err != nil {
+		t.Fatal(err)
+	}
+	var node model.Capability
+	node.Identity.ID, node.Identity.Transport = "x1", probe.kind
+	deliver := func(t *testing.T, rd *runDispatch, attempt, revision string, hosted bool) (lease, expected string) {
+		t.Helper()
+		rd.sink.expect(attempt, revision)
+		d := deliveryFor(node, model.Job{Kind: "test", Run: []string{"true"}})
+		d.AttemptID, d.LeaseID, d.Revision, d.Hosted = attempt, "lease-"+attempt, revision, hosted
+		ad := transportAdapter{hosted: rd.hostedRevision}
+		if err := ad.Deliver(context.Background(), d); err != nil {
+			t.Fatal(err)
+		}
+		probe.mu.Lock()
+		defer probe.mu.Unlock()
+		return probe.lease.Checkout.Revision, rd.sink.attempt(attempt).revision
+	}
+	newRD := func(id, checkout string) *runDispatch {
+		rd := &runDispatch{sess: &Session{RunID: id, Revision: head, Checkout: checkout}, sink: &remoteSink{by: map[string]*remoteAttempt{}}}
+		runDispatchers.Store(id, rd)
+		t.Cleanup(func() { runDispatchers.Delete(id) })
+		return rd
+	}
+
+	rd := newRD("r-offload-hosted", snap)
+	if lease, want := deliver(t, rd, "a1", snap, false); lease != snap || want != snap {
+		t.Errorf("node lease %s expects %s: want the snapshot", lease, want)
+	}
+	if n := dispatchNotes("r-offload-hosted"); len(n) != 0 {
+		t.Errorf("a node placement noted %v", n)
+	}
+	if lease, want := deliver(t, rd, "a2", snap, true); lease != head || want != head {
+		t.Errorf("hosted lease %s expects %s: want HEAD %s, never the snapshot", lease, want, head)
+	}
+	deliver(t, rd, "a3", snap, true)
+	if n := dispatchNotes("r-offload-hosted"); len(n) != 1 || n[0] != HostedDirtyNote {
+		t.Errorf("notes %v, want the hosted note once", n)
+	}
+
+	clean := newRD("r-offload-clean", "")
+	if lease, want := deliver(t, clean, "a1", head, true); lease != head || want != head || len(dispatchNotes("r-offload-clean")) != 0 {
+		t.Errorf("a run without a snapshot: hosted lease %s expects %s notes %v", lease, want, dispatchNotes("r-offload-clean"))
+	}
+}
diff --git a/free/ci/internal/run/offload_hook.go b/free/ci/internal/run/offload_hook.go
new file mode 100644
index 000000000..78a211411
--- /dev/null
+++ b/free/ci/internal/run/offload_hook.go
@@ -0,0 +1,62 @@
+package run
+
+// Purpose: the OffloadHook implementation for dev runs (P7-AUTO-13): a dirty
+// tree becomes a snapshot revision, without run importing internal/offload.
+// Inputs:  the request's Options.Root and the Revision GitRevision read.
+// Outputs: an OffloadResult whose Rev is the snapshot and Release deletes the
+// private ref; the excluded names go to Notes.
+// Constraints: a clean revision or a nil Build keeps the HEAD path; a Build
+// error refuses the run, so a node never tests a tree other than the user's.
+// A snapshot run is a dev run: unbound evidence, never a status of record.
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+// OffloadSnapshot is what the snapshot builder returns.
+type OffloadSnapshot struct {
+	SHA      string
+	Excluded []string
+	Release  func(context.Context) error
+}
+
+// SnapshotOffload is the OffloadHook backed by an injected snapshot builder.
+type SnapshotOffload struct {
+	// Build makes the snapshot of a dirty root (internal/offload via cmd wiring).
+	Build func(ctx context.Context, root string) (*OffloadSnapshot, error)
+	// Excluded receives the names left out of the snapshot (nil: dropped).
+	Excluded func(names []string)
+}
+
+// Offload implements OffloadHook.
+func (s SnapshotOffload) Offload(ctx context.Context, r OffloadRequest) (OffloadResult, error) {
+	if !r.Rev.Dirty || s.Build == nil {
+		return OffloadResult{}, nil
+	}
+	var snap *OffloadSnapshot
+	if err := guard("offload hook", func() (e error) { snap, e = s.Build(ctx, r.Opts.Root); return e }); err != nil {
+		return OffloadResult{}, err
+	}
+	if snap == nil || !fullSHA.MatchString(snap.SHA) {
+		return OffloadResult{}, nil
+	}
+	if s.Excluded != nil && len(snap.Excluded) > 0 {
+		s.Excluded(snap.Excluded)
+	}
+	res := OffloadResult{Rev: Revision{SHA: snap.SHA, Dirty: true}}
+	if snap.Release != nil {
+		res.Release = func() { _ = snap.Release(context.WithoutCancel(ctx)) }
+	}
+	return res, nil
+}
+
+// StatusOfRecord is always false for a snapshot run (CI-37 dirty-tree rule).
+func StatusOfRecord(r Revision) bool { return !r.Dirty }
+
+// DevSummary is the local summary of a failing dev job: the gate's exit code
+// and the log tail.
+func DevSummary(job string, exit int, tail string) string {
+	return fmt.Sprintf("%s failed (exit %d)\n%s", job, exit, strings.TrimRight(tail, "\n"))
+}
diff --git a/free/ci/internal/run/offload_hook_hosted.go b/free/ci/internal/run/offload_hook_hosted.go
new file mode 100644
index 000000000..f22c95f66
--- /dev/null
+++ b/free/ci/internal/run/offload_hook_hosted.go
@@ -0,0 +1,51 @@
+package run
+
+// Purpose: a hosted runner never receives a dirty-tree snapshot (P7-AUTO-13).
+// A hosted runner fetches the revision from the forge, where a snapshot never
+// exists; when placement picks one for a run whose nodes check out a snapshot,
+// the lease carries the commit the run started from instead, the run expects
+// evidence naming that commit, and the run output says the dirty changes were
+// not included.
+// Inputs:  the attempt id and the revision the dispatcher put on the lease.
+// Outputs: the revision the hosted lease checks out; a run note.
+// Constraints: a lease to an enrolled node is never changed; a run without a
+// snapshot is never changed. The note is printed once per run.
+
+import "slices"
+
+// HostedDirtyNote is the run note when a hosted runner gets HEAD without the
+// uncommitted changes of a dirty tree.
+const HostedDirtyNote = "dirty changes not included: hosted runner"
+
+// hostedRevision is the transport adapter's hosted hook for this run.
+func (rd *runDispatch) hostedRevision(attemptID, revision string) string {
+	snap := rd.sess.Checkout
+	if snap == "" || snap == rd.sess.Revision || revision != snap {
+		return revision
+	}
+	if ra := rd.sink.attempt(attemptID); ra != nil {
+		ra.revision = rd.sess.Revision // the hosted runner's evidence names the commit it fetched
+	}
+	rd.note(HostedDirtyNote)
+	return rd.sess.Revision
+}
+
+func (rd *runDispatch) note(n string) {
+	rd.notesMu.Lock()
+	defer rd.notesMu.Unlock()
+	if !slices.Contains(rd.notes, n) {
+		rd.notes = append(rd.notes, n)
+	}
+}
+
+// dispatchNotes returns the delivery notes of a run whose dispatcher is still open.
+func dispatchNotes(runID string) []string {
+	v, ok := runDispatchers.Load(runID)
+	if !ok {
+		return nil
+	}
+	rd := v.(*runDispatch)
+	rd.notesMu.Lock()
+	defer rd.notesMu.Unlock()
+	return append([]string(nil), rd.notes...)
+}
diff --git a/free/ci/internal/run/offload_hook_test.go b/free/ci/internal/run/offload_hook_test.go
new file mode 100644
index 000000000..51ee7b7ef
--- /dev/null
+++ b/free/ci/internal/run/offload_hook_test.go
@@ -0,0 +1,59 @@
+package run
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+const snapSHA = "0123456789abcdef0123456789abcdef01234567"
+
+func TestDirtyRunNoStatus(t *testing.T) {
+	released := 0
+	var names []string
+	h := SnapshotOffload{
+		Build: func(_ context.Context, root string) (*OffloadSnapshot, error) {
+			if root != "/r" {
+				t.Errorf("root %q", root)
+			}
+			return &OffloadSnapshot{SHA: snapSHA, Excluded: []string{".env.local"}, Release: func(context.Context) error { released++; return nil }}, nil
+		},
+		Excluded: func(n []string) { names = n },
+	}
+	var _ OffloadHook = h
+	res, err := h.Offload(context.Background(), OffloadRequest{Opts: Options{Root: "/r"}, Rev: Revision{SHA: strings.Repeat("a", 40), Dirty: true}})
+	if err != nil || res.Rev.SHA != snapSHA || !res.Rev.Dirty || StatusOfRecord(res.Rev) {
+		t.Fatalf("result %+v %v", res, err)
+	}
+	res.Release()
+	if released != 1 || len(names) != 1 {
+		t.Fatalf("released %d excluded %v", released, names)
+	}
+}
+
+func TestOffloadPassThroughAndRefusal(t *testing.T) {
+	clean := Revision{SHA: strings.Repeat("b", 40)}
+	boom := SnapshotOffload{Build: func(context.Context, string) (*OffloadSnapshot, error) { panic("not for a clean tree") }}
+	if res, err := boom.Offload(context.Background(), OffloadRequest{Rev: clean}); err != nil || res.Rev.SHA != "" || !StatusOfRecord(clean) {
+		t.Fatalf("clean: %+v %v", res, err)
+	}
+	refuse := SnapshotOffload{Build: func(context.Context, string) (*OffloadSnapshot, error) {
+		return nil, errors.New("E807: tracked file refused")
+	}}
+	if _, err := refuse.Offload(context.Background(), OffloadRequest{Rev: Revision{SHA: clean.SHA, Dirty: true}}); CodeOf(err) != "E807" {
+		t.Fatalf("err = %v", err)
+	}
+	if res, err := (SnapshotOffload{}).Offload(context.Background(), OffloadRequest{Rev: Revision{SHA: clean.SHA, Dirty: true}}); err != nil || res.Rev.SHA != "" {
+		t.Fatalf("nil build: %+v %v", res, err)
+	}
+	if _, err := boom.Offload(context.Background(), OffloadRequest{Rev: Revision{SHA: clean.SHA, Dirty: true}}); err == nil {
+		t.Fatal("panic must refuse the run")
+	}
+}
+
+func TestDevSummary(t *testing.T) {
+	if got := DevSummary("unit", 3, "boom\n"); !strings.Contains(got, "exit 3") || !strings.HasSuffix(got, "boom") {
+		t.Fatalf("summary %q", got)
+	}
+}
diff --git a/free/ci/internal/run/race_hook.go b/free/ci/internal/run/race_hook.go
new file mode 100644
index 000000000..a305afa4a
--- /dev/null
+++ b/free/ci/internal/run/race_hook.go
@@ -0,0 +1,90 @@
+package run
+
+// Purpose: the run side of race mode (P7-AUTO-14), without run importing
+// internal/race: sibling attempts of one job are made by CreateAttempt (the
+// only attempt creator), cancelled through the durable lease cancel intent
+// (the node kills the attempt's process group, NODE-23), and read back.
+// Inputs:  a context holding the run Session and an AttemptSpec template.
+// Outputs: RaceSibling values carrying the lease epoch that fences a cancel.
+// Constraints: a release or idempotent:false job is never raced (CACHE-05
+// at-most-once): Create refuses it before anything is persisted. Cancel is
+// idempotent: a repeat, or a cancel that lost to the result commit (E605), is
+// not an error. Nothing here posts a status.
+
+import (
+	"context"
+	"errors"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// RaceSibling is one admitted sibling attempt and the epoch its lease holds.
+type RaceSibling struct {
+	Admitted
+	N     int
+	Epoch int64
+}
+
+// RaceAttempts makes and stops the siblings of one job of the session in the context.
+type RaceAttempts struct {
+	// Spec is the template of every sibling: Pipeline, Job, Foreground and Band; N is set per sibling.
+	Spec AttemptSpec
+	// Pin carries the runner a sibling is meant for into the dispatch hook's
+	// placement request (nil: the context is unchanged).
+	Pin func(ctx context.Context, runner string) context.Context
+}
+
+// Raceable says job may have sibling attempts: never a release or idempotent:false job.
+func Raceable(job *model.Job) bool { return job != nil && retryable(*job) }
+
+// Create makes sibling n through CreateAttempt and reads its lease epoch.
+func (r RaceAttempts) Create(ctx context.Context, n int, runner string) (RaceSibling, error) {
+	if !Raceable(r.Spec.Job) {
+		return RaceSibling{}, fail(CodeRun, "a release or idempotent:false job is never raced")
+	}
+	s := r.Spec
+	s.N = n
+	if r.Pin != nil {
+		ctx = r.Pin(ctx, runner)
+	}
+	adm, err := CreateAttempt(ctx, s)
+	if err != nil {
+		return RaceSibling{}, err
+	}
+	_, epoch, err := SessionFrom(ctx).Store.AttemptStateEpoch(ctx, adm.AttemptID)
+	if err != nil {
+		return RaceSibling{}, err
+	}
+	return RaceSibling{Admitted: adm, N: n, Epoch: epoch}, nil
+}
+
+// Cancel writes the lease cancel intent of a sibling, fenced by its epoch.
+func (r RaceAttempts) Cancel(ctx context.Context, attemptID string, epoch int64, reason string) error {
+	sess := SessionFrom(ctx)
+	if sess == nil {
+		return fail(CodeRun, "no run session in the context")
+	}
+	err := retryBusy(func() error { return sess.Store.RequestCancel(ctx, attemptID, "race: "+reason, epoch) })
+	if err != nil && CodeOf(err) == codeStoreRef {
+		return nil // already requested, the epoch moved or the result is committed: nothing left to stop
+	}
+	return err
+}
+
+// State reads a sibling's state and failure class.
+func (r RaceAttempts) State(ctx context.Context, attemptID string) (state, class string, err error) {
+	sess := SessionFrom(ctx)
+	if sess == nil {
+		return "", "", errors.New("no run session in the context")
+	}
+	attempts, err := sess.Store.PipelineAttempts(ctx, sess.RunID)
+	if err != nil {
+		return "", "", err
+	}
+	for _, a := range attempts {
+		if a.ID == attemptID {
+			return string(a.State), a.FailureClass, nil
+		}
+	}
+	return "", "", fail(CodeRun, "attempt %s is not part of this run", attemptID)
+}
diff --git a/free/ci/internal/run/race_hook_test.go b/free/ci/internal/run/race_hook_test.go
new file mode 100644
index 000000000..26f319555
--- /dev/null
+++ b/free/ci/internal/run/race_hook_test.go
@@ -0,0 +1,44 @@
+package run
+
+import (
+	"context"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+func TestRaceableNeverAtMostOnce(t *testing.T) {
+	no, yes := false, true
+	cases := map[string]struct {
+		job  *model.Job
+		want bool
+	}{
+		"nil":            {nil, false},
+		"plain":          {&model.Job{}, true},
+		"idempotent":     {&model.Job{Idempotent: &yes}, true},
+		"release":        {&model.Job{Kind: "release"}, false},
+		"not idempotent": {&model.Job{Idempotent: &no}, false},
+	}
+	for name, c := range cases {
+		if got := Raceable(c.job); got != c.want {
+			t.Errorf("%s: Raceable = %v, want %v", name, got, c.want)
+		}
+	}
+}
+
+func TestRaceAttemptsRefuseRelease(t *testing.T) {
+	ra := RaceAttempts{Spec: AttemptSpec{Job: &model.Job{Kind: "release"}}}
+	if _, err := ra.Create(context.Background(), 2, "n1"); err == nil {
+		t.Fatal("a sibling of a release job was created")
+	}
+}
+
+func TestRaceAttemptsNeedSession(t *testing.T) {
+	ra := RaceAttempts{}
+	if err := ra.Cancel(context.Background(), "a", 1, "lost"); err == nil {
+		t.Fatal("cancel without a session succeeded")
+	}
+	if _, _, err := ra.State(context.Background(), "a"); err == nil {
+		t.Fatal("state without a session succeeded")
+	}
+}
diff --git a/free/ci/internal/run/record_gate.go b/free/ci/internal/run/record_gate.go
new file mode 100644
index 000000000..7ae2d06c1
--- /dev/null
+++ b/free/ci/internal/run/record_gate.go
@@ -0,0 +1,223 @@
+package run
+
+// Purpose: compose record-pool admission and publication checks with attest.Publish.
+// Inputs: the session, protected project policy and durable attempt lease holders.
+// Outputs: exclusions before delivery and E809 publication refusals with evidence.
+// Constraints: V15 only; a missing fact never authorizes a status of record.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync"
+
+	compat "github.com/nself-org/cli/sdk/go/v2/compat"
+	"github.com/nself-org/plugins/free/ci/internal/autoworld"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/pools/record"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// RecordFacts are trusted facts used by the publication gate.
+type RecordFacts struct {
+	Record      bool
+	Policy      trust.Effective
+	Runners     []pools.Runner
+	ReportOwner string
+	Role        report.Role
+}
+
+// RecordGate checks all contributing attempts, independently of placement.
+type RecordGate struct {
+	Facts func(context.Context, PublishRequest) (RecordFacts, error)
+	// Contexts checks the context selected by the status path against protection.
+	Contexts *report.ResultContexts
+}
+
+func recordRefused(detail string) error {
+	return fmt.Errorf("%s: %s: %s", record.Code, record.Reason, detail)
+}
+
+// Gate vetoes dev runs, missing facts, foreign reporting ownership and any
+// attempt outside the effective record pools. It never changes the publisher.
+func (g RecordGate) Gate(ctx context.Context, r PublishRequest, status report.Status) error {
+	if !compat.V15() {
+		return nil
+	}
+	if g.Facts == nil {
+		return recordRefused("pool facts unavailable")
+	}
+	f, err := g.Facts(ctx, r)
+	if err != nil {
+		return recordRefused("pool facts unreadable")
+	}
+	if !f.Record {
+		return recordRefused("dev run")
+	}
+	if f.ReportOwner == report.OwnerTeam && f.Role != report.RoleTeam {
+		return recordRefused(report.SuppressedReason)
+	}
+	if len(f.Runners) == 0 {
+		return recordRefused("no contributing runner facts")
+	}
+	for _, runner := range f.Runners {
+		if !record.Allows(record.FromPolicy(f.Policy), runner) {
+			return recordRefused("a contributing attempt is outside pools.record")
+		}
+	}
+	if g.Contexts != nil && r.Owner != "" && r.Repo != "" {
+		want := g.Contexts.ResolveResultContext(ctx, r.Owner, r.Repo, "")
+		if status.ContextName() != want {
+			return fmt.Errorf("result context must be %s; nothing posted", want)
+		}
+	}
+	return nil
+}
+
+type recordHooks struct{ sessions sync.Map }
+
+func init() {
+	h := &recordHooks{}
+	prev := Dispatch
+	Dispatch = func(ctx context.Context, spec AttemptSpec) (Admitted, error) {
+		if compat.V15() {
+			if s := SessionFrom(ctx); s != nil {
+				h.sessions.Store(s.RunID, s)
+			}
+		}
+		return prev(ctx, spec)
+	}
+	RegisterPublishGate(RecordGate{Facts: h.facts, Contexts: &report.ResultContexts{Read: (report.GH{}).RequiredPinned}})
+	RegisterAfterRun(h)
+	RegisterFinalizer(recordCleanup{h})
+	if err := autoworld.RegisterExclusion("pools.record", recordWorldExclusions); err != nil {
+		panic(err)
+	}
+}
+
+func recordWorldExclusions(ctx context.Context, w sched.World) (map[string][]model.PlacementReasonDetail, error) {
+	if !compat.V15() {
+		return nil, nil
+	}
+	s := SessionFrom(ctx)
+	if s == nil {
+		return nil, nil // plans are wired by the command composition root
+	}
+	c := pools.Config{Labels: s.Store, Team: func() bool { return report.ProcessRole() == report.RoleTeam }, Dev: func() bool { return !s.Record }}
+	if !s.Record {
+		return pools.ExclusionProvider(c)(ctx, w)
+	}
+	return record.ExclusionProvider(c, func(context.Context) bool { return s.Record })(ctx, w)
+}
+
+func (h *recordHooks) facts(ctx context.Context, r PublishRequest) (RecordFacts, error) {
+	v, ok := h.sessions.Load(r.Run.RunID)
+	if !ok {
+		return RecordFacts{}, recordRefused("session unavailable")
+	}
+	s := v.(*Session)
+	f := RecordFacts{Record: s.Record, Role: report.ProcessRole()}
+	if !s.Record {
+		return f, nil
+	}
+	if s.Store == nil {
+		return f, recordRefused("store unavailable")
+	}
+	row, ok, err := s.Store.PipelineByID(ctx, s.RunID)
+	if err != nil || !ok {
+		return f, recordRefused("pipeline unavailable")
+	}
+	resolver := policy.Resolver{Store: s.Store, Run: policy.Runner(report.Capture)}
+	pol, err := resolver.Resolve(ctx, policy.Repo{Root: row.Project, Project: policy.ProjectIDGitCached(ctx, resolver.Run, row.Project), Class: model.TrustClass(row.SourceTrust), Visibility: "unknown"}, policy.Revision{Dir: row.Project, Run: s.PolicyRun})
+	if err != nil {
+		return f, err
+	}
+	f.Policy = pol.Effective
+	if owner, _, ok := f.Policy.Value("providers.report_owner"); ok {
+		f.ReportOwner, _ = owner.(string)
+	}
+	f.Runners, err = recordRunners(ctx, s.Store, s.RunID, f.Role)
+	return f, err
+}
+
+func recordRunners(ctx context.Context, st *store.Store, runID string, role report.Role) ([]pools.Runner, error) {
+	attempts, err := st.PipelineAttempts(ctx, runID)
+	if err != nil {
+		return nil, err
+	}
+	var runners []pools.Runner
+	for _, a := range attempts {
+		if a.State == "queued" {
+			continue
+		}
+		facts, ok, err := (store.AttestLedger{S: st}).AttemptFacts(ctx, a.ID)
+		if err != nil || !ok {
+			return nil, recordRefused("attempt holder unavailable")
+		}
+		r := pools.Runner{ID: facts.RunnerID, Source: pools.SourceRegistry}
+		if role == report.RoleTeam {
+			r.Source = pools.SourceCoordinator
+		}
+		if r.ID == "local" {
+			r.Source = pools.SourceLocal
+		} else {
+			n, err := st.NodeGet(ctx, r.ID)
+			var cap model.Capability
+			if err != nil || json.Unmarshal(n.Capability, &cap) != nil {
+				return nil, recordRefused("runner fact unavailable")
+			}
+			if cap.Location.Kind.Value != nil && *cap.Location.Kind.Value == "hosted" {
+				r.Source = pools.SourceProvider
+			}
+		}
+		set, err := st.NodeLabels(ctx, r.ID)
+		if err != nil {
+			return nil, err
+		}
+		r.Assigned = labels.Strings(set)
+		runners = append(runners, r)
+	}
+	return runners, nil
+}
+
+// BeforeStatus records refusals before the post is considered.
+func (*recordHooks) BeforeStatus() {}
+
+func (h *recordHooks) AfterRun(ctx context.Context, r RunInfo) error {
+	if !compat.V15() {
+		return nil
+	}
+	err := (RecordGate{Facts: h.facts}).Gate(ctx, PublishRequest{Run: r}, report.Status{})
+	if err == nil {
+		return nil
+	}
+	if v, ok := h.sessions.Load(r.RunID); ok {
+		s := v.(*Session)
+		if s.Store != nil {
+			ev := r.Evidence
+			ev.Errors = append(ev.Errors, model.EvidenceError{Code: record.Code, Detail: record.Reason})
+			body, e := json.Marshal(ev)
+			if e == nil {
+				e = s.Store.RecordRunEvidence(ctx, "ev-record-"+r.RunID, r.RunID, r.Revision, ev.InputDigests.Config, body)
+			}
+			if e != nil {
+				return fmt.Errorf("%w; record refusal evidence could not be stored", err)
+			}
+		}
+	}
+	return err
+}
+
+type recordCleanup struct{ h *recordHooks }
+
+func (recordCleanup) Name() string { return "record-pools" }
+func (c recordCleanup) Finalize(_ context.Context, r RunInfo) error {
+	c.h.sessions.Delete(r.RunID)
+	return nil
+}
diff --git a/free/ci/internal/run/record_gate_test.go b/free/ci/internal/run/record_gate_test.go
new file mode 100644
index 000000000..0cad1f416
--- /dev/null
+++ b/free/ci/internal/run/record_gate_test.go
@@ -0,0 +1,176 @@
+package run
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/pools/record"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+func recordTestGate(f RecordFacts, err error) RecordGate {
+	return RecordGate{Facts: func(context.Context, PublishRequest) (RecordFacts, error) { return f, err }}
+}
+
+func TestRecordGateFailsClosed(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	for _, g := range []RecordGate{{}, recordTestGate(RecordFacts{}, errors.New("unreadable")), recordTestGate(RecordFacts{Record: true}, nil),
+		recordTestGate(RecordFacts{Record: true, Runners: []pools.Runner{{ID: "unknown"}}}, nil)} {
+		if err := g.Gate(context.Background(), PublishRequest{}, report.Status{}); err == nil || !strings.Contains(err.Error(), "E809: not_a_record_pool") {
+			t.Fatalf("gate did not fail closed: %v", err)
+		}
+	}
+	f := RecordFacts{Record: true, Runners: []pools.Runner{{ID: "local", Source: pools.SourceLocal}}}
+	if err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{}); err != nil {
+		t.Fatal(err)
+	}
+	// A forced placement contributes alongside an otherwise valid local attempt.
+	f.Runners = append(f.Runners, pools.Runner{ID: "team", Source: pools.SourceCoordinator, Assigned: []string{"pool.team"}})
+	if err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{}); err == nil {
+		t.Fatal("forced foreign placement posted")
+	}
+}
+
+func TestDevRunNoRecord(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	f := RecordFacts{Runners: []pools.Runner{{ID: "local", Source: pools.SourceLocal}}}
+	err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{})
+	if err == nil || !strings.Contains(err.Error(), "dev run") {
+		t.Fatalf("dev posted: %v", err)
+	}
+}
+
+func TestReportOwnerTeamNotPosted(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	f := RecordFacts{Record: true, ReportOwner: report.OwnerTeam, Role: report.RolePersonal,
+		Runners: []pools.Runner{{ID: "local", Source: pools.SourceLocal}}}
+	err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{})
+	if err == nil || !strings.Contains(err.Error(), report.SuppressedReason) {
+		t.Fatalf("personal process posted a team result: %v", err)
+	}
+	f.Role = report.RoleTeam
+	if err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRecordGateLegacyDormant(t *testing.T) {
+	t.Setenv("NSELF_V15", "0")
+	if err := (RecordGate{}).Gate(context.Background(), PublishRequest{}, report.Status{}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestNonRecordRunnerExcludedBeforeAdmission(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	reg, err := trust.NewRegistry(record.Spec())
+	if err != nil {
+		t.Fatal(err)
+	}
+	eff, _, err := reg.Merge("pin", trust.Scope{Kind: trust.SourceProtectedBranch, Values: map[string]json.RawMessage{record.Key: json.RawMessage(`["team"]`)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := RecordFacts{Record: true, Policy: eff, Runners: []pools.Runner{
+		{ID: "vps", Source: pools.SourceRegistry, Assigned: []string{"pool.mine"}},
+		{ID: "team", Source: pools.SourceCoordinator, Assigned: []string{"pool.team"}},
+	}}
+	excluded := record.Excluded(record.FromPolicy(eff), f.Runners)
+	if len(excluded["team"]) != 0 || excluded["vps"][0].Detail != record.Reason {
+		t.Fatal(excluded)
+	}
+	w := sched.World{Exclusions: excluded, Runners: []sched.Runner{{ID: "vps"}}}
+	got := sched.Place(w, []sched.Job{{Key: "j", Pipeline: sched.Pipeline{Record: true}}})
+	if len(got.Placements) != 0 {
+		t.Fatal("excluded runner admitted")
+	}
+	// A forced placement must also be stopped by the independent publish gate.
+	if err := recordTestGate(f, nil).Gate(context.Background(), PublishRequest{}, report.Status{}); err == nil {
+		t.Fatal("forced placement published")
+	}
+}
+
+type recordReporter struct{ posted int }
+
+func (r *recordReporter) Post(context.Context, report.Status) error { r.posted++; return nil }
+
+func TestRecordGateStopsPostStatus(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+	reporter := &recordReporter{}
+	outbox := &report.Outbox{Store: st, Reporter: reporter, Owner: "team", Repo: "private"}
+	sha := strings.Repeat("a", 40)
+	seq, err := outbox.Reserve(context.Background(), sha)
+	if err != nil {
+		t.Fatal(err)
+	}
+	facts := RecordFacts{Record: true, Runners: []pools.Runner{{ID: "team", Source: pools.SourceCoordinator}}}
+	f := finishIn{Rev: Revision{SHA: sha}, Hooks: Hooks{Publisher: attestPublisher{}, Auto: AutoHooks{Gates: []PublishGate{recordTestGate(facts, nil)}}},
+		Post: statusPost{Reporter: reporter, Owner: "team", Repo: "private", Outbox: outbox, Seq: seq}}
+	ev := model.Evidence{Binding: model.Binding{State: "bound"}, Result: "pass"}
+	line, _ := (&Coordinator{}).postStatus(context.Background(), f, RunInfo{Revision: sha, Result: "pass", Evidence: ev}, ev)
+	if reporter.posted != 0 || !strings.Contains(line, record.Reason) {
+		t.Fatalf("forced placement posted: %s", line)
+	}
+	entries, err := st.OutboxUnposted(context.Background())
+	if err != nil || len(entries) != 0 {
+		t.Fatal("refused status became deliverable", err)
+	}
+}
+
+func TestRecordGatePinnedContext(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	g := recordTestGate(RecordFacts{Record: true, Runners: []pools.Runner{{ID: "local", Source: pools.SourceLocal}}}, nil)
+	g.Contexts = &report.ResultContexts{Read: func(context.Context, string, string) (bool, error) { return true, nil }}
+	req := PublishRequest{Owner: "team", Repo: "private"}
+	if err := g.Gate(context.Background(), req, report.Status{}); err == nil {
+		t.Fatal("pinned result used nself-ci")
+	}
+	if err := g.Gate(context.Background(), req, report.Status{StatusContext: report.WatchContext}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRecordRefusalPersistsEvidence(t *testing.T) {
+	t.Setenv("NSELF_V15", "1")
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+	ctx := context.Background()
+	if err = st.CreatePipeline(ctx, store.PipelineRow{ID: "dev", Project: "project", Revision: "sha", Status: "passed"}); err != nil {
+		t.Fatal(err)
+	}
+	h := &recordHooks{}
+	h.sessions.Store("dev", &Session{Store: st, RunID: "dev", Record: false})
+	ev := model.Evidence{InputDigests: model.InputDigests{Config: "cfg"}, Result: "pass"}
+	err = h.AfterRun(ctx, RunInfo{RunID: "dev", Revision: "sha", Evidence: ev})
+	if err == nil || !strings.Contains(err.Error(), record.Reason) {
+		t.Fatal(err)
+	}
+	docs, err := st.EvidenceByRevision(ctx, "sha", "cfg")
+	if err != nil || len(docs) != 1 {
+		t.Fatalf("refusal evidence missing: %v %v", docs, err)
+	}
+	var got model.Evidence
+	if err := json.Unmarshal(docs[0].Body, &got); err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Errors) != 1 || got.Errors[0].Code != record.Code || got.Errors[0].Detail != record.Reason {
+		t.Fatal("refusal reason missing", got.Errors)
+	}
+}
diff --git a/free/ci/internal/run/release_hook.go b/free/ci/internal/run/release_hook.go
index 94888f0a6..ea79f964d 100644
--- a/free/ci/internal/run/release_hook.go
+++ b/free/ci/internal/run/release_hook.go
@@ -10,7 +10,8 @@ package run
 // internal/release/job.
 // Inputs:  AttemptSpec (Dispatch wrapper), JobSpec (isolator wrapper),
 // AttemptInfo (attempt-start hook).
-// Outputs: the previous hook's answer, or an E715 refusal.
+// Outputs: the previous hook's answer, or an E715 refusal (Guard's refusals
+// also leave a release.admission.refused row in the run's store).
 // Constraints: a release job runs only under the V15 engine (the v1.4 gate has
 // no release class): anywhere else it is refused. The facts come from the run's
 // own store rows and git worktree, never from a file the job could write.
@@ -48,6 +49,7 @@ func init() {
 		panic("run: release_hook.go must initialise after dispatch_hook.go and isolation_hook.go")
 	}
 	releaseStash.Revoked = func(keyID string) (bool, error) { return releaseRevoked(attestLedger(), keyID) }
+	releaseStash.Audit = releaseAudit
 	if err := job.Register(releaseStash); err != nil {
 		panic(err)
 	}
@@ -66,6 +68,15 @@ func releaseRevoked(l attest.Ledger, keyID string) (bool, error) {
 	return l.Revoked(context.Background(), keyID)
 }
 
+// releaseAudit writes a release admission refusal into the run's own store;
+// releaseDispatch refuses an attempt without a session before Guard runs.
+func releaseAudit(ctx context.Context, actor, action, target, detail string) error {
+	if sess := SessionFrom(ctx); sess != nil && sess.Store != nil {
+		return sess.Store.AppendAudit(ctx, actor, action, target, detail)
+	}
+	return errors.New("the run has no store for the release admission audit row")
+}
+
 // releaseFailure carries a release refusal as a run error with its code.
 func releaseFailure(e *job.Error) error { return fail(e.Code, "%s: %s", e.Reason, e.Message) }
 
@@ -98,8 +109,12 @@ func releaseDispatch(ctx context.Context, s AttemptSpec, prev DispatchHook) (Adm
 	}
 	var adm Admitted
 	err = releaseStash.Guard(ctx, id, provider, func() (e error) { adm, e = prev(ctx, s); return })
-	if je, ok := err.(*job.Error); ok {
-		return Admitted{}, releaseFailure(je)
+	var je *job.Error
+	if errors.As(err, &je) {
+		if err == error(je) {
+			return Admitted{}, releaseFailure(je)
+		}
+		return Admitted{}, errors.Join(releaseFailure(je), err) // the refusal and its lost audit row
 	}
 	return adm, err
 }
diff --git a/free/ci/internal/run/remote_cache_hook.go b/free/ci/internal/run/remote_cache_hook.go
index daf4dc0b3..c498dfcc1 100644
--- a/free/ci/internal/run/remote_cache_hook.go
+++ b/free/ci/internal/run/remote_cache_hook.go
@@ -264,3 +264,13 @@ func (s cacheLeaseSink) Result(ctx context.Context, r protocol.Result) error {
 	}
 	return s.Sink.Result(ctx, r)
 }
+
+// Restore pushes the lease's planned restore blobs to the node (carrier A). The
+// lease audits its own refusals; a failed push leaves the node a cold miss.
+func (s cacheLeaseSink) Restore(ctx context.Context, link transport.RestoreLink) error {
+	if err := s.l.Restore(ctx, link); err != nil {
+		cacheOn.warn("remote cache restore: " + firstLineOf(err.Error()))
+		return err
+	}
+	return nil
+}
diff --git a/free/ci/internal/run/session.go b/free/ci/internal/run/session.go
index 462fee0c1..77868597a 100644
--- a/free/ci/internal/run/session.go
+++ b/free/ci/internal/run/session.go
@@ -32,11 +32,14 @@ type Session struct {
 	Exec        *ciexec.Executor
 	RunID       string
 	Revision    string
-	Host        string
-	Home        string
-	Poll        time.Duration
-	Capacity    func() ciexec.Capacity
-	Admission   ciexec.AdmissionPolicy
+	// Checkout is the revision a node checks out: the dirty-tree snapshot of the
+	// offload hook (P7-AUTO-13), or "" for Revision.
+	Checkout  string
+	Host      string
+	Home      string
+	Poll      time.Duration
+	Capacity  func() ciexec.Capacity
+	Admission ciexec.AdmissionPolicy
 	// Plan is the run's plan and Record its Options.Record: the dispatch hook maps both
 	// into the scheduler job (P7-AUTO-28); a Session built without them still places.
 	Plan   *plan.Plan
@@ -150,3 +153,11 @@ func hostName() string {
 	}
 	return safeID(h)
 }
+
+// checkoutRevision is the revision a node checks out (Checkout, else Revision).
+func (s *Session) checkoutRevision() string {
+	if s.Checkout != "" {
+		return s.Checkout
+	}
+	return s.Revision
+}
diff --git a/free/ci/internal/sched/auto.go b/free/ci/internal/sched/auto.go
new file mode 100644
index 000000000..bee267dfa
--- /dev/null
+++ b/free/ci/internal/sched/auto.go
@@ -0,0 +1,149 @@
+package sched
+
+// Purpose: the `auto` preset's tier wait (P7-AUTO-05). Under `auto` a job whose
+// better-tier runners are only busy or not yet ready waits up to
+// sched.auto.step_sec for them before it runs on the best eligible runner.
+// Inputs: the World (Policy.Preset, Policy.Trust for step_sec, Bias for the
+// tier of each runner, written by internal/tiers) and Job.QueuedMs.
+// Outputs: TierFor, TierOf, AutoStepMs and the tier.waiting hold Place applies.
+// Constraints: pure and deterministic: QueuedMs comes from the Job, never a
+// clock; only capacity.busy and node.not_ready are waited for (an explicit set,
+// not PlacementReason.Static: offline, draining and provider.down are not
+// static but are never waited for); under auto the local fast path is off,
+// because the tier order (local last) decides; the hold is bounded by one step_sec,
+// whatever QueuedMs says; a step_sec of 0 never waits; every other preset is
+// untouched.
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// AutoPreset is the preset that places by tier order (P7-AUTO-05).
+const AutoPreset = "auto"
+
+// The tiers a runner can be in, by location class.
+const (
+	TierHosted = "hosted"
+	TierVPS    = "vps"
+	TierLAN    = "lan"
+	TierLocal  = "local"
+)
+
+// TierStepMs is the Bias between adjacent tiers. A rank stays below it, so the
+// tier index of a runner is its Bias divided by TierStepMs.
+const TierStepMs int64 = 60000
+
+// KeyAutoStepSec is the policy key of the tier wait, in seconds (0: never wait).
+const KeyAutoStepSec = "sched.auto.step_sec"
+
+// DefaultAutoStepSec is the registered default of KeyAutoStepSec.
+const DefaultAutoStepSec int64 = 30
+
+// tierWaitReasons are the only reasons a better tier is waited for.
+var tierWaitReasons = map[string]bool{string(model.CapacityBusy): true, string(model.NodeNotReady): true}
+
+// TierFor returns the tier of a location and cost class: hosted (hosted
+// location or included class), lan, local, or vps (any other remote runner).
+func TierFor(location, class string) string {
+	switch {
+	case location == "hosted" || class == "included":
+		return TierHosted
+	case location == "lan":
+		return TierLAN
+	case location == "local":
+		return TierLocal
+	}
+	return TierVPS
+}
+
+// TierOf returns the tier of r in w.
+func TierOf(w World, r Runner) string { return TierFor(location(r), runnerClass(w, r)) }
+
+// AutoStepMs returns sched.auto.step_sec of the world's policy in ms; the
+// default when the key is absent, 0 when it is 0 or not a whole number >= 0.
+func AutoStepMs(w World) int64 {
+	return stepMs(w.Policy.Trust)
+}
+
+func stepMs(eff trust.Effective) int64 {
+	sec := DefaultAutoStepSec
+	if v, _, ok := eff.Value(KeyAutoStepSec); ok {
+		n, isInt := trust.IntValue(v)
+		if !isInt || n < 0 {
+			return 0
+		}
+		sec = n
+	}
+	ms, _ := Mul(sec, 1000)
+	return ms
+}
+
+// placementFastPath is fastPath for every preset but auto, which never takes it.
+func placementFastPath(w World, jobs []Job, runners []Runner) model.FastPath {
+	if w.Policy.Preset == AutoPreset {
+		return model.FastPath{Reason: "none"}
+	}
+	return fastPath(w, jobs, runners)
+}
+
+func tierIndex(w World, r Runner) int64 {
+	b := w.Bias[r.ID]
+	if b <= 0 {
+		return 0
+	}
+	return b / TierStepMs
+}
+
+// waitOnly reports whether every reason is one the tier wait waits for.
+func waitOnly(rs []model.PlacementReasonDetail) bool {
+	if len(rs) == 0 {
+		return false
+	}
+	for _, q := range rs {
+		if !tierWaitReasons[q.Code] {
+			return false
+		}
+	}
+	return true
+}
+
+// tierHold returns the tier.waiting reason when j must wait for a better-tier
+// runner than runners[best]. alts[i] is the alternative of runners[i].
+func tierHold(w World, j Job, runners []Runner, alts []model.Alternative, best int) (model.PlacementReasonDetail, bool) {
+	if w.Policy.Preset != AutoPreset || best < 0 || len(alts) != len(runners) {
+		return model.PlacementReasonDetail{}, false
+	}
+	step := AutoStepMs(w)
+	queued := j.QueuedMs
+	if queued < 0 { // a skewed clock never adds wait
+		queued = 0
+	}
+	if step <= 0 || queued >= step {
+		return model.PlacementReasonDetail{}, false
+	}
+	bestTier := tierIndex(w, runners[best])
+	held := -1
+	for i, a := range alts {
+		if a.Eligible || !waitOnly(a.Reasons) || tierIndex(w, runners[i]) >= bestTier {
+			continue
+		}
+		if held < 0 || w.Bias[runners[i].ID] < w.Bias[runners[held].ID] {
+			held = i
+		}
+	}
+	if held < 0 {
+		return model.PlacementReasonDetail{}, false
+	}
+	r := runners[held]
+	codes := make([]string, len(alts[held].Reasons))
+	for i, q := range alts[held].Reasons {
+		codes[i] = q.Code
+	}
+	detail := fmt.Sprintf("held for %s (tier %s, bias %d, %s): %d ms left of step_sec %d s, then %s (tier %s)",
+		r.ID, TierOf(w, r), w.Bias[r.ID], strings.Join(codes, ","), step-queued, step/1000, runners[best].ID, TierOf(w, runners[best]))
+	return reason(model.TierWaiting, detail), true
+}
diff --git a/free/ci/internal/sched/auto_test.go b/free/ci/internal/sched/auto_test.go
new file mode 100644
index 000000000..b7af4306b
--- /dev/null
+++ b/free/ci/internal/sched/auto_test.go
@@ -0,0 +1,224 @@
+package sched
+
+// Purpose: the `auto` preset (P7-AUTO-05): tier bias against scoring and
+// eligibility, the bounded tier wait, and the reasons that are never waited for.
+
+import (
+	"encoding/json"
+	"math"
+	"math/rand"
+	"regexp"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// autoWorld returns an `auto` world whose Bias puts each runner in the tier
+// index given (the tier rank is 0), the way internal/tiers writes it.
+func autoWorld(tiers map[string]int64, rs ...Runner) World {
+	w := fixtureWorld(rs...)
+	w.Policy.Preset = AutoPreset
+	w.Bias = map[string]int64{}
+	for id, idx := range tiers {
+		w.Bias[id] = idx * TierStepMs
+	}
+	return w
+}
+
+// withStep sets sched.auto.step_sec through a merged policy, as the resolver would.
+func withStep(t *testing.T, w World, sec int64) World {
+	t.Helper()
+	dec := func(raw json.RawMessage) (any, error) {
+		var n json.Number
+		if err := json.Unmarshal(raw, &n); err != nil {
+			return nil, err
+		}
+		return n.Int64()
+	}
+	reg, err := trust.NewRegistry(trust.KeySpec{Key: KeyAutoStepSec, Owner: "sched", Kind: trust.TightenLower, Default: DefaultAutoStepSec, Decode: dec})
+	if err != nil {
+		t.Fatal(err)
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceProject, Values: map[string]json.RawMessage{KeyAutoStepSec: json.RawMessage(strconv.FormatInt(sec, 10))}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	w.Policy.Trust = eff
+	return w
+}
+
+func busy(r Runner) Runner {
+	r.Avail.Slots = 0
+	return r
+}
+
+var leftRe = regexp.MustCompile(`: (\d+) ms left of step_sec`)
+
+// heldLeft returns the ms left in a tier.waiting reason, or -1.
+func heldLeft(x Explanation) int64 {
+	for _, r := range x.Reasons {
+		if r.Code == string(model.TierWaiting) {
+			m := leftRe.FindStringSubmatch(r.Detail)
+			if m == nil {
+				return -1
+			}
+			n, _ := strconv.ParseInt(m[1], 10, 64)
+			return n
+		}
+	}
+	return -1
+}
+
+func TestAutoPresetProperty(t *testing.T) {
+	seed := int64(20261028)
+	rnd := rand.New(rand.NewSource(seed))
+	locs := []string{"remote", "lan", "local"}
+	ineligible := []func(*Runner){
+		func(r *Runner) { r.Capability.Availability.State.Value = ptr("offline") },
+		func(r *Runner) { r.Capability.Availability.State.Value = ptr("draining") },
+		func(r *Runner) { r.ProviderDown = true },
+		func(r *Runner) { r.Capability.Lifecycle.AuthorizedProjects = nil },
+		func(r *Runner) { *r = busy(*r) },
+	}
+	for n := 0; n < 10000; n++ {
+		bt := rnd.Intn(2)
+		lt := bt + 1 + rnd.Intn(2-bt)
+		better, lower := fixtureRunner("r1", locs[bt]), fixtureRunner("r2", locs[lt])
+		w := autoWorld(map[string]int64{"r1": int64(bt + 1), "r2": int64(lt + 1)}, better, lower)
+		w.Bias["r1"] += int64(rnd.Intn(50))
+		w.Bias["r2"] += int64(rnd.Intn(50))
+		w.Estimates = map[string]map[string]Sample{}
+		for _, id := range []string{"r1", "r2"} {
+			w.Estimates[id] = map[string]Sample{"j": {WaitMs: ptr(rnd.Int63n(4 * TierStepMs)), RuntimeMs: ptr(rnd.Int63n(TierStepMs)), Confidence: "known"}}
+		}
+		betterOK := rnd.Intn(3) != 0
+		if !betterOK {
+			ineligible[rnd.Intn(len(ineligible))](&w.Runners[0])
+		}
+		j := fixtureJob("j")
+		j.QueuedMs = []int64{math.MaxInt64, 30000, 1 << 40}[rnd.Intn(3)] // past the step: this property is about order, not the wait
+		res := Place(w, []Job{j})
+		if len(res.Placements) != 1 {
+			t.Fatalf("seed %d world %d: not placed: %+v", seed, n, res.Explanations)
+		}
+		got := res.Placements[0].RunnerID
+		if !betterOK {
+			if got != "r2" {
+				t.Fatalf("seed %d world %d: an ineligible better tier must lose to an eligible lower tier, got %s", seed, n, got)
+			}
+			continue
+		}
+		plain := w
+		plain.Bias = nil
+		sb, _ := score(plain, j, w.Runners[0])
+		sl, _ := score(plain, j, w.Runners[1])
+		want := "r1"
+		if sl+w.Bias["r2"] < sb+w.Bias["r1"] {
+			want = "r2"
+		}
+		if got != want {
+			t.Fatalf("seed %d world %d: got %s want %s (base %d vs %d, bias %v)", seed, n, got, want, sb, sl, w.Bias)
+		}
+		// rank adds under 50 ms here, so the lower tier wins only by scoring more than the tier steps lower
+		if got == "r2" && sb-sl <= int64(lt-bt)*TierStepMs-50 {
+			t.Fatalf("seed %d world %d: the lower tier won without beating the tier step (base %d vs %d)", seed, n, sb, sl)
+		}
+	}
+}
+
+func TestAutoStepWaitBounded(t *testing.T) {
+	w := autoWorld(map[string]int64{"vps": 1, "lan": 2}, busy(fixtureRunner("vps", "remote")), fixtureRunner("lan", "lan"))
+	step := AutoStepMs(w)
+	if step != DefaultAutoStepSec*1000 {
+		t.Fatalf("default step %d", step)
+	}
+	for _, c := range []struct {
+		queued int64
+		wait   bool
+		left   int64
+	}{{0, true, 30000}, {-5, true, 30000}, {math.MinInt64, true, 30000}, {12000, true, 18000}, {29999, true, 1}, {30000, false, 0}, {math.MaxInt64, false, 0}} {
+		j := fixtureJob("j")
+		j.QueuedMs = c.queued
+		res := Place(w, []Job{j})
+		x := res.Explanations[0]
+		if c.wait {
+			if x.Status != "waiting" || len(res.Placements) != 0 || heldLeft(x) != c.left || !strings.Contains(x.Reasons[0].Detail, "held for vps (tier vps") {
+				t.Fatalf("queued %d: want a tier.waiting hold with %d ms left: %+v", c.queued, c.left, x)
+			}
+			continue
+		}
+		if len(res.Placements) != 1 || res.Placements[0].RunnerID != "lan" {
+			t.Fatalf("queued %d: after step_sec the job runs on the next tier: %+v", c.queued, res)
+		}
+	}
+	// node.not_ready waits like capacity.busy.
+	nr := autoWorld(map[string]int64{"vps": 1, "lan": 2}, fixtureRunner("vps", "remote"), fixtureRunner("lan", "lan"))
+	nr.Exclusions = map[string][]model.PlacementReasonDetail{"vps": {{Code: string(model.NodeNotReady), Detail: "warming"}}}
+	if x := Place(nr, []Job{fixtureJob("j")}).Explanations[0]; x.Status != "waiting" || heldLeft(x) != 30000 {
+		t.Fatalf("node.not_ready must be waited for: %+v", x)
+	}
+	// step_sec 0 never waits; a lower step bounds the wait.
+	if res := Place(withStep(t, w, 0), []Job{fixtureJob("j")}); len(res.Placements) != 1 || res.Placements[0].RunnerID != "lan" {
+		t.Fatalf("step_sec 0 must never wait: %+v", res)
+	}
+	if x := Place(withStep(t, w, 5), []Job{fixtureJob("j")}).Explanations[0]; heldLeft(x) != 5000 {
+		t.Fatalf("step_sec 5: %+v", x)
+	}
+	// clock skew: any QueuedMs never panics and never adds more than one step.
+	rnd := rand.New(rand.NewSource(5))
+	for i := 0; i < 2000; i++ {
+		j := fixtureJob("j")
+		j.QueuedMs = rnd.Int63() - rnd.Int63()
+		x := Place(w, []Job{j}).Explanations[0]
+		if left := heldLeft(x); left > step || x.Status == "waiting" && left <= 0 {
+			t.Fatalf("queued %d: %d ms left exceeds one step: %+v", j.QueuedMs, left, x)
+		}
+	}
+	// a better tier that is free wins at once; a same-tier busy runner is not waited for.
+	same := autoWorld(map[string]int64{"a": 2, "b": 2}, busy(fixtureRunner("a", "lan")), fixtureRunner("b", "lan"))
+	if res := Place(same, []Job{fixtureJob("j")}); len(res.Placements) != 1 || res.Placements[0].RunnerID != "b" {
+		t.Fatalf("a busy runner of the same tier is not waited for: %+v", res)
+	}
+	// other presets never wait.
+	other := w
+	other.Policy.Preset = "balanced"
+	if res := Place(other, []Job{fixtureJob("j")}); len(res.Placements) != 1 {
+		t.Fatalf("balanced must not wait: %+v", res)
+	}
+}
+
+func TestAutoStaticNeverWaits(t *testing.T) {
+	cases := map[string]func(*World){
+		"revoked":      func(w *World) { now := time.Unix(1, 0); w.Runners[0].Capability.Lifecycle.RevokedAt = &now },
+		"unauthorized": func(w *World) { w.Runners[0].Capability.Lifecycle.AuthorizedProjects = nil },
+		"offline":      func(w *World) { w.Runners[0].Capability.Availability.State.Value = ptr("offline") },
+		"draining":     func(w *World) { w.Runners[0].Capability.Availability.State.Value = ptr("draining") },
+		"provider.down": func(w *World) {
+			w.Runners[0].ProviderDown = true
+		},
+		"pool.excluded": func(w *World) {
+			w.Exclusions = map[string][]model.PlacementReasonDetail{"vps": {{Code: string(model.PoolExcluded), Detail: "pool"}}}
+		},
+		"busy and offline": func(w *World) {
+			w.Runners[0] = busy(w.Runners[0])
+			w.Runners[0].Capability.Availability.State.Value = ptr("offline")
+		},
+		"limit": func(w *World) { w.Policy.Limits.Runner = 1; w.Counts.Runners = map[string]int{"vps": 1} },
+	}
+	base := autoWorld(map[string]int64{"vps": 1, "lan": 2}, fixtureRunner("vps", "remote"), fixtureRunner("lan", "lan"))
+	if res := Place(base, []Job{fixtureJob("j")}); len(res.Placements) != 1 || res.Placements[0].RunnerID != "vps" {
+		t.Fatalf("an eligible better tier must win: %+v", res)
+	}
+	for name, mutate := range cases {
+		w := autoWorld(map[string]int64{"vps": 1, "lan": 2}, fixtureRunner("vps", "remote"), fixtureRunner("lan", "lan"))
+		mutate(&w)
+		res := Place(w, []Job{fixtureJob("j")})
+		if len(res.Placements) != 1 || res.Placements[0].RunnerID != "lan" || heldLeft(res.Explanations[0]) >= 0 {
+			t.Errorf("%s: the better tier must be skipped at once: %+v", name, res)
+		}
+	}
+}
diff --git a/free/ci/internal/sched/bench_test.go b/free/ci/internal/sched/bench_test.go
new file mode 100644
index 000000000..67d2423f8
--- /dev/null
+++ b/free/ci/internal/sched/bench_test.go
@@ -0,0 +1,34 @@
+package sched
+
+import (
+	"fmt"
+	"testing"
+)
+
+// BenchmarkPlace measures complete decisions, including explanations, on a fixed
+// world. Fixture creation is excluded; Place must reserve only its private copy.
+func BenchmarkPlace(b *testing.B) {
+	for _, runners := range []int{1, 10, 100} {
+		for _, jobs := range []int{10, 100, 1000} {
+			b.Run(fmt.Sprintf("runners=%d/jobs=%d", runners, jobs), func(b *testing.B) {
+				rs := make([]Runner, runners)
+				for i := range rs {
+					rs[i] = fixtureRunner(fmt.Sprintf("runner-%03d", i), "lan")
+				}
+				w := fixtureWorld(rs...)
+				js := make([]Job, jobs)
+				for i := range js {
+					js[i] = fixtureJob(fmt.Sprintf("job-%04d", i))
+				}
+				b.ReportAllocs()
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					result := Place(w, js)
+					if len(result.Explanations) != jobs || len(result.Placements) != min(runners, jobs) {
+						b.Fatal("fixture did not exercise placement and capacity decisions")
+					}
+				}
+			})
+		}
+	}
+}
diff --git a/free/ci/internal/sched/place.go b/free/ci/internal/sched/place.go
index 31649f595..9065fc47f 100644
--- a/free/ci/internal/sched/place.go
+++ b/free/ci/internal/sched/place.go
@@ -13,7 +13,7 @@ func Place(w World, jobs []Job) Result {
 	w.Budgets.Providers = copyBudgets(w.Budgets.Providers)
 	runners := append(append([]Runner(nil), w.Runners...), w.Hosted...)
 	sort.Slice(runners, func(i, j int) bool { return runners[i].ID < runners[j].ID })
-	result := Result{Placements: []Placement{}, Explanations: []Explanation{}, FastPath: fastPath(w, jobs, runners)}
+	result := Result{Placements: []Placement{}, Explanations: []Explanation{}, FastPath: placementFastPath(w, jobs, runners)}
 	for _, j := range jobs {
 		x := Explanation{JobKey: j.Key, Alternatives: []model.Alternative{}, Reasons: []model.PlacementReasonDetail{}}
 		if !has(j.Pipeline.Support, j.Requirements.Platform) {
@@ -92,7 +92,10 @@ func Place(w World, jobs []Job) Result {
 			}
 			x.Alternatives = append(x.Alternatives, alt)
 		}
-		if best != nil {
+		if hold, held := tierHold(w, j, runners, x.Alternatives, bestIndex); best != nil && held {
+			x.Status = "waiting" // the auto preset waits a bounded step for a busy better tier
+			x.Reasons = append(x.Reasons, hold)
+		} else if best != nil {
 			x.Status = "placed"
 			result.Placements = append(result.Placements, *best)
 			w.reservePlacement(&runners[bestIndex], *best)
diff --git a/free/ci/internal/sched/preset_test.go b/free/ci/internal/sched/preset_test.go
index b3bfee1c9..889848a5b 100644
--- a/free/ci/internal/sched/preset_test.go
+++ b/free/ci/internal/sched/preset_test.go
@@ -42,7 +42,8 @@ func TestPresetFixture(t *testing.T) {
 		"fastest":               {map[string]int64{"L": 67500, "N": 57000, "H": 93000, "E": 98000}, "NLHE"},
 		"cheapest":              {map[string]int64{"L": 22500, "N": 14250, "H": 73250, "E": 424500}, "NLHE"},
 	}
-	if len(want) != len(Presets()) {
+	// the auto preset places by tier order, not by these weights; auto_test.go covers it
+	if _, ok := Presets()[AutoPreset]; !ok || len(want)+1 != len(Presets()) {
 		t.Fatal("preset count")
 	}
 	for name, expected := range want {
diff --git a/free/ci/internal/sched/presets.go b/free/ci/internal/sched/presets.go
index f954af3f6..8e3a8a427 100644
--- a/free/ci/internal/sched/presets.go
+++ b/free/ci/internal/sched/presets.go
@@ -1,5 +1,6 @@
 package sched
 
+// Preset is one named scoring profile: component weights, the ms per cost micro and a bias per cost class.
 type Preset struct {
 	Weights        [9]int64
 	MsPerCostMicro int64
@@ -13,6 +14,8 @@ var presetTable = map[string]Preset{
 	"preserve-hosted-quota": {[9]int64{1000, 1000, 1000, 1000, 1000, 1000, 1000, 4000, 1000}, 1, [5]int64{0, 0, 60000, 120000, 120000}},
 	"fastest":               {[9]int64{1000, 1000, 1000, 1000, 1000, 250, 0, 0, 1000}, 0, [5]int64{}},
 	"cheapest":              {[9]int64{250, 250, 250, 250, 250, 250, 4000, 2000, 250}, 10, [5]int64{}},
+	// auto scores like balanced; its order comes from the tier_rank Bias (internal/tiers), not a class bias.
+	AutoPreset: {[9]int64{1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000}, 1, [5]int64{}},
 }
 
 // Presets returns independent preset values.
diff --git a/free/ci/internal/schedpolicy/placement.go b/free/ci/internal/schedpolicy/placement.go
index 7aaa66eda..b786f412f 100644
--- a/free/ci/internal/schedpolicy/placement.go
+++ b/free/ci/internal/schedpolicy/placement.go
@@ -18,6 +18,9 @@ import (
 	"github.com/nself-org/plugins/free/ci/internal/model"
 	"github.com/nself-org/plugins/free/ci/internal/policy"
 	"github.com/nself-org/plugins/free/ci/internal/sched"
+	// The `auto` preset's keys (sched.auto.*) and its World.Bias contributor
+	// register from internal/tiers, linked wherever the sched keys are (P7-AUTO-05).
+	_ "github.com/nself-org/plugins/free/ci/internal/tiers"
 )
 
 // Owner is the owner recorded on every key this package registers.
diff --git a/free/ci/internal/selftest/alert.go b/free/ci/internal/selftest/alert.go
new file mode 100644
index 000000000..11f343db6
--- /dev/null
+++ b/free/ci/internal/selftest/alert.go
@@ -0,0 +1,140 @@
+package selftest
+
+// Purpose: `doctor --selftest --alert`: send one notifier message per failing set per day.
+// Inputs:  the selftest checks, the sinks, a state file, a clock.
+// Outputs: Result; the state file holds the sets already sent today.
+// Constraints: a failing set is the sorted ids of the failing selftest checks; the same
+// set is sent once per UTC day, a different set (one more check failing) is a new
+// message; a set no sink took is not recorded, so the next run tries again; a clean
+// report sends nothing. The event carries ids and names only, never a path or log text.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/notify"
+)
+
+// Alerter sends the alert.
+type Alerter struct {
+	Sinks     []notify.Notifier
+	StatePath string
+	Host      string
+	Now       func() time.Time // nil: time.Now
+}
+
+// Result says what an alert did.
+type Result struct {
+	Set     string `json:"set,omitempty"` // the failing ids, comma separated
+	Sent    bool   `json:"sent"`
+	Skipped string `json:"skipped,omitempty"` // why nothing was sent
+}
+
+type alertState struct {
+	Day  string   `json:"day"`
+	Sent []string `json:"sent"`
+}
+
+// FailingSet returns the sorted ids of the failing selftest checks.
+func FailingSet(checks []doctor.Check) []string {
+	var ids []string
+	for _, c := range checks {
+		if c.Status == doctor.Fail && strings.HasPrefix(c.ID, Prefix) {
+			ids = append(ids, c.ID)
+		}
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+// Alert sends the message for the failing set unless it already went out today.
+func (a Alerter) Alert(ctx context.Context, checks []doctor.Check) (Result, error) {
+	ids := FailingSet(checks)
+	if len(ids) == 0 {
+		return Result{Skipped: "no failing check"}, nil
+	}
+	set := strings.Join(ids, ",")
+	now := time.Now()
+	if a.Now != nil {
+		now = a.Now()
+	}
+	now = now.UTC()
+	day := now.Format("2006-01-02")
+	st := a.load()
+	if st.Day != day {
+		st = alertState{Day: day}
+	}
+	for _, s := range st.Sent {
+		if s == set {
+			return Result{Set: set, Skipped: "already sent today"}, nil
+		}
+	}
+	if len(a.Sinks) == 0 {
+		return Result{Set: set, Skipped: "no notifier sink is configured"}, nil
+	}
+	ev := notify.Event{Kind: notify.KindFailure, Time: now.Format(time.RFC3339), Context: "selftest", Show: "nself ci doctor --selftest",
+		Message: message(a.Host, checks, ids)}.Redacted()
+	var errs []error
+	took := false
+	for _, s := range a.Sinks {
+		if err := s.Notify(ctx, ev); err != nil {
+			errs = append(errs, fmt.Errorf("%s: %w", s.Name(), err))
+			continue
+		}
+		took = true
+	}
+	if !took {
+		return Result{Set: set, Skipped: "no sink took the message"}, errors.Join(errs...)
+	}
+	st.Sent = append(st.Sent, set)
+	return Result{Set: set, Sent: true}, errors.Join(append(errs, a.save(st))...)
+}
+
+func message(host string, checks []doctor.Check, ids []string) string {
+	names := map[string]string{}
+	for _, c := range checks {
+		names[c.ID] = c.Name
+	}
+	parts := make([]string, len(ids))
+	for i, id := range ids {
+		parts[i] = id + " " + names[id]
+	}
+	where := ""
+	if host != "" {
+		where = " on " + host
+	}
+	return fmt.Sprintf("nself-ci selftest%s: %d check(s) failing: %s", where, len(ids), strings.Join(parts, "; "))
+}
+
+// load reads the state; an unreadable file is an empty state (the alert is then sent again,
+// the safe direction).
+func (a Alerter) load() alertState {
+	var st alertState
+	if b, err := os.ReadFile(a.StatePath); err == nil {
+		_ = json.Unmarshal(b, &st)
+	}
+	return st
+}
+
+func (a Alerter) save(st alertState) error {
+	b, err := json.Marshal(st)
+	if err != nil {
+		return err
+	}
+	if err = os.MkdirAll(filepath.Dir(a.StatePath), 0o700); err != nil {
+		return err
+	}
+	tmp := a.StatePath + ".tmp"
+	if err = os.WriteFile(tmp, b, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, a.StatePath)
+}
diff --git a/free/ci/internal/selftest/audit_template_test.go b/free/ci/internal/selftest/audit_template_test.go
new file mode 100644
index 000000000..01f83ec80
--- /dev/null
+++ b/free/ci/internal/selftest/audit_template_test.go
@@ -0,0 +1,105 @@
+package selftest_test
+
+// Purpose: the audit pipeline template (P7-AUTO-20) is a valid pipeline config
+// whose only trigger is `schedule` (so it runs in the background band), and the
+// watcher's idle tick, which starts it, starts nothing on a host that is not ready.
+// Inputs: free/ci/templates/audit-pipeline.yml; a watcher with stub ports and no
+// watched repositories. Outputs: pass or fail. Constraints: no network, no clock.
+
+import (
+	"context"
+	"os"
+	"slices"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/background"
+	"github.com/nself-org/plugins/free/ci/internal/config"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/watch"
+)
+
+const auditTemplate = "../../templates/audit-pipeline.yml"
+
+// stubs satisfy the watcher's required ports; a pass with no repositories never calls them.
+type stubs struct{ t *testing.T }
+
+func (s stubs) Scan(context.Context, string) (watch.Scan, error) {
+	s.t.Fatal("no repository is watched, nothing may be scanned")
+	return watch.Scan{}, nil
+}
+func (s stubs) PostClaim(context.Context, report.Status) (time.Time, error) {
+	s.t.Fatal("an idle pass must not claim")
+	return time.Time{}, nil
+}
+func (s stubs) ListStatuses(context.Context, string, string, string) ([]report.LedgerStatus, time.Time, error) {
+	return nil, time.Time{}, nil
+}
+func (s stubs) Post(context.Context, report.Status) error {
+	s.t.Fatal("an idle pass must not post a status")
+	return nil
+}
+func (s stubs) Run(context.Context, watch.Job) (watch.Outcome, error) {
+	s.t.Fatal("an idle pass must not run a commit")
+	return watch.Outcome{}, nil
+}
+
+func TestAuditTemplateValid(t *testing.T) {
+	data, err := os.ReadFile(auditTemplate)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.Parse(auditTemplate, data)
+	if err != nil {
+		t.Fatalf("the template must pass the pipeline-config schema: %v", err)
+	}
+	p, ok := loaded.Config.Pipelines["audit"]
+	if !ok {
+		t.Fatal("the template must define the audit pipeline")
+	}
+	if len(p.Triggers) != 1 || string(p.Triggers[0]) != "schedule" || p.Schedule == "" || p.MaxAge == "" {
+		t.Fatalf("audit must be scheduled only, with a schedule and a max_age: %+v", p)
+	}
+	if !background.IsBackgroundKind(string(p.Triggers[0])) {
+		t.Fatal("a scheduled pipeline must run in the background band")
+	}
+	want := map[string]string{"audit-govulncheck": "govulncheck", "audit-pnpm": "pnpm", "audit-race": "go"}
+	if len(p.Jobs) != len(want) {
+		t.Fatalf("audit jobs = %v", p.Jobs)
+	}
+	for _, id := range p.Jobs {
+		j, ok := loaded.Config.Jobs[id]
+		if !ok || len(j.Run) == 0 || j.Run[0] != want[id] {
+			t.Fatalf("job %s must run %s: %+v", id, want[id], j)
+		}
+	}
+	if !slices.Contains(loaded.Config.Jobs["audit-race"].Run, "-race") {
+		t.Fatal("the race job must pass -race")
+	}
+
+	// The drill: the idle tick is what starts a due background pipeline; a host that
+	// is not ready never reaches it, a ready host with nothing to run does.
+	for _, ready := range []bool{false, true} {
+		started := 0
+		s := stubs{t}
+		w, err := watch.New(watch.Config{Host: "mini1"}, watch.Ports{Scanner: s, Ledger: s, Reporter: s, Runner: s,
+			Ready: func(context.Context) (bool, []string) {
+				if ready {
+					return true, nil
+				}
+				return false, []string{"disk.low"}
+			},
+			Idle: func(context.Context) (bool, error) { started++; return true, nil },
+			Now:  func() time.Time { return time.Date(2026, 10, 20, 2, 41, 0, 0, time.UTC) }})
+		if err != nil {
+			t.Fatal(err)
+		}
+		rep := w.Pass(context.Background())
+		if ready && (started != 1 || !rep.Idle) {
+			t.Fatalf("a ready idle host must start one background pipeline: started=%d %+v", started, rep)
+		}
+		if !ready && (started != 0 || rep.Idle) {
+			t.Fatalf("a host that is not ready must start nothing: started=%d %+v", started, rep)
+		}
+	}
+}
diff --git a/free/ci/internal/selftest/checks.go b/free/ci/internal/selftest/checks.go
new file mode 100644
index 000000000..a9ff8bdda
--- /dev/null
+++ b/free/ci/internal/selftest/checks.go
@@ -0,0 +1,125 @@
+package selftest
+
+// Purpose: the checks CI-DS001–CI-DS005, the host-environment half of the selftest.
+// Inputs:  Facts and Limits. Outputs: doctor checks. Constraints: pure.
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+)
+
+// The check ids of the selftest section (CI-DS…, owned by this package).
+const (
+	IDTools    = "CI-DS001"
+	IDProvider = "CI-DS002"
+	IDRepo     = "CI-DS003"
+	IDDisk     = "CI-DS004"
+	IDSinks    = "CI-DS005"
+	IDWatcher  = "CI-DS006"
+	IDClaims   = "CI-DS007"
+	IDOrphans  = "CI-DS008"
+	IDInfra    = "CI-DS009"
+)
+
+// Prefix starts the id of every selftest check; the alert looks at these only.
+const Prefix = "CI-DS"
+
+// Evaluate returns the nine selftest checks in id order.
+func Evaluate(f Facts, l Limits) []doctor.Check {
+	out := []doctor.Check{toolsCheck(f), providerCheck(f), repoCheck(f), diskCheck(f, l), sinksCheck(f, l)}
+	return append(out, watcherCheck(f, l), claimsCheck(f), orphansCheck(f), infraCheck(f, l))
+}
+
+func check(id, name string, st doctor.Status, msg, fix string) doctor.Check {
+	if st == doctor.Pass {
+		fix = ""
+	}
+	return doctor.Check{ID: id, Name: name, Status: st, Message: msg, Remediation: fix}
+}
+
+func unread(id, name, what, why string) doctor.Check {
+	return check(id, name, doctor.Warn, what+" could not be read: "+why, "Fix the cause above, then run `nself ci doctor --selftest` again")
+}
+
+func toolsCheck(f Facts) doctor.Check {
+	const name = "gate tools"
+	var fail, warn []string
+	for _, t := range f.Tools {
+		switch {
+		case t.Found:
+		case t.Required:
+			fail = append(fail, t.Name)
+		default:
+			warn = append(warn, t.Name)
+		}
+	}
+	fix := "Install the tool into a directory on the PATH the service runs with"
+	switch {
+	case len(fail) > 0:
+		return check(IDTools, name, doctor.Fail, "missing on the service PATH: "+strings.Join(append(fail, warn...), ", "), fix)
+	case len(warn) > 0:
+		return check(IDTools, name, doctor.Warn, "optional tool missing on the service PATH: "+strings.Join(warn, ", "), fix)
+	}
+	return check(IDTools, name, doctor.Pass, fmt.Sprintf("%d gate tool(s) found on the service PATH", len(f.Tools)), "")
+}
+
+func providerCheck(f Facts) doctor.Check {
+	const name = "provider"
+	p := f.Provider
+	switch {
+	case p.Err != "":
+		return unread(IDProvider, name, "the provider state", p.Err)
+	case !p.LoggedIn:
+		return check(IDProvider, name, doctor.Fail, "the provider CLI is not logged in", "Run `gh auth login` as the user the service runs as")
+	case !p.Reachable:
+		return check(IDProvider, name, doctor.Fail, "the provider API did not answer", "Check the network and the provider status page")
+	}
+	return check(IDProvider, name, doctor.Pass, "logged in and the API answers", "")
+}
+
+func repoCheck(f Facts) doctor.Check {
+	if f.Repo.OK {
+		return check(IDRepo, "repository read", doctor.Pass, "the repository is readable", "")
+	}
+	return check(IDRepo, "repository read", doctor.Fail, "the repository cannot be read: "+f.Repo.Err, "Check the path and its permissions for the user the service runs as")
+}
+
+func diskCheck(f Facts, l Limits) doctor.Check {
+	const name = "free disk"
+	d := f.Disk
+	switch {
+	case d.Err != "":
+		return unread(IDDisk, name, "the free space", d.Err)
+	case d.FreeMB < l.MinFreeMB:
+		return check(IDDisk, name, doctor.Fail, fmt.Sprintf("%d MB free, below the %d MB floor", d.FreeMB, l.MinFreeMB), "Run `nself ci runs prune --tidy --apply`")
+	case d.FreeMB < 2*l.MinFreeMB:
+		return check(IDDisk, name, doctor.Warn, fmt.Sprintf("%d MB free, close to the %d MB floor", d.FreeMB, l.MinFreeMB), "Run `nself ci runs prune --tidy` to see what can be freed")
+	}
+	return check(IDDisk, name, doctor.Pass, fmt.Sprintf("%d MB free", d.FreeMB), "")
+}
+
+func sinksCheck(f Facts, l Limits) doctor.Check {
+	const name = "notifier delivery"
+	if f.Sinks.Err != "" {
+		return unread(IDSinks, name, "the delivery counters", f.Sinks.Err)
+	}
+	var dead, recent []string
+	for _, s := range f.Sinks.List {
+		switch {
+		case s.Failed > 0 && s.Delivered == 0:
+			dead = append(dead, s.Name)
+		case s.Failed > 0 && f.Now.Sub(s.LastFailedAt) < l.SinkWindow:
+			recent = append(recent, s.Name)
+		}
+	}
+	fix := "Check the sink settings (`notify.sinks`) and the receiver"
+	switch {
+	case len(dead) > 0:
+		return check(IDSinks, name, doctor.Fail, "no delivery ever succeeded: "+strings.Join(dead, ", "), fix)
+	case len(recent) > 0:
+		return check(IDSinks, name, doctor.Warn, "a delivery failed in the last 24 h: "+strings.Join(recent, ", "), fix)
+	}
+	return check(IDSinks, name, doctor.Pass, fmt.Sprintf("%d sink(s), no recent delivery failure", len(f.Sinks.List)), "")
+}
diff --git a/free/ci/internal/selftest/checks_state.go b/free/ci/internal/selftest/checks_state.go
new file mode 100644
index 000000000..2de54ff22
--- /dev/null
+++ b/free/ci/internal/selftest/checks_state.go
@@ -0,0 +1,93 @@
+package selftest
+
+// Purpose: the checks CI-DS006–CI-DS009, the state half of the selftest: the
+// watcher, its claims, leftover job roots and infrastructure failures.
+// Inputs:  Facts and Limits. Outputs: doctor checks. Constraints: pure.
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/claims"
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+)
+
+func watcherCheck(f Facts, l Limits) doctor.Check {
+	const name = "watcher"
+	w := f.Watcher
+	if w.Err != "" {
+		return unread(IDWatcher, name, "the demand file", w.Err)
+	}
+	if !w.Present {
+		return check(IDWatcher, name, doctor.Pass, "no watcher runs on this host", "")
+	}
+	iv := w.Interval
+	if iv <= 0 {
+		iv = DefaultInterval
+	}
+	if limit := time.Duration(l.WatcherPasses) * iv; w.Age > limit {
+		return check(IDWatcher, name, doctor.Fail, fmt.Sprintf("the demand file is %s old, over %d intervals of %s", w.Age.Round(time.Second), l.WatcherPasses, iv),
+			"Restart the service: `nself ci serve install --launchd|--systemd`, or look at the watcher log")
+	}
+	return check(IDWatcher, name, doctor.Pass, fmt.Sprintf("the demand file is %s old", w.Age.Round(time.Second)), "")
+}
+
+func claimsCheck(f Facts) doctor.Check {
+	const name = "stuck claims"
+	c := f.Claims
+	if c.Err != "" {
+		return unread(IDClaims, name, "the claims of this host", c.Err)
+	}
+	if !c.Known {
+		return check(IDClaims, name, doctor.Pass, "no claim source on this host", "")
+	}
+	limit := c.RunLimit + claims.DeadGrace
+	var stuck []string
+	for _, cl := range c.List {
+		if cl.Age > limit {
+			stuck = append(stuck, cl.Ref)
+		}
+	}
+	if len(stuck) > 0 {
+		sort.Strings(stuck)
+		return check(IDClaims, name, doctor.Fail, fmt.Sprintf("%d claim(s) older than the run limit plus %s: %s", len(stuck), claims.DeadGrace, strings.Join(stuck, ", ")),
+			"Restart the watcher; another host takes the commit once the claim is dead")
+	}
+	return check(IDClaims, name, doctor.Pass, fmt.Sprintf("%d open claim(s), none stuck", len(c.List)), "")
+}
+
+func orphansCheck(f Facts) doctor.Check {
+	const name = "leaked temp folders"
+	o := f.Orphans
+	switch {
+	case o.Err != "":
+		return unread(IDOrphans, name, "the job roots", o.Err)
+	case len(o.List) > 0:
+		names := append([]string(nil), o.List...)
+		sort.Strings(names)
+		if len(names) > 5 {
+			names = append(names[:5], "…")
+		}
+		return check(IDOrphans, name, doctor.Fail, fmt.Sprintf("%d job root(s) no live attempt owns: %s", len(o.List), strings.Join(names, ", ")), "Run `nself ci runs prune --tidy --apply`")
+	}
+	return check(IDOrphans, name, doctor.Pass, "no leftover job roots", "")
+}
+
+func infraCheck(f Facts, l Limits) doctor.Check {
+	const name = "infrastructure failures"
+	in := f.Infra
+	if in.Err != "" {
+		return unread(IDInfra, name, "the run history", in.Err)
+	}
+	msg := fmt.Sprintf("%d of %d run(s) in the last 24 h ended in an infrastructure error", in.Count, in.Total)
+	fix := "Run `nself ci doctor` and read the failing runs with `nself ci runs list`"
+	switch {
+	case in.Count >= l.InfraFail:
+		return check(IDInfra, name, doctor.Fail, msg, fix)
+	case in.Count >= l.InfraWarn:
+		return check(IDInfra, name, doctor.Warn, msg, fix)
+	}
+	return check(IDInfra, name, doctor.Pass, msg, "")
+}
diff --git a/free/ci/internal/selftest/disk_unix.go b/free/ci/internal/selftest/disk_unix.go
new file mode 100644
index 000000000..91f381525
--- /dev/null
+++ b/free/ci/internal/selftest/disk_unix.go
@@ -0,0 +1,21 @@
+//go:build !windows
+
+package selftest
+
+import (
+	"fmt"
+	"syscall"
+)
+
+// FreeMB returns the megabytes a non-root user may still write under dir.
+func FreeMB(dir string) (int64, error) {
+	var st syscall.Statfs_t
+	if err := syscall.Statfs(dir, &st); err != nil {
+		return 0, err
+	}
+	free := int64(st.Bavail) * int64(st.Bsize) / (1 << 20)
+	if free < 0 {
+		return 0, fmt.Errorf("statfs %s returned a negative size", dir)
+	}
+	return free, nil
+}
diff --git a/free/ci/internal/selftest/disk_windows.go b/free/ci/internal/selftest/disk_windows.go
new file mode 100644
index 000000000..a5b7b5908
--- /dev/null
+++ b/free/ci/internal/selftest/disk_windows.go
@@ -0,0 +1,8 @@
+//go:build windows
+
+package selftest
+
+import "errors"
+
+// FreeMB is not available on this platform; the disk check then warns.
+func FreeMB(string) (int64, error) { return 0, errors.New("free space is not read on this platform") }
diff --git a/free/ci/internal/selftest/facts.go b/free/ci/internal/selftest/facts.go
new file mode 100644
index 000000000..be09ac1af
--- /dev/null
+++ b/free/ci/internal/selftest/facts.go
@@ -0,0 +1,121 @@
+// Package selftest backs `nself ci doctor --selftest [--alert]` and
+// `nself ci runs prune --tidy` (P7-AUTO-20): the health checks of an unattended
+// host, the once-a-day alert, and the tidy plan that frees disk.
+//
+// Purpose: turn observations of one host (tools, login, disk, notifier counters,
+// watcher liveness, claims, leftover job roots, infrastructure failures) into
+// doctor checks CI-DS001… and decide whether an alert is due.
+// Inputs:  Facts, gathered by Local or built by a test; Limits.
+// Outputs: doctor.Check values; one notifier message per failing set per day.
+// Constraints: Evaluate is pure (no clock, no I/O). A fact that could not be read
+// is a warning naming the cause, never a pass. Nothing here removes anything
+// except Tidy.Apply, and only when the caller asks for it.
+package selftest
+
+import "time"
+
+// Tool is one gate tool looked up on the explicit PATH.
+type Tool struct {
+	Name     string
+	Path     string
+	Found    bool
+	Required bool // a missing required tool fails the check, an optional one warns
+}
+
+// Provider is the provider login and API reachability.
+type Provider struct {
+	LoggedIn  bool
+	Reachable bool
+	Err       string // why the state could not be read
+}
+
+// Probe is one pass/fail observation with the reason.
+type Probe struct {
+	OK  bool
+	Err string
+}
+
+// Disk is the free space under the CI home.
+type Disk struct {
+	FreeMB int64
+	Err    string
+}
+
+// Sink holds one notifier sink's delivery counters (P7-AUTO-18).
+type Sink struct {
+	Name         string
+	Delivered    int64
+	Failed       int64
+	LastFailedAt time.Time // zero: never failed
+}
+
+// Sinks are the counters of every sink.
+type Sinks struct {
+	List []Sink
+	Err  string
+}
+
+// Watcher is the demand file of the watcher on this host.
+type Watcher struct {
+	Present  bool // a demand file exists
+	Age      time.Duration
+	Interval time.Duration // the watcher's pass interval; 0 means the default
+	Err      string
+}
+
+// Claim is a claim of this host that has not seen a status since Age ago.
+type Claim struct {
+	Ref string // repo@sha
+	Age time.Duration
+}
+
+// Claims are the open claims of this host.
+type Claims struct {
+	Known    bool // false: no claim source on this host
+	List     []Claim
+	RunLimit time.Duration
+	Err      string
+}
+
+// Orphans are the job-root folders no live attempt owns (TRUST-09).
+type Orphans struct {
+	List []string
+	Err  string
+}
+
+// Infra counts finished runs of the last 24 hours that ended in an infrastructure error.
+type Infra struct {
+	Count, Total int
+	Err          string
+}
+
+// Facts is everything one selftest looks at.
+type Facts struct {
+	Now      time.Time
+	Tools    []Tool
+	Provider Provider
+	Repo     Probe
+	Disk     Disk
+	Sinks    Sinks
+	Watcher  Watcher
+	Claims   Claims
+	Orphans  Orphans
+	Infra    Infra
+}
+
+// Limits are the thresholds the checks apply.
+type Limits struct {
+	MinFreeMB     int64         // below this the disk check fails; twice this warns
+	WatcherPasses int           // demand file older than this many intervals fails
+	InfraWarn     int           // infrastructure failures in 24 h that warn
+	InfraFail     int           // infrastructure failures in 24 h that fail
+	SinkWindow    time.Duration // a sink failure newer than this warns
+}
+
+// DefaultInterval is the watcher interval assumed when the demand file names none.
+const DefaultInterval = 5 * time.Minute
+
+// DefaultLimits returns the shipped thresholds.
+func DefaultLimits() Limits {
+	return Limits{MinFreeMB: 2048, WatcherPasses: 3, InfraWarn: 1, InfraFail: 3, SinkWindow: 24 * time.Hour}
+}
diff --git a/free/ci/internal/selftest/keys.go b/free/ci/internal/selftest/keys.go
new file mode 100644
index 000000000..8246eb070
--- /dev/null
+++ b/free/ci/internal/selftest/keys.go
@@ -0,0 +1,89 @@
+package selftest
+
+// Purpose: the two operator keys of the tidy (P7-AUTO-20): tidy.free_target_mb, the free space
+// `runs prune --tidy --apply` tries to reach, and tidy.cache_cap_mb, the byte cap it applies to
+// the cache (0: the cache's own cap).
+// Inputs:  the effective policy. Outputs: TidyConfig.
+// Constraints: the keys are fixed: only the operator scopes set them, a repository cannot.
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+)
+
+// Policy keys of the tidy.
+const (
+	KeyFreeTarget = "tidy.free_target_mb"
+	KeyCacheCap   = "tidy.cache_cap_mb"
+)
+
+// DefaultFreeTargetMB is the free space the tidy aims for when the operator names none.
+const DefaultFreeTargetMB = 5120
+
+const maxMB = 100_000_000
+
+// TidyConfig is the resolved tidy.* policy.
+type TidyConfig struct {
+	FreeTargetMB int64
+	CacheCapMB   int64 // 0: leave the cache's own cap
+}
+
+var registrationErrors []error
+
+// RegistrationErrors returns what init() could not register; empty when both keys are in the key set.
+func RegistrationErrors() []error { return append([]error(nil), registrationErrors...) }
+
+func init() {
+	for _, spec := range Keys() {
+		if err := policy.RegisterKey(spec); err != nil {
+			registrationErrors = append(registrationErrors, err)
+		}
+	}
+}
+
+// Keys returns the spec of both keys.
+func Keys() []policy.KeySpec {
+	k := func(key string, def int64) policy.KeySpec {
+		return policy.KeySpec{Key: key, Owner: "selftest", Kind: policy.TightenFixed, Default: def, Decode: func(raw json.RawMessage) (any, error) { return decodeMB(key, raw) }}
+	}
+	return []policy.KeySpec{k(KeyFreeTarget, DefaultFreeTargetMB), k(KeyCacheCap, 0)}
+}
+
+func decodeMB(key string, raw json.RawMessage) (any, error) {
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.DisallowUnknownFields()
+	var n int64
+	if err := dec.Decode(&n); err != nil || n < 0 || n > maxMB {
+		return nil, fmt.Errorf("E672 %s: expected a whole number of megabytes from 0 to %d", key, maxMB)
+	}
+	return n, nil
+}
+
+// TidyConfigFrom reads the effective policy; a nil Effective is an error.
+func TidyConfigFrom(eff *policy.Effective) (TidyConfig, error) {
+	if eff == nil {
+		return TidyConfig{}, fmt.Errorf("selftest: no effective policy")
+	}
+	c := TidyConfig{FreeTargetMB: DefaultFreeTargetMB}
+	read := func(key string, into *int64) error {
+		v, _, ok := eff.Value(key)
+		if !ok {
+			return nil
+		}
+		b, err := json.Marshal(v)
+		if err == nil {
+			err = json.Unmarshal(b, into)
+		}
+		if err != nil {
+			return fmt.Errorf("E672 %s: effective value is not a number", key)
+		}
+		return nil
+	}
+	if err := read(KeyFreeTarget, &c.FreeTargetMB); err != nil {
+		return TidyConfig{}, err
+	}
+	return c, read(KeyCacheCap, &c.CacheCapMB)
+}
diff --git a/free/ci/internal/selftest/local.go b/free/ci/internal/selftest/local.go
new file mode 100644
index 000000000..3eda72f1f
--- /dev/null
+++ b/free/ci/internal/selftest/local.go
@@ -0,0 +1,169 @@
+package selftest
+
+// Purpose: gather the Facts of the real host. Everything that needs the run store
+// (delivery counters, claims, run results) is a function field the command wires, so
+// this file has no store and tests need none.
+// Inputs:  the repository root, the CI home, the explicit PATH, injectable seams.
+// Outputs: Facts. Constraints: each fact fails alone: an error becomes that fact's Err.
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+)
+
+// Local reads one host.
+type Local struct {
+	Root, Home string
+	Path       string   // the PATH the service runs with
+	Tools      []string // gate tools; nil uses DefaultTools
+	Capture    doctor.CaptureFunc
+	Now        func() time.Time // nil: time.Now
+	FreeMB     func(dir string) (int64, error)
+	// Sinks, Claims and Infra read the run store; nil means no store: no sinks, no claim
+	// source, no runs.
+	Sinks  func(ctx context.Context) ([]Sink, error)
+	Claims func(ctx context.Context) (Claims, error)
+	Infra  func(ctx context.Context, since time.Time) (count, total int, err error)
+}
+
+// DefaultTools are the gate tools; git and go are required.
+var DefaultTools = []string{"git", "go", "gh", "pnpm", "govulncheck"}
+
+func (l Local) now() time.Time {
+	if l.Now != nil {
+		return l.Now().UTC()
+	}
+	return time.Now().UTC()
+}
+
+// Facts observes the host.
+func (l Local) Facts(ctx context.Context) Facts {
+	now := l.now()
+	f := Facts{Now: now, Tools: l.tools(), Provider: l.provider(ctx), Repo: l.repo(ctx)}
+	free := l.FreeMB
+	if free == nil {
+		free = FreeMB
+	}
+	if mb, err := free(l.Home); err != nil {
+		f.Disk.Err = err.Error()
+	} else {
+		f.Disk.FreeMB = mb
+	}
+	if l.Sinks != nil {
+		var err error
+		if f.Sinks.List, err = l.Sinks(ctx); err != nil {
+			f.Sinks.Err = err.Error()
+		}
+	}
+	f.Watcher = l.watcher(now)
+	if l.Claims != nil {
+		var err error
+		if f.Claims, err = l.Claims(ctx); err != nil {
+			f.Claims.Err = err.Error()
+		}
+	}
+	var err error
+	if f.Orphans.List, err = OrphanRoots(filepath.Join(l.Home, "work"), OrphanMinAge, now); err != nil {
+		f.Orphans.Err = err.Error()
+	}
+	if l.Infra != nil {
+		if f.Infra.Count, f.Infra.Total, err = l.Infra(ctx, now.Add(-24*time.Hour)); err != nil {
+			f.Infra.Err = err.Error()
+		}
+	}
+	return f
+}
+
+func (l Local) tools() []Tool {
+	names := l.Tools
+	if names == nil {
+		names = DefaultTools
+	}
+	var out []Tool
+	for _, n := range names {
+		p, ok := lookPath(l.Path, n)
+		out = append(out, Tool{Name: n, Path: p, Found: ok, Required: n == "git" || n == "go"})
+	}
+	return out
+}
+
+// lookPath finds name in the directories of path only, never in the caller's own PATH.
+func lookPath(path, name string) (string, bool) {
+	for _, dir := range filepath.SplitList(path) {
+		if dir == "" {
+			continue
+		}
+		for _, cand := range []string{name, name + ".exe"} {
+			p := filepath.Join(dir, cand)
+			if fi, err := os.Stat(p); err == nil && !fi.IsDir() && (runtime.GOOS == "windows" || fi.Mode()&0o111 != 0) {
+				return p, true
+			}
+		}
+	}
+	return "", false
+}
+
+func (l Local) provider(ctx context.Context) Provider {
+	if l.Capture == nil {
+		return Provider{Err: "no process runner"}
+	}
+	if _, ok := lookPath(l.Path, "gh"); !ok {
+		return Provider{Err: "gh is not on the service PATH"}
+	}
+	_, exit, err := l.Capture(ctx, "gh", "auth", "status")
+	if err != nil {
+		return Provider{Err: err.Error()}
+	}
+	if exit != 0 {
+		return Provider{}
+	}
+	_, exit, err = l.Capture(ctx, "gh", "api", "rate_limit")
+	return Provider{LoggedIn: true, Reachable: err == nil && exit == 0}
+}
+
+func (l Local) repo(ctx context.Context) Probe {
+	if l.Capture == nil {
+		return Probe{Err: "no process runner"}
+	}
+	out, exit, err := l.Capture(ctx, "git", "-C", l.Root, "rev-parse", "--git-dir")
+	switch {
+	case err != nil:
+		return Probe{Err: err.Error()}
+	case exit != 0:
+		return Probe{Err: "git cannot read " + l.Root + ": " + firstLine(out)}
+	}
+	return Probe{OK: true}
+}
+
+func (l Local) watcher(now time.Time) Watcher {
+	snap, err := demand.Read(demand.ReadConfig{Dir: l.Home, Clock: fixedClock(now)})
+	switch {
+	case err != nil && errors.Is(err, os.ErrPermission):
+		return Watcher{Err: err.Error()}
+	case err != nil:
+		return Watcher{Present: true, Age: 1 << 62, Err: ""} // unreadable or half-written: treated as stale
+	case !snap.Doc.Watcher.Alive:
+		return Watcher{}
+	}
+	return Watcher{Present: true, Age: snap.Age, Interval: time.Duration(snap.Doc.Watcher.IntervalSec * float64(time.Second))}
+}
+
+type fixedClock time.Time
+
+func (c fixedClock) Now() time.Time { return time.Time(c) }
+
+func firstLine(s string) string {
+	for i, r := range s {
+		if r == '\n' {
+			return s[:i]
+		}
+	}
+	return s
+}
diff --git a/free/ci/internal/selftest/orphans.go b/free/ci/internal/selftest/orphans.go
new file mode 100644
index 000000000..6889965b5
--- /dev/null
+++ b/free/ci/internal/selftest/orphans.go
@@ -0,0 +1,55 @@
+package selftest
+
+// Purpose: list the job-root folders no live attempt owns (the TRUST-09 orphan list), for
+// the leak check and for the tidy plan, with the same filter hygiene.SweepOrphans applies.
+// Inputs:  the job-root base (<home>/work), the minimum age, the time. Outputs: folder names.
+// Constraints: read-only; a base that is a symlink or not a directory is an error, as for
+// the sweep; only names shaped like an attempt (`<job row>.a<N>`) older than minAge count.
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+	"sort"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/hygiene"
+)
+
+// OrphanMinAge protects a root a sibling process may still be creating.
+const OrphanMinAge = time.Hour
+
+var attemptShape = regexp.MustCompile(`^.+\.a[0-9]+$`)
+
+// OrphanRoots returns the sorted names under base that a sweep would remove.
+func OrphanRoots(base string, minAge time.Duration, now time.Time) ([]string, error) {
+	if base == "" {
+		return nil, nil
+	}
+	info, err := os.Lstat(base)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
+		return nil, fmt.Errorf("job root base %s is not a plain directory", base)
+	}
+	entries, err := os.ReadDir(base)
+	if err != nil {
+		return nil, err
+	}
+	var out []string
+	for _, e := range entries {
+		name := e.Name()
+		if !hygiene.ValidAttempt(name) || !attemptShape.MatchString(name) {
+			continue
+		}
+		if fi, err := e.Info(); err == nil && now.Sub(fi.ModTime()) >= minAge {
+			out = append(out, name)
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
diff --git a/free/ci/internal/selftest/selftest_test.go b/free/ci/internal/selftest/selftest_test.go
new file mode 100644
index 000000000..b0e4badd1
--- /dev/null
+++ b/free/ci/internal/selftest/selftest_test.go
@@ -0,0 +1,233 @@
+package selftest
+
+// Purpose: P7-AUTO-20 acceptance for the pure half of the selftest: planted
+// faults flip the matching check, the alert goes out once per failing set per
+// UTC day, and a tidy is report-only unless applied.
+// Inputs: hand-built Facts, a fake notifier, fake tidy steps, a temp state file.
+// Outputs: pass or fail. Constraints: no clock reads, no real disk or network.
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/notify"
+)
+
+var day1 = time.Date(2026, 10, 20, 9, 0, 0, 0, time.UTC)
+
+// healthy is a host with nothing wrong: every selftest check passes.
+func healthy() Facts {
+	return Facts{
+		Now:      day1,
+		Tools:    []Tool{{Name: "go", Found: true, Required: true}, {Name: "gitleaks", Found: true}},
+		Provider: Provider{LoggedIn: true, Reachable: true},
+		Repo:     Probe{OK: true},
+		Disk:     Disk{FreeMB: 100000},
+		Sinks:    Sinks{List: []Sink{{Name: "ntfy", Delivered: 3}}},
+		Watcher:  Watcher{Present: true, Age: time.Minute, Interval: time.Minute},
+		Claims:   Claims{Known: true, RunLimit: time.Hour, List: []Claim{{Ref: "o/r@aaa", Age: time.Minute}}},
+		Infra:    Infra{Total: 10},
+	}
+}
+
+func statusOf(checks []doctor.Check) map[string]doctor.Status {
+	out := map[string]doctor.Status{}
+	for _, c := range checks {
+		out[c.ID] = c.Status
+	}
+	return out
+}
+
+func TestSelftestChecksFlip(t *testing.T) {
+	l := DefaultLimits()
+	base := Evaluate(healthy(), l)
+	if len(base) != 9 {
+		t.Fatalf("want nine selftest checks, got %d", len(base))
+	}
+	for _, c := range base {
+		if c.Status != doctor.Pass {
+			t.Fatalf("a healthy host must pass every check, %s is %s: %s", c.ID, c.Status, c.Message)
+		}
+	}
+	plants := []struct {
+		id    string
+		plant func(*Facts)
+	}{
+		{IDClaims, func(f *Facts) {
+			f.Claims.List = append(f.Claims.List, Claim{Ref: "o/r@bbb", Age: time.Hour + 11*time.Minute})
+		}},
+		{IDOrphans, func(f *Facts) { f.Orphans.List = []string{"job-root-123"} }},
+		{IDInfra, func(f *Facts) { f.Infra.Count = l.InfraFail }},
+		{IDWatcher, func(f *Facts) { f.Watcher.Age = 4 * time.Minute }},
+		{IDDisk, func(f *Facts) { f.Disk.FreeMB = l.MinFreeMB - 1 }},
+		{IDTools, func(f *Facts) { f.Tools[0].Found = false }},
+	}
+	for _, p := range plants {
+		t.Run(p.id, func(t *testing.T) {
+			f := healthy()
+			p.plant(&f)
+			got := statusOf(Evaluate(f, l))
+			for id, st := range got {
+				want := doctor.Pass
+				if id == p.id {
+					want = doctor.Fail
+				}
+				if st != want {
+					t.Fatalf("planting %s: %s is %s, want %s", p.id, id, st, want)
+				}
+			}
+		})
+	}
+	// A fact that could not be read warns with the cause; it is never a pass.
+	f := healthy()
+	f.Orphans.Err = "permission denied"
+	if got := statusOf(Evaluate(f, l))[IDOrphans]; got != doctor.Warn {
+		t.Fatalf("an unreadable fact must warn, got %s", got)
+	}
+}
+
+// fakeSink records what it was sent; fail makes it refuse.
+type fakeSink struct {
+	got  []notify.Event
+	fail bool
+}
+
+func (s *fakeSink) Name() string { return "fake" }
+func (s *fakeSink) Notify(_ context.Context, ev notify.Event) error {
+	if s.fail {
+		return errors.New("refused")
+	}
+	s.got = append(s.got, ev)
+	return nil
+}
+
+func failing(ids ...string) []doctor.Check {
+	out := []doctor.Check{{ID: IDTools, Name: "gate tools", Status: doctor.Pass}}
+	for _, id := range ids {
+		out = append(out, doctor.Check{ID: id, Name: "check " + id, Status: doctor.Fail})
+	}
+	return out
+}
+
+func TestSelftestAlertOncePerDay(t *testing.T) {
+	ctx := context.Background()
+	sink := &fakeSink{}
+	now := day1
+	a := Alerter{Sinks: []notify.Notifier{sink}, StatePath: filepath.Join(t.TempDir(), "alert.json"), Host: "mini1", Now: func() time.Time { return now }}
+	steps := []struct {
+		name   string
+		at     time.Time
+		checks []doctor.Check
+		sent   bool
+	}{
+		{"first failing set is sent", day1, failing(IDClaims), true},
+		{"the same set later that day is not", day1.Add(10 * time.Hour), failing(IDClaims), false},
+		{"one more failing check is a new set", day1.Add(11 * time.Hour), failing(IDClaims, IDOrphans), true},
+		{"a clean report sends nothing", day1.Add(12 * time.Hour), failing(), false},
+		{"the next UTC day sends the set again", day1.Add(24 * time.Hour), failing(IDClaims), true},
+	}
+	want := 0
+	for _, s := range steps {
+		now = s.at
+		res, err := a.Alert(ctx, s.checks)
+		if err != nil {
+			t.Fatalf("%s: %v", s.name, err)
+		}
+		if res.Sent != s.sent {
+			t.Fatalf("%s: sent=%v (%+v)", s.name, res.Sent, res)
+		}
+		if s.sent {
+			want++
+		}
+		if len(sink.got) != want {
+			t.Fatalf("%s: %d message(s) sent, want %d", s.name, len(sink.got), want)
+		}
+	}
+	if msg := sink.got[1].Message; !strings.Contains(msg, IDClaims) || !strings.Contains(msg, IDOrphans) || !strings.Contains(msg, "mini1") {
+		t.Fatalf("the message must name the host and every failing id: %q", msg)
+	}
+	// A set no sink took is not recorded, so the next run tries again.
+	refusing := &fakeSink{fail: true}
+	b := Alerter{Sinks: []notify.Notifier{refusing}, StatePath: filepath.Join(t.TempDir(), "alert.json"), Now: func() time.Time { return day1 }}
+	if res, _ := b.Alert(ctx, failing(IDInfra)); res.Sent {
+		t.Fatal("a refused message must not count as sent")
+	}
+	b.Sinks = []notify.Notifier{sink}
+	if res, err := b.Alert(ctx, failing(IDInfra)); err != nil || !res.Sent {
+		t.Fatalf("a set no sink took must be tried again: %+v %v", res, err)
+	}
+}
+
+// tidyRig is a disk whose free space grows by what the steps remove.
+type tidyRig struct {
+	free    int64
+	applied map[string][]Item
+}
+
+func (r *tidyRig) step(name string, items ...Item) Step {
+	return Step{Name: name,
+		Plan: func(context.Context) ([]Item, error) { return items, nil },
+		Apply: func(_ context.Context, got []Item) error {
+			r.applied[name] = got
+			for _, it := range got {
+				r.free += it.Bytes >> 20
+			}
+			return nil
+		}}
+}
+
+func (r *tidyRig) tidy(target int64) Tidy {
+	return Tidy{TargetMB: target, FreeMB: func() (int64, error) { return r.free, nil }, Steps: []Step{
+		r.step("history", Item{Step: "history", ID: "run_1", Bytes: 300 << 20}),
+		r.step("cache", Item{Step: "cache", ID: "entry_a", Bytes: 500 << 20}, Item{Step: "cache", ID: "entry_b", Bytes: 200 << 20}),
+		r.step("orphans", Item{Step: "orphans", ID: "job-root-9", Bytes: 100 << 20}),
+	}}
+}
+
+func TestTidyReportOnlyByDefault(t *testing.T) {
+	r := &tidyRig{free: 1000, applied: map[string][]Item{}}
+	rep, err := r.tidy(1800).Run(context.Background(), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(r.applied) != 0 || r.free != 1000 {
+		t.Fatalf("a report-only tidy removed something: %+v", r.applied)
+	}
+	if rep.Apply || len(rep.Items) != 4 || rep.FreeAfterMB != 1000 || !strings.Contains(rep.Why, "--apply would remove 4 item(s)") {
+		t.Fatalf("the report must list exactly what --apply would remove: %+v", rep)
+	}
+}
+
+func TestTidyApplyReachesTarget(t *testing.T) {
+	r := &tidyRig{free: 1000, applied: map[string][]Item{}}
+	plan, _ := r.tidy(1800).Run(context.Background(), false)
+	rep, err := r.tidy(1800).Run(context.Background(), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var applied []Item
+	for _, name := range []string{"history", "cache", "orphans"} {
+		applied = append(applied, r.applied[name]...)
+	}
+	if !reflect.DeepEqual(applied, plan.Items) {
+		t.Fatalf("apply must remove exactly the planned items:\n got %+v\nwant %+v", applied, plan.Items)
+	}
+	if !rep.Reached || rep.FreeBeforeMB != 1000 || rep.FreeAfterMB != 2100 || rep.Why != "" {
+		t.Fatalf("the tidy must reach the target: %+v", rep)
+	}
+	// A target out of reach is reported with why, never claimed.
+	r2 := &tidyRig{free: 1000, applied: map[string][]Item{}}
+	far, err := r2.tidy(5000).Run(context.Background(), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if far.Reached || !strings.Contains(far.Why, "below the 5000 MB target") {
+		t.Fatalf("an unreachable target must say why: %+v", far)
+	}
+}
diff --git a/free/ci/internal/selftest/tidy.go b/free/ci/internal/selftest/tidy.go
new file mode 100644
index 000000000..5251e391d
--- /dev/null
+++ b/free/ci/internal/selftest/tidy.go
@@ -0,0 +1,96 @@
+package selftest
+
+// Purpose: `runs prune --tidy [--apply]`: compose the run-history retention prune, the cache
+// prune and the orphan job-root sweep, and measure the free-space target.
+// Inputs:  the steps (each can list what it would remove and then remove exactly that),
+// a free-space reader, the target in MB.
+// Outputs: a Report listing every item; with Apply the free space before and after and
+// whether the target was reached or why not.
+// Constraints: without Apply nothing is removed, and the listed items are exactly what
+// Apply removes (a step plans once; Apply performs that plan). A step whose plan failed
+// is skipped and named in Errors; the other steps still run.
+
+import (
+	"context"
+	"fmt"
+)
+
+// Item is one thing a tidy removes.
+type Item struct {
+	Step  string `json:"step"`
+	ID    string `json:"id"`
+	Bytes int64  `json:"bytes,omitempty"`
+}
+
+// Step is one part of a tidy. Plan lists what Apply would remove; Apply removes exactly the
+// items Plan returned.
+type Step struct {
+	Name  string
+	Plan  func(ctx context.Context) ([]Item, error)
+	Apply func(ctx context.Context, items []Item) error
+}
+
+// Tidy runs the steps.
+type Tidy struct {
+	Steps    []Step
+	FreeMB   func() (int64, error)
+	TargetMB int64
+}
+
+// Report is the outcome of a tidy.
+type Report struct {
+	Apply        bool     `json:"apply"`
+	Items        []Item   `json:"items"`
+	FreeBeforeMB int64    `json:"free_before_mb"`
+	FreeAfterMB  int64    `json:"free_after_mb"`
+	TargetMB     int64    `json:"target_mb"`
+	Reached      bool     `json:"reached"`
+	Why          string   `json:"why,omitempty"`
+	Errors       []string `json:"errors,omitempty"`
+}
+
+// Run plans every step and, with apply, removes what was planned.
+func (t Tidy) Run(ctx context.Context, apply bool) (Report, error) {
+	rep := Report{Apply: apply, TargetMB: t.TargetMB, Items: []Item{}}
+	before, err := t.FreeMB()
+	if err != nil {
+		return rep, fmt.Errorf("free space not readable: %w", err)
+	}
+	rep.FreeBeforeMB, rep.FreeAfterMB = before, before
+	planned := make([][]Item, len(t.Steps))
+	for i, s := range t.Steps {
+		items, perr := s.Plan(ctx)
+		if perr != nil {
+			rep.Errors = append(rep.Errors, s.Name+": "+perr.Error())
+			continue
+		}
+		planned[i] = items
+		rep.Items = append(rep.Items, items...)
+	}
+	if !apply {
+		rep.Reached = before >= t.TargetMB
+		rep.Why = fmt.Sprintf("report only: --apply would remove %d item(s)", len(rep.Items))
+		return rep, nil
+	}
+	for i, s := range t.Steps {
+		if len(planned[i]) == 0 {
+			continue
+		}
+		if aerr := s.Apply(ctx, planned[i]); aerr != nil {
+			rep.Errors = append(rep.Errors, s.Name+": "+aerr.Error())
+		}
+	}
+	after, err := t.FreeMB()
+	if err != nil {
+		return rep, fmt.Errorf("free space not readable after the tidy: %w", err)
+	}
+	rep.FreeAfterMB, rep.Reached = after, after >= t.TargetMB
+	if !rep.Reached {
+		rep.Why = fmt.Sprintf("freed %d MB; %d MB free is %d MB below the %d MB target and nothing else is tidy to remove (history, cache and job roots are done)",
+			after-before, after, t.TargetMB-after, t.TargetMB)
+		if len(rep.Errors) > 0 {
+			rep.Why += "; " + fmt.Sprintf("%d step(s) failed, see errors", len(rep.Errors))
+		}
+	}
+	return rep, nil
+}
diff --git a/free/ci/internal/selftest/tidy_history.go b/free/ci/internal/selftest/tidy_history.go
new file mode 100644
index 000000000..6129d584c
--- /dev/null
+++ b/free/ci/internal/selftest/tidy_history.go
@@ -0,0 +1,92 @@
+package selftest
+
+// Purpose: the tidy steps that need the run store: the CI-39 retention prune of run history
+// and logs, and the cache prune with the operator's byte cap.
+// Constraints: Plan only reads; Apply performs the real prune. The history prune is its own
+// planner (a dry run of history.Prune), so the list and the removal use one rule.
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strconv"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/history"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// HistoryStep prunes run rows and logs by the retention policy.
+func HistoryStep(st *store.Store, home string, pol history.Policy, now func() time.Time) Step {
+	prune := func(ctx context.Context, dry bool) (history.PruneResult, error) {
+		return history.Prune(ctx, st, history.PruneParams{Home: home, Policy: pol, DryRun: dry, Now: now()})
+	}
+	return Step{
+		Name: "run history",
+		Plan: func(ctx context.Context) ([]Item, error) {
+			res, err := prune(ctx, true)
+			if err != nil {
+				return nil, err
+			}
+			var items []Item
+			for _, id := range res.Runs {
+				items = append(items, Item{Step: "run history", ID: "run " + id})
+			}
+			for _, id := range res.Orphans {
+				items = append(items, Item{Step: "run history", ID: "log dir " + id})
+			}
+			if len(items) > 0 && res.FreedBytes > 0 { // the freed log bytes belong to the step as a whole
+				items[0].Bytes = res.FreedBytes
+			}
+			return items, nil
+		},
+		Apply: func(ctx context.Context, _ []Item) error { _, err := prune(ctx, false); return err },
+	}
+}
+
+// CacheCapEnv returns a Getenv that applies the operator's cache cap (MB) on top of next; a cap
+// of 0 leaves the cache's own cap.
+func CacheCapEnv(capMB int64, next func(string) string) func(string) string {
+	return func(k string) string {
+		if k == "NSELF_CI_CACHE_MAX_BYTES" && capMB > 0 {
+			return strconv.FormatInt(capMB<<20, 10)
+		}
+		return next(k)
+	}
+}
+
+// CacheStep prunes the build cache. es must have been built with CacheCapEnv, so Caps reports the
+// cap Apply uses; the plan lists the least recently used entries past the age and byte caps.
+func CacheStep(be entries.Backend, es *entries.Store, budget time.Duration, now func() time.Time) Step {
+	return Step{
+		Name: "cache",
+		Plan: func(ctx context.Context) ([]Item, error) {
+			all, err := be.CacheEntries(ctx, "")
+			if err != nil {
+				return nil, err
+			}
+			maxBytes, maxAge := es.Caps()
+			sort.SliceStable(all, func(i, j int) bool { return all[i].LastUsedAt < all[j].LastUsedAt })
+			cutoff, total, dropped := now().Add(-maxAge).UnixNano(), int64(0), int64(0)
+			for _, m := range all {
+				total += m.Bytes()
+			}
+			var items []Item
+			for _, m := range all {
+				if m.LastUsedAt < cutoff || total-dropped > maxBytes {
+					items = append(items, Item{Step: "cache", ID: fmt.Sprintf("%s %.12s", m.Spec, m.Key), Bytes: m.Bytes()})
+					dropped += m.Bytes()
+				}
+			}
+			return items, nil
+		},
+		Apply: func(ctx context.Context, _ []Item) error {
+			res, err := es.Prune(ctx, budget)
+			if err == nil && res.More {
+				return fmt.Errorf("more cache entries remain; run the tidy again")
+			}
+			return err
+		},
+	}
+}
diff --git a/free/ci/internal/selftest/tidy_steps.go b/free/ci/internal/selftest/tidy_steps.go
new file mode 100644
index 000000000..f06cf587a
--- /dev/null
+++ b/free/ci/internal/selftest/tidy_steps.go
@@ -0,0 +1,43 @@
+package selftest
+
+// Purpose: the tidy step that needs no store: the orphan job-root sweep (TRUST-09).
+// The retention and cache steps need the run store and are built by the command.
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/hygiene"
+)
+
+// OrphanStep lists the job roots OrphanRoots finds and removes them with the hygiene sweep.
+// base is <home>/work; home holds the process markers.
+func OrphanStep(base, home string, now func() time.Time) Step {
+	return Step{
+		Name: "job roots",
+		Plan: func(context.Context) ([]Item, error) {
+			names, err := OrphanRoots(base, OrphanMinAge, now())
+			items := make([]Item, len(names))
+			for i, n := range names {
+				items[i] = Item{Step: "job roots", ID: n}
+			}
+			return items, err
+		},
+		Apply: func(ctx context.Context, _ []Item) error {
+			rep, err := (&hygiene.Host{Base: base, Home: home, MinAge: OrphanMinAge}).SweepOrphans(ctx, nil)
+			if err != nil {
+				return err
+			}
+			var failed []string
+			for what, ferr := range rep.Failed {
+				failed = append(failed, what+": "+ferr.Error())
+			}
+			if len(failed) > 0 {
+				return fmt.Errorf("%s", strings.Join(failed, "; "))
+			}
+			return nil
+		},
+	}
+}
diff --git a/free/ci/internal/signing/client.go b/free/ci/internal/signing/client.go
index 66e179c88..50a81248c 100644
--- a/free/ci/internal/signing/client.go
+++ b/free/ci/internal/signing/client.go
@@ -5,7 +5,8 @@ package signing
 // one request and read the envelopes back (cap:ci.release-signing: Sign,
 // PublicKey; P7-CACHE-17 and P7-CACHE-18 call it).
 // Inputs:  a Runner, the run's Source and a run id with payloads.
-// Outputs: DSSE envelopes in request order, or an E717 refusal.
+// Outputs: DSSE envelopes in request order, or an E717 refusal (with Audit set,
+// one release.sign.refused row per refused Sign).
 // Constraints: the signer's answer is checked for shape (one ci-release key id and one
 // 64-byte signature per item); its cryptographic check belongs to the verifier
 // that holds the trust file (P7-CACHE-09/18); the signer starts only when every attempt of the run is
@@ -21,6 +22,8 @@ import (
 	"crypto/ed25519"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
+	"fmt"
 	"os"
 	"time"
 
@@ -43,6 +46,10 @@ type Client struct {
 	// Team is set on a TEAM coordinator, which holds secret references only
 	// (Epic X8): it never starts the signer and never resolves the release key.
 	Team bool
+	// Audit, when set, records every refused Sign as release.sign.refused with
+	// its reason key (TM-18). The signer process never writes the store, so the
+	// coordinator records its refusals here.
+	Audit func(ctx context.Context, actor, action, target, detail string) error
 }
 
 func (c *Client) exe() (string, error) {
@@ -110,8 +117,20 @@ func signerRefusal(out []byte, code int) error {
 	return Failf(ReasonSignerFailed, "the signer failed (exit %d)", code)
 }
 
-// Sign signs the payloads of a finished run, or refuses.
+// Sign signs the payloads of a finished run, or refuses (and audits the refusal).
 func (c *Client) Sign(ctx context.Context, runID string, items []Item) ([]signing.Envelope, error) {
+	envs, err := c.sign(ctx, runID, items)
+	var e *Error
+	if err == nil || c.Audit == nil || !errors.As(err, &e) {
+		return envs, err
+	}
+	if aerr := c.Audit(ctx, "release", "release.sign.refused", runID, "reason="+e.Reason); aerr != nil {
+		return envs, errors.Join(err, fmt.Errorf("signer refusal audit: %w", aerr))
+	}
+	return envs, err
+}
+
+func (c *Client) sign(ctx context.Context, runID string, items []Item) ([]signing.Envelope, error) {
 	if c.Src == nil || c.Runner == nil {
 		return nil, Failf(ReasonSignerFailed, "the signer client has no run store or runner")
 	}
diff --git a/free/ci/internal/stats/blocks.go b/free/ci/internal/stats/blocks.go
new file mode 100644
index 000000000..6c358ab5f
--- /dev/null
+++ b/free/ci/internal/stats/blocks.go
@@ -0,0 +1,199 @@
+package stats
+
+// Purpose: the cache, spend, storage, lease, node, outbox and store blocks of contract:ci.stats.
+// Inputs:  the aggregated rows of the window (cache, spend) or of now (the rest).
+// Outputs: the matching Doc fields.
+// Constraints: a lease is stale when it expired under a leased or running attempt, self-fenced when its
+//          fence epoch predates the current coordinator incarnation, and active otherwise; nodes, the
+//          outbox and the store are coordinator-wide and appear only for a caller who may read it all.
+
+import (
+	"encoding/json"
+	"os"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func (d *Doc) buildCacheSpend(rows store.StatsRows, o Options) {
+	var c Cache
+	seen := false
+	for _, g := range rows.Cache {
+		if !o.visible(g.Project) {
+			continue
+		}
+		seen = true
+		switch g.Key {
+		case "hit":
+			c.Hits += g.N
+			c.BytesRestored += g.Sum
+		case "miss":
+			c.Misses += g.N
+		case "saved":
+			c.BytesSaved += g.Sum
+		}
+	}
+	switch {
+	case rows.Missing["cache_use"]:
+		d.Reasons["cache"] = ReasonNotInstalled
+	case !seen:
+		d.Reasons["cache"] = ReasonNoRows
+	default:
+		if n := c.Hits + c.Misses; n > 0 {
+			h := permille(c.Hits, n)
+			c.HitPermille = &h
+		} else {
+			d.Reasons["cache.hit_permille"] = ReasonNoLookups
+		}
+		d.Cache = &c
+	}
+	spend := map[string]Spend{}
+	for _, g := range rows.Ledger {
+		if o.visible(g.Project) {
+			s := spend[g.Key]
+			spend[g.Key] = Spend{Attempts: s.Attempts + g.N, Micro: s.Micro + g.Sum}
+		}
+	}
+	switch {
+	case rows.Missing["ledger"]:
+		d.Reasons["spend"] = ReasonNotInstalled
+	case len(spend) == 0:
+		d.Reasons["spend"] = ReasonNoRows
+	default:
+		for _, k := range []string{"known", "computed", "estimated", "unknown"} { // a real zero, the rows exist
+			if _, ok := spend[k]; !ok {
+				spend[k] = Spend{}
+			}
+		}
+		d.Spend = spend
+	}
+}
+
+func sumVisible(gs []store.StatGroup, o Options) (int64, bool) {
+	var n int64
+	var seen bool
+	for _, g := range gs {
+		if o.visible(g.Project) {
+			n, seen = n+g.Sum, true
+		}
+	}
+	return n, seen
+}
+
+func (d *Doc) buildPlatform(rows store.StatsRows, o Options) {
+	st := &Storage{}
+	for _, f := range []struct {
+		key   string
+		table string
+		rows  []store.StatGroup
+		dst   **int64
+	}{{"storage.cas_bytes", "cache_entry", rows.CAS, &st.CASBytes}, {"storage.artifact_bytes", "cache_artifact", rows.Artifacts, &st.ArtifactBytes}} {
+		switch n, seen := sumVisible(f.rows, o); {
+		case rows.Missing[f.table]:
+			d.Reasons[f.key] = ReasonNotInstalled
+		case !seen:
+			d.Reasons[f.key] = ReasonNoRows
+		default:
+			*f.dst = &n
+		}
+	}
+	d.Storage = st
+
+	now := o.Now.UnixNano()
+	var l Leases
+	for _, x := range rows.Leases {
+		if !o.visible(x.Project) {
+			continue
+		}
+		live := x.AttemptState == "leased" || x.AttemptState == "running"
+		switch {
+		case x.ExpiresAt < now && live:
+			l.Stale++
+		case live && x.Epoch > 0 && x.Epoch < rows.Incarnation<<32:
+			l.SelfFenced++
+		case x.ExpiresAt >= now:
+			l.Active++
+		}
+	}
+	d.Leases = &l
+
+	if !o.Global || o.Project != "" {
+		for _, k := range []string{"nodes", "outbox", "store"} {
+			d.Reasons[k] = ReasonScoped
+		}
+		return
+	}
+	d.buildNodes(rows, o.Now)
+	d.buildOutbox(rows, o.Now)
+	d.buildStore(rows)
+}
+
+func (d *Doc) buildNodes(rows store.StatsRows, now time.Time) {
+	switch {
+	case rows.Missing["node"]:
+		d.Reasons["nodes"] = ReasonNotInstalled
+	case len(rows.Nodes) == 0:
+		d.Reasons["nodes"] = ReasonNoRows
+	default:
+		n := &Nodes{ByState: map[string]int{}}
+		for _, x := range rows.Nodes {
+			n.ByState[x.State]++
+			if x.State == "offline" && now.UnixNano()-x.UpdatedAt > int64(24*time.Hour) {
+				n.OfflineOver24h++
+			}
+		}
+		d.Nodes = n
+	}
+}
+
+func (d *Doc) buildOutbox(rows store.StatsRows, now time.Time) {
+	if rows.Missing["outbox"] {
+		d.Reasons["outbox"] = ReasonNotInstalled
+		return
+	}
+	ob := &Outbox{Pending: rows.OutboxPending}
+	if rows.OutboxPending > 0 && rows.OutboxOldest > 0 {
+		age := (now.UnixNano() - rows.OutboxOldest) / int64(time.Millisecond)
+		ob.OldestAgeMs = &age
+	} else {
+		d.Reasons["outbox.oldest_age_ms"] = ReasonNonePending
+	}
+	d.Outbox = ob
+}
+
+func (d *Doc) buildStore(rows store.StatsRows) {
+	var size int64
+	for _, suffix := range []string{"", "-wal", "-shm"} {
+		if fi, err := os.Stat(rows.Path + suffix); err == nil {
+			size += fi.Size()
+		} else if suffix == "" {
+			d.Reasons["store"] = ReasonStoreUnstated
+			return
+		}
+	}
+	s := &StoreInfo{SizeBytes: size}
+	if free, ok := freeBytes(rows.Path); ok {
+		s.FreeBytes = &free
+	} else {
+		d.Reasons["store.free_bytes"] = ReasonStoreUnstated
+	}
+	d.Store = s
+}
+
+// nodeSlots maps a node id and name to its advertised slot count; nodes that state none are absent.
+func nodeSlots(nodes []store.StatNode) map[string]int {
+	out := map[string]int{}
+	for _, n := range nodes {
+		var doc struct {
+			Availability struct {
+				Slots struct {
+					Value *int `json:"value"`
+				} `json:"slots"`
+			} `json:"availability"`
+		}
+		if json.Unmarshal([]byte(n.Doc), &doc) == nil && doc.Availability.Slots.Value != nil {
+			out[n.ID], out[n.Name] = *doc.Availability.Slots.Value, *doc.Availability.Slots.Value
+		}
+	}
+	return out
+}
diff --git a/free/ci/internal/stats/compute.go b/free/ci/internal/stats/compute.go
new file mode 100644
index 000000000..6c8e41ef2
--- /dev/null
+++ b/free/ci/internal/stats/compute.go
@@ -0,0 +1,128 @@
+package stats
+
+// Purpose: assembles contract:ci.stats v1 from the rows internal/store reads (P7-SCHED-20, Epic SCHED D23).
+// Inputs:  Options (clock, window, project, visibility) and a store, or the rows themselves.
+// Outputs: Doc.
+// Constraints: read-only; a source that is absent or has no rows is null with a reason, never 0; the queue
+//          wait of a band is the telemetry wait of the finished attempts of that band; a project-scoped
+//          caller sees only coordinator-wide blocks that carry a project (leases, cache, spend, storage).
+
+import (
+	"context"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/fairq"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// Options selects what Compute reads.
+type Options struct {
+	Now     time.Time
+	Since   time.Duration // default 24h
+	Project string        // "" = all visible projects
+	// Allow reports whether the caller may read a project; nil allows all. Global says the caller may
+	// read the whole coordinator (all projects), which the blocks that carry no project need.
+	Allow  func(string) bool
+	Global bool
+}
+
+// DefaultSince is the window when none is given.
+const DefaultSince = 24 * time.Hour
+
+func (o Options) visible(project string) bool {
+	if o.Project != "" && project != o.Project {
+		return false
+	}
+	if project == "" {
+		return o.Global
+	}
+	return o.Allow == nil || o.Allow(project)
+}
+
+// Compute reads st in one read transaction and builds the document.
+func Compute(ctx context.Context, st *store.Store, o Options) (Doc, error) {
+	if o.Now.IsZero() {
+		o.Now = time.Now()
+	}
+	if o.Since <= 0 {
+		o.Since = DefaultSince
+	}
+	rows, err := st.StatsRead(ctx, store.StatsQuery{Now: o.Now, Since: o.Since, Project: o.Project})
+	if err != nil {
+		return Doc{}, err
+	}
+	return Build(rows, o), nil
+}
+
+// Build assembles the document from rows.
+func Build(rows store.StatsRows, o Options) Doc {
+	if o.Since <= 0 {
+		o.Since = DefaultSince
+	}
+	d := Doc{Contract: Contract, Version: Version, GeneratedAt: o.Now.UTC().Format(time.RFC3339), SinceMs: o.Since.Milliseconds(), Reasons: map[string]string{}}
+	if o.Project != "" {
+		p := o.Project
+		d.Project = &p
+	}
+	out := make([]store.StatOutcome, 0, len(rows.Outcomes))
+	for _, x := range rows.Outcomes {
+		if o.visible(x.Project) && (x.Result == "passed" || x.Result == "failed") {
+			out = append(out, x)
+		}
+	}
+	d.buildQueue(rows, out, o)
+	d.buildRuns(rows, out, o)
+	d.buildCacheSpend(rows, o)
+	d.buildPlatform(rows, o)
+	return d
+}
+
+func band(trigger string) string { return fairq.For("", trigger, false).String() }
+
+func (d *Doc) buildQueue(rows store.StatsRows, out []store.StatOutcome, o Options) {
+	depth := map[string]int{}
+	waits := map[string][]int64{}
+	for _, g := range rows.Queued {
+		if o.visible(g.Project) {
+			depth[band(g.Key)] += int(g.N)
+		}
+	}
+	bands := map[string]string{} // a trigger's band, worked out once per trigger instead of once per attempt
+	for _, x := range out {
+		if x.WaitMs >= 0 {
+			b, ok := bands[x.Trigger]
+			if !ok {
+				b = band(x.Trigger)
+				bands[x.Trigger] = b
+			}
+			waits[b] = append(waits[b], x.WaitMs)
+		}
+	}
+	if rows.Missing["schedtel_outcome"] && len(depth) == 0 {
+		d.Reasons["queue"] = ReasonNotInstalled
+		return
+	}
+	if len(depth) == 0 && len(waits) == 0 {
+		d.Reasons["queue"] = ReasonNoSamples
+		return
+	}
+	d.Queue = map[string]Band{}
+	for _, b := range []string{"interactive", "normal", "background"} {
+		if depth[b] == 0 && len(waits[b]) == 0 {
+			continue
+		}
+		d.Queue[b] = Band{Depth: depth[b], WaitMs: pct(waits[b])}
+		if len(waits[b]) == 0 {
+			d.Reasons["queue."+b+".wait_ms"] = ReasonNoSamples
+		}
+	}
+}
+
+// NoStoreRows stands for a machine with no run store: every optional set reads as not installed.
+func NoStoreRows() store.StatsRows {
+	m := map[string]bool{}
+	for _, t := range []string{"schedtel_outcome", "ledger", "cache_use", "cache_entry", "cache_artifact", "outbox", "node"} {
+		m[t] = true
+	}
+	return store.StatsRows{Missing: m}
+}
diff --git a/free/ci/internal/stats/fixture_test.go b/free/ci/internal/stats/fixture_test.go
new file mode 100644
index 000000000..f44aef394
--- /dev/null
+++ b/free/ci/internal/stats/fixture_test.go
@@ -0,0 +1,159 @@
+package stats
+
+// Purpose: the fixture store of the stats tests (P7-SCHED-20): two projects, three runners, retries, flakes,
+// cache hits and misses, two ephemeral cold starts, ledger rows of every confidence, a stale lease and a
+// two-hour-old outbox entry; buildFixture(t, 400) holds exactly 500 attempts, buildFixture(t, 80000) 100 000.
+// Inputs:  the number of jobs.
+// Outputs: an open store and the fixed clock the rows were written against.
+// Constraints: rows are written through a second connection in one transaction (the store has no seam for
+//          core rows); the values are formulas of the index, so the golden documents never change by chance.
+
+import (
+	"database/sql"
+	"fmt"
+	"path/filepath"
+	"testing"
+	"time"
+
+	_ "modernc.org/sqlite"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+var fixtureNow = time.Date(2026, 10, 26, 12, 0, 0, 0, time.UTC)
+
+type fx struct {
+	t  *testing.T
+	tx *sql.Tx
+}
+
+func (f fx) exec(q string, args ...any) {
+	f.t.Helper()
+	if _, err := f.tx.Exec(q, args...); err != nil {
+		f.t.Fatalf("%v\n%s", err, q)
+	}
+}
+
+func buildFixture(t *testing.T, jobs int) *store.Store {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "state.db")
+	st, err := store.Open(path, store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	db, err := sql.Open("sqlite", "file:"+path+"?_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = db.Close() }()
+	tx, err := db.Begin()
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := fx{t, tx}
+	f.attempts(jobs)
+	f.platform()
+	if err = tx.Commit(); err != nil {
+		t.Fatal(err)
+	}
+	return st
+}
+
+func (f fx) attempt(id, job, pipe string, n int, state string) {
+	f.exec(`INSERT INTO attempt(id,job_id,n,state) VALUES(?,?,?,?)`, id, job, n, state)
+}
+
+func (f fx) outcome(id, project, runner, class, result, failure string, i, cold int, ts time.Time) {
+	f.exec(`INSERT INTO schedtel_outcome(attempt_id,project,job_key,runner,runner_class,wait_ms,runtime_ms,cold_start_ms,cost_micro,result,failure_class,ts) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`,
+		id, project, fmt.Sprintf("job%d", i%4), runner, class, 100+(i*37)%900, 1000+(i*53)%5000, cold, 0, result, failure, ts.UnixMilli())
+}
+
+// attempts writes jobs jobs: the first eighth fail once then pass (flaky), the next eighth fail once on
+// infrastructure then pass, a seventeenth of the rest fail, the rest pass.
+func (f fx) attempts(jobs int) {
+	runners := []string{"mac1", "linux1", "eph1"}
+	triggers := []string{"push", "push", "schedule", "manual", "push"}
+	i := 0
+	for k := 0; k < jobs; k++ {
+		project := []string{"acme/a", "acme/b"}[k%2]
+		pipe, job := fmt.Sprintf("p%d", k), fmt.Sprintf("j%d", k)
+		f.exec(`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+			pipe, project, "rev", triggers[k%5], "owner", "z", "d", "i", "m", "r", "s", "passed", fixtureNow.UnixNano())
+		f.exec(`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES(?,?,?,?,?,?,?,?,?)`, job, pipe, "build", "k", 1, 1, "i", 1, "passed")
+		var results [][2]string
+		switch {
+		case k < jobs/8:
+			results = [][2]string{{"failed", "test"}, {"passed", ""}}
+		case k < jobs/4:
+			results = [][2]string{{"failed", "infra"}, {"passed", ""}}
+		case k%17 == 0:
+			results = [][2]string{{"failed", "test"}}
+		default:
+			results = [][2]string{{"passed", ""}}
+		}
+		for n, r := range results {
+			id := fmt.Sprintf("a%d-%d", k, n+1)
+			f.attempt(id, job, pipe, n+1, r[0])
+			runner, class, cold := runners[i%3], "owned", -1
+			if i == 7 || i == 8 { // the two ephemeral intents
+				runner, class, cold = "eph1", "ephemeral", 21000+3000*(i-7)
+			}
+			f.outcome(id, project, runner, class, r[0], r[1], i, cold, fixtureNow.Add(-time.Duration(i%1000)*time.Minute))
+			if i%5 == 0 { // cache use on every fifth attempt
+				f.exec(`INSERT INTO cache_attempt(attempt_id,project,trust,protection,secrets_declared,private_deps,recorded_at) VALUES(?,?,?,?,?,?,?)`, id, project, "owner", "none", 0, 0, 1)
+				res := "hit"
+				if i%3 == 0 {
+					res = "miss"
+				}
+				f.exec(`INSERT INTO cache_use(attempt_id,spec,cache_key,result,bytes,ms,ts) VALUES(?,?,?,?,?,?,?)`, id, "go", "k", res, 1000, 5, fixtureNow.Add(-time.Minute).UnixNano())
+				if i%10 == 0 {
+					f.exec(`INSERT INTO cache_use(attempt_id,spec,cache_key,result,bytes,ms,ts) VALUES(?,?,?,?,?,?,?)`, id, "go", "k", "saved", 5000, 5, fixtureNow.Add(-time.Minute).UnixNano())
+				}
+			}
+			i++
+		}
+	}
+}
+
+// platform writes the queue, ledger, cache store, lease, node and outbox rows.
+func (f fx) platform() {
+	for n, trig := range []string{"push", "schedule", "manual"} { // three queued attempts of project a
+		pipe, job := fmt.Sprintf("q%d", n), fmt.Sprintf("qj%d", n)
+		f.exec(`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+			pipe, "acme/a", "rev", trig, "owner", "z", "d", "i", "m", "r", "s", "running", fixtureNow.UnixNano())
+		f.exec(`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES(?,?,?,?,?,?,?,?,?)`, job, pipe, "build", "k", 1, 1, "i", 1, "queued")
+		f.attempt(fmt.Sprintf("qa%d", n), job, pipe, 1, "queued")
+	}
+	f.exec(`INSERT INTO coordinator(id,pid,process_start,boot_id,incarnation,heartbeat_at) VALUES('c1',1,'s','b',1,1)`)
+	for n, id := range []string{"stale", "live"} { // one expired lease under a running attempt, one current
+		pipe, job := "p"+id, "j"+id
+		f.exec(`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+			pipe, "acme/b", "rev", "push", "owner", "z", "d", "i", "m", "r", "s", "running", fixtureNow.UnixNano())
+		f.exec(`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES(?,?,?,?,?,?,?,?,?)`, job, pipe, "build", "k", 1, 1, "i", 1, "running")
+		f.attempt("a"+id, job, pipe, 1, "running")
+		exp := fixtureNow.Add(time.Hour)
+		if n == 0 {
+			exp = fixtureNow.Add(-time.Hour)
+		}
+		f.exec(`INSERT INTO lease(id,attempt_id,host,runner_id,expires_at,heartbeat_at,token_digest) VALUES(?,?,?,?,?,?,?)`, "l"+id, "a"+id, "h", "mac1", exp.UnixNano(), 1, "t")
+	}
+	for n, conf := range []string{"known", "computed", "estimated", "unknown"} {
+		f.exec(`INSERT INTO ledger(attempt_id,pipeline_id,project,provider,class,remote,est_ms,est_micro,act_ms,act_micro,confidence,budget_refs,window_day,rate_micro,rate_unit_ms,inc_ms,min_micro,extras_micro,admitted_at,finalized_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+			fmt.Sprintf("led%d", n), "p0", []string{"acme/a", "acme/b"}[n%2], "hetzner", "cloud", 1, 60000, 1000*(n+1), nil, nil, conf, "", "2026-10-26", 1, 1, 1, 0, 0, fixtureNow.Add(-time.Hour).UnixNano(), nil)
+	}
+	for n, size := range []int{4096, 8192} {
+		f.exec(`INSERT INTO cache_entry(cache_key,namespace,spec,attempt_id,epoch,source_trust,secrets_received,private_deps,scanned_clean,bytes,created_at,last_used_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`,
+			fmt.Sprintf("ck%d", n), []byte("ns"), "go", "a0-1", 1, "owner", 0, 0, 1, size, 1, 1)
+	}
+	f.exec(`INSERT INTO cache_artifact(id,project,run_id,job,attempt_id,revision,decl,path,name,kind,sha256,size,platform,runner_id,isolation,producer,visibility,retention,release,epoch,state,created_at) VALUES('art1','acme/a','p0','build','a0-1','rev',0,'p','n','file',?,2048,'linux','mac1','none','x','project','30d',0,1,'committed',1)`, fmt.Sprintf("%064d", 1))
+	for _, n := range []struct {
+		id, state string
+		age       time.Duration
+	}{{"mac1", "online", 0}, {"linux1", "online", 0}, {"old", "offline", 30 * time.Hour}} {
+		f.exec(`INSERT INTO node(id,name,version,lifecycle,trust_json,deploy_host_json,state,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?)`, n.id, n.id, 1, "enrolled", "{}", "{}", n.state, 1, fixtureNow.Add(-n.age).UnixNano())
+		f.exec(`INSERT INTO capability_snapshot(node_id,digest,doc_json,observed_at) VALUES(?,?,?,?)`, n.id, "d", fmt.Sprintf(`{"availability":{"slots":{"value":%d}}}`, map[string]int{"mac1": 4, "linux1": 2, "old": 1}[n.id]), 1)
+	}
+	f.exec(`INSERT INTO outbox(revision,context,seq,state,created_at) VALUES('rev','nself-ci',1,'pending',?)`, fixtureNow.Add(-2*time.Hour).UnixNano())
+	f.exec(`INSERT INTO outbox(revision,context,seq,state,created_at) VALUES('rev','nself-ci',2,'posted',?)`, fixtureNow.Add(-3*time.Hour).UnixNano())
+}
diff --git a/free/ci/internal/stats/golden_test.go b/free/ci/internal/stats/golden_test.go
new file mode 100644
index 000000000..9fd41bdf9
--- /dev/null
+++ b/free/ci/internal/stats/golden_test.go
@@ -0,0 +1,130 @@
+package stats
+
+// Purpose: TestStatsGolden (P7-SCHED-20): the fixture store gives the golden contract:ci.stats documents for
+// `--since 24h` over all projects and for `--project acme/a`; a store without cache, ledger or burst rows
+// reports those blocks as null with a reason and no figure as 0; a scoped caller loses the coordinator-wide blocks.
+// Inputs:  buildFixture(t, 400) and testdata/*.golden.json (rewrite with UPDATE_GOLDEN=1).
+// Outputs: pass or fail.
+// Constraints: the store size and free disk depend on the machine, so the golden documents are compared with
+//          those two figures removed.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func golden(t *testing.T, name string, d Doc) {
+	t.Helper()
+	d.Store = nil // machine dependent
+	delete(d.Reasons, "store.free_bytes")
+	got, err := json.MarshalIndent(d, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	got = append(got, '\n')
+	path := filepath.Join("testdata", name+".golden.json")
+	if os.Getenv("UPDATE_GOLDEN") != "" {
+		if err = os.WriteFile(path, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	want, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != string(want) {
+		t.Errorf("%s differs from the golden document:\n%s", name, got)
+	}
+}
+
+func TestStatsGolden(t *testing.T) {
+	st := buildFixture(t, 400)
+	ctx := context.Background()
+	all, err := Compute(ctx, st, Options{Now: fixtureNow, Since: 24 * time.Hour, Global: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	golden(t, "all", all)
+	if all.Attempts == nil || all.Attempts.Finished != 500 {
+		t.Fatalf("finished attempts = %+v, want 500", all.Attempts)
+	}
+	a, err := Compute(ctx, st, Options{Now: fixtureNow, Since: 24 * time.Hour, Project: "acme/a", Global: false})
+	if err != nil {
+		t.Fatal(err)
+	}
+	golden(t, "project-a", a)
+}
+
+func TestStatsAbsentSourcesAreNullNotZero(t *testing.T) {
+	st := buildFixture(t, 4)
+	d, err := Compute(context.Background(), st, Options{Now: fixtureNow.Add(100 * 24 * time.Hour), Since: time.Hour, Global: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Cache != nil || d.Spend != nil || d.Attempts != nil || d.Provisioning != nil || d.Runners != nil {
+		t.Fatalf("an empty window gave figures: %+v", d)
+	}
+	for _, b := range d.Queue { // the three queued attempts still count; their wait has no samples
+		if b.WaitMs != nil || d.Reasons["queue.normal.wait_ms"] != ReasonNoSamples {
+			t.Errorf("queue band %+v / reasons %v", b, d.Reasons)
+		}
+	}
+	for _, k := range []string{"cache", "spend", "attempts", "runners", "provisioning_ms"} {
+		if d.Reasons[k] == "" {
+			t.Errorf("no reason for null %s", k)
+		}
+	}
+	raw, _ := json.Marshal(d)
+	var m map[string]any
+	_ = json.Unmarshal(raw, &m)
+	for _, k := range []string{"cache", "spend", "attempts", "provisioning_ms"} {
+		if m[k] != nil {
+			t.Errorf("%s = %v, want null", k, m[k])
+		}
+	}
+}
+
+func TestStatsScopedCallerSeesOnlyAllowedProjects(t *testing.T) {
+	st := buildFixture(t, 40)
+	d, err := Compute(context.Background(), st, Options{Now: fixtureNow, Since: 24 * time.Hour, Allow: func(p string) bool { return p == "acme/b" }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Nodes != nil || d.Outbox != nil || d.Store != nil || d.Reasons["nodes"] != ReasonScoped {
+		t.Errorf("a scoped caller saw coordinator-wide blocks: %+v", d)
+	}
+	if d.Leases == nil || d.Leases.Stale != 1 { // the stale lease belongs to acme/b
+		t.Errorf("leases = %+v", d.Leases)
+	}
+	for _, r := range d.Runners {
+		if r.Attempts == 0 {
+			t.Error("runner without attempts")
+		}
+	}
+	if d.Attempts == nil || d.Attempts.Finished != 25 { // 20 jobs of b plus 5 retries
+		t.Errorf("attempts = %+v", d.Attempts)
+	}
+}
+
+func TestPercentilesAreNearestRank(t *testing.T) {
+	v := make([]int64, 100)
+	for i := range v {
+		v[i] = int64(i + 1)
+	}
+	if p := pct(v); p.P50 != 50 || p.P95 != 95 || p.N != 100 {
+		t.Errorf("pct = %+v", p)
+	}
+	if p := pct([]int64{7}); p.P50 != 7 || p.P95 != 7 {
+		t.Errorf("single = %+v", p)
+	}
+	if pct(nil) != nil {
+		t.Error("empty must be nil")
+	}
+	if permille(1, 3) != 333 || permille(2, 3) != 667 {
+		t.Error("permille rounding")
+	}
+}
diff --git a/free/ci/internal/stats/health.go b/free/ci/internal/stats/health.go
new file mode 100644
index 000000000..524c07567
--- /dev/null
+++ b/free/ci/internal/stats/health.go
@@ -0,0 +1,122 @@
+package stats
+
+// Purpose: the `health` section of `nself ci doctor` (P7-SCHED-20, ids CI-STAT-01..05): warnings from the same
+// numbers `nself ci runs stats` prints, over the last 24 hours of the local run store.
+// Inputs:  the doctor Env (NSELF_CI_HOME); the run store file, read only.
+// Outputs: one check per id, pass or warn.
+// Constraints: registered from init through the doctor Section registry; never a failure; a machine with no
+//          run store passes every check; a source that is null in the document passes its check with the
+//          reason, since nothing can be said about it.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// Doctor check ids and the thresholds that trigger them.
+const (
+	IDStaleLeases = "CI-STAT-01"
+	IDQueueWait   = "CI-STAT-02"
+	IDOutbox      = "CI-STAT-03"
+	IDNodes       = "CI-STAT-04"
+	IDStoreSize   = "CI-STAT-05"
+
+	QueueWaitWarnMs  = int64(10 * 60 * 1000)
+	OutboxAgeWarnMs  = int64(60 * 60 * 1000)
+	OutboxCountWarn  = 50
+	StoreDiskPercent = 20
+)
+
+func init() {
+	doctor.RegisterSection(doctor.Section{Name: "health", Selector: doctor.SelectAlways, Run: healthSection})
+}
+
+func healthSection(ctx context.Context, env doctor.Env) []doctor.Check {
+	path := filepath.Join(firstNonEmpty(env.Getenv("NSELF_CI_HOME"), homeDefault(env)), "state.db")
+	if _, err := os.Stat(path); err != nil {
+		return HealthChecks(nil)
+	}
+	st, err := store.Open(path, store.Options{})
+	if err != nil {
+		return []doctor.Check{{ID: IDStaleLeases, Name: "ci health", Status: doctor.Warn, Message: "the run store could not be read: " + err.Error(),
+			Remediation: "Run: nself ci doctor, and fix the store check CI-D004 first"}}
+	}
+	defer func() { _ = st.Close() }()
+	d, err := Compute(ctx, st, Options{Now: time.Now(), Since: DefaultSince, Global: true})
+	if err != nil {
+		return []doctor.Check{{ID: IDStaleLeases, Name: "ci health", Status: doctor.Warn, Message: "the health numbers could not be read: " + err.Error(),
+			Remediation: "Run: nself ci runs stats, and fix the store error it reports"}}
+	}
+	return HealthChecks(&d)
+}
+
+func homeDefault(env doctor.Env) string {
+	if h, err := os.UserHomeDir(); err == nil {
+		return filepath.Join(h, ".nself", "ci")
+	}
+	return ""
+}
+
+func firstNonEmpty(a, b string) string {
+	if a != "" {
+		return a
+	}
+	return b
+}
+
+// HealthChecks turns a stats document into the five checks; nil means there is no run store.
+func HealthChecks(d *Doc) []doctor.Check {
+	chk := func(id, name string, warn bool, ok, bad, fix string) doctor.Check {
+		c := doctor.Check{ID: id, Name: name, Status: doctor.Pass, Message: ok, Remediation: "None needed"}
+		if warn {
+			c.Status, c.Message, c.Remediation = doctor.Warn, bad, fix
+		}
+		return c
+	}
+	if d == nil {
+		none := "no run store on this machine yet"
+		return []doctor.Check{chk(IDStaleLeases, "no stale leases", false, none, "", ""), chk(IDQueueWait, "queue wait p95 under 10 minutes", false, none, "", ""),
+			chk(IDOutbox, "status outbox drained", false, none, "", ""), chk(IDNodes, "no node offline for 24 hours", false, none, "", ""),
+			chk(IDStoreSize, "run store small against free disk", false, none, "", "")}
+	}
+	var out []doctor.Check
+	stale := 0
+	if d.Leases != nil {
+		stale = d.Leases.Stale
+	}
+	out = append(out, chk(IDStaleLeases, "no stale leases", stale > 0, "no lease has expired under a running job",
+		fmt.Sprintf("%d lease(s) expired under a running job", stale), "Restart the agent on the node that holds it, or run: nself ci nodes show <node>"))
+	var worst int64 = -1
+	for _, b := range d.Queue {
+		if b.WaitMs != nil {
+			worst = max(worst, b.WaitMs.P95)
+		}
+	}
+	out = append(out, chk(IDQueueWait, "queue wait p95 under 10 minutes", worst > QueueWaitWarnMs, "queue wait is within 10 minutes",
+		fmt.Sprintf("queue wait p95 is %s", (time.Duration(worst)*time.Millisecond).Round(time.Second)), "Add capacity: nself ci nodes add, or lower what runs at once; see: nself ci runs queue"))
+	old, pending := int64(0), int64(0)
+	if d.Outbox != nil {
+		pending = d.Outbox.Pending
+		if d.Outbox.OldestAgeMs != nil {
+			old = *d.Outbox.OldestAgeMs
+		}
+	}
+	out = append(out, chk(IDOutbox, "status outbox drained", old > OutboxAgeWarnMs || pending > OutboxCountWarn, "the status outbox is draining",
+		fmt.Sprintf("%d status report(s) waiting, the oldest %s", pending, (time.Duration(old)*time.Millisecond).Round(time.Minute)), "Check the reporter credentials and network; see: nself ci runs outbox"))
+	off := 0
+	if d.Nodes != nil {
+		off = d.Nodes.OfflineOver24h
+	}
+	out = append(out, chk(IDNodes, "no node offline for 24 hours", off > 0, "no node has been offline for 24 hours",
+		fmt.Sprintf("%d node(s) offline for more than 24 hours", off), "Bring the node back or remove it: nself ci nodes remove <node>"))
+	big := d.Store != nil && d.Store.FreeBytes != nil && d.Store.SizeBytes*100 > *d.Store.FreeBytes*StoreDiskPercent
+	out = append(out, chk(IDStoreSize, "run store small against free disk", big, "the run store is under 20% of free disk",
+		"the run store is over 20% of the free disk", "Free disk space or prune old runs: nself ci runs prune"))
+	return out
+}
diff --git a/free/ci/internal/stats/health_test.go b/free/ci/internal/stats/health_test.go
new file mode 100644
index 000000000..b2b73ac75
--- /dev/null
+++ b/free/ci/internal/stats/health_test.go
@@ -0,0 +1,83 @@
+package stats
+
+// Purpose: tests of the `health` doctor section (P7-SCHED-20, CI-STAT-01..05): the fixture's stale lease, two-hour
+// outbox entry and day-old offline node warn; a machine with no run store passes every check; nothing fails.
+// Inputs:  the fixture store; the section run with NSELF_CI_HOME pointing at it.
+// Outputs: pass or fail.
+// Constraints: the section reads the wall clock, so only conditions that age in one direction are asserted.
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func statuses(checks []doctor.Check) map[string]doctor.Status {
+	out := map[string]doctor.Status{}
+	for _, c := range checks {
+		out[c.ID] = c.Status
+	}
+	return out
+}
+
+func TestHealthSectionWarnsOnTheFixture(t *testing.T) {
+	st := buildFixture(t, 40)
+	rows, err := st.StatsRead(context.Background(), store.StatsQuery{Now: time.Now(), Since: time.Hour})
+	if err != nil {
+		t.Fatal(err)
+	}
+	env := doctor.Env{Getenv: func(k string) string {
+		if k == "NSELF_CI_HOME" {
+			return filepath.Dir(rows.Path)
+		}
+		return ""
+	}}
+	got := statuses(healthSection(context.Background(), env))
+	for _, id := range []string{IDStaleLeases, IDOutbox, IDNodes} {
+		if got[id] != doctor.Warn {
+			t.Errorf("%s = %q, want warn (all: %v)", id, got[id], got)
+		}
+	}
+	for _, id := range []string{IDStaleLeases, IDQueueWait, IDOutbox, IDNodes, IDStoreSize} {
+		if got[id] == "" || got[id] == doctor.Fail {
+			t.Errorf("%s = %q", id, got[id])
+		}
+	}
+}
+
+func TestHealthSectionWithoutAStorePasses(t *testing.T) {
+	env := doctor.Env{Getenv: func(string) string { return t.TempDir() }}
+	got := statuses(healthSection(context.Background(), env))
+	if len(got) != 5 {
+		t.Fatalf("checks = %v", got)
+	}
+	for id, s := range got {
+		if s != doctor.Pass {
+			t.Errorf("%s = %q, want pass", id, s)
+		}
+	}
+}
+
+func TestHealthThresholds(t *testing.T) {
+	big, free := int64(300), int64(1000)
+	wait, age := QueueWaitWarnMs+1, OutboxAgeWarnMs+1
+	d := &Doc{Leases: &Leases{}, Queue: map[string]Band{"normal": {WaitMs: &Pct{P95: wait}}},
+		Outbox: &Outbox{Pending: 3, OldestAgeMs: &age}, Nodes: &Nodes{}, Store: &StoreInfo{SizeBytes: big, FreeBytes: &free}}
+	got := statuses(HealthChecks(d))
+	for _, id := range []string{IDQueueWait, IDOutbox, IDStoreSize} {
+		if got[id] != doctor.Warn {
+			t.Errorf("%s = %q, want warn", id, got[id])
+		}
+	}
+	if got[IDStaleLeases] != doctor.Pass || got[IDNodes] != doctor.Pass {
+		t.Errorf("clean checks warned: %v", got)
+	}
+	d.Outbox = &Outbox{Pending: OutboxCountWarn + 1}
+	if statuses(HealthChecks(d))[IDOutbox] != doctor.Warn {
+		t.Error("more than 50 pending must warn")
+	}
+}
diff --git a/free/ci/internal/stats/pct.go b/free/ci/internal/stats/pct.go
new file mode 100644
index 000000000..e70b3372b
--- /dev/null
+++ b/free/ci/internal/stats/pct.go
@@ -0,0 +1,25 @@
+package stats
+
+// Purpose: nearest-rank percentiles and permille rates from integers.
+// Inputs:  integer-millisecond samples; a numerator and denominator.
+// Outputs: *Pct (nil for no samples) and an integer permille.
+// Constraints: no floating point; the input slice is not modified.
+
+import "slices"
+
+// pct returns the nearest-rank P50 and P95 of v, or nil when v is empty.
+func pct(v []int64) *Pct {
+	if len(v) == 0 {
+		return nil
+	}
+	s := slices.Clone(v)
+	slices.Sort(s)
+	rank := func(p int) int64 {
+		r := (p*len(s) + 99) / 100 // ceil(p*n/100)
+		return s[max(r, 1)-1]
+	}
+	return &Pct{P50: rank(50), P95: rank(95), N: len(s)}
+}
+
+// permille returns num/den in thousandths, rounded half up; den must be positive.
+func permille(num, den int64) int { return int((num*1000 + den/2) / den) }
diff --git a/free/ci/internal/stats/plan_test.go b/free/ci/internal/stats/plan_test.go
new file mode 100644
index 000000000..f430605c5
--- /dev/null
+++ b/free/ci/internal/stats/plan_test.go
@@ -0,0 +1,72 @@
+package stats
+
+// Purpose: TestStatsQueryPlan (P7-SCHED-20): on a 100 000-attempt fixture every stats statement is planned
+// through an index (no full table scan), and the whole document is built inside the read budget.
+// Inputs:  buildFixture(t, 80000): 80 000 jobs and 100 000 attempts.
+// Outputs: pass or fail.
+// Constraints: the budget is 500 ms on the Linux runner and ten times that elsewhere, where the machine
+//          is shared and the file system slower, and ten times again under the race detector; the statements are the ones internal/store runs.
+
+import (
+	"context"
+	"database/sql"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func TestStatsQueryPlan(t *testing.T) {
+	st := buildFixture(t, 80000)
+	ctx := context.Background()
+	q := store.StatsQuery{Now: fixtureNow, Since: 24 * time.Hour}
+	rows, err := st.StatsRead(ctx, q)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows.Outcomes) != 100000 {
+		t.Fatalf("fixture holds %d outcomes, want 100000", len(rows.Outcomes))
+	}
+	db, err := sql.Open("sqlite", "file:"+rows.Path+"?mode=ro&_pragma=busy_timeout(5000)")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = db.Close() }()
+	for _, project := range []string{"", "acme/a"} {
+		q.Project = project
+		for _, s := range store.StatsStatements(q) {
+			r, err := db.QueryContext(ctx, "EXPLAIN QUERY PLAN "+s.SQL, s.Args...)
+			if err != nil {
+				t.Fatalf("%s: %v", s.Name, err)
+			}
+			for r.Next() {
+				var id, parent, unused int
+				var detail string
+				if err = r.Scan(&id, &parent, &unused, &detail); err != nil {
+					t.Fatal(err)
+				}
+				if strings.HasPrefix(detail, "SCAN ") && !strings.Contains(detail, "USING") && !strings.Contains(detail, "SUBQUERY") {
+					t.Errorf("statement %s (project %q) scans a table: %s", s.Name, project, detail)
+				}
+			}
+			_ = r.Close()
+		}
+	}
+	budget := 500 * time.Millisecond
+	if runtime.GOOS != "linux" {
+		budget *= 10
+	}
+	if raceEnabled {
+		budget *= 10 // the budget is a plain-build figure; the detector multiplies the cost of every memory access
+	}
+	start := time.Now()
+	d, err := Compute(ctx, st, Options{Now: fixtureNow, Since: 24 * time.Hour, Global: true})
+	if took := time.Since(start); err != nil || took > budget {
+		t.Fatalf("Compute took %s (budget %s), err %v", took, budget, err)
+	}
+	if d.Attempts == nil || d.Attempts.Finished != 100000 {
+		t.Fatalf("attempts = %+v", d.Attempts)
+	}
+}
diff --git a/free/ci/internal/stats/race_off_test.go b/free/ci/internal/stats/race_off_test.go
new file mode 100644
index 000000000..1d035f733
--- /dev/null
+++ b/free/ci/internal/stats/race_off_test.go
@@ -0,0 +1,6 @@
+//go:build !race
+
+package stats
+
+// raceEnabled is true when the race detector is on.
+const raceEnabled = false
diff --git a/free/ci/internal/stats/race_on_test.go b/free/ci/internal/stats/race_on_test.go
new file mode 100644
index 000000000..4545cc97c
--- /dev/null
+++ b/free/ci/internal/stats/race_on_test.go
@@ -0,0 +1,6 @@
+//go:build race
+
+package stats
+
+// raceEnabled is true when the race detector is on, which slows the 100 000-attempt budget test by an order of magnitude.
+const raceEnabled = true
diff --git a/free/ci/internal/stats/runs.go b/free/ci/internal/stats/runs.go
new file mode 100644
index 000000000..f6c0452e8
--- /dev/null
+++ b/free/ci/internal/stats/runs.go
@@ -0,0 +1,96 @@
+package stats
+
+// Purpose: the per-attempt blocks of contract:ci.stats: runner utilisation, outcome rates, job durations and
+// ephemeral provisioning latency.
+// Inputs:  the finished-attempt telemetry rows of the window.
+// Outputs: Doc.Runners, Attempts, Jobs, Provisioning.
+// Constraints: only passed and failed attempts count; a failure of class infra is an infra retry, any other
+//          failure marks its job as failed-before, and a later pass of that job makes the job flaky.
+
+import (
+	"math"
+
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func (d *Doc) buildRuns(rows store.StatsRows, out []store.StatOutcome, o Options) {
+	if rows.Missing["schedtel_outcome"] {
+		for _, k := range []string{"runners", "attempts", "jobs", "provisioning_ms"} {
+			d.Reasons[k] = ReasonNotInstalled
+		}
+		return
+	}
+	if len(out) == 0 {
+		for _, k := range []string{"runners", "attempts", "jobs", "provisioning_ms"} {
+			d.Reasons[k] = ReasonNoSamples
+		}
+		return
+	}
+	slots := nodeSlots(rows.Nodes)
+	window := o.Since.Milliseconds()
+	d.Runners, d.Jobs = map[string]Runner{}, map[string]Pct{}
+	runtimes := map[string][]int64{}
+	var cold []int64
+	var passed, failed, infra int64
+	// A job is flaky when a non-infra failure precedes a pass: its first such failure comes before its last pass.
+	type span struct{ firstFail, lastPass int }
+	jobs := make(map[string]span, len(out))
+	for _, x := range out {
+		s, ok := jobs[x.Job]
+		if !ok {
+			s = span{firstFail: math.MaxInt, lastPass: math.MinInt}
+		}
+		r := d.Runners[x.Runner]
+		r.Attempts++
+		if x.RuntimeMs >= 0 {
+			r.BusyMs += x.RuntimeMs
+			runtimes[x.JobKey] = append(runtimes[x.JobKey], x.RuntimeMs)
+		}
+		d.Runners[x.Runner] = r
+		if x.RunnerClass == "ephemeral" && x.ColdStartMs >= 0 {
+			cold = append(cold, x.ColdStartMs)
+		}
+		switch {
+		case x.Result == "passed":
+			passed++
+			s.lastPass = max(s.lastPass, x.N)
+		case x.FailureClass == "infra":
+			failed++
+			infra++
+		default:
+			failed++
+			s.firstFail = min(s.firstFail, x.N)
+		}
+		jobs[x.Job] = s
+	}
+	var flaky int64
+	for _, s := range jobs {
+		if s.firstFail < s.lastPass {
+			flaky++
+		}
+	}
+	for id, r := range d.Runners {
+		s, ok := slots[id]
+		if !ok || s <= 0 {
+			d.Reasons["runners."+id+".utilisation_permille"] = ReasonSlotsUnknown
+			continue
+		}
+		avail := int64(s) * window
+		u := min(1000, permille(r.BusyMs, avail))
+		r.Slots, r.AvailableMs, r.UtilisationPermille = &s, &avail, &u
+		d.Runners[id] = r
+	}
+	total := passed + failed
+	d.Attempts = &Attempts{Finished: int(total), PassPermille: permille(passed, total), FailPermille: permille(failed, total),
+		FlakyPermille: permille(flaky, int64(len(jobs))), InfraRetryPermille: permille(infra, total)}
+	for k, v := range runtimes {
+		d.Jobs[k] = *pct(v)
+	}
+	if len(d.Jobs) == 0 {
+		d.Jobs = nil
+		d.Reasons["jobs"] = ReasonNoSamples
+	}
+	if d.Provisioning = pct(cold); d.Provisioning == nil {
+		d.Reasons["provisioning_ms"] = ReasonNoSamples
+	}
+}
diff --git a/free/ci/internal/stats/space_other.go b/free/ci/internal/stats/space_other.go
new file mode 100644
index 000000000..f1e3aa333
--- /dev/null
+++ b/free/ci/internal/stats/space_other.go
@@ -0,0 +1,10 @@
+//go:build !(linux || darwin || freebsd)
+
+package stats
+
+// Purpose: free-space stand-in for platforms without statfs; the figure is reported as unknown (null).
+// Inputs:  a path.
+// Outputs: ok false.
+// Constraints: none.
+
+func freeBytes(string) (int64, bool) { return 0, false }
diff --git a/free/ci/internal/stats/space_unix.go b/free/ci/internal/stats/space_unix.go
new file mode 100644
index 000000000..0b443759d
--- /dev/null
+++ b/free/ci/internal/stats/space_unix.go
@@ -0,0 +1,18 @@
+//go:build linux || darwin || freebsd
+
+package stats
+
+// Purpose: free bytes of the volume that holds the run store.
+// Inputs:  a path on that volume.
+// Outputs: bytes available to this user.
+// Constraints: ok is false when the volume cannot be read.
+
+import "syscall"
+
+func freeBytes(path string) (int64, bool) {
+	var st syscall.Statfs_t
+	if syscall.Statfs(path, &st) != nil {
+		return 0, false
+	}
+	return int64(st.Bavail) * int64(st.Bsize), true
+}
diff --git a/free/ci/internal/stats/testdata/all.golden.json b/free/ci/internal/stats/testdata/all.golden.json
new file mode 100644
index 000000000..869e23a76
--- /dev/null
+++ b/free/ci/internal/stats/testdata/all.golden.json
@@ -0,0 +1,139 @@
+{
+  "contract": "ci.stats",
+  "version": 1,
+  "generated_at": "2026-10-26T12:00:00Z",
+  "since_ms": 86400000,
+  "project": null,
+  "queue": {
+    "background": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 549,
+        "p95": 965,
+        "n": 100
+      }
+    },
+    "interactive": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 526,
+        "p95": 952,
+        "n": 100
+      }
+    },
+    "normal": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 535,
+        "p95": 943,
+        "n": 300
+      }
+    }
+  },
+  "runners": {
+    "eph1": {
+      "attempts": 167,
+      "busy_ms": 567472,
+      "slots": null,
+      "available_ms": null,
+      "utilisation_permille": null
+    },
+    "linux1": {
+      "attempts": 166,
+      "busy_ms": 568379,
+      "slots": 2,
+      "available_ms": 172800000,
+      "utilisation_permille": 3
+    },
+    "mac1": {
+      "attempts": 167,
+      "busy_ms": 565899,
+      "slots": 4,
+      "available_ms": 345600000,
+      "utilisation_permille": 2
+    }
+  },
+  "attempts": {
+    "finished": 500,
+    "pass_permille": 764,
+    "fail_permille": 236,
+    "flaky_permille": 125,
+    "infra_retry_permille": 100
+  },
+  "jobs": {
+    "job0": {
+      "p50": 3332,
+      "p95": 5716,
+      "n": 125
+    },
+    "job1": {
+      "p50": 3349,
+      "p95": 5717,
+      "n": 125
+    },
+    "job2": {
+      "p50": 3366,
+      "p95": 5734,
+      "n": 125
+    },
+    "job3": {
+      "p50": 3367,
+      "p95": 5751,
+      "n": 125
+    }
+  },
+  "cache": {
+    "hits": 66,
+    "misses": 34,
+    "hit_permille": 660,
+    "bytes_restored": 66000,
+    "bytes_saved": 250000
+  },
+  "storage": {
+    "cas_bytes": 12288,
+    "artifact_bytes": 2048
+  },
+  "provisioning_ms": {
+    "p50": 21000,
+    "p95": 24000,
+    "n": 2
+  },
+  "spend": {
+    "computed": {
+      "attempts": 1,
+      "micro": 2000
+    },
+    "estimated": {
+      "attempts": 1,
+      "micro": 3000
+    },
+    "known": {
+      "attempts": 1,
+      "micro": 1000
+    },
+    "unknown": {
+      "attempts": 1,
+      "micro": 4000
+    }
+  },
+  "leases": {
+    "active": 1,
+    "stale": 1,
+    "self_fenced": 0
+  },
+  "nodes": {
+    "by_state": {
+      "offline": 1,
+      "online": 2
+    },
+    "offline_over_24h": 1
+  },
+  "outbox": {
+    "pending": 1,
+    "oldest_age_ms": 7200000
+  },
+  "store": null,
+  "reasons": {
+    "runners.eph1.utilisation_permille": "slots_unknown"
+  }
+}
diff --git a/free/ci/internal/stats/testdata/project-a.golden.json b/free/ci/internal/stats/testdata/project-a.golden.json
new file mode 100644
index 000000000..327c2a0e8
--- /dev/null
+++ b/free/ci/internal/stats/testdata/project-a.golden.json
@@ -0,0 +1,128 @@
+{
+  "contract": "ci.stats",
+  "version": 1,
+  "generated_at": "2026-10-26T12:00:00Z",
+  "since_ms": 86400000,
+  "project": "acme/a",
+  "queue": {
+    "background": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 574,
+        "p95": 965,
+        "n": 50
+      }
+    },
+    "interactive": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 526,
+        "p95": 956,
+        "n": 50
+      }
+    },
+    "normal": {
+      "depth": 1,
+      "wait_ms": {
+        "p50": 533,
+        "p95": 953,
+        "n": 150
+      }
+    }
+  },
+  "runners": {
+    "eph1": {
+      "attempts": 83,
+      "busy_ms": 286655,
+      "slots": null,
+      "available_ms": null,
+      "utilisation_permille": null
+    },
+    "linux1": {
+      "attempts": 84,
+      "busy_ms": 281347,
+      "slots": 2,
+      "available_ms": 172800000,
+      "utilisation_permille": 2
+    },
+    "mac1": {
+      "attempts": 83,
+      "busy_ms": 278598,
+      "slots": 4,
+      "available_ms": 345600000,
+      "utilisation_permille": 1
+    }
+  },
+  "attempts": {
+    "finished": 250,
+    "pass_permille": 764,
+    "fail_permille": 236,
+    "flaky_permille": 125,
+    "infra_retry_permille": 100
+  },
+  "jobs": {
+    "job0": {
+      "p50": 3332,
+      "p95": 5716,
+      "n": 125
+    },
+    "job1": {
+      "p50": 3261,
+      "p95": 5717,
+      "n": 50
+    },
+    "job2": {
+      "p50": 3366,
+      "p95": 5734,
+      "n": 75
+    }
+  },
+  "cache": {
+    "hits": 33,
+    "misses": 17,
+    "hit_permille": 660,
+    "bytes_restored": 33000,
+    "bytes_saved": 200000
+  },
+  "storage": {
+    "cas_bytes": 12288,
+    "artifact_bytes": 2048
+  },
+  "provisioning_ms": {
+    "p50": 24000,
+    "p95": 24000,
+    "n": 1
+  },
+  "spend": {
+    "computed": {
+      "attempts": 0,
+      "micro": 0
+    },
+    "estimated": {
+      "attempts": 1,
+      "micro": 3000
+    },
+    "known": {
+      "attempts": 1,
+      "micro": 1000
+    },
+    "unknown": {
+      "attempts": 0,
+      "micro": 0
+    }
+  },
+  "leases": {
+    "active": 0,
+    "stale": 0,
+    "self_fenced": 0
+  },
+  "nodes": null,
+  "outbox": null,
+  "store": null,
+  "reasons": {
+    "nodes": "scoped_to_projects",
+    "outbox": "scoped_to_projects",
+    "runners.eph1.utilisation_permille": "slots_unknown",
+    "store": "scoped_to_projects"
+  }
+}
diff --git a/free/ci/internal/stats/text.go b/free/ci/internal/stats/text.go
new file mode 100644
index 000000000..adfcfa6cf
--- /dev/null
+++ b/free/ci/internal/stats/text.go
@@ -0,0 +1,94 @@
+package stats
+
+// Purpose: the human table `nself ci runs stats` prints.
+// Inputs:  a Doc.
+// Outputs: text, one line per block; a null figure prints "-" and its reason is listed at the end.
+// Constraints: pure; keys are sorted so the output is stable.
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+func dur(ms int64) string {
+	return (time.Duration(ms) * time.Millisecond).Round(time.Millisecond).String()
+}
+
+func pctText(p *Pct) string {
+	if p == nil {
+		return "-"
+	}
+	return fmt.Sprintf("p50 %s p95 %s (%d samples)", dur(p.P50), dur(p.P95), p.N)
+}
+
+func rate(v int) string { return fmt.Sprintf("%.1f%%", float64(v)/10) }
+
+func sortedKeys[V any](m map[string]V) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Text renders d for a terminal.
+func Text(d Doc) string {
+	var b strings.Builder
+	w := func(f string, a ...any) { fmt.Fprintf(&b, f, a...) }
+	w("window %s", dur(d.SinceMs))
+	if d.Project != nil {
+		w(", project %s", *d.Project)
+	}
+	w("\n")
+	for _, k := range sortedKeys(d.Queue) {
+		q := d.Queue[k]
+		w("queue %-11s depth %d, wait %s\n", k, q.Depth, pctText(q.WaitMs))
+	}
+	if a := d.Attempts; a != nil {
+		w("attempts %d: pass %s, fail %s, flaky %s, infra retry %s\n", a.Finished, rate(a.PassPermille), rate(a.FailPermille), rate(a.FlakyPermille), rate(a.InfraRetryPermille))
+	}
+	for _, k := range sortedKeys(d.Runners) {
+		r, u := d.Runners[k], "-"
+		if r.UtilisationPermille != nil {
+			u = rate(*r.UtilisationPermille)
+		}
+		w("runner %-20s attempts %d, busy %s, utilisation %s\n", k, r.Attempts, dur(r.BusyMs), u)
+	}
+	for _, k := range sortedKeys(d.Jobs) {
+		p := d.Jobs[k]
+		w("job %-24s %s\n", k, pctText(&p))
+	}
+	if c := d.Cache; c != nil {
+		h := "-"
+		if c.HitPermille != nil {
+			h = rate(*c.HitPermille)
+		}
+		w("cache hit %s, restored %d B, saved %d B\n", h, c.BytesRestored, c.BytesSaved)
+	}
+	w("provisioning %s\n", pctText(d.Provisioning))
+	for _, k := range sortedKeys(d.Spend) {
+		w("spend %-10s %d micro over %d attempts\n", k, d.Spend[k].Micro, d.Spend[k].Attempts)
+	}
+	if l := d.Leases; l != nil {
+		w("leases active %d, stale %d, self-fenced %d\n", l.Active, l.Stale, l.SelfFenced)
+	}
+	if o := d.Outbox; o != nil {
+		age := "-"
+		if o.OldestAgeMs != nil {
+			age = dur(*o.OldestAgeMs)
+		}
+		w("outbox pending %d, oldest %s\n", o.Pending, age)
+	}
+	reasons := make([]string, 0, len(d.Reasons))
+	for k, v := range d.Reasons {
+		reasons = append(reasons, "unavailable "+k+": "+v)
+	}
+	sort.Strings(reasons)
+	for _, r := range reasons {
+		w("%s\n", r)
+	}
+	return b.String()
+}
diff --git a/free/ci/internal/stats/types.go b/free/ci/internal/stats/types.go
new file mode 100644
index 000000000..b8ac9d441
--- /dev/null
+++ b/free/ci/internal/stats/types.go
@@ -0,0 +1,125 @@
+package stats
+
+// Purpose: contract:ci.stats v1 (P7-SCHED-20, Epic SCHED D23): the document `nself ci runs stats` prints and
+// GET /v1/stats serves. Experimental until P8; the golden fixtures in testdata are its definition.
+// Inputs:  none (types only).
+// Outputs: Doc and its blocks.
+// Constraints: an absent source is null with a reason in Doc.Reasons (dotted path -> reason), never 0; rates are
+//          integer permille; durations are integer milliseconds; maps marshal in key order, so the output is stable.
+
+// Contract names the document; Version is its schema version.
+const (
+	Contract = "ci.stats"
+	Version  = 1
+)
+
+// Reasons a value is null.
+const (
+	ReasonNoSamples     = "no_samples"
+	ReasonNoRows        = "no_rows"
+	ReasonNotInstalled  = "not_installed"
+	ReasonNoLookups     = "no_lookups"
+	ReasonNonePending   = "none_pending"
+	ReasonSlotsUnknown  = "slots_unknown"
+	ReasonScoped        = "scoped_to_projects"
+	ReasonStoreUnstated = "store_unreadable"
+)
+
+// Pct is a nearest-rank percentile pair over N integer-millisecond samples.
+type Pct struct {
+	P50 int64 `json:"p50"`
+	P95 int64 `json:"p95"`
+	N   int   `json:"n"`
+}
+
+// Band is the queue state of one fair-queue band.
+type Band struct {
+	Depth  int  `json:"depth"`
+	WaitMs *Pct `json:"wait_ms"`
+}
+
+// Runner is one runner's use in the window.
+type Runner struct {
+	Attempts            int    `json:"attempts"`
+	BusyMs              int64  `json:"busy_ms"`
+	Slots               *int   `json:"slots"`
+	AvailableMs         *int64 `json:"available_ms"`
+	UtilisationPermille *int   `json:"utilisation_permille"`
+}
+
+// Attempts holds the outcome rates over finished attempts.
+type Attempts struct {
+	Finished           int `json:"finished"`
+	PassPermille       int `json:"pass_permille"`
+	FailPermille       int `json:"fail_permille"`
+	FlakyPermille      int `json:"flaky_permille"`
+	InfraRetryPermille int `json:"infra_retry_permille"`
+}
+
+// Cache is the cache use of the window.
+type Cache struct {
+	Hits          int64 `json:"hits"`
+	Misses        int64 `json:"misses"`
+	HitPermille   *int  `json:"hit_permille"`
+	BytesRestored int64 `json:"bytes_restored"`
+	BytesSaved    int64 `json:"bytes_saved"`
+}
+
+// Storage is what the CAS and the artifact store hold now.
+type Storage struct {
+	CASBytes      *int64 `json:"cas_bytes"`
+	ArtifactBytes *int64 `json:"artifact_bytes"`
+}
+
+// Spend is the cost recorded at one confidence.
+type Spend struct {
+	Attempts int64 `json:"attempts"`
+	Micro    int64 `json:"micro"`
+}
+
+// Leases counts leases by condition; a lease is in exactly one.
+type Leases struct {
+	Active     int `json:"active"`
+	Stale      int `json:"stale"`
+	SelfFenced int `json:"self_fenced"`
+}
+
+// Nodes counts nodes by state.
+type Nodes struct {
+	ByState        map[string]int `json:"by_state"`
+	OfflineOver24h int            `json:"offline_over_24h"`
+}
+
+// Outbox is the status-report backlog.
+type Outbox struct {
+	Pending     int64  `json:"pending"`
+	OldestAgeMs *int64 `json:"oldest_age_ms"`
+}
+
+// StoreInfo is the size of the run store and the free space of its volume.
+type StoreInfo struct {
+	SizeBytes int64  `json:"size_bytes"`
+	FreeBytes *int64 `json:"free_bytes"`
+}
+
+// Doc is contract:ci.stats v1.
+type Doc struct {
+	Contract     string            `json:"contract"`
+	Version      int               `json:"version"`
+	GeneratedAt  string            `json:"generated_at"`
+	SinceMs      int64             `json:"since_ms"`
+	Project      *string           `json:"project"`
+	Queue        map[string]Band   `json:"queue"`
+	Runners      map[string]Runner `json:"runners"`
+	Attempts     *Attempts         `json:"attempts"`
+	Jobs         map[string]Pct    `json:"jobs"`
+	Cache        *Cache            `json:"cache"`
+	Storage      *Storage          `json:"storage"`
+	Provisioning *Pct              `json:"provisioning_ms"`
+	Spend        map[string]Spend  `json:"spend"`
+	Leases       *Leases           `json:"leases"`
+	Nodes        *Nodes            `json:"nodes"`
+	Outbox       *Outbox           `json:"outbox"`
+	Store        *StoreInfo        `json:"store"`
+	Reasons      map[string]string `json:"reasons"`
+}
diff --git a/free/ci/internal/store/cache_artifacts_commit.go b/free/ci/internal/store/cache_artifacts_commit.go
index fb985ed1d..27217a422 100644
--- a/free/ci/internal/store/cache_artifacts_commit.go
+++ b/free/ci/internal/store/cache_artifacts_commit.go
@@ -5,7 +5,7 @@ package store
 // the current epoch, after the caller re-hashed every blob.
 // Inputs: attempt id, epoch, the verified staged records, a records.Policy.
 // Outputs: the 80 % warning text; *records.Error (E711 stale capability,
-// E712 size_cap) after one audit row.
+// E712 size_cap, digest_mismatch, uncommitted) after one audit row.
 // Constraints: one writer transaction re-reads the attempt, the staged rows
 // and the committed byte sums; the rows the caller verified must be exactly
 // the rows that are staged now; released-kind bytes count toward the cap.
@@ -56,14 +56,16 @@ func (s *Store) ArtifactCommit(ctx context.Context, attempt string, epoch int64,
 		var add int64
 		for _, v := range verified {
 			r, ok := staged[v.ID]
-			if !ok || r.SHA256 != v.SHA256 || r.Size != v.Size {
-				return records.Failf(records.ReasonDigest, "record %q is not the staged record that was verified", v.Name)
+			if !ok || r.SHA256 != v.SHA256 || r.Size != v.Size { // overwrite or substitution (TM-15): refused and audited
+				refusal = records.Failf(records.ReasonDigest, "record %q is not the staged record that was verified", v.Name)
+				return s.appendAudit(ctx, tx, "artifacts", "artifact.commit.refused", attempt, "reason="+records.ReasonDigest)
 			}
 			add += r.Size
 			delete(staged, v.ID)
 		}
 		if len(staged) > 0 {
-			return records.Failf(records.ReasonUncommitted, "%d staged record(s) of %s were not verified", len(staged), attempt)
+			refusal = records.Failf(records.ReasonUncommitted, "%d staged record(s) of %s were not verified", len(staged), attempt)
+			return s.appendAudit(ctx, tx, "artifacts", "artifact.commit.refused", attempt, "reason="+records.ReasonUncommitted)
 		}
 		u, err := artUsage(ctx, tx, project)
 		if err != nil {
diff --git a/free/ci/internal/store/migrations/cache-entries/0003_use_project.sql b/free/ci/internal/store/migrations/cache-entries/0003_use_project.sql
new file mode 100644
index 000000000..ba766f7ec
--- /dev/null
+++ b/free/ci/internal/store/migrations/cache-entries/0003_use_project.sql
@@ -0,0 +1,9 @@
+-- Expand-only (P7-SCHED-20). `nself ci runs stats` sums cache use per project; joining cache_attempt for every
+-- use row cost a seek a row, so each use keeps its attempt's project, set by triggers at write time. project is
+-- NULL exactly when the attempt has no cache_attempt row, which the old LEFT JOIN read as ''.
+ALTER TABLE cache_use ADD COLUMN project TEXT;
+UPDATE cache_use SET project=(SELECT c.project FROM cache_attempt c WHERE c.attempt_id=cache_use.attempt_id);
+CREATE TRIGGER cache_use_project AFTER INSERT ON cache_use BEGIN UPDATE cache_use SET project=(SELECT c.project FROM cache_attempt c WHERE c.attempt_id=NEW.attempt_id) WHERE id=NEW.id; END;
+CREATE TRIGGER cache_use_attempt_in AFTER INSERT ON cache_attempt BEGIN UPDATE cache_use SET project=NEW.project WHERE attempt_id=NEW.attempt_id; END;
+CREATE TRIGGER cache_use_attempt_out AFTER DELETE ON cache_attempt BEGIN UPDATE cache_use SET project=NULL WHERE attempt_id=OLD.attempt_id; END;
+CREATE INDEX cache_use_stats ON cache_use(ts,project,result,bytes);
diff --git a/free/ci/internal/store/migrations/node-labels/0001_labels.sql b/free/ci/internal/store/migrations/node-labels/0001_labels.sql
new file mode 100644
index 000000000..8879b5cda
--- /dev/null
+++ b/free/ci/internal/store/migrations/node-labels/0001_labels.sql
@@ -0,0 +1,12 @@
+CREATE TABLE node_label (
+ node_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL DEFAULT '',
+ updated_at INTEGER NOT NULL,
+ PRIMARY KEY (node_id, key)
+);
+CREATE TABLE node_label_audit (
+ seq INTEGER PRIMARY KEY AUTOINCREMENT, node_id TEXT NOT NULL, actor TEXT NOT NULL,
+ action TEXT NOT NULL CHECK(action IN ('set','change','remove')),
+ key TEXT NOT NULL, old_value TEXT NOT NULL DEFAULT '', value TEXT NOT NULL DEFAULT '',
+ at INTEGER NOT NULL
+);
+CREATE INDEX node_label_audit_node ON node_label_audit(node_id, seq);
diff --git a/free/ci/internal/store/migrations/sched-telemetry/0002_outcome_job.sql b/free/ci/internal/store/migrations/sched-telemetry/0002_outcome_job.sql
new file mode 100644
index 000000000..4e64f83cb
--- /dev/null
+++ b/free/ci/internal/store/migrations/sched-telemetry/0002_outcome_job.sql
@@ -0,0 +1,13 @@
+-- Expand-only (P7-SCHED-20). `nself ci runs stats` reads every outcome of the window with its job, attempt
+-- number and trigger. Joining attempt, job and pipeline for each row cost three index seeks a row (2.5 s for
+-- 100 000 outcomes on the Linux runner), so the outcome keeps the three values, set by triggers at write time.
+-- job_id is NULL exactly when the attempt-job-pipeline join finds no row; the stats read leaves those out,
+-- as the join did. The covering index answers that read from the index alone.
+ALTER TABLE schedtel_outcome ADD COLUMN job_id TEXT;
+ALTER TABLE schedtel_outcome ADD COLUMN attempt_n INTEGER;
+ALTER TABLE schedtel_outcome ADD COLUMN pipeline_trigger TEXT;
+UPDATE schedtel_outcome SET (job_id,attempt_n,pipeline_trigger)=(SELECT a.job_id,a.n,p.trigger FROM attempt a JOIN job j ON j.id=a.job_id JOIN pipeline p ON p.id=j.pipeline_id WHERE a.id=schedtel_outcome.attempt_id);
+CREATE TRIGGER schedtel_outcome_job AFTER INSERT ON schedtel_outcome BEGIN UPDATE schedtel_outcome SET (job_id,attempt_n,pipeline_trigger)=(SELECT a.job_id,a.n,p.trigger FROM attempt a JOIN job j ON j.id=a.job_id JOIN pipeline p ON p.id=j.pipeline_id WHERE a.id=NEW.attempt_id) WHERE rowid=NEW.rowid; END;
+CREATE TRIGGER schedtel_outcome_attempt_in AFTER INSERT ON attempt BEGIN UPDATE schedtel_outcome SET (job_id,attempt_n,pipeline_trigger)=(SELECT a.job_id,a.n,p.trigger FROM attempt a JOIN job j ON j.id=a.job_id JOIN pipeline p ON p.id=j.pipeline_id WHERE a.id=NEW.id) WHERE attempt_id=NEW.id; END;
+CREATE TRIGGER schedtel_outcome_attempt_out AFTER DELETE ON attempt BEGIN UPDATE schedtel_outcome SET job_id=NULL,attempt_n=NULL,pipeline_trigger=NULL WHERE attempt_id=OLD.id; END;
+CREATE INDEX schedtel_outcome_stats ON schedtel_outcome(project,ts,job_id,attempt_n,attempt_id,job_key,runner,runner_class,result,failure_class,pipeline_trigger,wait_ms,runtime_ms,cold_start_ms);
diff --git a/free/ci/internal/store/node_labels.go b/free/ci/internal/store/node_labels.go
new file mode 100644
index 000000000..2638dd3aa
--- /dev/null
+++ b/free/ci/internal/store/node_labels.go
@@ -0,0 +1,203 @@
+package store
+
+// Purpose: operator-assigned node labels (P7-NODE-30) and their per-key audit trail, in migration set
+// `node-labels`. The placement label source (internal/nodes/labels) reads them into the world.
+// Inputs:  a node id, the full desired label set and the acting operator.
+// Outputs: the stored labels sorted by key; one audit row per key that was set, changed or removed.
+// Constraints: the store checks shape only (non-empty node, actor and keys, no duplicate key); key and
+//          value syntax, the reserved prefix and the count limit belong to internal/nodes/labels (E658).
+//          A replace that changes nothing writes no audit rows. Labels and audit commit in one transaction.
+
+import (
+	"context"
+	"database/sql"
+	"embed"
+	"fmt"
+	"sort"
+)
+
+//go:embed migrations/node-labels/*.sql
+var nodeLabelsMigrations embed.FS
+
+func init() {
+	if err := Register("node-labels", nodeLabelsMigrations); err != nil {
+		panic(err)
+	}
+}
+
+// Label audit actions.
+const (
+	LabelSet    = "set"
+	LabelChange = "change"
+	LabelRemove = "remove"
+)
+
+// NodeLabel is one assigned label; an empty Value is a bare key label.
+type NodeLabel struct {
+	Key   string `json:"key"`
+	Value string `json:"value"`
+}
+
+// NodeLabelChange is one audit row of a label edit.
+type NodeLabelChange struct {
+	Seq      int64  `json:"seq"`
+	NodeID   string `json:"node"`
+	Actor    string `json:"actor"`
+	Action   string `json:"action"`
+	Key      string `json:"key"`
+	OldValue string `json:"old_value"`
+	Value    string `json:"value"`
+	At       int64  `json:"at"`
+}
+
+// NodeLabelsReplace makes set the node's whole label set and records each difference as an audit row.
+// Shape errors (empty node, actor or key, a duplicate key) are E607.
+func (s *Store) NodeLabelsReplace(ctx context.Context, nodeID string, set []NodeLabel, actor string) error {
+	if nodeID == "" || actor == "" {
+		return coded("E607", "node id and actor required")
+	}
+	want := map[string]string{}
+	for _, l := range set {
+		if l.Key == "" {
+			return coded("E607", "label key required")
+		}
+		if _, dup := want[l.Key]; dup {
+			return coded("E607", "duplicate label key "+l.Key)
+		}
+		want[l.Key] = l.Value
+	}
+	return s.write(ctx, func(tx *sql.Tx) error {
+		have, err := queryLabels(ctx, tx, nodeID)
+		if err != nil {
+			return err
+		}
+		old := map[string]string{}
+		for _, l := range have {
+			old[l.Key] = l.Value
+		}
+		keys := make([]string, 0, len(old)+len(want))
+		for k := range old {
+			keys = append(keys, k)
+		}
+		for k := range want {
+			if _, ok := old[k]; !ok {
+				keys = append(keys, k)
+			}
+		}
+		sort.Strings(keys)
+		now := s.now().UnixNano()
+		counts := map[string]int{}
+		for _, k := range keys {
+			was, had := old[k]
+			is, keep := want[k]
+			var action string
+			switch {
+			case had && !keep:
+				action = LabelRemove
+				_, err = tx.ExecContext(ctx, `DELETE FROM node_label WHERE node_id=? AND key=?`, nodeID, k)
+			case !had:
+				action = LabelSet
+				_, err = tx.ExecContext(ctx, `INSERT INTO node_label(node_id,key,value,updated_at) VALUES(?,?,?,?)`, nodeID, k, is, now)
+			case was != is:
+				action = LabelChange
+				_, err = tx.ExecContext(ctx, `UPDATE node_label SET value=?,updated_at=? WHERE node_id=? AND key=?`, is, now, nodeID, k)
+			default:
+				continue
+			}
+			if err != nil {
+				return err
+			}
+			if _, err = tx.ExecContext(ctx, `INSERT INTO node_label_audit(node_id,actor,action,key,old_value,value,at) VALUES(?,?,?,?,?,?,?)`,
+				nodeID, actor, action, k, was, is, now); err != nil {
+				return err
+			}
+			counts[action]++
+		}
+		if len(counts) == 0 {
+			return nil
+		}
+		detail := fmt.Sprintf("set=%d change=%d remove=%d", counts[LabelSet], counts[LabelChange], counts[LabelRemove])
+		return s.appendAudit(ctx, tx, actor, "node.labels", nodeID, detail)
+	})
+}
+
+// NodeLabels returns the node's labels sorted by key; an unknown node has none.
+func (s *Store) NodeLabels(ctx context.Context, nodeID string) ([]NodeLabel, error) {
+	return queryLabels(ctx, s.readers, nodeID)
+}
+
+// NodeLabelsAll returns every labeled node's labels, keyed by node id.
+func (s *Store) NodeLabelsAll(ctx context.Context) (map[string][]NodeLabel, error) {
+	rows, err := s.readers.QueryContext(ctx, `SELECT node_id,key,value FROM node_label ORDER BY node_id,key`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[string][]NodeLabel{}
+	for rows.Next() {
+		var id string
+		var l NodeLabel
+		if err = rows.Scan(&id, &l.Key, &l.Value); err != nil {
+			return nil, err
+		}
+		out[id] = append(out[id], l)
+	}
+	return out, rows.Err()
+}
+
+// PipelineProjects returns every project id a pipeline was recorded for, sorted: the projects this store has seen.
+func (s *Store) PipelineProjects(ctx context.Context) ([]string, error) {
+	rows, err := s.readers.QueryContext(ctx, `SELECT DISTINCT project FROM pipeline WHERE project<>'' ORDER BY project`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []string{}
+	for rows.Next() {
+		var p string
+		if err = rows.Scan(&p); err != nil {
+			return nil, err
+		}
+		out = append(out, p)
+	}
+	return out, rows.Err()
+}
+
+// NodeLabelAudit returns the node's label audit rows, oldest first.
+func (s *Store) NodeLabelAudit(ctx context.Context, nodeID string) ([]NodeLabelChange, error) {
+	rows, err := s.readers.QueryContext(ctx, `SELECT seq,node_id,actor,action,key,old_value,value,at FROM node_label_audit WHERE node_id=? ORDER BY seq`, nodeID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []NodeLabelChange
+	for rows.Next() {
+		var c NodeLabelChange
+		if err = rows.Scan(&c.Seq, &c.NodeID, &c.Actor, &c.Action, &c.Key, &c.OldValue, &c.Value, &c.At); err != nil {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+type labelQuerier interface {
+	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
+}
+
+func queryLabels(ctx context.Context, q labelQuerier, nodeID string) ([]NodeLabel, error) {
+	rows, err := q.QueryContext(ctx, `SELECT key,value FROM node_label WHERE node_id=? ORDER BY key`, nodeID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []NodeLabel{}
+	for rows.Next() {
+		var l NodeLabel
+		if err = rows.Scan(&l.Key, &l.Value); err != nil {
+			return nil, err
+		}
+		out = append(out, l)
+	}
+	return out, rows.Err()
+}
diff --git a/free/ci/internal/store/node_labels_test.go b/free/ci/internal/store/node_labels_test.go
new file mode 100644
index 000000000..0b603936e
--- /dev/null
+++ b/free/ci/internal/store/node_labels_test.go
@@ -0,0 +1,93 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"reflect"
+	"testing"
+)
+
+func TestNodeLabelsReplaceAudit(t *testing.T) {
+	ctx := context.Background()
+	s := testStore(t)
+	if err := s.NodeLabelsReplace(ctx, "n1", []NodeLabel{{"zone", "eu"}, {"gpu", ""}}, "alice"); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.NodeLabelsReplace(ctx, "n1", []NodeLabel{{"zone", "us"}, {"ssd", "yes"}}, "bob"); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.NodeLabelsReplace(ctx, "n1", []NodeLabel{{"ssd", "yes"}, {"zone", "us"}}, "bob"); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.NodeLabelsReplace(ctx, "n2", []NodeLabel{{"pool", "a"}}, "alice"); err != nil {
+		t.Fatal(err)
+	}
+	got, err := s.NodeLabels(ctx, "n1")
+	if err != nil || !reflect.DeepEqual(got, []NodeLabel{{"ssd", "yes"}, {"zone", "us"}}) {
+		t.Fatalf("labels %v %v", got, err)
+	}
+	all, err := s.NodeLabelsAll(ctx)
+	if err != nil || len(all) != 2 || !reflect.DeepEqual(all["n2"], []NodeLabel{{"pool", "a"}}) {
+		t.Fatalf("all %v %v", all, err)
+	}
+	audit, err := s.NodeLabelAudit(ctx, "n1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var acts []string
+	for _, c := range audit {
+		acts = append(acts, c.Actor+":"+c.Action+":"+c.Key+":"+c.OldValue+">"+c.Value)
+	}
+	want := []string{"alice:set:gpu:>", "alice:set:zone:>eu", "bob:remove:gpu:>", "bob:set:ssd:>yes", "bob:change:zone:eu>us"}
+	if !reflect.DeepEqual(acts, want) {
+		t.Fatalf("audit %v", acts)
+	}
+	if err = s.NodeLabelsReplace(ctx, "n1", nil, "carol"); err != nil {
+		t.Fatal(err)
+	}
+	if got, _ = s.NodeLabels(ctx, "n1"); len(got) != 0 {
+		t.Fatalf("cleared labels %v", got)
+	}
+}
+
+func TestNodeLabelsReplaceRejectsShape(t *testing.T) {
+	ctx := context.Background()
+	s := testStore(t)
+	for _, c := range []struct {
+		node, actor string
+		set         []NodeLabel
+	}{
+		{"", "a", nil},
+		{"n", "", nil},
+		{"n", "a", []NodeLabel{{"", "v"}}},
+		{"n", "a", []NodeLabel{{"k", "1"}, {"k", "2"}}},
+	} {
+		err := s.NodeLabelsReplace(ctx, c.node, c.set, c.actor)
+		if e, ok := err.(*Error); !ok || e.Code != "E607" {
+			t.Fatalf("%v: %v", c, err)
+		}
+	}
+}
+
+func TestPipelineProjectsListsDistinctSeen(t *testing.T) {
+	ctx := context.Background()
+	s := testStore(t)
+	got, err := s.PipelineProjects(ctx)
+	if err != nil || len(got) != 0 {
+		t.Fatalf("empty store: %v %v", got, err)
+	}
+	for i, p := range []string{"proj-b", "proj-a", "proj-b"} {
+		id := string(rune('a' + i))
+		err = s.write(ctx, func(tx *sql.Tx) error {
+			_, e := tx.ExecContext(ctx, `INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES(?,?,'r','push','t','z','d','i','m','r','s','passed',1)`, "p-"+id, p)
+			return e
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	got, err = s.PipelineProjects(ctx)
+	if err != nil || !reflect.DeepEqual(got, []string{"proj-a", "proj-b"}) {
+		t.Fatalf("projects %v %v", got, err)
+	}
+}
diff --git a/free/ci/internal/store/sched_stats.go b/free/ci/internal/store/sched_stats.go
new file mode 100644
index 000000000..76503d644
--- /dev/null
+++ b/free/ci/internal/store/sched_stats.go
@@ -0,0 +1,185 @@
+package store
+
+// Purpose: the read-only queries behind `nself ci runs stats` (P7-SCHED-20, Epic D23): one read
+// transaction over the rows the scheduling, cache, lease, node and outbox sets already keep.
+// Inputs:  a StatsQuery (clock, window, optional exact project).
+// Outputs: StatsRows, the raw rows internal/stats aggregates; no aggregation happens here.
+// Constraints: read transactions only; every statement is index-assisted (the query-plan test in
+//          internal/stats explains each StatsStatements entry); a set whose table is absent
+//          reports it in Missing instead of failing; times: telemetry ts is milliseconds, every
+//          other table nanoseconds; the project filter is an index range, never a table scan, and
+//          binds the outcome, queued and lease statements; nodes carry no project and feed the
+//          runner slots of a scoped document too; outcomes and cache use read the job, trigger and
+//          project their write-time triggers keep, so no statement looks rows up one by one.
+
+import (
+	"context"
+	"database/sql"
+	"time"
+)
+
+// StatsQuery selects the window. Project "" reads every project.
+type StatsQuery struct {
+	Now     time.Time
+	Since   time.Duration
+	Project string
+}
+
+// StatOutcome is one finished attempt with its job and trigger.
+type StatOutcome struct {
+	Attempt, Job, Project, JobKey, Runner, RunnerClass, Result, FailureClass, Trigger string
+	N                                                                                 int
+	WaitMs, RuntimeMs, ColdStartMs                                                    int64
+}
+
+// StatGroup is one aggregated row: a project, a key (result, confidence or state), a count and a sum.
+type StatGroup struct {
+	Project, Key string
+	N, Sum       int64
+}
+
+// StatLease is one lease with the state of its attempt and its project.
+type StatLease struct {
+	Project, AttemptState string
+	ExpiresAt, Epoch      int64
+}
+
+// StatNode is one node with its capability document (empty when none).
+type StatNode struct {
+	ID, Name, State, Doc string
+	UpdatedAt            int64
+}
+
+// StatsRows is everything the aggregation reads.
+type StatsRows struct {
+	Outcomes  []StatOutcome
+	Queued    []StatGroup // Key = trigger
+	Cache     []StatGroup // Key = result, Sum = bytes
+	Ledger    []StatGroup // Key = confidence, Sum = micro
+	CAS       []StatGroup // Sum = bytes
+	Artifacts []StatGroup // Sum = bytes
+	Leases    []StatLease
+	Nodes     []StatNode
+	// OutboxPending counts unposted entries; OutboxOldest is the creation time (ns) of the oldest, 0 for none.
+	OutboxPending, OutboxOldest int64
+	Incarnation                 int64
+	Path                        string
+	Missing                     map[string]bool
+}
+
+// StatsStmt is one statement with the arguments a query binds.
+type StatsStmt struct {
+	Name, SQL string
+	Args      []any
+}
+
+// statsTables are the tables whose set may be absent; the rest are core.
+var statsTables = []string{"schedtel_outcome", "ledger", "cache_use", "cache_entry", "cache_artifact", "outbox", "node"}
+
+// StatsStatements returns the read statements for q, in the order StatsRead runs them.
+func StatsStatements(q StatsQuery) []StatsStmt {
+	lo, hi := "", "\U0010ffff"
+	if q.Project != "" {
+		lo, hi = q.Project, q.Project
+	}
+	cut := q.Now.Add(-q.Since)
+	ms, ns := cut.UnixMilli(), cut.UnixNano()
+	return []StatsStmt{
+		{"outcomes", `SELECT attempt_id,job_id,attempt_n,project,job_key,runner,runner_class,result,failure_class,pipeline_trigger,wait_ms,runtime_ms,cold_start_ms
+FROM schedtel_outcome WHERE project BETWEEN ? AND ? AND ts>=? AND job_id IS NOT NULL`, []any{lo, hi, ms}},
+		{"queued", `SELECT p.project,p.trigger,count(*) FROM attempt a JOIN job j ON j.id=a.job_id JOIN pipeline p ON p.id=j.pipeline_id WHERE a.state='queued' AND p.project BETWEEN ? AND ? GROUP BY p.project,p.trigger`, []any{lo, hi}},
+		{"cache", `SELECT coalesce(project,''),result,count(*),sum(bytes) FROM cache_use WHERE ts>=? GROUP BY 1,2`, []any{ns}},
+		{"ledger", `SELECT project,confidence,count(*),sum(coalesce(act_micro,est_micro)) FROM ledger WHERE provider>='' AND admitted_at>=? GROUP BY project,confidence`, []any{ns}},
+		{"cas", `SELECT coalesce(c.project,''),count(*),sum(e.bytes) FROM cache_entry e LEFT JOIN cache_attempt c ON c.attempt_id=e.attempt_id WHERE e.namespace>=x'' GROUP BY 1`, nil},
+		{"artifacts", `SELECT project,count(*),sum(size) FROM cache_artifact WHERE project>='' AND state='committed' GROUP BY project`, nil},
+		{"leases", `SELECT coalesce(p.project,''),a.state,l.expires_at,l.epoch FROM lease l JOIN attempt a ON a.id=l.attempt_id JOIN job j ON j.id=a.job_id JOIN pipeline p ON p.id=j.pipeline_id WHERE l.expires_at>=0 AND p.project BETWEEN ? AND ?`, []any{lo, hi}},
+		{"nodes", `SELECT n.id,n.name,n.state,n.updated_at,coalesce(c.doc_json,'') FROM node n LEFT JOIN capability_snapshot c ON c.node_id=n.id WHERE n.id>=''`, nil},
+		{"outbox", `SELECT count(*),coalesce(min(created_at),0) FROM outbox WHERE state IN ('pending','posting','failed')`, nil},
+		{"incarnation", `SELECT coalesce(max(incarnation),0) FROM coordinator WHERE id>=''`, nil},
+	}
+}
+
+// StatsRead runs every statement in one read transaction. A statement whose table is absent is skipped.
+func (s *Store) StatsRead(ctx context.Context, q StatsQuery) (StatsRows, error) {
+	out := StatsRows{Path: s.path, Missing: map[string]bool{}}
+	tx, err := s.readers.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		return out, coded("E607", err.Error())
+	}
+	defer func() { _ = tx.Rollback() }()
+	for _, t := range statsTables {
+		var n int
+		if err = tx.QueryRowContext(ctx, `SELECT count(*) FROM sqlite_master WHERE type='table' AND name=?`, t).Scan(&n); err != nil {
+			return out, coded("E607", err.Error())
+		}
+		out.Missing[t] = n == 0
+	}
+	skip := map[string]bool{"outcomes": out.Missing["schedtel_outcome"], "cache": out.Missing["cache_use"], "ledger": out.Missing["ledger"],
+		"cas": out.Missing["cache_entry"], "artifacts": out.Missing["cache_artifact"], "nodes": out.Missing["node"], "outbox": out.Missing["outbox"]}
+	for _, st := range StatsStatements(q) {
+		if skip[st.Name] {
+			continue
+		}
+		rows, err := tx.QueryContext(ctx, st.SQL, st.Args...)
+		if err != nil {
+			return out, coded("E607", err.Error())
+		}
+		err = scanStats(rows, st.Name, &out)
+		_ = rows.Close()
+		if err == nil {
+			err = rows.Err()
+		}
+		if err != nil {
+			return out, coded("E607", err.Error())
+		}
+	}
+	return out, nil
+}
+
+func scanStats(rows *sql.Rows, name string, out *StatsRows) error {
+	for rows.Next() {
+		var err error
+		switch name {
+		case "outcomes":
+			var o StatOutcome
+			err = rows.Scan(&o.Attempt, &o.Job, &o.N, &o.Project, &o.JobKey, &o.Runner, &o.RunnerClass, &o.Result, &o.FailureClass, &o.Trigger, &o.WaitMs, &o.RuntimeMs, &o.ColdStartMs)
+			out.Outcomes = append(out.Outcomes, o)
+		case "queued":
+			var g StatGroup
+			err = rows.Scan(&g.Project, &g.Key, &g.N)
+			out.Queued = append(out.Queued, g)
+		case "cache", "ledger":
+			var g StatGroup
+			err = rows.Scan(&g.Project, &g.Key, &g.N, &g.Sum)
+			if name == "cache" {
+				out.Cache = append(out.Cache, g)
+			} else {
+				out.Ledger = append(out.Ledger, g)
+			}
+		case "cas", "artifacts":
+			var g StatGroup
+			err = rows.Scan(&g.Project, &g.N, &g.Sum)
+			if name == "cas" {
+				out.CAS = append(out.CAS, g)
+			} else {
+				out.Artifacts = append(out.Artifacts, g)
+			}
+		case "leases":
+			var l StatLease
+			err = rows.Scan(&l.Project, &l.AttemptState, &l.ExpiresAt, &l.Epoch)
+			out.Leases = append(out.Leases, l)
+		case "nodes":
+			var n StatNode
+			err = rows.Scan(&n.ID, &n.Name, &n.State, &n.UpdatedAt, &n.Doc)
+			out.Nodes = append(out.Nodes, n)
+		case "outbox":
+			err = rows.Scan(&out.OutboxPending, &out.OutboxOldest)
+		case "incarnation":
+			err = rows.Scan(&out.Incarnation)
+		}
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
diff --git a/free/ci/internal/store/sched_stats_denorm_test.go b/free/ci/internal/store/sched_stats_denorm_test.go
new file mode 100644
index 000000000..2d0c2c1a8
--- /dev/null
+++ b/free/ci/internal/store/sched_stats_denorm_test.go
@@ -0,0 +1,52 @@
+package store
+
+// Tests of the write-time stats columns (P7-SCHED-20): an outcome reads its job, attempt number and trigger
+// whichever of outcome and attempt is written first and drops out when its attempt is pruned, as the old
+// attempt-job-pipeline join did; a cache use follows its cache_attempt project the same way.
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestStatsOutcomeJobFollowsAttempt(t *testing.T) {
+	s := testStore(t)
+	ctx := context.Background()
+	now := time.Now()
+	exec := func(q string, args ...any) {
+		t.Helper()
+		if _, err := s.writer.Exec(q, args...); err != nil {
+			t.Fatalf("%v\n%s", err, q)
+		}
+	}
+	read := func() StatsRows {
+		t.Helper()
+		rows, err := s.StatsRead(ctx, StatsQuery{Now: now, Since: time.Hour})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return rows
+	}
+	exec(`INSERT INTO schedtel_outcome(attempt_id,project,job_key,runner,runner_class,wait_ms,runtime_ms,cold_start_ms,cost_micro,result,failure_class,ts) VALUES('a1','acme/a','build','r1','owned',10,20,-1,0,'passed','',?)`, now.UnixMilli())
+	exec(`INSERT INTO cache_use(attempt_id,spec,cache_key,result,bytes,ms,ts) VALUES('a1','go','k','hit',7,1,?)`, now.UnixNano())
+	if rows := read(); len(rows.Outcomes) != 0 || len(rows.Cache) != 1 || rows.Cache[0].Project != "" {
+		t.Fatalf("before the attempt: outcomes %+v, cache %+v", rows.Outcomes, rows.Cache)
+	}
+	exec(`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES('p1','acme/a','r','schedule','t','z','d','i','m','r','s','passed',1)`)
+	exec(`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES('j1','p1','build','k',1,1,'i',1,'passed')`)
+	exec(`INSERT INTO attempt(id,job_id,n,state) VALUES('a1','j1',2,'passed')`)
+	exec(`INSERT INTO cache_attempt(attempt_id,project,trust,protection,secrets_declared,private_deps,recorded_at) VALUES('a1','acme/a','owner','none',0,0,1)`)
+	rows := read()
+	if len(rows.Outcomes) != 1 || rows.Outcomes[0].Job != "j1" || rows.Outcomes[0].N != 2 || rows.Outcomes[0].Trigger != "schedule" {
+		t.Fatalf("after the attempt: %+v", rows.Outcomes)
+	}
+	if len(rows.Cache) != 1 || rows.Cache[0].Project != "acme/a" || rows.Cache[0].Sum != 7 {
+		t.Fatalf("cache after its attempt: %+v", rows.Cache)
+	}
+	exec(`DELETE FROM cache_attempt WHERE attempt_id='a1'`)
+	exec(`DELETE FROM attempt WHERE id='a1'`)
+	if rows = read(); len(rows.Outcomes) != 0 || len(rows.Cache) != 1 || rows.Cache[0].Project != "" {
+		t.Fatalf("after the prune: outcomes %+v, cache %+v", rows.Outcomes, rows.Cache)
+	}
+}
diff --git a/free/ci/internal/store/sched_stats_test.go b/free/ci/internal/store/sched_stats_test.go
new file mode 100644
index 000000000..4fea2f40d
--- /dev/null
+++ b/free/ci/internal/store/sched_stats_test.go
@@ -0,0 +1,66 @@
+package store
+
+// Tests of the stats read queries (P7-SCHED-20): an empty store reads clean, rows come back for the
+// window and project asked for, and a dropped set is reported missing instead of failing.
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func statsSeed(t *testing.T, s *Store, project, attempt string, tsMs int64) {
+	t.Helper()
+	for _, q := range []string{
+		`INSERT INTO pipeline(id,project,revision,trigger,source_trust,privacy_zone,policy_digest,input_digest,selection_mode,selection_reason,selection_digest,status,created_at) VALUES('p-` + attempt + `','` + project + `','r','push','t','z','d','i','m','r','s','passed',1)`,
+		`INSERT INTO job(id,pipeline_id,name,kind,idempotent,infra_max,input_digest,required,status) VALUES('j-` + attempt + `','p-` + attempt + `','build','k',1,1,'i',1,'passed')`,
+		`INSERT INTO attempt(id,job_id,n,state) VALUES('` + attempt + `','j-` + attempt + `',1,'passed')`,
+	} {
+		if _, err := s.writer.Exec(q); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := s.writer.Exec(`INSERT INTO schedtel_outcome(attempt_id,project,job_key,runner,runner_class,wait_ms,runtime_ms,cold_start_ms,cost_micro,result,failure_class,ts) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`,
+		attempt, project, "build", "r1", "owned", 10, 20, -1, 0, "passed", "", tsMs); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestStatsReadEmptyStore(t *testing.T) {
+	s := testStore(t)
+	rows, err := s.StatsRead(context.Background(), StatsQuery{Now: time.Now(), Since: time.Hour})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows.Outcomes)+len(rows.Leases)+len(rows.Nodes) != 0 || rows.OutboxPending != 0 || rows.Path == "" {
+		t.Fatalf("empty store gave rows: %+v", rows)
+	}
+}
+
+func TestStatsReadWindowAndProject(t *testing.T) {
+	s := testStore(t)
+	now := time.Now()
+	statsSeed(t, s, "acme/a", "a1", now.Add(-time.Minute).UnixMilli())
+	statsSeed(t, s, "acme/b", "b1", now.Add(-time.Minute).UnixMilli())
+	statsSeed(t, s, "acme/a", "a2", now.Add(-48*time.Hour).UnixMilli()) // outside the window
+	ctx := context.Background()
+	all, err := s.StatsRead(ctx, StatsQuery{Now: now, Since: 24 * time.Hour})
+	if err != nil || len(all.Outcomes) != 2 {
+		t.Fatalf("all: %d outcomes, %v", len(all.Outcomes), err)
+	}
+	one, err := s.StatsRead(ctx, StatsQuery{Now: now, Since: 24 * time.Hour, Project: "acme/a"})
+	if err != nil || len(one.Outcomes) != 1 || one.Outcomes[0].Attempt != "a1" || one.Outcomes[0].Trigger != "push" {
+		t.Fatalf("project a: %+v, %v", one.Outcomes, err)
+	}
+}
+
+func TestStatsReadMissingSet(t *testing.T) {
+	s := testStore(t)
+	if _, err := s.writer.Exec(`DROP TABLE outbox`); err != nil {
+		t.Fatal(err)
+	}
+	rows, err := s.StatsRead(context.Background(), StatsQuery{Now: time.Now(), Since: time.Hour})
+	if err != nil || !rows.Missing["outbox"] || rows.Missing["ledger"] {
+		t.Fatalf("missing = %v, %v", rows.Missing, err)
+	}
+}
diff --git a/free/ci/internal/store/trust_attest.go b/free/ci/internal/store/trust_attest.go
index 3b0b79457..7e5383878 100644
--- a/free/ci/internal/store/trust_attest.go
+++ b/free/ci/internal/store/trust_attest.go
@@ -200,6 +200,10 @@ func (l AttestLedger) RevokeNode(ctx context.Context, nodeID, reason string) (at
 
 func affected(ctx context.Context, tx *sql.Tx, keyIDs []string, out *attest.Affected) (err error) {
 	ids, _ := json.Marshal(keyIDs)
+	runs, err := tx.QueryContext(ctx, `SELECT DISTINCT run_id FROM attest_quarantine WHERE key_id IN (SELECT value FROM json_each(?)) ORDER BY run_id`, string(ids))
+	if out.Runs, err = pkiCollect(runs, err, func(r *sql.Rows) (id string, e error) { return id, r.Scan(&id) }); err != nil {
+		return err
+	}
 	gates, err := tx.QueryContext(ctx, `SELECT DISTINCT repo_id,revision,job FROM attest_use WHERE key_id IN (SELECT value FROM json_each(?)) ORDER BY repo_id,revision,job`, string(ids))
 	if out.Gates, err = pkiCollect(gates, err, func(r *sql.Rows) (g attest.GateRef, e error) { return g, r.Scan(&g.RepoID, &g.Revision, &g.Job) }); err != nil {
 		return err
diff --git a/free/ci/internal/svc/config.go b/free/ci/internal/svc/config.go
new file mode 100644
index 000000000..fbae057ff
--- /dev/null
+++ b/free/ci/internal/svc/config.go
@@ -0,0 +1,104 @@
+// Package svc renders and reconciles the personal watcher's service files.
+package svc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/toolchain"
+)
+
+// Config contains explicit paths; no service value is taken from PATH.
+type Config struct {
+	Manager                    string
+	System, DryRun             bool
+	Home, CIHome, Repo, Binary string
+	EnvFile                    string
+	UID                        int
+}
+
+// Run executes manager argv through the caller's process funnel.
+type Run func(context.Context, ...string) error
+
+// Installer owns only its fixed unit names and adjacent receipt.
+type Installer struct {
+	Config Config
+	Run    Run
+	Out    io.Writer
+}
+
+// GatePath builds a deterministic search list from manifest tools and their
+// private install roots, followed by standard host tool locations.
+func GatePath(home string) (string, error) {
+	v, err := toolchain.Embedded()
+	if err != nil {
+		return "", err
+	}
+	dirs := []string{filepath.Join(home, "bin")}
+	for _, row := range v.Rows {
+		if row.Kind == toolchain.KindTool && row.Owner != "internal/nodes/provision" {
+			root := filepath.Join(home, "tools", row.Name+"-"+row.Version)
+			dirs = append(dirs, root, filepath.Join(root, "bin"))
+		}
+	}
+	dirs = append(dirs, "/usr/local/go/bin", "/usr/local/rust/bin", "/usr/local/lib/pnpm", "/usr/local/python/bin", "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin")
+	return strings.Join(dirs, ":"), nil
+}
+
+func (c Config) validate() error {
+	if c.Manager != "launchd" && c.Manager != "systemd" {
+		return fmt.Errorf("choose --launchd or --systemd")
+	}
+	if err := c.systemGuard(); err != nil {
+		return err
+	}
+	for _, p := range []string{c.Home, c.CIHome, c.Repo, c.Binary} {
+		if !filepath.IsAbs(p) || strings.ContainsAny(p, "\r\n\x00:") {
+			return fmt.Errorf("service paths must be absolute and contain no newline or colon")
+		}
+	}
+	if c.EnvFile != "" {
+		if c.Manager != "systemd" {
+			return fmt.Errorf("launchd uses the login environment; --env-file requires systemd")
+		}
+		fi, err := os.Lstat(c.EnvFile)
+		if err != nil {
+			return err
+		}
+		if !filepath.IsAbs(c.EnvFile) || !fi.Mode().IsRegular() || fi.Mode().Perm() != 0600 || strings.ContainsAny(c.EnvFile, "\r\n\x00") {
+			return fmt.Errorf("--env-file must name an absolute regular 0600 file")
+		}
+	}
+	return nil
+}
+
+func (c Config) dir() string {
+	if c.Manager == "launchd" {
+		if c.System {
+			return "/Library/LaunchDaemons"
+		}
+		return filepath.Join(c.Home, "Library", "LaunchAgents")
+	}
+	if c.System {
+		return "/etc/systemd/system"
+	}
+	return filepath.Join(c.Home, ".config", "systemd", "user")
+}
+
+func (c Config) names() []string {
+	if c.Manager == "launchd" {
+		return []string{"org.nself.ci-watch.plist", "org.nself.ci-selftest.plist"}
+	}
+	return []string{"nself-ci-watch.service", "nself-ci-selftest.service", "nself-ci-selftest.timer"}
+}
+
+func (i Installer) writer() io.Writer {
+	if i.Out == nil {
+		return io.Discard
+	}
+	return i.Out
+}
diff --git a/free/ci/internal/svc/install.go b/free/ci/internal/svc/install.go
new file mode 100644
index 000000000..bfe8797d3
--- /dev/null
+++ b/free/ci/internal/svc/install.go
@@ -0,0 +1,240 @@
+package svc
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+type receipt struct {
+	Hashes map[string]string `json:"hashes"`
+	Active bool              `json:"active"`
+}
+
+func digest(b []byte) string         { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }
+func (c Config) receiptPath() string { return filepath.Join(c.dir(), ".nself-ci-watch.receipt.json") }
+
+func readRegular(path string) ([]byte, error) {
+	fi, err := os.Lstat(path)
+	if err != nil {
+		return nil, err
+	}
+	if !fi.Mode().IsRegular() {
+		return nil, fmt.Errorf("refusing non-regular service file %s", path)
+	}
+	return os.ReadFile(path)
+}
+
+func (c Config) receipt() (receipt, error) {
+	r := receipt{Hashes: map[string]string{}}
+	b, err := readRegular(c.receiptPath())
+	if errors.Is(err, os.ErrNotExist) {
+		return r, nil
+	}
+	if err != nil {
+		return r, err
+	}
+	if err = json.Unmarshal(b, &r); err != nil {
+		return r, err
+	}
+	if r.Hashes == nil {
+		return r, fmt.Errorf("invalid service receipt")
+	}
+	return r, nil
+}
+
+func atomicWrite(path string, b []byte) error {
+	f, err := os.CreateTemp(filepath.Dir(path), ".ci-service-*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	if _, err = f.Write(b); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err = f.Chmod(0600); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err = f.Close(); err != nil {
+		return err
+	}
+	return os.Rename(f.Name(), path)
+}
+
+func (c Config) save(r receipt) error {
+	b, err := json.MarshalIndent(r, "", "  ")
+	if err != nil {
+		return err
+	}
+	return atomicWrite(c.receiptPath(), append(b, '\n'))
+}
+
+// Install refuses unowned or edited files, writes only changes, and reconciles
+// the manager only after a change or an interrupted activation.
+func (i Installer) Install(ctx context.Context) error {
+	c := i.Config
+	files, err := Files(c)
+	if err != nil {
+		return err
+	}
+	r, err := c.receipt()
+	if err != nil {
+		return err
+	}
+	var changed []string
+	for _, n := range c.names() {
+		b, e := readRegular(filepath.Join(c.dir(), n))
+		if e != nil && !errors.Is(e, os.ErrNotExist) {
+			return e
+		}
+		if e == nil && (r.Hashes[n] == "" || digest(b) != r.Hashes[n]) {
+			return fmt.Errorf("leaving user-edited or unowned unit alone: %s", n)
+		}
+		if e != nil || digest(b) != digest(files[n]) {
+			changed = append(changed, n)
+		}
+	}
+	if len(changed) == 0 && r.Active {
+		fmt.Fprintln(i.writer(), "unchanged")
+		return nil
+	}
+	manager, err := ManagerPath(c)
+	if c.DryRun {
+		manager = c.Manager
+		if c.Manager == "launchd" {
+			manager = "launchctl"
+		} else {
+			manager = "systemctl"
+		}
+		err = nil
+	}
+	if err != nil {
+		return err
+	}
+	if !c.DryRun && i.Run == nil {
+		return fmt.Errorf("no service manager runner")
+	}
+	if err = i.prepareSystem(ctx); err != nil {
+		return err
+	}
+	for _, n := range changed {
+		fmt.Fprintf(i.writer(), "write %s\n", filepath.Join(c.dir(), n))
+		if c.DryRun {
+			fmt.Fprint(i.writer(), string(files[n]))
+		}
+		if !c.DryRun {
+			if err = os.MkdirAll(c.dir(), 0755); err != nil {
+				return err
+			}
+			if err = atomicWrite(filepath.Join(c.dir(), n), files[n]); err != nil {
+				return err
+			}
+			if err = os.Chmod(filepath.Join(c.dir(), n), 0644); err != nil {
+				return err
+			}
+		}
+		r.Hashes[n] = digest(files[n])
+	}
+	if !c.DryRun {
+		if !c.System {
+			err = os.MkdirAll(filepath.Join(c.CIHome, "logs", "watch"), 0700)
+		}
+		if err != nil {
+			return err
+		}
+		r.Active = false
+		if err = c.save(r); err != nil {
+			return err
+		}
+	}
+	// Retry all jobs after an interrupted activation, including unchanged files.
+	if err = i.activate(ctx, manager, c.names()); err != nil {
+		return err
+	}
+	if c.DryRun {
+		return nil
+	}
+	r.Active = true
+	return c.save(r)
+}
+
+// Uninstall removes only files whose contents still match the install receipt.
+// Edited units remain loaded, remain on disk, and retain their ownership record.
+func (i Installer) Uninstall(ctx context.Context) error {
+	c := i.Config
+	if err := c.validate(); err != nil {
+		return err
+	}
+	r, err := c.receipt()
+	if err != nil {
+		return err
+	}
+	var remove []string
+	for _, n := range c.names() {
+		if r.Hashes[n] == "" {
+			continue
+		}
+		b, e := readRegular(filepath.Join(c.dir(), n))
+		if errors.Is(e, os.ErrNotExist) {
+			delete(r.Hashes, n)
+			continue
+		}
+		if e != nil || digest(b) != r.Hashes[n] {
+			fmt.Fprintf(i.writer(), "leaving user-edited unit alone: %s\n", n)
+			continue
+		}
+		remove = append(remove, n)
+	}
+	if len(remove) == 0 {
+		return nil
+	}
+	manager, err := ManagerPath(c)
+	if c.DryRun {
+		manager = "systemctl"
+		if c.Manager == "launchd" {
+			manager = "launchctl"
+		}
+		err = nil
+	}
+	if err != nil {
+		return err
+	}
+	if !c.DryRun && i.Run == nil {
+		return fmt.Errorf("no service manager runner")
+	}
+	for _, n := range remove {
+		if err = i.deactivate(ctx, manager, n); err != nil {
+			return err
+		}
+		fmt.Fprintf(i.writer(), "remove %s\n", filepath.Join(c.dir(), n))
+		if !c.DryRun {
+			if err = os.Remove(filepath.Join(c.dir(), n)); err != nil {
+				return err
+			}
+			delete(r.Hashes, n)
+			if err = c.save(r); err != nil {
+				return err
+			}
+		}
+	}
+	if c.Manager == "systemd" {
+		args := []string{"daemon-reload"}
+		if !c.System {
+			args = append([]string{"--user"}, args...)
+		}
+		if err = i.command(ctx, manager, args...); err != nil {
+			return err
+		}
+	}
+	if !c.DryRun && len(r.Hashes) == 0 {
+		return os.Remove(c.receiptPath())
+	}
+	return nil
+}
diff --git a/free/ci/internal/svc/install_test.go b/free/ci/internal/svc/install_test.go
new file mode 100644
index 000000000..e2d94c05e
--- /dev/null
+++ b/free/ci/internal/svc/install_test.go
@@ -0,0 +1,205 @@
+package svc
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+func testInstaller(t *testing.T, manager string) (Installer, *bytes.Buffer, *[][]string) {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("CI", "1")
+	t.Setenv("HOME", home)
+	bin := filepath.Join(home, "bin")
+	if err := os.MkdirAll(bin, 0700); err != nil {
+		t.Fatal(err)
+	}
+	for _, n := range []string{"launchctl", "systemctl"} {
+		if err := os.WriteFile(filepath.Join(bin, n), []byte("#!/bin/sh\nexit 0\n"), 0700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", bin)
+	c := Config{Manager: manager, Home: home, CIHome: filepath.Join(home, "ci"), Repo: home, Binary: "/usr/local/bin/nself", UID: 501}
+	var out bytes.Buffer
+	calls := new([][]string)
+	i := Installer{Config: c, Out: &out, Run: func(_ context.Context, argv ...string) error {
+		*calls = append(*calls, append([]string{}, argv...))
+		return nil
+	}}
+	return i, &out, calls
+}
+
+func TestInstallIdempotent(t *testing.T) {
+	for _, manager := range []string{"launchd", "systemd"} {
+		t.Run(manager, func(t *testing.T) {
+			i, out, calls := testInstaller(t, manager)
+			if err := i.Install(context.Background()); err != nil {
+				t.Fatal(err)
+			}
+			old := time.Unix(123456, 0)
+			paths := append(i.Config.names(), filepath.Base(i.Config.receiptPath()))
+			for _, n := range paths {
+				if err := os.Chtimes(filepath.Join(i.Config.dir(), n), old, old); err != nil {
+					t.Fatal(err)
+				}
+			}
+			before := len(*calls)
+			out.Reset()
+			if err := i.Install(context.Background()); err != nil {
+				t.Fatal(err)
+			}
+			if out.String() != "unchanged\n" || before != len(*calls) {
+				t.Fatalf("second install: %q, calls %v", out, *calls)
+			}
+			for _, n := range paths {
+				fi, err := os.Stat(filepath.Join(i.Config.dir(), n))
+				if err != nil || !fi.ModTime().Equal(old) {
+					t.Fatalf("rewrote %s: %v", n, err)
+				}
+			}
+		})
+	}
+}
+
+func TestUninstallExact(t *testing.T) {
+	for _, manager := range []string{"launchd", "systemd"} {
+		t.Run(manager, func(t *testing.T) {
+			i, out, calls := testInstaller(t, manager)
+			if err := i.Install(context.Background()); err != nil {
+				t.Fatal(err)
+			}
+			name := i.Config.names()[0]
+			path := filepath.Join(i.Config.dir(), name)
+			if err := os.WriteFile(path, []byte("user edit"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			other := filepath.Join(i.Config.dir(), "other.service")
+			if err := os.WriteFile(other, []byte("unrelated"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			*calls = nil
+			if err := i.Uninstall(context.Background()); err != nil {
+				t.Fatal(err)
+			}
+			if !strings.Contains(out.String(), "leaving user-edited") {
+				t.Fatal("no note")
+			}
+			for _, p := range []string{path, other} {
+				if _, err := os.Stat(p); err != nil {
+					t.Fatal(err)
+				}
+			}
+			for _, n := range i.Config.names()[1:] {
+				if _, err := os.Stat(filepath.Join(i.Config.dir(), n)); !errors.Is(err, os.ErrNotExist) {
+					t.Fatalf("left %s: %v", n, err)
+				}
+			}
+			for _, argv := range *calls {
+				if strings.Contains(strings.Join(argv, " "), strings.TrimSuffix(name, ".plist")) {
+					t.Fatalf("touched edited job: %v", argv)
+				}
+			}
+		})
+	}
+	i, _, _ := testInstaller(t, "systemd")
+	if err := i.Install(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if err := i.Uninstall(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	entries, err := os.ReadDir(i.Config.dir())
+	if err != nil || len(entries) != 0 {
+		t.Fatalf("left files: %v, %v", entries, err)
+	}
+	if err := i.Uninstall(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestNeverTouchesRealManager(t *testing.T) {
+	i, _, calls := testInstaller(t, "systemd")
+	t.Setenv("PATH", "/usr/bin:/bin")
+	if err := i.Install(context.Background()); err == nil {
+		t.Fatal("accepted real manager in CI")
+	}
+	if len(*calls) != 0 {
+		t.Fatal("ran real manager")
+	}
+	if _, err := os.Stat(i.Config.dir()); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("wrote files before rejecting manager")
+	}
+	t.Setenv("PATH", filepath.Join(i.Config.Home, "bin"))
+	if err := os.Remove(filepath.Join(i.Config.Home, "bin", "systemctl")); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink("/usr/bin/true", filepath.Join(i.Config.Home, "bin", "systemctl")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ManagerPath(i.Config); err == nil {
+		t.Fatal("allowed symlink escape")
+	}
+}
+
+func TestDryRunAndRefusal(t *testing.T) {
+	i, out, calls := testInstaller(t, "launchd")
+	i.Config.DryRun = true
+	if err := i.Install(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if len(*calls) != 0 || !strings.Contains(out.String(), "bootstrap gui/501") || !strings.Contains(out.String(), "<plist") {
+		t.Fatalf("bad dry-run: %s", out)
+	}
+	if _, err := os.Stat(i.Config.dir()); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("dry-run wrote")
+	}
+	i.Config.DryRun = false
+	if err := os.MkdirAll(i.Config.dir(), 0700); err != nil {
+		t.Fatal(err)
+	}
+	p := filepath.Join(i.Config.dir(), i.Config.names()[1])
+	if err := os.WriteFile(p, []byte("unowned"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := i.Install(context.Background()); err == nil {
+		t.Fatal("overwrote unowned")
+	}
+	if len(*calls) != 0 {
+		t.Fatal("called manager on refusal")
+	}
+}
+
+func TestActivationRetry(t *testing.T) {
+	i, _, calls := testInstaller(t, "systemd")
+	run := i.Run
+	i.Run = func(context.Context, ...string) error { return errors.New("manager unavailable") }
+	if err := i.Install(context.Background()); err == nil {
+		t.Fatal("lost manager error")
+	}
+	i.Run = run
+	if err := i.Install(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	r, err := i.Config.receipt()
+	if err != nil || !r.Active || len(*calls) == 0 {
+		t.Fatalf("did not retry: %+v %v", r, err)
+	}
+	files, err := Files(i.Config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for n, want := range files {
+		got, err := os.ReadFile(filepath.Join(i.Config.dir(), n))
+		if err != nil || !reflect.DeepEqual(got, want) {
+			t.Fatal(n, err)
+		}
+	}
+}
diff --git a/free/ci/internal/svc/manager.go b/free/ci/internal/svc/manager.go
new file mode 100644
index 000000000..c8e613e9f
--- /dev/null
+++ b/free/ci/internal/svc/manager.go
@@ -0,0 +1,117 @@
+package svc
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// ManagerPath resolves a fixed system manager. Under CI=1 only an executable
+// beneath the temporary login HOME is accepted, with no fallback to the host.
+func ManagerPath(c Config) (string, error) {
+	name := "systemctl"
+	if c.Manager == "launchd" {
+		name = "launchctl"
+	}
+	dirs := []string{"/bin", "/usr/bin"}
+	if os.Getenv("CI") == "1" {
+		dirs = filepath.SplitList(os.Getenv("PATH"))
+	}
+	for _, dir := range dirs {
+		if !filepath.IsAbs(dir) {
+			continue
+		}
+		p, err := filepath.EvalSymlinks(filepath.Join(dir, name))
+		if err != nil {
+			continue
+		}
+		if os.Getenv("CI") == "1" {
+			home, herr := filepath.EvalSymlinks(c.Home)
+			rel, rerr := filepath.Rel(home, p)
+			if herr != nil || rerr != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+				continue
+			}
+		}
+		fi, err := os.Stat(p)
+		if err == nil && fi.Mode().IsRegular() && fi.Mode().Perm()&0111 != 0 {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("no permitted %s executable (CI=1 requires a fake beneath HOME)", name)
+}
+
+func (i Installer) command(ctx context.Context, manager string, args ...string) error {
+	fmt.Fprintf(i.writer(), "%s %s\n", manager, strings.Join(args, " "))
+	if i.Config.DryRun {
+		return nil
+	}
+	if i.Run == nil {
+		return fmt.Errorf("no service manager runner")
+	}
+	return i.Run(ctx, append([]string{manager}, args...)...)
+}
+
+func (i Installer) activate(ctx context.Context, manager string, names []string) error {
+	c := i.Config
+	if c.Manager == "systemd" {
+		prefix := []string{}
+		if !c.System {
+			prefix = append(prefix, "--user")
+		}
+		if err := i.command(ctx, manager, append(prefix, "daemon-reload")...); err != nil {
+			return err
+		}
+		for _, n := range names {
+			if n == "nself-ci-selftest.service" {
+				continue
+			}
+			if err := i.command(ctx, manager, append(prefix, "enable", "--now", n)...); err != nil {
+				return err
+			}
+			if err := i.command(ctx, manager, append(prefix, "restart", n)...); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	for _, n := range names {
+		// A newly installed or changed job may already be loaded. Probe first;
+		// only boot it out when launchd confirms it exists.
+		label := strings.TrimSuffix(n, ".plist")
+		if !c.DryRun && i.Run(ctx, manager, "print", c.domain()+"/"+label) == nil {
+			if err := i.command(ctx, manager, "bootout", c.domain()+"/"+label); err != nil {
+				return err
+			}
+		}
+		if err := i.command(ctx, manager, "bootstrap", c.domain(), filepath.Join(c.dir(), n)); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (c Config) domain() string {
+	if c.System {
+		return "system"
+	}
+	return "gui/" + strconv.Itoa(c.UID)
+}
+
+func (i Installer) deactivate(ctx context.Context, manager, name string) error {
+	c := i.Config
+	if c.Manager == "launchd" {
+		job := c.domain() + "/" + strings.TrimSuffix(name, ".plist")
+		if !c.DryRun && i.Run(ctx, manager, "print", job) != nil {
+			return nil
+		}
+		return i.command(ctx, manager, "bootout", job)
+	}
+	args := []string{}
+	if !c.System {
+		args = append(args, "--user")
+	}
+	return i.command(ctx, manager, append(args, "disable", "--now", name)...)
+}
diff --git a/free/ci/internal/svc/render.go b/free/ci/internal/svc/render.go
new file mode 100644
index 000000000..2b4a1d7ed
--- /dev/null
+++ b/free/ci/internal/svc/render.go
@@ -0,0 +1,122 @@
+package svc
+
+import (
+	"bytes"
+	"encoding/xml"
+	"fmt"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// Files renders fixed service names to deterministic bytes, without side effects.
+func Files(c Config) (map[string][]byte, error) {
+	if err := c.validate(); err != nil {
+		return nil, err
+	}
+	path, err := GatePath(c.CIHome)
+	if err != nil {
+		return nil, err
+	}
+	names := c.names()
+	files := map[string][]byte{}
+	if c.Manager == "launchd" {
+		files[names[0]] = []byte(plist(c, path, false))
+		files[names[1]] = []byte(plist(c, path, true))
+	} else {
+		files[names[0]] = []byte(unit(c, path, false))
+		files[names[1]] = []byte(unit(c, path, true))
+		files[names[2]] = []byte("[Unit]\nDescription=nSelf CI hourly selftest\n\n[Timer]\nOnCalendar=hourly\nPersistent=true\nUnit=nself-ci-selftest.service\n\n[Install]\nWantedBy=timers.target\n")
+	}
+	return files, nil
+}
+
+func arguments(selftest bool) []string {
+	if selftest {
+		return []string{"ci", "doctor", "--selftest", "--alert"}
+	}
+	return []string{"ci", "serve", "watch"}
+}
+
+func escapeXML(s string) string {
+	var b bytes.Buffer
+	_ = xml.EscapeText(&b, []byte(s))
+	return b.String()
+}
+
+func plist(c Config, path string, selftest bool) string {
+	label := "org.nself.ci-watch"
+	if selftest {
+		label = "org.nself.ci-selftest"
+	}
+	var b strings.Builder
+	b.WriteString("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\"><dict>\n")
+	entry := func(k, v string) { fmt.Fprintf(&b, "<key>%s</key><string>%s</string>\n", k, escapeXML(v)) }
+	entry("Label", label)
+	if c.System {
+		entry("UserName", "nself-ci-watch")
+		entry("GroupName", "nself-ci-watch")
+	}
+	b.WriteString("<key>ProgramArguments</key><array>\n")
+	for _, a := range append([]string{c.Binary}, arguments(selftest)...) {
+		fmt.Fprintf(&b, "<string>%s</string>\n", escapeXML(a))
+	}
+	b.WriteString("</array>\n<key>EnvironmentVariables</key><dict>\n")
+	entry("PATH", path)
+	entry("HOME", c.Home)
+	entry("NSELF_CI_HOME", c.CIHome)
+	entry("NSELF_CI_REPO", c.Repo)
+	entry("NSELF_V15", "1")
+	b.WriteString("</dict>\n")
+	entry("WorkingDirectory", c.Repo)
+	if selftest {
+		b.WriteString("<key>StartInterval</key><integer>3600</integer>\n")
+	} else {
+		b.WriteString("<key>RunAtLoad</key><true/>\n<key>KeepAlive</key><true/>\n<key>ThrottleInterval</key><integer>10</integer>\n")
+		entry("StandardOutPath", filepath.Join(c.CIHome, "logs", "watch", "watch.log"))
+		entry("StandardErrorPath", filepath.Join(c.CIHome, "logs", "watch", "watch.log"))
+	}
+	b.WriteString("</dict></plist>\n")
+	return b.String()
+}
+
+// systemd performs specifier and command dollar expansion even inside quotes.
+func systemdQuote(s string) string {
+	return strconv.Quote(strings.ReplaceAll(s, "%", "%%"))
+}
+
+// systemdPath escapes a path for a path-valued setting (WorkingDirectory=, EnvironmentFile=).
+// These settings take the value literally and accept no quotes; specifiers still expand.
+func systemdPath(s string) string {
+	return strings.ReplaceAll(s, "%", "%%")
+}
+
+func unit(c Config, path string, selftest bool) string {
+	kind, desc := "simple", "watcher"
+	if selftest {
+		kind, desc = "oneshot", "selftest"
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "[Unit]\nDescription=nSelf CI %s\nAfter=network-online.target\n\n[Service]\nType=%s\n", desc, kind)
+	if c.System {
+		b.WriteString("User=nself-ci-watch\nGroup=nself-ci-watch\n")
+	}
+	fmt.Fprintf(&b, "WorkingDirectory=%s\n", systemdPath(c.Repo))
+	for _, e := range []string{"PATH=" + path, "HOME=" + c.Home, "NSELF_CI_HOME=" + c.CIHome, "NSELF_CI_REPO=" + c.Repo, "NSELF_V15=1"} {
+		fmt.Fprintf(&b, "Environment=%s\n", systemdQuote(e))
+	}
+	if c.EnvFile != "" {
+		fmt.Fprintf(&b, "EnvironmentFile=%s\n", systemdPath(c.EnvFile))
+	}
+	fmt.Fprintf(&b, "ExecStart=%s %s\n", systemdQuote(strings.ReplaceAll(c.Binary, "$", "$$")), strings.Join(arguments(selftest), " "))
+	b.WriteString("StandardOutput=journal\nStandardError=journal\nUMask=0077\n")
+	if !selftest {
+		b.WriteString("Restart=on-failure\nRestartSec=10\n\n[Install]\n")
+		target := "default.target"
+		if c.System {
+			target = "multi-user.target"
+		}
+		fmt.Fprintf(&b, "WantedBy=%s\n", target)
+	}
+	return b.String()
+}
diff --git a/free/ci/internal/svc/render_test.go b/free/ci/internal/svc/render_test.go
new file mode 100644
index 000000000..c08903362
--- /dev/null
+++ b/free/ci/internal/svc/render_test.go
@@ -0,0 +1,194 @@
+package svc
+
+import (
+	"bytes"
+	"context"
+	"encoding/xml"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/toolchain"
+)
+
+func TestUnitGoldens(t *testing.T) {
+	for _, manager := range []string{"launchd", "systemd"} {
+		t.Run(manager, func(t *testing.T) {
+			i, _, _ := testInstaller(t, manager)
+			i.Config.Binary = "/usr/bin/true"
+			files, err := Files(i.Config)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(files) != len(i.Config.names()) {
+				t.Fatal("missing unit")
+			}
+			for n, b := range files {
+				if manager == "launchd" {
+					checkPlist(t, b, strings.Contains(n, "selftest"))
+				}
+				if err := os.WriteFile(filepath.Join(i.Config.Home, n), b, 0644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if manager == "launchd" {
+				if p, err := exec.LookPath("/usr/bin/plutil"); err == nil {
+					for n := range files {
+						if out, err := exec.Command(p, "-lint", "--", filepath.Join(i.Config.Home, n)).CombinedOutput(); err != nil {
+							t.Fatalf("plutil: %s: %v", out, err)
+						}
+					}
+				}
+				return
+			}
+			watch := string(files["nself-ci-watch.service"])
+			for _, want := range []string{"Type=simple\n", "ExecStart=\"/usr/bin/true\" ci serve watch\n", "Restart=on-failure\nRestartSec=10\n", "StandardOutput=journal\nStandardError=journal\n", "WantedBy=default.target\n"} {
+				if !strings.Contains(watch, want) {
+					t.Errorf("watch unit missing %q: %s", want, watch)
+				}
+			}
+			// path-valued settings take the path literally: systemd refuses a quoted WorkingDirectory=
+			if want := "WorkingDirectory=" + strings.ReplaceAll(i.Config.Repo, "%", "%%") + "\n"; !strings.Contains(watch, want) {
+				t.Errorf("watch unit missing %q: %s", want, watch)
+			}
+			self := string(files["nself-ci-selftest.service"])
+			if !strings.Contains(self, "Type=oneshot\n") || !strings.Contains(self, "ci doctor --selftest --alert\n") || strings.Contains(self, "Restart=") {
+				t.Fatal(self)
+			}
+			const timer = "[Unit]\nDescription=nSelf CI hourly selftest\n\n[Timer]\nOnCalendar=hourly\nPersistent=true\nUnit=nself-ci-selftest.service\n\n[Install]\nWantedBy=timers.target\n"
+			if string(files["nself-ci-selftest.timer"]) != timer {
+				t.Fatal("timer golden differs")
+			}
+			if p, err := exec.LookPath("/usr/bin/systemd-analyze"); err == nil {
+				args := []string{"verify"}
+				for _, n := range i.Config.names() {
+					args = append(args, filepath.Join(i.Config.Home, n))
+				}
+				if out, err := exec.Command(p, args...).CombinedOutput(); err != nil {
+					t.Fatalf("systemd-analyze: %s: %v", out, err)
+				}
+			}
+		})
+	}
+}
+
+func checkPlist(t *testing.T, b []byte, selftest bool) {
+	t.Helper()
+	d := xml.NewDecoder(bytes.NewReader(b))
+	keys := map[string]bool{}
+	for {
+		tok, err := d.Token()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		if start, ok := tok.(xml.StartElement); ok && start.Name.Local == "key" {
+			var key string
+			if err := d.DecodeElement(&key, &start); err != nil {
+				t.Fatal(err)
+			}
+			keys[key] = true
+		}
+	}
+	for _, k := range []string{"Label", "ProgramArguments", "EnvironmentVariables", "PATH", "WorkingDirectory", "NSELF_CI_HOME", "NSELF_V15"} {
+		if !keys[k] {
+			t.Error("missing", k)
+		}
+	}
+	if selftest {
+		if !keys["StartInterval"] || keys["KeepAlive"] || !bytes.Contains(b, []byte("<integer>3600</integer>")) {
+			t.Fatal("bad hourly plist")
+		}
+		for _, a := range []string{"doctor", "--selftest", "--alert"} {
+			if !bytes.Contains(b, []byte("<string>"+a+"</string>")) {
+				t.Fatal("missing", a)
+			}
+		}
+	} else {
+		for _, k := range []string{"RunAtLoad", "KeepAlive", "ThrottleInterval", "StandardOutPath", "StandardErrorPath"} {
+			if !keys[k] {
+				t.Error("missing", k)
+			}
+		}
+		if !bytes.Contains(b, []byte("/logs/watch/watch.log</string>")) {
+			t.Fatal("wrong watcher log")
+		}
+	}
+}
+
+func TestPathIndependentOfServiceEnv(t *testing.T) {
+	i, _, _ := testInstaller(t, "systemd")
+	v, err := toolchain.Embedded()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Put a manifest tool only in its private pinned install directory.
+	row, ok := v.Row("go")
+	if !ok {
+		t.Fatal("manifest has no go")
+	}
+	dir := filepath.Join(i.Config.CIHome, "tools", row.Name+"-"+row.Version, "bin")
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "go"), []byte("#!/bin/sh\nprintf manifest-tool"), 0700); err != nil {
+		t.Fatal(err)
+	}
+	before, err := Files(i.Config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", "/hostile/nonexistent")
+	after, err := Files(i.Config)
+	if err != nil || !bytes.Equal(before["nself-ci-watch.service"], after["nself-ci-watch.service"]) {
+		t.Fatal("service environment influenced unit", err)
+	}
+	path, err := GatePath(i.Config.CIHome)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(after["nself-ci-watch.service"]), "PATH="+path) {
+		t.Fatal("unit PATH differs")
+	}
+	cmd := exec.CommandContext(context.Background(), "/bin/sh", "-c", "go")
+	cmd.Env = []string{"PATH=" + path}
+	if out, err := cmd.CombinedOutput(); err != nil || string(out) != "manifest-tool" {
+		t.Fatalf("gate tool failed with hostile inherited PATH: %q %v", out, err)
+	}
+}
+
+func TestEscapingAndSystemIsolation(t *testing.T) {
+	i, _, _ := testInstaller(t, "launchd")
+	i.Config.Repo = filepath.Join(i.Config.Home, "a & b < c")
+	files, err := Files(i.Config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	checkPlist(t, files["org.nself.ci-watch.plist"], false)
+	if !bytes.Contains(files["org.nself.ci-watch.plist"], []byte("a &amp; b &lt; c")) {
+		t.Fatal("XML not escaped")
+	}
+	for _, manager := range []string{"launchd", "systemd"} {
+		c := i.Config
+		c.Manager, c.System, c.DryRun = manager, true, true
+		c.Home, c.CIHome = SystemHome(manager), SystemHome(manager)
+		files, err := Files(c)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, b := range files {
+			if bytes.Contains(b, []byte("nself-ci-job")) {
+				t.Fatal("reused job user")
+			}
+		}
+		c.DryRun = false
+		if _, err := Files(c); err == nil {
+			t.Fatal("system mutation allowed in CI")
+		}
+	}
+}
diff --git a/free/ci/internal/svc/system.go b/free/ci/internal/svc/system.go
new file mode 100644
index 000000000..41f5f82fc
--- /dev/null
+++ b/free/ci/internal/svc/system.go
@@ -0,0 +1,116 @@
+package svc
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// SystemHome is private watcher state, separate from agent and job accounts.
+func SystemHome(manager string) string {
+	if manager == "launchd" {
+		return "/var/db/nself-ci-watch"
+	}
+	return "/var/lib/nself-ci-watch"
+}
+
+func (c Config) systemGuard() error {
+	if !c.System {
+		return nil
+	}
+	if c.Home != SystemHome(c.Manager) || c.CIHome != c.Home {
+		return fmt.Errorf("system watcher requires its dedicated home %s", SystemHome(c.Manager))
+	}
+	if c.DryRun {
+		return nil
+	}
+	if os.Getenv("CI") == "1" {
+		return fmt.Errorf("system service mutation is disabled under CI=1")
+	}
+	if os.Geteuid() != 0 {
+		return fmt.Errorf("--system requires sudo; rerun with sudo and explicit --binary and --repo")
+	}
+	agent := "/etc/systemd/system/nself-ci-agent.service"
+	if c.Manager == "launchd" {
+		agent = "/Library/LaunchDaemons/org.nself.ci-agent.plist"
+	}
+	if fi, err := os.Lstat(agent); err != nil || !fi.Mode().IsRegular() {
+		return fmt.Errorf("--system requires an installed node agent")
+	}
+	return nil
+}
+
+func (i Installer) prepareSystem(ctx context.Context) error {
+	c := i.Config
+	if err := c.systemGuard(); err != nil {
+		return err
+	}
+	if !c.System {
+		return nil
+	}
+	// Constant scripts follow NODE-06/NODE-31: a locked role account, no home
+	// inherited from sudo, no job-user group, and no sudoers changes.
+	script := linuxAccount
+	if c.Manager == "launchd" {
+		script = darwinAccount
+	}
+	if c.DryRun {
+		fmt.Fprintf(i.writer(), "/bin/sh -c %q\n", script)
+		return nil
+	}
+	if err := i.Run(ctx, "/bin/sh", "-c", script); err != nil {
+		return err
+	}
+	for _, path := range []string{c.Home, filepath.Join(c.Home, "logs"), filepath.Join(c.Home, "logs", "watch")} {
+		fi, err := os.Lstat(path)
+		if err != nil || !fi.IsDir() || fi.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("invalid system watcher directory %s", path)
+		}
+	}
+	return nil
+}
+
+const linuxAccount = `set -eu
+PATH=/usr/bin:/bin:/usr/sbin:/sbin
+export PATH
+u=nself-ci-watch
+id -u "$u" >/dev/null 2>&1 || useradd --system --user-group --no-create-home --home-dir /var/lib/nself-ci-watch --shell /bin/false "$u"
+uid=$(id -u "$u")
+[ "$uid" != 0 ] && [ "$uid" != "$(id -u nself-ci)" ]
+for job in $(getent passwd | cut -d: -f1 | grep '^nself-ci-job-' || true); do [ "$uid" != "$(id -u "$job")" ]; done
+if id -nG "$u" | grep -qwE 'docker|sudo|wheel|adm|nself-ci|nself-ci-job-[0-9]+'; then exit 1; fi
+[ ! -L /var/lib/nself-ci-watch ] || exit 1
+install -d -o "$u" -g "$u" -m 0700 /var/lib/nself-ci-watch
+# Descendants of the role's home are created without root privileges.
+sudo -n -u "$u" /bin/mkdir -p /var/lib/nself-ci-watch/logs/watch
+`
+
+const darwinAccount = `set -eu
+PATH=/usr/bin:/bin:/usr/sbin:/sbin
+export PATH
+u=nself-ci-watch
+if ! dscl . -read /Users/$u IsHidden >/dev/null 2>&1; then
+  used=$({ dscl . -list /Users UniqueID; dscl . -list /Groups PrimaryGroupID; } | awk '{print $NF}')
+  i=450
+  while echo "$used" | grep -qx "$i"; do i=$((i + 1)); done
+  [ "$i" -le 499 ]
+  dscl . -create /Groups/$u
+  dscl . -create /Groups/$u PrimaryGroupID "$i"
+  dscl . -create /Users/$u
+  dscl . -create /Users/$u UniqueID "$i"
+  dscl . -create /Users/$u PrimaryGroupID "$i"
+  dscl . -create /Users/$u UserShell /usr/bin/false
+  dscl . -create /Users/$u NFSHomeDirectory /var/db/nself-ci-watch
+  dscl . -create /Users/$u Password '*'
+  dscl . -create /Users/$u IsHidden 1
+fi
+uid=$(id -u "$u")
+[ "$uid" != 0 ] && [ "$uid" != "$(id -u nself-ci)" ]
+for job in $(dscl . -list /Users | grep '^nself-ci-job-' || true); do [ "$uid" != "$(id -u "$job")" ]; done
+if id -Gn "$u" | grep -qwE 'admin|wheel|nself-ci|nself-ci-job-[0-9]+'; then exit 1; fi
+[ ! -L /var/db/nself-ci-watch ] || exit 1
+install -d -o "$u" -g "$u" -m 0700 /var/db/nself-ci-watch
+# Descendants of the role's home are created without root privileges.
+sudo -n -u "$u" /bin/mkdir -p /var/db/nself-ci-watch/logs/watch
+`
diff --git a/free/ci/internal/tiers/bias.go b/free/ci/internal/tiers/bias.go
new file mode 100644
index 000000000..84dff9462
--- /dev/null
+++ b/free/ci/internal/tiers/bias.go
@@ -0,0 +1,111 @@
+package tiers
+
+// Purpose: the data side of the `auto` preset: the effective tier order, the
+// rank of a runner inside its tier and World.Bias.
+// Inputs:  a sched.World (Policy.Preset, Policy.Trust, Runners, Hosted).
+// Outputs: Order, Rank, Bias and the world contributor.
+// Constraints: pure and deterministic (no clock, no map order in any output);
+// a rank is clamped below sched.TierStepMs so it never crosses into the next
+// tier; the effective list keeps the order it was written in, and a lower scope
+// can only drop entries (TightenSubset); a tier the order leaves out is tried
+// after every listed tier (the order is a preference: keeping a tier out is the
+// overrides' job, local_only, lan_only, private_only, providers.deny); not
+// `auto` means no output at all.
+
+import (
+	"context"
+	"slices"
+	"strconv"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// RankLabel is the label prefix `ci nodes sync` and `ci nodes label` write.
+const RankLabel = "rank="
+
+// Order returns the effective tier order of eff, best first: the merged
+// sched.auto.order without unknown or repeated entries, or DefaultOrder when the
+// key is absent.
+func Order(eff trust.Effective) []string {
+	v, _, ok := eff.Value(KeyOrder)
+	if !ok {
+		return DefaultOrder()
+	}
+	var raw []string
+	switch xs := v.(type) {
+	case []string:
+		raw = xs
+	case []any:
+		for _, x := range xs {
+			if s, ok := x.(string); ok {
+				raw = append(raw, s)
+			}
+		}
+	}
+	out := []string{}
+	for _, s := range raw {
+		if slices.Contains(DefaultOrder(), s) && !slices.Contains(out, s) {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// Rank returns the runner's rank inside its tier: its `rank=<n>` label when it
+// has one, else position, its index in the registry list it came from.
+func Rank(r sched.Runner, position int) int64 {
+	n := int64(position)
+	for _, l := range r.Capability.Identity.Labels {
+		if v, ok := strings.CutPrefix(l, RankLabel); ok {
+			if i, err := strconv.ParseInt(v, 10, 64); err == nil && i >= 0 {
+				n = i
+				break
+			}
+		}
+	}
+	if n < 0 {
+		n = 0
+	}
+	if n >= sched.TierStepMs {
+		n = sched.TierStepMs - 1
+	}
+	return n
+}
+
+// ranked calls fn for every runner of w with its tier and rank.
+func ranked(w sched.World, fn func(r sched.Runner, tier string, rank int64)) {
+	for i, r := range w.Runners {
+		fn(r, sched.TierOf(w, r), Rank(r, i))
+	}
+	for i, r := range w.Hosted {
+		fn(r, sched.TierOf(w, r), Rank(r, i))
+	}
+}
+
+// Bias returns tier index x sched.TierStepMs + rank per runner id; a runner
+// whose tier is not in order takes the index len(order), after every listed
+// tier. A runner in the best tier with rank 0 gets 0, which the scorer does not show.
+func Bias(w sched.World, order []string) map[string]int64 {
+	out := map[string]int64{}
+	ranked(w, func(r sched.Runner, tier string, rank int64) {
+		i := slices.Index(order, tier)
+		if i < 0 {
+			i = len(order)
+		}
+		b, _ := sched.Mul(int64(i), sched.TierStepMs)
+		out[r.ID], _ = sched.Add(b, rank)
+	})
+	return out
+}
+
+func contribute(_ context.Context, w *sched.World) error {
+	if w.Policy.Preset != sched.AutoPreset {
+		return nil
+	}
+	if b := Bias(*w, Order(w.Policy.Trust)); len(b) > 0 {
+		w.Bias = b
+	}
+	return nil
+}
diff --git a/free/ci/internal/tiers/plan_test.go b/free/ci/internal/tiers/plan_test.go
new file mode 100644
index 000000000..d8e2b605a
--- /dev/null
+++ b/free/ci/internal/tiers/plan_test.go
@@ -0,0 +1,141 @@
+package tiers
+
+// Purpose: the `auto` plan of a hosted + vps + lan + local world (tier, bias and
+// the wait in the placement-plan document and the explain lines, kept as a
+// golden) and the proof that every other preset's placement is unchanged by
+// this package.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/planview"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+var update = flag.Bool("update", false, "rewrite the auto goldens")
+
+func runner(id, loc, class string) sched.Runner {
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Lifecycle.AuthorizedProjects = []string{"project"}
+	c.Lifecycle.Eligible = true
+	c.Protocol.Versions, c.Protocol.Min = []int{1}, 1
+	c.Platform.OS.Value, c.Platform.Arch.Value = ptr("linux"), ptr("amd64")
+	c.Resources.CPU.Value, c.Resources.MemMB.Value = ptr(float64(8)), ptr(int64(8192))
+	c.Location.Kind.Value = ptr(loc)
+	return sched.Runner{ID: id, Location: loc, Class: class, Provider: "operator", Avail: sched.Avail{Slots: 1, CPU: 8, MemMB: 8192}, Capability: c,
+		Decl: trust.Declaration{Accepts: []model.TrustClass{"owner", "internal", "collaborator", "untrusted"}, Isolation: "vm", Network: "privileged", UIDSeparation: true, Ownership: "operator", PersonalOwnNode: loc == "local", NoLANRoute: true}}
+}
+
+func job(key string, queuedMs int64) sched.Job {
+	return sched.Job{Key: key, ID: key, Project: "project", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan", TimeoutMs: 60000, PersonalOwnRun: true, QueuedMs: queuedMs}
+}
+
+// fourTiers is a hosted (not admitted: paid is off), a busy vps, a lan and a local runner.
+func fourTiers(t *testing.T, preset string) sched.World {
+	t.Helper()
+	eff, _, err := registry(t).Merge("")
+	if err != nil {
+		t.Fatal(err)
+	}
+	vps := runner("v-vps", "remote", "owned")
+	vps.Avail.Slots = 0
+	return sched.World{Policy: sched.Policy{Preset: preset, Trust: eff}, Costs: map[string]sched.Cost{}, Previous: map[string]string{},
+		Runners: []sched.Runner{runner("l-lan", "lan", "owned"), vps, runner("x-local", "local", "local")},
+		Hosted:  []sched.Runner{runner("h-hosted", "hosted", "metered")}}
+}
+
+func doc(w sched.World, jobs []sched.Job) model.PlacementPlan {
+	return planview.Build(planview.Input{Name: "default", Revision: strings.Repeat("a", 40), Trigger: "local", PolicyDigest: "p" + strings.Repeat("0", 63),
+		WorldDigest: "w" + strings.Repeat("0", 63), World: w, Jobs: jobs, Result: sched.Place(w, jobs)})
+}
+
+func golden(t *testing.T, name string, got []byte) {
+	t.Helper()
+	path := "testdata/" + name
+	if *update {
+		if err := os.WriteFile(path, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	want, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(got, want) {
+		t.Fatalf("%s differs (go test -run %s -update):\n%s", path, t.Name(), got)
+	}
+}
+
+func TestAutoPlanShowsTierAndWait(t *testing.T) {
+	w := fourTiers(t, sched.AutoPreset)
+	if err := contribute(context.Background(), &w); err != nil {
+		t.Fatal(err)
+	}
+	jobs := []sched.Job{job("fresh", 0), job("older", 20000), job("stale", 30000)}
+	p := doc(w, jobs)
+	raw, _ := json.MarshalIndent(p, "", "  ")
+	schema, err := os.ReadFile("../../schemas/placement-plan.v1.schema.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = model.ValidateJSON(schema, raw); err != nil {
+		t.Fatalf("the auto plan must be valid placement-plan v1: %v", err)
+	}
+	st := map[string]string{}
+	for _, j := range p.Jobs {
+		st[j.ID] = j.Status
+	}
+	if st["fresh"] != "waiting" || st["older"] != "waiting" || st["stale"] != "placed" || p.Jobs[2].Placement.RunnerID != "l-lan" {
+		t.Fatalf("statuses %v", st)
+	}
+	text := string(raw)
+	for _, want := range []string{`"preset": "auto"`, `"tier_rank"`, "held for v-vps (tier vps, bias 60001, capacity.busy): 30000 ms left", ": 10000 ms left"} {
+		if !strings.Contains(text, want) {
+			t.Errorf("plan json lacks %q", want)
+		}
+	}
+	lines := strings.Join(planview.ExplainLines(p, planview.SourcePlan), "\n")
+	cells := strings.Join(planview.Cells(p), "\n")
+	for _, want := range []string{"tier lan  bias 120000", "reason  tier.waiting  held for v-vps", "tier_rank=120000"} {
+		if !strings.Contains(lines, want) {
+			t.Errorf("explain lacks %q:\n%s", want, lines)
+		}
+	}
+	if !strings.Contains(cells, "waiting: tier.waiting (held for v-vps") {
+		t.Errorf("plan cells lack the wait:\n%s", cells)
+	}
+	golden(t, "auto-plan.golden.json", append(raw, '\n'))
+	golden(t, "auto-explain.golden.txt", []byte(lines+"\n"+cells+"\n"))
+}
+
+func TestAutoOtherPresetsGolden(t *testing.T) {
+	jobs := []sched.Job{job("fresh", 0), job("older", 20000), job("stale", 30000)}
+	for preset := range sched.Presets() {
+		if preset == sched.AutoPreset {
+			continue
+		}
+		plain := fourTiers(t, preset)
+		contributed := fourTiers(t, preset)
+		if err := contribute(context.Background(), &contributed); err != nil || contributed.Bias != nil {
+			t.Fatalf("%s: the tiers contributor must leave the world alone: %v %v", preset, contributed.Bias, err)
+		}
+		a, _ := json.Marshal(doc(plain, jobs))
+		b, _ := json.Marshal(doc(contributed, jobs))
+		if !bytes.Equal(a, b) || bytes.Contains(a, []byte("tier_rank")) || bytes.Contains(a, []byte("tier.waiting")) {
+			t.Fatalf("%s: placement changed by the auto preset:\n%s\n%s", preset, a, b)
+		}
+		lines := strings.Join(planview.ExplainLines(doc(plain, jobs), planview.SourcePlan), "\n")
+		if strings.Contains(lines, "  tier ") {
+			t.Fatalf("%s: explain shows tier outside auto:\n%s", preset, lines)
+		}
+	}
+}
diff --git a/free/ci/internal/tiers/testdata/auto-explain.golden.txt b/free/ci/internal/tiers/testdata/auto-explain.golden.txt
new file mode 100644
index 000000000..f54a2dc4c
--- /dev/null
+++ b/free/ci/internal/tiers/testdata/auto-explain.golden.txt
@@ -0,0 +1,30 @@
+job fresh  waiting  band normal  source plan
+  needs  platform linux/amd64  cpu 1  mem_mb 128  isolation_min none  network none  secret classes none  tools none
+  reason  tier.waiting  held for v-vps (tier vps, bias 60001, capacity.busy): 30000 ms left of step_sec 30 s, then l-lan (tier lan)
+  alt     h-hosted  ineligible  privacy.hosted_not_authorized,cost.unknown_rate,paid.disabled,budget.unset,budget.exceeded
+  alt     l-lan  eligible  score 157500
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=2000(estimated) transfer=4000(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=120000(estimated)
+  alt     v-vps  ineligible  capacity.busy
+  alt     x-local  eligible  score 211502
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=0(estimated) transfer=0(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=180002(estimated)
+job older  waiting  band normal  source plan
+  needs  platform linux/amd64  cpu 1  mem_mb 128  isolation_min none  network none  secret classes none  tools none
+  reason  tier.waiting  held for v-vps (tier vps, bias 60001, capacity.busy): 10000 ms left of step_sec 30 s, then l-lan (tier lan)
+  alt     h-hosted  ineligible  privacy.hosted_not_authorized,cost.unknown_rate,paid.disabled,budget.unset,budget.exceeded
+  alt     l-lan  eligible  score 157500
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=2000(estimated) transfer=4000(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=120000(estimated)
+  alt     v-vps  ineligible  capacity.busy
+  alt     x-local  eligible  score 211502
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=0(estimated) transfer=0(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=180002(estimated)
+job stale  placed  band normal  source plan
+  needs  platform linux/amd64  cpu 1  mem_mb 128  isolation_min none  network none  secret classes none  tools none
+  chosen  l-lan  provider operator  lan  owned  score 157500  cost 0 micro [known]  tier lan  bias 120000
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=2000(estimated) transfer=4000(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=120000(estimated)
+  alt     h-hosted  ineligible  privacy.hosted_not_authorized,cost.unknown_rate,paid.disabled,budget.unset,budget.exceeded
+  alt     l-lan  chosen
+  alt     v-vps  ineligible  capacity.busy
+  alt     x-local  eligible  score 211502
+    wait=0(estimated) runtime=unknown(stand-in 30000) cold_start=0(estimated) transfer=0(estimated) cache=unknown(stand-in 0) contention=0(estimated) cost=0(estimated) scarcity=0(estimated) reliability=1500(estimated) tier_rank=180002(estimated)
+waiting: tier.waiting (held for v-vps (tier vps, bias 60001, capacity.busy): 30000 ms left of step_sec 30 s, then l-lan (tier lan))
+waiting: tier.waiting (held for v-vps (tier vps, bias 60001, capacity.busy): 10000 ms left of step_sec 30 s, then l-lan (tier lan))
+l-lan (lan, owned) cost 0 micro [known]
diff --git a/free/ci/internal/tiers/testdata/auto-plan.golden.json b/free/ci/internal/tiers/testdata/auto-plan.golden.json
new file mode 100644
index 000000000..cd186e80b
--- /dev/null
+++ b/free/ci/internal/tiers/testdata/auto-plan.golden.json
@@ -0,0 +1,649 @@
+{
+  "schema": "ci.placement-plan/v1",
+  "pipeline": {
+    "id": null,
+    "name": "default",
+    "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "trigger": "local",
+    "policy_digest": "p000000000000000000000000000000000000000000000000000000000000000",
+    "preset": "auto",
+    "world_digest": "w000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "fast_path": {
+    "taken": false,
+    "reason": "none"
+  },
+  "jobs": [
+    {
+      "id": "fresh",
+      "name": "",
+      "matrix_key": "",
+      "deps": [],
+      "band": "normal",
+      "requirements": {
+        "platform": "linux/amd64",
+        "isolation_min": "",
+        "network": "",
+        "labels": [],
+        "cpu": 1,
+        "mem_mb": 128,
+        "tools": []
+      },
+      "secret_classes": [],
+      "status": "waiting",
+      "reasons": [
+        {
+          "code": "tier.waiting",
+          "detail": "held for v-vps (tier vps, bias 60001, capacity.busy): 30000 ms left of step_sec 30 s, then l-lan (tier lan)"
+        }
+      ],
+      "placement": null,
+      "alternatives": [
+        {
+          "runner_id": "h-hosted",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "privacy.hosted_not_authorized",
+              "detail": "privacy.hosted_not_authorized"
+            },
+            {
+              "code": "cost.unknown_rate",
+              "detail": "missing or nonpositive rate"
+            },
+            {
+              "code": "paid.disabled",
+              "detail": "operator policy"
+            },
+            {
+              "code": "budget.unset",
+              "detail": "day, month or provider budget required"
+            },
+            {
+              "code": "budget.exceeded",
+              "detail": "saturated cost"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "l-lan",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 157500,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 2000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 120000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 4000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        },
+        {
+          "runner_id": "v-vps",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "capacity.busy",
+              "detail": "availability"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "x-local",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 211502,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 180002,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        }
+      ],
+      "expected_wait_ms": null
+    },
+    {
+      "id": "older",
+      "name": "",
+      "matrix_key": "",
+      "deps": [],
+      "band": "normal",
+      "requirements": {
+        "platform": "linux/amd64",
+        "isolation_min": "",
+        "network": "",
+        "labels": [],
+        "cpu": 1,
+        "mem_mb": 128,
+        "tools": []
+      },
+      "secret_classes": [],
+      "status": "waiting",
+      "reasons": [
+        {
+          "code": "tier.waiting",
+          "detail": "held for v-vps (tier vps, bias 60001, capacity.busy): 10000 ms left of step_sec 30 s, then l-lan (tier lan)"
+        }
+      ],
+      "placement": null,
+      "alternatives": [
+        {
+          "runner_id": "h-hosted",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "privacy.hosted_not_authorized",
+              "detail": "privacy.hosted_not_authorized"
+            },
+            {
+              "code": "cost.unknown_rate",
+              "detail": "missing or nonpositive rate"
+            },
+            {
+              "code": "paid.disabled",
+              "detail": "operator policy"
+            },
+            {
+              "code": "budget.unset",
+              "detail": "day, month or provider budget required"
+            },
+            {
+              "code": "budget.exceeded",
+              "detail": "saturated cost"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "l-lan",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 157500,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 2000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 120000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 4000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        },
+        {
+          "runner_id": "v-vps",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "capacity.busy",
+              "detail": "availability"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "x-local",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 211502,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 180002,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        }
+      ],
+      "expected_wait_ms": null
+    },
+    {
+      "id": "stale",
+      "name": "",
+      "matrix_key": "",
+      "deps": [],
+      "band": "normal",
+      "requirements": {
+        "platform": "linux/amd64",
+        "isolation_min": "",
+        "network": "",
+        "labels": [],
+        "cpu": 1,
+        "mem_mb": 128,
+        "tools": []
+      },
+      "secret_classes": [],
+      "status": "placed",
+      "reasons": [],
+      "placement": {
+        "runner_id": "l-lan",
+        "provider": "operator",
+        "location": "lan",
+        "cost_class": "owned",
+        "score": 157500,
+        "components": {
+          "cache": {
+            "value_ms": 0,
+            "weight_permille": 1000,
+            "confidence": "unknown"
+          },
+          "cold_start": {
+            "value_ms": 2000,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "contention": {
+            "value_ms": 0,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "cost": {
+            "value_ms": 0,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "reliability": {
+            "value_ms": 1500,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "runtime": {
+            "value_ms": 30000,
+            "weight_permille": 1000,
+            "confidence": "unknown"
+          },
+          "scarcity": {
+            "value_ms": 0,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "tier_rank": {
+            "value_ms": 120000,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "transfer": {
+            "value_ms": 4000,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          },
+          "wait": {
+            "value_ms": 0,
+            "weight_permille": 1000,
+            "confidence": "estimated"
+          }
+        },
+        "estimate": {
+          "wait_ms": 0,
+          "runtime_ms": null,
+          "cost_micro": 0,
+          "cost_confidence": "known"
+        }
+      },
+      "alternatives": [
+        {
+          "runner_id": "h-hosted",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "privacy.hosted_not_authorized",
+              "detail": "privacy.hosted_not_authorized"
+            },
+            {
+              "code": "cost.unknown_rate",
+              "detail": "missing or nonpositive rate"
+            },
+            {
+              "code": "paid.disabled",
+              "detail": "operator policy"
+            },
+            {
+              "code": "budget.unset",
+              "detail": "day, month or provider budget required"
+            },
+            {
+              "code": "budget.exceeded",
+              "detail": "saturated cost"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "l-lan",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 157500,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 2000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 120000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 4000,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        },
+        {
+          "runner_id": "v-vps",
+          "provider": "operator",
+          "eligible": false,
+          "reasons": [
+            {
+              "code": "capacity.busy",
+              "detail": "availability"
+            }
+          ],
+          "score": null,
+          "components": null
+        },
+        {
+          "runner_id": "x-local",
+          "provider": "operator",
+          "eligible": true,
+          "reasons": [],
+          "score": 211502,
+          "components": {
+            "cache": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "cold_start": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "contention": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "cost": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "reliability": {
+              "value_ms": 1500,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "runtime": {
+              "value_ms": 30000,
+              "weight_permille": 1000,
+              "confidence": "unknown"
+            },
+            "scarcity": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "tier_rank": {
+              "value_ms": 180002,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "transfer": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            },
+            "wait": {
+              "value_ms": 0,
+              "weight_permille": 1000,
+              "confidence": "estimated"
+            }
+          }
+        }
+      ],
+      "expected_wait_ms": 0
+    }
+  ],
+  "totals": {
+    "estimated_cost_micro": 0,
+    "cost_confidence": "known",
+    "placed": 1,
+    "waiting": 2,
+    "awaiting_approval": 0,
+    "unplaceable": 0
+  }
+}
diff --git a/free/ci/internal/tiers/tiers.go b/free/ci/internal/tiers/tiers.go
new file mode 100644
index 000000000..ce1cde834
--- /dev/null
+++ b/free/ci/internal/tiers/tiers.go
@@ -0,0 +1,122 @@
+// Package tiers is the tier order of the `auto` placement preset (P7-AUTO-05).
+//
+// Purpose: under `auto` a runner's tier (hosted, vps, lan, local; see
+// sched.TierFor) and its rank inside the tier become a score bias, so a better
+// tier wins when the scores are close while readiness, capacity, trust and
+// cost still overrule the order. This package owns the policy keys
+// sched.auto.order and sched.auto.step_sec and the World.Bias contributor.
+// Inputs:  the World the builder made (Policy.Preset, Policy.Trust, runners).
+// Outputs: World.Bias (tier index x sched.TierStepMs + rank, in ms; the
+// tier_rank score component).
+// Constraints: pure; only the `auto` preset is touched, every other preset's
+// world stays byte-identical; the bias is a score term, never a rank-only
+// shortcut past eligibility or scoring; no spend path: hosted runners are in
+// the world only when their provider emitted them and the eligibility rules
+// (providers.allow, paid and budget checks) still decide.
+package tiers
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"slices"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+// Name is the world contributor name.
+const Name = "tiers"
+
+// Owner is the owner recorded on the keys this package registers.
+const Owner = "sched"
+
+// KeyOrder is the tier order key: a subset of DefaultOrder, best tier first.
+const KeyOrder = "sched.auto.order"
+
+// KeyStepSec is the bounded wait for a busy better tier, in seconds.
+const KeyStepSec = sched.KeyAutoStepSec
+
+// DefaultOrder is the registered default of KeyOrder.
+func DefaultOrder() []string {
+	return []string{sched.TierHosted, sched.TierVPS, sched.TierLAN, sched.TierLocal}
+}
+
+var registrationErrors []error
+
+// RegistrationErrors returns what init() could not register.
+func RegistrationErrors() []error { return slices.Clone(registrationErrors) }
+
+func init() {
+	for _, spec := range Keys() {
+		if err := policy.RegisterKey(spec); err != nil {
+			registrationErrors = append(registrationErrors, err)
+		}
+	}
+	if err := world.Register(world.Contributor{Name: Name, Field: "Bias", Fn: contribute}); err != nil {
+		registrationErrors = append(registrationErrors, err)
+	}
+}
+
+// Keys returns the specs of the two auto keys.
+func Keys() []policy.KeySpec {
+	return []policy.KeySpec{
+		{Key: KeyOrder, Owner: Owner, Kind: policy.TightenSubset, Default: DefaultOrder(), Decode: decodeOrder},
+		{Key: KeyStepSec, Owner: Owner, Kind: policy.TightenLower, Default: sched.DefaultAutoStepSec, Decode: decodeStep},
+	}
+}
+
+func decodeJSON(key string, raw json.RawMessage) (any, error) {
+	d := json.NewDecoder(bytes.NewReader(raw))
+	d.UseNumber()
+	var v any
+	if err := d.Decode(&v); err != nil {
+		return nil, fmt.Errorf("%s: %v", key, err)
+	}
+	if d.More() {
+		return nil, fmt.Errorf("%s: trailing JSON value", key)
+	}
+	return v, nil
+}
+
+// decodeOrder accepts a non-empty list of unique tier names.
+func decodeOrder(raw json.RawMessage) (any, error) {
+	v, err := decodeJSON(KeyOrder, raw)
+	if err != nil {
+		return nil, err
+	}
+	items, ok := v.([]any)
+	if !ok || len(items) == 0 {
+		return nil, fmt.Errorf("%s: expected a non-empty list of tiers %v", KeyOrder, DefaultOrder())
+	}
+	out := make([]string, 0, len(items))
+	for _, item := range items {
+		s, ok := item.(string)
+		if !ok || !slices.Contains(DefaultOrder(), s) {
+			return nil, fmt.Errorf("%s: unknown tier %v (one of %v)", KeyOrder, item, DefaultOrder())
+		}
+		if slices.Contains(out, s) {
+			return nil, fmt.Errorf("%s: duplicate tier %q", KeyOrder, s)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// decodeStep accepts a whole number of seconds, 0 (never wait) or more.
+func decodeStep(raw json.RawMessage) (any, error) {
+	v, err := decodeJSON(KeyStepSec, raw)
+	if err != nil {
+		return nil, err
+	}
+	n, ok := v.(json.Number)
+	if !ok {
+		return nil, fmt.Errorf("%s: expected a whole number of seconds", KeyStepSec)
+	}
+	i, err := n.Int64()
+	if err != nil || i < 0 {
+		return nil, fmt.Errorf("%s: expected a whole number of seconds >= 0, got %s", KeyStepSec, n)
+	}
+	return i, nil
+}
diff --git a/free/ci/internal/tiers/tiers_test.go b/free/ci/internal/tiers/tiers_test.go
new file mode 100644
index 000000000..44b506d00
--- /dev/null
+++ b/free/ci/internal/tiers/tiers_test.go
@@ -0,0 +1,129 @@
+package tiers
+
+// Purpose: the auto keys tighten like every other policy key, decode strictly,
+// and the order, rank and bias are what the brief says (P7-AUTO-05).
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+func ptr[T any](v T) *T { return &v }
+
+func registry(t *testing.T) trust.Registry {
+	t.Helper()
+	reg, err := trust.NewRegistry(Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return reg
+}
+
+func scope(kind trust.Source, kv ...string) trust.Scope {
+	s := trust.Scope{Kind: kind, Values: map[string]json.RawMessage{}}
+	for i := 0; i+1 < len(kv); i += 2 {
+		s.Values[kv[i]] = json.RawMessage(kv[i+1])
+	}
+	return s
+}
+
+func TestKeysRegistered(t *testing.T) {
+	if errs := RegistrationErrors(); len(errs) != 0 {
+		t.Fatal(errs)
+	}
+	for _, k := range []string{KeyOrder, KeyStepSec} {
+		spec, ok := policy.Default.Find(k)
+		if !ok || spec.Owner != Owner || spec.Spend {
+			t.Errorf("%s registered as %+v", k, spec)
+		}
+	}
+	if err := world.Register(world.Contributor{Name: "intruder", Field: "Bias", Fn: func(context.Context, *sched.World) error { return nil }}); err == nil {
+		t.Fatal("World.Bias has one owner: a second contributor must be refused")
+	}
+}
+
+func TestTierOrderTighten(t *testing.T) {
+	reg := registry(t)
+	eff, _, err := reg.Merge("")
+	if err != nil || !reflect.DeepEqual(Order(eff), DefaultOrder()) || sched.AutoStepMs(sched.World{Policy: sched.Policy{Trust: eff}}) != 30000 {
+		t.Fatalf("defaults: %v %v", Order(eff), err)
+	}
+	// the operator reorders and drops; the project narrows further.
+	eff, _, err = reg.Merge("", scope(trust.SourceUser, KeyOrder, `["lan","vps","local"]`), scope(trust.SourceProject, KeyOrder, `["lan","local"]`, KeyStepSec, `10`))
+	if err != nil || !reflect.DeepEqual(Order(eff), []string{"lan", "local"}) || sched.AutoStepMs(sched.World{Policy: sched.Policy{Trust: eff}}) != 10000 {
+		t.Fatalf("narrowed: %v %v", Order(eff), err)
+	}
+	// a lower scope can never add a tier back or raise the wait.
+	for name, scopes := range map[string][]trust.Scope{
+		"project adds a tier": {scope(trust.SourceUser, KeyOrder, `["lan","local"]`), scope(trust.SourceProject, KeyOrder, `["lan","local","hosted"]`)},
+		"project raises step": {scope(trust.SourceUser, KeyStepSec, `5`), scope(trust.SourceProject, KeyStepSec, `20`)},
+		"operator over 30 s":  {scope(trust.SourceUser, KeyStepSec, `600`)},
+	} {
+		if _, _, err := reg.Merge("", scopes...); err == nil || !strings.Contains(err.Error(), "E670") {
+			t.Errorf("%s: want E670, got %v", name, err)
+		}
+	}
+	// a revision widening is ignored, not applied.
+	eff, _, err = reg.Merge("", scope(trust.SourceProject, KeyOrder, `["vps"]`), scope(trust.SourceRevision, KeyOrder, `["vps","lan"]`))
+	if err != nil || !reflect.DeepEqual(Order(eff), []string{"vps"}) || len(eff.Ignored()) != 1 {
+		t.Fatalf("revision widening: %v %v %v", Order(eff), eff.Ignored(), err)
+	}
+	for _, raw := range []string{`[]`, `["cloud"]`, `["lan","lan"]`, `"lan"`, `[1]`, `null`} {
+		if _, err := decodeOrder(json.RawMessage(raw)); err == nil {
+			t.Errorf("order %s accepted", raw)
+		}
+	}
+	for _, raw := range []string{`-1`, `1.5`, `"30"`, `null`, `1 2`} {
+		if _, err := decodeStep(json.RawMessage(raw)); err == nil {
+			t.Errorf("step_sec %s accepted", raw)
+		}
+	}
+	if v, err := decodeStep(json.RawMessage(`0`)); err != nil || v != int64(0) {
+		t.Fatalf("step_sec 0 means never wait: %v %v", v, err)
+	}
+}
+
+func TestRankAndBias(t *testing.T) {
+	r := func(id, loc string, labels ...string) sched.Runner {
+		x := sched.Runner{ID: id, Location: loc, Class: "owned"}
+		x.Capability.Identity.Labels = labels
+		return x
+	}
+	w := sched.World{Policy: sched.Policy{Preset: sched.AutoPreset},
+		Runners: []sched.Runner{r("a", "lan", "rank=7"), r("b", "lan"), r("c", "remote", "rank=x"), r("d", "local", "rank=999999999")},
+		Hosted:  []sched.Runner{{ID: "h", Location: "hosted", Class: "metered"}, {ID: "i", Location: "remote", Class: "included"}},
+		Costs:   map[string]sched.Cost{},
+	}
+	got := Bias(w, DefaultOrder())
+	want := map[string]int64{"a": 2*sched.TierStepMs + 7, "b": 2*sched.TierStepMs + 1, "c": sched.TierStepMs + 2, "d": 4*sched.TierStepMs - 1, "h": 0, "i": 1}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("bias %v want %v", got, want)
+	}
+	// a tier the order leaves out goes after every listed tier.
+	if b := Bias(w, []string{"local", "lan"}); b["c"] != 2*sched.TierStepMs+2 || b["d"] != sched.TierStepMs-1 || b["a"] != sched.TierStepMs+7 {
+		t.Fatalf("narrowed bias %v", b)
+	}
+	if err := contribute(context.Background(), &w); err != nil || !reflect.DeepEqual(w.Bias, want) {
+		t.Fatalf("contributor: %v %v", w.Bias, err)
+	}
+	w.Bias, w.Policy.Preset = nil, "balanced"
+	if err := contribute(context.Background(), &w); err != nil || w.Bias != nil {
+		t.Fatalf("other presets get no bias: %v", w.Bias)
+	}
+	for loc, tier := range map[string]string{"hosted": "hosted", "remote": "vps", "ephemeral": "vps", "lan": "lan", "local": "local"} {
+		if got := sched.TierFor(loc, "owned"); got != tier {
+			t.Errorf("%s: tier %s want %s", loc, got, tier)
+		}
+	}
+	if sched.TierFor("remote", "included") != "hosted" {
+		t.Error("an included-class runner is in the hosted tier")
+	}
+}
diff --git a/free/ci/internal/transport/agent/driver.go b/free/ci/internal/transport/agent/driver.go
index 96e1f41ee..696b9219c 100644
--- a/free/ci/internal/transport/agent/driver.go
+++ b/free/ci/internal/transport/agent/driver.go
@@ -69,7 +69,9 @@ type Driver struct {
 	finished  map[string]bool             // lease ids whose Run returned, bounded
 	order     []string
 	lastPrune time.Time
-	pending   map[string]map[string]string // node -> lease id -> reason: cancels that found no control stream
+	// Push queues a frame on a node's control stream (agentapi.Server.Push); nil disables the cache restore push.
+	Push    func(ctx context.Context, node string, m protocol.Message) error
+	pending map[string]map[string]string // node -> lease id -> reason: cancels that found no control stream
 }
 
 func (d *Driver) hasRoute(leaseID string) bool {
@@ -100,6 +102,7 @@ func (d *Driver) Admit(ctx context.Context, c agentapi.Call) error {
 		if !d.hasRoute(c.LeaseID) { // no run waits for this lease: do not renew it, tell the agent to stop it
 			return lost("no run is waiting for lease %s on this coordinator", c.LeaseID)
 		}
+		d.noteRunning(c.LeaseID)
 		if err := d.syncLogs(); err != nil {
 			d.logf("agent transport: syncing the lease logs: %v", err)
 			return err
@@ -166,10 +169,12 @@ type route struct {
 	once               sync.Once
 	lw                 *LogWriter
 	blobs              *blobSet
-	resultMu           sync.Mutex // serializes result commits and spend retries
-	resultDone         bool       // guarded by Driver.mu
-	fwd, prevFwd       uint64     // highest log line_seq the run's sink accepted (and the one before)
-	err                error      // why the lease failed (a corrupt blob); read after done is closed
+	resultMu           sync.Mutex           // serializes result commits and spend retries
+	resultDone         bool                 // guarded by Driver.mu
+	fwd, prevFwd       uint64               // highest log line_seq the run's sink accepted (and the one before)
+	offsets            chan protocol.Offset // the node's offset answers to a restore push (restore.go)
+	arm                func()               // starts the restore push; nil when the sink restores nothing
+	err                error                // why the lease failed (a corrupt blob); read after done is closed
 }
 
 func (r *route) finish() { r.once.Do(func() { close(r.done) }) }
@@ -252,6 +257,8 @@ func (d *Driver) Run(ctx context.Context, node model.Capability, lease protocol.
 	lease.Token = tok
 	d.prune(ctx, c.gate, time.Now())
 	rt := &route{node: nodeID, leaseID: lease.LeaseID, jti: jti, sink: sink, done: make(chan struct{})}
+	stopRestore := d.armRestore(ctx, rt, lease, sink)
+	defer stopRestore()
 	if err = d.enqueue(rt, lease); err != nil {
 		return err
 	}
diff --git a/free/ci/internal/transport/agent/restore.go b/free/ci/internal/transport/agent/restore.go
new file mode 100644
index 000000000..8c40e0456
--- /dev/null
+++ b/free/ci/internal/transport/agent/restore.go
@@ -0,0 +1,120 @@
+package agent
+
+// Purpose: the coordinator half of a cache restore over carrier B (P7-CACHE-21, Epic CACHE D7): once the
+//          node reports the lease running, the run's Sink (transport.Restorer) pushes digest and chunk
+//          frames down the node's control stream and reads the node's upstream offset answers.
+// Inputs:  the run's Sink, the lease, the first heartbeat naming the lease, offset frames (OffsetHandler).
+// Outputs: control-stream frames fenced to the lease and its epoch; Carrier.BlobRestore for the session.
+// Constraints: the push starts once, on the first heartbeat of the lease (the node has the lease and its
+//          feed by then), and ends with Run (its context is cancelled and the push is awaited); an offset
+//          for a lease without a restore, from another node, or a full buffer drops the oldest answer.
+
+import (
+	"context"
+	"sync"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/agentapi"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+const offsetBuffer = 64
+
+// BlobRestore says the pull carrier delivers the coordinator's digest and chunk frames (session.RestoreCarrier).
+func (*Carrier) BlobRestore() bool { return true }
+
+// SetPush installs the function that queues a frame on a node's control stream (agentapi.Server.Push).
+func (d *Driver) SetPush(fn func(ctx context.Context, node string, m protocol.Message) error) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	d.Push = fn
+}
+
+type restoreLink struct {
+	ctx   context.Context
+	push  func(context.Context, string, protocol.Message) error
+	rt    *route
+	epoch uint64
+}
+
+func (l restoreLink) send(typ string, body any) error {
+	e := l.epoch
+	return l.push(l.ctx, l.rt.node, protocol.Message{Type: typ, LeaseID: l.rt.leaseID, Epoch: &e, Body: body})
+}
+func (l restoreLink) Digest(d protocol.Digest) error  { return l.send("digest", d) }
+func (l restoreLink) Chunk(c protocol.Chunk) error    { return l.send("chunk", c) }
+func (l restoreLink) Offsets() <-chan protocol.Offset { return l.rt.offsets }
+
+var _ transport.RestoreLink = restoreLink{}
+
+// armRestore prepares the push of a Restorer sink; the returned func stops it and waits for it.
+func (d *Driver) armRestore(ctx context.Context, rt *route, lease protocol.Lease, sink transport.Sink) func() {
+	r, ok := sink.(transport.Restorer)
+	push := d.pushFn()
+	if !ok || push == nil {
+		return func() {}
+	}
+	rt.offsets = make(chan protocol.Offset, offsetBuffer)
+	rctx, cancel := context.WithCancel(ctx)
+	var once sync.Once
+	done := make(chan struct{})
+	rt.arm = func() {
+		once.Do(func() {
+			go func() {
+				defer close(done)
+				// the Sink audits a refusal; the node runs cold
+				if err := r.Restore(rctx, restoreLink{rctx, push, rt, lease.Epoch}); err != nil && rctx.Err() == nil {
+					d.logf("agent transport: restore push for lease %s: %v", rt.leaseID, err)
+				}
+			}()
+		})
+	}
+	return func() {
+		cancel()
+		once.Do(func() { close(done) })
+		<-done
+	}
+}
+
+func (d *Driver) pushFn() func(context.Context, string, protocol.Message) error {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	return d.Push
+}
+
+// noteRunning starts the restore push of a lease the node just reported.
+func (d *Driver) noteRunning(leaseID string) {
+	d.mu.Lock()
+	rt := d.routes[leaseID]
+	d.mu.Unlock()
+	if rt != nil && rt.arm != nil {
+		rt.arm()
+	}
+}
+
+// Offset implements agentapi.OffsetHandler: the node's answer to the restore push.
+func (h blobHandler) Offset(_ context.Context, node string, m protocol.Message) error {
+	o, ok := m.Body.(*protocol.Offset)
+	if !ok {
+		return nil
+	}
+	h.d.mu.Lock()
+	rt := h.d.routes[m.LeaseID]
+	h.d.mu.Unlock()
+	if rt == nil || rt.node != node || rt.offsets == nil {
+		return nil
+	}
+	for {
+		select {
+		case rt.offsets <- *o:
+			return nil
+		default:
+		}
+		select {
+		case <-rt.offsets:
+		default:
+		}
+	}
+}
+
+var _ agentapi.OffsetHandler = blobHandler{}
diff --git a/free/ci/internal/transport/restore.go b/free/ci/internal/transport/restore.go
new file mode 100644
index 000000000..7ef21e61a
--- /dev/null
+++ b/free/ci/internal/transport/restore.go
@@ -0,0 +1,49 @@
+package transport
+
+// Purpose: the seams of the reverse blob path (Epic CACHE D7, P7-CACHE-21): the
+// coordinator pushes the cache blobs a lease restores to the node, and the node
+// session hands those frames to the job hook that is receiving them.
+// Inputs:  a Sink that can open a lease's planned restore blobs (Restorer), and
+// the digest and chunk frames a node session receives (BlobFeed).
+// Outputs: RestoreLink for a driver to give the Sink, BlobFrame for the node.
+// Constraints: a carrier that cannot send coordinator frames to a node never
+// calls Restore, and its node session never offers a feed, so a cold restore
+// degrades at once instead of waiting for frames that cannot arrive.
+
+import (
+	"context"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+)
+
+// RestoreLink is the coordinator's end of one lease's reverse blob path, bound
+// to the lease and epoch of the session (a frame it sends carries both).
+type RestoreLink interface {
+	Digest(protocol.Digest) error
+	Chunk(protocol.Chunk) error
+	// Offsets carries the node's offset answers for this lease.
+	Offsets() <-chan protocol.Offset
+}
+
+// Restorer is implemented by a Sink that owns the cache plan of its lease. A
+// driver calls Restore once, after the lease frame is sent, on its own goroutine;
+// the error is the Sink's to audit, the job never waits for it.
+type Restorer interface {
+	Restore(ctx context.Context, link RestoreLink) error
+}
+
+// BlobFrame is one coordinator-to-node blob frame: exactly one field is set.
+type BlobFrame struct {
+	Digest *protocol.Digest
+	Chunk  *protocol.Chunk
+}
+
+// BlobFeed is the node session's end of a lease's reverse blob path.
+type BlobFeed interface {
+	// Frames carries the lease's digest and chunk frames in arrival order.
+	Frames() <-chan BlobFrame
+	// Offset answers the coordinator.
+	Offset(protocol.Offset) error
+	// Close tells the session nobody reads Frames any more; later frames are dropped.
+	Close()
+}
diff --git a/free/ci/internal/transport/ssh/restore.go b/free/ci/internal/transport/ssh/restore.go
new file mode 100644
index 000000000..5e1a03d24
--- /dev/null
+++ b/free/ci/internal/transport/ssh/restore.go
@@ -0,0 +1,60 @@
+package ssh
+
+// Purpose: the coordinator end of the reverse blob path on carrier A (P7-CACHE-21,
+// Epic CACHE D7): after the lease is sent, a Sink that owns the lease's cache plan
+// (transport.Restorer) pushes the restore blobs as digest and chunk frames, and the
+// node's offset answers are routed back to it.
+// Inputs:  the node's `offset` frames for this lease and epoch.
+// Outputs: `digest` and `chunk` frames fenced to the lease and epoch.
+// Constraints: the push runs beside the serve loop and ends with it (the context is
+// cancelled when the lease ends or is cancelled); an offset for another lease or
+// epoch is dropped; the answer channel never blocks the read loop (a full channel
+// drops the oldest answer, the newest one is the node's current position).
+
+import (
+	"context"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// offsetBuffer is how many unread node answers a session keeps.
+const offsetBuffer = 64
+
+type restoreLink struct{ s *sess }
+
+func (l restoreLink) Digest(d protocol.Digest) error  { return l.s.send("digest", d, true) }
+func (l restoreLink) Chunk(c protocol.Chunk) error    { return l.s.send("chunk", c, true) }
+func (l restoreLink) Offsets() <-chan protocol.Offset { return l.s.offsets }
+
+var _ transport.RestoreLink = restoreLink{}
+
+// startRestore begins the push when the Sink has restore blobs; the returned func stops it.
+func (s *sess) startRestore(ctx context.Context) func() {
+	r, ok := s.sink.(transport.Restorer)
+	if !ok {
+		return func() {}
+	}
+	rctx, cancel := context.WithCancel(ctx)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		_ = r.Restore(rctx, restoreLink{s}) // the Sink audits a refusal; the node runs cold
+	}()
+	return func() { cancel(); <-done }
+}
+
+// onOffset hands a node answer to the push.
+func (s *sess) onOffset(o protocol.Offset) {
+	for {
+		select {
+		case s.offsets <- o:
+			return
+		default:
+		}
+		select {
+		case <-s.offsets:
+		default:
+		}
+	}
+}
diff --git a/free/ci/internal/transport/ssh/run.go b/free/ci/internal/transport/ssh/run.go
index 427dc1d58..4407b633c 100644
--- a/free/ci/internal/transport/ssh/run.go
+++ b/free/ci/internal/transport/ssh/run.go
@@ -45,6 +45,7 @@ type sess struct {
 	seq    uint64
 
 	frames     chan frame
+	offsets    chan protocol.Offset // the node's offset answers for the restore push (restore.go)
 	stop       chan struct{}
 	readerDone chan struct{}
 	errDone    <-chan struct{}
@@ -85,7 +86,7 @@ func (d *Driver) Run(ctx context.Context, node model.Capability, lease protocol.
 	if err != nil {
 		return newErr(CodeTransport, ReasonConnect, "cannot start ssh for node %s: %v", node.Identity.ID, err)
 	}
-	s := &sess{d: d, node: node, lease: lease, sink: sink, conn: conn, frames: make(chan frame, 64),
+	s := &sess{d: d, node: node, lease: lease, sink: sink, conn: conn, frames: make(chan frame, 64), offsets: make(chan protocol.Offset, offsetBuffer),
 		stop: make(chan struct{}), readerDone: make(chan struct{}), origin: time.Now(), blobs: map[string]*blobState{}, committed: map[string]bool{}}
 	s.stderr, s.errDone = drain(conn.Stderr)
 	defer s.close()
diff --git a/free/ci/internal/transport/ssh/serve.go b/free/ci/internal/transport/ssh/serve.go
index 5ab1f76a6..56be42fff 100644
--- a/free/ci/internal/transport/ssh/serve.go
+++ b/free/ci/internal/transport/ssh/serve.go
@@ -27,6 +27,7 @@ func (s *sess) serve(ctx context.Context, bundle string) error {
 	if err := s.sendSecrets(ctx); err != nil {
 		return err
 	}
+	defer s.startRestore(ctx)()
 	uploaded := make(chan error, 1)
 	if bundle != "" {
 		go func() { uploaded <- s.upload(ctx, bundle) }()
@@ -236,6 +237,10 @@ func (s *sess) handle(ctx context.Context, m protocol.Message) (done bool, err e
 			return false, nil
 		}
 		return false, s.onChunk(*b)
+	case *protocol.Offset:
+		if s.scoped(m) {
+			s.onOffset(*b)
+		}
 	}
 	return false, nil
 }
diff --git a/free/ci/internal/watch/candidates.go b/free/ci/internal/watch/candidates.go
new file mode 100644
index 000000000..b62e618ee
--- /dev/null
+++ b/free/ci/internal/watch/candidates.go
@@ -0,0 +1,67 @@
+package watch
+
+// Purpose: which discovered heads a personal watcher may consider, and in what order (P7-AUTO-11).
+// Inputs:  the heads of every repository's scan; the ports that say whether the project is team-owned
+//          and whether an isolated runner exists.
+// Outputs: Order (newest default-branch head first) and gate (a skip reason, or "" to go on).
+// Constraints: a fork pull request head is never run, whatever else is true; an untrusted head is never
+//          run; a collaborator head runs only on an isolated runner and is otherwise reported skipped with
+//          E821, never forced onto this machine; a team-owned project is skipped (team_owned) because a
+//          PERSONAL process must not post for it (HOST-02).
+
+import (
+	"context"
+	"sort"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// rank orders the kinds of head: the default branch, protected branches, pull requests, extra branches.
+func rank(h Head) int {
+	switch {
+	case h.Default:
+		return 0
+	case h.PR == 0 && h.Protected && !h.Extra:
+		return 1
+	case h.PR > 0:
+		return 2
+	}
+	return 3
+}
+
+// Order sorts heads in place: by kind, then the newest commit first (an unknown time keeps the scan's
+// order, which lists pull requests by their last update).
+func Order(heads []Head) {
+	sort.SliceStable(heads, func(i, j int) bool {
+		ri, rj := rank(heads[i]), rank(heads[j])
+		if ri != rj {
+			return ri < rj
+		}
+		a, b := heads[i].CommittedAt, heads[j].CommittedAt
+		if a.IsZero() || b.IsZero() {
+			return false
+		}
+		return a.After(b)
+	})
+}
+
+// Gate is the rule for one head before any ledger read: "" lets it go on, else the skip reason and
+// its code. isolated is filled in for a collaborator head that may run on an isolated runner.
+func (w *Watcher) gate(ctx context.Context, h Head) (reason, code string, isolated bool) {
+	if h.Fork {
+		return SkipFork, "", false
+	}
+	if w.P.TeamOwned != nil && w.P.TeamOwned(ctx, h.Repo) {
+		return SkipTeam, "", false
+	}
+	switch h.Trust {
+	case model.TrustClass("owner"):
+		return "", "", false
+	case model.TrustClass("collaborator"):
+		if w.P.Isolated == nil || !w.P.Isolated(ctx) {
+			return SkipIsolated, CodeIsolated, false
+		}
+		return "", "", true
+	}
+	return SkipApproval, "", false
+}
diff --git a/free/ci/internal/watch/codes.go b/free/ci/internal/watch/codes.go
new file mode 100644
index 000000000..785377f97
--- /dev/null
+++ b/free/ci/internal/watch/codes.go
@@ -0,0 +1,26 @@
+package watch
+
+import "github.com/nself-org/plugins/free/ci/internal/model"
+
+// The codes of this Ticket's share of the AUTO block (model.CodeRanges: E804-E805, and the spare E821
+// for the isolated-runner skip, because E625 is P7-CI-37's).
+const (
+	CodeConfig   = "E804"
+	CodeQuota    = "E805"
+	CodeIsolated = "E821"
+)
+
+func init() {
+	for _, code := range []model.Code{
+		{ID: CodeConfig, Class: "usage", Summary: "a watch.* setting is invalid", Fix: "Fix the operator value (`nself ci policy show` names the key) and restart the watcher"},
+		{ID: CodeQuota, Class: "quota", Summary: "the GitHub quota stopped the watch pass", Fix: "Nothing to do: the watcher makes no request before the recorded reset time; raise providers.github.poll_interval if it recurs"},
+		{ID: CodeIsolated, Class: "policy", Summary: "skipped: needs isolated runner", Fix: "A collaborator head runs only on an isolated runner; add one (the isolation section of `nself ci doctor` shows what this machine proved) or let the coordinator run it"},
+	} {
+		model.Register(code)
+	}
+}
+
+// Error carries one of the registered watch codes. Its text never holds a token or a path.
+type Error struct{ Code, Message string }
+
+func (e *Error) Error() string { return e.Code + ": " + e.Message }
diff --git a/free/ci/internal/watch/commit.go b/free/ci/internal/watch/commit.go
new file mode 100644
index 000000000..ca7b4ffa1
--- /dev/null
+++ b/free/ci/internal/watch/commit.go
@@ -0,0 +1,204 @@
+package watch
+
+// Purpose: the decision for one head (P7-AUTO-11): gate it, resolve its result context, read its status
+//          history, honour a final result, a live claim and a hosted use or wait, and claim it when this
+//          host is ready and may take it.
+// Inputs:  a Head, readiness, whether this pass already ran a commit.
+// Outputs: a Decision; the claim through report.Ledger.PostClaim; the run through run.go.
+// Constraints: only statuses of the trusted creators count (claims.Inputs.Trusted); the retry count is
+//          the number of trusted `error` results on the result context minus one, so an error is retried
+//          watch.retry_max times watch.retry_gap apart and then stays final; a failure is final at once;
+//          a claim is read back before the run and the run starts only while the claim holds.
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/claims"
+	"github.com/nself-org/plugins/free/ci/internal/hostedtier"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+// ResidualContext carries the residual checks of a hosted use on a pinned repository.
+const ResidualContext = report.Context + "/residual"
+
+// hostedUse is the hosted decision a run must respect.
+type hostedUse struct {
+	use      bool
+	failed   bool // the hosted result was red
+	residual []string
+}
+
+func (w *Watcher) resultContext(ctx context.Context, h Head) string {
+	if w.C.StatusContext != "" {
+		return w.C.StatusContext
+	}
+	owner, repo, _ := strings.Cut(h.Repo, "/")
+	if w.P.ResultContext == nil {
+		return report.WatchContext
+	}
+	return w.P.ResultContext(ctx, owner, repo, "")
+}
+
+// inputs builds the claim-ledger inputs of h from its status history.
+func (w *Watcher) inputs(h Head, list []report.LedgerStatus, providerNow time.Time, resultCtx string) claims.Inputs {
+	st := make([]claims.Status, 0, len(list))
+	for _, s := range list {
+		st = append(st, claims.Status{Context: s.Context, State: string(s.State), Creator: s.Creator, Description: s.Description, CreatedAt: s.CreatedAt})
+	}
+	if providerNow.IsZero() {
+		providerNow = w.now()
+	}
+	w.mu.Lock()
+	first, ok := w.firstSeen[key(h)]
+	if !ok {
+		first = providerNow
+		w.firstSeen[key(h)] = first
+	}
+	w.mu.Unlock()
+	return claims.Inputs{Now: providerNow, Statuses: st, Me: claims.Me{Host: w.C.Host, Incarnation: w.C.Incarnation},
+		Trusted: w.C.Trusted, RunLimit: w.C.RunLimit, Preferred: w.C.Preferred, Hosts: w.C.Hosts, Step: w.C.Step,
+		FirstSeen: first, RetryMax: w.C.RetryMax, RetryGap: w.C.RetryGap, ResultContext: resultCtx, ClaimContext: report.ClaimContext}
+}
+
+// history reads the status history of h; ok is false when the ledger could not be read.
+func (w *Watcher) history(ctx context.Context, h Head, resultCtx string) (claims.Inputs, error) {
+	owner, repo, _ := strings.Cut(h.Repo, "/")
+	list, pnow, err := w.P.Ledger.ListStatuses(ctx, owner, repo, h.SHA)
+	if err != nil {
+		return claims.Inputs{}, err
+	}
+	return w.inputs(h, list, pnow, resultCtx), nil
+}
+
+// finals counts the trusted final results on the result context.
+func finals(in claims.Inputs, ctxName string) int {
+	n := 0
+	for _, s := range in.Statuses {
+		if trusted(in, s.Creator) && s.Context == ctxName && (s.State == "success" || s.State == "failure") {
+			n++
+		}
+	}
+	return n
+}
+
+// consider decides what to do with h and, when it takes h, runs it.
+func (w *Watcher) consider(ctx context.Context, h Head, ready, ran bool, rep *PassReport) Decision {
+	d := Decision{Repo: h.Repo, SHA: h.SHA, Action: "skip"}
+	reason, code, isolated := w.gate(ctx, h)
+	if reason != "" {
+		d.Reason, d.Code = reason, code
+		w.log("skip", map[string]any{"repo": h.Repo, "sha": h.SHA, "reason": reason})
+		return d
+	}
+	resultCtx := w.resultContext(ctx, h)
+	d.Context = resultCtx
+	in, err := w.history(ctx, h, resultCtx)
+	if err != nil {
+		d.Reason = SkipError
+		rep.Errors = append(rep.Errors, h.Repo+"@"+short(h.SHA)+": status history unreadable")
+		return d
+	}
+	if in.Final() {
+		w.noteDuplicate(h, in, resultCtx, rep)
+		d.Reason = SkipFinal
+		return d
+	}
+	hu := w.hosted(ctx, h, in.FirstSeen)
+	switch {
+	case hu == nil:
+		d.Reason = SkipHosted
+		return d
+	case hu.use && resultCtx != report.Context: // pinned: the Actions check stands, the residual is advisory
+		resultCtx, in.ResultContext, d.Context = ResidualContext, ResidualContext, ResidualContext
+		if in.Final() {
+			d.Reason = SkipFinal
+			return d
+		}
+		if len(hu.residual) == 0 {
+			d.Reason = SkipHostedUse
+			return d
+		}
+	}
+	dec := claims.Decide(in)
+	switch dec.Kind {
+	case claims.Skip:
+		d.Reason = SkipFinal
+		return d
+	case claims.Lost:
+		rep.Held++
+		d.Reason = SkipClaimed
+		return d
+	case claims.Wait:
+		rep.Queued++
+		d.Reason = SkipWait
+		return d
+	}
+	if !ready {
+		rep.Queued++
+		d.Reason = SkipNotReady
+		return d
+	}
+	if ran {
+		rep.Queued++
+		d.Reason = SkipBusy
+		return d
+	}
+	if !dec.Holds {
+		owner, repo, _ := strings.Cut(h.Repo, "/")
+		if _, err := w.P.Ledger.PostClaim(ctx, report.ClaimStatus(owner, repo, h.SHA, w.C.Host, w.C.Incarnation)); err != nil {
+			d.Reason = SkipError
+			rep.Errors = append(rep.Errors, h.Repo+"@"+short(h.SHA)+": claim not posted")
+			return d
+		}
+		if in, err = w.history(ctx, h, resultCtx); err != nil || !claims.Decide(in).Holds {
+			d.Reason = SkipLost
+			return d
+		}
+	}
+	return w.run(ctx, h, Job{Head: h, Context: resultCtx, Only: hostedResidual(hu), Isolated: isolated}, hu, rep)
+}
+
+// hosted returns the hosted decision of h, or nil when the hosted run is still inside its timers.
+func (w *Watcher) hosted(ctx context.Context, h Head, pushed time.Time) *hostedUse {
+	if w.P.Hosted == nil {
+		return &hostedUse{}
+	}
+	r := w.P.Hosted.Decide(ctx, h.Repo, h.SHA, pushed)
+	switch r.Decision {
+	case hostedtier.Wait:
+		return nil
+	case hostedtier.Use:
+		return &hostedUse{use: true, failed: r.Reason == hostedtier.ReasonFailure, residual: r.Residual}
+	}
+	return &hostedUse{}
+}
+
+func hostedResidual(hu *hostedUse) []string {
+	if hu == nil || !hu.use {
+		return nil
+	}
+	return hu.residual
+}
+
+// noteDuplicate reports, once per commit, a second final result (two hosts inside the fence window).
+func (w *Watcher) noteDuplicate(h Head, in claims.Inputs, ctxName string, rep *PassReport) {
+	if n := finals(in, ctxName); n > 1 {
+		w.mu.Lock()
+		seen := w.dups[key(h)]
+		w.dups[key(h)] = true
+		w.mu.Unlock()
+		if !seen {
+			rep.Duplicates += n - 1
+			w.log("duplicate", map[string]any{"repo": h.Repo, "sha": h.SHA, "finals": n})
+		}
+	}
+}
+
+func short(sha string) string {
+	if len(sha) > 12 {
+		return sha[:12]
+	}
+	return sha
+}
diff --git a/free/ci/internal/watch/conditional_test.go b/free/ci/internal/watch/conditional_test.go
new file mode 100644
index 000000000..e57db322b
--- /dev/null
+++ b/free/ci/internal/watch/conditional_test.go
@@ -0,0 +1,80 @@
+package watch
+
+// Purpose: P7-AUTO-11 conditional requests on the watcher side: a scan whose
+// conditional reads all answered 304 keeps the previous heads (no fresh listing
+// is needed to act on them), a 304 before any listing acts on nothing, and the
+// passes of two hosts are offset and jittered apart.
+// Inputs: the shared rig (fake ledger, scripted runner) and a scripted scanner.
+// Outputs: pass or fail. Constraints: no network, no sleeps.
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// notModScan answers the first scan with heads and every later one with 304.
+type notModScan struct {
+	heads []Head
+	calls int
+}
+
+func (s *notModScan) Scan(context.Context, string) (Scan, error) {
+	s.calls++
+	if s.calls == 1 {
+		return Scan{Heads: append([]Head(nil), s.heads...)}, nil
+	}
+	return Scan{NotModified: true}, nil
+}
+
+func TestConditionalRequests(t *testing.T) {
+	ctx := context.Background()
+
+	// A 304 keeps the heads of the last full scan: the pass still sees them (here: already final).
+	r := newRig(t, ownerHead("o/r", 1))
+	scan := &notModScan{heads: r.scan.heads}
+	r.w.P.Scanner = scan
+	if rep := r.w.Pass(ctx); rep.Ran != 1 {
+		t.Fatalf("the first pass must run the head: %+v", rep)
+	}
+	rep := r.w.Pass(ctx)
+	if scan.calls != 2 || len(rep.Decisions) != 1 || rep.Decisions[0].SHA != sha(1) || rep.Ran != 0 {
+		t.Fatalf("a 304 scan must keep the previous heads and run nothing new: calls=%d %+v", scan.calls, rep)
+	}
+	if r.runner.count() != 1 {
+		t.Fatalf("a 304 scan must not rerun a head: %d runs", r.runner.count())
+	}
+
+	// A 304 before any full scan has nothing to act on.
+	fresh := newRig(t)
+	fresh.w.P.Scanner = &notModScan{calls: 1}
+	if rep := fresh.w.Pass(ctx); len(rep.Decisions) != 0 || rep.Ran != 0 {
+		t.Fatalf("a 304 without a previous scan must act on nothing: %+v", rep)
+	}
+
+	// Two hosts poll out of step: distinct phase offsets inside one interval, and a
+	// jittered wait within [0.9, 1.1) of the interval.
+	c := Defaults()
+	c.Interval = time.Minute
+	mk := func(host string, jitter float64) *Watcher {
+		c.Host = host
+		w, err := New(c, Ports{Scanner: scan, Ledger: r.gh.on(host), Reporter: r.gh.on(host), Runner: r.runner, Jitter: func() float64 { return jitter }})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return w
+	}
+	a, b := mk("mini1", 0), mk("mini2", 0.999)
+	if a.Offset() == b.Offset() {
+		t.Fatalf("two hosts must not share a phase offset: %v", a.Offset())
+	}
+	for _, w := range []*Watcher{a, b} {
+		if o := w.Offset(); o < 0 || o >= c.Interval {
+			t.Fatalf("offset %v is outside one interval", o)
+		}
+	}
+	now := time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC)
+	if lo, hi := a.Next(now), b.Next(now); lo != 54*time.Second || hi < lo || hi >= 66*time.Second {
+		t.Fatalf("jittered waits %v and %v must lie in [0.9, 1.1) of the interval", lo, hi)
+	}
+}
diff --git a/free/ci/internal/watch/drain_test.go b/free/ci/internal/watch/drain_test.go
new file mode 100644
index 000000000..2c7d49ee2
--- /dev/null
+++ b/free/ci/internal/watch/drain_test.go
@@ -0,0 +1,123 @@
+package watch
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/hostedtier"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+// drainRig is a rig whose runner blocks and whose After hands each timer to the test.
+func drainRig(t *testing.T) (*rig, chan chan time.Time) {
+	r := newRig(t, ownerHead("o/r", 1))
+	r.runner.block, r.runner.started = make(chan struct{}), make(chan struct{}, 1)
+	timers := make(chan chan time.Time, 4)
+	r.w.P.After = func(time.Duration) <-chan time.Time {
+		ch := make(chan time.Time, 1)
+		timers <- ch
+		return ch
+	}
+	return r, timers
+}
+
+func TestDrainOnSigterm(t *testing.T) {
+	// the drain ends: the attempt is cancelled and closed with an error, the claim is not orphaned
+	r, timers := drainRig(t)
+	ctx, sigterm := context.WithCancel(context.Background())
+	done := make(chan PassReport, 1)
+	go func() { done <- r.w.Pass(ctx) }()
+	<-r.runner.started
+	sigterm()
+	timer := <-timers // the drain started; the attempt still runs
+	select {
+	case <-done:
+		t.Fatal("the pass ended before the drain")
+	default:
+	}
+	timer <- t0
+	rep := <-done
+	if got := r.gh.states(sha(1), report.Context); len(got) != 1 || got[0] != "error" {
+		t.Fatalf("cancelled attempt result %v (%+v)", got, rep.Decisions)
+	}
+	if p := r.gh.posts[0]; !strings.Contains(p.Description, "cancelled") {
+		t.Fatalf("description %q", p.Description)
+	}
+
+	// the attempt finishes inside the drain: its own result is posted
+	r, timers = drainRig(t)
+	ctx, sigterm = context.WithCancel(context.Background())
+	go func() { done <- r.w.Pass(ctx) }()
+	<-r.runner.started
+	sigterm()
+	<-timers
+	close(r.runner.block)
+	<-done
+	if got := r.gh.states(sha(1), report.Context); len(got) != 1 || got[0] != "success" {
+		t.Fatalf("finished attempt result %v", got)
+	}
+
+	// a loop cancelled between passes stops without another pass
+	r = newRig(t, ownerHead("o/r", 1))
+	ctx, sigterm = context.WithCancel(context.Background())
+	passes := 0
+	r.w.P.After = func(time.Duration) <-chan time.Time { sigterm(); return make(chan time.Time) }
+	r.w.Run(ctx, false, func(PassReport) { passes++ })
+	if passes != 0 || r.runner.count() != 0 {
+		t.Fatalf("passes %d after SIGTERM", passes)
+	}
+}
+
+type fixedHosted struct{ r hostedtier.Result }
+
+func (f fixedHosted) Decide(context.Context, string, string, time.Time) hostedtier.Result { return f.r }
+
+func TestResidualAggregation(t *testing.T) {
+	use := hostedtier.Result{Decision: hostedtier.Use, Reason: hostedtier.ReasonSuccess, Residual: []string{"secrets.gitleaks"}}
+	failRes := func(int, Job) report.State { return report.Failure }
+
+	// unpinned: nself-ci is the aggregate, failure when the residual failed
+	r := newRig(t, ownerHead("o/r", 1))
+	r.w.P.Hosted, r.runner.state = fixedHosted{use}, failRes
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(1), report.Context); len(got) != 1 || got[0] != "failure" {
+		t.Fatalf("unpinned aggregate %v", got)
+	}
+	if j := r.runner.jobs[0]; len(j.Only) != 1 || j.Only[0] != "secrets.gitleaks" {
+		t.Fatalf("only the residual checks run: %+v", j)
+	}
+
+	// pinned: nself-ci/residual plus a failure alert; nothing else is written
+	r = newRig(t, ownerHead("o/r", 2))
+	r.w.P.Hosted, r.runner.state = fixedHosted{use}, failRes
+	r.w.P.ResultContext = func(context.Context, string, string, string) string { return report.WatchContext }
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(2), ResidualContext); len(got) != 1 || got[0] != "failure" || len(r.alerts) != 1 {
+		t.Fatalf("pinned residual %v, alerts %v", got, r.alerts)
+	}
+	if len(r.gh.states(sha(2), report.Context))+len(r.gh.states(sha(2), report.WatchContext)) != 0 {
+		t.Fatal("the pinned result contexts stay untouched")
+	}
+	if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipFinal {
+		t.Fatalf("the residual result is final: %+v", d)
+	}
+
+	// a red hosted result stays red even when the residual passed
+	red := use
+	red.Reason = hostedtier.ReasonFailure
+	r = newRig(t, ownerHead("o/r", 3))
+	r.w.P.Hosted = fixedHosted{red}
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(3), report.Context); len(got) != 1 || got[0] != "failure" {
+		t.Fatalf("red hosted %v", got)
+	}
+
+	// wait: nothing is claimed while the hosted run is inside its timers
+	r = newRig(t, ownerHead("o/r", 4))
+	r.w.P.Hosted = fixedHosted{hostedtier.Result{Decision: hostedtier.Wait}}
+	if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipHosted || r.gh.claims != 0 {
+		t.Fatalf("hosted wait %+v", d)
+	}
+}
diff --git a/free/ci/internal/watch/fake_test.go b/free/ci/internal/watch/fake_test.go
new file mode 100644
index 000000000..bb03f9881
--- /dev/null
+++ b/free/ci/internal/watch/fake_test.go
@@ -0,0 +1,186 @@
+package watch
+
+// Purpose: the shared test rig: an in-memory provider status ledger with its own clock and partitions,
+//          a fixed scanner, a scripted runner and a manual After.
+// Constraints: no network, no sleeps, no ports; time is a value the test advances.
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+var t0 = time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC)
+
+func sha(n int) string { return strings.Repeat("a", 39) + strconv.Itoa(n%10) }
+
+type fakeGH struct {
+	mu     sync.Mutex
+	now    time.Time
+	st     map[string][]report.LedgerStatus
+	down   map[string]bool
+	claims int
+	posts  []report.Status
+}
+
+func newGH() *fakeGH {
+	return &fakeGH{now: t0, st: map[string][]report.LedgerStatus{}, down: map[string]bool{}}
+}
+
+func (g *fakeGH) advance(d time.Duration) { g.mu.Lock(); g.now = g.now.Add(d); g.mu.Unlock() }
+func (g *fakeGH) clock() time.Time        { g.mu.Lock(); defer g.mu.Unlock(); return g.now }
+
+// on returns the view of host h.
+func (g *fakeGH) on(h string) *hostGH { return &hostGH{g: g, host: h} }
+
+// states lists the states posted on ctxName for sha, oldest first.
+func (g *fakeGH) states(s, ctxName string) []string {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	var out []string
+	for _, x := range g.st[s] {
+		if x.Context == ctxName {
+			out = append(out, string(x.State))
+		}
+	}
+	return out
+}
+
+type hostGH struct {
+	g    *fakeGH
+	host string
+}
+
+var errPartition = errors.New("partition")
+
+func (h *hostGH) add(s report.Status) error {
+	g := h.g
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.down[h.host] {
+		return errPartition
+	}
+	g.st[s.Revision] = append(g.st[s.Revision], report.LedgerStatus{Context: s.ContextName(), State: s.State, Creator: "station", Description: s.Description, CreatedAt: g.now})
+	return nil
+}
+
+func (h *hostGH) PostClaim(_ context.Context, s report.Status) (time.Time, error) {
+	if err := h.add(s); err != nil {
+		return time.Time{}, err
+	}
+	h.g.mu.Lock()
+	h.g.claims++
+	h.g.mu.Unlock()
+	return h.g.clock(), nil
+}
+
+func (h *hostGH) Post(_ context.Context, s report.Status) error {
+	if err := s.Validate(); err != nil {
+		return err
+	}
+	if err := h.add(s); err != nil {
+		return err
+	}
+	h.g.mu.Lock()
+	h.g.posts = append(h.g.posts, s)
+	h.g.mu.Unlock()
+	return nil
+}
+
+func (h *hostGH) ListStatuses(_ context.Context, _, _, s string) ([]report.LedgerStatus, time.Time, error) {
+	g := h.g
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.down[h.host] {
+		return nil, time.Time{}, errPartition
+	}
+	src := g.st[s]
+	out := make([]report.LedgerStatus, 0, len(src))
+	for i := len(src) - 1; i >= 0; i-- {
+		out = append(out, src[i])
+	}
+	return out, g.now, nil
+}
+
+type fixedScan struct {
+	heads []Head
+	calls int
+	err   error
+}
+
+func (f *fixedScan) Scan(context.Context, string) (Scan, error) {
+	f.calls++
+	if f.err != nil {
+		return Scan{}, f.err
+	}
+	return Scan{Heads: append([]Head(nil), f.heads...)}, nil
+}
+
+type scriptRunner struct {
+	mu      sync.Mutex
+	jobs    []Job
+	state   func(n int, j Job) report.State
+	block   chan struct{} // when set, Run waits for it or for its context
+	started chan struct{} // when set, Run signals it on entry
+}
+
+func (r *scriptRunner) Run(ctx context.Context, j Job) (Outcome, error) {
+	r.mu.Lock()
+	r.jobs = append(r.jobs, j)
+	n := len(r.jobs)
+	r.mu.Unlock()
+	if r.started != nil {
+		r.started <- struct{}{}
+	}
+	if r.block != nil {
+		select {
+		case <-r.block:
+		case <-ctx.Done():
+			return Outcome{State: report.Error, Description: "cancelled"}, ctx.Err()
+		}
+	}
+	st := report.Success
+	if r.state != nil {
+		st = r.state(n, j)
+	}
+	return Outcome{State: st, Description: "gate " + string(st)}, nil
+}
+
+func (r *scriptRunner) count() int { r.mu.Lock(); defer r.mu.Unlock(); return len(r.jobs) }
+
+func ownerHead(repo string, n int) Head {
+	return Head{Repo: repo, SHA: sha(n), Branch: "main", Default: true, Protected: true, Trust: model.TrustClass("owner")}
+}
+
+type rig struct {
+	gh     *fakeGH
+	scan   *fixedScan
+	runner *scriptRunner
+	w      *Watcher
+	alerts []string
+}
+
+// newRig is one host "a" watching o/r, ready, unpinned, with the given heads.
+func newRig(t *testing.T, heads ...Head) *rig {
+	t.Helper()
+	r := &rig{gh: newGH(), scan: &fixedScan{heads: heads}, runner: &scriptRunner{}}
+	c := Defaults()
+	c.Repos, c.Host, c.Hosts, c.Trusted = []string{"o/r"}, "a", []string{"a"}, []string{"station"}
+	p := Ports{Scanner: r.scan, Ledger: r.gh.on("a"), Reporter: r.gh.on("a"), Runner: r.runner, Now: r.gh.clock,
+		Ready:         func(context.Context) (bool, []string) { return true, nil },
+		ResultContext: func(context.Context, string, string, string) string { return report.Context },
+		Alert:         func(_ context.Context, h Head, d string) { r.alerts = append(r.alerts, h.SHA+" "+d) }}
+	w, err := New(c, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.w = w
+	return r
+}
diff --git a/free/ci/internal/watch/keys.go b/free/ci/internal/watch/keys.go
new file mode 100644
index 000000000..fe79ed522
--- /dev/null
+++ b/free/ci/internal/watch/keys.go
@@ -0,0 +1,201 @@
+package watch
+
+// Purpose: the operator keys of the watcher (P7-AUTO-11): watch.branches, watch.max_branches,
+//          watch.branch_days, watch.retry_max, watch.retry_gap, watch.status_context and
+//          watch.drain_sec, and the typed view of them.
+// Inputs:  *policy.Effective from the operator's resolver.
+// Outputs: Keys (registered from init()), Defaults, ApplyPolicy.
+// Constraints: operator scope only (TightenFixed, Spend), so a repository can never widen what a
+//          personal watcher runs or posts; the registered Default is nil on purpose (a Fixed key with a
+//          default could never be set, E670), so the defaults live in Defaults. A bad value is E804.
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"path"
+	"regexp"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+)
+
+// The policy keys.
+const (
+	KeyBranches      = "watch.branches"
+	KeyMaxBranches   = "watch.max_branches"
+	KeyBranchDays    = "watch.branch_days"
+	KeyRetryMax      = "watch.retry_max"
+	KeyRetryGap      = "watch.retry_gap"
+	KeyStatusContext = "watch.status_context"
+	KeyDrainSec      = "watch.drain_sec"
+	keyOwner         = "P7-AUTO-11"
+)
+
+// The defaults of the keys.
+const (
+	DefaultMaxBranches = 20
+	DefaultBranchDays  = 3
+	DefaultRetryMax    = 3
+	DefaultRetryGap    = 10 * time.Minute
+	DefaultDrain       = 120 * time.Second
+	DefaultInterval    = 60 * time.Second
+	DefaultStep        = time.Minute
+	DefaultRunLimit    = time.Hour
+)
+
+var contextRe = regexp.MustCompile(`^nself-ci(/[a-z][a-z-]{0,30})?$`)
+
+var registrationErrors []error
+
+// RegistrationErrors returns what init() could not register; empty when every key is in place.
+func RegistrationErrors() []error { return append([]error(nil), registrationErrors...) }
+
+func init() {
+	for _, k := range Keys() {
+		if err := policy.RegisterKey(k); err != nil {
+			registrationErrors = append(registrationErrors, err)
+		}
+	}
+}
+
+// Keys returns the spec of every key this package owns.
+func Keys() []policy.KeySpec {
+	k := func(key string, dec func(json.RawMessage) (any, error)) policy.KeySpec {
+		return policy.KeySpec{Key: key, Owner: keyOwner, Kind: policy.TightenFixed, Spend: true, Decode: dec}
+	}
+	return []policy.KeySpec{
+		k(KeyBranches, decodeBranches), k(KeyMaxBranches, decodeInt(KeyMaxBranches, 0, 100)),
+		k(KeyBranchDays, decodeInt(KeyBranchDays, 1, 365)), k(KeyRetryMax, decodeInt(KeyRetryMax, 0, 10)),
+		k(KeyRetryGap, decodeGap), k(KeyStatusContext, decodeContext), k(KeyDrainSec, decodeInt(KeyDrainSec, 0, 3600)),
+	}
+}
+
+// Defaults is what an operator who set nothing gets.
+func Defaults() Config {
+	return Config{Interval: DefaultInterval, MaxBranches: DefaultMaxBranches, BranchDays: DefaultBranchDays,
+		RetryMax: DefaultRetryMax, RetryGap: DefaultRetryGap, Drain: DefaultDrain, Step: DefaultStep, RunLimit: DefaultRunLimit}
+}
+
+// ApplyPolicy overlays the operator's watch.* values on c. A nil Effective leaves c unchanged.
+func ApplyPolicy(c Config, eff *policy.Effective) (Config, error) {
+	if eff == nil {
+		return c, nil
+	}
+	num := func(key string, into *int) error {
+		v, _, ok := eff.Value(key)
+		if !ok {
+			return nil
+		}
+		f, isNum := v.(float64)
+		if n, isInt := v.(int); isInt {
+			f, isNum = float64(n), true
+		}
+		if !isNum {
+			return fail(key, "effective value %v is not a number", v)
+		}
+		*into = int(f)
+		return nil
+	}
+	for key, into := range map[string]*int{KeyMaxBranches: &c.MaxBranches, KeyBranchDays: &c.BranchDays, KeyRetryMax: &c.RetryMax} {
+		if err := num(key, into); err != nil {
+			return c, err
+		}
+	}
+	drain := int(c.Drain / time.Second)
+	if err := num(KeyDrainSec, &drain); err != nil {
+		return c, err
+	}
+	c.Drain = time.Duration(drain) * time.Second
+	if v, _, ok := eff.Value(KeyRetryGap); ok {
+		s, _ := v.(string)
+		d, err := time.ParseDuration(s)
+		if err != nil {
+			return c, fail(KeyRetryGap, "effective value %v is not a duration", v)
+		}
+		c.RetryGap = d
+	}
+	if v, _, ok := eff.Value(KeyStatusContext); ok {
+		c.StatusContext, _ = v.(string)
+	}
+	if v, _, ok := eff.Value(KeyBranches); ok {
+		list, _ := v.([]any)
+		c.Branches = nil
+		for _, x := range list {
+			if s, isStr := x.(string); isStr {
+				c.Branches = append(c.Branches, s)
+			}
+		}
+	}
+	return c, nil
+}
+
+func fail(key, format string, a ...any) error {
+	return &Error{Code: CodeConfig, Message: key + ": " + fmt.Sprintf(format, a...)}
+}
+
+func decodeOne(key string, raw json.RawMessage) (any, error) {
+	d := json.NewDecoder(bytes.NewReader(raw))
+	var v any
+	if err := d.Decode(&v); err != nil || d.More() {
+		return nil, fail(key, "expected exactly one JSON value")
+	}
+	return v, nil
+}
+
+func decodeInt(key string, lo, hi int) func(json.RawMessage) (any, error) {
+	return func(raw json.RawMessage) (any, error) {
+		v, err := decodeOne(key, raw)
+		if err != nil {
+			return nil, err
+		}
+		f, ok := v.(float64)
+		if !ok || f != float64(int(f)) || int(f) < lo || int(f) > hi {
+			return nil, fail(key, "expected a whole number from %d to %d", lo, hi)
+		}
+		return f, nil
+	}
+}
+
+func decodeGap(raw json.RawMessage) (any, error) {
+	v, err := decodeOne(KeyRetryGap, raw)
+	if err != nil {
+		return nil, err
+	}
+	s, _ := v.(string)
+	d, perr := time.ParseDuration(s)
+	if perr != nil || d < time.Minute || d > 24*time.Hour {
+		return nil, fail(KeyRetryGap, "expected a duration such as 10m, from 1m to 24h")
+	}
+	return d.String(), nil
+}
+
+func decodeContext(raw json.RawMessage) (any, error) {
+	v, err := decodeOne(KeyStatusContext, raw)
+	if err != nil {
+		return nil, err
+	}
+	s, _ := v.(string)
+	if !contextRe.MatchString(s) {
+		return nil, fail(KeyStatusContext, "expected nself-ci or nself-ci/<name>")
+	}
+	return s, nil
+}
+
+func decodeBranches(raw json.RawMessage) (any, error) {
+	v, err := decodeOne(KeyBranches, raw)
+	if err != nil {
+		return nil, err
+	}
+	list, ok := v.([]any)
+	if !ok || len(list) > 50 {
+		return nil, fail(KeyBranches, "expected a list of at most 50 branch names or globs")
+	}
+	for _, x := range list {
+		s, isStr := x.(string)
+		if _, perr := path.Match(s, ""); !isStr || s == "" || perr != nil {
+			return nil, fail(KeyBranches, "expected branch names or valid globs")
+		}
+	}
+	return list, nil
+}
diff --git a/free/ci/internal/watch/logs.go b/free/ci/internal/watch/logs.go
new file mode 100644
index 000000000..12b5407f5
--- /dev/null
+++ b/free/ci/internal/watch/logs.go
@@ -0,0 +1,129 @@
+package watch
+
+// Purpose: the watcher's own log writer and heartbeat (P7-AUTO-11): JSON lines under
+//          $NSELF_CI_HOME/logs/watch/, size-capped and rotated; the service units of P7-AUTO-12 only
+//          point at this directory.
+// Inputs:  the directory, a size cap and a file count.
+// Outputs: watch.log, watch.log.1 .. watch.log.N, and the heartbeat file.
+// Constraints: files 0600 in a 0700 directory; a line is written whole or not at all; an event never
+//          carries a token, an environment value or a path a caller did not put in its fields; a write
+//          failure is returned, never a panic.
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+// Log defaults.
+const (
+	DefaultLogBytes = 1 << 20
+	DefaultLogKeep  = 5
+	logName         = "watch.log"
+	heartbeatName   = "heartbeat"
+)
+
+// LogDir is the watcher's log directory under home ($NSELF_CI_HOME).
+func LogDir(home string) string { return filepath.Join(home, "logs", "watch") }
+
+// RotatingLog is a size-capped JSON-lines log. The zero MaxBytes and Keep take the defaults.
+type RotatingLog struct {
+	Dir      string
+	MaxBytes int64
+	Keep     int
+	Now      func() time.Time
+
+	mu sync.Mutex
+}
+
+// Event writes one line; failures are dropped, so logging never stops a pass.
+func (l *RotatingLog) Event(event string, fields map[string]any) { _ = l.Write(event, fields) }
+
+// Write writes one line {"ts","event",fields...}, rotating first when the line would pass the cap.
+func (l *RotatingLog) Write(event string, fields map[string]any) error {
+	now := time.Now
+	if l.Now != nil {
+		now = l.Now
+	}
+	rec := map[string]any{}
+	for k, v := range fields {
+		rec[k] = v
+	}
+	rec["ts"], rec["event"] = now().UTC().Format(time.RFC3339), event
+	line, err := json.Marshal(rec)
+	if err != nil {
+		return err
+	}
+	line = append(line, '\n')
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if err = os.MkdirAll(l.Dir, 0o700); err != nil {
+		return err
+	}
+	p := filepath.Join(l.Dir, logName)
+	if fi, serr := os.Stat(p); serr == nil && fi.Size()+int64(len(line)) > l.max() {
+		if err = l.rotate(); err != nil {
+			return err
+		}
+	}
+	f, err := os.OpenFile(p, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		return err
+	}
+	if _, err = f.Write(line); err != nil {
+		_ = f.Close()
+		return err
+	}
+	return f.Close()
+}
+
+func (l *RotatingLog) max() int64 {
+	if l.MaxBytes > 0 {
+		return l.MaxBytes
+	}
+	return DefaultLogBytes
+}
+
+// rotate shifts watch.log.(n-1) to watch.log.n down to watch.log -> watch.log.1; the oldest is dropped.
+func (l *RotatingLog) rotate() error {
+	keep := l.Keep
+	if keep <= 0 {
+		keep = DefaultLogKeep
+	}
+	base := filepath.Join(l.Dir, logName)
+	_ = os.Remove(fmt.Sprintf("%s.%d", base, keep))
+	for i := keep - 1; i >= 1; i-- {
+		from := fmt.Sprintf("%s.%d", base, i)
+		if _, err := os.Stat(from); err == nil {
+			if err = os.Rename(from, fmt.Sprintf("%s.%d", base, i+1)); err != nil {
+				return err
+			}
+		}
+	}
+	return os.Rename(base, base+".1")
+}
+
+// Heartbeat returns a writer of dir/heartbeat: the time of the last pass, replaced atomically.
+func Heartbeat(dir string) func(time.Time) error {
+	return func(at time.Time) error {
+		if err := os.MkdirAll(dir, 0o700); err != nil {
+			return err
+		}
+		tmp, err := os.CreateTemp(dir, ".heartbeat-*")
+		if err != nil {
+			return err
+		}
+		defer func() { _ = os.Remove(tmp.Name()) }()
+		if _, err = tmp.WriteString(at.UTC().Format(time.RFC3339) + "\n"); err != nil {
+			_ = tmp.Close()
+			return err
+		}
+		if err = tmp.Close(); err != nil {
+			return err
+		}
+		return os.Rename(tmp.Name(), filepath.Join(dir, heartbeatName))
+	}
+}
diff --git a/free/ci/internal/watch/logs_test.go b/free/ci/internal/watch/logs_test.go
new file mode 100644
index 000000000..0c17101b0
--- /dev/null
+++ b/free/ci/internal/watch/logs_test.go
@@ -0,0 +1,63 @@
+package watch
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+)
+
+func TestRotatingLog(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "logs", "watch")
+	l := &RotatingLog{Dir: dir, MaxBytes: 200, Keep: 2}
+	for i := 0; i < 20; i++ {
+		if err := l.Write("pass", map[string]any{"n": i, "pad": strings.Repeat("x", 40)}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, name := range []string{"watch.log", "watch.log.1", "watch.log.2"} {
+		fi, err := os.Stat(filepath.Join(dir, name))
+		if err != nil || fi.Size() > 200 || fi.Mode().Perm() != 0o600 {
+			t.Fatalf("%s: %v %v", name, fi, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(dir, "watch.log.3")); !os.IsNotExist(err) {
+		t.Fatal("only Keep rotated files are kept")
+	}
+	b, _ := os.ReadFile(filepath.Join(dir, "watch.log"))
+	for _, line := range strings.Split(strings.TrimSpace(string(b)), "\n") {
+		var rec map[string]any
+		if err := json.Unmarshal([]byte(line), &rec); err != nil || rec["event"] != "pass" || rec["ts"] == "" {
+			t.Fatalf("line %q", line)
+		}
+	}
+	if err := Heartbeat(dir)(t0); err != nil {
+		t.Fatal(err)
+	}
+	if b, _ = os.ReadFile(filepath.Join(dir, "heartbeat")); strings.TrimSpace(string(b)) != "2026-10-28T12:00:00Z" {
+		t.Fatalf("heartbeat %q", b)
+	}
+}
+
+func TestKeysDecode(t *testing.T) {
+	specs := map[string]policy.KeySpec{}
+	for _, k := range Keys() {
+		specs[k.Key] = k
+	}
+	for key, raw := range map[string]string{KeyBranches: `["release/*","dev"]`, KeyMaxBranches: `20`, KeyRetryGap: `"10m"`, KeyStatusContext: `"nself-ci/watch"`, KeyDrainSec: `60`} {
+		if _, err := specs[key].Decode([]byte(raw)); err != nil {
+			t.Errorf("%s %s: %v", key, raw, err)
+		}
+	}
+	for key, raw := range map[string]string{KeyBranches: `"main"`, KeyMaxBranches: `-1`, KeyRetryGap: `"5s"`, KeyStatusContext: `"other"`, KeyRetryMax: `1.5`} {
+		if _, err := specs[key].Decode([]byte(raw)); err == nil {
+			t.Errorf("%s %s accepted", key, raw)
+		}
+	}
+	if errs := RegistrationErrors(); len(errs) != 0 {
+		t.Fatal(errs)
+	}
+}
diff --git a/free/ci/internal/watch/loop.go b/free/ci/internal/watch/loop.go
new file mode 100644
index 000000000..c8096a9a3
--- /dev/null
+++ b/free/ci/internal/watch/loop.go
@@ -0,0 +1,63 @@
+package watch
+
+// Purpose: the watch loop (P7-AUTO-11): passes every Interval, offset per host and jittered so the hosts
+//          of a fleet do not poll in step, held back until a recorded quota reset.
+// Inputs:  a context that SIGTERM cancels; once.
+// Outputs: one PassReport per pass to the caller's sink.
+// Constraints: no sleep outside the injected After; the first pass of a long-running loop waits the
+//          host's phase offset (a stable hash of the host name, under one Interval); each later wait is
+//          Interval x [0.9, 1.1); a cancelled context ends the loop after the pass in flight has drained.
+
+import (
+	"context"
+	"hash/fnv"
+	"time"
+)
+
+// Offset is this host's phase inside one Interval: stable for a host name, different between hosts.
+func (w *Watcher) Offset() time.Duration {
+	h := fnv.New64a()
+	_, _ = h.Write([]byte(w.C.Host))
+	if w.C.Interval <= 0 {
+		return 0
+	}
+	return time.Duration(h.Sum64() % uint64(w.C.Interval))
+}
+
+// Next is the wait before the pass after one that ended at now.
+func (w *Watcher) Next(now time.Time) time.Duration {
+	j := 0.5
+	if w.P.Jitter != nil {
+		j = w.P.Jitter()
+	}
+	d := time.Duration(float64(w.C.Interval) * (0.9 + 0.2*j))
+	if q := w.QuotaUntil(); q.After(now) && q.Sub(now) > d {
+		d = q.Sub(now)
+	}
+	return d
+}
+
+// Run passes until ctx is cancelled, or once. sink receives every report (nil: discarded).
+func (w *Watcher) Run(ctx context.Context, once bool, sink func(PassReport)) {
+	if !once {
+		select {
+		case <-ctx.Done():
+			return
+		case <-w.after(w.Offset()):
+		}
+	}
+	for {
+		rep := w.Pass(ctx)
+		if sink != nil {
+			sink(rep)
+		}
+		if once || ctx.Err() != nil {
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-w.after(w.Next(rep.At)):
+		}
+	}
+}
diff --git a/free/ci/internal/watch/run.go b/free/ci/internal/watch/run.go
new file mode 100644
index 000000000..c805279e5
--- /dev/null
+++ b/free/ci/internal/watch/run.go
@@ -0,0 +1,130 @@
+package watch
+
+// Purpose: one claimed attempt (P7-AUTO-11): run it under the SIGTERM drain, read the ledger back, and
+//          post the one result, aggregating the residual checks of a hosted use.
+// Inputs:  the claimed Head, its Job and the hosted decision.
+// Outputs: a Decision with Action run; the result status through report.Reporter; on a pinned
+//          repository a residual failure also raises the notifier failure alert.
+// Constraints: a cancelled parent context waits watch.drain_sec for the attempt, then cancels it, so the
+//          attempt ends cancelled or finished and the coordinator releases its lease; the result is posted
+//          only while this host's claim still holds (claims.MayPublish), else the attempt is fenced and
+//          nothing is posted; a cancelled attempt ends as `error` so its claim is closed, not orphaned;
+//          an unpinned hosted use posts nself-ci as the aggregate (failure when either part failed); a
+//          pinned one posts nself-ci/residual and never touches the Actions result.
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/claims"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+// postTimeout bounds the read-back and the result post after a drain cancelled the pass.
+const postTimeout = 30 * time.Second
+
+// run executes j for h and posts its result.
+func (w *Watcher) run(ctx context.Context, h Head, j Job, hu *hostedUse, rep *PassReport) Decision {
+	d := Decision{Repo: h.Repo, SHA: h.SHA, Action: "run", Context: j.Context}
+	w.log("run", map[string]any{"repo": h.Repo, "sha": h.SHA, "context": j.Context, "residual": len(j.Only)})
+	var out Outcome
+	if hu != nil && hu.use && len(j.Only) == 0 {
+		out = Outcome{State: report.Success, Description: "hosted result"} // nothing residual: the aggregate is the hosted result
+	} else {
+		out = w.attempt(ctx, j)
+	}
+	pctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), postTimeout)
+	defer cancel()
+	in, err := w.history(pctx, h, j.Context)
+	if err != nil || !claims.MayPublish(in) {
+		d.Reason = "fenced"
+		w.log("fenced", map[string]any{"repo": h.Repo, "sha": h.SHA})
+		return d
+	}
+	state, desc := w.aggregate(out, hu, j.Context)
+	attempt := 1
+	for _, s := range in.Statuses {
+		if s.Context == j.Context && s.State == "error" && trusted(in, s.Creator) {
+			attempt++
+		}
+	}
+	desc = fmt.Sprintf("%s host=%s attempt=%d", desc, w.C.Host, attempt)
+	owner, repo, _ := strings.Cut(h.Repo, "/")
+	st := report.Status{Owner: owner, Repo: repo, Revision: h.SHA, State: state, Description: report.Truncate(desc), StatusContext: j.Context}
+	if err := w.P.Reporter.Post(pctx, st); err != nil {
+		d.Reason = "post_failed"
+		rep.Errors = append(rep.Errors, h.Repo+"@"+short(h.SHA)+": result not posted")
+		return d
+	}
+	d.State = string(state)
+	if j.Context == ResidualContext && state != report.Success && w.P.Alert != nil {
+		w.P.Alert(pctx, h, "residual checks "+string(state)+" on "+short(h.SHA))
+	}
+	w.log("result", map[string]any{"repo": h.Repo, "sha": h.SHA, "context": j.Context, "state": string(state), "attempt": attempt})
+	return d
+}
+
+func trusted(in claims.Inputs, creator string) bool {
+	for _, t := range in.Trusted {
+		if t != "" && t == creator {
+			return true
+		}
+	}
+	return false
+}
+
+// aggregate turns the attempt into the posted state. On the result context of a hosted use the hosted
+// conclusion is folded in; elsewhere the attempt stands.
+func (w *Watcher) aggregate(out Outcome, hu *hostedUse, ctxName string) (report.State, string) {
+	state, desc := out.State, out.Description
+	if !state.Valid() || state == report.Pending {
+		state = report.Error
+	}
+	if out.Cancelled {
+		state, desc = report.Error, "cancelled: the watcher stopped"
+	}
+	if hu == nil || !hu.use || ctxName == ResidualContext {
+		return state, desc
+	}
+	switch {
+	case hu.failed:
+		return report.Failure, "hosted run failed"
+	case state == report.Success:
+		return report.Success, "hosted run and residual checks passed"
+	case state == report.Failure:
+		return report.Failure, "residual checks failed"
+	}
+	return state, desc
+}
+
+// attempt runs j; a SIGTERM (ctx cancelled) waits watch.drain_sec before the attempt is cancelled.
+func (w *Watcher) attempt(ctx context.Context, j Job) Outcome {
+	runCtx, cancel := context.WithCancel(context.WithoutCancel(ctx))
+	defer cancel()
+	done := make(chan struct{})
+	defer close(done)
+	go func() {
+		select {
+		case <-done:
+			return
+		case <-ctx.Done():
+		}
+		w.log("drain", map[string]any{"repo": j.Head.Repo, "sha": j.Head.SHA, "drain_sec": w.C.Drain.Seconds()})
+		select {
+		case <-done:
+		case <-w.after(w.C.Drain):
+			cancel()
+		}
+	}()
+	out, err := w.P.Runner.Run(runCtx, j)
+	if runCtx.Err() != nil {
+		out.Cancelled = true
+	}
+	if err != nil && !out.Cancelled {
+		w.log("run_error", map[string]any{"repo": j.Head.Repo, "sha": j.Head.SHA, "error": err.Error()})
+		return Outcome{State: report.Error, Description: "infrastructure error"}
+	}
+	return out
+}
diff --git a/free/ci/internal/watch/types.go b/free/ci/internal/watch/types.go
new file mode 100644
index 000000000..9593db954
--- /dev/null
+++ b/free/ci/internal/watch/types.go
@@ -0,0 +1,169 @@
+// Package watch is the PERSONAL-mode trigger source `nself ci serve watch` (ADR 0032 decision 4,
+// P7-AUTO-11): an outbound-only poller that discovers heads through the HOST-17 head scan, claims a
+// commit on the provider's status ledger, runs it through the same coordinator path as
+// `nself ci --trigger watch`, and posts the one result. It opens no listener and owns no executor,
+// store or status writer: every effect goes through a port the caller wires.
+package watch
+
+// Purpose: the vocabulary of the watcher: its settings, a candidate head, the ports it calls and the
+//          per-pass report.
+// Inputs:  none (types only).
+// Outputs: Config, Head, Scanner, Runner, Job, Outcome, Ports, PassReport, Skip.
+// Constraints: no network import (architecture autoNoDirectIO); a port left nil takes the safe answer
+//          named on its field.
+
+import (
+	"context"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/hostedtier"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+// Config is the resolved watch.* keys plus the claim-ledger settings of this host.
+type Config struct {
+	Repos         []string      // owner/repo names to watch
+	Interval      time.Duration // pass cadence (providers.github.poll_interval or --interval)
+	Branches      []string      // watch.branches: extra branch names or globs
+	MaxBranches   int           // watch.max_branches
+	BranchDays    int           // watch.branch_days
+	RetryMax      int           // watch.retry_max: retries of an error result
+	RetryGap      time.Duration // watch.retry_gap
+	StatusContext string        // watch.status_context: overrides the resolved result context
+	Drain         time.Duration // watch.drain_sec: how long SIGTERM waits for a running attempt
+	Host          string        // this host's station name
+	Incarnation   string        // this process's incarnation (a claim names both)
+	Hosts         []string      // the watch hosts of the fleet; the first sorted one is preferred
+	Preferred     string        // an explicit preferred host
+	Trusted       []string      // creators whose statuses count (the station login first)
+	Step          time.Duration // how long a non-preferred host waits before it takes a commit
+	RunLimit      time.Duration // a claim with no status for RunLimit+claims.DeadGrace is dead
+}
+
+// Head is one candidate commit found by the scan.
+type Head struct {
+	Repo      string
+	SHA       string
+	Branch    string // branch heads; "" for a pull request
+	Default   bool
+	Protected bool
+	Extra     bool // selected by watch.branches
+	PR        int
+	Fork      bool // a pull request from another (or an unknown) repository
+	// Trust is the TRUST source class of the head (owner, collaborator or untrusted).
+	Trust       model.TrustClass
+	CommittedAt time.Time
+	Facts       model.TriggerFacts // kind api, source watch, auth per-repo
+}
+
+// Scan is one repository's discovery result.
+type Scan struct {
+	Heads       []Head
+	NotModified bool // every conditional read answered 304: the previous heads stand
+}
+
+// QuotaError stops a pass: the provider refused for quota until RetryAt.
+type QuotaError struct{ RetryAt time.Time }
+
+func (q *QuotaError) Error() string {
+	return "watch: quota reached, retry at " + q.RetryAt.UTC().Format(time.RFC3339)
+}
+
+// Scanner discovers the candidate heads of one repository (the HOST-17 head scan).
+type Scanner interface {
+	Scan(ctx context.Context, repo string) (Scan, error)
+}
+
+// Job is one attempt the runner executes.
+type Job struct {
+	Head    Head
+	Context string   // the context the result goes to
+	Only    []string // the residual check ids of a hosted use; empty means the whole pipeline
+	// Isolated asks for an isolated runner (a collaborator head); the runner must refuse otherwise.
+	Isolated bool
+}
+
+// Outcome is the state an attempt ended with.
+type Outcome struct {
+	State       report.State // success, failure or error
+	Description string
+	Cancelled   bool // the attempt was cancelled by the drain
+}
+
+// Runner runs one commit through the coordinator path (Options.Record set, trigger watch).
+type Runner interface {
+	Run(ctx context.Context, j Job) (Outcome, error)
+}
+
+// Hosted decides whether the repository's own hosted run stands (P7-AUTO-07).
+type Hosted interface {
+	Decide(ctx context.Context, repo, sha string, pushed time.Time) hostedtier.Result
+}
+
+// Ports are the watcher's effects. Ledger, Reporter, Scanner and Runner are required.
+type Ports struct {
+	Scanner  Scanner
+	Ledger   report.Ledger   // claims and the status history (P7-AUTO-10)
+	Reporter report.Reporter // the one status writer
+	Runner   Runner
+	// ResultContext resolves the result context of a repository (report.ResolveResultContext).
+	// nil: the advisory nself-ci/watch, as for an unreadable protection.
+	ResultContext func(ctx context.Context, owner, repo, override string) string
+	Hosted        Hosted                                                // nil: always hand over
+	Ready         func(ctx context.Context) (bool, []string)            // nil: not ready
+	Isolated      func(ctx context.Context) bool                        // nil: no isolated runner
+	TeamOwned     func(ctx context.Context, repo string) bool           // nil: personal
+	Alert         func(ctx context.Context, h Head, description string) // the notifier failure alert
+	Idle          func(ctx context.Context) (bool, error)               // one due background pipeline
+	Publish       func(doc demand.Document) error                       // the demand document
+	Heartbeat     func(at time.Time) error
+	Log           func(event string, fields map[string]any)
+	Now           func() time.Time                       // nil: time.Now
+	After         func(d time.Duration) <-chan time.Time // nil: time.After
+	Jitter        func() float64                         // in [0,1); nil: no random part
+}
+
+// Skip reasons a pass reports for a head it did not run.
+const (
+	SkipFinal     = "final"
+	SkipClaimed   = "claimed"
+	SkipWait      = "wait"
+	SkipHosted    = "hosted_wait"
+	SkipHostedUse = "hosted_use"
+	SkipFork      = "fork"
+	SkipTeam      = "team_owned"
+	SkipIsolated  = "needs isolated runner"
+	SkipApproval  = "needs approval"
+	SkipNotReady  = "not_ready"
+	SkipBusy      = "busy" // this pass already ran a commit
+	SkipLost      = "lost"
+	SkipError     = "ledger_error"
+)
+
+// Decision is what a pass did with one head.
+type Decision struct {
+	Repo    string `json:"repo"`
+	SHA     string `json:"sha"`
+	Action  string `json:"action"` // run, skip, post
+	Reason  string `json:"reason,omitempty"`
+	Code    string `json:"code,omitempty"`
+	Context string `json:"context,omitempty"`
+	State   string `json:"state,omitempty"`
+}
+
+// PassReport is one pass.
+type PassReport struct {
+	At         time.Time  `json:"at"`
+	Ready      bool       `json:"ready"`
+	ReadyWhy   []string   `json:"ready_why"`
+	Decisions  []Decision `json:"decisions"`
+	Ran        int        `json:"ran"`
+	Queued     int        `json:"queued"`
+	Held       int        `json:"held"`
+	Duplicates int        `json:"duplicates"`
+	QuotaUntil time.Time  `json:"quota_until,omitzero"`
+	Idle       bool       `json:"idle_started"`
+	Errors     []string   `json:"errors"`
+}
diff --git a/free/ci/internal/watch/watch_test.go b/free/ci/internal/watch/watch_test.go
new file mode 100644
index 000000000..efee7e3b2
--- /dev/null
+++ b/free/ci/internal/watch/watch_test.go
@@ -0,0 +1,196 @@
+package watch
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+)
+
+func only(t *testing.T, rep PassReport) Decision {
+	t.Helper()
+	if len(rep.Decisions) != 1 {
+		t.Fatalf("decisions %+v", rep.Decisions)
+	}
+	return rep.Decisions[0]
+}
+
+func TestCandidateRules(t *testing.T) {
+	newer, older := t0.Add(-time.Hour), t0.Add(-2*time.Hour)
+	heads := []Head{
+		{SHA: sha(1), Branch: "feat/x", Extra: true, CommittedAt: older},
+		{SHA: sha(2), PR: 7},
+		{SHA: sha(3), Branch: "release", Protected: true},
+		{SHA: sha(4), Branch: "feat/y", Extra: true, CommittedAt: newer},
+		{SHA: sha(5), Branch: "main", Default: true, Protected: true},
+	}
+	Order(heads)
+	var got []string
+	for _, h := range heads {
+		got = append(got, h.SHA[39:])
+	}
+	if strings.Join(got, "") != "53241" {
+		t.Fatalf("order %v: want default, protected, pull request, then extra newest first", got)
+	}
+
+	r := newRig(t, ownerHead("o/r", 1), ownerHead("o/r", 2), Head{Repo: "o/r", SHA: sha(3), PR: 3, Trust: model.TrustClass("untrusted")})
+	rep := r.w.Pass(context.Background())
+	if rep.Ran != 1 || r.runner.count() != 1 || r.runner.jobs[0].Head.SHA != sha(1) {
+		t.Fatalf("one commit per pass, the first in order: %+v", rep.Decisions)
+	}
+	if rep.Decisions[1].Reason != SkipBusy || rep.Decisions[2].Reason != SkipApproval {
+		t.Fatalf("decisions %+v", rep.Decisions)
+	}
+	if r.runner.jobs[0].Context != report.Context || len(r.runner.jobs[0].Only) != 0 {
+		t.Fatalf("job %+v", r.runner.jobs[0])
+	}
+	if got := r.gh.states(sha(1), report.Context); len(got) != 1 || got[0] != "success" {
+		t.Fatalf("result %v", got)
+	}
+	rep = r.w.Pass(context.Background())
+	if rep.Decisions[0].Reason != SkipFinal || rep.Decisions[1].Action != "run" {
+		t.Fatalf("second pass %+v", rep.Decisions)
+	}
+}
+
+func TestForkNeverRuns(t *testing.T) {
+	r := newRig(t, Head{Repo: "o/r", SHA: sha(1), PR: 4, Fork: true, Trust: model.TrustClass("owner")})
+	r.w.P.Isolated = func(context.Context) bool { return true }
+	for i := 0; i < 3; i++ {
+		if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipFork {
+			t.Fatalf("decision %+v", d)
+		}
+	}
+	if r.runner.count() != 0 || r.gh.claims != 0 || len(r.gh.posts) != 0 {
+		t.Fatal("a fork head must never be claimed, run or reported")
+	}
+}
+
+func TestCollaboratorNeedsIsolatedRunner(t *testing.T) {
+	h := Head{Repo: "o/r", SHA: sha(1), PR: 2, Trust: model.TrustClass("collaborator")}
+	r := newRig(t, h)
+	d := only(t, r.w.Pass(context.Background()))
+	if d.Reason != SkipIsolated || d.Code != CodeIsolated || r.runner.count() != 0 || r.gh.claims != 0 {
+		t.Fatalf("no isolated runner: %+v, runs %d", d, r.runner.count())
+	}
+	r.w.P.Isolated = func(context.Context) bool { return true }
+	if d = only(t, r.w.Pass(context.Background())); d.Action != "run" || !r.runner.jobs[0].Isolated {
+		t.Fatalf("isolated runner present: %+v", d)
+	}
+}
+
+func TestTeamOwnedSkipped(t *testing.T) {
+	r := newRig(t, ownerHead("o/r", 1))
+	r.w.P.TeamOwned = func(_ context.Context, repo string) bool { return repo == "o/r" }
+	if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipTeam {
+		t.Fatalf("decision %+v", d)
+	}
+	if r.runner.count() != 0 || r.gh.claims != 0 || len(r.gh.posts) != 0 {
+		t.Fatal("a personal watcher must not post for a team-owned project")
+	}
+}
+
+func TestNotReadyNoClaim(t *testing.T) {
+	r := newRig(t, ownerHead("o/r", 1))
+	var docs []demand.Document
+	r.w.P.Ready = func(context.Context) (bool, []string) { return false, []string{"load high"} }
+	r.w.P.Publish = func(d demand.Document) error { docs = append(docs, d); return nil }
+	if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipNotReady {
+		t.Fatalf("decision %+v", d)
+	}
+	if r.gh.claims != 0 || r.runner.count() != 0 {
+		t.Fatal("a not-ready host claims nothing")
+	}
+	if len(docs) != 1 || docs[0].Ready || docs[0].Queued != 1 || !docs[0].Watcher.Alive || docs[0].ReadyWhy[0] != "load high" {
+		t.Fatalf("demand %+v", docs)
+	}
+}
+
+func TestStatusContextPinned(t *testing.T) {
+	r := newRig(t, ownerHead("o/r", 1))
+	r.w.P.ResultContext = func(context.Context, string, string, string) string { return report.WatchContext }
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(1), report.WatchContext); len(got) != 1 || got[0] != "success" {
+		t.Fatalf("advisory result %v", got)
+	}
+	if got := r.gh.states(sha(1), report.Context); len(got) != 0 {
+		t.Fatalf("a pinned repository never gets nself-ci: %v", got)
+	}
+	r = newRig(t, ownerHead("o/r", 2))
+	r.w.P.ResultContext = nil // protection unreadable: treated as pinned
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(2), report.WatchContext); len(got) != 1 {
+		t.Fatalf("unreadable protection: %v", got)
+	}
+	r = newRig(t, ownerHead("o/r", 3))
+	r.w.P.ResultContext = func(context.Context, string, string, string) string { return report.WatchContext }
+	r.w.C.StatusContext = report.Context // watch.status_context overrides
+	r.w.Pass(context.Background())
+	if got := r.gh.states(sha(3), report.Context); len(got) != 1 {
+		t.Fatalf("override: %v", got)
+	}
+}
+
+func TestRetryErrorNotFailure(t *testing.T) {
+	r := newRig(t, ownerHead("o/r", 1))
+	r.runner.state = func(int, Job) report.State { return report.Error }
+	for i := 0; i < 12; i++ { // two passes per retry gap, a little over an hour
+		r.w.Pass(context.Background())
+		r.gh.advance(5*time.Minute + time.Second)
+	}
+	if got := r.gh.states(sha(1), report.Context); len(got) != 4 || r.runner.count() != 4 {
+		t.Fatalf("an error is retried 3 times: results %v, runs %d", got, r.runner.count())
+	}
+	if r.gh.claims != 4 {
+		t.Fatalf("each retry posts a new claim: %d", r.gh.claims)
+	}
+	if d := only(t, r.w.Pass(context.Background())); d.Reason != SkipFinal {
+		t.Fatalf("after the budget the error stays final: %+v", d)
+	}
+	gaps := []time.Time{}
+	for _, s := range r.gh.st[sha(1)] {
+		if s.Context == report.Context {
+			gaps = append(gaps, s.CreatedAt)
+		}
+	}
+	for i := 1; i < len(gaps); i++ {
+		if gaps[i].Sub(gaps[i-1]) < DefaultRetryGap {
+			t.Fatalf("retries %v apart, want at least %v", gaps[i].Sub(gaps[i-1]), DefaultRetryGap)
+		}
+	}
+
+	r = newRig(t, ownerHead("o/r", 2))
+	r.runner.state = func(int, Job) report.State { return report.Failure }
+	for i := 0; i < 6; i++ {
+		r.w.Pass(context.Background())
+		r.gh.advance(11 * time.Minute)
+	}
+	if r.runner.count() != 1 {
+		t.Fatalf("a failure is never retried: %d runs", r.runner.count())
+	}
+}
+
+func TestQuotaStopsPass(t *testing.T) {
+	r := newRig(t, ownerHead("o/r", 1))
+	r.scan.err = &QuotaError{RetryAt: t0.Add(10 * time.Minute)}
+	rep := r.w.Pass(context.Background())
+	if !rep.QuotaUntil.Equal(t0.Add(10*time.Minute)) || len(rep.Decisions) != 0 || r.scan.calls != 1 {
+		t.Fatalf("quota pass %+v", rep)
+	}
+	r.scan.err = nil
+	r.gh.advance(5 * time.Minute)
+	if rep = r.w.Pass(context.Background()); r.scan.calls != 1 || len(rep.Decisions) != 0 {
+		t.Fatal("no scan before the recorded reset")
+	}
+	if n := r.w.Next(r.gh.clock()); n < 5*time.Minute {
+		t.Fatalf("the next pass waits for the reset: %v", n)
+	}
+	r.gh.advance(6 * time.Minute)
+	if rep = r.w.Pass(context.Background()); r.scan.calls != 2 || rep.Ran != 1 {
+		t.Fatalf("after the reset %+v", rep)
+	}
+}
diff --git a/free/ci/internal/watch/watcher.go b/free/ci/internal/watch/watcher.go
new file mode 100644
index 000000000..b02b377c1
--- /dev/null
+++ b/free/ci/internal/watch/watcher.go
@@ -0,0 +1,182 @@
+package watch
+
+// Purpose: one watch pass (P7-AUTO-11): discover the heads of every watched repository, consider them
+//          newest default-branch head first, run at most one, then start a due background pipeline when
+//          nothing ran, and publish the demand document and the heartbeat.
+// Inputs:  Config and Ports.
+// Outputs: PassReport; the demand document, heartbeat and log events through the ports.
+// Constraints: a quota error stops the pass and records the reset time; no scan is made before it; a
+//          304 pass reuses the previous heads; demand is published every pass, ready or not; a not-ready
+//          host claims nothing.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+)
+
+// Watcher is one host's watch loop. Build it with New.
+type Watcher struct {
+	C Config
+	P Ports
+
+	mu         sync.Mutex
+	heads      map[string][]Head    // the last complete scan per repository
+	firstSeen  map[string]time.Time // repo@sha -> provider time it was first seen without a final result
+	dups       map[string]bool      // repo@sha whose duplicate final was reported
+	quotaUntil time.Time
+}
+
+// New checks the required ports and fills the defaults of c.
+func New(c Config, p Ports) (*Watcher, error) {
+	if p.Scanner == nil || p.Ledger == nil || p.Reporter == nil || p.Runner == nil {
+		return nil, &Error{Code: CodeConfig, Message: "the watcher needs a scanner, a ledger, a reporter and a runner"}
+	}
+	if c.Host == "" || strings.ContainsAny(c.Host, " \t\n") || strings.ContainsAny(c.Incarnation, " \t\n") {
+		return nil, &Error{Code: CodeConfig, Message: "the watcher needs a host name without spaces"}
+	}
+	d := Defaults()
+	if c.Interval <= 0 {
+		c.Interval = d.Interval
+	}
+	if c.RetryGap <= 0 {
+		c.RetryGap = d.RetryGap
+	}
+	if c.Step <= 0 {
+		c.Step = d.Step
+	}
+	if c.RunLimit <= 0 {
+		c.RunLimit = d.RunLimit
+	}
+	if c.Incarnation == "" {
+		c.Incarnation = "i1"
+	}
+	return &Watcher{C: c, P: p, heads: map[string][]Head{}, firstSeen: map[string]time.Time{}, dups: map[string]bool{}}, nil
+}
+
+func (w *Watcher) now() time.Time {
+	if w.P.Now != nil {
+		return w.P.Now().UTC()
+	}
+	return time.Now().UTC()
+}
+
+func (w *Watcher) after(d time.Duration) <-chan time.Time {
+	if w.P.After != nil {
+		return w.P.After(d)
+	}
+	return time.After(d)
+}
+
+func (w *Watcher) log(event string, fields map[string]any) {
+	if w.P.Log != nil {
+		w.P.Log(event, fields)
+	}
+}
+
+// QuotaUntil is the recorded reset time of the last quota error (zero when none).
+func (w *Watcher) QuotaUntil() time.Time {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.quotaUntil
+}
+
+// Pass runs one pass.
+func (w *Watcher) Pass(ctx context.Context) PassReport {
+	rep := PassReport{At: w.now(), ReadyWhy: []string{}, Decisions: []Decision{}, Errors: []string{}}
+	if w.P.Ready != nil {
+		rep.Ready, rep.ReadyWhy = w.P.Ready(ctx)
+		if rep.ReadyWhy == nil {
+			rep.ReadyWhy = []string{}
+		}
+	} else {
+		rep.ReadyWhy = []string{"no readiness source"}
+	}
+	heads, stopped := w.discover(ctx, &rep)
+	if !stopped {
+		Order(heads)
+		ran := false
+		for _, h := range heads {
+			if ctx.Err() != nil {
+				break
+			}
+			d := w.consider(ctx, h, rep.Ready, ran, &rep)
+			if d.Action == "run" {
+				ran = true
+				rep.Ran++
+			}
+			rep.Decisions = append(rep.Decisions, d)
+		}
+		if !ran && rep.Ready && w.P.Idle != nil && ctx.Err() == nil {
+			started, err := w.P.Idle(ctx)
+			rep.Idle = started && err == nil
+			if err != nil {
+				rep.Errors = append(rep.Errors, "background: "+err.Error())
+			}
+		}
+	}
+	w.publish(rep)
+	w.log("pass", map[string]any{"ran": rep.Ran, "queued": rep.Queued, "held": rep.Held, "ready": rep.Ready, "decisions": len(rep.Decisions), "errors": len(rep.Errors)})
+	return rep
+}
+
+// discover returns the heads to consider; stopped is true when a quota error ended the pass.
+func (w *Watcher) discover(ctx context.Context, rep *PassReport) (heads []Head, stopped bool) {
+	w.mu.Lock()
+	until := w.quotaUntil
+	w.mu.Unlock()
+	if until.After(rep.At) {
+		rep.QuotaUntil = until
+		return nil, true
+	}
+	for _, repo := range w.C.Repos {
+		s, err := w.P.Scanner.Scan(ctx, repo)
+		var q *QuotaError
+		switch {
+		case errors.As(err, &q):
+			w.mu.Lock()
+			w.quotaUntil = q.RetryAt.UTC()
+			w.mu.Unlock()
+			rep.QuotaUntil = q.RetryAt.UTC()
+			rep.Errors = append(rep.Errors, fmt.Sprintf("%s: %s", CodeQuota, q.Error()))
+			w.log("quota", map[string]any{"repo": repo, "retry_at": q.RetryAt.UTC().Format(time.RFC3339)})
+			return nil, true
+		case err != nil:
+			rep.Errors = append(rep.Errors, repo+": "+err.Error())
+		case !s.NotModified:
+			for i := range s.Heads {
+				s.Heads[i].Repo = repo
+			}
+			w.mu.Lock()
+			w.heads[repo] = s.Heads
+			w.mu.Unlock()
+		}
+		w.mu.Lock()
+		heads = append(heads, w.heads[repo]...)
+		w.mu.Unlock()
+	}
+	return heads, false
+}
+
+// publish writes the demand document and the heartbeat; failures are logged, never fatal.
+func (w *Watcher) publish(rep PassReport) {
+	if w.P.Publish != nil {
+		doc := demand.Document{Host: w.C.Host, Queued: rep.Queued, Held: rep.Held, Ready: rep.Ready, ReadyWhy: rep.ReadyWhy,
+			Watcher: demand.Watcher{Alive: true, LastPass: rep.At.Format(time.RFC3339), IntervalSec: w.C.Interval.Seconds()}}
+		if err := w.P.Publish(doc); err != nil {
+			w.log("demand_error", map[string]any{"error": err.Error()})
+		}
+	}
+	if w.P.Heartbeat != nil {
+		if err := w.P.Heartbeat(rep.At); err != nil {
+			w.log("heartbeat_error", map[string]any{"error": err.Error()})
+		}
+	}
+}
+
+func key(h Head) string { return strings.ToLower(h.Repo) + "@" + h.SHA }
diff --git a/free/ci/internal/where/where.go b/free/ci/internal/where/where.go
new file mode 100644
index 000000000..ef6f23779
--- /dev/null
+++ b/free/ci/internal/where/where.go
@@ -0,0 +1,135 @@
+// Package where maps the `--where` flag to per-run policy values.
+//
+// Purpose: one pure function, Values, turns local|<node>|<pool>|hosted|auto|all
+// into the revision-scope values of the run scope (P7-AUTO-29). There is no
+// second placement path: the values go through sched.Place and dispatch.Admit
+// like any other run-scope value.
+// Inputs:  the flag text, what the operator has registered (Known) and the
+// kind of run (Opts).
+// Outputs: a Target (kind, values, notes) or an *Error carrying E797.
+// Constraints: pure, no I/O, no clock. A flag value can only narrow: a pool or
+// node outside the effective set is refused with the pool.excluded reason,
+// never widened. `auto` leaves sched.preset to the operator (the sched.preset
+// key admits only its closed preset names, so no constant is written here).
+package where
+
+import (
+	"encoding/json"
+	"fmt"
+	"slices"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/schedpolicy"
+)
+
+// CodeInvalid is E797: an unknown --where value, or `all` before a race hook exists.
+const CodeInvalid = "E797"
+
+func init() {
+	model.Register(model.Code{ID: CodeInvalid, Class: "usage", Summary: "--where value is unknown or not available",
+		Fix: "Use local, a node id, a pool id, hosted, auto or all (all needs a race hook); list targets with `nself ci nodes pools list`"})
+}
+
+// Kinds of target.
+const (
+	KindLocal  = "local"
+	KindNode   = "node"
+	KindPool   = "pool"
+	KindHosted = "hosted"
+	KindAuto   = "auto"
+	KindAll    = "all"
+)
+
+// ReasonPoolExcluded is the placement reason of a target outside the effective set.
+const ReasonPoolExcluded = "pool.excluded"
+
+// Known is what the operator has registered, as the caller read it.
+type Known struct {
+	Nodes     []string          // registered node ids (non-local)
+	Pools     []string          // pool ids a runner belongs to
+	Providers []string          // registered hosted provider ids
+	Effective []string          // pools.allow after the merge; nil means every pool
+	Excluded  map[string]string // node id -> reason it is outside the effective set
+}
+
+// Opts describes the run.
+type Opts struct {
+	Dev       bool // a dev run: pool narrowing goes to pools.dev, not pools.allow
+	RaceReady bool // a RaceHook is registered (run.RaceRegistered)
+}
+
+// Target is the mapped flag.
+type Target struct {
+	Kind   string
+	Values map[string]json.RawMessage
+	Notes  []string
+}
+
+// Error is an E797 refusal with the reasons that explain it.
+type Error struct {
+	Message string
+	Reasons []string
+}
+
+func (e *Error) Error() string {
+	if len(e.Reasons) == 0 {
+		return CodeInvalid + ": " + e.Message
+	}
+	return CodeInvalid + ": " + e.Message + " (" + strings.Join(e.Reasons, "; ") + ")"
+}
+
+func refuse(reasons []string, format string, a ...any) *Error {
+	return &Error{Message: fmt.Sprintf(format, a...), Reasons: reasons}
+}
+
+// HasRemote reports whether the operator registered a non-local node or a provider.
+func (k Known) HasRemote() bool { return len(k.Nodes) > 0 || len(k.Providers) > 0 }
+
+func put(key string, v any) map[string]json.RawMessage {
+	raw, _ := json.Marshal(v) // strings, bools and string lists always marshal
+	return map[string]json.RawMessage{key: raw}
+}
+
+// Values maps one --where value. Names are matched in this order: the six
+// reserved words, a registered node id, then a pool id.
+func Values(flag string, k Known, o Opts) (Target, error) {
+	switch flag {
+	case pools.Local:
+		return Target{Kind: KindLocal, Values: put(schedpolicy.KeyLocalOnly, true)}, nil
+	case "hosted":
+		if len(k.Providers) == 0 {
+			return Target{}, refuse([]string{"no hosted provider is registered"}, "--where hosted has no target")
+		}
+		ids := slices.Clone(k.Providers)
+		slices.Sort(ids)
+		return Target{Kind: KindHosted, Values: put(schedpolicy.KeyProvidersAllow, ids)}, nil
+	case "auto":
+		return Target{Kind: KindAuto}, nil
+	case "all":
+		if !o.RaceReady {
+			return Target{}, refuse(nil, "race not available")
+		}
+		return Target{Kind: KindAll}, nil
+	case "":
+		return Target{}, refuse(nil, "--where needs a value")
+	}
+	if slices.Contains(k.Nodes, flag) {
+		if why, out := k.Excluded[flag]; out {
+			return Target{}, refuse([]string{ReasonPoolExcluded + ": " + why}, "node %q is outside the effective set", flag)
+		}
+		return Target{Kind: KindNode, Values: put(schedpolicy.KeyRunner, flag)}, nil
+	}
+	if pools.ValidID(flag) && slices.Contains(k.Pools, flag) {
+		if k.Effective != nil && !slices.Contains(k.Effective, flag) {
+			return Target{}, refuse([]string{ReasonPoolExcluded + ": pool " + flag + " is not in pools.allow"}, "pool %q is outside the effective set", flag)
+		}
+		key := pools.KeyAllow
+		if o.Dev {
+			key = pools.KeyDev
+		}
+		return Target{Kind: KindPool, Values: put(key, []string{flag})}, nil
+	}
+	return Target{}, refuse(nil, "unknown value %q (local, a node id, a pool id, hosted, auto or all)", flag)
+}
diff --git a/free/ci/internal/where/where_test.go b/free/ci/internal/where/where_test.go
new file mode 100644
index 000000000..50a9c87ff
--- /dev/null
+++ b/free/ci/internal/where/where_test.go
@@ -0,0 +1,93 @@
+package where
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+var world = Known{Nodes: []string{"ms5", "lan1"}, Pools: []string{"lan", "gpu"}, Providers: []string{"github", "gitlab"}}
+
+func TestWhereMappingTable(t *testing.T) {
+	for _, tc := range []struct {
+		flag string
+		k    Known
+		o    Opts
+		kind string
+		want map[string]string
+	}{
+		{"local", world, Opts{}, KindLocal, map[string]string{"sched.overrides.local_only": `true`}},
+		{"ms5", world, Opts{}, KindNode, map[string]string{"sched.overrides.runner": `"ms5"`}},
+		{"lan", world, Opts{}, KindPool, map[string]string{"pools.allow": `["lan"]`}},
+		{"lan", world, Opts{Dev: true}, KindPool, map[string]string{"pools.dev": `["lan"]`}},
+		{"hosted", world, Opts{}, KindHosted, map[string]string{"sched.overrides.providers.allow": `["github","gitlab"]`}},
+		{"auto", world, Opts{}, KindAuto, nil},
+		{"all", world, Opts{RaceReady: true}, KindAll, nil},
+	} {
+		got, err := Values(tc.flag, tc.k, tc.o)
+		if err != nil || got.Kind != tc.kind || len(got.Values) != len(tc.want) {
+			t.Errorf("%s: %+v %v", tc.flag, got, err)
+			continue
+		}
+		for key, v := range tc.want {
+			if string(got.Values[key]) != v {
+				t.Errorf("%s: %s = %s want %s", tc.flag, key, got.Values[key], v)
+			}
+		}
+	}
+}
+
+func TestWhereRefusals(t *testing.T) {
+	for name, tc := range map[string]struct {
+		flag, sub string
+		k         Known
+	}{
+		"unknown":       {"nowhere", "unknown value", world},
+		"empty":         {"", "needs a value", world},
+		"no providers":  {"hosted", "no hosted provider", Known{}},
+		"pool excluded": {"gpu", "pool.excluded", Known{Pools: []string{"gpu", "lan"}, Effective: []string{"lan"}}},
+		"node excluded": {"ms5", "pool.excluded", Known{Nodes: []string{"ms5"}, Excluded: map[string]string{"ms5": "pool lan only"}}},
+	} {
+		_, err := Values(tc.flag, tc.k, Opts{})
+		if err == nil || !strings.HasPrefix(err.Error(), CodeInvalid) || !strings.Contains(err.Error(), tc.sub) {
+			t.Errorf("%s: %v", name, err)
+		}
+	}
+}
+
+func TestWhereAllNotYet(t *testing.T) {
+	_, err := Values("all", world, Opts{})
+	if err == nil || err.Error() != "E797: race not available" {
+		t.Fatalf("got %v", err)
+	}
+}
+
+// TestWhereProjectFixedWins: a project-fixed runner beats `--where <other>`;
+// the revision value is ignored and reported by the merge.
+func TestWhereProjectFixedWins(t *testing.T) {
+	tgt, err := Values("ms5", world, Opts{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	fixed, _ := json.Marshal("lan1")
+	reg, err := trust.NewRegistry(policy.Default.Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	eff, _, err := reg.Merge("",
+		trust.Scope{Kind: trust.SourceProject, Values: map[string]json.RawMessage{"sched.overrides.runner": fixed}},
+		trust.Scope{Kind: trust.SourceRun, Values: tgt.Values})
+	if err != nil {
+		t.Fatal(err)
+	}
+	v, _, _ := eff.Value("sched.overrides.runner")
+	if v != "lan1" {
+		t.Fatalf("runner = %v, want the project's lan1", v)
+	}
+	if len(eff.Ignored()) == 0 {
+		t.Error("the ignored revision value must be reported")
+	}
+}
diff --git a/free/ci/plugin.json b/free/ci/plugin.json
index 0868279e8..8fa22a91c 100644
--- a/free/ci/plugin.json
+++ b/free/ci/plugin.json
@@ -17,10 +17,35 @@
   "commands": {
     "binary": "nself-ci",
     "command": "ci",
-    "json": "none",
+    "confirm": {
+      "flags": []
+    },
+    "json": "envelope",
     "output": "document",
     "side_effect": "remote",
     "subcommands": [
+      {
+        "args": [
+          {
+            "name": "subcommand"
+          },
+          {
+            "name": "name"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "artifacts",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List, show, fetch and prune stored run artifacts"
+      },
       {
         "args": [
           {
@@ -77,200 +102,2308 @@
         "summary": "Build a signed release artifact locally (Android only)"
       },
       {
+        "args": [
+          {
+            "name": "fingerprint"
+          }
+        ],
         "flags": [
           {
-            "default": "http://localhost:3844",
-            "name": "url",
-            "type": "string",
-            "usage": "Forgejo base URL"
+            "name": "by",
+            "type": "string"
+          },
+          {
+            "name": "reason",
+            "type": "string"
+          },
+          {
+            "name": "repo",
+            "type": "string"
           }
         ],
         "json": "none",
-        "name": "forgejo",
+        "name": "config ignore add",
         "output": "document",
-        "side_effect": "read",
-        "summary": "Show Forgejo server health (ops profile)"
+        "side_effect": "write",
+        "summary": "Append a reviewed fingerprint to .gitleaksignore (--reason required)"
       },
       {
         "flags": [
           {
-            "default": ":3845",
-            "name": "addr",
-            "type": "string",
-            "usage": "Listen address (host:port). Port 3845 = nself-ci-serve per F10 port registry"
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
           },
           {
-            "default": "false",
-            "name": "allow-unsandboxed",
-            "side_effect": "destructive",
-            "type": "bool",
-            "usage": "DANGEROUS: run the gate directly on this host when Docker is unavailable, instead of refusing the job. Default: refuse."
+            "name": "repo",
+            "type": "string"
           },
           {
-            "default": "[]",
-            "name": "allowed-repos",
-            "type": "stringSlice",
-            "usage": "Comma-separated or repeatable \"owner/repo\" allowlist. Default: empty, which rejects every job (fail-closed, no \"allow all\")."
+            "name": "write",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "config migrate",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Migrate .nself/ci.yaml to the current schema (--write applies)"
+      },
+      {
+        "flags": [
+          {
+            "name": "config",
+            "type": "string"
           },
           {
-            "default": "2",
-            "name": "concurrency",
-            "type": "int",
-            "usage": "Max concurrent CI jobs"
+            "name": "home",
+            "type": "string"
           },
           {
-            "default": "false",
-            "name": "insecure",
-            "type": "bool",
-            "usage": "DANGEROUS: start without a webhook secret (disables signature verification). Default: refuse to start when no secret is configured."
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
           },
           {
-            "name": "secret",
-            "secret": true,
-            "type": "string",
-            "usage": "HMAC-SHA256 webhook secret (overrides GITHUB_WEBHOOK_SECRET env)"
+            "name": "no-status",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
           },
           {
-            "default": "600",
             "name": "timeout",
-            "type": "int",
-            "usage": "Per-job timeout in seconds"
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "config show",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show the resolved CI configuration"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
           },
           {
-            "default": "false",
-            "name": "verbose",
-            "shorthand": "v",
-            "type": "bool",
-            "usage": "Verbose gate output"
+            "name": "alert",
+            "type": "bool"
           },
           {
-            "default": "/tmp/nself-ci-workdirs",
-            "name": "workdir",
-            "type": "string",
-            "usage": "Base directory for ephemeral checkout workdirs"
+            "name": "nodes",
+            "type": "bool"
+          },
+          {
+            "name": "providers",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "selftest",
+            "type": "bool"
           }
         ],
-        "json": "none",
-        "name": "serve",
-        "output": "stream",
-        "side_effect": "write",
-        "summary": "Start the nself-ci webhook listener daemon (port 3845)"
+        "json": "envelope",
+        "name": "doctor",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Check the CI environment, nodes and providers (--selftest [--alert] for an unattended host)"
       },
       {
         "args": [
           {
-            "name": "search-root"
+            "name": "revision"
           }
         ],
         "flags": [
           {
-            "name": "env",
-            "type": "string",
-            "usage": "Target environment: local"
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
           },
           {
-            "name": "gateway",
-            "type": "string",
-            "usage": "Explicit gateway base URL (e.g. http://host:3761)"
+            "name": "pipeline",
+            "type": "string"
           },
           {
-            "name": "v",
-            "type": "bool",
-            "usage": "Print each command before running"
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "evidence",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show the evidence document of a revision"
+      },
+      {
+        "args": [
+          {
+            "name": "revision"
+          }
+        ],
+        "flags": [
+          {
+            "name": "at-revision",
+            "type": "string"
           },
           {
-            "default": "300",
-            "name": "timeout",
-            "type": "int",
-            "usage": "Per-step timeout in seconds"
+            "name": "file",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "default": "required",
+            "name": "policy",
+            "type": "string"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "stream",
+            "type": "bool"
           }
         ],
-        "json": "none",
-        "name": "run",
+        "json": "envelope",
+        "name": "evidence verify",
         "output": "document",
-        "side_effect": "remote",
-        "summary": "Discover .ci.yaml manifests and run their stages (pipeline)"
+        "side_effect": "read",
+        "summary": "Verify the evidence of a revision against the policy"
       },
       {
+        "args": [
+          {
+            "name": "job"
+          }
+        ],
         "flags": [
           {
-            "name": "github-url",
-            "type": "string",
-            "usage": "Repo or org URL runners register against, e.g. https://github.com/nself-org/cli"
+            "name": "base",
+            "type": "string"
           },
           {
-            "default": "[]",
-            "name": "host",
-            "type": "stringSlice",
-            "usage": "SSH target(s) user@host to provision (repeatable). Default: this machine."
+            "name": "config",
+            "type": "string"
           },
           {
-            "name": "install-root",
-            "type": "string",
-            "usage": "Base install directory (default: /opt/actions-runner)"
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
           },
           {
-            "default": "1",
-            "name": "instances",
-            "type": "int",
-            "usage": "Number of runner instances to install on this host"
+            "name": "max-queue",
+            "type": "string"
           },
           {
-            "default": "false",
-            "name": "json",
-            "type": "bool",
-            "usage": "V15 only (NSELF_V15=1): print one v1 JSON envelope; in v1.4 the flag is refused as today"
+            "name": "pipeline",
+            "type": "string"
           },
           {
-            "default": "[]",
-            "name": "labels",
-            "type": "stringSlice",
-            "usage": "Extra labels appended after self-hosted,Linux,X64"
+            "name": "prefer",
+            "type": "string"
           },
           {
-            "name": "ssh-key",
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "runner",
+            "type": "string"
+          },
+          {
+            "name": "trigger",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "explain",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Explain why a job was or was not planned"
+      },
+      {
+        "flags": [
+          {
+            "name": "runner",
             "type": "string",
-            "usage": "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"
+            "usage": "Runner container name (default: <PROJECT>_forgejo_runner)"
           },
           {
-            "name": "token",
-            "secret": true,
+            "default": "http://localhost:3844",
+            "name": "url",
             "type": "string",
-            "usage": "GitHub Actions runner registration token (overrides GITHUB_RUNNER_TOKEN env). Never logged."
+            "usage": "Forgejo base URL"
           }
         ],
-        "json": "legacy",
-        "name": "nodes provision",
+        "json": "none",
+        "name": "forgejo",
         "output": "document",
-        "side_effect": "remote",
-        "summary": "Install runner dependencies, user, sudoers, and N runner instances",
-        "surface": "cli-only"
+        "side_effect": "read",
+        "summary": "Show Forgejo server health (ops profile)"
       },
       {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
         "flags": [
           {
-            "default": "[]",
-            "name": "host",
-            "type": "stringSlice",
-            "usage": "SSH target(s) user@host to verify (repeatable). Default: this machine."
+            "default": "0",
+            "name": "attempt",
+            "type": "int"
           },
           {
-            "default": "false",
+            "cli_only": true,
+            "name": "f",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
             "name": "json",
-            "type": "bool",
-            "usage": "Print JSON instead of the text parity matrix: raw []HostReport in v1.4, one v1 envelope in V15 (NSELF_V15=1)"
+            "type": "bool"
           },
           {
-            "name": "ssh-key",
-            "type": "string",
-            "usage": "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"
+            "name": "run",
+            "type": "string"
           }
         ],
-        "json": "legacy",
-        "name": "nodes verify",
+        "json": "envelope",
+        "name": "logs",
         "output": "document",
         "side_effect": "read",
-        "summary": "Check host(s) against the dependency manifest and report drift",
+        "summary": "Print the logs of a run attempt (-f follows)"
+      },
+      {
+        "flags": [
+          {
+            "name": "probe",
+            "type": "bool"
+          },
+          {
+            "name": "proxy",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "netproxy",
+        "output": "interactive",
+        "side_effect": "remote",
+        "summary": "Internal egress proxy used by restricted jobs",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "host"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "accepts",
+            "type": "string"
+          },
+          {
+            "name": "agent-binary",
+            "type": "string"
+          },
+          {
+            "name": "allow-deploy-host",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "name": "host-key",
+            "type": "string"
+          },
+          {
+            "name": "installer",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "default": "operator",
+            "name": "ownership",
+            "type": "string"
+          },
+          {
+            "name": "privacy-zone",
+            "type": "string"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          },
+          {
+            "name": "secret-classes",
+            "type": "string"
+          },
+          {
+            "default": "2",
+            "name": "slots",
+            "type": "int"
+          },
+          {
+            "name": "system",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes add",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Add and provision a CI node"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "default": "5s",
+            "name": "timeout",
+            "type": "duration"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes discover",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Discover nodes on the local network"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes drain",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Stop placing new jobs on a node"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes enable",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Place jobs on a node again"
+      },
+      {
+        "args": [
+          {
+            "name": "project-root"
+          }
+        ],
+        "json": "none",
+        "name": "nodes forget-project",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Forget a project's node records on this host (local, audited)",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          },
+          {
+            "name": "label"
+          }
+        ],
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "remove",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes label",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Set or remove node labels (key=value)"
+      },
+      {
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes list",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List nodes"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "flags": [
+          {
+            "name": "agent-url",
+            "type": "string"
+          },
+          {
+            "default": "0s",
+            "name": "cert-ttl",
+            "type": "duration"
+          },
+          {
+            "default": "local",
+            "name": "coordinator-id",
+            "type": "string"
+          },
+          {
+            "name": "data-dir",
+            "type": "string"
+          },
+          {
+            "default": ":3866",
+            "name": "enroll-addr",
+            "type": "string"
+          },
+          {
+            "name": "label",
+            "type": "string"
+          },
+          {
+            "name": "public-url",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "nodes pair",
+        "output": "interactive",
+        "side_effect": "remote",
+        "summary": "Pair an agent node (foreground enrollment listener)",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes pools explain",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Explain a project's effective pool set and every excluded runner"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes pools list",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List runner pools and whether the project may use them"
+      },
+      {
+        "args": [
+          {
+            "name": "pool"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes pools show",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show one runner pool"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          },
+          {
+            "name": "project"
+          }
+        ],
+        "flags": [
+          {
+            "name": "all",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes projects add",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Authorize projects on a node"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "flags": [
+          {
+            "name": "all",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes projects list",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List the projects a node is authorized for"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          },
+          {
+            "name": "project"
+          }
+        ],
+        "flags": [
+          {
+            "name": "all",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes projects remove",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Remove project authorizations from a node"
+      },
+      {
+        "flags": [
+          {
+            "name": "github-url",
+            "type": "string",
+            "usage": "Repo or org URL runners register against, e.g. https://github.com/nself-org/cli"
+          },
+          {
+            "default": "[]",
+            "name": "host",
+            "type": "stringSlice",
+            "usage": "SSH target(s) user@host to provision (repeatable). Default: this machine."
+          },
+          {
+            "name": "install-root",
+            "type": "string",
+            "usage": "Base install directory (default: /opt/actions-runner)"
+          },
+          {
+            "default": "1",
+            "name": "instances",
+            "type": "int",
+            "usage": "Number of runner instances to install on this host"
+          },
+          {
+            "default": "false",
+            "name": "json",
+            "type": "bool",
+            "usage": "V15 only (NSELF_V15=1): print one v1 JSON envelope; in v1.4 the flag is refused as today"
+          },
+          {
+            "default": "[]",
+            "name": "labels",
+            "type": "stringSlice",
+            "usage": "Extra labels appended after self-hosted,Linux,X64"
+          },
+          {
+            "name": "ssh-key",
+            "type": "string",
+            "usage": "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"
+          },
+          {
+            "name": "token",
+            "type": "string",
+            "usage": "GitHub Actions runner registration token (overrides GITHUB_RUNNER_TOKEN env). Never logged."
+          }
+        ],
+        "json": "legacy",
+        "name": "nodes provision",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Install runner dependencies, user, sudoers, and N runner instances",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes remove",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Remove a node and its registration"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes revoke",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Revoke a node credential"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "cert",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "name": "host-key",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "key-id",
+            "type": "string"
+          },
+          {
+            "default": "host-key",
+            "name": "mode",
+            "type": "string"
+          },
+          {
+            "name": "node-key",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes rotate",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Rotate a node host key, certificate or node key"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "flags": [
+          {
+            "name": "class",
+            "type": "string"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "nodes secrets grant",
+        "output": "interactive",
+        "side_effect": "remote",
+        "summary": "Grant a node access to a secret class",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "flags": [
+          {
+            "name": "class",
+            "type": "string"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "nodes secrets revoke",
+        "output": "interactive",
+        "side_effect": "remote",
+        "summary": "Revoke a node access to a secret class",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "name": "interactive",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "on-battery",
+            "type": "string"
+          },
+          {
+            "name": "persistence",
+            "type": "string"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          },
+          {
+            "name": "reserve-cpu",
+            "type": "string"
+          },
+          {
+            "name": "reserve-mem",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes set",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Set contention and persistence policy of a node"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes show",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show one node"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "local",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes status",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show readiness, watcher, queue and last results of every node"
+      },
+      {
+        "flags": [
+          {
+            "name": "cmd",
+            "type": "string"
+          },
+          {
+            "name": "dry-run",
+            "type": "bool"
+          },
+          {
+            "name": "from",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes sync",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Import an inventory/v1 file or command output over the node registry"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes test",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Probe a node and report its capabilities"
+      },
+      {
+        "args": [
+          {
+            "name": "node"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "all",
+            "type": "bool"
+          },
+          {
+            "name": "allow-downgrade",
+            "type": "bool"
+          },
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "default": "10m0s",
+            "name": "drain-wait",
+            "type": "duration"
+          },
+          {
+            "default": "1m0s",
+            "name": "hello-wait",
+            "type": "duration"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "version",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "nodes upgrade",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Upgrade node agents"
+      },
+      {
+        "flags": [
+          {
+            "default": "[]",
+            "name": "host",
+            "type": "stringSlice",
+            "usage": "SSH target(s) user@host to verify (repeatable). Default: this machine."
+          },
+          {
+            "default": "false",
+            "name": "json",
+            "type": "bool",
+            "usage": "Print JSON instead of the text parity matrix: raw []HostReport in v1.4, one v1 envelope in V15 (NSELF_V15=1)"
+          },
+          {
+            "name": "ssh-key",
+            "type": "string",
+            "usage": "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"
+          }
+        ],
+        "json": "legacy",
+        "name": "nodes verify",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Check host(s) against the dependency manifest and report drift",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "name": "base",
+            "type": "string"
+          },
+          {
+            "name": "config",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "max-queue",
+            "type": "string"
+          },
+          {
+            "name": "pipeline",
+            "type": "string"
+          },
+          {
+            "name": "prefer",
+            "type": "string"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "runner",
+            "type": "string"
+          },
+          {
+            "name": "trigger",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "plan",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Plan a run without executing it"
+      },
+      {
+        "args": [
+          {
+            "name": "sha"
+          }
+        ],
+        "flags": [
+          {
+            "name": "clear",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy pin",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Pin or clear the trusted revision",
+        "surface": "cli-only"
+      },
+      {
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "default": "15368",
+            "name": "app-id",
+            "type": "int"
+          },
+          {
+            "default": "0",
+            "name": "audit",
+            "type": "int"
+          },
+          {
+            "name": "branch",
+            "type": "string"
+          },
+          {
+            "name": "dry-run",
+            "type": "bool"
+          },
+          {
+            "name": "hook",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "restore",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy protect",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Show or apply branch protection that requires the nself-ci check"
+      },
+      {
+        "args": [
+          {
+            "name": "key"
+          },
+          {
+            "name": "value"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "scope",
+            "type": "string"
+          },
+          {
+            "name": "team",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy set",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Set an operator policy key",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "key"
+          }
+        ],
+        "flags": [
+          {
+            "name": "effective",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "team",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy show",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show the operator policy"
+      },
+      {
+        "args": [
+          {
+            "name": "key"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "scope",
+            "type": "string"
+          },
+          {
+            "name": "team",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy unset",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Unset an operator policy key",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "policy usage",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show spend and usage against the policy"
+      },
+      {
+        "json": "none",
+        "name": "providers",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Provider command group help",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "provider"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "allow-private",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers authorize",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Authorize a project for hosted runners"
+      },
+      {
+        "flags": [
+          {
+            "name": "agent-source",
+            "type": "string"
+          },
+          {
+            "name": "check",
+            "type": "bool"
+          },
+          {
+            "name": "dir",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "stdout",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers github init",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Render the GitHub dispatch workflow"
+      },
+      {
+        "flags": [
+          {
+            "name": "check",
+            "type": "bool"
+          },
+          {
+            "name": "dir",
+            "type": "string"
+          },
+          {
+            "name": "inputs",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "stdout",
+            "type": "bool"
+          },
+          {
+            "name": "untrusted-dir",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers gitlab init",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Render the GitLab dispatch pipeline"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers list",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List providers"
+      },
+      {
+        "args": [
+          {
+            "name": "provider"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers revoke",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Revoke a project authorization for hosted runners"
+      },
+      {
+        "args": [
+          {
+            "name": "provider"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers show",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show one provider"
+      },
+      {
+        "args": [
+          {
+            "name": "provider"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers test",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Probe a provider"
+      },
+      {
+        "args": [
+          {
+            "name": "file"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "providers usage import",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Import provider usage records"
+      },
+      {
+        "args": [
+          {
+            "name": "search-root"
+          }
+        ],
+        "flags": [
+          {
+            "name": "env",
+            "type": "string",
+            "usage": "Target environment: local"
+          },
+          {
+            "name": "gateway",
+            "type": "string",
+            "usage": "Explicit gateway base URL (e.g. http://host:3761)"
+          },
+          {
+            "name": "v",
+            "type": "bool",
+            "usage": "Print each command before running"
+          },
+          {
+            "default": "300",
+            "name": "timeout",
+            "type": "int",
+            "usage": "Per-step timeout in seconds"
+          }
+        ],
+        "json": "none",
+        "name": "run",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Discover .ci.yaml manifests and run their stages (pipeline)"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "flags": [
+          {
+            "name": "flaky",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show a run, or the flaky checks (--flaky)"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "sha",
+            "type": "string"
+          },
+          {
+            "name": "spend",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs approve",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Approve a run that waits for approval"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "json": "envelope",
+        "name": "runs cancel",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Cancel a run"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs decisions",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show the scheduling decisions of a run"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "default": "0",
+            "name": "from-seq",
+            "type": "int"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs follow",
+        "output": "stream",
+        "side_effect": "read",
+        "summary": "Follow the events of a run as an NDJSON stream"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "default": "20",
+            "name": "limit",
+            "type": "int"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs list",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List recent runs"
+      },
+      {
+        "json": "envelope",
+        "name": "runs outbox",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show queued status and event deliveries"
+      },
+      {
+        "json": "envelope",
+        "name": "runs pending",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "List runs waiting for approval"
+      },
+      {
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "apply",
+            "type": "bool"
+          },
+          {
+            "name": "dry-run",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "default": "0",
+            "name": "keep",
+            "type": "int"
+          },
+          {
+            "default": "20",
+            "name": "limit",
+            "type": "int"
+          },
+          {
+            "default": "0",
+            "name": "max-age-days",
+            "type": "int"
+          },
+          {
+            "name": "max-log-bytes",
+            "type": "int"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "tidy",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs prune",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Remove old runs and logs (--dry-run previews; --tidy [--apply] also tidies cache and job roots)"
+      },
+      {
+        "json": "envelope",
+        "name": "runs queue",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show the run queue"
+      },
+      {
+        "args": [
+          {
+            "name": "job"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "check",
+            "type": "bool"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "run",
+            "type": "string"
+          },
+          {
+            "name": "shell",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs reproduce",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Reproduce a job at its recorded inputs"
+      },
+      {
+        "args": [
+          {
+            "name": "run-or-sha"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "name": "job",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "where",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs rerun",
+        "output": "document",
+        "side_effect": "remote",
+        "summary": "Run a recorded revision again on a chosen target"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs resolve",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Resolve a pending run decision"
+      },
+      {
+        "json": "envelope",
+        "name": "runs stats",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Show run statistics"
+      },
+      {
+        "args": [
+          {
+            "name": "run"
+          }
+        ],
+        "flags": [
+          {
+            "name": "coordinator",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "default": "4m0s",
+            "name": "timeout",
+            "type": "duration"
+          }
+        ],
+        "json": "envelope",
+        "name": "runs wait",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Wait for a run to finish and print its result"
+      },
+      {
+        "flags": [
+          {
+            "default": ":3845",
+            "name": "addr",
+            "type": "string",
+            "usage": "Listen address (host:port). Port 3845 = nself-ci-serve per F10 port registry"
+          },
+          {
+            "default": "false",
+            "name": "allow-unsandboxed",
+            "side_effect": "destructive",
+            "type": "bool",
+            "usage": "DANGEROUS: run the gate directly on this host when Docker is unavailable, instead of refusing the job. Default: refuse."
+          },
+          {
+            "default": "[]",
+            "name": "allowed-repos",
+            "type": "stringSlice",
+            "usage": "Comma-separated or repeatable \"owner/repo\" allowlist. Default: empty, which rejects every job (fail-closed, no \"allow all\")."
+          },
+          {
+            "default": "2",
+            "name": "concurrency",
+            "type": "int",
+            "usage": "Max concurrent CI jobs"
+          },
+          {
+            "default": "false",
+            "name": "insecure",
+            "type": "bool",
+            "usage": "DANGEROUS: start without a webhook secret (disables signature verification). Default: refuse to start when no secret is configured."
+          },
+          {
+            "name": "secret",
+            "type": "string",
+            "usage": "HMAC-SHA256 webhook secret (overrides GITHUB_WEBHOOK_SECRET env)"
+          },
+          {
+            "default": "600",
+            "name": "timeout",
+            "type": "int",
+            "usage": "Per-job timeout in seconds"
+          },
+          {
+            "default": "false",
+            "name": "verbose",
+            "shorthand": "v",
+            "type": "bool",
+            "usage": "Verbose gate output"
+          },
+          {
+            "default": "/tmp/nself-ci-workdirs",
+            "name": "workdir",
+            "type": "string",
+            "usage": "Base directory for ephemeral checkout workdirs"
+          }
+        ],
+        "json": "none",
+        "name": "serve",
+        "output": "stream",
+        "side_effect": "write",
+        "summary": "Start the nself-ci webhook listener daemon (port 3845)",
+        "surface": "cli-only"
+      },
+      {
+        "json": "none",
+        "name": "serve admin",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Coordinator admin group help",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "since",
+            "type": "string"
+          },
+          {
+            "name": "verify",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve admin audit",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Read or verify the audit log"
+      },
+      {
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "pubkey",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve admin audit checkpoint",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Write a signed audit checkpoint",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "verb"
+          },
+          {
+            "name": "principal"
+          }
+        ],
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "self",
+            "type": "bool"
+          },
+          {
+            "default": "168h0m0s",
+            "name": "ttl",
+            "type": "duration"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve admin cert",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Issue a user mTLS certificate (printed once)",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "verb"
+          },
+          {
+            "name": "principal"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "stringSlice"
+          },
+          {
+            "name": "role",
+            "type": "string"
+          },
+          {
+            "name": "self",
+            "type": "bool"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve admin roles",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Grant, revoke or list roles",
+        "surface": "cli-only"
+      },
+      {
+        "args": [
+          {
+            "name": "verb"
+          },
+          {
+            "name": "principal"
+          }
+        ],
+        "confirm": {
+          "flags": []
+        },
+        "flags": [
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "project",
+            "type": "stringSlice"
+          },
+          {
+            "name": "role",
+            "type": "string"
+          },
+          {
+            "name": "self",
+            "type": "bool"
+          },
+          {
+            "default": "0s",
+            "name": "ttl",
+            "type": "duration"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve admin token",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Issue, revoke or list scoped user tokens",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "name": "data-dir",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "out",
+            "type": "string"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve backup",
+        "output": "document",
+        "side_effect": "read",
+        "summary": "Back up the coordinator data directory",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "name": "launchd",
+            "type": "bool"
+          },
+          {
+            "name": "systemd",
+            "type": "bool"
+          },
+          {
+            "name": "user",
+            "type": "bool"
+          },
+          {
+            "name": "system",
+            "type": "bool"
+          },
+          {
+            "name": "dry-run",
+            "type": "bool"
+          },
+          {
+            "name": "binary",
+            "type": "string"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "env-file",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "serve install",
+        "output": "document",
+        "side_effect": "write",
+        "summary": "Install the watcher service and hourly selftest",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "name": "data-dir",
+            "type": "string"
+          },
+          {
+            "name": "in",
+            "type": "string"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "kek",
+            "secret": true,
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "serve restore",
+        "output": "interactive",
+        "side_effect": "destructive",
+        "summary": "Restore the coordinator data directory from a backup",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "name": "launchd",
+            "type": "bool"
+          },
+          {
+            "name": "systemd",
+            "type": "bool"
+          },
+          {
+            "name": "user",
+            "type": "bool"
+          },
+          {
+            "name": "system",
+            "type": "bool"
+          },
+          {
+            "name": "dry-run",
+            "type": "bool"
+          },
+          {
+            "name": "binary",
+            "type": "string"
+          },
+          {
+            "name": "repo",
+            "type": "string"
+          },
+          {
+            "name": "env-file",
+            "type": "string"
+          }
+        ],
+        "json": "none",
+        "name": "serve uninstall",
+        "output": "document",
+        "side_effect": "destructive",
+        "summary": "Remove unchanged watcher service files",
+        "surface": "cli-only"
+      },
+      {
+        "flags": [
+          {
+            "default": "0s",
+            "name": "interval",
+            "type": "duration"
+          },
+          {
+            "cli_only": true,
+            "name": "json",
+            "type": "bool"
+          },
+          {
+            "name": "once",
+            "type": "bool"
+          },
+          {
+            "name": "repos",
+            "type": "stringSlice"
+          }
+        ],
+        "json": "envelope",
+        "name": "serve watch",
+        "output": "stream",
+        "side_effect": "remote",
+        "summary": "Keep commit CI current by polling, without an inbound port",
         "surface": "cli-only"
       }
     ],
diff --git a/free/ci/schemas/ci-conformance.v1.schema.json b/free/ci/schemas/ci-conformance.v1.schema.json
new file mode 100644
index 000000000..378b587b5
--- /dev/null
+++ b/free/ci/schemas/ci-conformance.v1.schema.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.nself.org/ci-conformance.v1.schema.json",
+  "title": "ci-conformance/v1 leg line",
+  "description": "One line of free/ci/scripts/ci-conformance.sh --json: a leg result, a catalogue row (--list) or the final summary.",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["leg", "pass", "reason", "evidence_ref", "duration_ms"],
+      "properties": {
+        "schema": { "const": "ci-conformance/v1" },
+        "leg": { "type": "string", "pattern": "^(A([1-9]|10)|F[0-9]+)$" },
+        "kind": { "enum": ["sim", "hardware"] },
+        "status": { "enum": ["pass", "fail", "skip"] },
+        "pass": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "evidence_ref": { "type": "string" },
+        "duration_ms": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["id", "kind", "path"],
+      "properties": {
+        "schema": { "const": "ci-conformance/v1" },
+        "id": { "type": "string", "pattern": "^(A([1-9]|10)|F[0-9]+)$" },
+        "kind": { "enum": ["sim", "hardware"] },
+        "path": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["summary"],
+      "properties": {
+        "schema": { "const": "ci-conformance/v1" },
+        "summary": {
+          "type": "object",
+          "required": ["kind", "pass", "fail", "skip"],
+          "properties": {
+            "kind": { "enum": ["sim", "hardware"] },
+            "pass": { "type": "integer", "minimum": 0 },
+            "fail": { "type": "integer", "minimum": 0 },
+            "skip": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}
diff --git a/free/ci/schemas/ci-evidence.v1.schema.json b/free/ci/schemas/ci-evidence.v1.schema.json
index a9510a04b..bc84c5806 100644
--- a/free/ci/schemas/ci-evidence.v1.schema.json
+++ b/free/ci/schemas/ci-evidence.v1.schema.json
@@ -696,6 +696,113 @@
         "verified_at"
       ],
       "additionalProperties": false
+    },
+    "attempts": {
+      "type": [
+        "null",
+        "array"
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "job_id": {
+            "type": "string"
+          },
+          "attempt": {
+            "type": "integer"
+          },
+          "runner": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "local",
+                  "ssh",
+                  "agent",
+                  "hosted"
+                ]
+              },
+              "tier": {
+                "type": "string"
+              },
+              "pool": {
+                "type": "string"
+              },
+              "rank": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "kind",
+              "tier",
+              "pool",
+              "rank"
+            ],
+            "additionalProperties": false
+          },
+          "timings": {
+            "type": [
+              "null",
+              "object"
+            ],
+            "properties": {
+              "queue_ms": {
+                "type": [
+                  "null",
+                  "integer"
+                ]
+              },
+              "transfer_ms": {
+                "type": [
+                  "null",
+                  "integer"
+                ]
+              },
+              "run_ms": {
+                "type": [
+                  "null",
+                  "integer"
+                ]
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "job_id",
+          "attempt",
+          "runner"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "errors": {
+      "type": [
+        "null",
+        "array"
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "job_id": {
+            "type": "string"
+          },
+          "attempt": {
+            "type": "integer"
+          },
+          "detail": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code"
+        ],
+        "additionalProperties": false
+      }
     }
   },
   "$id": "https://nself.org/schemas/ci-evidence.v1.schema.json",
diff --git a/free/ci/schemas/demand.v1.schema.json b/free/ci/schemas/demand.v1.schema.json
new file mode 100644
index 000000000..11e3e6d6d
--- /dev/null
+++ b/free/ci/schemas/demand.v1.schema.json
@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "contract:ci.demand/v1",
+  "title": "CI Demand v1",
+  "description": "Host-level CI demand document published atomically every watcher pass.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "ts",
+    "host",
+    "queued",
+    "held",
+    "running",
+    "ready",
+    "ready_why",
+    "watcher"
+  ],
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "UTC RFC3339 timestamp of this publication."
+    },
+    "host": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Hostname that published this document."
+    },
+    "queued": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of queued work items across watched repos."
+    },
+    "held": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of held work items."
+    },
+    "running": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of currently running work items."
+    },
+    "ready": {
+      "type": "boolean",
+      "description": "Whether the host is ready to accept new CI work."
+    },
+    "ready_why": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Reasons the host is not ready; empty when ready."
+    },
+    "watcher": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "alive",
+        "last_pass",
+        "interval_sec"
+      ],
+      "properties": {
+        "alive": {
+          "type": "boolean",
+          "description": "True when the watcher loop is publishing."
+        },
+        "last_pass": {
+          "type": "string",
+          "format": "date-time",
+          "description": "UTC RFC3339 timestamp of the last watcher pass."
+        },
+        "interval_sec": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Configured watcher interval in seconds."
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/free/ci/schemas/inventory.v1.schema.json b/free/ci/schemas/inventory.v1.schema.json
new file mode 100644
index 000000000..2aa8acdd6
--- /dev/null
+++ b/free/ci/schemas/inventory.v1.schema.json
@@ -0,0 +1,32 @@
+{
+  "$id": "https://nself.org/schemas/inventory.v1.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "inventory/v1: runner inventory read by `nself ci nodes sync`",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "entries"],
+  "properties": {
+    "schema": { "type": "string", "const": "inventory/v1" },
+    "entries": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$" },
+          "ssh": { "type": "string", "pattern": "^([A-Za-z0-9._-]{1,64}@)?[A-Za-z0-9][A-Za-z0-9._-]{0,252}$" },
+          "os": { "type": "string", "enum": ["linux", "darwin", "windows"] },
+          "arch": { "type": "string", "enum": ["amd64", "arm64"] },
+          "rank": { "type": "integer", "minimum": 0, "maximum": 1000 },
+          "local": { "type": "boolean" },
+          "labels": { "type": "array", "items": { "type": "string" }, "maxItems": 32 },
+          "pools": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}$" } },
+          "skip_repos": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 64 },
+          "public_only": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}
diff --git a/free/ci/schemas/placement-plan.v1.schema.json b/free/ci/schemas/placement-plan.v1.schema.json
index e9c1da82c..fab22608e 100644
--- a/free/ci/schemas/placement-plan.v1.schema.json
+++ b/free/ci/schemas/placement-plan.v1.schema.json
@@ -40,6 +40,7 @@
         "preset": {
           "type": "string",
           "enum": [
+            "auto",
             "balanced",
             "cheapest",
             "fastest",
diff --git a/free/ci/schemas/pool.v1.schema.json b/free/ci/schemas/pool.v1.schema.json
new file mode 100644
index 000000000..b9d235fc5
--- /dev/null
+++ b/free/ci/schemas/pool.v1.schema.json
@@ -0,0 +1,139 @@
+{
+  "$id": "https://nself.org/schemas/pool.v1.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "ci.pool/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,30}$"
+    },
+    "scope": {
+      "type": "string",
+      "enum": [
+        "operator",
+        "project",
+        "hosted"
+      ]
+    },
+    "members": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "runner_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "location": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "local",
+              "registry",
+              "coordinator",
+              "provider"
+            ]
+          }
+        },
+        "required": [
+          "runner_id",
+          "location",
+          "source"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "effective": {
+      "type": "object",
+      "properties": {
+        "allowed": {
+          "type": "boolean"
+        },
+        "reasons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string",
+                "const": "pool.excluded"
+              },
+              "detail": {
+                "type": "string",
+                "enum": [
+                  "not_in_project_list",
+                  "not_enrolled",
+                  "dev_not_allowed"
+                ]
+              }
+            },
+            "required": [
+              "code",
+              "detail"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "allowed",
+        "reasons"
+      ],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "allowed": {
+                "const": true
+              }
+            },
+            "required": [
+              "allowed"
+            ]
+          },
+          "then": {
+            "properties": {
+              "reasons": {
+                "maxItems": 0
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "allowed": {
+                "const": false
+              }
+            },
+            "required": [
+              "allowed"
+            ]
+          },
+          "then": {
+            "properties": {
+              "reasons": {
+                "minItems": 1
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "required": [
+    "schema",
+    "id",
+    "scope",
+    "members",
+    "effective"
+  ],
+  "additionalProperties": false
+}
diff --git a/free/ci/scripts/ci-conformance.sh b/free/ci/scripts/ci-conformance.sh
new file mode 100755
index 000000000..faebf2491
--- /dev/null
+++ b/free/ci/scripts/ci-conformance.sh
@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# ci-conformance.sh: acceptance A1-A10 of the AUTO fabric as one suite (P7-AUTO-25).
+# Purpose: one entry point. Sim legs are Go tests under free/ci/test/sim/auto (and the foreground
+#   remote tests of P7-AUTO-28 under free/ci/test/sim); hardware legs are scripts in
+#   free/ci/scripts/conformance/. Every leg prints one `ci-conformance/v1` JSON line
+#   {leg, pass, reason, evidence_ref, duration_ms} (plus status and kind).
+# Usage:   bash free/ci/scripts/ci-conformance.sh [--sim|--hardware] [--json] [--list]
+#   --sim       run the sim legs (the default)
+#   --hardware  run the hardware legs
+#   --json      one JSON line per leg and a final {"summary":...} line (without it, plain text)
+#   --list      print the leg catalogue (id, kind, script) and run nothing
+# Env:     TMPDIR (required for a run); CI_CONFORMANCE_BREAK=<leg> makes that sim leg look for a test
+#   that does not exist, to prove a broken leg fails the suite; CI_CONFORMANCE_OUT keeps the logs.
+# Exit:    0 every selected leg passed; 1 a leg failed; 2 usage; 3 no leg failed but one was skipped
+#   (a skipped leg is listed and never counted as a pass).
+# Constraints: bash 3.2; sim legs use CGO_ENABLED=0 and -mod=vendor; no host is named here.
+set -u
+
+KIND=sim; JSON=0; LIST=0
+for a in "$@"; do
+  case "$a" in
+    --sim) KIND=sim ;; --hardware) KIND=hardware ;; --json) JSON=1 ;; --list) LIST=1 ;;
+    *) echo "usage: ci-conformance.sh [--sim|--hardware] [--json] [--list]" >&2; exit 2 ;;
+  esac
+done
+
+HERE=$(cd "$(dirname "$0")" && pwd)    # free/ci/scripts
+CI_DIR=$(cd "$HERE/.." && pwd)         # free/ci
+
+# Catalogue rows: id|test name|package (sim) ; hardware rows: id|script.
+SIM_LEGS="A3|TestConformanceA3Watch|./test/sim/auto/
+A4|TestConformanceA4Hosted|./test/sim/auto/
+A5|TestConformanceA5Offload|./test/sim/auto/
+A6|TestConformanceA6Refusal|./test/sim/auto/
+A7|TestConformanceA7Race|./test/sim/auto/
+A9|TestConformanceA9DeadNode|./test/sim/auto/
+A10|TestConformanceA10Scope|./test/sim/auto/
+F28|TestForegroundRemote|./test/sim/"
+HW_LEGS="A1|a01.sh
+A2|a02.sh
+A3|a03.sh
+A4|a04.sh
+A5|a05.sh
+A6|a06.sh
+A7|a07.sh
+A8|a08.sh
+A9|a09.sh
+A10|a10.sh"
+
+jesc() { printf '%s' "$1" | tr -d '\000-\037' | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'; }
+now_ms() { echo $(( $(date +%s) * 1000 )); }
+
+if [ "$LIST" = 1 ]; then
+  list_one() { # id kind path
+    if [ "$JSON" = 1 ]; then printf '{"schema":"ci-conformance/v1","id":"%s","kind":"%s","path":"%s"}\n' "$1" "$2" "$3"
+    else printf '%s\t%s\t%s\n' "$1" "$2" "$3"; fi
+  }
+  echo "$SIM_LEGS" | while IFS='|' read -r id name pkg; do
+    [ "$KIND" = sim ] && list_one "$id" sim "free/ci/${pkg#./}"
+  done
+  echo "$HW_LEGS" | while IFS='|' read -r id script; do
+    [ "$KIND" = hardware ] && list_one "$id" hardware "free/ci/scripts/conformance/$script"
+  done
+  exit 0
+fi
+
+: "${TMPDIR:?TMPDIR must be set}"
+OUT=${CI_CONFORMANCE_OUT:-$(mktemp -d "$TMPDIR/ci-conformance.XXXXXX")} || exit 2
+mkdir -p "$OUT"
+NPASS=0; NFAIL=0; NSKIP=0
+
+report() { # id status reason evidence start
+  local pass=false
+  [ "$2" = pass ] && pass=true
+  case "$2" in pass) NPASS=$((NPASS + 1)) ;; fail) NFAIL=$((NFAIL + 1)) ;; skip) NSKIP=$((NSKIP + 1)) ;; esac
+  if [ "$JSON" = 1 ]; then
+    printf '{"schema":"ci-conformance/v1","leg":"%s","kind":"%s","status":"%s","pass":%s,"reason":"%s","evidence_ref":"%s","duration_ms":%s}\n' \
+      "$1" "$KIND" "$2" "$pass" "$(jesc "$3")" "$(jesc "$4")" "$(( $(now_ms) - $5 ))"
+  else
+    printf '%-4s %-4s %s\n' "$1" "$2" "$3"
+  fi
+}
+
+run_sim() { # id test pkg
+  local id=$1 name=$2 pkg=$3 log="$OUT/sim-$1.log" start
+  start=$(now_ms)
+  [ "${CI_CONFORMANCE_BREAK:-}" = "$id" ] && name="${name}DeliberatelyBroken"
+  if (cd "$CI_DIR" && CGO_ENABLED=0 go test -mod=vendor -count=1 -v -run "^${name}" "$pkg") >"$log" 2>&1; then
+    if grep -q -- "^--- PASS: ${name}" "$log"; then report "$id" pass "ok" "$log" "$start"
+    else report "$id" fail "no test named ${name} ran" "$log" "$start"; fi
+  else
+    report "$id" fail "$(grep -m1 -E -- '--- FAIL|FAIL|panic' "$log" | cut -c1-200)" "$log" "$start"
+  fi
+}
+
+run_hw() { # id script
+  local id=$1 script="$HERE/conformance/$2" log="$OUT/hw-$1.log" start rc line
+  start=$(now_ms)
+  CI_CONF_OUT="$OUT" bash "$script" >"$log" 2>&1; rc=$?
+  line=$(grep -E '^\{.*"leg"' "$log" | tail -1)
+  reason=$(printf '%s' "$line" | sed -n 's/.*"reason":"\([^"]*\)".*/\1/p')
+  case $rc in
+    0) report "$id" pass "${reason:-ok}" "$log" "$start" ;;
+    3) report "$id" skip "${reason:-a required host is missing}" "$log" "$start" ;;
+    *) report "$id" fail "${reason:-leg exited $rc}" "$log" "$start" ;;
+  esac
+}
+
+if [ "$KIND" = sim ]; then
+  while IFS='|' read -r id name pkg; do run_sim "$id" "$name" "$pkg"; done <<EOF2
+$SIM_LEGS
+EOF2
+else
+  while IFS='|' read -r id script; do run_hw "$id" "$script"; done <<EOF2
+$HW_LEGS
+EOF2
+fi
+
+if [ "$JSON" = 1 ]; then
+  printf '{"schema":"ci-conformance/v1","summary":{"kind":"%s","pass":%s,"fail":%s,"skip":%s}}\n' "$KIND" "$NPASS" "$NFAIL" "$NSKIP"
+else
+  echo "ci-conformance ($KIND): $NPASS passed, $NFAIL failed, $NSKIP skipped (logs: $OUT)"
+fi
+[ "$NFAIL" -gt 0 ] && exit 1
+[ "$NSKIP" -gt 0 ] && exit 3
+exit 0
diff --git a/free/ci/scripts/conformance/a01.sh b/free/ci/scripts/conformance/a01.sh
new file mode 100755
index 000000000..efe41d9d1
--- /dev/null
+++ b/free/ci/scripts/conformance/a01.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# a01.sh: A1 gate tables are identical on macOS arm64 and Linux amd64 for Go, Node and Go+Node
+# sample repos; no system change, no dialog, no hang (every gate run has a 600 s deadline).
+# Needs CI_CONF_MAC=local and CI_CONF_LINUX. Exit 0 pass, 1 fail, 3 skip.
+. "$(dirname "$0")/lib.sh"
+conf_begin A1
+conf_need CI_CONF_MAC CI_CONF_LINUX
+conf_bin
+before=$(ls -A "$HOME" | shasum | cut -d' ' -f1)
+for kind in go node gonode; do
+  conf_sample "$kind" "$CONF_DIR/$kind" || conf_fail "sample $kind could not be written"
+  a=$(conf_table local "$CONF_DIR/$kind")
+  b=$(conf_table "$CI_CONF_LINUX" "$CONF_DIR/$kind")
+  [ -n "$a" ] && [ -n "$b" ] || conf_fail "$kind: an empty gate table (hang or no output)"
+  [ "$a" = "$b" ] || { printf '%s\n---\n%s\n' "$a" "$b" >>"$CONF_EVID"; conf_fail "$kind: gate tables differ between hosts"; }
+done
+after=$(ls -A "$HOME" | shasum | cut -d' ' -f1)
+[ "$before" = "$after" ] || conf_fail "the home folder changed during the run"
+conf_pass "gate tables identical for go, node and gonode"
diff --git a/free/ci/scripts/conformance/a02.sh b/free/ci/scripts/conformance/a02.sh
new file mode 100755
index 000000000..042af30ff
--- /dev/null
+++ b/free/ci/scripts/conformance/a02.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# a02.sh: A2 the cli unit suite with TMPDIR on an external volume whose root is 0775 finishes in
+# under 10 minutes. The code fix is P7-HYG-49; this leg only re-proves it.
+# Needs CI_CONF_EXTVOL (the volume root) and CI_CONF_CLI_DIR (a cli checkout). Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A2
+conf_need CI_CONF_EXTVOL CI_CONF_CLI_DIR
+[ -d "$CI_CONF_EXTVOL" ] || conf_skip "missing host: $CI_CONF_EXTVOL is not mounted"
+mode=$(stat -f '%Lp' "$CI_CONF_EXTVOL" 2>/dev/null || stat -c '%a' "$CI_CONF_EXTVOL")
+[ "$mode" = "775" ] || conf_skip "missing host: $CI_CONF_EXTVOL root is $mode, not 775"
+tmp=$(mktemp -d "$CI_CONF_EXTVOL/ci-conf-a2.XXXXXX") || conf_fail "cannot create a temp folder on the volume"
+trap 'rm -rf "$tmp"' EXIT
+conf_timeout 600 env TMPDIR="$tmp" go -C "$CI_CONF_CLI_DIR" test -count=1 ./... >>"$CONF_EVID" 2>&1
+case $? in
+  0) conf_pass "cli unit suite passed with TMPDIR on the 0775 volume" ;;
+  124) conf_fail "cli unit suite took longer than 10 minutes" ;;
+  *) conf_fail "cli unit suite failed" ;;
+esac
diff --git a/free/ci/scripts/conformance/a03.sh b/free/ci/scripts/conformance/a03.sh
new file mode 100755
index 000000000..6bfa8aef6
--- /dev/null
+++ b/free/ci/scripts/conformance/a03.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# a03.sh: A3 three real hosts each run `ci serve watch` on a private scratch repository; every pushed
+# commit gets exactly one final status. Needs CI_CONF_NODE1, CI_CONF_NODE2, CI_CONF_MAC and a scratch
+# repository the hosts can reach in CI_CONF_WATCH_REPO (owner/name). Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A3
+conf_need CI_CONF_MAC CI_CONF_NODE1 CI_CONF_NODE2 CI_CONF_WATCH_REPO
+conf_bin
+sha=$(git ls-remote "https://github.com/$CI_CONF_WATCH_REPO" HEAD 2>>"$CONF_EVID" | cut -f1)
+[ -n "$sha" ] || conf_fail "the scratch repository has no head"
+for h in local "$CI_CONF_NODE1" "$CI_CONF_NODE2"; do
+  conf_timeout 900 "$BIN" --where "$h" serve watch --once --repo "$CI_CONF_WATCH_REPO" >>"$CONF_EVID" 2>&1 || conf_fail "watch pass failed on $h"
+done
+n=$(gh api "repos/$CI_CONF_WATCH_REPO/commits/$sha/statuses" --jq '[.[]|select(.context=="nself-ci" and (.state=="success" or .state=="failure"))]|length' 2>>"$CONF_EVID")
+[ "$n" = "1" ] || conf_fail "commit has $n final statuses, want 1"
+conf_pass "exactly one final status across three hosts"
diff --git a/free/ci/scripts/conformance/a04.sh b/free/ci/scripts/conformance/a04.sh
new file mode 100755
index 000000000..ae3ca4a09
--- /dev/null
+++ b/free/ci/scripts/conformance/a04.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# a04.sh: A4 the hosted-tier observer reads recent commits of an existing public repository with a
+# workflow (read only; no repository is created), plus the billing-blocked case from fixtures.
+# Needs CI_CONF_MAC=local and CI_CONF_HOSTED_REPO (default nself-org/plugins) readable through gh. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A4
+conf_need CI_CONF_MAC
+conf_bin
+command -v gh >/dev/null 2>&1 || conf_skip "missing tool: gh"
+repo=${CI_CONF_HOSTED_REPO:-nself-org/plugins}
+shas=$(gh api "repos/$repo/commits?per_page=3" --jq '.[].sha' 2>>"$CONF_EVID") || conf_skip "missing access: $repo is not readable"
+for s in $shas; do
+  out=$(conf_timeout 120 "$BIN" --where hosted --explain --sha "$s" --repo "$repo" --json 2>>"$CONF_EVID") || conf_fail "observer failed on $s"
+  printf '%s\n' "$out" >>"$CONF_EVID"
+  printf '%s' "$out" | grep -Eq 'hosted\.(success|failure|queued|running|absent|cancelled)' || conf_fail "no hosted decision for $s"
+done
+fix=$(cd "$(dirname "$0")/../.." && CGO_ENABLED=0 go test -mod=vendor -count=1 -run '^TestConformanceA4Hosted$' ./test/sim/auto/ 2>&1) || conf_fail "billing-blocked fixture failed"
+printf '%s\n' "$fix" >>"$CONF_EVID"
+conf_pass "observer decided recent commits read only; billing-blocked fixture passed"
diff --git a/free/ci/scripts/conformance/a05.sh b/free/ci/scripts/conformance/a05.sh
new file mode 100755
index 000000000..08712da8f
--- /dev/null
+++ b/free/ci/scripts/conformance/a05.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# a05.sh: A5 a dirty working tree runs on a real node: the node result names the snapshot, the
+# untracked secret-shaped file stays home, and the private ref is gone afterwards.
+# Needs CI_CONF_NODE1. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A5
+conf_need CI_CONF_NODE1
+conf_bin
+d="$CONF_DIR/dirty"
+conf_sample go "$d" || conf_fail "sample could not be written"
+printf 'package sample\n\nfunc Two() int { return 2 }\n' > "$d/two.go"
+printf 'placeholder\n' > "$d/.env"
+(cd "$d" && conf_timeout 600 "$BIN" --where "$CI_CONF_NODE1" --check --no-status --json) >>"$CONF_EVID" 2>&1 || conf_fail "dirty-tree run on $CI_CONF_NODE1 failed"
+git -C "$d" for-each-ref | grep -q 'refs/nself-ci/offload' && conf_fail "a private offload ref was left behind"
+grep -q 'placeholder' "$CONF_EVID" && conf_fail "the secret-shaped file reached the node output"
+conf_pass "dirty tree ran on the node; ref released; secret file stayed home"
diff --git a/free/ci/scripts/conformance/a06.sh b/free/ci/scripts/conformance/a06.sh
new file mode 100755
index 000000000..9c47c5a18
--- /dev/null
+++ b/free/ci/scripts/conformance/a06.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# a06.sh: A6 a node with a planted busy process or a low memory floor refuses the job, and
+# `doctor --nodes --json` shows it. CI_CONF_NODE1 is the node; CI_CONF_PLANT is a command that plants the
+# busy process or memory floor on it and prints a cleanup command (run after). Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A6
+conf_need CI_CONF_NODE1 CI_CONF_PLANT
+conf_bin
+cleanup=$(sh -c "$CI_CONF_PLANT" 2>>"$CONF_EVID") || conf_fail "the plant command failed"
+trap 'sh -c "$cleanup" >/dev/null 2>&1' EXIT
+d="$CONF_DIR/job"
+conf_sample go "$d" || conf_fail "sample could not be written"
+out=$(cd "$d" && conf_timeout 300 "$BIN" --where "$CI_CONF_NODE1" --check --no-status --json 2>&1)
+printf '%s\n' "$out" >>"$CONF_EVID"
+printf '%s' "$out" | grep -Eq 'node\.(interactive|not_ready)|resources\.insufficient|capacity\.busy|background\.contention' || conf_fail "the node did not refuse the job with a reason"
+HOME="$CONF_HOME" "$BIN" doctor --nodes --json 2>>"$CONF_EVID" | tee -a "$CONF_EVID" | grep -q "$CI_CONF_NODE1" || conf_fail "status does not show the node"
+conf_pass "node refused with a reason and status shows it"
diff --git a/free/ci/scripts/conformance/a07.sh b/free/ci/scripts/conformance/a07.sh
new file mode 100755
index 000000000..c712a9177
--- /dev/null
+++ b/free/ci/scripts/conformance/a07.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# a07.sh: A7 race across two real nodes: `--where all` finishes with exactly one result and the
+# slower node ends with no job process left. Needs CI_CONF_NODE1 and CI_CONF_NODE2. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A7
+conf_need CI_CONF_NODE1 CI_CONF_NODE2
+conf_bin
+d="$CONF_DIR/race"
+conf_sample go "$d" || conf_fail "sample could not be written"
+out=$(cd "$d" && conf_timeout 600 "$BIN" --where all --check --no-status --json 2>&1) || conf_fail "race run failed"
+printf '%s\n' "$out" >>"$CONF_EVID"
+n=$(printf '%s' "$out" | grep -c '"winner"')
+[ "$n" = "1" ] || conf_fail "race recorded $n winners, want 1"
+printf '%s' "$out" | grep -q 'cancelled' || conf_fail "no sibling was cancelled"
+conf_pass "one winner, the other sibling cancelled"
diff --git a/free/ci/scripts/conformance/a08.sh b/free/ci/scripts/conformance/a08.sh
new file mode 100755
index 000000000..42108fbe8
--- /dev/null
+++ b/free/ci/scripts/conformance/a08.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# a08.sh: A8 selftest and status flag a planted stuck watcher, a leaked temp folder and an infra
+# failure (needs CI_CONF_MAC=local). All three are planted inside the temp HOME of this leg. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A8
+conf_need CI_CONF_MAC
+conf_bin
+mkdir -p "$CONF_HOME/.nself/ci/tmp/leaked-run" "$CONF_HOME/.nself/ci/watch"
+touch -t 202001010000 "$CONF_HOME/.nself/ci/tmp/leaked-run"
+printf '999999 stuck\n' > "$CONF_HOME/.nself/ci/watch/watcher.pid"
+touch -t 202001010000 "$CONF_HOME/.nself/ci/watch/watcher.pid"
+out=$(HOME="$CONF_HOME" CI_CONF_PLANT_INFRA=1 conf_timeout 300 "$BIN" doctor --json 2>&1)
+printf '%s\n' "$out" >>"$CONF_EVID"
+printf '%s' "$out" | grep -qi 'watch' || conf_fail "the stuck watcher was not flagged"
+printf '%s' "$out" | grep -Eqi 'leak|stale|temp' || conf_fail "the leaked temp folder was not flagged"
+st=$(HOME="$CONF_HOME" conf_timeout 120 "$BIN" doctor --nodes --json 2>&1); printf '%s\n' "$st" >>"$CONF_EVID"
+printf '%s' "$st" | grep -Eqi 'fail|warn|infra' || conf_fail "status shows no infra failure"
+conf_pass "stuck watcher, leaked temp folder and infra failure flagged"
diff --git a/free/ci/scripts/conformance/a09.sh b/free/ci/scripts/conformance/a09.sh
new file mode 100755
index 000000000..9448f9dde
--- /dev/null
+++ b/free/ci/scripts/conformance/a09.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# a09.sh: A9 status with one registered node at an unroutable address (the dead-lab entry at
+# TEST-NET 192.0.2.1) among real nodes: status finishes in time, fails that node alone and keeps the
+# real nodes green. Needs CI_CONF_NODE1. The entry is registered in a temp HOME. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A9
+conf_need CI_CONF_NODE1
+conf_bin
+HOME="$CONF_HOME" "$BIN" nodes add dead-lab --ssh ci@192.0.2.1 >>"$CONF_EVID" 2>&1 || conf_skip "cannot register the dead-lab entry with this binary"
+out=$(HOME="$CONF_HOME" conf_timeout 90 "$BIN" doctor --nodes --json 2>&1); rc=$?
+printf '%s\n' "$out" >>"$CONF_EVID"
+[ "$rc" != 124 ] || conf_fail "status hung on the unroutable node"
+printf '%s' "$out" | grep -q 'dead-lab' || conf_fail "status does not name dead-lab"
+conf_pass "status finished; dead-lab reported"
diff --git a/free/ci/scripts/conformance/a10.sh b/free/ci/scripts/conformance/a10.sh
new file mode 100755
index 000000000..77d5f4083
--- /dev/null
+++ b/free/ci/scripts/conformance/a10.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# a10.sh: A10 scope proof with the personal VPS and a coordinator pool: a commit CI run keeps off the
+# personal VPS and uses the coordinator pool. Needs CI_CONF_VPS and CI_CONF_COORD. Exit 0, 1 or 3.
+. "$(dirname "$0")/lib.sh"
+conf_begin A10
+conf_need CI_CONF_VPS CI_CONF_COORD
+conf_bin
+d="$CONF_DIR/scope"
+conf_sample go "$d" || conf_fail "sample could not be written"
+out=$(cd "$d" && conf_timeout 600 "$BIN" --where "$CI_CONF_COORD" --record --check --no-status --json 2>&1) || conf_fail "pool run failed"
+printf '%s\n' "$out" >>"$CONF_EVID"
+printf '%s' "$out" | grep -q "$CI_CONF_VPS" && conf_fail "the personal VPS took a commit CI job"
+conf_pass "commit CI used the coordinator pool and kept off the personal VPS"
diff --git a/free/ci/scripts/conformance/lib.sh b/free/ci/scripts/conformance/lib.sh
new file mode 100644
index 000000000..8ba2413d2
--- /dev/null
+++ b/free/ci/scripts/conformance/lib.sh
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# lib.sh: shared helpers of the hardware conformance legs (P7-AUTO-25). Sourced, never run.
+# Purpose: print one `ci-conformance/v1` JSON line per leg and exit 0 (pass), 1 (fail) or 3 (skip).
+# Inputs (environment, all optional until a leg needs them):
+#   CI_CONF_BIN     the ci binary (default nself-ci)
+#   CI_CONF_OUT     evidence directory (default: a folder under TMPDIR)
+#   CI_CONF_MAC     "local" when this machine is the macOS arm64 host
+#   CI_CONF_LINUX   node id of a linux amd64 node
+#   CI_CONF_NODE1, CI_CONF_NODE2   node ids of two real nodes; CI_CONF_VPS a personal VPS node id
+#   CI_CONF_COORD   a coordinator pool id; CI_CONF_EXTVOL an external volume whose root is 0775
+# Outputs: the leg line on stdout; commands' output goes to the evidence file.
+# Constraints: bash 3.2; a leg never changes the host outside a temp HOME and the sample repo.
+set -u
+
+now_ms() { echo $(( $(date +%s) * 1000 )); }
+
+# jesc escapes a string for a JSON value (control characters dropped).
+jesc() { printf '%s' "$1" | tr -d '\000-\037' | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'; }
+
+conf_begin() {
+  CONF_LEG=$1
+  CONF_START=$(now_ms)
+  : "${TMPDIR:?TMPDIR must be set}"
+  CONF_DIR=$(mktemp -d "${CI_CONF_OUT:-$TMPDIR}/ci-conf-$1.XXXXXX") || exit 2
+  CONF_EVID="$CONF_DIR/evidence.log"
+  CONF_HOME="$CONF_DIR/home"
+  mkdir -p "$CONF_HOME"
+  : > "$CONF_EVID"
+  BIN=${CI_CONF_BIN:-nself-ci}
+}
+
+conf_emit() { # status pass reason
+  printf '{"schema":"ci-conformance/v1","leg":"%s","kind":"hardware","status":"%s","pass":%s,"reason":"%s","evidence_ref":"%s","duration_ms":%s}\n' \
+    "$CONF_LEG" "$1" "$2" "$(jesc "$3")" "$(jesc "$CONF_EVID")" "$(( $(now_ms) - CONF_START ))"
+}
+conf_pass() { conf_emit pass true "${1:-ok}"; exit 0; }
+conf_fail() { conf_emit fail false "$1"; exit 1; }
+conf_skip() { conf_emit skip false "$1"; exit 3; }
+
+# conf_need NAME...: skip unless every named variable is set and non-empty.
+conf_need() {
+  local v
+  for v in "$@"; do
+    eval "[ -n \"\${$v:-}\" ]" || conf_skip "missing host: $v is not set"
+  done
+}
+
+# conf_bin: skip unless the ci binary runs.
+conf_bin() { command -v "$BIN" >/dev/null 2>&1 || conf_skip "missing binary: $BIN"; }
+
+# conf_timeout SECONDS CMD...: run with a deadline; exit 124 on a hang.
+conf_timeout() {
+  local secs=$1 pid waited=0 rc
+  shift
+  "$@" & pid=$!
+  while kill -0 "$pid" 2>/dev/null; do
+    if [ "$waited" -ge "$secs" ]; then kill "$pid" 2>/dev/null; wait "$pid" 2>/dev/null; return 124; fi
+    sleep 1; waited=$((waited + 1))
+  done
+  wait "$pid"; rc=$?
+  return $rc
+}
+
+# conf_ci ARGS...: run the binary with a temp HOME, appending output to the evidence file.
+conf_ci() { HOME="$CONF_HOME" "$BIN" "$@" >>"$CONF_EVID" 2>&1; }
+
+# conf_sample KIND DIR: write a tiny repository of KIND go, node or gonode.
+conf_sample() {
+  local kind=$1 dir=$2
+  mkdir -p "$dir" && git -C "$dir" init -q || return 1
+  case "$kind" in
+    go|gonode)
+      printf 'module sample\n\ngo 1.22\n' > "$dir/go.mod"
+      printf 'package sample\n\nfunc One() int { return 1 }\n' > "$dir/sample.go"
+      printf 'package sample\n\nimport "testing"\n\nfunc TestOne(t *testing.T) {\n\tif One() != 1 {\n\t\tt.Fatal("one")\n\t}\n}\n' > "$dir/sample_test.go" ;;
+  esac
+  case "$kind" in
+    node|gonode)
+      printf '{"name":"sample","version":"0.0.0","scripts":{"test":"node -e 0"}}\n' > "$dir/package.json" ;;
+  esac
+  git -C "$dir" add . && git -C "$dir" -c user.name=conf -c user.email=conf@localhost commit -q -m sample
+}
+
+# conf_table WHERE DIR: the gate table of DIR on WHERE with timings removed, one row per line.
+conf_table() {
+  (cd "$2" && HOME="$CONF_HOME" conf_timeout 600 "$BIN" --where "$1" --check --no-status --json 2>>"$CONF_EVID") \
+    | grep -E '"(gate|job|status)"' | sed -E 's/"(duration|elapsed|started|finished)[a-z_]*":[^,}]*,?//g' | sort
+}
diff --git a/free/ci/surface/commands.yaml b/free/ci/surface/commands.yaml
new file mode 100644
index 000000000..63a4a104d
--- /dev/null
+++ b/free/ci/surface/commands.yaml
@@ -0,0 +1,911 @@
+# GENERATED INPUT BOUNDARY: the one authored declaration of the ci plugin machine surface (P7-CI-62, CI D31).
+# free/ci/plugin.json `commands` is generated from this file by tools/manifestgen (go generate); never edit that block by hand.
+# Keys: one row per key of cmd/subcommands.go (and per `runs <sub>`); cmd/surface_test.go fails on any difference.
+binary: nself-ci
+command: ci
+
+root:
+  summary: "Run the nself-ci gate suite and post a GitHub commit status"
+  side_effect: remote
+  output: document
+  json: envelope
+  confirm: {flags: []}
+  args: [{name: command, variadic: true}]
+  flags:
+    - {name: "base", type: "string"}
+    - {name: "config", type: "string"}
+    - {name: "confirm-flaky", type: "int", default: "0"}
+    - {name: "container", type: "bool"}
+    - {name: "coordinator", type: "string"}
+    - {name: "detach", type: "bool"}
+    - {name: "force", type: "bool"}
+    - {name: "image", type: "string"}
+    - {name: "isolation", type: "string"}
+    - {name: "job", type: "string"}
+    - {name: "json", type: "bool", cli_only: true}
+    - {name: "max-queue", type: "string"}
+    - {name: "network", type: "string"}
+    - {name: "no-status", type: "bool"}
+    - {name: "pipeline", type: "string"}
+    - {name: "post-status", type: "bool"}
+    - {name: "prefer", type: "string"}
+    - {name: "repo", type: "string"}
+    - {name: "runner", type: "string"}
+    - {name: "service", type: "stringSlice"}
+    - {name: "stream", type: "bool", cli_only: true}
+    - {name: "timeout", type: "duration", default: "0s"}
+    - {name: "trigger", type: "string"}
+    - {name: "trust", type: "string"}
+    - {name: "where", type: "string"}
+
+commands:
+  - path: artifacts
+    summary: "List, show, fetch and prune stored run artifacts"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: subcommand}, {name: name}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+  - path: build
+    summary: "Build a signed release artifact locally (Android only)"
+    side_effect: remote
+    output: document
+    json: none
+    args: [{name: android-project-dir}]
+    flags:
+      - {name: "artifact", type: "string", default: "android", usage: "Artifact type to build (only \"android\" is supported)"}
+      - {name: "owner", type: "string", usage: "GitHub owner for --upload (default: from git remote)"}
+      - {name: "repo", type: "string", usage: "GitHub repo for --upload (default: from git remote)"}
+      - {name: "tag", type: "string", usage: "Release tag to upload to (required with --upload)"}
+      - {name: "timeout", type: "int", default: "900", usage: "Build step timeout in seconds (release builds are slow)"}
+      - {name: "upload", type: "bool", default: "false", side_effect: "remote", usage: "Attach the built artifact to a GitHub release via `gh release upload`"}
+      - {name: "verbose", type: "bool", default: "false", shorthand: "v", usage: "Print each command before running"}
+  - path: config ignore add
+    summary: "Append a reviewed fingerprint to .gitleaksignore (--reason required)"
+    side_effect: write
+    output: document
+    json: none
+    args: [{name: fingerprint}]
+    flags:
+      - {name: "by", type: "string"}
+      - {name: "reason", type: "string"}
+      - {name: "repo", type: "string"}
+  - path: config migrate
+    summary: "Migrate .nself/ci.yaml to the current schema (--write applies)"
+    side_effect: write
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+      - {name: "write", type: "bool"}
+  - path: config show
+    summary: "Show the resolved CI configuration"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "config", type: "string"}
+      - {name: "home", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "no-status", type: "bool"}
+      - {name: "repo", type: "string"}
+      - {name: "timeout", type: "string"}
+  - path: doctor
+    summary: "Check the CI environment, nodes and providers (--selftest [--alert] for an unattended host)"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "alert", type: "bool"}
+      - {name: "nodes", type: "bool"}
+      - {name: "providers", type: "bool"}
+      - {name: "repo", type: "string"}
+      - {name: "selftest", type: "bool"}
+  - path: evidence
+    summary: "Show the evidence document of a revision"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: revision}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "pipeline", type: "string"}
+      - {name: "repo", type: "string"}
+  - path: evidence verify
+    summary: "Verify the evidence of a revision against the policy"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: revision}]
+    flags:
+      - {name: "at-revision", type: "string"}
+      - {name: "file", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "policy", type: "string", default: "required"}
+      - {name: "repo", type: "string"}
+      - {name: "stream", type: "bool"}
+  - path: explain
+    summary: "Explain why a job was or was not planned"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: job}]
+    flags:
+      - {name: "base", type: "string"}
+      - {name: "config", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "max-queue", type: "string"}
+      - {name: "pipeline", type: "string"}
+      - {name: "prefer", type: "string"}
+      - {name: "repo", type: "string"}
+      - {name: "runner", type: "string"}
+      - {name: "trigger", type: "string"}
+  - path: forgejo
+    summary: "Show Forgejo server health (ops profile)"
+    side_effect: read
+    output: document
+    json: none
+    flags:
+      - {name: "runner", type: "string", usage: "Runner container name (default: <PROJECT>_forgejo_runner)"}
+      - {name: "url", type: "string", default: "http://localhost:3844", usage: "Forgejo base URL"}
+  - path: logs
+    summary: "Print the logs of a run attempt (-f follows)"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: run}]
+    flags:
+      - {name: "attempt", type: "int", default: "0"}
+      - {name: "f", type: "bool", cli_only: true}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "run", type: "string"}
+  - path: netproxy
+    summary: "Internal egress proxy used by restricted jobs"
+    side_effect: remote
+    output: interactive
+    json: none
+    surface: cli-only
+    flags:
+      - {name: "probe", type: "bool"}
+      - {name: "proxy", type: "string"}
+  - path: nodes add
+    summary: "Add and provision a CI node"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: host}]
+    flags:
+      - {name: "accepts", type: "string"}
+      - {name: "agent-binary", type: "string"}
+      - {name: "allow-deploy-host", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "host-key", type: "string"}
+      - {name: "installer", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "name", type: "string"}
+      - {name: "ownership", type: "string", default: "operator"}
+      - {name: "privacy-zone", type: "string"}
+      - {name: "project", type: "string"}
+      - {name: "secret-classes", type: "string"}
+      - {name: "slots", type: "int", default: "2"}
+      - {name: "system", type: "bool"}
+  - path: nodes discover
+    summary: "Discover nodes on the local network"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "timeout", type: "duration", default: "5s"}
+  - path: nodes drain
+    summary: "Stop placing new jobs on a node"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes enable
+    summary: "Place jobs on a node again"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes forget-project
+    summary: "Forget a project's node records on this host (local, audited)"
+    side_effect: destructive
+    output: document
+    json: none
+    surface: cli-only
+    args: [{name: project-root}]
+  - path: nodes label
+    summary: "Set or remove node labels (key=value)"
+    side_effect: write
+    output: document
+    json: envelope
+    args: [{name: node}, {name: label}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "remove", type: "string"}
+  - path: nodes list
+    summary: "List nodes"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes pair
+    summary: "Pair an agent node (foreground enrollment listener)"
+    side_effect: remote
+    output: interactive
+    json: none
+    surface: cli-only
+    args: [{name: node}]
+    flags:
+      - {name: "agent-url", type: "string"}
+      - {name: "cert-ttl", type: "duration", default: "0s"}
+      - {name: "coordinator-id", type: "string", default: "local"}
+      - {name: "data-dir", type: "string"}
+      - {name: "enroll-addr", type: "string", default: ":3866"}
+      - {name: "label", type: "string"}
+      - {name: "public-url", type: "string"}
+  - path: nodes pools explain
+    summary: "Explain a project's effective pool set and every excluded runner"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "string"}
+  - path: nodes pools list
+    summary: "List runner pools and whether the project may use them"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "string"}
+  - path: nodes pools show
+    summary: "Show one runner pool"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: pool}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "string"}
+  - path: nodes projects add
+    summary: "Authorize projects on a node"
+    side_effect: write
+    output: document
+    json: envelope
+    args: [{name: node}, {name: project}]
+    flags:
+      - {name: "all", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes projects list
+    summary: "List the projects a node is authorized for"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: node}]
+    flags:
+      - {name: "all", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes projects remove
+    summary: "Remove project authorizations from a node"
+    side_effect: write
+    output: document
+    json: envelope
+    args: [{name: node}, {name: project}]
+    flags:
+      - {name: "all", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes provision
+    summary: "Install runner dependencies, user, sudoers, and N runner instances"
+    side_effect: remote
+    output: document
+    json: legacy
+    surface: cli-only
+    flags:
+      - {name: "github-url", type: "string", usage: "Repo or org URL runners register against, e.g. https://github.com/nself-org/cli"}
+      - {name: "host", type: "stringSlice", default: "[]", usage: "SSH target(s) user@host to provision (repeatable). Default: this machine."}
+      - {name: "install-root", type: "string", usage: "Base install directory (default: /opt/actions-runner)"}
+      - {name: "instances", type: "int", default: "1", usage: "Number of runner instances to install on this host"}
+      - {name: "json", type: "bool", default: "false", usage: "V15 only (NSELF_V15=1): print one v1 JSON envelope; in v1.4 the flag is refused as today"}
+      - {name: "labels", type: "stringSlice", default: "[]", usage: "Extra labels appended after self-hosted,Linux,X64"}
+      - {name: "ssh-key", type: "string", usage: "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"}
+      - {name: "token", type: "string", usage: "GitHub Actions runner registration token (overrides GITHUB_RUNNER_TOKEN env). Never logged."}
+  - path: nodes remove
+    summary: "Remove a node and its registration"
+    side_effect: destructive
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes revoke
+    summary: "Revoke a node credential"
+    side_effect: destructive
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes rotate
+    summary: "Rotate a node host key, certificate or node key"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "cert", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "host-key", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "key-id", type: "string"}
+      - {name: "mode", type: "string", default: "host-key"}
+      - {name: "node-key", type: "bool"}
+  - path: nodes secrets grant
+    summary: "Grant a node access to a secret class"
+    side_effect: remote
+    output: interactive
+    json: none
+    surface: cli-only
+    args: [{name: node}]
+    flags:
+      - {name: "class", type: "string"}
+      - {name: "project", type: "string"}
+  - path: nodes secrets revoke
+    summary: "Revoke a node access to a secret class"
+    side_effect: remote
+    output: interactive
+    json: none
+    surface: cli-only
+    args: [{name: node}]
+    flags:
+      - {name: "class", type: "string"}
+      - {name: "project", type: "string"}
+  - path: nodes set
+    summary: "Set contention and persistence policy of a node"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "interactive", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "on-battery", type: "string"}
+      - {name: "persistence", type: "string"}
+      - {name: "project", type: "string"}
+      - {name: "reserve-cpu", type: "string"}
+      - {name: "reserve-mem", type: "string"}
+  - path: nodes show
+    summary: "Show one node"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes status
+    summary: "Show readiness, watcher, queue and last results of every node"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "local", type: "bool"}
+  - path: nodes sync
+    summary: "Import an inventory/v1 file or command output over the node registry"
+    side_effect: write
+    output: document
+    json: envelope
+    flags:
+      - {name: "cmd", type: "string"}
+      - {name: "dry-run", type: "bool"}
+      - {name: "from", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes test
+    summary: "Probe a node and report its capabilities"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: nodes upgrade
+    summary: "Upgrade node agents"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: node}]
+    flags:
+      - {name: "all", type: "bool"}
+      - {name: "allow-downgrade", type: "bool"}
+      - {name: "coordinator", type: "string"}
+      - {name: "drain-wait", type: "duration", default: "10m0s"}
+      - {name: "hello-wait", type: "duration", default: "1m0s"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "version", type: "string"}
+  - path: nodes verify
+    summary: "Check host(s) against the dependency manifest and report drift"
+    side_effect: read
+    output: document
+    json: legacy
+    surface: cli-only
+    flags:
+      - {name: "host", type: "stringSlice", default: "[]", usage: "SSH target(s) user@host to verify (repeatable). Default: this machine."}
+      - {name: "json", type: "bool", default: "false", usage: "Print JSON instead of the text parity matrix: raw []HostReport in v1.4, one v1 envelope in V15 (NSELF_V15=1)"}
+      - {name: "ssh-key", type: "string", usage: "SSH private key path (default: NSELF_DEPLOY_KEY_PATH or ~/.ssh/id_ed25519)"}
+  - path: plan
+    summary: "Plan a run without executing it"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "base", type: "string"}
+      - {name: "config", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "max-queue", type: "string"}
+      - {name: "pipeline", type: "string"}
+      - {name: "prefer", type: "string"}
+      - {name: "repo", type: "string"}
+      - {name: "runner", type: "string"}
+      - {name: "trigger", type: "string"}
+  - path: policy pin
+    summary: "Pin or clear the trusted revision"
+    side_effect: write
+    output: document
+    json: envelope
+    surface: cli-only
+    args: [{name: sha}]
+    flags:
+      - {name: "clear", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: policy protect
+    summary: "Show or apply branch protection that requires the nself-ci check"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    flags:
+      - {name: "app-id", type: "int", default: "15368"}
+      - {name: "audit", type: "int", default: "0"}
+      - {name: "branch", type: "string"}
+      - {name: "dry-run", type: "bool"}
+      - {name: "hook", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+      - {name: "restore", type: "string"}
+  - path: policy set
+    summary: "Set an operator policy key"
+    side_effect: write
+    output: document
+    json: envelope
+    surface: cli-only
+    args: [{name: key}, {name: value}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "scope", type: "string"}
+      - {name: "team", type: "string"}
+  - path: policy show
+    summary: "Show the operator policy"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: key}]
+    flags:
+      - {name: "effective", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "team", type: "string"}
+  - path: policy unset
+    summary: "Unset an operator policy key"
+    side_effect: write
+    output: document
+    json: envelope
+    surface: cli-only
+    args: [{name: key}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "scope", type: "string"}
+      - {name: "team", type: "string"}
+  - path: policy usage
+    summary: "Show spend and usage against the policy"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+  - path: providers
+    summary: "Provider command group help"
+    side_effect: read
+    output: document
+    json: none
+    surface: cli-only
+  - path: providers authorize
+    summary: "Authorize a project for hosted runners"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: provider}]
+    flags:
+      - {name: "allow-private", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "string"}
+  - path: providers github init
+    summary: "Render the GitHub dispatch workflow"
+    side_effect: write
+    output: document
+    json: envelope
+    flags:
+      - {name: "agent-source", type: "string"}
+      - {name: "check", type: "bool"}
+      - {name: "dir", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "stdout", type: "bool"}
+  - path: providers gitlab init
+    summary: "Render the GitLab dispatch pipeline"
+    side_effect: write
+    output: document
+    json: envelope
+    flags:
+      - {name: "check", type: "bool"}
+      - {name: "dir", type: "string"}
+      - {name: "inputs", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "stdout", type: "bool"}
+      - {name: "untrusted-dir", type: "string"}
+  - path: providers list
+    summary: "List providers"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+  - path: providers revoke
+    summary: "Revoke a project authorization for hosted runners"
+    side_effect: destructive
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: provider}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "string"}
+  - path: providers show
+    summary: "Show one provider"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: provider}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+  - path: providers test
+    summary: "Probe a provider"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: provider}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+  - path: providers usage import
+    summary: "Import provider usage records"
+    side_effect: write
+    output: document
+    json: envelope
+    args: [{name: file}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+  - path: run
+    summary: "Discover .ci.yaml manifests and run their stages (pipeline)"
+    side_effect: remote
+    output: document
+    json: none
+    args: [{name: search-root}]
+    flags:
+      - {name: "env", type: "string", usage: "Target environment: local"}
+      - {name: "gateway", type: "string", usage: "Explicit gateway base URL (e.g. http://host:3761)"}
+      - {name: "v", type: "bool", usage: "Print each command before running"}
+      - {name: "timeout", type: "int", default: "300", usage: "Per-step timeout in seconds"}
+  - path: runs
+    summary: "Show a run, or the flaky checks (--flaky)"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: run}]
+    flags:
+      - {name: "flaky", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: runs approve
+    summary: "Approve a run that waits for approval"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: run}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "sha", type: "string"}
+      - {name: "spend", type: "bool"}
+  - path: runs cancel
+    summary: "Cancel a run"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: run}]
+  - path: runs decisions
+    summary: "Show the scheduling decisions of a run"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: run}]
+  - path: runs follow
+    summary: "Follow the events of a run as an NDJSON stream"
+    side_effect: read
+    output: stream
+    json: envelope
+    args: [{name: run}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "from-seq", type: "int", default: "0"}
+      - {name: "json", type: "bool", cli_only: true}
+  - path: runs list
+    summary: "List recent runs"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "limit", type: "int", default: "20"}
+      - {name: "repo", type: "string"}
+  - path: runs outbox
+    summary: "Show queued status and event deliveries"
+    side_effect: read
+    output: document
+    json: envelope
+  - path: runs pending
+    summary: "List runs waiting for approval"
+    side_effect: read
+    output: document
+    json: envelope
+  - path: runs prune
+    summary: "Remove old runs and logs (--dry-run previews; --tidy [--apply] also tidies cache and job roots)"
+    side_effect: destructive
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    flags:
+      - {name: "apply", type: "bool"}
+      - {name: "dry-run", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "keep", type: "int", default: "0"}
+      - {name: "limit", type: "int", default: "20"}
+      - {name: "max-age-days", type: "int", default: "0"}
+      - {name: "max-log-bytes", type: "int"}
+      - {name: "repo", type: "string"}
+      - {name: "tidy", type: "bool"}
+  - path: runs queue
+    summary: "Show the run queue"
+    side_effect: read
+    output: document
+    json: envelope
+  - path: runs reproduce
+    summary: "Reproduce a job at its recorded inputs"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: job}]
+    flags:
+      - {name: "check", type: "bool"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+      - {name: "run", type: "string"}
+      - {name: "shell", type: "bool"}
+  - path: runs rerun
+    summary: "Run a recorded revision again on a chosen target"
+    side_effect: remote
+    output: document
+    json: envelope
+    confirm: {flags: []}
+    args: [{name: run-or-sha}]
+    flags:
+      - {name: "job", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "repo", type: "string"}
+      - {name: "where", type: "string"}
+  - path: runs resolve
+    summary: "Resolve a pending run decision"
+    side_effect: write
+    output: document
+    json: envelope
+    args: [{name: run}]
+  - path: runs stats
+    summary: "Show run statistics"
+    side_effect: read
+    output: document
+    json: envelope
+  - path: runs wait
+    summary: "Wait for a run to finish and print its result"
+    side_effect: read
+    output: document
+    json: envelope
+    args: [{name: run}]
+    flags:
+      - {name: "coordinator", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "timeout", type: "duration", default: "4m0s"}
+  - path: serve
+    summary: "Start the nself-ci webhook listener daemon (port 3845)"
+    side_effect: write
+    output: stream
+    json: none
+    surface: cli-only
+    flags:
+      - {name: "addr", type: "string", default: ":3845", usage: "Listen address (host:port). Port 3845 = nself-ci-serve per F10 port registry"}
+      - {name: "allow-unsandboxed", type: "bool", default: "false", side_effect: "destructive", usage: "DANGEROUS: run the gate directly on this host when Docker is unavailable, instead of refusing the job. Default: refuse."}
+      - {name: "allowed-repos", type: "stringSlice", default: "[]", usage: "Comma-separated or repeatable \"owner/repo\" allowlist. Default: empty, which rejects every job (fail-closed, no \"allow all\")."}
+      - {name: "concurrency", type: "int", default: "2", usage: "Max concurrent CI jobs"}
+      - {name: "insecure", type: "bool", default: "false", usage: "DANGEROUS: start without a webhook secret (disables signature verification). Default: refuse to start when no secret is configured."}
+      - {name: "secret", type: "string", usage: "HMAC-SHA256 webhook secret (overrides GITHUB_WEBHOOK_SECRET env)"}
+      - {name: "timeout", type: "int", default: "600", usage: "Per-job timeout in seconds"}
+      - {name: "verbose", type: "bool", default: "false", shorthand: "v", usage: "Verbose gate output"}
+      - {name: "workdir", type: "string", default: "/tmp/nself-ci-workdirs", usage: "Base directory for ephemeral checkout workdirs"}
+  - path: serve admin
+    summary: "Coordinator admin group help"
+    side_effect: read
+    output: document
+    json: none
+    surface: cli-only
+  - path: serve admin audit
+    summary: "Read or verify the audit log"
+    side_effect: read
+    output: document
+    json: envelope
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "since", type: "string"}
+      - {name: "verify", type: "bool"}
+  - path: serve admin audit checkpoint
+    summary: "Write a signed audit checkpoint"
+    side_effect: write
+    output: document
+    json: envelope
+    surface: cli-only
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "pubkey", type: "string"}
+  - path: serve admin cert
+    summary: "Issue a user mTLS certificate (printed once)"
+    side_effect: write
+    output: document
+    json: envelope
+    surface: cli-only
+    args: [{name: verb}, {name: principal}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "self", type: "bool"}
+      - {name: "ttl", type: "duration", default: "168h0m0s"}
+  - path: serve admin roles
+    summary: "Grant, revoke or list roles"
+    side_effect: destructive
+    output: document
+    json: envelope
+    surface: cli-only
+    confirm: {flags: []}
+    args: [{name: verb}, {name: principal}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "stringSlice"}
+      - {name: "role", type: "string"}
+      - {name: "self", type: "bool"}
+  - path: serve admin token
+    summary: "Issue, revoke or list scoped user tokens"
+    side_effect: destructive
+    output: document
+    json: envelope
+    surface: cli-only
+    confirm: {flags: []}
+    args: [{name: verb}, {name: principal}]
+    flags:
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "project", type: "stringSlice"}
+      - {name: "role", type: "string"}
+      - {name: "self", type: "bool"}
+      - {name: "ttl", type: "duration", default: "0s"}
+  - path: serve backup
+    summary: "Back up the coordinator data directory"
+    side_effect: read
+    output: document
+    json: envelope
+    surface: cli-only
+    flags:
+      - {name: "data-dir", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "out", type: "string"}
+  - path: serve restore
+    summary: "Restore the coordinator data directory from a backup"
+    side_effect: destructive
+    output: interactive
+    json: none
+    surface: cli-only
+    flags:
+      - {name: "data-dir", type: "string"}
+      - {name: "in", type: "string"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "kek", type: "string", secret: true}
+  - path: serve install
+    summary: "Install the watcher service and hourly selftest"
+    side_effect: write
+    output: document
+    json: none
+    surface: cli-only
+    flags:
+      - {name: "launchd", type: "bool"}
+      - {name: "systemd", type: "bool"}
+      - {name: "user", type: "bool"}
+      - {name: "system", type: "bool"}
+      - {name: "dry-run", type: "bool"}
+      - {name: "binary", type: "string"}
+      - {name: "repo", type: "string"}
+      - {name: "env-file", type: "string"}
+  - path: serve watch
+    summary: "Keep commit CI current by polling, without an inbound port"
+    side_effect: remote
+    output: stream
+    json: envelope
+    surface: cli-only
+    flags:
+      - {name: "interval", type: "duration", default: "0s"}
+      - {name: "json", type: "bool", cli_only: true}
+      - {name: "once", type: "bool"}
+      - {name: "repos", type: "stringSlice"}
+  - path: serve uninstall
+    summary: "Remove unchanged watcher service files"
+    side_effect: destructive
+    output: document
+    json: none
+    surface: cli-only
+    flags:
+      - {name: "launchd", type: "bool"}
+      - {name: "systemd", type: "bool"}
+      - {name: "user", type: "bool"}
+      - {name: "system", type: "bool"}
+      - {name: "dry-run", type: "bool"}
+      - {name: "binary", type: "string"}
+      - {name: "repo", type: "string"}
+      - {name: "env-file", type: "string"}
diff --git a/free/ci/templates/audit-pipeline.yml b/free/ci/templates/audit-pipeline.yml
new file mode 100644
index 000000000..878f5e6ed
--- /dev/null
+++ b/free/ci/templates/audit-pipeline.yml
@@ -0,0 +1,35 @@
+# Audit pipeline for an unattended CI host.
+#
+# Purpose: a scheduled pipeline that runs the dependency and race audits
+#   (govulncheck, pnpm audit, go test -race) when the host has nothing else to
+#   do. `audit` is not a command: merge the `jobs` and `pipelines` blocks below
+#   into the project's .nself/ci.yaml.
+# How it starts: the only trigger is `schedule`, so its jobs run in the
+#   background band, behind every interactive and normal job. On a host that runs
+#   `nself ci serve watch`, a pass that ran no commit starts one due background
+#   pipeline, and only when the host is ready; a host that is not ready starts
+#   nothing. `max_age` makes an overdue audit show in `nself ci evidence
+#   --pipeline audit`.
+# Constraints: needs govulncheck, pnpm and go on the PATH the service runs with
+#   (`nself ci doctor --selftest` checks it); drop the pnpm job in a project
+#   without a pnpm lockfile. The race job needs cgo on the host.
+
+version: 1
+
+jobs:
+  audit-govulncheck:
+    kind: quality
+    run: [govulncheck, ./...]
+  audit-pnpm:
+    kind: quality
+    run: [pnpm, audit, --audit-level, high]
+  audit-race:
+    kind: test
+    run: [go, test, -race, ./...]
+
+pipelines:
+  audit:
+    triggers: [schedule]
+    schedule: "41 2 * * *"
+    max_age: 48h
+    jobs: [audit-govulncheck, audit-pnpm, audit-race]
diff --git a/free/ci/test/cachesec/artifact_test.go b/free/ci/test/cachesec/artifact_test.go
new file mode 100644
index 000000000..8e4546894
--- /dev/null
+++ b/free/ci/test/cachesec/artifact_test.go
@@ -0,0 +1,119 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"encoding/base64"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/artifacts/records"
+	"github.com/nself-org/plugins/free/ci/internal/authz"
+	"github.com/nself-org/plugins/free/ci/internal/cache/specs"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func artifactPolicy() records.Policy {
+	return records.Policy{MaxFile: 32 << 20, MaxTotal: 64 << 20, Statfs: func(string) (uint64, uint64, error) { return 1 << 40, 2 << 40, nil }}
+}
+
+func (r *rig) secret(id string) error {
+	// This generated marker is registered only in this isolated test redactor.
+	marker := []byte("fixture-" + digest([]byte(r.home)))
+	must(r.t, r.red.Register(marker))
+	payload := marker
+	if strings.HasSuffix(id, "base64") {
+		payload = []byte(base64.StdEncoding.EncodeToString(marker))
+	}
+	ws := r.t.TempDir()
+	must(r.t, os.Mkdir(filepath.Join(ws, "data"), 0o700))
+	must(r.t, os.WriteFile(filepath.Join(ws, "data", "payload"), payload, 0o600))
+	var err error
+	if strings.HasPrefix(id, "cache-") {
+		base, e := os.OpenRoot(ws)
+		must(r.t, e)
+		defer base.Close()
+		_, err = r.engine.Save(r.ctx, specs.SaveRequest{Base: base, Attempt: "writer", Epoch: 3, Namespace: namespace(r.t, owner()), Key: key(r.t, owner()), Spec: specs.Spec{ID: "go"}, Dirs: specs.Dirs{"data": "data"}})
+	} else {
+		c := records.Collector{Blobs: r.blobs, Scanner: r.red, Policy: artifactPolicy(), Audit: r.st.AppendAudit, Target: "writer"}
+		_, err = c.Collect(r.ctx, "project", ws, []records.Decl{{Path: "data/payload", Kind: records.KindBinary, Retention: "30d", Visibility: authz.VisibilityProject}})
+	}
+	r.noEntries()
+	if len(tree(r.t, filepath.Join(r.home, "blobs"))) != 0 {
+		r.t.Error("secret scan published blob bytes")
+	}
+	if err != nil && (strings.Contains(err.Error(), string(marker)) || strings.Contains(err.Error(), string(payload))) {
+		r.t.Fatal("refusal exposed the registered marker")
+	}
+	return err
+}
+
+func (r *rig) artifactStage(id string) records.Record {
+	r.running(id, owner())
+	d := records.Decl{Path: "app", Kind: records.KindBinary, Retention: "30d", Visibility: authz.VisibilityProject}
+	must(r.t, r.st.ArtifactDeclare(r.ctx, id, 2, []records.Decl{d}))
+	f, err := r.st.ArtifactFacts(r.ctx, id)
+	must(r.t, err)
+	recs := records.ToRecords(id, f, 2, []records.Staged{{Decl: d, Name: "app", Rel: "app", SHA256: digest([]byte(id)), Size: int64(len(id))}}, time.Now())
+	must(r.t, r.st.ArtifactStage(r.ctx, id, 2, recs))
+	must(r.t, r.st.Transition(r.ctx, id, "running", "finalizing", store.TransitionDetail{Epoch: 2}))
+	return recs[0]
+}
+
+func (r *rig) artifactMutation(id string) error {
+	a := r.artifactStage("attempt-a")
+	b := r.artifactStage("attempt-b")
+	if a.ID == b.ID {
+		r.t.Fatal("attempts share artifact identity")
+	}
+	before, err := r.st.ArtifactStaged(r.ctx, "attempt-a")
+	must(r.t, err)
+	changed := a
+	if id == "artifact-overwrite" {
+		changed.SHA256 = digest([]byte("replacement"))
+	} else {
+		changed = b
+	}
+	_, err = r.st.ArtifactCommit(r.ctx, "attempt-a", 3, []records.Record{changed}, artifactPolicy())
+	after, e := r.st.ArtifactStaged(r.ctx, "attempt-a")
+	must(r.t, e)
+	if !reflect.DeepEqual(before, after) {
+		r.t.Error("refused commit mutated staged records")
+	}
+	rows, e := r.st.ArtifactList(r.ctx, records.Filter{Project: "project"})
+	must(r.t, e)
+	for _, row := range rows {
+		if row.State == records.StateCommitted {
+			r.t.Error("substitution committed an artifact")
+		}
+	}
+	return err
+}
+
+func (r *rig) getDest(id string) error {
+	cwd := r.t.TempDir()
+	dest := "."
+	if id == "get-nonempty" {
+		dest = "out"
+		must(r.t, os.Mkdir(filepath.Join(cwd, dest), 0o700))
+		must(r.t, os.WriteFile(filepath.Join(cwd, dest, "sentinel"), []byte("keep"), 0o600))
+	}
+	if id == "get-hooks" {
+		dest = ".git/hooks"
+		must(r.t, os.MkdirAll(filepath.Join(cwd, dest), 0o700))
+	}
+	before := tree(r.t, cwd)
+	rec := r.artifactStage("download")
+	_, err := r.st.ArtifactCommit(r.ctx, "download", 3, []records.Record{rec}, artifactPolicy())
+	must(r.t, err)
+	// A visible committed record ensures the real download reaches the destination check.
+	reader := records.Reader{Ledger: r.st, Blobs: r.blobs, Audit: r.st.AppendAudit}
+	_, _, err = reader.Get(r.ctx, authz.Viewer{Project: "project", Role: authz.RoleMember}, rec.ID, dest, cwd)
+	if !reflect.DeepEqual(before, tree(r.t, cwd)) {
+		r.t.Error("refused download changed the destination")
+	}
+	return err
+}
diff --git a/free/ci/test/cachesec/cache_test.go b/free/ci/test/cachesec/cache_test.go
new file mode 100644
index 000000000..6b865bc50
--- /dev/null
+++ b/free/ci/test/cachesec/cache_test.go
@@ -0,0 +1,142 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/authz"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/cache/specs"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func (r *rig) cacheWrite(id string) error {
+	f, target := owner(), owner()
+	switch id {
+	case "fork-main":
+		f = fork("1")
+	case "pr-a-pr-b":
+		f, target = fork("1"), fork("2")
+	}
+	k := key(r.t, f)
+	r.finalizing("writer", f, k)
+	epoch := int64(3)
+	if id == "ended-local" {
+		must(r.t, r.st.Transition(r.ctx, "writer", "finalizing", "passed", store.TransitionDetail{Epoch: 3}))
+	}
+	if id == "epoch-local" {
+		epoch = 2
+	}
+	if id == "field-boundary-collision" {
+		a := entries.KeyInputs{Namespace: namespace(r.t, f), SpecID: "ab", SpecVersion: "c"}
+		b := a
+		b.SpecID, b.SpecVersion = "a", "bc"
+		ka, err := entries.Key(a)
+		must(r.t, err)
+		kb, err := entries.Key(b)
+		must(r.t, err)
+		if ka == kb {
+			r.t.Fatal("field boundaries collide")
+		}
+		// A valid key that was not planned must not alias the planned key.
+		k = kb
+	}
+	// Missing blobs are intentional: authorization must run before blob checks.
+	m := entries.Manifest{Namespace: namespace(r.t, target).Canonical(), Key: k, Spec: "go", Blobs: []entries.Blob{{Path: "data", SHA256: strings.Repeat("a", 64), Size: 1}}}
+	err := r.entries.Commit(r.ctx, "writer", epoch, namespace(r.t, target), m)
+	r.noEntries()
+	if len(tree(r.t, filepath.Join(r.home, "blobs"))) != 0 {
+		r.t.Error("unauthorized write left blob bytes")
+	}
+	return err
+}
+
+func (r *rig) restore(id string) error {
+	f := owner()
+	if id == "secret-snapshot" {
+		f.SecretsDeclared = true
+	}
+	k := key(r.t, f)
+	r.finalizing("writer", f, k)
+	b := r.archive(id)
+	m := r.manifest(f, k, b)
+	must(r.t, r.entries.Commit(r.ctx, "writer", 3, namespace(r.t, f), m))
+	must(r.t, r.st.Transition(r.ctx, "writer", "finalizing", "passed", store.TransitionDetail{Epoch: 3}))
+	if id == "corrupt-local" || id == "partial-local" {
+		d := m.Blobs[0].SHA256
+		p := filepath.Join(r.home, "blobs", string(cacheRealm(m.Namespace)), "sha256", d[:2], d)
+		changed := append([]byte(nil), b...)
+		if id == "partial-local" {
+			changed = changed[:len(changed)/2]
+		} else {
+			changed[512] ^= 1
+		}
+		must(r.t, os.WriteFile(p, changed, 0o600))
+	}
+	dest := r.t.TempDir()
+	base, err := os.OpenRoot(dest)
+	must(r.t, err)
+	defer base.Close()
+	access := authz.ModeRWOwn
+	if id == "secret-snapshot" {
+		access = authz.ModeROSnapshot
+	}
+	hit, n, err := r.engine.Restore(r.ctx, base, namespace(r.t, f), k, access, specs.Spec{ID: "go"}, specs.Dirs{"data": "restored"}, specs.UnpackOptions{})
+	if hit || n != 0 {
+		r.t.Error("crafted cache was restored")
+	}
+	if len(tree(r.t, dest)) != 0 {
+		r.t.Error("refused restore left bytes")
+	}
+	if err == nil {
+		r.note = "restore returned a miss (hit=false, 0 bytes restored), not a refusal"
+	}
+	return err
+}
+
+func (r *rig) archive(id string) []byte {
+	h := &tar.Header{Name: "payload", Mode: 0o600, Size: 1, Typeflag: tar.TypeReg}
+	content := []byte("x")
+	switch id {
+	case "restore-traversal":
+		h.Name = "../escape"
+	case "restore-absolute":
+		h.Name = "/escape"
+	case "restore-symlink":
+		h.Typeflag, h.Size, h.Linkname = tar.TypeSymlink, 0, "../../escape"
+		content = nil
+	case "restore-hardlink":
+		h.Typeflag, h.Size, h.Linkname = tar.TypeLink, 0, "../../escape"
+		content = nil
+	case "restore-fifo":
+		h.Typeflag, h.Size = tar.TypeFifo, 0
+		content = nil
+	case "restore-device":
+		h.Typeflag, h.Size = tar.TypeChar, 0
+		content = nil
+	case "restore-ratio":
+		content = bytes.Repeat([]byte("x"), 16<<20)
+		h.Size = int64(len(content))
+	}
+	var out bytes.Buffer
+	w := tar.NewWriter(&out)
+	must(r.t, w.WriteHeader(h))
+	_, err := w.Write(content)
+	must(r.t, err)
+	must(r.t, w.Close())
+	if id != "restore-ratio" {
+		return out.Bytes()
+	}
+	var compressed bytes.Buffer
+	g := gzip.NewWriter(&compressed)
+	_, err = g.Write(out.Bytes())
+	must(r.t, err)
+	must(r.t, g.Close())
+	return compressed.Bytes()
+}
diff --git a/free/ci/test/cachesec/doc.go b/free/ci/test/cachesec/doc.go
new file mode 100644
index 000000000..5a62b2724
--- /dev/null
+++ b/free/ci/test/cachesec/doc.go
@@ -0,0 +1,3 @@
+// Package cachesec contains the cache, artifact and release security drill.
+// The executable matrix is enabled with the cachesec build tag.
+package cachesec
diff --git a/free/ci/test/cachesec/matrix.yaml b/free/ci/test/cachesec/matrix.yaml
new file mode 100644
index 000000000..87677aa68
--- /dev/null
+++ b/free/ci/test/cachesec/matrix.yaml
@@ -0,0 +1,43 @@
+[
+  {"id":"fork-main","threat_row":"TM-12","expected":"refused","code":"E684","reason":"cache.namespace","audit":"cache.commit.denied"},
+  {"id":"pr-a-pr-b","threat_row":"TM-12","expected":"refused","code":"E684","reason":"cache.namespace","audit":"cache.commit.denied"},
+  {"id":"field-boundary-collision","threat_row":"TM-12","expected":"refused","code":"E711","reason":"not_planned","audit":"cache.commit.refused"},
+  {"id":"ended-local","threat_row":"TM-13","expected":"refused","code":"E711","reason":"attempt_state","audit":"cache.commit.refused"},
+  {"id":"epoch-local","threat_row":"TM-13","expected":"refused","code":"E711","reason":"epoch","audit":"cache.commit.refused"},
+  {"id":"ended-ssh","threat_row":"TM-13","expected":"refused","code":"E714","reason":"stale_epoch","audit":"cache.remote.refused"},
+  {"id":"epoch-ssh","threat_row":"TM-13","expected":"refused","code":"E714","reason":"stale_epoch","audit":"cache.remote.refused"},
+  {"id":"ended-agent","threat_row":"TM-13","expected":"refused","code":"E714","reason":"stale_epoch","audit":"cache.remote.refused"},
+  {"id":"epoch-agent","threat_row":"TM-13","expected":"refused","code":"E714","reason":"stale_epoch","audit":"cache.remote.refused"},
+  {"id":"restore-traversal","threat_row":"TM-14","expected":"refused","code":"E683","reason":"path.traversal","audit":"cache.restore.refused"},
+  {"id":"restore-absolute","threat_row":"TM-14","expected":"refused","code":"E683","reason":"path.absolute","audit":"cache.restore.refused"},
+  {"id":"restore-symlink","threat_row":"TM-14","expected":"refused","code":"E683","reason":"link.escape","audit":"cache.restore.refused"},
+  {"id":"restore-hardlink","threat_row":"TM-14","expected":"refused","code":"E683","reason":"entry.hardlink","audit":"cache.restore.refused"},
+  {"id":"restore-fifo","threat_row":"TM-14","expected":"refused","code":"E683","reason":"entry.fifo","audit":"cache.restore.refused"},
+  {"id":"restore-device","threat_row":"TM-14","expected":"refused","code":"E683","reason":"entry.device","audit":"cache.restore.refused"},
+  {"id":"restore-ratio","threat_row":"TM-14","expected":"refused","code":"E683","reason":"size.ratio","audit":"cache.restore.refused"},
+  {"id":"secret-snapshot","threat_row":"TM-12","expected":"refused","code":"E711","reason":"secret_match","audit":"cache.restore.refused"},
+  {"id":"cache-secret-raw","threat_row":"TM-16","expected":"refused","code":"E711","reason":"secret_match","audit":"cache.save.refused"},
+  {"id":"cache-secret-base64","threat_row":"TM-16","expected":"refused","code":"E711","reason":"secret_match","audit":"cache.save.refused"},
+  {"id":"artifact-secret-raw","threat_row":"TM-16","expected":"refused","code":"E712","reason":"secret_match","audit":"artifact.collect.refused"},
+  {"id":"artifact-secret-base64","threat_row":"TM-16","expected":"refused","code":"E712","reason":"secret_match","audit":"artifact.collect.refused"},
+  {"id":"artifact-overwrite","threat_row":"TM-15","expected":"refused","code":"E712","reason":"digest_mismatch","audit":"artifact.commit.refused"},
+  {"id":"artifact-substitution","threat_row":"TM-15","expected":"refused","code":"E712","reason":"digest_mismatch","audit":"artifact.commit.refused"},
+  {"id":"get-cwd","threat_row":"TM-14","expected":"refused","code":"E683","reason":"dest.cwd","audit":"artifact.get.refused"},
+  {"id":"get-nonempty","threat_row":"TM-14","expected":"refused","code":"E683","reason":"dest.not_empty","audit":"artifact.get.refused"},
+  {"id":"get-hooks","threat_row":"TM-14","expected":"refused","code":"E683","reason":"dest.under_git","audit":"artifact.get.refused"},
+  {"id":"corrupt-local","threat_row":"TM-15","expected":"refused","code":"E711","reason":"blob_invalid","audit":"cache.restore.refused"},
+  {"id":"partial-local","threat_row":"TM-15","expected":"refused","code":"E711","reason":"blob_invalid","audit":"cache.restore.refused"},
+  {"id":"corrupt-transit","threat_row":"TM-15","expected":"refused","code":"E714","reason":"digest_mismatch","audit":"cache.remote.refused"},
+  {"id":"partial-transit","threat_row":"TM-15","expected":"refused","code":"E714","reason":"interrupted","audit":"cache.remote.refused"},
+  {"id":"corrupt-readthrough","threat_row":"TM-15","expected":"refused","code":"E714","reason":"digest_mismatch","audit":"cache.restore.refused"},
+  {"id":"partial-readthrough","threat_row":"TM-15","expected":"refused","code":"E714","reason":"digest_mismatch","audit":"cache.restore.refused"},
+  {"id":"release-no-deps","threat_row":"TM-17","expected":"refused","code":"E715","reason":"deps_failing","audit":"release.admission.refused"},
+  {"id":"release-signed-remote","threat_row":"TM-17","expected":"admitted","code":"","reason":"","audit":""},
+  {"id":"release-revoked-remote","threat_row":"TM-20","expected":"refused","code":"E686","reason":"key_revoked","audit":"evidence.quarantined"},
+  {"id":"manifest-plugins-key","threat_row":"TM-18","expected":"refused","code":"E719","reason":"key_purpose","audit":"release.verify.refused"},
+  {"id":"manifest-agent-key","threat_row":"TM-18","expected":"refused","code":"E719","reason":"key_purpose","audit":"release.verify.refused"},
+  {"id":"sign-uncommitted","threat_row":"TM-18","expected":"refused","code":"E717","reason":"digest_not_committed","audit":"release.sign.refused"},
+  {"id":"untrusted-promotion","threat_row":"TM-17","expected":"refused","code":"E715","reason":"trust","audit":"release.admission.refused"},
+  {"id":"team-member-inputs","threat_row":"TM-24","expected":"refused","code":"E687","reason":"role","audit":"authorize"},
+  {"id":"job-signer","threat_row":"TM-24","expected":"refused","code":"E687","reason":"role","audit":"authorize"}
+]
diff --git a/free/ci/test/cachesec/matrix_run_test.go b/free/ci/test/cachesec/matrix_run_test.go
new file mode 100644
index 000000000..946613b91
--- /dev/null
+++ b/free/ci/test/cachesec/matrix_run_test.go
@@ -0,0 +1,175 @@
+//go:build cachesec
+
+package cachesec
+
+// Purpose: TestCacheSecMatrix runs every case of matrix.yaml against the real stores and engines through
+//          the rig, compares what it observed with the expected outcome, code, reason key and audit row, and
+//          writes testdata/results.json (one row per case). It fails when a case is unmapped, when a threat
+//          row this suite owns has no case, when an outcome differs from the expected one, and when a refusal
+//          lacks its code, reason key or audit row.
+// Inputs:  matrix.yaml (JSON, a subset of YAML) and the case runners in the other test files.
+// Outputs: testdata/results.json; pass or fail.
+// Constraints: a runner returns nil when the action was admitted and the refusal otherwise; the runners
+//          assert that no bytes landed. Nothing is relaxed here to make a case pass: a case that does not
+//          match its expected row is reported as it was observed.
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"reflect"
+	"regexp"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// ownedRows are the threat-model rows (hq architecture/ci-threat-model.md) this suite must cover.
+var ownedRows = []string{"TM-12", "TM-13", "TM-14", "TM-15", "TM-16", "TM-17", "TM-18", "TM-20", "TM-24"}
+
+// refusal is a refusal reported as data (a verifier result, a delegated test).
+type refusal struct{ Code, Reason, Msg string }
+
+func (e *refusal) Error() string { return e.Code + " " + e.Reason + ": " + e.Msg }
+
+// Row is one line of testdata/results.json.
+type Row struct {
+	ID         string `json:"id"`
+	ThreatRow  string `json:"threat_row"`
+	Expected   string `json:"expected"`
+	Outcome    string `json:"outcome"`
+	Code       string `json:"code"`
+	Reason     string `json:"reason"`
+	Audit      string `json:"audit"`
+	AuditFound bool   `json:"audit_found"`
+	Match      bool   `json:"match"`
+	Platform   string `json:"platform"`
+	Note       string `json:"note,omitempty"`
+}
+
+var codeRe = regexp.MustCompile(`\bE[0-9]{3}\b`)
+
+// observe reads the code and reason key off a refusal. The reason is the Reason field of the first error
+// in the chain that has one.
+func observe(err error) (code, reason string) {
+	if err == nil {
+		return "", ""
+	}
+	code = codeRe.FindString(err.Error())
+	for e := err; e != nil; e = errors.Unwrap(e) {
+		v := reflect.ValueOf(e)
+		for v.Kind() == reflect.Pointer && !v.IsNil() {
+			v = v.Elem()
+		}
+		if v.Kind() == reflect.Struct {
+			if f := v.FieldByName("Reason"); f.IsValid() && f.Kind() == reflect.String && f.String() != "" {
+				return code, f.String()
+			}
+		}
+	}
+	return code, ""
+}
+
+// run dispatches a case to the runner of its family.
+func (r *rig) run(id string) (error, string) {
+	switch id {
+	case "fork-main", "pr-a-pr-b", "field-boundary-collision", "ended-local", "epoch-local":
+		return r.cacheWrite(id), ""
+	case "ended-ssh", "epoch-ssh", "ended-agent", "epoch-agent":
+		return r.remoteWrite(id), ""
+	case "restore-traversal", "restore-absolute", "restore-symlink", "restore-hardlink", "restore-fifo", "restore-device",
+		"restore-ratio", "secret-snapshot", "corrupt-local", "partial-local":
+		err := r.restore(id)
+		return err, r.note
+	case "cache-secret-raw", "cache-secret-base64", "artifact-secret-raw", "artifact-secret-base64":
+		return r.secret(id), ""
+	case "artifact-overwrite", "artifact-substitution":
+		return r.artifactMutation(id), ""
+	case "get-cwd", "get-nonempty", "get-hooks":
+		return r.getDest(id), ""
+	case "corrupt-transit", "partial-transit":
+		return r.transferBlob(id), ""
+	case "corrupt-readthrough", "partial-readthrough":
+		return r.readThrough(id), ""
+	case "release-no-deps", "release-signed-remote", "release-revoked-remote", "untrusted-promotion":
+		return r.release(id), ""
+	case "manifest-plugins-key", "manifest-agent-key":
+		return r.manifestKey(id), ""
+	case "sign-uncommitted":
+		return r.signUncommitted()
+	case "team-member-inputs", "job-signer":
+		return r.roleRefusal(id), ""
+	}
+	r.t.Fatalf("matrix case %q has no runner", id)
+	return nil, ""
+}
+
+func TestCacheSecMatrix(t *testing.T) {
+	cases := loadMatrix(t)
+	covered := map[string]int{}
+	for _, c := range cases {
+		covered[c.ThreatRow]++
+	}
+	for _, row := range ownedRows {
+		if covered[row] == 0 {
+			t.Errorf("threat row %s has no case", row)
+		}
+	}
+	var rows []Row
+	for _, c := range cases {
+		var row Row
+		ok := t.Run(c.ID, func(t *testing.T) {
+			r := newRig(t)
+			err, note := r.run(c.ID)
+			row = Row{ID: c.ID, ThreatRow: c.ThreatRow, Expected: c.Expected, Audit: c.Audit, Platform: runtime.GOOS + "/" + runtime.GOARCH, Note: note}
+			if err == nil {
+				row.Outcome = "admitted"
+			} else {
+				row.Outcome = "refused"
+				row.Code, row.Reason = observe(err)
+				if row.Reason == "" && c.Reason != "" && strings.Contains(err.Error(), c.Reason) {
+					row.Reason, row.Note = c.Reason, "reason key read from the error text (the error type has no Reason field)"
+				}
+			}
+			if c.Expected == "refused" {
+				row.AuditFound = r.audit(c.Audit, c.Reason)
+			}
+			row.Match = row.Outcome == c.Expected
+			if c.Expected == "refused" && row.Outcome == "refused" {
+				row.Match = row.Code == c.Code && row.Reason == c.Reason && row.AuditFound
+			}
+			if !row.Match {
+				t.Errorf("%s: expected %s %s %s audit %q; observed %s %s %s audit found %v (%v)", c.ID, c.Expected, c.Code, c.Reason, c.Audit,
+					row.Outcome, row.Code, row.Reason, row.AuditFound, err)
+			}
+		})
+		if row.ID == "" { // the runner stopped the subtest before it recorded anything
+			row = Row{ID: c.ID, ThreatRow: c.ThreatRow, Expected: c.Expected, Audit: c.Audit, Outcome: "error", Platform: runtime.GOOS + "/" + runtime.GOARCH}
+		}
+		if !ok {
+			row.Match = false
+		}
+		rows = append(rows, row)
+	}
+	b, err := json.MarshalIndent(rows, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll("testdata", 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile("testdata/results.json", append(b, '\n'), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	bad := 0
+	for _, row := range rows {
+		if !row.Match {
+			bad++
+		}
+	}
+	if bad != 0 {
+		t.Errorf("%d of %d cases differ from the matrix", bad, len(rows))
+	}
+	t.Log(fmt.Sprintf("%d cases, %d match", len(rows), len(rows)-bad))
+}
diff --git a/free/ci/test/cachesec/matrix_test.go b/free/ci/test/cachesec/matrix_test.go
new file mode 100644
index 000000000..014de9776
--- /dev/null
+++ b/free/ci/test/cachesec/matrix_test.go
@@ -0,0 +1,50 @@
+package cachesec
+
+import (
+	"encoding/json"
+	"os"
+	"regexp"
+	"testing"
+)
+
+type matrixCase struct {
+	ID        string `json:"id"`
+	ThreatRow string `json:"threat_row"`
+	Expected  string `json:"expected"`
+	Code      string `json:"code"`
+	Reason    string `json:"reason"`
+	Audit     string `json:"audit"`
+}
+
+func loadMatrix(t *testing.T) []matrixCase {
+	t.Helper()
+	b, err := os.ReadFile("matrix.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases []matrixCase
+	if err = json.Unmarshal(b, &cases); err != nil {
+		t.Fatal(err)
+	}
+	seen := map[string]bool{}
+	row := regexp.MustCompile(`^TM-[0-9]{2}$`)
+	for _, c := range cases {
+		if c.ID == "" || seen[c.ID] || !row.MatchString(c.ThreatRow) {
+			t.Fatalf("duplicate or unmapped case: %q", c.ID)
+		}
+		seen[c.ID] = true
+		if c.Expected != "refused" && c.Expected != "admitted" {
+			t.Fatalf("%s: missing expected outcome", c.ID)
+		}
+		if c.Expected == "refused" && (c.Code == "" || c.Reason == "" || c.Audit == "") {
+			t.Fatalf("%s: incomplete refusal contract", c.ID)
+		}
+	}
+	if len(cases) == 0 {
+		t.Fatal("empty matrix")
+	}
+	return cases
+}
+
+// TestMatrixContract checks the manifest even when the drill tag is absent.
+func TestMatrixContract(t *testing.T) { loadMatrix(t) }
diff --git a/free/ci/test/cachesec/readthrough_test.go b/free/ci/test/cachesec/readthrough_test.go
new file mode 100644
index 000000000..08d6a4505
--- /dev/null
+++ b/free/ci/test/cachesec/readthrough_test.go
@@ -0,0 +1,92 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"errors"
+	"time"
+
+	cacheRemote "github.com/nself-org/plugins/free/ci/internal/cache/remote"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// wire joins the coordinator's Restore to a node's NodeRestorer in memory; mangle changes every chunk
+// on its way to the node (the bytes the node's read-through copy receives).
+type wire struct {
+	frames chan transport.BlobFrame
+	offs   chan protocol.Offset
+	mangle func(*protocol.Chunk)
+}
+
+func (w *wire) send(f transport.BlobFrame) error {
+	select {
+	case w.frames <- f:
+		return nil
+	case <-time.After(5 * time.Second):
+		return errors.New("wire: node not reading")
+	}
+}
+
+func (w *wire) Digest(d protocol.Digest) error { return w.send(transport.BlobFrame{Digest: &d}) }
+func (w *wire) Chunk(c protocol.Chunk) error {
+	w.mangle(&c)
+	return w.send(transport.BlobFrame{Chunk: &c})
+}
+func (w *wire) Offsets() <-chan protocol.Offset { return w.offs }
+
+type wireFeed struct{ w *wire }
+
+func (f wireFeed) Frames() <-chan transport.BlobFrame { return f.w.frames }
+func (f wireFeed) Offset(o protocol.Offset) error     { f.w.offs <- o; return nil }
+func (f wireFeed) Close()                             {}
+
+// readThrough restores one planned blob from the coordinator into a node's read-through copies while
+// every chunk is corrupted or cut short in transit; the node's re-hash must refuse each copy.
+func (r *rig) readThrough(id string) error {
+	want := []byte("intact payload")
+	ns := namespace(r.t, owner())
+	sha, size, err := r.blobs.Put(r.ctx, cacheRealm(ns.Canonical()), bytes.NewReader(want))
+	must(r.t, err)
+	b := protocol.CacheBlob{Path: "data", SHA256: sha, Size: size}
+	l, realm := r.bindRemote(false, b)
+	dir := r.t.TempDir()
+	copies, err := cacheRemote.NewReadThrough(dir, 4<<20)
+	must(r.t, err)
+	w := &wire{frames: make(chan transport.BlobFrame, 8), offs: make(chan protocol.Offset, 64), mangle: func(c *protocol.Chunk) {
+		c.Data = mangled(r, c.Data, id == "partial-readthrough")
+	}}
+	ctx, cancel := context.WithTimeout(r.ctx, 60*time.Second)
+	defer cancel()
+	done := make(chan error, 1)
+	go func() { done <- l.Restore(ctx, w) }()
+	n := &cacheRemote.NodeRestorer{Copies: copies, Feed: wireFeed{w}, Realm: realm, Wait: 5 * time.Second}
+	held := n.Fetch(ctx, []protocol.CacheBlob{b})
+	err = <-done
+	if held[sha] {
+		r.t.Error("invalid read-through copy was held")
+	}
+	if f, e := copies.Open(ctx, realm, sha, size, nil); e == nil {
+		f.Close()
+		r.t.Error("invalid read-through copy was served")
+	}
+	if len(tree(r.t, dir)) != 0 {
+		r.t.Error("read-through published invalid bytes")
+	}
+	return err
+}
+
+// mangled flips the first byte of a chunk's data, or keeps only its first half.
+func mangled(r *rig, data string, partial bool) string {
+	b, err := base64.StdEncoding.DecodeString(data)
+	must(r.t, err)
+	if partial {
+		b = b[:len(b)/2]
+	} else if len(b) > 0 {
+		b[0] ^= 1
+	}
+	return base64.StdEncoding.EncodeToString(b)
+}
diff --git a/free/ci/test/cachesec/release_test.go b/free/ci/test/cachesec/release_test.go
new file mode 100644
index 000000000..7e068b6cd
--- /dev/null
+++ b/free/ci/test/cachesec/release_test.go
@@ -0,0 +1,100 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"context"
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/json"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/agent/nodekey"
+	"github.com/nself-org/plugins/free/ci/internal/attest"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/release/job"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// releaseFacts builds the facts of a release whose one dep ended with status
+// (the coordinator's own evidence, consistent by construction).
+func releaseFacts(status string) job.Facts {
+	d := model.InputDigests{Config: strings.Repeat("c", 64), Lockfiles: []model.DigestRef{{Path: "go.sum", SHA256: strings.Repeat("1", 64)}}}
+	return job.BuildFacts(job.RunState{RunID: "pbuild", RepoID: "project", Revision: strings.Repeat("a", 40), PolicyDigest: "policy", ConfigDigest: d.Config, SourceTrust: "owner", Trigger: "local",
+		Pipeline: model.PipelineRef{ID: "pbuild", Name: "release", Kind: "default"}, Selection: model.Selection{Mode: "full", Reason: "selection.full_required", Digest: "digest"}, Deps: []string{"build"},
+		Outcomes: []job.Dep{{Name: "build", Status: status, Required: true}}, Clean: true, Bound: &d, Now: &d})
+}
+
+type evidenceSigner struct{ priv ed25519.PrivateKey }
+
+func (s evidenceSigner) KeyID() string                 { return nodekey.KeyIDOf(s.priv.Public().(ed25519.PublicKey)) }
+func (s evidenceSigner) Sign(b []byte) ([]byte, error) { return ed25519.Sign(s.priv, b), nil }
+
+// evidenceLedger supplies registry facts while recording consumption and
+// quarantine in the actual local store.
+type evidenceLedger struct {
+	store.AttestLedger
+	facts attest.AttemptFacts
+	pub   ed25519.PublicKey
+}
+
+func (l evidenceLedger) AttemptFacts(context.Context, string) (attest.AttemptFacts, bool, error) {
+	return l.facts, true, nil
+}
+func (l evidenceLedger) NodesByKey(context.Context, string) ([]attest.KeyNode, error) {
+	return []attest.KeyNode{{NodeID: "node", Public: l.pub, SigningEligible: true}}, nil
+}
+
+func (r *rig) release(id string) error {
+	f := releaseFacts("passed")
+	switch id {
+	case "release-no-deps":
+		// The dep failed: the evidence says so in its result, its check and its counts.
+		f = releaseFacts("failed")
+	case "untrusted-promotion":
+		f.Evidence.SourceTrust = "untrusted"
+	case "release-signed-remote", "release-revoked-remote":
+		r.running("build", owner())
+		pub, priv, err := ed25519.GenerateKey(rand.Reader)
+		must(r.t, err)
+		must(r.t, r.st.NodePut(r.ctx, store.NodeRecord{ID: "node", Name: "node", State: "online", Capability: []byte("{}")}, "test"))
+		f.Evidence.Attempt = &model.AttemptRef{ID: "build", N: 1}
+		name := "build"
+		f.Evidence.Job = &name
+		f.Evidence, err = attest.Sign(f.Evidence, evidenceSigner{priv})
+		must(r.t, err)
+		led := evidenceLedger{AttestLedger: store.AttestLedger{S: r.st}, pub: pub, facts: attest.AttemptFacts{RunnerID: "node", Revision: f.Revision, RunID: "pbuild", RepoID: f.RepoID, SourceTrust: "owner", PolicyDigest: f.PolicyDigest, SelectionMode: "full", Job: "build"}}
+		v := &attest.RunnerVerifier{Ledger: func() attest.Ledger { return led }}
+		attest.RegisterRemoteVerifier(v)
+		defer attest.RegisterRemoteVerifier(nil)
+		raw, err := json.Marshal(f.Evidence)
+		must(r.t, err)
+		must(r.t, v.VerifyEvidence(raw, f.Evidence))
+		if e := job.Evaluate(f); e != nil {
+			r.t.Fatalf("valid signed-remote control refused: %v", e)
+		}
+		if id == "release-signed-remote" {
+			return nil
+		}
+		_, err = (attest.Revoker{Ledger: led.AttestLedger, Audit: r.st.AppendAudit}).Revoke(r.ctx, "node", "test")
+		must(r.t, err)
+		q, err := led.Quarantined(r.ctx, "pbuild")
+		must(r.t, err)
+		if !q {
+			r.t.Error("revoked evidence was not quarantined")
+		}
+		if e := job.Evaluate(f); e == nil {
+			r.t.Error("revoked node evidence admitted a release")
+		}
+		return v.VerifyEvidence(raw, f.Evidence)
+	}
+	// The admission path a release attempt takes (run's Dispatch wrapper), with the run's store as audit sink.
+	st := job.NewStash()
+	st.Audit = r.st.AppendAudit
+	queued := false
+	err := st.Guard(r.ctx, "release-attempt", job.Static(f), func() error { queued = true; return nil })
+	if err != nil && queued {
+		r.t.Error("a refused release attempt was queued")
+	}
+	return err
+}
diff --git a/free/ci/test/cachesec/rig_test.go b/free/ci/test/cachesec/rig_test.go
new file mode 100644
index 000000000..eca7ee4b4
--- /dev/null
+++ b/free/ci/test/cachesec/rig_test.go
@@ -0,0 +1,159 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/authz"
+	"github.com/nself-org/plugins/free/ci/internal/blob/cas"
+	"github.com/nself-org/plugins/free/ci/internal/cache/entries"
+	"github.com/nself-org/plugins/free/ci/internal/cache/specs"
+	"github.com/nself-org/plugins/free/ci/internal/redact"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/storetest"
+)
+
+type rig struct {
+	t       *testing.T
+	ctx     context.Context
+	home    string
+	st      *store.Store
+	blobs   *cas.Store
+	entries *entries.Store
+	engine  *specs.Engine
+	red     *redact.Redactor
+	audits  []store.AuditRow
+	note    string // set by a runner when the admitted action was a clean miss rather than a restore
+}
+
+func newRig(t *testing.T) *rig {
+	t.Helper()
+	r := &rig{t: t, ctx: context.Background(), home: t.TempDir()}
+	var err error
+	r.st, err = store.Open(filepath.Join(r.home, "state.db"), store.Options{})
+	must(t, err)
+	t.Cleanup(func() { must(t, r.st.Close()) })
+	r.st.SetAuditSealer(func(_ []byte, row store.AuditRow) (store.AuditChain, error) {
+		r.audits = append(r.audits, row)
+		return store.AuditChain{Head: []byte("test-head"), Signature: []byte("test-seal")}, nil
+	})
+	r.blobs, err = cas.New(r.home)
+	must(t, err)
+	r.entries = entries.New(r.st, r.blobs, entries.Options{DisableFloor: true, Getenv: func(string) string { return "" }, Project: func(string) authz.ProjectFacts { return authz.ProjectFacts{NoPrivateDeps: true} }})
+	r.red = redact.New()
+	r.engine = &specs.Engine{Entries: r.entries, Blobs: r.blobs, Backend: r.st, Scanner: r.red}
+	return r
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func owner() entries.Facts {
+	return entries.Facts{Project: "project", Trust: "owner", Protection: "protected"}
+}
+func fork(pr string) entries.Facts {
+	return entries.Facts{Project: "project", Trust: "untrusted", Protection: "unprotected", HeadRepo: "fork/project", PR: pr}
+}
+
+func namespace(t *testing.T, f entries.Facts) authz.Namespace {
+	t.Helper()
+	ns, err := entries.NamespaceOf(f)
+	must(t, err)
+	return ns
+}
+
+func digest(b []byte) string {
+	s := sha256.Sum256(b)
+	return hex.EncodeToString(s[:])
+}
+
+func key(t *testing.T, f entries.Facts) string {
+	t.Helper()
+	k, err := entries.Key(entries.KeyInputs{Namespace: namespace(t, f), SpecID: "go", SpecVersion: "1", Platform: "linux/amd64", Isolation: "container"})
+	must(t, err)
+	return k
+}
+
+func (r *rig) running(id string, f entries.Facts) {
+	t, ctx, s := r.t, r.ctx, r.st
+	must(t, s.CreatePipeline(ctx, store.PipelineRow{ID: "p" + id, Revision: strings.Repeat("a", 40), Project: f.Project, Trigger: "local", SourceTrust: f.Trust, PrivacyZone: "local-only", PolicyDigest: "policy", InputDigest: "input", SelectionMode: "full", Status: "queued"}))
+	must(t, s.CreateJob(ctx, store.JobRow{ID: "j" + id, PipelineID: "p" + id, Name: id, Kind: "test", Idempotent: true, InfraMax: 1, InputDigest: "input"}))
+	must(t, s.CreateAttempt(ctx, store.AttemptRow{ID: id, JobID: "j" + id, N: 1}, ""))
+	must(t, storetest.Admit(ctx, s, id))
+	must(t, s.Transition(ctx, id, "leased", "running", store.TransitionDetail{Epoch: 1}))
+}
+
+func (r *rig) finalizing(id string, f entries.Facts, k string) {
+	r.running(id, f)
+	must(r.t, r.entries.RecordPlan(r.ctx, id, 2, f, []string{k}))
+	must(r.t, r.st.Transition(r.ctx, id, "running", "finalizing", store.TransitionDetail{Epoch: 2}))
+	must(r.t, r.entries.RecordResult(r.ctx, id, 3, true))
+}
+
+func (r *rig) manifest(f entries.Facts, k string, b []byte) entries.Manifest {
+	ns := namespace(r.t, f)
+	d, n, err := r.blobs.Put(r.ctx, cas.CacheRealm(string(ns.Canonical())), strings.NewReader(string(b)))
+	must(r.t, err)
+	return entries.Manifest{Namespace: ns.Canonical(), Key: k, Spec: "go", Blobs: []entries.Blob{{Path: "data", SHA256: d, Size: n}}, Writer: entries.Writer{ScannedClean: true}}
+}
+
+func (r *rig) audit(action, reason string) bool {
+	rows, err := r.st.AuditEntries(r.ctx, 0, 1000)
+	must(r.t, err)
+	for _, row := range rows {
+		if row.Action == action && strings.Contains(row.Detail, "reason="+reason) {
+			return true
+		}
+	}
+	return false
+}
+
+func cacheRealm(ns []byte) cas.Realm { return cas.CacheRealm(string(ns)) }
+
+func (r *rig) noEntries() {
+	r.t.Helper()
+	rows, err := r.st.CacheEntries(r.ctx, "")
+	must(r.t, err)
+	if len(rows) != 0 {
+		r.t.Errorf("refusal left %d cache entries", len(rows))
+	}
+}
+
+func tree(t *testing.T, root string) map[string]string {
+	t.Helper()
+	out := map[string]string{}
+	err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		rel, err := filepath.Rel(root, p)
+		if err != nil {
+			return err
+		}
+		b, err := os.ReadFile(p)
+		if err != nil {
+			return err
+		}
+		out[rel] = digest(b)
+		return nil
+	})
+	if os.IsNotExist(err) {
+		return out
+	}
+	must(t, err)
+	return out
+}
diff --git a/free/ci/test/cachesec/signer_test.go b/free/ci/test/cachesec/signer_test.go
new file mode 100644
index 000000000..e6e51ca22
--- /dev/null
+++ b/free/ci/test/cachesec/signer_test.go
@@ -0,0 +1,38 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"context"
+	"encoding/base64"
+
+	"github.com/nself-org/plugins/free/ci/internal/release/manifest"
+	cisigning "github.com/nself-org/plugins/free/ci/internal/signing"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// signerAnswer replays what the isolated signer process writes for a refused request (its stdout and
+// exit status: the wire contract internal/signing's client tests pin).
+type signerAnswer struct {
+	out  string
+	code int
+}
+
+func (a signerAnswer) RunStdio(context.Context, cisigning.StdioCall) ([]byte, int, error) {
+	return []byte(a.out), a.code, nil
+}
+
+// coordinatorSign asks the coordinator's signer client, over the rig store, to sign a manifest of a
+// finished run; the signer answers digest_not_committed. It returns the client's refusal.
+func (r *rig) coordinatorSign() error {
+	r.running("release", owner())
+	must(r.t, r.st.Transition(r.ctx, "release", "running", "finalizing", store.TransitionDetail{Epoch: 2}))
+	must(r.t, r.st.Transition(r.ctx, "release", "finalizing", "passed", store.TransitionDetail{Epoch: 3}))
+	answer := signerAnswer{out: `{"error":{"code":"E717","reason":"` + cisigning.ReasonDigestNotCommitted + `","message":"artifact app is not a committed record of the release attempt"}}`, code: 2}
+	c := &cisigning.Client{Runner: answer, Src: r.st, Audit: r.st.AppendAudit}
+	envs, err := c.Sign(r.ctx, "prelease", []cisigning.Item{{PayloadType: manifest.PayloadType, PayloadB64: base64.StdEncoding.EncodeToString([]byte(`{}`))}})
+	if len(envs) != 0 {
+		r.t.Error("a refused signing request returned envelopes")
+	}
+	return err
+}
diff --git a/free/ci/test/cachesec/signing_test.go b/free/ci/test/cachesec/signing_test.go
new file mode 100644
index 000000000..277fbfaec
--- /dev/null
+++ b/free/ci/test/cachesec/signing_test.go
@@ -0,0 +1,103 @@
+//go:build cachesec
+
+package cachesec
+
+// Purpose: the release-signing and control-plane cases of the matrix (threat rows TM-17, TM-18, TM-24):
+//          a manifest signed by a plugins or agent key, a signer request for a digest no record holds, a TEAM
+//          member fetching release inputs and a job reaching the release path.
+// Inputs:  the rig; the case id.
+// Outputs: the refusal each real component gives, or nil when it admitted the action.
+// Constraints: manifest-*-key drives release/verify with an operator trust file that holds one ci-release
+//          key and a manifest signed by a key of another purpose; the role cases issue real tokens and ask
+//          roles.Authorize, with a release-role control that must pass so the refusal is not blanket;
+//          sign-uncommitted runs the owning package's own named refusal test, because the signer's store
+//          fixture is that package's test code.
+
+import (
+	"crypto/ed25519"
+	"encoding/base64"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/nself-org/cli/sdk/go/v2/signing"
+
+	"github.com/nself-org/plugins/free/ci/internal/audit"
+	"github.com/nself-org/plugins/free/ci/internal/release/manifest"
+	"github.com/nself-org/plugins/free/ci/internal/release/verify"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+)
+
+func seed(n byte) ed25519.PrivateKey {
+	return ed25519.NewKeyFromSeed([]byte(strings.Repeat(string(rune('a'+n)), 32)))
+}
+
+// manifestKey verifies a release whose manifest envelope is signed by a key that is not a ci-release key.
+func (r *rig) manifestKey(id string) error {
+	trusted := seed(1)
+	line := signing.KeyID(signing.PurposeCIRelease, trusted.Public().(ed25519.PublicKey)) + " " +
+		base64.StdEncoding.EncodeToString(trusted.Public().(ed25519.PublicKey)) + "\n"
+	dir := r.t.TempDir()
+	keys := filepath.Join(dir, "ci-release.keys")
+	must(r.t, os.WriteFile(keys, []byte(line), 0o600))
+	purpose := signing.PurposePlugins
+	if id == "manifest-agent-key" {
+		purpose = signing.PurposeAgent
+	}
+	env, err := signing.SignEnvelope(signing.NewEd25519Signer(purpose, seed(2)), manifest.PayloadType, []byte(`{}`))
+	must(r.t, err)
+	b, err := json.Marshal(env)
+	must(r.t, err)
+	rel := filepath.Join(dir, "release")
+	must(r.t, os.Mkdir(rel, 0o700))
+	must(r.t, os.WriteFile(filepath.Join(rel, verify.ManifestFile), b, 0o600))
+	res := verify.Release(r.ctx, rel, verify.Options{OperatorKeys: keys, OperatorRevoked: filepath.Join(dir, "none"), Audit: r.st.AppendAudit})
+	if res.Verified {
+		return nil
+	}
+	return &refusal{Code: res.Code, Reason: res.Reason, Msg: res.Message}
+}
+
+// roleRefusal asks the role service for a release-level action as a member-role token.
+func (r *rig) roleRefusal(id string) error {
+	svc := roles.New(r.st, &audit.Log{St: r.st})
+	svc.Self = "alice"
+	op := svc.Operator("cli:alice")
+	token := func(principal string, role roles.Role) roles.Actor {
+		tok, _, err := svc.IssueToken(r.ctx, op, roles.Request{Principal: principal, Role: role, Projects: []string{"project"}})
+		must(r.t, err)
+		a, err := svc.ActorFromToken(r.ctx, tok)
+		must(r.t, err)
+		return a
+	}
+	ask := func(a roles.Actor) error {
+		if id == "job-signer" {
+			return roles.AuthorizeAction(r.ctx, a, roles.ActReleaseStart, "project")
+		}
+		return roles.Authorize(r.ctx, a, roles.Release, "project")
+	}
+	if err := ask(token("carol", roles.Release)); err != nil {
+		r.t.Fatalf("a release-role control was refused: %v", err)
+	}
+	principal := "bob"
+	if id == "job-signer" {
+		principal = "job-attempt-1"
+	}
+	return ask(token(principal, roles.Member))
+}
+
+// signUncommitted runs the signer's own refusal case for a digest that is not a committed record, then
+// hands that refusal, as the signer process answers it, to the coordinator's signer client.
+func (r *rig) signUncommitted() (error, string) {
+	const test = "internal/signing TestSignerRefuses/artifact_digest_is_not_a_record"
+	cmd := exec.Command("go", "test", "-mod=vendor", "-count=1", "-run", `^TestSignerRefuses$/^artifact_digest_is_not_a_record$`, "./internal/signing/")
+	cmd.Dir = filepath.Join("..", "..")
+	cmd.Env = append(os.Environ(), "CGO_ENABLED=0")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		r.t.Fatalf("%s did not pass: %v\n%s", test, err, out)
+	}
+	return r.coordinatorSign(), "signer check delegated to " + test + "; the coordinator client received the signer's E717 answer and audited it"
+}
diff --git a/free/ci/test/cachesec/testdata/results.json b/free/ci/test/cachesec/testdata/results.json
new file mode 100644
index 000000000..0d554335c
--- /dev/null
+++ b/free/ci/test/cachesec/testdata/results.json
@@ -0,0 +1,506 @@
+[
+  {
+    "id": "fork-main",
+    "threat_row": "TM-12",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E684",
+    "reason": "cache.namespace",
+    "audit": "cache.commit.denied",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "pr-a-pr-b",
+    "threat_row": "TM-12",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E684",
+    "reason": "cache.namespace",
+    "audit": "cache.commit.denied",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "field-boundary-collision",
+    "threat_row": "TM-12",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "not_planned",
+    "audit": "cache.commit.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "ended-local",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "attempt_state",
+    "audit": "cache.commit.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "epoch-local",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "epoch",
+    "audit": "cache.commit.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "ended-ssh",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "stale_epoch",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "epoch-ssh",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "stale_epoch",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "ended-agent",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "stale_epoch",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "epoch-agent",
+    "threat_row": "TM-13",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "stale_epoch",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "restore-traversal",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "path.traversal",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-absolute",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "path.absolute",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-symlink",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "link.escape",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-hardlink",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "entry.hardlink",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-fifo",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "entry.fifo",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-device",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "entry.device",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "restore-ratio",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "size.ratio",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "secret-snapshot",
+    "threat_row": "TM-12",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "secret_match",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "cache-secret-raw",
+    "threat_row": "TM-16",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "secret_match",
+    "audit": "cache.save.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "cache-secret-base64",
+    "threat_row": "TM-16",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "secret_match",
+    "audit": "cache.save.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "artifact-secret-raw",
+    "threat_row": "TM-16",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E712",
+    "reason": "secret_match",
+    "audit": "artifact.collect.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "artifact-secret-base64",
+    "threat_row": "TM-16",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E712",
+    "reason": "secret_match",
+    "audit": "artifact.collect.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "artifact-overwrite",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E712",
+    "reason": "digest_mismatch",
+    "audit": "artifact.commit.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "artifact-substitution",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E712",
+    "reason": "digest_mismatch",
+    "audit": "artifact.commit.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "reason key read from the error text (the error type has no Reason field)"
+  },
+  {
+    "id": "get-cwd",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "dest.cwd",
+    "audit": "artifact.get.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "get-nonempty",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "dest.not_empty",
+    "audit": "artifact.get.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "get-hooks",
+    "threat_row": "TM-14",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E683",
+    "reason": "dest.under_git",
+    "audit": "artifact.get.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "corrupt-local",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "blob_invalid",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "partial-local",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E711",
+    "reason": "blob_invalid",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "corrupt-transit",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "digest_mismatch",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "partial-transit",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "interrupted",
+    "audit": "cache.remote.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "corrupt-readthrough",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "digest_mismatch",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "partial-readthrough",
+    "threat_row": "TM-15",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E714",
+    "reason": "digest_mismatch",
+    "audit": "cache.restore.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "release-no-deps",
+    "threat_row": "TM-17",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E715",
+    "reason": "deps_failing",
+    "audit": "release.admission.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "release-signed-remote",
+    "threat_row": "TM-17",
+    "expected": "admitted",
+    "outcome": "admitted",
+    "code": "",
+    "reason": "",
+    "audit": "",
+    "audit_found": false,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "release-revoked-remote",
+    "threat_row": "TM-20",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E686",
+    "reason": "key_revoked",
+    "audit": "evidence.quarantined",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "manifest-plugins-key",
+    "threat_row": "TM-18",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E719",
+    "reason": "key_purpose",
+    "audit": "release.verify.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "manifest-agent-key",
+    "threat_row": "TM-18",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E719",
+    "reason": "key_purpose",
+    "audit": "release.verify.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "sign-uncommitted",
+    "threat_row": "TM-18",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E717",
+    "reason": "digest_not_committed",
+    "audit": "release.sign.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64",
+    "note": "signer check delegated to internal/signing TestSignerRefuses/artifact_digest_is_not_a_record; the coordinator client received the signer's E717 answer and audited it"
+  },
+  {
+    "id": "untrusted-promotion",
+    "threat_row": "TM-17",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E715",
+    "reason": "trust",
+    "audit": "release.admission.refused",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "team-member-inputs",
+    "threat_row": "TM-24",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E687",
+    "reason": "role",
+    "audit": "authorize",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  },
+  {
+    "id": "job-signer",
+    "threat_row": "TM-24",
+    "expected": "refused",
+    "outcome": "refused",
+    "code": "E687",
+    "reason": "role",
+    "audit": "authorize",
+    "audit_found": true,
+    "match": true,
+    "platform": "darwin/arm64"
+  }
+]
diff --git a/free/ci/test/cachesec/transfer_test.go b/free/ci/test/cachesec/transfer_test.go
new file mode 100644
index 000000000..bda9e28e5
--- /dev/null
+++ b/free/ci/test/cachesec/transfer_test.go
@@ -0,0 +1,106 @@
+//go:build cachesec
+
+package cachesec
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/blob/transfer"
+	cacheRemote "github.com/nself-org/plugins/free/ci/internal/cache/remote"
+	"github.com/nself-org/plugins/free/ci/internal/lease"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/transport"
+)
+
+// bindRemote binds the real coordinator receiver (cacheRemote.Handler) to a durable remote lease of
+// a fresh attempt. The agent carrier permits unordered refs; SSH preserves stream order. restore, when
+// set, is the lease plan's restore blob set.
+func (r *rig) bindRemote(unordered bool, restore ...protocol.CacheBlob) (*cacheRemote.Lease, string) {
+	f := owner()
+	eng := lease.New(r.st, nil, lease.Config{})
+	// Grant needs a queued attempt, so use a separate attempt from the local rig.
+	must(r.t, r.st.CreatePipeline(r.ctx, store.PipelineRow{ID: "pwire", Revision: strings.Repeat("a", 40), Project: f.Project, Trigger: "local", SourceTrust: f.Trust, PrivacyZone: "local-only", PolicyDigest: "policy", InputDigest: "input", SelectionMode: "full", Status: "queued"}))
+	must(r.t, r.st.CreateJob(r.ctx, store.JobRow{ID: "jwire", PipelineID: "pwire", Name: "wire", Kind: "test", Idempotent: true, InfraMax: 1, InputDigest: "input"}))
+	must(r.t, r.st.CreateAttempt(r.ctx, store.AttemptRow{ID: "remote-wire", JobID: "jwire", N: 1}, ""))
+	epoch, err := eng.Grant(r.ctx, "host", store.Demand{AttemptID: "remote-wire", LeaseID: "wire", RunnerID: "node", CPU: 1, MemMB: 1, CapacityCPU: 100, CapacityMemMB: 100, TTL: eng.Config.TTL}, 1)
+	must(r.t, err)
+	ns := namespace(r.t, f)
+	plan := &protocol.LeaseCache{Namespace: base64.RawURLEncoding.EncodeToString(ns.Canonical()), Access: "rw", Save: []protocol.CacheSave{{Spec: "go", Key: key(r.t, f), Dirs: []string{"go/data"}}}}
+	if len(restore) > 0 {
+		plan.Restore = []protocol.CacheRestore{{Spec: "go", Key: key(r.t, f), Dir: "go", Blobs: restore}}
+	}
+	h := &cacheRemote.Handler{Ledger: r.st, Entries: r.entries, Blobs: r.blobs}
+	l, err := h.Bind(cacheRemote.Binding{AttemptID: "remote-wire", LeaseID: "wire", Node: "node", Epoch: epoch, Facts: f, Plan: plan, Unordered: unordered, RestoreWait: 5 * time.Second, Fence: func(ctx context.Context) error {
+		if e := eng.Fence(ctx, "wire", epoch); e != nil {
+			return transfer.ErrStale
+		}
+		return nil
+	}})
+	must(r.t, err)
+	return l, plan.Namespace
+}
+
+func (r *rig) remoteWrite(id string) error {
+	r.running("remote", owner())
+	l, _ := r.bindRemote(strings.HasSuffix(id, "agent"))
+	if strings.HasPrefix(id, "ended-") {
+		state, cas, e := r.st.AttemptStateEpoch(r.ctx, "remote-wire")
+		must(r.t, e)
+		must(r.t, r.st.Transition(r.ctx, "remote-wire", state, "cancelled", store.TransitionDetail{Epoch: cas}))
+	} else {
+		// The binding retains the old epoch after the durable lease is lost.
+		durable, e := r.st.LeaseGet(r.ctx, "wire")
+		must(r.t, e)
+		must(r.t, r.st.LeaseFail(r.ctx, durable, time.Now(), "test fence moved", false))
+	}
+	w, err := l.Blob(r.ctx, transport.BlobHeader{Stream: "cache", SHA256: digest([]byte("payload")), Size: 7})
+	if w != nil {
+		r.t.Error("zombie obtained a blob writer")
+	}
+	r.noEntries()
+	if len(tree(r.t, filepath.Join(r.home, "blobs"))) != 0 {
+		r.t.Error("zombie left blob bytes")
+	}
+	return err
+}
+
+// transferBlob sends a corrupted or truncated blob to the coordinator's cache receiver of a live lease.
+func (r *rig) transferBlob(id string) error {
+	l, _ := r.bindRemote(false)
+	state, cas, err := r.st.AttemptStateEpoch(r.ctx, "remote-wire")
+	must(r.t, err)
+	must(r.t, r.st.Transition(r.ctx, "remote-wire", state, "running", store.TransitionDetail{Epoch: cas}))
+	realm := cacheRealm(namespace(r.t, owner()).Canonical())
+	want := []byte("intact payload")
+	bw, err := l.Blob(r.ctx, transport.BlobHeader{Stream: "cache", SHA256: digest(want), Size: int64(len(want))})
+	must(r.t, err)
+	w, ok := bw.(*transfer.Writer)
+	if !ok {
+		r.t.Fatalf("the cache receiver handed out a %T, not a transfer writer", bw)
+	}
+	got := bytes.Clone(want)
+	if id == "partial-transit" {
+		got = got[:len(got)/2]
+	} else {
+		got[0] ^= 1
+	}
+	_, err = w.Write(got)
+	must(r.t, err)
+	err = w.Close()
+	defer w.Abort()
+	if w.Published() {
+		r.t.Error("invalid transfer published bytes")
+	}
+	if f, e := r.blobs.Open(realm, digest(want)); e == nil {
+		f.Close()
+		r.t.Error("invalid transfer became readable")
+	}
+	r.noEntries()
+	return err
+}
diff --git a/free/ci/test/reliability/carrier_test.go b/free/ci/test/reliability/carrier_test.go
new file mode 100644
index 000000000..b3e02d8f9
--- /dev/null
+++ b/free/ci/test/reliability/carrier_test.go
@@ -0,0 +1,216 @@
+package reliability
+
+// Purpose: carrier faults. Agent carrier: an interrupted connection (network drop and restore, kill -9 of
+//          the coordinator mid log stream, a partial log upload) resumes with no duplicate log line,
+//          result or artifact reference. SSH carrier: session loss marks the attempt lost and it is
+//          retried elsewhere; no resume is claimed.
+// Inputs:  the coordinator's lease log writer (internal/transport/agent) and the sim world.
+// Outputs: assertions only.
+// Constraints: no sleeps; artifact references are recorded only behind the lease fence, as the hub does.
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/json"
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	agentcarrier "github.com/nself-org/plugins/free/ci/internal/transport/agent"
+	"github.com/nself-org/plugins/free/ci/internal/transport/ssh"
+)
+
+// logSeqs reads the line_seq values of a lease log file in order.
+func logSeqs(t *testing.T, path string) []uint64 {
+	t.Helper()
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = f.Close() }()
+	var out []uint64
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		var l struct {
+			LineSeq uint64 `json:"line_seq"`
+		}
+		if err := json.Unmarshal(sc.Bytes(), &l); err != nil {
+			t.Fatalf("log line %q: %v", sc.Text(), err)
+		}
+		out = append(out, l.LineSeq)
+	}
+	if err := sc.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func wantSeqs(t *testing.T, path string, n uint64) {
+	t.Helper()
+	got := logSeqs(t, path)
+	if uint64(len(got)) != n {
+		t.Fatalf("log has %d lines %v, want %d", len(got), got, n)
+	}
+	for i, s := range got {
+		if s != uint64(i)+1 {
+			t.Fatalf("log line %d has line_seq %d: %v", i, s, got)
+		}
+	}
+}
+
+// send appends lines from..to of a lease; it returns how many were written (not duplicates).
+func send(t *testing.T, lw *agentcarrier.LogWriter, leaseID string, from, to uint64) int {
+	t.Helper()
+	n := 0
+	for s := from; s <= to; s++ {
+		ok, err := lw.Append(protocol.Log{LeaseID: leaseID, LineSeq: s, Stream: "stdout", Text: fmt.Sprintf("line %d", s)})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if ok {
+			n++
+		}
+	}
+	return n
+}
+
+func openLog(t *testing.T, path string) *agentcarrier.LogWriter {
+	t.Helper()
+	lw, err := agentcarrier.OpenLog(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = lw.Close() })
+	return lw
+}
+
+// artifacts is the coordinator's artifact index: a reference is kept only while the lease fence holds.
+type artifacts map[string]int
+
+func (x artifacts) add(w *world, a *agent, path string) error {
+	if err := w.engine.Fence(w.ctx, a.leaseID, a.epoch); err != nil {
+		return err
+	}
+	sum := sha256.Sum256([]byte(path))
+	x[fmt.Sprintf("%s/%s/%x", a.leaseID, path, sum[:4])]++
+	return nil
+}
+
+// wantOnce asserts one artifact reference, recorded once.
+func (x artifacts) wantOnce(t *testing.T) {
+	t.Helper()
+	for _, n := range x {
+		if n != 1 || len(x) != 1 {
+			t.Fatalf("artifact index %v", x)
+		}
+	}
+	if len(x) != 1 {
+		t.Fatalf("artifact index %v", x)
+	}
+}
+
+func TestFaultAgentCarrierResume(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jres", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	path := agentcarrier.LogFile(t.TempDir(), "lease-a")
+	lw := openLog(t, path)
+	idx := artifacts{}
+	if n := send(t, lw, "lease-a", 1, 4); n != 4 {
+		t.Fatalf("first burst wrote %d", n)
+	}
+	if err := idx.add(w, a, "dist/app.tar"); err != nil {
+		t.Fatal(err)
+	}
+	a.partitioned = true // Wi-Fi drop: the acks for lines 3-4 and the artifact never reach the agent
+	w.run(heartbeat, a)
+	a.partitioned = false
+	if err := a.reconnect(); err != nil {
+		t.Fatal(err)
+	}
+	if n := send(t, lw, "lease-a", 3, 6); n != 2 { // the agent resends from its last acknowledged line
+		t.Fatalf("resend wrote %d lines, want 2", n)
+	}
+	idx.wantOnce(t)
+	if ran, err := a.finish("jres"); !ran || err != nil {
+		t.Fatalf("finish: ran=%t err=%v", ran, err)
+	}
+	wantCode(t, "resent result", a.lateResult(), "E605") // the finalizing CAS refuses a second result
+	wantCode(t, "resent artifact reference", idx.add(w, a, "dist/app.tar"), "E662")
+	idx.wantOnce(t)
+	if err := lw.Sync(); err != nil {
+		t.Fatal(err)
+	}
+	wantSeqs(t, path, 6)
+	w.wantAttempts("jres", "finalizing/")
+	w.wantEffect("jres", "node-a")
+}
+
+func TestFaultCoordinatorKilledMidLogStream(t *testing.T) {
+	path := agentcarrier.LogFile(t.TempDir(), "lease-k")
+	lw, err := agentcarrier.OpenLog(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	send(t, lw, "lease-k", 1, 3)
+	if err := lw.Sync(); err != nil {
+		t.Fatal(err)
+	}
+	_ = lw.Close()
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := f.WriteString(`{"line_seq":4,"stream":"std`); err != nil { // kill -9 mid write
+		t.Fatal(err)
+	}
+	_ = f.Close()
+	lw = openLog(t, path)
+	if lw.Last() != 3 {
+		t.Fatalf("recovered tail %d, want 3", lw.Last())
+	}
+	if n := send(t, lw, "lease-k", 2, 5); n != 2 {
+		t.Fatalf("resume wrote %d, want 2", n)
+	}
+	wantSeqs(t, path, 5)
+}
+
+func TestFaultPartialLogUpload(t *testing.T) {
+	path := agentcarrier.LogFile(t.TempDir(), "lease-p")
+	lw := openLog(t, path)
+	send(t, lw, "lease-p", 1, 2)
+	// The upload of lines 3-5 was cut after line 3 reached the coordinator.
+	send(t, lw, "lease-p", 3, 3)
+	if n := send(t, lw, "lease-p", 3, 5); n != 2 {
+		t.Fatalf("re-upload wrote %d, want 2", n)
+	}
+	if err := lw.Sync(); err != nil {
+		t.Fatal(err)
+	}
+	wantSeqs(t, path, 5)
+}
+
+func TestFaultSSHSessionLoss(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jssh", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(heartbeat, a)
+	l, err := w.store.LeaseGet(w.ctx, "lease-a")
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.dead = true // the ssh session carried the job; it ends with the session
+	if err := w.store.LeaseFail(w.ctx, l, w.clock(), ssh.ReasonSessionLost, false); err != nil {
+		t.Fatal(err)
+	}
+	if got := w.retryReasons(a1); len(got) != 1 || got[0] != ssh.ReasonSessionLost {
+		t.Fatalf("retry reasons %v", got)
+	}
+	wantCode(t, "resume over a new session", w.engine.Reconnect(w.ctx, "lease-a", a.epoch, "running"), "E662")
+	wantCode(t, "late result", a.lateResult(), "E662")
+	rows := w.wantAttempts("jssh", "retryable/lost", "queued/")
+	retryElsewhere(t, w, "jssh", rows)
+	w.wantAttempts("jssh", "retryable/lost", "finalizing/")
+	w.wantEffect("jssh", "node-b")
+}
diff --git a/free/ci/test/reliability/coordinator_outage_test.go b/free/ci/test/reliability/coordinator_outage_test.go
new file mode 100644
index 000000000..00481d921
--- /dev/null
+++ b/free/ci/test/reliability/coordinator_outage_test.go
@@ -0,0 +1,193 @@
+package reliability
+
+// Purpose: coordinator outages (EPIC D6, Acceptance 5), kill -9 of the coordinator, a VPS reboot of a
+//          node and drain hand-back. Down 20 s (< agent TTL) with 20 running agents: 0 requeues. Down
+//          5 minutes: every agent self-fences, each attempt goes lost (agent.self_fenced) and is retried
+//          exactly once, each side-effect file is written once, and the coordinator expires no lease for
+//          its own downtime. Drain hand-back never overlaps two attempts of a job.
+// Inputs:  the sim world; a coordinator restart is a new lease.Engine over the same store.
+// Outputs: assertions only.
+// Constraints: no sleeps.
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator/drain"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// fleet grants n jobs on n runners and lets one heartbeat land.
+func fleet(t *testing.T, w *world, n int) []*agent {
+	t.Helper()
+	agents := make([]*agent, n)
+	for i := range agents {
+		id := fmt.Sprintf("j%02d", i)
+		runner := fmt.Sprintf("node-%02d", i)
+		lid := "lease-" + id
+		agents[i] = w.startAgent(runner, lid, w.grant(w.job(id, "test", true, 1), lid, runner, 1))
+	}
+	w.run(heartbeat, agents...)
+	return agents
+}
+
+// outage stops the coordinator for d, then starts a new incarnation with restart grace.
+func outage(t *testing.T, w *world, d time.Duration, agents []*agent) {
+	t.Helper()
+	w.down = true
+	w.run(d, agents...)
+	w.engine = w.coordinator()
+	w.down = false
+	if _, err := w.engine.Start(w.ctx, "coordinator-2", 2); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestFaultCoordinatorDownShort(t *testing.T) {
+	w := newWorld(t)
+	agents := fleet(t, w, 20)
+	outage(t, w, 20*time.Second, agents)
+	for i, a := range agents {
+		if !a.fencedAt.IsZero() {
+			t.Fatalf("agent %d fenced during a 20 s outage", i)
+		}
+		if err := a.reconnect(); err != nil {
+			t.Fatalf("reconnect %d: %v", i, err)
+		}
+	}
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 0 {
+		t.Fatalf("short outage requeued %d: %v", n, err)
+	}
+	for i, a := range agents {
+		id := fmt.Sprintf("j%02d", i)
+		if ran, err := a.finish(id); !ran || err != nil {
+			t.Fatalf("job %s after short outage: ran=%t err=%v", id, ran, err)
+		}
+		w.wantAttempts(id, "finalizing/")
+		w.wantEffect(id, a.runner)
+	}
+}
+
+func TestFaultCoordinatorDownLong(t *testing.T) {
+	w := newWorld(t)
+	agents := fleet(t, w, 20)
+	down := w.clock()
+	outage(t, w, 5*time.Minute, agents)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 0 {
+		t.Fatalf("coordinator expired %d leases for its own downtime: %v", n, err)
+	}
+	for i, a := range agents {
+		id := fmt.Sprintf("j%02d", i)
+		if a.fencedAt.IsZero() || !a.fencedAt.After(down) || a.fencedAt.Sub(down) > coordTTL {
+			t.Fatalf("agent %d fenced at %v (outage began %v)", i, a.fencedAt, down)
+		}
+		if ran, _ := a.finish(id); ran {
+			t.Fatalf("fenced job %s wrote its side effect", id)
+		}
+		if err := a.reconnect(); err != nil {
+			t.Fatalf("fence report %d: %v", i, err)
+		}
+		wantCode(t, "duplicate fence report", a.reconnect(), "E662")
+		if got := w.retryReasons(id + ".a1"); len(got) != 1 || got[0] != "agent.self_fenced" {
+			t.Fatalf("job %s retry reasons %v", id, got)
+		}
+	}
+	for i, a := range agents {
+		id := fmt.Sprintf("j%02d", i)
+		rows := w.wantAttempts(id, "retryable/lost", "queued/")
+		next := fmt.Sprintf("node-%02d", (i+1)%len(agents))
+		lid := "lease-r-" + id
+		b := w.startAgent(next, lid, w.grant(rows[1].ID, lid, next, 2))
+		if ran, err := b.finish(id); !ran || err != nil {
+			t.Fatalf("retry %s: ran=%t err=%v", id, ran, err)
+		}
+		wantCode(t, "late result of the fenced attempt", a.lateResult(), "E662")
+		w.wantAttempts(id, "retryable/lost", "finalizing/")
+		w.wantEffect(id, next)
+	}
+}
+
+func TestFaultCoordinatorKilledMidRun(t *testing.T) {
+	w := newWorld(t)
+	agents := fleet(t, w, 3)
+	outage(t, w, 0, agents) // kill -9 and immediate restart: the new incarnation re-adopts every lease
+	w.run(3*heartbeat, agents...)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 0 {
+		t.Fatalf("restart requeued %d: %v", n, err)
+	}
+	for i, a := range agents {
+		id := fmt.Sprintf("j%02d", i)
+		if ran, err := a.finish(id); !ran || err != nil {
+			t.Fatalf("job %s: ran=%t err=%v", id, ran, err)
+		}
+		w.wantEffect(id, a.runner)
+	}
+}
+
+func TestFaultNodeReboot(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jboot", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(heartbeat, a)
+	// The container restarts: the job process is gone and the new agent process holds no live job, so it
+	// reports the lease it finds in its spool as self-fenced.
+	a.dead = true
+	w.run(heartbeat, a)
+	if err := w.engine.Reconnect(w.ctx, "lease-a", a.epoch, "self_fenced"); err != nil {
+		t.Fatal(err)
+	}
+	rows := w.wantAttempts("jboot", "retryable/lost", "queued/")
+	if prev := w.previousRunner(rows[1].ID); prev != "node-a" {
+		t.Fatalf("previous runner %q", prev)
+	}
+	b := w.startAgent("node-b", "lease-b", w.grant(rows[1].ID, "lease-b", "node-b", 1))
+	if ran, err := b.finish("jboot"); !ran || err != nil {
+		t.Fatalf("retry: ran=%t err=%v", ran, err)
+	}
+	w.wantEffect("jboot", "node-b")
+}
+
+func TestFaultDrainHandBack(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jdrain", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(heartbeat, a)
+	leases := &drain.EngineLeases{Engine: w.engine, JobInfo: func(context.Context, string) (string, bool, error) { return "test", true, nil }}
+	running, err := leases.Running(w.ctx)
+	if err != nil || len(running) != 1 || !running[0].HandBackable() {
+		t.Fatalf("running leases %+v %v", running, err)
+	}
+	a.partitioned = true // the draining node stops answering; the drain waits for expiry
+	w.run(coordTTL+heartbeat, a)
+	if n := w.active("jdrain"); n != 1 {
+		t.Fatalf("active attempts before hand-back = %d", n)
+	}
+	if err := leases.HandBack(w.ctx, running[0], true, "drain"); err != nil {
+		t.Fatal(err)
+	}
+	if n := w.active("jdrain"); n != 0 {
+		t.Fatalf("active attempts after hand-back = %d, want 0 before the retry is leased", n)
+	}
+	wantCode(t, "old lease after hand-back", w.engine.Fence(w.ctx, "lease-a", a.epoch), "E662")
+	rows := w.wantAttempts("jdrain", "retryable/lost", "queued/")
+	draining := simRunner("node-a")
+	draining.Capability.Availability.State.Value = ptr("draining")
+	res := place("jdrain", 2, "node-a", draining, simRunner("node-b"))
+	if len(res.Placements) != 1 || res.Placements[0].RunnerID != "node-b" || !contains(reasonsFor(res, "node-a"), string(model.NodeDraining)) {
+		t.Fatalf("placement after drain %+v", res)
+	}
+	b := w.startAgent("node-b", "lease-b", w.grant(rows[1].ID, "lease-b", "node-b", 1))
+	if n := w.active("jdrain"); n != 1 {
+		t.Fatalf("active attempts after retry lease = %d", n)
+	}
+	a.partitioned = false
+	if ran, _ := a.finish("jdrain"); ran {
+		t.Fatal("handed-back job wrote its side effect")
+	}
+	if ran, err := b.finish("jdrain"); !ran || err != nil {
+		t.Fatalf("retry: ran=%t err=%v", ran, err)
+	}
+	w.wantEffect("jdrain", "node-b")
+}
diff --git a/free/ci/test/reliability/doc.go b/free/ci/test/reliability/doc.go
new file mode 100644
index 000000000..0af28c524
--- /dev/null
+++ b/free/ci/test/reliability/doc.go
@@ -0,0 +1,19 @@
+// Package reliability holds the lost-runner fault suite (scenario 9 and the
+// reliability items of P7-NODE-11).
+//
+// Two layers run the same assertions:
+//
+//   - The sim layer (sim_*_test.go and the TestFault* tests) drives the real
+//     store, lease engine, agent fence, drain hand-back, placement and log
+//     writer with injected wall and monotonic clocks. Freezes, partitions,
+//     suspends, clock jumps, crashes and coordinator outages are clock and
+//     carrier events, so no test sleeps. It runs in every `go test`.
+//   - The Docker layer (docker_*_test.go) applies the same faults to real
+//     sshd containers through sdk/go/simharness: docker pause, a network
+//     partition, and a container restart. It runs only with INTEGRATION=1 on
+//     a Linux Docker Engine; without it simharness skips the test.
+//
+// Every test asserts store state, the evidence attempts and their
+// failure_class, process timestamps, and that the fixture job's side-effect
+// file is written at most once.
+package reliability
diff --git a/free/ci/test/reliability/scenario9_test.go b/free/ci/test/reliability/scenario9_test.go
new file mode 100644
index 000000000..fcddd939c
--- /dev/null
+++ b/free/ci/test/reliability/scenario9_test.go
@@ -0,0 +1,162 @@
+package reliability
+
+// Purpose: scenario 9. A node frozen (SIGSTOP / docker pause) or partitioned past the TTL self-fences
+//          before the coordinator's expiry; the attempt goes lost and is retried on another eligible
+//          node (retry.anti_affinity); the late result after SIGCONT or heal is rejected with E662; the
+//          side-effect file is written once; the evidence lists both attempts with failure_class.
+//          A deterministic failure is not retried; a lost release job goes needs-operator.
+// Inputs:  the sim world (real store, lease engine, agent fence, scheduler) with injected clocks.
+// Outputs: assertions only.
+// Constraints: no sleeps; the Docker variant of the same faults is docker_faults_test.go.
+
+import (
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+// retryElsewhere checks the retry placement and runs the retry to completion on node-b.
+func retryElsewhere(t *testing.T, w *world, jobID string, rows []store.AttemptView) *agent {
+	t.Helper()
+	prev := w.previousRunner(rows[1].ID)
+	if prev != "node-a" {
+		t.Fatalf("retry anti-affinity runner = %q, want node-a", prev)
+	}
+	res := place(jobID, rows[1].N, prev, simRunner("node-a"), simRunner("node-b"))
+	if len(res.Placements) != 1 || res.Placements[0].RunnerID != "node-b" {
+		t.Fatalf("retry placement = %+v, want node-b", res.Placements)
+	}
+	if got := reasonsFor(res, "node-a"); !contains(got, string(model.RetryAntiAffinity)) {
+		t.Fatalf("node-a reasons = %v, want %s", got, model.RetryAntiAffinity)
+	}
+	b := w.startAgent("node-b", "lease-b", w.grant(rows[1].ID, "lease-b", "node-b", 1))
+	w.run(heartbeat, b)
+	if ran, err := b.finish(jobID); !ran || err != nil {
+		t.Fatalf("retry on node-b: ran=%t err=%v", ran, err)
+	}
+	return b
+}
+
+// fencedBeforeExpiry asserts the agent's fence deadline falls before the coordinator's lease expiry.
+func fencedBeforeExpiry(t *testing.T, a *agent, expiresAt int64) {
+	t.Helper()
+	deadline := a.lastAck.Add(a.fence.TTL)
+	if !deadline.Before(time.Unix(0, expiresAt)) {
+		t.Fatalf("agent fence deadline %v not before coordinator expiry %v", deadline, time.Unix(0, expiresAt))
+	}
+	if !a.fencedAt.IsZero() && !a.fencedAt.Before(time.Unix(0, expiresAt)) {
+		t.Fatalf("agent fenced at %v, after coordinator expiry %v", a.fencedAt, time.Unix(0, expiresAt))
+	}
+}
+
+func TestFaultScenario9Freeze(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("j9", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(2*heartbeat, a)
+	l, err := w.store.LeaseGet(w.ctx, "lease-a")
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.frozen = true // SIGSTOP
+	w.run(time.Minute, a)
+	fencedBeforeExpiry(t, a, l.ExpiresAt)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 1 {
+		t.Fatalf("sweep after freeze: %d %v", n, err)
+	}
+	a.frozen = false // SIGCONT: the wake check latches the fence before job work resumes
+	if ran, _ := a.finish("j9"); ran || a.fencedAt.IsZero() {
+		t.Fatalf("frozen job resumed: ran=%t fencedAt=%v", ran, a.fencedAt)
+	}
+	wantCode(t, "late result after SIGCONT", a.lateResult(), "E662")
+	rows := w.wantAttempts("j9", "retryable/lost", "queued/")
+	if got := w.retryReasons(a1); len(got) != 1 || got[0] != "lease.expired" {
+		t.Fatalf("retry reasons %v", got)
+	}
+	retryElsewhere(t, w, "j9", rows)
+	wantCode(t, "late result after the retry", a.lateResult(), "E662")
+	w.wantAttempts("j9", "retryable/lost", "finalizing/")
+	w.wantEffect("j9", "node-b")
+	if w.engine.StaleCount() != 2 {
+		t.Fatalf("stale rejections = %d, want 2", w.engine.StaleCount())
+	}
+}
+
+func TestFaultScenario9Partition(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("j9p", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(2*heartbeat, a)
+	l, err := w.store.LeaseGet(w.ctx, "lease-a")
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.partitioned = true // netem loss 100 % / network disconnect
+	w.run(3*heartbeat, a)
+	if a.fencedAt.IsZero() {
+		t.Fatal("partitioned agent did not self-fence")
+	}
+	fencedBeforeExpiry(t, a, l.ExpiresAt)
+	if ran, _ := a.finish("j9p"); ran {
+		t.Fatal("fenced job wrote its side effect")
+	}
+	a.partitioned = false // heal: the agent reports its fence
+	if err := a.reconnect(); err != nil {
+		t.Fatal(err)
+	}
+	if got := w.retryReasons(a1); len(got) != 1 || got[0] != "agent.self_fenced" {
+		t.Fatalf("retry reasons %v", got)
+	}
+	wantCode(t, "late result after heal", a.lateResult(), "E662")
+	wantCode(t, "second fence report", a.reconnect(), "E662")
+	w.advance(coordTTL)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 0 {
+		t.Fatalf("sweep after self-fence: %d %v", n, err)
+	}
+	rows := w.wantAttempts("j9p", "retryable/lost", "queued/")
+	retryElsewhere(t, w, "j9p", rows)
+	w.wantAttempts("j9p", "retryable/lost", "finalizing/")
+	w.wantEffect("j9p", "node-b")
+}
+
+func TestFaultDeterministicNotRetried(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jdet", "test", true, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(heartbeat, a)
+	w.effect("jdet", "node-a")
+	_, epoch := w.state(a1)
+	if err := w.store.Transition(w.ctx, a1, "running", "failed", store.TransitionDetail{Epoch: epoch, FailureClass: "code"}); err != nil {
+		t.Fatal(err)
+	}
+	w.advance(2 * coordTTL)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 0 {
+		t.Fatalf("deterministic failure swept: %d %v", n, err)
+	}
+	w.wantAttempts("jdet", "failed/code")
+	w.wantEffect("jdet", "node-a")
+	if got := w.retryReasons(a1); len(got) != 0 {
+		t.Fatalf("deterministic failure retried: %v", got)
+	}
+}
+
+func TestFaultLostReleaseNeedsOperator(t *testing.T) {
+	w := newWorld(t)
+	a1 := w.job("jrel", "release", false, 1)
+	a := w.startAgent("node-a", "lease-a", w.grant(a1, "lease-a", "node-a", 1))
+	w.run(heartbeat, a)
+	a.dead = true // kill -9 of the agent running the release
+	w.run(2*coordTTL, a)
+	if n, err := w.engine.Sweep(w.ctx); err != nil || n != 1 {
+		t.Fatalf("sweep: %d %v", n, err)
+	}
+	w.wantAttempts("jrel", "needs-operator/lost")
+	if got := w.retryReasons(a1); len(got) != 0 {
+		t.Fatalf("release retried: %v", got)
+	}
+	if lines := w.effectLines("jrel"); len(lines) != 0 {
+		t.Fatalf("release side effect %v", lines)
+	}
+}
diff --git a/free/ci/test/reliability/sim_agent_test.go b/free/ci/test/reliability/sim_agent_test.go
new file mode 100644
index 000000000..729df54e0
--- /dev/null
+++ b/free/ci/test/reliability/sim_agent_test.go
@@ -0,0 +1,144 @@
+package reliability
+
+// Purpose: the node side of the sim: an agent with its own wall and monotonic clocks and the real
+//          lease.AgentFence, plus the placement view (sched.Place) a retry goes through.
+// Inputs:  the world, a runner name and the lease the agent holds.
+// Outputs: heartbeats, job completion (which writes the side-effect file) and late carrier frames.
+// Constraints: a frozen agent's clocks keep moving (time passes) but it runs no code; a suspended agent's
+//          monotonic clock stops while its wall clock jumps; no sleeps.
+
+import (
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/lease"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// agent is one node agent holding one lease.
+type agent struct {
+	w           *world
+	runner      string
+	leaseID     string
+	epoch       int64
+	wall        time.Time
+	mono        time.Duration
+	fence       *lease.AgentFence
+	fencedAt    time.Time // world time at which the fence latched (zero: never)
+	frozen      bool      // SIGSTOP / docker pause: no code runs
+	partitioned bool      // the carrier cannot reach the coordinator
+	dead        bool      // kill -9: never runs again
+	acks        int
+	lastAck     time.Time // world time of the last acknowledged heartbeat
+}
+
+func (w *world) startAgent(runner, leaseID string, epoch int64) *agent {
+	a := &agent{w: w, runner: runner, leaseID: leaseID, epoch: epoch, wall: w.clock()}
+	a.fence = lease.NewAgentFence(func() time.Time { return a.wall }, func() time.Duration { return a.mono }, coordTTL, heartbeat)
+	a.fence.OnFence = func() { a.fencedAt = w.clock() }
+	a.lastAck = w.clock()
+	return a
+}
+
+// run moves time forward in heartbeat steps; every live, unfrozen agent heartbeats at each step.
+func (w *world) run(d time.Duration, agents ...*agent) {
+	for left := d; left > 0; left -= heartbeat {
+		step := min(left, heartbeat)
+		w.advance(step)
+		for _, a := range agents {
+			a.wall = a.wall.Add(step)
+			a.mono += step
+			if !a.frozen && !a.dead {
+				a.beat()
+			}
+		}
+	}
+}
+
+// beat is one heartbeat: the fence is checked first, then the coordinator is asked to renew.
+func (a *agent) beat() {
+	if a.fence.Check() || a.partitioned || a.w.down {
+		return
+	}
+	if a.w.engine.Renew(a.w.ctx, a.leaseID, a.epoch, 0) == nil {
+		a.fence.Ack()
+		a.acks++
+		a.lastAck = a.w.clock()
+	}
+}
+
+// finish completes the fixture job: on a fenced agent the job is killed before its side effect;
+// otherwise the side effect is written and the result is sent.
+func (a *agent) finish(jobID string) (ran bool, err error) {
+	if a.dead || a.fence.Check() {
+		return false, nil
+	}
+	a.w.effect(jobID, a.runner)
+	return true, a.w.engine.Result(a.w.ctx, a.leaseID, a.epoch)
+}
+
+// lateResult is a result frame buffered before the fault and delivered after it.
+func (a *agent) lateResult() error { return a.w.engine.Result(a.w.ctx, a.leaseID, a.epoch) }
+
+// reconnect is the agent's report after a carrier or coordinator outage.
+func (a *agent) reconnect() error {
+	status := "running"
+	if a.fence.Check() {
+		status = "self_fenced"
+	}
+	return a.w.engine.Reconnect(a.w.ctx, a.leaseID, a.epoch, status)
+}
+
+func ptr[T any](v T) *T { return &v }
+
+// simRunner is an eligible linux/amd64 node speaking protocol 1.
+func simRunner(id string) sched.Runner {
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Lifecycle.AuthorizedProjects = []string{"project"}
+	c.Lifecycle.Eligible = true
+	c.Protocol.Versions = []int{1}
+	c.Protocol.Min = 1
+	c.Platform.OS.Value = ptr("linux")
+	c.Platform.Arch.Value = ptr("amd64")
+	c.Resources.CPU.Value = ptr(float64(8))
+	c.Resources.MemMB.Value = ptr(int64(8192))
+	c.Location.Kind.Value = ptr("lan")
+	return sched.Runner{ID: id, Location: "lan", Class: "owned", Provider: "operator", Avail: sched.Avail{Slots: 1, CPU: 8, MemMB: 8192}, Capability: c,
+		Decl: trust.Declaration{Accepts: []model.TrustClass{"owner", "internal", "collaborator", "untrusted"}, Isolation: "vm", Network: "privileged", UIDSeparation: true, Ownership: "operator", NoLANRoute: true}}
+}
+
+// place runs the scheduler for one job attempt; previous is the runner retry anti-affinity excludes.
+func place(jobKey string, attempt int, previous string, runners ...sched.Runner) sched.Result {
+	w := sched.World{Runners: runners, Policy: sched.Policy{Preset: "balanced"}, Costs: map[string]sched.Cost{}, Previous: map[string]string{}}
+	if previous != "" {
+		w.Previous[jobKey] = previous
+	}
+	j := sched.Job{Key: jobKey, ID: jobKey, Project: "project", Attempt: attempt, Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan", TimeoutMs: 60000}
+	return sched.Place(w, []sched.Job{j})
+}
+
+// reasonsFor returns the placement reason codes the scheduler gave one runner.
+func reasonsFor(r sched.Result, runner string) []string {
+	var out []string
+	for _, x := range r.Explanations {
+		for _, alt := range x.Alternatives {
+			if alt.RunnerID == runner {
+				for _, q := range alt.Reasons {
+					out = append(out, q.Code)
+				}
+			}
+		}
+	}
+	return out
+}
+
+func contains(values []string, want string) bool {
+	for _, v := range values {
+		if v == want {
+			return true
+		}
+	}
+	return false
+}
diff --git a/free/ci/test/reliability/sim_world_test.go b/free/ci/test/reliability/sim_world_test.go
new file mode 100644
index 000000000..0b5fc48ce
--- /dev/null
+++ b/free/ci/test/reliability/sim_world_test.go
@@ -0,0 +1,219 @@
+package reliability
+
+// Purpose: the coordinator side of the sim: one real store and lease engine behind an injected clock,
+//          fixture jobs, grants on named runners and the fixture job's side-effect file.
+// Inputs:  a *testing.T; every time moves through world.advance.
+// Outputs: helpers that fail the test on any unexpected store error.
+// Constraints: no sleeps; times start at time.Unix(1, 0); the side-effect file lives in the test's TempDir.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/lease"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+const (
+	coordTTL  = 45 * time.Second
+	heartbeat = 10 * time.Second
+)
+
+// world is one coordinator store with its lease engine and an injected clock.
+type world struct {
+	t       *testing.T
+	ctx     context.Context
+	mu      sync.Mutex
+	now     time.Time
+	down    bool // the coordinator process is not running
+	store   *store.Store
+	engine  *lease.Engine
+	effects string
+	audits  []store.AuditRow
+}
+
+func newWorld(t *testing.T) *world {
+	t.Helper()
+	w := &world{t: t, ctx: context.Background(), now: time.Unix(1, 0), effects: t.TempDir()}
+	s, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{Clock: w.clock})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	w.store = s
+	s.SetAuditSealer(func(_ []byte, row store.AuditRow) (store.AuditChain, error) {
+		w.mu.Lock()
+		w.audits = append(w.audits, row)
+		w.mu.Unlock()
+		return store.AuditChain{}, nil
+	})
+	w.engine = w.coordinator()
+	return w
+}
+
+// retryReasons lists the reasons of the retries queued for an attempt (audit action retry-queued).
+func (w *world) retryReasons(attemptID string) []string {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	var out []string
+	for _, row := range w.audits {
+		if row.Action == "retry-queued" && row.Target == attemptID {
+			out = append(out, row.Detail)
+		}
+	}
+	return out
+}
+
+// coordinator builds a fresh lease engine over the same store: a restarted coordinator process.
+func (w *world) coordinator() *lease.Engine {
+	return lease.New(w.store, nil, lease.Config{Clock: w.clock, Heartbeat: heartbeat, TTL: coordTTL})
+}
+
+func (w *world) clock() time.Time {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.now
+}
+
+func (w *world) advance(d time.Duration) {
+	w.mu.Lock()
+	w.now = w.now.Add(d)
+	w.mu.Unlock()
+}
+
+// job creates a pipeline, a job and its first attempt "<id>.a1".
+func (w *world) job(id, kind string, idempotent bool, infraMax int) string {
+	w.t.Helper()
+	p := store.PipelineRow{ID: "p-" + id, Project: "project", Revision: "r", Trigger: "local", SourceTrust: "owner", PrivacyZone: "local-only", PolicyDigest: "p", InputDigest: "i", SelectionMode: "full", Status: "queued"}
+	if err := w.store.CreatePipeline(w.ctx, p); err != nil {
+		w.t.Fatal(err)
+	}
+	if err := w.store.CreateJob(w.ctx, store.JobRow{ID: id, PipelineID: p.ID, Name: id, Kind: kind, Idempotent: idempotent, InfraMax: infraMax, InputDigest: "i"}); err != nil {
+		w.t.Fatal(err)
+	}
+	if err := w.store.CreateAttempt(w.ctx, store.AttemptRow{ID: id + ".a1", JobID: id, N: 1}, ""); err != nil {
+		w.t.Fatal(err)
+	}
+	return id + ".a1"
+}
+
+// grant leases a queued attempt to runner (one host per runner) and starts it; it returns the lease epoch.
+func (w *world) grant(attemptID, leaseID, runner string, incarnation int64) int64 {
+	w.t.Helper()
+	d := store.Demand{AttemptID: attemptID, LeaseID: leaseID, RunnerID: runner, CPU: 1, MemMB: 1, CapacityCPU: 100, CapacityMemMB: 100, TTL: coordTTL}
+	epoch, err := w.engine.Grant(w.ctx, "host-"+runner, d, incarnation)
+	if err != nil {
+		w.t.Fatalf("grant %s on %s: %v", attemptID, runner, err)
+	}
+	_, attemptEpoch := w.state(attemptID)
+	if err := w.store.Transition(w.ctx, attemptID, "leased", "running", store.TransitionDetail{Epoch: attemptEpoch}); err != nil {
+		w.t.Fatal(err)
+	}
+	return epoch
+}
+
+func (w *world) state(attemptID string) (string, int64) {
+	w.t.Helper()
+	st, epoch, err := w.store.AttemptStateEpoch(w.ctx, attemptID)
+	if err != nil {
+		w.t.Fatal(err)
+	}
+	return string(st), epoch
+}
+
+func (w *world) attempts(jobID string) []store.AttemptView {
+	w.t.Helper()
+	rows, err := w.store.AttemptsByJob(w.ctx, jobID)
+	if err != nil {
+		w.t.Fatal(err)
+	}
+	return rows
+}
+
+// active counts attempts of a job that hold or may hold a lease.
+func (w *world) active(jobID string) int {
+	n := 0
+	for _, a := range w.attempts(jobID) {
+		if a.State == "leased" || a.State == "running" || a.State == "finalizing" {
+			n++
+		}
+	}
+	return n
+}
+
+// wantAttempts checks the evidence: the state and failure_class of every attempt in order.
+func (w *world) wantAttempts(jobID string, want ...string) []store.AttemptView {
+	w.t.Helper()
+	rows := w.attempts(jobID)
+	got := make([]string, len(rows))
+	for i, a := range rows {
+		got[i] = a.State + "/" + a.FailureClass
+	}
+	if strings.Join(got, ",") != strings.Join(want, ",") {
+		w.t.Fatalf("job %s attempts = %v, want %v", jobID, got, want)
+	}
+	return rows
+}
+
+func (w *world) previousRunner(attemptID string) string {
+	w.t.Helper()
+	r, err := w.store.LeasePreviousRunner(w.ctx, attemptID)
+	if err != nil {
+		w.t.Fatal(err)
+	}
+	return r
+}
+
+// effect is the fixture job's side effect: one line per execution, stamped with the world clock.
+func (w *world) effect(jobID, runner string) {
+	w.t.Helper()
+	f, err := os.OpenFile(filepath.Join(w.effects, jobID), os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		w.t.Fatal(err)
+	}
+	defer func() { _ = f.Close() }()
+	if _, err := fmt.Fprintf(f, "%s %d\n", runner, w.clock().Unix()); err != nil {
+		w.t.Fatal(err)
+	}
+}
+
+// effects returns the lines of a job's side-effect file.
+func (w *world) effectLines(jobID string) []string {
+	w.t.Helper()
+	b, err := os.ReadFile(filepath.Join(w.effects, jobID))
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		w.t.Fatal(err)
+	}
+	return strings.Fields(strings.ReplaceAll(strings.TrimSpace(string(b)), " ", "@"))
+}
+
+// wantEffect asserts the side-effect file holds exactly one line, written by runner.
+func (w *world) wantEffect(jobID, runner string) {
+	w.t.Helper()
+	lines := w.effectLines(jobID)
+	if len(lines) != 1 || !strings.HasPrefix(lines[0], runner+"@") {
+		w.t.Fatalf("side effect of %s = %v, want one write by %s", jobID, lines, runner)
+	}
+}
+
+func hasCode(err error, code string) bool {
+	var coded *store.Error
+	return errors.As(err, &coded) && coded.Code == code
+}
+
+func wantCode(t *testing.T, what string, err error, code string) {
+	t.Helper()
+	if !hasCode(err, code) {
+		t.Fatalf("%s: got %v, want %s", what, err, code)
+	}
+}
diff --git a/free/ci/test/sim/auto/a10_scope_test.go b/free/ci/test/sim/auto/a10_scope_test.go
new file mode 100644
index 000000000..193c19f07
--- /dev/null
+++ b/free/ci/test/sim/auto/a10_scope_test.go
@@ -0,0 +1,36 @@
+package auto
+
+// Purpose: A10 scope proof: the commit-CI pool rule keeps the personal VPS out and the coordinator
+// pool in, and a dev run reaches the personal node only when the person lists its pool.
+// Inputs: pools.Resolve and pools/record.Excluded. Outputs: pass or fail. Constraints: pure.
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/pools/record"
+)
+
+func TestConformanceA10Scope(t *testing.T) {
+	runners := []pools.Runner{
+		{ID: "vps", Source: pools.SourceRegistry, Assigned: []string{"pool.mine"}, Projects: []string{"private"}},
+		{ID: "team-node", Source: pools.SourceCoordinator, Assigned: []string{"pool.team"}, Projects: []string{"private"}},
+	}
+	excluded := record.Excluded(pools.List{Set: true, IDs: []string{"team"}}, runners)
+	if len(excluded["vps"]) == 0 || excluded["vps"][0].Detail != record.Reason || len(excluded["team-node"]) != 0 {
+		t.Fatalf("commit CI pool rule: %v", excluded)
+	}
+	for _, tc := range []struct {
+		dev  []string
+		want bool
+	}{{[]string{"team"}, false}, {[]string{"mine", "team"}, true}} {
+		got := pools.Resolve(pools.Input{Runners: runners, Project: "private", Dev: true, DevPools: pools.List{Set: true, IDs: tc.dev}})
+		if slices.Contains(got.Eligible, "vps") != tc.want {
+			t.Fatalf("dev pools %v: %+v", tc.dev, got)
+		}
+		if !tc.want && got.Excluded["vps"][0].Detail != pools.DetailDevNotAllowed {
+			t.Fatalf("excluded = %v", got.Excluded)
+		}
+	}
+}
diff --git a/free/ci/test/sim/auto/a3_watch_test.go b/free/ci/test/sim/auto/a3_watch_test.go
new file mode 100644
index 000000000..944cc9a31
--- /dev/null
+++ b/free/ci/test/sim/auto/a3_watch_test.go
@@ -0,0 +1,160 @@
+package auto
+
+// Purpose: A3 three watch hosts, one fixture repository: every pushed commit gets a final result and
+// the duplicates the hosts report match the duplicates the ledger holds.
+// Inputs: watch.Watcher over an in-memory provider ledger; seeded pushes and partitions, then healing.
+// Outputs: pass or fail. Constraints: time is the ledger clock the test advances; the seed is printed.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math/rand/v2"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/watch"
+)
+
+var errPartition = errors.New("partition")
+
+type ledger struct {
+	mu    sync.Mutex
+	now   time.Time
+	st    map[string][]report.LedgerStatus
+	down  map[string]bool
+	heads []watch.Head
+}
+
+func (l *ledger) clock() time.Time { l.mu.Lock(); defer l.mu.Unlock(); return l.now }
+
+func (l *ledger) push(n int) string {
+	sha := fmt.Sprintf("%040x", n+1)
+	l.mu.Lock()
+	l.heads = append(l.heads, watch.Head{SHA: sha, Branch: fmt.Sprintf("b%d", n), Protected: true, Trust: model.TrustClass("owner")})
+	l.mu.Unlock()
+	return sha
+}
+
+func (l *ledger) finals(sha string) int {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	n := 0
+	for _, x := range l.st[sha] {
+		if x.Context == report.Context && (x.State == report.Success || x.State == report.Failure) {
+			n++
+		}
+	}
+	return n
+}
+
+type host struct {
+	l  *ledger
+	id string
+}
+
+func (h host) add(s report.Status) error {
+	h.l.mu.Lock()
+	defer h.l.mu.Unlock()
+	if h.l.down[h.id] {
+		return errPartition
+	}
+	h.l.st[s.Revision] = append(h.l.st[s.Revision], report.LedgerStatus{Context: s.ContextName(), State: s.State, Creator: "station", Description: s.Description, CreatedAt: h.l.now})
+	return nil
+}
+
+func (h host) PostClaim(_ context.Context, s report.Status) (time.Time, error) {
+	return h.l.clock(), h.add(s)
+}
+func (h host) Post(_ context.Context, s report.Status) error { return h.add(s) }
+
+func (h host) ListStatuses(_ context.Context, _, _, sha string) ([]report.LedgerStatus, time.Time, error) {
+	h.l.mu.Lock()
+	defer h.l.mu.Unlock()
+	if h.l.down[h.id] {
+		return nil, time.Time{}, errPartition
+	}
+	return append([]report.LedgerStatus(nil), h.l.st[sha]...), h.l.now, nil
+}
+
+func (h host) Scan(context.Context, string) (watch.Scan, error) {
+	h.l.mu.Lock()
+	defer h.l.mu.Unlock()
+	if h.l.down[h.id] {
+		return watch.Scan{}, errPartition
+	}
+	return watch.Scan{Heads: append([]watch.Head(nil), h.l.heads...)}, nil
+}
+
+type instant struct{}
+
+func (instant) Run(context.Context, watch.Job) (watch.Outcome, error) {
+	return watch.Outcome{State: report.Success, Description: "ok"}, nil
+}
+
+func newHost(t *testing.T, l *ledger, id string) *watch.Watcher {
+	t.Helper()
+	h := host{l: l, id: id}
+	c := watch.Defaults()
+	c.Repos, c.Host, c.Hosts, c.Trusted, c.Step, c.RunLimit = []string{"o/r"}, id, []string{"a", "b", "c"}, []string{"station"}, time.Minute, 30*time.Minute
+	w, err := watch.New(c, watch.Ports{Scanner: h, Ledger: h, Reporter: h, Runner: instant{}, Now: l.clock,
+		Ready:         func(context.Context) (bool, []string) { return true, nil },
+		ResultContext: func(context.Context, string, string, string) string { return report.Context }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return w
+}
+
+func TestConformanceA3Watch(t *testing.T) {
+	seed := uint64(time.Now().UnixNano())
+	rng := rand.New(rand.NewPCG(seed, 3))
+	l := &ledger{now: time.Date(2026, 10, 28, 9, 0, 0, 0, time.UTC), st: map[string][]report.LedgerStatus{}, down: map[string]bool{}}
+	ids := []string{"a", "b", "c"}
+	ws := map[string]*watch.Watcher{}
+	for _, id := range ids {
+		ws[id] = newHost(t, l, id)
+	}
+	var pushed []string
+	dups := 0
+	pass := func() {
+		for _, id := range ids {
+			dups += ws[id].Pass(context.Background()).Duplicates
+		}
+		l.mu.Lock()
+		l.now = l.now.Add(30 * time.Second)
+		l.mu.Unlock()
+	}
+	for i := 0; i < 120; i++ {
+		if rng.IntN(6) == 0 {
+			pushed = append(pushed, l.push(len(pushed)))
+		}
+		if rng.IntN(5) == 0 {
+			l.mu.Lock()
+			id := ids[rng.IntN(3)]
+			l.down[id] = !l.down[id]
+			l.mu.Unlock()
+		}
+		pass()
+	}
+	l.mu.Lock()
+	l.down = map[string]bool{}
+	l.mu.Unlock()
+	for i := 0; i < 200; i++ {
+		pass()
+	}
+	total := 0
+	for _, sha := range pushed {
+		n := l.finals(sha)
+		if n == 0 {
+			t.Fatalf("seed %d: commit %s has no final result", seed, sha[:12])
+		}
+		total += n - 1
+	}
+	if total != dups {
+		t.Fatalf("seed %d: %d duplicate finals in the ledger, %d reported", seed, total, dups)
+	}
+}
diff --git a/free/ci/test/sim/auto/a4_hosted_test.go b/free/ci/test/sim/auto/a4_hosted_test.go
new file mode 100644
index 000000000..7cc074ec2
--- /dev/null
+++ b/free/ci/test/sim/auto/a4_hosted_test.go
@@ -0,0 +1,74 @@
+package auto
+
+// Purpose: A4 the hosted tier on fixtures: a green hosted result stands, a red one stays red, a
+// queue that outlasts its timer hands over, and a billing-blocked account hands over then stays quiet.
+// Inputs: hostedtier.Observer over a fake read-only funnel. Outputs: pass or fail.
+// Constraints: no network; the clock is injected.
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/hostedtier"
+	"github.com/nself-org/plugins/free/ci/internal/providers/health"
+)
+
+var at = time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC)
+
+type funnel struct {
+	runs  []hostedtier.CheckRun
+	notes map[int64][]string
+	calls int
+}
+
+func (f *funnel) CheckRuns(context.Context, string) ([]hostedtier.CheckRun, error) {
+	f.calls++
+	return f.runs, nil
+}
+
+func (f *funnel) Annotations(_ context.Context, id int64) ([]string, error) {
+	f.calls++
+	return f.notes[id], nil
+}
+
+func hostedRun(status, conclusion string, created time.Time) hostedtier.CheckRun {
+	return hostedtier.CheckRun{ID: 7, Name: hostedtier.DefaultContext, AppID: hostedtier.GitHubActionsAppID, Status: status, Conclusion: conclusion, CreatedAt: created, StartedAt: created}
+}
+
+func observe(f *funnel) *hostedtier.Observer {
+	tr := health.New(health.Options{Clock: func() time.Time { return at }})
+	return &hostedtier.Observer{Funnel: f, Breaker: hostedtier.NewHealthBreaker(tr, "github-hosted"), Now: func() time.Time { return at }}
+}
+
+func TestConformanceA4Hosted(t *testing.T) {
+	cases := []struct {
+		name string
+		run  hostedtier.CheckRun
+		want hostedtier.Decision
+		why  string
+	}{
+		{"green", hostedRun("completed", "success", at), hostedtier.Use, hostedtier.ReasonSuccess},
+		{"red", hostedRun("completed", "failure", at), hostedtier.Use, hostedtier.ReasonFailure},
+		{"young queue", hostedRun("queued", "", at.Add(-10*time.Second)), hostedtier.Wait, hostedtier.ReasonQueued},
+		{"stale queue", hostedRun("queued", "", at.Add(-time.Minute)), hostedtier.HandOver, hostedtier.ReasonQueuedLong},
+	}
+	for _, c := range cases {
+		got := observe(&funnel{runs: []hostedtier.CheckRun{c.run}}).Decide(context.Background(), "sha", at)
+		if got.Decision != c.want || got.Reason != c.why {
+			t.Fatalf("%s: got %s/%s, want %s/%s", c.name, got.Decision, got.Reason, c.want, c.why)
+		}
+	}
+	// billing blocked: the first call hands over, the breaker window then makes no request at all
+	f := &funnel{runs: []hostedtier.CheckRun{hostedRun("completed", "failure", at)}, notes: map[int64][]string{7: {"recent account payments have failed or your spending limit needs to be increased"}}}
+	o := observe(f)
+	first := o.Decide(context.Background(), "sha", at)
+	if first.Decision != hostedtier.HandOver || first.Reason != hostedtier.ReasonBilling {
+		t.Fatalf("billing: got %s/%s", first.Decision, first.Reason)
+	}
+	calls := f.calls
+	again := o.Decide(context.Background(), "sha", at)
+	if again.Reason != hostedtier.ReasonUnavailable || again.Requests != 0 || f.calls != calls {
+		t.Fatalf("breaker window made requests: %+v", again)
+	}
+}
diff --git a/free/ci/test/sim/auto/a5_offload_test.go b/free/ci/test/sim/auto/a5_offload_test.go
new file mode 100644
index 000000000..5b72a54d9
--- /dev/null
+++ b/free/ci/test/sim/auto/a5_offload_test.go
@@ -0,0 +1,78 @@
+package auto
+
+// Purpose: A5 dirty-tree offload: a dirty tree becomes a snapshot commit under a private ref, a
+// secret-shaped untracked file is named and left out, and the ref is released.
+// Inputs: offload.Take over a scripted git (no process runs). Outputs: pass or fail.
+// Constraints: the scripted capture answers by git subcommand; nothing touches a real repository.
+
+import (
+	"context"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/offload"
+)
+
+const base = "1111111111111111111111111111111111111111"
+const snap = "2222222222222222222222222222222222222222"
+
+type gitLog struct{ calls []string }
+
+func (g *gitLog) capture(_ context.Context, argv ...string) (string, int, error) {
+	i := slices.Index(argv, "git")
+	sub := argv[i:]
+	for _, a := range sub {
+		switch a {
+		case "rev-parse":
+			g.calls = append(g.calls, a)
+			return base + "\n", 0, nil
+		case "status":
+			g.calls = append(g.calls, a)
+			return " M a.txt\n?? notes.txt\n?? .env\n", 0, nil
+		case "ls-files":
+			g.calls = append(g.calls, a)
+			if slices.Contains(sub, "--others") {
+				return "notes.txt\x00.env\x00", 0, nil
+			}
+			return "a.txt\x00", 0, nil
+		case "write-tree":
+			g.calls = append(g.calls, a)
+			return "tree\n", 0, nil
+		case "commit-tree":
+			g.calls = append(g.calls, a)
+			return snap + "\n", 0, nil
+		case "update-ref", "read-tree", "add":
+			g.calls = append(g.calls, a)
+			return "", 0, nil
+		}
+	}
+	return "", 1, nil
+}
+
+func TestConformanceA5Offload(t *testing.T) {
+	g := &gitLog{}
+	s, err := offload.Take(context.Background(), g.capture, t.TempDir(), t.TempDir(), "run1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Clean || s.SHA != snap || s.Ref != offload.RefPrefix+"run1" {
+		t.Fatalf("snapshot = %+v", s)
+	}
+	if !slices.Equal(s.Excluded, []string{".env"}) {
+		t.Fatalf("excluded = %v, want the env file by name", s.Excluded)
+	}
+	if !slices.Contains(g.calls, "update-ref") || !slices.Contains(g.calls, "commit-tree") {
+		t.Fatalf("calls = %v", g.calls)
+	}
+	n := len(g.calls)
+	if err = offload.Release(context.Background(), g.capture, t.TempDir(), s); err != nil {
+		t.Fatal(err)
+	}
+	if len(g.calls) <= n || !strings.Contains(strings.Join(g.calls[n:], " "), "update-ref") {
+		t.Fatalf("release did not delete the ref: %v", g.calls[n:])
+	}
+	if _, err = offload.Take(context.Background(), g.capture, t.TempDir(), t.TempDir(), "bad id"); err == nil {
+		t.Fatal("a bad snapshot id was accepted")
+	}
+}
diff --git a/free/ci/test/sim/auto/a6_refusal_test.go b/free/ci/test/sim/auto/a6_refusal_test.go
new file mode 100644
index 000000000..1a53fc3e2
--- /dev/null
+++ b/free/ci/test/sim/auto/a6_refusal_test.go
@@ -0,0 +1,77 @@
+package auto
+
+// Purpose: A6 a node that is busy (interactive use) or short of memory refuses the job, and the
+// explanation a `status --json` consumer reads names the runner, the reason code and eligibility.
+// Inputs: sched.Place over a world of one busy, one low-memory and one idle runner. Outputs: pass or fail.
+// Constraints: pure; no clock.
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/background"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+func runnerOf(id string, memMB int64, interactive string) sched.Runner {
+	loc, os, arch := "lan", "linux", "amd64"
+	cpu, mem := float64(8), memMB
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Lifecycle.AuthorizedProjects, c.Lifecycle.Eligible = []string{"p"}, true
+	c.Protocol.Versions, c.Protocol.Min = []int{1}, 1
+	c.Platform.OS.Value, c.Platform.Arch.Value = &os, &arch
+	c.Resources.CPU.Value, c.Resources.MemMB.Value = &cpu, &mem
+	c.Location.Kind.Value = &loc
+	if interactive != "" {
+		c.Availability.Interactive.Value = &interactive
+	}
+	return sched.Runner{ID: id, Location: loc, Class: "owned", Provider: "operator", Avail: sched.Avail{Slots: 2, CPU: 16, MemMB: memMB}, Capability: c,
+		Decl: trust.Declaration{Accepts: []model.TrustClass{"owner"}, Isolation: "vm", Network: "privileged", UIDSeparation: true, Ownership: "operator", NoLANRoute: true}}
+}
+
+func TestConformanceA6Refusal(t *testing.T) {
+	w := sched.World{Runners: []sched.Runner{runnerOf("idle", 16384, "idle"), runnerOf("low-mem", 64, "idle")},
+		Policy: sched.Policy{Preset: "balanced"}, Costs: map[string]sched.Cost{}, Previous: map[string]string{}}
+	j := sched.Job{Key: "job", ID: "job", Project: "p", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 2048}, Trust: "owner", Network: "lan", TimeoutMs: 60000}
+	res := sched.Place(w, []sched.Job{j})
+	if len(res.Placements) != 1 || res.Placements[0].RunnerID != "idle" {
+		t.Fatalf("placements = %+v", res.Placements)
+	}
+	raw, err := json.Marshal(res.Explanations)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rows []struct {
+		Alternatives []struct {
+			RunnerID string `json:"runner_id"`
+			Eligible bool   `json:"eligible"`
+			Reasons  []struct {
+				Code string `json:"code"`
+			} `json:"reasons"`
+		} `json:"alternatives"`
+	}
+	if err = json.Unmarshal(raw, &rows); err != nil || len(rows) != 1 {
+		t.Fatalf("explanation json: %v %s", err, raw)
+	}
+	seen := map[string]bool{}
+	for _, a := range rows[0].Alternatives {
+		if a.RunnerID == "low-mem" {
+			seen["low"] = !a.Eligible && len(a.Reasons) > 0
+		}
+		if a.RunnerID == "idle" {
+			seen["idle"] = a.Eligible && len(a.Reasons) == 0
+		}
+	}
+	if !seen["low"] || !seen["idle"] {
+		t.Fatalf("status fields = %s", raw)
+	}
+	// a node in interactive use refuses background work, naming the cause
+	v := background.Contended(runnerOf("busy", 16384, "active"))
+	if !v.Busy() || !slices.Contains(v.Causes, background.InteractiveActive) {
+		t.Fatalf("verdict = %+v", v)
+	}
+}
diff --git a/free/ci/test/sim/auto/a7_race_test.go b/free/ci/test/sim/auto/a7_race_test.go
new file mode 100644
index 000000000..7b6325728
--- /dev/null
+++ b/free/ci/test/sim/auto/a7_race_test.go
@@ -0,0 +1,102 @@
+package auto
+
+// Purpose: A7 two eligible nodes race one job: the faster finishes, the slower is cancelled, and
+// exactly one result is recorded and posted; a repeated cancel does nothing.
+// Inputs: race.Select and race.Run over a virtual two-node cluster. Outputs: pass or fail.
+// Constraints: no processes, no sleeps; the virtual clock ends the shortest process group.
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/race"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+type rnode struct {
+	takes  time.Duration
+	pgroup bool
+	end    chan race.Result
+}
+
+type cluster struct {
+	mu       sync.Mutex
+	nodes    map[string]*rnode
+	admitted int
+	posted   []race.Evidence
+	now      time.Duration
+}
+
+func (c *cluster) Create(_ context.Context, n int, runner string) (race.Sibling, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.nodes[runner].pgroup = true
+	c.admitted++
+	if c.admitted == len(c.nodes) {
+		var next *rnode
+		for _, nd := range c.nodes {
+			if nd.pgroup && (next == nil || nd.takes < next.takes) {
+				next = nd
+			}
+		}
+		c.now, next.pgroup = next.takes, false
+		next.end <- race.Result{State: race.StatePassed}
+	}
+	return race.Sibling{N: n, AttemptID: fmt.Sprintf("job.a%d", n), LeaseID: "lease-" + runner, RunnerID: runner, Epoch: 1}, nil
+}
+
+func (c *cluster) Wait(_ context.Context, s race.Sibling) race.Result {
+	return <-c.nodes[s.RunnerID].end
+}
+
+func (c *cluster) Cancel(_ context.Context, s race.Sibling, _ string) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if n := c.nodes[s.RunnerID]; n.pgroup {
+		n.pgroup = false
+		n.end <- race.Result{State: race.StateCancelled, FailureClass: race.StateCancelled}
+	}
+	return nil
+}
+
+func (c *cluster) Post(_ context.Context, e race.Evidence) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.posted = append(c.posted, e)
+	return nil
+}
+
+func TestConformanceA7Race(t *testing.T) {
+	w := sched.World{Runners: []sched.Runner{runnerOf("fast", 16384, "idle"), runnerOf("slow", 16384, "idle")},
+		Policy: sched.Policy{Preset: "balanced"}, Costs: map[string]sched.Cost{}, Previous: map[string]string{}}
+	j := sched.Job{Key: "job", ID: "job", Project: "p", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan", TimeoutMs: 60000}
+	choice := race.Select(w, j, race.DefaultWidth, false)
+	if !choice.Raceable() || len(choice.Runners) != 2 {
+		t.Fatalf("choice = %+v", choice)
+	}
+	c := &cluster{nodes: map[string]*rnode{
+		"fast": {takes: 40 * time.Second, end: make(chan race.Result, 1)},
+		"slow": {takes: 90 * time.Second, end: make(chan race.Result, 1)},
+	}}
+	ev, err := race.Run(context.Background(), race.Spec{Job: "job", Choice: choice, First: 1}, c, c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ev.Winner == nil || ev.Winner.RunnerID != "fast" || ev.Result.State != race.StatePassed || c.now != 40*time.Second {
+		t.Fatalf("winner = %+v result = %+v at %v", ev.Winner, ev.Result, c.now)
+	}
+	if c.nodes["fast"].pgroup || c.nodes["slow"].pgroup {
+		t.Fatal("a process group outlived the race")
+	}
+	if len(ev.Losers) != 1 || ev.Losers[0].RunnerID != "slow" || len(c.posted) != 1 {
+		t.Fatalf("losers = %+v, posted %d", ev.Losers, len(c.posted))
+	}
+	if err = c.Cancel(context.Background(), ev.Losers[0].Sibling, "again"); err != nil || len(c.nodes["slow"].end) != 0 {
+		t.Fatal("a repeated cancel had an effect")
+	}
+}
diff --git a/free/ci/test/sim/auto/a9_deadnode_test.go b/free/ci/test/sim/auto/a9_deadnode_test.go
new file mode 100644
index 000000000..768dcc077
--- /dev/null
+++ b/free/ci/test/sim/auto/a9_deadnode_test.go
@@ -0,0 +1,49 @@
+package auto
+
+// Purpose: A9 status with one registered node at an unroutable address (dead-lab, TEST-NET
+// 192.0.2.1) among healthy nodes: the node checks fail that node alone and the section exits red.
+// Inputs: nodes/doctor.Evaluate over Facts built in memory. Outputs: pass or fail.
+// Constraints: no dial happens; reachability is a fact the test supplies.
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/doctor"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	nd "github.com/nself-org/plugins/free/ci/internal/nodes/doctor"
+)
+
+func sshNodeOf(id, host string) nd.Node {
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Identity.ID, c.Identity.Name, c.Identity.Provider, c.Identity.Transport = id, id, "ssh", "ssh"
+	c.Identity.SSH = &model.CapabilitySSH{Hostname: host, Port: 22, User: "ci"}
+	return nd.Node{Cap: c, State: "online"}
+}
+
+func TestConformanceA9DeadNode(t *testing.T) {
+	f := nd.Facts{
+		Now:   time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC),
+		Nodes: []nd.Node{sshNodeOf("alpha", "alpha.lan.test"), sshNodeOf("bravo", "bravo.lan.test"), sshNodeOf("dead-lab", "192.0.2.1")},
+		Reach: map[string]error{"alpha": nil, "bravo": nil, "dead-lab": errors.New("dial tcp 192.0.2.1:22: i/o timeout")},
+	}
+	out := nd.Evaluate(f)
+	fails := map[string]bool{}
+	reach := 0
+	for _, c := range out {
+		if c.ID != nd.IDReach {
+			continue
+		}
+		reach++
+		if c.Status == doctor.Fail {
+			fails[c.Subject] = true
+		}
+	}
+	if reach != 3 || len(fails) != 1 || !fails["dead-lab"] {
+		t.Fatalf("reachability rows %d, failing subjects %v", reach, fails)
+	}
+	if doctor.ExitCode(out) == doctor.ExitClean {
+		t.Fatal("a dead node left the section clean")
+	}
+}
diff --git a/free/ci/test/sim/auto/doc.go b/free/ci/test/sim/auto/doc.go
new file mode 100644
index 000000000..b3805b0fc
--- /dev/null
+++ b/free/ci/test/sim/auto/doc.go
@@ -0,0 +1,8 @@
+// Package auto holds the simulated legs of the AUTO conformance suite (P7-AUTO-25).
+//
+// Purpose: acceptance legs A3 to A7, A9 and A10 as deterministic Go tests that
+// `free/ci/scripts/ci-conformance.sh --sim` runs one by one.
+// Inputs: in-memory fakes of the provider, nodes and processes; no network.
+// Outputs: pass or fail per test, named TestConformance<Leg>.
+// Constraints: pure Go, no processes, no sleeps, no fixed ports; seeded generators print the seed.
+package auto
diff --git a/free/ci/test/sim/claims_test.go b/free/ci/test/sim/claims_test.go
new file mode 100644
index 000000000..cb2dfdef3
--- /dev/null
+++ b/free/ci/test/sim/claims_test.go
@@ -0,0 +1,180 @@
+package sim
+
+// Purpose: P7-AUTO-10 proof of the claim ledger with three stations over an
+// in-memory provider: killed hosts, a partition during PostClaim, skewed local
+// clocks and delayed completion. Every decision reads only the provider clock.
+// Inputs:  claims.Decide over a shared status list. Outputs: pass or fail.
+// Constraints: no sleeps, no ports; time is a counter the test advances.
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/claims"
+)
+
+const (
+	clRunLimit = 30 * time.Minute
+	clStep     = time.Minute
+)
+
+var clT0 = time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+
+type clProvider struct {
+	now      time.Time
+	st       []claims.Status
+	down     map[string]bool // host -> partitioned
+	finals   int
+	dupFinal int
+}
+
+type clHost struct {
+	id        string
+	firstSeen time.Time
+	running   bool
+	doneAt    time.Time
+	errors    int
+	evidence  int
+	skew      time.Duration // local clock error; never read by a decision
+}
+
+func (p *clProvider) in(h *clHost) claims.Inputs {
+	return claims.Inputs{Now: p.now, Statuses: append([]claims.Status{}, p.st...), Me: claims.Me{Host: h.id, Incarnation: "i1"},
+		Trusted: []string{"station"}, RunLimit: clRunLimit, Hosts: []string{"a", "b", "c"}, Step: clStep,
+		FirstSeen: h.firstSeen, RetryMax: 1, RetryGap: time.Minute}
+}
+
+func (p *clProvider) post(h *clHost, ctx, state, desc string) error {
+	if p.down[h.id] {
+		return errors.New("partition")
+	}
+	p.st = append(p.st, claims.Status{Context: ctx, State: state, Creator: "station", Description: desc, CreatedAt: p.now})
+	return nil
+}
+
+// step is one watch pass of host h.
+func (p *clProvider) step(h *clHost) {
+	if h.running {
+		if p.now.Before(h.doneAt) {
+			return
+		}
+		h.running = false
+		if p.down[h.id] || !claims.MayPublish(p.in(h)) {
+			h.evidence++
+			return
+		}
+		_ = p.post(h, "nself-ci", "success", "done host="+h.id)
+		p.finals++
+		return
+	}
+	if p.down[h.id] {
+		h.errors++ // the host runs nothing and records an error locally
+		return
+	}
+	if h.firstSeen.IsZero() {
+		h.firstSeen = p.now
+	}
+	d := claims.Decide(p.in(h))
+	if d.Kind != claims.Take {
+		return
+	}
+	if !d.Holds {
+		if err := p.post(h, "nself-ci/claim", "pending", "claim "+h.id+" i1"); err != nil {
+			h.errors++
+			return
+		}
+		if d = claims.Decide(p.in(h)); !d.Holds {
+			return // lost the read-back: posts nothing more
+		}
+	}
+	h.running, h.doneAt = true, p.now.Add(5*time.Minute)
+}
+
+func clRun(p *clProvider, hs []*clHost, passes int, every time.Duration) {
+	for i := 0; i < passes; i++ {
+		for _, h := range hs {
+			p.step(h)
+		}
+		p.now = p.now.Add(every)
+	}
+}
+
+func clNew(skews ...time.Duration) (*clProvider, []*clHost) {
+	p := &clProvider{now: clT0, down: map[string]bool{}}
+	hs := []*clHost{{id: "a"}, {id: "b"}, {id: "c"}}
+	for i, s := range skews {
+		hs[i].skew = s
+	}
+	return p, hs
+}
+
+func TestClaimsThreeHostsKillPreferred(t *testing.T) {
+	// killed BEFORE it claims: b starts after step, c loses the tie
+	p, hs := clNew()
+	p.down["a"] = true
+	clRun(p, hs, 20, 30*time.Second)
+	if p.finals != 1 {
+		t.Fatalf("finals %d", p.finals)
+	}
+	if hs[0].running || hs[2].evidence != 0 {
+		t.Fatal("a must not run; c must not have a result")
+	}
+	// killed AFTER it claimed: b/c wait until the claim is dead
+	p, hs = clNew()
+	p.step(hs[0])
+	p.down["a"] = true
+	hs[0].running = false
+	clRun(p, hs, 20, time.Minute)
+	if p.finals != 0 {
+		t.Fatalf("claim still live at %v, final posted", p.now.Sub(clT0))
+	}
+	p.now = clT0.Add(clRunLimit + claims.DeadGrace + time.Second)
+	clRun(p, hs, 20, time.Minute)
+	if p.finals != 1 {
+		t.Fatalf("no commit may end without a final: %d", p.finals)
+	}
+}
+
+func TestClaimsPartition(t *testing.T) {
+	p, hs := clNew()
+	p.down["a"] = true
+	p.step(hs[0])
+	if hs[0].running || hs[0].errors != 1 || len(p.st) != 0 {
+		t.Fatal("a partitioned PostClaim means nothing runs")
+	}
+	p.down["a"] = false
+	clRun(p, hs, 12, time.Minute)
+	if p.finals != 1 {
+		t.Fatalf("recover on the next pass: %d", p.finals)
+	}
+	// a completion delayed past a takeover keeps its result as evidence
+	p, hs = clNew()
+	p.step(hs[0])
+	p.now = clT0.Add(clRunLimit + claims.DeadGrace + time.Minute)
+	hs[0].running = true
+	hs[0].doneAt = p.now
+	p.st = append(p.st, claims.Status{Context: "nself-ci/claim", State: "pending", Creator: "station",
+		Description: "claim b i1", CreatedAt: p.now.Add(-time.Second)})
+	p.step(hs[0])
+	if p.finals != 0 || hs[0].evidence != 1 {
+		t.Fatalf("late host posts nothing: finals %d evidence %d", p.finals, hs[0].evidence)
+	}
+}
+
+func TestClaimsClockSkew(t *testing.T) {
+	var want int
+	for i, skew := range []time.Duration{0, 10 * time.Minute, -10 * time.Minute} {
+		p, hs := clNew(skew, -skew, skew/2)
+		clRun(p, hs, 15, time.Minute)
+		if i == 0 {
+			want = p.finals
+		}
+		if p.finals != 1 || p.finals != want {
+			t.Fatalf("skew %v: finals %d", skew, p.finals)
+		}
+		if hs[1].running || hs[2].running {
+			t.Fatal("only the preferred host runs")
+		}
+	}
+}
diff --git a/free/ci/test/sim/foreground_remote_test.go b/free/ci/test/sim/foreground_remote_test.go
index 6438e1db0..128d5eb7b 100644
--- a/free/ci/test/sim/foreground_remote_test.go
+++ b/free/ci/test/sim/foreground_remote_test.go
@@ -55,8 +55,9 @@ type node struct {
 	sessions atomic.Int32
 	started  chan string // attempt ids whose job began here
 	mu       sync.Mutex
-	kill     func() error // drops the live session
-	jobs     []string     // lease ids this node ran
+	kill     func() error                          // drops the live session
+	wrap     func(session.Carrier) session.Carrier // optional: wraps the node's carrier (the offload sim stages the checkout bundle through it)
+	jobs     []string                              // lease ids this node ran
 }
 
 func (n *node) ran() []string {
@@ -80,6 +81,10 @@ func (n *node) serve(ctx context.Context, table *slots.Table, in io.Reader, out
 	if err != nil {
 		return err
 	}
+	var carrier session.Carrier = car
+	if n.wrap != nil {
+		carrier = n.wrap(car)
+	}
 	run := session.RunnerFunc(func(ctx context.Context, j session.JobRun) (session.JobResult, error) {
 		n.mu.Lock()
 		n.jobs = append(n.jobs, j.Lease.LeaseID)
@@ -90,7 +95,7 @@ func (n *node) serve(ctx context.Context, table *slots.Table, in io.Reader, out
 		}
 		return n.runner(ctx, n, j)
 	})
-	s, err := session.New(session.Config{Carrier: car, Key: fakeKey{}, Slots: table, Runner: run, StateDir: n.state, Hooks: []session.JobHook{},
+	s, err := session.New(session.Config{Carrier: carrier, Key: fakeKey{}, Slots: table, Runner: run, StateDir: n.state, Hooks: []session.JobHook{},
 		Coordinator: session.Coordinator{ID: "coord", RootFingerprint: "fp"}, Facts: session.Facts{AgentVersion: "1.5.0", MachineID: n.id}})
 	if err != nil {
 		return err
diff --git a/free/ci/test/sim/multiproject_test.go b/free/ci/test/sim/multiproject_test.go
new file mode 100644
index 000000000..bb4f305f8
--- /dev/null
+++ b/free/ci/test/sim/multiproject_test.go
@@ -0,0 +1,248 @@
+//go:build integration
+
+package sim
+
+// Purpose: P7-NODE-30 acceptance, scenario "several projects on one fleet" (Epic NODE D19). Projects A and B
+// are two git repositories; the fleet is mac1 (label xcode), vps-a (label project=a, authorized for A only)
+// and vps-shared (authorized for A and B). Labels and authorizations are set through the same operations
+// `nself ci nodes label` and `nodes projects` run, A's project-scope policy `sched.overrides.labels:
+// [project=a]` is written through the policy writer `ci policy set --scope project` uses, and the world
+// and the placement are the ones `ci plan` builds. A's jobs land only on vps-a, B's never on vps-a, and an A
+// job that also needs xcode waits with labels.mismatch whose explanation names the override.
+// Inputs:  git on PATH, no network, no processes beyond git.
+// Outputs: pass or fail.
+// Constraints: INTEGRATION=1; the world label source is process-wide, so this is the only test of the
+//          package that registers it; tests do not run in parallel.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/audit"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/roles"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/schedpolicy"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+// projectRepo makes a git repository with one commit and returns its root and repo id.
+func projectRepo(t *testing.T, run policy.Runner, name string) (root, id string) {
+	t.Helper()
+	root = filepath.Join(t.TempDir(), name)
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	gitIn(t, root, "init", "-q")
+	if err := os.WriteFile(filepath.Join(root, "f.txt"), []byte(name), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	gitIn(t, root, "add", "f.txt")
+	gitIn(t, root, "commit", "-q", "-m", "init "+name)
+	id = policy.ProjectIDGit(context.Background(), run, root)
+	if id == "" {
+		t.Fatalf("no repo id for %s", root)
+	}
+	return root, id
+}
+
+// registerFleetNode registers one linux node the owner's jobs may use, online, with the trust a dedicated
+// operator node has; the vps fixture supplies a valid capability document.
+func registerFleetNode(t *testing.T, st *store.Store, id string) {
+	t.Helper()
+	ctx := context.Background()
+	raw, err := os.ReadFile("../../internal/model/testdata/capability/valid/vps.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var c model.Capability
+	if err = json.Unmarshal(raw, &c); err != nil {
+		t.Fatal(err)
+	}
+	lan, owned, uid, slots := "lan", "owned", true, 4
+	c.Identity.ID, c.Identity.Name, c.Identity.Labels = id, id, nil
+	c.Location.Kind.Value, c.Economics.Class.Value = &lan, &owned
+	c.Separation.UIDSeparation = model.Fact[bool]{Value: &uid, Source: "self", ObservedAt: time.Now(), Confidence: "known"}
+	c.Availability.Slots.Value = &slots
+	c.Lifecycle = model.CapabilityLifecycle{AuthorizedProjects: []string{}} // enrolled by the operator, not merely discovered
+	reg := registry.New(st)
+	doc, err := json.Marshal(c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// the way `nodes add` stores an enrolled node: not merely discovered, no project yet
+	if err = st.NodePut(ctx, store.NodeRecord{ID: id, Name: id, State: "offline", Lifecycle: []byte("{}"), Trust: []byte("{}"), DeployHost: []byte("{}"), Capability: doc, ObservedAt: time.Now().UnixNano()}, "test"); err != nil {
+		t.Fatal(err)
+	}
+	admin, err := store.NewAdminAuthority("test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	trust := model.CapabilityTrust{
+		Accepts:       assigned([]model.TrustClass{"owner", "internal"}),
+		Isolation:     assigned(model.Isolation("container")),
+		Network:       assigned([]model.NetworkScope{"none", "internet", "restricted", "lan", "privileged"}),
+		SecretClasses: assigned([]model.SecretClass{"none"}),
+		PrivacyZone:   assigned(model.PrivacyZone("private-infrastructure")),
+	}
+	if _, err = reg.SetTrust(ctx, id, trust, admin); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = reg.SetState(ctx, id, "online", "", "test"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func fleetJob(key, project string, requires ...string) sched.Job {
+	return sched.Job{Key: key, ID: key, Project: project, Pipeline: sched.Pipeline{ID: "pipe-" + project, Support: []string{"linux/arm64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/arm64", CPU: 1, MemMB: 128, Labels: requires},
+		Trust:        "owner", Network: "lan", TimeoutMs: 60000, PersonalOwnRun: true}
+}
+
+// explain renders every alternative's reasons for a failure message.
+func explain(r sched.Result) string {
+	out := ""
+	for _, x := range r.Explanations {
+		out += x.JobKey + " " + x.Status + ":"
+		for _, a := range x.Alternatives {
+			out += " [" + a.RunnerID
+			for _, q := range a.Reasons {
+				out += " " + q.Code + "(" + q.Detail + ")"
+			}
+			out += "]"
+		}
+	}
+	return out
+}
+
+func TestSeveralProjects(t *testing.T) {
+	integration(t)
+	ctx := context.Background()
+	run := policy.Runner(report.Capture)
+	rootA, idA := projectRepo(t, run, "project-a")
+	rootB, idB := projectRepo(t, run, "project-b")
+	if idA == idB {
+		t.Fatal("two repositories share a repo id")
+	}
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	for _, n := range []string{"mac1", "vps-a", "vps-shared"} {
+		registerFleetNode(t, st, n)
+	}
+	resolve := func(c context.Context, dir string) (string, bool) {
+		id := policy.ProjectIDGit(c, run, dir)
+		return id, id != ""
+	}
+	env := labels.Env{Store: st, Registry: registry.New(st), Actor: "cli:test", ResolveDir: resolve}
+	if err = labels.RegisterSource(env.Store); err != nil {
+		t.Fatal(err)
+	}
+	for node, set := range map[string][]string{"mac1": {"xcode"}, "vps-a": {"project=a"}} {
+		if _, err = env.Edit(ctx, node, set, nil); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// A directory argument resolves to the repo id evidence uses; a bare id is taken as given.
+	for node, args := range map[string][]string{"mac1": {rootA, rootB}, "vps-a": {rootA}, "vps-shared": {rootA, idB}} {
+		added, e := env.AddProjects(ctx, node, args, false)
+		if e != nil || len(added) != len(args) {
+			t.Fatalf("authorize %s: %v %v", node, added, e)
+		}
+	}
+	if got, _ := env.Projects(ctx, "vps-a"); len(got) != 1 || got[0] != idA {
+		t.Fatalf("vps-a is authorized for %v, want only A", got)
+	}
+	// A's project-scope policy, written the way `ci policy set --scope project` writes it.
+	svc := roles.New(st, &audit.Log{St: st})
+	w := &policy.Writer{Store: st, Log: svc.Log, Run: run}
+	if _, err = w.Apply(ctx, svc.Operator("cli:test"), policy.Change{Op: policy.OpSet, Scope: "project", Root: rootA, Project: idA,
+		Key: schedpolicy.KeyLabels, Value: json.RawMessage(`["project=a"]`)}); err != nil {
+		t.Fatal(err)
+	}
+	policyOf := func(root, id string) sched.Policy {
+		t.Helper()
+		got, e := (&policy.Resolver{Store: st, Run: run}).Resolve(ctx, policy.Repo{Root: root, Project: id, Visibility: "unknown", Class: "owner"}, policy.Revision{})
+		if e != nil {
+			t.Fatal(e)
+		}
+		p, e := schedpolicy.Placement(&got.Effective)
+		if e != nil {
+			t.Fatal(e)
+		}
+		return p
+	}
+	place := func(root, id string, jobs ...sched.Job) sched.Result {
+		t.Helper()
+		sp := policyOf(root, id)
+		deps := world.Deps{Store: st, Policy: func(context.Context, string) (sched.Policy, error) { return sp, nil }, Clock: time.Now}
+		wd, _, e := world.Build(ctx, deps, jobs[0].Pipeline)
+		if e != nil {
+			t.Fatal(e)
+		}
+		return sched.Place(wd, jobs)
+	}
+
+	resA := place(rootA, idA, fleetJob("a1", idA), fleetJob("a2", idA), fleetJob("a3", idA))
+	if len(resA.Placements) != 3 {
+		t.Fatalf("A's jobs: %d placed, explanations %s", len(resA.Placements), explain(resA))
+	}
+	for _, p := range resA.Placements {
+		if p.RunnerID != "vps-a" {
+			t.Fatalf("A's job %s landed on %s, want only vps-a", p.JobKey, p.RunnerID)
+		}
+	}
+	resB := place(rootB, idB, fleetJob("b1", idB), fleetJob("b2", idB), fleetJob("b3", idB), fleetJob("b4", idB))
+	if len(resB.Placements) != 4 {
+		t.Fatalf("B's jobs: %d placed, explanations %+v", len(resB.Placements), resB.Explanations)
+	}
+	for _, p := range resB.Placements {
+		if p.RunnerID == "vps-a" {
+			t.Fatalf("B's job %s landed on vps-a, which is not authorized for B", p.JobKey)
+		}
+	}
+	// A job of A that also needs xcode: mac1 has xcode but not project=a, vps-a the reverse; it waits.
+	resX := place(rootA, idA, fleetJob("a-xcode", idA, "xcode"))
+	if len(resX.Placements) != 0 || len(resX.Explanations) != 1 {
+		t.Fatalf("an xcode job of A was placed: %+v", resX)
+	}
+	named := map[string]bool{}
+	for _, alt := range resX.Explanations[0].Alternatives {
+		for _, r := range alt.Reasons {
+			if r.Code == string(model.LabelsMismatch) {
+				named[alt.RunnerID+":"+r.Detail] = true
+			}
+		}
+	}
+	// project=a is not in the job's own requires.labels ([xcode]): the explanation names it only because
+	// A's project-scope policy sched.overrides.labels carries it, so the override is what the text points at.
+	if got := policyOf(rootA, idA).Overrides.Labels; len(got) != 1 || got[0] != "project=a" {
+		t.Fatalf("A's effective %s = %v", schedpolicy.KeyLabels, got)
+	}
+	for _, r := range resX.Explanations[0].Alternatives[0].Reasons {
+		if r.Detail == "project=a" && r.Code != string(model.LabelsMismatch) {
+			t.Fatalf("the override is reported as %s, want %s", r.Code, model.LabelsMismatch)
+		}
+	}
+	for _, want := range []string{"mac1:project=a", "vps-a:xcode", "vps-shared:xcode", "vps-shared:project=a"} {
+		if !named[want] {
+			t.Fatalf("labels.mismatch %q missing from the explanation: %v", want, named)
+		}
+	}
+	// B's xcode job has no override and runs on mac1, the only node with the label that B may use.
+	resBX := place(rootB, idB, fleetJob("b-xcode", idB, "xcode"))
+	if len(resBX.Placements) != 1 || resBX.Placements[0].RunnerID != "mac1" {
+		t.Fatalf("B's xcode job: %+v", resBX)
+	}
+}
diff --git a/free/ci/test/sim/offload_test.go b/free/ci/test/sim/offload_test.go
new file mode 100644
index 000000000..ffefe11fb
--- /dev/null
+++ b/free/ci/test/sim/offload_test.go
@@ -0,0 +1,363 @@
+package sim
+
+// Purpose: P7-AUTO-13 acceptance on a simulated node. A laptop tree with uncommitted work runs
+// on a node: the dirty tree becomes a snapshot commit, the real ssh driver bundles it, the
+// node-side checkout receiver verifies and unpacks it, and the node's job sees exactly the
+// user's tree. No Docker, no network, no real ssh.
+// Inputs:  a real git repository with a modified tracked file, an untracked file, an ignored
+//          .env and an untracked .env.local; two registered nodes (the foreground fixture).
+// Outputs: what the node staged, the run result, and the repository state before and after.
+// Constraints: NSELF_V15=1 (set by the fixture); the user's git status, index and refs are
+//              byte-identical after the run, after a failing job and after a cancel; the
+//              private offload ref is gone; secret file content never reaches the report.
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/agent/checkout"
+	"github.com/nself-org/plugins/free/ci/internal/agent/session"
+	ciexec "github.com/nself-org/plugins/free/ci/internal/exec"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/offload"
+	"github.com/nself-org/plugins/free/ci/internal/plan"
+	"github.com/nself-org/plugins/free/ci/internal/protocol"
+	"github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/transport/ssh"
+)
+
+const (
+	secretEnv   = "ENV_VALUE_MUST_NOT_TRAVEL"
+	secretLocal = "ENV_LOCAL_VALUE_MUST_NOT_TRAVEL"
+)
+
+// realGit is the run.Capture of a real process: the snapshot builder and GitRevision need real git.
+func realGit(ctx context.Context, argv ...string) (string, int, error) {
+	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	var b bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &b, &b
+	err := cmd.Run()
+	if ee, ok := err.(*exec.ExitError); ok {
+		return b.String(), ee.ExitCode(), nil
+	}
+	return b.String(), 0, err
+}
+
+// stageCarrier is the node side of the checkout: lease announcements and the bundle's chunk
+// frames go to the receiver, as `serve --stdio` does, and never reach the session.
+type stageCarrier struct {
+	session.Carrier
+	r *checkout.Receiver
+}
+
+func (c *stageCarrier) Recv() (protocol.Message, error) {
+	for {
+		m, err := c.Carrier.Recv()
+		if err != nil {
+			return m, err
+		}
+		switch b := m.Body.(type) {
+		case *protocol.Lease:
+			_ = c.r.Expect(*b)
+		case *protocol.Chunk:
+			if b.Stream != checkout.Stream {
+				return m, nil
+			}
+			epoch := uint64(0)
+			if m.Epoch != nil {
+				epoch = *m.Epoch
+			}
+			_ = c.r.Feed(m.LeaseID, epoch, *b)
+			continue
+		}
+		return m, nil
+	}
+}
+
+// seen is what a node's job found in the tree it was given.
+type seen struct {
+	err   error
+	head  string
+	files map[string]string // name -> content, for the names asked about; absent names are missing
+}
+
+// offloadNodes gives every node a receiver and returns a runner factory that stages the lease's
+// bundle, records what the job sees, then calls body.
+type offloadNodes struct {
+	mu    sync.Mutex
+	recv  map[string]*checkout.Receiver
+	seen  chan seen
+	probe []string
+}
+
+func newOffloadNodes(f *fixture, probe ...string) *offloadNodes {
+	o := &offloadNodes{recv: map[string]*checkout.Receiver{}, seen: make(chan seen, 4), probe: probe}
+	for _, n := range f.nodes {
+		n.wrap = func(c session.Carrier) session.Carrier {
+			r := checkout.NewReceiver(filepath.Join(n.state, "checkout"), nil)
+			o.mu.Lock()
+			o.recv[n.id] = r
+			o.mu.Unlock()
+			return &stageCarrier{Carrier: c, r: r}
+		}
+	}
+	return o
+}
+
+func (o *offloadNodes) runner(body func(context.Context, session.JobRun) (session.JobResult, error)) func(context.Context, *node, session.JobRun) (session.JobResult, error) {
+	return func(ctx context.Context, n *node, j session.JobRun) (session.JobResult, error) {
+		o.mu.Lock()
+		r := o.recv[n.id]
+		o.mu.Unlock()
+		s := seen{files: map[string]string{}}
+		src, err := r.Stage(ctx, j.Lease, j.Root.Dir)
+		if err != nil {
+			s.err = err
+			o.seen <- s
+			return session.JobResult{}, err
+		}
+		if out, e := exec.Command("git", "-C", src, "rev-parse", "HEAD").Output(); e == nil {
+			s.head = strings.TrimSpace(string(out))
+		}
+		for _, name := range o.probe {
+			if b, e := os.ReadFile(filepath.Join(src, name)); e == nil {
+				s.files[name] = string(b)
+			}
+		}
+		o.seen <- s
+		return body(ctx, j)
+	}
+}
+
+func (o *offloadNodes) wait(t *testing.T) seen {
+	t.Helper()
+	select {
+	case s := <-o.seen:
+		return s
+	case <-time.After(60 * time.Second):
+		t.Fatal("no node staged the checkout")
+	}
+	panic("unreachable")
+}
+
+// dirtyFixture is the foreground fixture plus a user's repository with uncommitted work.
+func dirtyFixture(t *testing.T, body func(context.Context, session.JobRun) (session.JobResult, error)) (*fixture, *offloadNodes) {
+	t.Helper()
+	probe := []string{"f.txt", "new.txt", ".env", ".env.local"}
+	f := newFixture(t, nil)
+	nodes := newOffloadNodes(f, probe...)
+	for _, n := range f.nodes {
+		n.runner = nodes.runner(body)
+	}
+	write := func(name, content string) {
+		if err := os.WriteFile(filepath.Join(f.repo, name), []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write(".gitignore", ".env\nignored.txt\n")
+	gitIn(t, f.repo, "add", ".gitignore")
+	gitIn(t, f.repo, "commit", "-q", "-m", "ignore")
+	f.sha = gitIn(t, f.repo, "rev-parse", "HEAD")
+	write("f.txt", "edited on the laptop\n")
+	write("new.txt", "untracked and not ignored\n")
+	write(".env", secretEnv+"\n")
+	write(".env.local", secretLocal+"\n")
+	write("ignored.txt", "ignored\n")
+	return f, nodes
+}
+
+// repoState is everything about the user's repository an offload must leave alone.
+func repoState(t *testing.T, repo string) string {
+	t.Helper()
+	parts := []string{
+		gitIn(t, repo, "status", "--porcelain=v2", "--ignored"),
+		gitIn(t, repo, "for-each-ref"),
+		gitIn(t, repo, "ls-files", "-s"),
+		gitIn(t, repo, "rev-parse", "HEAD"),
+	}
+	for _, name := range []string{"f.txt", "new.txt", ".env", ".env.local", "ignored.txt", ".gitignore"} {
+		b, err := os.ReadFile(filepath.Join(repo, name))
+		if err != nil {
+			t.Fatal(err)
+		}
+		parts = append(parts, name+"="+string(b))
+	}
+	return strings.Join(parts, "\n--\n")
+}
+
+// startDirty begins a dev run of one remote-only job with the snapshot offload hook installed.
+// Status is not disabled by option: a snapshot run is unbound, so it is never a status of record.
+func (f *fixture) startDirty(ctx context.Context, job model.Job) (<-chan run.Result, *bytes.Buffer, *[]string) {
+	f.t.Helper()
+	pl, err := plan.Build(plan.Input{Config: model.PipelineConfig{Version: 1, Jobs: map[string]model.Job{"unit": job}},
+		World: plan.World{Platform: runtime.GOOS + "/" + runtime.GOARCH, CPU: 8, MemMB: 16384}})
+	if err != nil {
+		f.t.Fatal(err)
+	}
+	var excluded []string
+	hook := run.SnapshotOffload{
+		Build: func(ctx context.Context, root string) (*run.OffloadSnapshot, error) {
+			s, err := offload.Take(ctx, realGit, root, f.t.TempDir(), "sim1")
+			if err != nil {
+				return nil, err
+			}
+			return &run.OffloadSnapshot{SHA: s.SHA, Excluded: s.Excluded, Release: func(ctx context.Context) error { return offload.Release(ctx, realGit, root, s) }}, nil
+		},
+		Excluded: func(names []string) { excluded = append(excluded, names...) },
+	}
+	out := &bytes.Buffer{}
+	c := &run.Coordinator{Opts: run.Options{Root: f.repo, Home: f.home}, Plan: pl, ConfigDigest: "cfg", Out: out, Capture: realGit, Reporter: noReport{},
+		Hooks: run.Hooks{Auto: run.AutoHooks{Offload: hook}},
+		Capacity: func() ciexec.Capacity {
+			return ciexec.Capacity{CPUs: 8, MemoryMB: 16384, FreeMemoryMB: 12000, BatteryPercent: -1, PluggedIn: true, Interactive: true}
+		}, Poll: 10 * time.Millisecond}
+	ch := make(chan run.Result, 1)
+	go func() {
+		res, err := c.Run(ctx)
+		if err != nil {
+			f.t.Errorf("Run: %v\n%s", err, out)
+		}
+		ch <- res
+	}()
+	return ch, out, &excluded
+}
+
+func passBody(_ context.Context, j session.JobRun) (session.JobResult, error) {
+	j.Output([]byte("tree checked\n"))
+	return session.JobResult{Outcome: session.Outcome{State: "passed"}, Evidence: evidence(j.Lease, "pass", "", nil)}, nil
+}
+
+// requireSnapshotTree checks what the node saw against the user's tree.
+func requireSnapshotTree(t *testing.T, f *fixture, s seen) {
+	t.Helper()
+	if s.err != nil {
+		t.Fatalf("the node could not stage the snapshot: %v", s.err)
+	}
+	if s.head == "" || s.head == f.sha {
+		t.Fatalf("node HEAD %q: want the snapshot commit, not the committed HEAD %s", s.head, f.sha)
+	}
+	if parent := gitIn(t, f.repo, "rev-parse", "--verify", "-q", s.head+"^"); parent != f.sha {
+		t.Fatalf("snapshot parent %s, want HEAD %s", parent, f.sha)
+	}
+	if s.files["f.txt"] != "edited on the laptop\n" {
+		t.Errorf("the node's f.txt = %q: the tracked change did not arrive", s.files["f.txt"])
+	}
+	if s.files["new.txt"] != "untracked and not ignored\n" {
+		t.Errorf("the node's new.txt = %q: the untracked file did not arrive", s.files["new.txt"])
+	}
+	for _, name := range []string{".env", ".env.local"} {
+		if c, ok := s.files[name]; ok {
+			t.Errorf("%s reached the node (%d bytes)", name, len(c))
+		}
+	}
+}
+
+func requirePrivateRefGone(t *testing.T, repo string) {
+	t.Helper()
+	if refs := gitIn(t, repo, "for-each-ref", "refs/nself-ci/"); refs != "" {
+		t.Errorf("private refs left behind:\n%s", refs)
+	}
+}
+
+func TestOffloadDirtyTreeToNode(t *testing.T) {
+	f, nodes := dirtyFixture(t, passBody)
+	before := repoState(t, f.repo)
+	ch, out, excluded := f.startDirty(context.Background(), remoteJob(1))
+	staged := nodes.wait(t)
+	res := wait(t, ch, "the run")
+	if res.Exit != 0 || res.Summary.Result != "pass" {
+		t.Fatalf("exit %d result %s\n%s", res.Exit, res.Summary.Result, out)
+	}
+	requireSnapshotTree(t, f, staged)
+	if len(*excluded) != 1 || (*excluded)[0] != ".env.local" {
+		t.Errorf("excluded = %v, want only the untracked .env.local (the ignored .env is never listed)", *excluded)
+	}
+	for _, s := range []string{secretEnv, secretLocal} {
+		if strings.Contains(out.String(), s) || strings.Contains(res.Summary.Status, s) {
+			t.Errorf("secret content %q reached the report", s)
+		}
+	}
+	// a snapshot run is a dev run: unbound evidence, no status of record
+	if d := res.Summary.Doc; d.WorktreeState != "dirty" || d.Binding.State != "unbound" {
+		t.Errorf("evidence worktree %q binding %q, want dirty and unbound", d.WorktreeState, d.Binding.State)
+	}
+	if after := repoState(t, f.repo); after != before {
+		t.Errorf("the user's repository changed:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+	requirePrivateRefGone(t, f.repo)
+}
+
+func TestOffloadCancelCleansRef(t *testing.T) {
+	staged := make(chan struct{})
+	body := func(ctx context.Context, j session.JobRun) (session.JobResult, error) {
+		close(staged)
+		j.Output([]byte("working\n"))
+		<-ctx.Done() // the agent kills the job when the lease is cancelled
+		return session.JobResult{Outcome: session.Outcome{State: "cancelled"}, Evidence: evidence(j.Lease, "cancelled", "", nil)}, nil
+	}
+	f, nodes := dirtyFixture(t, body)
+	ssh.Default.Heartbeat = 50 * time.Second // the agent beats rarely, so only the carrier cancel can stop the job
+	t.Cleanup(run.SetRemoteCancelWait(10 * time.Minute))
+	before := repoState(t, f.repo)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	ch, out, _ := f.startDirty(ctx, remoteJob(1))
+	requireSnapshotTree(t, f, nodes.wait(t))
+	select {
+	case <-staged:
+	case <-time.After(30 * time.Second):
+		t.Fatal("the job never started on a node")
+	}
+	if refs := gitIn(t, f.repo, "for-each-ref", "refs/nself-ci/offload/"); refs == "" {
+		t.Error("the snapshot ref does not exist while the job runs")
+	}
+	cancel() // Ctrl-C
+	var res run.Result
+	select {
+	case res = <-ch:
+	case <-time.After(30 * time.Second):
+		t.Fatalf("the cancelled run did not end in 30 s\n%s", out)
+	}
+	if res.Summary.Result != "cancelled" {
+		t.Fatalf("result %q, want cancelled\n%s", res.Summary.Result, out)
+	}
+	requirePrivateRefGone(t, f.repo)
+	if after := repoState(t, f.repo); after != before {
+		t.Errorf("the user's repository changed after a cancel:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+}
+
+func TestOffloadFailingJobReturnsTail(t *testing.T) {
+	body := func(_ context.Context, j session.JobRun) (session.JobResult, error) {
+		three := 3
+		j.Output([]byte("FAIL: TestSomething\nboom on the node\n"))
+		return session.JobResult{Outcome: session.Outcome{State: "failed", ExitCode: 3}, Evidence: evidence(j.Lease, "fail", "code", &three)}, nil
+	}
+	f, nodes := dirtyFixture(t, body)
+	before := repoState(t, f.repo)
+	ch, out, _ := f.startDirty(context.Background(), remoteJob(0))
+	requireSnapshotTree(t, f, nodes.wait(t))
+	res := wait(t, ch, "the run")
+	jo := res.Summary.Jobs[0]
+	if res.Exit == 0 || jo.State != "failed" || jo.ExitCode != 3 {
+		t.Fatalf("a failing dev job: exit %d outcome %+v\n%s", res.Exit, jo, out)
+	}
+	if !strings.Contains(jo.Tail, "boom on the node") {
+		t.Errorf("the log tail did not come back: %q", jo.Tail)
+	}
+	if res.Summary.Doc.Binding.State != "unbound" {
+		t.Errorf("binding %q: a failing snapshot run is a dev run", res.Summary.Doc.Binding.State)
+	}
+	requirePrivateRefGone(t, f.repo)
+	if after := repoState(t, f.repo); after != before {
+		t.Errorf("the user's repository changed after a failed job:\n--- before\n%s\n--- after\n%s", before, after)
+	}
+}
diff --git a/free/ci/test/sim/perf-budget.json b/free/ci/test/sim/perf-budget.json
new file mode 100644
index 000000000..2ca92bbef
--- /dev/null
+++ b/free/ci/test/sim/perf-budget.json
@@ -0,0 +1,8 @@
+{
+  "_note": "Absolute p95 ceiling in ms for store.write_p99_ms (the p99 of the intake write in each 10 s window of the 10 minute write-load leg): the measured p95 of those windows, 138.301 ms on mm4 (darwin/arm64, shared host, load average about 30), times 1.5 (P7-NODE-17). One baseline run only; the Linux baseline from the hosted ci-node-scenarios run is still to be added, and node.dispatch_ms has no ceiling because scenario 2 was not measured. Evidence: hq plan/p7/evidence/NODE-perf.md.",
+  "schema": "perfbench-budget/v1",
+  "platform": "darwin/arm64",
+  "p95_ms": {
+    "store.write_p99_ms": 208
+  }
+}
diff --git a/free/ci/test/sim/perf_test.go b/free/ci/test/sim/perf_test.go
new file mode 100644
index 000000000..934bd5c21
--- /dev/null
+++ b/free/ci/test/sim/perf_test.go
@@ -0,0 +1,152 @@
+//go:build integration
+
+package sim
+
+// Purpose: the perfbench/v1 document of the node scenario legs (P7-NODE-17): every measured leg adds
+// named samples, and TestMain writes one document after the run when -perf-json is set.
+// Inputs:  -perf-json <path>; samples from TestScenario2, TestScenario3 and TestWriteLoad.
+// Outputs: one JSON file with the command, revision and environment of the run and one entry per
+//          metric (count, min, p50, p95, p99, max, mean).
+// Constraints: nothing is written when no leg measured anything; the numbers are only ever measured,
+//          never defaulted, so a leg that did not run leaves its metric out and `perfbench check`
+//          reports it missing.
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+var (
+	perfJSON     = flag.String("perf-json", "", "write the perfbench/v1 measurements of the node scenario legs to this file")
+	writeLoadFor = flag.Duration("write-load-for", 10*time.Minute, "how long TestWriteLoad holds the load (the acceptance leg is 10m)")
+)
+
+// metric is one perfbench/v1 entry.
+type metric struct {
+	Name    string  `json:"name"`
+	Unit    string  `json:"unit"`
+	N       int     `json:"n"`
+	Leg     string  `json:"leg"`
+	Count   int     `json:"count"`
+	Min     float64 `json:"min"`
+	P50     float64 `json:"p50"`
+	P95     float64 `json:"p95"`
+	P99     float64 `json:"p99"`
+	Max     float64 `json:"max"`
+	Mean    float64 `json:"mean"`
+	Context string  `json:"context,omitempty"`
+}
+
+var perf struct {
+	mu      sync.Mutex
+	metrics []metric
+}
+
+// recordPerf adds the samples of one metric; an empty sample set records nothing.
+func recordPerf(leg, name, unit, context string, samples []float64) {
+	if len(samples) == 0 {
+		return
+	}
+	s := append([]float64(nil), samples...)
+	sort.Float64s(s)
+	sum := 0.0
+	for _, v := range s {
+		sum += v
+	}
+	m := metric{Name: name, Unit: unit, N: len(s), Leg: leg, Count: len(s), Min: s[0], P50: quantile(s, 0.50), P95: quantile(s, 0.95),
+		P99: quantile(s, 0.99), Max: s[len(s)-1], Mean: sum / float64(len(s)), Context: context}
+	perf.mu.Lock()
+	perf.metrics = append(perf.metrics, m)
+	perf.mu.Unlock()
+}
+
+// quantile is the nearest-rank quantile of sorted samples.
+func quantile(sorted []float64, q float64) float64 {
+	if len(sorted) == 0 {
+		return 0
+	}
+	i := int(q*float64(len(sorted))+0.999999) - 1
+	if i < 0 {
+		i = 0
+	}
+	if i >= len(sorted) {
+		i = len(sorted) - 1
+	}
+	return sorted[i]
+}
+
+func ms(d time.Duration) float64 { return float64(d.Microseconds()) / 1000 }
+
+// environment names where the numbers were measured.
+func environment() map[string]any {
+	env := map[string]any{"goos": runtime.GOOS, "goarch": runtime.GOARCH, "cpus": runtime.NumCPU(), "go": runtime.Version()}
+	if b, err := os.ReadFile("/proc/sys/kernel/osrelease"); err == nil {
+		env["kernel"] = strings.TrimSpace(string(b))
+	}
+	for k, v := range map[string]string{"runner_os": "RUNNER_OS", "runner_image": "ImageOS", "runner_image_version": "ImageVersion",
+		"github_run_id": "GITHUB_RUN_ID", "github_run_attempt": "GITHUB_RUN_ATTEMPT", "github_repository": "GITHUB_REPOSITORY"} {
+		if s := os.Getenv(v); s != "" {
+			env[k] = s
+		}
+	}
+	env["hosted"] = os.Getenv("GITHUB_ACTIONS") == "true"
+	return env
+}
+
+// revision is the commit of the checkout the legs ran from.
+func revision() string {
+	out, err := exec.Command("git", "rev-parse", "HEAD").Output()
+	if err != nil {
+		return "unknown"
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func writePerf(path string) error {
+	perf.mu.Lock()
+	defer perf.mu.Unlock()
+	if len(perf.metrics) == 0 {
+		return nil
+	}
+	sort.SliceStable(perf.metrics, func(i, j int) bool { return perf.metrics[i].Name < perf.metrics[j].Name })
+	doc := map[string]any{"schema": "perfbench/v1", "scenario": "node-scenarios", "sha": revision(), "goos": runtime.GOOS, "goarch": runtime.GOARCH,
+		"runs": 1, "injected": false, "suite": "plugins/free/ci/test/sim", "command": strings.Join(os.Args, " "),
+		"revision": revision(), "measured_at": time.Now().UTC().Format(time.RFC3339), "environment": environment(), "metrics": perf.metrics}
+	b, err := json.MarshalIndent(doc, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, append(b, '\n'), 0o600)
+}
+
+func TestMain(m *testing.M) {
+	flag.Parse()
+	code := m.Run()
+	if *perfJSON != "" {
+		if err := writePerf(*perfJSON); err != nil {
+			fmt.Fprintf(os.Stderr, "perf-json: %v\n", err)
+			if code == 0 {
+				code = 1
+			}
+		}
+	}
+	os.Exit(code)
+}
+
+// integration fails the leg unless INTEGRATION=1, the opt-in every Docker and load leg of the plugins
+// repo uses (simharness skips on its own; the load leg has no Docker, so it asks here).
+func integration(t *testing.T) {
+	t.Helper()
+	if os.Getenv("INTEGRATION") != "1" {
+		t.Skip("set INTEGRATION=1 to run the node scenario legs")
+	}
+}
diff --git a/free/ci/test/sim/race_test.go b/free/ci/test/sim/race_test.go
new file mode 100644
index 000000000..d016b0a9f
--- /dev/null
+++ b/free/ci/test/sim/race_test.go
@@ -0,0 +1,143 @@
+package sim
+
+// Purpose: P7-AUTO-14 Sim A7: two eligible nodes race one job; the faster
+// one finishes, its result stands, the slower one is cancelled (its remote
+// process group is gone), and exactly one result is recorded and posted.
+// Inputs:  a placement world of two owned LAN nodes and a paid one; each
+// node runs the job in a simulated process group that ends after a fixed
+// virtual duration.
+// Outputs: pass or fail.
+// Constraints: pure Go, no processes, no network, no sleeps: a virtual clock
+// ends the shortest live process group once every sibling is admitted.
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/race"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// raceNode is a remote node; pgroup is the process group of the sibling it runs.
+type raceNode struct {
+	takes  time.Duration
+	pgroup bool
+	end    chan race.Result
+}
+
+type raceCluster struct {
+	mu       sync.Mutex
+	nodes    map[string]*raceNode
+	want     int
+	admitted []race.Sibling
+	recorded []race.Evidence // the run store's result rows for the job
+	posted   []race.Evidence // statuses posted for the commit
+	now      time.Duration
+}
+
+func (c *raceCluster) Create(_ context.Context, n int, runner string) (race.Sibling, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	node := c.nodes[runner]
+	node.pgroup = true
+	s := race.Sibling{N: n, AttemptID: fmt.Sprintf("job.a%d", n), LeaseID: "lease-" + runner, RunnerID: runner, Epoch: 1}
+	c.admitted = append(c.admitted, s)
+	if len(c.admitted) == c.want {
+		c.advance()
+	}
+	return s, nil
+}
+
+// advance moves the virtual clock to the end of the shortest live process group.
+func (c *raceCluster) advance() {
+	var next *raceNode
+	for _, n := range c.nodes {
+		if n.pgroup && (next == nil || n.takes < next.takes) {
+			next = n
+		}
+	}
+	if next != nil {
+		c.now = next.takes
+		next.pgroup = false
+		next.end <- race.Result{State: race.StatePassed}
+	}
+}
+
+func (c *raceCluster) Wait(_ context.Context, s race.Sibling) race.Result {
+	return <-c.nodes[s.RunnerID].end
+}
+
+// Cancel is the lease cancel: the node kills the sibling's process group.
+func (c *raceCluster) Cancel(_ context.Context, s race.Sibling, _ string) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	n := c.nodes[s.RunnerID]
+	if !n.pgroup || s.Epoch != 1 {
+		return nil // already ended, or a stale epoch: idempotent
+	}
+	n.pgroup = false
+	n.end <- race.Result{State: race.StateCancelled, FailureClass: race.StateCancelled}
+	return nil
+}
+
+func (c *raceCluster) Post(_ context.Context, e race.Evidence) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.recorded = append(c.recorded, e)
+	c.posted = append(c.posted, e)
+	return nil
+}
+
+func raceRunner(id, class string) sched.Runner {
+	loc, os, arch := "lan", "linux", "amd64"
+	cpu, mem := float64(8), int64(8192)
+	c := model.Capability{Schema: "ci.runner-capability/v1"}
+	c.Lifecycle.AuthorizedProjects, c.Lifecycle.Eligible = []string{"p"}, true
+	c.Protocol.Versions, c.Protocol.Min = []int{1}, 1
+	c.Platform.OS.Value, c.Platform.Arch.Value = &os, &arch
+	c.Resources.CPU.Value, c.Resources.MemMB.Value = &cpu, &mem
+	c.Location.Kind.Value = &loc
+	return sched.Runner{ID: id, Location: loc, Class: class, Provider: "operator", Avail: sched.Avail{Slots: 2, CPU: 16, MemMB: 16384}, Capability: c,
+		Decl: trust.Declaration{Accepts: []model.TrustClass{"owner"}, Isolation: "vm", Network: "privileged", UIDSeparation: true, Ownership: "operator", NoLANRoute: true}}
+}
+
+func TestRaceCancelsLoserProcessGroup(t *testing.T) {
+	w := sched.World{Runners: []sched.Runner{raceRunner("fast", "owned"), raceRunner("slow", "owned"), raceRunner("rented", "paid")},
+		Policy: sched.Policy{Preset: "balanced", PaidEnabled: true}, Costs: map[string]sched.Cost{}, Previous: map[string]string{}}
+	j := sched.Job{Key: "job", ID: "job", Project: "p", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/amd64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/amd64", CPU: 1, MemMB: 128}, Trust: "owner", Network: "lan", TimeoutMs: 60000}
+	choice := race.Select(w, j, race.DefaultWidth, false)
+	if !choice.Raceable() || len(choice.Runners) != 2 || choice.Excluded["rented"] != race.ReasonSpend {
+		t.Fatalf("choice = %+v", choice)
+	}
+	c := &raceCluster{want: 2, nodes: map[string]*raceNode{
+		"fast": {takes: 40 * time.Second, end: make(chan race.Result, 1)},
+		"slow": {takes: 90 * time.Second, end: make(chan race.Result, 1)},
+	}}
+	ev, err := race.Run(context.Background(), race.Spec{Job: "job", Choice: choice, First: 1}, c, c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ev.Winner == nil || ev.Winner.RunnerID != "fast" || ev.Result.State != race.StatePassed || c.now != 40*time.Second {
+		t.Fatalf("winner = %+v result = %+v at %v", ev.Winner, ev.Result, c.now)
+	}
+	if c.nodes["slow"].pgroup || c.nodes["fast"].pgroup {
+		t.Fatal("a process group outlived the race")
+	}
+	cancelled := ev.CancelledSiblings()
+	if len(cancelled) != 1 || ev.Losers[0].RunnerID != "slow" {
+		t.Fatalf("cancelled = %v losers = %+v", cancelled, ev.Losers)
+	}
+	if len(c.recorded) != 1 || len(c.posted) != 1 {
+		t.Fatalf("recorded %d, posted %d: want exactly one of each", len(c.recorded), len(c.posted))
+	}
+	// a repeat cancel after the race is a no-op (idempotent, epoch fenced)
+	if err = c.Cancel(context.Background(), ev.Losers[0].Sibling, "again"); err != nil || len(c.nodes["slow"].end) != 0 {
+		t.Fatal("a repeated cancel had an effect")
+	}
+}
diff --git a/free/ci/test/sim/scope_test.go b/free/ci/test/sim/scope_test.go
new file mode 100644
index 000000000..61b4f7452
--- /dev/null
+++ b/free/ci/test/sim/scope_test.go
@@ -0,0 +1,174 @@
+package sim
+
+// Purpose: A10 scoped placement and private project authorization fixtures.
+// Inputs: personal and team pools, the real node project editor and dispatcher.
+// Outputs: placement, delivery and authorization assertions without external services.
+// Constraints: no sleeps, fixed ports or credentials.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/agent/session"
+	"github.com/nself-org/plugins/free/ci/internal/coordclient"
+	ciexec "github.com/nself-org/plugins/free/ci/internal/exec"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/labels"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/plan"
+	"github.com/nself-org/plugins/free/ci/internal/pools"
+	"github.com/nself-org/plugins/free/ci/internal/pools/record"
+	"github.com/nself-org/plugins/free/ci/internal/run"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/where"
+)
+
+func TestScopePersonalVsTeamPool(t *testing.T) {
+	runners := []pools.Runner{
+		{ID: "vps", Source: pools.SourceRegistry, Assigned: []string{"pool.mine"}, Projects: []string{"private"}},
+		{ID: "team-node", Source: pools.SourceCoordinator, Assigned: []string{"pool.team"}, Projects: []string{"private"}},
+	}
+	rec := pools.List{Set: true, IDs: []string{"team"}}
+	excluded := record.Excluded(rec, runners)
+	if excluded["vps"][0].Detail != record.Reason || len(excluded["team-node"]) != 0 {
+		t.Fatalf("commit CI pool rule: %v", excluded)
+	}
+	for _, tc := range []struct {
+		dev  []string
+		want bool
+	}{{[]string{"team"}, false}, {[]string{"mine", "team"}, true}} {
+		in := pools.Input{Runners: runners, Project: "private", Dev: true, DevPools: pools.List{Set: true, IDs: tc.dev}}
+		got := pools.Resolve(in)
+		if slices.Contains(got.Eligible, "vps") != tc.want {
+			t.Fatalf("dev pools %v: %+v", tc.dev, got)
+		}
+		if !tc.want && got.Excluded["vps"][0].Detail != pools.DetailDevNotAllowed {
+			t.Fatal(got.Excluded)
+		}
+	}
+}
+
+func scopeStore(t *testing.T, f *fixture) *store.Store {
+	t.Helper()
+	st, err := store.Open(filepath.Join(f.home, "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	return st
+}
+
+func scopePolicy(t *testing.T, st *store.Store, key, raw string) {
+	t.Helper()
+	err := st.ApplyWrite(context.Background(), store.PolicyWrite{Op: store.PolicySet, Scope: "user", Subject: "local", Key: key, Value: json.RawMessage(raw), Actor: "test"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func scopeRun(t *testing.T, f *fixture, rec bool) run.Result {
+	t.Helper()
+	pl, err := plan.Build(plan.Input{Config: model.PipelineConfig{Version: 1, Jobs: map[string]model.Job{"unit": remoteJob(0)}},
+		World: plan.World{Platform: runtime.GOOS + "/" + runtime.GOARCH, CPU: 8, MemMB: 16384}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := &bytes.Buffer{}
+	c := &run.Coordinator{Opts: run.Options{Root: f.repo, Home: f.home, NoStatus: true, Record: rec}, Plan: pl, ConfigDigest: "cfg", Out: out, Capture: f.git,
+		Capacity: func() ciexec.Capacity {
+			return ciexec.Capacity{CPUs: 8, MemoryMB: 16384, FreeMemoryMB: 12000, BatteryPercent: -1, PluggedIn: true, Interactive: true}
+		}}
+	res, err := c.Run(context.Background())
+	if err != nil {
+		t.Fatalf("run: %v %s", err, out)
+	}
+	return res
+}
+
+func TestRecordPoolTransportExclusion(t *testing.T) {
+	r := passRunner("scope")
+	f := newFixture(t, map[string]func(context.Context, *node, session.JobRun) (session.JobResult, error){"n1": r, "n2": r})
+	st := scopeStore(t, f)
+	for id, pool := range map[string]string{"n1": "mine", "n2": "team"} {
+		if err := st.NodeLabelsReplace(context.Background(), id, []store.NodeLabel{{Key: "pool." + pool}}, "test"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	scopePolicy(t, st, record.Key, `["team"]`)
+	res := scopeRun(t, f, true)
+	if res.Exit != 0 {
+		t.Fatalf("record run failed: %+v", res.Summary)
+	}
+	if len(f.nodes[0].ran()) != 0 || f.nodes[0].sessions.Load() != 0 || len(f.nodes[1].ran()) != 1 {
+		t.Fatal("a non-record runner received a checkout or lease")
+	}
+	attempts, err := st.PipelineAttempts(context.Background(), res.RunID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, a := range attempts {
+		facts, ok, err := (store.AttestLedger{S: st}).AttemptFacts(context.Background(), a.ID)
+		if err != nil || !ok || facts.RunnerID != "n2" {
+			t.Fatalf("lease holder %q %v %v", facts.RunnerID, ok, err)
+		}
+	}
+	scopePolicy(t, st, pools.KeyDev, `["mine"]`)
+	if res := scopeRun(t, f, false); res.Exit != 0 || len(f.nodes[0].ran()) != 1 {
+		t.Fatalf("dev run could not use the allowed personal VPS: %+v", res.Summary)
+	}
+	scopePolicy(t, st, pools.KeyDev, `["team"]`)
+	if res := scopeRun(t, f, false); res.Exit != 0 || len(f.nodes[0].ran()) != 1 || len(f.nodes[1].ran()) != 2 {
+		t.Fatalf("dev run ignored pools.dev: %+v", res.Summary)
+	}
+}
+
+func TestPersonalNodePrivateRepoOptIn(t *testing.T) {
+	r := passRunner("private")
+	f := newFixture(t, map[string]func(context.Context, *node, session.JobRun) (session.JobResult, error){"n1": r, "n2": r})
+	st := scopeStore(t, f)
+	reg := registry.New(st)
+	if _, err := reg.Deauthorize(context.Background(), "n1", f.repo, "test"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := reg.Deauthorize(context.Background(), "n2", f.repo, "test"); err != nil {
+		t.Fatal(err)
+	}
+	res := scopeRun(t, f, false)
+	if res.Exit == 0 || len(f.nodes[0].ran()) != 0 || f.nodes[0].sessions.Load() != 0 {
+		t.Fatal("unauthorized personal node received private source")
+	}
+	// This is the same editor `nodes projects add` calls, with a directory resolver.
+	editor := labels.Env{Store: st, Registry: reg, Actor: "test", ResolveDir: func(context.Context, string) (string, bool) { return f.repo, true }}
+	if _, err := editor.AddProjects(context.Background(), "n1", []string{f.repo}, false); err != nil {
+		t.Fatal(err)
+	}
+	res = scopeRun(t, f, false)
+	if res.Exit != 0 || len(f.nodes[0].ran()) != 1 {
+		t.Fatalf("authorized personal node ineligible: %+v", res.Summary)
+	}
+}
+
+func TestTeamPoolViaCoordinator(t *testing.T) {
+	r := &coordclient.Resolver{Inputs: func() coordclient.Inputs {
+		return coordclient.Inputs{Flag: "https://team.example.invalid", Home: t.TempDir(), Getenv: func(string) string { return "" }}
+	}, Warn: io.Discard}
+	target, err := r.Target()
+	if err != nil || target.Kind != coordclient.Remote || !r.Active() {
+		t.Fatalf("TEAM target was not remote: %v %v", target, err)
+	}
+	targetPool, err := where.Values("team", where.Known{Pools: []string{"mine", "team"}, Effective: []string{"team"}}, where.Opts{})
+	if err != nil || targetPool.Kind != where.KindPool || string(targetPool.Values[pools.KeyAllow]) != `["team"]` {
+		t.Fatalf("team pool was not selected: %+v %v", targetPool, err)
+	}
+	// An unreachable/unconfigured coordinator must remain authoritative, never fall back locally.
+	_, _, active, err := r.Client()
+	if err == nil || !active {
+		t.Fatal("remote target fell back to the personal engine")
+	}
+}
diff --git a/free/ci/test/sim/status_dead_node_test.go b/free/ci/test/sim/status_dead_node_test.go
new file mode 100644
index 000000000..474ce3006
--- /dev/null
+++ b/free/ci/test/sim/status_dead_node_test.go
@@ -0,0 +1,96 @@
+package sim
+
+// Purpose: P7-AUTO-19 acceptance A9: with one paused (dead) node among four, a fleet status pass
+// returns in under 15 s with that node unreachable and the other three complete.
+// Inputs:  a state.db in t.TempDir() with four registered nodes; a reader whose dead node never
+//          answers and ignores its context (a paused host). Outputs: pass or fail.
+// Constraints: pure Go, no processes, no network. The dead node's 8 s cap is an injected timer that
+//          fires when its reader starts, so the test proves the pass stops waiting at the cap without
+//          sleeping through it.
+
+import (
+	"context"
+	"encoding/json"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/demand"
+	"github.com/nself-org/plugins/free/ci/internal/fleet"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/probe"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+func TestStatusOneDeadNodeUnder15s(t *testing.T) {
+	st := openSimStore(t)
+	for _, id := range []string{"n1", "n2", "n3", "paused"} {
+		whereNode(t, st, id)
+	}
+	at := time.Date(2026, 10, 27, 12, 0, 10, 0, time.UTC)
+	stamp := at.Add(-10 * time.Second).Format(time.RFC3339)
+	live, err := json.Marshal(demand.Document{TS: stamp, Host: "h", Queued: 1, Running: 1, Ready: true, ReadyWhy: []string{},
+		Watcher: demand.Watcher{Alive: true, LastPass: stamp, IntervalSec: 30}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	paused := make(chan struct{})
+	t.Cleanup(func() { close(paused) })
+	expired := make(chan time.Time)
+	var once sync.Once
+	var mu sync.Mutex
+	caps := map[string]time.Duration{}
+	timer := func(id string, d time.Duration) <-chan time.Time {
+		mu.Lock()
+		defer mu.Unlock()
+		caps[id] = d
+		if id == "paused" {
+			return expired
+		}
+		return nil
+	}
+	read := func(ctx context.Context, n registry.Node) (probe.StatusDocs, error) {
+		if n.Record.ID == "paused" {
+			once.Do(func() { close(expired) }) // the cap passes while the host stays silent
+			<-paused
+			return probe.StatusDocs{}, ctx.Err()
+		}
+		return probe.StatusDocs{Demand: live}, nil
+	}
+	start := time.Now()
+	rep, err := fleet.Gather(context.Background(), st, read, fleet.Options{Timer: timer, Now: func() time.Time { return at }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if took := time.Since(start); took >= 15*time.Second {
+		t.Fatalf("status pass took %s, want < 15s", took)
+	}
+	if len(rep.Nodes) != 4 || rep.Unreachable != 1 {
+		t.Fatalf("report = %+v", rep)
+	}
+	for _, row := range rep.Nodes {
+		if caps[row.Node] != fleet.NodeCap {
+			t.Errorf("%s cap = %s, want %s", row.Node, caps[row.Node], fleet.NodeCap)
+		}
+		if row.Node == "paused" {
+			if row.Source != fleet.SourceUnreachable || row.Unreachable == "" {
+				t.Errorf("paused row = %+v", row)
+			}
+			continue
+		}
+		if row.Source != fleet.SourceLive || row.Watcher != fleet.WatcherAlive || row.Ready == nil || !*row.Ready || row.Queued == nil || *row.Queued != 1 {
+			t.Errorf("%s row incomplete: %+v", row.Node, row)
+		}
+	}
+}
+
+// openSimStore opens a fresh state database for one test.
+func openSimStore(t *testing.T) *store.Store {
+	t.Helper()
+	st, err := store.Open(t.TempDir()+"/state.db", store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	return st
+}
diff --git a/free/ci/test/sim/watch_test.go b/free/ci/test/sim/watch_test.go
new file mode 100644
index 000000000..9ccf9ac31
--- /dev/null
+++ b/free/ci/test/sim/watch_test.go
@@ -0,0 +1,237 @@
+package sim
+
+// Purpose: P7-AUTO-11 Sim A3: three `serve watch` hosts against one fixture repository (no app-pinned
+//          check) over an in-memory provider ledger: random pushes and partitions, then healing; a
+//          preferred host killed before and after it claims.
+// Inputs:  watch.Watcher with fake ports. Outputs: pass or fail.
+// Constraints: no sleeps, no ports; time is the provider clock the test advances; the generator is seeded
+//          and the seed is printed on failure.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math/rand/v2"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/claims"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/report"
+	"github.com/nself-org/plugins/free/ci/internal/watch"
+)
+
+var wT0 = time.Date(2026, 10, 28, 9, 0, 0, 0, time.UTC)
+
+const (
+	wStep     = time.Minute
+	wRunLimit = 30 * time.Minute
+)
+
+type wProv struct {
+	mu    sync.Mutex
+	now   time.Time
+	st    map[string][]report.LedgerStatus
+	down  map[string]bool
+	heads []watch.Head
+	runs  map[string]int // host -> attempts started
+}
+
+func newWProv() *wProv {
+	return &wProv{now: wT0, st: map[string][]report.LedgerStatus{}, down: map[string]bool{}, runs: map[string]int{}}
+}
+
+func (p *wProv) clock() time.Time { p.mu.Lock(); defer p.mu.Unlock(); return p.now }
+
+func (p *wProv) push(n int) string {
+	s := fmt.Sprintf("%040x", n+1)
+	p.mu.Lock()
+	p.heads = append(p.heads, watch.Head{SHA: s, Branch: fmt.Sprintf("b%d", n), Protected: true, Trust: model.TrustClass("owner")})
+	p.mu.Unlock()
+	return s
+}
+
+func (p *wProv) finals(s string) int {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	n := 0
+	for _, x := range p.st[s] {
+		if x.Context == report.Context && (x.State == report.Success || x.State == report.Failure) {
+			n++
+		}
+	}
+	return n
+}
+
+type wHost struct {
+	p  *wProv
+	id string
+}
+
+var errDown = errors.New("partition")
+
+func (h wHost) add(s report.Status) error {
+	h.p.mu.Lock()
+	defer h.p.mu.Unlock()
+	if h.p.down[h.id] {
+		return errDown
+	}
+	h.p.st[s.Revision] = append(h.p.st[s.Revision], report.LedgerStatus{Context: s.ContextName(), State: s.State, Creator: "station", Description: s.Description, CreatedAt: h.p.now})
+	return nil
+}
+
+func (h wHost) PostClaim(_ context.Context, s report.Status) (time.Time, error) {
+	return h.p.clock(), h.add(s)
+}
+
+func (h wHost) Post(_ context.Context, s report.Status) error { return h.add(s) }
+
+func (h wHost) ListStatuses(_ context.Context, _, _, s string) ([]report.LedgerStatus, time.Time, error) {
+	h.p.mu.Lock()
+	defer h.p.mu.Unlock()
+	if h.p.down[h.id] {
+		return nil, time.Time{}, errDown
+	}
+	return append([]report.LedgerStatus(nil), h.p.st[s]...), h.p.now, nil
+}
+
+func (h wHost) Scan(context.Context, string) (watch.Scan, error) {
+	h.p.mu.Lock()
+	defer h.p.mu.Unlock()
+	if h.p.down[h.id] {
+		return watch.Scan{}, errDown
+	}
+	return watch.Scan{Heads: append([]watch.Head(nil), h.p.heads...)}, nil
+}
+
+// wRunner runs instantly; kill, when set, is called on entry (the host dies after it claimed).
+type wRunner struct {
+	h    wHost
+	kill func()
+}
+
+func (r *wRunner) Run(context.Context, watch.Job) (watch.Outcome, error) {
+	r.h.p.mu.Lock()
+	r.h.p.runs[r.h.id]++
+	r.h.p.mu.Unlock()
+	if r.kill != nil {
+		r.kill()
+	}
+	return watch.Outcome{State: report.Success, Description: "ok"}, nil
+}
+
+func newWatchHost(t *testing.T, p *wProv, id string) (*watch.Watcher, *wRunner) {
+	t.Helper()
+	h := wHost{p: p, id: id}
+	run := &wRunner{h: h}
+	c := watch.Defaults()
+	c.Repos, c.Host, c.Hosts, c.Trusted, c.Step, c.RunLimit = []string{"o/r"}, id, []string{"a", "b", "c"}, []string{"station"}, wStep, wRunLimit
+	w, err := watch.New(c, watch.Ports{Scanner: h, Ledger: h, Reporter: h, Runner: run, Now: p.clock,
+		Ready:         func(context.Context) (bool, []string) { return true, nil },
+		ResultContext: func(context.Context, string, string, string) string { return report.Context }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return w, run
+}
+
+func TestWatchThreeHostsExactlyOneStatus(t *testing.T) {
+	seed := uint64(time.Now().UnixNano())
+	rng := rand.New(rand.NewPCG(seed, 11))
+	p := newWProv()
+	ws := map[string]*watch.Watcher{}
+	for _, id := range []string{"a", "b", "c"} {
+		ws[id], _ = newWatchHost(t, p, id)
+	}
+	var pushed []string
+	dups := 0
+	pass := func() {
+		for _, id := range []string{"a", "b", "c"} {
+			dups += ws[id].Pass(context.Background()).Duplicates
+		}
+		p.mu.Lock()
+		p.now = p.now.Add(30 * time.Second)
+		p.mu.Unlock()
+	}
+	for i := 0; i < 120; i++ { // pushes and partitions
+		if rng.IntN(6) == 0 {
+			pushed = append(pushed, p.push(len(pushed)))
+		}
+		if rng.IntN(5) == 0 {
+			p.mu.Lock()
+			id := []string{"a", "b", "c"}[rng.IntN(3)]
+			p.down[id] = !p.down[id]
+			p.mu.Unlock()
+		}
+		pass()
+	}
+	p.mu.Lock()
+	p.down = map[string]bool{} // the partitions heal
+	p.mu.Unlock()
+	for i := 0; i < 200; i++ {
+		pass()
+	}
+	total := 0
+	for _, s := range pushed {
+		n := p.finals(s)
+		if n == 0 {
+			t.Fatalf("seed %d: commit %s has no final result", seed, s[:12])
+		}
+		total += n - 1
+	}
+	if total != dups {
+		t.Fatalf("seed %d: %d duplicate finals, %d reported", seed, total, dups)
+	}
+	if len(pushed) == 0 {
+		t.Logf("seed %d pushed nothing", seed)
+	}
+}
+
+func TestWatchKillPreferredTakeover(t *testing.T) {
+	// killed before it claims: b starts after step_sec, c sees the final
+	p := newWProv()
+	s := p.push(0)
+	wb, _ := newWatchHost(t, p, "b")
+	wc, _ := newWatchHost(t, p, "c")
+	start := p.clock()
+	for p.finals(s) == 0 && p.clock().Sub(start) < 10*time.Minute {
+		wb.Pass(context.Background())
+		wc.Pass(context.Background())
+		p.mu.Lock()
+		p.now = p.now.Add(10 * time.Second)
+		p.mu.Unlock()
+	}
+	if p.finals(s) != 1 || p.runs["b"] != 1 || p.runs["c"] != 0 {
+		t.Fatalf("finals %d, runs %v", p.finals(s), p.runs)
+	}
+	if took := p.st[s][0].CreatedAt.Sub(start); took < wStep {
+		t.Fatalf("b claimed after %v, before step %v", took, wStep)
+	}
+
+	// killed after it claimed: nobody finishes until the claim is dead
+	p = newWProv()
+	s = p.push(0)
+	wa, ra := newWatchHost(t, p, "a")
+	ra.kill = func() { p.mu.Lock(); p.down["a"] = true; p.mu.Unlock() }
+	wa.Pass(context.Background())
+	if p.finals(s) != 0 || p.runs["a"] != 1 {
+		t.Fatalf("a died after its claim: finals %d", p.finals(s))
+	}
+	wb, _ = newWatchHost(t, p, "b")
+	wc, _ = newWatchHost(t, p, "c")
+	dead := wT0.Add(wRunLimit + claims.DeadGrace)
+	for p.clock().Before(dead.Add(5 * time.Minute)) {
+		if p.clock().Before(dead) && p.finals(s) != 0 {
+			t.Fatalf("a final at %v while a's claim was live", p.clock().Sub(wT0))
+		}
+		wb.Pass(context.Background())
+		wc.Pass(context.Background())
+		p.mu.Lock()
+		p.now = p.now.Add(time.Minute)
+		p.mu.Unlock()
+	}
+	if p.finals(s) != 1 {
+		t.Fatalf("after the claim died: finals %d, runs %v", p.finals(s), p.runs)
+	}
+}
diff --git a/free/ci/test/sim/where_test.go b/free/ci/test/sim/where_test.go
new file mode 100644
index 000000000..7f2df70f2
--- /dev/null
+++ b/free/ci/test/sim/where_test.go
@@ -0,0 +1,151 @@
+package sim
+
+// Purpose: P7-AUTO-06 proof: `--where <node>` places on that node, `--where
+// local` never on a registered node, `--where hosted` with no provider fails
+// fast with its reasons. The world is the one `ci plan` builds from a store
+// of registered nodes; the run-scope values come from internal/where.
+// Inputs:  an in-memory-sized state.db in t.TempDir(). Outputs: pass or fail.
+// Constraints: pure Go, no processes, no network, no clock reads in decisions.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/nodes/registry"
+	"github.com/nself-org/plugins/free/ci/internal/policy"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+	"github.com/nself-org/plugins/free/ci/internal/schedpolicy"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+	"github.com/nself-org/plugins/free/ci/internal/where"
+	"github.com/nself-org/plugins/free/ci/internal/world"
+)
+
+func whereFact[T any](v T) model.Fact[T] {
+	return model.Fact[T]{Value: &v, Source: "assigned", ObservedAt: time.Now(), Confidence: "known"}
+}
+
+// whereNode registers one online linux LAN node the owner's jobs may use.
+func whereNode(t *testing.T, st *store.Store, id string) {
+	t.Helper()
+	ctx := context.Background()
+	raw, err := os.ReadFile("../../internal/model/testdata/capability/valid/vps.valid.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var c model.Capability
+	if err = json.Unmarshal(raw, &c); err != nil {
+		t.Fatal(err)
+	}
+	lan, owned, uid, slots := "lan", "owned", true, 4
+	c.Identity.ID, c.Identity.Name, c.Identity.Labels = id, id, nil
+	c.Location.Kind.Value, c.Economics.Class.Value = &lan, &owned
+	c.Separation.UIDSeparation = model.Fact[bool]{Value: &uid, Source: "self", ObservedAt: time.Now(), Confidence: "known"}
+	c.Availability.Slots.Value = &slots
+	c.Lifecycle = model.CapabilityLifecycle{AuthorizedProjects: []string{}}
+	doc, err := json.Marshal(c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = st.NodePut(ctx, store.NodeRecord{ID: id, Name: id, State: "offline", Lifecycle: []byte("{}"), Trust: []byte("{}"), DeployHost: []byte("{}"), Capability: doc, ObservedAt: time.Now().UnixNano()}, "test"); err != nil {
+		t.Fatal(err)
+	}
+	admin, err := store.NewAdminAuthority("test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	reg := registry.New(st)
+	tr := model.CapabilityTrust{
+		Accepts:       whereFact([]model.TrustClass{"owner", "internal"}),
+		Isolation:     whereFact(model.Isolation("container")),
+		Network:       whereFact([]model.NetworkScope{"none", "internet", "restricted", "lan", "privileged"}),
+		SecretClasses: whereFact([]model.SecretClass{"none"}),
+		PrivacyZone:   whereFact(model.PrivacyZone("private-infrastructure")),
+	}
+	if _, err = reg.SetTrust(ctx, id, tr, admin); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = reg.SetState(ctx, id, "online", "", "test"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = reg.Authorize(ctx, id, "p", "test"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// wherePlace places one job under the run-scope values of a --where target.
+func wherePlace(t *testing.T, st *store.Store, vals map[string]json.RawMessage) sched.Result {
+	t.Helper()
+	reg, err := trust.NewRegistry(policy.Default.Keys()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	eff, _, err := reg.Merge("", trust.Scope{Kind: trust.SourceRun, Values: vals})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sp, err := schedpolicy.Placement(&eff)
+	if err != nil {
+		t.Fatal(err)
+	}
+	job := sched.Job{Key: "j", ID: "j", Project: "p", Pipeline: sched.Pipeline{ID: "pipe", Support: []string{"linux/arm64"}},
+		Requirements: model.PlacementRequirements{Platform: "linux/arm64", CPU: 1, MemMB: 128},
+		Trust:        "owner", Network: "lan", TimeoutMs: 60000, PersonalOwnRun: true}
+	deps := world.Deps{Store: st, Policy: func(context.Context, string) (sched.Policy, error) { return sp, nil }, Clock: time.Now}
+	wd, _, err := world.Build(context.Background(), deps, job.Pipeline)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return sched.Place(wd, []sched.Job{job})
+}
+
+func whereStore(t *testing.T) *store.Store {
+	t.Helper()
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	whereNode(t, st, "lan1")
+	whereNode(t, st, "lan2")
+	return st
+}
+
+func TestWhereNodeSim(t *testing.T) {
+	st := whereStore(t)
+	k := where.Known{Nodes: []string{"lan1", "lan2"}}
+	tgt, err := where.Values("lan2", k, where.Opts{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	res := wherePlace(t, st, tgt.Values)
+	if len(res.Placements) != 1 || res.Placements[0].RunnerID != "lan2" {
+		t.Fatalf("--where lan2 placed %+v", res)
+	}
+}
+
+func TestWhereLocalNeverRemote(t *testing.T) {
+	st := whereStore(t)
+	tgt, err := where.Values("local", where.Known{Nodes: []string{"lan1", "lan2"}}, where.Opts{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range wherePlace(t, st, tgt.Values).Placements {
+		if p.RunnerID == "lan1" || p.RunnerID == "lan2" {
+			t.Fatalf("--where local placed on registered node %s", p.RunnerID)
+		}
+	}
+}
+
+func TestWhereHostedNoProviderFailsFast(t *testing.T) {
+	_, err := where.Values("hosted", where.Known{Nodes: []string{"lan1"}}, where.Opts{})
+	we, ok := err.(*where.Error)
+	if !ok || len(we.Reasons) == 0 {
+		t.Fatalf("want an E797 with a reason list, got %v", err)
+	}
+}
diff --git a/free/ci/test/sim/writeload_test.go b/free/ci/test/sim/writeload_test.go
new file mode 100644
index 000000000..170f88f7c
--- /dev/null
+++ b/free/ci/test/sim/writeload_test.go
@@ -0,0 +1,237 @@
+//go:build integration
+
+package sim
+
+// Purpose: TestWriteLoad, the TEAM store write-load leg (P7-NODE-17): 50 agents renew a lease every 10 s
+//          while the webhook intake takes 20 deliveries per second, for -write-load-for (10 minutes), against
+//          one durable state.db. It asserts zero 503s and zero failed renewals and records the p99 write latency.
+// Inputs:  -write-load-for, -perf-json; INTEGRATION=1.
+// Outputs: metric store.write_p99_ms (ms): the p99 of the intake write latency (the webhook handler answers 2xx
+//          only after the trigger is stored) in each 10 s window of the run, so p50/p95/max are taken over the
+//          windows. The renew latency and the totals are logged.
+// Constraints: in-process (the real coordinator Handler, lease engine and store); no Docker, no network beyond
+//          the loopback of the test; deliveries are open-loop (one goroutine per tick), so a slow store shows up as
+//          latency and concurrency, not as a lower rate.
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"sort"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nself-org/plugins/free/ci/internal/coordinator"
+	"github.com/nself-org/plugins/free/ci/internal/lease"
+	"github.com/nself-org/plugins/free/ci/internal/store"
+)
+
+const (
+	loadAgents    = 50
+	loadBeat      = 10 * time.Second
+	loadHooksPerS = 20
+	loadWindow    = 10 * time.Second
+	loadSecret    = "write-load-secret"
+)
+
+type stamp struct {
+	at time.Time
+	ms float64
+}
+
+type loadResult struct {
+	mu      sync.Mutex
+	hooks   []stamp
+	renews  []stamp
+	codes   map[int]int
+	renewEr int
+	badBody string // the first answer that was not a 202, for the failure message
+}
+
+func (r *loadResult) hook(at time.Time, ms float64, code int, body string) {
+	r.mu.Lock()
+	if code != http.StatusAccepted && r.badBody == "" {
+		r.badBody = body
+	}
+	r.hooks = append(r.hooks, stamp{at, ms})
+	r.codes[code]++
+	r.mu.Unlock()
+}
+
+func (r *loadResult) renew(at time.Time, ms float64, err error) {
+	r.mu.Lock()
+	r.renews = append(r.renews, stamp{at, ms})
+	if err != nil {
+		r.renewEr++
+	}
+	r.mu.Unlock()
+}
+
+// windowP99 groups stamps into windows of loadWindow from start and returns each window's p99.
+func windowP99(s []stamp, start time.Time) []float64 {
+	by := map[int][]float64{}
+	for _, v := range s {
+		by[int(v.at.Sub(start)/loadWindow)] = append(by[int(v.at.Sub(start)/loadWindow)], v.ms)
+	}
+	keys := make([]int, 0, len(by))
+	for k := range by {
+		keys = append(keys, k)
+	}
+	sort.Ints(keys)
+	var out []float64
+	for _, k := range keys {
+		sort.Float64s(by[k])
+		out = append(out, quantile(by[k], 0.99))
+	}
+	return out
+}
+
+func allMS(s []stamp) []float64 {
+	out := make([]float64, 0, len(s))
+	for _, v := range s {
+		out = append(out, v.ms)
+	}
+	sort.Float64s(out)
+	return out
+}
+
+func grantLeases(t *testing.T, st *store.Store, eng *lease.Engine) (ids []string, epochs []int64) {
+	t.Helper()
+	ctx := context.Background()
+	err := st.CreatePipeline(ctx, store.PipelineRow{ID: "pload", Revision: "rev", Project: "o/r", Trigger: "local", SourceTrust: "owner",
+		PrivacyZone: "local-only", PolicyDigest: "p", InputDigest: "i", SelectionMode: "full", Status: "running"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < loadAgents; i++ {
+		a := fmt.Sprintf("load-a%02d", i)
+		if err = st.CreateJob(ctx, store.JobRow{ID: "job-" + a, PipelineID: "pload", Name: a, Kind: "test", Idempotent: true, InfraMax: 1, InputDigest: "i", Required: true}); err != nil {
+			t.Fatal(err)
+		}
+		if err = st.CreateAttempt(ctx, store.AttemptRow{ID: a, JobID: "job-" + a, N: 1}, ""); err != nil {
+			t.Fatal(err)
+		}
+		lid := fmt.Sprintf("load-l%02d", i)
+		epoch, err := eng.Grant(ctx, "host", store.Demand{AttemptID: a, LeaseID: lid, RunnerID: fmt.Sprintf("node-%02d", i), CPU: 1, MemMB: 1,
+			CapacityCPU: 1000, CapacityMemMB: 1000, TTL: eng.Config.TTL}, 1)
+		if err != nil {
+			t.Fatalf("grant %s: %v", lid, err)
+		}
+		ids, epochs = append(ids, lid), append(epochs, epoch)
+	}
+	return ids, epochs
+}
+
+func sign(body []byte) string {
+	m := hmac.New(sha256.New, []byte(loadSecret))
+	m.Write(body)
+	return "sha256=" + hex.EncodeToString(m.Sum(nil))
+}
+
+func hookRequest(n int) *http.Request {
+	sum := sha256.Sum256([]byte(fmt.Sprintf("load-revision-%d", n)))
+	body, _ := json.Marshal(map[string]any{"ref": "refs/heads/main", "after": hex.EncodeToString(sum[:20]),
+		"repository": map[string]string{"full_name": "o/r", "clone_url": "https://github.com/o/r.git"}})
+	req := httptest.NewRequest(http.MethodPost, "/webhook", bytes.NewReader(body))
+	req.Header.Set("X-GitHub-Event", "push")
+	req.Header.Set("X-GitHub-Delivery", fmt.Sprintf("load-%d", n))
+	req.Header.Set("X-Hub-Signature-256", sign(body))
+	return req
+}
+
+func TestWriteLoad(t *testing.T) {
+	integration(t)
+	dur := *writeLoadFor
+	st, err := store.Open(filepath.Join(t.TempDir(), "state.db"), store.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = st.Close() }()
+	eng := lease.New(st, nil, lease.Config{})
+	ids, epochs := grantLeases(t, st, eng)
+	c, err := coordinator.New(coordinator.Config{Store: st, Secret: loadSecret, AllowedRepos: []string{"o/r"}, PolicyDigest: "pd"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := c.Handler(true)
+	res := &loadResult{codes: map[int]int{}}
+	ctx, cancel := context.WithTimeout(context.Background(), dur)
+	defer cancel()
+	start := time.Now()
+	var wg sync.WaitGroup
+	for i := range ids {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			select { // spread the agents over one beat, as a fleet that started at different moments
+			case <-time.After(time.Duration(i) * loadBeat / loadAgents):
+			case <-ctx.Done():
+				return
+			}
+			tick := time.NewTicker(loadBeat)
+			defer tick.Stop()
+			for {
+				t0 := time.Now()
+				err := eng.Renew(context.Background(), ids[i], epochs[i], 0)
+				res.renew(t0, ms(time.Since(t0)), err)
+				select {
+				case <-tick.C:
+				case <-ctx.Done():
+					return
+				}
+			}
+		}(i)
+	}
+	tick := time.NewTicker(time.Second / loadHooksPerS)
+	defer tick.Stop()
+	for n := 0; ; n++ {
+		select {
+		case <-ctx.Done():
+			wg.Wait()
+			finishLoad(t, res, start, dur)
+			return
+		case <-tick.C:
+		}
+		wg.Add(1)
+		go func(n int) {
+			defer wg.Done()
+			w := httptest.NewRecorder()
+			t0 := time.Now()
+			h.ServeHTTP(w, hookRequest(n))
+			res.hook(t0, ms(time.Since(t0)), w.Code, w.Body.String())
+		}(n)
+	}
+}
+
+func finishLoad(t *testing.T, res *loadResult, start time.Time, dur time.Duration) {
+	t.Helper()
+	res.mu.Lock()
+	defer res.mu.Unlock()
+	if n := res.codes[http.StatusServiceUnavailable]; n != 0 {
+		t.Errorf("%d deliveries were answered 503", n)
+	}
+	for code, n := range res.codes {
+		if code != http.StatusAccepted {
+			t.Errorf("%d deliveries were answered %d, want 202 (first body: %s)", n, code, res.badBody)
+		}
+	}
+	if res.renewEr != 0 {
+		t.Errorf("%d lease renewals failed", res.renewEr)
+	}
+	wins := windowP99(res.hooks, start)
+	hooks, renews := allMS(res.hooks), allMS(res.renews)
+	t.Logf("write load %s: %d deliveries (codes %v), %d renewals, delivery p50 %.2f p99 %.2f max %.2f ms, renew p99 %.2f ms, %d windows",
+		dur, len(hooks), res.codes, len(renews), quantile(hooks, 0.50), quantile(hooks, 0.99), quantile(hooks, 1), quantile(renews, 0.99), len(wins))
+	if len(hooks) < int(dur/time.Second)*loadHooksPerS*9/10 {
+		t.Errorf("only %d deliveries were sent in %s; the rate fell short", len(hooks), dur)
+	}
+	recordPerf("write-load", "store.write_p99_ms", "ms", fmt.Sprintf("p99 of the intake write per %s window; %d agents at %s, %d deliveries/s, %s", loadWindow, loadAgents, loadBeat, loadHooksPerS, dur), wins)
+}
diff --git a/free/ci/tools/doccmds/check.go b/free/ci/tools/doccmds/check.go
new file mode 100644
index 000000000..e62b1f588
--- /dev/null
+++ b/free/ci/tools/doccmds/check.go
@@ -0,0 +1,85 @@
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+// Runner runs one doc block with its working directory set to dir and returns the block's exit code.
+// A non-nil error means the block could not be run at all.
+type Runner interface {
+	Run(dir, script string) (int, error)
+}
+
+// Fixture creates a clean project directory for one block. It returns the directory and a function
+// that removes it.
+type Fixture func() (dir string, cleanup func(), err error)
+
+// Options holds the injected pieces CheckPage uses, so tests run without spawning processes.
+type Options struct {
+	Runner  Runner
+	Fixture Fixture
+}
+
+// Failure reports one bash block that did not behave as its marker says it should.
+type Failure struct {
+	// Page is the doc page path, as given on the command line.
+	Page string
+	// Block is the 1-based number of the block among the page's bash blocks.
+	Block int
+	// ExitCode is the block's exit code, or -1 when the block or its fixture could not run.
+	ExitCode int
+	// Message says what went wrong, for example "exit 3".
+	Message string
+}
+
+// Error formats the failure as "page: block N: message".
+func (f Failure) Error() string {
+	return fmt.Sprintf("%s: block %d: %s", f.Page, f.Block, f.Message)
+}
+
+// CheckPage runs every bash block of the page at path, each in its own fresh fixture, and returns the
+// failures in page order. A page without bash blocks returns no failures and runs nothing.
+func CheckPage(path string, opts Options) ([]Failure, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	blocks, err := ExtractBlocks(string(data))
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", path, err)
+	}
+	var failures []Failure
+	for _, b := range blocks {
+		if f, failed := checkBlock(path, b, opts); failed {
+			failures = append(failures, f)
+		}
+	}
+	return failures, nil
+}
+
+// checkBlock runs one block in a fresh fixture and reports whether its exit code breaks the marker.
+func checkBlock(page string, b Block, opts Options) (Failure, bool) {
+	fail := func(code int, msg string) (Failure, bool) {
+		return Failure{Page: page, Block: b.Number, ExitCode: code, Message: msg}, true
+	}
+	dir, cleanup, err := opts.Fixture()
+	if err != nil {
+		return fail(-1, fmt.Sprintf("fixture: %v", err))
+	}
+	defer cleanup()
+	code, err := opts.Runner.Run(dir, b.Script)
+	if err != nil {
+		return fail(-1, fmt.Sprintf("could not run: %v", err))
+	}
+	if b.ExpectFail {
+		if code == 0 {
+			return fail(0, "exit 0 (expected non-zero: marked expect-fail)")
+		}
+		return Failure{}, false
+	}
+	if code != 0 {
+		return fail(code, fmt.Sprintf("exit %d", code))
+	}
+	return Failure{}, false
+}
diff --git a/free/ci/tools/doccmds/check_test.go b/free/ci/tools/doccmds/check_test.go
new file mode 100644
index 000000000..74d378285
--- /dev/null
+++ b/free/ci/tools/doccmds/check_test.go
@@ -0,0 +1,177 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// fakeRunner returns a canned exit code per script and records every call. It runs nothing.
+type fakeRunner struct {
+	codes map[string]int
+	err   error
+	dirs  []string
+	calls []string
+}
+
+// Run records the call and returns the canned code for script, or 0 when none is set.
+func (f *fakeRunner) Run(dir, script string) (int, error) {
+	f.dirs = append(f.dirs, dir)
+	f.calls = append(f.calls, script)
+	if f.err != nil {
+		return -1, f.err
+	}
+	return f.codes[script], nil
+}
+
+// fakeFixture hands out a fixed directory and counts creations and cleanups.
+type fakeFixture struct {
+	made    int
+	cleaned int
+	err     error
+}
+
+// fixture returns the fake Fixture function bound to f.
+func (f *fakeFixture) fixture() (string, func(), error) {
+	if f.err != nil {
+		return "", nil, f.err
+	}
+	f.made++
+	return "fixture-dir", func() { f.cleaned++ }, nil
+}
+
+// checkWith runs CheckPage on a testdata page with the fake runner and fixture.
+func checkWith(t *testing.T, page string, r *fakeRunner, fx *fakeFixture) []Failure {
+	t.Helper()
+	failures, err := CheckPage("testdata/"+page, Options{Runner: r, Fixture: fx.fixture})
+	if err != nil {
+		t.Fatalf("CheckPage(%s): %v", page, err)
+	}
+	return failures
+}
+
+func TestCheckPagePasses(t *testing.T) {
+	r := &fakeRunner{}
+	fx := &fakeFixture{}
+	if got := checkWith(t, "pass.md", r, fx); len(got) != 0 {
+		t.Fatalf("failures = %v, want none", got)
+	}
+	if want := []string{"echo ok", "true"}; !reflect.DeepEqual(r.calls, want) {
+		t.Errorf("ran %q, want %q (the sh block must be skipped)", r.calls, want)
+	}
+	if fx.made != 2 || fx.cleaned != 2 {
+		t.Errorf("fixtures made=%d cleaned=%d, want 2 and 2 (one fresh fixture per block)", fx.made, fx.cleaned)
+	}
+	for _, d := range r.dirs {
+		if d != "fixture-dir" {
+			t.Errorf("block ran in %q, want the fixture dir", d)
+		}
+	}
+}
+
+func TestCheckPageReportsNonZeroExit(t *testing.T) {
+	r := &fakeRunner{codes: map[string]int{"exit 3": 3, "exit 7": 7}}
+	got := checkWith(t, "fail.md", r, &fakeFixture{})
+	if len(got) != 2 {
+		t.Fatalf("got %d failures, want 2: %v", len(got), got)
+	}
+	want := []Failure{
+		{Page: "testdata/fail.md", Block: 2, ExitCode: 3, Message: "exit 3"},
+		{Page: "testdata/fail.md", Block: 3, ExitCode: 7, Message: "exit 7"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("failures = %+v, want %+v", got, want)
+	}
+	if msg := got[0].Error(); msg != "testdata/fail.md: block 2: exit 3" {
+		t.Errorf("Error() = %q", msg)
+	}
+	if msg := got[1].Error(); msg != "testdata/fail.md: block 3: exit 7" {
+		t.Errorf("Error() = %q", msg)
+	}
+}
+
+func TestCheckPageExpectFailMarker(t *testing.T) {
+	r := &fakeRunner{codes: map[string]int{"exit 1": 1, "exit 5": 5}}
+	got := checkWith(t, "expect-fail.md", r, &fakeFixture{})
+	if len(got) != 2 {
+		t.Fatalf("got %d failures, want 2: %v", len(got), got)
+	}
+	if got[0].Block != 2 || got[0].ExitCode != 0 || got[0].Message != "exit 0 (expected non-zero: marked expect-fail)" {
+		t.Errorf("marked zero-exit failure = %+v", got[0])
+	}
+	if msg := got[0].Error(); msg != "testdata/expect-fail.md: block 2: exit 0 (expected non-zero: marked expect-fail)" {
+		t.Errorf("Error() = %q", msg)
+	}
+	if got[1].Block != 3 || got[1].ExitCode != 5 || got[1].Message != "exit 5" {
+		t.Errorf("unmarked block failure = %+v, want block 3 exit 5", got[1])
+	}
+}
+
+func TestCheckPageWithoutBashBlocksRunsNothing(t *testing.T) {
+	r := &fakeRunner{}
+	fx := &fakeFixture{}
+	if got := checkWith(t, "no-blocks.md", r, fx); len(got) != 0 {
+		t.Fatalf("failures = %v, want none", got)
+	}
+	if len(r.calls) != 0 || fx.made != 0 {
+		t.Errorf("runner calls=%d fixtures=%d, want 0 and 0", len(r.calls), fx.made)
+	}
+}
+
+func TestCheckPageRunnerError(t *testing.T) {
+	r := &fakeRunner{err: errors.New("boom")}
+	got := checkWith(t, "pass.md", r, &fakeFixture{})
+	if len(got) != 2 {
+		t.Fatalf("got %d failures, want 2: %v", len(got), got)
+	}
+	if got[0].ExitCode != -1 || got[0].Message != "could not run: boom" {
+		t.Errorf("runner error failure = %+v", got[0])
+	}
+}
+
+func TestCheckPageFixtureError(t *testing.T) {
+	r := &fakeRunner{}
+	got := checkWith(t, "pass.md", r, &fakeFixture{err: errors.New("no disk")})
+	if len(got) != 2 || got[0].Message != "fixture: no disk" {
+		t.Fatalf("fixture failures = %v", got)
+	}
+	if len(r.calls) != 0 {
+		t.Errorf("runner ran %d blocks without a fixture", len(r.calls))
+	}
+}
+
+func TestCheckPageMissingFile(t *testing.T) {
+	_, err := CheckPage("testdata/missing.md", Options{Runner: &fakeRunner{}, Fixture: (&fakeFixture{}).fixture})
+	if err == nil {
+		t.Fatal("CheckPage on a missing page returned no error")
+	}
+}
+
+func TestRunUsage(t *testing.T) {
+	var out, errOut bytes.Buffer
+	if code := run(nil, &out, &errOut); code != 2 {
+		t.Errorf("run() = %d, want 2", code)
+	}
+	if !strings.Contains(errOut.String(), "usage: check-doc-commands.sh <page.md>...") {
+		t.Errorf("usage text = %q", errOut.String())
+	}
+}
+
+func TestRunMissingPageFails(t *testing.T) {
+	var out, errOut bytes.Buffer
+	if code := run([]string{"testdata/missing.md"}, &out, &errOut); code != 1 {
+		t.Errorf("run() = %d, want 1", code)
+	}
+	if !strings.Contains(errOut.String(), "missing.md") {
+		t.Errorf("stderr = %q, want the missing page named", errOut.String())
+	}
+}
+
+func TestRunPageWithoutBlocksPasses(t *testing.T) {
+	var out, errOut bytes.Buffer
+	if code := run([]string{"testdata/no-blocks.md"}, &out, &errOut); code != 0 {
+		t.Errorf("run() = %d, want 0; stdout=%q stderr=%q", code, out.String(), errOut.String())
+	}
+}
diff --git a/free/ci/tools/doccmds/extract.go b/free/ci/tools/doccmds/extract.go
new file mode 100644
index 000000000..a8c08432b
--- /dev/null
+++ b/free/ci/tools/doccmds/extract.go
@@ -0,0 +1,83 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+)
+
+// expectFailMarker, placed on the line directly above a bash fence, marks the block as expected to fail.
+const expectFailMarker = "<!-- doc-command: expect-fail -->"
+
+// Block is one fenced bash block taken from a doc page.
+type Block struct {
+	// Number is the 1-based position of the block among the page's bash blocks.
+	Number int
+	// Line is the 1-based line of the opening fence.
+	Line int
+	// Script is the block body without its fences.
+	Script string
+	// ExpectFail is true when the expect-fail marker sits directly above the opening fence.
+	ExpectFail bool
+}
+
+// ExtractBlocks returns the fenced bash blocks of content in page order. Fenced blocks in other
+// languages are skipped whole, so a bash-looking line inside them never runs. An unclosed bash fence
+// is an error; an unclosed fence in another language runs to the end of the page, as Markdown does.
+func ExtractBlocks(content string) ([]Block, error) {
+	lines := strings.Split(content, "\n")
+	var blocks []Block
+	for i := 0; i < len(lines); i++ {
+		ticks, lang, ok := parseOpenFence(lines[i])
+		if !ok {
+			continue
+		}
+		end := closingFence(lines, i+1, ticks)
+		if end < 0 {
+			if lang == "bash" {
+				return nil, fmt.Errorf("line %d: unclosed bash fence", i+1)
+			}
+			break
+		}
+		if lang == "bash" {
+			blocks = append(blocks, Block{
+				Number:     len(blocks) + 1,
+				Line:       i + 1,
+				Script:     strings.Join(lines[i+1:end], "\n"),
+				ExpectFail: i > 0 && strings.TrimSpace(lines[i-1]) == expectFailMarker,
+			})
+		}
+		i = end
+	}
+	return blocks, nil
+}
+
+// parseOpenFence reports whether line opens a code fence. It returns the backtick count and the
+// first word of the info string, which is the language.
+func parseOpenFence(line string) (int, string, bool) {
+	t := strings.TrimSpace(line)
+	if !strings.HasPrefix(t, "```") {
+		return 0, "", false
+	}
+	ticks := len(t) - len(strings.TrimLeft(t, "`"))
+	info := strings.TrimSpace(t[ticks:])
+	if strings.Contains(info, "`") {
+		return 0, "", false
+	}
+	lang := ""
+	if fields := strings.Fields(info); len(fields) > 0 {
+		lang = fields[0]
+	}
+	return ticks, lang, true
+}
+
+// closingFence returns the index of the first line at or after from that closes a fence opened with
+// ticks backticks, or -1 when none does.
+func closingFence(lines []string, from, ticks int) int {
+	for j := from; j < len(lines); j++ {
+		t := strings.TrimSpace(lines[j])
+		if len(t) >= ticks && strings.Trim(t, "`") == "" {
+			return j
+		}
+	}
+	return -1
+}
diff --git a/free/ci/tools/doccmds/extract_test.go b/free/ci/tools/doccmds/extract_test.go
new file mode 100644
index 000000000..d1e78ce82
--- /dev/null
+++ b/free/ci/tools/doccmds/extract_test.go
@@ -0,0 +1,87 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestExtractBlocksNumbersAndMarker(t *testing.T) {
+	content := strings.Join([]string{
+		"# Page",
+		"```sh",
+		"exit 9",
+		"```",
+		"```bash",
+		"echo one",
+		"echo two",
+		"```",
+		"<!-- doc-command: expect-fail -->",
+		"```bash title=second",
+		"exit 2",
+		"```",
+		"<!-- doc-command: expect-fail -->",
+		"",
+		"```bash",
+		"exit 4",
+		"```",
+	}, "\n")
+	got, err := ExtractBlocks(content)
+	if err != nil {
+		t.Fatalf("ExtractBlocks: %v", err)
+	}
+	want := []Block{
+		{Number: 1, Line: 5, Script: "echo one\necho two"},
+		{Number: 2, Line: 10, Script: "exit 2", ExpectFail: true},
+		{Number: 3, Line: 15, Script: "exit 4"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("blocks = %+v\nwant     %+v", got, want)
+	}
+}
+
+func TestExtractBlocksSkipsNestedFence(t *testing.T) {
+	// A four-backtick fence holds a bash fence as plain text, so no block is extracted.
+	content := "````text\n```bash\nexit 4\n```\n````\n"
+	got, err := ExtractBlocks(content)
+	if err != nil || len(got) != 0 {
+		t.Errorf("ExtractBlocks = %+v, %v; want no blocks and no error", got, err)
+	}
+}
+
+func TestExtractBlocksUnclosedBashFails(t *testing.T) {
+	_, err := ExtractBlocks("```bash\nexit 1\n")
+	if err == nil || err.Error() != "line 1: unclosed bash fence" {
+		t.Errorf("err = %v, want unclosed bash fence on line 1", err)
+	}
+}
+
+func TestExtractBlocksUnclosedOtherFenceRunsToEnd(t *testing.T) {
+	got, err := ExtractBlocks("```bash\nexit 1\n```\n```text\nfoo\n")
+	if err != nil || len(got) != 1 {
+		t.Errorf("ExtractBlocks = %+v, %v; want one block and no error", got, err)
+	}
+}
+
+func TestParseOpenFence(t *testing.T) {
+	cases := []struct {
+		line  string
+		ticks int
+		lang  string
+		ok    bool
+	}{
+		{"```bash", 3, "bash", true},
+		{"  ```bash title=x", 3, "bash", true},
+		{"````sh", 4, "sh", true},
+		{"```", 3, "", true},
+		{"``` a`b", 0, "", false},
+		{"text ```bash", 0, "", false},
+	}
+	for _, c := range cases {
+		ticks, lang, ok := parseOpenFence(c.line)
+		if ticks != c.ticks || lang != c.lang || ok != c.ok {
+			t.Errorf("parseOpenFence(%q) = %d, %q, %v; want %d, %q, %v",
+				c.line, ticks, lang, ok, c.ticks, c.lang, c.ok)
+		}
+	}
+}
diff --git a/free/ci/tools/doccmds/main.go b/free/ci/tools/doccmds/main.go
new file mode 100644
index 000000000..7157c4a77
--- /dev/null
+++ b/free/ci/tools/doccmds/main.go
@@ -0,0 +1,63 @@
+// Command doccmds runs the bash blocks of doc pages in clean fixture projects and fails when a block
+// exits in a way its marker does not allow. A block under <!-- doc-command: expect-fail --> must exit
+// non-zero; every other block must exit 0. It is run by .github/scripts/check-doc-commands.sh.
+//
+// Usage: doccmds <page.md>...
+// Exit codes: 0 all blocks behave, 1 a block or page failed, 2 usage.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+// usageText is printed when no page is given.
+const usageText = "usage: check-doc-commands.sh <page.md>..."
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+// run checks every page and writes one line per failure to stdout and page errors to stderr. It returns
+// the process exit code.
+func run(pages []string, stdout, stderr io.Writer) int {
+	base := os.Getenv("DOCCMDS_CALLER_DIR")
+	resolved := make([]string, len(pages))
+	for i, page := range pages {
+		resolved[i] = pagePath(base, page)
+	}
+	opts := Options{Runner: shellRunner{timeout: blockTimeout}, Fixture: newFixture}
+	return runWithOptions(resolved, stdout, stderr, opts)
+}
+
+// pagePath preserves paths relative to the wrapper's caller across go -C.
+func pagePath(base, page string) string {
+	if base == "" || filepath.IsAbs(page) {
+		return page
+	}
+	return filepath.Join(base, page)
+}
+
+// runWithOptions checks pages using injected execution and fixture creation.
+func runWithOptions(pages []string, stdout, stderr io.Writer, opts Options) int {
+	if len(pages) == 0 {
+		fmt.Fprintln(stderr, usageText)
+		return 2
+	}
+	status := 0
+	for _, page := range pages {
+		failures, err := CheckPage(page, opts)
+		if err != nil {
+			fmt.Fprintf(stderr, "%v\n", err)
+			status = 1
+			continue
+		}
+		for _, f := range failures {
+			fmt.Fprintln(stdout, f.Error())
+			status = 1
+		}
+	}
+	return status
+}
diff --git a/free/ci/tools/doccmds/main_test.go b/free/ci/tools/doccmds/main_test.go
new file mode 100644
index 000000000..5c4a83c57
--- /dev/null
+++ b/free/ci/tools/doccmds/main_test.go
@@ -0,0 +1,63 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestRunFixturePages(t *testing.T) {
+	cases := []struct {
+		page string
+		code int
+		out  string
+	}{
+		{"pass.md", 0, ""},
+		{"fail.md", 1, "testdata/fail.md: block 2: exit 3\ntestdata/fail.md: block 3: exit 7\n"},
+		{"expect-fail.md", 1, "testdata/expect-fail.md: block 2: exit 0 (expected non-zero: marked expect-fail)\ntestdata/expect-fail.md: block 3: exit 5\n"},
+		{"no-blocks.md", 0, ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.page, func(t *testing.T) {
+			r := &fakeRunner{codes: map[string]int{
+				"exit 1": 1, "exit 3": 3, "exit 5": 5, "exit 7": 7,
+			}}
+			fx := &fakeFixture{}
+			var out, errOut bytes.Buffer
+			code := runWithOptions([]string{"testdata/" + tc.page}, &out, &errOut,
+				Options{Runner: r, Fixture: fx.fixture})
+			if code != tc.code || out.String() != tc.out || errOut.Len() != 0 {
+				t.Fatalf("code=%d stdout=%q stderr=%q; want code=%d stdout=%q stderr empty",
+					code, out.String(), errOut.String(), tc.code, tc.out)
+			}
+			if fx.made != len(r.calls) || fx.cleaned != fx.made {
+				t.Errorf("calls=%d fixtures=%d cleanups=%d", len(r.calls), fx.made, fx.cleaned)
+			}
+		})
+	}
+}
+
+func TestPagePath(t *testing.T) {
+	base := filepath.Join(string(filepath.Separator), "caller")
+	abs := filepath.Join(base, "page.md")
+	for _, tc := range []struct{ base, page, want string }{
+		{base, "page.md", abs},
+		{base, abs, abs},
+		{"", "page.md", "page.md"},
+	} {
+		if got := pagePath(tc.base, tc.page); got != tc.want {
+			t.Errorf("pagePath(%q, %q) = %q; want %q", tc.base, tc.page, got, tc.want)
+		}
+	}
+}
+
+func TestWrapperExecutable(t *testing.T) {
+	info, err := os.Stat("../../../../.github/scripts/check-doc-commands.sh")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := info.Mode().Perm(); got != 0755 {
+		t.Errorf("wrapper mode = %04o; want 0755", got)
+	}
+}
diff --git a/free/ci/tools/doccmds/runner.go b/free/ci/tools/doccmds/runner.go
new file mode 100644
index 000000000..5579a34bc
--- /dev/null
+++ b/free/ci/tools/doccmds/runner.go
@@ -0,0 +1,109 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"time"
+
+	ciexec "github.com/nself-org/plugins/free/ci/internal/exec"
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// blockTimeout bounds one doc block, so a hung command fails the check instead of stalling CI.
+const blockTimeout = 10 * time.Minute
+
+// fixtureEnvPolicy gives a block the fixture environment and nothing else.
+type fixtureEnvPolicy struct{ dir string }
+
+func (p fixtureEnvPolicy) Environment(context.Context, model.Job) ([]string, error) {
+	return fixtureEnv(p.dir), nil
+}
+
+// runIn runs argv through the command funnel (internal/exec) with the fixture environment of dir.
+// The command starts in the executor's empty workspace; out receives its output.
+//
+// timeout is a wall-clock bound carried by the context, not by JobSpec.Timeout: the funnel turns a
+// JobSpec timeout into a CPU ulimit (hard limit), and a block that runs `nself ci -- cmd` starts an
+// inner job whose own limit (30m by default) is then above the block's. The inner job cannot raise
+// its hard limit and dies with "ulimit: Operation not permitted". Leaving the block without a CPU
+// limit lets the inner job set its own, and the context deadline still fails a hung block.
+func runIn(ctx context.Context, dir string, timeout time.Duration, out func([]byte), argv ...string) (ciexec.AttemptResult, error) {
+	home, err := os.MkdirTemp("", "doccmds-home-")
+	if err != nil {
+		return ciexec.AttemptResult{}, err
+	}
+	defer func() { _ = os.RemoveAll(home) }()
+	if timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, timeout)
+		defer cancel()
+	}
+	ex := ciexec.Executor{Isolation: ciexec.BaselineIsolator{}, Env: fixtureEnvPolicy{dir}}
+	res := ex.Run(ctx, ciexec.JobSpec{
+		AttemptID: "doccmds-" + strconv.FormatInt(time.Now().UnixNano(), 36), CoordinatorID: "doccmds",
+		Job: model.Job{Kind: "static"}, Home: home, Command: argv, Output: out,
+	})
+	return res, nil
+}
+
+// shellRunner runs a block with bash in the fixture directory.
+type shellRunner struct {
+	timeout time.Duration
+}
+
+// Run executes script with bash in dir and returns its exit code. Block output goes to stderr so the
+// failure report on stdout stays readable.
+func (r shellRunner) Run(dir, script string) (int, error) {
+	// $HOME is the fixture directory (fixtureEnv); the block runs there, as it would in a fresh project.
+	res, err := runIn(context.Background(), dir, r.timeout, func(b []byte) { _, _ = os.Stderr.Write(b) },
+		"bash", "-c", "cd \"$HOME\" || exit 1\n"+script)
+	if err != nil {
+		return -1, err
+	}
+	if res.Attempt.FailureClass == "timeout" {
+		return -1, fmt.Errorf("timed out after %s", r.timeout)
+	}
+	if res.Err != nil {
+		return -1, res.Err
+	}
+	return res.ExitCode, nil
+}
+
+// fixtureEnv is the whole environment a block sees. Nothing else from the caller leaks in, so a block
+// cannot read a credential from the CI environment.
+func fixtureEnv(dir string) []string {
+	return []string{
+		"PATH=" + os.Getenv("PATH"),
+		"HOME=" + dir,
+		"TMPDIR=" + os.TempDir(),
+		"LANG=C",
+		"NSELF_V15=1",
+		"CGO_ENABLED=0",
+		"GOFLAGS=-mod=vendor",
+	}
+}
+
+// newFixture makes an empty temp project with a git repo. It returns the directory and a function that
+// removes it.
+func newFixture() (string, func(), error) {
+	dir, err := os.MkdirTemp("", "doccmds-")
+	if err != nil {
+		return "", nil, err
+	}
+	cleanup := func() { _ = os.RemoveAll(dir) }
+	var out []byte
+	res, err := runIn(context.Background(), dir, time.Minute, func(b []byte) { out = append(out, b...) }, "git", "init", "-q", dir)
+	if err == nil && res.Err != nil {
+		err = res.Err
+	}
+	if err == nil && res.ExitCode != 0 {
+		err = fmt.Errorf("exit %d", res.ExitCode)
+	}
+	if err != nil {
+		cleanup()
+		return "", nil, fmt.Errorf("git init: %w: %s", err, out)
+	}
+	return dir, cleanup, nil
+}
diff --git a/free/ci/tools/doccmds/runner_test.go b/free/ci/tools/doccmds/runner_test.go
new file mode 100644
index 000000000..17f736837
--- /dev/null
+++ b/free/ci/tools/doccmds/runner_test.go
@@ -0,0 +1,41 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// A block that starts a job with a CPU limit of its own must not be refused because the block itself
+// carries a lower one: an ad hoc `nself ci -- cmd` example runs a 30 minute inner job inside a block with a
+// 10 minute bound. The inner `ulimit -t` raises the hard limit above the block's and fails with
+// "Operation not permitted" when the block was started under a CPU ulimit.
+func TestBlockCanStartJobWithHigherCPULimit(t *testing.T) {
+	dir, cleanup, err := newFixture()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer cleanup()
+	r := shellRunner{timeout: time.Minute}
+	code, err := r.Run(dir, "sh -c 'ulimit -t 1800 || exit 42; echo inner-ok'")
+	if err != nil || code != 0 {
+		t.Fatalf("block exit %d, err %v; want 0 (the inner job sets a limit above the block's bound)", code, err)
+	}
+}
+
+// The wall-clock bound still fails a hung block, and the error names the bound.
+func TestBlockTimeoutStillFailsHungBlock(t *testing.T) {
+	dir, cleanup, err := newFixture()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer cleanup()
+	start := time.Now()
+	code, err := shellRunner{timeout: 500 * time.Millisecond}.Run(dir, "sleep 30")
+	if err == nil || code != -1 || !strings.Contains(err.Error(), "timed out after") {
+		t.Fatalf("exit %d, err %v; want -1 and a timeout error", code, err)
+	}
+	if time.Since(start) > 20*time.Second {
+		t.Fatalf("a hung block ran %s past its bound", time.Since(start))
+	}
+}
diff --git a/free/ci/tools/doccmds/testdata/expect-fail.md b/free/ci/tools/doccmds/testdata/expect-fail.md
new file mode 100644
index 000000000..a025804d1
--- /dev/null
+++ b/free/ci/tools/doccmds/testdata/expect-fail.md
@@ -0,0 +1,20 @@
+# Expect-fail page
+
+Block 1 is marked and fails, so it passes. Block 2 is marked but exits 0, so it fails.
+Block 3 has the marker separated by a blank line, so the marker does not apply and it fails.
+
+<!-- doc-command: expect-fail -->
+```bash
+exit 1
+```
+
+<!-- doc-command: expect-fail -->
+```bash
+true
+```
+
+<!-- doc-command: expect-fail -->
+
+```bash
+exit 5
+```
diff --git a/free/ci/tools/doccmds/testdata/fail.md b/free/ci/tools/doccmds/testdata/fail.md
new file mode 100644
index 000000000..c0d8d6320
--- /dev/null
+++ b/free/ci/tools/doccmds/testdata/fail.md
@@ -0,0 +1,15 @@
+# Fail page
+
+Block 2 and block 3 exit non-zero without a marker.
+
+```bash
+echo ok
+```
+
+```bash
+exit 3
+```
+
+```bash
+exit 7
+```
diff --git a/free/ci/tools/doccmds/testdata/no-blocks.md b/free/ci/tools/doccmds/testdata/no-blocks.md
new file mode 100644
index 000000000..585db67de
--- /dev/null
+++ b/free/ci/tools/doccmds/testdata/no-blocks.md
@@ -0,0 +1,7 @@
+# No blocks page
+
+Prose only. The only fence is Go, so nothing runs.
+
+```go
+package main
+```
diff --git a/free/ci/tools/doccmds/testdata/pass.md b/free/ci/tools/doccmds/testdata/pass.md
new file mode 100644
index 000000000..5c17ff016
--- /dev/null
+++ b/free/ci/tools/doccmds/testdata/pass.md
@@ -0,0 +1,15 @@
+# Pass page
+
+Two bash blocks that exit 0, and one shell block that must be skipped.
+
+```bash
+echo ok
+```
+
+```sh
+exit 9
+```
+
+```bash
+true
+```
diff --git a/free/ci/tools/manifestgen/main.go b/free/ci/tools/manifestgen/main.go
new file mode 100644
index 000000000..72293b96e
--- /dev/null
+++ b/free/ci/tools/manifestgen/main.go
@@ -0,0 +1,62 @@
+package main
+
+// Purpose: `go generate` writer of the plugin.json `commands` block from surface/commands.yaml (P7-CI-62, CI D31).
+// Inputs:  --spec PATH (default ../../surface/commands.yaml), --manifest PATH (default ../../plugin.json), --check.
+// Outputs: rewrites the manifest in place; with --check it writes nothing and exits 1 when the manifest differs.
+// Constraints: touches only the `commands` key; exit 0 ok, 1 stale or invalid spec, 2 usage or I/O error.
+
+//go:generate go run . --spec ../../surface/commands.yaml --manifest ../../plugin.json
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+)
+
+func main() { os.Exit(run(os.Args[1:], os.Stdout, os.Stderr)) }
+
+func run(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("manifestgen", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	specPath := fs.String("spec", "../../surface/commands.yaml", "the authored machine-surface spec")
+	manifest := fs.String("manifest", "../../plugin.json", "the plugin manifest to update")
+	check := fs.Bool("check", false, "report a stale manifest instead of writing")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	raw, err := os.ReadFile(*specPath)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	cur, err := os.ReadFile(*manifest)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	spec, err := Parse(raw)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 1
+	}
+	next, err := Render(spec, cur)
+	if err != nil {
+		fmt.Fprintln(stderr, err)
+		return 1
+	}
+	if bytes.Equal(cur, next) {
+		return 0
+	}
+	if *check {
+		fmt.Fprintln(stderr, "plugin.json commands is stale: run go generate ./tools/manifestgen/...")
+		return 1
+	}
+	if err := os.WriteFile(*manifest, next, 0o644); err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
+	fmt.Fprintln(stdout, "wrote", *manifest)
+	return 0
+}
diff --git a/free/ci/tools/manifestgen/manifestgen_test.go b/free/ci/tools/manifestgen/manifestgen_test.go
new file mode 100644
index 000000000..d3e860181
--- /dev/null
+++ b/free/ci/tools/manifestgen/manifestgen_test.go
@@ -0,0 +1,108 @@
+package main
+
+// Purpose: tests of manifestgen (P7-CI-62): spec validation names the row, rendering is deterministic and touches only
+//          `commands`, and the committed plugin.json equals a fresh generation from the committed spec.
+// Constraints: no network; reads ../../surface/commands.yaml and ../../plugin.json.
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+)
+
+const okSpec = `
+binary: nself-ci
+command: ci
+root:
+  summary: run
+  side_effect: remote
+  output: document
+  json: envelope
+  confirm: {flags: []}
+commands:
+  - {path: plan, summary: plan, side_effect: read, output: document, json: envelope}
+`
+
+func TestParseProblems(t *testing.T) {
+	cases := map[string]struct{ old, new, want string }{
+		"remote without confirm":   {"path: plan, summary: plan, side_effect: read", "path: plan, summary: plan, side_effect: remote", "plan: a remote command exposed"},
+		"interactive not cli-only": {"output: document, json: envelope}\n", "output: interactive, json: envelope}\n", "plan: an interactive command"},
+		"bad side effect":          {"side_effect: read", "side_effect: sudo", `plan: side_effect "sudo"`},
+		"unknown key":              {"json: envelope}\n", "json: envelope, bogus: 1}\n", "bogus"},
+		"confirm on read":          {"json: envelope}\n", "json: envelope, confirm: {flags: []}}\n", "plan: confirm is only for"},
+	}
+	for name, c := range cases {
+		t.Run(name, func(t *testing.T) {
+			// replace only in the commands row (the last occurrence)
+			i := strings.LastIndex(okSpec, c.old)
+			if i < 0 {
+				t.Fatalf("fixture lacks %q", c.old)
+			}
+			_, err := Parse([]byte(okSpec[:i] + c.new + okSpec[i+len(c.old):]))
+			if err == nil || !strings.Contains(err.Error(), c.want) {
+				t.Fatalf("error = %v, want it to contain %q", err, c.want)
+			}
+		})
+	}
+	if _, err := Parse([]byte(okSpec)); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRenderOnlyCommands(t *testing.T) {
+	s, err := Parse([]byte(okSpec))
+	if err != nil {
+		t.Fatal(err)
+	}
+	in := []byte(`{"name":"ci","commands":{"old":true},"zeta":[1]}`)
+	a, err := Render(s, in)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := Render(s, in)
+	if !bytes.Equal(a, b) || !bytes.HasSuffix(a, []byte("}\n")) {
+		t.Fatal("render is not deterministic or lacks the trailing newline")
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(a, &doc); err != nil {
+		t.Fatal(err)
+	}
+	cmds, _ := doc["commands"].(map[string]any)
+	if doc["name"] != "ci" || len(doc["zeta"].([]any)) != 1 || cmds == nil || cmds["old"] != nil {
+		t.Fatalf("unexpected output: %s", a)
+	}
+	if _, ok := cmds["confirm"].(map[string]any); !ok || cmds["binary"] != "nself-ci" || cmds["command"] != "ci" {
+		t.Fatalf("root fields lost: %s", a)
+	}
+}
+
+func TestCommittedManifestCurrent(t *testing.T) {
+	var out, errb bytes.Buffer
+	if code := run([]string{"--check"}, &out, &errb); code != 0 {
+		t.Fatalf("exit %d: %s", code, errb.String())
+	}
+}
+
+func TestCheckDetectsDrift(t *testing.T) {
+	dir := t.TempDir()
+	m := dir + "/plugin.json"
+	if err := os.WriteFile(m, []byte(`{"commands":{}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	spec := dir + "/s.yaml"
+	if err := os.WriteFile(spec, []byte(okSpec), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var out, errb bytes.Buffer
+	if code := run([]string{"--check", "--spec", spec, "--manifest", m}, &out, &errb); code != 1 {
+		t.Fatalf("exit %d, want 1: %s", code, errb.String())
+	}
+	if code := run([]string{"--spec", spec, "--manifest", m}, &out, &errb); code != 0 {
+		t.Fatalf("write exit %d: %s", code, errb.String())
+	}
+	if code := run([]string{"--check", "--spec", spec, "--manifest", m}, &out, &errb); code != 0 {
+		t.Fatalf("check after write exit %d", code)
+	}
+}
diff --git a/free/ci/tools/manifestgen/render.go b/free/ci/tools/manifestgen/render.go
new file mode 100644
index 000000000..8a044c2f2
--- /dev/null
+++ b/free/ci/tools/manifestgen/render.go
@@ -0,0 +1,69 @@
+package main
+
+// Purpose: render the `commands` block of free/ci/plugin.json from a Spec and splice it into the manifest.
+// Inputs:  a Spec and the current plugin.json bytes.
+// Outputs: the new plugin.json bytes: only the `commands` key changes; keys are sorted, 2-space indent, trailing newline.
+// Constraints: root args and flags stay in the spec only (manifest v2 roots declare none); the root summary feeds the v1
+//              compatibility key cliCommands[0].description, so it must equal it; deterministic (same inputs, same bytes); no HTML escaping; rows are ordered by path.
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"sort"
+)
+
+// toMap converts any JSON-encodable value to generic maps so encoding sorts the keys.
+func toMap(v any) (map[string]any, error) {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return nil, err
+	}
+	var m map[string]any
+	return m, json.Unmarshal(b, &m)
+}
+
+// Commands builds the `commands` object for a spec.
+func Commands(s *Spec) (map[string]any, error) {
+	root, err := toMap(s.Root)
+	if err != nil {
+		return nil, err
+	}
+	root["binary"], root["command"] = s.Binary, s.Command
+	// The manifest v2 root declares no args or flags (cli manifestv2: the root has none); the spec keeps them for the tests.
+	delete(root, "args")
+	delete(root, "flags")
+	rows := append([]Row(nil), s.Commands...)
+	sort.Slice(rows, func(i, j int) bool { return rows[i].Path < rows[j].Path })
+	subs := make([]any, 0, len(rows))
+	for _, r := range rows {
+		m, err := toMap(r)
+		if err != nil {
+			return nil, err
+		}
+		subs = append(subs, m)
+	}
+	root["subcommands"] = subs
+	return root, nil
+}
+
+// Render returns manifest with its `commands` key replaced by the block generated from s.
+func Render(s *Spec, manifest []byte) ([]byte, error) {
+	var doc map[string]any
+	if err := json.Unmarshal(manifest, &doc); err != nil {
+		return nil, fmt.Errorf("plugin.json: %w", err)
+	}
+	cmds, err := Commands(s)
+	if err != nil {
+		return nil, err
+	}
+	doc["commands"] = cmds
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(doc); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
diff --git a/free/ci/tools/manifestgen/spec.go b/free/ci/tools/manifestgen/spec.go
new file mode 100644
index 000000000..cd43c7aca
--- /dev/null
+++ b/free/ci/tools/manifestgen/spec.go
@@ -0,0 +1,161 @@
+package main
+
+// Purpose: the typed form of free/ci/surface/commands.yaml, the one authored declaration of the ci plugin's machine
+//          surface (P7-CI-62, CI D31), and its validation.
+// Inputs:  the YAML bytes of the spec.
+// Outputs: a validated Spec; every problem is returned at once, each naming the row path.
+// Constraints: strict decode (an unknown key is an error); no I/O here; the rules mirror the registry's exposure
+//              rules (SURF D2, D3): a remote or destructive row that is exposed (json envelope) needs a confirm block,
+//              and an interactive row is cli-only.
+
+import (
+	"bytes"
+	"fmt"
+	"sort"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Arg is one positional argument in the registry Arg shape.
+type Arg struct {
+	Name     string `yaml:"name" json:"name"`
+	Required bool   `yaml:"required,omitempty" json:"required,omitempty"`
+	Variadic bool   `yaml:"variadic,omitempty" json:"variadic,omitempty"`
+	Secret   bool   `yaml:"secret,omitempty" json:"secret,omitempty"`
+}
+
+// Flag is one flag in the registry Flag shape.
+type Flag struct {
+	Name       string `yaml:"name" json:"name"`
+	Type       string `yaml:"type" json:"type"`
+	Default    string `yaml:"default,omitempty" json:"default,omitempty"`
+	Shorthand  string `yaml:"shorthand,omitempty" json:"shorthand,omitempty"`
+	Usage      string `yaml:"usage,omitempty" json:"usage,omitempty"`
+	SideEffect string `yaml:"side_effect,omitempty" json:"side_effect,omitempty"`
+	Secret     bool   `yaml:"secret,omitempty" json:"secret,omitempty"`
+	CLIOnly    bool   `yaml:"cli_only,omitempty" json:"cli_only,omitempty"`
+}
+
+// Confirm names the consent flags that skip a command's prompt; an empty list means a nonce-only round trip.
+type Confirm struct {
+	Flags []string `yaml:"flags" json:"flags"`
+}
+
+// Row is one command of the surface.
+type Row struct {
+	Path       string   `yaml:"path,omitempty" json:"name,omitempty"`
+	Summary    string   `yaml:"summary" json:"summary"`
+	SideEffect string   `yaml:"side_effect" json:"side_effect"`
+	Output     string   `yaml:"output" json:"output"`
+	JSON       string   `yaml:"json" json:"json"`
+	Surface    string   `yaml:"surface,omitempty" json:"surface,omitempty"`
+	Confirm    *Confirm `yaml:"confirm,omitempty" json:"confirm,omitempty"`
+	Args       []Arg    `yaml:"args,omitempty" json:"args,omitempty"`
+	Flags      []Flag   `yaml:"flags,omitempty" json:"flags,omitempty"`
+}
+
+// Spec is the whole file: the binary, the bare root and one row per command key.
+type Spec struct {
+	Binary   string `yaml:"binary"`
+	Command  string `yaml:"command"`
+	Root     Row    `yaml:"root"`
+	Commands []Row  `yaml:"commands"`
+}
+
+var (
+	sideEffects = map[string]bool{"read": true, "write": true, "remote": true, "destructive": true}
+	outputs     = map[string]bool{"document": true, "stream": true, "interactive": true}
+	jsonKinds   = map[string]bool{"envelope": true, "none": true, "legacy": true}
+	flagTypes   = map[string]bool{"bool": true, "string": true, "int": true, "duration": true, "stringSlice": true}
+)
+
+// Parse decodes and validates a spec.
+func Parse(b []byte) (*Spec, error) {
+	dec := yaml.NewDecoder(bytes.NewReader(b))
+	dec.KnownFields(true)
+	var s Spec
+	if err := dec.Decode(&s); err != nil {
+		return nil, fmt.Errorf("surface spec: %w", err)
+	}
+	if problems := s.Problems(); len(problems) != 0 {
+		return nil, fmt.Errorf("surface spec: %s", strings.Join(problems, "; "))
+	}
+	return &s, nil
+}
+
+// Problems lists every rule a spec breaks, sorted.
+func (s *Spec) Problems() []string {
+	var out []string
+	if s.Binary == "" || s.Command == "" {
+		out = append(out, "binary and command are required")
+	}
+	if s.Root.Path != "" {
+		out = append(out, "root: must not have a path")
+	}
+	out = append(out, rowProblems("root", s.Root)...)
+	seen := map[string]bool{}
+	for _, r := range s.Commands {
+		if r.Path == "" {
+			out = append(out, "a command row has no path")
+			continue
+		}
+		if seen[r.Path] {
+			out = append(out, r.Path+": duplicate row")
+		}
+		seen[r.Path] = true
+		out = append(out, rowProblems(r.Path, r)...)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func rowProblems(name string, r Row) []string {
+	var out []string
+	add := func(f string, a ...any) { out = append(out, name+": "+fmt.Sprintf(f, a...)) }
+	if strings.TrimSpace(r.Summary) == "" {
+		add("summary is required")
+	}
+	if !sideEffects[r.SideEffect] {
+		add("side_effect %q is not read|write|remote|destructive", r.SideEffect)
+	}
+	if !outputs[r.Output] {
+		add("output %q is not document|stream|interactive", r.Output)
+	}
+	if !jsonKinds[r.JSON] {
+		add("json %q is not envelope|none|legacy", r.JSON)
+	}
+	if r.Surface != "" && r.Surface != "all" && r.Surface != "cli-only" {
+		add("surface %q is not all|cli-only", r.Surface)
+	}
+	cliOnly := r.Surface == "cli-only"
+	if r.Output == "interactive" && !cliOnly {
+		add("an interactive command must be surface cli-only")
+	}
+	if (r.SideEffect == "remote" || r.SideEffect == "destructive") && r.JSON == "envelope" && r.Confirm == nil && !cliOnly {
+		add("a %s command exposed on a machine surface needs a confirm block", r.SideEffect)
+	}
+	if r.Confirm != nil && r.SideEffect != "remote" && r.SideEffect != "destructive" {
+		add("confirm is only for remote or destructive commands")
+	}
+	names := map[string]bool{}
+	for _, f := range r.Flags {
+		switch {
+		case f.Name == "":
+			add("a flag has no name")
+		case names[f.Name]:
+			add("flag %s is declared twice", f.Name)
+		case !flagTypes[f.Type]:
+			add("flag %s: type %q is not bool|string|int|duration|stringSlice", f.Name, f.Type)
+		}
+		names[f.Name] = true
+	}
+	if r.Confirm != nil {
+		for _, c := range r.Confirm.Flags {
+			if !names[c] {
+				add("confirm flag %s is not a declared flag", c)
+			}
+		}
+	}
+	return out
+}
diff --git a/free/ci/tools/refgen/codes.go b/free/ci/tools/refgen/codes.go
new file mode 100644
index 000000000..006d45301
--- /dev/null
+++ b/free/ci/tools/refgen/codes.go
@@ -0,0 +1,191 @@
+package main
+
+// Purpose: the registries of Reference.md read from source: error codes
+// (every model.Code literal), doctor check ids (every CI-D… string) and
+// reason codes (every string constant of a type named *Reason).
+// Inputs:  the parsed module.
+// Outputs: sorted rows; an error for a code literal whose ID cannot be read.
+// Constraints: the scan covers packages cmd does not link yet, so a code is
+// documented the day it is registered.
+
+import (
+	"fmt"
+	"go/ast"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// modelPath is the import path of the package that declares Code.
+const modelPath = modulePath + "/internal/model"
+
+// ErrorCode is one registered error code.
+type ErrorCode struct {
+	ID, Class, Summary, Fix, Package string
+}
+
+// DoctorCheck is one doctor check id and the name it is reported under.
+type DoctorCheck struct {
+	ID, Name, Package string
+}
+
+// ReasonCode is one reason constant and the type that holds it.
+type ReasonCode struct {
+	Value, Type, Package string
+}
+
+// doctorID matches a doctor check id.
+var doctorID = regexp.MustCompile(`^CI-D[A-Z]*[0-9]+$`)
+
+// shortPkg trims the module path from an import path.
+func shortPkg(path string) string {
+	if path == modulePath {
+		return "."
+	}
+	return strings.TrimPrefix(path, modulePath+"/")
+}
+
+// isCodeType reports whether t names model.Code from file f of package p.
+func isCodeType(p *pkg, f *srcFile, t ast.Expr) bool {
+	switch x := t.(type) {
+	case *ast.Ident:
+		return p.path == modelPath && x.Name == "Code"
+	case *ast.SelectorExpr:
+		id, ok := x.X.(*ast.Ident)
+		return ok && x.Sel.Name == "Code" && f.imports[id.Name] == modelPath
+	}
+	return false
+}
+
+// errorCodes returns every model.Code literal of the module.
+func errorCodes(m *module) ([]ErrorCode, error) {
+	var out []ErrorCode
+	var problems []string
+	for _, p := range m.sortedPkgs() {
+		for _, f := range p.files {
+			ast.Inspect(f.ast, func(n ast.Node) bool {
+				cl, ok := n.(*ast.CompositeLit)
+				if !ok {
+					return true
+				}
+				var lits []*ast.CompositeLit
+				if isCodeType(p, f, cl.Type) {
+					lits = append(lits, cl)
+				} else if at, ok := cl.Type.(*ast.ArrayType); ok && isCodeType(p, f, at.Elt) {
+					for _, el := range cl.Elts {
+						if sub, ok := el.(*ast.CompositeLit); ok && sub.Type == nil {
+							lits = append(lits, sub)
+						}
+					}
+				}
+				for _, lit := range lits {
+					c, ok := codeOf(m, p, f, lit)
+					if !ok {
+						problems = append(problems, shortPkg(p.path)+": unresolved code literal")
+						continue
+					}
+					out = append(out, c)
+				}
+				return true
+			})
+		}
+	}
+	if len(problems) > 0 {
+		return nil, fmt.Errorf("%s", strings.Join(problems, "; "))
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out, nil
+}
+
+// codeOf reads one Code literal, keyed or positional. Only the ID must
+// resolve; a text field built at run time is left empty.
+func codeOf(m *module, p *pkg, f *srcFile, cl *ast.CompositeLit) (ErrorCode, bool) {
+	c := ErrorCode{Package: shortPkg(p.path)}
+	dst := map[string]*string{"ID": &c.ID, "Class": &c.Class, "Summary": &c.Summary, "Fix": &c.Fix}
+	order := []string{"ID", "Class", "Summary", "Fix"}
+	for i, el := range cl.Elts {
+		name, val := "", el
+		if kv, ok := el.(*ast.KeyValueExpr); ok {
+			if k, ok := kv.Key.(*ast.Ident); ok {
+				name, val = k.Name, kv.Value
+			}
+		} else if i < len(order) {
+			name = order[i]
+		}
+		if d, ok := dst[name]; ok {
+			*d, _ = m.str(p, f, val, nil)
+		}
+	}
+	return c, c.ID != ""
+}
+
+// doctorChecks returns every doctor check id of the module, with the Name of
+// the literal that sets it when there is one.
+func doctorChecks(m *module) []DoctorCheck {
+	seen := map[string]DoctorCheck{}
+	add := func(id, name, pkgPath string) {
+		have, ok := seen[id]
+		if !ok || (have.Name == "" && name != "") {
+			seen[id] = DoctorCheck{ID: id, Name: name, Package: shortPkg(pkgPath)}
+		}
+	}
+	for _, p := range m.sortedPkgs() {
+		for name := range p.consts {
+			if v, ok := m.constValue(p.path, name); ok && doctorID.MatchString(v) {
+				add(v, "", p.path)
+			}
+		}
+		for _, f := range p.files {
+			ast.Inspect(f.ast, func(n ast.Node) bool {
+				switch x := n.(type) {
+				case *ast.CompositeLit:
+					fs := fields(x)
+					if e, ok := fs["ID"]; ok {
+						if id, ok := m.str(p, f, e, nil); ok && doctorID.MatchString(id) {
+							label, _ := m.str(p, f, fs["Name"], nil)
+							add(id, label, p.path)
+						}
+					}
+				case *ast.BasicLit:
+					if v, ok := m.str(p, f, x, nil); ok && doctorID.MatchString(v) {
+						add(v, "", p.path)
+					}
+				}
+				return true
+			})
+		}
+	}
+	out := make([]DoctorCheck, 0, len(seen))
+	for _, c := range seen {
+		out = append(out, c)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out
+}
+
+// reasonCodes returns every string constant whose declared type name ends
+// in Reason.
+func reasonCodes(m *module) []ReasonCode {
+	var out []ReasonCode
+	for _, p := range m.sortedPkgs() {
+		for name, def := range p.consts {
+			if !strings.HasSuffix(def.typeName, "Reason") {
+				continue
+			}
+			if v, ok := m.constValue(p.path, name); ok {
+				out = append(out, ReasonCode{Value: v, Type: def.typeName, Package: shortPkg(p.path)})
+			}
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		a, b := out[i], out[j]
+		if a.Package != b.Package {
+			return a.Package < b.Package
+		}
+		if a.Type != b.Type {
+			return a.Type < b.Type
+		}
+		return a.Value < b.Value
+	})
+	return out
+}
diff --git a/free/ci/tools/refgen/commands.go b/free/ci/tools/refgen/commands.go
new file mode 100644
index 000000000..69f71446a
--- /dev/null
+++ b/free/ci/tools/refgen/commands.go
@@ -0,0 +1,176 @@
+package main
+
+// Purpose: the command list of Reference.md: every key the cmd package
+// registers (register for v1.4, registerV15 for v1.5) merged with the
+// commands block of plugin.json.
+// Inputs:  the parsed cmd package; plugin.json.
+// Outputs: Command rows sorted by key.
+// Constraints: a key built in a range loop is expanded over the loop's
+// literal list; the side-effect class comes from the table entry
+// (SideEffect field, or the class field of the loop item), then from
+// plugin.json. A key the scanner cannot resolve is an error, never skipped.
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/ast"
+	"os"
+	"sort"
+	"strings"
+)
+
+// Command is one row of the command table.
+type Command struct {
+	Key        string
+	Surface    string
+	SideEffect string
+	Summary    string
+	Files      []string // cmd files that register the key
+}
+
+// manifestCommand is one subcommand of the plugin.json commands block.
+type manifestCommand struct {
+	Name        string            `json:"name"`
+	Summary     string            `json:"summary"`
+	SideEffect  string            `json:"side_effect"`
+	Subcommands []manifestCommand `json:"subcommands"`
+}
+
+// manifest is the part of plugin.json the reference uses.
+type manifest struct {
+	Version  string            `json:"version"`
+	Requires map[string]string `json:"requires"`
+	Commands struct {
+		Binary      string            `json:"binary"`
+		Command     string            `json:"command"`
+		SideEffect  string            `json:"side_effect"`
+		Summary     string            `json:"summary"`
+		Subcommands []manifestCommand `json:"subcommands"`
+	} `json:"commands"`
+}
+
+// readManifest decodes plugin.json.
+func readManifest(path string) (manifest, error) {
+	var mf manifest
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return mf, err
+	}
+	return mf, json.Unmarshal(b, &mf)
+}
+
+// manifestIndex flattens the commands block by space-joined key.
+func manifestIndex(subs []manifestCommand, prefix string, out map[string]manifestCommand) {
+	for _, s := range subs {
+		key := prefix + s.Name
+		out[key] = s
+		manifestIndex(s.Subcommands, key+" ", out)
+	}
+}
+
+// commands returns every registered command of the cmd package.
+func commands(m *module, mf manifest) ([]Command, error) {
+	p := m.pkgs[modulePath+"/cmd"]
+	if p == nil {
+		return nil, fmt.Errorf("cmd package not found")
+	}
+	byKey := map[string]*Command{}
+	var problems []string
+	for _, f := range p.files {
+		f := f
+		w := walker{m: m, p: p, f: f}
+		w.walk(f.ast, nil, nil, func(call *ast.CallExpr, env map[string][]string, item map[string]string) {
+			fn, ok := call.Fun.(*ast.Ident)
+			if !ok || len(call.Args) != 2 {
+				return
+			}
+			prefix, sub := subPrefix[fn.Name]
+			if fn.Name != "register" && fn.Name != "registerV15" && !sub {
+				return
+			}
+			keys := m.strs(p, f, call.Args[0], env)
+			for i := range keys {
+				keys[i] = prefix + keys[i]
+			}
+			if len(keys) == 0 {
+				problems = append(problems, fmt.Sprintf("%s: %s: unresolved command key", f.name, fn.Name))
+				return
+			}
+			for _, key := range keys {
+				c := byKey[key]
+				if c == nil {
+					c = &Command{Key: key}
+					byKey[key] = c
+				}
+				c.Files = addOnce(c.Files, f.name)
+				if fn.Name == "register" {
+					c.Surface = joinSurface(c.Surface, "v1.4")
+					continue
+				}
+				if sub {
+					c.Surface = joinSurface(c.Surface, "v1.5")
+					continue
+				}
+				surface, effect := "v1.5", ""
+				if cl, ok := call.Args[1].(*ast.CompositeLit); ok {
+					fs := fields(cl)
+					if isTrue(fs["Hidden"]) {
+						surface = "v1.5 (hidden)"
+					}
+					if e, ok := fs["SideEffect"]; ok {
+						effect, _ = m.str(p, f, e, env)
+					}
+				}
+				if effect == "" {
+					effect = item["class"]
+				}
+				c.Surface = joinSurface(c.Surface, surface)
+				if effect != "" {
+					c.SideEffect = effect
+				}
+			}
+		})
+	}
+	if len(problems) > 0 {
+		return nil, fmt.Errorf("%v", problems)
+	}
+	idx := map[string]manifestCommand{}
+	manifestIndex(mf.Commands.Subcommands, "", idx)
+	out := make([]Command, 0, len(byKey))
+	for _, c := range byKey {
+		if mc, ok := idx[c.Key]; ok {
+			c.Summary = mc.Summary
+			if c.SideEffect == "" {
+				c.SideEffect = mc.SideEffect
+			}
+		}
+		out = append(out, *c)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key })
+	return out, nil
+}
+
+// joinSurface adds s to the comma list have, once.
+func joinSurface(have, s string) string {
+	switch {
+	case have == "":
+		return s
+	case strings.Contains(", "+have+", ", ", "+s+", "):
+		return have
+	}
+	return have + ", " + s
+}
+
+// subPrefix maps the helpers that register one sub-verb of a v1.5 verb to
+// the verb they extend: registerRunsSub("approve", h) is "runs approve".
+var subPrefix = map[string]string{"registerRunsSub": "runs ", "registerArtifactsSub": "artifacts "}
+
+// addOnce appends s to list when it is not there.
+func addOnce(list []string, s string) []string {
+	for _, v := range list {
+		if v == s {
+			return list
+		}
+	}
+	return append(list, s)
+}
diff --git a/free/ci/tools/refgen/evidence.go b/free/ci/tools/refgen/evidence.go
new file mode 100644
index 000000000..e7e3fb453
--- /dev/null
+++ b/free/ci/tools/refgen/evidence.go
@@ -0,0 +1,116 @@
+package main
+
+// Purpose: the evidence field tables of Evidence-and-Machine-Output.md,
+// built by reflection over model.Evidence so a new field shows up the next
+// time the generator runs.
+// Inputs:  the model.Evidence type; the closed value lists of model.
+// Outputs: one Markdown table per struct, the root first, nested structs in
+// first-use order.
+// Constraints: a field is required unless its json tag has omitempty; a
+// field of a closed-list type lists its allowed values.
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+)
+
+// evidenceTables renders the field tables of the evidence document.
+func evidenceTables() string {
+	var b strings.Builder
+	queue := []reflect.Type{reflect.TypeOf(model.Evidence{})}
+	seen := map[reflect.Type]bool{queue[0]: true}
+	for len(queue) > 0 {
+		t := queue[0]
+		queue = queue[1:]
+		title := "`" + t.Name() + "`"
+		if t.Name() == "Evidence" {
+			title = "Evidence document (root)"
+		}
+		fmt.Fprintf(&b, "#### %s\n\n| Field | Type | Required | Values |\n|---|---|---|---|\n", title)
+		for i := 0; i < t.NumField(); i++ {
+			f := t.Field(i)
+			name, opts, _ := strings.Cut(f.Tag.Get("json"), ",")
+			if name == "-" || !f.IsExported() {
+				continue
+			}
+			if name == "" {
+				name = f.Name
+			}
+			required := "yes"
+			if strings.Contains(opts, "omitempty") {
+				required = "no"
+			}
+			fmt.Fprintf(&b, "| `%s` | %s | %s | %s |\n", name, typeText(f.Type), required, valuesText(f.Type))
+			if st := structOf(f.Type); st != nil && !seen[st] {
+				seen[st] = true
+				queue = append(queue, st)
+			}
+		}
+		b.WriteString("\n")
+	}
+	return strings.TrimSuffix(b.String(), "\n")
+}
+
+// structOf returns the model struct t holds directly or as an element, or nil.
+func structOf(t reflect.Type) reflect.Type {
+	for t.Kind() == reflect.Pointer || t.Kind() == reflect.Slice || t.Kind() == reflect.Map {
+		t = t.Elem()
+	}
+	if t.Kind() == reflect.Struct && t.PkgPath() == modelPath {
+		return t
+	}
+	return nil
+}
+
+// typeText is the JSON-facing type of t.
+func typeText(t reflect.Type) string {
+	switch t.Kind() {
+	case reflect.Pointer:
+		return typeText(t.Elem()) + " or null"
+	case reflect.Slice:
+		if t.Elem().Kind() == reflect.Uint8 {
+			return "string (base64)"
+		}
+		return "list of " + typeText(t.Elem())
+	case reflect.Map:
+		return "map of " + typeText(t.Elem())
+	case reflect.Struct:
+		if t.PkgPath() == modelPath {
+			return "`" + t.Name() + "`"
+		}
+		if t.String() == "time.Time" {
+			return "timestamp"
+		}
+		return "object"
+	case reflect.String:
+		return "string"
+	case reflect.Bool:
+		return "boolean"
+	case reflect.Float32, reflect.Float64:
+		return "number"
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
+		reflect.Uint, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return "integer"
+	case reflect.Interface:
+		return "any"
+	}
+	return t.Kind().String()
+}
+
+// valuesText lists the closed values of a model string type, or "".
+func valuesText(t reflect.Type) string {
+	for t.Kind() == reflect.Pointer || t.Kind() == reflect.Slice {
+		t = t.Elem()
+	}
+	if t.Kind() != reflect.String || t.PkgPath() != modelPath {
+		return ""
+	}
+	vals := model.EnumValues(t.Name())
+	if len(vals) == 0 {
+		return ""
+	}
+	return "`" + strings.Join(vals, "`, `") + "`"
+}
diff --git a/free/ci/tools/refgen/flags.go b/free/ci/tools/refgen/flags.go
new file mode 100644
index 000000000..23e2cd7f5
--- /dev/null
+++ b/free/ci/tools/refgen/flags.go
@@ -0,0 +1,219 @@
+package main
+
+// Purpose: the flag table of Reference.md: every flag name the cmd package
+// defines on a FlagSet, with the commands it belongs to.
+// Inputs:  the parsed cmd package and the command rows.
+// Outputs: Markdown table rows sorted by flag.
+// Constraints: a flag belongs to the commands registered in the same file;
+// a file that registers none (providers_authorize.go) falls back to the
+// commands whose first word is the file name up to its first underscore.
+// A flag name that is not a string literal or constant is an error.
+
+import (
+	"fmt"
+	"go/ast"
+	"sort"
+	"strings"
+)
+
+// flagDefs maps a FlagSet method to the index of its name argument.
+var flagDefs = map[string]int{
+	"Bool": 0, "String": 0, "Int": 0, "Int64": 0, "Uint": 0, "Float64": 0, "Duration": 0,
+	"Func": 0, "BoolFunc": 0,
+	"BoolVar": 1, "StringVar": 1, "IntVar": 1, "Int64Var": 1, "UintVar": 1, "Float64Var": 1, "DurationVar": 1, "Var": 1,
+}
+
+// FlagRow is one flag and the commands that take it.
+type FlagRow struct {
+	Name     string
+	Commands []string
+}
+
+// flagPackages lists the packages outside cmd that define flags of a verb,
+// with the verb that owns them: `nodes add` builds its FlagSet in
+// internal/nodes/lifecycle, and serve flags are added by packages through
+// coordinator.RegisterFlag. TestNoFlagDefinedOutsideScannedPackages fails
+// when another package defines a flag, so a flag is never silently omitted.
+var flagPackages = map[string]string{
+	modulePath + "/internal/nodes/lifecycle":   "nodes",
+	modulePath + "/internal/coordinator/drain": "serve",
+	modulePath + "/internal/config":            "config",
+	modulePath + "/internal/doctor":            "doctor",
+	modulePath + "/internal/discovery":         "nodes discover",
+}
+
+// listenerVerb owns every flag registered with coordinator.RegisterListener:
+// the listener flags are serve flags whichever file registers them.
+const listenerVerb = "serve"
+
+// fileFlagNames returns the flag names a file defines on a FlagSet.
+func fileFlagNames(m *module, p *pkg, f *srcFile) ([]string, error) {
+	var names []string
+	var bad error
+	ast.Inspect(f.ast, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok {
+			return true
+		}
+		i, ok := flagDefs[sel.Sel.Name]
+		if !ok || len(call.Args) <= i || len(call.Args) < 2 {
+			return true
+		}
+		name, ok := m.str(p, f, call.Args[i], nil)
+		if !ok {
+			if _, lit := call.Args[i].(*ast.BasicLit); lit {
+				bad = fmt.Errorf("%s: flag name not resolvable", f.name)
+			}
+			return true
+		}
+		names = append(names, name)
+		return true
+	})
+	return names, bad
+}
+
+// listenerFlagNames returns the flag names a file registers through
+// RegisterListener(name, flag, ...), expanding a range over a literal list
+// (`for _, l := range []struct{...}{...} { RegisterListener(l.name, l.flag, ...) }`).
+// A flag name it cannot resolve is an error: the table would silently lose a flag.
+func listenerFlagNames(m *module, p *pkg, f *srcFile) ([]string, error) {
+	var names []string
+	var bad error
+	w := walker{m: m, p: p, f: f}
+	w.walk(f.ast, nil, nil, func(call *ast.CallExpr, env map[string][]string, it map[string]string) {
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "RegisterListener" || len(call.Args) < 2 {
+			return
+		}
+		got := m.strs(p, f, call.Args[1], env)
+		if s, ok := call.Args[1].(*ast.SelectorExpr); ok && len(got) == 0 {
+			if v, ok := it[s.Sel.Name]; ok {
+				got = []string{v}
+			}
+		}
+		if len(got) == 0 {
+			bad = fmt.Errorf("%s: RegisterListener flag name not resolvable", f.name)
+			return
+		}
+		names = append(names, got...)
+	})
+	return names, bad
+}
+
+// ownersOfVerb returns the keys of the commands that are verb or start with it.
+func ownersOfVerb(cmds []Command, verb string) []string {
+	var out []string
+	for _, c := range cmds {
+		if c.Key == verb || strings.HasPrefix(c.Key, verb+" ") {
+			out = append(out, c.Key)
+		}
+	}
+	return out
+}
+
+// flagRows returns the flags of the cmd package and of flagPackages, sorted by name.
+func flagRows(m *module, cmds []Command) ([]FlagRow, error) {
+	p := m.pkgs[modulePath+"/cmd"]
+	if p == nil {
+		return nil, fmt.Errorf("cmd package not found")
+	}
+	byFile := map[string][]string{}
+	for _, c := range cmds {
+		for _, f := range c.Files {
+			byFile[f] = append(byFile[f], c.Key)
+		}
+	}
+	got := map[string]map[string]bool{}
+	add := func(name string, owners []string) {
+		if got[name] == nil {
+			got[name] = map[string]bool{}
+		}
+		for _, o := range owners {
+			got[name][o] = true
+		}
+	}
+	serve := ownersOfVerb(cmds, listenerVerb)
+	for _, f := range p.files {
+		owners := byFile[f.name]
+		if len(owners) == 0 {
+			stem := strings.TrimSuffix(f.name, ".go")
+			if i := strings.Index(stem, "_"); i > 0 {
+				stem = stem[:i]
+			}
+			for _, c := range cmds {
+				if c.Key == stem || strings.HasPrefix(c.Key, stem+" ") {
+					owners = append(owners, c.Key)
+				}
+			}
+		}
+		names, err := fileFlagNames(m, p, f)
+		if err != nil {
+			return nil, err
+		}
+		for _, n := range names {
+			add(n, owners)
+		}
+		if names, err = listenerFlagNames(m, p, f); err != nil {
+			return nil, err
+		}
+		for _, n := range names {
+			add(n, serve)
+		}
+	}
+	for path, verb := range flagPackages {
+		ep := m.pkgs[path]
+		if ep == nil {
+			return nil, fmt.Errorf("flag package %s not found", path)
+		}
+		owners := ownersOfVerb(cmds, verb)
+		for _, f := range ep.files {
+			names, err := fileFlagNames(m, ep, f)
+			if err != nil {
+				return nil, err
+			}
+			for _, n := range names {
+				add(n, owners)
+			}
+		}
+	}
+	var out []FlagRow
+	for n, set := range got {
+		r := FlagRow{Name: n}
+		for k := range set {
+			r.Commands = append(r.Commands, k)
+		}
+		r.Commands = collapse(r.Commands)
+		out = append(out, r)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, nil
+}
+
+// collapse shortens a command list: when a flag belongs to more than one
+// command of a verb, the verb is written once as `verb *`, because the flag
+// is shared by the file, not proven for every sub-verb.
+func collapse(keys []string) []string {
+	count := map[string]int{}
+	for _, k := range keys {
+		count[strings.Fields(k)[0]]++
+	}
+	seen := map[string]bool{}
+	var out []string
+	for _, k := range keys {
+		v := strings.Fields(k)[0]
+		e := k
+		if count[v] > 1 {
+			e = v + " *"
+		}
+		if !seen[e] {
+			seen[e] = true
+			out = append(out, e)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
diff --git a/free/ci/tools/refgen/flags_test.go b/free/ci/tools/refgen/flags_test.go
new file mode 100644
index 000000000..25ab02cdf
--- /dev/null
+++ b/free/ci/tools/refgen/flags_test.go
@@ -0,0 +1,147 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestReferenceListsListenerAndPackageFlags fails when a flag that is not a
+// FlagSet call in the cmd package is left out of Reference.md: the serve
+// listener flags (coordinator.RegisterListener, one of them from a literal
+// table) and the `nodes add` flags defined in internal/nodes/lifecycle.
+func TestReferenceListsListenerAndPackageFlags(t *testing.T) {
+	out, err := generate(filepath.Join("..", "..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref := string(out[referencePage])
+	for _, row := range []string{
+		"| `--agent-addr` | `serve *` |",
+		"| `--api-addr` | `serve *` |",
+		"| `--api-socket` | `serve *` |",
+		"| `--agent-binary` | `nodes *` |",
+		"| `--drain-deadline` | `serve *` |",
+	} {
+		if !strings.Contains(ref, row) {
+			t.Errorf("Reference.md has no row %s", row)
+		}
+	}
+}
+
+// unmappedFlagPackages are packages whose flags Reference.md does not list yet,
+// with the reason. The agent binary and the bench and helper tools are not
+// `nself ci` commands; the rest need an owner mapping decided by the CI wiki
+// owner (found by P7-AUTO-13/generator-gaps work, reported, not guessed).
+var unmappedFlagPackages = map[string]string{
+	"bench/cache/cmd/cachebench":        "benchmark tool, not a nself ci command",
+	"bench/cmd/cibench":                 "benchmark tool, not a nself ci command",
+	"bench/cmd/schedbench":              "benchmark tool, not a nself ci command",
+	"cmd/agent":                         "the nself-ci-agent binary has its own CLI",
+	"internal/agent/update":             "agent upgrade CLI (nself-ci-agent)",
+	"internal/gates/truth":              "gate helper CLI; owner command not mapped",
+	"internal/providers/github/jit":     "runner mint flags; owner command not mapped",
+	"internal/providers/gitlab/runners": "runner mint flags; owner command not mapped",
+}
+
+// TestNoFlagDefinedOutsideScannedPackages fails when a package that flagRows
+// does not read defines a flag, so a new flag cannot be left out silently:
+// add the package to flagPackages (or read its registration in cmd).
+func TestNoFlagDefinedOutsideScannedPackages(t *testing.T) {
+	m, err := loadModule(filepath.Join("..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range m.sortedPkgs() {
+		if p.path == modulePath+"/cmd" || strings.HasPrefix(p.path, modulePath+"/tools/") {
+			continue
+		}
+		if _, ok := flagPackages[p.path]; ok {
+			continue
+		}
+		if _, ok := unmappedFlagPackages[strings.TrimPrefix(p.path, modulePath+"/")]; ok {
+			continue
+		}
+		for _, f := range p.files {
+			names, err := fileFlagNames(m, p, f)
+			if err != nil {
+				t.Fatal(err)
+			}
+			listeners, err := listenerFlagNames(m, p, f)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got := append(names, listeners...); len(got) > 0 {
+				t.Errorf("%s/%s defines flags %v that refgen does not read: add the package to flagPackages", p.path, f.name, got)
+			}
+		}
+	}
+}
+
+// noPackages empties flagPackages for a test over a module that has none of them.
+func noPackages(t *testing.T) {
+	t.Helper()
+	was := flagPackages
+	flagPackages = map[string]string{}
+	t.Cleanup(func() { flagPackages = was })
+}
+
+// fakeModule loads a one-file cmd package from src.
+func fakeModule(t *testing.T, src string) *module {
+	t.Helper()
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "cmd"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "cmd", "serve_x.go"), []byte(src), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	m, err := loadModule(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestListenerFlagsFromLiteralAndTable(t *testing.T) {
+	noPackages(t)
+	m := fakeModule(t, `package cmd
+
+import "x/coordinator"
+
+func init() {
+	coordinator.RegisterListener("a", "a-addr", ":1", nil)
+	for _, l := range []struct{ name, flag, def string }{{"b", "b-addr", ":2"}, {"c", "c-sock", "auto"}} {
+		coordinator.RegisterListener(l.name, l.flag, l.def, nil)
+	}
+}
+`)
+	cmds := []Command{{Key: "serve", Files: []string{"serve_x.go"}}, {Key: "serve install"}}
+	rows, err := flagRows(m, cmds)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]string{}
+	for _, r := range rows {
+		got[r.Name] = strings.Join(r.Commands, ",")
+	}
+	for _, n := range []string{"a-addr", "b-addr", "c-sock"} {
+		if got[n] != "serve *" {
+			t.Errorf("flag %s = %q, want serve *", n, got[n])
+		}
+	}
+}
+
+func TestUnresolvableListenerFlagIsAnError(t *testing.T) {
+	noPackages(t)
+	m := fakeModule(t, `package cmd
+
+import "x/coordinator"
+
+func init() { coordinator.RegisterListener("a", flagName(), ":1", nil) }
+`)
+	if _, err := flagRows(m, []Command{{Key: "serve", Files: []string{"serve_x.go"}}}); err == nil {
+		t.Fatal("a listener flag that cannot be resolved was skipped")
+	}
+}
diff --git a/free/ci/tools/refgen/main.go b/free/ci/tools/refgen/main.go
new file mode 100644
index 000000000..7c9aaf7fe
--- /dev/null
+++ b/free/ci/tools/refgen/main.go
@@ -0,0 +1,145 @@
+// Command refgen generates the CI wiki reference from the code of free/ci:
+// guides/ci/Reference.md (commands, exit codes, error codes, reason codes,
+// doctor ids, pinned versions), the evidence field tables of
+// guides/ci/Evidence-and-Machine-Output.md, the trust reasons table of
+// guides/ci/Trust-Security-and-Privacy.md and the guides/ci block of
+// _Sidebar.md.
+//
+// Usage: go generate ./tools/refgen/... (from free/ci), or
+// go run ./tools/refgen [-root DIR] [-check].
+// Exit codes: 0 written or unchanged, 1 failed or (with -check) drift, 2 usage.
+package main
+
+//go:generate go run -mod=vendor . -root ../../../..
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/nself-org/plugins/free/ci/internal/toolchain"
+)
+
+// Paths of the generated files, relative to the plugins repository root.
+const (
+	referencePage = ".github/wiki/guides/ci/Reference.md"
+	evidencePage  = ".github/wiki/guides/ci/Evidence-and-Machine-Output.md"
+	trustPage     = ".github/wiki/guides/ci/Trust-Security-and-Privacy.md"
+	sidebarPage   = ".github/wiki/_Sidebar.md"
+	guidesDir     = ".github/wiki/guides/ci"
+	ciDir         = "free/ci"
+)
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+// run parses flags, generates and writes (or checks) the files.
+func run(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("refgen", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	root := fs.String("root", "../../../..", "plugins repository root")
+	check := fs.Bool("check", false, "report drift instead of writing")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	out, err := generate(*root)
+	if err != nil {
+		fmt.Fprintln(stderr, "refgen:", err)
+		return 1
+	}
+	status := 0
+	for _, rel := range []string{referencePage, evidencePage, schedulingPage, trustPage, sidebarPage} {
+		path := filepath.Join(*root, rel)
+		have, _ := os.ReadFile(path)
+		if bytes.Equal(have, out[rel]) {
+			continue
+		}
+		if *check {
+			fmt.Fprintf(stdout, "%s: out of date; run go generate ./tools/refgen/...\n", rel)
+			status = 1
+			continue
+		}
+		if err := os.WriteFile(path, out[rel], 0o644); err != nil {
+			fmt.Fprintln(stderr, "refgen:", err)
+			return 1
+		}
+		fmt.Fprintf(stdout, "wrote %s\n", rel)
+	}
+	return status
+}
+
+// generate returns the content every generated file should have, by path
+// relative to root.
+func generate(root string) (map[string][]byte, error) {
+	m, err := loadModule(filepath.Join(root, ciDir))
+	if err != nil {
+		return nil, err
+	}
+	mf, err := readManifest(filepath.Join(root, ciDir, "plugin.json"))
+	if err != nil {
+		return nil, err
+	}
+	d := refData{manifest: mf, reasons: reasonCodes(m), doctor: doctorChecks(m)}
+	if d.commands, err = commands(m, mf); err != nil {
+		return nil, err
+	}
+	if d.flags, err = flagRows(m, d.commands); err != nil {
+		return nil, err
+	}
+	if d.codes, err = errorCodes(m); err != nil {
+		return nil, err
+	}
+	v, err := toolchain.Embedded()
+	if err != nil {
+		return nil, err
+	}
+	d.pins = v.Rows
+	out := map[string][]byte{referencePage: []byte(renderReference(d))}
+
+	for _, f := range []struct{ rel, name, body string }{
+		{evidencePage, "evidence-fields", evidenceTables()},
+		{trustPage, "trust-reasons", trustReasonsTable()},
+	} {
+		doc, err := os.ReadFile(filepath.Join(root, f.rel))
+		if err != nil {
+			return nil, err
+		}
+		s, err := splice(string(doc), f.name, f.body)
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", f.rel, err)
+		}
+		out[f.rel] = []byte(s)
+	}
+	sdoc, err := os.ReadFile(filepath.Join(root, schedulingPage))
+	if err != nil {
+		return nil, err
+	}
+	ss := string(sdoc)
+	for _, r := range []struct{ name, body string }{
+		{"sched-presets", presetTable()},
+		{"sched-reasons", placementReasonTable(d.reasons)},
+	} {
+		if ss, err = splice(ss, r.name, r.body); err != nil {
+			return nil, fmt.Errorf("%s: %w", schedulingPage, err)
+		}
+	}
+	out[schedulingPage] = []byte(ss)
+	block, err := sidebarBlock(filepath.Join(root, guidesDir))
+	if err != nil {
+		return nil, err
+	}
+	doc, err := os.ReadFile(filepath.Join(root, sidebarPage))
+	if err != nil {
+		return nil, err
+	}
+	s, err := splice(string(doc), "guides-ci", block)
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", sidebarPage, err)
+	}
+	out[sidebarPage] = []byte(s)
+	return out, nil
+}
diff --git a/free/ci/tools/refgen/reference_test.go b/free/ci/tools/refgen/reference_test.go
new file mode 100644
index 000000000..96f087e82
--- /dev/null
+++ b/free/ci/tools/refgen/reference_test.go
@@ -0,0 +1,51 @@
+package main
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestReferenceListsEveryManifestCommandAndFlag fails when a command of
+// plugin.json, a registered sub-verb or a defined flag is missing from the
+// generated Reference.md.
+func TestReferenceListsEveryManifestCommandAndFlag(t *testing.T) {
+	root := filepath.Join("..", "..", "..", "..")
+	out, err := generate(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref := string(out[referencePage])
+	mf, err := readManifest(filepath.Join(root, ciDir, "plugin.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	idx := map[string]manifestCommand{}
+	manifestIndex(mf.Commands.Subcommands, "", idx)
+	for key := range idx {
+		if !strings.Contains(ref, "| `nself ci "+key+"` |") {
+			t.Errorf("command %q is in plugin.json but not in Reference.md", key)
+		}
+	}
+	for _, key := range []string{"runs approve", "runs pending"} {
+		if !strings.Contains(ref, "| `nself ci "+key+"` |") {
+			t.Errorf("sub-verb %q missing from Reference.md", key)
+		}
+	}
+	trust := string(out[trustPage])
+	if !strings.Contains(trust, begin("trust-reasons")) || !strings.Contains(trust, end("trust-reasons")) {
+		t.Error("trust-reasons markers missing from the trust guide")
+	}
+	again, err := generate(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for rel, b := range out {
+		if string(again[rel]) != string(b) {
+			t.Errorf("%s: generation is not deterministic", rel)
+		}
+	}
+	if !strings.Contains(ref, "| `--allow-private` |") {
+		t.Error("flag --allow-private missing from Reference.md")
+	}
+}
diff --git a/free/ci/tools/refgen/render.go b/free/ci/tools/refgen/render.go
new file mode 100644
index 000000000..4be5993a1
--- /dev/null
+++ b/free/ci/tools/refgen/render.go
@@ -0,0 +1,140 @@
+package main
+
+// Purpose: render Reference.md and splice generated regions into authored
+// pages.
+// Inputs:  the rows read from code (commands, codes, reasons, doctor ids),
+// the exit-code table and the toolchain pins.
+// Outputs: page text.
+// Constraints: a region sits between <!-- BEGIN GENERATED:<name> --> and
+// <!-- END GENERATED:<name> -->; a page without the markers is an error, so
+// the generator never guesses where authored text ends.
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/toolchain"
+)
+
+// refData is everything Reference.md shows.
+type refData struct {
+	manifest manifest
+	commands []Command
+	codes    []ErrorCode
+	flags    []FlagRow
+	reasons  []ReasonCode
+	doctor   []DoctorCheck
+	pins     []toolchain.Pin
+}
+
+// begin and end are the region markers of name.
+func begin(name string) string { return "<!-- BEGIN GENERATED:" + name + " -->" }
+func end(name string) string   { return "<!-- END GENERATED:" + name + " -->" }
+
+// region wraps body in the markers of name.
+func region(name, body string) string {
+	return begin(name) + "\n" + strings.TrimRight(body, "\n") + "\n" + end(name) + "\n"
+}
+
+// splice replaces the body of region name in doc.
+func splice(doc, name, body string) (string, error) {
+	b, e := begin(name), end(name)
+	i := strings.Index(doc, b)
+	j := strings.Index(doc, e)
+	if i < 0 || j < i {
+		return "", fmt.Errorf("region %s: markers missing or out of order", name)
+	}
+	return doc[:i] + strings.TrimSuffix(region(name, body), "\n") + doc[j+len(e):], nil
+}
+
+// cell escapes text for a Markdown table cell.
+func cell(s string) string {
+	s = strings.ReplaceAll(s, "|", `\|`)
+	s = strings.ReplaceAll(s, "\n", " ")
+	if s == "" {
+		return "-"
+	}
+	return s
+}
+
+// renderReference renders the whole of Reference.md.
+func renderReference(d refData) string {
+	var b strings.Builder
+	b.WriteString("# CI reference\n\n")
+	b.WriteString("<!-- Generated by `go generate ./tools/refgen/...` in free/ci. Do not edit this page by hand. -->\n\n")
+	b.WriteString("Every table on this page is read from the code of `free/ci`. Change the code, then regenerate the page.\n")
+	b.WriteString("For the flags of one command, run `nself ci <command> --help`.\n\n")
+
+	var t strings.Builder
+	fmt.Fprintf(&t, "## Commands\n\n`nself %s` runs the plugin binary `%s`. A v1.4 command runs without `NSELF_V15`; a v1.5 command needs `NSELF_V15=1`. Hidden commands are reachable but left out of `--help`.\n\n",
+		d.manifest.Commands.Command, d.manifest.Commands.Binary)
+	t.WriteString("| Command | Surface | Side effect | Summary |\n|---|---|---|---|\n")
+	fmt.Fprintf(&t, "| `nself %s` | v1.4, v1.5 | %s | %s |\n", d.manifest.Commands.Command, cell(d.manifest.Commands.SideEffect), cell(d.manifest.Commands.Summary))
+	for _, c := range d.commands {
+		fmt.Fprintf(&t, "| `nself %s %s` | %s | %s | %s |\n", d.manifest.Commands.Command, c.Key, c.Surface, cell(c.SideEffect), cell(c.Summary))
+	}
+	t.WriteString("\n### Flags\n\nA flag is read from the source file that defines it. `verb *` means the flag is shared by the file that registers several sub-verbs of that verb, so it is not proven for every one of them. Run `nself ci <command> --help` for the exact set.\n\n| Flag | Commands |\n|---|---|\n")
+	for _, f := range d.flags {
+		var cs []string
+		for _, k := range f.Commands {
+			cs = append(cs, "`"+k+"`")
+		}
+		fmt.Fprintf(&t, "| `--%s` | %s |\n", f.Name, cell(strings.Join(cs, ", ")))
+	}
+	b.WriteString(region("commands", t.String()) + "\n")
+
+	b.WriteString(region("exit-codes", "## Exit codes\n\n"+model.ExitMarkdown()) + "\n")
+
+	t.Reset()
+	t.WriteString("## Error codes\n\nErrors print as `E<number>: <message>`. The class says who fixes it: `usage` and `code` are yours, `infra` is the machine or the network.\n\n")
+	t.WriteString("| Code | Class | Summary | Fix | Package |\n|---|---|---|---|---|\n")
+	for _, c := range d.codes {
+		fmt.Fprintf(&t, "| %s | %s | %s | %s | `%s` |\n", c.ID, cell(c.Class), cell(c.Summary), cell(c.Fix), c.Package)
+	}
+	b.WriteString(region("error-codes", t.String()) + "\n")
+
+	t.Reset()
+	t.WriteString("## Reason codes\n\nA reason code says why a job was skipped, held or placed where it was. `nself ci explain <job>` prints the reasons of one job.\n\n")
+	t.WriteString("### Job reasons (`model.Reason`)\n\n")
+	for _, r := range model.EnumValues("Reason") {
+		fmt.Fprintf(&t, "- `%s`\n", r)
+	}
+	t.WriteString("\n### Typed reasons\n\n| Reason | Type | Package |\n|---|---|---|\n")
+	for _, r := range d.reasons {
+		fmt.Fprintf(&t, "| `%s` | `%s` | `%s` |\n", r.Value, r.Type, r.Package)
+	}
+	b.WriteString(region("reason-codes", t.String()) + "\n")
+
+	t.Reset()
+	t.WriteString("## Doctor checks\n\n`nself ci doctor` reports each check under its id. `--nodes` and `--providers` add their sections.\n\n")
+	t.WriteString("| Id | Name | Package |\n|---|---|---|\n")
+	for _, c := range d.doctor {
+		fmt.Fprintf(&t, "| %s | %s | `%s` |\n", c.ID, cell(c.Name), c.Package)
+	}
+	b.WriteString(region("doctor-ids", t.String()) + "\n")
+
+	t.Reset()
+	t.WriteString("## Pinned versions\n\n")
+	fmt.Fprintf(&t, "| Pin | Value |\n|---|---|\n| plugin version | %s |\n", cell(d.manifest.Version))
+	for _, k := range sortedKeys(d.manifest.Requires) {
+		fmt.Fprintf(&t, "| requires %s | `%s` |\n", k, d.manifest.Requires[k])
+	}
+	t.WriteString("\nThe toolchain pins, from `free/ci/toolchain/versions.yaml`:\n\n| Name | Kind | Version | Owner |\n|---|---|---|---|\n")
+	for _, p := range d.pins {
+		fmt.Fprintf(&t, "| %s | %s | `%s` | `%s` |\n", p.Name, p.Kind, cell(p.Version), p.Owner)
+	}
+	b.WriteString(region("pinned-versions", t.String()))
+	return b.String()
+}
+
+// sortedKeys returns the keys of m in order.
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
diff --git a/free/ci/tools/refgen/scan.go b/free/ci/tools/refgen/scan.go
new file mode 100644
index 000000000..5f1fc9cde
--- /dev/null
+++ b/free/ci/tools/refgen/scan.go
@@ -0,0 +1,229 @@
+package main
+
+// Purpose: load the non-test Go source of the free/ci module and resolve
+// string constants, so the generator reads commands and codes from code.
+// Inputs:  the module directory.
+// Outputs: one pkg per directory, with its files, imports and string consts.
+// Constraints: vendor, testdata and _test.go files are skipped; only string
+// constants built from literals, other constants and + are resolved.
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// modulePath is the import path of free/ci.
+const modulePath = "github.com/nself-org/plugins/free/ci"
+
+// srcFile is one parsed file and its import table (local name to path).
+type srcFile struct {
+	name    string // base name of the source file
+	ast     *ast.File
+	imports map[string]string
+}
+
+// constDef is one package-level constant before resolution.
+type constDef struct {
+	file     *srcFile
+	expr     ast.Expr
+	typeName string
+}
+
+// pkg is one package of the module.
+type pkg struct {
+	path   string
+	dir    string
+	files  []*srcFile
+	consts map[string]constDef
+}
+
+// module is every package of free/ci, by import path.
+type module struct {
+	pkgs     map[string]*pkg
+	resolved map[string]string
+	busy     map[string]bool
+}
+
+// loadModule parses every non-test Go file under root.
+func loadModule(root string) (*module, error) {
+	m := &module{pkgs: map[string]*pkg{}, resolved: map[string]string{}, busy: map[string]bool{}}
+	fset := token.NewFileSet()
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			if path != root && (d.Name() == "vendor" || d.Name() == "testdata" || strings.HasPrefix(d.Name(), ".")) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		f, err := parser.ParseFile(fset, path, nil, parser.SkipObjectResolution)
+		if err != nil {
+			return err
+		}
+		m.add(root, path, f)
+		return nil
+	})
+	return m, err
+}
+
+// add records file f, read from path, under its package.
+func (m *module) add(root, path string, f *ast.File) {
+	dir := filepath.Dir(path)
+	rel, _ := filepath.Rel(root, dir)
+	ip := modulePath
+	if rel != "." {
+		ip += "/" + filepath.ToSlash(rel)
+	}
+	p := m.pkgs[ip]
+	if p == nil {
+		p = &pkg{path: ip, dir: dir, consts: map[string]constDef{}}
+		m.pkgs[ip] = p
+	}
+	sf := &srcFile{name: filepath.Base(path), ast: f, imports: map[string]string{}}
+	for _, im := range f.Imports {
+		target, _ := strconv.Unquote(im.Path.Value)
+		name := target[strings.LastIndex(target, "/")+1:]
+		if im.Name != nil {
+			name = im.Name.Name
+		}
+		sf.imports[name] = target
+	}
+	p.files = append(p.files, sf)
+	for _, decl := range f.Decls {
+		gd, ok := decl.(*ast.GenDecl)
+		if !ok || gd.Tok != token.CONST {
+			continue
+		}
+		for _, spec := range gd.Specs {
+			vs := spec.(*ast.ValueSpec)
+			typeName := ""
+			if id, ok := vs.Type.(*ast.Ident); ok {
+				typeName = id.Name
+			}
+			for i, n := range vs.Names {
+				if i < len(vs.Values) {
+					p.consts[n.Name] = constDef{file: sf, expr: vs.Values[i], typeName: typeName}
+				}
+			}
+		}
+	}
+}
+
+// sortedPkgs returns the packages in import-path order, so output is stable.
+func (m *module) sortedPkgs() []*pkg {
+	out := make([]*pkg, 0, len(m.pkgs))
+	for _, p := range m.pkgs {
+		out = append(out, p)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].path < out[j].path })
+	return out
+}
+
+// constValue resolves the string constant name of package path.
+func (m *module) constValue(path, name string) (string, bool) {
+	key := path + "." + name
+	if v, ok := m.resolved[key]; ok {
+		return v, true
+	}
+	p := m.pkgs[path]
+	if p == nil || m.busy[key] {
+		return "", false
+	}
+	def, ok := p.consts[name]
+	if !ok {
+		return "", false
+	}
+	m.busy[key] = true
+	v, ok := m.str(p, def.file, def.expr, nil)
+	delete(m.busy, key)
+	if ok {
+		m.resolved[key] = v
+	}
+	return v, ok
+}
+
+// str evaluates e to one string. env holds loop variables that have a
+// single known value; see strs for several.
+func (m *module) str(p *pkg, f *srcFile, e ast.Expr, env map[string][]string) (string, bool) {
+	vals := m.strs(p, f, e, env)
+	if len(vals) != 1 {
+		return "", false
+	}
+	return vals[0], true
+}
+
+// strs evaluates e to every string it can take: a literal, a constant, a
+// loop variable of env, or a + of those (the cross product).
+func (m *module) strs(p *pkg, f *srcFile, e ast.Expr, env map[string][]string) []string {
+	switch x := e.(type) {
+	case *ast.BasicLit:
+		if x.Kind != token.STRING {
+			return nil
+		}
+		s, err := strconv.Unquote(x.Value)
+		if err != nil {
+			return nil
+		}
+		return []string{s}
+	case *ast.ParenExpr:
+		return m.strs(p, f, x.X, env)
+	case *ast.Ident:
+		if vals, ok := env[x.Name]; ok {
+			return vals
+		}
+		if v, ok := m.constValue(p.path, x.Name); ok {
+			return []string{v}
+		}
+	case *ast.SelectorExpr:
+		if id, ok := x.X.(*ast.Ident); ok && f != nil {
+			if target, ok := f.imports[id.Name]; ok {
+				if v, ok := m.constValue(target, x.Sel.Name); ok {
+					return []string{v}
+				}
+			}
+		}
+	case *ast.BinaryExpr:
+		if x.Op != token.ADD {
+			return nil
+		}
+		left, right := m.strs(p, f, x.X, env), m.strs(p, f, x.Y, env)
+		var out []string
+		for _, l := range left {
+			for _, r := range right {
+				out = append(out, l+r)
+			}
+		}
+		return out
+	}
+	return nil
+}
+
+// fields maps the keyed fields of a composite literal to their expressions.
+func fields(cl *ast.CompositeLit) map[string]ast.Expr {
+	out := map[string]ast.Expr{}
+	for _, el := range cl.Elts {
+		if kv, ok := el.(*ast.KeyValueExpr); ok {
+			if id, ok := kv.Key.(*ast.Ident); ok {
+				out[id.Name] = kv.Value
+			}
+		}
+	}
+	return out
+}
+
+// isTrue reports whether e is the identifier true.
+func isTrue(e ast.Expr) bool {
+	id, ok := e.(*ast.Ident)
+	return ok && id.Name == "true"
+}
diff --git a/free/ci/tools/refgen/sched.go b/free/ci/tools/refgen/sched.go
new file mode 100644
index 000000000..cc951be11
--- /dev/null
+++ b/free/ci/tools/refgen/sched.go
@@ -0,0 +1,81 @@
+package main
+
+// Purpose: the generated tables of Scheduling-and-Cost.md: the placement
+// presets and the placement reason codes.
+// Inputs:  sched.Presets (the preset table in code); the reason codes read
+// from the source of free/ci (reasonCodes), so a new constant shows up the
+// next time the generator runs.
+// Outputs: two Markdown tables, each spliced into its region of the page.
+// Constraints: values are rendered from code only; the component and class
+// names below must stay in the order of sched.Preset (a test checks the
+// counts).
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/model"
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+// schedulingPage is the page that holds the scheduling regions.
+const schedulingPage = ".github/wiki/guides/ci/Scheduling-and-Cost.md"
+
+// presetComponents names the score weights of a preset, in sched.Preset order.
+var presetComponents = [9]string{"wait", "runtime", "cold_start", "transfer", "cache", "contention", "cost", "scarcity", "reliability"}
+
+// presetClasses names the class bias entries of a preset, in sched.Preset order.
+var presetClasses = [5]string{"local", "owned", "included", "metered", "ephemeral"}
+
+// presetTable renders every preset: weights per mille, the milliseconds one
+// micro-unit of cost is worth, and the per-class bias in milliseconds.
+func presetTable() string {
+	presets := sched.Presets()
+	names := make([]string, 0, len(presets))
+	for n := range presets {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	var b strings.Builder
+	b.WriteString("| Preset |")
+	for _, c := range presetComponents {
+		fmt.Fprintf(&b, " `%s` |", c)
+	}
+	b.WriteString(" ms per cost micro-unit |")
+	for _, c := range presetClasses {
+		fmt.Fprintf(&b, " bias `%s` (ms) |", c)
+	}
+	b.WriteString("\n|---|" + strings.Repeat("---|", len(presetComponents)+1+len(presetClasses)) + "\n")
+	for _, n := range names {
+		p := presets[n]
+		fmt.Fprintf(&b, "| `%s` |", n)
+		for _, w := range p.Weights {
+			fmt.Fprintf(&b, " %d |", w)
+		}
+		fmt.Fprintf(&b, " %d |", p.MsPerCostMicro)
+		for _, c := range p.ClassBiasMs {
+			fmt.Fprintf(&b, " %d |", c)
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+// placementReasonTable renders every model.PlacementReason with whether it
+// is static (a runner cannot become eligible without a configuration change).
+func placementReasonTable(reasons []ReasonCode) string {
+	var b strings.Builder
+	b.WriteString("| Reason | Clears without a configuration change |\n|---|---|\n")
+	for _, r := range reasons {
+		if r.Type != "PlacementReason" {
+			continue
+		}
+		clears := "yes"
+		if model.PlacementReason(r.Value).Static() {
+			clears = "no (static)"
+		}
+		fmt.Fprintf(&b, "| `%s` | %s |\n", r.Value, clears)
+	}
+	return b.String()
+}
diff --git a/free/ci/tools/refgen/sched_test.go b/free/ci/tools/refgen/sched_test.go
new file mode 100644
index 000000000..e2dd97464
--- /dev/null
+++ b/free/ci/tools/refgen/sched_test.go
@@ -0,0 +1,35 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/sched"
+)
+
+func TestPresetTableCoversEveryPreset(t *testing.T) {
+	got := presetTable()
+	for name := range sched.Presets() {
+		if !strings.Contains(got, "| `"+name+"` |") {
+			t.Errorf("preset %s missing", name)
+		}
+	}
+	var p sched.Preset
+	if len(presetComponents) != len(p.Weights) || len(presetClasses) != len(p.ClassBiasMs) {
+		t.Fatal("column names out of step with sched.Preset")
+	}
+}
+
+func TestPlacementReasonTable(t *testing.T) {
+	got := placementReasonTable([]ReasonCode{
+		{Value: "paid.disabled", Type: "PlacementReason"},
+		{Value: "capacity.busy", Type: "PlacementReason"},
+		{Value: "x", Type: "Reason"},
+	})
+	if !strings.Contains(got, "| `paid.disabled` | no (static) |") || !strings.Contains(got, "| `capacity.busy` | yes |") {
+		t.Errorf("rows wrong:\n%s", got)
+	}
+	if strings.Contains(got, "`x`") {
+		t.Error("non-placement reason leaked")
+	}
+}
diff --git a/free/ci/tools/refgen/sidebar.go b/free/ci/tools/refgen/sidebar.go
new file mode 100644
index 000000000..3ed213cb0
--- /dev/null
+++ b/free/ci/tools/refgen/sidebar.go
@@ -0,0 +1,77 @@
+package main
+
+// Purpose: the guides/ci block of the wiki sidebar, built from the pages in
+// the folder.
+// Inputs:  the .md files of .github/wiki/guides/ci.
+// Outputs: one link per page, titled by the page's H1.
+// Constraints: pages follow the reading order of the fabric set; a page not
+// in that order follows it alphabetically, so a new page still appears.
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// readingOrder is where a known page sits in the sidebar.
+var readingOrder = []string{
+	"Getting-Started", "Architecture", "Configuration-and-Policy", "Evidence-and-Machine-Output",
+	"Nodes-and-Runners", "Trust-Security-and-Privacy", "Scheduling-and-Cost", "Hosted-Providers",
+	"Cache-and-Artifacts", "Walkthrough-Home-Lab", "Walkthrough-Multiple-Projects", "Walkthrough-Team",
+	"Walkthrough-Agents", "Migration", "Troubleshooting", "Reference", "Agent-Reference",
+}
+
+// sidebarBlock renders the links to every page of dir.
+func sidebarBlock(dir string) (string, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return "", err
+	}
+	rank := map[string]int{}
+	for i, name := range readingOrder {
+		rank[name] = i
+	}
+	var pages []string
+	for _, e := range entries {
+		if !e.IsDir() && strings.HasSuffix(e.Name(), ".md") {
+			pages = append(pages, strings.TrimSuffix(e.Name(), ".md"))
+		}
+	}
+	sort.Slice(pages, func(i, j int) bool {
+		ri, iok := rank[pages[i]]
+		rj, jok := rank[pages[j]]
+		switch {
+		case iok && jok:
+			return ri < rj
+		case iok != jok:
+			return iok
+		}
+		return pages[i] < pages[j]
+	})
+	var b strings.Builder
+	b.WriteString("### CI\n")
+	for _, p := range pages {
+		title, err := pageTitle(filepath.Join(dir, p+".md"))
+		if err != nil {
+			return "", err
+		}
+		fmt.Fprintf(&b, "- [[%s|guides/ci/%s]]\n", title, p)
+	}
+	return b.String(), nil
+}
+
+// pageTitle returns the text of the first H1 of a page.
+func pageTitle(path string) (string, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	for _, line := range strings.Split(string(b), "\n") {
+		if strings.HasPrefix(line, "# ") {
+			return strings.TrimSpace(strings.TrimPrefix(line, "# ")), nil
+		}
+	}
+	return "", fmt.Errorf("%s: no H1", path)
+}
diff --git a/free/ci/tools/refgen/trustreasons.go b/free/ci/tools/refgen/trustreasons.go
new file mode 100644
index 000000000..8808cc853
--- /dev/null
+++ b/free/ci/tools/refgen/trustreasons.go
@@ -0,0 +1,29 @@
+package main
+
+// Purpose: the trust reasons table of the Trust, Security and Privacy guide.
+// Inputs:  trust.ReasonMeaning, the one map of reason code to meaning.
+// Outputs: a Markdown table sorted by reason code.
+// Constraints: the table is generated only; the guide holds it between
+// <!-- BEGIN GENERATED:trust-reasons --> markers.
+
+import (
+	"sort"
+	"strings"
+
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+// trustReasonsTable renders every trust reason code and its meaning.
+func trustReasonsTable() string {
+	keys := make([]string, 0, len(trust.ReasonMeaning))
+	for r := range trust.ReasonMeaning {
+		keys = append(keys, string(r))
+	}
+	sort.Strings(keys)
+	var b strings.Builder
+	b.WriteString("| Reason | Meaning |\n|---|---|\n")
+	for _, k := range keys {
+		b.WriteString("| `" + k + "` | " + cell(trust.ReasonMeaning[trust.Reason(k)]) + " |\n")
+	}
+	return b.String()
+}
diff --git a/free/ci/tools/refgen/trustreasons_test.go b/free/ci/tools/refgen/trustreasons_test.go
new file mode 100644
index 000000000..59307e03e
--- /dev/null
+++ b/free/ci/tools/refgen/trustreasons_test.go
@@ -0,0 +1,23 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/nself-org/plugins/free/ci/internal/trust"
+)
+
+func TestTrustReasonsTableCoversEveryReason(t *testing.T) {
+	got := trustReasonsTable()
+	if !strings.HasPrefix(got, "| Reason | Meaning |\n|---|---|\n") {
+		t.Fatalf("header missing: %q", got)
+	}
+	for r, m := range trust.ReasonMeaning {
+		if !strings.Contains(got, "| `"+string(r)+"` | "+m+" |") {
+			t.Errorf("row for %s missing", r)
+		}
+	}
+	if strings.Count(got, "\n") != len(trust.ReasonMeaning)+2 {
+		t.Errorf("unexpected row count")
+	}
+}
diff --git a/free/ci/tools/refgen/walker.go b/free/ci/tools/refgen/walker.go
new file mode 100644
index 000000000..0318a4809
--- /dev/null
+++ b/free/ci/tools/refgen/walker.go
@@ -0,0 +1,175 @@
+package main
+
+// Purpose: visit the calls of a file with the values of its loop variables
+// known, so `registerV15("nodes "+name, …)` inside a range over a literal
+// list expands to one key per list item.
+// Inputs:  a parsed file of a package.
+// Outputs: one visit per call per loop item, with that item's fields.
+// Constraints: only a range over a composite literal, or over a package var
+// initialised with one, is expanded; struct items need keyed fields or a
+// struct type in the literal so positional fields can be named.
+
+import (
+	"go/ast"
+	"go/token"
+)
+
+// walker carries the package context the evaluator needs.
+type walker struct {
+	m *module
+	p *pkg
+	f *srcFile
+}
+
+// visitFunc receives a call, the loop variables in scope and the fields of
+// the innermost struct loop item.
+type visitFunc func(call *ast.CallExpr, env map[string][]string, item map[string]string)
+
+// item is one element of a ranged literal list: a string or a struct.
+type item struct {
+	str    string
+	fields map[string]string
+}
+
+// walk visits every call under n. Each range over a known list walks its
+// body once per item.
+func (w walker) walk(n ast.Node, env map[string][]string, cur map[string]string, visit visitFunc) {
+	ast.Inspect(n, func(node ast.Node) bool {
+		switch x := node.(type) {
+		case *ast.CallExpr:
+			visit(x, env, cur)
+		case *ast.RangeStmt:
+			v, ok := x.Value.(*ast.Ident)
+			if !ok {
+				return true
+			}
+			list := w.rangeItems(x.X)
+			if list == nil {
+				return true
+			}
+			for _, it := range list {
+				inner := copyEnv(env)
+				fieldsOf := cur
+				if it.fields != nil {
+					fieldsOf = it.fields
+				} else {
+					inner[v.Name] = []string{it.str}
+				}
+				bindCopies(x.Body, v.Name, it, inner)
+				w.walk(x.Body, inner, fieldsOf, visit)
+			}
+			return false
+		}
+		return true
+	})
+}
+
+// bindCopies binds the := copies of the loop variable, or of one of its
+// fields, at the top level of body.
+func bindCopies(body *ast.BlockStmt, loopVar string, it item, env map[string][]string) {
+	for _, st := range body.List {
+		as, ok := st.(*ast.AssignStmt)
+		if !ok || as.Tok != token.DEFINE || len(as.Lhs) != 1 || len(as.Rhs) != 1 {
+			continue
+		}
+		lhs, ok := as.Lhs[0].(*ast.Ident)
+		if !ok {
+			continue
+		}
+		switch r := as.Rhs[0].(type) {
+		case *ast.Ident:
+			if r.Name == loopVar && it.fields == nil {
+				env[lhs.Name] = []string{it.str}
+			}
+		case *ast.SelectorExpr:
+			if id, ok := r.X.(*ast.Ident); ok && id.Name == loopVar {
+				if val, ok := it.fields[r.Sel.Name]; ok {
+					env[lhs.Name] = []string{val}
+				}
+			}
+		}
+	}
+}
+
+// rangeItems resolves the ranged expression to its literal items, or nil.
+func (w walker) rangeItems(e ast.Expr) []item {
+	cl, ok := e.(*ast.CompositeLit)
+	if !ok {
+		id, isIdent := e.(*ast.Ident)
+		if !isIdent {
+			return nil
+		}
+		cl = w.packageVar(id.Name)
+		if cl == nil {
+			return nil
+		}
+	}
+	var names []string
+	if at, ok := cl.Type.(*ast.ArrayType); ok {
+		if st, ok := at.Elt.(*ast.StructType); ok {
+			for _, fl := range st.Fields.List {
+				for _, n := range fl.Names {
+					names = append(names, n.Name)
+				}
+			}
+		}
+	}
+	var out []item
+	for _, el := range cl.Elts {
+		if sub, ok := el.(*ast.CompositeLit); ok {
+			fs := map[string]string{}
+			for i, x := range sub.Elts {
+				if kv, ok := x.(*ast.KeyValueExpr); ok {
+					if k, ok := kv.Key.(*ast.Ident); ok {
+						if v, ok := w.m.str(w.p, w.f, kv.Value, nil); ok {
+							fs[k.Name] = v
+						}
+					}
+				} else if i < len(names) {
+					if v, ok := w.m.str(w.p, w.f, x, nil); ok {
+						fs[names[i]] = v
+					}
+				}
+			}
+			out = append(out, item{fields: fs})
+			continue
+		}
+		s, ok := w.m.str(w.p, w.f, el, nil)
+		if !ok {
+			return nil
+		}
+		out = append(out, item{str: s})
+	}
+	return out
+}
+
+// packageVar finds the composite literal a package-level var is set to.
+func (w walker) packageVar(name string) *ast.CompositeLit {
+	for _, f := range w.p.files {
+		for _, decl := range f.ast.Decls {
+			gd, ok := decl.(*ast.GenDecl)
+			if !ok || gd.Tok != token.VAR {
+				continue
+			}
+			for _, spec := range gd.Specs {
+				vs := spec.(*ast.ValueSpec)
+				for i, n := range vs.Names {
+					if n.Name == name && i < len(vs.Values) {
+						cl, _ := vs.Values[i].(*ast.CompositeLit)
+						return cl
+					}
+				}
+			}
+		}
+	}
+	return nil
+}
+
+// copyEnv returns a shallow copy of env.
+func copyEnv(env map[string][]string) map[string][]string {
+	out := map[string][]string{}
+	for k, v := range env {
+		out[k] = v
+	}
+	return out
+}
diff --git a/free/job-queue/README.md b/free/job-queue/README.md
index 459f942de..6d6049fb6 100644
--- a/free/job-queue/README.md
+++ b/free/job-queue/README.md
@@ -1,6 +1,7 @@
 # ɳSelf Job Queue Plugin
 
 **Port:** 8213
+
 **Bundle:** Unbundled (standalone)
 **Custom Service Slot:** CS_10
 **License flag:** `NSELF_JOB_QUEUE=true` (env checked at deploy)
diff --git a/registry.json b/registry.json
index 0874bc0ff..8b0f6b9e2 100644
--- a/registry.json
+++ b/registry.json
@@ -955,12 +955,89 @@
         "commands": {
           "command": "ci",
           "subcommands": [
+            "artifacts",
             "build",
+            "config ignore add",
+            "config migrate",
+            "config show",
+            "doctor",
+            "evidence",
+            "evidence verify",
+            "explain",
             "forgejo",
+            "logs",
+            "netproxy",
+            "nodes add",
+            "nodes discover",
+            "nodes drain",
+            "nodes enable",
+            "nodes forget-project",
+            "nodes label",
+            "nodes list",
+            "nodes pair",
+            "nodes pools explain",
+            "nodes pools list",
+            "nodes pools show",
+            "nodes projects add",
+            "nodes projects list",
+            "nodes projects remove",
             "nodes provision",
+            "nodes remove",
+            "nodes revoke",
+            "nodes rotate",
+            "nodes secrets grant",
+            "nodes secrets revoke",
+            "nodes set",
+            "nodes show",
+            "nodes status",
+            "nodes sync",
+            "nodes test",
+            "nodes upgrade",
             "nodes verify",
+            "plan",
+            "policy pin",
+            "policy protect",
+            "policy set",
+            "policy show",
+            "policy unset",
+            "policy usage",
+            "providers",
+            "providers authorize",
+            "providers github init",
+            "providers gitlab init",
+            "providers list",
+            "providers revoke",
+            "providers show",
+            "providers test",
+            "providers usage import",
             "run",
-            "serve"
+            "runs",
+            "runs approve",
+            "runs cancel",
+            "runs decisions",
+            "runs follow",
+            "runs list",
+            "runs outbox",
+            "runs pending",
+            "runs prune",
+            "runs queue",
+            "runs reproduce",
+            "runs rerun",
+            "runs resolve",
+            "runs stats",
+            "runs wait",
+            "serve",
+            "serve admin",
+            "serve admin audit",
+            "serve admin audit checkpoint",
+            "serve admin cert",
+            "serve admin roles",
+            "serve admin token",
+            "serve backup",
+            "serve install",
+            "serve restore",
+            "serve uninstall",
+            "serve watch"
           ]
         },
         "maturity": "implemented",
diff --git a/scripts/ci/ci-conformance-check.py b/scripts/ci/ci-conformance-check.py
new file mode 100644
index 000000000..5b81e33fc
--- /dev/null
+++ b/scripts/ci/ci-conformance-check.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Validate the JSON lines of free/ci/scripts/ci-conformance.sh against ci-conformance/v1.
+
+Usage: ci-conformance.sh --sim --json | ci-conformance-check.py [--require-legs A1 A2 ...]
+
+Without --require-legs the stream must hold result lines only (a --list stream is refused):
+every leg must pass (a skipped leg is not a pass), and the summary counts must match the lines.
+With --require-legs every named leg must appear as a result line or a --list row.
+Exit 0 valid, 1 invalid or a leg did not pass, 2 usage.
+"""
+import json
+import re
+import sys
+
+LEG = re.compile(r"^(A([1-9]|10)|F[0-9]+)$")
+RESULT = {"leg": str, "pass": bool, "reason": str, "evidence_ref": str, "duration_ms": int}
+ROW = {"id": str, "kind": str, "path": str}
+KINDS = {"sim", "hardware"}
+
+
+def typed(obj, spec):
+    for key, kind in spec.items():
+        value = obj.get(key)
+        if key not in obj or not isinstance(value, kind) or (kind is int and isinstance(value, bool)):
+            return f"{key} is missing or not a {kind.__name__}"
+    return None
+
+
+def check_line(obj):
+    """Return (category, problem) for one decoded line."""
+    if not isinstance(obj, dict):
+        return "bad", "not an object"
+    if "summary" in obj:
+        s = obj["summary"]
+        if not isinstance(s, dict) or typed(s, {"pass": int, "fail": int, "skip": int}) or s.get("kind") not in KINDS:
+            return "bad", "malformed summary"
+        return "summary", None
+    if "leg" in obj:
+        why = typed(obj, RESULT)
+        if why or not LEG.match(obj["leg"]) or obj.get("kind", "sim") not in KINDS:
+            return "bad", why or "bad leg id or kind"
+        status = obj.get("status", "pass" if obj["pass"] else "fail")
+        if status not in {"pass", "fail", "skip"} or (status == "pass") != obj["pass"]:
+            return "bad", "status and pass disagree"
+        if obj["duration_ms"] < 0:
+            return "bad", "negative duration"
+        return "result", None
+    if "id" in obj:
+        why = typed(obj, ROW)
+        if why or not LEG.match(obj["id"]) or obj["kind"] not in KINDS:
+            return "bad", why or "bad leg id or kind"
+        return "row", None
+    return "bad", "neither a result, a row nor a summary"
+
+
+def check(lines, required):
+    problems, results, rows, summaries = [], [], [], []
+    for n, line in enumerate(lines, 1):
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            problems.append(f"line {n}: not JSON")
+            continue
+        cat, why = check_line(obj)
+        if cat == "bad":
+            problems.append(f"line {n}: {why}")
+        elif cat == "result":
+            results.append(obj)
+        elif cat == "row":
+            rows.append(obj)
+        else:
+            summaries.append(obj["summary"])
+    seen = {r["leg"] for r in results} | {r["id"] for r in rows}
+    if required:
+        for leg in required:
+            if leg not in seen:
+                problems.append(f"required leg {leg} is absent")
+        return problems
+    if rows:
+        problems.append("a --list stream needs --require-legs")
+    if not results:
+        problems.append("no leg result lines")
+    for r in results:
+        if not r["pass"]:
+            problems.append(f"leg {r['leg']} did not pass: {r['reason']}")
+    if len(summaries) != 1:
+        problems.append("want exactly one summary line")
+    elif results:
+        s = summaries[0]
+        want = {"pass": sum(1 for r in results if r["pass"]),
+                "skip": sum(1 for r in results if r.get("status") == "skip")}
+        want["fail"] = len(results) - want["pass"] - want["skip"]
+        if any(s[k] != want[k] for k in want):
+            problems.append(f"summary {s} does not match the lines {want}")
+    return problems
+
+
+def main(argv):
+    required = []
+    if argv:
+        if argv[0] != "--require-legs" or len(argv) < 2:
+            sys.exit("usage: ci-conformance-check.py [--require-legs LEG ...]")
+        required = argv[1:]
+    problems = check(sys.stdin, required)
+    for p in problems:
+        print("ci-conformance-check:", p, file=sys.stderr)
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/scripts/ci/ci-machine-surface.sh b/scripts/ci/ci-machine-surface.sh
new file mode 100755
index 000000000..1dcf018a5
--- /dev/null
+++ b/scripts/ci/ci-machine-surface.sh
@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# Purpose: end-to-end proof of the ci plugin machine surface (P7-CI-62, CI D31, review F16): the head plugin installed in a
+#          temporary HOME, a cli built from "$NSELF/cli" origin/main, and the same six commands over CLI, HTTP and MCP.
+# Inputs:  --cli-src DIR (a cli checkout; its origin/main is built), --plugin-dir DIR (free/ci), --out DIR (results).
+#          Needs git, go, jq, curl, python3 and a free loopback port. Never touches the operator's ~/.nself.
+# Outputs: DIR/{tools.txt,routes.txt,*.cli,*.http,*.mcp}; exit 0 when every comparison is equal, 1 on any difference,
+#          2 on a missing prerequisite (for example a cli without tools/manifestv2migrate).
+# Constraints: the cli worktree, the temp HOME and the server are removed on exit; no network beyond loopback.
+set -euo pipefail
+
+cli_src="" plugin_dir="" out=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --cli-src) cli_src="$2"; shift 2 ;;
+    --plugin-dir) plugin_dir="$2"; shift 2 ;;
+    --out) out="$2"; shift 2 ;;
+    *) echo "usage: $0 --cli-src DIR --plugin-dir DIR --out DIR" >&2; exit 2 ;;
+  esac
+done
+[ -n "$cli_src" ] && [ -n "$plugin_dir" ] && [ -n "$out" ] || { echo "usage: $0 --cli-src DIR --plugin-dir DIR --out DIR" >&2; exit 2; }
+for tool in git go jq curl python3; do command -v "$tool" >/dev/null || { echo "missing prerequisite: $tool" >&2; exit 2; }; done
+plugin_dir=$(cd "$plugin_dir" && pwd)
+repo_root=$(cd "$plugin_dir/../.." && pwd)
+work=$(mktemp -d "${TMPDIR:?TMPDIR must be set}/ci62.XXXXXX")
+mkdir -p "$out"; out=$(cd "$out" && pwd)
+server_pid=""
+cleanup() {
+  [ -n "$server_pid" ] && kill "$server_pid" 2>/dev/null || true
+  git -C "$cli_src" worktree remove --force "$work/cli" 2>/dev/null || true
+  rm -rf "$work"
+}
+trap cleanup EXIT
+
+# 1. cli at origin/main, and the manifest v2 check from that tree.
+git -C "$cli_src" worktree add --detach "$work/cli" origin/main >/dev/null
+[ -d "$work/cli/tools/manifestv2migrate" ] || { echo "cli origin/main has no tools/manifestv2migrate (P7-PLUG-01 not merged)" >&2; exit 2; }
+(cd "$work/cli" && go run -mod=vendor ./tools/manifestv2migrate -in "$plugin_dir/plugin.json" -check)
+(cd "$work/cli" && CGO_ENABLED=0 go build -mod=vendor -o "$work/bin/nself" ./cmd/nself)
+
+# 2. head plugin into a temp HOME (P7-CI-47 layout).
+export HOME="$work/home"; mkdir -p "$HOME/.nself/plugins/ci" "$HOME/.nself/plugins/bin"
+cp "$plugin_dir/plugin.json" "$HOME/.nself/plugins/ci/plugin.json"
+(cd "$plugin_dir" && CGO_ENABLED=0 go build -mod=vendor -o "$HOME/.nself/plugins/bin/nself-ci" ./cmd)
+export PATH="$work/bin:$PATH" NSELF_V15=1 NSELF_NONINTERACTIVE=1 NSELF_CI_HOME="$work/cihome"
+
+# 3a. an nself project for the cli (mcp and admin serve need one), and
+# 3b. a fixture repo with one trivial pipeline.
+fx="$work/fixture"; mkdir -p "$fx/.nself"
+printf 'version: 1\njobs:\n  hello:\n    kind: test\n    run: ["true"]\n' >"$fx/.nself/ci.yaml"
+git -C "$fx" init -q && git -C "$fx" add .nself/ci.yaml && git -C "$fx" -c user.name=t -c user.email=t@example.invalid commit -q -m fixture
+export NSELF_CI_REPO="$fx"
+proj="$work/proj"; mkdir -p "$proj"
+(cd "$proj" && nself init --non-interactive >/dev/null 2>&1)
+
+# 4. normaliser for volatile ids and times.
+norm() { jq -S 'walk(if type=="string" then gsub("[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9:.]+Z?";"TIME") | gsub("run_[0-9a-f]+";"RUN") else . end) | del(.. | .duration_ms?, .elapsed_ms?, .world_digest?, .free_bytes?)'; }
+
+# 5. the MCP client: 40 lines of stdio JSON-RPC, used for tools/list and tools/call.
+mcp() { (cd "$proj" && python3 -B - "$@" <<'PY'
+import json, subprocess, sys
+proc = subprocess.Popen(["nself", "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+def call(i, method, params):
+    proc.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "params": params}) + "\n"); proc.stdin.flush()
+    while True:
+        msg = json.loads(proc.stdout.readline())
+        if msg.get("id") == i:
+            return msg
+def notify(method):
+    proc.stdin.write(json.dumps({"jsonrpc": "2.0", "method": method}) + "\n"); proc.stdin.flush()
+call(1, "initialize", {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "ci62", "version": "1"}})
+notify("notifications/initialized")
+verb = sys.argv[1]
+if verb == "list":
+    print(json.dumps(call(2, "tools/list", {})["result"]["tools"]))
+else:
+    res = call(2, "tools/call", {"name": sys.argv[2], "arguments": json.loads(sys.argv[3])})["result"]
+    print(json.dumps(res.get("structuredContent", res)))
+proc.stdin.close(); proc.wait(timeout=10)
+PY
+); }
+
+fail=0
+same() { if ! diff -u "$1" "$2" >"$out/diff.txt"; then echo "DIFFERENT: $1 vs $2" >&2; cat "$out/diff.txt" >&2; fail=1; fi; }
+
+# 6. help --json: every row lists canon plugin, side effect, json and confirm; bare ci is remote with confirm.
+nself help --json >"$out/help.json"
+jq -e '[.. | objects | select(.name? == "ci")] | length > 0' "$out/help.json" >/dev/null || { echo "ci missing from nself help --json" >&2; fail=1; }
+
+# 7. tools/list: the expected tools, none for cli-only, interactive or stream rows.
+mcp list | jq -r '.[].name' | sort >"$out/tools.txt"
+for t in nself_ci nself_ci_plan nself_ci_runs nself_ci_runs_wait nself_ci_runs_stats nself_ci_evidence_verify nself_ci_nodes_list nself_ci_nodes_revoke nself_ci_evidence; do
+  grep -qx "$t" "$out/tools.txt" || { echo "missing tool $t" >&2; fail=1; }
+done
+for t in nself_ci_policy_set nself_ci_policy_unset nself_ci_policy_pin nself_ci_serve nself_ci_nodes_pair; do
+  ! grep -qx "$t" "$out/tools.txt" || { echo "cli-only row exposed as tool $t" >&2; fail=1; }
+done
+
+# 8. HTTP: nself admin serve on a free loopback port with a generated token.
+port=$(python3 -B -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1",0)); print(s.getsockname()[1])')
+token=$(python3 -B -c 'import secrets; print(secrets.token_hex(16))')
+(cd "$proj" && NSELF_MCP_TOKEN="$token" exec nself admin serve --host 127.0.0.1 --port "$port") >"$work/serve.log" 2>&1 & server_pid=$!
+for _ in $(seq 1 50); do curl -fs "http://127.0.0.1:$port/openapi.json" -H "Authorization: Bearer $token" >"$out/openapi.json" 2>/dev/null && break; sleep 0.2; done
+jq -r '.paths | keys[]' "$out/openapi.json" | grep -i 'ci' | sort >"$out/routes.txt" || true
+! grep -Eq 'ci/serve(/backup|/restore)?$' "$out/routes.txt" || { echo "ci serve has an HTTP route" >&2; fail=1; }
+
+# 9. the machine-surface region of the wiki page names the same tools and routes (review F16).
+region="$repo_root/.github/wiki/plugins/CI.md"
+if grep -q 'machine-surface' "$region"; then
+  sed -n '/machine-surface/,/\/machine-surface/p' "$region" | grep -oE 'nself_ci[a-z_]*' | sort -u >"$out/region-tools.txt"
+  comm -13 "$out/tools.txt" "$out/region-tools.txt" >"$out/region-extra.txt"
+  [ ! -s "$out/region-extra.txt" ] || { echo "wiki region names tools the cli does not list" >&2; fail=1; }
+fi
+
+# 10. six samples, three surfaces: CLI stdout, HTTP body and MCP data must match after normalising.
+# Each sample: name|cli argv|tool|route|args as a JSON array.
+http() { curl -fs -X POST -H "Authorization: Bearer $token" -H 'Content-Type: application/json' -d "$2" "http://127.0.0.1:$port$1"; }
+head_sha=$(git -C "$fx" rev-parse HEAD)
+samples=(
+  'plan|plan|nself_ci_plan|/v1/commands/ci/plan|[]'
+  'list|runs list|nself_ci_runs_list|/v1/commands/ci/runs/list|[]'
+  "evidence|evidence verify $head_sha|nself_ci_evidence_verify|/v1/commands/ci/evidence/verify|[\"$head_sha\"]"
+  'stats|runs stats|nself_ci_runs_stats|/v1/commands/ci/runs/stats|[]'
+)
+for spec in "${samples[@]}"; do
+  IFS='|' read -r name argv tool route jargs <<<"$spec"
+  # shellcheck disable=SC2086
+  (cd "$fx" && nself ci $argv --json) 2>/dev/null | jq -S '.data // .' | norm >"$out/$name.cli" || true
+  mcp call "$tool" "$(jq -nc --argjson a "$jargs" '{args:$a}')" | jq -S '.value // .data // .' | norm >"$out/$name.mcp" || true
+  same "$out/$name.cli" "$out/$name.mcp"
+  http "$route" "$(jq -nc --argjson a "$jargs" '{args:$a}')" | jq -S '.value // .data // .' | norm >"$out/$name.http" || true
+  same "$out/$name.cli" "$out/$name.http"
+done
+# bare `ci` and nodes revoke: the first call returns a confirmation (kind request), only the call carrying its nonce acts.
+mcp call nself_ci '{}' >"$out/ci.first"
+jq -e '.kind == "request" and (.confirm | length) == 64' "$out/ci.first" >/dev/null || { echo "bare ci did not return a confirmation" >&2; fail=1; }
+mcp call nself_ci_nodes_revoke '{"args":["none"]}' >"$out/revoke.first"
+jq -e '.kind == "request"' "$out/revoke.first" >/dev/null || { echo "nodes revoke acted without a confirmation" >&2; fail=1; }
+nonce=$(jq -r '.confirm // empty' "$out/revoke.first")
+mcp call nself_ci_nodes_revoke "$(jq -nc --arg n "$nonce" '{args:["none"],confirm:$n}')" >"$out/revoke.second"
+! jq -e '.kind == "request"' "$out/revoke.second" >/dev/null 2>&1 || { echo "nodes revoke asked again with its nonce" >&2; fail=1; }
+
+[ "$fail" -eq 0 ] && echo "ci-machine-surface: ok" || { echo "ci-machine-surface: FAILED" >&2; exit 1; }
diff --git a/scripts/docs/check-walkthroughs.py b/scripts/docs/check-walkthroughs.py
new file mode 100755
index 000000000..bad5b9126
--- /dev/null
+++ b/scripts/docs/check-walkthroughs.py
@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Check the CI walkthrough pages against the generated reference and the test suite.
+
+Purpose: every `nself ci ...` line in a code block of a walkthrough page names a command that the generated
+         Reference.md lists, every `--flag` on a bare `nself ci` line is a flag that table lists, every
+         ```text block that contains `nself ci` carries a `<!-- proven-by: TestName -->` line directly above
+         it, every named proof exists in the repository, and the page has a "Proven by" table that lists
+         each proof its text blocks name.
+Inputs:  page paths, or --self-test; --reference overrides the Reference.md path (default: the generated page
+         beside the walkthroughs). Proofs are looked up with `git grep` in the repository that holds the
+         script: a Go test name must match `func Name(`, a path must be a tracked file.
+Outputs: one line per finding on stdout; exit 0 clean, 1 findings, 2 usage or unreadable input.
+Constraints: stdlib only; read-only; no network.
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+REPO = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+DEFAULT_REFERENCE = os.path.join(REPO, ".github", "wiki", "guides", "ci", "Reference.md")
+TESTDATA = os.path.join(os.path.dirname(os.path.abspath(__file__)), "testdata", "walkthroughs")
+
+FENCE = re.compile(r"^\s*(`{3,})\s*([A-Za-z0-9_+-]*)")
+PROVEN_BY = re.compile(r"^\s*<!--\s*proven-by:\s*([A-Za-z0-9_./-]+)\s*-->\s*$")
+COMMAND_ROW = re.compile(r"^\|\s*`(nself ci(?: [a-z][a-z0-9-]*)*)`\s*\|")
+FLAG_ROW = re.compile(r"^\|\s*`(--[a-z0-9][a-z0-9-]*)`\s*\|")
+WORD = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def load_reference(path):
+    """Return (commands, flags) from the generated command and flag tables of Reference.md."""
+    commands, flags = set(), set()
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            m = COMMAND_ROW.match(line)
+            if m:
+                commands.add(m.group(1))
+                continue
+            m = FLAG_ROW.match(line)
+            if m:
+                flags.add(m.group(1))
+    if not commands:
+        raise ValueError("%s: no command rows found" % path)
+    return commands, flags
+
+
+def code_blocks(lines):
+    """Yield (language, fence line index, body lines as (index, text)) for each fenced block."""
+    i = 0
+    while i < len(lines):
+        m = FENCE.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        ticks, lang, start = m.group(1), m.group(2), i
+        body = []
+        i += 1
+        while i < len(lines) and lines[i].strip() != ticks and not (
+            lines[i].strip().startswith(ticks) and lines[i].strip().strip("`") == ""
+        ):
+            body.append((i, lines[i]))
+            i += 1
+        yield lang, start, body
+        i += 1
+
+
+def ci_tokens(text):
+    """Return the tokens after `nself ci` when the line is an nself ci command, else None."""
+    s = text.strip()
+    if s.startswith("$ "):
+        s = s[2:].lstrip()
+    parts = s.split()
+    if len(parts) < 2 or parts[0] != "nself" or parts[1] != "ci":
+        return None
+    return parts[2:]
+
+
+def check_command(tokens, commands, flags):
+    """Return a finding for one `nself ci` line, or None."""
+    words = []
+    for tok in tokens:
+        if not WORD.match(tok):
+            break
+        words.append(tok)
+    path = "nself ci"
+    used = 0
+    for n in range(len(words), 0, -1):
+        cand = "nself ci " + " ".join(words[:n])
+        if cand in commands:
+            path, used = cand, n
+            break
+    if used < len(words):
+        nxt = path + " " + words[used]
+        if any(c == nxt or c.startswith(nxt + " ") for c in commands):
+            k = used + 1
+            while k < len(words):
+                head = "nself ci " + " ".join(words[: k + 1])
+                if not any(c == head or c.startswith(head + " ") for c in commands):
+                    break
+                k += 1
+            return "`%s` is not a command in Reference.md" % " ".join(["nself ci"] + words[: k + 1])
+        if path == "nself ci":
+            # A bare run takes flags and paths, never a plain word: a leading word is a misspelt verb.
+            return "`nself ci %s` is not a command in Reference.md" % words[0]
+    if path == "nself ci":
+        for tok in tokens:
+            if tok == "--":
+                break
+            if tok.startswith("--"):
+                name = tok.split("=", 1)[0]
+                if name not in flags:
+                    return "`%s` is not a flag listed in Reference.md" % name
+    return None
+
+
+def proof_exists(name, cache):
+    """Report whether a proof (a Go test name or a repo path) exists in the repository."""
+    if name in cache:
+        return cache[name]
+    if "/" in name:
+        args = ["git", "-C", REPO, "ls-files", "--error-unmatch", "--", name]
+    else:
+        args = ["git", "-C", REPO, "grep", "-q", "-F", "func %s(" % name, "--", "*.go"]
+    ok = subprocess.run(args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode == 0
+    cache[name] = ok
+    return ok
+
+
+def proven_by_table(lines):
+    """Return the proof names in the first column of the "## Proven by" table, or None without the section."""
+    names, inside = [], False
+    for line in lines:
+        if line.startswith("## "):
+            inside = line.strip() == "## Proven by"
+            continue
+        if inside and line.startswith("|"):
+            cells = [c.strip() for c in line.strip().strip("|").split("|")]
+            for m in re.finditer(r"`([A-Za-z0-9_./-]+)`", cells[-1] if len(cells) > 1 else ""):
+                names.append(m.group(1))
+    return names if any(l.strip() == "## Proven by" for l in lines) else None
+
+
+def check_page(path, commands, flags, cache):
+    """Return the findings for one page as strings."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            lines = f.read().split("\n")
+    except OSError as e:
+        return ["%s: %s" % (path, e)]
+    out = []
+    used_proofs = []
+    for lang, start, body in code_blocks(lines):
+        has_ci = False
+        for idx, text in body:
+            tokens = ci_tokens(text)
+            if tokens is None:
+                continue
+            has_ci = True
+            msg = check_command(tokens, commands, flags)
+            if msg:
+                out.append("%s:%d: %s" % (path, idx + 1, msg))
+        if lang == "text" and has_ci:
+            m = PROVEN_BY.match(lines[start - 1]) if start > 0 else None
+            if not m:
+                out.append("%s:%d: text block with `nself ci` has no proven-by line directly above it" % (path, start + 1))
+                continue
+            used_proofs.append((start, m.group(1)))
+    table = proven_by_table(lines)
+    if table is None:
+        out.append("%s: no \"## Proven by\" section" % path)
+        table = []
+    for name in sorted(set(table) | {n for _, n in used_proofs}):
+        if not proof_exists(name, cache):
+            out.append("%s: proof %s does not exist in the repository" % (path, name))
+    for start, name in used_proofs:
+        if name not in table:
+            out.append("%s:%d: proof %s is missing from the Proven by table" % (path, start, name))
+    return out
+
+
+def self_test():
+    """Run the fixtures: good.md must pass and every bad-*.md must fail. Return the exit code."""
+    ref = os.path.join(TESTDATA, "Reference.md")
+    commands, flags = load_reference(ref)
+    cache, status = {}, 0
+    for name in sorted(os.listdir(TESTDATA)):
+        if not name.endswith(".md") or name == "Reference.md":
+            continue
+        findings = check_page(os.path.join(TESTDATA, name), commands, flags, cache)
+        want_fail = name.startswith("bad-")
+        if want_fail and not findings:
+            print("self-test: %s passed but must fail" % name)
+            status = 1
+        elif not want_fail and findings:
+            print("self-test: %s must pass:\n  %s" % (name, "\n  ".join(findings)))
+            status = 1
+        else:
+            print("self-test: %s ok (%s)" % (name, findings[0] if findings else "clean"))
+    return status
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description="Check CI walkthrough pages.")
+    ap.add_argument("pages", nargs="*")
+    ap.add_argument("--reference", default=DEFAULT_REFERENCE)
+    ap.add_argument("--self-test", action="store_true")
+    a = ap.parse_args(argv)
+    if a.self_test:
+        return self_test()
+    if not a.pages:
+        ap.print_usage(sys.stderr)
+        return 2
+    try:
+        commands, flags = load_reference(a.reference)
+    except (OSError, ValueError) as e:
+        print(e, file=sys.stderr)
+        return 2
+    cache, findings = {}, []
+    for page in a.pages:
+        findings += check_page(page, commands, flags, cache)
+    for f in findings:
+        print(f)
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/scripts/docs/testdata/walkthroughs/Reference.md b/scripts/docs/testdata/walkthroughs/Reference.md
new file mode 100644
index 000000000..8fe28e550
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/Reference.md
@@ -0,0 +1,17 @@
+# CI reference (fixture)
+
+## Commands
+
+| Command | Surface | Side effect | Summary |
+|---|---|---|---|
+| `nself ci` | v1.5 | remote | Run the gate |
+| `nself ci nodes projects add` | v1.5 | write | - |
+| `nself ci nodes projects list` | v1.5 | read | - |
+| `nself ci runs wait` | v1.5 | read | - |
+
+### Flags
+
+| Flag | Commands |
+|---|---|
+| `--detach` | - |
+| `--json` | `runs *` |
diff --git a/scripts/docs/testdata/walkthroughs/bad-missing-proven-by.md b/scripts/docs/testdata/walkthroughs/bad-missing-proven-by.md
new file mode 100644
index 000000000..fc2d3f3f2
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/bad-missing-proven-by.md
@@ -0,0 +1,11 @@
+# Missing proven-by
+
+```text
+nself ci runs wait run_123 --json
+```
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Wait | `TestMachineDefaults` |
diff --git a/scripts/docs/testdata/walkthroughs/bad-root-flag.md b/scripts/docs/testdata/walkthroughs/bad-root-flag.md
new file mode 100644
index 000000000..ad6872c95
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/bad-root-flag.md
@@ -0,0 +1,12 @@
+# Unknown root flag
+
+<!-- proven-by: TestMachineDefaults -->
+```text
+nself ci --detatch --json
+```
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Detached run | `TestMachineDefaults` |
diff --git a/scripts/docs/testdata/walkthroughs/bad-subcommand.md b/scripts/docs/testdata/walkthroughs/bad-subcommand.md
new file mode 100644
index 000000000..2815020f0
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/bad-subcommand.md
@@ -0,0 +1,12 @@
+# Wrong subcommand
+
+<!-- proven-by: TestMachineDefaults -->
+```text
+nself ci nodes projects ad vps-a ~/src/project-a
+```
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Authorize | `TestMachineDefaults` |
diff --git a/scripts/docs/testdata/walkthroughs/bad-unknown-test.md b/scripts/docs/testdata/walkthroughs/bad-unknown-test.md
new file mode 100644
index 000000000..0c10aba04
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/bad-unknown-test.md
@@ -0,0 +1,12 @@
+# Unknown test name
+
+<!-- proven-by: TestNoSuchWalkthroughProof -->
+```text
+nself ci runs wait run_123 --json
+```
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Wait | `TestNoSuchWalkthroughProof` |
diff --git a/scripts/docs/testdata/walkthroughs/good.md b/scripts/docs/testdata/walkthroughs/good.md
new file mode 100644
index 000000000..d7f84881d
--- /dev/null
+++ b/scripts/docs/testdata/walkthroughs/good.md
@@ -0,0 +1,14 @@
+# Good fixture
+
+<!-- proven-by: TestMachineDefaults -->
+```text
+nself ci --detach --json
+nself ci nodes projects add vps-a ~/src/project-a
+nself ci runs wait run_123 --json
+```
+
+## Proven by
+
+| Step | Test |
+|---|---|
+| Detached run | `TestMachineDefaults` |
diff --git a/scripts/drill/cache-security/run b/scripts/drill/cache-security/run
new file mode 100755
index 000000000..d7de8ae95
--- /dev/null
+++ b/scripts/drill/cache-security/run
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# cache-security drill (P7-CACHE-11, Epic CACHE): runs the cache, artifact and release security matrix (build tag
+# cachesec, free/ci/test/cachesec) and fails on any case whose observed outcome differs from its expected one.
+# Why: the matrix maps every case to a row of the CI threat model (hq architecture/ci-threat-model.md). A refusal
+#   that stops happening (an unexpected pass), a refusal with another code or reason key, or one that leaves no audit
+#   row is a regression of a security control, so the drill fails.
+# Inputs:  none to run the suite. `--check-mapping <ci-threat-model.md>` instead checks, without running a test, that
+#   every case names a row that exists in that file and that every row the suite owns has a case.
+# Usage:   run
+#          run --check-mapping /path/to/ci-threat-model.md
+# Outputs: the test log tail and a per-case summary on stderr; testdata/results.json is rewritten by the suite.
+#          Exit 0 on success, 1 when a case differs, a test skips or the mapping is incomplete, 2 when a tool is missing.
+set -euo pipefail
+
+here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+root=$(cd "$here/../../.." && pwd)
+matrix="$root/free/ci/test/cachesec/matrix.yaml"
+results="$root/free/ci/test/cachesec/testdata/results.json"
+owned="TM-12 TM-13 TM-14 TM-15 TM-16 TM-17 TM-18 TM-20 TM-24"
+
+for tool in python3; do
+	command -v "$tool" >/dev/null || { echo "cache-security: $tool is required" >&2; exit 2; }
+done
+
+if [ "${1:-}" = "--check-mapping" ]; then
+	model=${2:-}
+	[ -n "$model" ] && [ -r "$model" ] || { echo "cache-security: --check-mapping needs a readable threat model file" >&2; exit 2; }
+	python3 - "$matrix" "$model" $owned <<'PY'
+import json, re, sys
+matrix, model, owned = sys.argv[1], sys.argv[2], sys.argv[3:]
+cases = json.load(open(matrix))
+rows = set(re.findall(r"^\|\s*(TM-[0-9]{2})\s*\|", open(model).read(), re.M))
+bad = [c["id"] for c in cases if c["threat_row"] not in rows]
+if bad:
+    sys.exit("cache-security: cases name a row that is not in the threat model: " + ", ".join(bad))
+none = [r for r in owned if not any(c["threat_row"] == r for c in cases)]
+if none:
+    sys.exit("cache-security: threat rows with no case: " + ", ".join(none))
+print("cache-security: %d cases map to %d threat-model rows" % (len(cases), len({c["threat_row"] for c in cases})), file=sys.stderr)
+PY
+	exit 0
+fi
+
+command -v go >/dev/null || { echo "cache-security: go is required" >&2; exit 2; }
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/cache-security.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+
+echo "cache-security: running free/ci/test/cachesec" >&2
+if ! (cd "$root/free/ci" && INTEGRATION=1 NSELF_V15=1 CGO_ENABLED=0 go test -json -mod=vendor -tags 'cachesec integration' -count=1 -timeout 60m -run '^TestCacheSecMatrix$' ./test/cachesec/...) >"$tmp/suite.json" 2>"$tmp/suite.err"; then
+	tail -n 40 "$tmp/suite.err" >&2 || true
+	python3 - "$tmp/suite.json" <<'PY' >&2 || true
+import json, sys
+for line in open(sys.argv[1]):
+    try:
+        e = json.loads(line)
+    except ValueError:
+        continue
+    if e.get("Action") == "output" and ("expected" in e.get("Output", "") or "differ" in e.get("Output", "")):
+        print(e["Output"].rstrip())
+PY
+	echo "cache-security: the suite failed" >&2
+	exit 1
+fi
+python3 "$root/scripts/ci/go-test-ran.py" TestCacheSecMatrix <"$tmp/suite.json" || { echo "cache-security: TestCacheSecMatrix did not run or skipped" >&2; exit 1; }
+python3 - "$results" <<'PY'
+import json, sys
+r = json.load(open(sys.argv[1]))
+bad = [c["id"] for c in r if c["outcome"] != c["expected"]]
+if bad or not r:
+    sys.exit("cache-security: unexpected outcome for: " + ", ".join(bad or ["(no results)"]))
+print("cache-security: %d cases, every outcome equals its expected one" % len(r), file=sys.stderr)
+PY
+echo "cache-security: ok" >&2
diff --git a/scripts/generate-ci-agent-reference.py b/scripts/generate-ci-agent-reference.py
index a05ac59a3..ec3a7970a 100644
--- a/scripts/generate-ci-agent-reference.py
+++ b/scripts/generate-ci-agent-reference.py
@@ -2,7 +2,7 @@
 """Render the pull-agent reference from its Go flags and reason constants.
 
 Inputs: pull.go and non-test transport/agent Go sources in this checkout.
-Outputs: Reference.md, or a nonzero --check result when it is stale or absent.
+Outputs: Agent-Reference.md, or a nonzero --check result when it is stale or absent.
 Constraints: offline, stdlib only; fail if source declarations cannot be read.
 """
 
@@ -12,7 +12,7 @@
 import sys
 
 ROOT = Path(__file__).resolve().parents[1]
-PAGE = ROOT / ".github/wiki/guides/ci/Reference.md"
+PAGE = ROOT / ".github/wiki/guides/ci/Agent-Reference.md"
 
 
 def render():
@@ -37,10 +37,11 @@ def render():
     if not flags or not tokens or not transport:
         raise ValueError("cannot read pull flags or agent reason constants")
     lines = [
-        "# CI reference", "",
+        "# CI agent reference", "",
         "<!-- Source: scripts/generate-ci-agent-reference.py; do not edit this page directly. -->", "",
         "This page covers the pull agent and its refusal and transport reasons. "
-        "It is a focused reference pending the full CI reference generator.", "",
+        "Commands, flags and codes of `nself ci` are on "
+        "[[CI reference|guides/ci/Reference]].", "",
         "Regenerate with `python3 scripts/generate-ci-agent-reference.py`; "
         "validate with `python3 scripts/generate-ci-agent-reference.py --check`.", "",
         "## `nself-ci-agent pull`", "",
diff --git a/scripts/generate-wiki-plugin-page.py b/scripts/generate-wiki-plugin-page.py
index 3ec94ac50..2779d0ce9 100644
--- a/scripts/generate-wiki-plugin-page.py
+++ b/scripts/generate-wiki-plugin-page.py
@@ -9,7 +9,20 @@
     ...
     <!-- END GENERATED:catalog -->
 
-Authored text outside the region is never touched, with one exception: the old
+Plugins whose manifest has a `commands` block also get a second region directly
+after the catalog region:
+
+    <!-- BEGIN GENERATED:machine-surface -->
+    ...
+    <!-- END GENERATED:machine-surface -->
+
+one row per command path: MCP tool name, HTTP route, side effect, output,
+exposure with its reason, and the confirmation kind. The rules mirror the cli
+(cmdregistry.ToolName/RoutePath; SURF D2/D5/D15 exposure) as data plus
+scripts/testdata/wiki-plugin-pages/surface-vectors.json; the cli is never
+imported. A plugin without commands has no such region.
+
+Authored text outside the regions is never touched, with one exception: the old
 generator's fixed "**Free — MIT licensed.**" phrase is removed. A missing page
 is created as H1 + region. A tier pair (the same slug in the free and licensed
 tiers) shares one page.
@@ -32,9 +45,13 @@
 
 import yaml
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from wiki_plugin_surface import (  # noqa: E402,F401  (helper beside this script; some names are re-exported for the tests)
+    BEGIN, END, MS_BEGIN, MS_END, MS_NOTE, Problem, _sub_names, apply_machine, check_ceilings, exposure,
+    load_manifest, machine_rows, render_machine_surface, route_path, surface_count, tool_name,
+)
+
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-BEGIN = "<!-- BEGIN GENERATED:catalog -->"
-END = "<!-- END GENERATED:catalog -->"
 NOTE = "<!-- Generated from catalog.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->"
 OLD_PHRASE = re.compile(r" ?\*\*Free — MIT licensed\.\*\*")
 MANIFEST_URL = "https://github.com/nself-org/cli/wiki/Plugin-Manifest"
@@ -56,10 +73,6 @@
 }
 
 
-class Problem(Exception):
-    """A problem found by --check (or a page that cannot be edited)."""
-
-
 def load_config(path):
     cfg = {}
     if os.path.exists(path):
@@ -99,13 +112,6 @@ def _requires(entry):
     return "; ".join(parts)
 
 
-def _sub_names(commands):
-    names = []
-    for sub in (commands or {}).get("subcommands") or []:
-        names.append(sub["name"] if isinstance(sub, dict) else str(sub))
-    return names
-
-
 def _licence(entry, bundles):
     if entry["tier"] == "free":
         return "Free (MIT)"
@@ -186,28 +192,6 @@ def new_page(slug, region, cfg):
     return f"# {page_title(slug, cfg).replace('-', ' ')} Plugin\n\n{region}\n"
 
 
-def surface_count(root, rule):
-    """First-level subcommand count of a manifest, aliases excluded."""
-    try:
-        with open(os.path.join(root, rule["manifest"]), encoding="utf-8") as fh:
-            manifest = json.load(fh)
-    except (OSError, ValueError) as exc:
-        raise Problem(f"surface ceiling manifest {rule['manifest']}: {exc}")
-    skip = set((rule.get("aliases") or {}).get("names") or [])
-    firsts = {n.split()[0] for n in _sub_names(manifest.get("commands")) if n.split()}
-    return len(firsts - skip)
-
-
-def check_ceilings(root, cfg):
-    problems, notes = [], []
-    for name, rule in sorted(cfg["surface_ceilings"].items()):
-        count = surface_count(root, rule)
-        notes.append(f"{name}: {count} first-level subcommands (ceiling {rule['max']})")
-        if count > rule["max"]:
-            problems.append(f"{name}: {count} first-level subcommands exceeds the ceiling {rule['max']}")
-    return problems, notes
-
-
 def plan(root, cfg, catalog, slugs):
     """Yield (slug, path, wanted_text_or_Problem, current_text_or_None)."""
     groups = group_by_slug(catalog)
@@ -216,15 +200,21 @@ def plan(root, cfg, catalog, slugs):
             raise Problem(f"{slug}: not a catalogue slug")
         path = os.path.join(root, PAGES_DIR, page_title(slug, cfg) + ".md")
         region = render_region(groups[slug], catalog)
+        try:
+            manifest = load_manifest(root, groups[slug])
+        except Problem as exc:
+            yield slug, path, exc, None
+            continue
+        mregion = render_machine_surface(manifest) if manifest else None
         if os.path.exists(path):
             with open(path, encoding="utf-8") as fh:
                 cur = fh.read()
             try:
-                yield slug, path, apply_region(cur, region), cur
+                yield slug, path, apply_machine(apply_region(cur, region), mregion), cur
             except Problem as exc:
                 yield slug, path, exc, cur
         else:
-            yield slug, path, new_page(slug, region, cfg), None
+            yield slug, path, apply_machine(new_page(slug, region, cfg), mregion), None
 
 
 def orphans(root, cfg, catalog):
diff --git a/scripts/preflight/licensed.sh b/scripts/preflight/licensed.sh
new file mode 100755
index 000000000..f61339cd1
--- /dev/null
+++ b/scripts/preflight/licensed.sh
@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# licensed.sh - served-bytes preflight, licensed tier (P7-PLUG-39).
+#
+# Downloads, for every licensed registry entry, the tarball ping.nself.org
+# serves with the scoped, expiring, revocable CI licence, and applies the
+# P7-PLUG-02 pipeline and classes (lib.sh). Adds class `entitlement`: the
+# download answered 401/403 although the CI licence should cover the entry.
+# A skip (for example --no-build) is not a pass.
+#
+# Usage:
+#   scripts/preflight/licensed.sh --out report.json [--md summary.md] [--strict]
+#       [--no-build] [--registry FILE] [--ping-url URL] [--log-dir DIR]
+# The key is read from the environment variable NSELF_CI_LICENSE_KEY only, is
+# sent as X-License-Key on the first hop (never to a redirect target), and is
+# never printed. Registry default: $NSELF/plugins-pro/registry.json.
+# Exit: 0 report written, 1 --strict and not pass, 2 usage/infrastructure,
+# 3 coverage failure (fewer entries measured than the registry lists).
+# shellcheck disable=SC2034
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib.sh
+. "$SCRIPT_DIR/lib.sh"
+# shellcheck source=docker.sh
+. "$SCRIPT_DIR/docker.sh"
+
+OUT="" MD="" STRICT=0 REGISTRY="${NSELF:+$NSELF/plugins-pro/registry.json}"
+PING_URL="https://ping.nself.org"
+PF_NO_BUILD=0 PF_LOG_DIR="" PF_BUILD_CACHE=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --out) OUT="${2:-}"; shift 2 ;;
+    --md) MD="${2:-}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    --no-build) PF_NO_BUILD=1; shift ;;
+    --registry) REGISTRY="${2:-}"; shift 2 ;;
+    --ping-url) PING_URL="${2:-}"; shift 2 ;;
+    --log-dir) PF_LOG_DIR="${2:-}"; shift 2 ;;
+    -h | --help) sed -n 2,17p "$0"; exit 0 ;;
+    *) pf_die "unknown argument: $1" ;;
+  esac
+done
+[ -n "$OUT" ] || pf_die "--out FILE is required"
+[ -n "$REGISTRY" ] && [ -f "$REGISTRY" ] || pf_die "licensed registry not found (set NSELF or --registry)"
+[ -n "${NSELF_CI_LICENSE_KEY:-}" ] || pf_die "NSELF_CI_LICENSE_KEY is not set"
+PING_URL="${PING_URL%/}"
+[ -n "$MD" ] || MD="${OUT%.json}.md"
+rm -f "$OUT" "$MD"
+
+pf_need curl jq tar awk find
+[ "$PF_NO_BUILD" = 1 ] || { pf_need docker; docker info >/dev/null 2>&1 || pf_die "docker daemon not reachable (use --no-build only to record skips)"; }
+PF_RUN_ID="pfl-$(date -u +%Y%m%dT%H%M%SZ)-$$"
+PF_BUILDER=""
+PF_TIMEOUT_BIN=""
+for t in timeout gtimeout; do command -v "$t" >/dev/null 2>&1 && { PF_TIMEOUT_BIN="$t"; break; }; done
+
+PF_WORK="$(mktemp -d "${TMPDIR:-/tmp}/preflight-licensed.XXXXXX")"
+trap '[ "$PF_NO_BUILD" = 1 ] || pf_docker_cleanup || true; rm -rf "$PF_WORK" "$OUT.tmp" "$MD.tmp"' EXIT
+mkdir -p "$PF_WORK/dl" "$PF_WORK/build" "$PF_WORK/logs"
+PF_ENTRIES="$PF_WORK/entries.jsonl"
+: >"$PF_ENTRIES"
+PF_MAIN_TABLE="$PF_WORK/main.tsv"
+PF_SERVED_TABLE="$PF_MAIN_TABLE" # no second registry: drift is not measured here
+
+# The header lives in a 0600 file so the key never appears in an argv.
+HDR="$PF_WORK/auth.hdr"
+(umask 077; printf 'X-License-Key: %s\n' "$NSELF_CI_LICENSE_KEY" >"$HDR")
+
+jq -e '.plugins | type == "object"' "$REGISTRY" >/dev/null || pf_die "registry has no plugins object"
+# Entries are fetched through ping, whatever host the registry's download_url names.
+jq -r '.plugins | to_entries | map(select((.value.requires_license // true) == true)) | .[]
+  | [.key, (.value.version // "-"), (if .value.installable == false then "false" else "true" end),
+     ("PING/plugins/" + .key + "/download"), (.value.checksum // "-")] | @tsv' "$REGISTRY" \
+  | LC_ALL=C sort | sed "s#PING#$PING_URL#" >"$PF_MAIN_TABLE"
+EXPECTED=$(wc -l <"$PF_MAIN_TABLE" | tr -d ' ')
+
+# Override: the first hop carries the key; a redirect target gets a plain GET.
+pf_fetch_cached() {
+  local key loc
+  key=$(pf_sha256_str "$1")
+  PF_DL_FILE="$PF_WORK/dl/$key.bin"
+  if [ -f "$PF_WORK/dl/$key.code" ]; then PF_DL_CODE=$(cat "$PF_WORK/dl/$key.code"); return 0; fi
+  PF_DL_CODE=$(pf_curl_code "$PF_DL_FILE" "$1" -H "@$HDR" -D "$PF_WORK/dl/$key.hdr")
+  case "$PF_DL_CODE" in
+    301 | 302 | 303 | 307 | 308)
+      loc=$(tr -d '\r' <"$PF_WORK/dl/$key.hdr" | awk 'tolower($1) == "location:" {print $2; exit}')
+      case "$loc" in /*) loc="${1%%://*}://$(printf '%s' "${1#*://}" | cut -d/ -f1)$loc" ;; esac
+      PF_DL_CODE=$(pf_curl_code "$PF_DL_FILE" "$loc" -L)
+      ;;
+  esac
+  [ "$PF_DL_CODE" = 200 ] || rm -f "$PF_DL_FILE"
+  printf '%s' "$PF_DL_CODE" >"$PF_WORK/dl/$key.code"
+}
+
+# Wrap pf_done: a 401/403 download is class entitlement, never skipped or 404.
+eval "pf_done_base() $(declare -f pf_done | tail -n +2)"
+pf_done() {
+  if [ "$1" = fail ] && [ "$2" = 404 ] && { [ "$dl" = 401 ] || [ "$dl" = 403 ]; }; then
+    pf_done_base fail entitlement "CI licence rejected (HTTP $dl) for an entry it should cover"
+  else
+    pf_done_base "$@"
+  fi
+}
+
+n=0
+while IFS=$'\t' read -r slug ver inst url sum <&3; do
+  n=$((n + 1))
+  pf_log "[licensed $n/$EXPECTED] $slug@$ver"
+  pf_check_entry main "$slug" "$ver" "$inst" "$url" "$sum"
+done 3<"$PF_MAIN_TABLE"
+
+mkdir -p "$(dirname "$OUT")" "$(dirname "$MD")"
+jq -S -s --arg run_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg ping "$PING_URL" --arg run_id "$PF_RUN_ID" \
+  --argjson expected "$EXPECTED" --argjson nobuild "$PF_NO_BUILD" '
+  (sort_by(.slug) | map(.source = "licensed")) as $e
+  | {schema: "preflight-licensed/1",
+     run: {run_at: $run_at, run_id: $run_id, ping_url: $ping, no_build: ($nobuild == 1)},
+     summary: {expected: $expected,
+               coverage: {ok: (($e | length) == $expected and $expected > 0)},
+               counts: {pass: ($e | map(select(.result == "pass")) | length),
+                        fail: ($e | map(select(.result == "fail")) | length),
+                        skip: ($e | map(select(.result == "skip")) | length)},
+               by_class: ($e | map(select(.result != "pass")) | group_by(.class) | map({(.[0].class // "none"): length}) | add // {}),
+               pass: (($e | length) == $expected and $expected > 0 and ($e | map(select(.result != "pass")) | length) == 0)},
+     entries: $e}' "$PF_ENTRIES" >"$OUT.tmp"
+mv "$OUT.tmp" "$OUT"
+{
+  printf '# Licensed preflight\n\n'
+  jq -r '"Entries: \(.summary.expected); pass \(.summary.counts.pass), fail \(.summary.counts.fail), skip \(.summary.counts.skip). Overall pass: \(.summary.pass).\n",
+         "| slug | result | class | reason |", "|---|---|---|---|",
+         (.entries[] | "| \(.slug) | \(.result) | \(.class // "-") | \(.reason | gsub("\\|"; "/")) |")' "$OUT"
+} >"$MD.tmp"
+mv "$MD.tmp" "$MD"
+pf_log "wrote $OUT and $MD"
+
+jq -e '.summary.coverage.ok' "$OUT" >/dev/null || { pf_log "ERROR: coverage failure ($(jq '.entries | length' "$OUT") of $EXPECTED)"; exit 3; }
+if [ "$STRICT" = 1 ] && ! jq -e '.summary.pass' "$OUT" >/dev/null; then
+  pf_log "FAIL: $(jq -c '.summary.counts' "$OUT")"
+  exit 1
+fi
+exit 0
diff --git a/scripts/test_generate_wiki_plugin_page.py b/scripts/test_generate_wiki_plugin_page.py
index 39eb2c251..63792e6d1 100644
--- a/scripts/test_generate_wiki_plugin_page.py
+++ b/scripts/test_generate_wiki_plugin_page.py
@@ -22,7 +22,9 @@
 
 
 def ci_manifest(names):
-    return {"commands": {"command": "ci", "subcommands": [{"name": n} for n in names]}}
+    subs = [{"name": n, "json": "none"} if n == "serve" else {"name": n} for n in names]
+    return {"commands": {"command": "ci", "json": "envelope", "output": "document", "side_effect": "read",
+                         "subcommands": subs}}
 
 
 class WikiPagesCase(unittest.TestCase):
@@ -232,5 +234,67 @@ def test_only_the_first_token_counts(self):
         self.assertIn("ci: 1 first-level subcommands", self.check()[1])
 
 
+class MachineSurfaceTests(WikiPagesCase):
+    def vectors(self):
+        with open(os.path.join(FIXTURES, "surface-vectors.json"), encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def test_naming_vectors(self):
+        for v in self.vectors()["names"]:
+            self.assertEqual(gen.tool_name(v["path"]), v["tool"])
+            self.assertEqual(gen.route_path(v["path"]), v["route"])
+
+    def test_exposure_vectors(self):
+        for v in self.vectors()["exposure"]:
+            self.assertEqual(gen.exposure(v["cmd"]), (v["exposure"], v["reason"], v["confirmation"]), v["name"])
+
+    def test_region_follows_catalog_region_with_a_row_per_command(self):
+        self.generate_all()
+        text = self.page("CI.md")
+        self.assertIn(gen.MS_BEGIN, text)
+        self.assertLess(text.index(gen.END), text.index(gen.MS_BEGIN))
+        self.assertIn("| `nself ci nodes provision` | `nself_ci_nodes_provision` | `/v1/commands/ci/nodes/provision` |", text)
+        self.assertIn("| `nself ci serve` | - | - | read | document | CLI only (json none) | none |", text)
+
+    def test_bare_hub_command_has_its_own_row(self):
+        """`nself ci` (tool nself_ci) is a command too: a manifest with subcommands still gets the hub's own row."""
+        self.generate_all()
+        text = self.page("CI.md")
+        self.assertIn("| `nself ci` | `nself_ci` | `/v1/commands/ci` | read | document | MCP and HTTP | none |", text)
+        rows = [r for r in text.splitlines() if r.startswith("| `nself ci")]
+        self.assertEqual(rows[0].split("|")[1].strip(), "`nself ci`", "the bare command sorts before its subcommands")
+
+    def test_bare_hub_row_carries_its_confirmation(self):
+        manifest = ci_manifest(["run"])
+        manifest["commands"].update({"side_effect": "remote", "confirm": {"flags": []}})
+        rows = dict(gen.machine_rows(manifest))
+        self.assertEqual(sorted(rows), ["ci", "ci run"])
+        self.assertEqual(gen.exposure(rows["ci"]), ("MCP and HTTP", "", "nonce"))
+
+    def test_stream_read_row_is_http_only(self):
+        path = os.path.join(self.root, "free", "ci", "plugin.json")
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump({"commands": {"command": "ci", "json": "envelope", "output": "stream", "side_effect": "read",
+                                    "subcommands": [{"name": "run"}]}}, fh)
+        self.generate_all()
+        self.assertIn("| `nself ci run` | - | `/v1/commands/ci/run` | read | stream | HTTP NDJSON only (stream) | none |",
+                      self.page("CI.md"))
+
+    def test_plugin_without_commands_has_no_region_and_bytes_outside_are_kept(self):
+        self.generate_all()
+        self.assertNotIn(gen.MS_BEGIN, self.page("Jobs.md"))
+        extended = self.page("CI.md") + "\nAuthored tail.\n"
+        self.assertEqual(gen.apply_machine(extended, None).count(gen.MS_BEGIN), 0)
+        self.assertTrue(gen.apply_machine(extended, None).endswith("\nAuthored tail.\n"))
+        self.assertEqual(gen.apply_machine(gen.apply_machine(extended, None), None), gen.apply_machine(extended, None))
+
+    def test_manifest_change_makes_check_fail_naming_the_page(self):
+        self.generate_all()
+        self.write_manifest(["run", "serve", "nodes provision", "nodes verify", "extra"])
+        code, out = self.cli("--all", "--check")
+        self.assertEqual(code, 1)
+        self.assertIn("CI.md: stale region", out)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/scripts/testdata/wiki-plugin-pages/catalog.json b/scripts/testdata/wiki-plugin-pages/catalog.json
index 75adb0831..14cee1eca 100644
--- a/scripts/testdata/wiki-plugin-pages/catalog.json
+++ b/scripts/testdata/wiki-plugin-pages/catalog.json
@@ -15,6 +15,9 @@
     {"slug": "cron", "tier": "free", "tier_pair": true, "bundles": [], "maturity": "implemented", "version": "1.2.0",
      "commands": null, "docs_url": null, "requires": {"nself": ">=1.0.0"}, "tarball_url": "https://example.test/cron-1.2.0.tar.gz"},
     {"slug": "api", "tier": "free", "tier_pair": false, "bundles": [], "maturity": "planned", "version": "0.1.0",
-     "commands": null, "docs_url": "https://docs.example.test/api", "requires": null, "tarball_url": "https://example.test/api.tar.gz"}
+     "commands": null, "docs_url": "https://docs.example.test/api", "requires": null, "tarball_url": "https://example.test/api.tar.gz"},
+    {"slug": "ci", "tier": "free", "tier_pair": false, "bundles": [], "maturity": "implemented", "version": "1.2.0",
+     "commands": {"command": "ci", "subcommands": ["run", "serve", "nodes provision", "nodes verify"]}, "docs_url": null,
+     "requires": null, "tarball_url": "https://example.test/ci.tar.gz"}
   ]
 }
diff --git a/scripts/testdata/wiki-plugin-pages/surface-vectors.json b/scripts/testdata/wiki-plugin-pages/surface-vectors.json
new file mode 100644
index 000000000..ec30c9edf
--- /dev/null
+++ b/scripts/testdata/wiki-plugin-pages/surface-vectors.json
@@ -0,0 +1,21 @@
+{
+  "_note": "Naming and exposure vectors copied from the cli P7-SURF-30/24 acceptance (SURF D2, D3, D5, D15). Change both sides together.",
+  "names": [
+    {"path": "deploy promote-env", "tool": "nself_deploy_promote_env", "route": "/v1/commands/deploy/promote-env"},
+    {"path": "config get", "tool": "nself_config_get", "route": "/v1/commands/config/get"},
+    {"path": "ci runs wait", "tool": "nself_ci_runs_wait", "route": "/v1/commands/ci/runs/wait"}
+  ],
+  "exposure": [
+    {"name": "document read", "cmd": {"json": "envelope", "output": "document", "side_effect": "read"}, "exposure": "MCP and HTTP", "reason": "", "confirmation": "none"},
+    {"name": "json none is CLI only", "cmd": {"json": "none", "output": "document", "side_effect": "read"}, "exposure": "CLI only", "reason": "json none", "confirmation": "none"},
+    {"name": "interactive is CLI only", "cmd": {"json": "envelope", "output": "interactive", "side_effect": "read"}, "exposure": "CLI only", "reason": "interactive", "confirmation": "none"},
+    {"name": "read stream is HTTP NDJSON only", "cmd": {"json": "envelope", "output": "stream", "side_effect": "read"}, "exposure": "HTTP NDJSON only", "reason": "stream", "confirmation": "none"},
+    {"name": "write stream is CLI only", "cmd": {"json": "envelope", "output": "stream", "side_effect": "write"}, "exposure": "CLI only", "reason": "stream, not read", "confirmation": "none"},
+    {"name": "surface cli-only", "cmd": {"json": "envelope", "output": "document", "side_effect": "read", "surface": "cli-only"}, "exposure": "CLI only", "reason": "surface cli-only", "confirmation": "none"},
+    {"name": "destructive without confirm", "cmd": {"json": "envelope", "output": "document", "side_effect": "destructive"}, "exposure": "CLI only", "reason": "destructive without confirm", "confirmation": "none"},
+    {"name": "remote without confirm", "cmd": {"json": "envelope", "output": "document", "side_effect": "remote", "confirm": null}, "exposure": "CLI only", "reason": "remote without confirm", "confirmation": "none"},
+    {"name": "remote with empty confirm flags", "cmd": {"json": "envelope", "output": "document", "side_effect": "remote", "confirm": {"flags": []}}, "exposure": "MCP and HTTP", "reason": "", "confirmation": "nonce"},
+    {"name": "destructive with yes flag", "cmd": {"json": "envelope", "output": "document", "side_effect": "destructive", "confirm": {"flags": ["yes"]}}, "exposure": "MCP and HTTP", "reason": "", "confirmation": "nonce"},
+    {"name": "plan confirm", "cmd": {"json": "envelope", "output": "document", "side_effect": "destructive", "confirm": {"flags": [], "plan": {"flag": "plan", "id_flag": "plan-id"}}}, "exposure": "MCP and HTTP", "reason": "", "confirmation": "plan"}
+  ]
+}
diff --git a/scripts/wiki-plugin-pages.yaml b/scripts/wiki-plugin-pages.yaml
index 05965669b..88fe7a306 100644
--- a/scripts/wiki-plugin-pages.yaml
+++ b/scripts/wiki-plugin-pages.yaml
@@ -12,7 +12,9 @@ index_pages: []
 
 # Surface ceilings (D11). The hermetic registry excludes installed plugins, so the
 # ceiling on first-level subcommands is checked here from the plugin manifest.
-# Aliases are listed with a removal version and are not counted.
+# Aliases are listed with a removal version and are not counted. Internal entries
+# are hidden helpers the engine starts itself (Hidden in cmd/, absent from --help);
+# they are not user verbs and are not counted either.
 surface_ceilings:
   ci:
     manifest: free/ci/plugin.json
@@ -20,3 +22,5 @@ surface_ceilings:
     aliases:
       names: [run, eval, build, forgejo]
       remove_in: v1.6.0
+    internal:
+      names: [netproxy]
diff --git a/scripts/wiki_plugin_surface.py b/scripts/wiki_plugin_surface.py
new file mode 100644
index 000000000..7a281cdc5
--- /dev/null
+++ b/scripts/wiki_plugin_surface.py
@@ -0,0 +1,139 @@
+"""Machine-surface and surface-ceiling helpers of generate-wiki-plugin-page.py.
+
+Purpose
+    The machine-surface region (P7-CI-62) and the first-level subcommand ceiling
+    (D11) of a plugin manifest, split out of the generator to keep both files
+    under the 300-line budget. The generator imports every name it uses from here.
+Inputs and outputs
+    Manifest dicts and page text in; region text, counts and Problem errors out.
+    Python 3 standard library only.
+"""
+import json
+import os
+
+BEGIN = "<!-- BEGIN GENERATED:catalog -->"
+END = "<!-- END GENERATED:catalog -->"
+MS_BEGIN = "<!-- BEGIN GENERATED:machine-surface -->"
+MS_END = "<!-- END GENERATED:machine-surface -->"
+MS_NOTE = "<!-- Generated from plugin.json by scripts/generate-wiki-plugin-page.py. Do not hand edit. -->"
+
+
+class Problem(Exception):
+    """A problem found by --check (or a page that cannot be edited)."""
+
+
+def _sub_names(commands):
+    names = []
+    for sub in (commands or {}).get("subcommands") or []:
+        names.append(sub["name"] if isinstance(sub, dict) else str(sub))
+    return names
+
+
+def tool_name(path):
+    """MCP tool name: `nself_` + path tokens joined by `_`, `-` to `_` (cmdregistry.ToolName)."""
+    return "nself_" + "_".join(path.split()).replace("-", "_")
+
+
+def route_path(path):
+    """HTTP route: `/v1/commands/` + path tokens joined by `/` (cmdregistry.RoutePath)."""
+    return "/v1/commands/" + "/".join(path.split())
+
+
+def exposure(cmd):
+    """(exposure, reason, confirmation) for a command dict with inherited fields (SURF D2, D3, D15)."""
+    side, conf = cmd.get("side_effect", "read"), cmd.get("confirm")
+    gated = side in ("remote", "destructive")
+    kind = ("plan" if conf.get("plan") else "nonce") if gated and conf else "none"
+    if cmd.get("surface") == "cli-only":
+        return "CLI only", "surface cli-only", "none"
+    if cmd.get("json") != "envelope":
+        return "CLI only", "json " + str(cmd.get("json")), "none"
+    out = cmd.get("output", "document")
+    if out == "interactive":
+        return "CLI only", "interactive", "none"
+    if out == "stream":
+        if side == "read":
+            return "HTTP NDJSON only", "stream", "none"
+        return "CLI only", "stream, not read", "none"
+    if gated and not conf:
+        return "CLI only", side + " without confirm", "none"
+    return "MCP and HTTP", "", kind
+
+
+def machine_rows(manifest):
+    """Rows (path, cmd) of a manifest `commands` block: the bare hub command (`nself ci`, tool `nself_ci`), then
+    each subcommand, which inherits the hub's fields."""
+    top = manifest.get("commands") or {}
+    subs = [s for s in top.get("subcommands") or [] if isinstance(s, dict)]
+    keys = ("json", "output", "side_effect", "surface", "confirm")
+    base = {k: top[k] for k in keys if k in top}
+    rows = [(f"{top['command']} {s['name']}", {**base, **{k: s[k] for k in keys if k in s}}) for s in subs]
+    if top.get("command"):
+        rows.append((top["command"], base))
+    return sorted(rows, key=lambda r: r[0])
+
+
+def render_machine_surface(manifest):
+    lines = [MS_BEGIN, MS_NOTE, "", "| Command | MCP tool | HTTP route | Side effect | Output | Exposure | Confirmation |",
+             "|---|---|---|---|---|---|---|"]
+    for path, cmd in machine_rows(manifest):
+        how, why, conf = exposure(cmd)
+        tool = f"`{tool_name(path)}`" if how == "MCP and HTTP" else "-"
+        route = f"`{route_path(path)}`" if how != "CLI only" else "-"
+        shown = how + (f" ({why})" if why else "")
+        lines.append(f"| `nself {path}` | {tool} | {route} | {cmd.get('side_effect', 'read')} | "
+                     f"{cmd.get('output', 'document')} | {shown} | {conf} |")
+    return "\n".join(lines + ["", MS_END])
+
+
+def load_manifest(root, entries):
+    """Manifest of the first free entry with a commands block, else None (licensed manifests are not in this repo)."""
+    for e in entries:
+        if e.get("commands") and e["tier"] == "free":
+            rel = os.path.join(e["tier"], e["slug"], "plugin.json")
+            try:
+                with open(os.path.join(root, rel), encoding="utf-8") as fh:
+                    return json.load(fh)
+            except (OSError, ValueError) as exc:
+                raise Problem(f"machine-surface manifest {rel}: {exc}")
+    return None
+
+
+def apply_machine(text, region):
+    """Put `region` (or None) right after the catalog region; replace or drop an existing one."""
+    nb, ne = text.count(MS_BEGIN), text.count(MS_END)
+    if nb or ne:
+        if nb != 1 or ne != 1 or text.index(MS_BEGIN) > text.index(MS_END):
+            raise Problem(f"malformed machine-surface markers ({nb} BEGIN, {ne} END; need one BEGIN then one END)")
+        head, rest = text.split(MS_BEGIN, 1)
+        tail = rest.split(MS_END, 1)[1]
+        if region is None:
+            return head.rstrip("\n") + "\n" + tail.lstrip("\n") if tail.strip() else head.rstrip("\n") + "\n"
+        return head + region + tail
+    if region is None:
+        return text
+    head, tail = text.split(END, 1)
+    return head + END + "\n\n" + region + tail
+
+
+def surface_count(root, rule):
+    """First-level subcommand count of a manifest, aliases and hidden internal commands excluded."""
+    try:
+        with open(os.path.join(root, rule["manifest"]), encoding="utf-8") as fh:
+            manifest = json.load(fh)
+    except (OSError, ValueError) as exc:
+        raise Problem(f"surface ceiling manifest {rule['manifest']}: {exc}")
+    skip = set((rule.get("aliases") or {}).get("names") or [])
+    skip |= set((rule.get("internal") or {}).get("names") or [])
+    firsts = {n.split()[0] for n in _sub_names(manifest.get("commands")) if n.split()}
+    return len(firsts - skip)
+
+
+def check_ceilings(root, cfg):
+    problems, notes = [], []
+    for name, rule in sorted(cfg["surface_ceilings"].items()):
+        count = surface_count(root, rule)
+        notes.append(f"{name}: {count} first-level subcommands (ceiling {rule['max']})")
+        if count > rule["max"]:
+            problems.append(f"{name}: {count} first-level subcommands exceeds the ceiling {rule['max']}")
+    return problems, notes