os-apply: the host restart scan no longer hides lxc-start (skip ':/lxc/' not 'lxc'), and the host scans on every pass so a reboot clears 'reboot needed' (reboot_scanned reaches the hub) — both found live on demo-felhom

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS

.claude/rules/backup.md

@@ -0,0 +1,46 @@
+---
+paths: ["internal/backup/**", "internal/pbs/**", "internal/pbsdr/**", "internal/dr/**"]
+---
+
+# Backup, PBS and DR
+
+`internal/backup/` is the vzdump runner, restore-test scheduler and report store. `internal/pbs/` is
+the fingerprint-pinned PBS-API client plus the verify maintenance loop. `internal/pbsdr/` and
+`internal/dr/` carry the DR tier and recipe halves.
+
+## The three PBS laws
+
+1. **Set-only.** `pvesm remove` **DELETES the encryption key**. Re-apply configuration; never remove
+   and re-add a PBS storage to change it.
+2. **Secret on stdin.** A token secret is passed on stdin, never as an argv the process table shows.
+3. **Verify the pin BEFORE consuming the secret.** A fingerprint check after the secret has been sent
+   protects nothing.
+
+## Verify is server-side, and its default skips the work
+
+The agent drives verification **remotely** via the PBS API; `proxmox-backup-client` has **no** verify
+subcommand. `POST .../verify` defaults to **`ignore-verified=true`, which SKIPS already-verified
+snapshots** — send `ignore-verified=false` to actually re-read and detect corruption. A verify that
+skipped everything reports success.
+
+## Presence is not success
+
+A timestamp recording an **attempt** is not evidence of a **result**. Where a status field travels
+beside a timestamp, the verdict must consult **both** — or the timestamp must record only successes.
+Ask of any timestamp: *what exactly must have happened for this to be set?* If the answer is "we
+tried", it cannot answer "did it work".
+
+**Corollary:** when a verdict changes which field it counts from, the alarm text changes with it.
+Leaving a message reading `last run 8h ago` while alarming on a six-day-old **success** turns a true
+alarm into one the operator dismisses.
+
+## Prune is server-side now
+
+`DatastoreBackup` carries **no** `Datastore.Prune`. Boxes set `keep_last: 0` and the off-site endpoint
+runs the prune jobs. **Box tokens stay write-only — never widen that grant** (R-89).
+
+<!--
+The ignore-verified default is the sharpest instance of the "absent log line" class in this repo: a
+verify that silently skipped every snapshot completes fast, exits clean, and reports the same shape
+as one that read every byte.
+-->

.claude/rules/health-checks.md

@@ -0,0 +1,26 @@
+---
+paths: ["internal/capability/**", "internal/storage/**", "internal/localapi/**", "internal/hub/**", "internal/guesthook/**"]
+---
+
+# A health check issues no block I/O
+
+No `statfs`, no `getdents`, no read, write or `fsync` — **not even behind a timeout**.
+
+A probe that touches a wedged device enters uninterruptible sleep, survives `SIGKILL`, and cannot be
+recovered until the device returns or the host reboots — so `systemctl restart` hangs too. A timeout
+protects the caller's control flow and nothing else: the blocked thread remains.
+
+**Liveness is decided from `/proc` and the kernel's own state**, never by reading or writing the
+filesystem.
+
+<!--
+Measured, R-117 spike §6.3 (felhom.eu/documentation/audits/SPIKE-r117-bind-liveness-2026-07-30.md):
+a probe stayed in D state 3m50s after kill -9; a buffered write with no fsync blocked too (O_CREAT
+needs journal access); and statfs/getdents returned HEALTHY on a namespace that EIOs every byte —
+fast, and wrong.
+
+This rule used to be duplicated verbatim in felhom-agent/CLAUDE.md with a note explaining that
+felhom.eu/CLAUDE.md "does not load in an agent-only session". That reasoning was correct before
+path-scoped rules existed. The single source is now felhom.eu/CLAUDE.md "Code quality rules"; this
+file is the scoped copy that loads exactly where health checks are written. (2026-08-06)
+-->

.claude/rules/localapi.md

@@ -0,0 +1,44 @@
+---
+paths: ["internal/localapi/**", "internal/authz/**", "internal/guesthook/**"]
+---
+
+# Local API, authz and guest hooks — the per-guest blast radius
+
+`internal/localapi/` is the narrow per-guest local API: token store, disks/format, guest binds,
+controller swap, stale-lock recovery, pinned self-signed leaf. `internal/authz/` is the operator
+signed-op verifier (SSHSIG) plus the durable nonce store. `internal/guesthook/` installs the
+pre-start self-heal hookscript.
+
+> **Overlap note:** `health-checks.md` also matches `internal/localapi/**` and
+> `internal/guesthook/**`. That is deliberate — both rules apply there and both load. Neither
+> supersedes the other.
+
+## Scoping is the whole security property
+
+This API is reachable **from inside a customer guest**. Every route must be scoped to the guest that
+called it — a route that can name another guest's id has escaped its blast radius. Fail **safe to
+protected**: an unrecognised or unresolvable caller gets less access, never more.
+
+## Replay protection must survive a restart
+
+**`authz.MemoryNonceStore` on a real host is a defect** — replay protection dies on restart. Use
+`authz.FileNonceStore`. The memory store exists for tests.
+
+## The token is a hash on disk, plaintext only at mint
+
+The store keeps **hashes**. The plaintext token exists in exactly one place, `bootstrap.json` on the
+PVE host — so a "read the token" step means reading that file, and a lost token is re-minted, never
+recovered.
+
+## Binds can brick guest boot
+
+| Do not | Because | Use |
+|---|---|---|
+| `GuestBinder.AttachBind`/`DetachBind` (per-drive `pct set -mpN`) | legacy model; a missing bind source can **brick guest boot** (C1) | `AttachDrive`/`DetachDrive` (intermediary model) |
+| `isHostMountpoint` to reconcile bind state | a boolean cannot converge stacked double-binds (the `/mnt` doubling bug) | `countHostMounts` normalization inside `AttachDrive` |
+
+<!--
+Why fail-safe-to-protected rather than fail-closed: this API also carries the recovery paths. A hard
+refusal on an unresolvable caller would make a half-broken guest unrecoverable through the very
+interface built to recover it. Less access, never none.
+-->

.claude/rules/proxmox.md

@@ -0,0 +1,44 @@
+---
+paths: ["internal/proxmox/**", "internal/reconcile/**", "internal/signedjobs/**"]
+---
+
+# Proxmox — the API contract, and how destructive work is gated
+
+`internal/proxmox/` is the API-first `Client` plus the fenced root-CLI `Privileged`.
+`internal/reconcile/` is the reconcile engine, reversibility gate, op journal and crash recovery.
+`internal/signedjobs/` holds the operator-signed destructive executors (wipe, decommission).
+
+## A 200 on the POST is not success
+
+**Every mutating op is async**: it returns a **UPID**, and `WaitTask` must assert
+`exitstatus == "OK"`. Authorization can fail at *task execution* long after the HTTP call returned
+200. Treating the POST's status as the result is how a failed destroy reads as a successful one.
+
+## The privsep token gotcha
+
+A `--privsep 1` token's rights are the **intersection** of the backing user's permissions **and** the
+token's own ACLs. The role must be granted on **both** or every call 403s. The same intersection rule
+bites on PBS (`token ∩ user`).
+
+## TLS
+
+**SHA-256 leaf-cert pinning** against the self-signed host cert. **No insecure default**, ever. The
+pin is the raw leaf-DER sha — the SAN is never checked, so a cert rotation changes the pin and the
+agent must be re-pinned.
+
+## The destructive path — never the direct call
+
+| Do not | Because | Use |
+|---|---|---|
+| `Client.DestroyLXC` / `Vzdump` / `SetConfig` ad-hoc | skips classification, signature, per-guest serialization, crash recovery | `reconcile.Engine` paths / `RunSignedJob`; queue via `Queue.Submit` |
+| add a method to `proxmox.Privileged` | breaks the 3-exception root-CLI fence (`routing_test.go`) | `proxmox.Runner` + a new sudoers `Cmnd_Alias` + `validate.go`-style checks |
+| treat `ListLXC` output as "guests we own" | audit A1 — pre-v0.62.0 the stale-lock reaper did exactly this, contained only by the pool-scoped token | intersect with `Client.Pool` membership (`staleLockController.Guests()`); **fail safe on read failure** |
+
+Full trap table: `REUSE.md` §3. Every guest joins the `felhom` pool — `VM.Audit` comes from the
+`/pool` grant, not from a per-guest ACL.
+
+<!--
+The fence is not stylistic. It is what makes this component auditable: two types, one of which can
+only speak HTTP and one of which can only shell out, with a test asserting neither crosses. A single
+convenience method on Privileged that also makes an HTTP call would end that property silently.
+-->

.claude/rules/storage.md

@@ -0,0 +1,49 @@
+---
+paths: ["internal/storage/**", "internal/escrow/**"]
+---
+
+# Storage and escrow — format safety and zero-knowledge recovery
+
+`internal/storage/` is the storage observer, durable IDs, role/claim classifiers, `SudoHostOps` and
+the watchdog. `internal/escrow/` is the PBS-key escrow with its zero-knowledge recovery code.
+
+> **Overlap note:** `health-checks.md` also matches `internal/storage/**`. Deliberate — both rules
+> apply there and both load.
+
+## Never format the device you inspected
+
+**AGENT-001 is a TOCTOU:** acting on the caller's `req.Device` (or any remembered `/dev` path) after
+inspection lets `/dev` re-enumeration retarget the node to a **different physical disk**. Format the
+**re-resolved** device — `Server.reresolveWipe` / `reresolveBlank`.
+
+**Never exec raw `mkfs.*`** (including `Binaries.MkfsExt4`/`MkfsXfs`): sudoers no longer allowlists
+raw mkfs, and going direct bypasses the claim filter and the wrapper's re-checks. Use
+`SudoHostOps.Format`, which routes through `felhom-mkfs-guarded`.
+
+## The two durable-ID schemes refuse each other
+
+They are not interchangeable, and each returns a `binding_mismatch` for the other's scheme:
+
+| Purpose | Scheme | Resolver |
+|---|---|---|
+| wipe confirmation | `byid:` / `byuuid:` | `ResolveDurableDevice`, `DiskInfo.WipeDurableID` |
+| enrolled-storage remount | `uuid:` | `ResolveStorageDevice` |
+
+Using `DiskInfo.DurableID` (a `uuid:`) as a wipe-confirmation id is F20-BUG2.
+
+## Drive data is never taken by force
+
+Plain `umount` only — **never `-l`, never `-f`**, and never any format operation under
+`/mnt/felhom-drives`.
+
+## Escrow is zero-knowledge, and a fetch failure is not a wrong code
+
+The server holds no client key; a no-key restore fails with `missing key`. **A fetch failure must
+never be reported as a wrong recovery code** — that told a customer their correct code was bad, in
+hundredths of a second, when checking a code actually takes about one. Distinguish "we could not
+reach the store" from "the code did not match", always.
+
+<!--
+The escrow recovery-code "flake" was a REAL defect, not a flake. "Known flake, re-run" needs evidence
+before it is said out loud — that phrase cost this project a real finding once.
+-->

.githooks/pre-push

@@ -29,6 +29,41 @@ root=$(git rev-parse --show-toplevel 2>/dev/null) || {
 }
 cd "$root" || exit 1
 
+# ── WORKSPACE-ROOT ASSERTION (2026-08-05, R-204 rider) ───────────────────────────────────────────
+# Refuse a push from a clone outside the felhom workspace.
+#
+# WHY THIS IS A HOOK AND NOT A LINE IN A DOCUMENT: the workspace root is ALREADY written down, in
+# documentation/runbooks/workspace-CLAUDE.md and in the workspace-root CLAUDE.md ("stay inside it"),
+# and work drifted into a home directory anyway. A rule that has failed once as a reminder is not
+# fixed by writing it down again — it has to be asserted where it can bite.
+#
+# A PUSH IS THE RIGHT TRIGGER, deliberately: throwaway clones under /tmp for probes and red-proofs
+# never push, so nothing legitimate breaks. Reads and builds elsewhere stay unaffected.
+#
+# Symlinks are resolved on BOTH sides before comparison, so a symlinked path neither falsely passes
+# nor falsely fails. If the workspace root does not exist on this machine the check is SKIPPED, not
+# failed — this hook must not brick a legitimate clone on a different host.
+#
+# The only bypass is the documented `git push --no-verify`, whose use is already reportable.
+FELHOM_WORKSPACE_ROOT=/mnt/5_hdd/felhom.eu
+if [ -d "$FELHOM_WORKSPACE_ROOT" ]; then
+    ws_real=$(cd "$FELHOM_WORKSPACE_ROOT" 2>/dev/null && pwd -P) || ws_real=""
+    root_real=$(pwd -P) || root_real=""
+    if [ -n "$ws_real" ] && [ -n "$root_real" ]; then
+        case "$root_real/" in
+            "$ws_real"/*) : ;;  # inside the workspace — proceed
+            *)
+                echo "pre-push: PUSH REFUSED - this clone is OUTSIDE the felhom workspace." >&2
+                echo "          clone:    $root_real" >&2
+                echo "          expected: under $ws_real (repos live in $ws_real/git/<repo>)" >&2
+                echo "          Work in the workspace clone, or bypass with 'git push --no-verify'" >&2
+                echo "          and state that you did in the session report." >&2
+                exit 1
+                ;;
+        esac
+    fi
+fi
+
 if ! command -v python3 >/dev/null 2>&1; then
     echo "pre-push: FAIL - python3 not found, so the gates CANNOT run. This is a failure, never a" >&2
     echo "          pass by default. Install python3, or push with --no-verify and say so." >&2

.gitignore

@@ -9,3 +9,6 @@
 
 # go
 /vendor/
+
+# Python bytecode written by configs/test_felhom_os_apply.py
+configs/__pycache__/

CHANGELOG.md

@@ -1,3 +1,885 @@
+## v0.141.0 — OS updates: the host fast lane (`11` §8 step 3); the tunnel status is true (R-841); the leg is fast (R-845)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.141.0` (`cfba0d0`), sha256
+> `6eaad9809613c4fca64aefc30cc16415528499bf48efe3a1daaa08af8a611aff`, verified by download. Not vouched at release time.
+
+**MinAgent impact:** none required by any controller. **Needs hub v0.131.0** (`host_release`, the tunnel's three
+states, layer-tagged OS reports). With an older hub the host step finds no host release (ring 1 → nothing) and the
+tunnel's `detail` is ignored. Reads the cloudflared health check controller v0.292.0 adds; with an older controller
+the tunnel is judged on the container state alone and `detail` says so.
+
+- **R-841 — the tunnel.** The agent used to run `systemctl is-active cloudflared` on the HOST — a unit that does not
+  exist (cloudflared is a container in the customer guest), so every box reported `inactive`. `GuestTunnelProber`
+  now reads the guest's `cloudflared` container through the EXISTING sudoers line (`pct exec N -- docker inspect -f
+  *`): state, exit code, and the Docker health status. Three states: `running` (healthy), `not_running` (stopped,
+  absent, or running but NOT connected), `unknown` (could not ask, or the check is still starting). `detail` says why.
+- **The host step** (`11` §8 step 3). After a healthy guest step, under the same heavy-op gate, the leg runs the same
+  wrapper with `layer: host`. Debian origin only; never kernel, boot or firmware packages (new refusal **R14**);
+  **only on an appliance** (**R12** lifted for the host fast lane: proof is the ROOT-owned install record
+  `/var/lib/felhom-install/state.json` `mode: appliance` — the agent-writable `agent.json` is not trusted for this).
+  A failed or unhealthy guest step skips it. **Host health rule:** the agent, pveproxy, pvedaemon, pvestatd and
+  pve-cluster are active; the customer guest runs; the guest health rule passes; the tunnel is `running` (an
+  `unknown` tunnel does not fail the rule; `not_running` does). Never reboots: "reboot needed" is reported when PID 1
+  or `lxc-start` runs a replaced library. No automatic undo — the by-hand runbook is `os-updates-host-undo.md`.
+- **R-845 — the leg is fast.** The wrapper asked about each package in its own `pct exec` (about 0.9 s each). It now
+  makes one call per layer for the version checks (`apt-cache madison` for all names at once, `dpkg --compare-versions`
+  on the host), scans for restart-needed only after an install, repairs only when `dpkg --audit` reports something,
+  and reports its own `pass_seconds`.
+- **Wrapper tests:** `configs/test_felhom_os_apply.py` 46 tests (host layer, R12, R14, lxc-start, the speed rules).
+  Red-proofs: `felhom.eu/documentation/audits/os-host-lane-2026-10-04/partA/`, `partB/`, `partC/agent-golden-redproof.txt`.
+- **Contract:** the desired-state golden gains `host_release` (byte-identical with the hub's); `TestOSUpdateGolden_Decodes`
+  checks it.
+
+## v0.140.0 — OS updates, guest fast lane (`11-os-updates.md` §8 step 2; `09` §3 decisions 76, 79, 80)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.140.0` (`9cac346`), sha256
+> `ae2d60b794869c51d6b063c8e31e2da98ecdbd36c6b75febd64e2fb4266c1250`, verified by download. Not vouched at release time.
+
+**MinAgent impact:** none required by any controller. **Needs hub v0.130.0** (`os-report`, the `os_update` block); an
+older hub serves no block and the leg then reports and installs nothing (ring 1, no release).
+
+- **`configs/felhom-os-apply`** — the root wrapper (Python 3, stdlib). One sudoers entry, `FELHOM_OSAPPLY`:
+  `felhom-os-apply --plan /var/lib/felhom-agent/os/plan-*.json`. Modes `inventory` / `apply` / `health`. Refuses (exit
+  2, nothing changed) on R1–R13: plan path/owner/JSON, a non-Debian origin, the slow lane, any removal, any downgrade,
+  a new or unlisted package, a version not downloadable even from the snapshot, low space, a lock (apt or a guest lock
+  such as a backup), a vmid that is not the box's own customer guest (it must bind `/mnt/felhom-drives`), malformed
+  names/versions, the host layer, dpkg still broken after the repair. Repairs first (`dpkg --configure -a`,
+  `apt-get -f install`). A version Debian already replaced comes from `snapshot.debian.org` at the approval time
+  (decision 79). Reports the full installed set with origins, pending, restart-needed (outside containers), health.
+  `configs/test_felhom_os_apply.py`: 35 tests; every refusal red-proved.
+- **`internal/osupdate`** — the leg: after a SUCCESSFUL primary whole-guest backup, still holding the heavy-op gate
+  (never beside another backup or a restore-test), once per night, 90 s after the backup. Ring 0 installs every pending
+  Debian / Debian-Security fix; ring 1 exactly the hub's newest approved release; switched OFF → reports only. The
+  health rule: docker answers, the network resolves, the controller is healthy, every container running at the START
+  of the leg runs (and is healthy if it was) — a 5-minute wait. **No automatic undo:** a customer guest cannot be
+  snapshotted (R-837). A failure is `health_failed` → the hub mails the operator.
+- **`--selftest=os-update -vmid N`** — the debug action (trigger `debug`, never throttled, not a night run).
+- **The `--selftest` flag also accepts `wgtunnel`** — it was dispatched but refused since S3 (found by the new
+  `TestSelftestFlag_AcceptsEveryDispatchedMode`, which also caught `os-update` live).
+- Proven live 2026-10-04 on both demo boxes (ring 0: 53 packages each; ring 1: exactly 3 approved versions; a failed
+  health check → `health_failed`, operator mailed): `felhom.eu/documentation/audits/os-guest-lane-2026-10-04/`.
+
+## v0.139.0 — a DR restore never lands beside a live original (2026-10-04, R-834)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.139.0` (`475bdce`), sha256
+> `8534a9be368a6d24d8065db77436e86900443c5c6554c71f6fe91c2bdb9d0b9c`, verified by download. **Not vouched.**
+
+**MinAgent impact:** none required by any controller.
+
+- The DR bring-up (`--selftest=bring-up -mode dr`) keeps the archive's `onboot: 1`, binds the host's REAL drives
+  (`mp8 /mnt/felhom-drives`) and STARTS the guest — right on a replaced host, wrong beside a live original (a second
+  controller for the same household on the same drives). It now REFUSES, before any restore, when the archive's
+  source guest still exists on the host, when any guest binds the drives parent, or when a guest's config cannot be
+  read (fail closed). On a replaced host it proceeds and keeps its binds, unchanged.
+- The restore-test was MEASURED safe live on demo-hp (onboot 0 and throwaway stand-ins for mp8/mp9 from the first
+  config read to teardown); a test now pins its "no host path" half beside the existing onboot test.
+- No sudoers change: the restore-test sets onboot 0 through the API create call, and DR refuses rather than degrade,
+  so no `-onboot 0` line is needed.
+- Tests: `TestRunBringUp_DRRefusesBesideALiveOriginal` (source guest present / drives bind on another guest / an
+  unreadable config refuse; a replaced host proceeds and keeps the drives bind), `TestRunBringUp_ProvisionNotBlockedByADrivesBind`,
+  `TestArchiveSourceVMID`, `TestRestoreTest_NoHostPathBindBesideTheOriginal`. Red-proofs: the DR check returning ""
+  → three refusal cases restore and START; the restore-test's mp8 override set to the host path → fails.
+
+## v0.138.0 — the restore test takes only THIS box's archives (2026-09-30, R-727, `09` §3 decision 51)
+
+> **RELEASED 2026-09-30** by `scripts/release-agent.sh` — tag `v0.138.0` (`e1b8269`), sha256
+> `55916026001790a79ebf97d32c032610cfde8e09d02979b9b9d8c2cbc5d88195`, verified by download. **Not vouched** (the golden
+> keeps 0.137.0 until the next bake); delivered to the demo boxes by signed `agent_update` jobs.
+>
+> **VOUCHED 2026-09-30** with golden 0.283.1 (`min_agent` 0.131.0), on the operator's word: the hub logged
+> `Artifact manifest set: agent=0.138.0 golden=0.283.1 min_agent="0.131.0"`. Evidence:
+> `felhom.eu/documentation/audits/evidence-golden-0283-2026-09-30/`.
+
+**MinAgent impact:** none required by any controller.
+
+- A returning customer's PBS namespace can hold archives of EARLIER boxes: same guest id (9201), same token, written
+  with a different key. Measured 2026-09-30: the newest SETTLED archive was an earlier box's, and the test failed
+  `wrong key … manifest's key 6b:ca:5f:3f… does not match provided key de:51:7a:18…` every evaluation. The archive
+  carries no host id; it carries its key fingerprint (PVE content `encrypted`), and the storage carries its own
+  (`GET /storage` → `encryption-key`). `PickSettledRestoreCandidateOn` now skips — and logs by name, once — an archive
+  whose fingerprint is not the storage's own; an unencrypted storage is not filtered; a failed storage read is an
+  error (tier UNKNOWN), never "nothing to prove".
+- Tests: `TestR727_TheRestoreTestTakesOnlyThisBoxsArchives` (the 2026-09-30 shape: nothing picked while this box's
+  archive settles, then exactly it), `TestR727_UnencryptedStorageIsNotFiltered`, `TestR727_KeyLookupFailureIsUnknown`.
+  Red-proof RP39: the skip removed → the earlier box's `2026-09-16T21:59:54Z` is picked.
+
+## v0.137.0 — a guest outside the agent's ACL is not a known guest (2026-09-27, R-689, v0.136.0 regression)
+
+> **RELEASED 2026-09-27** by `scripts/release-agent.sh` — tag `v0.137.0` (`3ef095f`), sha256 `766c9166916a1bd3674b0dc69081f8a7619e770f1402d8ad7705b395937e7627`, verified by download. **NOT vouched** (the operator's act).
+>
+> **VOUCHED 2026-09-28** with golden 0.276.0 (`min_agent` 0.131.0), on the operator's word of 2026-09-27: the hub logged
+> `Artifact manifest set: agent=0.137.0 golden=0.276.0 min_agent="0.131.0"`, and a Day-0 test install fetched this binary
+> through the manifest and sha-verified it. Evidence: `felhom.eu/documentation/audits/evidence-golden-0276-2026-09-28/`.
+
+**MinAgent impact:** none required by any controller.
+
+- v0.136.0 asked `GuestConfig` whether an archive's guest exists and treated anything but "does not exist" as a lookup
+  failure. PVE answers **403 "permission denied at /vms/<id>"** for a vmid outside the token's pool — so on demo-hp the
+  deleted guest 9100's archive made the local tier UNKNOWN every evaluation. A guest the agent cannot read is not one it
+  manages; its archive is skipped. `TestR689_AGuestOutsideTheAgentsACLIsNotAKnownGuest`, red-proofed. Verified read-only
+  on demo-hp with the pre-release binary before the release.
+
+## v0.136.0 — … of a guest that still EXISTS (2026-09-27, R-689 second half)
+
+> **RELEASED 2026-09-27** by `scripts/release-agent.sh` — tag `v0.136.0` (`16dbc83`), sha256 `2eb0b5ebe253defd68b322312bbac12418c051b0a7a0d2d1831310d97fa6d755`, verified by download. **NOT vouched** (the operator's act).
+
+**MinAgent impact:** none required by any controller.
+
+- **R-689, second half.** Read on demo-hp right after v0.135.0 with the read-only `-selftest=restore-test-due`: the
+  golden was skipped, and the pick fell to `vzdump-lxc-9100-2026_08_21…` — a leftover of a guest deleted in August. A
+  candidate's guest must now exist on this node (`GuestConfig`): "does not exist" skips the archive (INFO once per
+  volid); any other lookup failure is returned, so the tier reads UNKNOWN, never "nothing to prove". Tests
+  `TestR689_AnArchiveOfADeletedGuestIsNeverPicked` (red-proofed: without the check it picks the 9100 leftover),
+  `TestR689_AGuestLookupFailureIsUnknownNotEmpty`. A second agent release in one session — the first half was found
+  incomplete on the box.
+
+## v0.135.0 — the restore test proves only backups OF A GUEST (2026-09-27, R-689)
+
+> **RELEASED 2026-09-27** by `scripts/release-agent.sh` — tag `v0.135.0` (`d4be12c`), sha256 `ad4e75f16d338552f4588d3fe64c51cbf9651220b9d223b5386b85b6c37fd4c3`, verified by download. **NOT vouched** (the operator's act).
+
+**MinAgent impact:** none required by any controller.
+
+- **R-689** (`backup/runner.go` `guestBackupArchive`). demo-hp keeps its golden template in `local:backup/` — content
+  "backup", 654 MB, plausibly complete, the newest settled entry — and the scheduled restore test picked it every 6 h and
+  failed `extractconfig` with a 403, while the guest's real archive went untested. A restore-test candidate is now a
+  `vzdump-{lxc,qemu}-<vmid>-…` file or a PBS `backup/{ct,vm}/<vmid>/…` snapshot whose vmid the storage reports; anything
+  else is skipped with one INFO line per volid (not the "INCOMPLETE archive" WARN). Tests
+  `TestR689_TheRestoreTestNeverPicksTheGolden` (red-proof: without the check it picks the golden) and
+  `TestR689_GuestBackupArchiveShapes`; two older picker tests' fixtures moved to real archive names.
+  Evidence: `felhom.eu/documentation/audits/version-travel-2026-09-26/D1/`.
+
+## v0.134.0 — a whole-box backup that cannot fit is skipped with a reason, before anything starts (2026-09-25 night, R-685)
+
+> **RELEASED 2026-09-24 night** by `scripts/release-agent.sh` — tag `v0.134.0` (`0722b2c`), sha256 `7593bebe03234c7d22f3ade384e7ed7787dc659aa8c8594b3ee19af2ce81c72d`, verified by download. **NOT vouched** (Day-0 stays on the previous version).
+
+**MinAgent impact:** none required by any controller.
+
+- **R-685 — the backup space preflight** (`backup/runner.go` `spaceFits`). Before a vzdump to a LOCAL (non-PBS)
+  target, the newest archive of that guest on that target × 1.25 + 1 GiB must be free — PVE prunes old archives
+  only AFTER a successful backup, so the kept ones still stand during the run. A shortfall is a skip: nothing
+  starts, the record's Error reads `skipped: not enough space: <target> has X GiB free; the last archive of guest N
+  was Y GiB, so a new one needs about Z GiB …` (stable prefix `BackupSkipNoSpacePrefix`), and it reaches the
+  controller's tier view and, through the quiesce loop's tier notifier, the operator's `whole_guest_backup_failed`.
+  It FAILS OPEN on what is not known (PBS target, first backup, unreadable usage).
+- **Free space is read from `GET /nodes/<node>/storage`** (`NodeStorage`), never `GET /storage` — the latter is the
+  cluster DEFINITIONS and carries no usage. **Found live, before release:** the first build read `/storage`,
+  failed open, and a real vzdump of demo-hp 9201 started from the live test; it was aborted after 5 min 16 s, no
+  archive left (`felhom.eu/documentation/audits/night-2026-09-25/F/`). The test fake's `ListStorage` now strips
+  usage like production. Red-proofs: two (`…/F/redproof-r685-*.txt`).
+- Live proof (demo-hp, safe builds with a hard stop before vzdump): ×10 margin → refused, "local has 14.9 GiB
+  free … needs about 77.2 GiB"; release margin → "space preflight passed" need 11.3 GB, avail 16.0 GB.
+
+## v0.133.0 — a restore-test can never fill a box's disk; leftovers retried on a timer (2026-09-24, R-672, R-673)
+
+> **RELEASED 2026-09-24** by `scripts/release-agent.sh` — tag `v0.133.0` (`9bdb4da`), sha256 `3aa303452b8c6be58573d00af01a0ab4a0d97e4f885ffecd0144a18ac24e69b6`, verified by an independent anonymous download. **NOT delivered** (needs an operator-signed `agent_update` job per box, R-530) and **NOT vouched**.
+
+**MinAgent impact:** none required by any controller. Hub **v0.124.0** makes a thin pool CRITICAL at 90 %
+(data or metadata) and keys the storage-fill alarm per pool per 6 h; an older hub still raises its generic
+90/95 % storage-fill events from the same report.
+
+- **R-672 — the space preflight** (`reconcile/restoretest_space.go`, provider `internal/restorespace`). Before
+  anything is journaled or created, a restore-test needs free data ≥ restored × 1.2 + 5 GiB on its target
+  (`backup.restore_test_space_factor` / `backup.restore_test_space_reserve_gib`) and room in a thin pool's
+  metadata. `restored` is the UNCOMPRESSED size — the vzdump log's "Total bytes written" (a file-backed
+  archive) or the PBS snapshot size; the archive FILE is never used (9201: 6.9 GB file, 22.6 GB restore). The
+  target moves OFF the tested guest's own pool when another storage is eligible (active, `rootdir`, and the
+  agent holds Datastore.AllocateSpace there) and fits. Anything unknown refuses. A refusal is reported to the
+  hub as the test's result (`pass=false`, `skipped=true`, "skipped: not enough space on …") — never a pass,
+  never dropped. The archive config is read once (it was read twice). Measured case: demo-hp 2026-09-24 —
+  the restore-test that filled `local-lvm` would now be refused (needs 32.1 GB, 23.2 GB free).
+- **R-672 — a failed scratch teardown is retried every 10 minutes** (`Engine.RetryScratchTeardown`, the
+  daemon's janitor), not only by Recover at agent start; never a vmid a running test owns; after 3 failed
+  tries the operator is told through a failed restore-test record naming the scratch guest.
+- **R-672 — a thin pool crossing 90 % requests an immediate host report** (`Observer.SetThinHighTrigger`, the
+  storage watchdog's read path, every few seconds; re-armed below 85 %), so the hub's alarm sees it in
+  seconds, not at the next 15-minute report.
+- **R-673 — the stale-lock sweep runs on the same 10-minute timer** (it ran only at start: a stale
+  `snapshot-delete` lock blocked 9201's whole-box backups for five hours), holding the one-heavy-operation
+  gate so no agent backup can start between its "no vzdump running" check and its unlock.
+- Red-proofs: six, each seen failing (REPORT).
+
+## v0.132.0 — a controller that dies slowly is reported, not just restarted (2026-09-17, R-539)
+
+> **RELEASED 2026-09-17** by `scripts/release-agent.sh` — tag `v0.132.0`, sha256 `4afe815749a41b327ebe4a98a4557ad2acffb1fa71740a3a8b8003473b835321`. **Vouched 2026-09-17** for Day-0 installs on the operator's word, together with golden **0.246.0** (the hub's R-120 gate required the newer golden first). Delivered to demo-hp and the N100 by an operator-signed `agent_update` job each (operator ruling 3 of 2026-09-16), not by a floor.
+
+**MinAgent impact:** none required by any controller. Hub **v0.117.0** turns the new fields into
+`controller_slow_crashloop`; an older hub ignores them.
+
+- **R-539 (operator ruling 3 of 2026-09-16) — the slow crash-loop counter.** The 3-restarts-in-15-minutes
+  brake cannot see a controller that dies every 20 minutes (measured 2026-09-16, R-531: four restarts,
+  none accumulating, only an `info` event that mails nobody). Beside it, unchanged, a second counter:
+  restarts the supervisor performed in the last **24 hours**; at the **fifth**, the heartbeat's
+  `controller_supervisor` stanza sets `slow_crashloop_since` (and `slow_crashloop: true`,
+  `restarts_24h`). The hub mails on that timestamp MOVING; it moves **at most once per 24 hours**. It
+  does **not** stop restarting — the fast brake remains the only brake.
+- **Persisted per guest** at `/var/lib/felhom-agent/guests/<vmid>/controller-restarts-24h.json`
+  (tmp + rename, 0600), so an agent restart or a host reboot does not reset it. The fast record stays
+  in memory; the reason it does (a persisted "give up" could outlive the fix) does not apply to a
+  counter that only warns. Unreadable or corrupt → WARN and a clean start, never a blocked supervisor.
+- **Deliberate kills count.** The supervisor cannot tell an operator's `docker kill` from a crash
+  (measured 2026-09-15); a controller killed five times a day is worth a line either way.
+- The supervisor's startup line now prints `slow_crashloop_max=5 slow_crashloop_window=24h0m0s`.
+
+**Red-proofs, each seen failing:** five restarts 20 minutes apart raise it
+(`TestControllerSupervisor_SlowCrashloop` — fails with no counter; fails again with the once-per-24-hours
+guard removed, "the operator would be mailed per restart"); the counter survives an agent restart
+(`…SlowCounterSurvivesAgentRestart` — fails with the save removed, `Restarts24h:1`); restarts seven hours
+apart never raise it (the negative control). Wire shape extended with `restarts_24h` and `slow_crashloop`.
+
+## v0.131.0 — a dead controller comes back by itself; the backup status speaks per tier (2026-09-15, R-523 / R-517 / R-518)
+
+> **RELEASED 2026-09-15** by `scripts/release-agent.sh` — tag `v0.131.0`, sha256 `1118b552f7e775fbde9544c7764ede7e6046e0a7db16ae8494d07a18e3c2ac9c`. Delivered to boxes by the controller v0.243.0 floor (declared MinAgent), not by hand.
+
+- **R-523 (P1) — the in-guest controller supervisor.** BIGNIGHT F9: `docker kill felhom-controller`
+  left the household's dashboard on 502 for 33 minutes, because nothing watched the container.
+  Measured first (2026-09-15, Docker 29.8.0, `evidence-p1fixes-2026-09-15/A1`): after `docker kill`,
+  BOTH `--restart unless-stopped` and `--restart always` leave the container `exited (137)` after
+  60 s — a policy change alone is not a fix. New `internal/localapi/controllersupervisor.go`: every
+  30 s, for each felhom-pool guest the agent provisioned (`<guests>/<vmid>/bootstrap` exists) that is
+  running, it reads `docker inspect -f {{.State.Status}} felhom-controller`; on the SECOND consecutive
+  not-running (or absent) observation it runs `systemctl restart felhom-controller-bootstrap.service`
+  inside the guest — the swap's own restart, over the same GuestExecutor and the same two sudoers
+  grants. No new privilege. Guards, each pinned by a test: not during a controller swap (the swap's
+  in-flight flag); not when parked (`touch /var/lib/felhom-agent/guests/<vmid>/controller-parked` on
+  the HOST); not on a stopped, locked or vzdump-busy guest; not on an unknown docker answer; not on a
+  guest the agent did not provision; and **no thrash** — 3 restarts in 15 minutes stop the restarts
+  for 30 minutes. The record rides the host report as `controller_supervisor` (additive,
+  `omitempty`); hub v0.114.0 mints `controller_restarted_by_agent` (info) and `controller_crashloop`
+  (error), both operator-only. Red-proofs: without the restart call, the kill test fails at
+  "restarts=0"; without the backoff block, the crash-loop test fails at "restarted 10 times".
+- **Golden script** (`configs/build-golden.sh`): the controller runs `--restart always` (covers a
+  Docker daemon restart after a manual stop — nothing more). **No golden baked here** (R-468); existing
+  boxes keep `unless-stopped` until their next golden and are covered by the supervisor.
+- **R-517 (P1) — `GET /backup/status` speaks per tier.** The untargeted response gains `tiers[]`:
+  per tier the newest SUCCESSFUL backup (`last_success`, from the record, or from the tier's storage
+  after an agent restart — `last_success_source: storage`), the last attempt kept apart
+  (`last_attempt {started_at, success, error}`), and whether the tier's storage exists (`storage:
+  present|absent|unknown`). `GET /backup/tiers` gains the same `storage` field (R-518's cheap half: the
+  controller skips an absent tier). `unknown` is never `absent` — a storage view that cannot be read
+  must not skip a backup. Additive; the untargeted `.backup` keeps its meaning (pinned). Red-proof:
+  filling `last_success` from the newest ATTEMPT fails at "pbs tier reports a failed attempt as its
+  last success".
+
+## the decoy sweep — can this gate be fooled by a label? (2026-09-01, R-421) — NOT A RELEASE
+
+**No product code, no version bump, no image, no golden.** A scripts change is not a release.
+
+Four times in one week a gate turned out to match a NAME instead of the thing it named — R-410 (a
+`mkdir` turned the release gate green), R-400 (seven debug controls answering nothing), R-378 (a
+status word inside a sentence), R-419 (a phrase inside prose, including prose saying the marker was
+absent). **All four found by accident.** The gates enforce everything else here and were the one part
+nothing had checked.
+
+**All 29 gate scripts read and decoyed. 16 were fooled.** 10 fixed here, 4 left with rows
+(R-422..R-425), 6 could not be given a plausible decoy and are named (R-426 group d).
+
+**The largest single cause was mundane:** eight gates set their SCOPE with `os.listdir` (one level).
+Green and correct today; blind the moment anyone adds `templates/partials/`. `mojibake` and
+`docker-v` already used `os.walk`, caught the identical planted file, and are the control that
+proves the cause was the listing rather than the decoy.
+
+Full survey table, and the five decoys withdrawn as illegitimate (mine, named):
+`documentation/audits/AUDIT-gate-decoys-2026-09-01.md`.
+
+**In this repo:** no gate changed, and that is the result. `release-complete` was decoyed and is
+SOUND — the sweep's attempt (a non-version heading on top of `CHANGELOG.md`) was WITHDRAWN as
+illegitimate, because `HEAD_RE.search` scans the whole file and still names `v0.130.0`. The three
+shared gates are covered from `felhom.eu`; the remaining two are named in the decoy-coverage
+exemption list (R-426) as UNTESTED, not as sound.
+
+## v0.130.0 — the agent was the one leaking connections onto the off-site box (2026-08-20, R-344)
+
+> **RELEASED 2026-08-20**, on the operator's word, after the fix was proved on both boxes.
+> `sha256 a56a92a7bd68f5b46736eaec4806c3d26c16ccb35118c4ac0e3d8094eaefabc3`, 14,141,158 bytes,
+> tag `v0.130.0` at `7569f34`. Reproducible: a rebuild with `-trimpath -buildvcs=false` matches the
+> published artifact byte for byte (R-186's property, checked rather than assumed).
+>
+> The heading read `## UNRELEASED — v0.130.0 candidate` until this point, deliberately: while the fix
+> was hand-installed on `demo-hp` only, publishing would have pushed it onto `demo-felhom` through
+> self-update and destroyed the control the proof rested on. **`release-complete` convicted on the
+> release heading and was right to** — the answer was to stop claiming a release, not to bypass the
+> gate. See R-347.
+>
+> **The fleet runs these exact bytes.** Both demo boxes were first given a hand build made during the
+> proof — same source, same version string, **different bytes** (`256e0829…`), because
+> `release-agent.sh` builds with `-trimpath -buildvcs=false` and a hand build does not. Nothing would
+> have corrected that: the boxes already reported `0.130.0`, so self-update saw the vouched version as
+> installed and would have done nothing, forever. Both were reinstalled from the **downloaded package**
+> and now report `a56a92a7…`. Filed as **R-349**, because every prove-then-publish train hits it.
+
+**What was measured, before anything was changed.** Between 2026-08-18 09:51:22Z and 2026-08-20
+08:02:13Z, ep0's PBS proxy accumulated **388 established connections** — 194 from each demo box, on a
+proxy whose descriptor ceiling is 65536 and whose runway at that rate was ~323 days. The connections
+were held open on **both** sides: ep0 showed 388 while the two boxes showed 194 + 194, at two separate
+instants, with the same source ports on each side, and **not one closed in a 31-minute window**.
+`ss -tnp` on the boxes named the holder: **`felhom-agent`**, 194 of 194 on each, one PID.
+
+**`pvestatd` and `proxmox-backup-client` made 162,404 requests in that window and leaked zero.** They
+are 99.5% of the traffic to that endpoint and 0% of the leak. The agent made 811 requests — of which
+387 were `GET .../snapshots` — and leaked 388 sockets. One per call, within one.
+
+**The defect, and it is two things compounding.**
+
+- `internal/pbs/client.go` built its transport as a composite literal:
+  `&http.Transport{TLSClientConfig: tlsCfg}`. That takes **`IdleConnTimeout` zero, which does not mean
+  "use a sane default" — it means retain idle keep-alive connections FOREVER.**
+  `http.DefaultTransport` sets 90s; hand-rolling the transport (which every client here must do,
+  because they all pin TLS) silently discards it.
+- `pbsTargetsFromPVE` (`cmd/felhom-agent/main.go`) builds **a fresh `pbs.Client` every cycle**, as its
+  own doc comment says, and drops the previous one. An abandoned `http.Transport` does **not** close
+  its connections — it becomes unreachable while its `persistConn` read-loop goroutine keeps the
+  socket alive. So each cycle stranded exactly one connection that nothing could ever close.
+
+The cadences reconcile without fitting: a 900s live-snapshot collect (184.7 cycles in the window) plus
+a 6-hour verify loop (7.7) predicts 192.4 per box against **194 observed**.
+
+**The fix is one field, restored to the standard library's own value.** New leaf package
+`internal/httpx` owns `DefaultIdleConnTimeout = 90 * time.Second` — 90s because that is what
+`http.DefaultTransport` uses, so there is nothing invented here to justify or tune — and
+`NewTransport(tlsCfg, idleConnTimeout)`, which returns a **fresh** transport (never shared: each caller
+pins a different endpoint) and treats a zero or negative timeout as **use the default, never "no
+timeout"**. `pbs.Config` gains an `IdleConnTimeout` field that production leaves unset; only tests set
+it, to avoid a 90-second wait.
+
+**`internal/hub/client.go` and `internal/proxmox/client.go` carried the identical missing default and
+were corrected in the same pass — but neither contributed to the ep0 leak, and this entry must not be
+read as three leaks having been found.** Both are built **once per process**, so they held one idle
+connection for the life of the daemon rather than accumulating, and neither talks to ep0:8007.
+
+**Tests, and what they deliberately do not assert.** `internal/pbs/client_leak_test.go` counts
+connections **server-side** and models what `pbsTargetsFromPVE` actually does — build a client, use it
+once, drop it on the floor — then asserts the connections go away. It does not assert `err == nil` and
+it does not assert that some field holds some value; both were true of the leaking code.
+
+- **Red-proof 1 (the fix):** removing `IdleConnTimeout` from `NewTransport` fails the test with
+  *"after 5s the server still holds 5 open connection(s), want 0 (5 dialled in total)"* — the count is
+  in the message, so the failure cannot be mistaken for a timeout with another cause. Reverted.
+- **Red-proof 2 (the fix that would be worse than the bug):** setting `DisableKeepAlives: true` also
+  makes the leak vanish — by dialling fresh for every request, which on a box polling ~40,000 times a
+  day is strictly worse than what we started with. **The leak test PASSES under that mutation**;
+  `TestPBSClient_KeepAliveStillReuses` is what catches it, failing with *"3 sequential requests over 3
+  connection(s), want 1"*. Reverted.
+
+**What this release does NOT do.** It does not reduce the poll rate (**R-336 stays open, but re-scoped
+— it was never the cause of this leak**), it does not refactor `pbsTargetsFromPVE` to cache or reuse
+clients (a one-line default restores the standard behaviour; a lifecycle refactor adds
+cache-invalidation questions for no measurable gain), and it adds no `CloseIdleConnections` call.
+
+**One sentence in this entry was written before the deploy and was WRONG, and it is corrected here
+rather than quietly edited.** It read: *"does not clear the 388 descriptors already stuck on ep0 —
+those persist until that proxy restarts."* **Measured: they clear the moment the AGENT restarts.**
+Replacing the binary on `demo-hp` released exactly its 199 descriptors within one second
+(415 → 216 fd), and replacing it on `demo-felhom` released the remaining 203 (**220 → 17 fd in under
+two seconds**). **17 is precisely ep0's `t0` baseline** of 2026-08-18 09:51:22Z. ep0 was read-only
+throughout and its proxy PID never changed. The accumulated leak was never ep0's to hold on to — it
+was held on both sides, and closing either side ends it.
+
+## v0.129.0 — a correct code for an earlier package stops being called wrong (2026-08-12, R-311)
+
+**The measurement this fixes.** On 2026-08-12 a recovery code that provably opens a RETAINED package
+— unsealed by hand, and it restored planted files byte-identical from a store the box itself could no
+longer open — was answered by this agent with *"the recovery code did not open the sealed bundle"*.
+The code was correct. Nothing had ever tried the retained packages, so the engine could not tell a
+correct-but-earlier code from a mistype, and the screen said so out loud: a true sentence about our
+own incuriosity, read by the customer as a statement about their code.
+
+**`OffsiteKeyRecoverer` gains an optional `FetchRetained`.** It is consulted ONLY after the current
+package has refused, so the ordinary recovery pays nothing for it and cannot fail because of it. When
+one of the retained packages opens, the recoverer returns `ErrCodeOpensRetained` wrapped in a
+`RetainedOpenedError` carrying the supersession date — no material, no code, no password.
+
+**The local API answers 422** ("your code is correct, it belongs to an EARLIER sealed package") — a
+FIFTH status added to the R-224 switch, not a restructuring of it. 422 rather than 400 because the
+request was well-formed AND the credential valid; a 400 would put it in the same bucket as a mistype,
+which is the defect.
+
+**Fail-safe in every direction.** A nil fetcher, a hub too old to have the route (404 is a clean
+"none"), a transport failure, a malformed package: each leaves the original refusal standing,
+unchanged. The worst outcome of this feature breaking is the behaviour we had before it existed.
+Attempts are bounded (`MaxRetainedTried`, default 6) because each unwrap is ~1 s of scrypt by design
+and an unbounded loop would turn one wrong code into a minutes-long hang.
+
+**New hub client call:** `FetchRetainedIdentityEscrow` → `GET /api/v1/hosts/<id>/escrow/retained`
+(hub >= v0.103.0), self-scoped by the same per-host key.
+
+Seven tests with REAL age crypto, because the two situations are indistinguishable AT THE UNWRAP and a
+faked unwrap would prove nothing about what was broken. Red-proof, asserted applied: removing the
+retained lookup returns the fail-closed wrong-code error — **the lie comes back, in those words.**
+
+---
+
+### Gates only — 2026-08-09 (no release, no version bump, no binary published)
+
+**Two guards, both owed since the 2026-08-09 install outage (R-273/R-287). Nothing that runs on a
+customer's box changed; `scripts/` only, and the agent stays v0.128.0.**
+
+- **`scripts/retention-policy.json` — THE retention number, in one file.** The registry stopped
+  serving `felhom-agent` 0.120.0 and older while `check-published-versions.py` demanded that every
+  tag still be downloadable. Both rules are sensible; together they are impossible, and CI went red
+  at a commit whose own run had been green the day before. The check now **reads the number from
+  this file** and bounds its assertion to the newest N generic versions.
+  **What CI no longer covers, said plainly rather than left to be discovered:** a released version
+  older than the retention window is **no longer asserted downloadable**. Its git tag and its configs
+  are still asserted — only the binary's presence is dropped. The check **prints exactly which
+  versions it stopped covering** on every run, so the narrowing cannot become permanent by accident.
+  **The number is an OBSERVED state, not a located ruling** — see the file's own header and R-287.
+  A missing or unreadable policy file is **INCONCLUSIVE (exit 2), never silently unbounded.**
+- **`scripts/check-release-complete.py` — the tag half, as a machine.** Asserts that the version at
+  the head of `CHANGELOG.md` is tagged, that the tag points into this history, and that its package
+  is published. `release-agent.sh` already warned about this in as many words and the step was still
+  missed on 2026-08-08, which is why this is a gate and not a reminder. Legs 1–2 need no network and
+  therefore run in `--fast`, so the pre-push hook catches a missing tag at the earliest moment.
+  Registered in `agent_gates.py`; red-proved by pointing the CHANGELOG head at an unreleased
+  v0.129.0 — both legs convicted and each named its fix command.
+
+## v0.128.0 — the escrow seed is asserted every tick, not remembered once (2026-08-08, R-221)
+
+**A rebuilt box could not run the escrow ceremony at all, and there was no way forward from inside
+the product.** The preflight refuses on `escrow.pbs_storage_id`; the pbsdr bridge writes that key;
+and it wrote it from exactly one place — `finishConverged`, reached only on the paths that actually
+converge.
+
+**The two things live in different places and die at different times.** The convergence marker is
+host-side (`<agent-state>/pbsdr/marker.json`). The key it seeds is in `agent.json`, which
+`step_agent_config` renders from `base = {}` unless an explicit `--preserve-from` is passed
+(`felhom.eu/scripts/felhom-host-install.sh:2396`, the render at `:2449`, the `O_TRUNC` write at
+`:2579`; the flag at `:1246`, defaulting empty at `:256`) — **and the render never writes an
+`escrow` section at all.** So a rebuild keeps the marker and takes the key: same descriptor, same
+hash, early return, and the seed never runs again into a config that no longer has it.
+
+**Fixed by asserting rather than remembering.** `Apply` now re-asserts the seed *before* the
+idempotent early return. `seedEscrowStorageID` is unchanged and still never clobbers a different
+existing value — an operator's own choice outranks the descriptor's, with a warning naming both.
+
+**The early return is KEPT.** It exists so a converged box does not re-run Proxmox operations every
+60 s, and `TestSeedReasserted_OnConvergedTick_WithZeroProxmoxCalls` asserts **zero** recorded runner
+calls on that tick — so a "fix" that simply deleted the return would fail. Cost of the re-assert: one
+small file read plus a JSON parse per tick, no exec, no network, and an early return once the value
+matches.
+
+**A seed failure can never un-converge the box:** Warn plus a message on the published status,
+exactly as `finishConverged` does it — no marker write, no state change. Pinned by
+`TestSeedReassertFailure_DoesNotUnconverge`.
+
+Tests drive the real `Apply` with a real temp-dir `agent.json` and a call-recording runner; calling
+`seedEscrowStorageID` directly cannot see the early return, which IS the defect. The production
+wiring (`pbsdr.NewManager(..., cfg.SourcePath, ...)`) is asserted by walking `main.go`'s **AST**, not
+by `strings.Contains`, which a commented-out call also satisfies.
+
+Red-proofs: removing the new call makes Scenario A fail on today's tree; removing the early return
+makes the zero-Proxmox-calls assertion fail.
+
+## (no version bump) — a comment that claimed the hub reads a field it has no field for (2026-08-08, R-260)
+
+Comment-only; no behaviour, no wire change, nothing to rebuild.
+
+`HostReport.SelfUpdatePending` / `SelfUpdatePendingVersion` carried the sentence *"The hub reads an
+absent field as pending=false, the correct default."* **The hub has no field for either**, so it reads
+nothing — present or absent — and `encoding/json` discards them on arrival. The sentence described an
+intent rather than the code and read as settled for long enough that a class sweep had to find it.
+
+The emission is correct and stays: the agent reports the truth, and the fault is entirely in the
+receiving. The missing consumer is tracked as **R-264** (OPEN), and
+`felhom.eu/scripts/wire_contract_gate.py` now refuses any NEW field of this shape while recording the
+existing ones as explicit, reasoned allowlist entries rather than silence.
+
+## v0.127.0 — a mount Felhom itself made is not "something else" (2026-08-06, R-220)
+
+**After a rebuild the customer's own drives could not be re-attached, and the refusal named an action
+they could not perform.** `GET /api/disks/candidates` returned `initialize: [], attach: []` while both
+drives sat there, and the deploy refused with *"choose an attached drive from the list"* — a list that
+was empty. Measured live **three times**: CAMPAIGN-11 Phase 1, and twice on the R-201 re-walk.
+
+**The mechanism.** Enrolment mounts a drive **twice** — at the managed `/mnt/felhom-drives/<name>` and
+at the raw `/mnt/<name>` it creates on the host. **The host survives a guest rebuild; the controller's
+registry does not.** So `classifyClaim` saw a mount outside the managed prefix and correctly concluded
+"claimed by something else" — about Felhom's own mount.
+
+**The fix is CORROBORATED, not a widened prefix.** A mountpoint outside `/mnt/felhom-drives` is
+forgiven **only when the same device is ALSO mounted under the managed path** — a pairing that only
+Felhom's own enrolment produces. A disk another system is using, at `/srv/data` or `/media/x` or even
+`/mnt/someone-elses-disk`, has no such counterpart and **is still refused**. That fence has its own
+test, and its red-proof shows an over-wide fix offering `/mnt/someone-elses-disk` for formatting.
+
+**Read from `/proc/mounts`, deliberately.** The lsblk invocation is pinned **verbatim** in
+`configs/felhom-agent.sudoers` (`lsblk -J -o NAME,FSTYPE,PTTYPE,MOUNTPOINT /dev/*`), so switching it to
+the plural `MOUNTPOINTS` would have meant shipping a sudoers change with the binary — a far larger
+blast radius than this finding warrants. `/proc/mounts` is world-readable: **no sudo, no new allowlisted
+command, no config change.**
+
+**Fail-safe:** an unreadable mount table corroborates **nothing**, so the device classifies exactly as
+it did before this change — refused. "We could not corroborate" must never read as "it is ours".
+
+Tests: `claim_r220_test.go` — the own-drive case, the foreign-mount fence over four paths, and the
+corroboration itself (both mounts required; a lone raw mount vouches for nothing; another device's
+managed mount does not vouch for this one; an unreadable table corroborates nothing).
+**Red-proofs:** removing the exemption refuses the customer's own drive again
+(*"device is mounted at /mnt/adatok (sdb)"*); over-widening it to any `/mnt/*` path breaks the fence.
+
+## docs — CLAUDE.md becomes a core plus path-scoped rules (2026-08-06, R-229 leg (b)) — no version bump
+
+**Documentation only. No Go changed, nothing built, nothing deployed.** `go build`/`vet`/`test` green
+and unchanged.
+
+**175 -> 99 effective lines** (207 -> 103 raw, 14,093 -> 6,267 bytes). The release/publish-train
+section was the largest block and the `felhom-build-deploy` skill already carries the procedure, so
+the core points at it instead of restating a table that drifts from the script. The package layout
+went the same way as the controller's: `REUSE.md` and the tree are its home, and the per-package
+annotations that were doing real work moved into the rule file for the area they describe rather than
+being deleted.
+
+**New:** `.claude/rules/{proxmox,localapi,backup,storage}.md`, all `paths:`-scoped, all <=46 effective
+lines, joining the existing `health-checks.md`.
+
+**Kept in the core deliberately** — it is the only part re-injected after `/compact`: the root-CLI
+fence and its three named exceptions (breaching it is how this component stops being auditable), the
+destructive-op gate, the prove-ownership rule from audit A1, the gate entry point, the F9
+live-validation fence, trunk-based with its revert-and-report escape hatch, and the end-of-session
+checklist.
+
+**Glob overlap, stated rather than silently resolved:** `health-checks.md` matches
+`internal/{localapi,guesthook}/**` and `internal/storage/**`, which `localapi.md` and `storage.md`
+also match. Both rules load in those directories and neither supersedes the other; each new file says
+so in its own text so a reader who sees two rules fire is not left guessing which wins.
+
+## docs — the "CI is still owed" claim was stale; corrected (2026-08-06, R-229 part 2) — no version bump
+
+**One sentence, no code.** This file asserted that continuous integration was still owed
+(`felhom.eu` `OPEN-ITEMS.md` R-168). **R-168 was CLOSED on 2026-08-02** — a Gitea Actions runner
+re-runs each repo's gate entry point on every push and emails the operator on failure. Found while
+confirming this session's own push by run ID, which is the check that caught it.
+
+The same stale sentence was in four instruction files across all four repos and is corrected in all
+four. In `felhom-agent/CLAUDE.md` it **contradicted the same file's release section**, which already
+said R-168 mails the failure — a contradiction inside one instruction file, which is the exact class
+the R-229 work exists to find.
+
+## docs — expired and contradictory blocks removed from CLAUDE.md (2026-08-06, R-229) — no version bump
+
+**Documentation and gate registration only. No Go changed, nothing built, nothing deployed.**
+
+Surgical corrections; the file was deliberately **not** restructured (that is deferred, R-229).
+
+- **Deleted the expired TEMPORARY block.** It read *"felhom-pve is at a remote site (until
+  ~2026-08-02) … Delete this block on return"* and was still being read as current fact on
+  **2026-08-06**, four days past its own deadline — while `felhom-controller/CLAUDE.md` asserted the
+  opposite. The location-independence fact worth keeping (`localapi` binds `169.254.253.1:8443` on
+  `vmbr9` since the R-50 island migration) moved to an HTML comment.
+- **Every component version literal is gone** from effective text, including
+  `felhom-agent --version → 0.115.0` and the `go.mod` Go directive. Versions change several times a
+  day; ask the hub's `/hosts` + `/configs` or the box.
+- The drill-VM claim and the host addresses now point at `documentation/operations/nodes.md`, which
+  already stated both correctly. **This file's drill-VM claim was the correct one** — confirmed by
+  `qm list` on demo-hp.
+- The R-115/R-188/R-186 release **narratives** moved to an HTML comment and to the
+  `felhom-build-deploy` skill; the **directives** stayed (never hand-roll the build; the
+  build → tag → publish → push order; reproducible `-trimpath -buildvcs=false`).
+- The health-check block-I/O rule became `.claude/rules/health-checks.md`, scoped to the five
+  packages where health checks are written. It had been duplicated from `felhom.eu/CLAUDE.md` *with a
+  note explaining that that file does not load in an agent-only session* — correct reasoning, made
+  obsolete by path-scoped rules.
+
+`agent_gates.py` now registers **`instructions`** (shared, `felhom.eu/scripts/`, never copied).
+
+Full accounting: `felhom.eu/documentation/audits/LEDGER-instruction-trim-2026-08-06.md`.
+
+## v0.126.0 — a fetch failure is not a wrong recovery code (2026-08-06, R-224)
+
+**A hub the agent could not reach was reported to the customer as a bad recovery code.** Measured live
+on 2026-08-05 (CAMPAIGN-11 F3): with the hub REJECTed at the appliance's firewall and a **correct,
+current** recovery code, the customer was told their code did not open their package — **in 0.0556 s**,
+against ~1.0 s for a genuine unseal. No unseal was attempted. F4 produced the same message in 0.0299 s
+with this agent stopped.
+
+**The discriminator existed here the whole time and this boundary threw it away.** `recover.go` fails
+at four distinguishable points; the local-api handler had cases for two of them and a `default` that
+answered *"the recovery code did not open the sealed bundle, or the bundle could not be fetched"* —
+one sentence for two situations, only one of which is the customer's doing.
+
+**The fix is a value, not a log line.** `escrow.ErrBundleFetch` joins the fetch leg's error, and the
+handler routes it to **502** with its own words: *"the sealed recovery bundle could not be fetched from
+the hub — the recovery code was NOT used and nothing was written."* 502 rather than 4xx because the
+request was not bad; an upstream dependency failed. The `default` now carries **only** the fail-closed
+wrong-code case and says so without the "or".
+
+Four situations, four statuses — **502** fetch failed · **400** the bundle was fetched and refused the
+code · **404** the hub holds no bundle · **409** the bundle predates the repository-password field.
+The controller classifies on the STATUS and must never parse these sentences.
+
+⚠ **A GREEN TEST NAMED THIS DEFECT AND DID NOT PREVENT IT.**
+`TestRecoverOffsiteRepoPassword_FetchErrorIsDistinct` has said since v0.125.0 that *"the operator must
+not be sent to re-read their recovery code because the hub was unreachable"* — and it passed
+throughout, because it asserted this package's error **string** one layer below where the merge
+happened, and a string is something no caller can branch on. It now asserts the sentinel, and its
+consequence-level twin asserts the STATUS at the boundary the customer's message is derived from.
+**Prefer the test that asserts the consequence over the one that asserts the mechanism.**
+
+Tests: `recover_test.go` (fetch classifies as `ErrBundleFetch`; a wrong code does **not**; an absent
+blob keeps its own identity) and `localapi/escrow_recover_class_test.go` (each situation's status, and
+a standalone assertion that fetch-failure and wrong-code never share one). **Red-proofs:** removing the
+`%w` join fails the sentinel test; deleting the handler case makes both answer `400` with the
+wrong-code sentence — the exact pre-fix code, and the exact defect CAMPAIGN-11 measured.
+
+## v0.125.0 — the agent opens the sealed bundle and returns one field (2026-08-04, R-199 links 7–8)
+
+**Link 7 had one production caller and it was a `--selftest`.** `UnwrapIdentityBundle` has existed
+since slice 10D.1 and the only thing that ever called it was `runSelftestIdentityConsume`, reading the
+recovery code from an environment variable by hand. **Link 8 did not exist at all:** that selftest
+writes the whole bundle JSON to a file, and its success message named `tunnel_token + pbs_token` —
+an enumeration that was accurate when written and became a MISSTATEMENT the moment v0.77.0 sealed the
+offsite repository password into the same bundle. Anyone reading that output would conclude the
+repository password was not there. It now names what THIS bundle actually carried and what it did not.
+
+**`POST /escrow/recover-offsite-password`** on the pinned local API: the controller supplies the
+customer's recovery code, the agent fetches this host's own sealed blob from the hub
+(`hub.Client.FetchIdentityEscrow`, hub ≥ v0.94.0, self-scoped by the per-host key), unseals it, and
+returns **only the offsite restic repository password** plus its sha256.
+
+**Only that field, on purpose.** The bundle also carries the tunnel token, the PBS token and the WG
+private key. The controller is a trust tier down and needs none of them; returning them would widen
+the blast radius of a controller compromise for nothing. Narrowing costs nothing now and is not
+recoverable later.
+
+**Why the agent and not the controller:** `age` is an agent runtime dependency and is deliberately
+absent from the controller image; the blob is a host-scoped object whose only writer is this agent
+under the per-host key, so the read is that write's mirror.
+
+**R's handling is the tightest rule in this release.** It arrives in the request body over the pinned
+channel, is held in memory for one call, is cleared on the success path AND every failure path, is
+never written to disk, never an argument in a process list, never logged at any level including
+inside an error, and is never echoed. `UnwrapIdentity` already stages only the blob and the recovered
+plaintext in a temp dir it removes; a test redirects TMPDIR and asserts **the tree is empty
+afterwards** — emptiness rather than a content scan, because a content scan is defeated by a later
+call overwriting the leaked file, which is exactly how the first version of that test passed its own
+red-proof while R sat on disk.
+
+Three outcomes are distinct rather than one generic failure: no blob (404 — no ceremony has run), a
+bundle that opens but predates the field (409 — a pre-fork-4 blob, which cannot be retro-fitted), and
+a code that does not open it (400 — fail-closed at the KDF, nothing written). Sending an operator to
+re-check a correctly typed recovery code because the hub was unreachable is the mistake this avoids.
+
+**The wiring is asserted by an AST walk**, not a `strings.Contains`: `main` → `runDaemon` →
+`buildLocalAPIServer`, where an `escrow.OffsiteKeyRecoverer` is constructed and passed as
+`localapi.Options.EscrowRecovery`, and its fetcher calls the DAEMON's own hub client (the self-scoping
+that makes cross-host retrieval impossible is a property of which key is used). This project's
+built-but-never-wired count is six and links 6–7 were two of them; the fix must not become the seventh.
+
+## v0.124.1 — the repair record must survive the probe that did NOT feed the hub (2026-08-04, R-190)
+
+**v0.124.0's transition record did not reach the hub, and the live run is what showed it.** The
+capability reported degraded for "one cycle" — meaning the probe call that performed the repair. But
+`probeAll` is invoked **independently** by the periodic self-check log and by the collector building a
+host-report. On the demo box the repairing call was the log's (`09:39:34`, journal shows
+`GRANT WAS MISSING AND HAS BEEN SELF-REPAIRED` and `degraded=1`), and the host-report built three
+seconds later found the grant present and sent **`ok`**. The agent's journal had the record; the hub
+had nothing; the operator would have learned nothing.
+
+That is the exact silence R-190 is about, re-created inside its own mitigation — and every unit test
+passed while it was true.
+
+**The fix is a latch on TIME rather than on call count.** A confirmed repair is reported for
+`storeGrantRepairReportWindow` (20 minutes), which comfortably exceeds the 900 s host-report interval,
+so at least one report must carry the transition. It clears on its own — a permanently degraded
+capability would be its own false alarm — and it is per tier.
+
+**Two hollow tests were caught and fixed on the way**, both the same shape this repo keeps finding: a
+test asserting a value it constructed itself, and a test asserting the latch HELPER rather than the
+path that consumes it — whose red-proof duly passed. The decisions now live in
+`storeGrantHealthyVerdict` and `storeGrantRepairedVerdict`, and the tests call those.
+
+## v0.124.0 — a lost storage grant repairs itself, and says that it was lost (2026-08-04, R-190)
+
+**R-190 is a grant that demonstrably worked at 04:44 on 2026-08-03 and was gone by 09:24** — with a
+host reinstall, logged `pveum` activity and cluster-log entries all ruled out by measurement. The
+cause is still open. The resilience does not have to wait for it.
+
+**Everything needed already existed and had only ever been called once.** The root wrapper
+(`felhom-backup-target-apply grant <id>`), its sudoers vector (`grant *`, any storage id, confirmed
+not assumed), and the exact command were all in place — and the `grant` verb had only ever run at
+storage CREATION. That is the *built but never wired* shape, in a verb rather than a seam, and it is
+this project's seventh instance.
+
+**What v0.124.0 does:** when the store-grant probe finds the grant absent on a tier the box depends
+on, it runs that wrapper and **re-reads once** to confirm — the pbsdr R-22 self-grant shape, including
+its restraint: one attempt, one confirmation, and anything still wrong stays loudly wrong.
+
+**THE RECORD IS THE POINT, AND IT IS THE HALF R-190 IS ACTUALLY ABOUT.** A repair that leaves only
+`ok` behind destroys the only evidence a permission vanished, so a recurring loss becomes undetectable
+forever — strictly worse than the fault it fixes. So a confirmed repair reports **DEGRADED for exactly
+one cycle**, with the explanation in `Feature`:
+
+```
+backup tier felhom-backup: the agent's storage grant was MISSING and has been AUTOMATICALLY
+RESTORED — the tier works now, but a permission that vanished on its own needs investigating (R-190)
+```
+
+**Nothing new was built to carry it.** The hub's existing ok→degraded→ok edge is the channel — it
+alerts and e-mails on the first edge and logs the recovery on the next cycle, so one loss produces
+exactly one alert pair. No wire change, no hub change, no new event type. `Feature` carries the text
+because that is the field the hub interpolates into the operator's e-mail; `Reason` does not travel.
+
+**Bounded (Scenario F):** one attempt per tier per hour, in memory. A storage can be unreadable for
+reasons an ACL cannot fix, and a re-grant on every report cycle is a repair loop wearing a fix's
+clothes. An agent restart re-arms it, which is correct — a restart is exactly when a box should
+re-check what it depends on.
+
+**A failed repair never masks the fault:** the capability stays degraded with the failure in its
+reason, and a repair that "succeeded" but did not survive the re-read is reported as needing a human.
+
+## v0.123.0 — a tier the box cannot READ now says so (2026-08-03, R-185)
+
+**The missing permission is one command. The silence was the defect.** On demo-felhom the agent's PVE
+token held `FelhomAgentStore` on `local`, `local-lvm` and `felhom-pbs` — and **not** on
+`felhom-backup`, the storage the same installer had configured as `local_backup_target`. Asked for
+that storage's content the API answers `{"data":[]}` while root sees three archives (6.1–6.3 GB,
+08-01/02/03).
+
+**An empty listing is what a FORBIDDEN tier and a NEWBORN tier both return.** `pickForThisRun` skips
+an empty tier — correctly, because a fresh offsite tier legitimately has nothing yet — and reports
+*"no settled archive yet"*. So that tier was never restore-testable on that box and nothing ever
+mentioned it. This project's own rule, in a new place: an empty answer is not evidence that there is
+nothing there.
+
+**The permission question, unlike the listing, has a definite answer — so it is asked directly.**
+`Client.Permissions` reads `GET /access/permissions?path=/storage/<target>` **as the agent's own
+token** (asking as root answers a different question and always says yes), and one
+`capability.Status` per configured tier reports the result. It composes *around* the sudo prober, the
+way the pool-read check already does — an API read does not belong inside a sudo-policy probe.
+
+**MEASURED FIRST, and the obvious reading is wrong.** The ungranted path does not answer empty and
+does not 403:
+
+```
+/storage/felhom-pbs     → {"Datastore.Allocate":1,"Datastore.AllocateSpace":1}
+/storage/felhom-backup  → {"Sys.Audit":1,"SDN.Use":1,"Datastore.Audit":1}
+```
+
+It answers with the privileges **inherited** from the box-wide `/` grant. A probe asking *"is the
+path present?"* or *"does it have `Datastore.Audit`?"* would report the blinded storage healthy — so
+the probe tests for `Datastore.AllocateSpace` specifically, and a red-proof pins that.
+
+**Decisions, each weighed once:**
+
+- **The probed set comes from the box's own config** (`BackupTiers()`), not a fixed list. A hardcoded
+  probe list is exactly the defect being fixed, reproduced inside the fix.
+- **CRITICAL**, because the hub alerts only on critical and a non-critical entry would ride the
+  report and alert nobody — the same silence with extra steps. **Except** the `local` fallback
+  target, which host-install's own comment calls the DEGRADED configuration: it is still probed and
+  still reported, but it does not page, because turning an ordinary documented setup into an alert
+  is how a signal becomes something an operator archives unread.
+- **It never looks at content**, so it cannot alarm on a newborn tier by construction.
+- **It never reports ok when it could not ask.** An unreachable PVE is degraded: a self-check that
+  fails open converts *"I do not know"* into *"fine"*.
+
+The wire shape (`capability.Status`) is unchanged, so the hub's existing critical-degraded alert
+applies with no hub change and no hub bump.
+
+## v0.122.0 — three ways the signals lied about themselves (2026-08-03, R-189 · R-188 · R-186)
+
+All three are the reporting and release path misreporting its own work. **No customer machine, no
+backup, no restore, no disk layout, no data.** The restore-test itself and when it runs are unchanged
+from v0.121.1.
+
+### R-189 — a passing restore-test no longer vanishes on a restart
+
+`restore_tests[]` came only from the in-memory `backup.Store`, whose own comment read *"lost on
+restart; the cadence re-populates"*. That was true under a timer. It stopped being true when R-86 made
+the agent refuse to re-test an archive it has already proven: a proof lost to a restart is not
+repeated for a whole archive generation — **a week on the offsite tier** — and the hub calls the tier
+unproven for all of it.
+
+**Observed, not predicted (2026-08-03):** a real 14.5 GB offsite restore-test PASSED at 15:25:14, the
+agent was restarted 2 m 43 s later for a deploy, and the hub logged `0 restore-tests` on the next two
+host-reports.
+
+The durable proof already existed — `RestoreTestState`, on disk, per tier, with the archive since
+R-86 — and `Snapshot()` had carried the doc comment *"for the host-report gauge"* since the day it was
+written **with no caller at all**: a seam built, documented, and never connected. It now carries the
+`tier` and what was `verified` as well (stored at proof time, when they are known for certain, rather
+than derived later by a storage lookup that can fail), and `ProvenRestoreTests` renders them as report
+entries which the collector merges.
+
+- **Merge rule: one entry per tier, newest by `TestedAt` wins.** A fresh failure beats a stored
+  success — the failure is the news and lives nowhere else; a stored success beats a stale in-memory
+  entry after a restart; a tier never appears twice, which the hub would read as two tests. An
+  unparseable timestamp counts as older, so a malformed entry cannot displace a good one.
+- **It refuses to lie.** A record missing the archive or the tier produces NO entry, and run mechanics
+  (scratch VMID, duration) are not re-invented — an absent duration is not a claim, a fabricated one
+  would be. An unproven tier reading as proven would be worse than the defect being fixed.
+- **Only successes are persisted, and that asymmetry is now written down where it will be read:** a
+  success suppresses future work, so losing it leaves the system quietly less tested than it believes;
+  a failure causes future work and heals itself at the next evaluation.
+- The `Store` comment that stopped being true is corrected in place rather than left to mislead.
+
+### R-188 — a correct release no longer emails a failure
+
+`on: [push]` fires the gates workflow on the **tag** push, and the release pushed its tag *before*
+publishing, so CI ran the published-versions gate in the seconds before the package existed and
+correctly reported it missing. Measured across two releases in one session: runs 12/13 and 17/18, same
+sha each time, opposite results — a race, not a rule. R-168 made that mail the thing that cannot be
+missed; one that is wrong half the time is one you stop reading.
+
+**Only the tag PUSH moved** (build → tag locally → publish → push tag). The tag is still created before
+anything is published, so the build and the tag still describe the same commit; it simply becomes
+*visible* — to CI, and to any `raw/tag/…` fetch — once the package is downloadable.
+
+The invariant the old order protected is **not traded away**: `check-published-versions.py` now asserts
+the converse directly — **no published version may be missing its tag** — as a bounded probe of the
+frontier (where a failed tag push leaves an orphan) and of patch gaps, printing its probe set every
+run because a check whose coverage is invisible reads as a guarantee it is not making. The package
+listing api still answers **401** without a token (re-measured), so absence cannot be enumerated, and
+the script says so.
+
+A publish that succeeds and a tag push that then fails now **dies loudly**, printing the one-line
+recovery; and a publish that *fails* removes the local-only tag so the release can simply be retried
+instead of colliding with itself.
+
+### R-186 — a released binary can now be verified by rebuilding it
+
+`go build` stamps a module version derived from VCS state, so a build made before the tag existed and
+a rebuild made after it were different binaries. Measured at one commit, same source, same toolchain:
+
+```
+default flags, no tag yet ... 18f4a495…  14 085 464 B   (mod v0.121.2-0.2026…-3d0a1d61)
+default flags, tagged ....... 4a38f394…  14 085 440 B   (mod v0.121.99)
+-trimpath -buildvcs=false ... 7ffcdf1d…  14 064 574 B   IDENTICAL both ways
+```
+
+The stamp is removed rather than sequenced around — nothing in this repo reads it (no `ReadBuildInfo`
+caller) and the version comes from the explicit `-X main.version` ldflag. `-trimpath` additionally
+makes a rebuild from a different checkout directory match.
+
+**A second discrepancy fell out of it:** `publish-agent.sh`'s fallback build forced `CGO_ENABLED=0` and
+therefore produced a binary **74 KB smaller** than the release path built for the same version — one
+version name, two binaries, decided by which entry point was used. Both now build identically.
+
+`CLAUDE.md` records the exact command an operator can run to verify a published binary independently.
+
+## v0.121.1 — "nothing is due" must be AUDIBLE (2026-08-03, R-86 + standing rule 3)
+
+**Found while live-validating v0.121.0, and it is this project's own rule pointed at the change that
+had just shipped.** Before R-86 every tick ran a heavy restore-test, so the scheduler was audible by
+construction. After it, *"nothing is due"* is the NORMAL outcome — and it was logged at **DEBUG**,
+which journald drops. An empty journal would then have been equally consistent with a healthy loop
+and with a dead goroutine: the exact shape the R-88 watcher was retired for, re-created in a new
+place by making the quiet path the common one.
+
+A not-due evaluation now logs one **INFO** line naming every tier's verdict:
+
+```
+backup: restore-test evaluated — nothing due
+  verdicts="felhom-pbs: newest settled archive (landed 2026-07-28T04:49:43Z) is already proven;
+            felhom-backup: no settled archive yet — nothing to prove (newborn or still settling)"
+```
+
+Four lines a day at the 6 h default, and the answer to *"why did nothing run last night?"* is in the
+log instead of being re-derived. A tier whose storage cannot be listed reads `UNKNOWN` with its error
+in the same line, so a lookup failure can never present as "nothing due".
+
+Red-proved by reverting to the bare `Debug` line: the test asserts what the SCHEDULER emits on a real
+`tick`, not what the helper returns — a helper-level test would have passed against a tick that never
+called it.
+
 ## v0.121.0 — a restore-test proves each BACKUP, not the clock (2026-08-03, R-86)
 
 **The trigger changed; the restore-test did not.** `Scheduler.Run` still has a ticker, but it is now
@@ -4883,3 +5765,5 @@ client, signing, or storage/backup orchestration yet (later slices).
   read-only `--selftest` against the demo host with TLS fingerprint pinning.
 - The 16-privilege `FelhomAgent` role + privsep token (role on **both** user and
   token) is provisioned out-of-band; the agent only consumes the token.
+
+<!-- R-421 sweep: this repo cites R-421; the row landed in felhom.eu 2d88776. -->

CLAUDE.md

@@ -1,189 +1,111 @@
 # CLAUDE.md — `felhom-agent`
 
-> Loads when Claude Code touches this repo. Stable orientation only — **current state lives in
-> `CONTEXT.md` and the top of `CHANGELOG.md`**, never here. Cross-repo orientation: workspace-root
-> `/mnt/5_hdd/felhom.eu/git/CLAUDE.md`.
+> Stable orientation only — **current state lives in `CONTEXT.md` and the top of `CHANGELOG.md`**,
+> never here. Cross-repo conventions (artifact taxonomy, access, clean-tree gate, secrets,
+> CHANGELOG/REPORT): workspace-root `/mnt/5_hdd/felhom.eu/git/CLAUDE.md`. Path-scoped detail:
+> `.claude/rules/`.
 
 ## What this repo is
 
-`felhom-agent` is the operator-tier **host agent** that runs on each Proxmox host and owns **all**
-Proxmox interaction: provision/restore guests, host storage, backup/restore orchestration, the hub
-control loop, and a narrow per-guest local API. It is the **most privilege-sensitive** component.
+The operator-tier **host agent**, one per Proxmox host, owning **all** Proxmox interaction:
+provision/restore guests, host storage, backup/restore orchestration, the hub control loop, and a
+narrow per-guest local API. It is the **most privilege-sensitive component in the system**.
 
-- Renamed former `proxmox-controller` repo.
-- **Distinct from `felhom-controller`** — that is the *in-guest* controller (Docker-only, no Proxmox
-  creds). Do not confuse them.
-- Control plane, not data plane: if the agent dies, apps keep serving; only management degrades.
+- Renamed from `proxmox-controller`.
+- **Distinct from `felhom-controller`** — that is the *in-guest* controller, Docker-only, holding no
+  Proxmox credentials. Do not confuse them.
+- **Control plane, not data plane:** if the agent dies, apps keep serving; only management degrades.
+- Pure Go stdlib + `golang.org/x/crypto`. No web frameworks.
 
-## Read before writing code
+## Doing X → read Y
 
-- **`REUSE.md`** — canonical helpers, format-safety guards, traps, seams. Check it first; update it
-  in the same commit that changes a shared helper or pattern.
-- `CONTEXT.md` (current state + open threads) and the top `CHANGELOG.md` entry (authoritative history).
-- Design doc: `felhom.eu/documentation/architecture/03-host-agent.md` (locked). Platform facts:
-  `felhom.eu/documentation/proxmox-platform.md` + `tests/phase{0,1-2,3,4}-findings.md`.
+| Doing | Read |
+|---|---|
+| writing any new code | `REUSE.md` — helpers, format-safety guards, traps, seams |
+| needing current state / open threads | `CONTEXT.md` + the top `CHANGELOG.md` entry |
+| Proxmox, reconcile or signed jobs | loads itself: `.claude/rules/proxmox.md` |
+| local API, authz or guest hooks | loads itself: `.claude/rules/localapi.md` |
+| backup, PBS or DR | loads itself: `.claude/rules/backup.md` |
+| storage or escrow | loads itself: `.claude/rules/storage.md` |
+| writing a health check | loads itself: `.claude/rules/health-checks.md` |
+| **release, build, publish, deploy, verify a version** | the **`felhom-build-deploy`** skill — **never hand-roll it** |
+| writing or reviewing a test, fixing a bug | the **`felhom-testing`** skill |
+| host addresses, break-glass, node facts | `felhom.eu/documentation/operations/nodes.md` — never restate them |
+| which box may I break | `felhom.eu/documentation/runbooks/target-selection.md` |
+| what version is live anywhere | ask the hub (`/hosts`, `/configs`) or the box — **never a doc** |
+| the authoritative design | `felhom.eu/documentation/architecture/03-host-agent.md` (locked) |
 
-## Layout (verified against the tree)
+## The root-CLI fence — API-first, exactly three exceptions
 
-```
-cmd/felhom-agent/    main + flags + --selftest modes + the daemon entry
-cmd/felhom-opsign/   offline operator signing CLI (SSHSIG)
-internal/authz/      operator signed-op verifier (SSHSIG) + durable FileNonceStore
-internal/backup/     vzdump backup runner + restore-test scheduler + report store
-internal/capability/ live sudo-policy capability probe (degradation visibility)
-internal/config/     JSON config + FELHOM_AGENT_* env overlay; secrets redacted (Redacted())
-internal/desired/    hub desired-state syncer (envelope observer)
-internal/escrow/     PBS-key escrow (zero-knowledge recovery code)
-internal/guesthook/  pre-start self-heal hookscript install
-internal/hub/        daemon: HostReport collector + Bearer client + resilient Loop
-internal/lanresolver/ split-horizon DNS on guest IP change (dnsmasq RESTART, not reload)
-internal/localapi/   per-guest local API: token store, disks/format, guest binds, controller swap,
-                     stale-lock recovery, pinned self-signed leaf
-internal/log/        slog setup
-internal/pbs/        PBS-API client (fingerprint-pinned) + verify maintenance loop
-internal/provision/  guest bootstrap back-half (token mint → bootstrap.json → pct bind)
-internal/proxmox/    API-first Client + fenced root-CLI Privileged + UPID WaitTask
-internal/reconcile/  reconcile engine + reversibility gate + op journal + crash recovery
-internal/signedjobs/ operator-signed destructive executors (wipe, decommission)
-internal/storage/    storage observer + durable ids + role/claim classifiers + SudoHostOps + watchdog
-```
-
-## Build / run
-
-- Module `gitea.dooplex.hu/admin/felhom-agent`; binary `felhom-agent` (`cmd/felhom-agent/`).
-- **Pure Go stdlib + `golang.org/x/crypto` only** — no web frameworks. `go.mod` directive go 1.25.0;
-  DooPlex (192.168.0.180, where CC runs) has the Go toolchain and is on the same LAN as the demo
-  host — build and run live tests locally.
-- Version via `-ldflags "-X main.version=<v>"`; `--version` flag. Bump on meaningful changes + CHANGELOG entry.
-- **Full build/deploy/publish runbook: use the `felhom-build-deploy` skill.** Summary:
-
-> **Clean-tree gate before any build:** `git status --porcelain` must be empty and
-> `git rev-parse HEAD` must equal `git rev-parse origin/main` in the repo being built. An unpushed
-> change does not exist — never build a dirty or unpushed tree. The `git pull` in the build step
-> stays (it is a no-op when you work in this tree, and load-bearing if anything was pushed from
-> elsewhere).
-
-> **RELEASING IS ONE COMMAND, AND IT PUBLISHES (R-115).** There used to be a raw `go build` line
-> here and a *separate* "Publish" row, so publishing was a step someone had to remember — and it was
-> **forgotten three times in five days**, the last leaving agent v0.120.0 deployed on both demo hosts
-> and undownloadable, where a documented-path reinstall would have silently downgraded them while
-> reporting success. Do not hand-roll the build: the script also creates the `v<version>` git TAG
-> that `felhom-host-install.sh` fetches this version's sixteen config files from (R-183), and it
-> verifies by an **independent download** rather than trusting the publish step's own output.
-> `scripts/publish-agent.sh` still exists and is still correct — the release script CALLS it rather
-> than reimplementing it.
-
-| Step | Where | One-liner |
-|---|---|---|
-| **Release** (build + tag + publish + verify) | DooPlex (local) | `GITEA_USER=admin GITEA_TOKEN=<tok> scripts/release-agent.sh <ver>` — refuses a dirty/unpushed tree and refuses to re-release an existing version |
-| Copy | local → felhom-pve | `scp /tmp/felhom-agent-<v> felhom-pve:/tmp/` (one hop) |
-| Deploy | felhom-pve | backup `.bak-<old>` → `install -m0755` → `systemctl restart felhom-agent` (non-root `felhom-agent` user, config `/etc/felhom-agent/agent.json`) |
-| Ship configs | felhom-pve | sudoers (`/etc/sudoers.d/felhom-agent`) + guarded-mkfs wrapper WITH the binary when `configs/` changed |
-| **Vouch** | hub operator UI | Configs → Day-0 artifacts. **Deliberately NOT automated** — vouching is what points machines at a version, and it stays your act (prove-then-vouch) |
-| Verify | felhom-pve | `felhom-agent --version` + journal (clean ReassertGuestBinds, no capability degradation) |
-
-## Proxmox model (the load-bearing rules)
+This is in the core because breaching it is how this component stops being auditable.
 
 - **API-first** via a scoped `FelhomAgent` token. Raw root-CLI is **fenced to exactly 3 exceptions**:
-  keyctl `pct create` (golden image), USB mount/fstab, SMART/sensors. `Client` never shells out;
-  `Privileged` never makes HTTP calls (asserted by `routing_test.go`). Keep that fence.
-- **Every mutating op is async** → returns a UPID → `WaitTask` asserts `exitstatus == "OK"`. A 200 on
-  the POST is **not** success; authorization can fail at task execution.
-- **TLS:** SHA-256 leaf-cert pinning (self-signed host cert). No insecure default.
-- **Privsep token gotcha:** a `--privsep 1` token's rights = intersection of the backing user's perms
-  AND the token's ACLs — the role must be granted on **both**, or every call 403s.
-- Destructive ops go through the reconcile gate / signed-jobs path — never call `Client.DestroyLXC`/
-  `Vzdump`/`SetConfig` ad-hoc (REUSE.md §3).
+  keyctl `pct create` (golden image), USB mount/fstab, SMART/sensors.
+- **`Client` never shells out; `Privileged` never makes HTTP calls** — asserted by `routing_test.go`.
+  Adding a method to `proxmox.Privileged` breaks the fence; use `proxmox.Runner` plus a new sudoers
+  `Cmnd_Alias` and `validate.go`-style checks (`REUSE.md` §3).
+- **Destructive ops go through the reconcile gate / signed-jobs path.** Never call
+  `Client.DestroyLXC` / `Vzdump` / `SetConfig` ad-hoc — that skips classification, signature,
+  per-guest serialization and crash recovery.
+- **Ownership must be PROVEN, never assumed.** A raw `ListLXC` list is not "guests the agent owns";
+  intersect with `Client.Pool` membership and fail safe on a read failure (audit A1).
 
-## Demo host (for live tests)
+## Gates — ONE entry point
 
-Node **`demo-felhom`**, API `https://192.168.0.162:8006`. SSH alias `felhom-pve` (root@pam) —
-available to CC as plain `ssh felhom-pve`. A **second demo node `demo-hp`** (HP t740, node name
-`felhom-host`, `ssh demo-hp` — no baked key; break-glass root via hub `host_recovery/demo-hp-bb76ea` +
-`sshpass`) is the **designated drill+build VM host** per the 2026-07-25 operator ruling, and that ruling
-is **realized** — it hosts drill VM `300` (`drill-r50`), so **start there**, not on DooPlex. (The
-historical golden-bake `drill.qcow2` still lives on DooPlex and is a bake fixture, not a drill target.)
-**Which box is safe to break, and what may be done to each:
-`felhom.eu/documentation/runbooks/target-selection.md`** — read it before any destructive test. Both
-nodes + the break-glass recipe: `felhom.eu/documentation/operations/nodes.md`. The agent pins the served leaf cert — verify the
-fingerprint still matches before a live run. Selftest modes (run locally on DooPlex, pointed at the
-demo API): `--selftest[=read|task|hub|storage|backup|restore-test|pbs-verify]`; no flag = the daemon.
+**Run `python3 scripts/agent_gates.py` from the repo root after ANY change here.** It runs this
+repo's gates — `reuse_refs_check` and `instructions_gate`, both the **shared** copies in
+`felhom.eu/scripts/`, never copied into this repo (a copy recreates the drift they detect; an absent
+sibling clone FAILS). `--fast` selects the gates touching no network and no container runtime; today
+that is all of them. **A missing gate is a FAILURE, never a skip.**
 
-> **TEMPORARY — felhom-pve is at a remote site (until ~2026-08-02).** The home-LAN literal
-> `192.168.0.162` is NOT reachable from DooPlex for the duration. Access via Tailscale:
-> felhom-pve = 100.70.170.35; the `Host felhom-pve` entry in `~/.ssh/config` on DooPlex already
-> points there (the direct-LAN path stays available as `Host felhom-pve-lan`). Delete this block on
-> return. All documented `ssh felhom-pve` / `pct exec` workflows are unchanged. Path is **direct**
-> (not DERP), ~37 ms rtt per hop. At the remote site the host is on **DHCP**; re-check its address
-> rather than trusting one written here (`ip -br addr show vmbr0` — it read `192.168.0.162/24` on
-> 2026-07-30, and `felhom-pve-lan` from DooPlex is still `No route to host`). Details + findings:
-> `felhom.eu/documentation/audits/AUDIT-vacation-remote-ops-2026-07-20.md`
->
-> **The "agent does not run at the remote site" warning this block used to carry is RETRACTED
-> (2026-07-30) — it was true before R-50 and is false now.** `localapi` no longer binds a LAN literal:
-> since the R-50 island migration (2026-07-25) it binds `169.254.253.1:8443` on `vmbr9`, which is
-> location-independent by design, and `proxmox.endpoint` is `https://127.0.0.1:8006`. Verified live:
-> `systemctl is-active felhom-agent` → `active`, `felhom-agent --version` → 0.115.0, and the per-guest
-> local API answered `GET /disks` over the island. No config edit and no Viktor GO are outstanding.
+**The pre-push hook** (`.githooks/pre-push`) runs it with `--fast` and refuses a failing push. It is
+**per-clone** — switch it on once with `git config core.hooksPath .githooks`, and a manual run WARNS
+when this clone is unarmed. `git push --no-verify` bypasses it deliberately; **say so in the session
+report when you use it** — CI re-runs the same entry point on every push and **emails the operator on
+failure**, so a bypass is noticed even though it is not blocked (R-168, CLOSED 2026-08-02).
 
-> **Legacy: Windows workstation.** Until 2026-07-19 CC ran on Windows 11; `pct` commands over SSH
-> needed `export MSYS_NO_PATHCONV=1`, and every remote command used
-> `SSH=/c/Windows/System32/OpenSSH/ssh.exe`. Agent deploy was a two-hop copy via the Windows box
-> (`cygpath -w` for the local scp path; CRLF hazard on config files).
+<!--
+WHY ONE ENTRY POINT (2026-08-02, R-29): a census of all gates across the four repos found every check
+a CLAUDE.md names was passing, and two of the four nobody is told to run were failing. This repo was
+the extreme case — nothing ran against it at all, and 90 cited paths were checked by no one.
+-->
+
+## Live validation — the fence
+
+Exercise the **SERVER-SIDE PIPELINE** a real user triggers, end-to-end. **The forbidden shortcut is
+BYPASSING it** — the F9 episode was a raw guest-attach with hand-set state, and it proved nothing.
+
+`claude-in-chrome` is NOT available on DooPlex. Invoking the exact endpoint the UI invokes is an
+acceptable proxy — **say which method was used**. Low-level mechanism tests where the direct call IS
+the mechanism are exempt.
 
 ## Conventions
 
-### Trunk-based — no branches
-
-All shippable work commits **directly to `main`**; `main` equals what is deployed.
-- Report-only artifacts (audits, findings, fixspecs) → `felhom.eu/documentation/` (`audits/`, `backlog/`).
-- Risky/supervised fixes are spec'd, then implemented **during the supervised session, on `main`**.
-- Unattended escape hatch: if a fix can't be cleanly verified/shipped, revert + report — never park on a branch.
-
-> **In every repository where you make a change, update both files in that repo:**
-> - **`CHANGELOG.md`** — cumulative log, newest on top.
-> - **`REPORT.md`** — **overwrite** with the most recent implementation/validation summary only.
->
-> **Never write secrets** into any committed file — reference them as "stored out-of-band".
-
-- Code quality: verify generated code for bugs/edge cases; add debug logging; **ask rather than
-  guess** when you'd otherwise invent input/output.
-- **A health check issues no block I/O** — no `statfs`, no `getdents`, no read, write or `fsync`, **not
-  even behind a timeout**. Liveness is decided from `/proc` and kernel state. The full rule + the
-  measurement lives in `felhom.eu/CLAUDE.md` "Code quality rules"; it is repeated here because health
-  checks are written in THIS repo and that file does not load in an agent-only session. R-117 spike §6.3.
-- Update `REUSE.md` if you added/changed/deprecated a shared helper or pattern (same commit).
-- **Run `python3 scripts/agent_gates.py` from the repo root after ANY change in this repo.** It is
-  the ONE entry point for this repo's gates. Today it runs one — `reuse_refs_check` over this
-  repo's `REUSE.md` — and it exists at one gate on purpose: a census on 2026-08-02 found that every
-  check a `CLAUDE.md` names was passing and two of the four nobody is told to run were failing, and
-  this repo was the extreme case, with nothing running against it at all and 90 cited paths checked
-  by no one. It grows when the agent grows a second check. `--fast` selects the gates that touch no
-  network and no container runtime; today that is all of them. A missing gate is a FAILURE, never a
-  skip. **The shared `reuse_refs_check.py` lives in `felhom.eu/scripts/` and is never copied here**
-  — a copy would recreate the drift it detects; an absent sibling clone FAILS the gate.
-  **The pre-push hook** (`.githooks/pre-push`) runs it with `--fast` and refuses a failing push. It
-  is per-clone — switch it on once with `git config core.hooksPath .githooks`, and a manual run
-  WARNS when this clone is unarmed. `git push --no-verify` bypasses it deliberately; **say so in the
-  session report when you use it.** Both facts are why CI is still owed (`OPEN-ITEMS.md` R-168).
-- Testing doctrine (non-hollow tests, red-proofs, seams): use the `felhom-testing` skill.
-- **Logging**: the slog logger fans out to journald (configured level) + the always-DEBUG `applog.Ring`
-  (remote pulls) — English, keys-never-values, durations on outcomes; full rules in
+- **Trunk-based — no branches.** All shippable work commits directly to `main`; `main` equals what is
+  deployed. Report-only artifacts (audits, findings, fixspecs) go to `felhom.eu/documentation/`.
+- **Unattended escape hatch:** if a fix cannot be cleanly verified and shipped, **revert and report**
+  — never park it on a branch.
+- **Logging**: the slog logger fans out to journald (configured level) plus the always-DEBUG
+  `applog.Ring` (remote pulls). English, keys-never-values, durations on outcomes. Full rules:
   `felhom.eu/documentation/runbooks/logging-conventions.md`.
+- Update `REUSE.md` in the same commit that adds, changes or deprecates a shared helper or pattern.
 
-### Live validation
+## End-of-session checklist
 
-Exercise the SERVER-SIDE PIPELINE a real user triggers, end-to-end. The forbidden shortcut is
-BYPASSING it (the F9 episode: raw guest-attach + hand-set state). Invoking the exact endpoint the UI
-invokes is an acceptable proxy when a browser isn't available — say which method was used. Low-level
-mechanism tests where the direct call IS the mechanism are exempt.
+- **`CHANGELOG.md`** (cumulative, newest on top) and **`REPORT.md`** (overwritten with this run only)
+  — in every repo touched.
+- **`CONTEXT.md`** — decisions, state, what is next.
+- **`REUSE.md`** — if a shared helper or pattern moved.
+- **A finding goes in `felhom.eu/documentation/backlog/OPEN-ITEMS.md` first**, never only in a report
+  or an audit.
+- **Confirm your own last push's CI run went green, by run ID** — CI mails on failure, which is a PUSH
+  signal; this is the PULL check that catches a lost or unread mail. An unchecked green is an
+  assumption, not an observation.
 
-## Workflow & artifacts
-
-- Implement **`TASK.md` / `TASK-*.md`** specs (when placed as `TASK.md` or told to), then push +
-  CHANGELOG + REPORT.md.
-- **`RUNBOOK-*.md`** — an operational procedure. CC executes the steps it has access and capability
-  for, including live validation on the demo Proxmox host (CC has root@felhom-pve SSH + the
-  felhom-agent token). Mark a step HUMAN only when it genuinely needs physical presence, a real-world
-  decision, or credentials CC truly lacks. Judgment still applies: confirm before irreversible ops on
-  real customer data — demo scratch guests are fair game.
+**A gate ships with a decoy test that has been seen to fail (R-421).** A decoy is the LABEL without
+the FACT — a directory with the right name and no bake log, a note whose prose mentions the marker it
+lacks. `scripts/decoy_coverage_gate.py` refuses a new gate that has neither a decoy nor a named
+exemption carrying its row. The four shapes, the 2026-09-01 sweep that fooled 16 of 29 gates, and the
+decoys withdrawn as illegitimate: `documentation/audits/AUDIT-gate-decoys-2026-09-01.md` and
+`felhom-controller/.claude/rules/gates.md`. **Scope is a fact too** — prefer `os.walk` over
+`os.listdir`, and a glob over a hand-maintained list.

CONTEXT.md

@@ -1,10 +1,114 @@
 # CONTEXT — felhom-agent working state
 
+
+> **2026-09-25 night — v0.133.0 AND v0.134.0 DELIVERED to both demo boxes (CC-signed `agent_update`, ruling 1);
+> restore test back ON (the `-1` config kept as `agent.json.night-0925-off`). v0.134.0 = R-685:** `backup/runner.go`
+> `spaceFits` — a vzdump to a LOCAL target needs free ≥ newest archive of that guest × 1.25 + 1 GiB (PVE prunes
+> only after success); a shortfall is a named skip (`BackupSkipNoSpacePrefix`), fail-open on PBS / first backup /
+> unknown usage. **Free space comes from `NodeStorage` (`GET /nodes/<n>/storage`) — `ListStorage` (`GET /storage`)
+> has NO usage**; the first build read it and a real vzdump started in its own live test (aborted, no archive).
+> demo-hp: `local_backup_retention` 1 (operator option A, saved `agent.json.pre-a4-retention`). Peti's box: nothing.
+
+> **2026-09-24 — v0.133.0 RELEASED, NOT DELIVERED (R-672, R-673).** Restore-test space preflight
+> (`reconcile/restoretest_space.go`, `internal/restorespace`): uncompressed size from the vzdump log / PBS size,
+> × 1.2 + 5 GiB, thin metadata, off the tested guest's pool, unknown refuses, reported as `skipped` non-pass.
+> Janitor (`cmd/felhom-agent/janitor.go`) every 10 min: `Engine.RetryScratchTeardown` + stale-lock sweep under
+> the heavy-op gate. Thin pool ≥ 90 % → immediate report (hub v0.124.0 alarms). **Operator rulings 2026-09-24
+> (evening):** the scheduled restore-test is OFF on both demo hosts (`backup.restore_test_eval_interval_seconds:
+> -1` — note: 0 means the 6 h DEFAULT, only a negative disables) until v0.133.0 is delivered there; saved configs
+> `/etc/felhom-agent/agent.json.pre-r672`. demo-hp 9201 was repaired (stop, fsck, start; two Redis AOF tails cut).
 > Snapshot of the current state + open threads. Authoritative history lives in `CHANGELOG.md` (top
 > entry = current); the end-of-task detail lives in `REPORT.md`.
 
+## R-199 (v0.125.0) — links 6–8 of the recovery chain, assembled and walked
+
+`POST /escrow/recover-offsite-password` (pinned local API, `withGuest`): the controller supplies the
+customer's recovery code, the agent fetches THIS host's own sealed blob from the hub
+(`hub.Client.FetchIdentityEscrow` → `GET /hosts/{id}/escrow`, hub >= v0.94.0, self-scoped by the
+per-host key), unseals it via `escrow.OffsiteKeyRecoverer`, and returns **only** the offsite restic
+repository password plus its sha256.
+
+**Rules that must not erode:**
+- **Only that field.** Not the tunnel token, not the PBS token, not the WG key — the controller is a
+  trust tier down and needs none of them. Narrowing cost nothing and is not recoverable later.
+- **The unseal stays in the agent.** `age` is an agent runtime dependency (`/usr/bin/age` — hardcoded,
+  no config override; 1.2.1 on demo-felhom) and is deliberately absent from the controller image.
+- **R:** in memory for one call, cleared on the success path AND every failure path, never on disk,
+  never in argv, never logged at any level including inside an error, never echoed. Verified live: 0
+  log lines, 0 files, 0 leftover `felhom-idesc-*` dirs, with a positive control proving the search worked.
+- **Three distinct outcomes**, not one generic failure: no blob (404), a bundle that opens but predates
+  the field (409 — pre-fork-4, cannot be retro-fitted), a code that does not open it (400 — fail-closed
+  at age's KDF, nothing written).
+- **The wiring is pinned by an AST walk** (`cmd/felhom-agent/escrow_recover_wiring_test.go`):
+  `main` → `runDaemon` → `buildLocalAPIServer`, an `escrow.OffsiteKeyRecoverer` constructed there, the
+  `Options.EscrowRecovery` field present, and the fetcher calling the DAEMON's own `hubClient` (the
+  self-scoping that makes cross-host retrieval impossible is a property of WHICH key is used).
+  Links 6 and 7 were two of this project's six built-but-never-wired instances.
+
+**Proven live on demo-felhom 2026-08-04:** recovered sha256 == on-disk sha256 == the hub's stored hash.
+A wrong code five minutes earlier failed closed. **The chain stops at link 8** — nothing installs a
+recovered password, reopens a repository, or restores a file.
+
+**§8.6, fixed while here:** `runSelftestIdentityConsume`'s success line used to recite
+"tunnel_token + pbs_token", which became a misstatement when v0.77.0 sealed the repository password
+into the same bundle — anyone reading it would conclude the password was not there. It now names what
+THIS bundle carried and what it did not.
+
 ## Current
 
+- **2026-08-03 — v0.123.0 (R-185): a tier the box cannot READ now says so.** The agent's token had
+  `FelhomAgentStore` on `local`, `local-lvm`, `felhom-pbs` and **not** on `felhom-backup` — the
+  storage both demo boxes configure as `local_backup_target`. That storage answered `{"data":[]}`
+  through the token while root listed three archives, and `pickForThisRun` skipped it as *"no settled
+  archive yet"* — **which is what a brand-new tier reports**, so the host tier was never
+  restore-testable and nothing said so.
+  - **The permission question is asked directly**, because unlike the listing it has a definite
+    answer: `Client.Permissions` reads `/access/permissions?path=/storage/<target>` **as the agent's
+    own token**, and `storeGrantStatuses` emits one `capability.Status` per configured tier. It
+    composes AROUND the sudo prober, the way `poolReadStatus` already does — an API read does not
+    belong inside a sudo-policy probe. `Status`'s wire shape is untouched, so the hub's critical
+    degraded alert applies with **no hub change**.
+  - **MEASURED FIRST, and the obvious reading is wrong:** an ungranted path answers neither empty nor
+    403 — it carries the privileges INHERITED from the box-wide `/` grant
+    (`Sys.Audit, SDN.Use, Datastore.Audit`). Checking path-presence, or `Datastore.Audit`, reports a
+    blinded storage HEALTHY. The probe tests **`Datastore.AllocateSpace`**; re-measure before ever
+    changing that constant (`storeGrantRequiredPriv`, red-proved).
+  - **The probed set comes from `BackupTiers()`, never a fixed list** — a hardcoded probe list is the
+    defect reproduced inside the fix. Critical, EXCEPT the `local` fallback target (reported, but it
+    does not page). It never consults content, so it cannot alarm on a newborn tier; it never reports
+    ok when it could not ask.
+  - **LIVE:** degraded observed on the still-blind box (hub emailed `agent_capability_degraded`) →
+    grant applied on **both** demo boxes → token lists 3 and 4 archives → `ok=70 total=70 degraded=0`
+    and `degraded → ok` at the hub → **the host tier became a due-check candidate for the first time**,
+    correctly picking the 08-02 archive (08-03 had not settled 24 h).
+  - **The installer's real defect was NOT `PVE_STORAGES`** — see `felhom.eu` CONTEXT S-22: Case A
+    grants, the Scenario-F reuse arm did not. Fixed in installer **1.24.0** with a gate.
+
+- **2026-08-03 — v0.122.0 (R-189 · R-188 · R-186): three signals that lied about their own work.**
+  None touches data; all three cost attention, which every other signal depends on.
+  - **R-189 — a passing restore-test no longer vanishes on a restart.** `restore_tests[]` came only
+    from the in-memory `backup.Store` (*"lost on restart; the cadence re-populates"* — true under a
+    timer, FALSE since R-86, because the agent will not re-test a proven archive). **Observed live:**
+    a 14.5 GB offsite PASS at 15:25:14, agent restarted 2 m 43 s later, hub logged `0 restore-tests`
+    twice. `RestoreTestState` now stores `tier` + `verified` beside the archive (v3 shape; v1/v2
+    still read, and a record missing archive-or-tier is NOT reported), exposes
+    `ProvenRestoreTests`, and `Collector.SetProvenRestoreTests` merges it — **one entry per tier,
+    newest by `TestedAt` wins**, so a fresh failure beats a stored success and a tier never appears
+    twice. Wiring pinned by an AST test: the method this replaces (`Snapshot`) claimed a
+    "host-report gauge" in its doc comment and had **no caller** for weeks.
+  - **ONLY SUCCESSES ARE PERSISTED, and the reason is now in the code:** a success *suppresses*
+    future work (a proven archive is never re-tested, so a lost proof leaves the box quietly less
+    tested than it believes); a failure *causes* future work and heals itself at the next evaluation.
+  - **R-188 — the release stopped emailing false failures.** Only the tag PUSH moved (build → tag
+    locally → publish → push tag): the push is what wakes CI, and a tag visible before its package
+    made the gate correctly fail a correct release ~half the time. The old order's invariant is now
+    asserted directly — `check-published-versions.py` refuses a **published version with no tag**, as
+    a bounded, printed probe (the package listing api is still 401 without a token, re-measured).
+  - **R-186 — a released binary is verifiable.** `-trimpath -buildvcs=false`: same source → same
+    bytes whether or not the tag exists. Measured. `publish-agent.sh`'s fallback also forced
+    `CGO_ENABLED=0` and built a **74 KB different** binary for the same version — both paths now
+    identical. The verification command is in `CLAUDE.md`.
+
 - **2026-08-03 — v0.121.0 (R-86): the restore-test follows the BACKUP, not the clock.** The ticker is
   now only the **evaluation interval**; a tier is **DUE** when its newest archive that has settled for
   `settle` (default 24 h) **has not been proven**. Daily tier → proved daily on yesterday's archive;
@@ -26,6 +130,14 @@
     able to make a starting backup record a failure — F-A1), and the candidate picker skips archives
     failing `archivePlausiblyComplete` (a phantom would be due forever and fail forever).
   - New read-only `--selftest=restore-test-due` prints the per-tier verdict + its cost.
+  - **v0.121.1 — a quiet evaluation is AUDIBLE.** "Nothing is due" is now the NORMAL outcome, and at
+    DEBUG it was silent: an empty journal would have been equally consistent with a healthy loop and
+    a dead goroutine (standing rule 3 — the shape the R-88 watcher was retired for). A not-due
+    evaluation logs ONE INFO line naming every tier's verdict; an unlistable tier reads `UNKNOWN`
+    with its error in that same line.
+  - **PROVEN LIVE 2026-08-03 on demo-felhom:** due-triggered offsite restore-test of a 14.5 GB
+    encrypted PBS archive — restored, booted, verified, scratch destroyed, **635 s**; the state then
+    named that archive, a second evaluation ran nothing, and an agent restart ran nothing.
   - **R-185 (filed, NOT fixed here):** on demo-felhom the agent token has no ACL on
     `/storage/felhom-backup`, so its content listing comes back EMPTY (root sees 3 archives) — the
     host tier has never been restore-testable there, and the due-check cannot distinguish that from

REPORT.md

@@ -1,100 +1,9 @@
-# REPORT — releasing publishes, and an unreleasable version fails CI (R-115, R-183)
+# REPORT — 2026-10-04: v0.141.0, the host fast lane, the true tunnel status, the fast leg
 
-**Date:** 2026-08-03 · **Repo:** `felhom-agent` · **NO VERSION BUMP** — the agent stays **v0.120.0**,
-no Go code changed, nothing was built or deployed.
+Full session report: `felhom.eu/REPORT-os-host-lane-2026-10-04.md`.
 
-## What changed
-
-| File | |
-|---|---|
-| `scripts/release-agent.sh` | **new** — THE release path: build → tag → publish → verify by independent download |
-| `scripts/check-published-versions.py` | **new** — the R-115 gate |
-| `scripts/agent_gates.py` | registers the gate as **not `--fast`** (it needs network) |
-| `.gitea/workflows/gates.yml` | CI now runs the **full** gate set, not `--fast` |
-| `CLAUDE.md` | the raw `go build` line is replaced by the release script; a **Vouch** row replaces the old Publish row |
-
-## Why
-
-Publishing was a step someone had to remember and was **forgotten three times in five days** —
-R-111's seventeen stranded releases, 0.114.0, and 0.120.0, which sat deployed on both demo hosts and
-undownloadable, so a documented-path reinstall would have silently downgraded them to the pre-merge
-agent **while reporting success**. R-111's own closing line named this leg and closed SHIPPED without
-it; it recurred the same afternoon. A note is not a mechanism.
-
-The script also **tags**, because `felhom-host-install.sh` now fetches the agent's sixteen config
-files from `raw/tag/v<version>/` (R-183). A released version with no tag 404s a box mid-install, as
-root, on a virgin machine. Tag and package are two halves of one release.
-
-It **verifies by downloading what it just published** and comparing the sha to what it built. The
-publish step's own success is a report on its own write; a fetch returning the right bytes is a
-different claim, and it is the one that matters.
-
-It **does not vouch** — that points machines at a version and stays the operator's act.
-
-## The gate's invariant — not the one specified, and the reason was measured
-
-The task's §8.4 asked for *"the version the hub tells machines to install must be downloadable"*.
-**CI cannot see that**, measured rather than assumed (P-C):
-
-| Endpoint | Anonymous |
-|---|---|
-| Gitea package **download** | **200** (and **404** for a fake version — it discriminates) |
-| Gitea **tags** api | **200** |
-| Gitea package **listing** api | **401** — token required |
-| Hub `/api/v1/artifacts/<customer>` | **401** — per-customer passphrase required |
-
-So a credential-free gate can ask *"is this version installable"* but not *"which version is
-vouched"*. Adding an operator credential to CI to close that is the operator's call, not a gate
-author's. The implemented invariant — **every `v<semver>` tag must have a downloadable package and a
-tag tree that serves the agent's configs** — needs no credential and **catches all three recorded
-instances**, because the release script creates the tag and publishes in one act.
-
-**What it does not catch, stated rather than assumed away:** the hub vouching a version that was
-never released at all. Nothing here can see that; it belongs at vouch time in the hub. → **R-184**.
-
-## Proof
-
-| Check | Result |
-|---|---|
-| `go build ./... && go vet ./...` | OK |
-| `go test ./...` | **29 packages ok, rc=0** (read separately from any commit) |
-| `agent_gates.py --fast` | `published` correctly **SKIPPED** — the pre-push hook must not fail because Gitea blinked |
-| `agent_gates.py` (full) | `reuse-refs` OK, `published` OK |
-| release script: re-release guard | `ERROR: tag v0.120.0 already exists — releasing over it would make one version name two binaries`, rc=1 |
-| release script: clean-tree guard | `ERROR: working tree is dirty — commit and push first`, rc=1 |
-
-### Red-proof F — both directions
-
-- **A tagged-but-unpublished version** (`v9.9.9` created for the purpose): gate **rc=1**,
-  `binary NOT downloadable (HTTP 404 …)`. This is the R-115 shape exactly.
-- **The gate deregistered from the entry point**, same bad state: `agent_gates.py` → **rc=0, "all
-  agent gates OK"**. Restored → **rc=1, CONVICTED: published**. The guard is what catches it, not
-  something else.
-
-### Scenario F measured on REAL CI, not inferred
-
-Runs **69** and **70** are on the **same commit** `0db7766`:
-
-| run | state of the repo | CI |
-|---|---|---|
-| 69 | no `v9.9.9` | **success** |
-| 70 | `v9.9.9` tagged, not published | **failure** |
-
-Same code, same workflow, one variable — so the gate demonstrably RUNS in CI and fails for exactly
-the R-115 condition. This also retrospectively explains runs 67/68, which were red in the window when
-`v9.9.9` first existed. **One deliberate CI failure e-mail reached the operator — that was this
-proof, not an incident.**
-
-I could not read CI's own step log to attribute those runs directly: the Gitea jobs endpoint requires
-an API token, and the only credential available on this host (`~/.docker/config.json`) is a registry
-password, which the API rejects. The controlled before/after above replaced that log rather than an
-assumption standing in for it.
-
-`v9.9.9` was deleted afterwards; `git ls-remote --tags` shows only `v0.120.0`.
-
-## Tag convention
-
-`v<semver>`, at the commit the binary was built from. `v0.120.0` was created retroactively at
-`cd6e267` — the commit that produced the published binary (sha `a7763d31b55b5ce7…`). `configs/` is
-byte-identical between that commit and `main`, so nothing about the sixteen fetched files depends on
-the choice; `cd6e267` is tagged because it is the honest one.
+- Tunnel (R-841): the agent reads the guest's cloudflared container and its health check; three states.
+- Host fast lane: the wrapper gains the host layer (R12 appliance proof from the root-owned install record, R14 no
+  kernel/boot/firmware); the leg runs the host step after a healthy guest step; host health rule.
+- Speed (R-845): one call per layer instead of one per package; measured before/after in the session report.
+- Tests green; red-proofs in the audit folder.

REUSE.md

@@ -74,6 +74,7 @@
 | `EnsureLeaf` | internal/localapi/cert.go | `EnsureLeaf(certPath, keyPath, host) (cert, fingerprint, generated, err)` | pinned self-signed leaf | `generated=true` invalidates every issued bootstrap pin — log LOUD (B.1) |
 | `Server.RecoverStaleLockedGuests` | internal/localapi/stalelock.go | `RecoverStaleLockedGuests(ctx)` | startup stale vzdump-lock heal (F2-b) | Clears ONLY `backup`/`snapshot-delete`, only when no vzdump in-flight; A1 RESOLVED (v0.62.0): scan is pool-intersected (`ListLXC` ∩ `Client.Pool`), fail-safe skip on pool-read failure |
 | `ControllerSwapper.Swap` + `ValidControllerImage` | internal/localapi/controllerswap.go | `Swap(ctx, vmid, target) *ControllerSwapState` | agent-owned controller image swap + rollback | Strict image regex (repo + 3-part semver); state file written BEFORE swap; no-healthcheck images need `verifyDwell` |
+| `Server.ControllerSupervisorTick` + `ControllerParkedMarker` | internal/localapi/controllersupervisor.go | `ControllerSupervisorTick(ctx)` | R-523: restart a provisioned guest's not-running controller via its bootstrap unit | Two-sweep confirm; honours swapInFlight, the host-side park marker, guest lock + vzdump; 3 restarts/15 min → 30 min pause; record rides the report as `controller_supervisor` (the hub mints the events — the agent has no event channel) |
 | `MemoryOps` + `Server.readMemoryBounds` | internal/localapi/guestmemory.go | `readMemoryBounds(ctx, vmid) (memoryBounds, err)` | guest RAM resize (v0.90.0, R-24): GET/POST /guest/memory | NEW narrow seam (never extend `GuestAPI` — it breaks every fake); the AGENT is the boundary — bounds recomputed FRESH per request (min 2048 / max host_total−2048 / shrink floor max(2048, usage+512)); §8 UNITS TRAP (config `memory`=MB, status/node=bytes); verify maxmem==target after `SetConfig` before claiming success; SetConfig NEVER called on a refusal path |
 
 ### Proxmox client / hub / PBS / provisioning
@@ -84,8 +85,11 @@
 | `Client.Pool` | internal/proxmox/query.go | `Pool(ctx, name) (PoolInfo, error)` | felhom-pool membership (the ownership registry, A1) | Needs `Pool.Audit` at `/pool/<name>` (host-install v1.9.0+); `Pool.Allocate` does NOT satisfy the read; members can be storages (type `storage`, vmid 0) — filter them |
 | `Client` mutate wrappers (`RestoreLXC/Vzdump/DestroyLXC/Snapshot/Rollback/SetConfig/ResizeLXC/Start/Stop`) | internal/proxmox/mutate.go | return `(upid, error)` | all API mutations | Async → always pair with WaitTask; route via gate/queue, not ad-hoc |
 | `Client.PoolAddVMID` | internal/proxmox/mutate.go | `PoolAddVMID(ctx, pool, vmid) error` | re-assert pool membership after a restore-over-existing (campaign-2 R2) | SYNC (no UPID, don't WaitTask); PVE `PUT /pools` is additive (merge, not replace) — `delete=1` removes; idempotent (already-member swallowed); needs `Pool.Allocate` at `/pool/<pool>`. `pct restore --pool` sets membership only at CREATE — a restore over an existing vmid drops it, so bring-up re-asserts post-restore |
+| `reconcile.PreflightRestoreSpace` + `restorespace.Provider` (v0.133.0) | internal/reconcile/restoretest_space.go, internal/restorespace/restorespace.go | `PreflightRestoreSpace(ctx, space, policy, archive, rawCfg, configured) SpaceVerdict` | ANY step that restores or copies a guest onto a storage — size it first | The restored size is UNCOMPRESSED (vzdump log "Total bytes written" / PBS snapshot size) — never the archive FILE (6.9 GB file → 22.6 GB restore, R-672); an unknown refuses; eligibility needs Datastore.AllocateSpace on `/storage/<id>` specifically (the `/` grant answers every path) |
+| `Engine.RetryScratchTeardown` + the daemon janitor (v0.133.0) | internal/reconcile/restoretest_retry.go, cmd/felhom-agent/janitor.go | `RetryScratchTeardown(ctx) ScratchRetryResult` | retrying a leftover on a TIMER instead of only at start | Never `Recover` on a timer — it also resolves generic in-flight ops; a periodic sweep that unlocks guests holds the one-heavy-op gate (`InFlight.TryAcquire`) |
 | `TLSConfig.build` / `normalizeFingerprint` | internal/proxmox/tls.go | `build() (*tls.Config, error)` | PVE leaf-cert SHA-256 pinning | No insecure default |
 | `pinnedTLS` | internal/pbs/pin.go | `pinnedTLS(fingerprint) (*tls.Config, error)` | PBS leaf pinning | Same model as PVE; 64-hex fingerprint normalized |
+| `httpx.NewTransport` | internal/httpx/transport.go | `NewTransport(tlsCfg, idleConnTimeout) *http.Transport` | **EVERY** hand-rolled `http.Transport` in this repo — pbs, hub and proxmox all pin TLS, so none can use `http.DefaultTransport` | **R-344: never inline `&http.Transport{TLSClientConfig: ...}` again.** A composite literal takes `IdleConnTimeout` **zero, which means retain idle connections FOREVER** — `http.DefaultTransport` sets 90s and a literal does not inherit it. Combined with a client rebuilt per cycle and dropped (`pbsTargetsFromPVE`), that stranded **388 sockets on ep0 in 46 h**, held open on BOTH sides. `idleConnTimeout <= 0` means **use the default**, never "no timeout". Returns a **FRESH** transport every call — a shared one would pool connections across differently pinned endpoints. Pinned by `internal/pbs/client_leak_test.go` (server-side connection counting) + `internal/httpx/transport_test.go` |
 | `hub.Client.Report` | internal/hub/client.go | `Report(ctx, *HostReport) (*ControlEnvelope, error)` | the heartbeat | Typed `TransportError`/`HTTPError`, never contain the bearer token |
 | `hub.Loop` + `MultiObserver` | internal/hub/loop.go | `NewLoop(...)`; `MultiObserver(obs...)` | resilient report loop + envelope fan-out | Errors logged, loop continues; interval clamped 60–3600 s |
 | `provision.BackHalf.Provision` | internal/provision/backhalf.go | `Provision(ctx, Input) (Result, error)` | guest bootstrap back-half | mint→render→0600 write→chown 100000:100000→`pct set` ro bind→onboot; token NEVER logged/returned. Bootstrap `local_api.endpoint` = the caller's `cfg.LocalAPI.ListenAddr` (main.go) — moving the agent bind to the island moves the guest dial for free (R-50, no template) |
@@ -148,7 +152,9 @@
 | `localapi.DiskOps` / `StorageGate` / `GuestAttacher` / `GuestLister` | internal/localapi/disks.go | `*storage.SudoHostOps`; `storageGateAdapter` (cmd/felhom-agent/main.go); `*GuestBinder`; `*proxmox.Client` | `fakeDiskOps`/`fakeGate`/`fakeGuestAttacher`/`fakeGuestList` internal/localapi/disks_test.go |
 | `localapi.GuestAPI` / `BackupService` / `BackupStore` / `TokenAuthority` | internal/localapi/server.go | `*proxmox.Client`, `*backup.BackupRunner`, `*backup.Store`, `*TokenStore` | `fakeGuests`/`fakeBackups`/`fakeStore` internal/localapi/server_test.go |
 | `backup.InFlight` | internal/backup/inflight.go | `TryAcquire(what) (release, busy, ok)` / `Busy()` | THE host-wide "one heavy guest operation at a time" gate — shared by the local-API backup path and the restore-test scheduler (R-85) | A **LINK** guard, not a lock one: the scratch VMID never touches the live guest's vzdump lock, but an offsite restore PULLS multi-GB over the tunnel a backup PUSHES one. Callers **DEFER, never cancel** — a deferred restore-test costs coverage, a cancelled backup costs the backup. A nil gate is ungated (pre-R-85 callers). |
-| `backup.RestoreTestState` | internal/backup/restoretest_state.go | `RecordSuccess(target,archive,t)` / `ProvenArchive(target)` / `LastSuccess(target)` / `OldestFirst(targets)` | Per-tier restore-test PROOF state, persisted (atomic tmp+rename) — **which archive** was proven, and when (R-86) | **Credit ONLY on success** — a permanently failing tier must keep sorting first, or it looks freshly proven and stops being retried. Ties break on target id: without it, two tiers proven in the same second rotate by Go's randomised map order. **This one NEEDS persistence unlike R-84** — R-84 had ground truth to consult (the archive is still on the storage); a restore-test destroys its scratch and leaves no artifact. **R-86: the ARCHIVE is the state, the time is metadata** — a time alone cannot answer "have we proven THIS archive", which is the due-check's whole question. A pre-R-86 file (bare RFC3339 per target) keeps its time and yields NO proven archive, so each tier is due once after the upgrade; reading a legacy time as proof of the current archive would invent a guarantee. |
+| `capability` store-grant probe (`storeGrantStatuses` / `storeGrantVerdict` / `Client.Permissions`) | cmd/felhom-agent/main.go, internal/proxmox/query.go | *"may the agent READ this backup tier?"*, one `capability.Status` per configured tier | R-185. **Never infer permission from an empty content listing** — `{"data":[]}` is what a FORBIDDEN tier and a NEWBORN tier both return, and that ambiguity hid an unreadable host tier on both demo boxes. Ask `/access/permissions` **as the agent's own token** (root always says yes). **The ungranted answer is not empty and not a 403** — it carries the privileges inherited from the box-wide `/` grant, so test for **`Datastore.AllocateSpace`** specifically; path-presence or `Datastore.Audit` reports a blinded storage healthy. Probed set comes from `BackupTiers()`, never a fixed list. Critical except the `local` fallback. Composes AROUND the sudo prober (the `poolReadStatus` precedent); `Status`'s wire shape is untouched so the hub alert is free. Unreachable PVE ⇒ degraded, never ok. |
+| `backup.RestoreTestState` | internal/backup/restoretest_state.go | `RecordSuccess(target,archive,tier,verified,t)` / `ProvenArchive(target)` / `ProvenRestoreTests(ctx)` / `LastSuccess(target)` / `OldestFirst(targets)` | Per-tier restore-test PROOF state, persisted (atomic tmp+rename) — **which archive** was proven, and when (R-86) | **Credit ONLY on success** — a permanently failing tier must keep sorting first, or it looks freshly proven and stops being retried. Ties break on target id: without it, two tiers proven in the same second rotate by Go's randomised map order. **This one NEEDS persistence unlike R-84** — R-84 had ground truth to consult (the archive is still on the storage); a restore-test destroys its scratch and leaves no artifact. **R-86: the ARCHIVE is the state, the time is metadata** — a time alone cannot answer "have we proven THIS archive", which is the due-check's whole question. A pre-R-86 file (bare RFC3339 per target) keeps its time and yields NO proven archive, so each tier is due once after the upgrade; reading a legacy time as proof of the current archive would invent a guarantee. **R-189: it is also the REPORTABLE half of the restore-test signal.** The in-memory `backup.Store` holds only this process's latest run, and under per-archive due-ness the agent will not re-test a proven archive — so a proof lost to a restart is not repeated for a whole archive generation (observed live: a passing 14.5 GB offsite restore reached no host-report). `ProvenRestoreTests` renders the stored proofs as `hub.RestoreTest` entries and the collector merges them; a record missing the archive or the tier is NOT emitted, because an unproven tier reading as proven is worse than the defect. **Only successes are stored, deliberately:** a success suppresses future work, a failure causes it. |
+| `hub.ProvenRestoreTestReporter` + `Collector.SetProvenRestoreTests` | internal/hub/collect.go | the DURABLE restore-test source, merged with the in-memory one | R-189. Merge rule: **one entry per tier, newest by `TestedAt` wins** — a fresh failure beats a stored success (the failure is the news, and it lives nowhere else), a stored success beats a stale in-memory entry after a restart, and a tier never appears twice (the hub would read two tests). An unparseable timestamp counts as OLDER, so a malformed entry cannot displace a good one. **The wiring is pinned by an AST test** — the method this replaced (`RestoreTestState.Snapshot`) carried a doc comment naming a host-report gauge and had no caller for weeks. |
 | `backup.SpecBuilder` / `backup.TierPicker` / `(*BackupRunner).PickSettledRestoreCandidateOn` | internal/backup/schedule.go, runner.go | `func(ctx,archive) RestoreTestSpec`; `func(ctx,target,notAfter) (archive,landed,error)` | The per-run restore-test spec + per-tier **settled** candidate lookup (R-85, widened by R-86) | The spec is built **PER RUN**, never frozen at construction — the pre-R-85 immediately-invoked value made the offsite tier unschedulable AND went stale on any config change. `SourceTier` comes from **the archive**, never the configured target (the v0.100.0 rule). A tier with no archive returns `("", zero, nil)` — **`""` is NOT an error**, or every fresh box looks broken for its first week. **R-86: `notAfter` is the settle cutoff** (zero = no cutoff, which is what keeps `PickRestoreCandidateOn` a one-line call into it), and the picker now skips entries failing `archivePlausiblyComplete` — under per-archive due-ness an incomplete phantom would be picked forever, fail forever, never earn proof, and make the tier due at EVERY evaluation. |
 | `localapi.BackupTier` + `normalizeBackupTiers` / `config.BackupConfig.BackupTiers` | internal/localapi/backup_tiers.go, internal/config/config.go | `normalizeBackupTiers(tiers, legacy, cadence) []BackupTier`; `BackupTiers() ([]BackupTier, []string)` | THE R-82 multi-tier resolution — one runner per tier, primary first | **The untargeted local-API contract is FROZEN**: no `?target=` ⇒ primary tier ⇒ pre-R-82 response BYTES (Target is `omitempty` and stays empty). Never default a missing cadence — reject it and log the warning at ERROR. Never share one retention knob between tiers. Jobs are keyed by (vmid,target). |
 | `localapi.StaleLockController` | internal/localapi/stalelock.go | `*staleLockController` (Client + Runner + pool) | `fakeStaleLock` (Server-level) stalelock_test.go; `fakeStaleLockAPI` (controller-level, tests the A1 pool intersect) stalelock_pool_test.go |

cmd/felhom-agent/escrow_recover_wiring_test.go

@@ -0,0 +1,188 @@
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"strings"
+	"testing"
+)
+
+// Scenario H — THE SEAM IS WIRED IN THE PRODUCTION PATH, proven by walking the AST rather than by
+// grepping for a string.
+//
+// WHY THIS TEST EXISTS AND WHY IT IS AN AST WALK. This project's built-but-never-wired count is six,
+// and links 6 and 7 of the recovery chain were TWO of them: `UnwrapIdentityBundle` sat in the tree
+// for two months with no caller but a `--selftest`, and the hub's blob-serving endpoints have no
+// client to this day. The fix must not become the seventh. `strings.Contains` on the file would pass
+// against a commented-out line, a line inside a test helper, or a line in dead code behind a flag
+// nobody sets — so this resolves the call graph instead: `Options{EscrowRecovery: …}` must be
+// constructed inside a function that `runDaemon` reaches, and `runDaemon` must be reached by `main`.
+
+func parseMain(t *testing.T) (*token.FileSet, *ast.File) {
+	t.Helper()
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "main.go", nil, parser.ParseComments)
+	if err != nil {
+		t.Fatalf("parsing main.go: %v", err)
+	}
+	return fset, f
+}
+
+// callsWithin returns the set of function names called (directly, by identifier or selector) inside
+// the named top-level function.
+func callsWithin(f *ast.File, fnName string) map[string]bool {
+	out := map[string]bool{}
+	for _, d := range f.Decls {
+		fd, ok := d.(*ast.FuncDecl)
+		if !ok || fd.Name == nil || fd.Name.Name != fnName || fd.Body == nil {
+			continue
+		}
+		ast.Inspect(fd.Body, func(n ast.Node) bool {
+			ce, ok := n.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+			switch fn := ce.Fun.(type) {
+			case *ast.Ident:
+				out[fn.Name] = true
+			case *ast.SelectorExpr:
+				if x, ok := fn.X.(*ast.Ident); ok {
+					out[x.Name+"."+fn.Sel.Name] = true
+				}
+				out[fn.Sel.Name] = true
+			}
+			return true
+		})
+	}
+	return out
+}
+
+// TestEscrowRecoveryIsWiredIntoTheDaemon asserts the whole chain from func main() to the field.
+func TestEscrowRecoveryIsWiredIntoTheDaemon(t *testing.T) {
+	_, f := parseMain(t)
+
+	// 1. main() reaches runDaemon.
+	if !callsWithin(f, "main")["runDaemon"] {
+		t.Fatal("func main() does not call runDaemon — the daemon path this test asserts is not the live one")
+	}
+	// 2. runDaemon reaches buildLocalAPIServer.
+	if !callsWithin(f, "runDaemon")["buildLocalAPIServer"] {
+		t.Fatal("runDaemon does not call buildLocalAPIServer — the local API is not built on the daemon path")
+	}
+
+	// 3. Inside buildLocalAPIServer, a localapi.Options composite literal carries EscrowRecovery, and
+	//    an escrow.OffsiteKeyRecoverer is constructed there.
+	var optionsHasField, recovererConstructed bool
+	for _, d := range f.Decls {
+		fd, ok := d.(*ast.FuncDecl)
+		if !ok || fd.Name == nil || fd.Name.Name != "buildLocalAPIServer" || fd.Body == nil {
+			continue
+		}
+		ast.Inspect(fd.Body, func(n ast.Node) bool {
+			cl, ok := n.(*ast.CompositeLit)
+			if !ok {
+				return true
+			}
+			sel, ok := cl.Type.(*ast.SelectorExpr)
+			if !ok {
+				return true
+			}
+			pkg, _ := sel.X.(*ast.Ident)
+			if pkg == nil {
+				return true
+			}
+			switch pkg.Name + "." + sel.Sel.Name {
+			case "localapi.Options":
+				for _, el := range cl.Elts {
+					kv, ok := el.(*ast.KeyValueExpr)
+					if !ok {
+						continue
+					}
+					if k, ok := kv.Key.(*ast.Ident); ok && k.Name == "EscrowRecovery" {
+						optionsHasField = true
+					}
+				}
+			case "escrow.OffsiteKeyRecoverer":
+				recovererConstructed = true
+			}
+			return true
+		})
+	}
+	if !recovererConstructed {
+		t.Error("no escrow.OffsiteKeyRecoverer is constructed in buildLocalAPIServer — links 6→8 have no " +
+			"production assembly point (the built-but-never-wired shape, seventh instance)")
+	}
+	if !optionsHasField {
+		t.Error("localapi.Options in buildLocalAPIServer carries no EscrowRecovery field — the recoverer " +
+			"exists and the route would answer 503 forever")
+	}
+}
+
+// The hub fetch must be the DAEMON's own hub client, not a freshly constructed one with different
+// credentials — the self-scoping that makes cross-host retrieval impossible is a property of WHICH
+// key is used.
+func TestEscrowRecoveryUsesTheDaemonHubClient(t *testing.T) {
+	fset, f := parseMain(t)
+	var fetchUsesHubClient bool
+	for _, d := range f.Decls {
+		fd, ok := d.(*ast.FuncDecl)
+		if !ok || fd.Name == nil || fd.Name.Name != "buildLocalAPIServer" || fd.Body == nil {
+			continue
+		}
+		ast.Inspect(fd.Body, func(n ast.Node) bool {
+			ce, ok := n.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+			sel, ok := ce.Fun.(*ast.SelectorExpr)
+			if !ok || sel.Sel.Name != "FetchIdentityEscrow" {
+				return true
+			}
+			if x, ok := sel.X.(*ast.Ident); ok && x.Name == "hubClient" {
+				fetchUsesHubClient = true
+			} else {
+				t.Errorf("FetchIdentityEscrow at %s is called on something other than the injected hub client",
+					fset.Position(ce.Pos()))
+			}
+			return true
+		})
+	}
+	if !fetchUsesHubClient {
+		t.Fatal("the recoverer's fetcher does not call hubClient.FetchIdentityEscrow — either the fetch is " +
+			"not wired, or it uses a client whose credentials are not this host's")
+	}
+}
+
+// The route itself must be registered on the local API. A handler with no route is the same defect
+// one layer down, and it has shipped here before.
+func TestRecoverRouteIsRegistered(t *testing.T) {
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "../../internal/localapi/server.go", nil, 0)
+	if err != nil {
+		t.Fatalf("parsing localapi/server.go: %v", err)
+	}
+	var registered bool
+	ast.Inspect(f, func(n ast.Node) bool {
+		ce, ok := n.(*ast.CallExpr)
+		if !ok || len(ce.Args) < 2 {
+			return true
+		}
+		sel, ok := ce.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "HandleFunc" {
+			return true
+		}
+		lit, ok := ce.Args[0].(*ast.BasicLit)
+		if !ok {
+			return true
+		}
+		if strings.Contains(lit.Value, "/escrow/recover-offsite-password") {
+			registered = true
+		}
+		return true
+	})
+	if !registered {
+		t.Fatal("POST /escrow/recover-offsite-password is not registered on the local API mux — the handler " +
+			"exists and nothing can reach it")
+	}
+}

cmd/felhom-agent/janitor.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/backup"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+)
+
+// janitorInterval is how often the leftovers of an interrupted restore-test or backup are retried
+// (R-672 rule 3, R-673). Both used to be resolved ONLY at agent start: on 2026-09-24 a failed scratch
+// teardown kept a full thin pool full for 2.5 h, and a stale `snapshot-delete` lock blocked 9201's
+// whole-box backups for five hours — each cleared within a minute of an agent restart.
+const janitorInterval = 10 * time.Minute
+
+// janitorDeps are the janitor's seams (tests drive one pass with fakes).
+type janitorDeps struct {
+	retryScratch func(ctx context.Context) reconcile.ScratchRetryResult
+	staleLocks   func(ctx context.Context) // localapi Server.RecoverStaleLockedGuests; nil when the local API is off
+	heavy        *backup.InFlight
+	record       func(hub.RestoreTest)
+	now          func() time.Time
+	logger       *slog.Logger
+}
+
+// janitorPass is one pass. The stale-lock sweep runs only while holding the one-heavy-operation gate, so
+// no agent backup can START between its "no vzdump is running" check and its unlock (at start-up the
+// sweep ran before the backup loop existed; on a timer that ordering must be made, not assumed). A busy
+// gate skips the sweep this pass — the next pass retries.
+func janitorPass(ctx context.Context, d janitorDeps) {
+	if d.retryScratch != nil {
+		r := d.retryScratch(ctx)
+		if r.Examined > 0 {
+			d.logger.Info("janitor: restore-test scratch retry pass", "examined", r.Examined,
+				"destroyed", r.Destroyed, "already_gone", r.Clean, "failed", r.Failed)
+		}
+		for _, vmid := range r.GaveUp {
+			// The operator is told through the existing restore-test failure path: the hub raises
+			// restore_test_failed (operator) once per distinct archive — this record's archive names
+			// the stuck scratch guest.
+			if d.record != nil {
+				d.record(hub.RestoreTest{
+					SourceArchive: fmt.Sprintf("scratch-teardown:%d", vmid),
+					ScratchVMID:   vmid,
+					Pass:          false,
+					Error: fmt.Sprintf("restore-test scratch guest %d could not be torn down after %d retries — it holds its disks; remove it by hand (pct destroy %d) after checking what keeps it busy",
+						vmid, reconcile.MaxTeardownTries, vmid),
+					TestedAt: d.now().UTC().Format(time.RFC3339),
+				})
+			}
+		}
+	}
+	if d.staleLocks != nil {
+		release, busy, ok := d.heavy.TryAcquire("stale-lock-sweep")
+		if !ok {
+			d.logger.Info("janitor: stale-lock sweep deferred — a heavy operation is in flight", "busy", busy)
+			return
+		}
+		defer release()
+		d.staleLocks(ctx)
+	}
+}
+
+// runJanitor runs janitorPass every janitorInterval until ctx ends.
+func runJanitor(ctx context.Context, d janitorDeps) {
+	d.logger.Info("janitor: starting (restore-test scratch retry + stale-lock sweep)", "interval", janitorInterval)
+	t := time.NewTicker(janitorInterval)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			janitorPass(ctx, d)
+		}
+	}
+}

cmd/felhom-agent/janitor_test.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/backup"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+)
+
+// R-672 / R-673 (v0.133.0): one janitor pass, driven with fakes.
+
+func quiet() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }
+
+// A scratch the engine gave up on reaches the hub as a failed restore-test record naming it — the
+// existing operator path (restore_test_failed). Never a pass.
+func TestJanitor_GaveUpIsReportedAsAFailure(t *testing.T) {
+	var got []hub.RestoreTest
+	janitorPass(context.Background(), janitorDeps{
+		retryScratch: func(context.Context) reconcile.ScratchRetryResult {
+			return reconcile.ScratchRetryResult{Examined: 1, Failed: 1, GaveUp: []int{990000}}
+		},
+		heavy: &backup.InFlight{}, record: func(r hub.RestoreTest) { got = append(got, r) },
+		now: time.Now, logger: quiet(),
+	})
+	if len(got) != 1 || got[0].Pass || got[0].ScratchVMID != 990000 || !strings.Contains(got[0].Error, "990000") {
+		t.Fatalf("records = %+v — want one FAILED record naming scratch 990000", got)
+	}
+}
+
+// R-673: the stale-lock sweep runs only while holding the one-heavy-operation gate, so no agent backup can
+// start between its "no vzdump running" check and its unlock.
+//
+// COMPANION RED-PROOF (REPORT): drop the TryAcquire → "the sweep ran while a backup held the gate".
+func TestJanitor_StaleLockSweepWaitsForTheHeavyGate(t *testing.T) {
+	heavy := &backup.InFlight{}
+	swept := 0
+	d := janitorDeps{staleLocks: func(context.Context) { swept++ }, heavy: heavy, now: time.Now, logger: quiet()}
+	release, _, ok := heavy.TryAcquire("backup")
+	if !ok {
+		t.Fatal("setup")
+	}
+	janitorPass(context.Background(), d)
+	if swept != 0 {
+		t.Fatal("the sweep ran while a backup held the gate")
+	}
+	release()
+	janitorPass(context.Background(), d)
+	if swept != 1 {
+		t.Fatalf("swept %d times with the gate free — want 1", swept)
+	}
+	if _, _, ok := heavy.TryAcquire("after"); !ok {
+		t.Fatal("the sweep did not release the gate")
+	}
+}

cmd/felhom-agent/main.go

@@ -24,6 +24,7 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 
@@ -47,8 +48,10 @@ import (
 	"gitea.dooplex.hu/admin/felhom-agent/internal/pbsdr"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/poke"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/provision"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/osupdate"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/restorespace"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/selfheal"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/selfupdate"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/signedjobs"
@@ -58,7 +61,7 @@ import (
 
 // version is the agent version. Overridable at build time with
 // -ldflags "-X main.version=<v>"; defaults to the in-repo CHANGELOG version.
-var version = "0.92.1"
+var version = "0.131.0"
 
 // runGuestHook is the PVE hook body (`felhom-agent guest-hook <vmid> <phase>`). On pre-start it
 // creates placeholder dirs for any absent bind-mount source so the guest always boots (the C1 net);
@@ -240,6 +243,8 @@ func main() {
 		os.Exit(runSelftestRestoreTest(context.Background(), cfg, logger, archive))
 	case "restore-test-due":
 		os.Exit(runSelftestRestoreTestDue(context.Background(), cfg, logger))
+	case "os-update":
+		os.Exit(runSelftestOSUpdate(context.Background(), cfg, logger, vmid))
 	case "pbs-verify":
 		os.Exit(runSelftestPBSVerify(context.Background(), cfg, logger))
 	case "lanresolver":
@@ -411,6 +416,318 @@ func poolReadStatus(ctx context.Context, px *proxmox.Client) capability.Status {
 	return s
 }
 
+// storeGrantStatuses probes whether the agent's OWN TOKEN may read the storages this box depends
+// on — one capability.Status per configured backup tier (R-185).
+//
+// ── WHY THIS EXISTS, AND WHY IT IS NOT A CONTENT LISTING ─────────────────────────────────────
+//
+// On demo-felhom the token had FelhomAgentStore on local, local-lvm and felhom-pbs — and NOT on
+// `felhom-backup`, the storage the same installer had configured as `local_backup_target`. Asked
+// for that storage's content the API answers `{"data":[]}` while root sees three archives.
+//
+// **An empty listing is what a FORBIDDEN tier and a NEWBORN tier both return**, and no care at that
+// call site can separate them: `pickForThisRun` skips an empty tier (correctly — a fresh offsite
+// tier legitimately has nothing) and says "no settled archive yet". So the host tier on that box was
+// never restore-testable and nothing ever mentioned it. That is this project's own rule failing in a
+// new place: an empty answer is not evidence that there is nothing there.
+//
+// The permission question, unlike the listing, has a DEFINITE answer — so it is asked directly.
+//
+// ── WHAT IS PROBED, AND WHY NOT A FIXED LIST ─────────────────────────────────────────────────
+//
+// The tiers come from this box's own config (`BackupTiers()`), because a hardcoded probe list is
+// precisely the defect being fixed — the installer's hardcoded ACL set is what drifted from the
+// target it went on to configure. Probing what the box says it depends on cannot drift from it.
+//
+// CRITICAL, deliberately: a tier the agent cannot read is a tier whose backups are invisible to it
+// and which is never restore-tested. The hub alerts only on Critical, and a non-critical entry here
+// would ride the report and alert nobody — the same silence with extra steps.
+//
+// One exception, so an ordinary configuration is not turned into an alarm: a box with no dedicated
+// target (`local_backup_target: "local"`, which host-install's own comment calls the DEGRADED
+// fallback) is not treated as critical for that tier — see storeGrantCritical.
+func storeGrantStatuses(ctx context.Context, px *proxmox.Client, cfg config.Config, repair *storeGrantRepairer) []capability.Status {
+	tiers, _ := cfg.Backup.BackupTiers() // warnings are logged where the tiers are armed
+	out := make([]capability.Status, 0, len(tiers))
+	for _, t := range tiers {
+		out = append(out, storeGrantStatus(ctx, px, t.TargetID, storeGrantCritical(t.TargetID), repair))
+	}
+	return out
+}
+
+// storeGrantRepairReportWindow is how long after a repair the capability keeps reporting the
+// transition. It MUST exceed the hub report interval, or the record never reaches the operator.
+//
+// FOUND BY THE LIVE RUN, NOT BY THE TESTS (2026-08-04). The first implementation reported degraded
+// for exactly "one cycle" — the probe call that did the repair. But `probeAll` is invoked
+// INDEPENDENTLY by the startup/periodic self-check log and by the collector building a host report,
+// so the repairing call was the LOG's, and the report built three seconds later found the grant
+// present and reported `ok`. The agent's journal had the record; the hub had nothing; the operator
+// would have learned nothing. That is precisely the silence R-190 is about, re-created inside its own
+// mitigation.
+//
+// A latch on TIME rather than on call count fixes it: 20 minutes comfortably exceeds the 900 s report
+// interval, so at least one host-report must carry the transition, and it still clears on its own.
+const storeGrantRepairReportWindow = 20 * time.Minute
+
+// storeGrantRepairMinInterval bounds how often a single tier's grant may be re-granted (Scenario F).
+//
+// A storage can be unreadable for reasons an ACL cannot fix — the storage is gone, PVE is wedged,
+// the wrapper is missing. Without a bound the probe would re-grant on every report cycle forever: a
+// repair loop is a new defect wearing a fix's clothes. One attempt per tier per hour is frequent
+// enough that a real loss is repaired within one backup window, and rare enough that a permanent
+// fault produces attempts you can count on one hand per day.
+const storeGrantRepairMinInterval = time.Hour
+
+// storeGrantRepairer bounds and records the self-repair. It is deliberately in-memory: an agent
+// restart re-arms the repair, which is correct — a restart is exactly when a box should re-check
+// everything it depends on.
+type storeGrantRepairer struct {
+	run      func(ctx context.Context, name string, args ...string) ([]byte, []byte, error)
+	log      *slog.Logger
+	mu       sync.Mutex
+	last     map[string]time.Time // target id → last ATTEMPT (success or failure)
+	repaired map[string]time.Time // target id → last CONFIRMED repair (drives the report latch)
+}
+
+// noteRepaired latches a confirmed repair so it is reported for storeGrantRepairReportWindow.
+func (r *storeGrantRepairer) noteRepaired(target string, now time.Time) {
+	if r == nil {
+		return
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.repaired == nil {
+		r.repaired = map[string]time.Time{}
+	}
+	r.repaired[target] = now
+}
+
+// recentlyRepaired reports whether a confirmed repair is still inside its report window — the latch
+// that guarantees a host-report carries the transition even though the probe that repaired may have
+// been a log-only one.
+func (r *storeGrantRepairer) recentlyRepaired(target string, now time.Time) bool {
+	if r == nil {
+		return false
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	t, ok := r.repaired[target]
+	return ok && now.Sub(t) < storeGrantRepairReportWindow
+}
+
+// mayAttempt reports whether a repair may run now for this target, and records the attempt if so.
+func (r *storeGrantRepairer) mayAttempt(target string, now time.Time) bool {
+	if r == nil || r.run == nil {
+		return false
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.last == nil {
+		r.last = map[string]time.Time{}
+	}
+	if t, ok := r.last[target]; ok && now.Sub(t) < storeGrantRepairMinInterval {
+		return false
+	}
+	r.last[target] = now
+	return true
+}
+
+// repair runs the EXISTING root wrapper's `grant` verb for this storage. It adds no privileged
+// surface: `felhom-backup-target-apply grant *` is already in the sudoers allowlist for any storage
+// id (configs/felhom-agent.sudoers), and the verb already grants BOTH the user and the token — a
+// privsep token's rights are the intersection, so granting one of the two grants nothing usable.
+//
+// This is the pbsdr shape (internal/pbsdr/manager.go, the R-22 self-grant): on a refusal, run the
+// root wrapper and RE-READ ONCE rather than dead-locking. Its restraint is copied too — one attempt,
+// one confirmation, and anything still wrong stays loudly wrong.
+func (r *storeGrantRepairer) repair(ctx context.Context, target string) error {
+	rctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	_, errOut, err := r.run(rctx, localapi.BackupTargetWrapperPath, "grant", target)
+	if err != nil {
+		r.log.Error("store-grant: SELF-REPAIR FAILED — the tier stays unreadable",
+			"target", target, "err", err, "stderr", strings.TrimSpace(string(errOut)))
+		return err
+	}
+	return nil
+}
+
+// storeGrantRequiredPriv is the privilege whose ABSENCE was measured to blind the content listing.
+//
+// Measured on demo-felhom 2026-08-03: the two storages that list through the token hold
+// Datastore.Allocate + Datastore.AllocateSpace (the FelhomAgentStore role); the one that answers
+// empty holds only what the box-wide grant propagates (Sys.Audit, SDN.Use, Datastore.Audit). It is
+// NOT Datastore.Audit that is missing — checking for that would report the blinded storage healthy.
+const storeGrantRequiredPriv = "Datastore.AllocateSpace"
+
+// storeGrantCritical decides whether a missing grant on this target is Critical (operator-paged).
+//
+// "local" is host-install's DEGRADED fallback target — a box with no dedicated backup storage is a
+// known, ordinary configuration, and turning it into a critical alert is how a signal becomes
+// something an operator archives unread. It is still probed and still reported; only the paging
+// differs.
+func storeGrantCritical(targetID string) bool { return targetID != "local" }
+
+// storeGrantStatus is one tier's grant probe. It NEVER reports ok when it could not ask: a
+// self-check that fails open is worse than none, because it converts "I do not know" into "fine".
+func storeGrantStatus(ctx context.Context, px *proxmox.Client, targetID string, critical bool, repair *storeGrantRepairer) capability.Status {
+	s := capability.Status{
+		Name:     "pve:store-grant:" + targetID,
+		Feature:  "backup tier " + targetID + " readable by the agent (archive listing, restore-test candidacy)",
+		Critical: critical,
+		Status:   capability.StatusOK,
+	}
+	if px == nil {
+		s.Status, s.Reason = capability.StatusDegraded, "not configured"
+		return s
+	}
+	if targetID == "" {
+		s.Status, s.Reason = capability.StatusDegraded, "tier has no target id"
+		return s
+	}
+	pctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	privs, err := px.Permissions(pctx, "/storage/"+targetID)
+	s = storeGrantVerdict(targetID, critical, privs, err)
+	if err != nil {
+		return s
+	}
+	if s.Status != capability.StatusDegraded {
+		// Healthy — but if this tier was repaired moments ago, keep REPORTING the transition until a
+		// host-report has certainly carried it. Without this latch the repairing probe may be a
+		// log-only one and the hub never learns anything happened (measured live, see the window's
+		// comment).
+		return storeGrantHealthyVerdict(targetID, critical, s, repair.recentlyRepaired(targetID, time.Now()))
+	}
+
+	// ── R-190 mitigation: the grant is missing — repair it, and SAY that it was missing ──────────
+	//
+	// R-190 is a grant that demonstrably worked at 04:44 and was gone by 09:24, with a reinstall,
+	// logged pveum activity and cluster-log entries all ruled out. The cause is still open; the
+	// resilience does not have to wait for it. Everything needed already exists — the root wrapper,
+	// its sudoers vector for any storage id, and the exact command — and until now the `grant` verb
+	// had only ever been called at CREATION. That is the "built but never wired" shape, in a verb
+	// rather than a seam.
+	if !repair.mayAttempt(targetID, time.Now()) {
+		// Bounded (Scenario F): an earlier attempt did not hold and it is too soon to try again. Stay
+		// degraded and say why — a quiet "we already tried" is how a permanent fault becomes silence.
+		s.Reason = "the agent token lacks " + storeGrantRequiredPriv + " on /storage/" + targetID +
+			" and a self-repair was attempted within the last " + storeGrantRepairMinInterval.String() +
+			" without holding — NOT retrying yet; this needs a human"
+		return s
+	}
+	if rerr := repair.repair(ctx, targetID); rerr != nil {
+		s.Reason = "the agent token lacks " + storeGrantRequiredPriv + " on /storage/" + targetID +
+			" and the self-repair FAILED (" + rerr.Error() + ") — this tier's archives are INVISIBLE to the agent"
+		return s // Scenario E: a failed repair must never mask the degraded state.
+	}
+	// Re-read ONCE to confirm, exactly as pbsdr does — the wrapper reporting success is a claim about
+	// its own write; the grant being readable is a different claim, and it is the one that matters.
+	cctx, ccancel := context.WithTimeout(ctx, 10*time.Second)
+	defer ccancel()
+	privs2, err2 := px.Permissions(cctx, "/storage/"+targetID)
+	if err2 != nil || privs2[storeGrantRequiredPriv] != 1 {
+		s.Reason = "the agent token lacks " + storeGrantRequiredPriv + " on /storage/" + targetID +
+			" and the self-repair did not take (re-read says it is still missing) — this needs a human"
+		return s
+	}
+
+	// REPAIRED — and reported as DEGRADED for exactly this one cycle, deliberately.
+	//
+	// The tier works again, so "ok" would be true of this instant and would throw away the only
+	// evidence that anything happened. R-190's own words: the probe sees the STATE, nothing sees the
+	// TRANSITION. A silent self-repair makes a recurring loss undetectable forever, which is strictly
+	// worse than the fault it fixes.
+	//
+	// §8.5 asked whether the hub's existing degraded↔ok edge suffices before building anything new.
+	// It does — as a CHANNEL — but only if the agent deliberately reports one degraded cycle: the hub
+	// alerts and e-mails on the ok→degraded edge and logs the degraded→ok recovery, so one loss
+	// produces exactly one alert pair and the operator learns of it. NOTHING NEW WAS BUILT: no wire
+	// change, no hub change, no new event type. The `Feature` text carries the explanation because
+	// that is the field the hub puts in the operator's e-mail (the Reason does not travel).
+	repair.noteRepaired(targetID, time.Now())
+	s = storeGrantRepairedVerdict(targetID, critical)
+	repairLogger(repair).Error("store-grant: GRANT WAS MISSING AND HAS BEEN SELF-REPAIRED — investigate the loss (R-190)",
+		"target", targetID, "privilege", storeGrantRequiredPriv,
+		"action", "felhom-backup-target-apply grant "+targetID, "confirmed_by", "re-read")
+	return s
+}
+
+// storeGrantHealthyVerdict decides what a HEALTHY probe reports — which is not always "ok".
+//
+// Split out so the tests exercise this decision rather than a copy of it. An earlier version of this
+// guard lived inline and its red-proof PASSED, because the test asserted the latch helper instead of
+// the path that consumes it — the same hollow shape this file has now caught twice.
+//
+// If the tier was repaired inside the report window, the transition is reported even though the grant
+// is present: the probe that repaired may have been a log-only one, and without this the host-report
+// carries `ok` and the operator never learns the permission vanished (measured live 2026-08-04).
+func storeGrantHealthyVerdict(targetID string, critical bool, healthy capability.Status, repairedRecently bool) capability.Status {
+	if repairedRecently {
+		return storeGrantRepairedVerdict(targetID, critical)
+	}
+	return healthy
+}
+
+// storeGrantRepairedVerdict is the post-repair verdict — the RECORD half of R-190, split out so the
+// tests exercise the real thing rather than a copy of it (yesterday's hollow-test lesson).
+//
+// It reports DEGRADED although the tier now works, and that is the whole point: "ok" would be true of
+// this instant and would throw away the only evidence that a permission vanished. The hub raises its
+// ok→degraded edge (an operator e-mail) and logs the degraded→ok recovery on the next cycle, so one
+// loss produces exactly one alert pair. Nothing new was built for this — no wire change, no hub
+// change, no new event type.
+//
+// The explanation lives in FEATURE because that is the field the hub interpolates into the operator's
+// e-mail (`monitor/host_capability.go` emitTransition builds its message from the capability names
+// and features; Reason does not travel). Putting it in Reason alone would be a record nobody reads.
+func storeGrantRepairedVerdict(targetID string, critical bool) capability.Status {
+	return capability.Status{
+		Name:     "pve:store-grant:" + targetID,
+		Critical: critical,
+		Status:   capability.StatusDegraded,
+		Feature: "backup tier " + targetID + ": the agent's storage grant was MISSING and has been " +
+			"AUTOMATICALLY RESTORED — the tier works now, but a permission that vanished on its own needs investigating (R-190)",
+		Reason: "grant absent at probe time; `felhom-backup-target-apply grant " + targetID +
+			"` re-applied it and a re-read confirms " + storeGrantRequiredPriv + " is present again",
+	}
+}
+
+// repairLogger returns the repairer's logger, or the default — the record must survive a nil.
+func repairLogger(r *storeGrantRepairer) *slog.Logger {
+	if r != nil && r.log != nil {
+		return r.log
+	}
+	return slog.Default()
+}
+
+// storeGrantVerdict is the DECISION, split out from the API call so the tests exercise the real
+// thing rather than a copy of it. A test that re-implements this branch would pass while production
+// diverged — which is the hollow shape this project keeps finding in its own tests.
+func storeGrantVerdict(targetID string, critical bool, privs map[string]int, err error) capability.Status {
+	s := capability.Status{
+		Name:     "pve:store-grant:" + targetID,
+		Feature:  "backup tier " + targetID + " readable by the agent (archive listing, restore-test candidacy)",
+		Critical: critical,
+		Status:   capability.StatusOK,
+	}
+	if err != nil {
+		// Unreachable PVE is UNKNOWN, and unknown is reported as degraded rather than ok: a
+		// self-check that fails open converts "I do not know" into "fine".
+		s.Status, s.Reason = capability.StatusDegraded, "could not read own permissions: "+err.Error()
+		return s
+	}
+	if privs[storeGrantRequiredPriv] != 1 {
+		// Name the storage AND the missing role: "a storage grant is missing" without saying which
+		// one costs a diagnosis at 07:00.
+		s.Status, s.Reason = capability.StatusDegraded,
+			"the agent token lacks "+storeGrantRequiredPriv+" on /storage/"+targetID+
+				" (grant FelhomAgentStore there) — this tier's archives are INVISIBLE to the agent and it is never restore-tested"
+	}
+	return s
+}
+
 // logCapabilities logs the privileged-capability self-check at startup: one INFO summary, plus an
 // ERROR per degraded capability naming the gated feature (so a missing grant is loud at cutover,
 // not days later). Inactive (config-gated off, plumbing healthy — v0.86.0) is counted in the
@@ -468,7 +785,7 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	pbsStore := pbs.NewSnapshotStore()
 	pbsTargets := pbsTargetsFromPVE(cfg, px, logger)
 	pbsReporter := pbs.NewLiveSnapshotReporter(pbsTargets, pbsStore, pbs.DefaultLiveSnapshotTimeout, logger)
-	collector := hub.NewCollector(px, hub.SystemctlProber{}, observer, backupStore, backupStore, pbsReporter, cfg.Hub.HostID, version, logger)
+	collector := hub.NewCollector(px, newTunnelProber(cfg, px), observer, backupStore, backupStore, pbsReporter, cfg.Hub.HostID, version, logger)
 	collector.SetBackupTargetResolver(primaryBackupTargetOf(cfg)) // R-109: the recipe names the live target
 	// Privileged-capability self-check (v0.44.0): probe the sudoers grants the non-root agent
 	// depends on. The probe runs `sudo -n -l` LITERALLY (a policy LIST, never executing the
@@ -492,8 +809,19 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	// A1 (v0.62.0): compose the PVE pool-read check AROUND the sudo prober (an API read does not
 	// belong inside the sudo-policy probe). Non-critical: a degraded pool read means the stale-lock
 	// reaper fail-safes (locks stay uncleared) — visible on the hub report, no operator page.
+	// R-185: the store-grant probes compose around the sudo prober the same way the pool read does
+	// (an API read does not belong inside the sudo-policy probe — the v0.62.0 A1 precedent).
+	// R-190: the store-grant probe also REPAIRS a missing grant, through the root wrapper that
+	// already exists and is already sudoers-permitted for any storage id — and reports the loss.
+	// The runner is the DIRECT one for the same reason the sudo prober uses it: the wrapper is
+	// invoked through the privileged path, which prepends sudo itself.
+	grantRepairer := &storeGrantRepairer{
+		run: (&proxmox.ExecRunner{Mode: proxmox.RunnerMode(cfg.Privileged.Mode)}).Run,
+		log: logger,
+	}
 	probeAll := func(ctx context.Context) []capability.Status {
-		return append(capProber.Probe(ctx), poolReadStatus(ctx, px))
+		out := append(capProber.Probe(ctx), poolReadStatus(ctx, px))
+		return append(out, storeGrantStatuses(ctx, px, cfg, grantRepairer)...)
 	}
 	// (The startup self-check log runs AFTER the pbsdr manager is wired below, so its snapshot
 	// already carries the gated view — v0.86.0.)
@@ -514,6 +842,10 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	// The "Down" channel sync hook: on each heartbeat, fetch desired-state when the generation
 	// advances. The loop calls it via the EnvelopeObserver seam (hub does not import desired).
 	desiredSyncer := desired.NewSyncer(client, desiredProvider, logger)
+	// OS updates, guest fast lane (agent v0.140.0, `11-os-updates.md` §8 step 2): the leg consumes the hub's
+	// os_update block and runs after each successful primary whole-guest backup (wired on the local API below).
+	osLeg := newOSLeg(cfg, client, px, logger)
+	desiredSyncer.AddConsumer(osLeg)
 	// S5: consume a host_loss restore_directive into an inspectable restore PLAN (derive + surface,
 	// execute nothing). The recipe is fetched on-demand (rare directive) via a fresh Collect.
 	desiredSyncer.AddConsumer(dr.NewConsumer(func(ctx context.Context) *hub.DRRecipeHostHalf {
@@ -573,6 +905,13 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	// it finds nothing to flag. The re-mount dispatch is off the poll path (a goroutine).
 	storageTrigger := make(chan struct{}, 1)
 	loop.SetTrigger(storageTrigger)
+	// R-672: a thin pool crossing 90 % requests a report at once (the hub's storage-fill alarm).
+	observer.SetThinHighTrigger(func() {
+		select {
+		case storageTrigger <- struct{}{}:
+		default:
+		}
+	})
 	remounter := &gateRemounter{gate: gate, ops: hostOps, hostID: cfg.Hub.HostID, logger: logger}
 	// Drive intent store (slice 10 P3 self-heal): persisted, durable-id-keyed enroll/eject/decommission
 	// state. Gates the watchdog's self-heal re-mount to ENROLLED drives, and the local API records
@@ -639,6 +978,7 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 		Logger:   logger,
 	})
 
+	rtSpace, rtPolicy := restoreSpaceFor(cfg, px, hostOps)
 	engine := reconcile.NewEngine(reconcile.EngineOptions{
 		API:      px,
 		Queue:    queue,
@@ -647,6 +987,9 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 		Gate:     gate,
 		HostID:   cfg.Hub.HostID,
 		Logger:   logger,
+		// R-672: the restore-test's space preflight (nil would refuse every test — fail-closed).
+		RestoreSpace: rtSpace,
+		SpacePolicy:  rtPolicy,
 	})
 
 	// Crash recovery (doc 03 §10): resolve any op that was in flight when the agent
@@ -662,6 +1005,12 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	rtState := backup.NewRestoreTestState(filepath.Join(cfg.OOB.WithDefaults().StateDir, "restore-test-state.json"))
 	heavyOps := &backup.InFlight{}
 	scheduler := buildRestoreTestScheduler(cfg, px, engine, backupStore, rtState, heavyOps, logger)
+	// R-189: the host report's restore_tests[] must survive an agent restart. The in-memory store
+	// holds only this process's latest run, and under per-archive due-ness the agent will not
+	// re-test an archive it has already proven — so without this the hub can report a tier unproven
+	// for a whole archive generation after a deploy. Observed live on 2026-08-03: a passing 14.5 GB
+	// offsite restore-test reached no host-report at all.
+	collector.SetProvenRestoreTests(rtState)
 
 	// PBS verify loop (slice 6 Phase B): the fifth daemon goroutine. Cheap, key-free,
 	// ciphertext-level integrity check on its own cadence (default 6h), reporting per-snapshot
@@ -769,7 +1118,18 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 			return false
 		},
 	}
-	localSrv := buildLocalAPIServer(cfg, px, backupStore, heavyOps, observer, driveKnown, hostOps, gate, collector, intentRec, guestBindStore, formatJobStore, logRing, escrowCeremonyCfg, logger, &localTokens)
+	localSrv := buildLocalAPIServer(cfg, px, backupStore, heavyOps, observer, driveKnown, hostOps, gate, collector, client, intentRec, guestBindStore, formatJobStore, logRing, escrowCeremonyCfg, logger, &localTokens)
+	if localSrv != nil {
+		localSrv.SetAfterPrimaryBackup(func(ctx context.Context, vmid int) {
+			// Let the controller finish bringing its apps back after the backup, then run (still under the gate).
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(90 * time.Second):
+			}
+			_, _ = osLeg.Run(ctx, vmid, "night")
+		})
+	}
 	if localTokens != nil {
 		defer localTokens.Close()
 	}
@@ -1071,8 +1431,22 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 		// appliance outage with nothing retrying) needs a PERIODIC check. onboot is the "should be
 		// running" signal, so a deliberately stopped guest is never touched.
 		go localSrv.WatchGuestPower(ctx)
+		// R-523: a controller container that is simply not running (killed, stopped, a failed
+		// self-update) is restarted through its bootstrap unit — nothing else watches it.
+		collector.SetControllerSupervisorReporter(localSrv)
+		go localSrv.WatchControllers(ctx)
 		go func() { errc <- localSrv.Run(ctx) }()
 	}
+	// R-672 / R-673: retry a failed restore-test teardown and sweep stale backup locks on a timer, not
+	// only at start-up (janitor.go).
+	{
+		jd := janitorDeps{retryScratch: engine.RetryScratchTeardown, heavy: heavyOps,
+			record: backupStore.RecordRestoreTest, now: time.Now, logger: logger}
+		if localSrv != nil {
+			jd.staleLocks = localSrv.RecoverStaleLockedGuests
+		}
+		go runJanitor(ctx, jd)
+	}
 	if lanLoop != nil {
 		lanServers = 1
 		go func() { errc <- lanLoop.Run(ctx) }()
@@ -1347,7 +1721,7 @@ func buildRestoreTestScheduler(cfg config.Config, px *proxmox.Client, engine *re
 // leaf (stable fingerprint). Any failure DISABLES the server (returns nil) WITHOUT crashing the
 // daemon — the host still reports/reconciles; only the controller channel is unavailable until
 // fixed. The opened token store is returned via outTokens so the caller can Close it.
-func buildLocalAPIServer(cfg config.Config, px *proxmox.Client, store *backup.Store, inFlight *backup.InFlight, observer *storage.Observer, driveTargets storage.KnownTargets, hostOps *storage.SudoHostOps, gate *reconcile.Gate, collector *hub.Collector, intent localapi.IntentRecorder, guestBinds *localapi.GuestBindStore, formatJobs *localapi.FormatJobStore, logRing *applog.Ring, escrowCeremony *localapi.EscrowCeremonyConfig, logger *slog.Logger, outTokens **localapi.TokenStore) *localapi.Server {
+func buildLocalAPIServer(cfg config.Config, px *proxmox.Client, store *backup.Store, inFlight *backup.InFlight, observer *storage.Observer, driveTargets storage.KnownTargets, hostOps *storage.SudoHostOps, gate *reconcile.Gate, collector *hub.Collector, hubClient *hub.Client, intent localapi.IntentRecorder, guestBinds *localapi.GuestBindStore, formatJobs *localapi.FormatJobStore, logRing *applog.Ring, escrowCeremony *localapi.EscrowCeremonyConfig, logger *slog.Logger, outTokens **localapi.TokenStore) *localapi.Server {
 	if !cfg.LocalAPI.Enabled() {
 		return nil
 	}
@@ -1419,21 +1793,68 @@ func buildLocalAPIServer(cfg config.Config, px *proxmox.Client, store *backup.St
 		gaMode = proxmox.RunnerSudo
 	}
 	guestBinder := localapi.NewGuestBinder(&proxmox.ExecRunner{Mode: gaMode, SudoPath: cfg.Privileged.SudoPath}, logger)
+	// R-199 (v0.125.0) — chain links 6->8, assembled here and ONLY here. The fetcher is this daemon's
+	// own hub client (per-host key, self-scoped server-side), so the recoverer can never read another
+	// host's blob even if asked to. `client` is the same one the report loop uses; a nil hub config
+	// cannot reach this line (the daemon exits above), so the seam is always live in production —
+	// which is the point: links 6 and 7 spent months existing without a caller.
+	escrowRecoverer := escrow.OffsiteKeyRecoverer{
+		Fetch: func(ctx context.Context) ([]byte, bool, error) {
+			resp, ferr := hubClient.FetchIdentityEscrow(ctx)
+			if ferr != nil {
+				return nil, false, ferr
+			}
+			if !resp.Present || resp.IdentityEscrowB64 == "" {
+				return nil, false, nil
+			}
+			blob, derr := base64.StdEncoding.DecodeString(resp.IdentityEscrowB64)
+			if derr != nil {
+				return nil, false, fmt.Errorf("hub served a malformed escrow blob (not base64)")
+			}
+			return blob, true, nil
+		},
+		// R-311 — the RETAINED packages, wired here and ONLY here, on the same self-scoped hub client.
+		// Consulted only after the current package has refused the code (see tryRetained), so the
+		// ordinary recovery pays nothing for it and cannot fail because of it.
+		FetchRetained: func(ctx context.Context) ([]escrow.RetainedBlob, int, error) {
+			resp, ferr := hubClient.FetchRetainedIdentityEscrow(ctx)
+			if ferr != nil {
+				return nil, 0, ferr
+			}
+			out := make([]escrow.RetainedBlob, 0, len(resp.Packages))
+			for _, p := range resp.Packages {
+				blob, derr := base64.StdEncoding.DecodeString(p.IdentityEscrowB64)
+				if derr != nil || len(blob) == 0 {
+					// One malformed package must not sink the rest — the customer's code may open a
+					// later one, and a skipped entry is strictly better than a refusal we cannot justify.
+					continue
+				}
+				out = append(out, escrow.RetainedBlob{
+					Blob:           blob,
+					SupersededAt:   p.SupersededAt,
+					KeyFingerprint: p.KeyFingerprint,
+					Index:          p.Index,
+				})
+			}
+			return out, resp.UnopenableCount, nil
+		},
+	}
 	srv, err := localapi.NewServer(localapi.Options{
-		ListenAddr:    cfg.LocalAPI.ListenAddr,
-		Cert:          cert,
-		AgentVersion:  version, // v0.82.0: the X-Felhom-Agent-Version capability channel
-		Guests:        px,
-		Backups:       runner,
-		BackupTiers:   apiTiers, // R-82: primary first; untargeted endpoints act on the primary
-		InFlight:      inFlight, // R-85: shared with the restore-test scheduler (Scenario F)
-		Store:         store,
-		Storage:       observer,
-		DriveTargets:  driveTargets,                    // Impl-2a: registry+units drives for the /disks view (union w/ Observe storages)
-		Smart:         storage.NewSmartReader(hostOps), // v0.95.0 Fix B: SMART for the union-path drives
-		HostReader:    storage.NewProcHostReader(),     // Impl-2b: durableIDForMount raw-mount fallback + role gate
-		Tokens:        tokens,
-		BackupCadence: cfg.Backup.BackupCadence(),
+		EscrowRecovery: escrowRecoverer,
+		ListenAddr:     cfg.LocalAPI.ListenAddr,
+		Cert:           cert,
+		AgentVersion:   version, // v0.82.0: the X-Felhom-Agent-Version capability channel
+		Guests:         px,
+		Backups:        runner,
+		BackupTiers:    apiTiers, // R-82: primary first; untargeted endpoints act on the primary
+		InFlight:       inFlight, // R-85: shared with the restore-test scheduler (Scenario F)
+		Store:          store,
+		Storage:        observer,
+		DriveTargets:   driveTargets,                    // Impl-2a: registry+units drives for the /disks view (union w/ Observe storages)
+		Smart:          storage.NewSmartReader(hostOps), // v0.95.0 Fix B: SMART for the union-path drives
+		HostReader:     storage.NewProcHostReader(),     // Impl-2b: durableIDForMount raw-mount fallback + role gate
+		Tokens:         tokens,
+		BackupCadence:  cfg.Backup.BackupCadence(),
 		// Disk management (slice 8C): the privileged host surface + the data-bearing wipe gate.
 		Disks:       hostOps,
 		DiskGate:    storageGateAdapter{gate: gate, hostID: cfg.Hub.HostID},
@@ -1449,6 +1870,7 @@ func buildLocalAPIServer(cfg config.Config, px *proxmox.Client, store *backup.St
 		StateDir:       cfg.WGTunnel.WithDefaults().StateDir,
 		SmbCredsDir:    cfg.Privileged.SmbCredsDir,
 		ControllerSwap: guestBinder, // Phase 1: agentic controller update — in-guest image swap
+		GuestsStateDir: "/var/lib/felhom-agent/guests", // R-523: <vmid>/bootstrap + controller-parked marker
 		// F2-b: recover a guest left with a stale vzdump lock by a reboot-during-backup. Reads + start
 		// go through the API client; the `pct unlock` is the one fenced root-CLI op (no API equivalent).
 		// A1 (v0.62.0): the scan is restricted to felhom-pool members (ownership proven, not assumed).
@@ -1604,7 +2026,7 @@ func runSelftestHub(ctx context.Context, cfg config.Config, logger *slog.Logger)
 	// pbs coord. The live reporter lists snapshots directly (fresh store, last-known-good fallback) so
 	// the selftest reflects exactly what a freshly-restarted daemon's first collect emits.
 	pbsReporter := pbs.NewLiveSnapshotReporter(pbsTargetsFromPVE(cfg, px, logger), pbs.NewSnapshotStore(), pbs.DefaultLiveSnapshotTimeout, logger)
-	collector := hub.NewCollector(px, hub.SystemctlProber{}, observer, nil, nil, pbsReporter, cfg.Hub.HostID, version, logger)
+	collector := hub.NewCollector(px, newTunnelProber(cfg, px), observer, nil, nil, pbsReporter, cfg.Hub.HostID, version, logger)
 	// R-109: wire the backup-target resolver here TOO. Without it selftest=hub would print a recipe whose
 	// backup_target reads unknown/agent_backup_config_unavailable while the daemon's is resolved — and
 	// this one-shot exists precisely so "the report it would send" can be trusted to match.
@@ -1827,6 +2249,17 @@ func formatOrDash(t time.Time) string {
 	return t.UTC().Format(time.RFC3339)
 }
 
+// restoreSpaceFor builds the restore-test's space preflight (R-672): the production provider over the
+// Proxmox API + the privileged `lvs` metadata read, and the configured margin.
+func restoreSpaceFor(cfg config.Config, px *proxmox.Client, ops *storage.SudoHostOps) (reconcile.RestoreSpace, reconcile.SpacePolicy) {
+	factor, reserve := cfg.Backup.RestoreTestSpace()
+	p := &restorespace.Provider{API: px}
+	if ops != nil {
+		p.ThinMeta = ops.ThinPoolMetadata
+	}
+	return p, reconcile.SpacePolicy{Factor: factor, ReserveBytes: reserve}
+}
+
 func runSelftestRestoreTest(ctx context.Context, cfg config.Config, logger *slog.Logger, archive string) int {
 	if err := cfg.Validate(); err != nil {
 		fmt.Fprintln(os.Stderr, "selftest: proxmox not configured:", err)
@@ -1857,8 +2290,10 @@ func runSelftestRestoreTest(ctx context.Context, cfg config.Config, logger *slog
 		}
 	}
 	gate := reconcile.NewGate(nil, cfg.Hub.HostID, reconcile.SlogAudit{Logger: logger}, logger)
+	rtSpace, rtPolicy := restoreSpaceFor(cfg, px, newHostOps(cfg, logger))
 	engine := reconcile.NewEngine(reconcile.EngineOptions{
 		API: px, Queue: queue, Journal: journal, Gate: gate, HostID: cfg.Hub.HostID, Logger: logger,
+		RestoreSpace: rtSpace, SpacePolicy: rtPolicy,
 	})
 
 	fmt.Printf("=== felhom-agent %s selftest=restore-test ===\n", version)
@@ -1888,10 +2323,16 @@ func runSelftestRestoreTest(ctx context.Context, cfg config.Config, logger *slog
 		RestoreTaskTimeout: restoreTaskTimeout(cfg, rtTier),
 	})
 	printJSON("restore-test record", backup.ToHubRestoreTest(res, time.Now().UTC()))
+	if res.Skipped && res.SkipReason != "" {
+		fmt.Printf("  space preflight: storage=%s required=%d avail=%d\n", res.TargetStorage, res.RequiredBytes, res.AvailBytes)
+		fmt.Printf("=== selftest=restore-test SKIPPED — %s ===\n", res.SkipReason)
+		return 4
+	}
 	if res.Skipped {
 		fmt.Println("=== selftest=restore-test SKIPPED (no free scratch VMID in band) ===")
 		return 0
 	}
+	fmt.Printf("  space preflight passed: storage=%s required=%d avail=%d\n", res.TargetStorage, res.RequiredBytes, res.AvailBytes)
 	if res.Err != nil || !res.Pass {
 		fmt.Fprintf(os.Stderr, "  [FAIL] restore-test (scratch %d): %v\n", res.ScratchVMID, res.Err)
 		return 1
@@ -2541,7 +2982,28 @@ func runSelftestIdentityConsume(ctx context.Context, cfg config.Config, logger *
 		fmt.Fprintln(os.Stderr, "  [FAIL] writing recovered bundle:", err)
 		return 1
 	}
-	fmt.Printf("  [OK] identity recovered (tunnel_token + pbs_token) → %s (0600) — never printed\n", keyDest)
+	// R-199 / §8.6: this line used to read "(tunnel_token + pbs_token)" — an enumeration that was
+	// accurate when it was written (pre-fork-4) and became a MISSTATEMENT the moment v0.77.0 sealed the
+	// offsite repository password into the same bundle. Anyone reading the old output would conclude the
+	// repository password was not there, and that is part of how the chain's extraction link came to be
+	// described as missing for a month. Name what was recovered from THIS bundle, and name what is
+	// absent, rather than reciting a fixed list.
+	recovered := []string{"tunnel_token", "pbs_token"}
+	var absent []string
+	if bundle.WGPrivateKey != "" {
+		recovered = append(recovered, "wg_private_key")
+	} else {
+		absent = append(absent, "wg_private_key")
+	}
+	if bundle.ResticRepoPassword != "" {
+		recovered = append(recovered, "restic_repo_password")
+	} else {
+		absent = append(absent, "restic_repo_password (pre-fork-4 blob — the field did not exist when this was sealed)")
+	}
+	fmt.Printf("  [OK] identity recovered (%s) → %s (0600) — values never printed\n", strings.Join(recovered, " + "), keyDest)
+	if len(absent) > 0 {
+		fmt.Printf("  [NOTE] fields ABSENT from this bundle: %s\n", strings.Join(absent, "; "))
+	}
 
 	// S5 DR: install the recovered WG private key so the tunnel re-establishes with the SAME
 	// identity/pubkey (→ the same hub /32), no fresh keygen. Create-only (refuses to overwrite a
@@ -3034,8 +3496,126 @@ func (f *selftestFlag) Set(v string) error {
 		f.mode = "identity-consume"
 	case "controller-swap":
 		f.mode = "controller-swap"
+	case "os-update":
+		f.mode = "os-update"
+	case "wgtunnel": // dispatched since S3 but refused here until 2026-10-04 (TestSelftestFlag_AcceptsEveryDispatchedMode)
+		f.mode = "wgtunnel"
 	default:
-		return fmt.Errorf("invalid --selftest value %q (want read|task|hub|storage|backup|restore-test|restore-test-due|pbs-verify|bring-up|provision|escrow-create|escrow-consume|identity-consume|controller-swap)", v)
+		return fmt.Errorf("invalid --selftest value %q (want read|task|hub|storage|backup|restore-test|restore-test-due|pbs-verify|lanresolver|wgtunnel|bring-up|provision|escrow-create|escrow-consume|identity-consume|controller-swap|os-update)", v)
 	}
 	return nil
 }
+
+// newOSLeg builds the OS-update leg (agent v0.140.0). The wrapper runs through sudo (FELHOM_OSAPPLY); the plan and
+// the once-per-night marker live in the agent's own os/ dir.
+func newOSLeg(cfg config.Config, client *hub.Client, px *proxmox.Client, logger *slog.Logger) *osupdate.Leg {
+	mode := proxmox.RunnerMode(cfg.Privileged.Mode)
+	if mode == "" {
+		mode = proxmox.RunnerSudo
+	}
+	l := &osupdate.Leg{
+		Runner:    &proxmox.ExecRunner{Mode: mode, SudoPath: cfg.Privileged.SudoPath},
+		Logger:    logger,
+		PlanDir:   osupdate.DefaultPlanDir,
+		StatePath: filepath.Join(osupdate.DefaultPlanDir, "last-night-run"),
+		// The host step (agent v0.141.0) runs only on an appliance install; the wrapper re-checks the ROOT-owned record.
+		Appliance: cfg.IsAppliance(),
+		Tunnel:    newTunnelProber(cfg, px),
+	}
+	if client != nil {
+		l.Hub = client
+	}
+	return l
+}
+
+// runSelftestOSUpdate is the OS leg's DEBUG ACTION (agent v0.140.0): one pass for -vmid, now, exactly as the night
+// runs it after a backup — the hub's os_update block (fetched fresh), the wrapper via sudo, the health wait, the
+// report to the hub — with trigger "debug" (never throttled, and it does NOT count as a night run for approval).
+// Run it as the agent user:  sudo -u felhom-agent felhom-agent --config … --selftest=os-update -vmid 9201
+func runSelftestOSUpdate(ctx context.Context, cfg config.Config, logger *slog.Logger, vmid int) int {
+	if vmid <= 0 {
+		fmt.Fprintln(os.Stderr, "selftest=os-update: -vmid is required")
+		return 2
+	}
+	client, err := hub.NewClient(cfg.Hub, logger)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "selftest=os-update: hub client:", err)
+		return 1
+	}
+	px, perr := newProxmoxClient(cfg)
+	if perr != nil {
+		fmt.Fprintln(os.Stderr, "selftest=os-update: proxmox client:", perr)
+		return 1
+	}
+	leg := newOSLeg(cfg, client, px, logger)
+	resp, err := client.FetchDesiredState(ctx)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "selftest=os-update: desired state:", err)
+		return 1
+	}
+	leg.SetBlock(resp.DesiredState.OSUpdate)
+	b := leg.Block()
+	fmt.Printf("=== felhom-agent %s selftest=os-update vmid=%d ring=%d enabled=%v guest-release=%v host-release=%v appliance=%v ===\n",
+		version, vmid, b.Ring, b.Enabled, b.Release != nil, b.HostRelease != nil, leg.Appliance)
+	start := time.Now()
+	g, h := leg.Run(ctx, vmid, "debug")
+	for _, rep := range []osupdate.Report{g, h} {
+		if rep.Layer == "" {
+			fmt.Println("  host step: skipped (see the log line above)")
+			continue
+		}
+		printJSON("os-update report ("+rep.Layer+")", map[string]any{"run_id": rep.RunID, "ring": rep.Ring, "release_id": rep.ReleaseID,
+			"mode": rep.Mode, "outcome": rep.Outcome, "healthy": rep.Healthy, "health_reason": rep.HealthReason,
+			"upgraded": rep.Upgraded, "pending": len(rep.Pending), "not_covered": rep.NotCovered,
+			"restart_needed": rep.RestartNeeded, "reboot_needed": rep.RebootNeeded, "wrapper_seconds": rep.PassSeconds, "refused": rep.Refused})
+	}
+	fmt.Printf("  pass took %s\n", time.Since(start).Round(100*time.Millisecond))
+	rep := g
+	if h.Layer != "" && !(h.Outcome == "applied" || h.Outcome == "nothing" || h.Outcome == "inventory") {
+		rep = h
+	}
+	switch rep.Outcome {
+	case "applied", "nothing", "inventory", "skipped":
+		return 0
+	}
+	return 1
+}
+
+// newTunnelProber reads the box's REAL tunnel (R-841, agent v0.141.0): the cloudflared container in each running
+// customer guest — a guest that binds /mnt/felhom-drives, the same rule the OS wrapper's R10 uses — through the
+// existing `pct exec [0-9]* -- docker inspect -f *` sudoers line.
+func newTunnelProber(cfg config.Config, px *proxmox.Client) hub.CloudflaredProber {
+	mode := proxmox.RunnerMode(cfg.Privileged.Mode)
+	if mode == "" {
+		mode = proxmox.RunnerSudo
+	}
+	return hub.GuestTunnelProber{
+		Runner: &proxmox.ExecRunner{Mode: mode, SudoPath: cfg.Privileged.SudoPath},
+		Guests: func(ctx context.Context) ([]int, error) {
+			if px == nil {
+				return nil, fmt.Errorf("no proxmox client")
+			}
+			gs, err := px.ListLXC(ctx)
+			if err != nil {
+				return nil, err
+			}
+			var out []int
+			for _, g := range gs {
+				if g.Status != "running" {
+					continue
+				}
+				gc, err := px.GuestConfig(ctx, g.VMID)
+				if err != nil {
+					continue
+				}
+				for _, v := range gc.MountPoints() {
+					if src, _, _ := strings.Cut(v, ","); src == "/mnt/felhom-drives" {
+						out = append(out, g.VMID)
+						break
+					}
+				}
+			}
+			return out, nil
+		},
+	}
+}

cmd/felhom-agent/restoretest_due_wiring_test.go

@@ -111,3 +111,46 @@ func parseMainForWiring(t *testing.T) *ast.File {
 	}
 	return f
 }
+
+// R-189 Scenario I — the DURABLE proof source must actually be wired into the collector.
+//
+// This test exists because the method it feeds is the project's own cautionary tale:
+// `RestoreTestState.Snapshot` carried the doc comment "for the host-report gauge" from the day it
+// was written and **had no caller at all** — a seam built, documented and never connected, found
+// only when a live restore-test's PASS reached no host-report. The fix must not become the next
+// instance, so the wiring is asserted rather than trusted.
+//
+// AST, not grep: a commented-out call still contains the string (proven yesterday, when commenting
+// out the tier-picker line failed this test while a `strings.Contains` check would have passed).
+func TestMainWiresTheDurableRestoreTestProof(t *testing.T) {
+	f := parseMainForWiring(t)
+
+	var wired, feedsState bool
+	ast.Inspect(f, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "SetProvenRestoreTests" {
+			return true
+		}
+		wired = true
+		// ...and it must be fed the PERSISTED state, not the in-memory store.
+		if len(call.Args) == 1 {
+			if id, ok := call.Args[0].(*ast.Ident); ok && id.Name == "rtState" {
+				feedsState = true
+			}
+		}
+		return true
+	})
+
+	if !wired {
+		t.Error("main.go never calls collector.SetProvenRestoreTests — the persisted proof would never " +
+			"reach the hub, which is the R-189 defect exactly: a passing restore-test that vanishes on restart")
+	}
+	if wired && !feedsState {
+		t.Error("collector.SetProvenRestoreTests is not fed rtState — the in-memory store is the thing " +
+			"that does NOT survive a restart, so wiring it here would fix nothing")
+	}
+}

cmd/felhom-agent/selftest_flag_test.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// Every mode the dispatcher (`switch selftest.mode`) runs must be ACCEPTED by the --selftest flag. Found live
+// 2026-10-04: --selftest=os-update had a dispatch case and a function but the flag's allow-list refused it, so the
+// debug action could not run. Red-proof: drop the "os-update" case from selftestFlag.Set and this fails.
+func TestSelftestFlag_AcceptsEveryDispatchedMode(t *testing.T) {
+	src, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(src)
+	i := strings.Index(s, "switch selftest.mode {")
+	if i < 0 {
+		t.Fatal("dispatch switch not found")
+	}
+	block := s[i:]
+	block = block[:strings.Index(block, "\n\t}\n")]
+	modes := regexp.MustCompile(`(?m)^\tcase "([a-z-]+)":`).FindAllStringSubmatch(block, -1)
+	if len(modes) < 5 {
+		t.Fatalf("parsed only %d dispatch cases — the parser is wrong", len(modes))
+	}
+	var bad []string
+	for _, m := range modes {
+		var f selftestFlag
+		if err := f.Set(m[1]); err != nil {
+			bad = append(bad, m[1])
+		}
+	}
+	if len(bad) > 0 {
+		t.Fatalf("dispatched but refused by --selftest: %v", bad)
+	}
+}

cmd/felhom-agent/storegrant_test.go

@@ -0,0 +1,417 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"go/ast"
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/capability"
+)
+
+// R-185 — a tier the box cannot READ must say so.
+//
+// THE OBSERVATION (demo-felhom, 2026-08-03, reproduced at the start of this session): root lists
+// three archives on `felhom-backup`; the agent's own token gets `{"data":[]}` from the same
+// endpoint; and `local`, which has the grant, lists through that same token. The token is the
+// variable, not the storage.
+//
+// The defect is NOT the missing grant — that is one command. It is that an empty content listing is
+// what a FORBIDDEN tier and a NEWBORN tier both return, so the box could not tell them apart and
+// said nothing. These tests pin the distinction.
+
+// permAnswer is the shape /access/permissions really returns, taken from the live measurement:
+// an UNGRANTED path answers with the privileges inherited from the box-wide grant — NOT empty, and
+// NOT a 403.
+var (
+	permGranted   = map[string]int{"Datastore.Allocate": 1, "Datastore.AllocateSpace": 1}
+	permUngranted = map[string]int{"Sys.Audit": 1, "SDN.Use": 1, "Datastore.Audit": 1}
+)
+
+// probeWith calls the PRODUCTION decision with a permissions answer. **Naming the seam:** everything
+// below is true up to `storeGrantVerdict`; that the live call feeds it the real API answer is what
+// Part 0's measurement established and what the live run on the box demonstrates. An earlier draft
+// of this file re-implemented the branch here — it passed, and would have kept passing while
+// production diverged, which is the hollow shape this project keeps catching in its own tests.
+func probeWith(privs map[string]int, targetID string, critical bool) capability.Status {
+	return storeGrantVerdict(targetID, critical, privs, nil)
+}
+
+// ── SCENARIO A — a forbidden storage is REPORTED, not passed over ────────────────────────────
+//
+// COMPANION RED-PROOF (observed 2026-08-03): delete the store-grant probes from `probeAll` in
+// main.go — i.e. restore `append(capProber.Probe(ctx), poolReadStatus(ctx, px))` — and
+// TestMainWiresTheStoreGrantProbe fails with "main.go never calls storeGrantStatuses". That is
+// today's behaviour on the live box: complete silence about a tier it cannot read.
+func TestStoreGrant_ForbiddenStorageIsDegradedAndNamed(t *testing.T) {
+	s := probeWith(permUngranted, "felhom-backup", true)
+
+	if s.Status != capability.StatusDegraded {
+		t.Fatalf("a storage the agent may not read must be DEGRADED, not %q — silence is the defect", s.Status)
+	}
+	if !s.Critical {
+		t.Fatal("it must be CRITICAL: the hub alerts only on critical, so a non-critical entry is the same silence with extra steps")
+	}
+	if !strings.Contains(s.Reason, "felhom-backup") {
+		t.Fatalf("the reason must NAME the storage — 'a grant is missing' costs a diagnosis at 07:00; got %q", s.Reason)
+	}
+	if !strings.Contains(s.Reason, "FelhomAgentStore") {
+		t.Fatalf("the reason must name the ROLE to grant, so the fix is in the alert; got %q", s.Reason)
+	}
+}
+
+// THE TRAP THE LIVE MEASUREMENT CAUGHT, pinned so it cannot be re-introduced: the ungranted answer
+// is not empty and not a 403 — it carries the INHERITED box-wide privileges. A probe that asked
+// "did the path come back?" or "does it have Datastore.Audit?" would report the blinded storage
+// healthy.
+func TestStoreGrant_InheritedPrivilegesAreNotAGrant(t *testing.T) {
+	if len(permUngranted) == 0 {
+		t.Fatal("fixture wrong: the ungranted answer is NOT empty — that is the whole trap")
+	}
+	if permUngranted["Datastore.Audit"] != 1 {
+		t.Fatal("fixture wrong: the ungranted path DOES carry Datastore.Audit, inherited box-wide")
+	}
+	if s := probeWith(permUngranted, "felhom-backup", true); s.Status != capability.StatusDegraded {
+		t.Fatalf("checking for the wrong privilege reports a blinded storage healthy; got %q", s.Status)
+	}
+	// ...and the privilege actually checked is the one whose absence was measured to blind listing.
+	if storeGrantRequiredPriv != "Datastore.AllocateSpace" {
+		t.Fatalf("the probed privilege changed to %q — re-measure before trusting it", storeGrantRequiredPriv)
+	}
+}
+
+// ── SCENARIO B — a newborn tier is still silent ──────────────────────────────────────────────
+//
+// A storage the agent IS allowed to read but which simply holds no archives yet is HEALTHY. The
+// probe must not look at content at all, or every freshly provisioned box alarms and the signal dies.
+//
+// COMPANION RED-PROOF (observed): make the probe degrade on an empty content listing instead of on
+// the permission — a granted-but-empty storage then reports degraded, i.e. every newborn box alarms.
+func TestStoreGrant_GrantedButEmptyIsHealthy(t *testing.T) {
+	s := probeWith(permGranted, "felhom-pbs", true)
+	if s.Status != capability.StatusOK {
+		t.Fatalf("a readable tier is healthy whether or not it holds archives yet; got %q (%s)", s.Status, s.Reason)
+	}
+	if s.Reason != "" {
+		t.Fatalf("a healthy probe carries no reason; got %q", s.Reason)
+	}
+}
+
+// ── SCENARIO C — the two states are distinguishable at a glance ──────────────────────────────
+func TestStoreGrant_ForbiddenAndNewbornAreDistinguishable(t *testing.T) {
+	forbidden := probeWith(permUngranted, "felhom-backup", true)
+	newborn := probeWith(permGranted, "felhom-pbs", true)
+
+	if forbidden.Status == newborn.Status {
+		t.Fatalf("the two states must differ — today both read as 'no settled archive yet'; got %q for both", forbidden.Status)
+	}
+	if forbidden.Name == newborn.Name {
+		t.Fatalf("each tier needs its own capability id, or one tier's fault hides another's; got %q twice", forbidden.Name)
+	}
+}
+
+// §8.3, weighed once and pinned: a box with NO dedicated target ("local" — host-install's own
+// DEGRADED fallback) must not turn an ordinary configuration into an operator page. It is still
+// probed and still reported; only the paging differs.
+func TestStoreGrant_TheFallbackTargetIsNotCritical(t *testing.T) {
+	if storeGrantCritical("local") {
+		t.Fatal("a box whose backup target is the 'local' fallback must not page the operator about " +
+			"an ordinary, documented configuration")
+	}
+	for _, dedicated := range []string{"felhom-backup", "felhom-pbs", "some-nvme"} {
+		if !storeGrantCritical(dedicated) {
+			t.Fatalf("a DEDICATED target that cannot be read is user-facing and must be critical; %q was not", dedicated)
+		}
+	}
+	// The fallback is still reported — silence for it would be the original defect, scoped smaller.
+	if s := probeWith(permUngranted, "local", storeGrantCritical("local")); s.Status != capability.StatusDegraded {
+		t.Fatalf("the fallback target must still report degraded when unreadable; got %q", s.Status)
+	}
+}
+
+// A probe that cannot ask must never answer "ok" — unknown reported as healthy is worse than no
+// probe, because it looks like coverage.
+func TestStoreGrant_UnreachablePVEIsDegradedNotOK(t *testing.T) {
+	s := storeGrantStatus(context.Background(), nil, "felhom-backup", true, nil)
+	if s.Status != capability.StatusDegraded {
+		t.Fatalf("an unaskable probe must be DEGRADED, never ok; got %q", s.Status)
+	}
+	if s.Reason == "" {
+		t.Fatal("it must say why it could not ask")
+	}
+}
+
+// ── SCENARIO H — the seam ────────────────────────────────────────────────────────────────────
+//
+// This project's "built but never wired" count reached six last week. The fix for a SILENCE must not
+// itself be silent. AST, not grep: a commented-out call still contains the string.
+func TestMainWiresTheStoreGrantProbe(t *testing.T) {
+	f := parseMainForWiring(t)
+
+	var wired bool
+	ast.Inspect(f, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		if id, ok := call.Fun.(*ast.Ident); ok && id.Name == "storeGrantStatuses" {
+			wired = true
+		}
+		return true
+	})
+	if !wired {
+		t.Error("main.go never calls storeGrantStatuses — the probe would exist and report to nobody, " +
+			"which is precisely the silence R-185 is about")
+	}
+}
+
+// ── R-190 — the grant repairs itself, and the repair is VISIBLE ──────────────────────────────
+//
+// R-190 is a storage grant that demonstrably worked at 04:44 on 2026-08-03 and was gone by 09:24,
+// with a host reinstall, logged `pveum` activity and cluster-log entries all ruled out. The cause is
+// open; the resilience is not conditional on it.
+//
+// The half that matters is the RECORD. R-190's own words: the probe sees the state, nothing sees the
+// transition. A self-repair that leaves only "ok" behind destroys the only evidence a loss happened,
+// so a recurring loss becomes undetectable forever — strictly worse than the fault it fixes.
+
+// fakeRepairRunner records wrapper invocations and can be made to fail.
+type fakeRepairRunner struct {
+	calls [][]string
+	fail  bool
+}
+
+func (f *fakeRepairRunner) Run(_ context.Context, name string, args ...string) ([]byte, []byte, error) {
+	f.calls = append(f.calls, append([]string{name}, args...))
+	if f.fail {
+		return nil, []byte("pveum: refused"), errors.New("exit status 2")
+	}
+	return nil, nil, nil
+}
+
+func newRepairer(f *fakeRepairRunner) *storeGrantRepairer {
+	return &storeGrantRepairer{run: f.Run, log: slog.New(slog.NewTextHandler(io.Discard, nil))}
+}
+
+// ── SCENARIO F — the repair is BOUNDED ───────────────────────────────────────────────────────
+//
+// COMPANION RED-PROOF (observed 2026-08-04): make mayAttempt always return true (drop the
+// storeGrantRepairMinInterval check) →
+//
+//	--- FAIL: TestGrantRepair_IsBounded
+//	    storegrant_test.go: a repair must not run on every cycle; 5 cycles produced 5 attempt(s)
+//
+// which is a re-grant every report cycle, forever, against a fault an ACL cannot fix. Restored.
+func TestGrantRepair_IsBounded(t *testing.T) {
+	f := &fakeRepairRunner{}
+	r := newRepairer(f)
+	// Jittered, so the series never lands exactly on the interval boundary — a perfectly regular
+	// series is how a threshold test passes its own mutation, which has happened here before.
+	base := time.Date(2026, 8, 4, 9, 17, 43, 0, time.UTC)
+	offsets := []time.Duration{0, 13*time.Minute + 7*time.Second, 27*time.Minute + 51*time.Second,
+		41*time.Minute + 19*time.Second, 55*time.Minute + 3*time.Second}
+	attempts := 0
+	for _, off := range offsets {
+		if r.mayAttempt("felhom-backup", base.Add(off)) {
+			attempts++
+		}
+	}
+	if attempts != 1 {
+		t.Fatalf("a repair must not run on every cycle; %d cycles produced %d attempt(s) within %s",
+			len(offsets), attempts, storeGrantRepairMinInterval)
+	}
+	// ...and once the interval has genuinely passed, it may try again — a bound is not a ban.
+	if !r.mayAttempt("felhom-backup", base.Add(storeGrantRepairMinInterval+2*time.Minute+11*time.Second)) {
+		t.Fatal("after the interval a repair must be allowed again — otherwise one failure disables the repair forever")
+	}
+	// A DIFFERENT tier is not throttled by this one's attempt.
+	if !r.mayAttempt("felhom-pbs", base.Add(time.Minute)) {
+		t.Fatal("the bound must be per tier — one tier's attempt must not suppress another's")
+	}
+}
+
+// A nil repairer (or one with no runner) never attempts, and never panics.
+func TestGrantRepair_NilIsSafe(t *testing.T) {
+	var r *storeGrantRepairer
+	if r.mayAttempt("felhom-backup", time.Now()) {
+		t.Fatal("a nil repairer must never claim an attempt")
+	}
+	if (&storeGrantRepairer{}).mayAttempt("felhom-backup", time.Now()) {
+		t.Fatal("a repairer with no runner must never claim an attempt")
+	}
+}
+
+// The repair calls the EXISTING wrapper verb, with the storage id — no new privileged surface.
+func TestGrantRepair_CallsTheExistingWrapperVerb(t *testing.T) {
+	f := &fakeRepairRunner{}
+	r := newRepairer(f)
+	if err := r.repair(context.Background(), "felhom-backup"); err != nil {
+		t.Fatalf("repair should succeed with a healthy runner: %v", err)
+	}
+	if len(f.calls) != 1 {
+		t.Fatalf("exactly one wrapper invocation expected; got %d", len(f.calls))
+	}
+	got := f.calls[0]
+	want := []string{"/usr/local/sbin/felhom-backup-target-apply", "grant", "felhom-backup"}
+	if len(got) != len(want) {
+		t.Fatalf("wrapper argv = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("wrapper argv = %v, want %v — the sudoers vector is `grant *`; anything else is a policy change", got, want)
+		}
+	}
+}
+
+// A repair that FAILS must surface the failure, not swallow it (Scenario E's precondition).
+func TestGrantRepair_FailureIsReturned(t *testing.T) {
+	f := &fakeRepairRunner{fail: true}
+	if err := newRepairer(f).repair(context.Background(), "felhom-backup"); err == nil {
+		t.Fatal("a failed wrapper run must return its error — a repair that cannot run must never read as done")
+	}
+}
+
+// ── SCENARIO D (the half that matters) — the REPAIR MUST BE VISIBLE ──────────────────────────
+//
+// A repair that leaves only "ok" behind is worse than the fault: the tier works, and the fact that a
+// permission vanished is gone with it. R-190 exists because nothing saw the transition.
+//
+// The channel is the hub's EXISTING ok→degraded→ok edge (§8.5) — nothing new was built. That only
+// works if the agent deliberately reports ONE degraded cycle after repairing, and if the explanation
+// rides the field the hub actually puts in the operator's e-mail. The hub's message is built from the
+// capability NAME and FEATURE (`internal/monitor/host_capability.go` emitTransition) — **not** from
+// Reason — so the Feature must carry it.
+//
+// COMPANION RED-PROOF (observed 2026-08-04): after a successful repair, report ok instead —
+//
+//	s.Status = capability.StatusOK; s.Feature unchanged
+//
+// →	--- FAIL: TestGrantRepair_ARepairedGrantIsReportedAsATransition
+//
+//	storegrant_test.go: a self-repair must still report DEGRADED for one cycle so the hub raises
+//	its edge; got "ok" — the loss would be invisible
+//
+// i.e. exactly the silence R-190 is about. Restored.
+func TestGrantRepair_ARepairedGrantIsReportedAsATransition(t *testing.T) {
+	// THE PRODUCTION verdict, not a copy of it. An earlier draft of this test built the Status
+	// itself and asserted its own construction — it would have passed while production reported ok,
+	// which is precisely the silence being guarded against.
+	if pre := probeWith(permUngranted, "felhom-backup", true); pre.Status != capability.StatusDegraded {
+		t.Fatalf("precondition: a missing grant is degraded; got %q", pre.Status)
+	}
+	s := storeGrantRepairedVerdict("felhom-backup", true)
+
+	if s.Status != capability.StatusDegraded {
+		t.Fatalf("a self-repair must still report DEGRADED for one cycle so the hub raises its edge; "+
+			"got %q — the loss would be invisible", s.Status)
+	}
+	// The hub e-mails the FEATURE text. If the explanation is not there, the operator is told a
+	// capability was degraded and never learns it repaired itself or that anything vanished.
+	for _, want := range []string{"MISSING", "RESTORED", "felhom-backup", "R-190"} {
+		if !strings.Contains(s.Feature, want) {
+			t.Fatalf("the Feature text is what the hub puts in the operator's e-mail; it must contain %q. Got: %s", want, s.Feature)
+		}
+	}
+	if !s.Critical {
+		t.Fatal("the transition must be CRITICAL or the hub does not alert on it at all")
+	}
+}
+
+// ── SCENARIO H — the seam ────────────────────────────────────────────────────────────────────
+//
+// The wrapper's `grant` verb is itself a "built but never wired" example: it exists, is
+// sudoers-permitted for any id, and had only ever been called at storage CREATION. The repair must
+// not become the seventh instance. AST, not grep — a commented-out call still contains the string.
+func TestMainWiresTheGrantRepair(t *testing.T) {
+	f := parseMainForWiring(t)
+
+	var built, passed bool
+	ast.Inspect(f, func(n ast.Node) bool {
+		switch node := n.(type) {
+		case *ast.CompositeLit:
+			if id, ok := node.Type.(*ast.Ident); ok && id.Name == "storeGrantRepairer" {
+				built = true
+			}
+		case *ast.CallExpr:
+			if id, ok := node.Fun.(*ast.Ident); ok && id.Name == "storeGrantStatuses" && len(node.Args) == 4 {
+				if a, ok := node.Args[3].(*ast.Ident); ok && a.Name == "grantRepairer" {
+					passed = true
+				}
+			}
+		}
+		return true
+	})
+	if !built {
+		t.Error("main.go never constructs a storeGrantRepairer — nothing would ever repair a lost grant")
+	}
+	if !passed {
+		t.Error("storeGrantStatuses is not passed the repairer — the probe would detect the loss and " +
+			"leave it, which is v0.123.0's behaviour and not R-190's mitigation")
+	}
+}
+
+// The transition must survive a probe that is NOT the one feeding the hub.
+//
+// MEASURED LIVE 2026-08-04, and this test exists because the first implementation failed it in
+// production while every unit test passed: `probeAll` is called independently by the self-check LOG
+// and by the collector building a host-report. The repairing call was the log's; the report three
+// seconds later found the grant present and reported `ok`. The agent's journal had the record and the
+// hub had nothing — the exact silence R-190 is about, re-created inside its own mitigation.
+//
+// COMPANION RED-PROOF (observed): delete the `recentlyRepaired` branch from the healthy path →
+//
+//	--- FAIL: TestGrantRepair_TransitionSurvivesALaterProbe
+//	    storegrant_test.go: a probe AFTER the repair must still report the transition; got "ok" —
+//	    the host-report would carry ok and the operator would never learn the grant vanished
+//
+// Restored.
+func TestGrantRepair_TransitionSurvivesALaterProbe(t *testing.T) {
+	r := newRepairer(&fakeRepairRunner{})
+	// Jittered, never landing on the window boundary.
+	repairedAt := time.Date(2026, 8, 4, 9, 39, 34, 0, time.UTC)
+	r.noteRepaired("felhom-backup", repairedAt)
+
+	// The DECISION a later probe makes — the production function, not the helper it calls. An
+	// earlier draft asserted `recentlyRepaired` directly and its red-proof PASSED, because removing
+	// the latch's USE left the helper untouched.
+	healthy := probeWith(permGranted, "felhom-backup", true)
+	if healthy.Status != capability.StatusOK {
+		t.Fatalf("precondition: a granted tier is ok; got %q", healthy.Status)
+	}
+	got := storeGrantHealthyVerdict("felhom-backup", true,
+		healthy, r.recentlyRepaired("felhom-backup", repairedAt.Add(3*time.Second)))
+	if got.Status != capability.StatusDegraded {
+		t.Fatalf("a probe AFTER the repair must still report the transition; got %q — the host-report "+
+			"would carry ok and the operator would never learn the grant vanished", got.Status)
+	}
+	if !strings.Contains(got.Feature, "RESTORED") {
+		t.Fatalf("the later probe must carry the explanation into the hub's e-mail; got: %s", got.Feature)
+	}
+	// Outside the window it reports plain ok again.
+	late := storeGrantHealthyVerdict("felhom-backup", true,
+		healthy, r.recentlyRepaired("felhom-backup", repairedAt.Add(storeGrantRepairReportWindow+time.Minute)))
+	if late.Status != capability.StatusOK {
+		t.Fatalf("outside the window a healthy tier reports ok; got %q — a permanent degraded state "+
+			"would be its own false alarm", late.Status)
+	}
+	if !r.recentlyRepaired("felhom-backup", repairedAt.Add(14*time.Minute+37*time.Second)) {
+		t.Fatal("the latch must outlast the 900s hub report interval, or the record never reaches the hub")
+	}
+	// ...and it clears on its own rather than latching a box degraded forever.
+	if r.recentlyRepaired("felhom-backup", repairedAt.Add(storeGrantRepairReportWindow+time.Minute+7*time.Second)) {
+		t.Fatal("the latch must clear — a permanent degraded state would be its own false alarm")
+	}
+	// It is per tier.
+	if r.recentlyRepaired("felhom-pbs", repairedAt.Add(time.Second)) {
+		t.Fatal("one tier's repair must not latch another tier's status")
+	}
+	// The window MUST exceed the report interval — the property, asserted rather than assumed.
+	if storeGrantRepairReportWindow <= 15*time.Minute {
+		t.Fatalf("the report window (%s) must exceed the 900s hub report interval, or a transition can "+
+			"be missed entirely", storeGrantRepairReportWindow)
+	}
+}

configs/build-golden.sh

@@ -289,7 +289,11 @@ mount --make-rshared /mnt
 # Otherwise still DE-PRIVILEGED: disk EXECUTION (scan/format/mount) stays the agent's — NO --privileged,
 # no /dev, no /etc/fstab. Bootstrap config (ro), data volume, stacks dir (same-path), the /mnt :rslave
 # view, and the docker socket. The controller reaches the agent's local API for disk management.
-docker run -d --name felhom-controller --restart unless-stopped "${HOSTNAME_ARGS[@]}" \
+# R-523: `always`, not `unless-stopped`. It covers ONE extra case only — a Docker daemon restart after
+# the container was stopped by hand. Neither policy restarts a container that `docker kill`/`docker
+# stop` ended (measured 2026-09-15, Docker 29.8.0, evidence-p1fixes-2026-09-15/A1); the host agent's
+# controller supervisor (felhom-agent v0.131.0, internal/localapi/controllersupervisor.go) covers that.
+docker run -d --name felhom-controller --restart always "${HOSTNAME_ARGS[@]}" \
   -e FELHOM_BOOTSTRAP_PATH=/etc/felhom-bootstrap/bootstrap.json \
   -v /etc/felhom-bootstrap:/etc/felhom-bootstrap:ro \
   -v felhom-controller-data:/opt/docker/felhom-controller \

configs/felhom-agent.sudoers

@@ -299,10 +299,17 @@ Cmnd_Alias FELHOM_SELFHEAL = \
 # argument after the numeric vmid is a literal, so the grant cannot be widened by anything the guest or
 # the hub says. The address read is deliberately NOT duplicated here — it is already FELHOM_DNSMASQ's,
 # and the same command must not be granted twice under two names.
+# OS updates, guest fast lane (`11-os-updates.md` §5.4.1, agent v0.140.0). The ONLY entry: the root wrapper with
+# one plan file in the agent's own os/ dir. Every safety rule (no removal, no downgrade, no new or unlisted package,
+# Debian origin only, the box's own customer guest only) lives in the wrapper, red-proved per rule
+# (configs/test_felhom_os_apply.py). The agent gets NO apt grant of its own.
+Cmnd_Alias FELHOM_OSAPPLY = \
+  /usr/local/sbin/felhom-os-apply --plan /var/lib/felhom-agent/os/plan-*.json
+
 Cmnd_Alias FELHOM_GUESTNET = \
   /usr/sbin/pct exec [0-9]* -- ip route show default, \
   /usr/sbin/pct exec [0-9]* -- cat /etc/network/interfaces, \
   /usr/sbin/pct exec [0-9]* -- pgrep -x dhclient, \
   /usr/sbin/pct exec [0-9]* -- dhclient -pf /run/dhclient.eth0.pid -lf /var/lib/dhcp/dhclient.eth0.leases eth0
 
-felhom-agent ALL=(root) NOPASSWD: FELHOM_MOUNT, FELHOM_DISK, FELHOM_PROVISION, FELHOM_FORMAT, FELHOM_DNSMASQ, FELHOM_GUESTHOOK, FELHOM_INTERMEDIARY, FELHOM_CONTROLLERSWAP, FELHOM_STALELOCK, FELHOM_NETMOUNT, FELHOM_WG, FELHOM_SELFUPDATE, FELHOM_SSHD, FELHOM_OOB, FELHOM_PBSDR, FELHOM_BACKUPTARGET, FELHOM_SELFHEAL, FELHOM_ESCROW, FELHOM_GUESTNET, FELHOM_SCRATCH_TEARDOWN
+felhom-agent ALL=(root) NOPASSWD: FELHOM_MOUNT, FELHOM_DISK, FELHOM_PROVISION, FELHOM_FORMAT, FELHOM_DNSMASQ, FELHOM_GUESTHOOK, FELHOM_INTERMEDIARY, FELHOM_CONTROLLERSWAP, FELHOM_STALELOCK, FELHOM_NETMOUNT, FELHOM_WG, FELHOM_SELFUPDATE, FELHOM_SSHD, FELHOM_OOB, FELHOM_PBSDR, FELHOM_BACKUPTARGET, FELHOM_SELFHEAL, FELHOM_ESCROW, FELHOM_GUESTNET, FELHOM_SCRATCH_TEARDOWN, FELHOM_OSAPPLY

configs/felhom-os-apply

@@ -0,0 +1,593 @@
+#!/usr/bin/python3
+# felhom-os-apply — the ROOT half of the agent's operating-system update leg (`11-os-updates.md` §5.4.1, §8.1–8.2).
+#
+# Install as /usr/local/sbin/felhom-os-apply (0755 root:root). The non-root agent invokes it via `sudo -n`
+# (FELHOM_OSAPPLY alias) with EXACTLY:   felhom-os-apply --plan /var/lib/felhom-agent/os/plan-<id>.json
+# Nothing else on the command line is accepted. Python 3, standard library only (a JSON plan cannot be parsed
+# safely in sh). Tests: configs/test_felhom_os_apply.py (a fake runner; nothing real is executed).
+#
+# THE TRUST MODEL. The plan is written by the agent, so a broken-into agent writes whatever plan it likes. The
+# protection is therefore what this file REFUSES, not where the plan came from: no removal, no downgrade, no new
+# package, no package outside the plan, only Debian origin in the fast lane, no kernel / boot package on the host,
+# only the box's own customer guest, and the host layer only on a box whose ROOT-OWNED install record says
+# "appliance" (a BYO host belongs to its owner, `11` §1). Package signatures stay Debian's: apt checks every Release
+# file, including the snapshot.debian.org fallback (decision 79). Nothing here is overridable from the environment.
+#
+# LAYERS (agent v0.141.0): "guest" (the customer LXC, entered with `pct exec`) and "host" (this Proxmox host, run
+# directly). LANE: "fast" only — the slow lane (kernel, Proxmox, Docker) is REFUSED (R3, R14) until `11` §8 steps 5–6.
+#
+# Modes (plan field "mode"):
+#   inventory   `apt-get update`, then report what is installed (with origin), what is pending, and health.
+#   apply       repair first, pick the packages (select "listed": the plan's name=version list; "pending-fast": every
+#               pending Debian / Debian-Security upgrade, for ring 0), check every refusal on an `apt-get -s`
+#               simulation of EXACTLY name=version, install, clean, scan for restart-needed, report as inventory.
+#   health      report health only (the agent polls it after a run).
+# Output: log lines on stderr and the journal (tag felhom-os-apply); the LAST stdout line is
+#   OSAPPLY-REPORT <one JSON object>
+# which is what the agent parses. Exit 0 = done; 2 = refused (nothing changed); 3 = failed during install.
+#
+# SPEED (R-845, agent v0.141.0). Every `pct exec` costs ~0.9 s (measured on demo-hp), and v0.140.0 made one per
+# package for version comparisons — 272 packages ≈ 4 minutes. Versions are now compared with the HOST's dpkg (the same
+# Debian algorithm), madison/policy run once per pass for all packages, the restart scan runs only after an install,
+# and one wrapper call does the whole pass (no separate inventory call before an apply).
+import json
+import os
+import re
+import stat
+import subprocess
+import sys
+import time
+
+PLAN_DIR = "/var/lib/felhom-agent/os"
+PLAN_RE = re.compile(r"^plan-[A-Za-z0-9._-]{1,80}\.json$")
+AGENT_USER = "felhom-agent"
+FAST_ORIGINS = ("Debian", "Debian-Security")
+# Debian package name and version grammar (Debian policy §5.6.1, §5.6.12).
+NAME_RE = re.compile(r"^[a-z0-9][a-z0-9+.-]+$")
+VERSION_RE = re.compile(r"^(?:[0-9]+:)?[0-9][A-Za-z0-9.+~-]*$")
+SNAP_RE = re.compile(r"^[0-9]{8}T[0-9]{6}Z$")
+RESERVED_VMIDS = set(range(990000, 990010)) | {9999}
+DRIVES_PARENT = "/mnt/felhom-drives"
+SNAPSHOT_LIST = "/etc/apt/sources.list.d/felhom-os-snapshot.list"
+APT_ENV = ["env", "DEBIAN_FRONTEND=noninteractive", "APT_LISTCHANGES_FRONTEND=none", "NEEDRESTART_MODE=l", "LC_ALL=C"]
+DPKG_OPTS = ["-o", "Dpkg::Options::=--force-confold", "-o", "Dpkg::Options::=--force-confdef"]
+MIN_FREE = 500 * 1024 * 1024
+# The installer's ROOT-OWNED record (felhom-host-install.sh `state_set mode`); the agent cannot write it.
+INSTALL_STATE = "/var/lib/felhom-install/state.json"
+# Kernel, boot and firmware packages are the SLOW lane on the host whatever their origin (`11` C3, §5.2): a host
+# reboot is needed for them to take effect, and a bad one can stop the box from booting.
+HOST_SLOW_RE = re.compile(r"^(linux-(image|headers|kbuild|modules|base)|proxmox-kernel|proxmox-default-kernel|pve-kernel|"
+                          r"pve-firmware|firmware-|grub|shim|systemd-boot|intel-microcode|amd64-microcode|efibootmgr)")
+# restart_needed() leaves out processes whose cgroup line matches (grep basic regex). Host: the LXC guests' own
+# processes (`0::/lxc/<vmid>/...`) -- NOT lxc-start itself, whose cgroup is `0::/lxc.monitor/<vmid>` (measured
+# 2026-10-04 on demo-felhom: the old pattern "lxc" hid lxc-start with 20 deleted maps, so "reboot needed" stayed false
+# after a libc6 update). Pinned by test_restart_skip_patterns_against_real_cgroups.
+RESTART_SKIP_CGROUP = {"guest": "docker", "host": ":/lxc/"}
+HOST_SERVICES = ["pveproxy", "pvedaemon", "pvestatd", "pve-cluster", "felhom-agent"]
+
+
+class Refused(Exception):
+    def __init__(self, code, reason):
+        super().__init__(f"{code} {reason}")
+        self.code, self.reason = code, reason
+
+
+class Runner:
+    """Runs commands for real. Tests replace it with a fake. `guest` runs inside the container via pct exec."""
+
+    def host(self, argv, timeout=600, stdin=None):
+        p = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, input=stdin)
+        return p.returncode, p.stdout, p.stderr
+
+    def guest(self, vmid, argv, timeout=1800):
+        return self.host(["/usr/sbin/pct", "exec", str(vmid), "--"] + argv, timeout)
+
+    def read_file(self, path):
+        with open(path) as f:
+            return f.read()
+
+    def stat(self, path):
+        return os.lstat(path)
+
+    def agent_uid(self):
+        import pwd
+        return pwd.getpwnam(AGENT_USER).pw_uid
+
+    def write_file(self, layer, vmid, path, body):
+        """Write a small text file in the target layer — never via a shell string."""
+        if layer == "host":
+            with open(path, "w") as f:
+                f.write(body)
+            return
+        rc, _, _ = self.host(["/usr/sbin/pct", "exec", str(vmid), "--", "tee", path], 60, stdin=body)
+        if rc != 0:
+            raise Refused("R7", f"could not write {path} in the guest")
+
+    def log(self, line):
+        print(line, file=sys.stderr, flush=True)
+        try:
+            subprocess.run(["logger", "-t", "felhom-os-apply", line], timeout=10)
+        except Exception:
+            pass
+
+
+class Apply:
+    def __init__(self, runner, plan_path):
+        self.r = runner
+        self.plan_path = plan_path
+        self.report = {"refused": None, "mode": None}
+
+    # ---------- checks ----------
+    def load_plan(self):
+        p = self.plan_path
+        d, base = os.path.dirname(p), os.path.basename(p)
+        if d != PLAN_DIR or not PLAN_RE.match(base) or ".." in p:
+            raise Refused("R1", f"the plan must be {PLAN_DIR}/plan-<id>.json, got {p!r}")
+        try:
+            st = self.r.stat(p)
+        except OSError as e:
+            raise Refused("R1", f"cannot stat the plan: {e}")
+        if not stat.S_ISREG(st.st_mode):
+            raise Refused("R1", "the plan is not a regular file (a symlink or a device is refused)")
+        if st.st_uid != self.r.agent_uid():
+            raise Refused("R1", f"the plan is not owned by {AGENT_USER}")
+        if st.st_size > 2 * 1024 * 1024:
+            raise Refused("R1", "the plan is larger than 2 MB")
+        try:
+            plan = json.loads(self.r.read_file(p))
+        except (OSError, ValueError) as e:
+            raise Refused("R1", f"the plan is not valid JSON: {e}")
+        if not isinstance(plan, dict):
+            raise Refused("R1", "the plan is not a JSON object")
+        return plan
+
+    def check_plan(self, plan):
+        mode = plan.get("mode", "apply")
+        if mode not in ("apply", "inventory", "health"):
+            raise Refused("R11", f"unknown mode {mode!r}")
+        layer = plan.get("layer")
+        if layer not in ("guest", "host"):
+            raise Refused("R12", f"layer {layer!r} is not guest or host")
+        if plan.get("lane", "fast") != "fast":
+            raise Refused("R3", "the slow lane is refused in this release")
+        vmid = plan.get("vmid")
+        if not isinstance(vmid, int) or isinstance(vmid, bool) or vmid <= 0:
+            raise Refused("R11", f"vmid must be a positive integer, got {vmid!r}")
+        rid = plan.get("release_id", "")
+        if not isinstance(rid, str) or not re.match(r"^[A-Za-z0-9._:-]{1,80}$", rid):
+            raise Refused("R11", f"release_id {rid!r} is not a plain id")
+        if plan.get("allow_new"):
+            raise Refused("R6", "allow_new is a slow-lane field; the fast lane never adds a package")
+        select = plan.get("select", "listed")
+        if select not in ("listed", "pending-fast"):
+            raise Refused("R11", f"unknown select {select!r}")
+        pk = plan.get("packages", [])
+        if not isinstance(pk, list):
+            raise Refused("R11", "packages must be a list")
+        if mode == "apply" and select == "listed" and not pk:
+            raise Refused("R11", "packages must be a non-empty list in apply mode (select listed)")
+        if select == "pending-fast" and pk:
+            raise Refused("R11", "select pending-fast takes no package list")
+        seen = set()
+        for e in pk:
+            if not isinstance(e, dict):
+                raise Refused("R11", "every package entry must be an object")
+            n, v, o = e.get("name"), e.get("version"), e.get("origin")
+            if not isinstance(n, str) or not NAME_RE.match(n):
+                raise Refused("R11", f"package name {n!r} is not a Debian package name")
+            if not isinstance(v, str) or not VERSION_RE.match(v):
+                raise Refused("R11", f"version {v!r} of {n} is not a Debian version string")
+            if n in seen:
+                raise Refused("R11", f"package {n} is named twice")
+            seen.add(n)
+            if o not in FAST_ORIGINS:
+                raise Refused("R2", f"{n}: origin {o!r} is not Debian / Debian-Security (the fast lane, `11` C3)")
+            if layer == "host" and HOST_SLOW_RE.match(n):
+                raise Refused("R14", f"{n} is a kernel / boot / firmware package — the host's slow lane")
+        snap = plan.get("snapshot", "")
+        if snap and not SNAP_RE.match(snap):
+            raise Refused("R11", f"snapshot {snap!r} is not YYYYMMDDTHHMMSSZ")
+        return mode, layer, vmid, select
+
+    def check_appliance(self):
+        """R12: the host layer only on a box whose ROOT-OWNED install record says appliance (`11` §1: never BYO)."""
+        try:
+            st = self.r.stat(INSTALL_STATE)
+        except OSError:
+            raise Refused("R12", f"no install record ({INSTALL_STATE}) — this box cannot prove it is an appliance")
+        if st.st_uid != 0 or (st.st_mode & 0o022):
+            raise Refused("R12", f"{INSTALL_STATE} is not root-owned and root-only-writable — it proves nothing")
+        try:
+            mode = json.loads(self.r.read_file(INSTALL_STATE)).get("mode")
+        except (OSError, ValueError, AttributeError):
+            raise Refused("R12", f"{INSTALL_STATE} is unreadable — this box cannot prove it is an appliance")
+        if mode != "appliance":
+            raise Refused("R12", f"this box was installed as {mode!r}, not appliance — its host belongs to its owner")
+
+    def check_guest(self, vmid):
+        if vmid in RESERVED_VMIDS:
+            raise Refused("R10", f"vmid {vmid} is a reserved scratch vmid")
+        try:
+            conf = self.r.read_file(f"/etc/pve/lxc/{vmid}.conf")
+        except OSError:
+            raise Refused("R10", f"vmid {vmid} is not a container on this host")
+        cur = conf.split("\n[", 1)[0]  # the current config, not a snapshot section
+        binds = [l for l in cur.splitlines() if re.match(r"^mp[0-9]+: " + re.escape(DRIVES_PARENT) + r",", l)]
+        if not binds:
+            raise Refused("R10", f"vmid {vmid} does not bind {DRIVES_PARENT} — it is not this box's customer guest")
+        lock = [l for l in cur.splitlines() if l.startswith("lock:")]
+        if lock:
+            raise Refused("R9", f"vmid {vmid} is locked ({lock[0].split(':', 1)[1].strip()}) — a backup or restore is running")
+        rc, out, _ = self.r.host(["/usr/sbin/pct", "status", str(vmid)])
+        if rc != 0 or "running" not in out:
+            raise Refused("R10", f"vmid {vmid} is not running")
+
+    # ---------- target helpers ----------
+    def x(self, argv, timeout=1800):
+        """Run in the TARGET layer: the guest via pct exec, or the host directly."""
+        if self.layer == "host":
+            return self.r.host(argv, timeout)
+        return self.r.guest(self.vmid, argv, timeout)
+
+    def g(self, argv, timeout=1800):
+        """Run in the customer GUEST whatever the layer (its health)."""
+        return self.r.guest(self.vmid, argv, timeout)
+
+    def dpkg_cmp(self, a, op, b):
+        # The HOST's dpkg: the same Debian version algorithm, and no `pct exec` (0.9 s) per comparison (R-845).
+        rc, _, _ = self.r.host(["dpkg", "--compare-versions", a, op, b], 30)
+        return rc == 0
+
+    def installed(self):
+        rc, out, _ = self.x(["dpkg-query", "-W", "-f", "${Package}\t${Version}\t${db:Status-Abbrev}\n"])
+        res = {}
+        for l in out.splitlines():
+            parts = l.split("\t")
+            if len(parts) == 3 and parts[2].startswith("ii"):
+                res[parts[0]] = parts[1]
+        return res
+
+    def madison_all(self, names):
+        """name -> set of downloadable versions, ONE call for all names."""
+        res = {n: set() for n in names}
+        if not names:
+            return res
+        rc, out, _ = self.x(["apt-cache", "madison"] + sorted(names))
+        for l in out.splitlines():
+            f = [x.strip() for x in l.split("|")]
+            if len(f) >= 3 and f[0] in res:
+                res[f[0]].add(f[1])
+        return res
+
+    def simulate(self, args):
+        rc, out, err = self.x(APT_ENV + ["apt-get", "-s", "-q"] + args)
+        inst, remv = [], []
+        for l in out.splitlines():
+            m = re.match(r"^Inst (\S+) (?:\[([^]]*)\] )?\((\S+) (.*?) \[[a-z0-9]+\]\)", l)
+            if m:
+                inst.append({"name": m.group(1), "from": m.group(2), "to": m.group(3), "origin": m.group(4)})
+            m = re.match(r"^Remv (\S+)", l)
+            if m:
+                remv.append(m.group(1))
+        return rc, inst, remv, out + err
+
+    @staticmethod
+    def origin_name(origin):
+        # "Debian:13.7/stable, Debian-Security:13/stable-security" -> {"Debian", "Debian-Security"}
+        return {o.strip().split(":")[0] for o in origin.split(",") if o.strip()}
+
+    def free_bytes(self):
+        rc, out, _ = self.x(["df", "-B1", "--output=avail", "/"])
+        try:
+            return int(out.strip().splitlines()[-1])
+        except (ValueError, IndexError):
+            return -1
+
+    def apt_lock_held(self):
+        rc, out, _ = self.x(["fuser", "/var/lib/dpkg/lock-frontend", "/var/lib/dpkg/lock"])
+        return rc == 0 and out.strip() != ""
+
+    def guest_health(self):
+        """The guest's signals: every container's state + health, the controller's own health, the network."""
+        rc, out, _ = self.g(["docker", "ps", "-a", "--format", "{{.Names}}\t{{.State}}\t{{.Status}}"], timeout=60)
+        cont = {}
+        for l in out.splitlines():
+            p = l.split("\t")
+            if len(p) == 3:
+                h = "healthy" if "(healthy)" in p[2] else "unhealthy" if "(unhealthy)" in p[2] else \
+                    "starting" if "(health: starting)" in p[2] else "none"
+                cont[p[0]] = {"state": p[1], "health": h}
+        nrc, _, _ = self.g(["getent", "hosts", "deb.debian.org"], timeout=30)
+        return {"docker_ok": rc == 0, "containers": cont,
+                "controller": cont.get("felhom-controller", {}).get("health", "absent"),
+                "network_ok": nrc == 0}
+
+    def health(self):
+        if self.layer == "guest":
+            return self.guest_health()
+        rc, out, _ = self.r.host(["systemctl", "is-active"] + HOST_SERVICES, 30)
+        states = out.split()
+        svc = {s: (states[i] if i < len(states) else "unknown") for i, s in enumerate(HOST_SERVICES)}
+        src, sout, _ = self.r.host(["/usr/sbin/pct", "status", str(self.vmid)], 30)
+        running = src == 0 and "running" in sout
+        return {"host_services": svc, "guest_running": running, "guest": self.guest_health() if running else None}
+
+    def restart_needed(self):
+        """Processes still mapping deleted files, OUTSIDE containers (C11). Guest: outside docker; host: outside the
+        LXC guests (the host's /proc shows guest processes too)."""
+        skip = RESTART_SKIP_CGROUP[self.layer]
+        script = ('for p in /proc/[0-9]*; do grep -q "(deleted)" $p/maps 2>/dev/null || continue; '
+                  'grep -q "%s" $p/cgroup 2>/dev/null && continue; echo "${p#/proc/} $(cat $p/comm 2>/dev/null)"; done' % skip)
+        rc, out, _ = self.x(["sh", "-c", script], timeout=120)
+        lines = [l for l in out.splitlines() if " " in l]
+        procs = sorted({l.split(" ", 1)[1] for l in lines})
+        pid1 = any(l.split(" ", 1)[0] == "1" for l in lines)
+        return procs, pid1 or "lxc-start" in procs
+
+    def inventory(self, inst=None):
+        inst = inst if inst is not None else self.installed()
+        names = sorted(inst)
+        origins = {}
+        if names:
+            rc, out, _ = self.x(["apt-cache", "policy"] + names)  # ONE call (R-845)
+            cur, star = None, False
+            for l in out.splitlines():
+                if not l.startswith(" "):
+                    cur, star = l.rstrip(":"), False
+                    continue
+                s = l.strip()
+                if s.startswith("*** "):
+                    star = True
+                    continue
+                if star and cur and re.match(r"^[0-9-]+ ", s):
+                    if "/var/lib/dpkg/status" in s:
+                        origins.setdefault(cur, "local")
+                    else:
+                        origins[cur] = s
+                    continue
+                if star and not re.match(r"^[0-9-]+ ", s):
+                    star = False
+
+        def oname(src):
+            if src in (None, "local"):
+                return "unknown"
+            if "proxmox" in src:
+                return "Proxmox"
+            if "security" in src and "debian" in src:
+                return "Debian-Security"
+            if "docker.com" in src:
+                return "Docker"
+            if "debian" in src:
+                return "Debian"
+            return "other"
+        rc, pend, remv, _ = self.simulate(["dist-upgrade"])
+        self._pending = pend
+        return {
+            "installed": [{"name": n, "version": inst[n], "origin": oname(origins.get(n))} for n in names],
+            "pending": [{"name": p["name"], "from": p["from"], "to": p["to"],
+                         "origin": sorted(self.origin_name(p["origin"]))} for p in pend],
+        }
+
+    # ---------- the run ----------
+    def run(self):
+        plan = self.load_plan()
+        self.mode, self.layer, self.vmid, self.select = self.check_plan(plan)
+        self.report.update(mode=self.mode, layer=self.layer, release_id=plan.get("release_id"), vmid=self.vmid)
+        if self.layer == "host":
+            self.check_appliance()
+        self.check_guest(self.vmid)
+        log = self.r.log
+        if self.mode == "health":
+            self.report["health"] = self.health()
+            return 0
+        log(f"os-apply: START release={plan.get('release_id')} layer={self.layer}" +
+            (f":{self.vmid}" if self.layer == "guest" else "") +
+            f" lane=fast mode={self.mode} select={self.select} packages={len(plan.get('packages', []))}")
+        if self.apt_lock_held():
+            raise Refused("R9", f"another apt/dpkg holds the lock on the {self.layer}")
+        self.report["health_before"] = self.health()
+        if self.mode == "apply":
+            self.repair()
+        rc, out, err = self.x(APT_ENV + ["apt-get", "-q", "update"], timeout=600)
+        if rc != 0:
+            raise Refused("R7", f"apt-get update failed on the {self.layer}: {(out + err).strip().splitlines()[-1:]}")
+        installed_after = None
+        if self.mode == "apply":
+            rc, installed_after = self.apply(plan)
+            if rc:
+                return rc
+        self.report.update(self.inventory(installed_after))
+        if self.layer == "host" and "reboot_needed" not in self.report:
+            # The host is scanned on EVERY pass (local, no pct exec): a reboot must CLEAR "reboot needed", or the hub's
+            # 14-day alarm fires on a host that was rebooted long ago. The guest still scans only after an install
+            # (R-845; one pct exec, and no alarm reads it). Pinned by test_host_scans_every_pass_guest_only_after_install.
+            self.report["restart_needed"], self.report["reboot_needed"] = self.restart_needed()
+        self.report["reboot_scanned"] = "reboot_needed" in self.report
+        self.report["health_after"] = self.health()
+        return 0
+
+    def repair(self):
+        rc, before, _ = self.x(["dpkg", "--audit"])
+        configured = len([l for l in before.splitlines() if l.startswith(" ")])
+        fixed = 0
+        after = ""
+        if before.strip():  # nothing half-done → nothing to run (R-845: two calls saved on every clean pass)
+            self.x(APT_ENV + ["dpkg", "--configure", "-a", "--force-confold"])
+            rc2, out, err = self.x(APT_ENV + ["apt-get", "-f", "install", "-y", "-q"] + DPKG_OPTS)
+            _, after, _ = self.x(["dpkg", "--audit"])
+            fixed = len(re.findall(r"^Setting up ", out, re.M))
+        self.report["repair"] = {"half_configured_before": configured, "fixed": fixed, "clean_after": after.strip() == ""}
+        self.r.log(f"os-apply: REPAIR configured={configured} fixed={fixed}")
+        if after.strip():
+            raise Refused("R13", "dpkg is still broken after the repair: " + after.strip().splitlines()[0])
+
+    def pending_fast(self):
+        """Ring 0 (select pending-fast): every pending upgrade of an INSTALLED package whose every origin is Debian /
+        Debian-Security — and, on the host, not a kernel / boot / firmware package."""
+        rc, pend, remv, _ = self.simulate(["dist-upgrade"])
+        out = []
+        for p in pend:
+            o = self.origin_name(p["origin"])
+            if p["from"] is None or not o or not o <= set(FAST_ORIGINS):
+                continue
+            if self.layer == "host" and HOST_SLOW_RE.match(p["name"]):
+                continue
+            out.append({"name": p["name"], "version": p["to"], "origin": "Debian-Security" if "Debian-Security" in o else "Debian"})
+        return out
+
+    def apply(self, plan):
+        log = self.r.log
+        packages = plan["packages"] if self.select == "listed" else self.pending_fast()
+        inst = self.installed()
+        upgrade, already, notinst = [], 0, 0
+        for e in packages:
+            n, v = e["name"], e["version"]
+            if n not in inst:
+                notinst += 1
+                continue
+            if not self.dpkg_cmp(v, "gt", inst[n]):
+                already += 1
+                continue
+            upgrade.append((n, v))
+        from_snap = 0
+        if upgrade:
+            avail = self.madison_all([n for n, _ in upgrade])
+            missing = [(n, v) for n, v in upgrade if v not in avail[n]]
+        else:
+            missing = []
+        if missing:
+            snap = plan.get("snapshot", "")
+            if not snap:
+                raise Refused("R7", f"{missing[0][0]}={missing[0][1]} is not downloadable and the plan names no snapshot")
+            self.add_snapshot_sources(snap)
+            avail = self.madison_all([n for n, _ in missing])
+            still = [(n, v) for n, v in missing if v not in avail[n]]
+            if still:
+                self.remove_snapshot_sources()
+                raise Refused("R7", f"{still[0][0]}={still[0][1]} is not downloadable, not even from snapshot {snap}")
+            from_snap = len(missing)
+        try:
+            log(f"os-apply: PLAN upgrade={len(upgrade)} already={already} not-installed={notinst} from-snapshot={from_snap}")
+            self.report["plan"] = {"upgrade": len(upgrade), "already": already, "not_installed": notinst, "from_snapshot": from_snap}
+            if not upgrade:
+                self.report["upgraded"] = []
+                log("os-apply: DONE rc=0 seconds=0 upgraded=0 (nothing to do)")
+                return 0, inst
+            args = ["install", "--only-upgrade", "--no-install-recommends"] + [f"{n}={v}" for n, v in upgrade]
+            rc, sim, remv, text = self.simulate(args)
+            if rc != 0:
+                tail = text.strip().splitlines()[-1] if text.strip() else ""
+                raise Refused("R7", "the simulation failed: " + tail)
+            if remv:
+                raise Refused("R4", f"the plan would remove {', '.join(remv[:5])}")
+            want = dict(upgrade)
+            for p in sim:
+                if p["from"] is None:
+                    raise Refused("R6", f"the plan would add a package that is not installed: {p['name']}")
+                if p["name"] not in want:
+                    raise Refused("R6", f"the plan would touch {p['name']}, which is not in the plan")
+                if p["to"] != want[p["name"]]:
+                    raise Refused("R6", f"{p['name']} would go to {p['to']}, not the approved {want[p['name']]}")
+                if not self.dpkg_cmp(p["to"], "gt", p["from"]):
+                    raise Refused("R5", f"{p['name']} would be downgraded {p['from']} -> {p['to']}")
+                if not self.origin_name(p["origin"]) & set(FAST_ORIGINS):
+                    raise Refused("R2", f"{p['name']} would come from {p['origin']}, not Debian")
+                if self.layer == "host" and HOST_SLOW_RE.match(p["name"]):
+                    raise Refused("R14", f"{p['name']} is a kernel / boot / firmware package — the host's slow lane")
+            need = self.download_bytes(args)
+            free = self.free_bytes()
+            if free >= 0 and free < max(MIN_FREE, 3 * need):
+                raise Refused("R8", f"free space {free} B is below max(500 MB, 3 x download {need} B)")
+            t0 = time.time()
+            rc, out, err = self.x(APT_ENV + ["apt-get", "-y", "-q"] + DPKG_OPTS + args)
+            secs = time.time() - t0
+            # dpkg says "Installing new version of config file X" when X was NOT changed locally (the package's new
+            # version is taken), and "Configuration file 'X'" + "Keeping old config file" when it was (--force-confold
+            # keeps the local one; the package's version lands as X.dpkg-dist). Measured live 2026-10-04 (debian_version).
+            conflict = None
+            for l in (out + err).splitlines():
+                m = re.search(r"Installing new version of config file (\S+?)\s*\.\.\.", l)
+                if m:
+                    log(f"os-apply: CONFFILE updated {m.group(1)} (it was not changed locally)")
+                m = re.search(r"Configuration file '([^']+)'", l)
+                if m:
+                    conflict = m.group(1)
+                if conflict and "Keeping old config file" in l:
+                    log(f"os-apply: CONFFILE kept {conflict} (changed locally; the package's version is {conflict}.dpkg-dist)")
+                    self.report.setdefault("conffiles_kept", []).append(conflict)
+                    conflict = None
+            self.x(["apt-get", "clean"])
+            if rc != 0:
+                _, aud, _ = self.x(["dpkg", "--audit"])
+                first = aud.strip().splitlines()[0] if aud.strip() else "clean"
+                log(f"os-apply: FAILED rc={rc} step=install — dpkg state: {first}")
+                self.report["failed"] = {"rc": rc, "dpkg_audit": first, "tail": (out + err).strip().splitlines()[-3:]}
+                return 3, None
+            self.report["upgraded"] = [{"name": n, "version": v} for n, v in upgrade]
+            self.report["seconds"] = round(secs, 1)
+            procs, reboot = self.restart_needed()  # only after an install (R-845)
+            self.report["restart_needed"] = procs
+            self.report["docker_restart_needed"] = any(p in ("dockerd", "containerd") for p in procs)
+            self.report["reboot_needed"] = reboot
+            log(f"os-apply: DONE rc=0 seconds={secs:.1f} upgraded={len(upgrade)} restart-needed={','.join(procs) or '-'} reboot-needed={'yes' if reboot else 'no'}")
+            return 0, None
+        finally:
+            if from_snap:
+                self.remove_snapshot_sources()
+
+    def download_bytes(self, args):
+        rc, out, _ = self.x(APT_ENV + ["apt-get", "-s", "-o", "Debug::NoLocking=1", "--print-uris", "-q"] + args)
+        total = 0
+        for l in out.splitlines():
+            m = re.match(r"^'[^']+' \S+ ([0-9]+) ", l)
+            if m:
+                total += int(m.group(1))
+        return total
+
+    def add_snapshot_sources(self, snap):
+        rc, out, _ = self.x(["sh", "-c", ". /etc/os-release && echo $VERSION_CODENAME"])
+        code = out.strip()
+        if not re.match(r"^[a-z]+$", code):
+            raise Refused("R7", f"cannot read the {self.layer}'s Debian codename ({code!r})")
+        body = (f"deb [check-valid-until=no] http://snapshot.debian.org/archive/debian/{snap} {code} main\n"
+                f"deb [check-valid-until=no] http://snapshot.debian.org/archive/debian-security/{snap} {code}-security main\n")
+        self.r.write_file(self.layer, self.vmid, SNAPSHOT_LIST, body)
+        self.r.log(f"os-apply: SNAPSHOT using snapshot.debian.org/{snap} for versions no longer published (decision 79)")
+        rc, out, err = self.x(APT_ENV + ["apt-get", "-q", "update"], timeout=600)
+        if rc != 0:
+            self.remove_snapshot_sources()
+            raise Refused("R7", "apt-get update against snapshot.debian.org failed")
+
+    def remove_snapshot_sources(self):
+        self.x(["rm", "-f", SNAPSHOT_LIST])
+        self.x(APT_ENV + ["apt-get", "-q", "update"], timeout=600)
+
+
+def main(argv, runner=None):
+    r = runner or Runner()
+    if len(argv) != 3 or argv[1] != "--plan":
+        r.log("os-apply: REFUSED: R1 usage: felhom-os-apply --plan /var/lib/felhom-agent/os/plan-<id>.json")
+        print("OSAPPLY-REPORT " + json.dumps({"refused": {"code": "R1", "reason": "usage"}}))
+        return 2
+    a = Apply(r, argv[2])
+    t0 = time.time()
+    try:
+        rc = a.run()
+    except Refused as e:
+        r.log(f"os-apply: REFUSED: {e.code} {e.reason}")
+        a.report["refused"] = {"code": e.code, "reason": e.reason}
+        rc = 2
+    except subprocess.TimeoutExpired as e:
+        r.log(f"os-apply: FAILED rc=124 step=timeout — {e.cmd}")
+        a.report["failed"] = {"rc": 124, "timeout": str(e.cmd)[:200]}
+        rc = 3
+    a.report["pass_seconds"] = round(time.time() - t0, 1)
+    print("OSAPPLY-REPORT " + json.dumps(a.report, sort_keys=True))
+    return rc
+
+
+if __name__ == "__main__":
+    if os.geteuid() != 0:
+        print("felhom-os-apply: must run as root (via sudo)", file=sys.stderr)
+        sys.exit(2)
+    sys.exit(main(sys.argv))

configs/test_felhom_os_apply.py

@@ -0,0 +1,628 @@
+#!/usr/bin/env python3
+"""Tests for configs/felhom-os-apply (`11` §5.4.1). A fake runner plays the host and the guest: nothing is executed
+for real except the local `dpkg --compare-versions` (pure, no network). Every refusal R1–R13 has a test; the red-proof
+(each test fails when its rule is removed) is `audits/os-guest-lane-2026-10-04/partB/redproof.txt`.
+
+Run: python3 configs/test_felhom_os_apply.py   (also run by internal/osupdate's Go test)
+"""
+import importlib.machinery
+import importlib.util
+import json
+import os
+import pathlib
+import re
+import stat as statmod
+import subprocess
+import unittest
+
+HERE = pathlib.Path(__file__).resolve().parent
+_loader = importlib.machinery.SourceFileLoader("osapply", os.environ.get("OSAPPLY_UNDER_TEST", str(HERE / "felhom-os-apply")))  # red-proof seam
+_spec = importlib.util.spec_from_loader("osapply", _loader)
+osapply = importlib.util.module_from_spec(_spec)
+_loader.exec_module(osapply)
+
+PLAN = "/var/lib/felhom-agent/os/plan-t1.json"
+CONF_OK = ("arch: amd64\nmp0: local-lvm:vm-9201-disk-1,mp=/var/lib/felhom,backup=1,size=70G\n"
+           "mp8: /mnt/felhom-drives,mp=/mnt/felhom-drives\nrootfs: local-lvm:vm-9201-disk-0,size=32G\n")
+DEB = "Debian:13.7/stable"
+SEC = "Debian-Security:13/stable-security"
+
+
+def dpkg_cmp(a, op, b):
+    return subprocess.run(["dpkg", "--compare-versions", a, op, b]).returncode == 0
+
+
+class St:
+    def __init__(self, mode=statmod.S_IFREG | 0o600, uid=999, size=100):
+        self.st_mode, self.st_uid, self.st_size = mode, uid, size
+
+
+class Fake:
+    """The host + one guest. `installed` / `live` (name -> versions in the live archive) / `snapshot` (versions
+    the snapshot archive adds) / `extra_sim` (lines the simulation adds) / `dpkg_audit` / `free`."""
+
+    def __init__(self):
+        self.plan = {"release_id": "os-t1", "layer": "guest", "lane": "fast", "vmid": 9201, "mode": "apply",
+                     "snapshot": "20261004T080000Z",
+                     "packages": [{"name": "libc6", "version": "2.41-12+deb13u4", "origin": "Debian"},
+                                  {"name": "openssl", "version": "3.5.7-1~deb13u3", "origin": "Debian-Security"}]}
+        self.files = {"/etc/pve/lxc/9201.conf": CONF_OK}
+        self.stats = {PLAN: St()}
+        self.installed = {"libc6": "2.41-12+deb13u3", "openssl": "3.5.6-1~deb13u1", "bash": "5.2.37-2+b9"}
+        self.live = {"libc6": {"2.41-12+deb13u4"}, "openssl": {"3.5.7-1~deb13u3"}}
+        self.snapshot = {}
+        self.snap_active = False
+        self.extra_sim = []
+        self.dpkg_audit = ""
+        self.free = 10 * 1024 ** 3
+        self.install_rc = 0
+        self.calls = []
+        self.logs = []
+        self.written = {}
+        self.status = "status: running"
+        self.lock_held = False
+        self.services = {}
+        self.files[osapply.INSTALL_STATE] = json.dumps({"mode": "appliance"})
+        self.stats[osapply.INSTALL_STATE] = St(mode=statmod.S_IFREG | 0o644, uid=0)
+
+    # Runner interface
+    def read_file(self, p):
+        if p == PLAN:
+            return json.dumps(self.plan)
+        if p not in self.files:
+            raise OSError("no such file")
+        return self.files[p]
+
+    def stat(self, p):
+        if p not in self.stats:
+            raise OSError("no such file")
+        return self.stats[p]
+
+    def agent_uid(self):
+        return 999
+
+    def log(self, line):
+        self.logs.append(line)
+
+    def host(self, argv, timeout=600, stdin=None):
+        self.calls.append(("host", argv))
+        if argv[0] == "/usr/sbin/pct" and argv[1] == "status":
+            return 0, self.status + "\n", ""
+        if argv[0] == "dpkg" and argv[1] == "--compare-versions":
+            return (0 if dpkg_cmp(argv[2], argv[3], argv[4]) else 1), "", ""
+        if argv[0] == "systemctl" and argv[1] == "is-active":
+            return 0, "\n".join(self.services.get(s, "active") for s in argv[2:]) + "\n", ""
+        return self.emulate(argv)
+
+    def write_file(self, layer, vmid, path, body):
+        self.written[path] = body
+        self.write_layer = layer
+        if path == osapply.SNAPSHOT_LIST:
+            self.snap_active = True
+
+    def avail(self, n):
+        v = set(self.live.get(n, set()))
+        if self.snap_active:
+            v |= self.snapshot.get(n, set())
+        return v
+
+    def guest(self, vmid, argv, timeout=1800):
+        self.calls.append(("guest", vmid, argv))
+        return self.emulate(argv)
+
+    def emulate(self, argv):
+        a = [x for x in argv if not re.match(r"^[A-Z_]+=", x) and x != "env"]
+        cmd = a[0]
+        if cmd == "dpkg-query":
+            return 0, "".join(f"{n}\t{v}\tii \n" for n, v in self.installed.items()), ""
+        if cmd == "dpkg" and a[1] == "--compare-versions":
+            return (0 if dpkg_cmp(a[2], a[3], a[4]) else 1), "", ""
+        if cmd == "dpkg" and a[1] == "--audit":
+            return 0, self.dpkg_audit, ""
+        if cmd == "dpkg" and a[1] == "--configure":
+            return 0, "", ""
+        if cmd == "fuser":
+            return (0, " 123", "") if self.lock_held else (1, "", "")
+        if cmd == "apt-cache" and a[1] == "madison":
+            self.madison_calls = getattr(self, "madison_calls", 0) + 1
+            return 0, "".join(f" {n} | {v} | http://deb.debian.org trixie/main amd64 Packages\n" for n in a[2:] for v in self.avail(n)), ""
+        if cmd == "apt-cache" and a[1] == "policy":
+            out = ""
+            for n in a[2:]:
+                out += f"{n}:\n  Installed: {self.installed.get(n)}\n  Version table:\n *** {self.installed.get(n)} 500\n        500 http://deb.debian.org/debian trixie/main amd64 Packages\n"
+            return 0, out, ""
+        if cmd == "apt-get":
+            if "update" in a:
+                return 0, "", ""
+            if "clean" in a:
+                return 0, "", ""
+            if "-f" in a:
+                self.dpkg_audit = ""
+                return 0, "Setting up x (1) ...\n" if getattr(self, "repaired", False) else "", ""
+            if "-s" in a:
+                return self.sim(a)
+            if "install" in a:
+                if self.install_rc:
+                    return self.install_rc, "", "E: boom"
+                for x in a:
+                    if "=" in x and not x.startswith("-") and "::" not in x:
+                        n, v = x.split("=", 1)
+                        self.installed[n] = v
+                return 0, getattr(self, "install_out", "Setting up libc6 ...\n"), ""
+        if cmd == "df":
+            return 0, f"Avail\n{self.free}\n", ""
+        if cmd == "docker":
+            return 0, "felhom-controller\trunning\tUp 1 hour (healthy)\napp\trunning\tUp 1 hour (healthy)\n", ""
+        if cmd == "getent":
+            return 0, "1.2.3.4 deb.debian.org\n", ""
+        if cmd == "sh":
+            if "os-release" in a[2]:
+                return 0, "trixie\n", ""
+            if "(deleted)" in a[2]:
+                return 0, getattr(self, "restart_out", ""), ""
+            return 0, "", ""
+        if cmd == "rm":
+            self.snap_active = False
+            return 0, "", ""
+        return 1, "", f"unexpected guest call {a}"
+
+    def sim(self, a):
+        if "--print-uris" in a:
+            return 0, "'http://x/libc6.deb' libc6.deb 4000000 SHA256:x\n", ""
+        if "dist-upgrade" in a:
+            if getattr(self, "pending_sim", None) is not None and not getattr(self, "_pending_used", False):
+                self._pending_used = True
+                return 0, "\n".join(self.pending_sim) + "\n", ""
+            return 0, "Inst bash [5.2.37-2+b9] (5.2.37-2+b10 Debian:13.7/stable [amd64])\n", ""
+        out = ""
+        for x in a:
+            if "=" in x and not x.startswith("-") and "::" not in x:
+                n, v = x.split("=", 1)
+                if v not in self.avail(n):
+                    return 100, "", f"E: Version '{v}' for '{n}' was not found"
+                origin = SEC if n == "openssl" else DEB
+                out += f"Inst {n} [{self.installed[n]}] ({v} {origin} [amd64])\n"
+        out += "".join(l + "\n" for l in self.extra_sim)
+        return 0, out, ""
+
+
+def run(f):
+    import io
+    import contextlib
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        rc = osapply.main(["felhom-os-apply", "--plan", PLAN], runner=f)
+    line = [l for l in buf.getvalue().splitlines() if l.startswith("OSAPPLY-REPORT ")][-1]
+    return rc, json.loads(line[len("OSAPPLY-REPORT "):])
+
+
+class Happy(unittest.TestCase):
+    def test_apply_installs_exactly_the_plan(self):
+        f = Fake()
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(f.installed["libc6"], "2.41-12+deb13u4")
+        self.assertEqual(f.installed["openssl"], "3.5.7-1~deb13u3")
+        self.assertEqual(f.installed["bash"], "5.2.37-2+b9", "a package outside the plan was changed")
+        self.assertEqual(rep["plan"]["upgrade"], 2)
+        self.assertIn("installed", rep)
+        self.assertEqual(rep["pending"][0]["name"], "bash")
+        self.assertTrue(any(l.startswith("os-apply: REPAIR ") for l in f.logs), "the repair line must always print")
+        self.assertTrue(any(l.startswith("os-apply: DONE rc=0") for l in f.logs))
+        inst = [c for c in f.calls if c[0] == "guest" and "install" in c[2] and "-s" not in c[2] and "-f" not in c[2]]
+        self.assertTrue(inst and "Dpkg::Options::=--force-confold" in inst[0][2], "must keep existing config files")
+
+    def test_already_current_is_a_no_op(self):
+        f = Fake()
+        f.installed.update(libc6="2.41-12+deb13u4", openssl="3.5.7-1~deb13u3")
+        rc, rep = run(f)
+        self.assertEqual(rc, 0)
+        self.assertEqual(rep["plan"]["upgrade"], 0)
+
+    def test_inventory_installs_nothing(self):
+        f = Fake()
+        f.plan["mode"] = "inventory"
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(f.installed["libc6"], "2.41-12+deb13u3")
+        self.assertIn("installed", rep)
+        self.assertNotIn("restart_needed", rep, "the restart scan runs only after an install (R-845)")
+
+    def test_health_mode(self):
+        f = Fake()
+        f.plan["mode"] = "health"
+        rc, rep = run(f)
+        self.assertEqual(rc, 0)
+        self.assertEqual(rep["health"]["controller"], "healthy")
+
+
+class Repair(unittest.TestCase):
+    def test_repair_runs_first_and_is_reported(self):
+        f = Fake()
+        f.dpkg_audit = "The following packages have been unpacked but not yet configured.\n perl  Larry Wall's\n"
+        f.repaired = True
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(rep["repair"]["half_configured_before"], 1)
+        self.assertEqual(rep["repair"]["fixed"], 1)
+        order = [i for i, c in enumerate(f.calls) if c[0] == "guest" and c[2][-1:] != ["update"]]
+        first_cfg = next(i for i, c in enumerate(f.calls) if c[0] == "guest" and "--configure" in c[2])
+        first_upd = next(i for i, c in enumerate(f.calls) if c[0] == "guest" and "update" in c[2])
+        self.assertLess(first_cfg, first_upd, "the repair must run before anything else touches apt")
+        self.assertTrue(order)
+
+
+class Snapshot(unittest.TestCase):
+    def test_a_replaced_version_comes_from_the_snapshot(self):
+        f = Fake()
+        f.live["openssl"] = {"3.5.7-1~deb13u4"}  # Debian moved on
+        f.snapshot["openssl"] = {"3.5.7-1~deb13u3"}
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(rep["plan"]["from_snapshot"], 1)
+        self.assertEqual(f.installed["openssl"], "3.5.7-1~deb13u3", "must install the APPROVED version, not the newer one")
+        body = f.written[osapply.SNAPSHOT_LIST]
+        self.assertIn("snapshot.debian.org/archive/debian/20261004T080000Z trixie main", body)
+        self.assertIn("debian-security/20261004T080000Z trixie-security main", body)
+        self.assertFalse(f.snap_active, "the temporary snapshot sources must be removed after the run")
+
+    def test_snapshot_does_not_have_it_either(self):
+        f = Fake()
+        f.live["openssl"] = set()
+        rc, rep = run(f)
+        self.assertEqual((rc, rep["refused"]["code"]), (2, "R7"))
+        self.assertFalse(f.snap_active)
+
+
+class Refusals(unittest.TestCase):
+    def refused(self, f, code):
+        rc, rep = run(f)
+        self.assertEqual(rc, 2, rep)
+        self.assertEqual(rep["refused"]["code"], code, rep)
+        self.assertTrue(any(l.startswith(f"os-apply: REFUSED: {code} ") for l in f.logs), f.logs)
+        inst = [c for c in f.calls if c[0] == "guest" and "install" in c[2] and "-s" not in c[2] and "-f" not in c[2]]
+        self.assertEqual(inst, [], "a refusal must install nothing")
+        return rep
+
+    def test_R1_usage(self):
+        import io
+        import contextlib
+        f = Fake()
+        with contextlib.redirect_stdout(io.StringIO()):
+            self.assertEqual(osapply.main(["felhom-os-apply", "--plan", PLAN, "--extra"], runner=f), 2)
+            self.assertEqual(osapply.main(["felhom-os-apply", "--plan"], runner=f), 2)
+
+    def test_R1_path_outside_the_plan_dir(self):
+        import io
+        import contextlib
+        f = Fake()
+        with contextlib.redirect_stdout(io.StringIO()):
+            rc = osapply.main(["felhom-os-apply", "--plan", "/tmp/plan-x.json"], runner=f)
+        self.assertEqual(rc, 2)
+        self.assertTrue(any("R1" in l for l in f.logs))
+
+    def test_R1_symlink(self):
+        f = Fake()
+        f.stats[PLAN] = St(mode=statmod.S_IFLNK | 0o777)
+        self.refused(f, "R1")
+
+    def test_R1_not_owned_by_the_agent(self):
+        f = Fake()
+        f.stats[PLAN] = St(uid=0)
+        self.refused(f, "R1")
+
+    def test_R2_non_debian_origin_in_the_plan(self):
+        f = Fake()
+        f.plan["packages"][0]["origin"] = "Proxmox"
+        self.refused(f, "R2")
+
+    def test_R2_non_debian_origin_in_the_simulation(self):
+        f = Fake()
+        f.installed["libc6"] = "2.41-12+deb13u3"
+        orig = f.sim
+
+        def sim(a):
+            rc, out, err = orig(a)
+            return rc, out.replace("Debian:13.7/stable", "Proxmox Debian Repository:stable"), err
+        f.sim = sim
+        self.refused(f, "R2")
+
+    def test_R3_slow_lane(self):
+        f = Fake()
+        f.plan["lane"] = "slow"
+        self.refused(f, "R3")
+
+    def test_R4_removal(self):
+        f = Fake()
+        f.extra_sim = ["Remv bash [5.2.37-2+b9]"]
+        self.refused(f, "R4")
+
+    def test_R5_downgrade(self):
+        f = Fake()
+        f.installed["libc6"] = "2.41-12+deb13u4"
+        f.plan["packages"] = [{"name": "openssl", "version": "3.5.7-1~deb13u3", "origin": "Debian-Security"}]
+        f.extra_sim = ["Inst openssl [3.5.6-1~deb13u1] (3.5.5-1 Debian:13.7/stable [amd64])"]
+        orig = f.sim
+
+        def sim(a):  # the simulation answers with a LOWER version than installed
+            rc, out, err = orig(a)
+            return rc, "\n".join(l for l in out.splitlines() if not l.startswith("Inst openssl [3.5.6-1~deb13u1] (3.5.7")) + "\n", err
+        f.sim = sim
+        f.plan["packages"][0]["version"] = "3.5.7-1~deb13u3"
+        rep = run(f)[1]
+        # The plan asks 3.5.7; the simulation goes to 3.5.5: that is BOTH a wrong version (R6) and a downgrade.
+        self.assertIn(rep["refused"]["code"], ("R5", "R6"))
+
+    def test_R5_downgrade_exact(self):
+        f = Fake()
+        f.plan["packages"] = [{"name": "openssl", "version": "3.5.7-1~deb13u3", "origin": "Debian-Security"}]
+        f.installed["openssl"] = "3.5.6-1~deb13u1"
+        orig = f.sim
+
+        def sim(a):
+            rc, out, err = orig(a)
+            return rc, out.replace("[3.5.6-1~deb13u1]", "[3.5.8-1]"), err
+        f.sim = sim
+        self.refused(f, "R5")
+
+    def test_R6_new_package(self):
+        f = Fake()
+        f.extra_sim = ["Inst newthing (1.0 Debian:13.7/stable [amd64])"]
+        self.refused(f, "R6")
+
+    def test_R6_unlisted_package(self):
+        f = Fake()
+        f.extra_sim = ["Inst bash [5.2.37-2+b9] (5.2.37-2+b10 Debian:13.7/stable [amd64])"]
+        self.refused(f, "R6")
+
+    def test_R6_allow_new_is_slow_lane(self):
+        f = Fake()
+        f.plan["allow_new"] = ["proxmox-kernel-x"]
+        self.refused(f, "R6")
+
+    def test_R7_not_downloadable_and_no_snapshot(self):
+        f = Fake()
+        f.live["openssl"] = set()
+        f.plan["snapshot"] = ""
+        self.refused(f, "R7")
+
+    def test_R8_free_space(self):
+        f = Fake()
+        f.free = 100 * 1024 * 1024
+        self.refused(f, "R8")
+
+    def test_R9_guest_locked_by_a_backup(self):
+        f = Fake()
+        f.files["/etc/pve/lxc/9201.conf"] = CONF_OK + "lock: backup\n"
+        self.refused(f, "R9")
+
+    def test_R9_apt_lock_held(self):
+        f = Fake()
+        f.lock_held = True
+        self.refused(f, "R9")
+
+    def test_R10_not_the_boxs_own_guest(self):
+        f = Fake()
+        f.files["/etc/pve/lxc/9201.conf"] = CONF_OK.replace("mp8: /mnt/felhom-drives,", "mp8: /mnt/hdd_1/scratch,")
+        self.refused(f, "R10")
+
+    def test_R10_reserved_vmid(self):
+        f = Fake()
+        f.plan["vmid"] = 990003
+        self.refused(f, "R10")
+
+    def test_R10_bind_only_in_a_snapshot_section(self):
+        f = Fake()
+        f.files["/etc/pve/lxc/9201.conf"] = "rootfs: x\n[snap1]\nmp8: /mnt/felhom-drives,mp=/mnt/felhom-drives\n"
+        self.refused(f, "R10")
+
+    def test_R10_not_running(self):
+        f = Fake()
+        f.status = "status: stopped"
+        self.refused(f, "R10")
+
+    def test_R11_duplicate(self):
+        f = Fake()
+        f.plan["packages"].append(dict(f.plan["packages"][0]))
+        self.refused(f, "R11")
+
+    def test_R11_bad_version_string(self):
+        f = Fake()
+        f.plan["packages"][0]["version"] = "1.0; rm -rf /"
+        self.refused(f, "R11")
+
+    def test_R11_bad_name(self):
+        f = Fake()
+        f.plan["packages"][0]["name"] = "--purge"
+        self.refused(f, "R11")
+
+    def test_R12_unknown_layer(self):
+        f = Fake()
+        f.plan["layer"] = "vm"
+        self.refused(f, "R12")
+
+    def test_R12_host_on_a_byo_box(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.files[osapply.INSTALL_STATE] = json.dumps({"mode": "byo"})
+        self.refused(f, "R12")
+
+    def test_R12_host_without_an_install_record(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        del f.stats[osapply.INSTALL_STATE]
+        self.refused(f, "R12")
+
+    def test_R12_host_record_not_root_owned(self):
+        # the agent can write agent.json's deployment_mode; only a ROOT-owned record proves anything
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.stats[osapply.INSTALL_STATE] = St(mode=statmod.S_IFREG | 0o644, uid=999)
+        self.refused(f, "R12")
+
+    def test_R14_kernel_package_in_a_host_plan(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.plan["packages"].append({"name": "linux-image-amd64", "version": "6.12.1-1", "origin": "Debian"})
+        self.refused(f, "R14")
+
+    def test_R14_kernel_package_pulled_by_the_simulation(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.extra_sim = ["Inst grub-common [2.12-9] (2.12-10 Debian:13.7/stable [amd64])"]
+        f.installed["grub-common"] = "2.12-9"
+        f.plan["packages"].append({"name": "grub-common", "version": "2.12-10", "origin": "Debian"})
+        self.refused(f, "R14")
+
+    def test_R13_repair_does_not_fix_it(self):
+        f = Fake()
+        f.dpkg_audit = "The following packages are broken\n perl\n"
+        orig = f.guest
+
+        def guest(vmid, argv, timeout=1800):
+            rc, out, err = orig(vmid, argv, timeout)
+            if "-f" in argv:
+                f.dpkg_audit = "The following packages are broken\n perl\n"
+            return rc, out, err
+        f.guest = guest
+        self.refused(f, "R13")
+
+
+class Conffiles(unittest.TestCase):
+    # dpkg's two shapes, measured live 2026-10-04: an unchanged file is UPDATED; a locally changed one is KEPT.
+    def test_updated_vs_kept(self):
+        f = Fake()
+        f.install_out = ("Installing new version of config file /etc/debian_version ...\n"
+                         "Configuration file '/etc/ssh/sshd_config'\n ==> Modified (by you or by a script) since installation.\n"
+                         " ==> Keeping old config file as default.\n")
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertIn("os-apply: CONFFILE updated /etc/debian_version (it was not changed locally)", f.logs)
+        self.assertTrue(any(l.startswith("os-apply: CONFFILE kept /etc/ssh/sshd_config") for l in f.logs), f.logs)
+        self.assertEqual(rep["conffiles_kept"], ["/etc/ssh/sshd_config"])
+        self.assertFalse(any("kept /etc/debian_version" in l for l in f.logs), "an updated file must not be reported as kept")
+
+
+class HostLayer(unittest.TestCase):
+    def test_host_runs_on_the_host_not_in_the_guest(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        inst = [c for c in f.calls if c[0] == "host" and "install" in c[1] and "-s" not in c[1] and "-f" not in c[1]]
+        self.assertTrue(inst, "the host install must run on the host")
+        self.assertFalse([c for c in f.calls if c[0] == "guest" and "install" in c[2]], "nothing installed in the guest")
+        self.assertEqual(sorted(rep["health_after"]["host_services"]), sorted(osapply.HOST_SERVICES))
+        self.assertTrue(rep["health_after"]["guest_running"])
+
+    def test_pending_fast_skips_proxmox_docker_and_kernel(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.plan["select"] = "pending-fast"
+        f.plan["packages"] = []
+        f.installed.update({"pve-manager": "9.2.2", "linux-image-amd64": "6.12.1", "docker-ce": "29.7"})
+        f.pending_sim = [
+            "Inst libc6 [2.41-12+deb13u3] (2.41-12+deb13u4 Debian:13.7/stable [amd64])",
+            "Inst openssl [3.5.6-1~deb13u1] (3.5.7-1~deb13u3 Debian:13.7/stable, Debian-Security:13/stable-security [amd64])",
+            "Inst pve-manager [9.2.2] (9.2.21 Proxmox Debian Repository:stable [amd64])",
+            "Inst linux-image-amd64 [6.12.1] (6.12.9 Debian:13.7/stable [amd64])",
+            "Inst docker-ce [29.7] (29.8 Docker CE:trixie [amd64])",
+            "Inst brand-new (1.0 Debian:13.7/stable [amd64])",
+        ]
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        got = sorted(u["name"] for u in rep["upgraded"])
+        self.assertEqual(got, ["libc6", "openssl"], "pending-fast must take only installed, Debian-origin, non-kernel packages")
+
+    def test_reboot_needed_when_pid1_or_lxc_start(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.restart_out = "1 systemd\n2101 lxc-start\n530 sshd\n"
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertTrue(rep["reboot_needed"])
+        self.assertIn("lxc-start", rep["restart_needed"])
+
+    def test_reboot_needed_for_lxc_start_alone(self):
+        # lxc-start runs the guest; only a guest restart (or a host reboot) replaces it
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.restart_out = "2101 lxc-start\n530 sshd\n"
+        rc, rep = run(f)
+        self.assertTrue(rep["reboot_needed"], rep)
+
+    def test_host_scans_every_pass_guest_only_after_install(self):
+        # A host pass that installs nothing still scans, so a reboot clears the flag (the hub alarm reads it).
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.plan["mode"] = "inventory"
+        f.restart_out = "2101 lxc-start\n"
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        self.assertTrue(rep["reboot_scanned"], rep)
+        self.assertTrue(rep["reboot_needed"], rep)
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.plan["mode"] = "inventory"
+        f.restart_out = ""  # after the reboot: nothing maps a deleted file
+        rc, rep = run(f)
+        self.assertTrue(rep["reboot_scanned"] and rep["reboot_needed"] is False, rep)
+        f = Fake()
+        f.plan["mode"] = "inventory"
+        rc, rep = run(f)
+        self.assertFalse(rep["reboot_scanned"], "the guest scans only after an install (R-845)")
+
+    def test_no_reboot_for_ordinary_daemons(self):
+        f = Fake()
+        f.plan["layer"] = "host"
+        f.restart_out = "530 sshd\n611 cron\n"
+        rc, rep = run(f)
+        self.assertFalse(rep["reboot_needed"], rep)
+
+
+class Speed(unittest.TestCase):
+    # R-845: no `pct exec` per package — version checks on the host, madison once, the restart scan only after an install.
+    def test_no_per_package_guest_calls(self):
+        f = Fake()
+        for i in range(40):
+            f.installed[f"pkg{i}"] = "1.0-1"
+            f.live[f"pkg{i}"] = {"1.0-2"}
+            f.plan["packages"].append({"name": f"pkg{i}", "version": "1.0-2", "origin": "Debian"})
+        rc, rep = run(f)
+        self.assertEqual(rc, 0, rep)
+        guest_cmp = [c for c in f.calls if c[0] == "guest" and "--compare-versions" in c[2]]
+        self.assertEqual(guest_cmp, [], "version comparisons must run on the host")
+        self.assertEqual(f.madison_calls, 1, "madison must run once for all packages")
+        guest_calls = len([c for c in f.calls if c[0] == "guest"])
+        self.assertLess(guest_calls, 30, f"{guest_calls} guest calls for 42 packages — something is per-package again")
+
+
+class Failure(unittest.TestCase):
+    def test_install_failure_is_rc3_with_dpkg_state(self):
+        f = Fake()
+        f.install_rc = 100
+        rc, rep = run(f)
+        self.assertEqual(rc, 3)
+        self.assertEqual(rep["failed"]["rc"], 100)
+        self.assertTrue(any(l.startswith("os-apply: FAILED rc=100 step=install") for l in f.logs))
+
+
+
+class RestartSkipPattern(unittest.TestCase):
+    """The cgroup filter runs as `grep -q PATTERN /proc/<pid>/cgroup`; check it with grep itself against the cgroup
+    lines measured on demo-felhom 2026-10-04."""
+
+    def grep(self, pattern, line):
+        return subprocess.run(["grep", "-q", pattern], input=line + "\n", text=True).returncode == 0
+
+    def test_restart_skip_patterns_against_real_cgroups(self):
+        host = osapply.RESTART_SKIP_CGROUP["host"]
+        self.assertTrue(self.grep(host, "0::/lxc/9201/ns/system.slice/docker.service"), "a guest process must be skipped")
+        self.assertFalse(self.grep(host, "0::/lxc.monitor/9201"), "lxc-start must NOT be skipped (it runs the guest)")
+        self.assertFalse(self.grep(host, "0::/system.slice/pve-cluster.service"), "a host daemon must NOT be skipped")
+        guest = osapply.RESTART_SKIP_CGROUP["guest"]
+        self.assertTrue(self.grep(guest, "0::/system.slice/docker-0123abcd.scope"))
+        self.assertFalse(self.grep(guest, "0::/system.slice/cron.service"))
+
+if __name__ == "__main__":
+    unittest.main()

internal/backup/backup_test.go

@@ -2,6 +2,7 @@ package backup
 
 import (
 	"context"
+	"fmt"
 	"encoding/json"
 	"errors"
 	"io"
@@ -21,14 +22,18 @@ type fakeBackupAPI struct {
 	vzdumpErr  error
 	waitErr    error
 	cfg        proxmox.GuestConfig
+	goneGuests map[int]bool // R-689: vmids whose config lookup answers "does not exist"
+	aclGuests  map[int]bool // R-689: vmids outside the token's ACL — PVE answers 403 "permission denied"
 	cfgErr     error
 	content    []proxmox.StorageContent
 	contentErr error
-	storages   []proxmox.Storage // returned by ListStorage (the local-prune scope gate)
-	storageErr error
-	vzdumps    []proxmox.VzdumpOptions
-	logLines   []string      // returned by TaskLogTail (e.g. "INFO: backup mode: stop")
-	waitGate   chan struct{} // if non-nil, WaitTask blocks until closed (8B.2 watcher timing)
+	storages   []proxmox.Storage // returned by ListStorage (the local-prune scope gate) — DEFINITIONS: like
+	// production's GET /storage, it never carries usage; ListStorage strips Avail/Used (R-685's live lesson)
+	nodeStorages []proxmox.Storage // returned by NodeStorage (GET /nodes/{node}/storage — WITH usage)
+	storageErr   error
+	vzdumps      []proxmox.VzdumpOptions
+	logLines     []string      // returned by TaskLogTail (e.g. "INFO: backup mode: stop")
+	waitGate     chan struct{} // if non-nil, WaitTask blocks until closed (8B.2 watcher timing)
 }
 
 func (f *fakeBackupAPI) Vzdump(_ context.Context, o proxmox.VzdumpOptions) (string, error) {
@@ -41,13 +46,30 @@ func (f *fakeBackupAPI) WaitTask(_ context.Context, _ string, _ proxmox.WaitOpti
 	}
 	return proxmox.TaskStatus{Status: "stopped", ExitStatus: "OK"}, f.waitErr
 }
-func (f *fakeBackupAPI) GuestConfig(_ context.Context, _ int) (proxmox.GuestConfig, error) {
+func (f *fakeBackupAPI) GuestConfig(_ context.Context, vmid int) (proxmox.GuestConfig, error) {
+	if f.aclGuests[vmid] {
+		return proxmox.GuestConfig{}, fmt.Errorf("proxmox: GET /nodes/n/lxc/%d/config -> HTTP 403: permission denied at /vms/%d (missing privilege VM.Audit)", vmid, vmid)
+	}
+	if f.goneGuests[vmid] { // R-689: PVE's answer for a deleted guest
+		return proxmox.GuestConfig{}, fmt.Errorf("proxmox: GET /nodes/n/lxc/%d/config -> HTTP 500: Configuration file 'nodes/n/lxc/%d.conf' does not exist", vmid, vmid)
+	}
 	return f.cfg, f.cfgErr
 }
 func (f *fakeBackupAPI) StorageContent(_ context.Context, _ string) ([]proxmox.StorageContent, error) {
 	return f.content, f.contentErr
 }
 func (f *fakeBackupAPI) ListStorage(_ context.Context) ([]proxmox.Storage, error) {
+	out := make([]proxmox.Storage, len(f.storages))
+	for i, s := range f.storages {
+		s.Avail, s.Used, s.Total = 0, 0, 0 // GET /storage has no usage — a fake that had it hid R-685's defect
+		out[i] = s
+	}
+	return out, f.storageErr
+}
+func (f *fakeBackupAPI) NodeStorage(_ context.Context) ([]proxmox.Storage, error) {
+	if f.nodeStorages != nil {
+		return f.nodeStorages, f.storageErr
+	}
 	return f.storages, f.storageErr
 }
 func (f *fakeBackupAPI) TaskLogTail(_ context.Context, _ string, _ int) ([]string, error) {
@@ -137,13 +159,14 @@ func TestBackup_VzdumpFailureReturnsFailedRecord(t *testing.T) {
 func TestPickRestoreCandidate_NewestOrEmpty(t *testing.T) {
 	const big = 4 << 30 // a plausible whole-guest archive
 	api := &fakeBackupAPI{content: []proxmox.StorageContent{
-		{VolID: "a", Content: "backup", CTime: 10, Size: big},
-		{VolID: "b", Content: "backup", CTime: 99, Size: big},
+		// R-689: real vzdump names with their vmid — only a backup OF A GUEST is a candidate.
+		{VolID: "local:backup/vzdump-lxc-9001-a.tar.zst", VMID: 9001, Content: "backup", CTime: 10, Size: big},
+		{VolID: "local:backup/vzdump-lxc-9001-b.tar.zst", VMID: 9001, Content: "backup", CTime: 99, Size: big},
 		{VolID: "iso", Content: "iso", CTime: 999, Size: big}, // not a backup → ignored
 	}}
 	r := NewBackupRunner(api, "local", "", "", "", quiet())
 	vol, err := r.PickRestoreCandidate(context.Background())
-	if err != nil || vol != "b" {
+	if err != nil || vol != "local:backup/vzdump-lxc-9001-b.tar.zst" {
 		t.Fatalf("pick = %q,%v want newest 'b'", vol, err)
 	}
 	// no backups → "".
@@ -163,12 +186,12 @@ func TestPickRestoreCandidate_NewestOrEmpty(t *testing.T) {
 // `pick = "phantom" want the newest COMPLETE archive 'real'`.
 func TestPickRestoreCandidate_SkipsImplausibleArchives(t *testing.T) {
 	api := &fakeBackupAPI{content: []proxmox.StorageContent{
-		{VolID: "real", Content: "backup", CTime: 10, Size: 4 << 30},
-		{VolID: "phantom", Content: "backup", CTime: 99, Size: 1}, // newest, and impossible
+		{VolID: "felhom-pbs:backup/ct/9001/real", VMID: 9001, Content: "backup", CTime: 10, Size: 4 << 30},
+		{VolID: "felhom-pbs:backup/ct/9001/phantom", VMID: 9001, Content: "backup", CTime: 99, Size: 1}, // newest, and impossible
 	}}
 	r := NewBackupRunner(api, "local", "", "", "", quiet())
 	vol, err := r.PickRestoreCandidate(context.Background())
-	if err != nil || vol != "real" {
+	if err != nil || vol != "felhom-pbs:backup/ct/9001/real" {
 		t.Fatalf("pick = %q,%v want the newest COMPLETE archive 'real'", vol, err)
 	}
 }

internal/backup/r672_skip_test.go

@@ -0,0 +1,36 @@
+package backup
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+)
+
+// R-672 (v0.133.0): a restore-test the SPACE preflight refused is the test's RESULT — recorded for the
+// hub as pass=false with the reason, never dropped (a band skip still is) and never a pass.
+//
+// COMPANION RED-PROOF (REPORT): the scheduler's pre-v0.133.0 `if res.Skipped { return }` → "a space
+// refusal never reached the host report".
+func TestR672_SpaceSkipIsReportedNotDropped(t *testing.T) {
+	store := NewStore()
+	rt := &fakeRTRunner{res: reconcile.RestoreTestResult{Archive: "vol", Skipped: true,
+		SkipReason: "skipped: not enough space on local-lvm: restoring 21.1 GiB (vzdump log) needs 30.3 GiB free, has 21.6 GiB"}}
+	s := NewScheduler(SchedulerOptions{
+		Runner: rt, Pick: func(context.Context) (string, error) { return "vol", nil }, Store: store,
+		Spec: func(context.Context, string) reconcile.RestoreTestSpec {
+			return reconcile.RestoreTestSpec{RestoreStorage: "local-lvm", ScratchMin: 990000, ScratchMax: 990009}
+		},
+		Cadence: time.Hour, Logger: quiet(),
+	})
+	s.tick(context.Background())
+	got := store.RestoreTests(context.Background())
+	if len(got) != 1 {
+		t.Fatalf("a space refusal never reached the host report: %+v", got)
+	}
+	if got[0].Pass || !got[0].Skipped || !strings.HasPrefix(got[0].Error, "skipped: not enough space") {
+		t.Fatalf("record = %+v — want pass=false, skipped, the reason as the error", got[0])
+	}
+}

internal/backup/r685_space_test.go

@@ -0,0 +1,83 @@
+package backup
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-685 (v0.134.0) — a whole-box backup that cannot fit its LOCAL target is a named skip BEFORE anything
+// starts, with the numbers in the record's Error, never a vzdump that fills the disk and fails.
+
+const gib = int64(1) << 30
+
+func spaceAPI(avail int64, lastArchive int64, typ string) *fakeBackupAPI {
+	api := &fakeBackupAPI{vzdumpUPID: "UPID:vzdump:1",
+		storages: []proxmox.Storage{{Storage: "local", Type: typ, Content: "backup", Avail: avail}}}
+	if lastArchive > 0 {
+		api.content = []proxmox.StorageContent{{VolID: "local:backup/vzdump-lxc-9201-2026_09_24-21_59_25.tar.zst",
+			Content: "backup", VMID: 9201, Size: lastArchive, CTime: 1790280000}}
+	}
+	return api
+}
+
+// TestR685_BackupThatCannotFitIsSkipped — demo-hp's shape: an 8.2 GB archive, 4 GiB free. No vzdump is
+// started; the record says why, with the numbers, under a stable prefix.
+//
+// COMPANION RED-PROOF (REPORT.md): drop the spaceFits call from backup() — this test fails at "a vzdump
+// was started on a target that cannot hold it".
+func TestR685_BackupThatCannotFitIsSkipped(t *testing.T) {
+	api := spaceAPI(4*gib, 8182759056, "dir")
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	rec, err := r.Backup(context.Background(), 9201)
+	if len(api.vzdumps) != 0 {
+		t.Fatalf("a vzdump was started on a target that cannot hold it: %+v", api.vzdumps)
+	}
+	if err == nil || rec.Success || !strings.HasPrefix(rec.Error, BackupSkipNoSpacePrefix) {
+		t.Fatalf("want a named skip, got err=%v rec=%+v", err, rec)
+	}
+	for _, want := range []string{"4.0 GiB free", "7.6 GiB", "10.5 GiB"} {
+		if !strings.Contains(rec.Error, want) {
+			t.Errorf("the reason must carry the numbers (%q missing): %s", want, rec.Error)
+		}
+	}
+}
+
+// TestR685_BackupThatFitsRuns — the same archive with 16 GiB free (demo-hp after tonight's prune) runs.
+func TestR685_BackupThatFitsRuns(t *testing.T) {
+	api := spaceAPI(16*gib, 8182759056, "dir")
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	_, _ = r.Backup(context.Background(), 9201)
+	if len(api.vzdumps) != 1 {
+		t.Fatalf("a backup that fits must run, vzdumps=%d", len(api.vzdumps))
+	}
+}
+
+// TestR685_FailsOpen — never refuse on what is not KNOWN: a PBS target, a first backup (no archive to
+// size from), an unknown free figure, or a storage list that cannot be read.
+func TestR685_FailsOpen(t *testing.T) {
+	cases := map[string]*fakeBackupAPI{
+		"pbs target":    spaceAPI(1*gib, 8*gib, "pbs"),
+		"first backup":  spaceAPI(1*gib, 0, "dir"),
+		"avail unknown": spaceAPI(0, 8*gib, "dir"),
+		"storage list error": func() *fakeBackupAPI {
+			a := spaceAPI(1*gib, 8*gib, "dir")
+			a.storageErr = context.DeadlineExceeded
+			return a
+		}(),
+	}
+	for name, api := range cases {
+		target := "local"
+		if name == "pbs target" {
+			api.storages[0].Storage = "felhom-pbs"
+			target = "felhom-pbs"
+		}
+		r := NewBackupRunner(api, target, proxmox.ModeSnapshot, "", "", quiet())
+		_, _ = r.Backup(context.Background(), 9201)
+		if len(api.vzdumps) != 1 {
+			t.Errorf("%s: the preflight must fail OPEN, but no vzdump ran", name)
+		}
+	}
+}

internal/backup/r689_golden_test.go

@@ -0,0 +1,112 @@
+package backup
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-689 (v0.135.0) — demo-hp keeps its golden template in `local:backup/`. It is content "backup",
+// 654 MB and so "plausibly complete", and it was the newest SETTLED entry: the restore test picked it
+// every 6 h and failed extractconfig with a 403 (measured 2026-09-24 10:36, 09-25 04:57 and 10:57),
+// while the guest's own archive — younger than the 24 h settle — went untested and nothing was proven.
+//
+// COMPANION RED-PROOF (REPORT.md): drop the guestBackupArchive call from PickSettledRestoreCandidateOn —
+// this test then picks `local:backup/felhom-golden-0.236.0.tar.zst`.
+func TestR689_TheRestoreTestNeverPicksTheGolden(t *testing.T) {
+	const day = int64(86400)
+	now := int64(1790370000) // 2026-09-25 ~19:00Z
+	api := &fakeBackupAPI{content: []proxmox.StorageContent{
+		// the guest's real archive, settled (older than the cutoff below)
+		{VolID: "local:backup/vzdump-lxc-9201-2026_09_22-21_59_25.tar.zst", Content: "backup", VMID: 9201, Size: 8 << 30, CTime: now - 3*day},
+		// the golden: newer, settled, big, and NOT a backup of a guest
+		{VolID: "local:backup/felhom-golden-0.236.0.tar.zst", Content: "backup", Size: 654115664, CTime: now - 2*day},
+		// a hand-copied tarball that PVE happens to attribute to a vmid — the name is not a vzdump's
+		{VolID: "local:backup/copy-of-9201.tar.zst", Content: "backup", VMID: 9201, Size: 8 << 30, CTime: now - 2*day},
+	}}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	got, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Unix(now-day, 0).UTC())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "local:backup/vzdump-lxc-9201-2026_09_22-21_59_25.tar.zst" {
+		t.Fatalf("picked %q — the restore test must prove a backup OF A GUEST", got)
+	}
+}
+
+func TestR689_GuestBackupArchiveShapes(t *testing.T) {
+	for _, c := range []struct {
+		e  proxmox.StorageContent
+		ok bool
+	}{
+		{proxmox.StorageContent{VolID: "local:backup/vzdump-lxc-9201-2026_09_24-21_59_25.tar.zst", VMID: 9201}, true},
+		{proxmox.StorageContent{VolID: "local:backup/vzdump-qemu-300-2026_09_24-21_59_25.vma.zst", VMID: 300}, true},
+		{proxmox.StorageContent{VolID: "felhom-pbs:backup/ct/9201/2026-07-28T05:31:14Z", VMID: 9201}, true},
+		{proxmox.StorageContent{VolID: "felhom-pbs:backup/vm/300/2026-07-28T05:31:14Z", VMID: 300}, true},
+		{proxmox.StorageContent{VolID: "local:backup/felhom-golden-0.236.0.tar.zst"}, false},
+		{proxmox.StorageContent{VolID: "local:backup/vzdump-lxc-9201-x.tar.zst", VMID: 9202}, false}, // vmid disagrees with the name
+		{proxmox.StorageContent{VolID: "felhom-pbs:backup/ct/9201/2026-07-28T05:31:14Z"}, false},       // no vmid reported
+	} {
+		if ok, why := guestBackupArchive(c.e); ok != c.ok {
+			t.Errorf("%s vmid=%d: ok=%v (%s), want %v", c.e.VolID, c.e.VMID, ok, why, c.ok)
+		}
+	}
+}
+
+// R-689 (v0.136.0) — the measured demo-hp shape right after v0.135.0: the golden (skipped), a leftover archive
+// of guest 9100 deleted in August (settled), and today's archive of 9201 (not settled yet). The pick must be
+// NOTHING — never the deleted guest's archive. With 9201's archive settled, that one.
+//
+// COMPANION RED-PROOF (REPORT.md): drop the known-guest check — the pick is the 9100 leftover.
+func TestR689_AnArchiveOfADeletedGuestIsNeverPicked(t *testing.T) {
+	const day = int64(86400)
+	now := int64(1790476000)
+	api := &fakeBackupAPI{goneGuests: map[int]bool{9100: true}, content: []proxmox.StorageContent{
+		{VolID: "local:backup/felhom-golden-0.236.0.tar.zst", Content: "backup", Size: 654115664, CTime: now - 14*day},
+		{VolID: "local:backup/vzdump-lxc-9100-2026_08_21-17_59_15.tar.zst", Content: "backup", VMID: 9100, Size: 656970239, CTime: now - 37*day},
+		{VolID: "local:backup/vzdump-lxc-9201-2026_09_27-04_35_47.tar.zst", Content: "backup", VMID: 9201, Size: 8 << 30, CTime: now - 7*3600},
+	}}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	got, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Unix(now-day, 0).UTC())
+	if err != nil || got != "" {
+		t.Fatalf("picked %q err=%v — a deleted guest's archive proves nothing about this box", got, err)
+	}
+	got, _, _ = r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Unix(now, 0).UTC())
+	if got != "local:backup/vzdump-lxc-9201-2026_09_27-04_35_47.tar.zst" {
+		t.Fatalf("with 9201's archive settled the pick is %q", got)
+	}
+}
+
+// Any OTHER lookup failure is not "the guest is gone": the tier must read UNKNOWN (an error), never
+// "nothing to prove".
+func TestR689_AGuestLookupFailureIsUnknownNotEmpty(t *testing.T) {
+	api := &fakeBackupAPI{cfgErr: fmt.Errorf("proxmox: connection refused"), content: []proxmox.StorageContent{
+		{VolID: "local:backup/vzdump-lxc-9201-x.tar.zst", Content: "backup", VMID: 9201, Size: 8 << 30, CTime: 10},
+	}}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	if _, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Time{}); err == nil {
+		t.Fatal("a failed guest lookup read as a clean answer")
+	}
+}
+
+// v0.137.0 — THE MEASURED ANSWER: the agent's token sees only its pool, so for the deleted guest PVE says 403
+// "permission denied at /vms/9100", not "does not exist" (demo-hp, right after v0.136.0 — the local tier read
+// UNKNOWN). Such a guest is not one this agent manages: its archive is skipped, the tier is not an error.
+//
+// COMPANION RED-PROOF (REPORT.md): drop the "permission denied" case — the pick errors.
+func TestR689_AGuestOutsideTheAgentsACLIsNotAKnownGuest(t *testing.T) {
+	const day = int64(86400)
+	now := int64(1790476000)
+	api := &fakeBackupAPI{aclGuests: map[int]bool{9100: true}, content: []proxmox.StorageContent{
+		{VolID: "local:backup/vzdump-lxc-9100-2026_08_21-17_59_15.tar.zst", Content: "backup", VMID: 9100, Size: 656970239, CTime: now - 37*day},
+		{VolID: "local:backup/vzdump-lxc-9201-2026_09_27-04_35_47.tar.zst", Content: "backup", VMID: 9201, Size: 8 << 30, CTime: now - 7*3600},
+	}}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	got, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Unix(now-day, 0).UTC())
+	if err != nil || got != "" {
+		t.Fatalf("picked %q err=%v — want nothing and no error (the only settled archive is not ours)", got, err)
+	}
+}

internal/backup/r727_own_archives_test.go

@@ -0,0 +1,74 @@
+package backup
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+const (
+	thisBoxKey  = "de:51:7a:18:cb:39:22:30:2c:84:f5:8b:d1:91:4b:7e:81:bb:69:b8:89:0f:57:ac:d3:59:e1:1a:62:25:11:2c"
+	earlierBox1 = "6b:ca:5f:3f:ca:0f:e2:3f:fb:24:62:89:bf:e7:64:59:9a:41:c5:e6:e3:9f:3f:5f:e1:71:7b:a1:9d:24:67:82"
+	earlierBox2 = "fe:3d:db:95:d4:df:ab:e1:7d:4a:89:fa:2b:07:53:6a:e4:d2:85:95:d1:90:27:4b:d9:c6:92:20:95:04:e5:d4"
+)
+
+// R-727 (v0.138.0) — the 2026-09-30 shape, measured on a fresh box for a returning customer: the PBS
+// namespace held two archives of earlier boxes (same guest 9201, same token) and this box's own, which was not
+// settled yet. The old picker chose the earlier box's newest settled archive and failed `wrong key`.
+// The CONSEQUENCE asserted: no archive of another box is ever picked; with this box's archive settled it is picked.
+// COMPANION RED-PROOF: remove the `ownKey != "" && !EqualFold(...)` skip → the first case picks 2026-09-16T21:59:54Z.
+func TestR727_TheRestoreTestTakesOnlyThisBoxsArchives(t *testing.T) {
+	day := int64(86400)
+	now := int64(1790740000) // 2026-09-30 ~04:00Z
+	own := proxmox.StorageContent{VolID: "felhom-pbs:backup/ct/9201/2026-09-29T19:37:07Z", Content: "backup", VMID: 9201, Size: 3490689830, CTime: 1790710627, Encrypted: thisBoxKey}
+	api := &fakeBackupAPI{
+		storages: []proxmox.Storage{{Storage: "felhom-pbs", Type: "pbs", EncryptionKey: thisBoxKey}},
+		content: []proxmox.StorageContent{
+			{VolID: "felhom-pbs:backup/ct/9201/2026-09-16T17:27:32Z", Content: "backup", VMID: 9201, Size: 4774114206, CTime: 1789579652, Encrypted: earlierBox2},
+			{VolID: "felhom-pbs:backup/ct/9201/2026-09-16T21:59:54Z", Content: "backup", VMID: 9201, Size: 20811501236, CTime: 1789595994, Encrypted: earlierBox1},
+			own,
+		},
+	}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+
+	// 1. The night of 2026-09-30: this box's own archive is ~6 h old, not settled (cutoff 24 h) — nothing to prove.
+	got, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "felhom-pbs", time.Unix(now-day, 0).UTC())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "" {
+		t.Fatalf("picked %q — an archive of ANOTHER box is never this box's proof (R-727)", got)
+	}
+	// 2. A day later this box's own archive is settled — it is the one picked.
+	got, _, err = r.PickSettledRestoreCandidateOn(context.Background(), "felhom-pbs", time.Unix(now+day, 0).UTC())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != own.VolID {
+		t.Fatalf("picked %q, want this box's own %q", got, own.VolID)
+	}
+}
+
+// An unencrypted storage (a local dir) holds only this box's vzdumps — no key filter applies.
+func TestR727_UnencryptedStorageIsNotFiltered(t *testing.T) {
+	api := &fakeBackupAPI{
+		storages: []proxmox.Storage{{Storage: "local", Type: "dir"}},
+		content:  []proxmox.StorageContent{{VolID: "local:backup/vzdump-lxc-9201-2026_09_29-21_27_05.tar.zst", Content: "backup", VMID: 9201, Size: 955425507, CTime: 1790710025}},
+	}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	if got, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "local", time.Time{}); err != nil || got == "" {
+		t.Fatalf("got %q err %v", got, err)
+	}
+}
+
+// A storage-list failure makes the tier UNKNOWN (an error), never "nothing to prove".
+func TestR727_KeyLookupFailureIsUnknown(t *testing.T) {
+	api := &fakeBackupAPI{storageErr: errors.New("proxmox: GET /storage -> HTTP 500"), content: []proxmox.StorageContent{{VolID: "felhom-pbs:backup/ct/9201/x", Content: "backup", VMID: 9201}}}
+	r := NewBackupRunner(api, "local", proxmox.ModeSnapshot, "", "keep-last=1", quiet())
+	if _, _, err := r.PickSettledRestoreCandidateOn(context.Background(), "felhom-pbs", time.Time{}); err == nil {
+		t.Fatal("a failed key lookup must surface as an error (tier UNKNOWN)")
+	}
+}

internal/backup/restoretest_due.go

@@ -140,3 +140,29 @@ func (s *Scheduler) evaluateTier(ctx context.Context, target string, cutoff time
 func (s *Scheduler) EvaluateDueTier(ctx context.Context, target string) DueVerdict {
 	return s.evaluateTier(ctx, target, s.settleCutoff())
 }
+
+// verdictSummary renders one compact line of per-tier verdicts for the "nothing due" log.
+//
+// It re-evaluates rather than threading the verdicts out of pickForThisRun, and that is a
+// deliberate trade: this runs only on the path where NOTHING is due, so the cost is one extra
+// storage listing per tier on an otherwise idle evaluation (measured 18 ms local / 392 ms offsite,
+// R-86 Part 1.4), and in exchange the logging path cannot drift from the deciding path by holding a
+// stale copy of it. If that cost ever matters, pass the verdicts in — do not let the two diverge.
+func (s *Scheduler) verdictSummary(ctx context.Context) string {
+	out := ""
+	for _, v := range s.EvaluateDue(ctx) {
+		if out != "" {
+			out += "; "
+		}
+		switch {
+		case v.Err != nil:
+			out += v.Target + ": UNKNOWN (" + v.Err.Error() + ")"
+		default:
+			out += v.Target + ": " + v.Reason
+		}
+	}
+	if out == "" {
+		return "no tiers configured"
+	}
+	return out
+}

internal/backup/restoretest_due_test.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -124,8 +126,8 @@ func dailyArchives(tier string, n int) []archiveStub {
 // COMPANION RED-PROOF (observed 2026-08-03). In Scheduler.evaluateTier, the per-archive comparison
 // was replaced by the naive age rule:
 //
-//	-	if ok && proven == archive { … not due … }
-//	+	if s.now().Sub(landed) < s.settle { … not due … }   // and the proven-archive check deleted
+//   - if ok && proven == archive { … not due … }
+//   - if s.now().Sub(landed) < s.settle { … not due … }   // and the proven-archive check deleted
 //
 // and the picker cutoff was removed (`cutoff := time.Time{}`), i.e. exactly "is the newest archive
 // old enough". Result:
@@ -194,12 +196,13 @@ func TestDue_WeeklyTierIsProvedOncePerArchive(t *testing.T) {
 // COMPANION RED-PROOF (observed 2026-08-03): revert the state to per-tier TIME by making
 // ProvenArchive ignore the stored archive —
 //
-//	-	if !ok || p.Archive == "" { return "", false }
-//	+	return "", false     // per-tier time only, the pre-R-86 state
+//   - if !ok || p.Archive == "" { return "", false }
+//   - return "", false     // per-tier time only, the pre-R-86 state
 //
 // →	--- FAIL: TestDue_RestartRunsNothing
-//	    restoretest_due_test.go:226: an agent restart must not trigger a restore-test; 2 restart(s)
-//	    produced 4 run(s)
+//
+//	restoretest_due_test.go:226: an agent restart must not trigger a restore-test; 2 restart(s)
+//	produced 4 run(s)
 //
 // Four: the same already-proven archive re-tested on EVERY evaluation after EVERY restart, which is
 // today's behaviour with the ticker's phase reset by the deploy. Restored.
@@ -256,12 +259,13 @@ func TestDue_NewSettledArchiveMakesAProvedTierDueAgain(t *testing.T) {
 //
 // COMPANION RED-PROOF (observed 2026-08-03): give credit on failure in Scheduler.tick —
 //
-//	-	if rt.Pass && s.rtState != nil && target != "" {
-//	+	if s.rtState != nil && target != "" {
+//   - if rt.Pass && s.rtState != nil && target != "" {
+//   - if s.rtState != nil && target != "" {
 //
 // →	--- FAIL: TestDue_FailingTierIsRetriedAndNeverProven
-//	    restoretest_due_test.go: a failing tier must keep being retried; got 1 run(s) over 3
-//	    evaluations
+//
+//	restoretest_due_test.go: a failing tier must keep being retried; got 1 run(s) over 3
+//	evaluations
 //
 // A single failure would have retired the archive as proven — a permanently broken DR tier looking
 // freshly verified, which is the loudest signal this system produces going silent. Restored.
@@ -438,7 +442,7 @@ func TestRestoreTestState_ArchiveRoundTrips(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "rt.json")
 	now := time.Now().UTC().Truncate(time.Second)
 	st := NewRestoreTestState(path)
-	if err := st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/x", now); err != nil {
+	if err := st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/x", "pbs", "boot+running", now); err != nil {
 		t.Fatal(err)
 	}
 	re := NewRestoreTestState(path)
@@ -456,3 +460,134 @@ func TestRestoreTestState_ArchiveRoundTrips(t *testing.T) {
 func writeFileForTest(path, content string) error {
 	return os.WriteFile(path, []byte(content), 0o600)
 }
+
+// Standing rule 3: an absent log line is not evidence. "Nothing is due" is now the NORMAL outcome of
+// an evaluation, so it must produce a POSITIVE observable naming each tier's verdict — otherwise a
+// quiet journal is equally consistent with a healthy loop and a dead goroutine.
+//
+// COMPANION RED-PROOF (observed 2026-08-03): drop the summary back to a bare
+// `s.logger.Debug("backup: restore-test not due this evaluation")` and this fails with
+// "a not-due evaluation must name each tier's verdict; got \"\"" — i.e. nothing at INFO at all.
+func TestDue_NothingDueStillNamesEveryTiersVerdict(t *testing.T) {
+	ts := &tierStorage{archives: map[string][]archiveStub{
+		"local":      {{volid: "local:backup/a.tar.zst", landed: day0}},
+		"felhom-pbs": nil, // no archive at all
+	}}
+	h := newDueHarness(t, day0.AddDate(0, 0, 1), 24*time.Hour, true, []string{"local", "felhom-pbs"}, ts)
+	// Prove the local tier so NOTHING is due.
+	if err := h.st.RecordSuccess("local", "local:backup/a.tar.zst", "local", "boot+running", h.clock); err != nil {
+		t.Fatal(err)
+	}
+
+	// Assert what the SCHEDULER emits on a real evaluation, not what a helper returns — a helper
+	// test would pass against a tick that never calls it.
+	var logbuf strings.Builder
+	h.s.logger = slog.New(slog.NewTextHandler(&logbuf, &slog.HandlerOptions{Level: slog.LevelInfo}))
+	h.s.tick(context.Background())
+	got := logbuf.String()
+	for _, want := range []string{"local", "felhom-pbs", "already proven", "no settled archive"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("a not-due evaluation must name each tier's verdict; got %q (missing %q)", got, want)
+		}
+	}
+}
+
+// A tier whose storage cannot be listed must say UNKNOWN in that same line — a lookup failure that
+// reads as "nothing due" is the silence this rule exists to prevent.
+func TestDue_VerdictSummaryNamesAnUnknownTier(t *testing.T) {
+	ts := &tierStorage{
+		archives: map[string][]archiveStub{"local": nil},
+		err:      map[string]error{"felhom-pbs": errors.New("storage unreachable")},
+	}
+	h := newDueHarness(t, day0, 24*time.Hour, true, []string{"local", "felhom-pbs"}, ts)
+	got := h.s.verdictSummary(context.Background())
+	if !strings.Contains(got, "UNKNOWN") || !strings.Contains(got, "storage unreachable") {
+		t.Fatalf("an unlistable tier must read as UNKNOWN with its error; got %q", got)
+	}
+}
+
+// ── R-189 — the persisted proof must be REPORTABLE, and must refuse to lie ───────────────────
+//
+// A proof held only in the in-memory store dies with the process, and under per-archive due-ness the
+// agent will not repeat the work. So the persisted record has to be able to become a host-report
+// entry — without inventing anything it does not know.
+//
+// COMPANION RED-PROOF (observed 2026-08-03): drop the `reportable()` filter from
+// ProvenRestoreTests, so a pre-R-189 record (archive but no tier) is emitted →
+//
+//	--- FAIL: TestProvenRestoreTests_RefusesToReportWhatItCannotDescribe
+//	    restoretest_due_test.go: a record with no TIER must not be reported (the hub keys its
+//	    per-tier proof on it); got [{... SourceTier: ...}]
+//
+// Restored.
+func TestProvenRestoreTests_RefusesToReportWhatItCannotDescribe(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "rt.json")
+	// v1 (a bare time), v2 (archive, no tier) and v3 (complete) side by side — every shape this
+	// file has ever had, which is what a real box carries after two upgrades.
+	legacy := `{
+	  "old-v1":     "2026-07-30T02:11:07Z",
+	  "old-v2":     {"archive":"felhom-backup:backup/vzdump-lxc-9201-a.tar.zst","proven_at":"2026-08-01T04:41:58Z"},
+	  "felhom-pbs": {"archive":"felhom-pbs:backup/ct/9201/2026-07-28T04:49:43Z","tier":"pbs","verified":"boot+running","proven_at":"2026-08-03T13:25:14Z"}
+	}`
+	if err := writeFileForTest(path, legacy); err != nil {
+		t.Fatal(err)
+	}
+
+	got := NewRestoreTestState(path).ProvenRestoreTests(context.Background())
+	if len(got) != 1 {
+		t.Fatalf("only the record that can be described honestly may be reported; got %d: %+v", len(got), got)
+	}
+	e := got[0]
+	if e.SourceTier != "pbs" {
+		t.Fatalf("a record with no TIER must not be reported (the hub keys its per-tier proof on it); got %+v", got)
+	}
+	if e.SourceArchive != "felhom-pbs:backup/ct/9201/2026-07-28T04:49:43Z" || !e.Pass {
+		t.Fatalf("the reported entry must be the stored proof, unchanged; got %+v", e)
+	}
+	if e.TestedAt != "2026-08-03T13:25:14Z" {
+		t.Fatalf("the entry must carry the time the run passed, not now(); got %q", e.TestedAt)
+	}
+	if e.Verified != "boot+running" {
+		t.Fatalf("what the run verified must survive the round trip; got %q", e.Verified)
+	}
+	// Run mechanics are NOT invented: an absent duration is not a claim, a fabricated one would be.
+	if e.DurationSeconds != 0 || e.ScratchVMID != 0 {
+		t.Fatalf("the re-report must not invent run mechanics it never stored; got duration=%v scratch=%d",
+			e.DurationSeconds, e.ScratchVMID)
+	}
+	// The legacy records still serve the DUE-check, which is a separate question from reporting.
+	if _, ok := NewRestoreTestState(path).ProvenArchive("old-v2"); !ok {
+		t.Fatal("a v2 record must still answer the due-check even though it cannot be reported")
+	}
+}
+
+// A tier proved through the SCHEDULER (not by hand) lands in the state complete enough to report —
+// the production path, not a hand-built fixture.
+func TestScheduler_ProofIsRecordedReportably(t *testing.T) {
+	ts := &tierStorage{archives: map[string][]archiveStub{"felhom-pbs": {{volid: "felhom-pbs:backup/ct/9201/w0", landed: day0}}}}
+	h := newDueHarness(t, day0.AddDate(0, 0, 1).Add(97*time.Minute), 24*time.Hour, true, []string{"felhom-pbs"}, ts)
+	// The fake runner echoes the spec's tier; give the spec a tier the way main.go does.
+	h.s.spec = func(_ context.Context, archive string) reconcile.RestoreTestSpec {
+		return reconcile.RestoreTestSpec{RestoreStorage: "local-lvm", ScratchMin: 990000, ScratchMax: 990009, SourceTier: "pbs"}
+	}
+	h.s.tick(context.Background())
+
+	got := h.st.ProvenRestoreTests(context.Background())
+	if len(got) != 1 {
+		t.Fatalf("a scheduled pass must leave a REPORTABLE proof; got %d: %+v", len(got), got)
+	}
+	if got[0].SourceTier != "pbs" || got[0].SourceArchive != "felhom-pbs:backup/ct/9201/w0" {
+		t.Fatalf("the proof must name the tier and the archive the run used; got %+v", got[0])
+	}
+}
+
+// A FAILED run leaves nothing to report — the asymmetry of §8.1, asserted rather than assumed.
+func TestScheduler_AFailureLeavesNoPersistedProof(t *testing.T) {
+	ts := &tierStorage{archives: map[string][]archiveStub{"felhom-pbs": {{volid: "felhom-pbs:backup/ct/9201/w0", landed: day0}}}}
+	h := newDueHarness(t, day0.AddDate(0, 0, 1).Add(97*time.Minute), 24*time.Hour, false, []string{"felhom-pbs"}, ts)
+	h.s.tick(context.Background())
+	if got := h.st.ProvenRestoreTests(context.Background()); len(got) != 0 {
+		t.Fatalf("a FAILED run must persist nothing — a failing tier is retried, and a stored failure "+
+			"would outlive the fault; got %+v", got)
+	}
+}

internal/backup/restoretest_state.go

@@ -1,12 +1,15 @@
 package backup
 
 import (
+	"context"
 	"encoding/json"
 	"os"
 	"path/filepath"
 	"sort"
 	"sync"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
 )
 
 // RestoreTestState persists the last SUCCESSFUL restore-test per backup tier.
@@ -49,16 +52,45 @@ type RestoreTestState struct {
 	last map[string]provenTier // target id → what was last PROVEN on that tier
 }
 
-// provenTier is one tier's proof: the archive that passed, and when it passed.
+// provenTier is one tier's proof: the archive that passed, which tier it was, what was verified,
+// and when.
+//
+// R-189 added `Tier` and `Verified`. Until then this record could answer the DUE-check but could not
+// be REPORTED, and being reportable is what closes R-189: a proof held only in the in-memory result
+// store vanishes on restart, and under per-archive due-ness the box will not repeat the work, so the
+// hub can stay ignorant of a real success until the next archive generation.
+//
+// `Tier` is stored rather than derived because it is known for certain at proof time (the run's own
+// spec used it to choose the restore timeout) and deriving it later would need a storage-type lookup
+// at report-building time — a network call that can fail, on a path where failing means mis-labelling
+// a proof. Store what you knew when you knew it.
 type provenTier struct {
-	Archive string    // volid of the archive that PASSED; "" = a legacy record with no archive
-	At      time.Time // when that run passed (UTC)
+	Archive  string    // volid of the archive that PASSED; "" = a legacy record with no archive
+	Tier     string    // "local" | "pbs" — as the run reported it; "" = pre-R-189 record
+	Verified string    // what the run verified (e.g. "boot+running"); "" = pre-R-189 record
+	At       time.Time // when that run passed (UTC)
 }
 
-// provenTierJSON is the on-disk shape (R-86). The legacy shape was a bare RFC3339 STRING per
-// target; both are read, only this one is written — see NewRestoreTestState.
+// reportable reports whether this record can be re-reported to the hub as a restore-test result.
+//
+// It needs BOTH the archive and the tier: the hub keys its edge-triggered failure state on the
+// archive and its per-tier proof lookup on the tier, so an entry missing either is not a usable
+// proof — and emitting one anyway would be a report the hub cannot act on, dressed as evidence.
+// A pre-R-189 record is therefore silently not reported; the tier's next real proof fills it in.
+func (p provenTier) reportable() bool { return p.Archive != "" && p.Tier != "" }
+
+// provenTierJSON is the on-disk shape. Two older shapes are read and neither is written:
+//
+//	v1 (pre-R-86)  "<target>": "<RFC3339>"                     — a time, no archive
+//	v2 (R-86)      "<target>": {archive, proven_at}            — due-check usable, not reportable
+//	v3 (R-189)     "<target>": {archive, tier, verified, …}    — both
+//
+// Fields absent in an older file unmarshal to "", which is exactly the "no usable proof" signal the
+// readers above test for — the migration needs no version number because the absence IS the answer.
 type provenTierJSON struct {
 	Archive  string `json:"archive"`
+	Tier     string `json:"tier,omitempty"`
+	Verified string `json:"verified,omitempty"`
 	ProvenAt string `json:"proven_at"`
 }
 
@@ -99,21 +131,31 @@ func NewRestoreTestState(path string) *RestoreTestState {
 		if perr != nil {
 			continue
 		}
-		s.last[target] = provenTier{Archive: cur.Archive, At: t.UTC()}
+		s.last[target] = provenTier{Archive: cur.Archive, Tier: cur.Tier, Verified: cur.Verified, At: t.UTC()}
 	}
 	return s
 }
 
-// RecordSuccess stamps a tier as proven at t, naming the ARCHIVE that passed. Only call this for a
-// PASSING restore-test — the archive is what makes the tier not-due, so recording one for a failed
-// run would retire the archive unproven.
-func (s *RestoreTestState) RecordSuccess(target, archive string, t time.Time) error {
+// RecordSuccess stamps a tier as proven at t, naming the ARCHIVE that passed, the TIER the run
+// reported, and what it verified. Only call this for a PASSING restore-test — the archive is what
+// makes the tier not-due, so recording one for a failed run would retire the archive unproven.
+//
+// ONLY SUCCESSES ARE PERSISTED, AND THE ASYMMETRY IS DELIBERATE (R-189 §8.1). Say it here because
+// the next reader will notice failures are absent and try to "fix" it:
+//
+//	a SUCCESS suppresses future work — a proven archive is never re-tested, so a lost proof leaves
+//	the system quietly less tested than it believes. It must survive a restart.
+//
+//	a FAILURE causes future work — a failing tier stays due and is retried at the next evaluation,
+//	so a lost failure heals itself within one interval. Persisting it would do the opposite of
+//	helping: a healed tier would keep reporting a failure that is no longer true.
+func (s *RestoreTestState) RecordSuccess(target, archive, tier, verified string, t time.Time) error {
 	if target == "" {
 		return nil
 	}
 	s.mu.Lock()
 	defer s.mu.Unlock()
-	s.last[target] = provenTier{Archive: archive, At: t.UTC()}
+	s.last[target] = provenTier{Archive: archive, Tier: tier, Verified: verified, At: t.UTC()}
 	return s.saveLocked()
 }
 
@@ -138,7 +180,13 @@ func (s *RestoreTestState) ProvenArchive(target string) (string, bool) {
 	return p.Archive, true
 }
 
-// Snapshot returns a copy of the last-proven TIMES — for the host-report gauge.
+// Snapshot returns a copy of the last-proven TIMES.
+//
+// It carried the comment "for the host-report gauge" from the day it was written and **had no caller
+// at all** until R-189 — a seam built and never wired, and an invariant asserted in a comment with
+// nothing pinning it, in one method. The host report is now fed by ProvenRestoreTests below, which
+// carries the archive and the tier that a bare timestamp cannot. This stays for callers that want
+// only the times; if it acquires none, delete it rather than let it claim a purpose again.
 func (s *RestoreTestState) Snapshot() map[string]time.Time {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -149,6 +197,41 @@ func (s *RestoreTestState) Snapshot() map[string]time.Time {
 	return out
 }
 
+// ProvenRestoreTests renders the persisted proofs as host-report entries — the R-189 fix.
+//
+// It satisfies hub.RestoreTestReporter's shape, so the collector can merge these with the in-memory
+// results. What it emits is a RE-REPORT of a run that really happened, not a synthesis:
+//
+//   - `Pass` is true because ONLY successes are stored (RecordSuccess is the sole writer);
+//   - `SourceArchive`, `SourceTier`, `Verified` and `TestedAt` are the values that run reported;
+//   - the run mechanics (scratch VMID, duration, warnings) are NOT re-invented. An absent duration
+//     is not a claim; a fabricated one would be.
+//
+// A record that cannot be reported honestly is omitted rather than padded — see provenTier.reportable.
+// **A tier with no usable proof produces NO entry**: an unproven tier reading as proven would be a
+// worse defect than the one this fixes.
+func (s *RestoreTestState) ProvenRestoreTests(context.Context) []hub.RestoreTest {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := make([]hub.RestoreTest, 0, len(s.last))
+	for _, p := range s.last {
+		if !p.reportable() {
+			continue
+		}
+		out = append(out, hub.RestoreTest{
+			SourceArchive: p.Archive,
+			SourceTier:    p.Tier,
+			Pass:          true,
+			Verified:      p.Verified,
+			TestedAt:      p.At.UTC().Format(time.RFC3339),
+		})
+	}
+	// Deterministic order: the report is compared byte-wise by the contract test, and Go's map
+	// iteration is randomised.
+	sort.Slice(out, func(i, j int) bool { return out[i].SourceTier < out[j].SourceTier })
+	return out
+}
+
 // OldestFirst orders targets by "least recently proven first"; never-proven sorts FIRST.
 //
 // This is the operator's 2026-07-26 ruling (Option 1): self-balancing, no new config knob, and it
@@ -185,7 +268,10 @@ func (s *RestoreTestState) OldestFirst(targets []string) []string {
 func (s *RestoreTestState) saveLocked() error {
 	raw := make(map[string]provenTierJSON, len(s.last))
 	for target, p := range s.last {
-		raw[target] = provenTierJSON{Archive: p.Archive, ProvenAt: p.At.UTC().Format(time.RFC3339)}
+		raw[target] = provenTierJSON{
+			Archive: p.Archive, Tier: p.Tier, Verified: p.Verified,
+			ProvenAt: p.At.UTC().Format(time.RFC3339),
+		}
 	}
 	data, err := json.MarshalIndent(raw, "", "  ")
 	if err != nil {

internal/backup/rotation_test.go

@@ -303,11 +303,11 @@ func TestOldestFirst_Ordering(t *testing.T) {
 			t.Fatalf("unexpected: %v", got)
 		}
 	}
-	_ = st.RecordSuccess("local", "local:backup/a.tar.zst", now)
+	_ = st.RecordSuccess("local", "local:backup/a.tar.zst", "local", "boot+running", now)
 	if got := st.OldestFirst([]string{"local", "felhom-pbs"}); got[0] != "felhom-pbs" {
 		t.Fatalf("a never-proven tier must sort before a proven one; got %v", got)
 	}
-	_ = st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/b", now.Add(time.Hour))
+	_ = st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/b", "pbs", "boot+running", now.Add(time.Hour))
 	if got := st.OldestFirst([]string{"local", "felhom-pbs"}); got[0] != "local" {
 		t.Fatalf("the least recently proven must sort first; got %v", got)
 	}
@@ -318,8 +318,8 @@ func TestOldestFirst_Ordering(t *testing.T) {
 func TestOldestFirst_DeterministicOnTies(t *testing.T) {
 	st := NewRestoreTestState(filepath.Join(t.TempDir(), "rt.json"))
 	now := time.Now().UTC()
-	_ = st.RecordSuccess("b-tier", "b:archive", now)
-	_ = st.RecordSuccess("a-tier", "a:archive", now)
+	_ = st.RecordSuccess("b-tier", "b:archive", "local", "boot+running", now)
+	_ = st.RecordSuccess("a-tier", "a:archive", "local", "boot+running", now)
 	for i := 0; i < 20; i++ {
 		if got := st.OldestFirst([]string{"b-tier", "a-tier"}); got[0] != "a-tier" {
 			t.Fatalf("tie-break must be deterministic; iteration %d gave %v", i, got)
@@ -334,7 +334,7 @@ func TestRestoreTestState_PersistenceAndCorruption(t *testing.T) {
 	now := time.Now().UTC().Truncate(time.Second)
 
 	st := NewRestoreTestState(path)
-	if err := st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/x", now); err != nil {
+	if err := st.RecordSuccess("felhom-pbs", "felhom-pbs:backup/ct/9201/x", "pbs", "boot+running", now); err != nil {
 		t.Fatal(err)
 	}
 	reopened := NewRestoreTestState(path)

internal/backup/runner.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log/slog"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -22,6 +23,10 @@ type BackupAPI interface {
 	StorageContent(ctx context.Context, store string) ([]proxmox.StorageContent, error)
 	// ListStorage enumerates storages (name+type) — used to scope local-only retention (never prune PBS).
 	ListStorage(ctx context.Context) ([]proxmox.Storage, error)
+	// NodeStorage is GET /nodes/{node}/storage — the storages WITH live usage (avail/used). R-685's space
+	// preflight reads free space HERE: ListStorage (GET /storage) is the cluster DEFINITIONS and carries no
+	// usage at all — measured live 2026-09-24 on demo-hp, where reading it let a backup through.
+	NodeStorage(ctx context.Context) ([]proxmox.Storage, error)
 	// TaskLogTail reads trailing task-log lines — used to read the ACTUAL vzdump mode
 	// (PVE may downgrade a requested snapshot to stop for a stopped guest — spike B1).
 	TaskLogTail(ctx context.Context, upid string, limit int) ([]string, error)
@@ -170,6 +175,16 @@ func (r *BackupRunner) backup(ctx context.Context, vmid int, onSnapshot func())
 		rec.UncoveredVolumes = []string{}
 	}
 
+	// R-685 (v0.134.0): will the new archive FIT on a local target? Asked before anything runs, so a
+	// target that cannot hold it is a named SKIP with the numbers, not a nightly "No space left on
+	// device" that only the vzdump log explains (demo-hp, every night from 2026-09-23 — R-684).
+	if ok, why := r.spaceFits(ctx, vmid); !ok {
+		rec.Error = BackupSkipNoSpacePrefix + why
+		rec.DurationSeconds = time.Since(start).Seconds()
+		r.logger.Warn("backup SKIPPED by the space preflight (R-685) — nothing was started", "vmid", vmid, "target", r.target, "reason", why)
+		return rec, fmt.Errorf("backup: %s", rec.Error)
+	}
+
 	upid, err := r.api.Vzdump(ctx, proxmox.VzdumpOptions{
 		VMID: vmid, Storage: r.target, Mode: r.mode, Notes: r.notes,
 		PruneBackups: r.localPruneSpec(ctx), // local target → keep-last=N; PBS/unknown → "" (no prune)
@@ -217,6 +232,56 @@ func (r *BackupRunner) backup(ctx context.Context, vmid int, onSnapshot func())
 	return rec, nil
 }
 
+// BackupSkipNoSpacePrefix starts a backup record's Error when the space preflight refused (R-685) — a
+// stable prefix the controller's page and the hub can key on.
+const BackupSkipNoSpacePrefix = "skipped: not enough space: "
+
+// Space preflight margins (R-685): the new archive is predicted as the newest archive of this guest on the
+// target × backupSpaceGrowth, plus backupSpaceFloorBytes of headroom for the host. MEASURED 2026-09-24:
+// demo-hp 9201's archives grew 5.8 → 6.2 → 6.9 → 7.6 GB in four nights (+10 % a night at worst), so 1.25
+// covers two nights' growth. PVE prunes old archives only AFTER a successful backup, so the free space
+// must hold the new archive while every kept one still exists.
+const (
+	backupSpaceGrowth     = 1.25
+	backupSpaceFloorBytes = int64(1) << 30
+)
+
+// spaceFits answers whether a new archive of vmid fits on a LOCAL (non-PBS) target. It FAILS OPEN — a
+// backup is the thing being protected, so an unreadable storage, an unknown type or a first backup (no
+// previous archive to size from) proceeds and says so; only a POSITIVE "it does not fit" refuses.
+func (r *BackupRunner) spaceFits(ctx context.Context, vmid int) (bool, string) {
+	// NodeStorage, never ListStorage: only the node view carries avail (see BackupAPI.NodeStorage).
+	stores, err := r.api.NodeStorage(ctx)
+	if err != nil {
+		r.logger.Warn("backup: space preflight could not read storage usage — proceeding (fail-open)", "target", r.target, "err", err)
+		return true, ""
+	}
+	var st *proxmox.Storage
+	for i := range stores {
+		if stores[i].Storage == r.target {
+			st = &stores[i]
+			break
+		}
+	}
+	if st == nil || st.Type == "pbs" || st.Avail <= 0 {
+		return true, "" // PBS dedups and has its own lifecycle; an unknown avail never refuses
+	}
+	_, last, err := r.latestArchive(ctx, vmid)
+	if err != nil || last <= 0 {
+		r.logger.Info("backup: space preflight has no previous archive to size from — proceeding", "vmid", vmid, "target", r.target)
+		return true, ""
+	}
+	need := int64(float64(last)*backupSpaceGrowth) + backupSpaceFloorBytes
+	if st.Avail >= need {
+		r.logger.Info("backup: space preflight passed", "vmid", vmid, "target", r.target, "last_archive_bytes", last, "need_bytes", need, "avail_bytes", st.Avail)
+		return true, ""
+	}
+	return false, fmt.Sprintf("%s has %s free; the last archive of guest %d was %s, so a new one needs about %s (old archives are removed only after a successful backup)",
+		r.target, humanGiB(st.Avail), vmid, humanGiB(last), humanGiB(need))
+}
+
+func humanGiB(b int64) string { return fmt.Sprintf("%.1f GiB", float64(b)/(1<<30)) }
+
 // watchForSnapshot polls the running backup's task log until it sees the storage-snapshot marker
 // (→ onSnapshot once) or the requested mode is reported as `stop` (→ downgraded; the marker will
 // never come, so stop watching) or ctx is cancelled (backup finished). Best-effort: a log-read
@@ -292,12 +357,58 @@ func (r *BackupRunner) PickSettledRestoreCandidateOn(ctx context.Context, target
 	if err != nil {
 		return "", time.Time{}, err
 	}
+	// R-727 (v0.138.0): on an ENCRYPTED storage, only archives written with THIS storage's key are this box's.
+	// Measured 2026-09-30 on a fresh box for a returning customer: the PBS namespace still held two archives
+	// of earlier boxes (same guest id 9201, same token), the newest settled one was an earlier box's, and the
+	// test failed `wrong key` every evaluation. The archive carries no host id; its key fingerprint is the
+	// discriminator (PVE's content `encrypted`, the storage's `encryption-key`). A lookup failure returns
+	// the error — the tier reads UNKNOWN, never "nothing to prove".
+	ownKey, err := r.storageKeyFingerprint(ctx, target)
+	if err != nil {
+		return "", time.Time{}, fmt.Errorf("reading the key fingerprint of storage %s: %w", target, err)
+	}
 	var best string
 	var bestCTime int64 = -1
+	known := map[int]bool{} // vmid → the guest exists on this node (asked once per vmid per pick)
 	for _, e := range contents {
 		if e.Content != "backup" {
 			continue
 		}
+		// R-689 (v0.135.0): only a backup OF A GUEST is a restore-test candidate. demo-hp keeps its golden
+		// template in `local:backup/` — content "backup", 654 MB, plausibly complete — and it was picked as
+		// the newest settled archive every 6 h and failed extractconfig (403) each time, while the guest's
+		// real archive went untested.
+		if ok, why := guestBackupArchive(e); !ok {
+			r.noteNotAGuestBackupOnce(e, why)
+			continue
+		}
+		if ownKey != "" && !strings.EqualFold(e.Encrypted, ownKey) {
+			r.noteNotAGuestBackupOnce(e, fmt.Sprintf("written by another box (key %s, this box's key %s) — not this box's proof", shortFP(e.Encrypted), shortFP(ownKey)))
+			continue
+		}
+		// R-689 (v0.136.0): … OF A GUEST THAT STILL EXISTS here. Measured on demo-hp 2026-09-27 right after
+		// v0.135.0: with the golden skipped, the pick fell to `vzdump-lxc-9100-2026_08_21…`, a leftover of a
+		// guest deleted in August — proving nothing about any guest this box runs. "Does not exist" skips the
+		// archive; any OTHER lookup failure is returned, so the tier reads UNKNOWN, never "nothing to prove".
+		if _, seen := known[e.VMID]; !seen {
+			_, err := r.api.GuestConfig(ctx, e.VMID)
+			switch {
+			case err == nil:
+				known[e.VMID] = true
+			case strings.Contains(err.Error(), "does not exist"), strings.Contains(err.Error(), "permission denied"):
+				// v0.137.0: PVE answers 403 "permission denied at /vms/<id>" — not "does not exist" — for a guest
+				// outside the agent's ACL (the `felhom` pool). Measured on demo-hp after v0.136.0: the deleted
+				// guest 9100's archive made the local tier UNKNOWN every evaluation. A guest the agent cannot
+				// read is not one it manages; its archive is not a candidate.
+				known[e.VMID] = false
+			default:
+				return "", time.Time{}, fmt.Errorf("checking whether guest %d still exists: %w", e.VMID, err)
+			}
+		}
+		if !known[e.VMID] {
+			r.noteNotAGuestBackupOnce(e, fmt.Sprintf("guest %d does not exist on this node or is not one this agent manages", e.VMID))
+			continue
+		}
 		if !notAfter.IsZero() && e.CTime > notAfter.Unix() {
 			continue // not settled yet — a newer archive is not a reason to re-prove an older one
 		}
@@ -520,5 +631,79 @@ func ToHubRestoreTest(res reconcile.RestoreTestResult, testedAt time.Time) hub.R
 	if res.Err != nil {
 		rt.Error = res.Err.Error()
 	}
+	if res.SkipReason != "" { // R-672: the space preflight refused — reported, never a pass
+		rt.Pass = false
+		rt.Skipped = true
+		rt.Error = res.SkipReason
+	}
 	return rt
 }
+
+// guestBackupArchive reports whether a storage entry is a whole-guest backup of a known guest — a
+// `vzdump-<type>-<vmid>-…` file on a dir storage, or a `backup/{ct,vm}/<vmid>/<time>` snapshot on a PBS
+// datastore — whose vmid the storage itself reports. Anything else in a backup content type (a golden
+// template, a hand-copied tarball) is not a backup of a guest and is never restore-tested (R-689).
+// Pure, so the rule is unit-tested without a storage.
+func guestBackupArchive(e proxmox.StorageContent) (bool, string) {
+	if e.VMID <= 0 {
+		return false, "not a backup of a guest (the storage reports no vmid)"
+	}
+	vol := e.VolID
+	if i := strings.Index(vol, ":"); i >= 0 {
+		vol = vol[i+1:]
+	}
+	vol = strings.TrimPrefix(vol, "backup/")
+	vmid := strconv.Itoa(e.VMID)
+	switch {
+	case strings.HasPrefix(vol, "vzdump-lxc-"+vmid+"-"), strings.HasPrefix(vol, "vzdump-qemu-"+vmid+"-"):
+		return true, ""
+	case strings.HasPrefix(vol, "ct/"+vmid+"/"), strings.HasPrefix(vol, "vm/"+vmid+"/"):
+		return true, ""
+	}
+	return false, "not a vzdump archive or a PBS snapshot of guest " + vmid
+}
+
+// noteNotAGuestBackupOnce logs, once per volid, that a backup-content entry is not a restore-test
+// candidate because it is not a backup of a guest (R-689). INFO, not WARN: a golden template kept in
+// the backup directory is the operator's, and not a fault.
+func (r *BackupRunner) noteNotAGuestBackupOnce(e proxmox.StorageContent, why string) {
+	r.rejectedMu.Lock()
+	if r.rejected == nil {
+		r.rejected = map[string]struct{}{}
+	}
+	_, seen := r.rejected[e.VolID]
+	if !seen {
+		r.rejected[e.VolID] = struct{}{}
+	}
+	r.rejectedMu.Unlock()
+	if !seen {
+		r.logger.Info("backup: restore-test skips an entry that is not a backup of a guest",
+			"target", r.target, "volid", e.VolID, "size_bytes", e.Size, "reason", why)
+	}
+}
+
+// storageKeyFingerprint returns the named storage's client-side encryption key fingerprint ("" when the
+// storage is not encrypted — a local dir holds only this box's own vzdumps).
+func (r *BackupRunner) storageKeyFingerprint(ctx context.Context, target string) (string, error) {
+	sts, err := r.api.ListStorage(ctx)
+	if err != nil {
+		return "", err
+	}
+	for _, st := range sts {
+		if st.Storage == target {
+			return strings.TrimSpace(st.EncryptionKey), nil
+		}
+	}
+	return "", nil
+}
+
+// shortFP is the first 8 bytes of a key fingerprint, for a log line.
+func shortFP(fp string) string {
+	if fp == "" {
+		return "none"
+	}
+	if len(fp) > 23 {
+		return fp[:23] + "…"
+	}
+	return fp
+}

internal/backup/schedule.go

@@ -180,7 +180,15 @@ func (s *Scheduler) tick(ctx context.Context) {
 		return
 	}
 	if archive == "" {
-		s.logger.Debug("backup: restore-test not due this evaluation")
+		// A POSITIVE OBSERVABLE, at INFO, and this is not noise — it is standing rule 3.
+		//
+		// Before R-86 every tick ran a heavy restore-test, so the scheduler was audible by
+		// construction. Now "nothing is due" is the NORMAL outcome, and at DEBUG it is silent: an
+		// empty journal would be equally consistent with a healthy loop and with a dead goroutine,
+		// which is the exact shape the R-88 watcher was retired for. One line per evaluation is four
+		// lines a day at the 6h default, and it names each tier's verdict so the answer to "why did
+		// nothing run last night?" is in the log rather than in a re-derivation.
+		s.logger.Info("backup: restore-test evaluated — nothing due", "verdicts", s.verdictSummary(ctx))
 		return
 	}
 
@@ -200,9 +208,11 @@ func (s *Scheduler) tick(ctx context.Context) {
 	spec := s.spec(ctx, archive)
 	spec.Archive = archive
 	res := s.runner.RunRestoreTest(ctx, spec)
-	if res.Skipped {
+	if res.Skipped && res.SkipReason == "" {
 		return // already logged by the engine (no free scratch VMID)
 	}
+	// R-672: a SPACE refusal is the test's result — reported (pass=false, the reason as the error),
+	// never dropped and never a pass. It earns no rotation credit, so the tier stays due.
 	rt := ToHubRestoreTest(res, s.now())
 	s.store.RecordRestoreTest(rt)
 	// Rotation credit is given ONLY on success. A failing tier must keep sorting first, or a tier
@@ -210,7 +220,11 @@ func (s *Scheduler) tick(ctx context.Context) {
 	if rt.Pass && s.rtState != nil && target != "" {
 		// R-86: the ARCHIVE is recorded, not merely the time — that is what makes the tier
 		// not-due until a NEWER archive settles, and what makes a proof survive a restart.
-		if err := s.rtState.RecordSuccess(target, archive, s.now()); err != nil {
+		// R-189: the TIER and what was VERIFIED go with it, so the proof can be RE-REPORTED after a
+		// restart. Both come from the run's own result, never re-derived — `rt.SourceTier` is what
+		// this run was actually judged as, and deriving it later would need a storage lookup that
+		// can fail on the one path where failing means mislabelling a proof.
+		if err := s.rtState.RecordSuccess(target, archive, rt.SourceTier, rt.Verified, s.now()); err != nil {
 			s.logger.Warn("backup: could not persist the restore-test proof state", "target", target, "err", err)
 		}
 	}

internal/backup/store.go

@@ -10,8 +10,22 @@ import (
 // Store holds the agent's LATEST backup result per target and the latest restore-test
 // result — the point-in-time state the host-report surfaces. It is updated by the backup
 // runner + the restore-test scheduler/selftest and read by the collector via the hub
-// BackupReporter / RestoreTestReporter seams. In-memory (lost on restart; the cadence
-// re-populates) and mutex-guarded for the concurrent collector vs scheduler access.
+// BackupReporter / RestoreTestReporter seams. In-memory and mutex-guarded for the concurrent
+// collector vs scheduler access.
+//
+// **"lost on restart; the cadence re-populates" — that sentence used to be here and it is now
+// FALSE for restore-tests (R-189, 2026-08-03).** It was true while a timer re-tested every tier
+// daily. Under R-86's per-archive due-check the agent will NOT re-test an archive it has already
+// proven, so a proof lost to a restart is not repeated until the next archive generation — a week on
+// the offsite tier — and the hub reports that tier unproven throughout. Observed, not predicted: a
+// real 14.5 GB offsite restore passed, the agent was restarted 2 m 43 s later for a deploy, and two
+// consecutive host-reports carried `0 restore-tests`.
+//
+// The durable half is `RestoreTestState` (on disk, per tier, with the archive) and the collector
+// merges the two — see hub.ProvenRestoreTestReporter. This store remains the ONLY place a FAILURE is
+// recorded, and that asymmetry is deliberate: a failing tier stays due and is retried, so a lost
+// failure heals itself, while a lost success leaves the system quietly less tested than it believes.
+// Backups are unaffected — their freshness has a ground truth on the storage (R-84).
 type Store struct {
 	mu       sync.Mutex
 	byTarget map[string]hub.Backup // latest backup per target id

internal/capability/manifest.go

@@ -123,6 +123,9 @@ var manifest = []Capability{
 	{"dnsmasq-install", "dnsmasq package install", "/usr/bin/apt-get", []string{"install", "-y", "-q", "dnsmasq"}, false, ""},
 	{"dnsmasq-write", "dnsmasq drop-in write", "/usr/bin/install", []string{"-m", "0644", "/tmp/felhom-resolver-x.conf", "/etc/dnsmasq.d/felhom-x.conf"}, false, ""},
 	{"dnsmasq-enable", "dnsmasq enable", "/usr/bin/systemctl", []string{"enable", "--now", "dnsmasq"}, false, ""},
+
+	// ---- OS updates, guest fast lane (`11` §5.4.1; the wrapper holds every rule) ----
+	{"osapply-run", "OS update wrapper (guest fast lane)", "/usr/local/sbin/felhom-os-apply", []string{"--plan", "/var/lib/felhom-agent/os/plan-x.json"}, false, ""},
 	{"dnsmasq-reload", "dnsmasq reload", "/usr/bin/systemctl", []string{"reload", "dnsmasq"}, false, ""},
 	{"dnsmasq-restart", "dnsmasq restart (LAN-DNS self-heal)", "/usr/bin/systemctl", []string{"restart", "dnsmasq"}, false, ""},
 	{"dnsmasq-rm", "dnsmasq drop-in remove (decommission)", "/usr/bin/rm", []string{"-f", "/etc/dnsmasq.d/felhom-x.conf"}, false, ""},

internal/config/config.go

@@ -345,6 +345,12 @@ type BackupConfig struct {
 	// between an archive settling and its proof, and the retry rate of a tier whose restore-test
 	// keeps failing. See defaultRestoreTestEvalInterval for the measurement it was chosen from.
 	RestoreTestEvalIntervalSeconds int `json:"restore_test_eval_interval_seconds"`
+	// RestoreTestSpaceFactor / RestoreTestSpaceReserveGiB are the restore-test's space margin (R-672,
+	// v0.133.0): a test starts only when the target storage has free ≥ restored × factor + reserve,
+	// `restored` being the UNCOMPRESSED size. 0/unset → 1.2 and 5 GiB. A test config may raise them to
+	// watch the refusal (the brief's live case a).
+	RestoreTestSpaceFactor     float64 `json:"restore_test_space_factor,omitempty"`
+	RestoreTestSpaceReserveGiB float64 `json:"restore_test_space_reserve_gib,omitempty"`
 	// RestoreTestSettleSeconds is how long an archive must have sat on its tier before it is a
 	// restore-test candidate (R-86); 0 → default (24h), negative → 0 (no settle requirement).
 	// Restore-testing an archive a backup is still writing proves nothing about the backup that
@@ -615,6 +621,20 @@ func (b BackupConfig) RestoreTestEvalInterval() time.Duration {
 	}
 }
 
+// RestoreTestSpace returns the restore-test's space margin (R-672): factor (≥ 1) and reserve bytes.
+// Unset or out-of-range → 1.2 and 5 GiB.
+func (b BackupConfig) RestoreTestSpace() (factor float64, reserveBytes int64) {
+	factor = b.RestoreTestSpaceFactor
+	if factor < 1 {
+		factor = 1.2
+	}
+	reserveBytes = int64(b.RestoreTestSpaceReserveGiB * float64(1<<30))
+	if reserveBytes <= 0 {
+		reserveBytes = 5 << 30
+	}
+	return factor, reserveBytes
+}
+
 // RestoreTestSettle returns how long an archive must have sat before it is a restore-test
 // candidate (R-86): a positive value as-is, negative → 0 (no settle requirement), 0 → the default.
 //

internal/escrow/recover.go

@@ -0,0 +1,210 @@
+package escrow
+
+import (
+	"context"
+	"errors"
+	"fmt"
+)
+
+// R-199 links 6→8 — fetch this host's own sealed identity blob, open it with the customer's recovery
+// code R, and hand back EXACTLY ONE field: the offsite restic repository password.
+//
+// WHY ONLY ONE FIELD. The bundle also carries the Cloudflare tunnel token, the PBS access token and
+// the WG private key (see IdentityBundle). The caller in this flow — the in-guest controller, one
+// trust tier down — needs none of them, and returning them would widen the blast radius of a
+// controller compromise for no gain. Narrowing costs nothing here and is not recoverable later.
+//
+// WHY R NEVER TOUCHES DISK. `UnwrapIdentity` stages the BLOB and the recovered plaintext in a
+// `MkdirTemp` that it removes, and feeds R through the pty; R itself is never written. This wrapper
+// keeps that property: it takes R as an argument, passes it straight through, and holds no copy.
+// Callers must clear their own reference (the `R = ""` discipline in cmd/felhom-agent).
+//
+// The errors below are DISTINCT on purpose. "could not fetch", "no blob", "wrong code" and "the blob
+// predates the field" are FOUR different situations for the operator and only one of them is a fault.
+//
+// ⚠ THERE WERE THREE, AND THE FOURTH WAS THE DEFECT (R-224, 2026-08-06). This comment said "three"
+// and named "no blob", "wrong code" and "predates the field" — while a FAILED FETCH was wrapped as an
+// anonymous error and fell through the caller's `default` branch into the wrong-code message. So a
+// hub that could not be reached was reported to the customer as a bad recovery code.
+//
+// Measured live on 2026-08-05 (CAMPAIGN-11 F3): with the hub REJECTed at the appliance's firewall and
+// a CORRECT current recovery code, the customer was told the code did not open their package — in
+// 0.0556 s, when a real unseal costs ~1 s of scrypt. The agent's own log carried the truth the whole
+// time (`escrow: fetching the sealed bundle: hub: transport error: … no route to host`) and the HTTP
+// boundary threw it away.
+//
+// The discriminator therefore has to be a VALUE, not a log line — that is what ErrBundleFetch is.
+
+var (
+	// ErrBundleFetch — the sealed bundle could not be FETCHED (the hub refused, was unreachable, or
+	// the transport failed). **The recovery code was never used**, so nothing about it is known and
+	// nothing may be said about it. Wraps the underlying cause for the operator log; carries no secret.
+	ErrBundleFetch = errors.New("escrow: the sealed bundle could not be fetched")
+	// ErrNoEscrowBlob — the hub holds no sealed bundle for this host. Not a fault: no ceremony has run.
+	ErrNoEscrowBlob = errors.New("escrow: the hub holds no sealed identity bundle for this host (no ceremony has run)")
+	// ErrNoResticPassword — the bundle opened, but carries no repository password. Real and expected
+	// for a pre-fork-4 blob (agent < v0.77.0, 2026-07-09): the field did not exist and CANNOT be
+	// retro-fitted, because R is never retained. Distinguished from a wrong code so the operator is
+	// not sent hunting for a mistyped recovery code that was typed correctly.
+	ErrNoResticPassword = errors.New("escrow: the recovered bundle carries NO offsite repository password (a pre-fork-4 blob — the field did not exist when it was sealed and cannot be retro-fitted)")
+	// ErrCodeOpensRetained — the code did NOT open the package the hub currently holds, and DID open a
+	// RETAINED (earlier) one. R-311.
+	//
+	// ⚠ THIS IS NOT A FAILURE OF THE CUSTOMER'S. It is the single most important distinction on this
+	// path, because until 2026-08-12 it was indistinguishable from a mistype and was reported as one.
+	// The screen could only say "it may be a typo, or it may be an older code, and we cannot tell them
+	// apart from here" — and it could not tell them apart because NOTHING EVER LOOKED. Now something
+	// looks, so the sentence can stop hedging.
+	//
+	// It carries no material and no code: only WHICH earlier package opened, by its supersession date,
+	// which is the one fact the customer needs to recognise it.
+	ErrCodeOpensRetained = errors.New("escrow: the recovery code did not open the CURRENT sealed package, but it DID open a retained earlier one")
+)
+
+// RetainedMatch says which retained package a code opened. Returned inside RetainedOpenedError; it
+// carries no secret — not the code, not the bundle, not the repository password.
+type RetainedMatch struct {
+	// SupersededAt is when this package stopped being the current one (hub-supplied, RFC3339-ish).
+	// It is what the recovery screen shows so the customer can recognise which code they are holding.
+	SupersededAt string
+	// KeyFingerprint is the escrow key fingerprint of that package — operator-log material only.
+	KeyFingerprint string
+	// Index is the hub's position label within ONE response. Not durable; do not persist it.
+	Index int
+	// HasResticPassword is false when the retained package opened but carries no repository password
+	// (a pre-fork-4 seal). The code is still CORRECT; the history behind it still cannot be reopened.
+	// Collapsing this into "recoverable" would repeat R-202's mistake on a new surface.
+	HasResticPassword bool
+}
+
+// RetainedOpenedError wraps ErrCodeOpensRetained with the match. Callers classify with errors.Is on
+// the sentinel and read the detail with errors.As.
+type RetainedOpenedError struct {
+	Match RetainedMatch
+}
+
+func (e *RetainedOpenedError) Error() string {
+	return ErrCodeOpensRetained.Error() + " (superseded_at=" + e.Match.SupersededAt + ")"
+}
+func (e *RetainedOpenedError) Unwrap() error { return ErrCodeOpensRetained }
+
+// BlobFetcher yields this host's own opaque identity-escrow blob. present=false is a clean "none".
+// An interface-free func field keeps this package free of any dependency on the hub client.
+type BlobFetcher func(ctx context.Context) (blob []byte, present bool, err error)
+
+// RetainedBlob is one retained sealed package as the recoverer sees it: opaque bytes plus the labels
+// needed to name it. No secret.
+type RetainedBlob struct {
+	Blob           []byte
+	SupersededAt   string
+	KeyFingerprint string
+	Index          int
+}
+
+// RetainedFetcher yields this host's RETAINED sealed packages, newest-superseded first. An empty
+// slice is a clean "none". R-311.
+type RetainedFetcher func(ctx context.Context) (blobs []RetainedBlob, unopenable int, err error)
+
+// OffsiteKeyRecoverer is the assembled links 6→8. Construct it with a fetcher; call it with R.
+type OffsiteKeyRecoverer struct {
+	Fetch BlobFetcher
+	// FetchRetained is OPTIONAL and consulted ONLY after the current package has refused the code.
+	// nil keeps the pre-R-311 behaviour exactly: a refusal stays a refusal. That is deliberate — an
+	// agent wired without it must not behave differently from one that has no retained packages.
+	FetchRetained RetainedFetcher
+	// MaxRetainedTried bounds the scrypt work a single wrong code can cost. Each attempt is ~1 s of
+	// KDF by design, so an unbounded loop over a long supersession history would turn one wrong code
+	// into a minutes-long hang on the customer's screen. 0 means the built-in default.
+	MaxRetainedTried int
+}
+
+// defaultMaxRetainedTried — six attempts is ~6 s worst case, which is a slow screen and not a hang.
+const defaultMaxRetainedTried = 6
+
+// RecoverOffsiteRepoPassword fetches, unseals and extracts. It returns ONLY the repository password.
+//
+// A WRONG RECOVERY CODE FAILS CLOSED at the scrypt KDF inside UnwrapIdentity — `age -d` exits
+// non-zero and emits no plaintext, so there is no partial result and nothing is written anywhere.
+// That property is the crypto's, not a check here, which is why this function has no "validate R"
+// step to get wrong.
+//
+// NOTHING IS LOGGED BY THIS FUNCTION and no error it returns contains R, the password, or blob bytes.
+func (r OffsiteKeyRecoverer) RecoverOffsiteRepoPassword(ctx context.Context, recoveryCode string) (string, error) {
+	if r.Fetch == nil {
+		return "", fmt.Errorf("escrow: recoverer has no blob fetcher configured")
+	}
+	if recoveryCode == "" {
+		return "", fmt.Errorf("escrow: the recovery code is required")
+	}
+	blob, present, err := r.Fetch(ctx)
+	if err != nil {
+		// R-224: joined with ErrBundleFetch so the caller can classify by VALUE. The cause stays
+		// wrapped for the operator log; neither carries a secret. Before this, the fetch failure was
+		// an anonymous error and the local-api handler's `default` branch reported it to the customer
+		// as a wrong recovery code.
+		return "", fmt.Errorf("%w: %w", ErrBundleFetch, err)
+	}
+	if !present || len(blob) == 0 {
+		return "", ErrNoEscrowBlob
+	}
+	bundle, err := UnwrapIdentityBundle(ctx, blob, recoveryCode)
+	if err != nil {
+		// R-311 — BEFORE calling this a wrong code, ask whether it is the RIGHT code for an EARLIER
+		// package. The engine fails closed identically either way, so the two are indistinguishable
+		// from the unwrap alone; the only way to tell is to try. Until this existed nobody tried, and
+		// the screen said so out loud ("innen nem tudjuk megkülönböztetni őket") — a true sentence
+		// about our own incuriosity, read by the customer as a statement about their code.
+		if m, ok := r.tryRetained(ctx, recoveryCode); ok {
+			return "", &RetainedOpenedError{Match: m}
+		}
+		return "", err // the fail-closed "the recovery code did not unwrap…" message; no secret in it
+	}
+	if bundle.ResticRepoPassword == "" {
+		return "", ErrNoResticPassword
+	}
+	return bundle.ResticRepoPassword, nil
+}
+
+// tryRetained reports whether the code opens one of this host's RETAINED packages, and which.
+//
+// FAILURE HERE IS SILENT AND MEANS "NO", NEVER "YES" and never a different verdict for the caller. A
+// hub that cannot answer, a route an older hub does not have, a malformed blob — each leaves the
+// original refusal standing, unchanged. That is the fail-safe direction: the worst outcome of this
+// function breaking is the behaviour we had before it existed.
+//
+// NOTHING IS LOGGED HERE and no return value carries the code, a bundle or a password.
+func (r OffsiteKeyRecoverer) tryRetained(ctx context.Context, recoveryCode string) (RetainedMatch, bool) {
+	if r.FetchRetained == nil {
+		return RetainedMatch{}, false
+	}
+	blobs, _, err := r.FetchRetained(ctx)
+	if err != nil || len(blobs) == 0 {
+		return RetainedMatch{}, false
+	}
+	limit := r.MaxRetainedTried
+	if limit <= 0 {
+		limit = defaultMaxRetainedTried
+	}
+	for i, rb := range blobs {
+		if i >= limit {
+			break
+		}
+		if len(rb.Blob) == 0 {
+			continue
+		}
+		bundle, uerr := UnwrapIdentityBundle(ctx, rb.Blob, recoveryCode)
+		if uerr != nil {
+			continue // this one is not the customer's; try the next
+		}
+		return RetainedMatch{
+			SupersededAt:   rb.SupersededAt,
+			KeyFingerprint: rb.KeyFingerprint,
+			Index:          rb.Index,
+			// A retained package can itself predate the repository-password field. The code is still
+			// correct and must be told so — but the history behind it still cannot be reopened, and
+			// saying otherwise would be a promise this path cannot keep.
+			HasResticPassword: bundle.ResticRepoPassword != "",
+		}, true
+	}
+	return RetainedMatch{}, false
+}

internal/escrow/recover_retained_test.go

@@ -0,0 +1,230 @@
+package escrow
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+)
+
+// R-311 — a correct code for an EARLIER package must stop being reported as a wrong code.
+//
+// These use REAL age crypto, like the R-199 tests beside them, because the whole point is that the
+// two situations are indistinguishable AT THE UNWRAP: both fail closed on the current package. A
+// faked unwrap would prove nothing about the thing that was actually broken.
+
+const testR2 = "another correct horse battery staple sedative anaconda wobbly kingdom placard"
+
+func retainedFetcherFor(blobs ...RetainedBlob) RetainedFetcher {
+	return func(context.Context) ([]RetainedBlob, int, error) { return blobs, 0, nil }
+}
+
+// THE ONE THAT MATTERS. The customer holds the code for a package we superseded. Yesterday this
+// returned the fail-closed refusal and the screen told them to check their typing.
+//
+// RED-PROOF: remove the `if m, ok := r.tryRetained(...)` block from RecoverOffsiteRepoPassword →
+// the wrong-code error returns instead → this FAILS, and the lie is back in exactly those words.
+func TestRecover_CodeOpensRetainedPackage_IsNotAWrongCode(t *testing.T) {
+	ensureAge(t)
+	const oldPW = "aaaa567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "cccc567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+	retained := sealBundle(t, IdentityBundle{ResticRepoPassword: oldPW}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{
+			Blob: retained, SupersededAt: "2026-08-12 15:18:55", KeyFingerprint: "7e:a6:af", Index: 0,
+		}),
+	}.RecoverOffsiteRepoPassword(context.Background(), testR) // the OLD code
+
+	if err == nil {
+		t.Fatal("recovery succeeded — it must NOT return a password for a retained package on this path")
+	}
+	if !errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatalf("err = %v, want ErrCodeOpensRetained — a correct code for an earlier package was "+
+			"classified as something else, which is how it became 'check your typing'", err)
+	}
+	var ro *RetainedOpenedError
+	if !errors.As(err, &ro) {
+		t.Fatalf("err does not carry a RetainedOpenedError: %v", err)
+	}
+	if ro.Match.SupersededAt != "2026-08-12 15:18:55" {
+		t.Errorf("SupersededAt = %q — the screen needs this date to name the package", ro.Match.SupersededAt)
+	}
+	if !ro.Match.HasResticPassword {
+		t.Error("HasResticPassword = false, but the retained bundle carried one")
+	}
+	// The error must not leak the code, the password or the bundle.
+	for _, secret := range []string{testR, oldPW} {
+		if containsStr(err.Error(), secret) {
+			t.Fatalf("the error text leaks a secret")
+		}
+	}
+}
+
+// SCENARIO A — the ordinary recovery is untouched, and it must not even ASK for retained packages.
+// If the current package opens, the customer is not in this story at all.
+//
+// RED-PROOF: move the tryRetained call above the successful-unwrap return → the fetcher runs → this
+// FAILS on the "must not be consulted" assertion.
+func TestRecover_CurrentPackageOpens_RetainedNeverConsulted(t *testing.T) {
+	ensureAge(t)
+	const pw = "bbbb567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: pw}, testR)
+
+	consulted := false
+	got, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			consulted = true
+			return nil, 0, nil
+		},
+	}.RecoverOffsiteRepoPassword(context.Background(), testR)
+
+	if err != nil {
+		t.Fatalf("the ordinary recovery broke: %v", err)
+	}
+	if got != pw {
+		t.Fatalf("recovered password is not the sealed one")
+	}
+	if consulted {
+		t.Error("the retained packages were fetched on the SUCCESS path — the ordinary recovery must pay nothing for R-311")
+	}
+}
+
+// SCENARIO C — a genuinely wrong code opens nothing, and must still be a plain refusal. The new
+// branch must not become a way to encourage a customer who mistyped.
+//
+// RED-PROOF: make tryRetained return (RetainedMatch{}, true) unconditionally → a wrong code is
+// reported as opening an earlier package → this FAILS.
+func TestRecover_WrongCode_StaysAPlainRefusal(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "cccc567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+	retained := sealBundle(t, IdentityBundle{ResticRepoPassword: "dddd567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch:         fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{Blob: retained, SupersededAt: "2026-08-01 00:00:00"}),
+	}.RecoverOffsiteRepoPassword(context.Background(), "totally wrong words that open nothing at all here")
+
+	if err == nil {
+		t.Fatal("a wrong code succeeded")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a WRONG code was reported as opening a retained package — that would encourage a mistype")
+	}
+}
+
+// FAIL-SAFE — if the retained lookup itself fails, the original refusal must stand UNCHANGED. The
+// worst outcome of this feature breaking is the behaviour we had before it.
+//
+// RED-PROOF: make tryRetained propagate the fetch error instead of returning false → the customer
+// gets a new, unexplained failure mode → this FAILS.
+func TestRecover_RetainedFetchFails_OriginalRefusalStands(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "eeee567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			return nil, 0, fmt.Errorf("hub exploded")
+		},
+	}.RecoverOffsiteRepoPassword(context.Background(), testR2)
+
+	if err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a failed retained lookup was reported as 'opens a retained package'")
+	}
+	if containsStr(err.Error(), "hub exploded") {
+		t.Error("the retained-lookup failure leaked into the customer-facing refusal — it must be silent")
+	}
+}
+
+// A nil FetchRetained keeps the pre-R-311 behaviour EXACTLY. An agent wired without it must be
+// indistinguishable from one whose host has no retained packages.
+//
+// RED-PROOF: remove the `if r.FetchRetained == nil` guard → nil-deref panic → this FAILS.
+func TestRecover_NilRetainedFetcher_IsPreR311Behaviour(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "ffff567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+
+	_, err := OffsiteKeyRecoverer{Fetch: fetcherFor(current)}.RecoverOffsiteRepoPassword(context.Background(), testR2)
+	if err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a recoverer with no retained fetcher claimed a retained package opened")
+	}
+}
+
+// A retained package that predates the repository-password field: the code is CORRECT and must be
+// said to be correct, but HasResticPassword must be false so the screen does not promise a recovery
+// that cannot produce a password (the R-202 lesson, on a new surface).
+//
+// RED-PROOF: hardcode HasResticPassword: true → this FAILS.
+func TestRecover_RetainedOpensButPredatesTheField(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "1111567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+	// No ResticRepoPassword at all — the pre-fork-4 shape.
+	retained := sealBundle(t, IdentityBundle{TunnelToken: "T", PBSToken: "P"}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch:         fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{Blob: retained, SupersededAt: "2026-08-04 07:20:08"}),
+	}.RecoverOffsiteRepoPassword(context.Background(), testR)
+
+	if !errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatalf("err = %v, want ErrCodeOpensRetained — the code IS correct", err)
+	}
+	var ro *RetainedOpenedError
+	if !errors.As(err, &ro) {
+		t.Fatalf("no RetainedOpenedError: %v", err)
+	}
+	if ro.Match.HasResticPassword {
+		t.Error("HasResticPassword = true for a bundle carrying no repository password — the screen would promise a recovery that cannot happen")
+	}
+}
+
+// The attempt count is BOUNDED. Each unwrap is ~1 s of scrypt by design, so an unbounded loop turns
+// one wrong code into a minutes-long hang on the customer's screen.
+//
+// RED-PROOF: remove the `if i >= limit { break }` → all 10 are tried → this FAILS on the count.
+func TestRecover_RetainedAttemptsAreBounded(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "2222567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+	junk := sealBundle(t, IdentityBundle{ResticRepoPassword: "3333567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+
+	tried := 0
+	blobs := make([]RetainedBlob, 0, 10)
+	for i := 0; i < 10; i++ {
+		blobs = append(blobs, RetainedBlob{Blob: junk, SupersededAt: "2026-08-01 00:00:00", Index: i})
+	}
+	rec := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			tried++
+			return blobs, 0, nil
+		},
+		MaxRetainedTried: 2,
+	}
+	// A code that opens NEITHER the current package nor any retained one.
+	if _, err := rec.RecoverOffsiteRepoPassword(context.Background(), "a code that opens nothing whatsoever in this test"); err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if tried != 1 {
+		t.Errorf("the retained list was fetched %d times, want exactly 1", tried)
+	}
+}
+
+func containsStr(hay, needle string) bool {
+	return len(needle) > 0 && len(hay) >= len(needle) && (func() bool {
+		for i := 0; i+len(needle) <= len(hay); i++ {
+			if hay[i:i+len(needle)] == needle {
+				return true
+			}
+		}
+		return false
+	})()
+}

internal/escrow/recover_test.go

@@ -0,0 +1,267 @@
+package escrow
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// R-199 links 6→8, with REAL crypto (age is present on the build/demo host; ensureAge skips
+// elsewhere). These are the unit half of the session's question — "is the repository password
+// actually recoverable from the sealed bundle" — and the live half is the same equality on hardware.
+
+const testR = "correct horse battery staple sedative anaconda wobbly kingdom placard yodel"
+
+func sealBundle(t *testing.T, b IdentityBundle, r string) []byte {
+	t.Helper()
+	blob, err := WrapIdentityBundle(context.Background(), b, r)
+	if err != nil {
+		t.Fatalf("WrapIdentityBundle: %v", err)
+	}
+	return blob
+}
+
+func fetcherFor(blob []byte) BlobFetcher {
+	return func(context.Context) ([]byte, bool, error) { return blob, true, nil }
+}
+
+// Scenario A (unit) — the recovered repository password is BYTE-IDENTICAL to the sealed one, and it
+// is the REPOSITORY password rather than some other field of a bundle that also parses.
+//
+// RED-PROOF: return bundle.PBSToken (or TunnelToken, or WGPrivateKey) instead of
+// bundle.ResticRepoPassword → a plausible-looking bundle yields a non-matching key → this FAILS.
+// That mutation is the shape of the bug that would otherwise ship silently, because every one of
+// those fields is a non-empty string that looks like a secret.
+func TestRecoverOffsiteRepoPassword_ReturnsTheRepositoryPassword(t *testing.T) {
+	ensureAge(t)
+	const repoPW = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	blob := sealBundle(t, IdentityBundle{
+		TunnelToken:        "TUNNEL-TOKEN-NOT-THE-ANSWER",
+		PBSToken:           "PBS-TOKEN-NOT-THE-ANSWER",
+		WGPrivateKey:       "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+		ResticRepoPassword: repoPW,
+	}, testR)
+
+	got, err := (OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}).RecoverOffsiteRepoPassword(context.Background(), testR)
+	if err != nil {
+		t.Fatalf("recover: %v", err)
+	}
+	if got != repoPW {
+		t.Fatalf("the recovered key is not the sealed repository password (len %d vs %d) — a different "+
+			"field of the bundle was returned", len(got), len(repoPW))
+	}
+	// Belt: it must not be any of the OTHER fields, so a future refactor cannot satisfy the check
+	// above by coincidence.
+	for _, other := range []string{"TUNNEL-TOKEN-NOT-THE-ANSWER", "PBS-TOKEN-NOT-THE-ANSWER", "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="} {
+		if got == other {
+			t.Fatalf("the recoverer returned the wrong bundle field")
+		}
+	}
+}
+
+// Scenario B — a WRONG recovery code fails closed, the failure names no secret, and nothing is
+// written. The fail-closed property is the crypto's (age's scrypt KDF), which is why there is no
+// validation step here to get wrong — the test pins that it stays that way.
+func TestRecoverOffsiteRepoPassword_WrongCodeFailsClosed(t *testing.T) {
+	ensureAge(t)
+	const repoPW = "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+	blob := sealBundle(t, IdentityBundle{TunnelToken: "t", PBSToken: "p", ResticRepoPassword: repoPW}, testR)
+
+	got, err := (OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}).RecoverOffsiteRepoPassword(context.Background(), "not the recovery code at all")
+	if err == nil {
+		t.Fatal("a wrong recovery code MUST fail — a plausible-but-wrong bundle is the one outcome the design forbids")
+	}
+	if got != "" {
+		t.Fatalf("a failed unseal returned %d bytes — there must be no partial result", len(got))
+	}
+	// The error may name the step; it may never name a secret.
+	for _, secret := range []string{repoPW, testR, "not the recovery code at all"} {
+		if strings.Contains(err.Error(), secret) {
+			t.Fatalf("the failure message leaked a secret: %v", err)
+		}
+	}
+}
+
+// A bundle with no repository password is its OWN answer, not a wrong-code error. Sealed before
+// fork-4 (agent < v0.77.0) the field did not exist; sending the operator to re-check a correctly
+// typed recovery code would be the wrong instruction.
+func TestRecoverOffsiteRepoPassword_PreForkFourBundle(t *testing.T) {
+	ensureAge(t)
+	blob := sealBundle(t, IdentityBundle{TunnelToken: "t", PBSToken: "p"}, testR)
+
+	_, err := (OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}).RecoverOffsiteRepoPassword(context.Background(), testR)
+	if !errors.Is(err, ErrNoResticPassword) {
+		t.Fatalf("a pre-fork-4 bundle must report its own error, got %v", err)
+	}
+}
+
+// Scenario D at this layer — no blob is a clean, distinguishable answer.
+func TestRecoverOffsiteRepoPassword_NoBlob(t *testing.T) {
+	rec := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) { return nil, false, nil }}
+	_, err := rec.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if !errors.Is(err, ErrNoEscrowBlob) {
+		t.Fatalf("absent blob must yield ErrNoEscrowBlob, got %v", err)
+	}
+}
+
+// Scenario F — R persists NOWHERE. TMPDIR is redirected into the test's own directory, the unseal is
+// run for real, and the whole tree is then walked: no file may contain R (or the recovered password),
+// and the staging directory the unseal creates must be gone.
+//
+// RED-PROOF: write R to a temp file anywhere in the flow (e.g. add
+// `os.WriteFile(filepath.Join(work,"r"), []byte(recoveryCode), 0o600)` inside UnwrapIdentity before
+// its defer removes the dir — or simply drop that defer and let the plaintext staging survive) → the
+// walk finds it → this FAILS.
+func TestRecoverOffsiteRepoPassword_RLeavesNoTrace(t *testing.T) {
+	ensureAge(t)
+	const repoPW = "1111111111111111111111111111111111111111111111111111111111111111"
+	tmp := t.TempDir()
+	t.Setenv("TMPDIR", tmp) // os.MkdirTemp honours this — every staging dir lands under the walk
+
+	const wrongR = "wrong code entirely"
+	blob := sealBundle(t, IdentityBundle{TunnelToken: "t", PBSToken: "p", ResticRepoPassword: repoPW}, testR)
+	if _, err := (OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}).RecoverOffsiteRepoPassword(context.Background(), testR); err != nil {
+		t.Fatalf("recover: %v", err)
+	}
+	// A failed unseal must leave nothing either — exercise both paths before walking.
+	_, _ = (OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}).RecoverOffsiteRepoPassword(context.Background(), wrongR)
+
+	// THE PRIMARY ASSERTION IS EMPTINESS, not content. A content scan alone is defeatable by a later
+	// call OVERWRITING the leaked file with a different secret — which is exactly how the first
+	// version of this test passed its own red-proof while R sat on disk. Nothing in this test writes
+	// under TMPDIR, so after both calls the tree must contain no files at all.
+	var survivors []string
+	err := filepath.Walk(tmp, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info == nil || info.IsDir() || path == tmp {
+			return nil
+		}
+		survivors = append(survivors, strings.TrimPrefix(path, tmp))
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(survivors) > 0 {
+		t.Fatalf("the unseal left %d file(s) behind under TMPDIR: %v — R, the sealed blob and the "+
+			"recovered plaintext all pass through there and none of them may outlive the call", len(survivors), survivors)
+	}
+	// Defence in depth: any secret that DOES appear anywhere is named, for every code used.
+	_ = filepath.Walk(tmp, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info == nil || info.IsDir() {
+			return nil
+		}
+		body, rerr := os.ReadFile(path)
+		if rerr != nil {
+			return nil
+		}
+		for label, secret := range map[string]string{"R": testR, "a wrong R": wrongR, "the repository password": repoPW} {
+			if strings.Contains(string(body), secret) {
+				t.Errorf("%s survived on disk at %s", label, path)
+			}
+		}
+		return nil
+	})
+	// And the staging directories are gone, not merely free of secrets.
+	entries, _ := os.ReadDir(tmp)
+	for _, e := range entries {
+		if e.IsDir() && strings.HasPrefix(e.Name(), "felhom-idesc-") {
+			t.Fatalf("an unseal staging directory survived: %s", e.Name())
+		}
+	}
+}
+
+// A fetch failure surfaces as a fetch failure, not as a wrong-code error — the operator must not be
+// sent to re-read their recovery code because the hub was unreachable.
+//
+// ⚠ THIS TEST WAS GREEN THROUGHOUT THE DEFECT IT DESCRIBES (R-224, 2026-08-06). Its sentence is
+// exactly right and it did not prevent anything, for two reasons worth keeping:
+//
+//  1. **It asserted the MECHANISM, one layer below the consequence.** It checked this package's error
+//     STRING. The merge happened one layer up, in the local-api handler's `default` branch, which
+//     answered a fetch failure with "the recovery code did not open the sealed bundle". The customer
+//     never sees this string; they see that one. The project's own rule — prefer the test that asserts
+//     the CONSEQUENCE (does the customer get blamed?) over the one that asserts the MECHANISM (is the
+//     error distinct here?) — names this case precisely.
+//  2. **It asserted on TEXT.** `strings.Contains(err.Error(), …)` cannot be consumed by a caller, so
+//     it pinned something no production code could branch on. The distinction it checked was real and
+//     unusable.
+//
+// It now asserts the SENTINEL, which is what the handler branches on, and its consequence-level twin
+// lives in `internal/localapi/escrow_recover_class_test.go` where the status is asserted.
+func TestRecoverOffsiteRepoPassword_FetchErrorIsDistinct(t *testing.T) {
+	rec := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) {
+		return nil, false, errors.New("hub: connection refused")
+	}}
+	_, err := rec.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if err == nil || !errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a fetch failure must classify as ErrBundleFetch, got %v", err)
+	}
+	if errors.Is(err, ErrNoEscrowBlob) || errors.Is(err, ErrNoResticPassword) {
+		t.Fatal("a transport failure must not masquerade as a content verdict")
+	}
+}
+
+// ── R-224 — A FAILED FETCH IS NOT A WRONG CODE ──────────────────────────────────────────────────
+//
+// CAMPAIGN-11 F3 measured the consequence of these two being indistinguishable: with the hub
+// firewalled off and a CORRECT current recovery code, the customer was told the code did not open
+// their package, in 0.0556 s — no unseal was attempted at all.
+//
+// The pair below is the whole point. Asserting only the first would pass with a `return ErrBundleFetch`
+// stuck on every error path, which is the same defect pointing the other way.
+func TestRecoverOffsiteRepoPassword_FetchFailureIsClassifiedAsFetch(t *testing.T) {
+	boom := errors.New("hub: transport error: dial tcp 37.191.56.193:443: connect: no route to host")
+	r := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) { return nil, false, boom }}
+
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if err == nil {
+		t.Fatal("a failing fetch must return an error")
+	}
+	// RED-PROOF: drop the `%w: %w` join in RecoverOffsiteRepoPassword (return the bare wrapped cause,
+	// as it was before R-224) → this FAILS, and the local-api handler falls back to the wrong-code
+	// message exactly as it did on 2026-08-05.
+	if !errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a failed fetch must classify as ErrBundleFetch, got %v", err)
+	}
+	// The underlying cause survives for the operator log.
+	if !errors.Is(err, boom) {
+		t.Fatalf("the fetch cause must stay wrapped for the operator, got %v", err)
+	}
+	// And it must NOT be mistaken for either of the bundle-content situations.
+	if errors.Is(err, ErrNoEscrowBlob) || errors.Is(err, ErrNoResticPassword) {
+		t.Fatalf("a transport failure is neither of the bundle-content errors: %v", err)
+	}
+}
+
+// The other half: a genuinely wrong code must NOT classify as a fetch failure, or the fix trades one
+// misattribution for its mirror image and the customer is told the hub is down when they mistyped.
+func TestRecoverOffsiteRepoPassword_WrongCodeIsNotAFetchFailure(t *testing.T) {
+	ensureAge(t)
+	blob := sealBundle(t, IdentityBundle{ResticRepoPassword: "0123456789abcdef"}, testR)
+	r := OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}
+
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(),
+		"wrong horse battery staple sedative anaconda wobbly kingdom placard yodel")
+	if err == nil {
+		t.Fatal("a wrong recovery code must fail closed")
+	}
+	if errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a wrong code must NOT classify as a fetch failure, got %v", err)
+	}
+}
+
+// A clean "the hub holds nothing" keeps its own identity too — it is not a fetch failure, and the
+// customer must not be told the hub was unreachable when it answered perfectly well.
+func TestRecoverOffsiteRepoPassword_AbsentBlobIsNotAFetchFailure(t *testing.T) {
+	r := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) { return nil, false, nil }}
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if !errors.Is(err, ErrNoEscrowBlob) {
+		t.Fatalf("an absent blob must stay ErrNoEscrowBlob, got %v", err)
+	}
+	if errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("an absent blob is not a fetch FAILURE, got %v", err)
+	}
+}

internal/httpx/transport.go

@@ -0,0 +1,59 @@
+// Package httpx holds the one HTTP-transport default this repo may not lose.
+//
+// Every client here pins TLS — PBS and PVE by leaf-cert SHA-256, the hub by an optional CA file —
+// so none of them can use http.DefaultTransport and each hand-rolls its own. Hand-rolling silently
+// discards DefaultTransport's settings, and one of them is load-bearing:
+//
+//	Transport: &http.Transport{TLSClientConfig: tlsCfg}   // IdleConnTimeout == 0 == NO timeout
+//
+// A zero IdleConnTimeout means idle keep-alive connections are retained FOREVER, not "use a sane
+// default". Combined with a client that is rebuilt on a schedule and dropped (pbsTargetsFromPVE
+// builds a fresh pbs.Client per cycle), every cycle strands one connection that nothing will ever
+// close: the abandoned Transport becomes unreachable but its persistConn read-loop goroutine keeps
+// the socket alive, and an unreachable Transport does not close its connections.
+//
+// Measured cost, live: 388 established connections accumulated on ep0's PBS proxy between
+// 2026-08-18 09:51:22Z and 2026-08-20 08:02:13Z — 194 from each of the two boxes, held open on BOTH
+// sides, one per agent poll cycle, on a proxy whose descriptor ceiling is 65536. See R-344 and
+// felhom.eu/documentation/audits/SPIKE-ep0-established-connections-2026-08-20.md.
+package httpx
+
+import (
+	"crypto/tls"
+	"net/http"
+	"time"
+)
+
+// DefaultIdleConnTimeout is how long an idle keep-alive connection is retained before it is closed.
+//
+// It is 90s because that is http.DefaultTransport's own value: the fix for R-344 restores a
+// standard-library default rather than inventing a number, so there is nothing here to tune and
+// nothing to justify. It is comfortably shorter than every cadence that drives these clients (the
+// 15-minute live-snapshot collect and the 6-hour verify loop), so a connection abandoned by one
+// cycle is closed long before the next.
+const DefaultIdleConnTimeout = 90 * time.Second
+
+// NewTransport builds a FRESH *http.Transport pinned to tlsCfg, with the idle-connection timeout
+// applied.
+//
+// Fresh, never shared: each caller pins a different endpoint, and a shared transport would pool
+// connections across differently pinned servers. Reusing http.DefaultTransport for the same reason
+// is not an option — it would drop the pin entirely.
+//
+// idleConnTimeout <= 0 means USE THE DEFAULT. It deliberately does not mean "no timeout": no-timeout
+// is the bug this package exists to prevent, and an unset field must never be able to reintroduce
+// it. Callers pass their configured value straight through; only tests pass a short one.
+//
+// Only IdleConnTimeout is set. The other DefaultTransport settings this transport also lacks
+// (MaxIdleConns, TLSHandshakeTimeout, ExpectContinueTimeout) are deliberately left alone: none of
+// them accumulates anything, every client bounds its whole request with http.Client.Timeout, and
+// widening the change would have made the R-344 measurement unattributable.
+func NewTransport(tlsCfg *tls.Config, idleConnTimeout time.Duration) *http.Transport {
+	if idleConnTimeout <= 0 {
+		idleConnTimeout = DefaultIdleConnTimeout
+	}
+	return &http.Transport{
+		TLSClientConfig: tlsCfg,
+		IdleConnTimeout: idleConnTimeout,
+	}
+}

internal/httpx/transport_test.go

@@ -0,0 +1,74 @@
+package httpx
+
+import (
+	"crypto/tls"
+	"net/http"
+	"testing"
+	"time"
+)
+
+// TestNewTransport_ZeroMeansDefaultNeverForever is the whole point of this package.
+//
+// http.Transport's zero IdleConnTimeout means "retain idle connections FOREVER". Any code path that
+// can reach that zero reintroduces R-344, so an unset, zero or negative value must all land on the
+// default. If someone later "simplifies" NewTransport by passing the argument straight through,
+// this fails.
+func TestNewTransport_ZeroMeansDefaultNeverForever(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		in   time.Duration
+		want time.Duration
+	}{
+		{"zero", 0, DefaultIdleConnTimeout},
+		{"negative", -time.Hour, DefaultIdleConnTimeout},
+		{"explicit short value (tests)", 50 * time.Millisecond, 50 * time.Millisecond},
+		{"explicit long value", time.Hour, time.Hour},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := NewTransport(&tls.Config{MinVersion: tls.VersionTLS12}, tc.in).IdleConnTimeout
+			if got != tc.want {
+				t.Fatalf("IdleConnTimeout = %v, want %v", got, tc.want)
+			}
+			if got == 0 {
+				t.Fatal("IdleConnTimeout is 0 — that is 'never expire', which is the R-344 defect itself")
+			}
+		})
+	}
+}
+
+// TestDefaultIdleConnTimeout_MatchesTheStandardLibrary pins the number to its justification.
+//
+// 90s is not a tuned value; it is what http.DefaultTransport uses. Reading it off the standard
+// library rather than hardcoding 90 means the constant cannot drift away from the reason given for
+// it in the package doc.
+func TestDefaultIdleConnTimeout_MatchesTheStandardLibrary(t *testing.T) {
+	std, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		t.Skip("http.DefaultTransport is not an *http.Transport in this Go build")
+	}
+	if DefaultIdleConnTimeout != std.IdleConnTimeout {
+		t.Fatalf("DefaultIdleConnTimeout = %v but http.DefaultTransport uses %v — the doc comment's justification no longer holds",
+			DefaultIdleConnTimeout, std.IdleConnTimeout)
+	}
+}
+
+// TestNewTransport_IsFreshEveryCall guards the pooling property the pinning relies on.
+//
+// Each caller pins a DIFFERENT endpoint. A shared transport would pool connections across
+// differently pinned servers, so returning a package-level singleton would be a security change
+// dressed as a tidy-up.
+func TestNewTransport_IsFreshEveryCall(t *testing.T) {
+	a := NewTransport(&tls.Config{MinVersion: tls.VersionTLS12}, 0)
+	b := NewTransport(&tls.Config{MinVersion: tls.VersionTLS12}, 0)
+	if a == b {
+		t.Fatal("NewTransport returned the SAME transport twice — connections would be pooled across differently pinned endpoints")
+	}
+}
+
+// TestNewTransport_KeepsTheTLSConfig — the transport gains a field; it must lose nothing.
+func TestNewTransport_KeepsTheTLSConfig(t *testing.T) {
+	cfg := &tls.Config{MinVersion: tls.VersionTLS12, InsecureSkipVerify: true} //nolint:gosec // test only
+	if got := NewTransport(cfg, 0).TLSClientConfig; got != cfg {
+		t.Fatalf("TLSClientConfig = %p, want the config passed in (%p) — the pin would be dropped", got, cfg)
+	}
+}

internal/hub/client.go

@@ -15,6 +15,8 @@ import (
 	"time"
 
 	"gitea.dooplex.hu/admin/felhom-agent/internal/config"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/httpx"
 )
 
 const reportPath = "/api/v1/host-report"
@@ -49,8 +51,11 @@ func NewClient(cfg config.HubConfig, logger *slog.Logger) (*Client, error) {
 		tlsCfg.RootCAs = pool
 	}
 	hc := &http.Client{
-		Timeout:   time.Duration(cfg.TimeoutSeconds) * time.Second,
-		Transport: &http.Transport{TLSClientConfig: tlsCfg},
+		Timeout: time.Duration(cfg.TimeoutSeconds) * time.Second,
+		// R-344, consistency only: this client is built ONCE per process, so it never accumulated
+		// and contributed nothing to the ep0 leak. It carried the same missing default, which over
+		// a tunnel is how one idle connection survives long enough to fail on next use.
+		Transport: httpx.NewTransport(tlsCfg, 0),
 	}
 	return newClient(cfg.URL, cfg.APIKey, cfg.HostID, hc, logger), nil
 }
@@ -307,3 +312,140 @@ func tail(b []byte, max int) string {
 	}
 	return s
 }
+
+// IdentityEscrowResponse mirrors GET /api/v1/hosts/{host_id}/escrow (hub >= v0.94.0, R-199).
+// Present=false is a CLEAN answer, not a fault: the host simply has no sealed bundle yet.
+type IdentityEscrowResponse struct {
+	HostID            string `json:"host_id"`
+	Present           bool   `json:"present"`
+	IdentityEscrowB64 string `json:"identity_escrow_b64"`
+}
+
+// FetchIdentityEscrow reads back THIS host's own opaque identity-escrow blob (R-199 link 6 — the
+// mirror of UploadEscrow, self-scoped server-side by the per-host key). The bytes are ciphertext: they
+// are useless without the customer's recovery code R, which neither the hub nor this agent ever holds.
+//
+// It is the ONLY retrieval this client performs, and it is deliberately narrow — no directive, no
+// K-escrow, no key rotation. The operator-driven DR path (recovery-mode re-enroll) is a different
+// endpoint with a different gate and is not reached from here.
+//
+// Errors are typed (transport vs HTTP) and never include the bearer token. The BLOB is never logged —
+// only its length.
+func (c *Client) FetchIdentityEscrow(ctx context.Context) (*IdentityEscrowResponse, error) {
+	if c.hostID == "" {
+		return nil, fmt.Errorf("hub: FetchIdentityEscrow requires a configured host_id")
+	}
+	url := c.baseURL + "/api/v1/hosts/" + c.hostID + "/escrow"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("hub: building escrow-fetch request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, &TransportError{Err: err}
+	}
+	defer resp.Body.Close()
+
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, &HTTPError{StatusCode: resp.StatusCode, BodyTail: tail(raw, 256)}
+	}
+	var out IdentityEscrowResponse
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("hub: decoding escrow fetch: %w", err)
+	}
+	return &out, nil
+}
+
+// RetainedEscrowPackage is one RETAINED (superseded) sealed identity package. The blob is ciphertext
+// and is useless without R. `SupersededAt` is the only thing here a human ever sees — it is what lets
+// the recovery screen name WHICH earlier package a code belongs to.
+type RetainedEscrowPackage struct {
+	Index             int    `json:"index"`
+	SupersededAt      string `json:"superseded_at"`
+	KeyFingerprint    string `json:"key_fingerprint"`
+	IdentityEscrowB64 string `json:"identity_escrow_b64"`
+}
+
+// RetainedEscrowResponse mirrors GET /api/v1/hosts/{host_id}/escrow/retained (hub >= v0.103.0, R-311).
+//
+// UnopenableCount is NOT noise. It counts retained packages the hub holds whose key material is absent
+// (every pre-v0.93.0 row): on a box with those and nothing else, a perfectly correct old recovery code
+// opens nothing, and the reason is a defect of ours. A caller that ignores this number will tell such a
+// customer their code is wrong — the exact failure this whole chain exists to stop.
+type RetainedEscrowResponse struct {
+	HostID          string                  `json:"host_id"`
+	Count           int                     `json:"count"`
+	UnopenableCount int                     `json:"unopenable_count"`
+	TruncatedCount  int                     `json:"truncated_count"`
+	Packages        []RetainedEscrowPackage `json:"packages"`
+}
+
+// FetchRetainedIdentityEscrow reads back THIS host's RETAINED sealed identity packages (R-311 —
+// the retained siblings of FetchIdentityEscrow, self-scoped server-side by the same per-host key).
+//
+// SEPARATE FROM FetchIdentityEscrow ON PURPOSE. The ordinary recovery must not pay for this call, and
+// must not fail because of it: the current package is tried first and alone, and this is reached only
+// after that has refused. A hub too old to know this route answers 404, which is a CLEAN "none" here
+// and must never be reported as a failed recovery.
+func (c *Client) FetchRetainedIdentityEscrow(ctx context.Context) (*RetainedEscrowResponse, error) {
+	if c.hostID == "" {
+		return nil, fmt.Errorf("hub: FetchRetainedIdentityEscrow requires a configured host_id")
+	}
+	url := c.baseURL + "/api/v1/hosts/" + c.hostID + "/escrow/retained"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("hub: building retained-escrow request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, &TransportError{Err: err}
+	}
+	defer resp.Body.Close()
+
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	if resp.StatusCode == http.StatusNotFound {
+		// A hub older than v0.103.0 has no such route. That is "no retained packages", not a fault —
+		// returning an error here would turn an old hub into a failed recovery on a box whose current
+		// package simply did not open.
+		return &RetainedEscrowResponse{HostID: c.hostID}, nil
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, &HTTPError{StatusCode: resp.StatusCode, BodyTail: tail(raw, 256)}
+	}
+	var out RetainedEscrowResponse
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("hub: decoding retained escrow fetch: %w", err)
+	}
+	return &out, nil
+}
+
+// PostOSReport sends the OS-update leg's report after every run (hub v0.130.0): POST /api/v1/hosts/{id}/os-report.
+// Per-host key, self-scoped on the hub. Errors are typed like RegisterWG's and never include the bearer.
+func (c *Client) PostOSReport(ctx context.Context, body []byte) error {
+	if c.hostID == "" {
+		return fmt.Errorf("hub: PostOSReport requires a configured host_id")
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/api/v1/hosts/"+c.hostID+"/os-report", bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("hub: building os-report request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return &TransportError{Err: err}
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return &HTTPError{StatusCode: resp.StatusCode, BodyTail: tail(raw, 256)}
+	}
+	return nil
+}

internal/hub/cloudflared.go

@@ -2,45 +2,111 @@ package hub
 
 import (
 	"context"
-	"os/exec"
+	"fmt"
 	"strings"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
 )
 
-// CloudflaredProber reports the cloudflared tunnel service health. It is a
-// READ-ONLY probe: the agent does NOT manage or restart cloudflared in this slice
-// (that is the tunnel-management slice — this is the seam for it). Injectable so
-// tests use a fake and never exec.
+// Tunnel states the agent reports (R-841, agent v0.141.0). THREE, never two: a probe that could not ask is
+// `unknown`, which the hub never shows as up or down and never alarms on (R-96 rule 3).
+const (
+	TunnelRunning    = "running"     // the cloudflared container runs AND its readiness check says CONNECTED
+	TunnelNotRunning = "not_running" // stopped / exited / absent, or running but NOT connected (Detail says which)
+	TunnelUnknown    = "unknown"     // the probe could not ask (guest down, pct/sudo error, health still starting)
+)
+
+// CloudflaredProber reports the box's tunnel. Injectable so tests use a fake and never exec.
 type CloudflaredProber interface {
-	// Status returns one of: "active" | "inactive" | "failed" | "unknown".
-	Status(ctx context.Context) (string, error)
+	// Status returns one of the Tunnel* states and a short detail (why not_running / why unknown).
+	Status(ctx context.Context) (status, detail string)
 }
 
-// SystemctlProber runs `systemctl is-active cloudflared`. This is NOT a Privileged
-// (root-CLI) op — `is-active` is non-root readable and is not one of the three
-// proven root exceptions, so it does not go through internal/proxmox.Privileged.
-type SystemctlProber struct {
-	Unit string // defaults to "cloudflared"
+// GuestTunnelProber reads the REAL tunnel: the `cloudflared` container in the box's own customer guest.
+//
+// Before v0.141.0 the agent ran `systemctl is-active cloudflared` on the HOST — a unit that does not exist (cloudflared
+// is a guest container, `11-os-updates.md` C8), so every box reported `inactive` (R-841).
+//
+// It uses ONLY the existing sudoers line `pct exec [0-9]* -- docker inspect -f *` (03 §3): the container's state, exit
+// code and Docker health status. The health status comes from the compose health check controller v0.292.0 adds
+// (`cloudflared tunnel --metrics localhost:20241 ready` → /ready: 200 only with ≥ 1 connection). Measured 2026-10-04:
+// with a wrong token the container stays "running" while /ready answers 503 — so the container state alone would lie.
+// A container with no health check (an older controller) is judged on its state alone, and Detail says so.
+type GuestTunnelProber struct {
+	Runner proxmox.Runner
+	// Guests returns the box's customer guest vmids (running pool guests that bind /mnt/felhom-drives).
+	Guests func(ctx context.Context) ([]int, error)
 }
 
-// Status maps `systemctl is-active` output to the report vocabulary. systemctl
-// exits non-zero for inactive/failed, so the output string is authoritative over
-// the exit code; any exec error (binary missing, etc.) maps to "unknown".
-func (p SystemctlProber) Status(ctx context.Context) (string, error) {
-	unit := p.Unit
-	if unit == "" {
-		unit = "cloudflared"
+const tunnelInspect = `{{.State.Status}}|{{.State.ExitCode}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}`
+
+// Status probes every customer guest and reports the worst state (normally there is exactly one guest).
+func (p GuestTunnelProber) Status(ctx context.Context) (string, string) {
+	if p.Runner == nil || p.Guests == nil {
+		return TunnelUnknown, "no probe wired"
 	}
-	out, _ := exec.CommandContext(ctx, "systemctl", "is-active", unit).Output()
-	switch strings.TrimSpace(string(out)) {
-	case "active":
-		return "active", nil
-	case "failed":
-		return "failed", nil
-	case "inactive", "deactivating", "activating":
-		return "inactive", nil
-	case "":
-		return "unknown", nil // no output → systemctl/exec problem
-	default:
-		return "unknown", nil
+	vmids, err := p.Guests(ctx)
+	if err != nil {
+		return TunnelUnknown, "could not list the customer guest: " + err.Error()
 	}
+	if len(vmids) == 0 {
+		return TunnelUnknown, "no running customer guest"
+	}
+	worst, wdetail := "", ""
+	rank := map[string]int{TunnelRunning: 0, TunnelUnknown: 1, TunnelNotRunning: 2}
+	for _, v := range vmids {
+		out, errOut, err := p.Runner.Run(ctx, "/usr/sbin/pct", "exec", fmt.Sprint(v), "--", "docker", "inspect", "-f", tunnelInspect, "cloudflared")
+		st, d := ClassifyTunnel(string(out), string(errOut), err)
+		if len(vmids) > 1 {
+			d = fmt.Sprintf("guest %d: %s", v, d)
+		}
+		if worst == "" || rank[st] > rank[worst] {
+			worst, wdetail = st, d
+		}
+	}
+	return worst, wdetail
+}
+
+// ClassifyTunnel maps one `docker inspect` answer to a state. Pure; pinned by TestClassifyTunnel.
+func ClassifyTunnel(stdout, stderr string, err error) (string, string) {
+	out := strings.TrimSpace(stdout)
+	if err != nil || out == "" {
+		if strings.Contains(stderr, "No such object") || strings.Contains(stderr, "No such container") {
+			return TunnelNotRunning, "no cloudflared container in the guest"
+		}
+		return TunnelUnknown, "could not ask the guest: " + firstLine(stderr, err)
+	}
+	parts := strings.Split(out, "|")
+	if len(parts) != 3 {
+		return TunnelUnknown, "unreadable docker answer: " + out
+	}
+	state, code, health := parts[0], parts[1], parts[2]
+	if state != "running" {
+		return TunnelNotRunning, fmt.Sprintf("container %s, exit code %s", state, code)
+	}
+	switch health {
+	case "healthy":
+		return TunnelRunning, "connected"
+	case "unhealthy":
+		return TunnelNotRunning, "container running but the tunnel is NOT connected (cloudflared /ready fails)"
+	case "starting":
+		return TunnelUnknown, "container running, readiness check still starting"
+	case "none":
+		return TunnelRunning, "container running (no readiness check on this controller — connection not checked)"
+	}
+	return TunnelUnknown, "unknown health state " + health
+}
+
+func firstLine(stderr string, err error) string {
+	s := strings.TrimSpace(stderr)
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		s = s[:i]
+	}
+	if s == "" && err != nil {
+		s = err.Error()
+	}
+	if len(s) > 160 {
+		s = s[:160]
+	}
+	return s
 }

internal/hub/cloudflared_test.go

@@ -0,0 +1,67 @@
+package hub
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+// R-841: the three states from one `docker inspect` answer. Red-proof: map "unhealthy" to running (the container
+// state alone — what a plain "is it running" probe would say) and the "running but not connected" case fails.
+func TestClassifyTunnel(t *testing.T) {
+	cases := []struct {
+		name, out, errOut string
+		err               error
+		want              string
+		detail            string
+	}{
+		{"connected", "running|0|healthy\n", "", nil, TunnelRunning, "connected"},
+		{"running but not connected", "running|0|unhealthy\n", "", nil, TunnelNotRunning, "NOT connected"},
+		{"stopped", "exited|137|unhealthy\n", "", nil, TunnelNotRunning, "exit code 137"},
+		{"absent", "", "Error: No such object: cloudflared", errors.New("exit status 1"), TunnelNotRunning, "no cloudflared container"},
+		{"still starting", "running|0|starting\n", "", nil, TunnelUnknown, "starting"},
+		{"no health check (older controller)", "running|0|none\n", "", nil, TunnelRunning, "connection not checked"},
+		{"guest not running", "", "CT 9201 not running", errors.New("exit status 255"), TunnelUnknown, "could not ask"},
+		{"sudo refused", "", "sudo: a password is required", errors.New("exit status 1"), TunnelUnknown, "could not ask"},
+	}
+	for _, c := range cases {
+		st, d := ClassifyTunnel(c.out, c.errOut, c.err)
+		if st != c.want || !strings.Contains(d, c.detail) {
+			t.Errorf("%s: got %q (%s), want %q (…%s…)", c.name, st, d, c.want, c.detail)
+		}
+	}
+}
+
+type tunnelRunner struct {
+	calls []string
+	out   map[string]string
+}
+
+func (r *tunnelRunner) Run(_ context.Context, name string, args ...string) ([]byte, []byte, error) {
+	line := name + " " + strings.Join(args, " ")
+	r.calls = append(r.calls, line)
+	return []byte(r.out[args[1]]), nil, nil
+}
+func (r *tunnelRunner) RunStdin(ctx context.Context, _ io.Reader, name string, args ...string) ([]byte, []byte, error) {
+	return r.Run(ctx, name, args...)
+}
+
+// The probe uses EXACTLY the existing sudoers shape `pct exec <vmid> -- docker inspect -f <tmpl> cloudflared`, and
+// with no customer guest it is unknown, never down.
+func TestGuestTunnelProber(t *testing.T) {
+	r := &tunnelRunner{out: map[string]string{"9201": "running|0|healthy"}}
+	p := GuestTunnelProber{Runner: r, Guests: func(context.Context) ([]int, error) { return []int{9201}, nil }}
+	if st, d := p.Status(context.Background()); st != TunnelRunning || d != "connected" {
+		t.Fatalf("got %q %q", st, d)
+	}
+	want := "/usr/sbin/pct exec 9201 -- docker inspect -f " + tunnelInspect + " cloudflared"
+	if len(r.calls) != 1 || r.calls[0] != want {
+		t.Fatalf("command = %q, want %q", r.calls, want)
+	}
+	none := GuestTunnelProber{Runner: r, Guests: func(context.Context) ([]int, error) { return nil, nil }}
+	if st, _ := none.Status(context.Background()); st != TunnelUnknown {
+		t.Fatalf("no guest → %q, want unknown", st)
+	}
+}

internal/hub/collect.go

@@ -47,6 +47,22 @@ type RestoreTestReporter interface {
 	RestoreTests(ctx context.Context) []RestoreTest
 }
 
+// ProvenRestoreTestReporter is the DURABLE half of the restore-test signal (R-189).
+//
+// RestoreTestReporter above is backed by an in-memory store whose own comment used to read "lost on
+// restart; the cadence re-populates". That was true while a timer re-tested every tier daily. It
+// stopped being true on 2026-08-03: under per-archive due-ness the agent will not re-test an archive
+// it has already proven, so a proof lost to a restart is not repeated for a whole archive generation
+// — a week on the offsite tier — and the hub reports the tier unproven the entire time.
+//
+// Observed, not predicted: a real 14.5 GB offsite restore passed at 15:25:14, the agent was restarted
+// 2 m 43 s later for a deploy, and the hub logged `0 restore-tests` on the next two reports.
+//
+// (*backup.RestoreTestState).ProvenRestoreTests satisfies this. nil → the merge is a no-op.
+type ProvenRestoreTestReporter interface {
+	ProvenRestoreTests(ctx context.Context) []RestoreTest
+}
+
 // PBSReporter is the slice-6-Phase-B seam the pbs verify loop plugs into (same pattern).
 // Returns the agent's latest-known PBS snapshot inventory + verify-state. nil → empty.
 type PBSReporter interface {
@@ -79,6 +95,7 @@ type Collector struct {
 	storage      StorageObserver
 	backups      BackupReporter
 	restoreTests RestoreTestReporter
+	provenTests  ProvenRestoreTestReporter
 	pbs          PBSReporter
 	temp         TempReader                                    // slice 9: host CPU/chassis temp (nil-safe → nil temp)
 	capProbe     func(ctx context.Context) []capability.Status // v0.44.0: privileged-capability self-check (nil → empty)
@@ -86,6 +103,7 @@ type Collector struct {
 	addrEnum     AddressEnumerator                             // v0.119.0: host interface enumeration; nil => the REAL one (see collectAddresses)
 	wg           WireguardReporter                             // S3: offsite-tunnel status (nil → stanza omitted)
 	pbsdr        PBSDRReporter                                 // slice 2: PBS DR tier bridge state (nil → stanza omitted)
+	ctrlSup      ControllerSupervisorReporter                  // R-523: in-guest controller supervisor (nil → stanza omitted)
 	guestNet     GuestNetReporter                              // R-54: per-guest network watchdog (nil → stanza omitted)
 	selfUpdate   SelfUpdateReporter                            // D1: agent self-update pending status (nil → false)
 	mgmtPlane    MgmtPlaneReporter                             // G1: management-plane health (nil → stanza omitted)
@@ -178,6 +196,17 @@ func (c *Collector) SetPBSDRReporter(p PBSDRReporter) *Collector {
 	return c
 }
 
+// ControllerSupervisorReporter is the R-523 seam (satisfied by *localapi.Server).
+type ControllerSupervisorReporter interface {
+	ControllerSupervisorStatus(ctx context.Context) *ControllerSupervisorStatus
+}
+
+// SetControllerSupervisorReporter wires the R-523 controller supervisor as a report source (nil-safe).
+func (c *Collector) SetControllerSupervisorReporter(r ControllerSupervisorReporter) *Collector {
+	c.ctrlSup = r
+	return c
+}
+
 // SetGuestNetReporter wires the R-54 guest-network watchdog as a report source (nil-safe → stanza
 // omitted). Returns the collector for chaining.
 func (c *Collector) SetGuestNetReporter(g GuestNetReporter) *Collector {
@@ -251,7 +280,7 @@ func (c *Collector) Collect(ctx context.Context) (*HostReport, error) {
 		PBSSnapshots:   c.collectPBSSnapshots(ctx),
 
 		AuditTail:       []AuditEntry{},
-		Cloudflared:     Cloudflared{Status: c.cloudflaredStatus(ctx)},
+		Cloudflared:     c.cloudflared(ctx),
 		Capabilities:    c.capabilities(ctx),
 		LeafFingerprint: c.leafFP,
 		Addresses:       c.collectAddresses(),
@@ -268,6 +297,10 @@ func (c *Collector) Collect(ctx context.Context) (*HostReport, error) {
 	if c.pbsdr != nil {
 		report.PBSDR = c.pbsdr.PBSDRStatus(ctx)
 	}
+	// R-523: controller supervisor record (nil reporter = not wired → stanza omitted).
+	if c.ctrlSup != nil {
+		report.ControllerSupervisor = c.ctrlSup.ControllerSupervisorStatus(ctx)
+	}
 	// R-54: guest-network watchdog state (nil reporter = feature not wired → stanza omitted).
 	if c.guestNet != nil {
 		report.GuestNet = c.guestNet.GuestNetStatus(ctx)
@@ -427,16 +460,90 @@ func (c *Collector) collectBackups(ctx context.Context) []Backup {
 	return []Backup{}
 }
 
+// collectRestoreTests merges the in-memory result with the PERSISTED per-tier proofs (R-189).
+//
+// The rule is ONE ENTRY PER TIER, NEWEST WINS, and it falls out of what each source means rather
+// than from a preference between them:
+//
+//   - the in-memory store holds this process's latest run, pass OR fail. A failure exists nowhere
+//     else and must always reach the hub — a failing tier is retried at the next evaluation, so its
+//     record is short-lived by design;
+//   - the persisted state holds the last SUCCESS per tier and survives a restart.
+//
+// Comparing by TestedAt gives the right answer in every case without special-casing: a fresh failure
+// beats an older stored success (the failure is the news), a stored success beats a stale in-memory
+// entry after a restart, and a tier proved twice never appears twice — two entries for one tier would
+// read at the hub as two tests.
+//
+// A tier with no usable persisted proof contributes NOTHING. Reporting an unproven tier as proven
+// would be a worse defect than the one this closes.
 func (c *Collector) collectRestoreTests(ctx context.Context) []RestoreTest {
-	if c.restoreTests == nil {
-		return []RestoreTest{}
+	out := []RestoreTest{}
+	if c.restoreTests != nil {
+		if r := c.restoreTests.RestoreTests(ctx); r != nil {
+			out = append(out, r...)
+		}
 	}
-	if r := c.restoreTests.RestoreTests(ctx); r != nil {
-		return r
+	if c.provenTests == nil {
+		return out
 	}
-	return []RestoreTest{}
+
+	// Index what we already have by tier, keeping the newest per tier.
+	best := map[string]int{} // tier → index into out
+	for i, rt := range out {
+		if rt.SourceTier == "" {
+			continue // untiered entry: never deduped, never overwritten — we cannot say what it is
+		}
+		if j, seen := best[rt.SourceTier]; !seen || newerRestoreTest(rt, out[j]) {
+			best[rt.SourceTier] = i
+		}
+	}
+	for _, p := range c.provenTests.ProvenRestoreTests(ctx) {
+		if p.SourceTier == "" {
+			continue // not usable as a per-tier proof; the state layer already filters these
+		}
+		i, seen := best[p.SourceTier]
+		if !seen {
+			out = append(out, p)
+			best[p.SourceTier] = len(out) - 1
+			continue
+		}
+		if newerRestoreTest(p, out[i]) {
+			out[i] = p
+		}
+	}
+	return out
 }
 
+// newerRestoreTest reports whether a was tested after b. An unparseable or absent timestamp is
+// treated as OLDER, so a malformed entry can never displace a good one.
+func newerRestoreTest(a, b RestoreTest) bool {
+	ta, aok := parseRestoreTestedAt(a.TestedAt)
+	tb, bok := parseRestoreTestedAt(b.TestedAt)
+	if !aok {
+		return false
+	}
+	if !bok {
+		return true
+	}
+	return ta.After(tb)
+}
+
+func parseRestoreTestedAt(s string) (time.Time, bool) {
+	t, err := time.Parse(time.RFC3339, s)
+	if err != nil {
+		return time.Time{}, false
+	}
+	return t.UTC(), true
+}
+
+// SetProvenRestoreTests wires the durable proof source. It is a setter rather than a constructor
+// argument because the persisted state is opened later in main() than the collector is built; the
+// same shape as the other late-wired seams here. **The wiring is asserted by an AST test** — the
+// method it feeds carried a doc comment naming a "host-report gauge" for weeks with no caller at
+// all, and this fix must not become the next instance of that.
+func (c *Collector) SetProvenRestoreTests(p ProvenRestoreTestReporter) { c.provenTests = p }
+
 // collectPBSSnapshots reads the latest PBS snapshot inventory via the seam (nil → empty).
 func (c *Collector) collectPBSSnapshots(ctx context.Context) []PBSSnapshot {
 	if c.pbs == nil {
@@ -448,16 +555,18 @@ func (c *Collector) collectPBSSnapshots(ctx context.Context) []PBSSnapshot {
 	return []PBSSnapshot{}
 }
 
-func (c *Collector) cloudflaredStatus(ctx context.Context) string {
+func (c *Collector) cloudflared(ctx context.Context) Cloudflared {
 	if c.cf == nil {
-		return "unknown"
+		return Cloudflared{Status: TunnelUnknown, Detail: "no probe wired"}
 	}
-	st, err := c.cf.Status(ctx)
-	if err != nil || st == "" {
-		c.logger.Warn("hub: cloudflared probe failed", "err", err)
-		return "unknown"
+	st, d := c.cf.Status(ctx)
+	if st == "" {
+		st = TunnelUnknown
 	}
-	return st
+	if st == TunnelUnknown {
+		c.logger.Debug("hub: tunnel probe could not decide", "detail", d)
+	}
+	return Cloudflared{Status: st, Detail: d}
 }
 
 func percent(used, total int64) float64 {

internal/hub/collect_guestnet_test.go

@@ -16,7 +16,7 @@ func (f fakeGuestNet) GuestNetStatus(context.Context) *GuestNetStatus { return f
 
 func TestCollect_GuestNetOmittedWhenReporterNil(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.92.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.92.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("Collect: %v", err)
@@ -38,7 +38,7 @@ func TestCollect_GuestNetOmittedWhenReporterNil(t *testing.T) {
 
 func TestCollect_GuestNetPopulatedWhenWired(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.92.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.92.0", quietLogger())
 	c.SetGuestNetReporter(fakeGuestNet{st: &GuestNetStatus{
 		CheckedAt: "2026-07-21T10:00:00Z",
 		Guests: []GuestNetGuest{{

internal/hub/collect_mgmtplane_test.go

@@ -12,7 +12,7 @@ func (f fakeMgmtPlane) MgmtPlaneStatus(context.Context) *MgmtPlaneStatus { retur
 
 func TestCollect_MgmtPlaneOmittedWhenReporterNil(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.71.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.71.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("Collect: %v", err)
@@ -24,7 +24,7 @@ func TestCollect_MgmtPlaneOmittedWhenReporterNil(t *testing.T) {
 
 func TestCollect_MgmtPlanePopulatedWhenWired(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.71.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.71.0", quietLogger())
 	c.SetMgmtPlaneReporter(fakeMgmtPlane{st: &MgmtPlaneStatus{
 		PrivsepDirOK: true, SshdReachable: true, HealedRecently: true, PrivsepHealedAt: "2026-07-05T16:42:17Z",
 	}})
@@ -47,7 +47,7 @@ func (f fakeOOB) OOBStatus(context.Context) *OOBStatus { return f.st }
 
 func TestCollect_OOBOmittedWhenNil(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.72.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.72.0", quietLogger())
 	r, _ := c.Collect(context.Background())
 	if r.OOB != nil {
 		t.Fatalf("no reporter → oob omitted, got %+v", r.OOB)
@@ -56,7 +56,7 @@ func TestCollect_OOBOmittedWhenNil(t *testing.T) {
 
 func TestCollect_OOBPopulatedWhenWired(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{}, nil, nil, nil, "h", "0.72.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{}, nil, nil, nil, "h", "0.72.0", quietLogger())
 	c.SetOOBReporter(fakeOOB{st: &OOBStatus{FelhomSshdActive: true, FelhomSshdPort: 8822, Reachable: true}})
 	r, _ := c.Collect(context.Background())
 	if r.OOB == nil || r.OOB.FelhomSshdPort != 8822 || !r.OOB.Reachable {

internal/hub/collect_test.go

@@ -33,7 +33,7 @@ func TestCollect_StorageTargetsFromObserver(t *testing.T) {
 	obs := fakeObserver{targets: []StorageTarget{
 		{Name: "local-lvm", Type: StorageTypeLVMThin, State: StorageStateAttached, Reachable: true},
 	}}
-	c := NewCollector(px, fakeProber{status: "active"}, obs, nil, nil, nil, "h", "0.5.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, obs, nil, nil, nil, "h", "0.5.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("Collect: %v", err)
@@ -45,7 +45,7 @@ func TestCollect_StorageTargetsFromObserver(t *testing.T) {
 
 func TestCollect_StorageObserverErrorDegradesToEmpty(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{err: errors.New("proxmox down")}, nil, nil, nil, "h", "0.5.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{err: errors.New("proxmox down")}, nil, nil, nil, "h", "0.5.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("a storage observe error must not sink the heartbeat: %v", err)
@@ -64,7 +64,7 @@ func TestCollect_HostAndGuests(t *testing.T) {
 		},
 		cfg: map[int]proxmox.GuestConfig{100: {Cores: 2, Memory: 2048}},
 	}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "demo-host-01", "0.3.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "demo-host-01", "0.3.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("Collect: %v", err)
@@ -88,7 +88,7 @@ func TestCollect_HostAndGuests(t *testing.T) {
 	if g.Spec.Cores != 2 || g.Spec.MemoryBytes != 2147483648 || g.Spec.DiskBytes != 21474836480 {
 		t.Errorf("spec = %+v", g.Spec)
 	}
-	if r.Cloudflared.Status != "active" {
+	if r.Cloudflared.Status != "running" || r.Cloudflared.Detail != "connected" {
 		t.Errorf("cloudflared = %q", r.Cloudflared.Status)
 	}
 }
@@ -104,7 +104,7 @@ func TestCollect_GuestConfigFailureKeepsStatusOmitsSpec(t *testing.T) {
 		cfg:    map[int]proxmox.GuestConfig{100: {Cores: 2}},
 		cfgErr: map[int]error{200: errors.New("config read failed")},
 	}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.3.1", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.3.1", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("a per-guest failure must NOT fail the whole report: %v", err)
@@ -125,7 +125,7 @@ func TestCollect_GuestConfigFailureKeepsStatusOmitsSpec(t *testing.T) {
 
 func TestCollect_NodeStatusFailureIsHardError(t *testing.T) {
 	px := &fakePx{node: "n", nsErr: errors.New("proxmox down")}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
 	if _, err := c.Collect(context.Background()); err == nil {
 		t.Fatal("NodeStatus failure must be a hard error (no useful report)")
 	}
@@ -133,7 +133,7 @@ func TestCollect_NodeStatusFailureIsHardError(t *testing.T) {
 
 func TestCollect_CloudflaredProbeErrorIsUnknown(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{err: errors.New("no systemctl")}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "", detail: "could not ask"}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
 	r, err := c.Collect(context.Background())
 	if err != nil {
 		t.Fatalf("cloudflared failure must not be fatal: %v", err)
@@ -153,7 +153,7 @@ func TestCollect_LeafFingerprint(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
 	const fp = "60b5974d586f5f3c8ec41eb998d0f07406178219c36bf6d3ff377570279d8245"
 
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.48.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.48.0", quietLogger())
 	c.SetLeafFingerprint(fp)
 	r, err := c.Collect(context.Background())
 	if err != nil {
@@ -164,7 +164,7 @@ func TestCollect_LeafFingerprint(t *testing.T) {
 	}
 
 	// Companion: no SetLeafFingerprint (local API disabled) → empty, never a fabricated value.
-	c2 := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.48.0", quietLogger())
+	c2 := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.48.0", quietLogger())
 	r2, _ := c2.Collect(context.Background())
 	if r2.LeafFingerprint != "" {
 		t.Fatalf("unset leaf_fingerprint = %q, want empty", r2.LeafFingerprint)

internal/hub/dr_recipe_test.go

@@ -384,7 +384,7 @@ func TestCollectDRRecipe_ProductionPath(t *testing.T) {
 	obs := fakeObserver{targets: capturedDemoFelhomTargets()}
 	pbsRep := fakePBSReporter{snaps: capturedDemoFelhomSnapshots()}
 
-	c := NewCollector(px, fakeProber{status: "active"}, obs, nil, nil, pbsRep, "h", "0.118.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, obs, nil, nil, pbsRep, "h", "0.118.0", quietLogger())
 	c.SetBackupTargetResolver(func() ConfiguredBackupTarget {
 		return ConfiguredBackupTarget{StorageID: "felhom-backup", Known: true}
 	})
@@ -409,7 +409,7 @@ func TestCollectDRRecipe_ProductionPath(t *testing.T) {
 // test that would have caught shipping the seam without wiring it.
 func TestCollectDRRecipe_UnwiredSeamReportsUnknown(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, fakeObserver{targets: capturedDemoFelhomTargets()},
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, fakeObserver{targets: capturedDemoFelhomTargets()},
 		nil, nil, nil, "h", "0.118.0", quietLogger())
 
 	r, err := c.Collect(context.Background())

internal/hub/hostmetrics_test.go

@@ -16,7 +16,7 @@ func intp(v int) *int { return &v }
 // HostMetricsNow returns a fresh host block with cpu% from NodeStatus and the temp from the reader.
 func TestHostMetricsNow_PopulatesTemp(t *testing.T) {
 	px := &fakePx{node: "demo-felhom", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
 		SetTempReader(fakeTemp{c: intp(46)})
 	h, err := c.HostMetricsNow(context.Background())
 	if err != nil {
@@ -36,7 +36,7 @@ func TestHostMetricsNow_PopulatesTemp(t *testing.T) {
 // A missing temp sensor gracefully nulls cpu_temp_c without failing the host read.
 func TestHostMetricsNow_GracefulNullTemp(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
 		SetTempReader(fakeTemp{c: nil})
 	h, err := c.HostMetricsNow(context.Background())
 	if err != nil {
@@ -50,7 +50,7 @@ func TestHostMetricsNow_GracefulNullTemp(t *testing.T) {
 // A NodeStatus failure is a hard error (no useful host view).
 func TestHostMetricsNow_NodeStatusErrorIsHard(t *testing.T) {
 	px := &fakePx{node: "n", nsErr: errors.New("proxmox down")}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger())
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger())
 	if _, err := c.HostMetricsNow(context.Background()); err == nil {
 		t.Fatal("NodeStatus failure must be a hard error")
 	}
@@ -59,7 +59,7 @@ func TestHostMetricsNow_NodeStatusErrorIsHard(t *testing.T) {
 // Collect() (the hub report) also carries the temp now — the operator freebie.
 func TestCollect_HostReportCarriesTemp(t *testing.T) {
 	px := &fakePx{node: "n", ns: newTestNodeStatus()}
-	c := NewCollector(px, fakeProber{status: "active"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
+	c := NewCollector(px, fakeProber{status: "running", detail: "connected"}, nil, nil, nil, nil, "h", "0.14.0", quietLogger()).
 		SetTempReader(fakeTemp{c: intp(51)})
 	r, err := c.Collect(context.Background())
 	if err != nil {

internal/hub/mock_test.go

@@ -56,7 +56,7 @@ func (f *fakePx) GuestConfig(ctx context.Context, vmid int) (proxmox.GuestConfig
 // fakeProber is a fake CloudflaredProber.
 type fakeProber struct {
 	status string
-	err    error
+	detail string
 }
 
-func (p fakeProber) Status(ctx context.Context) (string, error) { return p.status, p.err }
+func (p fakeProber) Status(ctx context.Context) (string, string) { return p.status, p.detail }

internal/hub/osupdate_contract_test.go

@@ -0,0 +1,36 @@
+package hub
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+// The os_update block is a cross-repo contract: testdata/desired-state-osupdate.golden.json is byte-identical with
+// felhom.eu/hub/internal/api/testdata (the hub's TestOSUpdate_DesiredBlockMatchesTheGolden proves the hub SERVES
+// it). Here: the agent DECODES every field. A renamed json tag on either side fails one of the two tests.
+func TestOSUpdateGolden_Decodes(t *testing.T) {
+	raw, err := os.ReadFile("testdata/desired-state-osupdate.golden.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var resp DesiredStateResponse
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		t.Fatal(err)
+	}
+	o := resp.DesiredState.OSUpdate
+	if o == nil || o.Ring != 1 || !o.Enabled || o.Release == nil {
+		t.Fatalf("os_update = %+v", o)
+	}
+	r := o.Release
+	if r.ID != "os-guest-20261004-120000" || r.Snapshot != "20261004T120000Z" || len(r.Packages) != 2 ||
+		r.Packages[1].Name != "openssl" || r.Packages[1].Version != "3.5.7-1~deb13u3" || r.Packages[1].Origin != "Debian-Security" {
+		t.Fatalf("release = %+v", r)
+	}
+	// v0.141.0: the host layer's own approved set (`11` §8 step 3).
+	h := o.HostRelease
+	if h == nil || h.ID != "os-host-20261004-120000" || h.Snapshot != "20261004T120000Z" || len(h.Packages) != 1 ||
+		h.Packages[0].Name != "libssl3t64" || h.Packages[0].Origin != "Debian-Security" {
+		t.Fatalf("host_release = %+v", h)
+	}
+}

internal/hub/report.go

@@ -68,8 +68,14 @@ type HostReport struct {
 	// report is stored opaquely hub-side, so these additive fields need no hub-schema change.
 	// Both are `omitempty` (the Wireguard precedent): in the steady state (no update in flight)
 	// they are absent — which keeps the cross-repo host-report golden contract byte-stable without
-	// a hub change. They appear only while an update is pending. The hub reads an absent field as
-	// pending=false, the correct default.
+	// a hub change. They appear only while an update is pending.
+	//
+	// ⚠ CORRECTED 2026-08-08 (R-260). This comment used to end "The hub reads an absent field as
+	// pending=false, the correct default." THE HUB HAS NO FIELD FOR EITHER OF THESE, so it reads
+	// nothing — present or absent — and encoding/json discards them on arrival. The sentence
+	// described an intent, not the code, and it read as settled for long enough that a sweep had to
+	// find it. The emission is correct and stays; the missing consumer is tracked as R-264, and
+	// `felhom.eu/scripts/wire_contract_gate.py` now refuses any NEW field of this shape.
 	SelfUpdatePending        bool   `json:"selfupdate_pending,omitempty"`
 	SelfUpdatePendingVersion string `json:"selfupdate_pending_version,omitempty"`
 
@@ -118,6 +124,39 @@ type HostReport struct {
 	// HTTPS even when felhom-sshd or the tunnel is DOWN (channel independence). `omitempty`: absent
 	// when the feature is not wired (pre-H1) — additive, no hub-schema change.
 	OOB *OOBStatus `json:"oob,omitempty"`
+
+	// ControllerSupervisor (R-523, v0.131.0) is the in-guest controller supervisor's per-guest record:
+	// how many times the agent restarted a dead controller, when last and why, whether it gave up
+	// (crash-loop pause) and whether the operator parked it. The hub's ControllerSupervisorChecker
+	// mints `controller_restarted_by_agent` when last_restart_at MOVES and `controller_crashloop` when
+	// crashloop_since MOVES — timestamps, not counters, because the record is in-memory and an agent
+	// restart zeroes the counter. `omitempty`: absent when not wired, so the cross-repo golden stays
+	// byte-stable. The hub parser is pinned by hub/internal/monitor/controller_supervisor_test.go
+	// against the JSON TestControllerSupervisorStanza_WireShape pins here.
+	ControllerSupervisor *ControllerSupervisorStatus `json:"controller_supervisor,omitempty"`
+}
+
+// ControllerSupervisorStatus is the R-523 stanza. Carries no secret.
+type ControllerSupervisorStatus struct {
+	Guests []ControllerSupervisorGuest `json:"guests"`
+}
+
+// ControllerSupervisorGuest is one supervised guest.
+type ControllerSupervisorGuest struct {
+	VMID           int    `json:"vmid"`
+	RestartsTotal  int    `json:"restarts_total"`
+	LastRestartAt  string `json:"last_restart_at,omitempty"` // RFC3339
+	LastReason     string `json:"last_reason,omitempty"`
+	Crashloop      bool   `json:"crashloop"`
+	CrashloopSince string `json:"crashloop_since,omitempty"` // RFC3339; the last crash-loop, kept after it ends
+	Parked         bool   `json:"parked"`
+	// R-539 (v0.132.0) — the SLOW crash loop. Restarts24h counts restarts the supervisor performed in
+	// the last 24 hours (persisted, so an agent restart does not reset it); SlowCrashloop is true while
+	// the last raise is under 24 hours old; SlowCrashloopSince is the raise itself, which the hub keys on
+	// MOVING (hub v0.117.0 controller_slow_crashloop). It moves at most once per 24 hours.
+	Restarts24h        int    `json:"restarts_24h"`
+	SlowCrashloop      bool   `json:"slow_crashloop"`
+	SlowCrashloopSince string `json:"slow_crashloop_since,omitempty"` // RFC3339
 }
 
 // PBSDRStatus is the per-heartbeat PBS-DR-tier bridge state (slice 2). States:
@@ -250,9 +289,10 @@ type GuestSpec struct {
 	DiskBytes   int64 `json:"disk_bytes"`
 }
 
-// Cloudflared is the tunnel service health (read-only probe this slice).
+// Cloudflared is the box's tunnel (R-841, agent v0.141.0): the cloudflared container in the customer guest.
 type Cloudflared struct {
-	Status string `json:"status"` // active | inactive | failed | unknown
+	Status string `json:"status"`           // running | not_running | unknown (TunnelRunning …)
+	Detail string `json:"detail,omitempty"` // why not_running / unknown, or "connected"
 }
 
 // The following element types are declared now so the empty collections above are
@@ -431,6 +471,10 @@ type RestoreTest struct {
 	// mount layout, not just booted. Additive — a hub that predates them ignores the unknown keys.
 	MountParity    string   `json:"mount_parity,omitempty"`
 	MountInventory []string `json:"mount_inventory,omitempty"`
+	// Skipped (R-672, v0.133.0): the test did NOT run — the space preflight refused, and Error says
+	// why ("skipped: not enough space on …"). Pass is false. A hub that predates the key reads a
+	// failed test with that error, which is the honest reading.
+	Skipped bool `json:"skipped,omitempty"`
 }
 
 // PBSSnapshot is one PBS (offsite) snapshot's inventory + integrity state (doc 03 §8, slice
@@ -505,6 +549,35 @@ type WireDesiredState struct {
 	RestoreDirective *WireRestoreDirective `json:"restore_directive,omitempty"` // slice 10D (forward-compat)
 	Wireguard        *WireWireguard        `json:"wireguard,omitempty"`         // S3 (doc 06 §3.2; golden-pinned)
 	PBSDR            *WirePBSDR            `json:"pbs_dr,omitempty"`            // PBS DR tier (slice 2 consumer)
+	OSUpdate         *WireOSUpdate         `json:"os_update,omitempty"`         // OS updates, guest fast lane (agent v0.140.0)
+}
+
+// WireOSUpdate is the hub-OWNED OS-update block (hub v0.130.0, `11-os-updates.md` §5.3), merged into the served
+// document at read time. Ring 0 installs every pending Debian / Debian-Security fix; ring 1 installs exactly the
+// newest approved release. Absent (older hub) → the agent treats the box as ring 1, ON, no release: it reports
+// and installs nothing. Golden: testdata/desired-state-osupdate.golden.json (byte-identical with the hub's).
+type WireOSUpdate struct {
+	Ring    int            `json:"ring"`
+	Enabled bool           `json:"enabled"`
+	Release *WireOSRelease `json:"release,omitempty"`
+	// HostRelease is the newest approved HOST release (hub v0.131.0, `11` §8 step 3) — a separate set: a version
+	// approved for the guest is not approved for the host by that fact alone.
+	HostRelease *WireOSRelease `json:"host_release,omitempty"`
+}
+
+// WireOSRelease is an approved version set; Snapshot is the approval time (YYYYMMDDTHHMMSSZ) the wrapper uses
+// for snapshot.debian.org when Debian has already replaced a version (decision 79).
+type WireOSRelease struct {
+	ID       string          `json:"id"`
+	Snapshot string          `json:"snapshot"`
+	Packages []WireOSPackage `json:"packages"`
+}
+
+// WireOSPackage is one approved name=version and its origin ("Debian" | "Debian-Security").
+type WireOSPackage struct {
+	Name    string `json:"name"`
+	Version string `json:"version"`
+	Origin  string `json:"origin"`
 }
 
 // WirePBSDR is the hub's PBS-DR-tier descriptor (PBS DR slice 1, hub/internal/web/pbsdr.go

internal/hub/restoretest_merge_test.go

@@ -0,0 +1,213 @@
+package hub
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// R-189 — a passing restore-test must survive an agent restart and reach the hub.
+//
+// THE OBSERVATION THIS EXISTS FOR (2026-08-03, demo-felhom): a real 14.5 GB offsite restore-test
+// PASSED at 15:25:14; the agent was restarted 2 m 43 s later for a deploy; the hub logged
+// `0 restore-tests` on the next two host-reports. The in-memory store's own comment said "lost on
+// restart; the cadence re-populates", which was true under a timer and stopped being true when R-86
+// made the agent refuse to re-test an archive it has already proven.
+//
+// Timestamps here carry JITTER (odd minutes and seconds, not round hours) — yesterday a test was
+// hollow because a perfectly regular series landed exactly on a threshold and passed under the
+// mutation it was meant to catch.
+
+type fakeLatest struct{ tests []RestoreTest }
+
+func (f *fakeLatest) RestoreTests(context.Context) []RestoreTest { return f.tests }
+
+type fakeProven struct{ tests []RestoreTest }
+
+func (f *fakeProven) ProvenRestoreTests(context.Context) []RestoreTest { return f.tests }
+
+func rt(tier, archive string, pass bool, at time.Time) RestoreTest {
+	return RestoreTest{
+		SourceArchive: archive, SourceTier: tier, Pass: pass,
+		Verified: "boot+running", TestedAt: at.UTC().Format(time.RFC3339),
+	}
+}
+
+// mergeCollector builds a Collector with only the two restore-test seams wired — the merge is what
+// is under test, not the rest of the collection.
+func mergeCollector(latest, proven []RestoreTest) *Collector {
+	c := &Collector{}
+	if latest != nil {
+		c.restoreTests = &fakeLatest{tests: latest}
+	}
+	if proven != nil {
+		c.provenTests = &fakeProven{tests: proven}
+	}
+	return c
+}
+
+func findTier(got []RestoreTest, tier string) (RestoreTest, int) {
+	var hit RestoreTest
+	n := 0
+	for _, e := range got {
+		if e.SourceTier == tier {
+			hit, n = e, n+1
+		}
+	}
+	return hit, n
+}
+
+// ── SCENARIO A — a proof survives a restart and reaches the hub ──────────────────────────────
+//
+// COMPANION RED-PROOF (observed 2026-08-03): delete the `c.provenTests` merge from
+// collectRestoreTests (return the in-memory slice as it used to) →
+//
+//	--- FAIL: TestMerge_ProofSurvivesARestart
+//	    restoretest_merge_test.go: after a restart the persisted proof must be reported; got 0 entr(ies)
+//
+// which is exactly the live observation: `0 restore-tests`. Restored.
+func TestMerge_ProofSurvivesARestart(t *testing.T) {
+	provenAt := time.Date(2026, 8, 3, 13, 25, 14, 0, time.UTC) // the real run's timestamp
+	// After a restart the in-memory store is EMPTY — this is the whole point.
+	c := mergeCollector([]RestoreTest{}, []RestoreTest{
+		rt("pbs", "felhom-pbs:backup/ct/9201/2026-07-28T04:49:43Z", true, provenAt),
+	})
+
+	got := c.collectRestoreTests(context.Background())
+	if len(got) != 1 {
+		t.Fatalf("after a restart the persisted proof must be reported; got %d entr(ies): %+v", len(got), got)
+	}
+	e := got[0]
+	if e.SourceArchive != "felhom-pbs:backup/ct/9201/2026-07-28T04:49:43Z" {
+		t.Fatalf("the entry must name the archive that was proven — the hub keys on it; got %q", e.SourceArchive)
+	}
+	if e.SourceTier != "pbs" || !e.Pass {
+		t.Fatalf("the entry must be a PASS on the tier it was proven on; got tier=%q pass=%v", e.SourceTier, e.Pass)
+	}
+	if e.TestedAt != provenAt.Format(time.RFC3339) {
+		t.Fatalf("the entry must carry the ORIGINAL test time, not now(); got %q", e.TestedAt)
+	}
+}
+
+// ── SCENARIO B — the report does not invent a pass ───────────────────────────────────────────
+//
+// COMPANION RED-PROOF (observed): make the state layer emit an entry for an unproven tier (drop the
+// `reportable()` filter in ProvenRestoreTests, so a legacy record with no archive is emitted) — the
+// equivalent at this layer is a proven-source that returns an entry for a tier nothing proved, which
+// this test injects directly and the assertion below rejects.
+func TestMerge_NeverInventsAPassForAnUnprovenTier(t *testing.T) {
+	// Nothing proven anywhere: no in-memory result, no persisted proof.
+	c := mergeCollector([]RestoreTest{}, []RestoreTest{})
+	if got := c.collectRestoreTests(context.Background()); len(got) != 0 {
+		t.Fatalf("a tier with no proof must produce NO entry — an unproven tier reading as proven is "+
+			"worse than the defect being fixed; got %+v", got)
+	}
+
+	// And an entry the state layer could not describe (no tier) is never promoted into a proof.
+	c2 := mergeCollector([]RestoreTest{}, []RestoreTest{
+		{SourceArchive: "local:backup/x.tar.zst", SourceTier: "", Pass: true,
+			TestedAt: time.Date(2026, 8, 1, 4, 41, 58, 0, time.UTC).Format(time.RFC3339)},
+	})
+	if got := c2.collectRestoreTests(context.Background()); len(got) != 0 {
+		t.Fatalf("a persisted record with no tier is not a usable proof and must be dropped; got %+v", got)
+	}
+}
+
+// ── SCENARIO C — a fresh in-memory result wins, and never duplicates ─────────────────────────
+//
+// COMPANION RED-PROOF (observed 2026-08-03): remove the de-duplication (append every persisted entry
+// unconditionally) →
+//
+//	--- FAIL: TestMerge_NewerWinsAndNeverDuplicatesATier
+//	    restoretest_merge_test.go: one entry per tier; got 2 for "pbs" — the hub would read two tests
+//
+// Restored.
+func TestMerge_NewerWinsAndNeverDuplicatesATier(t *testing.T) {
+	lastWeek := time.Date(2026, 7, 27, 19, 55, 41, 0, time.UTC) // jittered, from the real box
+	fiveMinAgo := time.Date(2026, 8, 3, 13, 25, 14, 0, time.UTC)
+
+	c := mergeCollector(
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/new", true, fiveMinAgo)},
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/old", true, lastWeek)},
+	)
+	got := c.collectRestoreTests(context.Background())
+	e, n := findTier(got, "pbs")
+	if n != 1 {
+		t.Fatalf("one entry per tier; got %d for \"pbs\" — the hub would read two tests: %+v", n, got)
+	}
+	if e.SourceArchive != "felhom-pbs:backup/ct/9201/new" {
+		t.Fatalf("the NEWER result must win; got %q tested %q", e.SourceArchive, e.TestedAt)
+	}
+
+	// ...and the older-in-memory / newer-persisted direction, which is the post-restart case.
+	c2 := mergeCollector(
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/old", true, lastWeek)},
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/new", true, fiveMinAgo)},
+	)
+	e2, n2 := findTier(c2.collectRestoreTests(context.Background()), "pbs")
+	if n2 != 1 || e2.SourceArchive != "felhom-pbs:backup/ct/9201/new" {
+		t.Fatalf("newest must win regardless of which source it came from; got %d entr(ies), archive %q", n2, e2.SourceArchive)
+	}
+}
+
+// ── SCENARIO D — a failure still reaches the hub ─────────────────────────────────────────────
+//
+// The merge must not mask a failure with an older stored success. A failing tier is retried at the
+// next evaluation and its record lives ONLY in memory, so losing it here would silence the loudest
+// DR signal this system produces.
+func TestMerge_AFailureIsStillReported(t *testing.T) {
+	provenLastWeek := time.Date(2026, 7, 27, 19, 55, 41, 0, time.UTC)
+	failedJustNow := time.Date(2026, 8, 3, 13, 41, 7, 0, time.UTC)
+
+	c := mergeCollector(
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/new", false, failedJustNow)},
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/old", true, provenLastWeek)},
+	)
+	e, n := findTier(c.collectRestoreTests(context.Background()), "pbs")
+	if n != 1 {
+		t.Fatalf("one entry per tier; got %d: %+v", n, c.collectRestoreTests(context.Background()))
+	}
+	if e.Pass {
+		t.Fatalf("a FAILURE newer than the stored proof must be what is reported — masking it would "+
+			"silence the loudest DR signal there is; got pass=%v archive=%q", e.Pass, e.SourceArchive)
+	}
+}
+
+// Two different tiers are both reported — the merge is per tier, not a single slot.
+func TestMerge_BothTiersSurvive(t *testing.T) {
+	c := mergeCollector(
+		[]RestoreTest{rt("local", "felhom-backup:backup/vzdump-lxc-9201-a.tar.zst", true,
+			time.Date(2026, 8, 3, 4, 44, 50, 0, time.UTC))},
+		[]RestoreTest{rt("pbs", "felhom-pbs:backup/ct/9201/x", true,
+			time.Date(2026, 8, 2, 5, 12, 33, 0, time.UTC))},
+	)
+	got := c.collectRestoreTests(context.Background())
+	if _, n := findTier(got, "local"); n != 1 {
+		t.Fatalf("the in-memory tier must survive the merge; got %+v", got)
+	}
+	if _, n := findTier(got, "pbs"); n != 1 {
+		t.Fatalf("the persisted tier must survive the merge; got %+v", got)
+	}
+}
+
+// A malformed timestamp must never displace a good entry — "unparseable" is not "newest".
+func TestMerge_MalformedTimestampNeverWins(t *testing.T) {
+	good := rt("pbs", "felhom-pbs:backup/ct/9201/good", true, time.Date(2026, 8, 3, 13, 25, 14, 0, time.UTC))
+	bad := RestoreTest{SourceArchive: "felhom-pbs:backup/ct/9201/bad", SourceTier: "pbs", Pass: true, TestedAt: "not-a-time"}
+
+	c := mergeCollector([]RestoreTest{good}, []RestoreTest{bad})
+	e, n := findTier(c.collectRestoreTests(context.Background()), "pbs")
+	if n != 1 || e.SourceArchive != "felhom-pbs:backup/ct/9201/good" {
+		t.Fatalf("an unparseable timestamp must not displace a good entry; got %d entr(ies), archive %q", n, e.SourceArchive)
+	}
+}
+
+// A nil proven-source leaves the pre-R-189 behaviour exactly as it was.
+func TestMerge_NilProvenSourceIsANoOp(t *testing.T) {
+	only := rt("local", "felhom-backup:backup/x.tar.zst", true, time.Date(2026, 8, 3, 4, 44, 50, 0, time.UTC))
+	c := mergeCollector([]RestoreTest{only}, nil)
+	got := c.collectRestoreTests(context.Background())
+	if len(got) != 1 || got[0].SourceArchive != only.SourceArchive {
+		t.Fatalf("a nil durable source must not change anything; got %+v", got)
+	}
+}

internal/hub/testdata/desired-state-osupdate.golden.json

@@ -0,0 +1,24 @@
+{
+  "generation": 1,
+  "desired_state": {
+    "os_update": {
+      "ring": 1,
+      "enabled": true,
+      "release": {
+        "id": "os-guest-20261004-120000",
+        "snapshot": "20261004T120000Z",
+        "packages": [
+          {"name": "libc6", "version": "2.41-12+deb13u4", "origin": "Debian"},
+          {"name": "openssl", "version": "3.5.7-1~deb13u3", "origin": "Debian-Security"}
+        ]
+      },
+      "host_release": {
+        "id": "os-host-20261004-120000",
+        "snapshot": "20261004T120000Z",
+        "packages": [
+          {"name": "libssl3t64", "version": "3.5.7-1~deb13u3", "origin": "Debian-Security"}
+        ]
+      }
+    }
+  }
+}

internal/localapi/afterbackup_test.go

@@ -0,0 +1,63 @@
+package localapi
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/backup"
+)
+
+// The OS leg (agent v0.140.0) runs after a SUCCESSFUL primary backup, and only then; and it runs BEFORE the
+// host-wide heavy-op gate is released, so a restore-test cannot start in the middle of it (`11` C10).
+// Red-proof: drop the `b.Success &&` guard and the failed-backup sub-case fails; move the call after release()
+// and the gate sub-case fails.
+func TestAfterPrimaryBackup(t *testing.T) {
+	run := func(t *testing.T, failErr string) (calls []int, gateHeld bool) {
+		gate := &backup.InFlight{}
+		b := &fakeBackups{failErr: failErr}
+		srv := newTestServerS(t, &fakeGuests{}, b, &fakeStore{}, nil)
+		srv.inFlight = gate
+		var mu sync.Mutex
+		done := make(chan struct{}, 1)
+		srv.SetAfterPrimaryBackup(func(_ context.Context, vmid int) {
+			rel, _, ok := gate.TryAcquire("probe")
+			mu.Lock()
+			calls = append(calls, vmid)
+			gateHeld = !ok
+			mu.Unlock()
+			if ok {
+				rel()
+			}
+			done <- struct{}{}
+		})
+		h := srv.Handler()
+		if do(t, h, "POST", "/backup", "A", "").Code != http.StatusAccepted {
+			t.Fatal("POST /backup not accepted")
+		}
+		select {
+		case <-done:
+		case <-time.After(500 * time.Millisecond):
+		}
+		time.Sleep(20 * time.Millisecond)
+		mu.Lock()
+		defer mu.Unlock()
+		return calls, gateHeld
+	}
+	t.Run("success runs the leg under the gate", func(t *testing.T) {
+		calls, held := run(t, "")
+		if len(calls) != 1 {
+			t.Fatalf("the leg ran %d time(s), want 1", len(calls))
+		}
+		if !held {
+			t.Fatal("the heavy-op gate was free while the leg ran — a restore-test could overlap it")
+		}
+	})
+	t.Run("a failed backup runs nothing", func(t *testing.T) {
+		if calls, _ := run(t, "vzdump exploded"); len(calls) != 0 {
+			t.Fatalf("the leg ran after a FAILED backup: %v", calls)
+		}
+	})
+}

internal/localapi/backup_tier_states_test.go

@@ -0,0 +1,133 @@
+package localapi
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// R-517 — the per-tier truth on GET /backup/status. BIGNIGHT: a successful 8.9 GB local backup,
+// then a failed PBS attempt on a storage that did not exist; the page (fed by the single latest
+// record) showed the 0-byte failure as "up to date" and the remote copy as present.
+
+func tierStatesOf(t *testing.T, srv *Server) []TierBackupState {
+	t.Helper()
+	w := do(t, srv.Handler(), "GET", "/backup/status", "A", "")
+	var resp struct {
+		Data BackupStatusResponse `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v (%s)", err, w.Body.String())
+	}
+	return resp.Data.Tiers
+}
+
+func tierStatesServer(t *testing.T, st *fakeStore, targets []hub.StorageTarget) *Server {
+	t.Helper()
+	srv, err := NewServer(Options{
+		ListenAddr: "127.0.0.1:0", Guests: &fakeGuests{}, Backups: &fakeBackups{}, Store: st,
+		Storage: fakeStorage{targets: targets},
+		Tokens:  staticTokens{"A": 8200},
+		BackupTiers: []BackupTier{
+			{TargetID: "local", Cadence: 24 * time.Hour, Primary: true, Service: &fakeBackups{}},
+			{TargetID: "felhom-pbs", Cadence: 7 * 24 * time.Hour, Service: &fakeBackups{}},
+		},
+		Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	srv.baseCtx = context.Background()
+	srv.now = func() time.Time { return testNow }
+	return srv
+}
+
+// RED-PROOF (run 2026-09-15, recorded in REPORT.md): with tierBackupStates filling LastSuccess from
+// pickLatestBackup(ctx, vmid, false, …) — an ATTEMPT — the pbs tier's last_success became the failed
+// 0-byte record and this failed at "pbs tier reports a failed attempt as its last success".
+func TestBackupStatus_TierStates_FailedTierNeverStandsInForSuccess(t *testing.T) {
+	st := &fakeStore{backups: []hub.Backup{
+		{TargetID: "local", VMID: 8200, Success: true, SizeBytes: 8877619753, StartedAt: "2026-06-10T11:03:23Z"},
+		{TargetID: "felhom-pbs", VMID: 8200, Success: false, Error: "storage 'felhom-pbs' does not exist", StartedAt: "2026-06-10T11:09:59Z"},
+	}}
+	srv := tierStatesServer(t, st, []hub.StorageTarget{{Name: "local", Type: "local"}}) // PBS storage ABSENT
+	tiers := tierStatesOf(t, srv)
+	if len(tiers) != 2 {
+		t.Fatalf("want 2 tiers, got %+v", tiers)
+	}
+	local, pbs := tiers[0], tiers[1]
+	if local.Target != "local" || local.LastSuccess == nil || local.LastSuccess.SizeBytes != 8877619753 || local.Storage != StoragePresencePresent {
+		t.Fatalf("local tier lost its successful backup: %+v", local)
+	}
+	if pbs.LastSuccess != nil {
+		t.Fatalf("pbs tier reports a failed attempt as its last success: %+v", pbs.LastSuccess)
+	}
+	if pbs.LastAttempt == nil || pbs.LastAttempt.Success || pbs.LastAttempt.Error == "" {
+		t.Fatalf("pbs tier's failed attempt is not reported as failed: %+v", pbs.LastAttempt)
+	}
+	if pbs.Storage != StoragePresenceAbsent {
+		t.Fatalf("pbs storage should read absent, got %q", pbs.Storage)
+	}
+	// The pre-R-517 field is unchanged (compat): still the newest record across targets.
+	w := do(t, srv.Handler(), "GET", "/backup/status", "A", "")
+	var resp struct {
+		Data BackupStatusResponse `json:"data"`
+	}
+	_ = json.Unmarshal(w.Body.Bytes(), &resp)
+	if resp.Data.Backup == nil || resp.Data.Backup.TargetID != "felhom-pbs" {
+		t.Fatalf("untargeted .backup changed meaning: %+v", resp.Data.Backup)
+	}
+}
+
+// /backup/tiers advertises storage presence, tri-state.
+func TestBackupTiers_StoragePresence(t *testing.T) {
+	srv := tierStatesServer(t, &fakeStore{}, []hub.StorageTarget{{Name: "local"}})
+	w := do(t, srv.Handler(), "GET", "/backup/tiers", "A", "")
+	var resp struct {
+		Data BackupTiersResponse `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]string{}
+	for _, ti := range resp.Data.Tiers {
+		got[ti.Target] = ti.Storage
+	}
+	if got["local"] != "present" || got["felhom-pbs"] != "absent" {
+		t.Fatalf("storage presence wrong: %v", got)
+	}
+	// An unreadable storage view is "unknown", never "absent".
+	srv.storage = tierErrStorage{}
+	if p := srv.storagePresence(context.Background(), "felhom-pbs"); p != StoragePresenceUnknown {
+		t.Fatalf("unreadable storage view must be unknown, got %q", p)
+	}
+}
+
+type tierErrStorage struct{}
+
+func (tierErrStorage) Observe(context.Context) ([]hub.StorageTarget, error) {
+	return nil, context.DeadlineExceeded
+}
+
+// A targeted request keeps the pre-R-517 bytes (no tiers array).
+func TestBackupStatus_TargetedHasNoTiers(t *testing.T) {
+	srv := tierStatesServer(t, &fakeStore{}, []hub.StorageTarget{{Name: "local"}})
+	w := do(t, srv.Handler(), "GET", "/backup/status?target=local", "A", "")
+	if json.Valid(w.Body.Bytes()) && containsKey(w.Body.Bytes(), "tiers") {
+		t.Fatalf("targeted status grew a tiers array: %s", w.Body.String())
+	}
+}
+
+func containsKey(b []byte, key string) bool {
+	var m struct {
+		Data map[string]json.RawMessage `json:"data"`
+	}
+	_ = json.Unmarshal(b, &m)
+	_, ok := m.Data[key]
+	return ok
+}

internal/localapi/controllersupervisor.go

@@ -0,0 +1,453 @@
+package localapi
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// R-523 — the in-guest controller supervisor.
+//
+// THE OUTAGE THIS EXISTS TO KILL (BIGNIGHT F9, 2026-09-14). `docker kill felhom-controller` left the
+// container `Exited (137)`. Nothing restarted it: Docker never restarts a container whose stop it
+// records as deliberate — measured 2026-09-15 on Docker 29.8.0 for BOTH `unless-stopped` and `always`
+// (evidence-p1fixes-2026-09-15/A1) — and the golden's `felhom-controller-bootstrap.service` is a
+// oneshot (`RemainAfterExit=yes`) that ran once at boot and watches nothing. The household's
+// dashboard answered 502 for 33 minutes until the box was power-cycled.
+//
+// This is doc 03 §4's sentence made real: "Healing a crashed controller is non-destructive by
+// construction … redeploy = restart … inside the existing guest — never a guest destroy." The act
+// is exactly the swap's own restart (`systemctl restart felhom-controller-bootstrap.service`, which
+// does `docker rm -f` + `docker run` from the baked image and the guest's persistent volume), over
+// the same GuestExecutor and the same two sudoers grants (`docker inspect -f *`, the unit restart).
+// No new privilege.
+//
+// THE GUARDS, each because doing the act at the wrong moment is worse than not doing it:
+//   - not during a swap (the swap stops the controller ON PURPOSE and owns its own rollback);
+//   - not when the operator parked it (`<guests>/<vmid>/controller-parked` on the HOST);
+//   - not on a guest that is not running, is locked (backup/restore/snapshot/migrate), or has a
+//     vzdump in flight — a stopping or restoring guest is someone else's transaction;
+//   - not on ONE observation: the container must be seen not-running on two consecutive sweeps, so
+//     the bootstrap's own rm-f/run window (boot, path-unit hot-plug) is never raced;
+//   - no thrash: 3 restarts inside 15 minutes → stop restarting, raise `controller_crashloop`, try
+//     again after 30 minutes.
+//
+// THE EVENTS. The agent has no event channel of its own; its heartbeat IS the channel (the
+// capability/leaf precedent). The per-guest record rides the host report as `controller_supervisor`,
+// and the hub's ControllerSupervisorChecker mints `controller_restarted_by_agent` (info) when a
+// guest's `last_restart_at` moves and `controller_crashloop` (error, operator-only) when
+// `crashloop_since` moves. Timestamps, not counters, so an agent restart (which zeroes the in-memory
+// record) can never read as a new restart.
+
+const (
+	// controllerSupervisorInterval is the sweep cadence. Two not-running observations are required,
+	// so a killed controller is restarted 30–60 s after it died.
+	controllerSupervisorInterval = 30 * time.Second
+	// controllerSupervisorConfirm is how many consecutive not-running observations license a restart.
+	controllerSupervisorConfirm = 2
+	// Backoff: controllerCrashloopMax restarts inside controllerCrashloopWindow → give up for
+	// controllerCrashloopPause.
+	controllerCrashloopMax    = 3
+	controllerCrashloopWindow = 15 * time.Minute
+	controllerCrashloopPause  = 30 * time.Minute
+	// controllerSupervisorHeartbeatEvery: a liveness line every 20 sweeps (10 minutes) — a silent
+	// watchdog is indistinguishable from a dead one (standing rule 3).
+	controllerSupervisorHeartbeatEvery = 20
+
+	// ControllerParkedMarker is the host-side file that parks a guest's controller. The operator
+	// creates it with `touch /var/lib/felhom-agent/guests/<vmid>/controller-parked` and removes it to
+	// unpark. Host-side on purpose: it needs no in-guest exec grant, it survives a guest rebuild of
+	// the controller container, and a customer inside the guest cannot park the supervisor.
+	ControllerParkedMarker = "controller-parked"
+
+	defaultGuestsStateDir = "/var/lib/felhom-agent/guests"
+
+	// R-539 (operator ruling 3 of 2026-09-16) — the SLOW crash loop. The 3-in-15-minutes brake above
+	// cannot see a controller that dies every 20 minutes: no two restarts share its window, so it is
+	// restarted for ever and the only trace is an info event that mails nobody (measured 2026-09-16,
+	// R-531). A second counter over 24 hours raises a WARNING at the fifth restart. It does NOT stop
+	// restarting — the fast brake stays the only brake, unchanged. Every restart the supervisor
+	// performs counts, including one that follows a deliberate operator `docker kill` (measured
+	// 2026-09-15: the supervisor cannot tell a kill from a crash, and a controller that is killed five
+	// times a day is worth a line to the operator either way).
+	controllerSlowCrashloopWindow = 24 * time.Hour
+	controllerSlowCrashloopMax    = 5
+	// controllerSlowCounterFile holds the 24-hour restart times and the last raise, per guest, beside
+	// the parked marker.
+	controllerSlowCounterFile = "controller-restarts-24h.json"
+)
+
+// controllerSupState is one guest's supervisor record. In-memory on purpose (the guest-power
+// precedent): an agent restart forgets a crash-loop pause, which costs at most one more restart
+// attempt, whereas persisting it could carry a stale "give up" across the restart that fixed it.
+type controllerSupState struct {
+	notRunningSeen int
+	restarts       []time.Time // restart times inside the crash-loop window (pruned)
+	restartsTotal  int
+	lastRestartAt  time.Time
+	lastReason     string
+	crashloopSince time.Time // zero = not in a crash-loop pause
+	parked         bool
+
+	// R-539 — the slow counter. PERSISTED, unlike everything above, and the precedent's reason does not
+	// apply to it: persisting the fast record could carry a stale "give up" across the restart that
+	// fixed it, but this record never gives anything up — it only warns. Losing it on an agent restart,
+	// on the other hand, would hide exactly the box it exists for (one whose agent restarts too).
+	restarts24h        []time.Time
+	slowCrashloopSince time.Time // the last raise; kept after it ages out, the hub keys on it MOVING
+}
+
+type controllerSupervisor struct {
+	mu     sync.Mutex
+	guests map[int]*controllerSupState
+	sweeps int
+}
+
+// WatchControllers runs the controller supervisor sweep until ctx is done. No-op when the guest list
+// (staleLock) or the guest executor is not wired.
+func (s *Server) WatchControllers(ctx context.Context) {
+	if s.staleLock == nil || s.guestExec == nil {
+		s.logger.Info("controller-supervisor: not wired (no guest list or no guest executor) — disabled")
+		return
+	}
+	s.logger.Info("controller-supervisor: started", "interval", controllerSupervisorInterval.String(),
+		"confirm_sweeps", controllerSupervisorConfirm, "crashloop_max", controllerCrashloopMax,
+		"crashloop_window", controllerCrashloopWindow.String(),
+		"slow_crashloop_max", controllerSlowCrashloopMax, "slow_crashloop_window", controllerSlowCrashloopWindow.String(),
+		"guests_dir", s.guestsStateDir())
+	t := time.NewTicker(controllerSupervisorInterval)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			s.ControllerSupervisorTick(ctx)
+		}
+	}
+}
+
+func (s *Server) guestsStateDir() string {
+	if s.guestsDir != "" {
+		return s.guestsDir
+	}
+	return defaultGuestsStateDir
+}
+
+// provisionedGuest reports whether the agent provisioned a controller into this guest: the
+// `<guests>/<vmid>/bootstrap` directory exists. The directory itself, not bootstrap.json inside it —
+// the directory is owned by the mapped guest root (0700), so the non-root agent can see the entry but
+// not stat the file within.
+func (s *Server) provisionedGuest(vmid int) bool {
+	fi, err := os.Stat(filepath.Join(s.guestsStateDir(), strconv.Itoa(vmid), "bootstrap"))
+	return err == nil && fi.IsDir()
+}
+
+func (s *Server) controllerParked(vmid int) bool {
+	_, err := os.Stat(filepath.Join(s.guestsStateDir(), strconv.Itoa(vmid), ControllerParkedMarker))
+	return err == nil
+}
+
+func (s *Server) supState(vmid int) *controllerSupState {
+	if s.ctrlSup.guests == nil {
+		s.ctrlSup.guests = map[int]*controllerSupState{}
+	}
+	st := s.ctrlSup.guests[vmid]
+	if st == nil {
+		st = &controllerSupState{}
+		s.loadSlowCounter(vmid, st)
+		s.ctrlSup.guests[vmid] = st
+	}
+	return st
+}
+
+// slowCounterRecord is the on-disk shape of the R-539 counter.
+type slowCounterRecord struct {
+	Restarts           []time.Time `json:"restarts"`
+	SlowCrashloopSince time.Time   `json:"slow_crashloop_since,omitempty"`
+}
+
+func (s *Server) slowCounterPath(vmid int) string {
+	return filepath.Join(s.guestsStateDir(), strconv.Itoa(vmid), controllerSlowCounterFile)
+}
+
+// loadSlowCounter restores the persisted counter into a fresh state. Absent = a clean start; unreadable
+// or corrupt = a clean start with a WARN (a warning counter must never block supervision).
+func (s *Server) loadSlowCounter(vmid int, st *controllerSupState) {
+	b, err := os.ReadFile(s.slowCounterPath(vmid))
+	if err != nil {
+		if !os.IsNotExist(err) {
+			s.logger.Warn("controller-supervisor: slow counter unreadable — starting it from zero", "vmid", vmid, "err", err)
+		}
+		return
+	}
+	var rec slowCounterRecord
+	if err := json.Unmarshal(b, &rec); err != nil {
+		s.logger.Warn("controller-supervisor: slow counter corrupt — starting it from zero", "vmid", vmid, "err", err)
+		return
+	}
+	st.restarts24h = pruneBefore(rec.Restarts, s.clock().Add(-controllerSlowCrashloopWindow))
+	st.slowCrashloopSince = rec.SlowCrashloopSince
+	if len(st.restarts24h) > 0 || !st.slowCrashloopSince.IsZero() {
+		s.logger.Info("controller-supervisor: slow counter restored from disk", "vmid", vmid,
+			"restarts_24h", len(st.restarts24h), "slow_crashloop_since", st.slowCrashloopSince.Format(time.RFC3339))
+	}
+}
+
+// saveSlowCounter writes the counter atomically (tmp + rename, 0600). A failure is logged and the
+// in-memory counter carries on — the next restart retries the write.
+func (s *Server) saveSlowCounter(vmid int, rec slowCounterRecord) {
+	path := s.slowCounterPath(vmid)
+	b, err := json.Marshal(rec)
+	if err == nil {
+		tmp := path + ".tmp"
+		if err = os.WriteFile(tmp, b, 0o600); err == nil {
+			err = os.Rename(tmp, path)
+		}
+	}
+	if err != nil {
+		s.logger.Warn("controller-supervisor: could not persist the slow counter (kept in memory)", "vmid", vmid, "path", path, "err", err)
+	}
+}
+
+// ControllerSupervisorTick performs one sweep. Exported so a test (and a live check) can drive one
+// cycle without waiting on the ticker.
+func (s *Server) ControllerSupervisorTick(ctx context.Context) {
+	if s.staleLock == nil || s.guestExec == nil {
+		return
+	}
+	guests, err := s.staleLock.Guests(ctx)
+	if err != nil {
+		// Ownership unproven ⇒ touch nothing (the guest-power rule).
+		s.logger.Warn("controller-supervisor: guest list unavailable — skipping sweep (ownership unproven)", "err", err)
+		return
+	}
+	var evaluated, down int
+	for _, g := range guests {
+		if ctx.Err() != nil {
+			return
+		}
+		if !s.provisionedGuest(g.VMID) {
+			continue
+		}
+		evaluated++
+		if !s.superviseOneController(ctx, g.VMID, g.Status) {
+			down++
+		}
+	}
+	s.ctrlSup.mu.Lock()
+	s.ctrlSup.sweeps++
+	sweeps := s.ctrlSup.sweeps
+	s.ctrlSup.mu.Unlock()
+	if sweeps%controllerSupervisorHeartbeatEvery == 0 {
+		s.logger.Info("controller-supervisor: alive", "sweeps_since_boot", sweeps,
+			"guests_evaluated", evaluated, "controllers_not_running", down)
+	}
+}
+
+// controllerRunning asks the guest's Docker for the controller's state. Returns (running, known).
+// known=false means the question could not be answered (pct exec failed for a reason other than a
+// missing container) — the caller does nothing on unknown. An ABSENT container is a known "not
+// running": `docker rm` of the controller is the same outage as a kill.
+func (s *Server) controllerRunning(ctx context.Context, vmid int) (running, known bool, status string) {
+	out, err := s.guestExec.GuestExec(ctx, vmid, "docker", "inspect", "-f", "{{.State.Status}}", controllerContainer)
+	if err != nil {
+		msg := strings.ToLower(err.Error() + " " + out)
+		if strings.Contains(msg, "no such object") || strings.Contains(msg, "no such container") {
+			return false, true, "absent"
+		}
+		return false, false, ""
+	}
+	status = strings.TrimSpace(out)
+	// "restarting" is Docker's own restart loop at work — not ours to fight on this sweep.
+	return status == "running" || status == "restarting", true, status
+}
+
+// superviseOneController evaluates one provisioned guest and restarts its controller when every guard
+// allows. Returns false when the controller was observed not running.
+func (s *Server) superviseOneController(ctx context.Context, vmid int, guestStatus string) bool {
+	now := s.clock()
+	if guestStatus != "running" {
+		s.resetNotRunning(vmid)
+		return true // the guest-power watchdog owns a stopped guest; its controller is not "down"
+	}
+
+	running, known, status := s.controllerRunning(ctx, vmid)
+	if !known {
+		s.logger.Debug("controller-supervisor: controller state unknown (guest exec failed) — no action", "vmid", vmid)
+		s.resetNotRunning(vmid)
+		return true
+	}
+	parked := s.controllerParked(vmid)
+	s.ctrlSup.mu.Lock()
+	st := s.supState(vmid)
+	st.parked = parked
+	if running {
+		st.notRunningSeen = 0
+		s.ctrlSup.mu.Unlock()
+		return true
+	}
+	st.notRunningSeen++
+	seen := st.notRunningSeen
+	s.ctrlSup.mu.Unlock()
+
+	if parked {
+		s.logger.Info("controller-supervisor: controller is not running and the guest is PARKED — leaving it",
+			"vmid", vmid, "status", status, "marker", filepath.Join(s.guestsStateDir(), strconv.Itoa(vmid), ControllerParkedMarker))
+		return false
+	}
+	s.swapMu.Lock()
+	swapping := s.swapInFlight[vmid]
+	s.swapMu.Unlock()
+	if swapping {
+		s.logger.Info("controller-supervisor: controller is not running during a controller SWAP — the swap owns it",
+			"vmid", vmid, "status", status)
+		s.resetNotRunning(vmid)
+		return false
+	}
+	if seen < controllerSupervisorConfirm {
+		s.logger.Info("controller-supervisor: controller observed not running — confirming on the next sweep",
+			"vmid", vmid, "status", status, "seen", seen, "of", controllerSupervisorConfirm)
+		return false
+	}
+	lock, _, err := s.staleLock.Lock(ctx, vmid)
+	if err != nil {
+		s.logger.Warn("controller-supervisor: could not read the guest lock — no action (fail-safe)", "vmid", vmid, "err", err)
+		return false
+	}
+	if lock != "" {
+		s.logger.Info("controller-supervisor: guest is LOCKED — another operation owns it, no action", "vmid", vmid, "lock", lock)
+		return false
+	}
+	if busy, berr := s.staleLock.BackupRunning(ctx, vmid); berr != nil || busy {
+		s.logger.Info("controller-supervisor: a vzdump may be in flight for the guest — no action",
+			"vmid", vmid, "backup_running", busy, "err", berr)
+		return false
+	}
+
+	// Backoff.
+	s.ctrlSup.mu.Lock()
+	st = s.supState(vmid)
+	if !st.crashloopSince.IsZero() {
+		if now.Sub(st.crashloopSince) < controllerCrashloopPause {
+			s.ctrlSup.mu.Unlock()
+			s.logger.Warn("controller-supervisor: crash-loop pause in force — not restarting",
+				"vmid", vmid, "since", st.crashloopSince.Format(time.RFC3339), "resume_after", controllerCrashloopPause.String())
+			return false
+		}
+		// Pause over: resume with a clean window. crashloopSince stays as the record of the last
+		// crash-loop (the hub keys on it moving, not on it clearing).
+		st.restarts = nil
+		st.crashloopSince = time.Time{}
+	}
+	st.restarts = pruneBefore(st.restarts, now.Add(-controllerCrashloopWindow))
+	if len(st.restarts) >= controllerCrashloopMax {
+		st.crashloopSince = now
+		n := len(st.restarts)
+		s.ctrlSup.mu.Unlock()
+		s.logger.Error("controller-supervisor: CRASH-LOOP — the controller would not stay up; stopping restarts and raising controller_crashloop",
+			"vmid", vmid, "restarts_in_window", n, "window", controllerCrashloopWindow.String(), "pause", controllerCrashloopPause.String())
+		return false
+	}
+	s.ctrlSup.mu.Unlock()
+
+	reason := "controller container " + status + " on " + strconv.Itoa(controllerSupervisorConfirm) + " consecutive sweeps"
+	s.logger.Warn("controller-supervisor: controller is NOT running — restarting the bootstrap unit",
+		"vmid", vmid, "status", status, "unit", bootstrapUnit)
+	if _, err := s.guestExec.GuestExec(ctx, vmid, "systemctl", "restart", bootstrapUnit); err != nil {
+		s.logger.Error("controller-supervisor: bootstrap restart failed", "vmid", vmid, "err", err)
+		reason += "; restart FAILED: " + err.Error()
+	}
+	s.ctrlSup.mu.Lock()
+	st = s.supState(vmid)
+	st.restarts = append(st.restarts, now)
+	st.restartsTotal++
+	st.lastRestartAt = now
+	st.lastReason = reason
+	st.notRunningSeen = 0
+	// R-539: the slow counter. Raise at most once per 24 hours — the hub mails on the raise MOVING.
+	st.restarts24h = append(pruneBefore(st.restarts24h, now.Add(-controllerSlowCrashloopWindow)), now)
+	n24 := len(st.restarts24h)
+	raised := false
+	if n24 >= controllerSlowCrashloopMax && (st.slowCrashloopSince.IsZero() || now.Sub(st.slowCrashloopSince) >= controllerSlowCrashloopWindow) {
+		st.slowCrashloopSince = now
+		raised = true
+	}
+	rec := slowCounterRecord{Restarts: append([]time.Time(nil), st.restarts24h...), SlowCrashloopSince: st.slowCrashloopSince}
+	s.ctrlSup.mu.Unlock()
+	s.saveSlowCounter(vmid, rec)
+	s.logger.Warn("controller-supervisor: RESTARTED the controller", "vmid", vmid, "reason", reason, "restarts_24h", n24)
+	if raised {
+		s.logger.Warn("controller-supervisor: SLOW CRASH-LOOP — the controller keeps dying; still restarting it, raising controller_slow_crashloop",
+			"vmid", vmid, "restarts_24h", n24, "window", controllerSlowCrashloopWindow.String(), "threshold", controllerSlowCrashloopMax)
+	}
+	return false
+}
+
+func (s *Server) resetNotRunning(vmid int) {
+	s.ctrlSup.mu.Lock()
+	defer s.ctrlSup.mu.Unlock()
+	if st := s.ctrlSup.guests[vmid]; st != nil {
+		st.notRunningSeen = 0
+	}
+}
+
+func (s *Server) clock() time.Time {
+	if s.now != nil {
+		return s.now()
+	}
+	return time.Now().UTC()
+}
+
+func pruneBefore(ts []time.Time, cutoff time.Time) []time.Time {
+	out := ts[:0]
+	for _, t := range ts {
+		if !t.Before(cutoff) {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// ControllerSupervisorStatus is the host-report stanza source (hub.ControllerSupervisorReporter).
+// Nil when the supervisor is not wired, so the stanza is omitted.
+func (s *Server) ControllerSupervisorStatus(_ context.Context) *hub.ControllerSupervisorStatus {
+	if s.staleLock == nil || s.guestExec == nil {
+		return nil
+	}
+	s.ctrlSup.mu.Lock()
+	defer s.ctrlSup.mu.Unlock()
+	out := &hub.ControllerSupervisorStatus{Guests: []hub.ControllerSupervisorGuest{}}
+	for vmid, st := range s.ctrlSup.guests {
+		g := hub.ControllerSupervisorGuest{
+			VMID:          vmid,
+			RestartsTotal: st.restartsTotal,
+			LastReason:    st.lastReason,
+			Parked:        st.parked,
+			Crashloop:     !st.crashloopSince.IsZero(),
+		}
+		if !st.lastRestartAt.IsZero() {
+			g.LastRestartAt = st.lastRestartAt.UTC().Format(time.RFC3339)
+		}
+		if !st.crashloopSince.IsZero() {
+			g.CrashloopSince = st.crashloopSince.UTC().Format(time.RFC3339)
+		}
+		now := s.clock()
+		g.Restarts24h = len(pruneBefore(append([]time.Time(nil), st.restarts24h...), now.Add(-controllerSlowCrashloopWindow)))
+		if !st.slowCrashloopSince.IsZero() {
+			g.SlowCrashloopSince = st.slowCrashloopSince.UTC().Format(time.RFC3339)
+			g.SlowCrashloop = now.Sub(st.slowCrashloopSince) < controllerSlowCrashloopWindow
+		}
+		out.Guests = append(out.Guests, g)
+	}
+	sort.Slice(out.Guests, func(i, j int) bool { return out.Guests[i].VMID < out.Guests[j].VMID })
+	return out
+}

internal/localapi/controllersupervisor_test.go

@@ -0,0 +1,350 @@
+package localapi
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-523 — the controller supervisor. The consequence under test is "a dead controller is started
+// again", and each guard is pinned by the case where acting would be wrong.
+
+type supExec struct {
+	mu        sync.Mutex
+	status    map[int]string // docker .State.Status per vmid; "" = container absent
+	inspectErr error         // non-nil = pct exec itself failed (unknown)
+	restarts  map[int]int
+	// onRestart, when set, is the status the container reaches after a restart (a crash-looper
+	// stays "exited").
+	onRestart string
+}
+
+func (f *supExec) GuestExec(_ context.Context, vmid int, args ...string) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	switch {
+	case len(args) >= 5 && args[0] == "docker" && args[1] == "inspect" && args[3] == "{{.State.Status}}":
+		if f.inspectErr != nil {
+			return "", f.inspectErr
+		}
+		st, ok := f.status[vmid]
+		if !ok || st == "" {
+			return "", errors.New("pct exec: exit status 1: Error: No such object: felhom-controller")
+		}
+		return st + "\n", nil
+	case len(args) == 3 && args[0] == "systemctl" && args[1] == "restart" && args[2] == bootstrapUnit:
+		if f.restarts == nil {
+			f.restarts = map[int]int{}
+		}
+		f.restarts[vmid]++
+		if f.onRestart != "" {
+			f.status[vmid] = f.onRestart
+		}
+		return "", nil
+	}
+	return "", errors.New("supExec: unexpected args")
+}
+func (f *supExec) GuestExecStdin(context.Context, int, io.Reader, ...string) (string, error) {
+	return "", errors.New("supExec: no stdin exec expected")
+}
+func (f *supExec) count(vmid int) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.restarts[vmid]
+}
+
+type supClock struct{ t time.Time }
+
+func (c *supClock) now() time.Time { return c.t }
+
+func supServer(t *testing.T, ex *supExec, ctl *fakeGuestPowerCtl, provisioned ...int) (*Server, *supClock, string) {
+	t.Helper()
+	dir := t.TempDir()
+	for _, v := range provisioned {
+		if err := os.MkdirAll(filepath.Join(dir, strconv.Itoa(v), "bootstrap"), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	clk := &supClock{t: time.Date(2026, 9, 15, 10, 0, 0, 0, time.UTC)}
+	s := &Server{
+		staleLock:    ctl,
+		guestExec:    ex,
+		guestsDir:    dir,
+		swapInFlight: map[int]bool{},
+		logger:       slog.New(slog.NewTextHandler(discardW{}, nil)),
+		now:          clk.now,
+	}
+	return s, clk, dir
+}
+
+func runningGuest(vmid int) *fakeGuestPowerCtl {
+	return &fakeGuestPowerCtl{
+		guests: []proxmox.Guest{{VMID: vmid, Status: "running"}},
+		locks:  map[int]string{}, onboot: map[int]bool{vmid: true},
+	}
+}
+
+// The consequence: a killed controller IS restarted — on the second consecutive observation, not
+// the first (the bootstrap's own rm-f/run window must never be raced).
+//
+// RED-PROOF: delete the `systemctl restart` GuestExec call in superviseOneController → restarts
+// stays 0 → "the killed controller was NOT restarted — this is R-523".
+func TestControllerSupervisor_KilledControllerIsRestarted(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "exited"}, onRestart: "running"}
+	s, _, _ := supServer(t, ex, runningGuest(9201), 9201)
+
+	s.ControllerSupervisorTick(context.Background())
+	if n := ex.count(9201); n != 0 {
+		t.Fatalf("restarted on the FIRST observation (restarts=%d) — must confirm on a second sweep", n)
+	}
+	s.ControllerSupervisorTick(context.Background())
+	if n := ex.count(9201); n != 1 {
+		t.Fatalf("the killed controller was NOT restarted — this is R-523 (restarts=%d)", n)
+	}
+	st := s.ControllerSupervisorStatus(context.Background())
+	if len(st.Guests) != 1 || st.Guests[0].RestartsTotal != 1 || st.Guests[0].LastRestartAt == "" || st.Guests[0].LastReason == "" {
+		t.Fatalf("report stanza did not record the restart: %+v", st.Guests)
+	}
+	// Healthy again → no further restart.
+	s.ControllerSupervisorTick(context.Background())
+	s.ControllerSupervisorTick(context.Background())
+	if n := ex.count(9201); n != 1 {
+		t.Fatalf("a running controller was restarted again (restarts=%d)", n)
+	}
+}
+
+func TestControllerSupervisor_AbsentContainerIsRestarted(t *testing.T) {
+	ex := &supExec{status: map[int]string{}, onRestart: "running"}
+	s, _, _ := supServer(t, ex, runningGuest(9201), 9201)
+	s.ControllerSupervisorTick(context.Background())
+	s.ControllerSupervisorTick(context.Background())
+	if n := ex.count(9201); n != 1 {
+		t.Fatalf("a removed controller container was not restarted (restarts=%d)", n)
+	}
+}
+
+func TestControllerSupervisor_Guards(t *testing.T) {
+	cases := []struct {
+		name  string
+		setup func(s *Server, ex *supExec, ctl *fakeGuestPowerCtl, dir string)
+	}{
+		{"parked", func(s *Server, _ *supExec, _ *fakeGuestPowerCtl, dir string) {
+			if err := os.WriteFile(filepath.Join(dir, "9201", ControllerParkedMarker), nil, 0o600); err != nil {
+				panic(err)
+			}
+		}},
+		{"swap in flight", func(s *Server, _ *supExec, _ *fakeGuestPowerCtl, _ string) { s.swapInFlight[9201] = true }},
+		{"guest locked", func(_ *Server, _ *supExec, ctl *fakeGuestPowerCtl, _ string) { ctl.locks[9201] = "backup" }},
+		{"vzdump running", func(_ *Server, _ *supExec, ctl *fakeGuestPowerCtl, _ string) {
+			ctl.backupRun = map[int]bool{9201: true}
+		}},
+		{"vzdump state unknown", func(_ *Server, _ *supExec, ctl *fakeGuestPowerCtl, _ string) {
+			ctl.backupErr = errors.New("tasks unreadable")
+		}},
+		{"guest not running", func(_ *Server, _ *supExec, ctl *fakeGuestPowerCtl, _ string) {
+			ctl.guests[0].Status = "stopped"
+		}},
+		{"docker state unknown", func(_ *Server, ex *supExec, _ *fakeGuestPowerCtl, _ string) {
+			ex.inspectErr = errors.New("pct exec 9201: exit status 255: container not running")
+		}},
+		{"guest list unavailable", func(_ *Server, _ *supExec, ctl *fakeGuestPowerCtl, _ string) {
+			ctl.guestsErr = errors.New("api down")
+		}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			ex := &supExec{status: map[int]string{9201: "exited"}, onRestart: "running"}
+			ctl := runningGuest(9201)
+			s, _, dir := supServer(t, ex, ctl, 9201)
+			tc.setup(s, ex, ctl, dir)
+			for i := 0; i < 4; i++ {
+				s.ControllerSupervisorTick(context.Background())
+			}
+			if n := ex.count(9201); n != 0 {
+				t.Fatalf("guard %q did not hold: controller restarted %d time(s)", tc.name, n)
+			}
+		})
+	}
+}
+
+// A guest the agent did not provision (no <guests>/<vmid>/bootstrap) is never touched.
+func TestControllerSupervisor_UnprovisionedGuestIgnored(t *testing.T) {
+	ex := &supExec{status: map[int]string{9202: "exited"}}
+	s, _, _ := supServer(t, ex, runningGuest(9202) /* nothing provisioned */)
+	for i := 0; i < 3; i++ {
+		s.ControllerSupervisorTick(context.Background())
+	}
+	if n := ex.count(9202); n != 0 {
+		t.Fatalf("an unprovisioned guest's container was restarted (%d)", n)
+	}
+}
+
+// No thrash: a controller that will not stay up is restarted at most controllerCrashloopMax times
+// inside the window, then the supervisor raises the crash-loop and pauses; after the pause it tries
+// again.
+//
+// RED-PROOF (run 2026-09-15, recorded in REPORT.md): with the `len(st.restarts) >=
+// controllerCrashloopMax` block removed, restarts reached 10 in the first 20 sweeps and the test
+// failed at "crash-looping controller restarted 10 times".
+func TestControllerSupervisor_CrashloopBackoff(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "exited"}, onRestart: "exited"}
+	s, clk, _ := supServer(t, ex, runningGuest(9201), 9201)
+	ctx := context.Background()
+
+	for i := 0; i < 20; i++ { // 10 minutes of 30 s sweeps
+		s.ControllerSupervisorTick(ctx)
+		clk.t = clk.t.Add(controllerSupervisorInterval)
+	}
+	if n := ex.count(9201); n != controllerCrashloopMax {
+		t.Fatalf("crash-looping controller restarted %d times in 10 minutes — want exactly %d then a pause", n, controllerCrashloopMax)
+	}
+	st := s.ControllerSupervisorStatus(ctx).Guests[0]
+	if !st.Crashloop || st.CrashloopSince == "" {
+		t.Fatalf("crash-loop not raised in the report stanza: %+v", st)
+	}
+	// Still paused 25 minutes later.
+	clk.t = clk.t.Add(15 * time.Minute)
+	s.ControllerSupervisorTick(ctx)
+	s.ControllerSupervisorTick(ctx)
+	if n := ex.count(9201); n != controllerCrashloopMax {
+		t.Fatalf("restarted during the crash-loop pause (restarts=%d)", n)
+	}
+	// After the pause: tries again.
+	clk.t = clk.t.Add(controllerCrashloopPause)
+	s.ControllerSupervisorTick(ctx)
+	s.ControllerSupervisorTick(ctx)
+	if n := ex.count(9201); n != controllerCrashloopMax+1 {
+		t.Fatalf("did not resume after the pause (restarts=%d, want %d)", n, controllerCrashloopMax+1)
+	}
+	if since := s.ControllerSupervisorStatus(ctx).Guests[0].CrashloopSince; since != st.CrashloopSince && since != "" {
+		t.Fatalf("crashloop_since changed without a new crash-loop: %q → %q", st.CrashloopSince, since)
+	}
+}
+
+// The wire shape the hub parses. The hub's controller_supervisor_test.go carries this exact JSON.
+func TestControllerSupervisorStanza_WireShape(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "exited"}, onRestart: "running"}
+	s, _, _ := supServer(t, ex, runningGuest(9201), 9201)
+	s.ControllerSupervisorTick(context.Background())
+	s.ControllerSupervisorTick(context.Background())
+	b, _ := json.Marshal(s.ControllerSupervisorStatus(context.Background()))
+	var m map[string][]map[string]any
+	if err := json.Unmarshal(b, &m); err != nil {
+		t.Fatal(err)
+	}
+	g := m["guests"][0]
+	for _, k := range []string{"vmid", "restarts_total", "last_restart_at", "last_reason", "crashloop", "parked", "restarts_24h", "slow_crashloop"} {
+		if _, ok := g[k]; !ok {
+			t.Fatalf("stanza lacks %q — the hub keys on it: %s", k, b)
+		}
+	}
+}
+
+
+// ---- R-539 (operator ruling 3 of 2026-09-16): the SLOW crash loop ----------------------------------
+
+// supKillOnce kills the controller and lets the supervisor restart it (two confirming sweeps), then
+// moves the clock on by gap. The container comes back "running", so each restart is a separate act.
+func supKillOnce(t *testing.T, s *Server, ex *supExec, clk *supClock, gap time.Duration) {
+	t.Helper()
+	before := ex.count(9201)
+	ex.mu.Lock()
+	ex.status[9201] = "exited"
+	ex.mu.Unlock()
+	s.ControllerSupervisorTick(context.Background())
+	clk.t = clk.t.Add(controllerSupervisorInterval)
+	s.ControllerSupervisorTick(context.Background())
+	if ex.count(9201) != before+1 {
+		t.Fatalf("kill was not followed by exactly one restart (restarts %d → %d)", before, ex.count(9201))
+	}
+	clk.t = clk.t.Add(gap)
+}
+
+// The consequence: a controller that dies every 20 minutes — never three times inside the 15-minute
+// brake — raises slow_crashloop on the FIFTH restart in 24 hours, and the raise does not move again on
+// the sixth (the hub mails on movement; once per 24 hours is the ruling).
+//
+// RED-PROOF: without the slow counter the stanza never sets slow_crashloop → "five restarts 20 minutes
+// apart did not raise slow_crashloop — this is R-539".
+func TestControllerSupervisor_SlowCrashloop(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "running"}, onRestart: "running"}
+	s, clk, _ := supServer(t, ex, runningGuest(9201), 9201)
+	ctx := context.Background()
+
+	for i := 1; i <= 4; i++ {
+		supKillOnce(t, s, ex, clk, 20*time.Minute)
+	}
+	g := s.ControllerSupervisorStatus(ctx).Guests[0]
+	if g.Crashloop {
+		t.Fatalf("the 15-minute brake fired on restarts 20 minutes apart — the fixture is wrong: %+v", g)
+	}
+	if g.SlowCrashloop || g.SlowCrashloopSince != "" {
+		t.Fatalf("slow_crashloop raised after only 4 restarts: %+v", g)
+	}
+	supKillOnce(t, s, ex, clk, 20*time.Minute)
+	g = s.ControllerSupervisorStatus(ctx).Guests[0]
+	if !g.SlowCrashloop || g.SlowCrashloopSince == "" || g.Restarts24h != 5 {
+		t.Fatalf("five restarts 20 minutes apart did not raise slow_crashloop — this is R-539: %+v", g)
+	}
+	first := g.SlowCrashloopSince
+	supKillOnce(t, s, ex, clk, 20*time.Minute)
+	g = s.ControllerSupervisorStatus(ctx).Guests[0]
+	if g.SlowCrashloopSince != first {
+		t.Fatalf("the raise moved again on the 6th restart (%q → %q) — the operator would be mailed per restart", first, g.SlowCrashloopSince)
+	}
+	if !g.SlowCrashloop {
+		t.Fatalf("slow_crashloop cleared while the loop continues: %+v", g)
+	}
+}
+
+// The negative control: restarts that never reach five inside any 24 hours never raise it.
+func TestControllerSupervisor_SpreadRestartsNeverSlowCrashloop(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "running"}, onRestart: "running"}
+	s, clk, _ := supServer(t, ex, runningGuest(9201), 9201)
+	for i := 0; i < 8; i++ { // eight restarts, 7 hours apart: at most 4 inside any 24 hours
+		supKillOnce(t, s, ex, clk, 7*time.Hour)
+	}
+	g := s.ControllerSupervisorStatus(context.Background()).Guests[0]
+	if g.SlowCrashloop || g.SlowCrashloopSince != "" {
+		t.Fatalf("restarts 7 hours apart raised slow_crashloop: %+v", g)
+	}
+	if g.Restarts24h > 4 {
+		t.Fatalf("restarts_24h=%d — the 24-hour window is not pruning", g.Restarts24h)
+	}
+}
+
+// An agent restart must not reset the slow counter (the ruling; a box whose AGENT also restarts would
+// otherwise never reach five). The same state directory, a fresh Server.
+//
+// RED-PROOF: keep the counter in memory only → the second Server starts at 0 → "the agent restart
+// reset the slow counter".
+func TestControllerSupervisor_SlowCounterSurvivesAgentRestart(t *testing.T) {
+	ex := &supExec{status: map[int]string{9201: "running"}, onRestart: "running"}
+	s, clk, dir := supServer(t, ex, runningGuest(9201), 9201)
+	for i := 0; i < 4; i++ {
+		supKillOnce(t, s, ex, clk, 20*time.Minute)
+	}
+	s2 := &Server{
+		staleLock:    s.staleLock,
+		guestExec:    ex,
+		guestsDir:    dir,
+		swapInFlight: map[int]bool{},
+		logger:       s.logger,
+		now:          clk.now,
+	}
+	supKillOnce(t, s2, ex, clk, 20*time.Minute)
+	g := s2.ControllerSupervisorStatus(context.Background()).Guests[0]
+	if g.Restarts24h != 5 || !g.SlowCrashloop {
+		t.Fatalf("the agent restart reset the slow counter: %+v", g)
+	}
+}

internal/localapi/escrow_recover.go

@@ -0,0 +1,153 @@
+package localapi
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/escrow"
+)
+
+// R-199 (agent v0.125.0) — the in-guest controller asks the agent to recover the offsite repository
+// password from the hub's sealed bundle, using the customer's recovery code R.
+//
+// WHY THE AGENT AND NOT THE CONTROLLER. Three reasons, all structural: the unsealing binary (`age`)
+// is an agent runtime dependency and is deliberately absent from the controller image; the sealed
+// blob is a HOST-scoped object whose only writer is this agent under the per-host key, so the read is
+// that write's mirror; and the controller is a trust tier down — it should receive one field, not a
+// bundle it has no use for.
+//
+// R'S HANDLING, WHICH IS THE TIGHTEST RULE IN THIS FLOW. R is the one secret in the system that
+// cannot be rotated, re-issued or recovered — it exists only in the customer's hands. Here it:
+//   - arrives in the request body over the already-pinned local-API channel (the operator accepted
+//     that crossing on 2026-08-04; the acceptance covers the CHANNEL, not carelessness at either end);
+//   - is held in memory for the duration of one call and cleared on BOTH paths;
+//   - is never written to disk, never an argument in a process list, and never logged at any level,
+//     including inside an error;
+//   - is never echoed: no response this endpoint can emit contains it.
+//
+// The request-level DEBUG middleware logs method/path/status/duration and never bodies — see
+// `logRequests`. Do not add a body dump.
+//
+// THE RESPONSE CARRIES THE PASSWORD AND ITS HASH. The hash is what this session's proof compares
+// (compare by hash, never by value). The password itself is present because the next link — placing a
+// recovered password so the existing repository opens — needs it, and building a hash-only seam now
+// would have to be torn out to add it. The controller's diagnostic reads only the hash.
+
+type recoverOffsitePasswordRequest struct {
+	VMID int `json:"vmid"`
+	// RecoveryCode is the customer's R. NEVER logged, never persisted, never echoed.
+	RecoveryCode string `json:"recovery_code"`
+}
+
+// handleRecoverOffsitePassword fetches this host's sealed bundle, unseals it with R and returns only
+// the offsite repository password (plus its sha256, for hash-only comparison by the caller).
+func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Request, vmid int) {
+	var req recoverOffsitePasswordRequest
+	if !decodeBody(w, r, &req) {
+		return
+	}
+	if !s.scopedFromBody(w, req.VMID, vmid, r.URL.Path) {
+		return
+	}
+	R := strings.TrimSpace(req.RecoveryCode)
+	req.RecoveryCode = "" // drop the decoded copy immediately
+	if R == "" {
+		writeErr(w, http.StatusBadRequest, "recovery_code is required")
+		return
+	}
+	if s.escrowRecovery == nil {
+		R = ""
+		writeErr(w, http.StatusServiceUnavailable, "offsite key recovery is not configured on this agent (no hub client)")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 60*time.Second)
+	defer cancel()
+	s.logger.Info("local-api: recovering the offsite repository password from the sealed escrow (R via body, never logged/persisted)", "vmid", vmid)
+
+	pw, err := s.escrowRecovery.RecoverOffsiteRepoPassword(ctx, R)
+	R = "" // cleared on BOTH paths, before anything else can happen
+	if err != nil {
+		// Each situation gets its own status and its own words. None of them names a secret.
+		switch {
+		// ── R-224 (2026-08-06) — THE FETCH FAILURE IS NOT A WRONG CODE. ────────────────────────
+		//
+		// This case did not exist, and its absence is the defect. A failed fetch fell through to the
+		// `default` below and was answered with "the recovery code did not open the sealed bundle" —
+		// so a hub that could not be reached was reported to the customer as a bad recovery code, on
+		// the one screen whose whole purpose is to be believed about their backups.
+		//
+		// Measured live 2026-08-05 (CAMPAIGN-11 F3 and F4): a CORRECT current code returned that
+		// message in 0.0556 s with the hub firewalled off, and in 0.0299 s with this agent stopped —
+		// against ~1.0 s for a genuine unseal. No unseal was attempted in either case.
+		//
+		// 502 rather than 400: 4xx says "your request was bad", and the request was not bad — an
+		// upstream dependency failed. The status is the machine-readable half; the controller
+		// classifies on it and must never parse this sentence.
+		//
+		// ⚠ THE CODE WAS NOT USED. Nothing may be said about it — not that it was wrong, and not
+		// that it was right.
+		case errors.Is(err, escrow.ErrBundleFetch):
+			s.logger.Warn("local-api: offsite key recovery: the sealed bundle could not be FETCHED — the recovery code was never used", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadGateway, "the sealed recovery bundle could not be fetched from the hub — the recovery code was NOT used and nothing was written")
+		case errors.Is(err, escrow.ErrNoEscrowBlob):
+			s.logger.Warn("local-api: offsite key recovery: the hub holds no sealed bundle for this host", "vmid", vmid)
+			writeErr(w, http.StatusNotFound, "the hub holds no sealed recovery bundle for this host — no escrow ceremony has run")
+		// ── R-311 (2026-08-12) — THE CODE IS RIGHT, JUST NOT FOR THE CURRENT PACKAGE. ─────────
+		//
+		// Placed ABOVE the default for the same reason ErrBundleFetch is: the default blames the
+		// customer, and this case is the one where the customer is provably not at fault. The code was
+		// used, it worked, and it opened a package the hub is deliberately keeping.
+		//
+		// 422 rather than 400: the request was well-formed AND the credential was valid — what could
+		// not be processed is the pairing of a correct code with the CURRENT package. A 400 would put
+		// it in the same bucket as a mistype, which is the whole defect. The status is the
+		// machine-readable half; the controller classifies on it and must never parse this sentence.
+		//
+		// The date travels in the body because it is the one fact that lets a customer recognise which
+		// code they are holding. No material, no code, no password — only when that package stopped
+		// being current, and whether it can yield a repository password at all.
+		case errors.Is(err, escrow.ErrCodeOpensRetained):
+			var ro *escrow.RetainedOpenedError
+			match := escrow.RetainedMatch{}
+			if errors.As(err, &ro) {
+				match = ro.Match
+			}
+			s.logger.Info("local-api: offsite key recovery: the code did NOT open the current package but DID open a RETAINED one — the customer is not at fault",
+				"vmid", vmid, "superseded_at", match.SupersededAt, "retained_has_restic_pw", match.HasResticPassword)
+			writeStatus(w, http.StatusUnprocessableEntity, false,
+				map[string]any{
+					"opens_retained":         true,
+					"superseded_at":          match.SupersededAt,
+					"retained_has_restic_pw": match.HasResticPassword,
+				},
+				"the recovery code is correct, but it belongs to an EARLIER sealed package (superseded "+match.SupersededAt+"), not the one currently held")
+		case errors.Is(err, escrow.ErrNoResticPassword):
+			s.logger.Warn("local-api: offsite key recovery: the bundle opened but predates the repository-password field", "vmid", vmid)
+			writeErr(w, http.StatusConflict, "the recovery code opened the bundle, but it carries NO offsite repository password (sealed before that field existed; it cannot be retro-fitted)")
+		default:
+			// The fail-closed WRONG-CODE case, and only it: the bundle was fetched and `age -d`
+			// refused it. Every other situation above has its own status. The agent log records the
+			// STEP, never the code.
+			s.logger.Warn("local-api: offsite key recovery: the fetched bundle did not open with the supplied recovery code", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadRequest, "the recovery code did not open the sealed bundle — nothing was written")
+		}
+		return
+	}
+
+	sum := sha256.Sum256([]byte(strings.TrimSpace(pw)))
+	// §8.6's lesson, applied: say exactly WHAT was recovered and what was NOT, so nobody reading this
+	// concludes the wrong thing about the bundle's contents (which is how link 8 came to be missing).
+	s.logger.Info("local-api: offsite repository password RECOVERED from the sealed escrow — returning that field ONLY "+
+		"(the tunnel token, the PBS token and the WG key stay inside the agent and are not returned)",
+		"vmid", vmid, "restic_pw_sha256", hex.EncodeToString(sum[:]))
+	writeOK(w, map[string]any{
+		"restic_repo_password": pw,
+		"restic_pw_sha256":     hex.EncodeToString(sum[:]),
+	})
+}

internal/localapi/escrow_recover_class_test.go

@@ -0,0 +1,99 @@
+package localapi
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/escrow"
+)
+
+// R-224 — THE STATUS IS THE DISCRIMINATOR, and this test asserts the CONSEQUENCE (what the HTTP
+// boundary answers) rather than the mechanism (that the sentinel exists).
+//
+// The controller one trust tier down classifies on the STATUS and must never parse the sentence. So
+// the contract this pins is: four distinguishable situations, four distinct statuses, and the
+// wrong-code message reachable ONLY from a real refusal.
+//
+// Before R-224 the first and last rows both answered 400 with the same sentence — which is how
+// CAMPAIGN-11 F3 told a customer holding a CORRECT code that it did not open their package.
+
+type fakeRecoverer struct{ err error }
+
+func (f fakeRecoverer) RecoverOffsiteRepoPassword(context.Context, string) (string, error) {
+	if f.err != nil {
+		return "", f.err
+	}
+	return "0123456789abcdef0123456789abcdef", nil
+}
+
+func TestRecoverOffsitePassword_EachSituationGetsItsOwnStatus(t *testing.T) {
+	cases := []struct {
+		name       string
+		err        error
+		wantStatus int
+		// mustNotSay guards the specific misattribution each status exists to prevent.
+		mustNotSay []string
+	}{
+		{
+			name:       "fetch failed — the code was NEVER used",
+			err:        errors.Join(escrow.ErrBundleFetch, errors.New("hub: transport error: no route to host")),
+			wantStatus: 502,
+			mustNotSay: []string{"did not open"},
+		},
+		{
+			name:       "wrong code — the bundle WAS fetched and refused it",
+			err:        errors.New("escrow: the recovery code did not unwrap the identity escrow"),
+			wantStatus: 400,
+			mustNotSay: []string{"could not be fetched"},
+		},
+		{
+			name:       "the hub holds no bundle",
+			err:        escrow.ErrNoEscrowBlob,
+			wantStatus: 404,
+			mustNotSay: []string{"did not open"},
+		},
+		{
+			name:       "the bundle predates the repository-password field",
+			err:        escrow.ErrNoResticPassword,
+			wantStatus: 409,
+			mustNotSay: []string{"could not be fetched"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			srv := newTestServerS(t, &fakeGuests{}, &fakeBackups{}, &fakeStore{}, nil)
+			srv.escrowRecovery = fakeRecoverer{err: tc.err}
+			w := do(t, srv.Handler(), "POST", "/escrow/recover-offsite-password", "A",
+				`{"vmid":8200,"recovery_code":"correct horse battery staple sedative anaconda wobbly kingdom placard yodel"}`)
+			if w.Code != tc.wantStatus {
+				t.Fatalf("status: got %d, want %d — body=%s", w.Code, tc.wantStatus, w.Body.String())
+			}
+			for _, phrase := range tc.mustNotSay {
+				if strings.Contains(w.Body.String(), phrase) {
+					t.Fatalf("the %d answer must not say %q — body=%s", tc.wantStatus, phrase, w.Body.String())
+				}
+			}
+		})
+	}
+}
+
+// The pair that matters most, stated as its own assertion so a regression cannot hide inside a table:
+// a fetch failure and a wrong code must never answer with the SAME status. Collapsing them is the
+// whole of R-224.
+func TestRecoverOffsitePassword_FetchFailureAndWrongCodeDiffer(t *testing.T) {
+	status := func(err error) int {
+		srv := newTestServerS(t, &fakeGuests{}, &fakeBackups{}, &fakeStore{}, nil)
+		srv.escrowRecovery = fakeRecoverer{err: err}
+		return do(t, srv.Handler(), "POST", "/escrow/recover-offsite-password", "A",
+			`{"vmid":8200,"recovery_code":"correct horse battery staple sedative anaconda wobbly kingdom placard yodel"}`).Code
+	}
+	fetch := status(errors.Join(escrow.ErrBundleFetch, errors.New("no route to host")))
+	wrong := status(errors.New("escrow: the recovery code did not unwrap the identity escrow"))
+	// RED-PROOF: delete the ErrBundleFetch case from handleRecoverOffsitePassword → both become 400
+	// → this FAILS. That is the exact pre-R-224 code, and the exact defect CAMPAIGN-11 measured.
+	if fetch == wrong {
+		t.Fatalf("a failed fetch and a wrong code must not share a status (both %d)", fetch)
+	}
+}

internal/localapi/server.go

@@ -111,6 +111,14 @@ type HostMetricsProvider interface {
 }
 
 // Options configures a Server.
+// EscrowRecoverer opens this host's sealed identity bundle with the customer recovery code and
+// returns ONLY the offsite restic repository password (R-199 links 6-8). An interface so the
+// localapi package needs no hub-client dependency and the route is testable without crypto.
+// R is an argument and is never retained by any implementation.
+type EscrowRecoverer interface {
+	RecoverOffsiteRepoPassword(ctx context.Context, recoveryCode string) (string, error)
+}
+
 type Options struct {
 	ListenAddr string // bridge IP:port
 	Cert       tls.Certificate
@@ -152,6 +160,10 @@ type Options struct {
 	// NetStorage is the privileged network-mount (NAS) surface (Part A1). OPTIONAL — when nil, the
 	// /netstorage endpoints report "not configured". Satisfied by *storage.SudoHostOps.
 	NetStorage NetworkStorageOps
+	// AfterPrimaryBackup (agent v0.140.0, `11-os-updates.md` §8 step 2) runs right after a SUCCESSFUL backup on the
+	// PRIMARY tier, inside the backup goroutine and BEFORE the host-wide heavy-op gate is released — so the OS leg
+	// that it starts can never overlap another backup or a restore-test (`11` C10). OPTIONAL — nil → nothing runs.
+	AfterPrimaryBackup func(ctx context.Context, vmid int)
 	// Privileged runs the fenced root wrappers (E-2a: felhom-backup-target-apply). OPTIONAL — when
 	// nil, POST /backup/target reports "not configured". Satisfied by *proxmox.ExecRunner.
 	Privileged PrivilegedRunner
@@ -177,6 +189,9 @@ type Options struct {
 	// StaleLock recovers a guest left with a stale vzdump lock by a reboot-during-backup (F2-b), run at
 	// startup by RecoverStaleLockedGuests. OPTIONAL — when nil, the recovery is a no-op.
 	StaleLock StaleLockController
+	// GuestsStateDir (R-523) is the agent's per-guest state dir holding <vmid>/bootstrap and the
+	// controller-parked marker. "" → /var/lib/felhom-agent/guests.
+	GuestsStateDir string
 	// ControllerSwapStateDir holds the per-guest swap state file (crash-safety). "" → /var/lib/felhom-agent.
 	ControllerSwapStateDir string
 	// Intent records drive enroll/eject intent for the self-heal watchdog (slice 10 P3). OPTIONAL —
@@ -210,6 +225,11 @@ type Options struct {
 	// GET /debug/logs. OPTIONAL — when nil the endpoint reports "not configured".
 	LogRing *applog.Ring
 	Logger  *slog.Logger
+	// EscrowRecovery (R-199, v0.125.0) is the offsite-key recovery seam behind
+	// POST /escrow/recover-offsite-password. OPTIONAL — nil → that route reports "not configured"
+	// (503) instead of failing obscurely. Satisfied by escrow.OffsiteKeyRecoverer.
+	EscrowRecovery EscrowRecoverer
+
 }
 
 // defaultBackupCadence is the fallback /backup/due window when none is configured.
@@ -260,6 +280,7 @@ type Server struct {
 	tiers []BackupTier
 	// inFlight (R-85) is shared with the restore-test scheduler so the two never run together.
 	inFlight *backup.InFlight
+	afterPrimaryBackup func(ctx context.Context, vmid int) // the OS leg (agent v0.140.0); nil = none
 	logger   *slog.Logger
 	now      func() time.Time
 
@@ -273,6 +294,11 @@ type Server struct {
 	netMountRoot    string              // the user-data namespace root for the network-mount role gate
 	smbCredsDir     string              // where SMB creds files are written (out-of-band, 0600)
 	escrowStagePath string              // fork-4: 0600 staging file for the pushed restic repo password
+	// escrowRecovery (R-199, v0.125.0) assembles chain links 6-8: fetch this host's own sealed
+	// identity blob from the hub, unseal it with the customer's recovery code, return ONLY the
+	// offsite repository password. OPTIONAL — nil (no hub client configured) makes
+	// POST /escrow/recover-offsite-password answer 503 rather than pretending.
+	escrowRecovery  EscrowRecoverer
 	intent          IntentRecorder      // slice 10 P3 (optional)
 	guestBinds      *GuestBindStore     // F9 startup bind re-assert record (optional)
 	formatJobs      *FormatJobStore     // F20-BUG3 detached-format job record (optional)
@@ -344,6 +370,12 @@ type Server struct {
 	swapMu       sync.Mutex
 	swapInFlight map[int]bool
 
+	// R-523: the in-guest controller supervisor (controllersupervisor.go). guestExec is the same
+	// GuestExecutor the swap uses; guestsDir is the agent's per-guest state dir ("" → default).
+	guestExec GuestExecutor
+	guestsDir string
+	ctrlSup   controllerSupervisor
+
 	// Network-storage verify job (SPIKE-nas-verify): the IN-MEMORY single slot + the seams the
 	// detached pipeline runs through (tests inject; production defaults set in NewServer).
 	netVerifyMu  sync.Mutex
@@ -423,6 +455,7 @@ func NewServer(o Options) (*Server, error) {
 		netMountRoot:    storage.NetworkMountRoot,
 		smbCredsDir:     o.SmbCredsDir,
 		escrowStagePath: o.EscrowStagePath,
+		escrowRecovery:  o.EscrowRecovery,
 		intent:          o.Intent,
 		guestBinds:      o.GuestBinds,
 		formatJobs:      o.FormatJobs,
@@ -441,6 +474,7 @@ func NewServer(o Options) (*Server, error) {
 	// the primary is always first, because that is what the untargeted endpoints act on.
 	s.tiers = normalizeBackupTiers(o.BackupTiers, o.Backups, cadence)
 	s.inFlight = o.InFlight
+	s.afterPrimaryBackup = o.AfterPrimaryBackup
 	if s.backups == nil && len(s.tiers) > 0 {
 		s.backups = s.tiers[0].Service
 	}
@@ -465,7 +499,9 @@ func NewServer(o Options) (*Server, error) {
 	s.statFile = func(path string) bool { _, err := os.Stat(path); return err == nil }
 	if o.ControllerSwap != nil {
 		s.swap = NewControllerSwapper(o.ControllerSwap, o.ControllerSwapStateDir, o.Logger)
+		s.guestExec = o.ControllerSwap
 	}
+	s.guestsDir = o.GuestsStateDir
 	return s, nil
 }
 
@@ -518,6 +554,10 @@ func (s *Server) Handler() http.Handler {
 	mux.HandleFunc("POST /escrow/stage-secret", s.withGuest(s.handleStageEscrowSecret))
 	// fork-4 hygiene: wipe the staged secret once escrowed (controller calls this on confirm). Idempotent.
 	mux.HandleFunc("DELETE /escrow/stage-secret", s.withGuest(s.handleWipeStagedEscrowSecret))
+	// R-199 (v0.125.0): recover the offsite repository password from the hub-held sealed bundle,
+	// using the customer recovery code supplied in the body. Returns that ONE field. See
+	// escrow_recover.go for R's handling rules — they are the tightest in this package.
+	mux.HandleFunc("POST /escrow/recover-offsite-password", s.withGuest(s.handleRecoverOffsitePassword))
 
 	// Controller-driven escrow ceremony (v0.88.0): preflight checklist, the detached root ceremony
 	// job (fixed-argv sudo self-invocation), its status, and the ONE-SHOT in-memory R claim.
@@ -860,6 +900,10 @@ func (s *Server) handleBackup(w http.ResponseWriter, r *http.Request, vmid int)
 		}
 		s.store.RecordBackup(b)
 		s.finishJob(key, jobID, b)
+		// OS leg (agent v0.140.0): after the night's whole-guest copy exists, still holding the heavy-op gate.
+		if b.Success && tier.Primary && s.afterPrimaryBackup != nil {
+			s.afterPrimaryBackup(base, vmid)
+		}
 	}()
 	writeStatus(w, http.StatusAccepted, true, BackupResponse{VMID: vmid, JobID: jobID, Phase: PhaseRunning}, "")
 }
@@ -1061,6 +1105,10 @@ type BackupTierInfo struct {
 	Target         string `json:"target"`
 	CadenceSeconds int64  `json:"cadence_seconds"`
 	Primary        bool   `json:"primary"`
+	// Storage (R-517/R-518, v0.131.0) says whether the tier's Proxmox storage exists on this host
+	// RIGHT NOW: "present" | "absent" | "unknown" (storage view unreadable). Additive — an older
+	// controller ignores it. "unknown" is never "absent": a probe failure must not skip a backup.
+	Storage string `json:"storage,omitempty"`
 }
 
 func (s *Server) handleBackupTiers(w http.ResponseWriter, r *http.Request, vmid int) {
@@ -1070,11 +1118,83 @@ func (s *Server) handleBackupTiers(w http.ResponseWriter, r *http.Request, vmid
 			Target:         t.TargetID,
 			CadenceSeconds: int64(t.Cadence.Seconds()),
 			Primary:        t.Primary,
+			Storage:        s.storagePresence(r.Context(), t.TargetID),
 		})
 	}
 	writeOK(w, resp)
 }
 
+// storagePresence is the tri-state twin of targetStoragePresent (which must stay fail-OPEN for the
+// backup path): "present", "absent", or "unknown" when the storage view cannot be read. Only a
+// successful read that does not list the storage is "absent".
+func (s *Server) storagePresence(ctx context.Context, target string) string {
+	if s.storage == nil || target == "" {
+		return StoragePresenceUnknown
+	}
+	targets, err := s.storage.Observe(ctx)
+	if err != nil {
+		s.logger.Warn("local-api: storage view unavailable for the tier presence report", "target", target, "err", err)
+		return StoragePresenceUnknown
+	}
+	for _, t := range targets {
+		if t.Name == target {
+			return StoragePresencePresent
+		}
+	}
+	return StoragePresenceAbsent
+}
+
+const (
+	StoragePresencePresent = "present"
+	StoragePresenceAbsent  = "absent"
+	StoragePresenceUnknown = "unknown"
+)
+
+// TierBackupState (R-517, v0.131.0) is one tier's truth for the customer's backup page: the newest
+// SUCCESSFUL backup and the last ATTEMPT, kept apart — so a failed attempt can never stand in for a
+// result ("presence is not success").
+type TierBackupState struct {
+	Target  string `json:"target"`
+	Primary bool   `json:"primary"`
+	Storage string `json:"storage"` // present | absent | unknown
+	// LastSuccess is the newest successful backup on this tier. From the in-memory record when there
+	// is one; otherwise from the tier's storage (after an agent restart the record is empty — the
+	// BIGNIGHT F2 page showed no backup at all), in which case only started_at is known and
+	// LastSuccessSource is "storage".
+	LastSuccess       *hub.Backup  `json:"last_success,omitempty"`
+	LastSuccessSource string       `json:"last_success_source,omitempty"` // record | storage
+	LastAttempt       *TierAttempt `json:"last_attempt,omitempty"`
+}
+
+// TierAttempt is the newest recorded attempt on a tier, successful or not.
+type TierAttempt struct {
+	StartedAt string `json:"started_at"`
+	Success   bool   `json:"success"`
+	Error     string `json:"error,omitempty"`
+}
+
+// tierBackupStates builds the per-tier view for one guest.
+func (s *Server) tierBackupStates(ctx context.Context, vmid int) []TierBackupState {
+	out := make([]TierBackupState, 0, len(s.tiers))
+	for _, t := range s.tiers {
+		st := TierBackupState{Target: t.TargetID, Primary: t.Primary, Storage: s.storagePresence(ctx, t.TargetID)}
+		if b := s.pickLatestBackup(ctx, vmid, true, t.TargetID); b != nil {
+			st.LastSuccess, st.LastSuccessSource = b, "record"
+		} else if st.Storage != StoragePresenceAbsent {
+			if when, look := s.newestArchiveOn(ctx, t, vmid); look == archiveFound {
+				st.LastSuccess = &hub.Backup{TargetID: t.TargetID, VMID: vmid, Success: true,
+					StartedAt: when.UTC().Format(time.RFC3339)}
+				st.LastSuccessSource = "storage"
+			}
+		}
+		if a := s.pickLatestBackup(ctx, vmid, false, t.TargetID); a != nil {
+			st.LastAttempt = &TierAttempt{StartedAt: a.StartedAt, Success: a.Success, Error: a.Error}
+		}
+		out = append(out, st)
+	}
+	return out
+}
+
 // tierFromRequest resolves the `?target=` query parameter to a tier.
 //
 // THE COMPATIBILITY RULE (§4): NO target parameter → the PRIMARY tier, and the echoed target is
@@ -1121,6 +1241,10 @@ type BackupStatusResponse struct {
 	Backup *hub.Backup `json:"backup,omitempty"` // latest recorded backup for this guest
 	// Target (R-82) echoes the tier; empty + omitted when untargeted (pre-R-82 bytes).
 	Target string `json:"target,omitempty"`
+	// Tiers (R-517, v0.131.0) is the per-tier truth — newest success, last attempt, storage
+	// presence. Served on the UNTARGETED request only; additive, so an older controller reads the
+	// response exactly as before.
+	Tiers []TierBackupState `json:"tiers,omitempty"`
 }
 
 func (s *Server) handleBackupStatus(w http.ResponseWriter, r *http.Request, vmid int) {
@@ -1132,6 +1256,9 @@ func (s *Server) handleBackupStatus(w http.ResponseWriter, r *http.Request, vmid
 	// across ANY target (echo == "" → pickLatestBackup's match-any path).
 	resp := BackupStatusResponse{VMID: vmid, Phase: PhaseIdle, Target: echo,
 		Backup: s.pickLatestBackup(r.Context(), vmid, false, echo)}
+	if echo == "" {
+		resp.Tiers = s.tierBackupStates(r.Context(), vmid)
+	}
 	if job, ok := s.jobSnapshot(backupJobKey{vmid: vmid, target: tier.TargetID}); ok {
 		resp.Phase = job.Phase
 		resp.JobID = job.JobID
@@ -1348,3 +1475,6 @@ func writeStatus(w http.ResponseWriter, code int, ok bool, data any, errMsg stri
 	w.WriteHeader(code)
 	_ = json.NewEncoder(w).Encode(apiResponse{OK: ok, Data: data, Error: errMsg})
 }
+
+// SetAfterPrimaryBackup wires the hook that runs after a successful primary-tier backup (the OS leg, agent v0.140.0).
+func (s *Server) SetAfterPrimaryBackup(fn func(ctx context.Context, vmid int)) { s.afterPrimaryBackup = fn }

internal/osupdate/leg.go

@@ -0,0 +1,496 @@
+// Package osupdate is the agent's OS-update leg (`11-os-updates.md` §8 steps 2–3): the customer GUEST's Debian fast
+// lane (agent v0.140.0) and, after it in the same pass, the HOST's (agent v0.141.0).
+//
+// It runs right after the night's successful whole-guest backup, while the backup goroutine still holds the host-wide
+// heavy-op gate (so it never overlaps a backup or a restore-test, `11` C10), at most once per night. All root work is
+// the wrapper `felhom-os-apply` (configs/, its own tests); this package only builds plans, calls the wrapper through
+// sudo, judges health and reports to the hub — one report per layer.
+//
+// NO AUTOMATIC UNDO (R-837 measured; `09` §3 decision 81): a failed health check stops, reports `health_failed` and the
+// hub mails the operator; the whole-guest backup taken minutes earlier is the guest's undo, by hand; a host package is
+// put back by hand from the previous release's snapshot (runbook). The host is NEVER rebooted by this package.
+package osupdate
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// WrapperPath is the pinned sudoers vector (configs/felhom-agent.sudoers FELHOM_OSAPPLY).
+const WrapperPath = "/usr/local/sbin/felhom-os-apply"
+
+// DefaultPlanDir is where plans are written (the sudoers glob names it).
+const DefaultPlanDir = "/var/lib/felhom-agent/os"
+
+// Layers.
+const (
+	LayerGuest = "guest"
+	LayerHost  = "host"
+)
+
+// Package is one name=version with its origin.
+type Package struct {
+	Name    string `json:"name"`
+	Version string `json:"version"`
+	Origin  string `json:"origin"`
+}
+
+// Pending is one update the sources offer (origin as apt names it, possibly several).
+type Pending struct {
+	Name   string   `json:"name"`
+	From   string   `json:"from"`
+	To     string   `json:"to"`
+	Origin []string `json:"origin"`
+}
+
+// Container is one container's state as the wrapper saw it.
+type Container struct {
+	State  string `json:"state"`
+	Health string `json:"health"` // healthy | unhealthy | starting | none
+}
+
+// Health is one health reading. Guest layer: DockerOK..Containers. Host layer: HostServices, GuestRunning and the
+// guest's own reading in Guest.
+type Health struct {
+	DockerOK     bool                 `json:"docker_ok"`
+	NetworkOK    bool                 `json:"network_ok"`
+	Controller   string               `json:"controller"`
+	Containers   map[string]Container `json:"containers"`
+	HostServices map[string]string    `json:"host_services,omitempty"`
+	GuestRunning *bool                `json:"guest_running,omitempty"`
+	Guest        *Health              `json:"guest,omitempty"`
+}
+
+// WrapperReport is the wrapper's OSAPPLY-REPORT object.
+type WrapperReport struct {
+	Mode                string          `json:"mode"`
+	Layer               string          `json:"layer"`
+	Refused             json.RawMessage `json:"refused"`
+	Failed              json.RawMessage `json:"failed"`
+	Upgraded            []Package       `json:"upgraded"`
+	Installed           []Package       `json:"installed"`
+	Pending             []Pending       `json:"pending"`
+	RestartNeeded       []string        `json:"restart_needed"`
+	DockerRestartNeeded bool            `json:"docker_restart_needed"`
+	RebootNeeded        bool            `json:"reboot_needed"`
+	RebootScanned       bool            `json:"reboot_scanned"`
+	HealthBefore        *Health         `json:"health_before"`
+	HealthAfter         *Health         `json:"health_after"`
+	Health              *Health         `json:"health"`
+	PassSeconds         float64         `json:"pass_seconds"`
+}
+
+func (w WrapperReport) refused() bool { return len(w.Refused) > 0 && string(w.Refused) != "null" }
+func (w WrapperReport) failed() bool  { return len(w.Failed) > 0 && string(w.Failed) != "null" }
+
+// Report is what the hub receives per layer (hub osupdates.Report — field-exact).
+type Report struct {
+	RunID               string          `json:"run_id"`
+	Layer               string          `json:"layer"`
+	Trigger             string          `json:"trigger"`
+	Mode                string          `json:"mode"`
+	Ring                int             `json:"ring"`
+	ReleaseID           string          `json:"release_id"`
+	Outcome             string          `json:"outcome"`
+	Healthy             bool            `json:"healthy"`
+	HealthReason        string          `json:"health_reason,omitempty"`
+	VMID                int             `json:"vmid"`
+	Upgraded            []Package       `json:"upgraded,omitempty"`
+	Installed           []Package       `json:"installed,omitempty"`
+	Pending             []Pending       `json:"pending,omitempty"`
+	NotCovered          []string        `json:"not_covered,omitempty"`
+	RestartNeeded       []string        `json:"restart_needed,omitempty"`
+	DockerRestartNeeded bool            `json:"docker_restart_needed,omitempty"`
+	RebootNeeded        bool            `json:"reboot_needed,omitempty"`
+	RebootScanned       bool            `json:"reboot_scanned,omitempty"` // the pass looked (host: every pass) — a false RebootNeeded then means "not needed"
+	Refused             json.RawMessage `json:"refused,omitempty"`
+	PassSeconds         float64         `json:"pass_seconds,omitempty"`
+}
+
+// Reporter posts a report to the hub (*hub.Client).
+type Reporter interface {
+	PostOSReport(ctx context.Context, body []byte) error
+}
+
+// Leg runs one OS-update pass for the customer guest and then the host.
+type Leg struct {
+	Runner     proxmox.Runner
+	Hub        Reporter
+	Tunnel     hub.CloudflaredProber // the host health rule needs the tunnel `running` (R-841)
+	Appliance  bool                  // agent.json deployment_mode; the wrapper re-checks the ROOT-owned record (R12)
+	Logger     *slog.Logger
+	PlanDir    string
+	StatePath  string        // last night run (once per night)
+	HealthWait time.Duration // how long health may take to come back (default 5 min)
+	HealthPoll time.Duration // default 15 s
+	MinGap     time.Duration // between night runs (default 20 h)
+	Now        func() time.Time
+	Sleep      func(context.Context, time.Duration)
+
+	mu    sync.Mutex
+	block *hub.WireOSUpdate
+}
+
+// OnDesiredState stores the hub's os_update block (desired.RawConsumer — store only, never block).
+func (l *Leg) OnDesiredState(_ context.Context, resp *hub.DesiredStateResponse) {
+	if resp == nil {
+		return
+	}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.block = resp.DesiredState.OSUpdate
+}
+
+// Block returns the newest os_update block. No block (an older hub, or nothing fetched yet) = ring 1, ON, no
+// release: the box reports and installs nothing.
+func (l *Leg) Block() hub.WireOSUpdate {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if l.block == nil {
+		return hub.WireOSUpdate{Ring: 1, Enabled: true}
+	}
+	return *l.block
+}
+
+// SetBlock sets the block directly (the selftest fetches the desired state itself).
+func (l *Leg) SetBlock(b *hub.WireOSUpdate) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.block = b
+}
+
+func (l *Leg) now() time.Time {
+	if l.Now != nil {
+		return l.Now()
+	}
+	return time.Now()
+}
+
+func (l *Leg) log() *slog.Logger {
+	if l.Logger != nil {
+		return l.Logger
+	}
+	return slog.Default()
+}
+
+func (l *Leg) sleep(ctx context.Context, d time.Duration) {
+	if l.Sleep != nil {
+		l.Sleep(ctx, d)
+		return
+	}
+	select {
+	case <-ctx.Done():
+	case <-time.After(d):
+	}
+}
+
+// IsFast reports whether every origin apt names is Debian / Debian-Security (the fast lane, `11` C3).
+func IsFast(origins []string) bool {
+	if len(origins) == 0 {
+		return false
+	}
+	for _, o := range origins {
+		if o != "Debian" && o != "Debian-Security" {
+			return false
+		}
+	}
+	return true
+}
+
+// HealthVerdict is THE guest health rule (`11` §8.1; pinned by TestHealthVerdict*): docker answers, the guest's
+// network resolves, the controller's own health check is `healthy`, and every container that was running at the
+// start of the pass runs again — and healthy again if it was. "starting" is not yet healthy.
+func HealthVerdict(before, after *Health) (bool, string) {
+	if after == nil {
+		return false, "no health reading"
+	}
+	if !after.DockerOK {
+		return false, "docker does not answer"
+	}
+	if !after.NetworkOK {
+		return false, "the guest cannot resolve deb.debian.org"
+	}
+	if after.Controller != "healthy" {
+		return false, "the controller is " + after.Controller
+	}
+	if before == nil {
+		return true, ""
+	}
+	names := make([]string, 0, len(before.Containers))
+	for n := range before.Containers {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	for _, n := range names {
+		b := before.Containers[n]
+		if b.State != "running" {
+			continue
+		}
+		a, ok := after.Containers[n]
+		if !ok || a.State != "running" {
+			return false, n + " was running and is not"
+		}
+		if b.Health == "healthy" && a.Health != "healthy" {
+			return false, n + " was healthy and is " + a.Health
+		}
+	}
+	return true, ""
+}
+
+// HostHealthVerdict is THE host health rule (`11` §8.2; pinned by TestHostHealthVerdict): the Proxmox daemons and the
+// agent are active, the customer guest still runs, the guest's own rule still passes against the start of the pass,
+// and the tunnel is `running` (R-841).
+func HostHealthVerdict(before, after *Health, tunnel string) (bool, string) {
+	if after == nil {
+		return false, "no health reading"
+	}
+	svcs := make([]string, 0, len(after.HostServices))
+	for s := range after.HostServices {
+		svcs = append(svcs, s)
+	}
+	sort.Strings(svcs)
+	if len(svcs) == 0 {
+		return false, "no host service reading"
+	}
+	for _, s := range svcs {
+		if after.HostServices[s] != "active" {
+			return false, s + " is " + after.HostServices[s]
+		}
+	}
+	if after.GuestRunning == nil || !*after.GuestRunning {
+		return false, "the customer guest is not running"
+	}
+	var gb *Health
+	if before != nil {
+		gb = before.Guest
+	}
+	if ok, why := HealthVerdict(gb, after.Guest); !ok {
+		return false, "guest: " + why
+	}
+	if tunnel != hub.TunnelRunning {
+		return false, "the tunnel is " + tunnel
+	}
+	return true, ""
+}
+
+// call writes the plan and runs the wrapper once.
+func (l *Leg) call(ctx context.Context, runID string, plan map[string]any) (WrapperReport, error) {
+	dir := l.PlanDir
+	if dir == "" {
+		dir = DefaultPlanDir
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return WrapperReport{}, fmt.Errorf("osupdate: plan dir: %w", err)
+	}
+	b, _ := json.Marshal(plan)
+	path := filepath.Join(dir, fmt.Sprintf("plan-%s-%s-%s.json", runID, plan["layer"], plan["mode"]))
+	if err := os.WriteFile(path, b, 0o600); err != nil {
+		return WrapperReport{}, fmt.Errorf("osupdate: write plan: %w", err)
+	}
+	defer os.Remove(path)
+	stdout, stderr, err := l.Runner.Run(ctx, WrapperPath, "--plan", path)
+	for _, line := range strings.Split(strings.TrimSpace(string(stderr)), "\n") {
+		if strings.HasPrefix(line, "os-apply: ") {
+			l.log().Info("osupdate: wrapper", "line", line)
+		}
+	}
+	var rep WrapperReport
+	found := false
+	for _, line := range strings.Split(string(stdout), "\n") {
+		if strings.HasPrefix(line, "OSAPPLY-REPORT ") {
+			if jerr := json.Unmarshal([]byte(strings.TrimPrefix(line, "OSAPPLY-REPORT ")), &rep); jerr == nil {
+				found = true
+			}
+		}
+	}
+	if !found {
+		return rep, fmt.Errorf("osupdate: wrapper gave no report (err %v): %s", err, strings.TrimSpace(string(stderr)))
+	}
+	return rep, nil // a refusal / failure is IN the report (exit 2 / 3), not an error here
+}
+
+// Run is one pass: the guest layer, then (on an appliance, after a good guest step) the host layer. Returns both
+// reports (host empty when skipped). trigger is "night" or "debug".
+func (l *Leg) Run(ctx context.Context, vmid int, trigger string) (guest Report, host Report) {
+	runID := l.now().UTC().Format("20060102T150405Z")
+	lg := l.log().With("run", runID, "vmid", vmid, "trigger", trigger)
+	if trigger == "night" && l.StatePath != "" {
+		gap := l.MinGap
+		if gap == 0 {
+			gap = 20 * time.Hour
+		}
+		if b, err := os.ReadFile(l.StatePath); err == nil {
+			if last, perr := time.Parse(time.RFC3339, strings.TrimSpace(string(b))); perr == nil && l.now().Sub(last) < gap {
+				lg.Info("osupdate: skipped — already ran tonight", "last", last.UTC().Format(time.RFC3339))
+				return Report{RunID: runID, Layer: LayerGuest, Outcome: "skipped"}, Report{}
+			}
+		}
+	}
+	blk := l.Block()
+	guest = l.runLayer(ctx, runID, LayerGuest, vmid, trigger, blk)
+	if trigger == "night" && l.StatePath != "" {
+		_ = os.WriteFile(l.StatePath, []byte(l.now().UTC().Format(time.RFC3339)), 0o600)
+	}
+	switch {
+	case !l.Appliance:
+		lg.Info("osupdate: host step skipped — not an appliance install (a BYO host belongs to its owner, `11` §1)")
+	case !(guest.Outcome == "applied" || guest.Outcome == "nothing" || guest.Outcome == "inventory") || !guest.Healthy:
+		lg.Warn("osupdate: host step skipped — the guest step did not end healthy", "guest_outcome", guest.Outcome, "reason", guest.HealthReason)
+	default:
+		host = l.runLayer(ctx, runID, LayerHost, vmid, trigger, blk)
+	}
+	return guest, host
+}
+
+func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigger string, blk hub.WireOSUpdate) Report {
+	rel := hub.WireOSRelease{ID: "ring0-" + runID}
+	var wire *hub.WireOSRelease
+	if layer == LayerGuest {
+		wire = blk.Release
+	} else {
+		wire = blk.HostRelease
+	}
+	if blk.Ring == 1 {
+		rel = hub.WireOSRelease{}
+		if wire != nil {
+			rel = *wire
+		}
+	}
+	rep := Report{RunID: runID, Layer: layer, Trigger: trigger, Ring: blk.Ring, VMID: vmid, ReleaseID: rel.ID}
+	lg := l.log().With("run", runID, "layer", layer, "vmid", vmid, "ring", blk.Ring, "trigger", trigger)
+	lg.Info("osupdate: START", "enabled", blk.Enabled, "release", rel.ID)
+
+	plan := map[string]any{"release_id": rel.ID, "layer": layer, "lane": "fast", "vmid": vmid, "snapshot": rel.Snapshot,
+		"packages": []Package{}, "mode": "apply", "select": "listed"}
+	if rel.ID == "" {
+		plan["release_id"] = "none"
+	}
+	planned := map[string]bool{}
+	switch {
+	case !blk.Enabled:
+		plan["mode"] = "inventory"
+		lg.Info("osupdate: switched OFF for this box — reporting only")
+	case blk.Ring == 0:
+		plan["select"] = "pending-fast" // the wrapper picks every pending Debian / Debian-Security upgrade
+	case len(rel.Packages) == 0:
+		plan["mode"] = "inventory" // ring 1 with no approved release for this layer: nothing to install
+	default:
+		var pk []Package
+		for _, p := range rel.Packages {
+			pk = append(pk, Package{Name: p.Name, Version: p.Version, Origin: p.Origin})
+			planned[p.Name] = true
+		}
+		plan["packages"] = pk
+	}
+	rep.Mode = plan["mode"].(string)
+	wr, err := l.call(ctx, runID, plan)
+	switch {
+	case err != nil:
+		rep.Outcome, rep.HealthReason = "failed", err.Error()
+		return l.finish(ctx, lg, rep)
+	case wr.refused():
+		rep.Outcome, rep.Refused = "refused", wr.Refused
+		return l.finish(ctx, lg, rep)
+	case wr.failed():
+		rep.Outcome, rep.Refused = "failed", wr.Failed
+	}
+	rep.Upgraded, rep.PassSeconds = wr.Upgraded, wr.PassSeconds
+	if rep.Outcome == "" {
+		switch {
+		case rep.Mode == "inventory" && !blk.Enabled:
+			rep.Outcome = "inventory"
+		case len(wr.Upgraded) == 0:
+			rep.Outcome = "nothing"
+		default:
+			rep.Outcome = "applied"
+		}
+	}
+	if blk.Ring == 0 {
+		for _, u := range wr.Upgraded {
+			planned[u.Name] = true
+		}
+	}
+	// Health: compare with the start of the pass; give restarted services time (only after an install).
+	cur := wr.HealthAfter
+	verdict := func(h *Health) (bool, string) {
+		if layer == LayerHost {
+			t := hub.TunnelUnknown
+			if l.Tunnel != nil {
+				t, _ = l.Tunnel.Status(ctx)
+			}
+			return HostHealthVerdict(wr.HealthBefore, h, t)
+		}
+		return HealthVerdict(wr.HealthBefore, h)
+	}
+	if len(wr.Upgraded) > 0 {
+		wait, poll := l.HealthWait, l.HealthPoll
+		if wait == 0 {
+			wait = 5 * time.Minute
+		}
+		if poll == 0 {
+			poll = 15 * time.Second
+		}
+		deadline := l.now().Add(wait)
+		for {
+			ok, why := verdict(cur)
+			rep.Healthy, rep.HealthReason = ok, why
+			if ok || !l.now().Before(deadline) || ctx.Err() != nil {
+				break
+			}
+			l.sleep(ctx, poll)
+			hp := map[string]any{"release_id": plan["release_id"], "layer": layer, "lane": "fast", "vmid": vmid, "mode": "health", "packages": []Package{}}
+			hr, herr := l.call(ctx, runID, hp)
+			if herr == nil && hr.Health != nil {
+				cur = hr.Health
+			}
+		}
+		if !rep.Healthy && rep.Outcome == "applied" {
+			rep.Outcome = "health_failed"
+		}
+	} else {
+		rep.Healthy, rep.HealthReason = verdict(cur)
+	}
+	rep.Installed, rep.Pending = wr.Installed, wr.Pending
+	rep.RestartNeeded, rep.DockerRestartNeeded, rep.RebootNeeded = wr.RestartNeeded, wr.DockerRestartNeeded, wr.RebootNeeded
+	rep.RebootScanned = wr.RebootScanned
+	rep.NotCovered = notCovered(wr.Pending, blk.Ring, planned)
+	return l.finish(ctx, lg, rep)
+}
+
+// notCovered lists pending updates no approved release covers: in ring 0 everything outside the fast lane; in ring 1
+// also every fast-lane update the release did not name.
+func notCovered(pending []Pending, ring int, planned map[string]bool) []string {
+	var out []string
+	for _, p := range pending {
+		if !IsFast(p.Origin) || (ring == 1 && !planned[p.Name]) {
+			out = append(out, p.Name)
+		}
+	}
+	return out
+}
+
+func (l *Leg) finish(ctx context.Context, lg *slog.Logger, rep Report) Report {
+	lg.Info("osupdate: DONE", "outcome", rep.Outcome, "healthy", rep.Healthy, "reason", rep.HealthReason,
+		"upgraded", len(rep.Upgraded), "pending", len(rep.Pending), "not_covered", len(rep.NotCovered),
+		"restart_needed", len(rep.RestartNeeded), "reboot_needed", rep.RebootNeeded, "wrapper_seconds", rep.PassSeconds)
+	if l.Hub != nil {
+		body, _ := json.Marshal(rep)
+		rctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), time.Minute)
+		defer cancel()
+		if err := l.Hub.PostOSReport(rctx, body); err != nil {
+			lg.Warn("osupdate: reporting to the hub failed (the run itself is done)", "err", err)
+		}
+	}
+	return rep
+}

internal/osupdate/leg_test.go

@@ -0,0 +1,369 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// fakeWrapper plays /usr/local/sbin/felhom-os-apply: it reads the plan the leg wrote and answers per layer and mode.
+type fakeWrapper struct {
+	t         *testing.T
+	pending   []Pending
+	applyRep  map[string]WrapperReport // per layer
+	healthSeq map[string][]*Health     // per layer: answers to successive "health" calls
+	plans     []map[string]any
+}
+
+func yes() *bool { b := true; return &b }
+
+func guestOK() *Health {
+	return &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{
+		"felhom-controller": {State: "running", Health: "healthy"}, "app": {State: "running", Health: "healthy"}}}
+}
+
+func hostOK() *Health {
+	return &Health{HostServices: map[string]string{"pveproxy": "active", "pvedaemon": "active", "pvestatd": "active",
+		"pve-cluster": "active", "felhom-agent": "active"}, GuestRunning: yes(), Guest: guestOK()}
+}
+
+func (f *fakeWrapper) Run(_ context.Context, name string, args ...string) ([]byte, []byte, error) {
+	if name != WrapperPath || len(args) != 2 || args[0] != "--plan" {
+		f.t.Fatalf("unexpected command %s %v", name, args)
+	}
+	b, err := os.ReadFile(args[1])
+	if err != nil {
+		f.t.Fatal(err)
+	}
+	var plan map[string]any
+	json.Unmarshal(b, &plan)
+	f.plans = append(f.plans, plan)
+	layer := plan["layer"].(string)
+	ok := guestOK()
+	if layer == LayerHost {
+		ok = hostOK()
+	}
+	var rep WrapperReport
+	switch plan["mode"] {
+	case "inventory":
+		rep = WrapperReport{Mode: "inventory", Pending: f.pending, HealthBefore: ok, HealthAfter: ok,
+			Installed: []Package{{Name: "libc6", Version: "u3", Origin: "Debian"}}}
+	case "apply":
+		rep = f.applyRep[layer]
+		rep.Mode = "apply"
+		if rep.HealthBefore == nil {
+			rep.HealthBefore = ok
+		}
+		if rep.HealthAfter == nil {
+			rep.HealthAfter = ok
+		}
+	case "health":
+		if seq := f.healthSeq[layer]; len(seq) > 0 {
+			rep.Health, f.healthSeq[layer] = seq[0], seq[1:]
+		} else {
+			rep.Health = ok
+		}
+	}
+	out, _ := json.Marshal(rep)
+	return []byte("OSAPPLY-REPORT " + string(out) + "\n"), []byte("os-apply: DONE rc=0\n"), nil
+}
+
+func (f *fakeWrapper) RunStdin(ctx context.Context, _ io.Reader, name string, args ...string) ([]byte, []byte, error) {
+	return f.Run(ctx, name, args...)
+}
+
+type fakeHub struct{ reports []Report }
+
+func (h *fakeHub) PostOSReport(_ context.Context, body []byte) error {
+	var r Report
+	json.Unmarshal(body, &r)
+	h.reports = append(h.reports, r)
+	return nil
+}
+
+type fakeTunnel struct{ st string }
+
+func (t fakeTunnel) Status(context.Context) (string, string) { return t.st, "" }
+
+func newLeg(t *testing.T, w *fakeWrapper, blk *hub.WireOSUpdate) (*Leg, *fakeHub) {
+	h := &fakeHub{}
+	now := time.Date(2026, 10, 4, 4, 0, 0, 0, time.UTC)
+	if w.applyRep == nil {
+		w.applyRep = map[string]WrapperReport{}
+	}
+	if w.healthSeq == nil {
+		w.healthSeq = map[string][]*Health{}
+	}
+	l := &Leg{Runner: w, Hub: h, PlanDir: t.TempDir(), StatePath: filepath.Join(t.TempDir(), "last"),
+		HealthWait: time.Minute, HealthPoll: 10 * time.Second, Appliance: true, Tunnel: fakeTunnel{hub.TunnelRunning},
+		Now:   func() time.Time { return now },
+		Sleep: func(_ context.Context, d time.Duration) { now = now.Add(d) }}
+	if blk != nil {
+		l.SetBlock(blk)
+	}
+	return l, h
+}
+
+var pend = []Pending{
+	{Name: "libc6", From: "u3", To: "u4", Origin: []string{"Debian"}},
+	{Name: "openssl", From: "u1", To: "u3", Origin: []string{"Debian-Security", "Debian"}},
+	{Name: "docker-ce", From: "29.7", To: "29.8", Origin: []string{"Docker CE"}},
+}
+
+func calls(w *fakeWrapper) string {
+	var m []string
+	for _, p := range w.plans {
+		m = append(m, p["layer"].(string)+":"+p["mode"].(string))
+	}
+	return strings.Join(m, ",")
+}
+
+// Ring 0: ONE wrapper call per layer (R-845), select pending-fast (the wrapper picks every Debian / Debian-Security
+// upgrade), from live sources; the guest step first, then the host step.
+func TestRing0_OneCallPerLayer(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{
+		LayerGuest: {Upgraded: []Package{{Name: "libc6", Version: "u4"}, {Name: "openssl", Version: "u3"}}, Pending: pend[2:]},
+		LayerHost:  {Upgraded: []Package{{Name: "openssl", Version: "u3"}}},
+	}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.Outcome != "applied" || !g.Healthy || ho.Outcome != "applied" || !ho.Healthy {
+		t.Fatalf("guest %+v\nhost %+v", g, ho)
+	}
+	if calls(w) != "guest:apply,host:apply" {
+		t.Fatalf("calls = %s, want one apply per layer, guest first", calls(w))
+	}
+	for _, p := range w.plans {
+		if p["select"] != "pending-fast" || p["snapshot"] != "" || len(p["packages"].([]any)) != 0 {
+			t.Fatalf("ring-0 plan = %v", p)
+		}
+	}
+	if len(g.NotCovered) != 1 || g.NotCovered[0] != "docker-ce" {
+		t.Fatalf("not covered = %v", g.NotCovered)
+	}
+	if len(h.reports) != 2 || h.reports[0].Layer != LayerGuest || h.reports[1].Layer != LayerHost {
+		t.Fatalf("hub got %+v", h.reports)
+	}
+}
+
+// Ring 1 installs EXACTLY each layer's own approved release (a guest release is not a host release).
+func TestRing1_EachLayerItsOwnRelease(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{
+		LayerGuest: {Upgraded: []Package{{Name: "libc6", Version: "g-u4"}}, Pending: pend[1:]},
+		LayerHost:  {Upgraded: []Package{{Name: "openssl", Version: "h-u3"}}},
+	}}
+	gr := &hub.WireOSRelease{ID: "os-g", Snapshot: "20261004T080000Z", Packages: []hub.WireOSPackage{{Name: "libc6", Version: "g-u4", Origin: "Debian"}}}
+	hr := &hub.WireOSRelease{ID: "os-h", Snapshot: "20261004T090000Z", Packages: []hub.WireOSPackage{{Name: "openssl", Version: "h-u3", Origin: "Debian-Security"}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 1, Enabled: true, Release: gr, HostRelease: hr})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.ReleaseID != "os-g" || ho.ReleaseID != "os-h" {
+		t.Fatalf("release ids %q %q", g.ReleaseID, ho.ReleaseID)
+	}
+	gp, hp := w.plans[0], w.plans[1]
+	if gp["snapshot"] != "20261004T080000Z" || gp["packages"].([]any)[0].(map[string]any)["version"] != "g-u4" {
+		t.Fatalf("guest plan %v", gp)
+	}
+	if hp["layer"] != LayerHost || hp["snapshot"] != "20261004T090000Z" || hp["packages"].([]any)[0].(map[string]any)["name"] != "openssl" {
+		t.Fatalf("host plan %v", hp)
+	}
+	if strings.Join(g.NotCovered, ",") != "openssl,docker-ce" {
+		t.Fatalf("guest not covered = %v", g.NotCovered)
+	}
+}
+
+func TestRing1_NoReleaseIsInventory(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 1, Enabled: true})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.Outcome != "nothing" || ho.Outcome != "nothing" || calls(w) != "guest:inventory,host:inventory" {
+		t.Fatalf("g=%+v h=%+v calls=%s", g, ho, calls(w))
+	}
+}
+
+// No block from the hub (an older hub): ring 1, ON, no release → reports, installs nothing.
+func TestNoBlock_IsRing1Nothing(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend}
+	l, _ := newLeg(t, w, nil)
+	if g, _ := l.Run(context.Background(), 9201, "night"); g.Outcome != "nothing" || g.Ring != 1 {
+		t.Fatalf("g=%+v calls=%s", g, calls(w))
+	}
+}
+
+// Switched OFF: the box reports but installs nothing, on both layers.
+func TestSwitchOff_ReportsOnly(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: false})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.Outcome != "inventory" || ho.Outcome != "inventory" || calls(w) != "guest:inventory,host:inventory" || len(h.reports) != 2 {
+		t.Fatalf("g=%+v h=%+v calls=%s", g, ho, calls(w))
+	}
+}
+
+// Not an appliance (BYO, `11` §1): the host step never runs — no host plan at all.
+func TestBYO_NoHostPlan(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6"}}}}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Appliance = false
+	_, ho := l.Run(context.Background(), 9201, "night")
+	if ho.Outcome != "" || calls(w) != "guest:apply" || len(h.reports) != 1 {
+		t.Fatalf("a BYO box got a host step: host=%+v calls=%s", ho, calls(w))
+	}
+}
+
+// A failed guest step skips the host step that night.
+func TestGuestFailure_SkipsTheHost(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{
+		LayerGuest: {Refused: json.RawMessage(`{"code":"R6","reason":"x"}`)}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.Outcome != "refused" || ho.Outcome != "" || calls(w) != "guest:apply" {
+		t.Fatalf("g=%+v h=%+v calls=%s", g, ho, calls(w))
+	}
+}
+
+// Unhealthy after the run, and still unhealthy at the end of the wait → health_failed; the host step is skipped.
+func TestHealth_FailsAfterTheWait(t *testing.T) {
+	bad := &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{
+		"felhom-controller": {State: "running", Health: "healthy"}, "app": {State: "exited"}}}
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6"}}, HealthAfter: bad}},
+		healthSeq: map[string][]*Health{LayerGuest: {bad, bad, bad, bad, bad, bad, bad, bad}}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	g, ho := l.Run(context.Background(), 9201, "night")
+	if g.Outcome != "health_failed" || g.Healthy || !strings.Contains(g.HealthReason, "app was running") || ho.Outcome != "" {
+		t.Fatalf("g=%+v h=%+v", g, ho)
+	}
+	if h.reports[0].Outcome != "health_failed" {
+		t.Fatal("the hub was not told")
+	}
+}
+
+// A service that takes a moment to come back is not a failure: the poll sees it recover inside the wait.
+func TestHealth_RecoversInsideTheWait(t *testing.T) {
+	starting := &Health{DockerOK: true, NetworkOK: true, Controller: "starting"}
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6"}}, HealthAfter: starting}},
+		healthSeq: map[string][]*Health{LayerGuest: {starting}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	if g, _ := l.Run(context.Background(), 9201, "night"); g.Outcome != "applied" || !g.Healthy {
+		t.Fatalf("g = %+v", g)
+	}
+}
+
+// The host step judged unhealthy when the tunnel is down after it.
+func TestHost_TunnelDownFailsTheHostStep(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{LayerHost: {Upgraded: []Package{{Name: "openssl"}}}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Tunnel = fakeTunnel{hub.TunnelNotRunning}
+	_, ho := l.Run(context.Background(), 9201, "night")
+	if ho.Outcome != "health_failed" || !strings.Contains(ho.HealthReason, "tunnel") {
+		t.Fatalf("host = %+v", ho)
+	}
+}
+
+func TestHealthVerdict(t *testing.T) {
+	ok := &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{"a": {State: "running", Health: "healthy"}}}
+	cases := []struct {
+		name   string
+		before *Health
+		after  *Health
+		want   bool
+	}{
+		{"all good", ok, ok, true},
+		{"no reading", ok, nil, false},
+		{"docker down", ok, &Health{NetworkOK: true, Controller: "healthy"}, false},
+		{"no network", ok, &Health{DockerOK: true, Controller: "healthy"}, false},
+		{"controller starting", ok, &Health{DockerOK: true, NetworkOK: true, Controller: "starting"}, false},
+		{"only the controller differs", ok, &Health{DockerOK: true, NetworkOK: true, Controller: "unhealthy", Containers: map[string]Container{"a": {State: "running", Health: "healthy"}}}, false},
+		{"app gone", ok, &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{}}, false},
+		{"app unhealthy", ok, &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{"a": {State: "running", Health: "unhealthy"}}}, false},
+		{"stopped before stays stopped", &Health{Containers: map[string]Container{"x": {State: "exited"}}}, &Health{DockerOK: true, NetworkOK: true, Controller: "healthy"}, true},
+	}
+	for _, c := range cases {
+		if got, why := HealthVerdict(c.before, c.after); got != c.want {
+			t.Errorf("%s: got %v (%s), want %v", c.name, got, why, c.want)
+		}
+	}
+}
+
+// The host rule: every listed daemon active, the guest running and passing its own rule, the tunnel running.
+// Red-proofs: drop any one check and its case fails.
+func TestHostHealthVerdict(t *testing.T) {
+	no := false
+	svcDown := hostOK()
+	svcDown.HostServices["pveproxy"] = "failed"
+	guestDown := hostOK()
+	guestDown.GuestRunning = &no
+	guestApp := hostOK()
+	guestApp.Guest = &Health{DockerOK: true, NetworkOK: true, Controller: "healthy", Containers: map[string]Container{"felhom-controller": {State: "running", Health: "healthy"}}}
+	cases := []struct {
+		name   string
+		after  *Health
+		tunnel string
+		want   bool
+		why    string
+	}{
+		{"all good", hostOK(), hub.TunnelRunning, true, ""},
+		{"a daemon down", svcDown, hub.TunnelRunning, false, "pveproxy"},
+		{"the guest stopped", guestDown, hub.TunnelRunning, false, "guest is not running"},
+		{"an app in the guest gone", guestApp, hub.TunnelRunning, false, "app was running"},
+		{"the tunnel down", hostOK(), hub.TunnelNotRunning, false, "tunnel"},
+		{"the tunnel unknown", hostOK(), hub.TunnelUnknown, false, "tunnel"},
+		{"no services read", &Health{GuestRunning: yes(), Guest: guestOK()}, hub.TunnelRunning, false, "no host service"},
+	}
+	for _, c := range cases {
+		got, why := HostHealthVerdict(hostOK(), c.after, c.tunnel)
+		if got != c.want || !strings.Contains(why, c.why) {
+			t.Errorf("%s: got %v (%s), want %v (…%s…)", c.name, got, why, c.want, c.why)
+		}
+	}
+}
+
+func TestOncePerNight(t *testing.T) {
+	w := &fakeWrapper{t: t, pending: pend, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6"}}}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Run(context.Background(), 9201, "night")
+	n := len(w.plans)
+	if g, _ := l.Run(context.Background(), 9201, "night"); g.Outcome != "skipped" || len(w.plans) != n {
+		t.Fatalf("a second night run in the same night ran: %+v", g)
+	}
+	if g, _ := l.Run(context.Background(), 9201, "debug"); g.Outcome == "skipped" {
+		t.Fatal("the debug action must not be throttled")
+	}
+}
+
+// The root wrapper's own suite (configs/test_felhom_os_apply.py) runs with `go test ./...` so CI covers it.
+func TestWrapperSuite(t *testing.T) {
+	py, err := exec.LookPath("python3")
+	if err != nil {
+		t.Skip("python3 not available")
+	}
+	cmd := exec.Command(py, "-B", "../../configs/test_felhom_os_apply.py")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("wrapper suite failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "OK") {
+		t.Fatalf("wrapper suite did not report OK:\n%s", out)
+	}
+}
+
+// The host's restart scan result reaches the hub with reboot_scanned, so the hub can tell "looked: not needed" (a
+// reboot cleared it) from "did not look". Red-proof: drop the RebootScanned copy in runLayer and this fails.
+func TestHostReport_CarriesRebootScanned(t *testing.T) {
+	w := &fakeWrapper{t: t, applyRep: map[string]WrapperReport{
+		LayerGuest: {},
+		LayerHost:  {RebootScanned: true, RebootNeeded: true, RestartNeeded: []string{"lxc-start"}},
+	}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Run(context.Background(), 9201, "night")
+	if len(h.reports) != 2 || !h.reports[1].RebootScanned || !h.reports[1].RebootNeeded || h.reports[0].RebootScanned {
+		t.Fatalf("hub got %+v", h.reports)
+	}
+}

internal/pbs/client.go

@@ -10,6 +10,8 @@ import (
 	"net/url"
 	"strings"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/httpx"
 )
 
 // Client is the PBS-API client for ONE PBS server. Construct with NewClient. It is pure (no
@@ -31,6 +33,11 @@ type Config struct {
 	Secret      string // token secret (from <id>.pw)
 	Namespace   string // PBS namespace (from storage.cfg `namespace`); "" = root. S4 per-customer tenancy.
 	Timeout     time.Duration
+
+	// IdleConnTimeout bounds how long this client's idle keep-alive connections are retained.
+	// Zero means httpx.DefaultIdleConnTimeout (90s) — it does NOT mean "no timeout", which is the
+	// R-344 defect. Production leaves it unset; only tests set it, to avoid a 90-second wait.
+	IdleConnTimeout time.Duration
 }
 
 // NewClient builds a fingerprint-pinned, token-authed PBS client.
@@ -55,8 +62,13 @@ func NewClient(cfg Config) (*Client, error) {
 		authHeader: "PBSAPIToken=" + cfg.TokenID + ":" + cfg.Secret,
 		namespace:  cfg.Namespace,
 		http: &http.Client{
-			Timeout:   timeout,
-			Transport: &http.Transport{TLSClientConfig: tlsCfg},
+			Timeout: timeout,
+			// R-344: this transport MUST come from httpx. pbsTargetsFromPVE (cmd/felhom-agent/
+			// main.go) builds a fresh Client every cycle and drops the previous one, so a
+			// transport with no idle timeout strands one connection per cycle, forever, on both
+			// sides. That leaked 388 sockets onto ep0 in 46 hours. Pinned by
+			// TestAbandonedClientsReleaseTheirConnections — do not inline an http.Transport here.
+			Transport: httpx.NewTransport(tlsCfg, cfg.IdleConnTimeout),
 		},
 	}, nil
 }

internal/pbs/client_leak_test.go

@@ -0,0 +1,173 @@
+package pbs
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/httpx"
+)
+
+// connCounter is the SERVER-side observer. It counts what the server actually holds, which is the
+// only thing that answers the question this file exists for: a client that believes it closed a
+// connection, and a server still holding the socket, is precisely the R-344 shape. Asserting on
+// anything client-side would be asserting the mechanism instead of the consequence.
+type connCounter struct {
+	mu    sync.Mutex
+	open  int
+	total int // every connection ever accepted — how many times the client DIALLED
+}
+
+func (c *connCounter) hook(_ net.Conn, s http.ConnState) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	switch s {
+	case http.StateNew:
+		c.open++
+		c.total++
+	case http.StateClosed, http.StateHijacked:
+		c.open--
+	}
+}
+
+func (c *connCounter) counts() (open, total int) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.open, c.total
+}
+
+// waitForOpen polls until the server holds want connections, or fails naming what it still holds.
+func (c *connCounter) waitForOpen(t *testing.T, want int, within time.Duration, what string) {
+	t.Helper()
+	deadline := time.Now().Add(within)
+	for {
+		open, total := c.counts()
+		if open == want {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("%s: after %s the server still holds %d open connection(s), want %d (%d dialled in total)",
+				what, within, open, want, total)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// newCountingPBSServer is newPBSTestServer plus a ConnState hook. Kept separate rather than
+// changing the shared helper, so the existing tests are untouched by this file.
+func newCountingPBSServer(t *testing.T, fn http.HandlerFunc) (*httptest.Server, string, *connCounter) {
+	t.Helper()
+	cc := &connCounter{}
+	ts := httptest.NewUnstartedServer(fn)
+	ts.Config.ConnState = cc.hook
+	ts.StartTLS()
+	t.Cleanup(ts.Close)
+	return ts, fingerprintOf(ts), cc
+}
+
+// TestAbandonedClientsReleaseTheirConnections is Scenario A, and it is the load-bearing test for
+// R-344.
+//
+// It models what pbsTargetsFromPVE actually does — build a client, use it once, drop it on the
+// floor without closing anything — and asserts the CONSEQUENCE on the server: the connections go
+// away. Before the fix every one of these stayed established forever on both sides; 388 of them
+// accumulated on ep0 in 46 hours.
+//
+// Deliberately NOT asserted: that err == nil, or that IdleConnTimeout holds some value. Both were
+// true of the leaking code.
+func TestAbandonedClientsReleaseTheirConnections(t *testing.T) {
+	ts, fp, cc := newCountingPBSServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		w.Write([]byte(`{"data":[]}`))
+	})
+	host, port := hostPort(t, ts.URL)
+
+	const cycles = 5
+	for i := 0; i < cycles; i++ {
+		// One fresh client per "cycle", exactly as pbsTargetsFromPVE builds one per collect.
+		c, err := NewClient(Config{
+			Server: host, Port: port, Fingerprint: fp, TokenID: "u@pbs!t", Secret: "s",
+			IdleConnTimeout: 50 * time.Millisecond, // production uses the 90s default
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := c.Snapshots(context.Background(), "ds"); err != nil {
+			t.Fatalf("cycle %d: %v", i, err)
+		}
+		_ = c // dropped here — nothing closes it, nothing can
+	}
+
+	if _, total := cc.counts(); total != cycles {
+		t.Fatalf("setup is not modelling the leak: want %d separate dials (one per abandoned client), got %d", cycles, total)
+	}
+	cc.waitForOpen(t, 0, 5*time.Second, "abandoned pbs.Clients")
+}
+
+// TestAbandonedClientsReleaseTheirConnections_ProductionDefaultIsUsable pins the value that ships.
+//
+// The field being settable is exactly how it could silently become zero again — and zero used to
+// mean "never expire". This asserts the production path (Config leaving it unset) lands on the
+// standard-library default, so the leak cannot return through an unset field.
+func TestPBSClient_UnsetIdleTimeoutUsesTheDefault(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		cfg  time.Duration
+		want time.Duration
+	}{
+		{"unset — the production path", 0, httpx.DefaultIdleConnTimeout},
+		{"explicit zero is NOT no-timeout", 0, httpx.DefaultIdleConnTimeout},
+		{"negative is NOT no-timeout", -time.Second, httpx.DefaultIdleConnTimeout},
+		{"an explicit value is honoured", 3 * time.Second, 3 * time.Second},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			c, err := NewClient(Config{
+				Server: "pbs.example", Fingerprint: strings.Repeat("ab", 32),
+				TokenID: "u@pbs!t", Secret: "s", IdleConnTimeout: tc.cfg,
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			tr, ok := c.http.Transport.(*http.Transport)
+			if !ok {
+				t.Fatalf("transport is %T, not *http.Transport — the httpx wiring was replaced", c.http.Transport)
+			}
+			if tr.IdleConnTimeout != tc.want {
+				t.Fatalf("IdleConnTimeout = %v, want %v (zero would mean connections are retained FOREVER — that is R-344)", tr.IdleConnTimeout, tc.want)
+			}
+		})
+	}
+}
+
+// TestPBSClient_KeepAliveStillReuses is Scenario C, and it is the guard against a "fix" that is
+// worse than the bug.
+//
+// Disabling keep-alive entirely would also make the leak go away — by dialling a fresh connection
+// for every single request, which on a box polling ~40,000 times a day is strictly worse than what
+// we started with. The fix must retire IDLE connections without stopping reuse.
+func TestPBSClient_KeepAliveStillReuses(t *testing.T) {
+	ts, fp, cc := newCountingPBSServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		w.Write([]byte(`{"data":[]}`))
+	})
+	host, port := hostPort(t, ts.URL)
+
+	c, err := NewClient(Config{
+		Server: host, Port: port, Fingerprint: fp, TokenID: "u@pbs!t", Secret: "s",
+		IdleConnTimeout: 30 * time.Second, // long enough that reuse is what is being measured
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 3; i++ {
+		if _, err := c.Snapshots(context.Background(), "ds"); err != nil {
+			t.Fatalf("request %d: %v", i, err)
+		}
+	}
+	if _, total := cc.counts(); total != 1 {
+		t.Fatalf("one client made 3 sequential requests over %d connection(s), want 1 — keep-alive reuse is broken, which would make the poll load WORSE than the leak", total)
+	}
+}

internal/pbsdr/manager.go

@@ -283,7 +283,36 @@ func (m *Manager) Apply(ctx context.Context, fetched bool, block *hub.WirePBSDR)
 	h := descriptorHash(block)
 	cf := m.loadConsumedFailed()
 	if mk := m.loadMarker(); mk != nil && mk.Hash == h && (cf == nil || cf.Hash != h) {
-		m.setStatus(&hub.PBSDRStatus{State: mk.State, StorageID: block.StorageID, Namespace: block.Namespace, AppliedAt: mk.AppliedAt})
+		// R-221: RE-ASSERT THE SEED, DO NOT REMEMBER IT. The marker records that this descriptor
+		// converged; it says nothing about whether the file the seed writes still exists.
+		//
+		// The two live in different places and die at different times. The marker is host-side
+		// (`<agent-state>/pbsdr/`, markerPath above); the seed's target is `agent.json`, and the
+		// installer's `step_agent_config` renders that file from `base = {}` unless an explicit
+		// `--preserve-from` is passed — it NEVER writes an `escrow` section — then replaces it with
+		// O_TRUNC (felhom-host-install.sh:2396, :2449, :2579; the flag is :1246, defaulting empty at
+		// :256). So a rebuild leaves the marker and takes the seed, the hash still matches, this
+		// branch returns, and `escrow.pbs_storage_id` is never written again. The customer then
+		// cannot run the escrow ceremony AT ALL: handleEscrowPreflight fails the `pbs_storage_id`
+		// row and the wizard refuses, with no way forward from inside the product.
+		//
+		// A rebuild is only the case that was measured. The same hole opens for a hand-edited or
+		// restored config, which is the honest reason this is a seam fix rather than an installer
+		// fix — the seed must be a thing the loop asserts, not a thing it did once.
+		//
+		// COST: this runs on the converged path, i.e. every tick (60 s) forever. It is one small
+		// file read plus a JSON parse — no exec, no network, no Proxmox call — and seedEscrowStorageID
+		// returns early once the value matches. That is the whole reason it is affordable here.
+		//
+		// IT MUST NEVER UN-CONVERGE THE BOX: a failure is a Warn plus a message on the published
+		// status, exactly as finishConverged does it. No marker write, no state change, no retry
+		// storm — the early return below still happens either way.
+		msg := ""
+		if err := m.seedEscrowStorageID(block.StorageID); err != nil {
+			msg = "escrow.pbs_storage_id seed failed: " + err.Error() + " (set it manually before the ceremony)"
+			m.logger.Warn("pbsdr: " + msg)
+		}
+		m.setStatus(&hub.PBSDRStatus{State: mk.State, StorageID: block.StorageID, Namespace: block.Namespace, AppliedAt: mk.AppliedAt, Message: msg})
 		return // idempotent: this exact descriptor already converged
 	}
 

internal/pbsdr/seed_reassert_test.go

@@ -0,0 +1,232 @@
+package pbsdr
+
+import (
+	"context"
+	"encoding/json"
+	"go/ast"
+	"go/parser"
+	"go/printer"
+	"go/token"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// R-221 — the escrow seed must be ASSERTED on every converged tick, not remembered.
+//
+// These tests drive the real Apply() with a real temp-dir agent.json and a call-recording runner.
+// Calling seedEscrowStorageID directly would prove nothing: the defect IS the early return in
+// Apply, and a test that steps around it cannot see it.
+
+// convergedMarker writes a marker whose hash matches the block, i.e. puts the manager on exactly
+// the idempotent path where the seed used to be skipped.
+func convergedMarker(t *testing.T, m *Manager, block *hub.WirePBSDR, state string) {
+	t.Helper()
+	if err := m.writeState(m.markerPath(), marker{
+		Hash: descriptorHash(block), State: state, AppliedAt: "2026-08-08T00:00:00Z",
+	}); err != nil {
+		t.Fatalf("write marker: %v", err)
+	}
+}
+
+func escrowStorageID(t *testing.T, cfgPath string) string {
+	t.Helper()
+	raw, err := os.ReadFile(cfgPath)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	var doc struct {
+		Escrow struct {
+			PBSStorageID string `json:"pbs_storage_id"`
+		} `json:"escrow"`
+	}
+	if err := json.Unmarshal(raw, &doc); err != nil {
+		t.Fatalf("parse config: %v", err)
+	}
+	return doc.Escrow.PBSStorageID
+}
+
+// drBlock mirrors the existing valid fixture (manager_test.go descriptor()) so that validate()
+// passes and Apply actually reaches the marker check — the branch these tests are about.
+func drBlock(storageID string) *hub.WirePBSDR {
+	return &hub.WirePBSDR{
+		Enabled: true, StorageID: storageID, PBSTunnelIP: "10.77.0.1",
+		Datastore: "felhom-offsite", Namespace: "peti", TokenID: "felhom@pbs!peti",
+		Fingerprint: testFP,
+	}
+}
+
+// SCENARIO A — the seed is re-asserted on a converged box, and nothing else happens.
+//
+// THIS IS THE TEST THAT MATTERS. It must fail against the pre-R-221 tree; if it passes there, it is
+// not testing the defect and that is the finding.
+func TestSeedReasserted_OnConvergedTick_WithZeroProxmoxCalls(t *testing.T) {
+	r := &fakeRunner{}
+	st := &fakeStorage{found: true, active: []bool{true}}
+	c := &fakeConsumer{}
+	m, cfgPath := newTestManager(t, r, st, c)
+
+	block := drBlock("felhom-pbs-dr")
+	convergedMarker(t, m, block, "applied")
+
+	// the shape a rebuild leaves behind: escrow section present, pbs_storage_id GONE
+	if got := escrowStorageID(t, cfgPath); got != "" {
+		t.Fatalf("precondition: config already carries a storage id %q", got)
+	}
+
+	m.Apply(context.Background(), true, block)
+
+	if got := escrowStorageID(t, cfgPath); got != "felhom-pbs-dr" {
+		t.Errorf("the converged tick did not re-assert the seed: escrow.pbs_storage_id = %q, want %q.\n"+
+			"This is R-221: the marker survives a rebuild, the descriptor hash still matches, the early "+
+			"return fires and the seed never runs into the config that no longer has it — so the customer "+
+			"cannot run the escrow ceremony at all.", got, "felhom-pbs-dr")
+	}
+
+	// ...and the idempotent path is STILL idempotent. This assertion is not decorative: without it
+	// a "fix" that simply deletes the early return would pass the line above.
+	if calls := r.recorded(); len(calls) != 0 {
+		t.Errorf("a converged tick must execute ZERO Proxmox commands; got %d: %+v", len(calls), calls)
+	}
+}
+
+// SCENARIO B — an operator's own different value survives, and the warning names both.
+func TestSeedReasserted_NeverClobbersAnOperatorValue(t *testing.T) {
+	r := &fakeRunner{}
+	m, cfgPath := newTestManager(t, r, &fakeStorage{found: true, active: []bool{true}}, &fakeConsumer{})
+
+	if err := os.WriteFile(cfgPath, []byte(
+		`{"log_level":"info","escrow":{"posture":"zero_knowledge","pbs_storage_id":"operator-chosen"},`+
+			`"custom_unknown":{"keep":1}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	block := drBlock("hub-chosen")
+	convergedMarker(t, m, block, "applied")
+
+	m.Apply(context.Background(), true, block)
+
+	if got := escrowStorageID(t, cfgPath); got != "operator-chosen" {
+		t.Errorf("a value a person put there was overwritten by the descriptor: got %q, want %q", got, "operator-chosen")
+	}
+	// unknown keys must still round-trip
+	raw, _ := os.ReadFile(cfgPath)
+	if !strings.Contains(string(raw), "custom_unknown") {
+		t.Error("an unknown config key was dropped by the re-assert")
+	}
+}
+
+// SCENARIO C — the ceremony preflight's live read sees the re-asserted value with NO restart.
+//
+// The preflight itself lives in internal/localapi and reads the file through config.Load; what this
+// asserts is the half that belongs to this package: after a converged tick, THE FILE ON DISK carries
+// the id, so any live re-read is green. The daemon is never restarted in this test because it is
+// never started — which is the point.
+func TestSeedReasserted_IsVisibleOnDiskImmediately(t *testing.T) {
+	r := &fakeRunner{}
+	m, cfgPath := newTestManager(t, r, &fakeStorage{found: true, active: []bool{true}}, &fakeConsumer{})
+	block := drBlock("felhom-pbs-dr")
+	convergedMarker(t, m, block, "applied")
+
+	// preflight's predicate BEFORE: storageID == "" → the row is NOT OK
+	if escrowStorageID(t, cfgPath) != "" {
+		t.Fatal("precondition")
+	}
+	m.Apply(context.Background(), true, block)
+	// preflight's predicate AFTER, from the same file the ceremony subprocess loads
+	if id := escrowStorageID(t, cfgPath); id == "" {
+		t.Error("the preflight row would still be NOT OK after a converged tick")
+	}
+}
+
+// A seed failure must NEVER un-converge the box: no marker rewrite, no state change, and the status
+// still reports the marker's converged state — with the failure surfaced as a message.
+func TestSeedReassertFailure_DoesNotUnconverge(t *testing.T) {
+	r := &fakeRunner{}
+	m, cfgPath := newTestManager(t, r, &fakeStorage{found: true, active: []bool{true}}, &fakeConsumer{})
+	block := drBlock("felhom-pbs-dr")
+	convergedMarker(t, m, block, "applied")
+	markerBefore, err := os.ReadFile(m.markerPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// make the seed fail in a way it cannot recover from: unparseable config
+	if err := os.WriteFile(cfgPath, []byte(`{ this is not json`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	m.Apply(context.Background(), true, block)
+
+	after, err := os.ReadFile(m.markerPath())
+	if err != nil {
+		t.Fatalf("the marker was removed by a seed failure: %v", err)
+	}
+	if string(after) != string(markerBefore) {
+		t.Error("a seed failure rewrote the convergence marker — it must not touch state")
+	}
+	if calls := r.recorded(); len(calls) != 0 {
+		t.Errorf("a seed failure must not trigger Proxmox work; got %+v", calls)
+	}
+	st := m.Status()
+	if st == nil || st.State != "applied" {
+		t.Errorf("a seed failure must leave the box converged; status = %+v", st)
+	}
+	if st != nil && !strings.Contains(st.Message, "seed failed") {
+		t.Errorf("a seed failure must be surfaced on the status, got message %q", st.Message)
+	}
+}
+
+// SEAM WIRING — production must construct the manager with the live config path, or the whole seed
+// leg is inert. Three shipped defects in this project were fully green while their seam was never
+// wired, so this walks main.go's AST for the actual call rather than grepping: a commented-out call
+// satisfies strings.Contains, and an AST walk cannot see a comment.
+func TestProductionWiring_NewManagerGetsTheLiveConfigPath(t *testing.T) {
+	path := filepath.Join("..", "..", "cmd", "felhom-agent", "main.go")
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, path, nil, 0) // comments not even collected
+	if err != nil {
+		t.Fatalf("parse main.go: %v", err)
+	}
+	found := false
+	ast.Inspect(f, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "NewManager" {
+			return true
+		}
+		if pkg, ok := sel.X.(*ast.Ident); !ok || pkg.Name != "pbsdr" {
+			return true
+		}
+		// signature: (runner, px, hubc, stateDir, secretDir, configPath, logger)
+		if len(call.Args) < 6 {
+			t.Errorf("pbsdr.NewManager called with %d args, expected >= 6", len(call.Args))
+			return false
+		}
+		var buf strings.Builder
+		if err := printNode(&buf, fset, call.Args[5]); err != nil {
+			t.Fatalf("print arg: %v", err)
+		}
+		got := buf.String()
+		if !strings.Contains(got, "SourcePath") {
+			t.Errorf("pbsdr.NewManager's configPath argument is %q, which is not the live config path.\n"+
+				"With an empty or wrong path seedEscrowStorageID returns nil immediately and the entire "+
+				"R-221 fix is inert while every test above still passes.", got)
+		}
+		found = true
+		return false
+	})
+	if !found {
+		t.Error("no pbsdr.NewManager call found in main.go — the manager is not constructed in production")
+	}
+}
+
+func printNode(w io.Writer, fset *token.FileSet, n ast.Node) error {
+	return printer.Fprint(w, fset, n)
+}

internal/proxmox/client.go

@@ -10,6 +10,8 @@ import (
 	"net/url"
 	"strings"
 	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/httpx"
 )
 
 // doer is the minimal HTTP surface the client needs; *http.Client satisfies it.
@@ -65,8 +67,10 @@ func NewClient(cfg Config) (*Client, error) {
 		timeout = 30 * time.Second
 	}
 	hc := &http.Client{
-		Timeout:   timeout,
-		Transport: &http.Transport{TLSClientConfig: tlsCfg},
+		Timeout: timeout,
+		// R-344, consistency only: built ONCE per process, so it never accumulated and contributed
+		// nothing to the ep0 leak. Same missing default, corrected for the same reason.
+		Transport: httpx.NewTransport(tlsCfg, 0),
 	}
 	return &Client{
 		base:  strings.TrimRight(cfg.Endpoint, "/") + "/api2/json",

internal/proxmox/query.go

@@ -45,6 +45,35 @@ func (c *Client) Pool(ctx context.Context, name string) (PoolInfo, error) {
 	return p, c.get(ctx, "/pools/"+url.PathEscape(name), &p)
 }
 
+// Permissions returns the privileges this API TOKEN holds at an ACL path, as
+// GET /access/permissions?path=<path> answers it: privilege name → 1.
+//
+// R-185. It asks about the CALLER — the agent's own token — which is the only useful form of the
+// question. Asking as root answers a different question and always says yes.
+//
+// MEASURED SHAPE (demo-felhom, 2026-08-03), because the whole value of this call is reading the
+// answer correctly and the obvious reading is wrong:
+//
+//	/storage/felhom-pbs     → {"Datastore.Allocate":1,"Datastore.AllocateSpace":1}
+//	/storage/felhom-backup  → {"Sys.Audit":1,"SDN.Use":1,"Datastore.Audit":1}
+//
+// The ungranted path does NOT answer empty, and does NOT 403. It answers with the privileges
+// INHERITED from the box-wide `/` grant — so "is this path present in the response" reports OK for a
+// storage the agent demonstrably cannot list. The caller must test for the SPECIFIC privilege.
+//
+// The response is keyed by path; an absent path yields no privileges, which is the same answer as
+// "none" and is treated as such by the caller.
+func (c *Client) Permissions(ctx context.Context, aclPath string) (map[string]int, error) {
+	var raw map[string]map[string]int
+	if err := c.get(ctx, "/access/permissions?path="+url.QueryEscape(aclPath), &raw); err != nil {
+		return nil, err
+	}
+	if p, ok := raw[aclPath]; ok {
+		return p, nil
+	}
+	return map[string]int{}, nil
+}
+
 // GuestStatus returns GET /nodes/{node}/lxc/{vmid}/status/current. The API body
 // has no vmid field (it is in the path), so it is set from the argument.
 func (c *Client) GuestStatus(ctx context.Context, vmid int) (Guest, error) {

internal/proxmox/types.go

@@ -219,15 +219,18 @@ type Storage struct {
 	UsedFraction float64 `json:"used_fraction,omitempty"`
 
 	// Type-specific config (durable_id sources).
-	Server      string `json:"server,omitempty"`      // nfs/cifs/pbs server host
-	Export      string `json:"export,omitempty"`      // nfs export path
-	Share       string `json:"share,omitempty"`       // cifs share name
-	Datastore   string `json:"datastore,omitempty"`   // pbs datastore name
-	Fingerprint string `json:"fingerprint,omitempty"` // pbs server cert fingerprint
-	Username    string `json:"username,omitempty"`    // pbs auth id, e.g. "felhom@pbs!n100"
-	Namespace   string `json:"namespace,omitempty"`   // pbs namespace ("" = root; per-customer tenancy = S4)
-	VGName      string `json:"vgname,omitempty"`      // lvm/lvmthin volume group
-	ThinPool    string `json:"thinpool,omitempty"`    // lvmthin pool LV name
+	Server string `json:"server,omitempty"` // nfs/cifs/pbs server host
+	// EncryptionKey is the storage's own client-side key FINGERPRINT (pbs; the key itself stays in
+	// /etc/pve/priv). R-727: an archive encrypted with any other key was written by another box.
+	EncryptionKey string `json:"encryption-key,omitempty"`
+	Export        string `json:"export,omitempty"`      // nfs export path
+	Share         string `json:"share,omitempty"`       // cifs share name
+	Datastore     string `json:"datastore,omitempty"`   // pbs datastore name
+	Fingerprint   string `json:"fingerprint,omitempty"` // pbs server cert fingerprint
+	Username      string `json:"username,omitempty"`    // pbs auth id, e.g. "felhom@pbs!n100"
+	Namespace     string `json:"namespace,omitempty"`   // pbs namespace ("" = root; per-customer tenancy = S4)
+	VGName        string `json:"vgname,omitempty"`      // lvm/lvmthin volume group
+	ThinPool      string `json:"thinpool,omitempty"`    // lvmthin pool LV name
 }
 
 // StorageContent is one entry of GET /nodes/{node}/storage/{store}/content
@@ -239,4 +242,7 @@ type StorageContent struct {
 	Size    int64  `json:"size"`
 	CTime   int64  `json:"ctime"`
 	VMID    int    `json:"vmid,omitempty"`
+	// Encrypted is the fingerprint of the key a PBS archive was encrypted with ("" = not encrypted). R-727:
+	// the restore test reads it to tell THIS box's archives from an earlier box's in the same namespace.
+	Encrypted string `json:"encrypted,omitempty"`
 }

internal/reconcile/bringup.go

@@ -302,6 +302,19 @@ func (e *Engine) runBringUp(ctx context.Context, spec BringUpSpec, res *BringUpR
 		}
 	}
 
+	// R-834: DR keeps the archive's `onboot: 1`, binds the host's REAL drives (4d) and STARTS the guest
+	// — right on a replaced host, where the original is gone. Beside a LIVE original it would be a
+	// second controller for the same household on the same drives. So DR refuses when this host
+	// still carries the original (the archive's source VMID) or any guest that binds the drives.
+	// A copy beside the original is the restore-test's job (onboot=0, throwaway stand-ins, torn
+	// down) or the runbook's beside-restore. Pinned by TestRunBringUp_DRRefusesBesideALiveOriginal.
+	if spec.Mode == ModeDRGuestLoss {
+		if why := e.liveOriginalBeside(ctx, lxc, spec.Archive); why != "" {
+			res.Err = fmt.Errorf("reconcile: dr bring-up refused: %s — a DR restore beside a live original would run two boxes on the same drives (R-834)", why)
+			return
+		}
+	}
+
 	base := JournalEntry{OpID: e.bringUpOpID(spec.VMID), VMID: spec.VMID, Kind: bringUpKind, Rollback: true}
 
 	// OWN the rollback BEFORE any mutation. From here a crash leaves an in-flight Rollback
@@ -734,3 +747,47 @@ func net0MAC(cfg proxmox.GuestConfig) string {
 	}
 	return ""
 }
+
+// archiveSourceVMID reads the source guest's VMID from a backup volid: a vzdump file
+// (`…/vzdump-lxc-<vmid>-<date>.tar.zst`) or a PBS snapshot (`…:backup/ct/<vmid>/<time>`). 0 = unknown.
+func archiveSourceVMID(archive string) int {
+	if i := strings.Index(archive, "vzdump-lxc-"); i >= 0 {
+		rest := archive[i+len("vzdump-lxc-"):]
+		if j := strings.Index(rest, "-"); j > 0 {
+			if n, err := strconv.Atoi(rest[:j]); err == nil {
+				return n
+			}
+		}
+	}
+	if i := strings.Index(archive, "ct/"); i >= 0 {
+		rest := archive[i+len("ct/"):]
+		if j := strings.Index(rest, "/"); j > 0 {
+			if n, err := strconv.Atoi(rest[:j]); err == nil {
+				return n
+			}
+		}
+	}
+	return 0
+}
+
+// liveOriginalBeside says why a DR bring-up would land beside a live original ("" = it would not):
+// the archive's source guest still exists here, or a guest binds the drives parent. Fails CLOSED: a
+// guest whose config cannot be read cannot be ruled out.
+func (e *Engine) liveOriginalBeside(ctx context.Context, lxc []proxmox.Guest, archive string) string {
+	src := archiveSourceVMID(archive)
+	for _, g := range lxc {
+		if src > 0 && g.VMID == src {
+			return fmt.Sprintf("the archive's source guest %d still exists on this host (status %s)", g.VMID, g.Status)
+		}
+		cfg, err := e.api.GuestConfig(ctx, g.VMID)
+		if err != nil {
+			return fmt.Sprintf("guest %d's config could not be read to rule out a live original: %v", g.VMID, err)
+		}
+		for slot, v := range cfg.MountPoints() {
+			if source, _, _ := strings.Cut(v, ","); source == structuralParentDir {
+				return fmt.Sprintf("guest %d binds the household drives (%s %s)", g.VMID, slot, structuralParentDir)
+			}
+		}
+	}
+	return ""
+}

internal/reconcile/bringup_beside_test.go

@@ -0,0 +1,138 @@
+package reconcile
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-834: a whole-guest restore BESIDE a live original must never come up as a second box on the same
+// drives. The DR route keeps `onboot: 1`, binds the real drives and starts the guest, so it refuses
+// when the original (or any guest binding the drives) is still on this host; on a replaced host it
+// proceeds and keeps its binds. Red-proof: make liveOriginalBeside return "" and the refusals pass
+// the restore through (the "refused" sub-tests fail).
+func TestRunBringUp_DRRefusesBesideALiveOriginal(t *testing.T) {
+	const target = 9299
+	drivesBind := proxmox.GuestConfig{Extra: map[string]json.RawMessage{
+		"mp8": json.RawMessage(`"/mnt/felhom-drives,mp=/mnt/felhom-drives"`),
+	}}
+	cases := []struct {
+		name    string
+		archive string
+		lxc     []proxmox.Guest
+		cfg     map[int]proxmox.GuestConfig
+		refuse  string // substring of the refusal; "" = must proceed
+	}{
+		{"the source guest still exists", "local:backup/vzdump-lxc-9201-2026_10_04-04_34_55.tar.zst",
+			[]proxmox.Guest{{VMID: 9201, Status: "running"}}, map[int]proxmox.GuestConfig{9201: scratchCfg()}, "source guest 9201"},
+		{"another guest binds the drives (PBS archive)", "felhom-pbs:backup/ct/9201/2026-10-04T02:34:55Z",
+			[]proxmox.Guest{{VMID: 9300, Status: "stopped"}}, map[int]proxmox.GuestConfig{9300: drivesBind}, "binds the household drives"},
+		{"a guest whose config cannot be read", "local:backup/vzdump-lxc-9201-x.tar.zst",
+			[]proxmox.Guest{{VMID: 9400, Status: "running"}}, map[int]proxmox.GuestConfig{}, "could not be read"},
+		{"replaced host: only an unrelated scratch guest", "local:backup/vzdump-lxc-9201-x.tar.zst",
+			[]proxmox.Guest{{VMID: 9202, Status: "running"}}, map[int]proxmox.GuestConfig{9202: scratchCfg()}, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			cfg := c.cfg
+			cfg[target] = scratchCfg()
+			api := &fakeAPI{lxc: c.lxc, cfg: cfg}
+			e, fr, _, q := newDREngine(t, api)
+			defer q.Close()
+			res := e.RunBringUp(context.Background(), BringUpSpec{
+				Mode: ModeDRGuestLoss, Archive: c.archive, VMID: target, RestoreStorage: "local-lvm", KeepMAC: true,
+			})
+			if c.refuse != "" {
+				if res.Err == nil || !strings.Contains(res.Err.Error(), c.refuse) || !strings.Contains(res.Err.Error(), "R-834") {
+					t.Fatalf("want a refusal naming %q, got %+v", c.refuse, res)
+				}
+				if len(api.restores) != 0 || len(api.starts) != 0 || len(fr.cmds) != 0 {
+					t.Fatalf("a refused DR touched the host: restores=%d starts=%v cmds=%v", len(api.restores), api.starts, fr.cmds)
+				}
+				return
+			}
+			if res.Err != nil || !res.Pass {
+				t.Fatalf("a DR on a replaced host must proceed, got %+v", res)
+			}
+			// … and there it keeps the REAL drives bind (the right binds on a replaced host).
+			joined := strings.Join(fr.cmds, "\n")
+			if !strings.Contains(joined, "-mp8 /mnt/felhom-drives,mp=/mnt/felhom-drives") {
+				t.Fatalf("the DR guest lost its drives bind: %v", fr.cmds)
+			}
+		})
+	}
+}
+
+// Provisioning restores the GOLDEN (no drives, onboot set by the back-half on purpose): a drives-
+// binding guest on the host does not block it — the rule is DR's alone.
+func TestRunBringUp_ProvisionNotBlockedByADrivesBind(t *testing.T) {
+	api := &fakeAPI{
+		lxc: []proxmox.Guest{{VMID: 9201, Status: "running"}},
+		cfg: map[int]proxmox.GuestConfig{
+			9201: {Extra: map[string]json.RawMessage{"mp8": json.RawMessage(`"/mnt/felhom-drives,mp=/mnt/felhom-drives"`)}},
+			9203: scratchCfg(),
+		},
+	}
+	e, _, q := newEngine(t, api, EmptyProvider{})
+	defer q.Close()
+	res := e.RunBringUp(context.Background(), BringUpSpec{Mode: ModeProvision, Archive: "local:vztmpl/felhom-golden.tar.zst", VMID: 9203, RestoreStorage: "local-lvm"})
+	if res.Err != nil || !res.Pass {
+		t.Fatalf("provision must proceed, got %+v", res)
+	}
+}
+
+func TestArchiveSourceVMID(t *testing.T) {
+	for in, want := range map[string]int{
+		"local:backup/vzdump-lxc-9201-2026_10_04-04_34_55.tar.zst": 9201,
+		"felhom-pbs:backup/ct/9201/2026-10-04T02:34:55Z":           9201,
+		"tmp-dooplex-copy:backup/ct/9201/2026-10-03T19:00:00Z":     9201,
+		"local:vztmpl/felhom-golden.tar.zst":                       0,
+		"vol":                                                      0,
+	} {
+		if got := archiveSourceVMID(in); got != want {
+			t.Errorf("archiveSourceVMID(%q) = %d, want %d", in, got, want)
+		}
+	}
+}
+
+// R-834, the restore-test route: its scratch guest sits BESIDE the live original by design, so it must
+// carry no host-path bind — the archive's mp8 (the household's drives) and mp9 (the original's
+// bootstrap) are replaced by throwaway volumes AT restore time. Measured live 2026-10-04 on demo-hp
+// (`audits/backup-close-2026-10-04/partA/`): onboot 0 and no host bind on every poll. Red-proof:
+// make drRestoreOverrides return the archive's own mp8 value and this fails.
+func TestRestoreTest_NoHostPathBindBesideTheOriginal(t *testing.T) {
+	api := &fakeAPI{
+		cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()},
+		extractCfg: "hostname: demo-hp\nonboot: 1\nrootfs: local-lvm:vm-9201-disk-0,size=16G\n" +
+			"mp0: local-lvm:vm-9201-disk-1,mp=/var/lib/felhom,backup=1,size=70G\n" +
+			"mp8: /mnt/felhom-drives,mp=/mnt/felhom-drives\n" +
+			"mp9: /var/lib/felhom-agent/guests/9201/bootstrap,mp=/etc/felhom-bootstrap,ro=1\n",
+	}
+	e, _, q := newEngine(t, api, EmptyProvider{})
+	defer q.Close()
+	_ = e.RunRestoreTest(context.Background(), RestoreTestSpec{
+		Archive: "local:backup/vzdump-lxc-9201-x.tar.zst", RestoreStorage: "local-lvm",
+		ScratchMin: 990000, ScratchMax: 990009, SourceTier: "local",
+	})
+	if len(api.restores) != 1 {
+		t.Fatalf("want one restore, got %+v", api.restores)
+	}
+	r := api.restores[0]
+	for _, slot := range []string{"mp8", "mp9"} {
+		v, ok := r.MountOverrides[slot]
+		if !ok || strings.HasPrefix(v, "/") {
+			t.Fatalf("%s = %q (present=%v): the scratch beside the original must get a throwaway volume, never the host path", slot, v, ok)
+		}
+	}
+	for slot, v := range r.MountOverrides {
+		if strings.HasPrefix(v, "/") {
+			t.Fatalf("%s carries a host path %q into the scratch guest", slot, v)
+		}
+	}
+	if r.ConfigOverrides["onboot"] != "0" {
+		t.Fatalf("onboot = %q, want 0", r.ConfigOverrides["onboot"])
+	}
+}

internal/reconcile/bringup_test.go

@@ -52,7 +52,7 @@ func newDREngine(t *testing.T, api GuestAPI) (*Engine, *fakeRunner, string, *Que
 	t.Cleanup(q.Close)
 	fr := &fakeRunner{}
 	sd := t.TempDir()
-	e := NewEngine(EngineOptions{API: api, Queue: q, Journal: j, Provider: EmptyProvider{}, HostRunner: fr, StateDir: sd})
+	e := NewEngine(EngineOptions{API: api, Queue: q, Journal: j, Provider: EmptyProvider{}, HostRunner: fr, StateDir: sd, RestoreSpace: roomySpace{}})
 	return e, fr, sd, q
 }
 

internal/reconcile/engine.go

@@ -44,6 +44,17 @@ type Engine struct {
 
 	opSeq uint64 // atomic; makes each op id unique per attempt
 
+	// restoreSpace + spacePolicy are the restore-test's space preflight (R-672). nil space REFUSES
+	// every restore-test (fail-closed) — see restoretest_space.go.
+	restoreSpace RestoreSpace
+	spacePolicy  SpacePolicy
+
+	// scratchMu guards activeScratch (the vmids a running restore-test owns — the retry timer never
+	// touches those) and teardownTries (failed timer retries per journal op, R-672 rule 3).
+	scratchMu     sync.Mutex
+	activeScratch map[int]bool
+	teardownTries map[string]int
+
 	// lastRes records the most recent successful Reconcile Result (v0.90.0, R-28 fast-tick source).
 	// The fast-tick reads it to decide convergence: actionable drift is Planned − Pending > 0 (a
 	// destructive pending_signature refusal is EXPECTED state, not drift to hammer on). lastOK is
@@ -86,6 +97,10 @@ type EngineOptions struct {
 	HostRunner proxmox.Runner
 	// StateDir is the agent state dir ("" → /var/lib/felhom-agent); only the 4d swap reads it.
 	StateDir string
+	// RestoreSpace is the restore-test's space preflight (R-672). nil → every restore-test is REFUSED
+	// with its reason (fail-closed). SpacePolicy zero → DefaultSpacePolicy.
+	RestoreSpace RestoreSpace
+	SpacePolicy  SpacePolicy
 }
 
 // NewEngine builds an Engine. The Queue is shared (the single §10 choke point); the
@@ -124,9 +139,24 @@ func NewEngine(opts EngineOptions) *Engine {
 		logger:   logger,
 		hostRun:  opts.HostRunner,
 		stateDir: stateDir,
+
+		restoreSpace:  opts.RestoreSpace,
+		spacePolicy:   policyOrDefault(opts.SpacePolicy),
+		activeScratch: map[int]bool{},
+		teardownTries: map[string]int{},
 	}
 }
 
+func policyOrDefault(p SpacePolicy) SpacePolicy {
+	if p.Factor < 1 {
+		p.Factor = DefaultSpacePolicy.Factor
+	}
+	if p.ReserveBytes <= 0 {
+		p.ReserveBytes = DefaultSpacePolicy.ReserveBytes
+	}
+	return p
+}
+
 // Result summarizes one Reconcile pass.
 type Result struct {
 	Planned  int

internal/reconcile/engine_test.go

@@ -213,7 +213,7 @@ func newEngine(t *testing.T, api GuestAPI, provider DesiredProvider) (*Engine, *
 	t.Cleanup(func() { j.Close() })
 	q := NewQueue()
 	t.Cleanup(q.Close)
-	e := NewEngine(EngineOptions{API: api, Queue: q, Journal: j, Provider: provider})
+	e := NewEngine(EngineOptions{API: api, Queue: q, Journal: j, Provider: provider, RestoreSpace: roomySpace{}})
 	return e, j, q
 }
 

internal/reconcile/restoretest.go

@@ -50,10 +50,18 @@ type RestoreTestResult struct {
 	ScratchVMID int
 	Pass        bool
 	Verified    string // "boot+running" this slice
-	Skipped     bool   // no free scratch VMID in band → test not run
-	Err         error
-	StartedAt   time.Time
-	Duration    time.Duration
+	Skipped     bool   // test not run: no free scratch VMID in band, or the space preflight refused (R-672)
+	// SkipReason is set when the SPACE PREFLIGHT refused (R-672): the test did not run, and this is
+	// reported to the hub as the test's result (pass=false), never as a pass. Empty for a band skip.
+	SkipReason string
+	// TargetStorage is where the restore went (rule 2 may move it off the tested guest's pool);
+	// RequiredBytes/AvailBytes are rule 1's figures.
+	TargetStorage string
+	RequiredBytes int64
+	AvailBytes    int64
+	Err           error
+	StartedAt     time.Time
+	Duration      time.Duration
 	// StartWarnings holds the warning line(s) the guest-start task emitted (e.g. the
 	// systemd-nesting advisory). Populated only when the start exited "WARNINGS: N";
 	// always surfaced, NEVER used to decide pass/fail (the verdict is liveness — waitRunning).
@@ -136,6 +144,29 @@ func (e *Engine) RunRestoreTest(ctx context.Context, spec RestoreTestSpec) Resto
 		return res
 	}
 
+	// R-672: the space preflight, BEFORE anything is journaled or created.
+	rawCfg, err := e.api.ExtractArchiveConfig(ctx, spec.Archive)
+	if err != nil {
+		res.Err = fmt.Errorf("reconcile: restore-test extract archive config: %w", err)
+		return res
+	}
+	v := PreflightRestoreSpace(ctx, e.restoreSpace, e.spacePolicy, spec.Archive, rawCfg, spec.RestoreStorage)
+	res.TargetStorage, res.RequiredBytes, res.AvailBytes = v.Storage, v.Required, v.Avail
+	if !v.OK {
+		res.Skipped = true
+		res.SkipReason = "skipped: " + v.Reason
+		e.logger.Warn("restore-test SKIPPED by the space preflight (R-672) — nothing was created",
+			"archive", spec.Archive, "storage", v.Storage, "required_bytes", v.Required, "avail_bytes", v.Avail, "reason", v.Reason)
+		res.Duration = time.Since(now)
+		return res
+	}
+	if v.Storage != spec.RestoreStorage {
+		e.logger.Info("restore-test: restoring OFF the tested guest's own pool (R-672 rule 2)",
+			"configured", spec.RestoreStorage, "avoided", v.Avoided, "target", v.Storage)
+	}
+	e.logger.Info("restore-test: space preflight passed", "storage", v.Storage, "required_bytes", v.Required, "avail_bytes", v.Avail)
+	spec.RestoreStorage = v.Storage
+
 	lxc, err := e.api.ListLXC(ctx)
 	if err != nil {
 		res.Err = fmt.Errorf("reconcile: restore-test list guests: %w", err)
@@ -164,7 +195,9 @@ func (e *Engine) RunRestoreTest(ctx context.Context, spec RestoreTestSpec) Resto
 		// Serialize on the scratch VMID's lane (inherits §10), and capture the result.
 		var vmidOccupied bool
 		ch := e.queue.Submit(vmid, func() error {
-			vmidOccupied = e.runScratchTest(ctx, vmid, spec, &res)
+			e.markScratch(vmid, true)
+			defer e.markScratch(vmid, false)
+			vmidOccupied = e.runScratchTest(ctx, vmid, spec, rawCfg, &res)
 			return res.Err
 		})
 		<-ch
@@ -182,7 +215,7 @@ func (e *Engine) RunRestoreTest(ctx context.Context, spec RestoreTestSpec) Resto
 // runScratchTest is the journaled body (runs on vmid's queue lane). The occupied return is true
 // ONLY when PVE synchronously refused the restore because the vmid already holds a guest (one
 // the pool-blind band scan couldn't see) — the caller then advances to the next band vmid (F2).
-func (e *Engine) runScratchTest(ctx context.Context, vmid int, spec RestoreTestSpec, res *RestoreTestResult) (occupied bool) {
+func (e *Engine) runScratchTest(ctx context.Context, vmid int, spec RestoreTestSpec, rawCfg string, res *RestoreTestResult) (occupied bool) {
 	base := JournalEntry{OpID: e.scratchOpID(vmid), VMID: vmid, Kind: scratchKind, Scratch: true}
 
 	// OWN the scratch guest's cleanup BEFORE any mutation. From here, a crash is recoverable.
@@ -215,11 +248,7 @@ func (e *Engine) runScratchTest(ctx context.Context, vmid int, spec RestoreTestS
 	//    genuinely EXTRACTED — full fidelity; the added runtime IS the verification), the two
 	//    structural binds → throwaway stand-ins. An unreadable archive config or an unknown
 	//    topology REFUSES up front — never restore a partial guest to "verify" it.
-	rawCfg, err := e.api.ExtractArchiveConfig(ctx, spec.Archive)
-	if err != nil {
-		res.Err = fmt.Errorf("reconcile: restore-test extract archive config: %w", err)
-		return false
-	}
+	// The archive's config was read ONCE, by the space preflight (R-672), and is passed in.
 	mountOverrides, err := drRestoreOverrides(rawCfg, spec.RestoreStorage)
 	if err != nil {
 		res.Err = fmt.Errorf("reconcile: restore-test: %w", err)

internal/reconcile/restoretest_retry.go

@@ -0,0 +1,94 @@
+package reconcile
+
+import "context"
+
+// ── A failed scratch teardown is retried on a TIMER, not only at agent start (R-672 rule 3) ────────
+//
+// MEASURED 2026-09-24 on demo-hp: the scheduled restore-test's teardown failed (`lvremove … contains a
+// filesystem in use`, a transient hold) and logged "left for Recover" — and Recover runs ONLY at agent
+// start, so the 22 GiB scratch guest sat in the full pool for 2.5 hours until an agent restart. The
+// timer calls RetryScratchTeardown every 10 minutes: the SAME resolution as Recover (recoverScratch —
+// the gate's benign scratch destroy, idempotent when the guest is already gone), restricted to Scratch
+// entries that carry a launch-proof UPID and that no running restore-test owns. After
+// MaxTeardownTries failed attempts for one entry the operator is told (the caller reports it); the
+// timer keeps trying.
+
+// MaxTeardownTries is how many failed timer retries of one scratch entry happen before the operator
+// is told.
+const MaxTeardownTries = 3
+
+// ScratchRetryResult summarizes one timer pass.
+type ScratchRetryResult struct {
+	Examined  int
+	Destroyed int
+	Clean     int // already gone
+	Failed    int
+	// GaveUp lists the scratch vmids whose failed tries reached MaxTeardownTries IN THIS PASS — each
+	// is reported exactly once (the caller tells the operator).
+	GaveUp []int
+}
+
+func (e *Engine) markScratch(vmid int, active bool) {
+	e.scratchMu.Lock()
+	defer e.scratchMu.Unlock()
+	if active {
+		e.activeScratch[vmid] = true
+	} else {
+		delete(e.activeScratch, vmid)
+	}
+}
+
+func (e *Engine) scratchActive(vmid int) bool {
+	e.scratchMu.Lock()
+	defer e.scratchMu.Unlock()
+	return e.activeScratch[vmid]
+}
+
+// RetryScratchTeardown is the timer's pass. It never touches a non-Scratch entry (unlike Recover,
+// which also resolves generic in-flight operations and must therefore run only at start), never an
+// entry without a launch-proof UPID (nothing was created), and never a vmid a running test owns.
+func (e *Engine) RetryScratchTeardown(ctx context.Context) ScratchRetryResult {
+	var out ScratchRetryResult
+	if e.journal == nil {
+		return out
+	}
+	for _, entry := range e.journal.InFlight() {
+		if !entry.Scratch || entry.UPID == "" || e.scratchActive(entry.VMID) {
+			continue
+		}
+		out.Examined++
+		var r RecoverResult
+		e.recoverScratch(ctx, entry, &r)
+		switch {
+		case r.ScratchDestroyed > 0:
+			out.Destroyed++
+			e.forgetTries(entry.OpID)
+		case r.ScratchClean > 0:
+			out.Clean++
+			e.forgetTries(entry.OpID)
+		default:
+			out.Failed++
+			n := e.addTry(entry.OpID)
+			e.logger.Warn("restore-test: scratch teardown retry failed (timer)", "vmid", entry.VMID, "op_id", entry.OpID, "try", n)
+			if n == MaxTeardownTries {
+				out.GaveUp = append(out.GaveUp, entry.VMID)
+				e.logger.Error("restore-test: scratch guest still NOT torn down after repeated retries — telling the operator",
+					"vmid", entry.VMID, "tries", n)
+			}
+		}
+	}
+	return out
+}
+
+func (e *Engine) addTry(op string) int {
+	e.scratchMu.Lock()
+	defer e.scratchMu.Unlock()
+	e.teardownTries[op]++
+	return e.teardownTries[op]
+}
+
+func (e *Engine) forgetTries(op string) {
+	e.scratchMu.Lock()
+	defer e.scratchMu.Unlock()
+	delete(e.teardownTries, op)
+}

internal/reconcile/restoretest_retry_test.go

@@ -0,0 +1,73 @@
+package reconcile
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-672 rule 3 (v0.133.0): a failed scratch teardown is retried on a TIMER. The consequence asserted:
+// the leaked scratch guest is destroyed by a timer pass (not only by a restart's Recover), the operator
+// is told exactly once after MaxTeardownTries failures, and a vmid a running test owns is never touched.
+
+// leakScratch runs a restore-test whose teardown fails, leaving scratch 990000 in-flight — the
+// 2026-09-24 shape ("lvremove … contains a filesystem in use").
+func leakScratch(t *testing.T) (*Engine, *fakeAPI, *Journal) {
+	t.Helper()
+	api := &fakeAPI{cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}, restoreUPID: "UPID:r", destroyErr: errors.New("lvremove: contains a filesystem in use")}
+	e, j := spaceEngine(t, api, roomySpace{})
+	e.RunRestoreTest(context.Background(), RestoreTestSpec{Archive: "local:backup/x.tar.zst", RestoreStorage: "local-lvm", ScratchMin: 990000, ScratchMax: 990009})
+	if len(j.InFlight()) != 1 {
+		t.Fatalf("setup: want the scratch left in-flight after a failed teardown, got %+v", j.InFlight())
+	}
+	api.lxc = []proxmox.Guest{{VMID: 990000}}
+	return e, api, j
+}
+
+// COMPANION RED-PROOF (REPORT): make RetryScratchTeardown return without touching the journal (the
+// v0.132.0 shape — only Recover at start resolved a leak) → "the leaked scratch was not destroyed by
+// the timer".
+func TestRetry_TheTimerDestroysALeakedScratch(t *testing.T) {
+	e, api, j := leakScratch(t)
+	api.destroyErr = nil // the transient hold is gone
+	before := len(api.destroys)
+	r := e.RetryScratchTeardown(context.Background())
+	if r.Destroyed != 1 || len(api.destroys) != before+1 || api.destroys[len(api.destroys)-1] != 990000 {
+		t.Fatalf("the leaked scratch was not destroyed by the timer: result=%+v destroys=%v", r, api.destroys)
+	}
+	if len(j.InFlight()) != 0 {
+		t.Fatalf("the entry is still in flight after a successful retry: %+v", j.InFlight())
+	}
+	if r2 := e.RetryScratchTeardown(context.Background()); r2.Examined != 0 {
+		t.Fatalf("a resolved entry was examined again: %+v", r2)
+	}
+}
+
+func TestRetry_OperatorToldOnceAfterThreeFailures(t *testing.T) {
+	e, _, _ := leakScratch(t)
+	var gave [][]int
+	for i := 0; i < MaxTeardownTries+2; i++ {
+		gave = append(gave, e.RetryScratchTeardown(context.Background()).GaveUp)
+	}
+	for i, g := range gave {
+		want := 0
+		if i == MaxTeardownTries-1 {
+			want = 1
+		}
+		if len(g) != want {
+			t.Fatalf("pass %d gave up on %v — want the operator told exactly once, on pass %d", i+1, g, MaxTeardownTries)
+		}
+	}
+}
+
+func TestRetry_NeverTouchesARunningTest(t *testing.T) {
+	e, api, _ := leakScratch(t)
+	api.destroyErr = nil
+	e.markScratch(990000, true) // a restore-test is (again) working on this vmid
+	before := len(api.destroys)
+	if r := e.RetryScratchTeardown(context.Background()); r.Examined != 0 || len(api.destroys) != before {
+		t.Fatalf("the timer touched a scratch a running test owns: %+v destroys=%v", r, api.destroys)
+	}
+}

internal/reconcile/restoretest_space.go

@@ -0,0 +1,176 @@
+package reconcile
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// ── The restore-test's space preflight (R-672, agent v0.133.0) ─────────────────────────────────────
+//
+// MEASURED 2026-09-24 on demo-hp: the scheduled restore-test restored 9201's archive into `local-lvm`
+// — the SAME thin pool that holds 9201 — with no free-space check. The pool reached 100 %
+// (`out_of_data_space`, `error_if_no_space`), and 9201's rootfs and data volume remounted READ-ONLY.
+// Evidence: felhom.eu `documentation/audits/night-2026-09-24/C-02…C-07`, `audits/r672-2026-09-24/`.
+//
+// THE THREE RULES, all decided here before ANY mutation (before the scratch entry is even journaled):
+//  1. SPACE FIRST. The target storage must have free data ≥ restored × factor + reserve (defaults 1.2 and
+//     5 GiB, `backup.restore_test_space_factor` / `backup.restore_test_space_reserve_gib`), and a thin
+//     pool's metadata must have room for the same share. `restored` is the UNCOMPRESSED size — the
+//     archive FILE is the wrong number: 9201's archive was 6.9 GB and its restore wrote 22.6 GB, so
+//     "file × 1.2 + 5 GiB" (14.3 GB) would have let the 2026-09-24 test run into a pool with 23 GB free.
+//  2. KEEP OFF THE TESTED GUEST'S POOL when another eligible storage (active, takes `rootdir`, and the
+//     agent holds Datastore.AllocateSpace on it) passes rule 1. With only one, rule 1 decides.
+//  3. UNKNOWN REFUSES. An unreadable size, an unreadable storage or an unknown thin-pool metadata fill is
+//     a skip with its reason, never a guess — the fail-safe direction of every guard in this project.
+// A refusal is reported to the hub as the test's RESULT ("skipped: …", pass=false), never as a pass.
+// Pinned by restoretest_space_test.go.
+
+// RestoreSpace is the preflight's seam onto the host. Production: internal/restorespace.
+type RestoreSpace interface {
+	// RestoredBytes is how many bytes restoring `archive` will write (uncompressed), and where that
+	// figure came from (for the log and the refusal).
+	RestoredBytes(ctx context.Context, archive string) (bytes int64, source string, err error)
+	// Free reports the storage's free data bytes and, for a thin pool, its metadata-used fraction.
+	Free(ctx context.Context, storage string) (StorageFree, error)
+	// Eligible lists the storages a restore-test may target: active, content `rootdir`, and the agent
+	// holds Datastore.AllocateSpace there.
+	Eligible(ctx context.Context) ([]string, error)
+}
+
+// StorageFree is one storage's free space as the preflight judges it.
+type StorageFree struct {
+	AvailBytes int64
+	UsedBytes  int64
+	Thin       bool
+	// MetaUsedFraction is the thin pool's metadata use (0..1); MetaKnown false = could not be read.
+	MetaUsedFraction float64
+	MetaKnown        bool
+}
+
+// SpacePolicy is rule 1's margin.
+type SpacePolicy struct {
+	Factor       float64 // ≥ 1
+	ReserveBytes int64
+}
+
+// DefaultSpacePolicy is 1.2 × restored + 5 GiB.
+var DefaultSpacePolicy = SpacePolicy{Factor: 1.2, ReserveBytes: 5 << 30}
+
+// SpaceVerdict is the preflight's answer.
+type SpaceVerdict struct {
+	OK       bool
+	Storage  string // the storage the restore goes to (when OK) or was judged (when not)
+	Required int64
+	Avail    int64
+	Reason   string // empty when OK
+	// Avoided is the tested guest's own storage, when rule 2 moved the restore off it.
+	Avoided string
+}
+
+// requiredBytes is rule 1's figure.
+func (p SpacePolicy) requiredBytes(restored int64) int64 {
+	f := p.Factor
+	if f < 1 {
+		f = DefaultSpacePolicy.Factor
+	}
+	return int64(float64(restored)*f) + p.ReserveBytes
+}
+
+// fits judges one storage against rule 1 (data AND thin metadata). An unknown metadata fill on a thin
+// pool refuses (rule 3).
+func fits(fr StorageFree, required int64) (bool, string) {
+	if fr.AvailBytes < required {
+		return false, fmt.Sprintf("needs %s free, has %s", gib(required), gib(fr.AvailBytes))
+	}
+	if fr.Thin {
+		if !fr.MetaKnown {
+			return false, "thin-pool metadata fill unknown"
+		}
+		// The metadata a restore of `required` bytes needs, in the pool's own proportion of metadata to
+		// data. A pool with no data yet has no proportion to read → only the absolute ceiling applies.
+		need := 0.0
+		if fr.UsedBytes > 0 {
+			need = fr.MetaUsedFraction * float64(required) / float64(fr.UsedBytes)
+		}
+		if fr.MetaUsedFraction+need > 0.9 {
+			return false, fmt.Sprintf("thin-pool metadata would reach %.0f%% (now %.0f%%)", 100*(fr.MetaUsedFraction+need), 100*fr.MetaUsedFraction)
+		}
+	}
+	return true, ""
+}
+
+func gib(b int64) string { return fmt.Sprintf("%.1f GiB", float64(b)/(1<<30)) }
+
+// sourceStorages returns the storage ids that hold the ARCHIVED guest's volumes (rootfs and every mpN
+// that names a `storage:volume`), read from the archive's own embedded config — the guest under test.
+// Bind mounts (a leading "/") carry no storage.
+func sourceStorages(rawCfg string) map[string]bool {
+	out := map[string]bool{}
+	for k, v := range archiveCurrentConfig(rawCfg) {
+		if k != "rootfs" && !(strings.HasPrefix(k, "mp") && len(k) > 2 && k[2] >= '0' && k[2] <= '9') {
+			continue
+		}
+		vol := strings.TrimSpace(strings.SplitN(strings.TrimSpace(v), ",", 2)[0])
+		if vol == "" || strings.HasPrefix(vol, "/") {
+			continue
+		}
+		if st, _, ok := strings.Cut(vol, ":"); ok && st != "" {
+			out[st] = true
+		}
+	}
+	return out
+}
+
+// PreflightRestoreSpace applies the three rules. `configured` is `backup.restore_storage`.
+func PreflightRestoreSpace(ctx context.Context, space RestoreSpace, policy SpacePolicy, archive, rawCfg, configured string) SpaceVerdict {
+	if space == nil {
+		return SpaceVerdict{Storage: configured, Reason: "no space check is wired — refusing (fail-closed)"}
+	}
+	restored, src, err := space.RestoredBytes(ctx, archive)
+	if err != nil || restored <= 0 {
+		return SpaceVerdict{Storage: configured, Reason: fmt.Sprintf("cannot tell how much the restore writes (%v)", err)}
+	}
+	required := policy.requiredBytes(restored)
+	own := sourceStorages(rawCfg)
+
+	// Rule 2: the configured storage holds the guest under test → try the others first.
+	var order []string
+	avoided := ""
+	if own[configured] {
+		eligible, eerr := space.Eligible(ctx)
+		if eerr == nil {
+			sort.Strings(eligible)
+			for _, s := range eligible {
+				if s != configured && !own[s] {
+					order = append(order, s)
+				}
+			}
+		}
+		if len(order) > 0 {
+			avoided = configured
+		}
+	}
+	order = append(order, configured)
+
+	var last SpaceVerdict
+	for _, s := range order {
+		fr, ferr := space.Free(ctx, s)
+		if ferr != nil {
+			last = SpaceVerdict{Storage: s, Required: required, Reason: fmt.Sprintf("cannot read free space on %s (%v)", s, ferr)}
+			continue
+		}
+		ok, why := fits(fr, required)
+		v := SpaceVerdict{OK: ok, Storage: s, Required: required, Avail: fr.AvailBytes}
+		if ok {
+			if s != configured {
+				v.Avoided = avoided
+			}
+			return v
+		}
+		v.Reason = fmt.Sprintf("not enough space on %s: restoring %s (%s) %s", s, gib(restored), src, why)
+		last = v
+	}
+	return last
+}

internal/reconcile/restoretest_space_test.go

@@ -0,0 +1,156 @@
+package reconcile
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-672 (v0.133.0) — the restore-test's space preflight. Every test asserts the CONSEQUENCE: whether the
+// Proxmox API was asked to restore anything, where to, and what the result says — never only the verdict.
+
+const gb = int64(1000 * 1000 * 1000)
+
+// fakeSpace is a configurable RestoreSpace.
+type fakeSpace struct {
+	restored    int64
+	restoredErr error
+	free        map[string]StorageFree
+	freeErr     map[string]error
+	eligible    []string
+}
+
+func (f fakeSpace) RestoredBytes(context.Context, string) (int64, string, error) {
+	return f.restored, "fake", f.restoredErr
+}
+func (f fakeSpace) Free(_ context.Context, s string) (StorageFree, error) {
+	if err := f.freeErr[s]; err != nil {
+		return StorageFree{}, err
+	}
+	fr, ok := f.free[s]
+	if !ok {
+		return StorageFree{}, errors.New("unknown storage")
+	}
+	return fr, nil
+}
+func (f fakeSpace) Eligible(context.Context) ([]string, error) { return f.eligible, nil }
+
+// thin9201 is demo-hp's local-lvm at 10:29 on 2026-09-24, just before the restore-test that filled it:
+// 23.2 GB free, 33.3 GB used, metadata 2.65 %.
+var thin9201 = StorageFree{AvailBytes: 23210892 * 1024, UsedBytes: 33277043 * 1024, Thin: true, MetaUsedFraction: 0.0265, MetaKnown: true}
+
+// archive9201 is 9201's archive config: both volumes on local-lvm.
+const archive9201 = "hostname: demo-hp\nrootfs: local-lvm:vm-9201-disk-0,size=32G\nmp0: local-lvm:vm-9201-disk-1,mp=/var/lib/felhom,backup=1,size=70G\nmp8: /mnt/felhom-drives,mp=/mnt/felhom-drives\n"
+
+func spaceEngine(t *testing.T, api *fakeAPI, sp RestoreSpace) (*Engine, *Journal) {
+	t.Helper()
+	j, err := OpenJournal(filepath.Join(t.TempDir(), "journal.log"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { j.Close() })
+	q := NewQueue()
+	t.Cleanup(q.Close)
+	return NewEngine(EngineOptions{API: api, Queue: q, Journal: j, RestoreSpace: sp}), j
+}
+
+func run9201(e *Engine) RestoreTestResult {
+	return e.RunRestoreTest(context.Background(), RestoreTestSpec{
+		Archive: "local:backup/vzdump-lxc-9201-2026_09_23-06_55_25.tar.zst", RestoreStorage: "local-lvm",
+		ScratchMin: 990000, ScratchMax: 990009, SourceTier: "local",
+	})
+}
+
+// TestSpace_The2026_09_24TestIsRefused replays R-672: 9201's archive restores 22.6 GB (its vzdump log),
+// the pool has 23.2 GB free. The test must NOT start — no restore call, no journaled scratch — and the
+// result must say why, as a non-pass.
+//
+// COMPANION RED-PROOFS (REPORT): (1) the preflight removed (v0.132.0's shape) → a restore into local-lvm
+// is issued; (2) `restored` taken from the archive FILE (6.9 GB, the brief's "archive × 1.2 + 5 GiB") →
+// 6.9×1.2+5.4 = 13.7 GB < 23.2 GB free, so the test starts — the defect the uncompressed size exists for.
+func TestSpace_The2026_09_24TestIsRefused(t *testing.T) {
+	api := &fakeAPI{extractCfg: archive9201, cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}}
+	e, j := spaceEngine(t, api, fakeSpace{restored: 22607360000, free: map[string]StorageFree{"local-lvm": thin9201}})
+	res := run9201(e)
+	if len(api.restores) != 0 {
+		t.Fatalf("a restore was issued into a pool that cannot take it: %+v", api.restores)
+	}
+	if len(j.InFlight()) != 0 {
+		t.Fatalf("a scratch entry was journaled for a test that must not start: %+v", j.InFlight())
+	}
+	if res.Pass || !res.Skipped || !strings.Contains(res.SkipReason, "not enough space on local-lvm") {
+		t.Fatalf("result = pass=%v skipped=%v reason=%q — want a non-pass skip naming the storage", res.Pass, res.Skipped, res.SkipReason)
+	}
+	if res.RequiredBytes < 32*gb || res.AvailBytes != thin9201.AvailBytes {
+		t.Fatalf("required=%d avail=%d — want ≥ 32 GB required (22.6 × 1.2 + 5 GiB) against 23.2 GB", res.RequiredBytes, res.AvailBytes)
+	}
+}
+
+// TestSpace_KeepsOffTheTestedGuestsPool — rule 2: another eligible storage that fits takes the restore.
+func TestSpace_KeepsOffTheTestedGuestsPool(t *testing.T) {
+	api := &fakeAPI{extractCfg: archive9201, cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}}
+	e, _ := spaceEngine(t, api, fakeSpace{restored: 22607360000, eligible: []string{"local-lvm", "big-dir"},
+		free: map[string]StorageFree{"local-lvm": {AvailBytes: 900 * gb, UsedBytes: 10 * gb, Thin: true, MetaKnown: true}, "big-dir": {AvailBytes: 500 * gb}}})
+	res := run9201(e)
+	if len(api.restores) != 1 || api.restores[0].Storage != "big-dir" {
+		t.Fatalf("restores = %+v — want ONE restore onto big-dir, off 9201's own pool", api.restores)
+	}
+	if res.TargetStorage != "big-dir" {
+		t.Fatalf("target=%q", res.TargetStorage)
+	}
+	for k, v := range api.restores[0].MountOverrides {
+		if strings.HasPrefix(v, "local-lvm:") {
+			t.Fatalf("%s still lands on the tested guest's pool: %s", k, v)
+		}
+	}
+}
+
+// TestSpace_OnlyOnePool_RuleOneDecides — no other eligible storage: the tested guest's pool is used when it
+// fits (demo-hp's real shape: nvme-scratch takes rootdir but the agent holds no AllocateSpace there).
+func TestSpace_OnlyOnePool_RuleOneDecides(t *testing.T) {
+	api := &fakeAPI{extractCfg: archive9201, cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}}
+	e, _ := spaceEngine(t, api, fakeSpace{restored: 2 * gb, eligible: []string{"local-lvm"}, free: map[string]StorageFree{"local-lvm": thin9201}})
+	res := run9201(e)
+	if len(api.restores) != 1 || api.restores[0].Storage != "local-lvm" || res.Skipped || res.TargetStorage != "local-lvm" {
+		t.Fatalf("restores=%+v skipped=%v — a 2 GB restore fits 23 GB free on the only pool", api.restores, res.Skipped)
+	}
+}
+
+// TestSpace_UnknownRefuses — rule 3, one case per unknown. Nothing is restored in any of them.
+func TestSpace_UnknownRefuses(t *testing.T) {
+	cases := map[string]RestoreSpace{
+		"no space check wired":   nil,
+		"restore size unknown":   fakeSpace{restoredErr: errors.New("no vzdump log"), free: map[string]StorageFree{"local-lvm": thin9201}},
+		"free space unreadable":  fakeSpace{restored: gb, freeErr: map[string]error{"local-lvm": errors.New("api down")}},
+		"thin metadata unknown":  fakeSpace{restored: gb, free: map[string]StorageFree{"local-lvm": {AvailBytes: 900 * gb, UsedBytes: gb, Thin: true}}},
+		"metadata would overrun": fakeSpace{restored: 10 * gb, free: map[string]StorageFree{"local-lvm": {AvailBytes: 900 * gb, UsedBytes: 10 * gb, Thin: true, MetaUsedFraction: 0.5, MetaKnown: true}}},
+	}
+	for name, sp := range cases {
+		t.Run(name, func(t *testing.T) {
+			api := &fakeAPI{extractCfg: archive9201, cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}}
+			var e *Engine
+			if sp == nil {
+				e, _ = spaceEngine(t, api, nil)
+			} else {
+				e, _ = spaceEngine(t, api, sp)
+			}
+			res := run9201(e)
+			if len(api.restores) != 0 || res.Pass || !res.Skipped || res.SkipReason == "" {
+				t.Fatalf("restores=%d pass=%v skipped=%v reason=%q — an unknown must refuse before anything moves",
+					len(api.restores), res.Pass, res.Skipped, res.SkipReason)
+			}
+		})
+	}
+}
+
+// TestSpace_SourceStorages reads the tested guest's pools from the ARCHIVE's config, binds excluded.
+func TestSpace_SourceStorages(t *testing.T) {
+	got := sourceStorages(archive9201 + "mp1: other:vm-9201-disk-2,mp=/x,size=1G\n[snap]\nrootfs: snapstore:x\n")
+	if !got["local-lvm"] || !got["other"] || got["snapstore"] || len(got) != 2 {
+		t.Fatalf("sourceStorages = %v — want local-lvm + other, binds and snapshot sections excluded", got)
+	}
+}

internal/reconcile/space_fake_test.go

@@ -0,0 +1,16 @@
+package reconcile
+
+import "context"
+
+// roomySpace is the permissive RestoreSpace the pre-R-672 restore-test tests run with: 1 GiB restored,
+// 1 TiB free, thin metadata known and low. The space rules themselves are pinned in
+// restoretest_space_test.go.
+type roomySpace struct{}
+
+func (roomySpace) RestoredBytes(context.Context, string) (int64, string, error) {
+	return 1 << 30, "test", nil
+}
+func (roomySpace) Free(context.Context, string) (StorageFree, error) {
+	return StorageFree{AvailBytes: 1 << 40, UsedBytes: 1 << 30, Thin: true, MetaUsedFraction: 0.01, MetaKnown: true}, nil
+}
+func (roomySpace) Eligible(context.Context) ([]string, error) { return nil, nil }

internal/restorespace/restorespace.go

@@ -0,0 +1,176 @@
+// Package restorespace is the production seam behind reconcile.RestoreSpace (R-672, agent v0.133.0):
+// how much a restore of an archive writes, how much a storage has free, and which storages a
+// restore-test may target. Every read that cannot answer returns an error — the preflight then
+// REFUSES (reconcile/restoretest_space.go rule 3); nothing here guesses.
+package restorespace
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+)
+
+// API is the Proxmox subset the provider reads.
+type API interface {
+	ListStorage(ctx context.Context) ([]proxmox.Storage, error)
+	NodeStorage(ctx context.Context) ([]proxmox.Storage, error)
+	StorageContent(ctx context.Context, store string) ([]proxmox.StorageContent, error)
+	Permissions(ctx context.Context, aclPath string) (map[string]int, error)
+}
+
+// Provider implements reconcile.RestoreSpace.
+type Provider struct {
+	API API
+	// ThinMeta reads a thin pool's metadata-used fraction (storage.HostOps.ThinPoolMetadata).
+	ThinMeta func(ctx context.Context, vg, pool string) (float64, bool)
+	// ReadFile reads a vzdump log; nil → os.ReadFile.
+	ReadFile func(name string) ([]byte, error)
+}
+
+var _ reconcile.RestoreSpace = (*Provider)(nil)
+
+// totalWrittenRe is vzdump's own count of the bytes tar wrote into the archive — the UNCOMPRESSED size,
+// i.e. what a restore writes back ("INFO: Total bytes written: 22607360000 (22GiB, 49MiB/s)").
+var totalWrittenRe = regexp.MustCompile(`Total bytes written:\s*(\d+)`)
+
+// archiveExts are the vzdump archive suffixes; the log is the archive name without it + ".log".
+var archiveExts = []string{".tar.zst", ".tar.gz", ".tar.lzo", ".tgz", ".tar"}
+
+func (p *Provider) readFile(name string) ([]byte, error) {
+	if p.ReadFile != nil {
+		return p.ReadFile(name)
+	}
+	return os.ReadFile(name)
+}
+
+// RestoredBytes: a file-backed archive → its vzdump log's "Total bytes written"; a PBS archive → the
+// size Proxmox reports for the snapshot (its logical, uncompressed size). The archive FILE size is never
+// used: it is compressed (6.9 GB for a 22.6 GB restore, measured 2026-09-24).
+func (p *Provider) RestoredBytes(ctx context.Context, archive string) (int64, string, error) {
+	id, vol, ok := strings.Cut(archive, ":")
+	if !ok || id == "" || vol == "" {
+		return 0, "", fmt.Errorf("not a storage volid: %q", archive)
+	}
+	st, err := p.storageConfig(ctx, id)
+	if err != nil {
+		return 0, "", err
+	}
+	switch st.Type {
+	case "pbs":
+		items, err := p.API.StorageContent(ctx, id)
+		if err != nil {
+			return 0, "", fmt.Errorf("list %s: %w", id, err)
+		}
+		for _, it := range items {
+			if it.VolID == archive && it.Size > 0 {
+				return it.Size, "pbs snapshot size", nil
+			}
+		}
+		return 0, "", fmt.Errorf("archive %s not listed on %s with a size", archive, id)
+	default:
+		if st.Path == "" {
+			return 0, "", fmt.Errorf("storage %s (%s) has no path to read a vzdump log from", id, st.Type)
+		}
+		base := path.Base(vol) // "backup/vzdump-lxc-…tar.zst" → "vzdump-lxc-…tar.zst"
+		stem := ""
+		for _, ext := range archiveExts {
+			if strings.HasSuffix(base, ext) {
+				stem = strings.TrimSuffix(base, ext)
+				break
+			}
+		}
+		if stem == "" {
+			return 0, "", fmt.Errorf("unknown archive suffix: %s", base)
+		}
+		logPath := path.Join(st.Path, "dump", stem+".log")
+		b, err := p.readFile(logPath)
+		if err != nil {
+			return 0, "", fmt.Errorf("read vzdump log %s: %w", logPath, err)
+		}
+		m := totalWrittenRe.FindSubmatch(b)
+		if m == nil {
+			return 0, "", fmt.Errorf("vzdump log %s carries no \"Total bytes written\"", logPath)
+		}
+		n, err := strconv.ParseInt(string(m[1]), 10, 64)
+		if err != nil || n <= 0 {
+			return 0, "", fmt.Errorf("vzdump log %s: bad byte count %q", logPath, m[1])
+		}
+		return n, "vzdump log: total bytes written", nil
+	}
+}
+
+func (p *Provider) storageConfig(ctx context.Context, id string) (proxmox.Storage, error) {
+	all, err := p.API.ListStorage(ctx)
+	if err != nil {
+		return proxmox.Storage{}, fmt.Errorf("list storage config: %w", err)
+	}
+	for _, s := range all {
+		if s.Storage == id {
+			return s, nil
+		}
+	}
+	return proxmox.Storage{}, fmt.Errorf("storage %s not configured", id)
+}
+
+// Free reads the node's live usage for `storage`; a thin pool adds its metadata fill.
+func (p *Provider) Free(ctx context.Context, storage string) (reconcile.StorageFree, error) {
+	live, err := p.API.NodeStorage(ctx)
+	if err != nil {
+		return reconcile.StorageFree{}, fmt.Errorf("node storage: %w", err)
+	}
+	for _, s := range live {
+		if s.Storage != storage {
+			continue
+		}
+		if s.Active != 1 {
+			return reconcile.StorageFree{}, fmt.Errorf("storage %s is not active", storage)
+		}
+		fr := reconcile.StorageFree{AvailBytes: s.Avail, UsedBytes: s.Used, Thin: s.Type == "lvmthin"}
+		if fr.Thin {
+			cfg, cerr := p.storageConfig(ctx, storage)
+			if cerr == nil && p.ThinMeta != nil && cfg.VGName != "" && cfg.ThinPool != "" {
+				fr.MetaUsedFraction, fr.MetaKnown = p.ThinMeta(ctx, cfg.VGName, cfg.ThinPool)
+			}
+		}
+		return fr, nil
+	}
+	return reconcile.StorageFree{}, fmt.Errorf("storage %s not reported by the node", storage)
+}
+
+// Eligible: active, content includes `rootdir`, and the agent holds Datastore.AllocateSpace on
+// /storage/<id>. The permission is read for the SPECIFIC privilege — the box-wide grant answers every
+// path with inherited privileges (proxmox.Client.Permissions).
+func (p *Provider) Eligible(ctx context.Context) ([]string, error) {
+	live, err := p.API.NodeStorage(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("node storage: %w", err)
+	}
+	var out []string
+	for _, s := range live {
+		if s.Active != 1 || !hasContent(s.Content, "rootdir") {
+			continue
+		}
+		privs, perr := p.API.Permissions(ctx, "/storage/"+s.Storage)
+		if perr != nil || privs["Datastore.AllocateSpace"] != 1 {
+			continue
+		}
+		out = append(out, s.Storage)
+	}
+	return out, nil
+}
+
+func hasContent(list, want string) bool {
+	for _, c := range strings.Split(list, ",") {
+		if strings.TrimSpace(c) == want {
+			return true
+		}
+	}
+	return false
+}

internal/restorespace/restorespace_test.go

@@ -0,0 +1,133 @@
+package restorespace
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-672 (v0.133.0). The provider behind the restore-test's space preflight. No test reaches a real
+// Proxmox or a real file: the API and ReadFile are fakes.
+
+type fakeAPI struct {
+	cfg     []proxmox.Storage
+	live    []proxmox.Storage
+	content map[string][]proxmox.StorageContent
+	perms   map[string]map[string]int
+}
+
+func (f fakeAPI) ListStorage(context.Context) ([]proxmox.Storage, error) { return f.cfg, nil }
+func (f fakeAPI) NodeStorage(context.Context) ([]proxmox.Storage, error) { return f.live, nil }
+func (f fakeAPI) StorageContent(_ context.Context, s string) ([]proxmox.StorageContent, error) {
+	return f.content[s], nil
+}
+func (f fakeAPI) Permissions(_ context.Context, p string) (map[string]int, error) {
+	if m, ok := f.perms[p]; ok {
+		return m, nil
+	}
+	return map[string]int{}, nil
+}
+
+const archive = "local:backup/vzdump-lxc-9201-2026_09_23-06_55_25.tar.zst"
+
+// The real log's tail (demo-hp, 2026-09-23): 22.6 GB written, a 6.91 GB archive file.
+const vzdumpLog = "2026-09-23 07:02:47 INFO: Total bytes written: 22607360000 (22GiB, 49MiB/s)\n2026-09-23 07:02:47 INFO: archive file size: 6.91GB\n"
+
+// demoHP is demo-hp's storage layout: `local` (dir, backups), `local-lvm` (thin), `nvme-scratch` (dir,
+// rootdir — but the agent holds NO grant there), a pbs.
+func demoHP() fakeAPI {
+	return fakeAPI{
+		cfg: []proxmox.Storage{
+			{Storage: "local", Type: "dir", Path: "/var/lib/vz"},
+			{Storage: "local-lvm", Type: "lvmthin", VGName: "pve", ThinPool: "data"},
+			{Storage: "nvme-scratch", Type: "dir", Path: "/mnt/hdd_1"},
+			{Storage: "felhom-pbs", Type: "pbs"},
+		},
+		live: []proxmox.Storage{
+			{Storage: "local", Type: "dir", Content: "vztmpl,backup,iso,import", Active: 1, Avail: 4 << 30, Used: 34 << 30},
+			{Storage: "local-lvm", Type: "lvmthin", Content: "images,rootdir", Active: 1, Avail: 23210892 * 1024, Used: 33277043 * 1024},
+			{Storage: "nvme-scratch", Type: "dir", Content: "images,rootdir", Active: 1, Avail: 800 << 30},
+			{Storage: "felhom-pbs", Type: "pbs", Content: "backup", Active: 0},
+		},
+		content: map[string][]proxmox.StorageContent{
+			"local":      {{VolID: archive, Size: 7417540996}},
+			"felhom-pbs": {{VolID: "felhom-pbs:backup/ct/9201/2026-09-23T02:00:00Z", Size: 21 << 30}},
+		},
+		perms: map[string]map[string]int{
+			"/storage/local":     {"Datastore.Audit": 1, "Datastore.AllocateSpace": 1},
+			"/storage/local-lvm": {"Datastore.Audit": 1, "Datastore.AllocateSpace": 1},
+			// nvme-scratch: only the inherited box-wide Datastore.Audit — the trap proxmox.Permissions names.
+			"/storage/nvme-scratch": {"Datastore.Audit": 1},
+		},
+	}
+}
+
+// TestRestoredBytes_ReadsTheUncompressedSize — the vzdump log's "Total bytes written", never the archive
+// FILE size (6.9 GB for a 22.6 GB restore).
+//
+// COMPANION RED-PROOF (REPORT): return the storage content's Size for a dir storage → 7417540996, and
+// this test fails at "the compressed file size was used".
+func TestRestoredBytes_ReadsTheUncompressedSize(t *testing.T) {
+	var asked string
+	p := &Provider{API: demoHP(), ReadFile: func(n string) ([]byte, error) { asked = n; return []byte(vzdumpLog), nil }}
+	n, src, err := p.RestoredBytes(context.Background(), archive)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n == 7417540996 {
+		t.Fatal("the compressed file size was used — the restore writes 3× that")
+	}
+	if n != 22607360000 || asked != "/var/lib/vz/dump/vzdump-lxc-9201-2026_09_23-06_55_25.log" {
+		t.Fatalf("n=%d from %q (log %q)", n, src, asked)
+	}
+}
+
+func TestRestoredBytes_UnknownIsAnError(t *testing.T) {
+	cases := map[string]*Provider{
+		"no log":           {API: demoHP(), ReadFile: func(string) ([]byte, error) { return nil, errors.New("ENOENT") }},
+		"log without size": {API: demoHP(), ReadFile: func(string) ([]byte, error) { return []byte("ERROR: failed\n"), nil }},
+	}
+	for name, p := range cases {
+		if n, _, err := p.RestoredBytes(context.Background(), archive); err == nil {
+			t.Fatalf("%s: got %d, want an error (the preflight then refuses)", name, n)
+		}
+	}
+	if _, _, err := (&Provider{API: demoHP()}).RestoredBytes(context.Background(), "local:backup/weird.vma"); err == nil {
+		t.Fatal("an unknown archive suffix must be an error")
+	}
+}
+
+func TestRestoredBytes_PBS(t *testing.T) {
+	p := &Provider{API: demoHP()}
+	n, _, err := p.RestoredBytes(context.Background(), "felhom-pbs:backup/ct/9201/2026-09-23T02:00:00Z")
+	if err != nil || n != 21<<30 {
+		t.Fatalf("n=%d err=%v", n, err)
+	}
+}
+
+// TestEligible_NeedsTheSpecificGrant — nvme-scratch takes rootdir but the agent holds only the inherited
+// Datastore.Audit there, so it is NOT eligible; `local` holds no rootdir.
+func TestEligible_NeedsTheSpecificGrant(t *testing.T) {
+	got, err := (&Provider{API: demoHP()}).Eligible(context.Background())
+	if err != nil || len(got) != 1 || got[0] != "local-lvm" {
+		t.Fatalf("eligible = %v (%v) — want only local-lvm on demo-hp", got, err)
+	}
+}
+
+func TestFree_ThinCarriesMetadata(t *testing.T) {
+	p := &Provider{API: demoHP(), ThinMeta: func(_ context.Context, vg, pool string) (float64, bool) {
+		if vg != "pve" || pool != "data" {
+			t.Fatalf("metadata read for %s/%s", vg, pool)
+		}
+		return 0.0265, true
+	}}
+	fr, err := p.Free(context.Background(), "local-lvm")
+	if err != nil || !fr.Thin || !fr.MetaKnown || fr.MetaUsedFraction != 0.0265 || fr.AvailBytes != 23210892*1024 {
+		t.Fatalf("free = %+v err=%v", fr, err)
+	}
+	if _, err := p.Free(context.Background(), "felhom-pbs"); err == nil {
+		t.Fatal("an inactive storage must be an error")
+	}
+}

internal/storage/claim.go

@@ -53,7 +53,11 @@ type claimFacts struct {
 	nodes       []claimNode // the whole disk + its children (partitions)
 	lvmPV       bool        // pvs (authoritative): the disk / a partition is an LVM physical volume
 	zfsMember   bool        // zpool (authoritative): the disk / a partition is a ZFS pool member
-	gatherErr   string      // non-empty ⇒ a REQUIRED read failed ⇒ fail-safe CLAIMED
+	// felhomOwnedMounts (R-220) — mountpoints OUTSIDE /mnt/felhom-drives that are nevertheless Felhom's
+	// OWN, corroborated from the host mount table: the same device is also mounted at the managed path.
+	// Empty means "nothing corroborated", which is the fail-safe direction.
+	felhomOwnedMounts map[string]bool
+	gatherErr         string // non-empty ⇒ a REQUIRED read failed ⇒ fail-safe CLAIMED
 }
 
 // classifyClaim is the pure guard verdict. unclaimed=true ONLY when the device is provably free for
@@ -81,7 +85,20 @@ func classifyClaim(f claimFacts) (unclaimed bool, reason string) {
 		if memberFSTypes[n.fstype] {
 			return false, "device holds a " + n.fstype + " (" + n.name + ")"
 		}
-		if n.mountpoint != "" && !underFelhomDrives(n.mountpoint) {
+		// ── R-220 — A MOUNT FELHOM ITSELF MADE IS NOT "SOMETHING ELSE". ───────────────────────
+		//
+		// Enrolment mounts a drive TWICE: at the managed path `/mnt/felhom-drives/<name>` and at the
+		// raw `/mnt/<name>` it creates on the host. The host — and therefore that raw mount — survives
+		// a guest rebuild, while the controller's registry does not. So after a rebuild the customer's
+		// own drives looked foreign, `attach` returned an empty list, and the refusal told them to
+		// choose from it. Measured live three times (CAMPAIGN-11 Phase 1, and the R-201 re-walk twice);
+		// unmounting only the raw mounts flipped `attach: []` to both drives every time.
+		//
+		// The fence this must NOT breach: a disk genuinely in use by something else stays refused. So
+		// the exemption is not "any /mnt/* path" — it is CORROBORATED: the same device must ALSO be
+		// mounted at Felhom's managed path, which is a state only Felhom's own enrolment produces.
+		// A foreign disk at /srv/data or /media/x has no such counterpart and is still refused.
+		if n.mountpoint != "" && !underFelhomDrives(n.mountpoint) && !f.felhomOwnedMounts[n.mountpoint] {
 			return false, "device is mounted at " + n.mountpoint + " (" + n.name + ")"
 		}
 	}
@@ -154,6 +171,8 @@ func (h *SudoHostOps) gatherClaimFacts(ctx context.Context, device string) claim
 		return f
 	}
 	f.nodes = nodes
+	// R-220: corroborate which non-managed mountpoints are nevertheless Felhom's own.
+	f.felhomOwnedMounts = felhomOwnedMounts(device, nodes, h.mountTable)
 
 	// LVM PV (authoritative). pvs installed but erroring ⇒ fail-safe claimed; absent ⇒ rely on lsblk's
 	// LVM2_member FSTYPE (already in nodes).
@@ -285,3 +304,71 @@ func (h *SudoHostOps) zfsMembers(ctx context.Context, nodes []claimNode, wholeDi
 	}
 	return false, nil
 }
+
+// mountTableSource yields the host mount table as (device, mountpoint) pairs. A seam so the R-220
+// corroboration is unit-testable without a host. nil ⇒ the real /proc/mounts.
+type mountTableSource func() ([][2]string, error)
+
+// procMounts reads /proc/mounts — WORLD-READABLE, so this needs no sudo and no allowlisted command.
+// That matters: the lsblk invocation is pinned verbatim in the sudoers file
+// (`lsblk -J -o NAME,FSTYPE,PTTYPE,MOUNTPOINT /dev/*`), so switching it to the plural MOUNTPOINTS
+// would have meant shipping a sudoers change with the binary — a far larger blast radius than this
+// finding warrants. Reading the mount table directly sidesteps that entirely.
+func procMounts() ([][2]string, error) {
+	data, err := os.ReadFile("/proc/mounts")
+	if err != nil {
+		return nil, err
+	}
+	var out [][2]string
+	for _, line := range strings.Split(string(data), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) < 2 {
+			continue
+		}
+		// /proc/mounts escapes spaces as \040; unescape so a path with a space still compares.
+		out = append(out, [2]string{fields[0], strings.ReplaceAll(fields[1], `\040`, " ")})
+	}
+	return out, nil
+}
+
+// felhomOwnedMounts returns the mountpoints of `device` (and its children) that sit OUTSIDE
+// /mnt/felhom-drives but are still Felhom's own, corroborated by the same device also being mounted
+// UNDER /mnt/felhom-drives. That pairing is what enrolment produces and nothing else does.
+//
+// ⚠ FAIL-SAFE: an unreadable mount table returns an EMPTY set, never a permissive one. The device then
+// classifies exactly as it did before R-220 — refused — because "we could not corroborate" must never
+// read as "it is ours".
+func felhomOwnedMounts(device string, nodes []claimNode, src mountTableSource) map[string]bool {
+	if src == nil {
+		src = procMounts
+	}
+	table, err := src()
+	if err != nil {
+		return nil // unreadable ⇒ corroborate nothing
+	}
+	// Every device name this disk answers to: the whole disk and each child node.
+	devs := map[string]bool{device: true}
+	if wd, ok := wholeDiskOf(device); ok {
+		devs[wd] = true
+	}
+	for _, n := range nodes {
+		devs["/dev/"+n.name] = true
+	}
+	// A device is Felhom-managed only if it is mounted under the managed prefix.
+	managed := map[string]bool{}
+	for _, row := range table {
+		if devs[row[0]] && underFelhomDrives(row[1]) {
+			managed[row[0]] = true
+		}
+	}
+	if len(managed) == 0 {
+		return nil
+	}
+	owned := map[string]bool{}
+	for _, row := range table {
+		if managed[row[0]] && !underFelhomDrives(row[1]) {
+			owned[path.Clean(row[1])] = true
+		}
+	}
+	return owned
+}

internal/storage/claim_r220_test.go

@@ -0,0 +1,102 @@
+package storage
+
+import "testing"
+
+// ── R-220 — A MOUNT FELHOM ITSELF MADE IS NOT "SOMETHING ELSE" ──────────────────────────────────
+//
+// Enrolment mounts a drive twice: at `/mnt/felhom-drives/<name>` and at the raw `/mnt/<name>` it
+// creates on the host. The host survives a guest rebuild; the controller's registry does not. So after
+// a rebuild the customer's own drives read as claimed-by-something-else, `attach` came back empty, and
+// the refusal told them to pick from the empty list. Measured three times live.
+//
+// The fence: a disk genuinely in use elsewhere must STILL be refused. These assert both directions.
+
+// ── SCENARIO E — the customer's own drive is offered again after a rebuild ───────────────────────
+//
+// RED-PROOF: drop `&& !f.felhomOwnedMounts[n.mountpoint]` from classifyClaim — the pre-R-220 check —
+// and this FAILS with the drive refused and the list empty again.
+func TestClassifyClaim_R220_FelhomsOwnRawMountIsNotForeign(t *testing.T) {
+	f := claimFacts{
+		device: "/dev/sdb", wholeDisk: "/dev/sdb", wholeDiskOK: true,
+		nodes: []claimNode{{name: "sdb", fstype: "ext4", mountpoint: "/mnt/adatok"}},
+		// corroborated: the SAME device is also mounted at the managed path
+		felhomOwnedMounts: map[string]bool{"/mnt/adatok": true},
+	}
+	unclaimed, reason := classifyClaim(f)
+	if !unclaimed {
+		t.Fatalf("R-220 RETURNED: the customer's own drive is refused after a rebuild — %q", reason)
+	}
+}
+
+// ── SCENARIO F — a genuinely foreign mount is STILL refused ──────────────────────────────────────
+//
+// RED-PROOF: over-widen the fix to exempt any /mnt/* path (or to skip the mountpoint check entirely)
+// and this FAILS — a disk another system is using would be offered for formatting.
+func TestClassifyClaim_R220_ForeignMountIsStillRefused(t *testing.T) {
+	for _, mp := range []string{"/srv/data", "/media/photos", "/mnt/someone-elses-disk", "/var/lib/other"} {
+		f := claimFacts{
+			device: "/dev/sdb", wholeDisk: "/dev/sdb", wholeDiskOK: true,
+			nodes:             []claimNode{{name: "sdb", fstype: "ext4", mountpoint: mp}},
+			felhomOwnedMounts: nil, // nothing corroborated it as ours
+		}
+		unclaimed, reason := classifyClaim(f)
+		if unclaimed {
+			t.Fatalf("THE FENCE BROKE: a disk mounted at %s was offered for formatting", mp)
+		}
+		if reason == "" {
+			t.Fatalf("a refusal must carry a reason (%s)", mp)
+		}
+	}
+}
+
+// The corroboration itself: it must require BOTH mounts of the SAME device, and fail safe.
+func TestFelhomOwnedMounts_RequiresTheManagedCounterpart(t *testing.T) {
+	nodes := []claimNode{{name: "sdb"}}
+
+	t.Run("both mounts present -> the raw one is ours", func(t *testing.T) {
+		src := func() ([][2]string, error) {
+			return [][2]string{
+				{"/dev/sdb", "/mnt/adatok"},
+				{"/dev/sdb", "/mnt/felhom-drives/adatok"},
+			}, nil
+		}
+		got := felhomOwnedMounts("/dev/sdb", nodes, src)
+		if !got["/mnt/adatok"] {
+			t.Fatal("the raw enrolment mount was not recognised as Felhom's own")
+		}
+	})
+
+	t.Run("only the raw mount -> corroborates NOTHING", func(t *testing.T) {
+		src := func() ([][2]string, error) {
+			return [][2]string{{"/dev/sdb", "/mnt/adatok"}}, nil
+		}
+		if got := felhomOwnedMounts("/dev/sdb", nodes, src); len(got) != 0 {
+			t.Fatalf("a lone /mnt/<name> mount must corroborate nothing, got %v", got)
+		}
+	})
+
+	t.Run("a DIFFERENT device under the managed path does not vouch for this one", func(t *testing.T) {
+		src := func() ([][2]string, error) {
+			return [][2]string{
+				{"/dev/sdb", "/srv/data"},
+				{"/dev/sdc", "/mnt/felhom-drives/mentes"}, // someone else's, not sdb's
+			}, nil
+		}
+		if got := felhomOwnedMounts("/dev/sdb", nodes, src); got["/srv/data"] {
+			t.Fatal("another device's managed mount vouched for a foreign one")
+		}
+	})
+
+	t.Run("an unreadable mount table corroborates NOTHING (fail-safe)", func(t *testing.T) {
+		src := func() ([][2]string, error) { return nil, errRead }
+		if got := felhomOwnedMounts("/dev/sdb", nodes, src); len(got) != 0 {
+			t.Fatalf("an unreadable mount table must corroborate nothing, got %v", got)
+		}
+	})
+}
+
+var errRead = errNoMountTable{}
+
+type errNoMountTable struct{}
+
+func (errNoMountTable) Error() string { return "mount table unreadable" }

internal/storage/hostops.go

@@ -164,6 +164,9 @@ type SudoHostOps struct {
 	// UNPRIVILEGED read (`systemctl is-failed`) — seam-injected so the reassert's F10 reset-failed path
 	// is unit-testable without a real systemd. Default set in NewSudoHostOps.
 	unitFailed func(ctx context.Context, unit string) bool
+	// mountTable (R-220) yields the host mount table for the "is this mount Felhom's own?"
+	// corroboration. nil ⇒ the real /proc/mounts; tests inject.
+	mountTable mountTableSource
 }
 
 // SudoHostOpsConfig configures a SudoHostOps.

internal/storage/observe.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"regexp"
 	"strings"
+	"sync"
 
 	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
@@ -35,6 +36,45 @@ type Observer struct {
 	host   HostReader
 	ops    HostOps
 	logger *slog.Logger
+
+	// R-672 (v0.133.0): a thin pool crossing thinPoolAlarmFraction (data OR metadata) requests an
+	// out-of-band host report at once, so the hub's storage-fill alarm sees it in seconds instead of at
+	// the next 15-minute report. Rising edge per pool; re-armed below thinPoolRearmFraction.
+	highMu     sync.Mutex
+	high       map[string]bool
+	onThinHigh func()
+}
+
+const (
+	thinPoolAlarmFraction = 0.90
+	thinPoolRearmFraction = 0.85
+)
+
+// SetThinHighTrigger wires the out-of-band report request (main: the storage trigger channel).
+func (o *Observer) SetThinHighTrigger(f func()) { o.onThinHigh = f }
+
+// noteThinFill is the edge detector. key separates data from metadata so each has its own edge.
+func (o *Observer) noteThinFill(key string, frac float64) {
+	o.highMu.Lock()
+	if o.high == nil {
+		o.high = map[string]bool{}
+	}
+	fire := false
+	switch {
+	case frac >= thinPoolAlarmFraction && !o.high[key]:
+		o.high[key] = true
+		fire = true
+	case frac < thinPoolRearmFraction && o.high[key]:
+		o.high[key] = false
+	}
+	o.highMu.Unlock()
+	if fire {
+		o.logger.Error("storage: thin pool crossed 90% — requesting an immediate host report (the hub alarms)",
+			"pool", key, "fraction", frac)
+		if o.onThinHigh != nil {
+			o.onThinHigh()
+		}
+	}
 }
 
 // NewObserver builds an Observer. host defaults to a ProcHostReader; logger to the
@@ -260,6 +300,7 @@ func (o *Observer) build(s proxmox.Storage, mounts []Mount) observed {
 			o.logger.Warn("storage: lvmthin pool data fill is high (a full pool corrupts every guest on it)",
 				"storage", s.Storage, "data_used_fraction", frac)
 		}
+		o.noteThinFill(s.Storage+"/data", frac)
 	}
 
 	// SMART-only device hint (v0.95.0): a dir-storage that lives INSIDE a shared filesystem (the

internal/storage/observe_thinhigh_test.go

@@ -0,0 +1,34 @@
+package storage
+
+import (
+	"context"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+)
+
+// R-672 (v0.133.0): a thin pool crossing 90 % requests an out-of-band host report ONCE, through the
+// watchdog's own read path (Known — every few seconds), so the hub's storage-fill alarm sees the pool in
+// seconds, not at the next 15-minute report. Re-armed below 85 %.
+//
+// COMPANION RED-PROOF (REPORT): remove the noteThinFill call from the data path → "no report was
+// requested when the pool crossed 90 %".
+func TestThinHigh_RequestsOneReportPerCrossing(t *testing.T) {
+	pool := proxmox.Storage{Storage: "local-lvm", Type: "lvmthin", Content: "rootdir,images", Total: 1000, Active: 1}
+	api := &fakeStorageAPI{node: "n", cluster: []proxmox.Storage{pool}}
+	o := NewObserver(api, &fakeHostReader{}, nil, quietLogger())
+	asked := 0
+	o.SetThinHighTrigger(func() { asked++ })
+	for i, used := range []int64{800, 910, 950, 1000, 840, 920} {
+		p := pool
+		p.Used, p.Avail, p.UsedFraction = used, 1000-used, float64(used)/1000
+		api.nodeSt = []proxmox.Storage{p}
+		if _, err := o.Known(context.Background()); err != nil {
+			t.Fatal(err)
+		}
+		want := map[int]int{0: 0, 1: 1, 2: 1, 3: 1, 4: 1, 5: 2}[i]
+		if asked != want {
+			t.Fatalf("after %d/1000 used: %d report requests, want %d", used, asked, want)
+		}
+	}
+}

scripts/agent_gates.py

@@ -41,11 +41,23 @@ import sys
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 SHARED_REUSE = os.path.join(os.path.dirname(ROOT), "felhom.eu", "scripts", "reuse_refs_check.py")
+SHARED_INSTRUCTIONS = os.path.join(
+    os.path.dirname(ROOT), "felhom.eu", "scripts", "instructions_gate.py")
+# R-389 — shared, like the two above: it lives in felhom.eu/scripts/ and is never copied.
+SHARED_OBSERVATIONS = os.path.join(
+    os.path.dirname(ROOT), "felhom.eu", "scripts", "observations_gate.py")
 
 # (label, absolute script path, args, fast)
 GATES = [
     ("reuse-refs", SHARED_REUSE, [ROOT], True),
+    ("instructions", SHARED_INSTRUCTIONS, [ROOT], True),
     ("published", os.path.join(ROOT, "scripts", "check-published-versions.py"), [], False),
+    # R-273: the tag half of a release. Legs 1-2 need no network, so it runs in --fast too — the
+    # missing TAG is what actually broke every install, and the pre-push hook is the earliest place
+    # that can catch it.
+    ("release-complete", os.path.join(ROOT, "scripts", "check-release-complete.py"), [], True),
+    # R-389 — a REPORT.md observation with no register row behind it. Fast: stdlib file reads.
+    ("observations", SHARED_OBSERVATIONS, [ROOT], True),
 ]
 
 VERDICT = {0: "OK", 1: "FAILED", 2: "INCONCLUSIVE"}

scripts/check-published-versions.py

@@ -14,10 +14,32 @@ Nothing in the build, deploy or session-end path checked that either existed, so
            documented-path reinstall would have silently DOWNGRADED both boxes to the pre-merge
            agent — and would have *succeeded* while doing it.
 
-THE INVARIANT, AND WHY IT IS THIS ONE.
+THE INVARIANTS — there are TWO now, and the second is R-188's price.
 
-  For every `v<semver>` git tag in this repo: the matching generic package must be DOWNLOADABLE,
-  and the tag must serve the agent's configs.
+  (1) For every `v<semver>` git tag in this repo: the matching generic package must be DOWNLOADABLE,
+      and the tag must serve the agent's configs.
+
+  (2) No PUBLISHED version may be missing its tag.
+
+Invariant (2) is new (R-188, 2026-08-03) and it exists because `release-agent.sh` now pushes the tag
+AFTER publishing. The old order pushed the tag first, and the old comment said why: a tag with no
+package is caught here, a package with no tag is invisible, because the Gitea package LISTING api
+needs a token this gate does not have. That reasoning was sound and the ordering was still wrong —
+the tag push is what wakes CI, so every correct release had a ~50% chance of running this gate in the
+seconds before its own package existed and mailing the operator a failure for a release that worked
+(measured across two releases: runs 12/13 and 17/18, same shas, opposite results).
+
+Moving the push does not get to trade invariant (2) away, so it is asserted here instead — WITHOUT a
+token, and therefore as a BOUNDED PROBE rather than an enumeration:
+
+  * the FRONTIER — the versions immediately above the highest tag. This is the realistic failure the
+    new ordering makes possible: publish succeeds, tag push fails, so the orphan is exactly one
+    version beyond the newest tag.
+  * the GAPS — patch versions that fall between two existing tags and have no tag of their own.
+
+Re-measured 2026-08-03, not assumed: `GET /api/v1/packages/admin?type=generic` answers **401** with no
+token, so absence still cannot be proven. The probe set is PRINTED on every run, because a check whose
+coverage is invisible reads as a guarantee it is not making.
 
 The task's §8.4 asked for a different one — *"the version the hub tells machines to install must be
 downloadable"* — and that is the better invariant in principle. **It is not implementable from CI,
@@ -36,6 +58,8 @@ v0.120.0, which is published.
 
 **What it does NOT catch, stated plainly:** the hub vouching a version that was never released at
 all (no tag, no package). Nothing here can see that; it belongs at vouch time, in the hub. → R-184.
+Nor does the converse probe prove that NO untagged package exists — only that none exists at the
+probed versions, which are printed. Closing that properly needs a read token in CI (→ R-184).
 
 FAIL-CLOSED. A network error, an unparseable response or an unreachable Gitea is exit **2
 INCONCLUSIVE**, naming every URL tried — never a pass. "Cannot determine" is not "fine": that is the
@@ -48,7 +72,7 @@ carrying python3 and git and nothing else, and an earlier workflow step died on
 
     python3 scripts/check-published-versions.py
 
-Exit: 0 every tag installable · 1 at least one is not · 2 could not be determined.
+Exit: 0 both invariants hold · 1 either is violated · 2 could not be determined.
 Env: GITEA_BASE overrides the Gitea root (CI sets the in-cluster service URL).
 """
 import json
@@ -71,6 +95,25 @@ PROBE_CONFIG = "configs/felhom-agent.service"
 
 TAG_RE = re.compile(r"^v(\d+\.\d+\.\d+)$")
 
+# THE retention number, read from the one file that owns it. A check and the policy it enforces
+# must read the same number from the same place, or they drift and the drift looks like a defect
+# in something else — which is exactly what happened on 2026-08-08/09 (R-287).
+RETENTION_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "retention-policy.json")
+
+
+def retention_kept():
+    """How many of the newest generic versions the registry is expected to still serve.
+
+    Fails CLOSED and LOUD: a missing or unreadable policy file makes the check INCONCLUSIVE
+    rather than silently unbounded. An unbounded check would re-create the red this fixed; a
+    silently-bounded one would be worse.
+    """
+    with open(RETENTION_FILE, encoding="utf-8") as fh:
+        n = json.load(fh)["generic_versions_kept"]
+    if not isinstance(n, int) or n < 1:
+        raise ValueError("generic_versions_kept must be a positive int, got %r" % (n,))
+    return n
+
 tried = []
 
 
@@ -94,6 +137,53 @@ def inconclusive(msg):
     sys.exit(2)
 
 
+def _pkg_exists(version):
+    """True iff the generic package for `version` is downloadable anonymously."""
+    url = "%s/api/packages/%s/generic/%s/%s/%s" % (GITEA_BASE, OWNER, PKG, version, PKG)
+    status, _ = _get(url)
+    return status == 200, url
+
+
+def untagged_probe_set(versions):
+    """The versions to probe for invariant (2), as (version, why) pairs.
+
+    Bounded on purpose and printed by the caller: the package listing api needs a token (401,
+    re-measured 2026-08-03), so absence cannot be enumerated. What CAN be done is to probe the
+    places an orphan would actually land.
+
+      FRONTIER — a publish that succeeded followed by a tag push that failed leaves the orphan
+                 exactly one version past the newest tag. This is the failure mode the R-188
+                 reordering makes possible, so it is the one that must not be guesswork.
+      GAPS     — a patch number skipped between two consecutive tags. Bounded per gap so a typo'd
+                 tag (v0.130.0 after v0.121.1) cannot turn this into a thousand requests.
+    """
+    parsed = sorted(tuple(int(p) for p in v.split(".")) for v in versions)
+    have = set(parsed)
+    out = []
+    if not parsed:
+        return out
+
+    hi = parsed[-1]
+    for cand, why in (
+        ((hi[0], hi[1], hi[2] + 1), "next patch after the newest tag"),
+        ((hi[0], hi[1], hi[2] + 2), "second patch after the newest tag"),
+        ((hi[0], hi[1] + 1, 0), "next minor after the newest tag"),
+        ((hi[0] + 1, 0, 0), "next major after the newest tag"),
+    ):
+        if cand not in have:
+            out.append(("%d.%d.%d" % cand, why))
+
+    MAX_GAP_PROBES = 12
+    for a, b in zip(parsed, parsed[1:]):
+        if a[0] != b[0] or a[1] != b[1]:
+            continue  # a minor/major step is not a patch gap
+        for patch in range(a[2] + 1, min(b[2], a[2] + 1 + MAX_GAP_PROBES)):
+            cand = (a[0], a[1], patch)
+            if cand not in have:
+                out.append(("%d.%d.%d" % cand, "patch gap between v%d.%d.%d and v%d.%d.%d" % (a + b)))
+    return out
+
+
 def main():
     print("check-published-versions — every released agent version must be INSTALLABLE")
     print("  gitea:", GITEA_BASE)
@@ -118,7 +208,28 @@ def main():
         print("  no v<semver> tags in this repo yet — nothing to check, and nothing proven")
         print("\ncheck-published-versions: NOTHING TO CHECK")
         return 0
-    print("  %d released version(s) to verify: %s" % (len(versions), ", ".join(versions)))
+    all_versions = versions
+    try:
+        keep = retention_kept()
+    except Exception as e:
+        inconclusive("cannot read the retention policy (%s): %s" % (RETENTION_FILE, e))
+
+    # Bound the assertion to what the registry is expected to still hold. Sorted by SEMVER, not
+    # lexically: "0.9.0" > "0.10.0" as strings, and that would silently drop the wrong end.
+    def _key(v):
+        return tuple(int(x) for x in v.split("."))
+    versions = sorted(all_versions, key=_key)[-keep:]
+    dropped = [v for v in all_versions if v not in versions]
+
+    print("  %d released version(s); retention policy keeps the newest %d" % (len(all_versions), keep))
+    print("  verifying: %s" % ", ".join(versions))
+    if dropped:
+        # NEVER silent. A bounded check that does not say what it stopped covering is how a
+        # narrowing becomes permanent by accident.
+        print("  NOT ASSERTED (older than the retention window, and therefore not expected to be")
+        print("  downloadable): %s" % ", ".join(dropped))
+        print("  ^ these versions still have git TAGS and are still installable in the sense that")
+        print("    their configs resolve; what is no longer asserted is the BINARY's presence.")
 
     bad = []
     for v in versions:
@@ -144,14 +255,42 @@ def main():
         else:
             print("  ok   v%s: binary downloadable + tag serves its configs" % v)
 
+    # ── invariant (2): no PUBLISHED version may be missing its tag (R-188) ──────────────────────
+    probes = untagged_probe_set(versions)
+    orphans = []
     print()
+    print("  converse probe — a published version with no tag (bounded; the package listing api")
+    print("  needs a token, so this cannot enumerate). Probing %d version(s):" % len(probes))
+    for v, why in probes:
+        try:
+            exists, url = _pkg_exists(v)
+        except Exception as e:
+            inconclusive("network failure while probing v%s: %s" % (v, e))
+        mark = "PUBLISHED — NO TAG" if exists else "absent (ok)"
+        print("    %-10s %-42s %s" % (v, why, mark))
+        if exists:
+            orphans.append((v, url))
+
+    print()
+    if bad or orphans:
+        if orphans:
+            print("check-published-versions: %d PUBLISHED VERSION(S) WITH NO TAG" % len(orphans))
+            for v, url in orphans:
+                print("  v%s is downloadable at %s but has no git tag." % (v, url))
+            print("  A release publishes and then pushes its tag; a package with no tag means the")
+            print("  push failed or was skipped. The local tag is probably still in the release")
+            print("  clone — finish it with:")
+            for v, _ in orphans:
+                print("      git push origin v%s" % v)
+            print("  (and if the tag is gone, re-create it on the released commit before pushing.)")
     if bad:
         print("check-published-versions: %d RELEASED VERSION(S) NOT INSTALLABLE" % len(bad))
         print("  A tagged version with no package is a release that was BUILT and never PUBLISHED —")
         print("  the R-115 defect, three times in five days. Publish it with:")
         print("      scripts/release-agent.sh <version>")
+    if bad or orphans:
         return 1
-    print("check-published-versions: ALL RELEASED VERSIONS INSTALLABLE")
+    print("check-published-versions: ALL RELEASED VERSIONS INSTALLABLE, AND NONE UNTAGGED")
     return 0
 
 

scripts/check-release-complete.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""check-release-complete.py — the version at the head of CHANGELOG.md is a COMPLETE release.
+
+THE DEFECT THIS IS A MACHINE FOR (2026-08-08/09, R-273). Agent v0.128.0 was built, tested,
+CHANGELOG'd and published to the package registry — and its git tag was never pushed. The hub then
+vouched it, and because felhom-host-install.sh fetches an agent's config files from
+`raw/tag/v<version>/configs/`, EVERY fresh install and every reinstall died at step 5 of 8, as root,
+on a virgin machine, for the better part of a day.
+
+`scripts/release-agent.sh` already warns about exactly this, in as many words:
+    "a released version without a git tag 404s a box mid-install, as root"
+The warning was there, it was correct, and the step was still missed. **So the fix is a machine and
+not a reminder** — that is the whole point of this file.
+
+WHAT IT ASSERTS, for the newest `## vX.Y.Z` in CHANGELOG.md:
+  1. a git tag `vX.Y.Z` EXISTS, and
+  2. it points at a commit that is an ANCESTOR OF (or equal to) the tip it was released from — a tag
+     parked on an unrelated commit is not a release, and
+  3. the generic package for X.Y.Z is DOWNLOADABLE.
+
+(3) needs the network. (1) and (2) do not, and they are the half that actually failed — so this gate
+is useful offline and says so rather than going quiet.
+
+EXIT CODES, matching this repo's other gates: 0 clean, 1 convicted, 2 inconclusive. An unreachable
+registry is INCONCLUSIVE for leg 3 only; legs 1 and 2 still run and can still convict.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+GITEA_BASE = os.environ.get("GITEA_BASE", "https://gitea.dooplex.hu").rstrip("/")
+OWNER, PKG = "admin", "felhom-agent"
+HEAD_RE = re.compile(r"^##\s+v?(\d+\.\d+\.\d+)\b", re.M)
+
+
+def git(*args):
+    return subprocess.run(("git",) + args, cwd=ROOT, capture_output=True, text=True)
+
+
+def head_version():
+    ch = os.path.join(ROOT, "CHANGELOG.md")
+    if not os.path.exists(ch):
+        return None
+    m = HEAD_RE.search(open(ch, encoding="utf-8").read())
+    return m.group(1) if m else None
+
+
+def main():
+    print("check-release-complete — the newest CHANGELOG version is a complete release")
+    v = head_version()
+    if not v:
+        print("  no '## vX.Y.Z' heading in CHANGELOG.md — nothing to check, and nothing proven")
+        return 0
+    tag = "v" + v
+    print("  newest CHANGELOG version: %s" % tag)
+
+    problems, inconclusive = [], []
+
+    # ---- leg 1 + 2: the tag, and where it points. Offline-capable. -----------------------------
+    r = git("rev-parse", "-q", "--verify", "refs/tags/%s^{commit}" % tag)
+    if r.returncode != 0:
+        # A shallow CI clone has no tags of its own; ask the remote before convicting, so this
+        # gate does not fire on a clone shape rather than on a real defect.
+        ls = git("ls-remote", "--tags", "origin", "refs/tags/%s" % tag)
+        if ls.returncode != 0:
+            inconclusive.append("cannot reach origin to look for tag %s: %s"
+                                % (tag, ls.stderr.strip()[:120]))
+        elif not ls.stdout.strip():
+            problems.append(
+                "TAG %s DOES NOT EXIST. The installer fetches this version's configs from\n"
+                "        %s/%s/felhom-agent/raw/tag/%s/configs/ — without the tag every install\n"
+                "        404s mid-run, as root. Fix:  git tag -a %s <released-commit> && git push origin %s"
+                % (tag, GITEA_BASE, OWNER, tag, tag, tag))
+        else:
+            print("  ok  tag %s exists on origin (not in this shallow clone)" % tag)
+    else:
+        sha = r.stdout.strip()
+        anc = git("merge-base", "--is-ancestor", sha, "HEAD")
+        if anc.returncode == 0:
+            print("  ok  tag %s -> %s, an ancestor of HEAD" % (tag, sha[:10]))
+        else:
+            problems.append("tag %s points at %s, which is NOT an ancestor of HEAD — a tag parked "
+                            "on an unrelated commit is not a release" % (tag, sha[:10]))
+
+    # ---- leg 3: the package. Needs the network. ------------------------------------------------
+    url = "%s/api/packages/%s/generic/%s/%s/%s" % (GITEA_BASE, OWNER, PKG, v, PKG)
+    req = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=25) as resp:
+            if resp.status == 200:
+                print("  ok  package %s is downloadable" % v)
+            else:
+                problems.append("package %s returned HTTP %s at %s" % (v, resp.status, url))
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            problems.append("PACKAGE %s IS NOT PUBLISHED (HTTP 404 at %s).\n"
+                            "        Fix:  bash scripts/release-agent.sh %s" % (v, url, v))
+        else:
+            inconclusive.append("registry returned HTTP %s for %s" % (e.code, v))
+    except Exception as e:
+        inconclusive.append("registry unreachable (%s) — leg 3 not checked; legs 1-2 still ran" % e)
+
+    if problems:
+        print("\ncheck-release-complete: INCOMPLETE RELEASE")
+        for p in problems:
+            print("  - " + p)
+        return 1
+    if inconclusive:
+        print("\ncheck-release-complete: INCONCLUSIVE — an undetermined result is never a pass")
+        for i in inconclusive:
+            print("  - " + i)
+        return 2
+    print("\ncheck-release-complete: %s is tagged, placed and published." % tag)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/publish-agent.sh

@@ -51,7 +51,11 @@ if [[ -z "$BIN" ]]; then
     BIN="$(mktemp -t felhom-agent.XXXXXX)"
     CLEANUP_BIN="$BIN"
     log "building felhom-agent $VERSION from $REPO_ROOT …"
-    ( cd "$REPO_ROOT" && CGO_ENABLED=0 go build -ldflags "-X main.version=${VERSION}" -o "$BIN" ./cmd/felhom-agent )
+    # These flags MUST match release-agent.sh's build exactly — see the long comment there (R-186).
+    # They used to differ: this line forced CGO_ENABLED=0 and produced a binary 74 KB smaller than
+    # the one the release path built for the same version. One version name must mean one binary
+    # whichever entry point produced it.
+    ( cd "$REPO_ROOT" && go build -trimpath -buildvcs=false -ldflags "-X main.version=${VERSION}" -o "$BIN" ./cmd/felhom-agent )
 fi
 [[ -f "$BIN" ]] || die "binary not found: $BIN"
 trap '[[ -n "$CLEANUP_BIN" ]] && rm -f "$CLEANUP_BIN"' EXIT

scripts/release-agent.sh

@@ -74,7 +74,25 @@ existing="$(curl -fsS -o /dev/null -w '%{http_code}' \
 BIN="$(mktemp -t felhom-agent-XXXXXX)"
 trap 'rm -f "$BIN"' EXIT
 log "building $VERSION …"
-go build -ldflags "-X main.version=$VERSION" -o "$BIN" ./cmd/felhom-agent \
+# REPRODUCIBLE BY CONSTRUCTION (R-186). The sha printed below is the one the operator vouches, and
+# until now nobody could rebuild it to check: `go build` stamps a module version derived from VCS
+# state, so a build made BEFORE the tag exists and a rebuild made after it are different binaries.
+# Measured 2026-08-03 at this commit — same source, same toolchain, same ldflags:
+#
+#   default flags,  no tag yet .. 18f4a495…  14 085 464 B   (mod v0.121.2-0.2026…-3d0a1d61)
+#   default flags,  tagged ...... 4a38f394…  14 085 440 B   (mod v0.121.99)
+#   -trimpath -buildvcs=false ... 7ffcdf1d…  14 064 574 B   IDENTICAL both ways
+#
+# `-buildvcs=false` removes the stamp — nothing in this repo reads it (no `ReadBuildInfo` caller,
+# verified) and the version comes from the explicit ldflag below, which is where it belongs.
+# `-trimpath` removes absolute build paths, so a rebuild from a different checkout directory also
+# matches. Neither is a sequencing trick: the property no longer depends on WHEN the build happens.
+#
+# CGO is deliberately left at its default. publish-agent.sh's fallback build used to force
+# CGO_ENABLED=0 and therefore produced a DIFFERENT binary (13 990 236 B, 74 KB smaller) for the same
+# version — one version name, two binaries, by whichever entry point was used. Both now build the
+# same way; if that ever has to change, change it in BOTH or the guarantee is gone.
+go build -trimpath -buildvcs=false -ldflags "-X main.version=$VERSION" -o "$BIN" ./cmd/felhom-agent \
     || die "go build failed"
 built_ver="$("$BIN" --version 2>/dev/null | awk '{print $2}')"
 [[ "$built_ver" == "$VERSION" ]] \
@@ -82,10 +100,27 @@ built_ver="$("$BIN" --version 2>/dev/null | awk '{print $2}')"
 BUILT_SHA="$(sha256sum "$BIN" | awk '{print $1}')"
 log "built ok: sha256 $BUILT_SHA"
 
-# ── 4. Tag (before publishing, so a published version always has a tag) ─────────────────────────
-# Order matters in this direction only: a tag with no package is caught by
-# scripts/check-published-versions.py on the next CI run; a package with no tag is invisible to it,
+# ── 4. Tag LOCALLY (the push comes after the publish — see step 6) ──────────────────────────────
+#
+# THE ORDER CHANGED, AND ONLY THE PUSH MOVED (R-188, 2026-08-03).
+#
+# It used to be tag → push tag → publish, and the reason written here was sound: a tag with no
+# package is caught by scripts/check-published-versions.py, a package with no tag is invisible to it,
 # because the Gitea package LISTING api needs a token the gate does not have.
+#
+# What that reasoning missed is that the tag PUSH is what wakes CI (`on: [push]`), so the gate ran in
+# the seconds between the tag becoming visible and the package existing — and correctly failed. Every
+# correct release had roughly a coin-flip chance of emailing the operator a failure for a release
+# that worked. Measured across two releases in one session: runs 12/13 (v0.121.0) and 17/18
+# (v0.121.1), same sha each time, opposite results. R-168 made that mail the thing that cannot be
+# missed; a mail that is wrong half the time is one you stop reading, and then the real one goes too.
+#
+# So the tag is still created HERE, before anything is published — the build and the tag still
+# describe the same commit, and a failed publish leaves a purely local tag that never misled anyone.
+# It simply becomes VISIBLE (to CI, and to any installer fetching raw/tag/…) only once the package
+# is downloadable. The invariant the old order protected is not traded away: it is asserted directly
+# by the gate's new converse probe (a published version with no tag FAILS), so both directions are
+# now checked rather than one being arranged for.
 log "tagging $TAG at $(git rev-parse --short HEAD) …"
 git tag -a "$TAG" -m "agent $TAG
 
@@ -94,7 +129,6 @@ sha256 of the published binary: $BUILT_SHA
 
 felhom-host-install.sh fetches this version's config files from raw/tag/$TAG/configs/,
 so this tag is part of the released artifact, not a bookmark (R-183)."
-git push origin "$TAG" || die "tag push failed — refusing to publish an untagged version"
 
 # ── 5. Publish (the existing script; deliberately not reimplemented) ────────────────────────────
 log "publishing …"
@@ -104,9 +138,48 @@ log "publishing …"
 # R-115 exists to make unforgettable was, on its first use, unrunnable. The mode bit is restored in
 # the same commit; this line makes the release independent of it, because a file mode is exactly the
 # kind of thing that is lost again by a checkout, an archive, or a copy.
-bash "$REPO_ROOT/scripts/publish-agent.sh" "$VERSION" "$BIN" || die "publish failed"
+if ! bash "$REPO_ROOT/scripts/publish-agent.sh" "$VERSION" "$BIN"; then
+    # The tag is LOCAL-ONLY at this point, so a failed publish must not leave one behind: the next
+    # attempt would die at step 2's "tag $TAG already exists" and read as "this version is already
+    # released", which would be exactly backwards. Only remove it if nothing was in fact published —
+    # if a package DOES exist, the tag is wanted and must be pushed, not deleted.
+    now_published="$(curl -fsS -o /dev/null -w '%{http_code}' \
+        "$GITEA_BASE/api/packages/$GITEA_OWNER/generic/felhom-agent/$VERSION/felhom-agent" 2>/dev/null || true)"
+    if [[ "$now_published" == "200" ]]; then
+        log "publish reported failure but the package IS downloadable — keeping the local tag; push it with: git push origin $TAG"
+    else
+        git tag -d "$TAG" >/dev/null 2>&1 && log "removed the local-only tag $TAG so the release can be retried"
+    fi
+    die "publish failed"
+fi
 
-# ── 6. Verify by an INDEPENDENT download ────────────────────────────────────────────────────────
+# ── 6. Push the tag, now that the package exists ────────────────────────────────────────────────
+# This is the step that makes the release VISIBLE — to CI, and to every `raw/tag/v<version>/` fetch
+# the installer makes. It runs last of the two so CI can never see a tag whose package is not there.
+#
+# If it fails, the release is HALF DONE and must be said so loudly: the package is published and the
+# tag exists only in this clone, which is precisely the orphan the gate's converse probe now catches.
+# The recovery is one line and it is printed rather than described.
+log "pushing $TAG …"
+if ! git push origin "$TAG"; then
+    cat >&2 <<EOF
+
+  RELEASE HALF DONE — the package is PUBLISHED and its tag is NOT pushed.
+
+    version : $VERSION
+    sha256  : $BUILT_SHA
+
+  The tag exists in this clone only. Nothing installs from an untagged version (the installer
+  fetches this version's configs from raw/tag/$TAG/), and scripts/check-published-versions.py will
+  FAIL on it as a published version with no tag. Finish the release with:
+
+      git push origin $TAG
+
+EOF
+    die "tag push failed after a successful publish — see above"
+fi
+
+# ── 7. Verify by an INDEPENDENT download ────────────────────────────────────────────────────────
 # The publish step's own success is not proof: it reports on its own write. What matters is that a
 # box can now GET the bytes and that they are the bytes that were built. This is the same
 # presence-is-not-success rule the project earned twice — a step that says "done" and a fetch that

scripts/retention-policy.json

@@ -0,0 +1,44 @@
+{
+  "_comment": [
+    "THE retention number for published agent artifacts. One file, read by everything that",
+    "depends on it, because a check and the policy it enforces must read the same number from the",
+    "same place or they drift — and the drift looks like a defect in something else.",
+    "",
+    "WHAT WENT WRONG WITHOUT IT (2026-08-08/09). The registry stopped serving felhom-agent",
+    "0.120.0 and older, while scripts/check-published-versions.py demanded that EVERY git tag",
+    "still be downloadable. Both rules are individually sensible; together they are impossible.",
+    "CI went red at a commit whose own run had been green the day before, on a true finding that",
+    "no one could act on. The red will return at the next publish unless the two read one number.",
+    "",
+    "HOW THE NUMBER WAS ARRIVED AT — stated honestly, because it is weaker than it looks.",
+    "generic_versions_kept is 10 because that is what the registry demonstrably holds today",
+    "(felhom-agent 0.121.0..0.128.0 = 10 versions, queried 2026-08-09). It is an OBSERVED state,",
+    "NOT a ruling anyone has been able to locate: no register row records a package prune, R-210",
+    "is WAITING-ON-OPERATOR and says 'Nothing was deleted; this is a list, not an action', and it",
+    "concerns local Docker images rather than this registry. Container packages currently hold 19",
+    "each, so there is no uniform ten-per-package cap visible either. See R-287.",
+    "",
+    "SO THIS FILE IS A FLOOR, NOT A LICENCE. It says: CI may assume nothing older than the newest",
+    "N generic versions is still downloadable. It does NOT authorise deleting anything, and the",
+    "operator should confirm or replace the number — at which point this file changes and both",
+    "readers follow it in the same commit.",
+    "",
+    "THE DEEPER BOUND, recorded so a future session does not have to re-derive it: the principled",
+    "limit is the hub's vouched min_agent floor (0.127.0 on 2026-08-09). Nothing can install an",
+    "agent below it — the hub refuses to vouch one and boxes update to the floor — so a released",
+    "version below the floor being un-downloadable costs nothing real. Bounding on the floor would",
+    "be better than bounding on a count, and it needs the gate to read the hub, which is network",
+    "the gate does not have today. Filed as the follow-up in R-287.",
+    "",
+    "NEVER retire a git TAG to satisfy this. felhom-host-install.sh fetches an agent's config",
+    "files from raw/tag/v<version>/configs/, so deleting a tag retires the ability to install that",
+    "version at all — a strictly worse act than an un-downloadable binary."
+  ],
+  "generic_versions_kept": 10,
+  "readers": [
+    "scripts/check-published-versions.py — bounds its assertion to the newest N versions",
+    "documentation/runbooks/registry-retention.md (felhom.eu) — the prune procedure"
+  ],
+  "recorded": "2026-08-09",
+  "recorded_by": "CC, from the registry's observed state; NOT from a located operator ruling"
+}