v0.145.0 code: the OS wrapper repairs dpkg's update journal by itself after a power cut (R-876); restore-test first check 30 min after start (R-874); neutral "sent late" text (R-875)

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

.gitignore

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

CHANGELOG.md

@@ -1,3 +1,232 @@
+## v0.144.1 — a killed pass really keeps its report: the wrapper survives a dead reader; the agent looks again every 5 minutes (R-868, measured live) (2026-10-05)
+
+Released by `scripts/release-agent.sh`: binary sha256 `6ccd521d47e64999017e8eb5bc613d724543cfdc5ef9b13bcae9e3ea8c53b8f3`,
+config bundle sha256 `e89a9ddfb767e177f8874d56f3dcd3bfd47409d157ff830d362653333bf815e8`. The wrapper changed again:
+a box needs the signed `agent_update` AND the signed `agent_config_update`.
+
+- **Found live on demo-hp 2026-10-05 05:45 UTC with v0.144.0** (the night's A5 shape: kill -9 of the pass and the
+  daemon while apt-get ran): apt finished all 13 packages, but the wrapper's next log line went to a stderr pipe no
+  process read any more → `BrokenPipeError` → the wrapper died before it saved its report copy (journal: `PLAN
+  upgrade=13`, then nothing; no copy; the hub got nothing). v0.144.0's mechanism was right and never reached.
+  `Runner.log` and the final `OSAPPLY-REPORT` line now survive a dead reader (the journal still gets every line).
+  Test `AgentDiesMidPass` drives the REAL `log()` into a pipe that breaks while apt-get runs.
+- **Also found live:** the restarted daemon looked for kept copies ~7 s before the orphaned wrapper wrote one. The
+  daemon now looks at start and every 5 minutes (`Leg.SendUnsentLoop`); `TestR868_ACopyWrittenAfterTheStartIsSentByTheLoop`.
+- Red-proofs: `felhom.eu/documentation/audits/night-fixes-2026-10-05/partD/r868-brokenpipe-red-proof.txt`.
+- A second agent release in one session, against "one release per repo": recorded as `09` decision 108 (operator may
+  reverse) — the alternative was to ship a fix proven not to work.
+
+## v0.144.0 — R8 measures the real download; an OS pass reports even when its agent was killed; the debug pass runs with the hub away (R-865, R-868, R-866) (2026-10-05)
+
+Released by `scripts/release-agent.sh`: binary sha256 `f18093c3466749ec4cd47f83f97a401160a24bad1e704f1183051adad14db928`,
+config bundle `felhom-config-bundle.json` sha256 `6acf42fe46df5223384d767801cb2bf73238ba4dab82debb7811ca2f790591d8`.
+The wrapper `felhom-os-apply` changed, so a box needs BOTH the signed `agent_update` and the signed `agent_config_update`.
+
+- **R-865.** `download_bytes` runs `apt-get --print-uris` WITHOUT `-s`: with `-s` apt prints the simulation and no URI
+  list, so R8 summed 0 B and only its 500 MB floor ever applied. `--print-uris` alone downloads nothing (measured on
+  9202: the archive cache and the versions unchanged). The test fake now answers like real apt (with `-s`: no URIs),
+  and `test_R8_counts_the_real_download` / `test_download_bytes_never_simulates` pin it.
+- **R-868.** The wrapper writes every apply pass's report to `<plan dir>/report-<run>-<layer>-apply.json` before it
+  prints it (root writes into the agent's dir: the dir opened O_NOFOLLOW and checked to be the agent's own, the file
+  created O_EXCL|O_NOFOLLOW, 0600, handed to the agent). The plan now carries `run_id`, `trigger`, `ring`, echoed in
+  the report. The agent deletes the copy once the hub has the report; a copy left on disk (the agent was killed, or
+  the hub was away) is sent at the agent's start and before every pass (`Leg.SendUnsent`), then deleted. A pass lock
+  (flock on `pass.lock`, across the daemon and a selftest) keeps the sender off a pass that is still running.
+- **R-866.** The daemon saves the hub's newest os_update block (`os-update-block.json`); `--selftest=os-update` uses it
+  when the hub cannot be reached and says so in its header (`block=SAVED(<time>; hub unreachable: …)`); with no hub
+  and nothing saved it does not run.
+- Tests: `configs/test_felhom_os_apply.py` (UnsentReport, SaveReportOnDisk — real files, symlink cases), Go
+  `TestR868_*`, `TestR866_*`. Red-proofs: `felhom.eu/documentation/audits/night-fixes-2026-10-05/part{C,D}/`.
+
+## v0.143.0 — the config bundle: a signed route for a box's root-owned files (R-840, decision 96) (2026-10-04)
+
+Released by `scripts/release-agent.sh`: binary sha256 `41c0d3060013dfda795262147454248149bee0888c0935170fdb85de6e7a35da`,
+config bundle `felhom-config-bundle.json` sha256 `8d7273cf5313ef62b867cb6f831c631923a436452d6f90b8ff7f0771170396ba`.
+
+- **The bundle.** Every root-owned file the installer's step 5 writes (sudoers ×2, the five wrappers, the crash guard
+  and its units, the agent and rollback units, the start-limit drop-in, the mgmt watchdog, the OOB belt's files) as ONE
+  reproducible JSON file, built by `scripts/build-config-bundle.py` from `BUNDLE_FILES` in `configs/felhom-os-apply`
+  (one table) and published beside the binary. The installer (1.31.0) installs the same file.
+- **The route.** A signed `agent_config_update` {agent_version, bundle_sha256} (`felhom-opsign -op agent_config_update
+  -bundle-sha256 …`). The agent is the courier (downloads, checks the sha, hands over); `felhom-os-apply` mode `bundle`
+  verifies it ITSELF: the operator signature against the root-owned `/etc/felhom/operator-signers` (or, when that file
+  is missing, ONLY the installer's pinned key, after which it creates the file with exactly that key), the host binding,
+  the window, its own nonce; the bundle sha; every path in `BUNDLE_FILES` (R16) and never a trust file (R17); every
+  content check before the first write (visudo, sh/bash -n, python, unit sections, the RuntimeDirectory guard, User=,
+  nft -c, and that the route itself survives). Atomic per file, previous copies kept under
+  `/var/lib/felhom-os-apply/bundle-prev/`; a self-check after (visudo -c, `sudo -l` lists the route, the new wrapper's
+  `--self-check`, the self-update wrapper's usage, the crash guard's status = kernel.panic); any failure puts every
+  previous copy back. A newly installed crash guard is started (`enable --now`: kernel.panic for this boot, no reboot).
+  Record `/etc/felhom/config-bundle.json`; the agent reports it as `system.config_bundle`, the facts mode adds drift.
+- **Bootstrap.** A box whose `felhom-os-apply` predates 0.143.0 cannot take the first bundle by the route (nothing on it
+  can write a root file from a signed job): `felhom.eu/scripts/felhom-bundle-bootstrap.sh` is the one by-hand step.
+- **`build-golden.sh` 3.2.0** (not part of the binary): `GOLDEN_GUEST_PKGS` brings the template to exactly the
+  approved guest release (only installed packages, never newer, never a removal or a new package) and prints the
+  first-night count.
+- Tests: `configs/test_felhom_config_bundle.py` (43; 22 of 22 mutants red), `internal/osupdate/bundle_test.go`,
+  `internal/hub/bundle_record_test.go`. Live: `felhom.eu/documentation/audits/r840-config-bundle-2026-10-04/partB/`.
+
+## v0.142.1 — a Docker step no longer leaves the controller and traefik blind (R-858, `09` decision 95)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.142.1` (`4950030`), sha256
+> `003f882a59abfc10021a1f97a4744ab78ab1e916b1392dcef132e7067f3c62bd`, verified by download. Not vouched at release time.
+
+**MinAgent impact:** none. A same-day patch release, by the operator's ruling 95 after a live incident.
+
+- **The incident.** v0.142.0's Docker step on demo-felhom (14:13 UTC) restarted dockerd, which recreates
+  `/run/docker.sock`. live-restore kept every container running — including `felhom-controller` and `traefik`, which
+  bind-mount the socket FILE and so kept the deleted inode. The controller could not reach Docker for 1 h 44 min (hub:
+  DOWN, "docker not reachable"); its own health check stayed "healthy", so the step's health rule PASSED.
+- **The fix.** After a Docker step that installed something, the wrapper restarts ONLY the containers that mount
+  `/var/run/docker.sock` or `/run/docker.sock` (`os-apply: SOCKET-USERS restarted=…`; the apps and the engine untouched).
+  The guest health reading gains `controller_docker_ok` (`docker exec felhom-controller docker version`), and the health
+  rule fails when it is false — the consequence, not the mechanism.
+- Proven live on demo-hp BEFORE the release (signed undo to 29.7.2): the two restarted, guest / controller / traefik on
+  the same socket inode, healthy. Red-proofs: `felhom.eu/documentation/audits/os-docker-crash-2026-10-04/partE-incident/`.
+
+## v0.142.0 — the Docker engine slow lane, the version report, the crash guard (`11` §5.8, §5.9; `09` decisions 87–89)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.142.0` (`b1746c2`), sha256
+> `7beb32224d6495e9561acfd3ad8a48393a799520f196080011cb27fceb6d1de6`, verified by download. Not vouched at release time.
+
+**MinAgent impact:** none. **Needs hub v0.132.0** for the System page, the Docker approval and the crash events; an older
+hub stores the new `system` stanza unread. **Needs the new root files** on an installed box (R-840): the wrapper,
+`/etc/felhom/os-trust.json`, `/etc/felhom/operator-signers` and the crash guard — the installer 1.30.0 writes them; the
+demo boxes got them by hand.
+
+- **Docker `live-restore` ON** (decision 87). Wrapper mode `live-restore-on`: merge `"live-restore": true` into the
+  guest's `/etc/docker/daemon.json` and `systemctl reload docker` — never a restart (R-835). An invalid daemon.json is
+  left alone (R16); a reload that does not enable it puts the old file back. The leg runs it once before a Docker step;
+  `--selftest=live-restore -vmid N` runs it by hand. Measured: demo-hp 24 containers, demo-felhom 5 — the same ids after.
+- **The Docker engine slow lane** (`11` §5.8). Wrapper layer `docker`, lane `slow` only, the six Docker packages only,
+  origin `Docker CE` only (R2; a Docker package in a fast-lane plan is refused). **R3 — the wrapper checks the authority
+  itself**, never the agent's config: a ring-1 step or ANY undo needs a signed `os_docker_step` it verifies with
+  `ssh-keygen -Y verify` against the ROOT-owned `/etc/felhom/operator-signers` (namespace `felhom-op-v1`, the blob's
+  `key_id`), bound to `/etc/felhom/os-trust.json` `host_id`, inside its time window, never replayed (a root-owned nonce
+  file), with exactly the signed packages and undo flag; an unsigned ring-0 step needs that file's
+  `"ring0_slow_lane": true` (the demo boxes only, set by hand). **R15:** live-restore must be on. An undo may downgrade
+  (`--allow-downgrades`) only inside a signed job. The leg: ring 0 runs the Docker step at night after a healthy guest
+  and host step (`select pending-docker`); ring 1 never does — only `DockerStepExecutor` (signed job, heavy-op gate).
+  **Health:** the guest rule + every container running at the start has the SAME id after + the engine reports the
+  installed version; a changed id is `health_failed`. Measured ring 0: 29.7.x → 29.8.2 on both demo boxes, every id kept.
+- **The version report** (R-852, decision 89). Wrapper mode `facts` (read-only): host Debian, running and next-boot
+  kernel (`next_entry` > saved default > newest installed, by dpkg order), held packages (R-848), kernel taint (oops,
+  warn), `kernel.panic`, the crash guard state; guest Debian, Docker engine, containerd, live-restore. The host report
+  gains `system {pve_version, kernel_version, vmid, facts, facts_error}`, read at most every 10 min (~2 s);
+  `--selftest=os-facts -vmid N`. A value nobody could read is `unknown`.
+- **R-849:** the guest is scanned for "restart needed" on every pass too, so a guest restart clears it.
+- **The crash guard** (decision 88, R-851): `configs/felhom-crash-guard` + `felhom-crash-guard.service` (early boot;
+  its ExecStop writes a clean-stop marker) + an hourly re-arm timer + `/etc/felhom/crash-guard.conf`. A boot without
+  the marker followed an unclean stop (a crash, a power cut or a hard reset — pstore saved nothing for a real panic on
+  demo-hp, so they cannot be told apart). Armed: `kernel.panic = 10`. After the 2nd unclean boot within 60 min it
+  TRIPS (`kernel.panic = 0`), so the 3rd crash within the hour leaves the box off; it re-arms after 24 h of normal
+  running or `felhom-crash-guard rearm`. State in `/var/lib/felhom-crash-guard/state.json` (0644; read by facts).
+- **After the tag (main only, not shipped to boxes): `configs/build-golden.sh` 3.1.0** — the golden's `daemon.json`
+  carries `"live-restore": true` with a fail-closed assertion, and `GOLDEN_DOCKER_PKGS` pins the approved Docker engine
+  set (all six `name=version`); without it the bake log warns that the set is the newest, not an approved one.
+- Tests: wrapper 76 (DockerLane, LiveRestore, Facts, RealSignatureCheck with a throwaway key), crash guard 9, Go leg +
+  executor; red-proofs `felhom.eu/documentation/audits/os-docker-crash-2026-10-04/partB/agent-redproofs.txt` (17 caught).
+
+## v0.141.1 — "reboot needed" is true on the host (found live on demo-felhom, 2026-10-04)
+
+> **RELEASED 2026-10-04** by `scripts/release-agent.sh` — tag `v0.141.1` (`a6bc3f1`), sha256
+> `b712f577099fd2d374f648df1e825874821302fe1b46e93c7b4b70044fbe84b5`, verified by download. Not vouched at release time.
+
+**MinAgent impact:** none. **Pairs with hub v0.131.1** (reads `reboot_scanned`); an older hub ignores the field.
+
+A patch release in the same session as v0.141.0 — a deliberate exception to "one release per repo": v0.141.0's host
+"reboot needed" was wrong in two ways, and it feeds an operator alarm.
+- **The scan hid `lxc-start`.** The host scan skipped every process whose cgroup line contains `lxc`, to leave out the
+  guests' own processes. `lxc-start` lives in `0::/lxc.monitor/<vmid>`, so it was skipped too. Measured: after a
+  108-package host pass (libc6 included) `lxc-start` mapped 20 deleted files and the report said `reboot_needed:
+  false`. The pattern is now `:/lxc/` (`RESTART_SKIP_CGROUP`), pinned by a test that runs `grep` against the measured
+  cgroup lines.
+- **A reboot never cleared it.** v0.141.0 scanned only after an install (R-845). The host now scans on EVERY pass (it
+  is local, no `pct exec`); the guest still scans only after an install. The report carries `reboot_scanned`.
+- Red-proofs: `felhom.eu/documentation/audits/os-host-lane-2026-10-04/partB/live-defects-redproofs.txt`.
+
+## 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

CONTEXT.md

@@ -1,5 +1,13 @@
 # CONTEXT — felhom-agent working state
 
+> **2026-10-04 night — v0.143.0 RELEASED + vouched (R-840, decision 96): the config bundle.** `felhom-os-apply` mode
+> `bundle` (signed `agent_config_update`, verified by the wrapper itself; trust files never bundle paths) +
+> `--install-bundle` (installer 1.31.0); `BUNDLE_FILES` is the one table; `scripts/build-config-bundle.py`;
+> `release-agent.sh` publishes it. A box whose `felhom-os-apply` predates 0.143.0 needs ONE by-hand bootstrap
+> (`felhom.eu/scripts/felhom-bundle-bootstrap.sh`) — done on both demo boxes; Tester 2 waits for the operator (R-862).
+> Both demo boxes: agent 0.143.0, bundle 0.143.0 (record `/etc/felhom/config-bundle.json`). R-861 found: the sudoers is
+> root-equivalent. `build-golden.sh` 3.2.0 (`GOLDEN_GUEST_PKGS`). Runbook `felhom.eu/documentation/runbooks/config-bundle.md`.
+
 
 > **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`

REPORT.md

@@ -1,12 +1,19 @@
-# REPORT — 2026-09-30: v0.138.0 (R-727)
+# REPORT — agent v0.144.0 + v0.144.1 (2026-10-05): the night's fixes
 
-Full session report: `felhom.eu/REPORT-fixes-first-tester-2026-09-30.md`.
+Brief: the 2026-10-05 night-fixes brief (operator), Parts C, D, E. Full session report:
+`felhom.eu/REPORT-night-fixes-2026-10-05.md`. Architecture read: `11-os-updates.md` (§5.4.1 R8, §8.1–8.3).
 
-- **Measured:** a PBS archive carries its key FINGERPRINT (PVE content `encrypted`), not a host id; the storage
-  carries its own (`GET /storage` → `encryption-key`). The restore test now skips an archive written with another
-  key and logs it by name; an unencrypted storage is not filtered; a failed storage read is UNKNOWN.
-- Tests `TestR727_*`; red-proof RP39 (the skip removed → the 2026-09-16 archive of an earlier box is picked).
-- Released by `release-agent.sh` (tag `v0.138.0`, sha256 `55916026…8195`, verified by download); **not vouched**.
-  Delivered by signed `agent_update` jobs to `demo-hp-bb76ea` and `demo-felhom-8363b5` (both committed within 340 s);
-  `-selftest=restore-test-due` on both reads each tier normally on 0.138.0.
-- ep0 (decision 51): the three drill archives in `tester-1`'s namespace removed; other namespaces byte-identical.
+| Row | Fix | Proof |
+|---|---|---|
+| R-865 | R8: `--print-uris` WITHOUT `-s` (with `-s` apt lists no URIs → 0 B) | fake answers like real apt (verbatim 9202 output); red-proof; live: the installed wrapper read 12 802 456 B for 13 pending upgrades on demo-hp |
+| R-868 | the wrapper keeps its apply report beside the plan; the agent sends kept copies (start + every 5 min) and deletes them; pass lock (flock) | v0.144.0 measured NOT to work live (the wrapper died on a broken stderr pipe); v0.144.1: survives a dead reader + the 5-min look; live A5 shape on demo-hp → ONE `applied` report (13 packages) at the hub |
+| R-866 | the daemon saves the hub's block; the selftest uses it with the hub away and says so | live on demo-felhom with the hub blackholed: `block=SAVED(…)`, pass ran; its kept reports reached the hub at the next start |
+
+Released by `scripts/release-agent.sh`: v0.144.0 (`f18093c3…`, bundle `6acf42fe…`) and v0.144.1 (`6ccd521d…`, bundle
+`e89a9ddf…`), both verified by download. Delivered by signed `agent_update` + `agent_config_update` to demo-hp,
+demo-felhom and tester-1 (71/71 capability probe after each bundle). Vouched: agent 0.144.1, golden 0.294.0,
+min_agent 0.131.0. A second release in one session is `09` decision 108.
+
+**Found, not fixed: R-876 (P2)** — after a power cut mid-update (Part E, demo-hp) `dpkg --audit` is clean but dpkg's
+update journal is not; `repair()` skips, every pass fails until `dpkg --configure -a` by hand. Next agent release.
+Also R-875 (P4): the kept-report reason text is wrong for the hub-away case.

REUSE.md

@@ -15,6 +15,10 @@
 | `SudoHostOps.run` | internal/storage/hostops.go | `run(ctx, name, args...) error` | allowlisted exec with stderr-wrapped error | Every arg pre-validated via validate.go before this is called |
 | `Prober.Probe` | internal/capability/probe.go | `Probe(ctx) []Status` | live sudo-policy capability check (`sudo -n -l --`) | Needs a DIRECT runner (never the sudo-prefixing one — double-sudo); never executes probed cmds. v0.86.0: config-gated caps (`Capability.GatedBy` + `Prober.GateActive`) report `inactive`/"disabled by configuration" ONLY when healthy — broken plumbing stays degraded; the pbsdr-* gate answers from `pbsdr.Manager.DRConfigured` (marker-backed across restarts) |
 | `stageTemp` | internal/localapi/intermediary.go | `stageTemp(pattern, content) (path, err)` | random-named temp before a root `install` (audit B1) | Fixed /tmp names are a TOCTOU — sudoers globs expect `/tmp/felhom-*-*.ext` |
+| `BUNDLE_FILES` + `Bundle` (mode `bundle`, `--install-bundle`) | configs/felhom-os-apply | the ONE table of root-owned paths + the installer of them | ANY new root-owned file the installer writes (sudoers line, wrapper, unit) — add it to the table, never a new installer fetch (R-840) | The builder (`scripts/build-config-bundle.py`) and the installer read the same table; `test_every_root_file_the_installer_writes_is_in_the_bundle` fails on a path the bundle lacks. Trust files (`/etc/felhom/os-trust.json`, `operator-signers`) are NEVER bundle paths (R17) |
+| `osupdate.ConfigUpdateExecutor` | internal/osupdate/bundle.go | signed op `agent_config_update` {agent_version, bundle_sha256} | delivering the bundle to an installed box | a courier only: the root wrapper re-verifies signature, host, nonce and sha itself |
+| `osupdate.Leg.SendUnsent` / `lockPass` (v0.144.0, R-868) | internal/osupdate/unsent.go | `(ctx) int` | an OS-pass report the agent never sent (killed mid-pass): the wrapper keeps `report-<run>-<layer>-apply.json` beside the plan; the agent deletes it once the hub has it | any new caller that runs an apply pass must hold `lockPass` (flock, across processes) — the sender must never take a running pass's copy |
+| `osupdate.LoadSavedBlock` (v0.144.0, R-866) | internal/osupdate/leg.go | `(planDir) (block, savedAt, ok)` | the hub's newest os_update block as the daemon last received it (`os-update-block.json`) | the debug pass uses it ONLY when the hub cannot be reached, and says so in its header; no saved block → no pass |
 | `guesthook.InstallSnippet` / `Register` | internal/guesthook/install.go | `InstallSnippet(ctx, runner) error` | pre-start self-heal hook install (C1 net) | Same random-temp+install pattern; snippet delegates to the agent binary (no shell logic). Issues `mkdir -p /var/lib/vz/snippets` FIRST (v0.63.0, B2 — fresh boxes lack the dir; sudoers grants exactly that argv) |
 
 ### Disk / format safety (role gates, durable IDs, format guards)

cmd/felhom-agent/main.go

@@ -44,6 +44,7 @@ import (
 	"gitea.dooplex.hu/admin/felhom-agent/internal/localapi"
 	applog "gitea.dooplex.hu/admin/felhom-agent/internal/log"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/mgmtplane"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/osupdate"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/pbs"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/pbsdr"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/poke"
@@ -242,6 +243,12 @@ 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 "os-facts":
+		os.Exit(runSelftestFacts(context.Background(), cfg, logger, vmid))
+	case "live-restore":
+		os.Exit(runSelftestLiveRestore(context.Background(), cfg, logger, vmid))
 	case "pbs-verify":
 		os.Exit(runSelftestPBSVerify(context.Background(), cfg, logger))
 	case "lanresolver":
@@ -782,7 +789,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
@@ -839,6 +846,11 @@ 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)
+	collector.SetSystemReporter(&factsReporter{leg: osLeg, guest: firstGuest(px)}) // R-852: the versions
+	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 {
@@ -856,6 +868,12 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	logger.Info("felhom-agent daemon starting",
 		"version", version, "host_id", cfg.Hub.HostID, "hub_url", cfg.Hub.URL,
 		"interval_s", hcfg.PollSeconds) // hub key intentionally not logged
+	// R-868 (v0.144.0): an OS pass whose agent was killed kept its report on disk — send it now (a pass that starts
+	// first sends it itself; the pass lock keeps the two apart).
+	// v0.144.1: and again every 5 minutes — the wrapper of a killed pass can finish AFTER the restart (measured).
+	go osLeg.SendUnsentLoop(ctx, 5*time.Minute, func(n int) {
+		logger.Info("osupdate: sent kept report(s)", "count", n)
+	})
 
 	// Reconcile (slice 4) runs alongside the hub loop, sharing the per-guest queue
 	// (doc 03 §10). At slice 4 the desired-state provider is empty (no hub serving
@@ -1080,7 +1098,27 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 	// recurring clobber before it locks the box out. Port 22 for G1 (H1 passes the felhom-sshd port).
 	collector.SetMgmtPlaneReporter(mgmtplane.NewReporter(mgmtplane.DefaultPrivsepDir, mgmtplane.DefaultHealMarker, mgmtplane.DefaultSshdPort))
 
-	jobsRunner := signedjobs.NewRunner(client, gate, signedjobs.ExecutorChain{wipeExec, decommExec, updateExec}, cfg.Hub.HostID, logger)
+	// Agent v0.142.0: a signed Docker engine step (`11` §5.8) — ring 1 and every undo; under the heavy-op gate.
+	dockerExec := osupdate.DockerStepExecutor{Leg: osLeg, Guest: firstGuest(px),
+		Gate: func(ctx context.Context) (func(), error) {
+			release, busy, ok := heavyOps.TryAcquire("os-docker-step")
+			if !ok {
+				return nil, fmt.Errorf("busy: %s", busy)
+			}
+			return release, nil
+		}}
+	// Agent v0.143.0 (R-840): the config bundle — the box's root-owned files by a signed job; the wrapper verifies it.
+	bundleExec := osupdate.ConfigUpdateExecutor{Leg: osLeg, URLTemplate: suCfg.URLTemplate, Username: suCfg.Username, Token: suCfg.Token,
+		// The capability probe confirms from the agent's side: `sudo -l` lists every command the new sudoers grants.
+		AfterInstall: func(ctx context.Context) {
+			ok, total, degraded := capability.Summarize(probeAll(ctx))
+			names := make([]string, 0, len(degraded))
+			for _, d := range degraded {
+				names = append(names, d.Name)
+			}
+			logger.Warn("osupdate: capability probe after the config bundle", "ok", ok, "total", total, "degraded", strings.Join(names, ","))
+		}}
+	jobsRunner := signedjobs.NewRunner(client, gate, signedjobs.ExecutorChain{wipeExec, decommExec, updateExec, dockerExec, bundleExec}, cfg.Hub.HostID, logger)
 	loop.SetEnvelopeObserver(hub.MultiObserver(desiredSyncer, jobsRunner))
 
 	// Controller-driven escrow ceremony (v0.88.0): static config facts + the LATE-BOUND DR gate —
@@ -1112,6 +1150,17 @@ func runDaemon(cfg config.Config, logger *slog.Logger, logRing *applog.Ring) int
 		},
 	}
 	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()
 	}
@@ -2008,7 +2057,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.
@@ -3478,8 +3527,237 @@ 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 "os-facts", "live-restore": // agent v0.142.0
+		f.mode = v
+	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|os-facts|live-restore)", 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)
+	blk, source, ok := selftestOSBlock(ctx, client, leg.PlanDir)
+	if !ok {
+		fmt.Fprintln(os.Stderr, "selftest=os-update:", source)
+		return 1
+	}
+	leg.SetBlock(blk)
+	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 block=%s ===\n",
+		version, vmid, b.Ring, b.Enabled, b.Release != nil, b.HostRelease != nil, leg.Appliance, source)
+	start := time.Now()
+	pass := leg.Run(ctx, vmid, "debug")
+	worst := pass.Guest
+	for i, rep := range []osupdate.Report{pass.Guest, pass.Host, pass.Docker} {
+		if rep.Layer == "" {
+			fmt.Printf("  %s step: skipped (see the log line above)\n", []string{"guest", "host", "docker"}[i])
+			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, "docker_engine": rep.DockerEngine, "authority": rep.Authority})
+		if !(rep.Outcome == "applied" || rep.Outcome == "nothing" || rep.Outcome == "inventory" || rep.Outcome == "skipped") {
+			worst = rep
+		}
+	}
+	fmt.Printf("  pass took %s\n", time.Since(start).Round(100*time.Millisecond))
+	switch worst.Outcome {
+	case "applied", "nothing", "inventory", "skipped":
+		return 0
+	}
+	return 1
+}
+
+// selftestOSBlock is the debug pass's os_update block (R-866, v0.144.0): the hub's, fetched fresh; when the hub cannot
+// be reached, the block the daemon last saved — named in the selftest's first line, so a pass with the hub away can
+// be exercised by hand (the daemon's own leg already ran from its last block; the selftest stopped). No saved block
+// and no hub → not run (ok=false), never a guessed block.
+func selftestOSBlock(ctx context.Context, f interface {
+	FetchDesiredState(context.Context) (*hub.DesiredStateResponse, error)
+}, planDir string) (*hub.WireOSUpdate, string, bool) {
+	resp, err := f.FetchDesiredState(ctx)
+	if err == nil {
+		return resp.DesiredState.OSUpdate, "hub", true
+	}
+	saved, at, ok := osupdate.LoadSavedBlock(planDir)
+	if !ok {
+		return nil, fmt.Sprintf("desired state: %v — and no saved block (the daemon saves one when the hub sends it)", err), false
+	}
+	return saved, fmt.Sprintf("SAVED(%s; hub unreachable: %v)", at.UTC().Format(time.RFC3339), err), true
+}
+
+// runSelftestFacts prints the versions the host report carries (R-852, agent v0.142.0) — read-only.
+//
+//	sudo -u felhom-agent felhom-agent --config … --selftest=os-facts -vmid 9201
+func runSelftestFacts(ctx context.Context, cfg config.Config, logger *slog.Logger, vmid int) int {
+	if vmid <= 0 {
+		fmt.Fprintln(os.Stderr, "selftest=os-facts: -vmid is required")
+		return 2
+	}
+	px, _ := newProxmoxClient(cfg)
+	leg := newOSLeg(cfg, nil, px, logger)
+	start := time.Now()
+	f, err := leg.Facts(ctx, vmid)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "selftest=os-facts:", err)
+		return 1
+	}
+	var v any
+	_ = json.Unmarshal(f, &v)
+	printJSON(fmt.Sprintf("facts (vmid %d, %s)", vmid, time.Since(start).Round(100*time.Millisecond)), v)
+	return 0
+}
+
+// runSelftestLiveRestore is the ONE-TIME live-restore step (`09` decision 87) as a debug action — the night leg does
+// the same before a ring-0 Docker step. It prints the container ids before and after (they must not change).
+//
+//	sudo -u felhom-agent felhom-agent --config … --selftest=live-restore -vmid 9202
+func runSelftestLiveRestore(ctx context.Context, cfg config.Config, logger *slog.Logger, vmid int) int {
+	if vmid <= 0 {
+		fmt.Fprintln(os.Stderr, "selftest=live-restore: -vmid is required")
+		return 2
+	}
+	px, _ := newProxmoxClient(cfg)
+	leg := newOSLeg(cfg, nil, px, logger)
+	if err := leg.EnsureLiveRestore(ctx, time.Now().UTC().Format("20060102T150405Z"), vmid); err != nil {
+		fmt.Fprintln(os.Stderr, "selftest=live-restore:", err)
+		return 1
+	}
+	fmt.Println("live-restore: on (see the wrapper's LIVE-RESTORE line above for the container ids)")
+	return 0
+}
+
+// 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: customerGuests(px),
+	}
+}
+
+// customerGuests lists the running guests that bind /mnt/felhom-drives — the box's customer guest(s), the same rule the
+// OS wrapper's R10 uses. Shared by the tunnel probe, the facts read and the signed Docker step.
+func customerGuests(px *proxmox.Client) func(ctx context.Context) ([]int, error) {
+	return 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
+	}
+}
+
+// firstGuest is the single customer guest (an error when there is none).
+func firstGuest(px *proxmox.Client) func(ctx context.Context) (int, error) {
+	f := customerGuests(px)
+	return func(ctx context.Context) (int, error) {
+		v, err := f(ctx)
+		if err != nil {
+			return 0, err
+		}
+		if len(v) == 0 {
+			return 0, fmt.Errorf("no running customer guest")
+		}
+		return v[0], nil
+	}
+}
+
+// factsReporter feeds the host report's `system` stanza (R-852, agent v0.142.0) from the wrapper's read-only facts
+// mode, at most every 10 minutes (each read is ~2 s of pct exec; the host reports every 15 min).
+type factsReporter struct {
+	leg   *osupdate.Leg
+	guest func(ctx context.Context) (int, error)
+	mu    sync.Mutex
+	at    time.Time
+	vmid  int
+	facts json.RawMessage
+	err   error
+}
+
+func (f *factsReporter) SystemFacts(ctx context.Context) (int, json.RawMessage, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if !f.at.IsZero() && time.Since(f.at) < 10*time.Minute {
+		return f.vmid, f.facts, f.err
+	}
+	f.at = time.Now()
+	f.vmid, f.err = f.guest(ctx)
+	if f.err != nil {
+		f.facts = nil
+		return 0, nil, f.err
+	}
+	f.facts, f.err = f.leg.Facts(ctx, f.vmid)
+	return f.vmid, f.facts, f.err
+}

cmd/felhom-agent/r866_selftest_block_test.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/osupdate"
+)
+
+type r866Fetcher struct{ err error }
+
+func (f r866Fetcher) FetchDesiredState(context.Context) (*hub.DesiredStateResponse, error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+	r := &hub.DesiredStateResponse{}
+	r.DesiredState.OSUpdate = &hub.WireOSUpdate{Ring: 1, Enabled: true}
+	return r, nil
+}
+
+// R-866 (v0.144.0). THE NIGHT'S SHAPE (A3, Tester 1 box, hub blocked): `selftest=os-update: desired state: hub:
+// transport error … connect: invalid argument` — the debug pass could not run at all. Now it runs from the block the
+// daemon saved, and its header says so.
+// COMPANION RED-PROOF: return at once on a fetch error in selftestOSBlock → "the pass did not run from the saved block".
+func TestR866_DebugPassUsesTheSavedBlockWhenTheHubIsAway(t *testing.T) {
+	dir := t.TempDir()
+	leg := &osupdate.Leg{PlanDir: dir}
+	r := &hub.DesiredStateResponse{}
+	r.DesiredState.OSUpdate = &hub.WireOSUpdate{Ring: 0, Enabled: true}
+	leg.OnDesiredState(context.Background(), r) // the daemon received a block and saved it
+	away := r866Fetcher{err: errors.New("hub: transport error: connect: invalid argument")}
+	b, src, ok := selftestOSBlock(context.Background(), away, dir)
+	if !ok || b == nil || b.Ring != 0 {
+		t.Fatalf("the pass did not run from the saved block: ok=%v block=%+v src=%q", ok, b, src)
+	}
+	if !strings.HasPrefix(src, "SAVED(") || !strings.Contains(src, "hub unreachable") {
+		t.Fatalf("the header must say the block is the saved one: %q", src)
+	}
+	// the hub reachable: its block wins, and the header says "hub"
+	b, src, ok = selftestOSBlock(context.Background(), r866Fetcher{}, dir)
+	if !ok || b.Ring != 1 || src != "hub" {
+		t.Fatalf("hub block not used: %+v %q", b, src)
+	}
+}
+
+// No hub and nothing saved: the pass does not run on a guessed block.
+func TestR866_NoHubNoSavedBlockDoesNotRun(t *testing.T) {
+	_, why, ok := selftestOSBlock(context.Background(), r866Fetcher{err: errors.New("down")}, t.TempDir())
+	if ok || !strings.Contains(why, "no saved block") {
+		t.Fatalf("ok=%v why=%q", ok, why)
+	}
+}

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-opsign/main.go

@@ -43,7 +43,7 @@ func main() {
 
 func run() error {
 	var (
-		op        = flag.String("op", "", "op class to sign, e.g. storage_wipe | guest_destroy | decommission | agent_update")
+		op        = flag.String("op", "", "op class to sign, e.g. storage_wipe | guest_destroy | decommission | agent_update | os_docker_step | agent_config_update")
 		host      = flag.String("host", "", "target host_id (anti-retarget — the op runs ONLY on this host)")
 		guest     = flag.String("guest", "", "target guest_id (\"\" = host-scoped op)")
 		keyID     = flag.String("key-id", "", "key id of the signing key (must match a pinned agent signer)")
@@ -52,6 +52,7 @@ func run() error {
 		fstype    = flag.String("fstype", "ext4", "for storage_wipe: the filesystem to mkfs after wipe")
 		agentVer  = flag.String("agent-version", "", "for agent_update: the target agent version (e.g. 0.70.1)")
 		sha256Hex = flag.String("sha256", "", "for agent_update: the pinned lowercase-hex sha256 of the target binary")
+		bundleSHA = flag.String("bundle-sha256", "", "for agent_config_update: the pinned sha256 of felhom-config-bundle.json (R-840)")
 		keyFile   = flag.String("key", "", "operator signing key (ssh private key / sk- key handle) for ssh-keygen -Y sign")
 		ttl       = flag.Duration("ttl", 30*time.Minute, "validity window from now (issued_at..expires_at)")
 		nonce     = flag.String("nonce", "", "explicit nonce (default: a fresh 128-bit random nonce)")
@@ -95,6 +96,17 @@ func run() error {
 			}
 			pj, _ := json.Marshal(map[string]string{"version": *agentVer, "sha256": *sha256Hex})
 			params = string(pj)
+		case "agent_config_update":
+			// R-840: the box's root-owned files. The ROOT wrapper verifies this signature itself and refuses a bundle
+			// whose sha256 is not exactly this one.
+			if *agentVer == "" || *bundleSHA == "" {
+				return fmt.Errorf("agent_config_update needs -agent-version and -bundle-sha256 (the pinned bundle hash)")
+			}
+			if !isHex64(*bundleSHA) {
+				return fmt.Errorf("agent_config_update -bundle-sha256 must be 64 lowercase hex chars (got %d)", len(*bundleSHA))
+			}
+			pj, _ := json.Marshal(map[string]string{"agent_version": *agentVer, "bundle_sha256": *bundleSHA})
+			params = string(pj)
 		default:
 			params = "{}"
 		}

configs/build-golden.sh

@@ -61,7 +61,7 @@ set -euo pipefail
 
 # Script provenance — logged into every bake transcript next to the baked controller tag, so an
 # archive can always be traced to the script that produced it. Bump on any behavior change.
-GOLDEN_SCRIPT_VERSION="3.0.0"
+GOLDEN_SCRIPT_VERSION="3.2.0"
 
 VMID="${1:-9100}"
 TEMPLATE="${2:-local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst}"
@@ -112,7 +112,15 @@ for i in $(seq 1 30); do
   if pct exec "$VMID" -- getent hosts download.docker.com >/dev/null 2>&1; then break; fi
   sleep 1
 done
-pct exec "$VMID" -- bash -c '
+# v3.1.0 (`11` §5.8): GOLDEN_DOCKER_PKGS pins the APPROVED Docker engine set (the hub's newest Docker release, all six
+# "name=version"); without it the newest stable set is installed and the bake log says so.
+GOLDEN_DOCKER_PKGS="${GOLDEN_DOCKER_PKGS:-}"
+if [[ -n "$GOLDEN_DOCKER_PKGS" ]]; then
+  echo "[golden] Docker engine set PINNED to the approved release: $GOLDEN_DOCKER_PKGS"
+else
+  echo "[golden] WARNING: GOLDEN_DOCKER_PKGS not set — installing the newest stable Docker set, not an approved one"
+fi
+pct exec "$VMID" -- env GOLDEN_DOCKER_PKGS="$GOLDEN_DOCKER_PKGS" bash -c '
   set -e
   export DEBIAN_FRONTEND=noninteractive
   apt-get update -qq
@@ -122,7 +130,54 @@ pct exec "$VMID" -- bash -c '
   echo "deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian trixie stable" \
     > /etc/apt/sources.list.d/docker.list
   apt-get update -qq
+  if [ -n "$GOLDEN_DOCKER_PKGS" ]; then
+    apt-get install -y -qq $GOLDEN_DOCKER_PKGS >/dev/null
+  else
     apt-get install -y -qq docker-ce docker-ce-cli containerd.io >/dev/null
+  fi
+  dpkg-query -W containerd.io docker-buildx-plugin docker-ce docker-ce-cli docker-ce-rootless-extras docker-compose-plugin 2>/dev/null | sed "s/^/  installed: /"
+'
+# v3.2.0 (Part F of the R-840 brief, `11` §5.3): GOLDEN_GUEST_PKGS = the newest APPROVED guest release, as
+# "name=version …" (the hub's os_releases row for layer guest, IN FORCE — never a cancelled test approval). The bake
+# brings every package the template HAS to exactly that version, under felhom-os-apply's rules: never a package the
+# template lacks (--only-upgrade), never newer than approved, never a removal or a new package (a simulation is checked
+# first and the bake FAILS on either). Empty = no approved guest release in force: the template's versions stay, and
+# the box's first night installs whatever release is approved then. Either way the bake PRINTS the first-night count:
+# how many installed packages are older than the approved version (target 0).
+GOLDEN_GUEST_PKGS="${GOLDEN_GUEST_PKGS:-}"
+pct exec "$VMID" -- env GOLDEN_GUEST_PKGS="$GOLDEN_GUEST_PKGS" bash -c '
+  set -e
+  export DEBIAN_FRONTEND=noninteractive
+  if [ -z "$GOLDEN_GUEST_PKGS" ]; then
+    echo "[golden] no approved guest release given - the template versions stay; first-night count vs an approved release: n/a"
+    echo "[golden] pending Debian upgrades in the baked guest (what a FUTURE approval may bring): $(apt list --upgradable 2>/dev/null | grep -c /)"
+    exit 0
+  fi
+  want=""
+  for nv in $GOLDEN_GUEST_PKGS; do
+    n=${nv%%=*}; v=${nv#*=}
+    cur=$(dpkg-query -W -f="\${Version}" "$n" 2>/dev/null) || continue           # not in the template: never added
+    dpkg --compare-versions "$cur" lt "$v" && want="$want $n=$v"
+  done
+  if [ -n "$want" ]; then
+    sim=$(apt-get -s install --only-upgrade -o Dpkg::Options::=--force-confold $want)
+    if echo "$sim" | grep -q "^Remv "; then echo "[golden] FATAL: the approved guest set would REMOVE a package"; echo "$sim" | grep "^Remv "; exit 1; fi
+    for p in $(echo "$sim" | awk "/^Inst /{print \$2}"); do
+      dpkg-query -W "$p" >/dev/null 2>&1 || { echo "[golden] FATAL: the approved guest set would ADD $p - not in the template"; exit 1; }
+    done
+    apt-get install -y -qq --only-upgrade -o Dpkg::Options::=--force-confold -o Dpkg::Options::=--force-confdef $want >/dev/null
+    echo "[golden] approved guest release installed: $(echo $want | wc -w) package(s) brought to the approved version"
+  else
+    echo "[golden] approved guest release: the template already runs every approved version"
+  fi
+  left=0
+  for nv in $GOLDEN_GUEST_PKGS; do
+    n=${nv%%=*}; v=${nv#*=}
+    cur=$(dpkg-query -W -f="\${Version}" "$n" 2>/dev/null) || continue
+    dpkg --compare-versions "$cur" lt "$v" && { left=$((left+1)); echo "  still older: $n $cur < $v"; }
+  done
+  echo "[golden] first-night count vs the approved guest release: $left (target 0)"
+  [ "$left" -eq 0 ] || { echo "[golden] FATAL: $left package(s) stayed older than the approved release"; exit 1; }
 '
 echo "[golden] baking daemon.json: classic overlay2 driver (containerd-snapshotter OFF) + log rotation …"
 # containerd-snapshotter (Docker 28+/29 default) keeps the IMAGE content store under
@@ -135,9 +190,12 @@ echo "[golden] baking daemon.json: classic overlay2 driver (containerd-snapshott
 # layout (a container's `df /` reports the single volume, phase-0 spike). Since v3.0.0 /var/lib/docker
 # is a BIND of <volume>/docker rather than the mp0 mount itself, wired immediately below; data-root
 # still needs no override because the path is unchanged. Log caps kill the most common runaway.
+# v3.1.0: "live-restore": true (`09` decision 87) — a Docker engine update then restarts no app (`11` C5). A box made
+# from this golden never needs the agent's one-time live-restore-on step. NEVER removed by a plain restart (R-835).
 pct exec "$VMID" -- bash -c 'mkdir -p /etc/docker; cat > /etc/docker/daemon.json <<JSON
 {
   "features": { "containerd-snapshotter": false },
+  "live-restore": true,
   "log-driver": "json-file",
   "log-opts": { "max-size": "10m", "max-file": "3" }
 }
@@ -175,6 +233,8 @@ pct exec "$VMID" -- bash -c 'systemctl restart docker; sleep 3; docker run --rm
 # Guard: the image store MUST be on the data volume now. /var/lib/containerd holding the images would
 # mean containerd-snapshotter is still on (the split would leave images on the rootfs).
 pct exec "$VMID" -- bash -c 'drv=$(docker info 2>/dev/null | sed -n "s/.*Storage Driver: //p"); [ "$drv" = "overlay2" ] || { echo "[golden] FATAL: storage driver is $drv, expected overlay2 — images would not land on the data volume"; exit 1; }'
+# v3.1.0 ASSERTION: live-restore is ON in the running daemon (decision 87), or the bake fails closed.
+pct exec "$VMID" -- bash -c 'lr=$(docker info --format "{{.LiveRestoreEnabled}}" 2>/dev/null); [ "$lr" = "true" ] && echo "  live-restore: on" || { echo "[golden] FATAL: live-restore is $lr, expected true (decision 87)"; exit 1; }'
 # ASSERTION 1 (RETARGETED v3.0.0, not removed). /var/lib/docker must be a real mount — now the V-c
 # bind of <volume>/docker rather than the mp0 mount itself. Still fails closed on the same failure:
 # if the bind did not take, Docker's data-root silently sits on the OS rootfs and the golden ships

configs/crash-guard.conf

@@ -0,0 +1,8 @@
+# /etc/felhom/crash-guard.conf — read by /usr/local/sbin/felhom-crash-guard (`11` §5.9).
+# The LIMIT-th unclean stop within WINDOW_MINUTES leaves the box off. Decided by CC unattended — operator may reverse.
+LIMIT=3
+WINDOW_MINUTES=60
+# kernel.panic while armed: seconds after a crash before the kernel restarts the box.
+PANIC_SECONDS=10
+# A tripped guard re-arms after this many hours of normal running (or `felhom-crash-guard rearm`).
+REARM_HOURS=24

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-crash-guard

@@ -0,0 +1,235 @@
+#!/usr/bin/python3
+# felhom-crash-guard — a crashed host restarts by itself, but not forever (`09` decision 88, R-851, `11` §5.9).
+#
+# Install as /usr/local/sbin/felhom-crash-guard (0755 root:root), with felhom-crash-guard.service (boot / clean-stop)
+# and felhom-crash-guard-check.timer (hourly re-arm check). Python 3, standard library only.
+# Tests: configs/test_felhom_crash_guard.py (temp dirs; nothing real is touched).
+#
+# WHAT IT DOES
+#   boot        early at every boot. Was the previous boot ended CLEANLY? (the clean-stop marker exists). If not, this
+#               boot follows an UNCLEAN stop — a kernel crash, a power cut or a hard reset (they cannot be told apart
+#               on these boxes: measured 2026-10-04 on demo-hp, efi_pstore is on yet saved NOTHING for a real panic;
+#               the journal and `last` show only "no shutdown"). It records the unclean boot, counts those in the last
+#               WINDOW_MINUTES, and sets kernel.panic:
+#                 - fewer than LIMIT-1 recent unclean boots → kernel.panic = PANIC_SECONDS (a crash restarts the box);
+#                 - LIMIT-1 or more → the guard TRIPS: kernel.panic = 0, so the LIMIT-th crash within the window
+#                   leaves the box OFF (operator's own words: "if it crashes 3 times within one hour, it stays off").
+#               A tripped guard stays tripped across further boots until it re-arms.
+#   clean-stop  ExecStop of the service: writes the clean-stop marker during an orderly shutdown or reboot.
+#   check       hourly: a tripped guard re-arms after REARM_HOURS of normal running (since the trip AND since boot).
+#   rearm       the operator re-arms by hand (`felhom-crash-guard rearm`).
+#   status      prints the state.
+# The state is /var/lib/felhom-crash-guard/state.json (0644: the non-root agent reads it into its host report).
+# Before the service runs (very early boot) the kernel default kernel.panic = 0 applies, so a crash THAT early leaves
+# the box off — the safe side: a box that cannot reach userspace must not loop.
+import json
+import os
+import sys
+import time
+
+CONF = "/etc/felhom/crash-guard.conf"
+STATE_DIR = "/var/lib/felhom-crash-guard"
+DEFAULTS = {"LIMIT": 3, "WINDOW_MINUTES": 60, "PANIC_SECONDS": 10, "REARM_HOURS": 24}
+
+
+class Env:
+    """Paths and clock; tests replace them."""
+
+    def __init__(self, conf=CONF, state_dir=STATE_DIR, panic_path="/proc/sys/kernel/panic",
+                 uptime_path="/proc/uptime", boot_id_path="/proc/sys/kernel/random/boot_id"):
+        self.conf, self.state_dir = conf, state_dir
+        self.panic_path, self.uptime_path, self.boot_id_path = panic_path, uptime_path, boot_id_path
+
+    def now(self):
+        return time.time()
+
+    def log(self, line):
+        print(line, file=sys.stderr, flush=True)
+        try:
+            import subprocess
+            subprocess.run(["logger", "-t", "felhom-crash-guard", line], timeout=10)
+        except Exception:
+            pass
+
+
+def iso(t):
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(t))
+
+
+def parse_iso(s):
+    import calendar
+    return calendar.timegm(time.strptime(s, "%Y-%m-%dT%H:%M:%SZ"))
+
+
+def load_conf(env):
+    c = dict(DEFAULTS)
+    try:
+        for line in open(env.conf):
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = (x.strip() for x in line.split("=", 1))
+            if k in c and v.isdigit() and int(v) >= (1 if k != "PANIC_SECONDS" else 1):
+                c[k] = int(v)
+    except OSError:
+        pass
+    return c
+
+
+def state_path(env):
+    return os.path.join(env.state_dir, "state.json")
+
+
+def marker_path(env):
+    return os.path.join(env.state_dir, "clean-stop")
+
+
+def load_state(env):
+    try:
+        with open(state_path(env)) as f:
+            s = json.load(f)
+        return s if isinstance(s, dict) else None
+    except (OSError, ValueError):
+        return None
+
+
+def save_state(env, s):
+    os.makedirs(env.state_dir, mode=0o755, exist_ok=True)
+    tmp = state_path(env) + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(s, f, indent=2, sort_keys=True)
+        f.write("\n")
+    os.chmod(tmp, 0o644)
+    os.replace(tmp, state_path(env))
+
+
+def set_panic(env, seconds):
+    with open(env.panic_path, "w") as f:
+        f.write(f"{seconds}\n")
+
+
+def read(path, default=""):
+    try:
+        with open(path) as f:
+            return f.read().strip()
+    except OSError:
+        return default
+
+
+def summarize(s, c, now):
+    window = c["WINDOW_MINUTES"] * 60
+    times = [parse_iso(t) for t in s.get("unclean_boots", [])]
+    after = parse_iso(s["rearmed_at"]) if s.get("rearmed_at") else 0
+    # a re-arm starts a fresh window (or the next unclean boot would trip again at once); the history stays
+    s["unclean_boots_in_window"] = sum(1 for t in times if now - t <= window and t > after)
+    s["unclean_boots_24h"] = sum(1 for t in times if now - t <= 86400)
+    s["config"] = c
+    s["updated_at"] = iso(now)
+
+
+def boot(env):
+    c = load_conf(env)
+    now = env.now()
+    try:
+        up = float(read(env.uptime_path, "0").split()[0])
+    except (ValueError, IndexError):
+        up = 0.0
+    boot_at = now - up
+    prev = load_state(env)
+    first = prev is None
+    s = prev or {"version": 1, "unclean_boots": [], "tripped": False}
+    clean = os.path.exists(marker_path(env))
+    unclean = (not first) and (not clean)
+    try:
+        os.remove(marker_path(env))
+    except OSError:
+        pass
+    # keep 7 days of history (the 24 h figure and the operator's view), drop older
+    s["unclean_boots"] = [t for t in s.get("unclean_boots", []) if now - parse_iso(t) <= 7 * 86400]
+    if unclean:
+        s["unclean_boots"].append(iso(boot_at))
+    s["last_boot_at"] = iso(boot_at)
+    s["last_boot_unclean"] = unclean
+    s["boot_id"] = read(env.boot_id_path, "unknown")
+    summarize(s, c, now)
+    if not s.get("tripped") and s["unclean_boots_in_window"] >= c["LIMIT"] - 1:
+        s["tripped"], s["tripped_at"] = True, iso(now)
+        s["tripped_reason"] = (f"{s['unclean_boots_in_window']} unclean boots within {c['WINDOW_MINUTES']} minutes — "
+                               f"the next crash leaves the box off (limit {c['LIMIT']})")
+        env.log(f"crash-guard: TRIPPED: {s['tripped_reason']}")
+    panic = 0 if s.get("tripped") else c["PANIC_SECONDS"]
+    set_panic(env, panic)
+    s["kernel_panic"] = panic
+    s["armed"] = not s.get("tripped")
+    save_state(env, s)
+    env.log(f"crash-guard: boot first={first} unclean={unclean} in-window={s['unclean_boots_in_window']} "
+            f"tripped={s.get('tripped')} kernel.panic={panic}")
+    return 0
+
+
+def clean_stop(env):
+    os.makedirs(env.state_dir, mode=0o755, exist_ok=True)
+    with open(marker_path(env), "w") as f:
+        f.write(iso(env.now()) + "\n")
+    env.log("crash-guard: clean stop recorded")
+    return 0
+
+
+def rearm(env, by):
+    c = load_conf(env)
+    now = env.now()
+    s = load_state(env) or {"version": 1, "unclean_boots": []}
+    was = bool(s.get("tripped"))
+    s["tripped"] = False
+    s["armed"] = True
+    s["rearmed_at"], s["rearmed_by"] = iso(now), by
+    if was:
+        s["last_trip"] = {"at": s.get("tripped_at"), "reason": s.get("tripped_reason")}
+    s.pop("tripped_at", None)
+    s.pop("tripped_reason", None)
+    summarize(s, c, now)
+    set_panic(env, c["PANIC_SECONDS"])
+    s["kernel_panic"] = c["PANIC_SECONDS"]
+    save_state(env, s)
+    env.log(f"crash-guard: RE-ARMED by {by} (was tripped: {was}); kernel.panic={c['PANIC_SECONDS']}")
+    return 0
+
+
+def check(env):
+    c = load_conf(env)
+    now = env.now()
+    s = load_state(env)
+    if not s:
+        return 0
+    if s.get("tripped"):
+        since = max(parse_iso(s["tripped_at"]), parse_iso(s.get("last_boot_at", s["tripped_at"])))
+        if now - since >= c["REARM_HOURS"] * 3600:
+            return rearm(env, f"timer ({c['REARM_HOURS']} h of normal running)")
+    summarize(s, c, now)
+    save_state(env, s)
+    return 0
+
+
+def main(argv, env=None):
+    env = env or Env()
+    cmd = argv[1] if len(argv) == 2 else ""
+    if cmd == "boot":
+        return boot(env)
+    if cmd == "clean-stop":
+        return clean_stop(env)
+    if cmd == "check":
+        return check(env)
+    if cmd == "rearm":
+        return rearm(env, "operator")
+    if cmd == "status":
+        print(json.dumps(load_state(env), indent=2, sort_keys=True))
+        return 0
+    print("usage: felhom-crash-guard boot|clean-stop|check|rearm|status", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    if os.geteuid() != 0:
+        print("felhom-crash-guard: must run as root", file=sys.stderr)
+        sys.exit(2)
+    sys.exit(main(sys.argv))

configs/felhom-crash-guard-check.service

@@ -0,0 +1,7 @@
+# Hourly: a tripped crash guard re-arms after REARM_HOURS of normal running (felhom-crash-guard check).
+[Unit]
+Description=Felhom crash guard re-arm check
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/felhom-crash-guard check

configs/felhom-crash-guard-check.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Felhom crash guard re-arm check (hourly)
+
+[Timer]
+OnBootSec=15min
+OnUnitActiveSec=1h
+
+[Install]
+WantedBy=timers.target

configs/felhom-crash-guard.service

@@ -0,0 +1,19 @@
+# felhom-crash-guard — a crashed host restarts by itself, with a limit (`09` decision 88, R-851, `11` §5.9).
+# Starts early at boot (sets kernel.panic for THIS boot); its ExecStop writes the clean-stop marker during an orderly
+# shutdown or reboot. A boot that finds no marker followed a crash, a power cut or a hard reset.
+[Unit]
+Description=Felhom crash guard (restart after a kernel crash, with a limit)
+DefaultDependencies=no
+After=local-fs.target
+Before=sysinit.target shutdown.target
+Conflicts=shutdown.target
+RequiresMountsFor=/var/lib
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/felhom-crash-guard boot
+ExecStop=/usr/local/sbin/felhom-crash-guard clean-stop
+
+[Install]
+WantedBy=sysinit.target

configs/test_felhom_config_bundle.py

@@ -0,0 +1,545 @@
+#!/usr/bin/env python3
+"""Tests for the config bundle (R-840, `11` §5.4.2): felhom-os-apply's `bundle` mode and `--install-bundle`, and
+scripts/build-config-bundle.py. An in-memory host plays the files; nothing real is written or run. Each refusal has a
+test; each test names the rule it pins. Red-proof: `audits/r840-config-bundle-2026-10-04/partB/redproof.txt`.
+
+Run: python3 configs/test_felhom_config_bundle.py   (also run by internal/osupdate's Go test)
+"""
+import sys
+sys.dont_write_bytecode = True  # importing the builder must not leave scripts/__pycache__ behind
+import base64
+import contextlib
+import hashlib
+import importlib.machinery
+import importlib.util
+import io
+import json
+import os
+import pathlib
+import re
+import stat as statmod
+import unittest
+
+HERE = pathlib.Path(__file__).resolve().parent
+REPO = HERE.parent
+_loader = importlib.machinery.SourceFileLoader("osapply", os.environ.get("OSAPPLY_UNDER_TEST", str(HERE / "felhom-os-apply")))
+_spec = importlib.util.spec_from_loader("osapply", _loader)
+osapply = importlib.util.module_from_spec(_spec)
+_loader.exec_module(osapply)
+_bl = importlib.machinery.SourceFileLoader("bundlebuild", str(REPO / "scripts" / "build-config-bundle.py"))
+_bs = importlib.util.spec_from_loader("bundlebuild", _bl)
+builder = importlib.util.module_from_spec(_bs)
+_bl.exec_module(builder)
+
+PLAN = "/var/lib/felhom-agent/os/plan-b1.json"
+BUNDLE = "/var/lib/felhom-agent/os/bundle-0.143.0.json"
+HOST = "demo-hp-bb76ea"
+INSTALLER = REPO.parent / "felhom.eu" / "scripts" / "felhom-host-install.sh"
+
+
+class St:
+    def __init__(self, mode, uid):
+        self.st_mode, self.st_uid, self.st_size = mode, uid, 100
+
+
+class Box:
+    """An in-memory host. files: path -> bytes; modes/uids per path; dirs: a set."""
+
+    def __init__(self, bundle_bytes, signed, oob=False, signers=True):
+        self.files, self.modes, self.uids = {}, {}, {}
+        self.dirs = {osapply.OOB_DIR} if oob else set()
+        self.put(osapply.TRUST_FILE, json.dumps({"host_id": HOST, "ring0_slow_lane": False}).encode(), 0o644)
+        if signers:
+            self.put(osapply.TRUST_SIGNERS, b'felhom-op-1 namespaces="felhom-op-v1" ssh-ed25519 AAAA felhom-op-1\n', 0o644)
+        self.put("/proc/sys/kernel/panic", b"0\n", 0o644)
+        self.plan = {"release_id": "bundle-0.143.0", "layer": "host", "mode": "bundle", "bundle": BUNDLE, "signed": signed}
+        self.put(PLAN, json.dumps(self.plan).encode(), 0o600, uid=999)
+        self.put(BUNDLE, bundle_bytes, 0o600, uid=999)
+        self.sig_rc, self.nonces, self.clock = 0, {}, 1791115200.0  # 2026-10-04T12:00:00Z
+        self.calls, self.logs, self.writes = [], [], []
+        self.visudo_fail = False      # the WHOLE sudoers (`visudo -c`) after install
+        self.sudo_l = "    (root) NOPASSWD: /usr/local/sbin/felhom-os-apply --plan /var/lib/felhom-agent/os/plan-*.json\n"
+        self.guard = {"armed": True, "kernel_panic": 10}
+
+    def put(self, p, data, mode, uid=0):
+        self.files[p], self.modes[p], self.uids[p] = data, mode, uid
+
+    # Runner interface
+    def now(self):
+        return self.clock
+
+    def log(self, line):
+        self.logs.append(line)
+
+    def agent_uid(self):
+        return 999
+
+    def verify_sig(self, signers, key_id, ns, blob, sig):
+        self.verified = (signers, key_id, ns)
+        return self.sig_rc
+
+    def read_nonces(self):
+        return dict(self.nonces)
+
+    def write_nonces(self, d):
+        self.nonces = dict(d)
+
+    def read_file(self, p):
+        if p not in self.files:
+            raise OSError("no such file")
+        return self.files[p].decode()
+
+    def read_bytes(self, p):
+        if p not in self.files:
+            raise OSError("no such file")
+        return self.files[p]
+
+    def stat(self, p):
+        if p not in self.files:
+            raise OSError("no such file")
+        return St(statmod.S_IFREG | self.modes[p], self.uids[p])
+
+    def lexists(self, p):
+        return p in self.files
+
+    def isdir(self, p):
+        return p in self.dirs
+
+    def put_file(self, p, data, mode):
+        self.writes.append(p)
+        self.put(p, data, mode)
+
+    def remove(self, p):
+        self.writes.append("rm " + p)
+        del self.files[p]
+
+    def list_dir(self, p):
+        return sorted({k[len(p) + 1:].split("/")[0] for k in self.files if k.startswith(p + "/")})
+
+    def rmtree(self, p):
+        for k in [k for k in self.files if k.startswith(p + "/")]:
+            del self.files[k]
+
+    def check_content(self, kind, data):
+        return (1, f"{kind}: syntax error") if b"BROKEN-SYNTAX" in data else (0, "")
+
+    def host(self, argv, timeout=600, stdin=None):
+        self.calls.append(argv)
+        if argv[:2] == ["visudo", "-c"]:
+            return (1, "", "parse error") if self.visudo_fail else (0, "ok", "")
+        if argv[:2] == ["sudo", "-n"]:
+            return 0, self.sudo_l, ""
+        if argv[-1] == "--self-check":
+            body = self.files.get("/usr/local/sbin/felhom-os-apply", b"")
+            return (0, "felhom-os-apply ok bundle-format=1 files=22\n", "") if b"BUNDLE_OP" in body else (1, "", "boom")
+        if argv[-1] == "/usr/local/sbin/felhom-selfupdate-guarded":
+            return 2, "", "felhom-selfupdate-guarded: usage: ...\n"
+        if argv[-1] == "status" and argv[0].endswith("felhom-crash-guard"):
+            return 0, json.dumps(self.guard), ""
+        if argv[:3] == ["systemctl", "enable", "--now"] and "felhom-crash-guard.service" in argv:
+            self.put("/proc/sys/kernel/panic", f"{self.guard['kernel_panic']}\n".encode(), 0o644)
+        return 0, "", ""
+
+
+def signed_job(sha, version="0.143.0", host=HOST, op="agent_config_update", nonce="b1",
+               issued="2026-10-04T11:50:00Z", expires="2026-10-04T12:30:00Z"):
+    blob = json.dumps({"expires_at": expires, "issued_at": issued, "key_id": "felhom-op-1", "nonce": nonce, "op": op,
+                       "params": {"agent_version": version, "bundle_sha256": sha},
+                       "target": {"guest_id": "", "host_id": host}}, sort_keys=True).encode()
+    return {"blob_b64": base64.b64encode(blob).decode(), "sig": "-----BEGIN SSH SIGNATURE-----\nx\n-----END SSH SIGNATURE-----\n"}
+
+
+def real_bundle(version="0.143.0"):
+    data = builder.build(version)
+    return data, hashlib.sha256(data).hexdigest()
+
+
+def edited_bundle(edit):
+    """The real bundle, with edit(files_list) applied and every sha recomputed — a SIGNED bundle with bad content."""
+    b = json.loads(builder.build("0.143.0"))
+    edit(b["files"])
+    for e in b["files"]:
+        e["sha256"] = hashlib.sha256(base64.b64decode(e["content_b64"])).hexdigest()
+    data = (json.dumps(b, indent=1, sort_keys=True) + "\n").encode()
+    return data, hashlib.sha256(data).hexdigest()
+
+
+def replace_content(files, path, fn):
+    for e in files:
+        if e["path"] == path:
+            e["content_b64"] = base64.b64encode(fn(base64.b64decode(e["content_b64"]))).decode()
+
+
+def run(box, argv=None, environ=None):
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        rc = osapply.main(argv or ["felhom-os-apply", "--plan", PLAN], runner=box, environ=environ or {})
+    line = [l for l in buf.getvalue().splitlines() if l.startswith("OSAPPLY-REPORT ")][-1]
+    return rc, json.loads(line[len("OSAPPLY-REPORT "):])
+
+
+def box_files(box):
+    return {p: box.files[p] for p in box.files if p in osapply.BUNDLE_DESTS}
+
+
+class Install(unittest.TestCase):
+    def test_fresh_box_gets_every_file_and_a_record(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        b = rep["bundle"]
+        # every path but the four OOB ones (no belt on this box)
+        self.assertEqual(len(b["written"]), len(osapply.BUNDLE_FILES) - 4, b)
+        self.assertEqual(len(b["skipped"]), 4)
+        self.assertEqual(box.files["/etc/sudoers.d/felhom-agent"], (REPO / "configs" / "felhom-agent.sudoers").read_bytes())
+        self.assertEqual(box.modes["/etc/sudoers.d/felhom-agent"], 0o440)
+        rec = json.loads(box.files[osapply.BUNDLE_RECORD])
+        self.assertEqual((rec["agent_version"], rec["bundle_sha256"], rec["authority"]), ("0.143.0", sha, "signed"))
+        self.assertIn("b1", box.nonces, "the job is consumed")
+        self.assertEqual(b["self_check"]["crash_guard"], {"armed": True, "kernel_panic": 10})
+        self.assertIn(["systemctl", "daemon-reload"], box.calls)
+
+    def test_sudoers_is_written_after_every_wrapper(self):
+        """Order: a referenced wrapper is in place before the sudoers line that allows it."""
+        data, sha = edited_bundle(lambda f: f.reverse())  # the bundle lists the sudoers FIRST; the wrapper must reorder
+        box = Box(data, signed_job(sha))
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        w = [p for p in box.writes if p in osapply.BUNDLE_DESTS]
+        self.assertEqual(w[-1], "/etc/sudoers.d/felhom-agent")
+        self.assertLess(w.index("/usr/local/sbin/felhom-os-apply"), w.index("/etc/sudoers.d/felhom-agent"))
+
+    def test_identical_box_writes_nothing(self):
+        """The demo boxes' case: hand-copied files equal to the release → 0 written, all 'same'."""
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        for dest, src, mode, _, policy in osapply.BUNDLE_FILES:
+            if policy != "oob":
+                box.put(dest, (REPO / "configs" / src).read_bytes(), mode)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(rep["bundle"]["written"], [])
+        self.assertEqual(rep["bundle"]["same"], len(osapply.BUNDLE_FILES) - 5)  # 4 oob skipped + crash-guard.conf kept
+        self.assertEqual(rep["bundle"]["kept"], ["/etc/felhom/crash-guard.conf"])
+
+    def test_a_wrong_mode_is_rewritten(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.put("/etc/sudoers.d/felhom-agent", (REPO / "configs" / "felhom-agent.sudoers").read_bytes(), 0o644)
+        rc, rep = run(box)
+        self.assertIn("/etc/sudoers.d/felhom-agent", rep["bundle"]["written"])
+        self.assertEqual(box.modes["/etc/sudoers.d/felhom-agent"], 0o440)
+
+    def test_tuned_crash_guard_conf_is_kept(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.put("/etc/felhom/crash-guard.conf", b"LIMIT=5\n", 0o644)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(box.files["/etc/felhom/crash-guard.conf"], b"LIMIT=5\n")
+
+    def test_oob_files_only_on_a_box_with_the_belt(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha), oob=True)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertIn("/etc/sudoers.d/felhom-op", rep["bundle"]["written"])
+        self.assertEqual(rep["bundle"]["skipped"], [])
+
+    def test_previous_copies_are_kept(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.put("/usr/local/sbin/felhom-pbs-apply", b"#!/bin/bash\necho old\n", 0o755)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(box.files[rep["bundle"]["prev_dir"] + "/usr/local/sbin/felhom-pbs-apply"], b"#!/bin/bash\necho old\n")
+
+
+class Refusals(unittest.TestCase):
+    """Each: refused, and NOTHING on the box changed."""
+
+    def refused(self, box, code):
+        before = dict(box_files(box))
+        rc, rep = run(box)
+        self.assertEqual(rc, 2, rep)
+        self.assertEqual(rep["refused"]["code"], code, rep)
+        self.assertEqual(box_files(box), before, "a refusal changed a file")
+        self.assertNotIn(osapply.BUNDLE_RECORD, box.files)
+        return rep
+
+    def test_wrong_sha_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job("0" * 64))
+        self.refused(box, "R18")
+        self.assertEqual(box.nonces, {}, "a wrong sha must not burn the job")
+
+    def test_bad_signature_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.sig_rc = 255
+        self.refused(box, "R3")
+
+    def test_other_op_is_refused(self):
+        data, sha = real_bundle()
+        self.refused(Box(data, signed_job(sha, op="agent_update")), "R3")
+
+    def test_other_host_is_refused(self):
+        data, sha = real_bundle()
+        self.refused(Box(data, signed_job(sha, host="demo-felhom-8363b5")), "R3")
+
+    def test_expired_job_is_refused(self):
+        data, sha = real_bundle()
+        self.refused(Box(data, signed_job(sha, expires="2026-10-04T11:55:00Z")), "R3")
+
+    def test_replayed_job_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.nonces = {"b1": box.clock + 600}
+        self.refused(box, "R3")
+
+    def test_version_mismatch_is_refused(self):
+        data, sha = real_bundle()
+        self.refused(Box(data, signed_job(sha, version="0.142.1")), "R18")
+
+    def test_sudoers_failing_visudo_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/etc/sudoers.d/felhom-agent", lambda c: c + b"BROKEN-SYNTAX\n"))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_sudoers_dropping_the_route_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/etc/sudoers.d/felhom-agent",
+                                                            lambda c: c.replace(b"/usr/local/sbin/felhom-os-apply --plan", b"/bin/true --plan")))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_wrapper_without_bundle_mode_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/usr/local/sbin/felhom-os-apply",
+                                                            lambda c: c.replace(b'BUNDLE_OP = "agent_config_update"', b'BUNDLE_OPX = 1')))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_python_syntax_error_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/usr/local/sbin/felhom-crash-guard", lambda c: c + b"\ndef (\n"))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_unit_with_runtime_directory_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/etc/systemd/system/felhom-mgmt-watchdog.service",
+                                                            lambda c: c + b"RuntimeDirectory=sshd\n"))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_agent_unit_not_as_the_agent_user_is_refused(self):
+        data, sha = edited_bundle(lambda f: replace_content(f, "/etc/systemd/system/felhom-agent.service",
+                                                            lambda c: c.replace(b"User=felhom-agent", b"User=root")))
+        self.refused(Box(data, signed_job(sha)), "R18")
+
+    def test_a_bundle_that_changes_a_signer_is_refused(self):
+        """R17: the trust root is not a bundle's to change — not even a signed one."""
+        def add(f):
+            f.append({"path": osapply.TRUST_SIGNERS, "content_b64": base64.b64encode(b"evil-key\n").decode()})
+        data, sha = edited_bundle(add)
+        box = Box(data, signed_job(sha))
+        self.refused(box, "R17")
+        self.assertIn(b"felhom-op-1", box.files[osapply.TRUST_SIGNERS])
+
+    def test_a_path_outside_the_table_is_refused(self):
+        def add(f):
+            f.append({"path": "/etc/shadow", "content_b64": base64.b64encode(b"root::0:0\n").decode()})
+        data, sha = edited_bundle(add)
+        self.refused(Box(data, signed_job(sha)), "R16")
+
+    def test_content_not_matching_its_sha_is_refused(self):
+        b = json.loads(builder.build("0.143.0"))
+        b["files"][0]["content_b64"] = base64.b64encode(b"#!/bin/bash\nexit 0\n").decode()
+        data = json.dumps(b).encode()
+        self.refused(Box(data, signed_job(hashlib.sha256(data).hexdigest())), "R18")
+
+    def test_bundle_outside_the_plan_dir_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.plan["bundle"] = "/tmp/bundle-0.143.0.json"
+        box.files[PLAN] = json.dumps(box.plan).encode()
+        self.refused(box, "R1")
+
+    def test_bundle_not_owned_by_the_agent_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.uids[BUNDLE] = 0
+        self.refused(box, "R1")
+
+    def test_no_trust_file_is_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        del box.files[osapply.TRUST_FILE]
+        self.refused(box, "R3")
+
+
+class SelfCheckUndo(unittest.TestCase):
+    def assert_restored(self, box, before, rep):
+        self.assertTrue(rep["bundle"]["rolled_back"], rep)
+        self.assertEqual(box_files(box), before, "the previous files must be back, byte for byte")
+        self.assertNotIn(osapply.BUNDLE_RECORD, box.files)
+
+    def with_old_files(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.put("/usr/local/sbin/felhom-pbs-apply", b"#!/bin/bash\necho old\n", 0o755)
+        box.put("/etc/sudoers.d/felhom-agent", b"# old sudoers\n", 0o440)
+        return box
+
+    def test_route_missing_after_install_puts_everything_back(self):
+        box = self.with_old_files()
+        before = dict(box_files(box))
+        box.sudo_l = "    (root) NOPASSWD: /bin/true\n"
+        rc, rep = run(box)
+        self.assertEqual(rc, 3, rep)
+        self.assert_restored(box, before, rep)
+        self.assertEqual(box.calls[-1], ["visudo", "-c"], "the undo re-checks the whole sudoers")
+
+    def test_visudo_failing_after_install_puts_everything_back(self):
+        box = self.with_old_files()
+        before = dict(box_files(box))
+        box.visudo_fail = True
+        rc, rep = run(box)
+        self.assertEqual(rc, 3, rep)
+        self.assert_restored(box, before, rep)
+
+    def test_crash_guard_disagreeing_with_kernel_panic_puts_everything_back(self):
+        box = self.with_old_files()
+        before = dict(box_files(box))
+        box.guard = {"armed": True, "kernel_panic": 10}
+        box.host_orig = box.host
+
+        def host(argv, timeout=600, stdin=None):
+            if argv[:3] == ["systemctl", "enable", "--now"]:
+                box.calls.append(argv)
+                return 0, "", ""   # the unit "started" but kernel.panic stayed 0
+            return box.host_orig(argv, timeout, stdin)
+        box.host = host
+        rc, rep = run(box)
+        self.assertEqual(rc, 3, rep)
+        self.assert_restored(box, before, rep)
+
+
+class TrustBootstrap(unittest.TestCase):
+    def test_missing_signers_verifies_against_the_pinned_key_and_creates_it(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha), signers=False)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(box.verified[0], osapply.PINNED_SIGNERS, "verified against the pinned key, nothing else")
+        self.assertTrue(rep["bundle"]["signers_created"])
+        self.assertEqual(box.files[osapply.TRUST_SIGNERS], osapply.pinned_signers_line().encode())
+        self.assertEqual(box.modes[osapply.TRUST_SIGNERS], 0o644)
+
+    def test_missing_signers_and_a_job_the_pinned_key_did_not_sign(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha), signers=False)
+        box.sig_rc = 255
+        rc, rep = run(box)
+        self.assertEqual((rc, rep["refused"]["code"]), (2, "R3"))
+        self.assertNotIn(osapply.TRUST_SIGNERS, box.files)
+
+    def test_present_signers_are_never_touched(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.put(osapply.TRUST_SIGNERS, b'felhom-op-2 namespaces="felhom-op-v1" ssh-ed25519 BBBB felhom-op-2\n', 0o644)
+        rc, rep = run(box)
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(box.verified[0], osapply.TRUST_SIGNERS)
+        self.assertFalse(rep["bundle"]["signers_created"])
+        self.assertIn(b"felhom-op-2", box.files[osapply.TRUST_SIGNERS])
+
+    def test_agent_writable_signers_are_refused(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        box.uids[osapply.TRUST_SIGNERS] = 999
+        rc, rep = run(box)
+        self.assertEqual((rc, rep["refused"]["code"]), (2, "R3"))
+
+    def test_pinned_operator_key_equals_the_installers(self):
+        """The bootstrap key is exactly the one felhom-host-install.sh pins (OPERATOR_KEY_OPERATIONAL_*)."""
+        text = INSTALLER.read_text()
+        kid = re.search(r'^OPERATOR_KEY_OPERATIONAL_ID="([^"]+)"', text, re.M).group(1)
+        line = re.search(r'^OPERATOR_KEY_OPERATIONAL_LINE="([^"]+)"', text, re.M).group(1)
+        self.assertEqual((osapply.PINNED_OPERATOR_KEY_ID, osapply.PINNED_OPERATOR_KEY_LINE), (kid, line))
+        # and the file format is the installer's printf, byte for byte
+        self.assertIn("printf '%s namespaces=\"felhom-op-v1\" %s\\n'", text)
+
+
+class InstallerEntry(unittest.TestCase):
+    def test_installer_installs_without_a_signature(self):
+        data, sha = real_bundle()
+        box = Box(data, None)
+        box.put("/root/bundle.json", data, 0o600)
+        rc, rep = run(box, ["felhom-os-apply", "--install-bundle", "/root/bundle.json", "--sha256", sha])
+        self.assertEqual(rc, 0, rep)
+        self.assertEqual(json.loads(box.files[osapply.BUNDLE_RECORD])["authority"], "installer")
+
+    def test_installer_entry_checks_the_sha(self):
+        data, sha = real_bundle()
+        box = Box(data, None)
+        box.put("/root/bundle.json", data, 0o600)
+        rc, rep = run(box, ["felhom-os-apply", "--install-bundle", "/root/bundle.json", "--sha256", "1" * 64])
+        self.assertEqual((rc, rep["refused"]["code"]), (2, "R18"))
+
+    def test_installer_entry_is_refused_through_sudo(self):
+        data, sha = real_bundle()
+        box = Box(data, None)
+        box.put("/root/bundle.json", data, 0o600)
+        rc, rep = run(box, ["felhom-os-apply", "--install-bundle", "/root/bundle.json", "--sha256", sha], {"SUDO_UID": "999"})
+        self.assertEqual((rc, rep["refused"]["code"]), (2, "R1"))
+        self.assertNotIn(osapply.BUNDLE_RECORD, box.files)
+
+    def test_self_check_answers(self):
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            rc = osapply.main(["felhom-os-apply", "--self-check"], runner=Box(b"", None))
+        self.assertEqual(rc, 0)
+        self.assertIn("bundle-format=1", buf.getvalue())
+
+
+class Facts(unittest.TestCase):
+    def test_state_reports_drift_against_the_record(self):
+        data, sha = real_bundle()
+        box = Box(data, signed_job(sha))
+        run(box)
+        box.put("/usr/local/sbin/felhom-pbs-apply", b"#!/bin/bash\necho by hand\n", 0o755)
+        a = osapply.Apply(box, PLAN)
+        st = osapply.Bundle(a).state()
+        self.assertEqual(st["version"], "0.143.0")
+        self.assertEqual(st["drift"], ["/usr/local/sbin/felhom-pbs-apply"])
+        self.assertTrue(st["signers_present"])
+
+    def test_state_without_a_record_says_none(self):
+        box = Box(b"", None)
+        st = osapply.Bundle(osapply.Apply(box, PLAN)).state()
+        self.assertEqual(st["version"], "none")
+        self.assertNotIn("drift", st)
+        self.assertEqual(st["live"]["/etc/sudoers.d/felhom-agent"], "absent")
+
+
+class Builder(unittest.TestCase):
+    def test_reproducible(self):
+        self.assertEqual(builder.build("0.143.0"), builder.build("0.143.0"))
+
+    def test_every_source_exists_and_every_dest_is_unique(self):
+        dests = [e[0] for e in osapply.BUNDLE_FILES]
+        self.assertEqual(len(dests), len(set(dests)))
+        for _, src, *_ in osapply.BUNDLE_FILES:
+            self.assertTrue((REPO / "configs" / src).is_file(), src)
+
+    def test_every_root_file_the_installer_writes_is_in_the_bundle(self):
+        """One source of truth: a felhom root-owned path the installer names must be a bundle path, a trust file, or a
+        path the AGENT itself writes at run time (named here, with why). Scope is a regex over the WHOLE installer."""
+        text = INSTALLER.read_text()
+        found = set(re.findall(r"(/usr/local/sbin/felhom-[a-z-]+|/etc/systemd/system/felhom-[a-z.-]+|"
+                               r"/etc/sudoers\.d/felhom-[a-z-]+|/etc/felhom-oob\.nft|/etc/tmpfiles\.d/felhom-[a-z.-]+|"
+                               r"/etc/felhom/[a-z.-]+)", text))
+        agent_writes = {"/usr/local/sbin/felhom-shared-parent", "/etc/systemd/system/felhom-shared-parent.service"}
+        trust = {osapply.TRUST_FILE, osapply.TRUST_SIGNERS, osapply.TRUST_SIGNERS + ".tmp", osapply.BUNDLE_RECORD}
+        missing = sorted(p for p in found if p not in osapply.BUNDLE_DESTS and p not in agent_writes | trust)
+        self.assertEqual(missing, [], "the installer writes these root files, but the bundle does not carry them")
+        # the limits drop-in is named through $AGENT_UNIT in the installer
+        self.assertIn("/etc/systemd/system/felhom-agent.service.d/felhom-agent-limits.conf", osapply.BUNDLE_DESTS)
+
+
+if __name__ == "__main__":
+    unittest.main()

configs/test_felhom_crash_guard.py

@@ -0,0 +1,143 @@
+#!/usr/bin/python3
+"""Tests for felhom-crash-guard (`11` §5.9). Temp dirs only; nothing real is touched. Red-proof seam: CRASHGUARD_UNDER_TEST."""
+import importlib.machinery
+import importlib.util
+import json
+import os
+import pathlib
+import tempfile
+import unittest
+
+HERE = pathlib.Path(__file__).resolve().parent
+_loader = importlib.machinery.SourceFileLoader("crashguard", os.environ.get("CRASHGUARD_UNDER_TEST", str(HERE / "felhom-crash-guard")))
+_spec = importlib.util.spec_from_loader("crashguard", _loader)
+cg = importlib.util.module_from_spec(_spec)
+_loader.exec_module(cg)
+
+T0 = 1791115200.0  # 2026-10-04T12:00:00Z
+
+
+class FakeEnv(cg.Env):
+    def __init__(self, d):
+        super().__init__(conf=os.path.join(d, "conf"), state_dir=os.path.join(d, "state"),
+                         panic_path=os.path.join(d, "panic"), uptime_path=os.path.join(d, "uptime"),
+                         boot_id_path=os.path.join(d, "bootid"))
+        self.t = T0
+        self.logs = []
+        open(self.panic_path, "w").write("0\n")
+        open(self.uptime_path, "w").write("20.00 10.00\n")
+
+    def now(self):
+        return self.t
+
+    def log(self, line):
+        self.logs.append(line)
+
+    def panic(self):
+        return int(open(self.panic_path).read())
+
+    def state(self):
+        return json.load(open(os.path.join(self.state_dir, "state.json")))
+
+
+class Guard(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.TemporaryDirectory()
+        self.e = FakeEnv(self.d.name)
+
+    def tearDown(self):
+        self.d.cleanup()
+
+    def crash_boot(self, minutes_later):
+        self.e.t += minutes_later * 60
+        cg.main(["x", "boot"], self.e)  # no clean-stop before it: an unclean stop
+
+    def clean_reboot(self, minutes_later):
+        cg.main(["x", "clean-stop"], self.e)
+        self.e.t += minutes_later * 60
+        cg.main(["x", "boot"], self.e)
+
+    def test_first_boot_is_not_a_crash_and_arms(self):
+        cg.main(["x", "boot"], self.e)
+        s = self.e.state()
+        self.assertFalse(s["last_boot_unclean"])
+        self.assertEqual(self.e.panic(), 10)
+        self.assertTrue(s["armed"])
+
+    def test_clean_reboots_never_count(self):
+        cg.main(["x", "boot"], self.e)
+        for _ in range(5):
+            self.clean_reboot(1)
+        s = self.e.state()
+        self.assertEqual(s["unclean_boots_in_window"], 0)
+        self.assertEqual(self.e.panic(), 10)
+
+    def test_third_crash_in_an_hour_leaves_the_box_off(self):
+        # operator's words: "if it crashes 3 times within one hour, it stays off" — after crash 2 the guard trips,
+        # so crash 3 (kernel.panic = 0) does not restart the box.
+        cg.main(["x", "boot"], self.e)
+        self.crash_boot(5)
+        self.assertEqual(self.e.panic(), 10, "one crash: still restarts")
+        self.crash_boot(5)
+        s = self.e.state()
+        self.assertTrue(s["tripped"], s)
+        self.assertEqual(self.e.panic(), 0, "after the 2nd crash boot the 3rd crash must leave the box off")
+        self.assertIn("2 unclean boots within 60 minutes", s["tripped_reason"])
+
+    def test_crashes_spread_over_more_than_the_window_do_not_trip(self):
+        cg.main(["x", "boot"], self.e)
+        self.crash_boot(5)
+        self.crash_boot(61)
+        self.assertFalse(self.e.state()["tripped"])
+        self.assertEqual(self.e.panic(), 10)
+
+    def test_tripped_stays_tripped_across_boots(self):
+        cg.main(["x", "boot"], self.e)
+        self.crash_boot(5)
+        self.crash_boot(5)
+        self.clean_reboot(30)  # the operator switched it on; even a clean boot keeps the trip
+        self.assertTrue(self.e.state()["tripped"])
+        self.assertEqual(self.e.panic(), 0)
+
+    def test_rearms_after_24h_of_normal_running(self):
+        cg.main(["x", "boot"], self.e)
+        self.crash_boot(5)
+        self.crash_boot(5)
+        self.e.t += 23 * 3600
+        cg.main(["x", "check"], self.e)
+        self.assertTrue(self.e.state()["tripped"], "not before 24 h")
+        self.e.t += 3600
+        cg.main(["x", "check"], self.e)
+        s = self.e.state()
+        self.assertFalse(s["tripped"])
+        self.assertEqual(self.e.panic(), 10)
+        self.assertIn("timer", s["rearmed_by"])
+
+    def test_operator_rearm_starts_a_fresh_window(self):
+        cg.main(["x", "boot"], self.e)
+        self.crash_boot(5)
+        self.crash_boot(5)
+        self.e.t += 60
+        cg.main(["x", "rearm"], self.e)
+        s = self.e.state()
+        self.assertFalse(s["tripped"])
+        self.assertEqual(s["rearmed_by"], "operator")
+        self.assertEqual(s["unclean_boots_24h"], 2, "the history stays")
+        self.crash_boot(5)
+        self.assertFalse(self.e.state()["tripped"], "one crash after a re-arm must not trip at once")
+
+    def test_config_numbers_are_read(self):
+        open(self.e.conf, "w").write("LIMIT=2\nPANIC_SECONDS=30\n")
+        cg.main(["x", "boot"], self.e)
+        self.assertEqual(self.e.panic(), 30)
+        self.crash_boot(1)
+        self.assertTrue(self.e.state()["tripped"], "LIMIT=2: the first crash boot trips")
+
+    def test_state_is_world_readable_for_the_agent(self):
+        cg.main(["x", "boot"], self.e)
+        mode = os.stat(os.path.join(self.e.state_dir, "state.json")).st_mode & 0o777
+        self.assertEqual(mode, 0o644)
+
+
+if __name__ == "__main__":
+    unittest.main()

internal/backup/r874_first_eval_test.go

@@ -0,0 +1,63 @@
+package backup
+
+import (
+	"context"
+	"fmt"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+)
+
+// R-874 (v0.145.0). THE MEASURED SHAPE (Part F spike, Tester 2): power-on sessions of ~1.5 h and ~5 min against a
+// 6 h evaluation ticker that restarts at every start — no restore-test ever evaluated. Now the first evaluation runs
+// FirstEval after start.
+// COMPANION RED-PROOF: drop the first-evaluation timer in Run (back to the bare ticker) → "no evaluation within".
+func TestR874_FirstEvaluationAfterStart(t *testing.T) {
+	var picks int32
+	s := NewScheduler(SchedulerOptions{
+		Runner: &fakeRTRunner{res: reconcile.RestoreTestResult{Pass: true, Verified: "boot+running"}},
+		Pick: func(context.Context) (string, error) {
+			atomic.AddInt32(&picks, 1)
+			return fmt.Sprintf("local:backup/vzdump-lxc-9201-%d.tar.zst", atomic.LoadInt32(&picks)), nil
+		},
+		Store: NewStore(), Spec: (&specSpy{}).build,
+		Cadence: 6 * time.Hour, FirstEval: 30 * time.Millisecond, Logger: quiet(),
+	})
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { _ = s.Run(ctx); close(done) }()
+	deadline := time.Now().Add(3 * time.Second)
+	for atomic.LoadInt32(&picks) == 0 && time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+	}
+	cancel()
+	<-done
+	if atomic.LoadInt32(&picks) == 0 {
+		t.Fatal("no evaluation within 3 s of start (FirstEval 30 ms) — a box with short sessions never gets a restore-test")
+	}
+}
+
+// The earned restraint stays: an agent that restarts before FirstEval never evaluates (a crash loop does not
+// hammer a failing tier).
+func TestR874_CrashLoopNeverEvaluates(t *testing.T) {
+	var picks int32
+	for i := 0; i < 5; i++ { // five quick "restarts"
+		s := NewScheduler(SchedulerOptions{
+			Runner: &fakeRTRunner{res: reconcile.RestoreTestResult{Pass: true}},
+			Pick:   func(context.Context) (string, error) { atomic.AddInt32(&picks, 1); return "x", nil },
+			Store:  NewStore(), Spec: (&specSpy{}).build,
+			Cadence: 6 * time.Hour, FirstEval: 200 * time.Millisecond, Logger: quiet(),
+		})
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+		_ = s.Run(ctx)
+		cancel()
+	}
+	if n := atomic.LoadInt32(&picks); n != 0 {
+		t.Fatalf("a restart before FirstEval evaluated %d time(s)", n)
+	}
+	if DefaultFirstEval != 30*time.Minute {
+		t.Fatalf("DefaultFirstEval = %s, the documented 30 min", DefaultFirstEval)
+	}
+}

internal/backup/schedule.go

@@ -64,8 +64,17 @@ type Scheduler struct {
 	tierPick  TierPicker        // newest archive on a named tier
 	rtState   *RestoreTestState // persisted last-successful-per-tier (drives oldest-first)
 	inFlight  *InFlight         // shared with the backup path — Scenario F
+	firstEval time.Duration     // R-874: the first evaluation after start
 }
 
+// DefaultFirstEval (R-874): the first due-ness evaluation runs 30 minutes after the agent starts, then every
+// cadence. MEASURED need (2026-10-05 Part F spike): a box whose power-on sessions are all shorter than the 6 h
+// interval (Tester 2: ~1.5 h and ~5 min) NEVER evaluated, because the ticker restarts at each start. 30 minutes
+// keeps the earned restraint below — a crash-looping agent restarts far more often than that and still never
+// evaluates — while a box that stays on for half an hour gets its due test. Pinned by
+// TestR874_FirstEvaluationAfterStart and TestR874_CrashLoopNeverEvaluates.
+const DefaultFirstEval = 30 * time.Minute
+
 // SchedulerOptions configures a Scheduler.
 type SchedulerOptions struct {
 	Runner RestoreTestRunner
@@ -81,6 +90,8 @@ type SchedulerOptions struct {
 	// 0 → no settle requirement (any archive is a candidate).
 	Settle time.Duration
 	Logger *slog.Logger
+	// FirstEval (R-874, v0.145.0) is when the FIRST evaluation runs after start; 0 → DefaultFirstEval.
+	FirstEval time.Duration
 
 	// R-85 (all optional — omit for the pre-R-85 single-tier behaviour):
 	// Tiers are the configured tier target ids (primary first); TierPick resolves an archive on a
@@ -110,6 +121,12 @@ func NewScheduler(opts SchedulerOptions) *Scheduler {
 		tierPick: opts.TierPick,
 		rtState:  opts.State,
 		inFlight: opts.InFlight,
+		firstEval: func() time.Duration {
+			if opts.FirstEval > 0 {
+				return opts.FirstEval
+			}
+			return DefaultFirstEval
+		}(),
 	}
 }
 
@@ -120,8 +137,9 @@ func NewScheduler(opts SchedulerOptions) *Scheduler {
 // trigger any more: its phase is the process's uptime, and agent deploys reset it, which is exactly
 // the defect R-86 removes. What decides that a test happens is `EvaluateDue`.
 //
-// It still does NOT evaluate immediately on start — the first evaluation is one interval in. That
-// is an EARNED restraint, kept deliberately: a restore is heavy, agent restarts are routine, and a
+// It still does NOT evaluate immediately on start. v0.145.0 (R-874): the first evaluation is
+// firstEval (30 min) in, then every interval — it was one full interval in, which a box with short
+// power-on sessions never reached. The restraint itself is EARNED and kept: a restore is heavy, agent restarts are routine, and a
 // crash-loop that evaluated at start would hammer a permanently-failing tier as fast as it could
 // restart. Due-ness does not expire while we wait, so the only cost is up to one interval of
 // latency on a tier that just became due. On-demand runs use `--selftest=restore-test`.
@@ -135,6 +153,16 @@ func (s *Scheduler) Run(ctx context.Context) error {
 	}
 	s.logger.Info("backup: restore-test scheduler starting (per-archive due-check)",
 		"eval_interval", s.cadence, "settle", s.settle)
+	first := time.NewTimer(s.firstEval)
+	defer first.Stop()
+	select {
+	case <-ctx.Done():
+		s.logger.Info("backup: restore-test scheduler shutting down", "reason", ctx.Err())
+		return nil
+	case <-first.C:
+		s.logger.Info("backup: restore-test first evaluation after start (R-874)", "after", s.firstEval)
+		s.tick(ctx)
+	}
 	t := time.NewTicker(s.cadence)
 	defer t.Stop()
 	for {

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/hub/bundle_record_test.go

@@ -0,0 +1,25 @@
+package hub
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// R-840: the agent reports the bundle record itself — "none" when no bundle ever reached the box (so an old wrapper
+// cannot hide that), "unknown" when it cannot be read, else the version and sha the root wrapper recorded.
+func TestReadBundleRecord(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config-bundle.json")
+	if got := string(readBundleRecord(p)); got != `{"version":"none"}` {
+		t.Fatalf("absent: %s", got)
+	}
+	os.WriteFile(p, []byte("{broken"), 0o644)
+	if got := string(readBundleRecord(p)); got != `{"version":"unknown"}` {
+		t.Fatalf("broken: %s", got)
+	}
+	os.WriteFile(p, []byte(`{"format":1,"agent_version":"0.143.0","bundle_sha256":"abc","installed_at":"2026-10-04T20:00:00Z","authority":"signed","files":{"/x":"y"}}`), 0o644)
+	if got := string(readBundleRecord(p)); got != `{"authority":"signed","bundle_sha256":"abc","installed_at":"2026-10-04T20:00:00Z","version":"0.143.0"}` {
+		t.Fatalf("record: %s", got)
+	}
+}

internal/hub/client.go

@@ -425,3 +425,27 @@ func (c *Client) FetchRetainedIdentityEscrow(ctx context.Context) (*RetainedEscr
 	}
 	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

@@ -4,10 +4,12 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"io"
 	"log/slog"
 	"os"
+	"strings"
 	"time"
 
 	"gitea.dooplex.hu/admin/felhom-agent/internal/capability"
@@ -108,6 +110,8 @@ type Collector struct {
 	selfUpdate       SelfUpdateReporter                            // D1: agent self-update pending status (nil → false)
 	mgmtPlane        MgmtPlaneReporter                             // G1: management-plane health (nil → stanza omitted)
 	oob              OOBReporter                                   // H1: operator-access health (nil → stanza omitted)
+	system           SystemReporter                                // R-852: the box versions (nil → API fields only)
+	bundleRecordPath string                                        // R-840: test seam; "" = BundleRecordPath
 	backupTarget     func() ConfiguredBackupTarget                 // R-109: primary backup tier id (nil → recipe records unknown)
 	hostID           string
 	agentVersion     string
@@ -248,6 +252,69 @@ type OOBReporter interface {
 }
 
 // SetOOBReporter wires the operator-access health source (H1; nil-safe → stanza omitted).
+// SystemReporter reads the box's versions (R-852): the customer guest's vmid and the wrapper's raw facts.
+type SystemReporter interface {
+	SystemFacts(ctx context.Context) (vmid int, facts json.RawMessage, err error)
+}
+
+// SetSystemReporter wires the facts read (agent v0.142.0). Without it the stanza carries the Proxmox API fields only.
+func (c *Collector) SetSystemReporter(r SystemReporter) *Collector {
+	c.system = r
+	return c
+}
+
+// BundleRecordPath is the root-owned record felhom-os-apply writes after a config bundle installs (R-840).
+const BundleRecordPath = "/etc/felhom/config-bundle.json"
+
+// readBundleRecord returns the record's summary: version/sha/installed_at, "none" when the file is absent, "unknown"
+// when it cannot be read or parsed (never a guess).
+func readBundleRecord(path string) json.RawMessage {
+	if path == "" {
+		path = BundleRecordPath
+	}
+	b, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return json.RawMessage(`{"version":"none"}`)
+	}
+	var rec struct {
+		AgentVersion string `json:"agent_version"`
+		BundleSHA256 string `json:"bundle_sha256"`
+		InstalledAt  string `json:"installed_at"`
+		Authority    string `json:"authority"`
+	}
+	if err != nil || json.Unmarshal(b, &rec) != nil || rec.AgentVersion == "" {
+		return json.RawMessage(`{"version":"unknown"}`)
+	}
+	out, _ := json.Marshal(map[string]string{"version": rec.AgentVersion, "bundle_sha256": rec.BundleSHA256,
+		"installed_at": rec.InstalledAt, "authority": rec.Authority})
+	return out
+}
+
+func unknownIfEmpty(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "unknown"
+	}
+	return s
+}
+
+// systemInfo builds the `system` stanza. Never fatal: a failed facts read is FactsError, the API fields stay.
+func (c *Collector) systemInfo(ctx context.Context, ns proxmox.NodeStatus) *SystemInfo {
+	si := &SystemInfo{PVEVersion: unknownIfEmpty(ns.PVEVersion), KernelVersion: unknownIfEmpty(ns.KVersion),
+		ReadAt: c.now().Format(time.RFC3339)}
+	si.ConfigBundle = readBundleRecord(c.bundleRecordPath)
+	if c.system == nil {
+		si.FactsError = "no facts reader wired"
+		return si
+	}
+	vmid, f, err := c.system.SystemFacts(ctx)
+	si.VMID, si.Facts = vmid, f
+	if err != nil {
+		si.FactsError = err.Error()
+		c.logger.Debug("hub: system facts unavailable", "err", err)
+	}
+	return si
+}
+
 func (c *Collector) SetOOBReporter(o OOBReporter) *Collector {
 	c.oob = o
 	return c
@@ -280,10 +347,11 @@ 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(),
+		System:          c.systemInfo(ctx, ns),
 	}
 	// DR recipe host-half — derived from the just-collected guest/storage/PBS facts (no new reads).
 	// Secret-free by construction (identifiers/intents/sizes/coordinates only).
@@ -555,16 +623,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

@@ -89,6 +89,12 @@ type HostReport struct {
 	// hub-schema change and are absent when the reporter is not wired.
 	MgmtPlane *MgmtPlaneStatus `json:"mgmt_plane,omitempty"`
 
+	// System is the box's versions for the hub's System page (agent v0.142.0, R-852, `09` decision 89): Proxmox and the
+	// running kernel from the Proxmox API, and the wrapper's read-only facts (host Debian, next-boot kernel, held
+	// packages, taint, the crash guard; guest Debian, Docker engine, containerd, live-restore). A value nobody could
+	// read is "unknown", never empty and never guessed. The hub v0.132.0 consumes it (hosts + System pages).
+	System *SystemInfo `json:"system,omitempty"`
+
 	// PBSDR is the PBS-DR-tier bridge status stanza (slice 2). Present only when the pbsdr
 	// consumer is wired. `consumed_failed` is the LOUD persistent state: the one-time token
 	// secret was consumed but the apply failed afterwards — the secret is burned, the bridge
@@ -241,6 +247,20 @@ type WireguardStatus struct {
 	AssignedIP        string `json:"assigned_ip,omitempty"` // from the marker, e.g. "10.77.0.2/32"
 }
 
+// SystemInfo is the `system` stanza (see HostReport.System).
+type SystemInfo struct {
+	PVEVersion    string          `json:"pve_version"`    // GET /nodes/{node}/status pveversion
+	KernelVersion string          `json:"kernel_version"` // GET /nodes/{node}/status kversion
+	VMID          int             `json:"vmid,omitempty"` // the customer guest the facts read
+	Facts         json.RawMessage `json:"facts,omitempty"`
+	FactsError    string          `json:"facts_error,omitempty"`
+	ReadAt        string          `json:"read_at"`
+	// ConfigBundle is the box's root-owned config bundle record (R-840, agent v0.143.0), read by the agent itself from
+	// /etc/felhom/config-bundle.json (0644): {"version":"none"} on a box no bundle reached, so an OLD wrapper cannot
+	// hide it. The wrapper's facts carry the same record plus the drift (files changed by hand).
+	ConfigBundle json.RawMessage `json:"config_bundle,omitempty"`
+}
+
 // HostMetrics is the host block, sourced from proxmox NodeStatus.
 type HostMetrics struct {
 	Node             string   `json:"node"`
@@ -289,9 +309,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
@@ -548,6 +569,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/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/server.go

@@ -160,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
@@ -276,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
 
@@ -469,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
 	}
@@ -894,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}, "")
 }
@@ -1465,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/bundle.go

@@ -0,0 +1,157 @@
+package osupdate
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/signedjobs"
+)
+
+// OpConfigUpdate is the signed op that brings a box's ROOT-OWNED files (sudoers, wrappers, units) to a release's config
+// bundle (R-840, `11` §5.4.2). The params pin the agent version and the bundle's sha256; the root wrapper re-verifies
+// the signature, the host binding, the nonce and the sha ITSELF — this executor is only the courier.
+const OpConfigUpdate = "agent_config_update"
+
+// BundleFileName is the bundle's name beside the binary in the Gitea generic package felhom-agent/<version>/.
+const BundleFileName = "felhom-config-bundle.json"
+
+var (
+	bundleVersionRe = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$`)
+	bundleSHARe     = regexp.MustCompile(`^[0-9a-f]{64}$`)
+)
+
+// ConfigUpdateParams are the signed params (the wrapper reads the same two names out of the signed blob).
+type ConfigUpdateParams struct {
+	AgentVersion string `json:"agent_version"`
+	BundleSHA256 string `json:"bundle_sha256"`
+}
+
+// BundleURL derives the bundle's URL from the agent binary's URL template (".../felhom-agent/{version}/felhom-agent").
+func BundleURL(binaryTemplate, version string) (string, error) {
+	if !strings.HasSuffix(binaryTemplate, "/felhom-agent") || !strings.Contains(binaryTemplate, "{version}") {
+		return "", fmt.Errorf("cannot derive the bundle URL from %q (want …/{version}/felhom-agent)", binaryTemplate)
+	}
+	t := strings.TrimSuffix(binaryTemplate, "felhom-agent") + BundleFileName
+	return strings.ReplaceAll(t, "{version}", version), nil
+}
+
+// ConfigUpdateExecutor runs a verified agent_config_update (signedjobs.Executor).
+type ConfigUpdateExecutor struct {
+	Leg         *Leg
+	URLTemplate string // the agent binary's template (config.SelfUpdate.URLTemplate)
+	Username    string
+	Token       string
+	HTTPClient  *http.Client
+	// AfterInstall runs after a bundle installed (the capability re-probe; nil = none).
+	AfterInstall func(ctx context.Context)
+}
+
+// Execute implements signedjobs.Executor.
+func (e ConfigUpdateExecutor) Execute(ctx context.Context, op string, params json.RawMessage) error {
+	if op != OpConfigUpdate {
+		return signedjobs.ErrNoExecutor
+	}
+	so, ok := signedjobs.SignedOpFrom(ctx)
+	if !ok {
+		return fmt.Errorf("agent_config_update: no signed envelope in the context — the wrapper could not verify it")
+	}
+	var p ConfigUpdateParams
+	if err := json.Unmarshal(params, &p); err != nil {
+		return fmt.Errorf("agent_config_update: bad params: %w", err)
+	}
+	if !bundleVersionRe.MatchString(p.AgentVersion) || !bundleSHARe.MatchString(p.BundleSHA256) {
+		return fmt.Errorf("agent_config_update: params must pin agent_version (semver) and bundle_sha256 (64 hex)")
+	}
+	lg := e.Leg.log().With("op", OpConfigUpdate, "agent_version", p.AgentVersion)
+	url, err := BundleURL(e.URLTemplate, p.AgentVersion)
+	if err != nil {
+		return fmt.Errorf("agent_config_update: %w", err)
+	}
+	dir := e.Leg.PlanDir
+	if dir == "" {
+		dir = DefaultPlanDir
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return fmt.Errorf("agent_config_update: plan dir: %w", err)
+	}
+	path := filepath.Join(dir, "bundle-"+p.AgentVersion+".json")
+	start := time.Now()
+	got, err := e.download(ctx, url, path)
+	if err != nil {
+		_ = os.Remove(path)
+		return fmt.Errorf("agent_config_update: download %s: %w", url, err)
+	}
+	defer os.Remove(path)
+	// The agent's own check is a courtesy (an early, clear error); the wrapper's is the gate.
+	if got != p.BundleSHA256 {
+		return fmt.Errorf("agent_config_update: the downloaded bundle's sha256 is %s, the signed job pins %s — nothing installed", got, p.BundleSHA256)
+	}
+	lg.Info("osupdate: config bundle downloaded; handing it to the root wrapper", "sha256", got[:16], "duration_ms", time.Since(start).Milliseconds())
+	runID := "bundle-" + e.Leg.now().UTC().Format("20060102T150405Z")
+	wr, err := e.Leg.call(ctx, runID, map[string]any{"release_id": "bundle-" + p.AgentVersion, "layer": LayerHost,
+		"mode": "bundle", "bundle": path,
+		"signed": map[string]string{"blob_b64": base64.StdEncoding.EncodeToString(so.Blob), "sig": string(so.Sig)}})
+	if err != nil {
+		return fmt.Errorf("agent_config_update: %w", err)
+	}
+	if wr.refused() {
+		lg.Warn("osupdate: config bundle REFUSED by the wrapper — nothing changed", "refused", string(wr.Refused))
+		return fmt.Errorf("agent_config_update: refused: %s", wr.Refused)
+	}
+	if wr.failed() {
+		lg.Error("osupdate: config bundle FAILED — the wrapper put the previous files back", "failed", string(wr.Failed), "bundle", string(wr.Bundle))
+		return fmt.Errorf("agent_config_update: failed (previous files restored): %s", wr.Failed)
+	}
+	lg.Warn("osupdate: config bundle INSTALLED", "bundle", string(wr.Bundle), "pass_seconds", wr.PassSeconds)
+	if e.AfterInstall != nil {
+		e.AfterInstall(ctx)
+	}
+	return nil
+}
+
+func (e ConfigUpdateExecutor) download(ctx context.Context, url, dest string) (string, error) {
+	hc := e.HTTPClient
+	if hc == nil {
+		hc = &http.Client{Timeout: 2 * time.Minute}
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", err
+	}
+	if e.Username != "" || e.Token != "" {
+		req.SetBasicAuth(e.Username, e.Token)
+	}
+	resp, err := hc.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+	f, err := os.OpenFile(dest, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o600)
+	if err != nil {
+		return "", err
+	}
+	h := sha256.New()
+	// 4 MB is the wrapper's own limit; read one byte more so an oversized bundle fails there, visibly.
+	if _, err := io.Copy(io.MultiWriter(f, h), io.LimitReader(resp.Body, 4*1024*1024+1)); err != nil {
+		f.Close()
+		return "", err
+	}
+	if err := f.Close(); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}

internal/osupdate/bundle_test.go

@@ -0,0 +1,155 @@
+package osupdate
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/signedjobs"
+)
+
+// bundleWrapper plays felhom-os-apply for mode "bundle": it records the plan and the bundle file's bytes AT CALL TIME
+// (the executor deletes the file afterwards), and answers with rep.
+type bundleWrapper struct {
+	t      *testing.T
+	rep    string
+	plans  []map[string]any
+	bodies [][]byte
+}
+
+func (b *bundleWrapper) Run(_ context.Context, name string, args ...string) ([]byte, []byte, error) {
+	if name != WrapperPath || len(args) != 2 || args[0] != "--plan" {
+		b.t.Fatalf("unexpected command %s %v", name, args)
+	}
+	raw, err := os.ReadFile(args[1])
+	if err != nil {
+		b.t.Fatal(err)
+	}
+	var plan map[string]any
+	_ = json.Unmarshal(raw, &plan)
+	b.plans = append(b.plans, plan)
+	body, _ := os.ReadFile(plan["bundle"].(string))
+	b.bodies = append(b.bodies, body)
+	return []byte("OSAPPLY-REPORT " + b.rep + "\n"), nil, nil
+}
+
+func serveBundle(t *testing.T, body []byte) (*httptest.Server, string) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/felhom-agent/0.143.0/"+BundleFileName {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = w.Write(body)
+	}))
+	t.Cleanup(srv.Close)
+	sum := sha256.Sum256(body)
+	return srv, hex.EncodeToString(sum[:])
+}
+
+func bundleExec(t *testing.T, w *bundleWrapper, srvURL string) (ConfigUpdateExecutor, *bool) {
+	l, _ := newLeg(t, &fakeWrapper{t: t}, nil)
+	l.Runner = w
+	called := false
+	return ConfigUpdateExecutor{Leg: l, URLTemplate: srvURL + "/felhom-agent/{version}/felhom-agent",
+		AfterInstall: func(context.Context) { called = true }}, &called
+}
+
+func signedCtx() context.Context {
+	return signedjobs.WithSignedOp(context.Background(), &reconcile.SignedOp{Blob: []byte(`{"op":"agent_config_update"}`), Sig: []byte("SIG")})
+}
+
+func params(v, sha string) json.RawMessage {
+	p, _ := json.Marshal(ConfigUpdateParams{AgentVersion: v, BundleSHA256: sha})
+	return p
+}
+
+// The courier hands the wrapper the bundle bytes it downloaded and the RAW signed envelope (the wrapper verifies both
+// itself), then runs the capability probe. Red-proof: drop "signed" from the plan → the plan check below fails.
+func TestConfigUpdate_PassesBundleAndEnvelopeToTheWrapper(t *testing.T) {
+	body := []byte(`{"format":1,"agent_version":"0.143.0","files":[]}`)
+	srv, sha := serveBundle(t, body)
+	w := &bundleWrapper{t: t, rep: `{"mode":"bundle","bundle":{"agent_version":"0.143.0","written":["/etc/sudoers.d/felhom-agent"]}}`}
+	e, called := bundleExec(t, w, srv.URL)
+	if err := e.Execute(signedCtx(), OpConfigUpdate, params("0.143.0", sha)); err != nil {
+		t.Fatal(err)
+	}
+	p := w.plans[0]
+	sg, _ := p["signed"].(map[string]any)
+	if p["mode"] != "bundle" || p["layer"] != "host" || sg == nil || sg["sig"] != "SIG" ||
+		sg["blob_b64"] != base64.StdEncoding.EncodeToString([]byte(`{"op":"agent_config_update"}`)) {
+		t.Fatalf("plan = %v", p)
+	}
+	if string(w.bodies[0]) != string(body) || !strings.HasSuffix(p["bundle"].(string), "/bundle-0.143.0.json") {
+		t.Fatalf("the wrapper got %q at %v", w.bodies[0], p["bundle"])
+	}
+	if !*called {
+		t.Fatal("the capability probe must run after an install")
+	}
+	if _, err := os.Stat(p["bundle"].(string)); !os.IsNotExist(err) {
+		t.Fatal("the downloaded bundle must be removed after the call")
+	}
+}
+
+func TestConfigUpdate_WrongShaNeverReachesTheWrapper(t *testing.T) {
+	srv, _ := serveBundle(t, []byte("tampered"))
+	w := &bundleWrapper{t: t}
+	e, called := bundleExec(t, w, srv.URL)
+	err := e.Execute(signedCtx(), OpConfigUpdate, params("0.143.0", strings.Repeat("a", 64)))
+	if err == nil || len(w.plans) != 0 || *called {
+		t.Fatalf("err=%v plans=%d", err, len(w.plans))
+	}
+}
+
+func TestConfigUpdate_RefusedAndFailedAreErrors(t *testing.T) {
+	for _, rep := range []string{`{"refused":{"code":"R17","reason":"trust root"}}`, `{"failed":{"rc":3},"bundle":{"rolled_back":["/x"]}}`} {
+		srv, sha := serveBundle(t, []byte("{}"))
+		w := &bundleWrapper{t: t, rep: rep}
+		e, called := bundleExec(t, w, srv.URL)
+		if err := e.Execute(signedCtx(), OpConfigUpdate, params("0.143.0", sha)); err == nil || *called {
+			t.Fatalf("%s: err=%v called=%v", rep, err, *called)
+		}
+	}
+}
+
+func TestConfigUpdate_GuardsBeforeAnyDownload(t *testing.T) {
+	w := &bundleWrapper{t: t}
+	e, _ := bundleExec(t, w, "http://127.0.0.1:1")
+	if err := e.Execute(signedCtx(), "agent_update", nil); !errors.Is(err, signedjobs.ErrNoExecutor) {
+		t.Fatalf("another op must pass through the chain: %v", err)
+	}
+	if err := e.Execute(context.Background(), OpConfigUpdate, params("0.143.0", strings.Repeat("a", 64))); err == nil {
+		t.Fatal("no envelope must refuse")
+	}
+	for _, p := range []json.RawMessage{params("0.143", strings.Repeat("a", 64)), params("0.143.0", "ABC"), json.RawMessage(`nope`)} {
+		if err := e.Execute(signedCtx(), OpConfigUpdate, p); err == nil {
+			t.Fatalf("bad params %s must refuse", p)
+		}
+	}
+	if len(w.plans) != 0 {
+		t.Fatal("no wrapper call on a refusal")
+	}
+}
+
+func TestBundleURL(t *testing.T) {
+	u, err := BundleURL("https://gitea.dooplex.hu/api/packages/admin/generic/felhom-agent/{version}/felhom-agent", "0.143.0")
+	if err != nil || u != "https://gitea.dooplex.hu/api/packages/admin/generic/felhom-agent/0.143.0/felhom-config-bundle.json" {
+		t.Fatalf("%s %v", u, err)
+	}
+	if _, err := BundleURL("https://example/felhom-agent-{version}.bin", "0.143.0"); err == nil {
+		t.Fatal("an underivable template must refuse")
+	}
+}
+
+func (b *bundleWrapper) RunStdin(ctx context.Context, _ io.Reader, name string, args ...string) ([]byte, []byte, error) {
+	return b.Run(ctx, name, args...)
+}

internal/osupdate/dockerjob.go

@@ -0,0 +1,91 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/signedjobs"
+)
+
+// OpDockerStep is the signed op class of a Docker engine step (`11` §5.8): a ring-1 box takes an approved engine set,
+// and every box takes an UNDO, only through it. CC may sign it until the first paying customer (R-530 ruling).
+const OpDockerStep = "os_docker_step"
+
+// DockerStepParams are the signed params. The wrapper compares Packages and Undo with the plan byte-for-byte.
+type DockerStepParams struct {
+	ReleaseID string    `json:"release_id"`
+	Packages  []Package `json:"packages"`
+	Undo      bool      `json:"undo"`
+	VMID      int       `json:"vmid,omitempty"`
+}
+
+// DockerStepExecutor runs a verified os_docker_step (signedjobs.Executor). Guest finds the box's customer guest when
+// the params name none; Gate (optional) takes the host-wide heavy-op gate so a step never runs beside a backup.
+type DockerStepExecutor struct {
+	Leg   *Leg
+	Guest func(ctx context.Context) (int, error)
+	Gate  func(ctx context.Context) (release func(), err error)
+}
+
+// Execute implements signedjobs.Executor.
+func (e DockerStepExecutor) Execute(ctx context.Context, op string, params json.RawMessage) error {
+	if op != OpDockerStep {
+		return signedjobs.ErrNoExecutor
+	}
+	so, ok := signedjobs.SignedOpFrom(ctx)
+	if !ok {
+		return fmt.Errorf("os_docker_step: no signed envelope in the context — the wrapper could not verify it")
+	}
+	var p DockerStepParams
+	if err := json.Unmarshal(params, &p); err != nil || len(p.Packages) == 0 {
+		return fmt.Errorf("os_docker_step: params must name the engine set: %v", err)
+	}
+	vmid := p.VMID
+	if vmid == 0 {
+		if e.Guest == nil {
+			return fmt.Errorf("os_docker_step: no vmid and no guest finder")
+		}
+		v, err := e.Guest(ctx)
+		if err != nil {
+			return fmt.Errorf("os_docker_step: find the customer guest: %w", err)
+		}
+		vmid = v
+	}
+	if e.Gate != nil {
+		release, err := e.Gate(ctx)
+		if err != nil {
+			return fmt.Errorf("os_docker_step: heavy-op gate busy (a backup or restore-test runs): %w", err)
+		}
+		defer release()
+	}
+	rep := e.Leg.RunDockerSigned(ctx, vmid, p, so.Blob, string(so.Sig))
+	switch rep.Outcome {
+	case "applied", "nothing":
+		if rep.Healthy {
+			return nil
+		}
+	}
+	return fmt.Errorf("os_docker_step: %s (%s) %s", rep.Outcome, rep.HealthReason, string(rep.Refused))
+}
+
+// RunDockerSigned is one signed Docker step (ring 1 or an undo): live-restore first (decision 87, a no-op when on),
+// then the docker layer with the signed envelope, which the wrapper verifies itself.
+func (l *Leg) RunDockerSigned(ctx context.Context, vmid int, p DockerStepParams, blob []byte, sig string) Report {
+	unlock := l.lockPass(true)
+	defer unlock()
+	l.sendUnsentLocked(ctx) // R-868
+	runID := l.now().UTC().Format("20060102T150405Z")
+	lg := l.log().With("run", runID, "vmid", vmid, "trigger", "signed", "release", p.ReleaseID, "undo", p.Undo)
+	if err := l.EnsureLiveRestore(ctx, runID, vmid); err != nil {
+		return l.finish(ctx, lg, Report{RunID: runID, Layer: LayerDocker, Trigger: "signed", Ring: l.Block().Ring, VMID: vmid,
+			Mode: "apply", ReleaseID: p.ReleaseID, Outcome: "failed", HealthReason: "live-restore could not be turned on: " + err.Error()})
+	}
+	rid := p.ReleaseID
+	if rid == "" {
+		rid = "signed-" + runID
+	}
+	return l.runLayer(ctx, runID, LayerDocker, vmid, "signed", l.Block(), dockerOpts{releaseID: rid, packages: p.Packages,
+		undo: p.Undo, signed: map[string]string{"blob_b64": base64.StdEncoding.EncodeToString(blob), "sig": sig}})
+}

internal/osupdate/dockerjob_test.go

@@ -0,0 +1,49 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/reconcile"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/signedjobs"
+)
+
+// The executor hands the RAW signed bytes to the wrapper (which verifies them itself) and the exact signed package
+// list. Red-proof: drop the `signed` field from the docker plan in runLayer and the plan check fails.
+func TestDockerStepExecutor_PassesTheSignedEnvelope(t *testing.T) {
+	w := &fakeWrapper{t: t, applyRep: map[string]WrapperReport{LayerDocker: {
+		Upgraded: []Package{{Name: "docker-ce", Version: "5:29.8.2-1~debian.13~trixie"}}, DockerEngine: "29.8.2", Authority: "signed"}}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 1, Enabled: true})
+	e := DockerStepExecutor{Leg: l, Guest: func(context.Context) (int, error) { return 9201, nil }}
+	params, _ := json.Marshal(DockerStepParams{ReleaseID: "os-docker-1", Packages: []Package{{Name: "docker-ce", Version: "5:29.8.2-1~debian.13~trixie", Origin: "Docker CE"}}})
+	ctx := signedjobs.WithSignedOp(context.Background(), &reconcile.SignedOp{Blob: []byte(`{"op":"os_docker_step"}`), Sig: []byte("SIG")})
+	if err := e.Execute(ctx, OpDockerStep, params); err != nil {
+		t.Fatal(err)
+	}
+	dp := w.plans[len(w.plans)-1]
+	sg, _ := dp["signed"].(map[string]any)
+	if dp["layer"] != "docker" || dp["lane"] != "slow" || dp["release_id"] != "os-docker-1" || sg == nil ||
+		sg["blob_b64"] != base64.StdEncoding.EncodeToString([]byte(`{"op":"os_docker_step"}`)) || sg["sig"] != "SIG" {
+		t.Fatalf("docker plan = %v", dp)
+	}
+	if calls(w) != "guest:live-restore-on,docker:apply" || len(h.reports) != 1 || h.reports[0].Trigger != "signed" {
+		t.Fatalf("calls=%s reports=%+v", calls(w), h.reports)
+	}
+}
+
+func TestDockerStepExecutor_RefusesWithoutEnvelopeAndPassesOtherOps(t *testing.T) {
+	w := &fakeWrapper{t: t}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 1, Enabled: true})
+	e := DockerStepExecutor{Leg: l, Guest: func(context.Context) (int, error) { return 9201, nil }}
+	if err := e.Execute(context.Background(), "agent_update", nil); !errors.Is(err, signedjobs.ErrNoExecutor) {
+		t.Fatalf("another op must pass through the chain: %v", err)
+	}
+	params, _ := json.Marshal(DockerStepParams{Packages: []Package{{Name: "docker-ce", Version: "1"}}})
+	if err := e.Execute(context.Background(), OpDockerStep, params); err == nil || len(w.plans) != 0 {
+		t.Fatalf("no envelope must refuse before any wrapper call: err=%v calls=%s", err, calls(w))
+	}
+}

internal/osupdate/leg.go

@@ -0,0 +1,759 @@
+// Package osupdate is the agent's OS-update leg (`11-os-updates.md` §8 steps 2–3, §5.8): the customer GUEST's Debian
+// fast lane (agent v0.140.0), after it in the same pass the HOST's (agent v0.141.0), and then — ring 0 only — the
+// guest's DOCKER engine set, the slow lane (agent v0.142.0; a ring-1 box takes a Docker step only inside a signed
+// operator job, DockerStepExecutor). It also reads the box's versions for the hub's System page (Facts, R-852).
+//
+// 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"
+	LayerDocker = "docker" // the guest's Docker engine set — slow lane (`11` §5.8)
+)
+
+// DockerNames are the six packages of the Docker engine set (the wrapper's DOCKER_NAMES).
+var DockerNames = map[string]bool{"containerd.io": true, "docker-buildx-plugin": true, "docker-ce": true,
+	"docker-ce-cli": true, "docker-ce-rootless-extras": true, "docker-compose-plugin": true}
+
+// 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
+	ID     string `json:"id,omitempty"`
+}
+
+// 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"`
+	// ControllerDockerOK: the controller reaches the engine from INSIDE its container (R-858, wrapper ≥ v0.142.1;
+	// nil from an older wrapper = not checked). Its own health check stayed "healthy" while it was blind.
+	ControllerDockerOK *bool             `json:"controller_docker_ok,omitempty"`
+	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"`
+	DockerEngine        string          `json:"docker_engine"`
+	Authority           string          `json:"authority"`
+	Undo                bool            `json:"undo"`
+	LiveRestore         json.RawMessage `json:"live_restore"`
+	Facts               json.RawMessage `json:"facts"`
+	Bundle              json.RawMessage `json:"bundle"` // the config bundle's result (R-840, mode "bundle")
+	// R-868 (v0.144.0): the agent's ids, echoed from the plan, so a report kept on disk can be sent without the
+	// agent process that started the pass. ReleaseID / VMID were always in the report.
+	RunID     string `json:"run_id"`
+	Trigger   string `json:"trigger"`
+	Ring      *int   `json:"ring"`
+	ReleaseID string `json:"release_id"`
+	VMID      int    `json:"vmid"`
+}
+
+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"`
+	DockerEngine        string          `json:"docker_engine,omitempty"` // docker layer: the engine after the step
+	Authority           string          `json:"authority,omitempty"`     // docker layer: ring0 | signed
+	Undo                bool            `json:"undo,omitempty"`          // docker layer: a signed undo (downgrade)
+
+	unsent string // R-868: the wrapper's kept copy of this pass's report — deleted once the hub has it
+}
+
+// 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
+}
+
+// planFile / reportFile: the plan the agent writes and the copy of the report the wrapper keeps beside it (R-868).
+func planFile(dir, runID, layer, mode string) string {
+	return filepath.Join(dir, fmt.Sprintf("plan-%s-%s-%s.json", runID, layer, mode))
+}
+
+func reportFile(dir, runID, layer, mode string) string {
+	return filepath.Join(dir, fmt.Sprintf("report-%s-%s-%s.json", runID, layer, mode))
+}
+
+func (l *Leg) planDir() string {
+	if l.PlanDir == "" {
+		return DefaultPlanDir
+	}
+	return l.PlanDir
+}
+
+// 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()
+	l.block = resp.DesiredState.OSUpdate
+	l.mu.Unlock()
+	l.saveBlock(resp.DesiredState.OSUpdate)
+}
+
+// SavedBlockFile is the hub's newest os_update block as the daemon last received it (R-866, v0.144.0): the debug
+// pass falls back to it when the hub cannot be reached, and says so.
+const SavedBlockFile = "os-update-block.json"
+
+type savedBlock struct {
+	SavedAt time.Time         `json:"saved_at"`
+	Block   *hub.WireOSUpdate `json:"block"`
+}
+
+func (l *Leg) saveBlock(b *hub.WireOSUpdate) {
+	dir := l.planDir()
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return
+	}
+	body, _ := json.Marshal(savedBlock{SavedAt: l.now().UTC(), Block: b})
+	tmp := filepath.Join(dir, SavedBlockFile+".tmp")
+	if err := os.WriteFile(tmp, body, 0o600); err == nil {
+		_ = os.Rename(tmp, filepath.Join(dir, SavedBlockFile))
+	}
+}
+
+// LoadSavedBlock reads the block the daemon saved (R-866). ok=false: none saved yet.
+func LoadSavedBlock(dir string) (b *hub.WireOSUpdate, savedAt time.Time, ok bool) {
+	raw, err := os.ReadFile(filepath.Join(dir, SavedBlockFile))
+	if err != nil {
+		return nil, time.Time{}, false
+	}
+	var s savedBlock
+	if json.Unmarshal(raw, &s) != nil {
+		return nil, time.Time{}, false
+	}
+	return s.Block, s.SavedAt, true
+}
+
+// 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 after.ControllerDockerOK != nil && !*after.ControllerDockerOK {
+		return false, "the controller cannot reach Docker (it holds an old socket — R-858)"
+	}
+	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, ""
+}
+
+// EngineOf is the engine version `docker version` prints for a docker-ce package version: "5:29.8.2-1~debian.13~trixie"
+// → "29.8.2" (no epoch, no Debian revision).
+func EngineOf(pkgVersion string) string {
+	v := pkgVersion
+	if i := strings.Index(v, ":"); i >= 0 {
+		v = v[i+1:]
+	}
+	if i := strings.Index(v, "-"); i >= 0 {
+		v = v[:i]
+	}
+	return v
+}
+
+// DockerHealthVerdict is THE Docker-step health rule (`11` §5.8; pinned by TestDockerHealthVerdict): the guest rule,
+// plus every container running at the start still runs as the SAME container (same id — a changed id means the
+// household's apps restarted, which `live-restore` exists to prevent), plus the engine now reports the version the step
+// installed (wantEngine "" = no engine change expected).
+func DockerHealthVerdict(before, after *Health, wantEngine, gotEngine string) (bool, string) {
+	if ok, why := HealthVerdict(before, after); !ok {
+		return false, why
+	}
+	if before != nil {
+		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" || b.ID == "" {
+				continue
+			}
+			if a := after.Containers[n]; a.ID != b.ID {
+				return false, n + " is a new container (id changed) — the engine step restarted it"
+			}
+		}
+	}
+	if wantEngine != "" && gotEngine != wantEngine {
+		return false, "the engine is " + gotEngine + ", not " + wantEngine
+	}
+	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 err := os.MkdirAll(dir, 0o700); err != nil {
+		return WrapperReport{}, fmt.Errorf("osupdate: plan dir: %w", err)
+	}
+	b, _ := json.Marshal(plan)
+	path := planFile(dir, runID, fmt.Sprint(plan["layer"]), fmt.Sprint(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
+}
+
+// Pass is one leg's reports; an empty Layer means the step did not run.
+type Pass struct {
+	Guest, Host, Docker Report
+}
+
+// Run is one pass: the guest layer, then (on an appliance, after a good guest step) the host layer, then (ring 0
+// only, after good earlier steps) the Docker engine set. trigger is "night" or "debug".
+func (l *Leg) Run(ctx context.Context, vmid int, trigger string) Pass {
+	unlock := l.lockPass(true)
+	defer unlock()
+	l.sendUnsentLocked(ctx) // R-868: a report a killed agent never sent goes first
+	g, h := l.runFast(ctx, vmid, trigger)
+	p := Pass{Guest: g, Host: h}
+	if g.Outcome == "skipped" {
+		return p
+	}
+	blk := l.Block()
+	okStep := func(r Report) bool {
+		return (r.Outcome == "applied" || r.Outcome == "nothing" || r.Outcome == "inventory") && r.Healthy
+	}
+	lg := l.log().With("run", g.RunID, "vmid", vmid, "trigger", trigger)
+	switch {
+	case blk.Ring != 0 || !blk.Enabled:
+		lg.Info("osupdate: docker step skipped — ring 1 takes an engine set only inside a signed operator job (`11` §5.8)", "ring", blk.Ring, "enabled", blk.Enabled)
+	case !okStep(g) || (h.Layer != "" && !okStep(h)):
+		lg.Warn("osupdate: docker step skipped — an earlier step did not end healthy")
+	default:
+		if err := l.EnsureLiveRestore(ctx, g.RunID, vmid); err != nil {
+			p.Docker = l.finish(ctx, lg, Report{RunID: g.RunID, Layer: LayerDocker, Trigger: trigger, Ring: 0, VMID: vmid,
+				Mode: "apply", Outcome: "failed", HealthReason: "live-restore could not be turned on: " + err.Error()})
+			return p
+		}
+		p.Docker = l.runLayer(ctx, g.RunID, LayerDocker, vmid, trigger, blk, dockerOpts{})
+	}
+	return p
+}
+
+// dockerOpts is a signed Docker step (DockerStepExecutor); the zero value is ring 0's unsigned "pending-docker".
+type dockerOpts struct {
+	releaseID string
+	packages  []Package
+	undo      bool
+	signed    map[string]string // blob_b64, sig — the wrapper verifies them ITSELF
+}
+
+// EnsureLiveRestore is the ONE-TIME step of `09` decision 87: the wrapper merges `"live-restore": true` into the guest's
+// daemon.json and RELOADS docker (never a restart, R-835). A no-op when it is already on.
+func (l *Leg) EnsureLiveRestore(ctx context.Context, runID string, vmid int) error {
+	wr, err := l.call(ctx, runID, map[string]any{"release_id": "live-restore", "layer": LayerGuest, "lane": "fast",
+		"vmid": vmid, "mode": "live-restore-on", "packages": []Package{}})
+	if err != nil {
+		return err
+	}
+	if wr.refused() {
+		return fmt.Errorf("refused: %s", wr.Refused)
+	}
+	if wr.failed() {
+		return fmt.Errorf("failed: %s", wr.Failed)
+	}
+	l.log().Info("osupdate: live-restore", "vmid", vmid, "result", string(wr.LiveRestore))
+	return nil
+}
+
+// Facts reads the box's versions through the wrapper's read-only facts mode (R-852): host Debian, kernels, held
+// packages, taint, the crash guard; guest Debian, Docker engine, containerd, live-restore. Raw JSON, the wrapper's shape.
+func (l *Leg) Facts(ctx context.Context, vmid int) (json.RawMessage, error) {
+	wr, err := l.call(ctx, "facts"+l.now().UTC().Format("150405"), map[string]any{"release_id": "facts", "layer": LayerHost,
+		"lane": "fast", "vmid": vmid, "mode": "facts", "packages": []Package{}})
+	if err != nil {
+		return nil, err
+	}
+	if wr.refused() {
+		return nil, fmt.Errorf("facts refused: %s", wr.Refused)
+	}
+	if len(wr.Facts) == 0 {
+		return nil, fmt.Errorf("facts: the wrapper returned none (an older wrapper?)")
+	}
+	return wr.Facts, nil
+}
+
+// runFast is the guest + host fast lane (agent v0.141.x behaviour).
+func (l *Leg) runFast(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, dockerOpts{})
+	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, dockerOpts{})
+	}
+	return guest, host
+}
+
+func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigger string, blk hub.WireOSUpdate, do dockerOpts) Report {
+	rel := hub.WireOSRelease{ID: "ring0-" + runID}
+	var wire *hub.WireOSRelease
+	switch layer {
+	case LayerGuest:
+		wire = blk.Release
+	case LayerHost:
+		wire = blk.HostRelease
+	}
+	lane := "fast"
+	if layer == LayerDocker {
+		lane = "slow"
+		if do.signed != nil {
+			rel = hub.WireOSRelease{ID: do.releaseID}
+		}
+	} else 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": lane, "vmid": vmid, "snapshot": rel.Snapshot,
+		"packages": []Package{}, "mode": "apply", "select": "listed",
+		"run_id": runID, "trigger": trigger, "ring": blk.Ring} // R-868: echoed into the wrapper's kept copy
+	if rel.ID == "" {
+		plan["release_id"] = "none"
+	}
+	planned := map[string]bool{}
+	switch {
+	case layer == LayerDocker && do.signed != nil:
+		plan["packages"], plan["signed"] = do.packages, do.signed
+		if do.undo {
+			plan["undo"] = true
+		}
+		for _, p := range do.packages {
+			planned[p.Name] = true
+		}
+	case layer == LayerDocker:
+		plan["select"] = "pending-docker" // ring 0: the wrapper checks the box's ROOT-OWNED ring-0 mark itself
+	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)
+	if rep.Mode == "apply" {
+		rep.unsent = reportFile(l.planDir(), runID, layer, rep.Mode) // the wrapper kept a copy (R-868)
+	}
+	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
+	rep.DockerEngine, rep.Authority, rep.Undo = wr.DockerEngine, wr.Authority, wr.Undo
+	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
+	wantEngine := ""
+	for _, u := range wr.Upgraded {
+		if u.Name == "docker-ce" {
+			wantEngine = EngineOf(u.Version)
+		}
+	}
+	verdict := func(h *Health) (bool, string) {
+		if layer == LayerDocker {
+			return DockerHealthVerdict(wr.HealthBefore, h, wantEngine, wr.DockerEngine)
+		}
+		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": lane, "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
+	if layer == LayerDocker {
+		// the docker report carries the engine set only (the guest report already carries the Debian packages)
+		rep.Installed, rep.Pending = onlyDocker(wr.Installed), onlyDockerPending(wr.Pending)
+		rep.NotCovered = nil
+	} else {
+		rep.NotCovered = notCovered(wr.Pending, blk.Ring, planned)
+	}
+	return l.finish(ctx, lg, rep)
+}
+
+func onlyDocker(in []Package) []Package {
+	var out []Package
+	for _, p := range in {
+		if DockerNames[p.Name] {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+func onlyDockerPending(in []Pending) []Pending {
+	var out []Pending
+	for _, p := range in {
+		if DockerNames[p.Name] {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// 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; the kept copy is sent at the next start or pass)", "err", err)
+		} else if rep.unsent != "" {
+			if rerr := os.Remove(rep.unsent); rerr != nil && !os.IsNotExist(rerr) {
+				lg.Warn("osupdate: could not delete the sent report's kept copy (it may be sent twice)", "path", rep.unsent, "err", rerr)
+			}
+		}
+	}
+	return rep
+}

internal/osupdate/leg_test.go

@@ -0,0 +1,506 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"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
+	keep      bool // R-868: like the real wrapper, keep an apply report beside the plan
+}
+
+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
+		}
+	}
+	if f.keep && plan["mode"] == "apply" {
+		kept := rep
+		kept.Layer, kept.RunID, _ = layer, fmt.Sprint(plan["run_id"]), 0
+		if tr, ok := plan["trigger"].(string); ok {
+			kept.Trigger = tr
+		}
+		if r, ok := plan["ring"].(float64); ok {
+			ri := int(r)
+			kept.Ring = &ri
+		}
+		kb, _ := json.Marshal(kept)
+		dst := filepath.Join(filepath.Dir(args[1]), "report-"+strings.TrimPrefix(filepath.Base(args[1]), "plan-"))
+		if err := os.WriteFile(dst, kb, 0o600); err != nil {
+			f.t.Fatal(err)
+		}
+	}
+	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 := run2(l, "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,guest:live-restore-on,docker:apply" {
+		t.Fatalf("calls = %s, want one apply per layer, guest first, then live-restore and the ring-0 docker step", calls(w))
+	}
+	for _, p := range w.plans[:2] {
+		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) != 3 || h.reports[0].Layer != LayerGuest || h.reports[1].Layer != LayerHost || h.reports[2].Layer != LayerDocker {
+		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 := run2(l, "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 := run2(l, "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, _ := run2(l, "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 := run2(l, "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 := run2(l, "night")
+	// the guest (and so its Docker engine) is ours on a BYO box too: only the HOST is the owner's
+	if ho.Outcome != "" || calls(w) != "guest:apply,guest:live-restore-on,docker:apply" || len(h.reports) != 2 {
+		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 := run2(l, "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 := run2(l, "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, _ := run2(l, "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 := run2(l, "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})
+	run2(l, "night")
+	n := len(w.plans)
+	if g, _ := run2(l, "night"); g.Outcome != "skipped" || len(w.plans) != n {
+		t.Fatalf("a second night run in the same night ran: %+v", g)
+	}
+	if g, _ := run2(l, "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")
+	}
+	// the OS wrapper and (agent v0.142.0) the crash guard — both root programs in configs/ with their own suites
+	for _, suite := range []string{"../../configs/test_felhom_os_apply.py", "../../configs/test_felhom_crash_guard.py", "../../configs/test_felhom_config_bundle.py"} {
+		cmd := exec.Command(py, "-B", suite)
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("%s failed: %v\n%s", suite, err, out)
+		}
+		if !strings.Contains(string(out), "OK") {
+			t.Fatalf("%s did not report OK:\n%s", suite, 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})
+	run2(l, "night")
+	if len(h.reports) != 3 || !h.reports[1].RebootScanned || !h.reports[1].RebootNeeded || h.reports[0].RebootScanned {
+		t.Fatalf("hub got %+v", h.reports)
+	}
+}
+
+// run2 is the guest + host reports of one pass (the tests written before the docker step).
+func run2(l *Leg, trigger string) (Report, Report) {
+	p := l.Run(context.Background(), 9201, trigger)
+	return p.Guest, p.Host
+}
+
+// ---- the Docker step (`11` §5.8, agent v0.142.0) ----
+
+// Ring 1 never takes an engine step in the night leg — only inside a signed operator job. Red-proof: drop the
+// `blk.Ring != 0` case in Run and the ring-1 pass makes a docker call.
+func TestDocker_Ring1NightLegNeverSteps(t *testing.T) {
+	w := &fakeWrapper{t: t}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 1, Enabled: true})
+	p := l.Run(context.Background(), 9201, "night")
+	if p.Docker.Layer != "" || strings.Contains(calls(w), "docker") || strings.Contains(calls(w), "live-restore") {
+		t.Fatalf("ring 1 took a docker step: %s", calls(w))
+	}
+}
+
+// An unhealthy earlier step skips the docker step.
+func TestDocker_SkippedAfterAnUnhealthyStep(t *testing.T) {
+	w := &fakeWrapper{t: t, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6"}}}},
+		healthSeq: map[string][]*Health{}}
+	bad := guestOK()
+	bad.Controller = "unhealthy"
+	w.applyRep[LayerGuest] = WrapperReport{Upgraded: []Package{{Name: "libc6"}}, HealthAfter: bad}
+	w.healthSeq[LayerGuest] = []*Health{bad, bad, bad, bad, bad, bad, bad, bad}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	p := l.Run(context.Background(), 9201, "night")
+	if p.Docker.Layer != "" || strings.Contains(calls(w), "docker") {
+		t.Fatalf("docker step ran after an unhealthy guest step: %s", calls(w))
+	}
+}
+
+// The docker plan is the slow lane, pending-docker for ring 0; the report carries only the engine set.
+func TestDocker_Ring0PlanAndReport(t *testing.T) {
+	w := &fakeWrapper{t: t, applyRep: map[string]WrapperReport{LayerDocker: {
+		Upgraded:     []Package{{Name: "docker-ce", Version: "5:29.8.2-1~debian.13~trixie"}},
+		Installed:    []Package{{Name: "docker-ce", Version: "5:29.8.2-1~debian.13~trixie", Origin: "Docker"}, {Name: "libc6", Version: "u4", Origin: "Debian"}},
+		DockerEngine: "29.8.2", Authority: "ring0"}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	p := l.Run(context.Background(), 9201, "night")
+	dp := w.plans[len(w.plans)-1]
+	if dp["layer"] != "docker" || dp["lane"] != "slow" || dp["select"] != "pending-docker" {
+		t.Fatalf("docker plan = %v", dp)
+	}
+	d := p.Docker
+	if d.Outcome != "applied" || !d.Healthy || d.DockerEngine != "29.8.2" || len(d.Installed) != 1 || d.Installed[0].Name != "docker-ce" {
+		t.Fatalf("docker report = %+v", d)
+	}
+}
+
+// THE docker health rule. Red-proof: drop the id comparison (or the engine check) in DockerHealthVerdict and a case fails.
+func TestDockerHealthVerdict(t *testing.T) {
+	before := guestOK()
+	before.Containers = map[string]Container{"felhom-controller": {State: "running", Health: "healthy", ID: "a"},
+		"app": {State: "running", Health: "healthy", ID: "b"}}
+	same := guestOK()
+	same.Containers = map[string]Container{"felhom-controller": {State: "running", Health: "healthy", ID: "a"},
+		"app": {State: "running", Health: "healthy", ID: "b"}}
+	moved := guestOK()
+	moved.Containers = map[string]Container{"felhom-controller": {State: "running", Health: "healthy", ID: "a"},
+		"app": {State: "running", Health: "healthy", ID: "c"}}
+	if ok, why := DockerHealthVerdict(before, same, "29.8.2", "29.8.2"); !ok {
+		t.Fatalf("same ids, right engine: %s", why)
+	}
+	if ok, _ := DockerHealthVerdict(before, moved, "29.8.2", "29.8.2"); ok {
+		t.Fatal("a changed container id passed — live-restore failed and the apps restarted")
+	}
+	if ok, _ := DockerHealthVerdict(before, same, "29.8.2", "29.7.2"); ok {
+		t.Fatal("the engine did not move and the step passed")
+	}
+	if EngineOf("5:29.8.2-1~debian.13~trixie") != "29.8.2" {
+		t.Fatalf("EngineOf = %q", EngineOf("5:29.8.2-1~debian.13~trixie"))
+	}
+}
+
+// A changed id after the step → health_failed (the consequence, not only the verdict).
+func TestDocker_ChangedIDIsHealthFailed(t *testing.T) {
+	before := guestOK()
+	before.Containers = map[string]Container{"felhom-controller": {State: "running", Health: "healthy", ID: "a"}}
+	after := guestOK()
+	after.Containers = map[string]Container{"felhom-controller": {State: "running", Health: "healthy", ID: "z"}}
+	w := &fakeWrapper{t: t, applyRep: map[string]WrapperReport{LayerDocker: {
+		Upgraded: []Package{{Name: "docker-ce", Version: "5:29.8.2-1"}}, DockerEngine: "29.8.2",
+		HealthBefore: before, HealthAfter: after}}, healthSeq: map[string][]*Health{}}
+	w.healthSeq[LayerDocker] = []*Health{after, after, after, after, after, after, after, after}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	p := l.Run(context.Background(), 9201, "night")
+	if p.Docker.Outcome != "health_failed" || !strings.Contains(p.Docker.HealthReason, "id changed") {
+		t.Fatalf("docker = %+v", p.Docker)
+	}
+}
+
+// R-858: a controller that cannot reach Docker fails the health rule even though its own check says healthy.
+// Red-proof: drop the ControllerDockerOK check in HealthVerdict and this fails.
+func TestHealthVerdict_ControllerBlindToDockerFails(t *testing.T) {
+	no, yes2 := false, true
+	after := guestOK()
+	after.ControllerDockerOK = &no
+	if ok, why := HealthVerdict(guestOK(), after); ok || !strings.Contains(why, "R-858") {
+		t.Fatalf("a blind controller passed: %v %q", ok, why)
+	}
+	if ok, _ := DockerHealthVerdict(guestOK(), after, "", ""); ok {
+		t.Fatal("the Docker rule passed a blind controller")
+	}
+	after.ControllerDockerOK = &yes2
+	if ok, why := HealthVerdict(guestOK(), after); !ok {
+		t.Fatalf("a seeing controller failed: %s", why)
+	}
+	if ok, _ := HealthVerdict(guestOK(), guestOK()); !ok {
+		t.Fatal("an older wrapper (no field) must not fail")
+	}
+}

internal/osupdate/unsent.go

@@ -0,0 +1,197 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// ── R-868 (v0.144.0): a pass whose agent was killed still reports ─────────────────────────────────────
+//
+// MEASURED 2026-10-05 02:57 UTC on demo-hp (night drill A5): the debug pass and the agent daemon were kill -9-ed while
+// apt-get ran. The root wrapper (its own process under sudo) finished all six packages, but the agent that would have
+// read its stdout and posted the report was gone; the hub never learned what the pass installed.
+//
+// THE MECHANISM: the wrapper writes its apply report to <plan dir>/report-<run>-<layer>-apply.json BEFORE printing
+// it (configs/felhom-os-apply save_report). The agent deletes that copy once the hub has the report (finish). A copy
+// still on disk is a report nobody sent: SendUnsent posts it — at the agent's start, and before every pass — and then
+// deletes it. A pass lock (flock on <plan dir>/pass.lock, released by the kernel when a process dies) keeps the
+// sender from picking up the copy of a pass that is still running, also across the daemon and a selftest process.
+// Pinned by TestR868_* (unsent_test.go).
+
+// lockPass takes the pass lock. block=false returns ok=false at once when another pass holds it. A lock that cannot
+// be opened at all (no plan dir yet) does not stop a pass: the unlock is then a no-op.
+func (l *Leg) lockPass(block bool) (unlock func()) {
+	u, _ := l.tryLockPass(block)
+	return u
+}
+
+func (l *Leg) tryLockPass(block bool) (unlock func(), ok bool) {
+	dir := l.planDir()
+	_ = os.MkdirAll(dir, 0o700)
+	f, err := os.OpenFile(filepath.Join(dir, "pass.lock"), os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		l.log().Warn("osupdate: pass lock unavailable — continuing without it", "err", err)
+		return func() {}, true
+	}
+	how := syscall.LOCK_EX
+	if !block {
+		how |= syscall.LOCK_NB
+	}
+	if err := syscall.Flock(int(f.Fd()), how); err != nil {
+		f.Close()
+		return func() {}, false
+	}
+	return func() { _ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN); f.Close() }, true
+}
+
+// SendUnsent posts every report a pass kept on disk and nobody sent (R-868). It skips when a pass runs now (that
+// pass sends them first). Called at the agent's start.
+func (l *Leg) SendUnsent(ctx context.Context) int {
+	unlock, ok := l.tryLockPass(false)
+	if !ok {
+		l.log().Info("osupdate: a pass is running — its start sends any kept report")
+		return 0
+	}
+	defer unlock()
+	return l.sendUnsentLocked(ctx)
+}
+
+// SendUnsentLoop runs SendUnsent now and then every `every` until ctx ends (v0.144.1). MEASURED live on demo-hp
+// 2026-10-05: after a kill -9 the daemon restarted in ~5 s, while the orphaned root wrapper was still installing — its
+// copy appeared ~7 s AFTER the start-time sender had looked. One look at start is therefore not enough. A glob of the
+// plan dir every few minutes costs nothing; the pass lock keeps it off a running pass. Pinned by
+// TestR868_ACopyWrittenAfterTheStartIsSentByTheLoop.
+func (l *Leg) SendUnsentLoop(ctx context.Context, every time.Duration, onSent func(int)) {
+	for {
+		if n := l.SendUnsent(ctx); n > 0 && onSent != nil {
+			onSent(n)
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(every):
+		}
+	}
+}
+
+func (l *Leg) sendUnsentLocked(ctx context.Context) int {
+	if l.Hub == nil {
+		return 0 // nobody to send to: keep the copies for a process that has the hub
+	}
+	files, _ := filepath.Glob(filepath.Join(l.planDir(), "report-*.json"))
+	sent := 0
+	for _, f := range files {
+		b, err := os.ReadFile(f)
+		if err != nil {
+			l.log().Warn("osupdate: a kept report cannot be read", "path", f, "err", err)
+			continue
+		}
+		var wr WrapperReport
+		if err := json.Unmarshal(b, &wr); err != nil || wr.Layer == "" {
+			l.log().Warn("osupdate: a kept report is not a report — moved aside", "path", f, "err", err)
+			_ = os.Rename(f, f+".bad")
+			continue
+		}
+		rep := l.reportFromKept(ctx, wr, f)
+		lg := l.log().With("run", rep.RunID, "layer", rep.Layer, "vmid", rep.VMID, "ring", rep.Ring, "trigger", rep.Trigger)
+		lg.Info("osupdate: sending a kept report late (the agent was stopped mid-pass or the hub was away, R-868)", "path", f)
+		before := rep.unsent
+		_ = l.finish(ctx, lg, rep)
+		if _, err := os.Stat(before); os.IsNotExist(err) {
+			sent++
+			// the pass's plan file is left behind too when the agent was killed inside call()
+			_ = os.Remove(filepath.Join(filepath.Dir(f), "plan-"+strings.TrimPrefix(filepath.Base(f), "report-")))
+		}
+	}
+	return sent
+}
+
+// reportFromKept builds the hub report from a kept wrapper report, as runLayer would have. Health: the copy's own
+// before/after reading; when that is not healthy after an install, one fresh reading (services restart after an
+// install, and the pass that would have waited for them is gone).
+func (l *Leg) reportFromKept(ctx context.Context, wr WrapperReport, path string) Report {
+	ring := 1
+	if wr.Ring != nil {
+		ring = *wr.Ring
+	}
+	runID, trigger := wr.RunID, wr.Trigger
+	if runID == "" {
+		runID = strings.TrimSuffix(strings.TrimPrefix(filepath.Base(path), "report-"), ".json")
+	}
+	if trigger == "" {
+		trigger = "unknown"
+	}
+	rep := Report{RunID: runID, Layer: wr.Layer, Trigger: trigger, Mode: wr.Mode, Ring: ring, ReleaseID: wr.ReleaseID,
+		VMID: wr.VMID, unsent: path}
+	prefix := "sent late — kept on the box until the hub could take it (R-868, R-875)"
+	switch {
+	case wr.refused():
+		rep.Outcome, rep.Refused, rep.HealthReason = "refused", wr.Refused, prefix
+		return rep
+	case wr.failed():
+		rep.Outcome, rep.Refused = "failed", wr.Failed
+	case len(wr.Upgraded) == 0:
+		rep.Outcome = "nothing"
+	default:
+		rep.Outcome = "applied"
+	}
+	rep.Upgraded, rep.PassSeconds = wr.Upgraded, wr.PassSeconds
+	rep.DockerEngine, rep.Authority, rep.Undo = wr.DockerEngine, wr.Authority, wr.Undo
+	wantEngine := ""
+	for _, u := range wr.Upgraded {
+		if u.Name == "docker-ce" {
+			wantEngine = EngineOf(u.Version)
+		}
+	}
+	verdict := func(h *Health) (bool, string) {
+		switch wr.Layer {
+		case LayerDocker:
+			return DockerHealthVerdict(wr.HealthBefore, h, wantEngine, wr.DockerEngine)
+		case LayerHost:
+			t := hub.TunnelUnknown
+			if l.Tunnel != nil {
+				t, _ = l.Tunnel.Status(ctx)
+			}
+			return HostHealthVerdict(wr.HealthBefore, h, t)
+		}
+		return HealthVerdict(wr.HealthBefore, h)
+	}
+	ok, why := verdict(wr.HealthAfter)
+	if !ok && len(wr.Upgraded) > 0 && wr.VMID > 0 {
+		lane := "fast"
+		if wr.Layer == LayerDocker {
+			lane = "slow"
+		}
+		if hr, err := l.call(ctx, "kept-"+runID, map[string]any{"release_id": "kept", "layer": wr.Layer, "lane": lane,
+			"vmid": wr.VMID, "mode": "health", "packages": []Package{}}); err == nil && hr.Health != nil {
+			ok, why = verdict(hr.Health)
+		}
+	}
+	rep.Healthy, rep.HealthReason = ok, prefix
+	if why != "" {
+		rep.HealthReason = prefix + ": " + why
+	}
+	if !ok && rep.Outcome == "applied" {
+		rep.Outcome = "health_failed"
+	}
+	rep.Installed, rep.Pending = wr.Installed, wr.Pending
+	rep.RestartNeeded, rep.DockerRestartNeeded, rep.RebootNeeded = wr.RestartNeeded, wr.DockerRestartNeeded, wr.RebootNeeded
+	rep.RebootScanned = wr.RebootScanned
+	if wr.Layer == LayerDocker {
+		rep.Installed, rep.Pending = onlyDocker(wr.Installed), onlyDockerPending(wr.Pending)
+	} else {
+		planned := map[string]bool{}
+		for _, u := range wr.Upgraded {
+			planned[u.Name] = true
+		}
+		rep.NotCovered = notCovered(wr.Pending, ring, planned)
+	}
+	return rep
+}

internal/osupdate/unsent_test.go

@@ -0,0 +1,152 @@
+package osupdate
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
+)
+
+// R-868 (v0.144.0). THE NIGHT'S SHAPE (A5, demo-hp 2026-10-05 02:57 UTC): the wrapper finished six packages, the agent
+// was kill -9-ed before it read the report; the hub never got it. Here: the wrapper's kept copy and the plan file are
+// on disk, a NEW agent process starts — it must send exactly one `applied` report and delete both files.
+// COMPANION RED-PROOF: drop the SendUnsent body (return 0) → "the hub got no report".
+func TestR868_KilledPassIsReportedAtStart(t *testing.T) {
+	w := &fakeWrapper{t: t}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	ring := 0
+	kept := WrapperReport{Mode: "apply", Layer: LayerGuest, RunID: "20261005T025700Z", Trigger: "debug", Ring: &ring, VMID: 9201,
+		ReleaseID: "ring0-20261005T025700Z", HealthBefore: guestOK(), HealthAfter: guestOK(),
+		Upgraded: []Package{{Name: "libc6", Version: "u4"}, {Name: "openssl", Version: "u3"}}}
+	b, _ := json.Marshal(kept)
+	rp := reportFile(l.PlanDir, kept.RunID, LayerGuest, "apply")
+	pp := planFile(l.PlanDir, kept.RunID, LayerGuest, "apply")
+	must(t, os.WriteFile(rp, b, 0o600))
+	must(t, os.WriteFile(pp, []byte("{}"), 0o600))
+	if n := l.SendUnsent(context.Background()); n != 1 {
+		t.Fatalf("sent %d, want 1", n)
+	}
+	if len(h.reports) != 1 {
+		t.Fatalf("the hub got no report (or several): %+v", h.reports)
+	}
+	r := h.reports[0]
+	if r.Outcome != "applied" || !r.Healthy || r.Trigger != "debug" || r.RunID != kept.RunID || r.Ring != 0 || len(r.Upgraded) != 2 || r.VMID != 9201 {
+		t.Fatalf("report = %+v", r)
+	}
+	// R-875 (v0.145.0): neutral — the copy cannot tell a killed agent from an absent hub.
+	if !strings.HasPrefix(r.HealthReason, "sent late") || strings.Contains(r.HealthReason, "stopped mid-pass") {
+		t.Fatalf("health_reason = %q, want the neutral \"sent late …\"", r.HealthReason)
+	}
+	for _, p := range []string{rp, pp} {
+		if _, err := os.Stat(p); !os.IsNotExist(err) {
+			t.Fatalf("%s still on disk after the hub got it", filepath.Base(p))
+		}
+	}
+	// a second start sends nothing again — no duplicate report
+	if n := l.SendUnsent(context.Background()); n != 0 || len(h.reports) != 1 {
+		t.Fatalf("sent again: %d, reports %d", n, len(h.reports))
+	}
+}
+
+// A normal pass: the hub gets ONE report per layer and the kept copies are gone after it (nothing resent later).
+// COMPANION RED-PROOF: drop the os.Remove(rep.unsent) in finish → the next pass resends → "2 guest reports".
+func TestR868_NormalPassLeavesNoCopyAndNoDuplicate(t *testing.T) {
+	w := &fakeWrapper{t: t, keep: true, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6", Version: "u4"}}}}}
+	l, h := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Run(context.Background(), 9201, "debug")
+	left, _ := filepath.Glob(filepath.Join(l.PlanDir, "report-*.json"))
+	if len(left) != 0 {
+		t.Fatalf("kept copies left after the hub got them: %v", left)
+	}
+	l.Run(context.Background(), 9201, "debug") // the next pass sends kept copies first
+	guest := 0
+	for _, r := range h.reports {
+		if r.Layer == LayerGuest && r.Outcome == "applied" {
+			guest++
+		}
+	}
+	if guest != 2 {
+		t.Fatalf("%d guest reports for 2 passes (a duplicate or a loss)", guest)
+	}
+}
+
+type failingHub struct{ n int }
+
+func (h *failingHub) PostOSReport(context.Context, []byte) error {
+	h.n++
+	return errors.New("hub away")
+}
+
+// The hub away: the copy stays, and goes at the next chance.
+func TestR868_HubAwayKeepsTheCopy(t *testing.T) {
+	w := &fakeWrapper{t: t, keep: true, applyRep: map[string]WrapperReport{LayerGuest: {Upgraded: []Package{{Name: "libc6", Version: "u4"}}}}}
+	l, _ := newLeg(t, w, &hub.WireOSUpdate{Ring: 0, Enabled: true})
+	l.Appliance = false
+	l.Hub = &failingHub{}
+	l.Run(context.Background(), 9201, "night")
+	left, _ := filepath.Glob(filepath.Join(l.PlanDir, "report-*.json"))
+	if len(left) != 2 { // ring 0: the guest step and the Docker step each kept one
+		t.Fatalf("the copies must stay while the hub is away: %v", left)
+	}
+	h := &fakeHub{}
+	l.Hub = h
+	if n := l.SendUnsent(context.Background()); n != 2 {
+		t.Fatalf("sent %d: %+v", n, h.reports)
+	}
+	for _, r := range h.reports {
+		if r.Trigger != "night" || r.Ring != 0 {
+			t.Fatalf("the kept report lost its ids: %+v", r)
+		}
+	}
+}
+
+// A pass in progress holds the lock: the sender at start must not take that pass's copy (it would be sent twice).
+func TestR868_RunningPassKeepsTheSenderOff(t *testing.T) {
+	w := &fakeWrapper{t: t}
+	l, h := newLeg(t, w, nil)
+	must(t, os.WriteFile(reportFile(l.PlanDir, "r1", LayerGuest, "apply"), []byte(`{"mode":"apply","layer":"guest"}`), 0o600))
+	unlock := l.lockPass(true)
+	if n := l.SendUnsent(context.Background()); n != 0 || len(h.reports) != 0 {
+		t.Fatalf("sent while a pass ran: %d", n)
+	}
+	unlock()
+	if n := l.SendUnsent(context.Background()); n != 1 {
+		t.Fatalf("not sent after the pass: %d", n)
+	}
+}
+
+// v0.144.1 — THE LIVE SHAPE (demo-hp 2026-10-05 05:45 UTC): the restarted daemon looked at 05:45:09, the orphaned
+// wrapper wrote its copy at ~05:45:16. The loop must still send it.
+// COMPANION RED-PROOF: make SendUnsentLoop return after the first look → "the late copy was never sent".
+func TestR868_ACopyWrittenAfterTheStartIsSentByTheLoop(t *testing.T) {
+	w := &fakeWrapper{t: t}
+	l, h := newLeg(t, w, nil)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	sent := make(chan int, 4)
+	go l.SendUnsentLoop(ctx, 20*time.Millisecond, func(n int) { sent <- n })
+	time.Sleep(50 * time.Millisecond) // the start-time look found nothing
+	must(t, os.WriteFile(reportFile(l.PlanDir, "late", LayerGuest, "apply"),
+		[]byte(`{"mode":"apply","layer":"guest","run_id":"late","trigger":"debug","ring":0,"vmid":9201,"upgraded":[{"name":"openssl","version":"u3"}]}`), 0o600))
+	select {
+	case n := <-sent:
+		if n != 1 || len(h.reports) != 1 || h.reports[0].RunID != "late" || h.reports[0].Outcome == "" {
+			t.Fatalf("sent %d: %+v", n, h.reports)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("the late copy was never sent")
+	}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}

internal/reconcile/classify.go

@@ -47,6 +47,14 @@ const (
 	// Destructive for unknown classes — this named constant documents the class and keeps the
 	// signed-op vocabulary explicit, it does not (and must not) loosen anything.
 	ClassAgentUpdate OpClass = "agent_update"
+
+	// A Docker engine step in the customer guest (agent v0.142.0, `11` §5.8) — ring 1, and every undo. Destructive-class
+	// (signed, operational key) like agent_update; the root wrapper re-verifies the same signature itself.
+	ClassOSDockerStep OpClass = "os_docker_step"
+
+	// The config bundle (agent v0.143.0, R-840, `11` §5.4.2): the box's ROOT-OWNED files (sudoers, wrappers, units).
+	// Destructive-class (signed, operational key) like agent_update; the root wrapper re-verifies the signature itself.
+	ClassAgentConfigUpdate OpClass = "agent_config_update"
 )
 
 // Disposition is the classifier verdict.
@@ -115,7 +123,7 @@ func Classify(class OpClass, prov Provenance) Disposition {
 		return Destructive
 	case ClassKeyRotation:
 		return Destructive
-	case ClassAgentUpdate:
+	case ClassAgentUpdate, ClassOSDockerStep, ClassAgentConfigUpdate:
 		// Never benign — no agent-internal provenance can make replacing the agent binary
 		// unsigned-safe (a compromised process must not be able to self-bless an update).
 		return Destructive

internal/signedjobs/runner.go

@@ -49,6 +49,21 @@ type Executor interface {
 	Execute(ctx context.Context, op string, params json.RawMessage) error
 }
 
+type signedOpKey struct{}
+
+// WithSignedOp / SignedOpFrom carry the RAW verified envelope (blob bytes + armored signature) to an executor whose
+// ROOT half verifies it AGAIN against a root-owned key file (agent v0.142.0, the Docker slow lane: the agent's own
+// config is agent-writable, so a root wrapper must not take the agent's word for a signature).
+func WithSignedOp(ctx context.Context, s *reconcile.SignedOp) context.Context {
+	return context.WithValue(ctx, signedOpKey{}, s)
+}
+
+// SignedOpFrom returns the envelope set by WithSignedOp.
+func SignedOpFrom(ctx context.Context) (*reconcile.SignedOp, bool) {
+	s, ok := ctx.Value(signedOpKey{}).(*reconcile.SignedOp)
+	return s, ok && s != nil
+}
+
 // ErrNoExecutor signals an op class with no executor wired in this build (don't clear the job).
 var ErrNoExecutor = fmt.Errorf("signedjobs: no executor for this op class in this build")
 
@@ -158,7 +173,7 @@ func (r *Runner) processJob(ctx context.Context, j hub.JobWire) bool {
 	// Allowed: the nonce is already durably burned (Verify, before this point). Execute.
 	r.logger.Warn("signedjobs: AUTHORIZED signed op — executing",
 		"job", j.JobID, "op", ob.Op, "key_id", dec.Verified.KeyID, "nonce", dec.Verified.Nonce)
-	err := r.exec.Execute(ctx, ob.Op, ob.Params)
+	err := r.exec.Execute(WithSignedOp(ctx, signed), ob.Op, ob.Params)
 	switch {
 	case err == nil:
 		r.logger.Warn("signedjobs: signed op COMPLETED", "job", j.JobID, "op", ob.Op)

scripts/build-config-bundle.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""build-config-bundle.py — build the agent's CONFIG BUNDLE (R-840, `11` §5.4.2).
+
+Usage:  python3 scripts/build-config-bundle.py <agent-version> <out.json>     (prints the bundle's sha256)
+
+The bundle is every root-owned file the installer's step 5 writes for the agent (sudoers, wrappers, units), as ONE
+JSON file published beside the binary (felhom-agent/<version>/felhom-config-bundle.json). A box takes it by a signed
+`agent_config_update` job; a new box takes the SAME file from the installer. The list of files is NOT kept here: it is
+`BUNDLE_FILES` in configs/felhom-os-apply, the root wrapper that installs it — one table, so the builder cannot put in a
+path the wrapper would refuse, nor leave out one it expects.
+
+Reproducible by construction: no timestamps, sorted keys, the table's order. The same source at the same version gives
+the same sha256 every time (pinned by configs/test_felhom_config_bundle.py).
+"""
+import base64
+import hashlib
+import importlib.machinery
+import importlib.util
+import json
+import pathlib
+import re
+import sys
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+CONFIGS = REPO / "configs"
+
+
+def load_wrapper(configs=CONFIGS):
+    loader = importlib.machinery.SourceFileLoader("osapply_for_bundle", str(configs / "felhom-os-apply"))
+    spec = importlib.util.spec_from_loader("osapply_for_bundle", loader)
+    mod = importlib.util.module_from_spec(spec)
+    loader.exec_module(mod)
+    return mod
+
+
+def build(version, configs=CONFIGS):
+    if not re.match(r"^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$", version):
+        raise SystemExit(f"build-config-bundle: version {version!r} is not semver")
+    w = load_wrapper(configs)
+    files = []
+    for dest, src, mode, check, policy in w.BUNDLE_FILES:
+        data = (configs / src).read_bytes()
+        files.append({"path": dest, "source": f"configs/{src}", "mode": oct(mode), "check": check, "policy": policy,
+                      "sha256": hashlib.sha256(data).hexdigest(), "content_b64": base64.b64encode(data).decode()})
+    body = {"format": w.BUNDLE_FORMAT, "agent_version": version, "files": files}
+    return (json.dumps(body, indent=1, sort_keys=True) + "\n").encode()
+
+
+def main(argv):
+    if len(argv) != 3:
+        print(__doc__, file=sys.stderr)
+        return 2
+    data = build(argv[1])
+    pathlib.Path(argv[2]).write_bytes(data)
+    print(hashlib.sha256(data).hexdigest())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

scripts/release-agent.sh

@@ -100,6 +100,15 @@ built_ver="$("$BIN" --version 2>/dev/null | awk '{print $2}')"
 BUILT_SHA="$(sha256sum "$BIN" | awk '{print $1}')"
 log "built ok: sha256 $BUILT_SHA"
 
+# ── 3b. The config bundle (R-840) ───────────────────────────────────────────────────────────────
+# Every root-owned file the installer's step 5 writes (sudoers, wrappers, units), as ONE file beside the binary. A box
+# takes it by a signed agent_config_update; a new box from the installer. Reproducible: same source → same sha.
+BUNDLE="$(mktemp -t felhom-config-bundle-XXXXXX)"
+trap 'rm -f "$BIN" "$BUNDLE"' EXIT
+BUNDLE_SHA="$(python3 "$REPO_ROOT/scripts/build-config-bundle.py" "$VERSION" "$BUNDLE")" || die "config bundle build failed"
+[[ "$BUNDLE_SHA" =~ ^[0-9a-f]{64}$ ]] || die "config bundle build printed no sha256"
+log "config bundle built: sha256 $BUNDLE_SHA"
+
 # ── 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).
@@ -153,6 +162,12 @@ if ! bash "$REPO_ROOT/scripts/publish-agent.sh" "$VERSION" "$BIN"; then
     die "publish failed"
 fi
 
+# ── 5b. Publish the config bundle beside the binary (same package version, same credentials) ──
+BURL="$GITEA_BASE/api/packages/$GITEA_OWNER/generic/felhom-agent/$VERSION/felhom-config-bundle.json"
+bcode="$(curl -sS -o /dev/null -w '%{http_code}' -u "${GITEA_USER}:${GITEA_TOKEN}" -X PUT --upload-file "$BUNDLE" "$BURL")"
+[[ "$bcode" == "201" || "$bcode" == "200" ]] || die "config bundle upload failed: HTTP $bcode (the binary IS published; re-run only the bundle upload)"
+log "config bundle published (HTTP $bcode)"
+
 # ── 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.
@@ -193,6 +208,11 @@ DL_SHA="$(sha256sum "$DL" | awk '{print $1}')"
 [[ "$DL_SHA" == "$BUILT_SHA" ]] \
     || die "published sha $DL_SHA != built sha $BUILT_SHA — the artifact is not what was built"
 
+BDL="$(mktemp -t felhom-config-bundle-dl-XXXXXX)"
+trap 'rm -f "$BIN" "$DL" "$BUNDLE" "$BDL"' EXIT
+curl -fsS -o "$BDL" "$BURL" || die "round-trip GET of the config bundle failed"
+[[ "$(sha256sum "$BDL" | awk '{print $1}')" == "$BUNDLE_SHA" ]] || die "published config bundle sha != built sha"
+
 # The tag must also serve the configs the installer will fetch from it.
 cfg_code="$(curl -fsS -o /dev/null -w '%{http_code}' \
     "$GITEA_BASE/$GITEA_OWNER/felhom-agent/raw/tag/$TAG/configs/felhom-agent.service" 2>/dev/null || true)"
@@ -206,6 +226,7 @@ cat <<EOF
     version : $VERSION
     tag     : $TAG
     sha256  : $BUILT_SHA
+    bundle  : $BUNDLE_SHA   (felhom-config-bundle.json — vouch it with the agent)
 
   NOT VOUCHED. Vouching is what points machines at this version and stays your deliberate act:
   hub operator UI → Configs → Day-0 artifacts. Until then boxes keep installing the previous one.