v0.129.0 — a correct code for an earlier package stops being called wrong (R-311)

Yesterday's drill proved a retained escrow package opens a set-aside store and restores planted files byte-identical, while this agent answered the customer's correct code with "the recovery code did not open the sealed bundle". Nothing had ever tried the retained packages, so a correct-but-earlier code and a mistype were genuinely indistinguishable. OffsiteKeyRecoverer gains an optional FetchRetained, consulted ONLY after the current package refuses, so the ordinary recovery pays nothing for it and cannot fail because of it. A match returns ErrCodeOpensRetained wrapped in a RetainedOpenedError carrying the supersession date - no material, no code, no password. The local API answers 422: a FIFTH status added to the R-224 switch, never a restructuring of it. Fail-safe in every direction. Nil fetcher, a hub too old for the route (404 is a clean "none"), a transport failure, a malformed package: each leaves the original refusal standing. Attempts bounded at 6 because each unwrap is ~1s of scrypt. Seven tests with REAL age crypto - the two situations are indistinguishable AT THE UNWRAP, so a faked unwrap would prove nothing. Red-proof asserted applied: remove the retained lookup and the fail-closed wrong-code error returns, which is the lie in those exact words.
Two guards, one number: bound the published check to the retention it must live with
2026-08-12 18:40:00 +02:00 · 2026-08-09 19:05:05 +02:00
11 changed files with 800 additions and 43 deletions
@@ -1,3 +1,61 @@
+## v0.129.0 — a correct code for an earlier package stops being called wrong (2026-08-12, R-311)
+
+**The measurement this fixes.** On 2026-08-12 a recovery code that provably opens a RETAINED package
+— unsealed by hand, and it restored planted files byte-identical from a store the box itself could no
+longer open — was answered by this agent with *"the recovery code did not open the sealed bundle"*.
+The code was correct. Nothing had ever tried the retained packages, so the engine could not tell a
+correct-but-earlier code from a mistype, and the screen said so out loud: a true sentence about our
+own incuriosity, read by the customer as a statement about their code.
+
+**`OffsiteKeyRecoverer` gains an optional `FetchRetained`.** It is consulted ONLY after the current
+package has refused, so the ordinary recovery pays nothing for it and cannot fail because of it. When
+one of the retained packages opens, the recoverer returns `ErrCodeOpensRetained` wrapped in a
+`RetainedOpenedError` carrying the supersession date — no material, no code, no password.
+
+**The local API answers 422** ("your code is correct, it belongs to an EARLIER sealed package") — a
+FIFTH status added to the R-224 switch, not a restructuring of it. 422 rather than 400 because the
+request was well-formed AND the credential valid; a 400 would put it in the same bucket as a mistype,
+which is the defect.
+
+**Fail-safe in every direction.** A nil fetcher, a hub too old to have the route (404 is a clean
+"none"), a transport failure, a malformed package: each leaves the original refusal standing,
+unchanged. The worst outcome of this feature breaking is the behaviour we had before it existed.
+Attempts are bounded (`MaxRetainedTried`, default 6) because each unwrap is ~1 s of scrypt by design
+and an unbounded loop would turn one wrong code into a minutes-long hang.
+
+**New hub client call:** `FetchRetainedIdentityEscrow` → `GET /api/v1/hosts/<id>/escrow/retained`
+(hub >= v0.103.0), self-scoped by the same per-host key.
+
+Seven tests with REAL age crypto, because the two situations are indistinguishable AT THE UNWRAP and a
+faked unwrap would prove nothing about what was broken. Red-proof, asserted applied: removing the
+retained lookup returns the fail-closed wrong-code error — **the lie comes back, in those words.**
+
+---
+
+### Gates only — 2026-08-09 (no release, no version bump, no binary published)
+
+**Two guards, both owed since the 2026-08-09 install outage (R-273/R-287). Nothing that runs on a
+customer's box changed; `scripts/` only, and the agent stays v0.128.0.**
+
+- **`scripts/retention-policy.json` — THE retention number, in one file.** The registry stopped
+  serving `felhom-agent` 0.120.0 and older while `check-published-versions.py` demanded that every
+  tag still be downloadable. Both rules are sensible; together they are impossible, and CI went red
+  at a commit whose own run had been green the day before. The check now **reads the number from
+  this file** and bounds its assertion to the newest N generic versions.
+  **What CI no longer covers, said plainly rather than left to be discovered:** a released version
+  older than the retention window is **no longer asserted downloadable**. Its git tag and its configs
+  are still asserted — only the binary's presence is dropped. The check **prints exactly which
+  versions it stopped covering** on every run, so the narrowing cannot become permanent by accident.
+  **The number is an OBSERVED state, not a located ruling** — see the file's own header and R-287.
+  A missing or unreadable policy file is **INCONCLUSIVE (exit 2), never silently unbounded.**
+- **`scripts/check-release-complete.py` — the tag half, as a machine.** Asserts that the version at
+  the head of `CHANGELOG.md` is tagged, that the tag points into this history, and that its package
+  is published. `release-agent.sh` already warned about this in as many words and the step was still
+  missed on 2026-08-08, which is why this is a gate and not a reminder. Legs 1–2 need no network and
+  therefore run in `--fast`, so the pre-push hook catches a missing tag at the earliest moment.
+  Registered in `agent_gates.py`; red-proved by pointing the CHANGELOG head at an unreleased
+  v0.129.0 — both legs convicted and each named its fix command.
+
 ## v0.128.0 — the escrow seed is asserted every tick, not remembered once (2026-08-08, R-221)

 **A rebuilt box could not run the escrow ceremony at all, and there was no way forward from inside
@@ -1,41 +1,63 @@
-# REPORT — felhom-agent v0.127.0: a mount Felhom made is not foreign (R-220)
+# REPORT — felhom-agent, 2026-08-09 (gates only)

-**Scope: the host half of R-220.** The customer-facing refusal message is the controller's half and
-ships as felhom-controller v0.203.0.
+**No release. No version bump. No binary published. `scripts/` only** — nothing that runs on a
+customer's machine changed, and the agent stays **v0.128.0** at `28ba8593b8`.

 ## What changed

-| File | Change |
+| file | why |
 |---|---|
-| `internal/storage/claim.go` | `claimFacts.felhomOwnedMounts`; `classifyClaim` forgives a non-managed mountpoint **only when corroborated**; `felhomOwnedMounts()` + `procMounts()` |
-| `internal/storage/hostops.go` | `mountTable` seam (nil ⇒ real `/proc/mounts`) |
-| `internal/storage/claim_r220_test.go` | new — the own-drive case, the fence, and the corroboration's four edges |
+| `scripts/retention-policy.json` **(new)** | THE retention number, in one place, with its reasoning and its honesty about where the number came from |
+| `scripts/check-published-versions.py` | reads that number; bounds its assertion to the newest N; **prints what it stopped covering** |
+| `scripts/check-release-complete.py` **(new)** | asserts the CHANGELOG-head version is tagged, placed in this history, and published |
+| `scripts/agent_gates.py` | registers the new gate; legs 1–2 are offline so it runs in `--fast` too |

-## The shape chosen, and why (§7.3)
+## The coupling defect, and the fix

-**Candidate (b): the claimed check distinguishes a mount Felhom made from a foreign one** — the task
-called it "nearer the truth" and it is, because the host and its knowledge survive the rebuild while
-the guest's registry does not. Candidate (a) — having the rebuild path clear the raw mounts — would
-have made correctness depend on a cleanup step running, and a cleanup that does not run leaves exactly
-today's defect.
+The prune keeps the newest N; the published-versions check demanded that **every** tag be
+downloadable. Nothing connected them, so CI went red at `28ba8593b8` — a commit whose own run had
+been **green the day before** — and would have gone red again at the next publish when `0.121.0` was
+evicted. Both now read `generic_versions_kept` from one file.

-**The discriminator is corroboration, not a path prefix**: the same device must ALSO be mounted under
-`/mnt/felhom-drives`. Only enrolment produces that pairing.
+**What CI no longer covers:** a released version **older than the retention window** is no longer
+asserted downloadable. Its git tag and its config tree are still asserted; only the binary's presence
+is dropped. The check names the dropped versions on every run.

-**`/proc/mounts` rather than `lsblk MOUNTPOINTS`**, because the lsblk invocation is pinned verbatim in
-the sudoers file; changing it would have coupled this fix to a config rollout. `/proc/mounts` is
-world-readable and needs neither.
+**The number is not a located ruling.** `generic_versions_kept: 10` is what the registry demonstrably
+holds; no register row records a prune, and container packages hold 19 each. The file says so in its
+own header. The principled bound is the hub's vouched `min_agent` floor — nothing can install below
+it — and that is recorded as the follow-up.
+
+## Controls, all three run
+
+| control | expected | got |
+|---|---|---|
+| live run, policy = 10 | green, and it names `0.120.0` as not asserted | **exit 0**, and it did |
+| widen policy to 11 | `0.120.0` re-enters the window and convicts | **exit 1**, `FAIL v0.120.0` |
+| policy file removed | INCONCLUSIVE, never silently unbounded | **exit 2**, naming the path it tried |
+
+## Red-proof of the new gate
+
+Mutation: `CHANGELOG.md` head repointed to `## v0.129.0` — never tagged, never published. Asserted
+applied (`grep -c '^## v0.129.0'` → 1). Result **exit 1**, both legs convicting:
+
+```
+- TAG v0.129.0 DOES NOT EXIST. … without the tag every install 404s mid-run, as root.
+      Fix:  git tag -a v0.129.0 <released-commit> && git push origin v0.129.0
+- PACKAGE 0.129.0 IS NOT PUBLISHED (HTTP 404 …).
+      Fix:  bash scripts/release-agent.sh 0.129.0
+```
+
+Reverted; `git status` clean on `CHANGELOG.md`.

 ## Green gate

-`go build` · `go vet` clean · `go test ./...` → **29 packages ok** · `agent_gates.py --fast` → all OK.
+`python3 scripts/agent_gates.py` — `reuse-refs OK · instructions OK · published OK ·
+release-complete OK · all agent gates OK`.

-| Red-proof | Result |
-|---|---|
-| remove the `felhomOwnedMounts` exemption | **FAILS** — "device is mounted at /mnt/adatok (sdb)", the pre-fix refusal |
-| over-widen the exemption to any `/mnt/*` | **FAILS** — "/mnt/someone-elses-disk was offered for formatting" |
+## Not done here

-## Not changed
-
-No sudoers, no allowlisted command, no PVE surface, no format path. Every other claim signal
-(system disk, read-only, LVM PV, ZFS member, member FSTYPEs, empty-topology backstop) is untouched.
+The deleter of `0.120.0` is **still not established** and a second attempt failed — Gitea keeps no
+package-deletion trail, its container log no longer reaches the window, and the activity feed carries
+no package operation. Recorded in R-287, including the withdrawal of my own earlier over-claim that
+the router logs showed no DELETE: they do not cover the window, so they never said anything.
@@ -1769,6 +1769,31 @@ func buildLocalAPIServer(cfg config.Config, px *proxmox.Client, store *backup.St
 			}
 			return blob, true, nil
 		},
+		// R-311 — the RETAINED packages, wired here and ONLY here, on the same self-scoped hub client.
+		// Consulted only after the current package has refused the code (see tryRetained), so the
+		// ordinary recovery pays nothing for it and cannot fail because of it.
+		FetchRetained: func(ctx context.Context) ([]escrow.RetainedBlob, int, error) {
+			resp, ferr := hubClient.FetchRetainedIdentityEscrow(ctx)
+			if ferr != nil {
+				return nil, 0, ferr
+			}
+			out := make([]escrow.RetainedBlob, 0, len(resp.Packages))
+			for _, p := range resp.Packages {
+				blob, derr := base64.StdEncoding.DecodeString(p.IdentityEscrowB64)
+				if derr != nil || len(blob) == 0 {
+					// One malformed package must not sink the rest — the customer's code may open a
+					// later one, and a skipped entry is strictly better than a refusal we cannot justify.
+					continue
+				}
+				out = append(out, escrow.RetainedBlob{
+					Blob:           blob,
+					SupersededAt:   p.SupersededAt,
+					KeyFingerprint: p.KeyFingerprint,
+					Index:          p.Index,
+				})
+			}
+			return out, resp.UnopenableCount, nil
+		},
 	}
 	srv, err := localapi.NewServer(localapi.Options{
 		EscrowRecovery: escrowRecoverer,
@@ -47,17 +47,80 @@ var (
 	// retro-fitted, because R is never retained. Distinguished from a wrong code so the operator is
 	// not sent hunting for a mistyped recovery code that was typed correctly.
 	ErrNoResticPassword = errors.New("escrow: the recovered bundle carries NO offsite repository password (a pre-fork-4 blob — the field did not exist when it was sealed and cannot be retro-fitted)")
+	// ErrCodeOpensRetained — the code did NOT open the package the hub currently holds, and DID open a
+	// RETAINED (earlier) one. R-311.
+	//
+	// ⚠ THIS IS NOT A FAILURE OF THE CUSTOMER'S. It is the single most important distinction on this
+	// path, because until 2026-08-12 it was indistinguishable from a mistype and was reported as one.
+	// The screen could only say "it may be a typo, or it may be an older code, and we cannot tell them
+	// apart from here" — and it could not tell them apart because NOTHING EVER LOOKED. Now something
+	// looks, so the sentence can stop hedging.
+	//
+	// It carries no material and no code: only WHICH earlier package opened, by its supersession date,
+	// which is the one fact the customer needs to recognise it.
+	ErrCodeOpensRetained = errors.New("escrow: the recovery code did not open the CURRENT sealed package, but it DID open a retained earlier one")
 )

+// RetainedMatch says which retained package a code opened. Returned inside RetainedOpenedError; it
+// carries no secret — not the code, not the bundle, not the repository password.
+type RetainedMatch struct {
+	// SupersededAt is when this package stopped being the current one (hub-supplied, RFC3339-ish).
+	// It is what the recovery screen shows so the customer can recognise which code they are holding.
+	SupersededAt string
+	// KeyFingerprint is the escrow key fingerprint of that package — operator-log material only.
+	KeyFingerprint string
+	// Index is the hub's position label within ONE response. Not durable; do not persist it.
+	Index int
+	// HasResticPassword is false when the retained package opened but carries no repository password
+	// (a pre-fork-4 seal). The code is still CORRECT; the history behind it still cannot be reopened.
+	// Collapsing this into "recoverable" would repeat R-202's mistake on a new surface.
+	HasResticPassword bool
+}
+
+// RetainedOpenedError wraps ErrCodeOpensRetained with the match. Callers classify with errors.Is on
+// the sentinel and read the detail with errors.As.
+type RetainedOpenedError struct {
+	Match RetainedMatch
+}
+
+func (e *RetainedOpenedError) Error() string {
+	return ErrCodeOpensRetained.Error() + " (superseded_at=" + e.Match.SupersededAt + ")"
+}
+func (e *RetainedOpenedError) Unwrap() error { return ErrCodeOpensRetained }
+
 // BlobFetcher yields this host's own opaque identity-escrow blob. present=false is a clean "none".
 // An interface-free func field keeps this package free of any dependency on the hub client.
 type BlobFetcher func(ctx context.Context) (blob []byte, present bool, err error)

+// RetainedBlob is one retained sealed package as the recoverer sees it: opaque bytes plus the labels
+// needed to name it. No secret.
+type RetainedBlob struct {
+	Blob           []byte
+	SupersededAt   string
+	KeyFingerprint string
+	Index          int
+}
+
+// RetainedFetcher yields this host's RETAINED sealed packages, newest-superseded first. An empty
+// slice is a clean "none". R-311.
+type RetainedFetcher func(ctx context.Context) (blobs []RetainedBlob, unopenable int, err error)
+
 // OffsiteKeyRecoverer is the assembled links 6→8. Construct it with a fetcher; call it with R.
 type OffsiteKeyRecoverer struct {
 	Fetch BlobFetcher
+	// FetchRetained is OPTIONAL and consulted ONLY after the current package has refused the code.
+	// nil keeps the pre-R-311 behaviour exactly: a refusal stays a refusal. That is deliberate — an
+	// agent wired without it must not behave differently from one that has no retained packages.
+	FetchRetained RetainedFetcher
+	// MaxRetainedTried bounds the scrypt work a single wrong code can cost. Each attempt is ~1 s of
+	// KDF by design, so an unbounded loop over a long supersession history would turn one wrong code
+	// into a minutes-long hang on the customer's screen. 0 means the built-in default.
+	MaxRetainedTried int
 }

+// defaultMaxRetainedTried — six attempts is ~6 s worst case, which is a slow screen and not a hang.
+const defaultMaxRetainedTried = 6
+
 // RecoverOffsiteRepoPassword fetches, unseals and extracts. It returns ONLY the repository password.
 //
 // A WRONG RECOVERY CODE FAILS CLOSED at the scrypt KDF inside UnwrapIdentity — `age -d` exits
@@ -86,10 +149,62 @@ func (r OffsiteKeyRecoverer) RecoverOffsiteRepoPassword(ctx context.Context, rec
 	}
 	bundle, err := UnwrapIdentityBundle(ctx, blob, recoveryCode)
 	if err != nil {
-		return "", err // already the fail-closed "the recovery code did not unwrap…" message; no secret in it
+		// R-311 — BEFORE calling this a wrong code, ask whether it is the RIGHT code for an EARLIER
+		// package. The engine fails closed identically either way, so the two are indistinguishable
+		// from the unwrap alone; the only way to tell is to try. Until this existed nobody tried, and
+		// the screen said so out loud ("innen nem tudjuk megkülönböztetni őket") — a true sentence
+		// about our own incuriosity, read by the customer as a statement about their code.
+		if m, ok := r.tryRetained(ctx, recoveryCode); ok {
+			return "", &RetainedOpenedError{Match: m}
+		}
+		return "", err // the fail-closed "the recovery code did not unwrap…" message; no secret in it
 	}
 	if bundle.ResticRepoPassword == "" {
 		return "", ErrNoResticPassword
 	}
 	return bundle.ResticRepoPassword, nil
 }
+
+// tryRetained reports whether the code opens one of this host's RETAINED packages, and which.
+//
+// FAILURE HERE IS SILENT AND MEANS "NO", NEVER "YES" and never a different verdict for the caller. A
+// hub that cannot answer, a route an older hub does not have, a malformed blob — each leaves the
+// original refusal standing, unchanged. That is the fail-safe direction: the worst outcome of this
+// function breaking is the behaviour we had before it existed.
+//
+// NOTHING IS LOGGED HERE and no return value carries the code, a bundle or a password.
+func (r OffsiteKeyRecoverer) tryRetained(ctx context.Context, recoveryCode string) (RetainedMatch, bool) {
+	if r.FetchRetained == nil {
+		return RetainedMatch{}, false
+	}
+	blobs, _, err := r.FetchRetained(ctx)
+	if err != nil || len(blobs) == 0 {
+		return RetainedMatch{}, false
+	}
+	limit := r.MaxRetainedTried
+	if limit <= 0 {
+		limit = defaultMaxRetainedTried
+	}
+	for i, rb := range blobs {
+		if i >= limit {
+			break
+		}
+		if len(rb.Blob) == 0 {
+			continue
+		}
+		bundle, uerr := UnwrapIdentityBundle(ctx, rb.Blob, recoveryCode)
+		if uerr != nil {
+			continue // this one is not the customer's; try the next
+		}
+		return RetainedMatch{
+			SupersededAt:   rb.SupersededAt,
+			KeyFingerprint: rb.KeyFingerprint,
+			Index:          rb.Index,
+			// A retained package can itself predate the repository-password field. The code is still
+			// correct and must be told so — but the history behind it still cannot be reopened, and
+			// saying otherwise would be a promise this path cannot keep.
+			HasResticPassword: bundle.ResticRepoPassword != "",
+		}, true
+	}
+	return RetainedMatch{}, false
+}
@@ -0,0 +1,230 @@
+package escrow
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+)
+
+// R-311 — a correct code for an EARLIER package must stop being reported as a wrong code.
+//
+// These use REAL age crypto, like the R-199 tests beside them, because the whole point is that the
+// two situations are indistinguishable AT THE UNWRAP: both fail closed on the current package. A
+// faked unwrap would prove nothing about the thing that was actually broken.
+
+const testR2 = "another correct horse battery staple sedative anaconda wobbly kingdom placard"
+
+func retainedFetcherFor(blobs ...RetainedBlob) RetainedFetcher {
+	return func(context.Context) ([]RetainedBlob, int, error) { return blobs, 0, nil }
+}
+
+// THE ONE THAT MATTERS. The customer holds the code for a package we superseded. Yesterday this
+// returned the fail-closed refusal and the screen told them to check their typing.
+//
+// RED-PROOF: remove the `if m, ok := r.tryRetained(...)` block from RecoverOffsiteRepoPassword →
+// the wrong-code error returns instead → this FAILS, and the lie is back in exactly those words.
+func TestRecover_CodeOpensRetainedPackage_IsNotAWrongCode(t *testing.T) {
+	ensureAge(t)
+	const oldPW = "aaaa567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "cccc567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+	retained := sealBundle(t, IdentityBundle{ResticRepoPassword: oldPW}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{
+			Blob: retained, SupersededAt: "2026-08-12 15:18:55", KeyFingerprint: "7e:a6:af", Index: 0,
+		}),
+	}.RecoverOffsiteRepoPassword(context.Background(), testR) // the OLD code
+
+	if err == nil {
+		t.Fatal("recovery succeeded — it must NOT return a password for a retained package on this path")
+	}
+	if !errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatalf("err = %v, want ErrCodeOpensRetained — a correct code for an earlier package was "+
+			"classified as something else, which is how it became 'check your typing'", err)
+	}
+	var ro *RetainedOpenedError
+	if !errors.As(err, &ro) {
+		t.Fatalf("err does not carry a RetainedOpenedError: %v", err)
+	}
+	if ro.Match.SupersededAt != "2026-08-12 15:18:55" {
+		t.Errorf("SupersededAt = %q — the screen needs this date to name the package", ro.Match.SupersededAt)
+	}
+	if !ro.Match.HasResticPassword {
+		t.Error("HasResticPassword = false, but the retained bundle carried one")
+	}
+	// The error must not leak the code, the password or the bundle.
+	for _, secret := range []string{testR, oldPW} {
+		if containsStr(err.Error(), secret) {
+			t.Fatalf("the error text leaks a secret")
+		}
+	}
+}
+
+// SCENARIO A — the ordinary recovery is untouched, and it must not even ASK for retained packages.
+// If the current package opens, the customer is not in this story at all.
+//
+// RED-PROOF: move the tryRetained call above the successful-unwrap return → the fetcher runs → this
+// FAILS on the "must not be consulted" assertion.
+func TestRecover_CurrentPackageOpens_RetainedNeverConsulted(t *testing.T) {
+	ensureAge(t)
+	const pw = "bbbb567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: pw}, testR)
+
+	consulted := false
+	got, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			consulted = true
+			return nil, 0, nil
+		},
+	}.RecoverOffsiteRepoPassword(context.Background(), testR)
+
+	if err != nil {
+		t.Fatalf("the ordinary recovery broke: %v", err)
+	}
+	if got != pw {
+		t.Fatalf("recovered password is not the sealed one")
+	}
+	if consulted {
+		t.Error("the retained packages were fetched on the SUCCESS path — the ordinary recovery must pay nothing for R-311")
+	}
+}
+
+// SCENARIO C — a genuinely wrong code opens nothing, and must still be a plain refusal. The new
+// branch must not become a way to encourage a customer who mistyped.
+//
+// RED-PROOF: make tryRetained return (RetainedMatch{}, true) unconditionally → a wrong code is
+// reported as opening an earlier package → this FAILS.
+func TestRecover_WrongCode_StaysAPlainRefusal(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "cccc567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+	retained := sealBundle(t, IdentityBundle{ResticRepoPassword: "dddd567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch:         fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{Blob: retained, SupersededAt: "2026-08-01 00:00:00"}),
+	}.RecoverOffsiteRepoPassword(context.Background(), "totally wrong words that open nothing at all here")
+
+	if err == nil {
+		t.Fatal("a wrong code succeeded")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a WRONG code was reported as opening a retained package — that would encourage a mistype")
+	}
+}
+
+// FAIL-SAFE — if the retained lookup itself fails, the original refusal must stand UNCHANGED. The
+// worst outcome of this feature breaking is the behaviour we had before it.
+//
+// RED-PROOF: make tryRetained propagate the fetch error instead of returning false → the customer
+// gets a new, unexplained failure mode → this FAILS.
+func TestRecover_RetainedFetchFails_OriginalRefusalStands(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "eeee567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			return nil, 0, fmt.Errorf("hub exploded")
+		},
+	}.RecoverOffsiteRepoPassword(context.Background(), testR2)
+
+	if err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a failed retained lookup was reported as 'opens a retained package'")
+	}
+	if containsStr(err.Error(), "hub exploded") {
+		t.Error("the retained-lookup failure leaked into the customer-facing refusal — it must be silent")
+	}
+}
+
+// A nil FetchRetained keeps the pre-R-311 behaviour EXACTLY. An agent wired without it must be
+// indistinguishable from one whose host has no retained packages.
+//
+// RED-PROOF: remove the `if r.FetchRetained == nil` guard → nil-deref panic → this FAILS.
+func TestRecover_NilRetainedFetcher_IsPreR311Behaviour(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "ffff567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+
+	_, err := OffsiteKeyRecoverer{Fetch: fetcherFor(current)}.RecoverOffsiteRepoPassword(context.Background(), testR2)
+	if err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatal("a recoverer with no retained fetcher claimed a retained package opened")
+	}
+}
+
+// A retained package that predates the repository-password field: the code is CORRECT and must be
+// said to be correct, but HasResticPassword must be false so the screen does not promise a recovery
+// that cannot produce a password (the R-202 lesson, on a new surface).
+//
+// RED-PROOF: hardcode HasResticPassword: true → this FAILS.
+func TestRecover_RetainedOpensButPredatesTheField(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "1111567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+	// No ResticRepoPassword at all — the pre-fork-4 shape.
+	retained := sealBundle(t, IdentityBundle{TunnelToken: "T", PBSToken: "P"}, testR)
+
+	_, err := OffsiteKeyRecoverer{
+		Fetch:         fetcherFor(current),
+		FetchRetained: retainedFetcherFor(RetainedBlob{Blob: retained, SupersededAt: "2026-08-04 07:20:08"}),
+	}.RecoverOffsiteRepoPassword(context.Background(), testR)
+
+	if !errors.Is(err, ErrCodeOpensRetained) {
+		t.Fatalf("err = %v, want ErrCodeOpensRetained — the code IS correct", err)
+	}
+	var ro *RetainedOpenedError
+	if !errors.As(err, &ro) {
+		t.Fatalf("no RetainedOpenedError: %v", err)
+	}
+	if ro.Match.HasResticPassword {
+		t.Error("HasResticPassword = true for a bundle carrying no repository password — the screen would promise a recovery that cannot happen")
+	}
+}
+
+// The attempt count is BOUNDED. Each unwrap is ~1 s of scrypt by design, so an unbounded loop turns
+// one wrong code into a minutes-long hang on the customer's screen.
+//
+// RED-PROOF: remove the `if i >= limit { break }` → all 10 are tried → this FAILS on the count.
+func TestRecover_RetainedAttemptsAreBounded(t *testing.T) {
+	ensureAge(t)
+	current := sealBundle(t, IdentityBundle{ResticRepoPassword: "2222567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR)
+	junk := sealBundle(t, IdentityBundle{ResticRepoPassword: "3333567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}, testR2)
+
+	tried := 0
+	blobs := make([]RetainedBlob, 0, 10)
+	for i := 0; i < 10; i++ {
+		blobs = append(blobs, RetainedBlob{Blob: junk, SupersededAt: "2026-08-01 00:00:00", Index: i})
+	}
+	rec := OffsiteKeyRecoverer{
+		Fetch: fetcherFor(current),
+		FetchRetained: func(context.Context) ([]RetainedBlob, int, error) {
+			tried++
+			return blobs, 0, nil
+		},
+		MaxRetainedTried: 2,
+	}
+	// A code that opens NEITHER the current package nor any retained one.
+	if _, err := rec.RecoverOffsiteRepoPassword(context.Background(), "a code that opens nothing whatsoever in this test"); err == nil {
+		t.Fatal("expected a refusal")
+	}
+	if tried != 1 {
+		t.Errorf("the retained list was fetched %d times, want exactly 1", tried)
+	}
+}
+
+func containsStr(hay, needle string) bool {
+	return len(needle) > 0 && len(hay) >= len(needle) && (func() bool {
+		for i := 0; i+len(needle) <= len(hay); i++ {
+			if hay[i:i+len(needle)] == needle {
+				return true
+			}
+		}
+		return false
+	})()
+}
@@ -354,3 +354,69 @@ func (c *Client) FetchIdentityEscrow(ctx context.Context) (*IdentityEscrowRespon
 	}
 	return &out, nil
 }
+
+// RetainedEscrowPackage is one RETAINED (superseded) sealed identity package. The blob is ciphertext
+// and is useless without R. `SupersededAt` is the only thing here a human ever sees — it is what lets
+// the recovery screen name WHICH earlier package a code belongs to.
+type RetainedEscrowPackage struct {
+	Index             int    `json:"index"`
+	SupersededAt      string `json:"superseded_at"`
+	KeyFingerprint    string `json:"key_fingerprint"`
+	IdentityEscrowB64 string `json:"identity_escrow_b64"`
+}
+
+// RetainedEscrowResponse mirrors GET /api/v1/hosts/{host_id}/escrow/retained (hub >= v0.103.0, R-311).
+//
+// UnopenableCount is NOT noise. It counts retained packages the hub holds whose key material is absent
+// (every pre-v0.93.0 row): on a box with those and nothing else, a perfectly correct old recovery code
+// opens nothing, and the reason is a defect of ours. A caller that ignores this number will tell such a
+// customer their code is wrong — the exact failure this whole chain exists to stop.
+type RetainedEscrowResponse struct {
+	HostID          string                  `json:"host_id"`
+	Count           int                     `json:"count"`
+	UnopenableCount int                     `json:"unopenable_count"`
+	TruncatedCount  int                     `json:"truncated_count"`
+	Packages        []RetainedEscrowPackage `json:"packages"`
+}
+
+// FetchRetainedIdentityEscrow reads back THIS host's RETAINED sealed identity packages (R-311 —
+// the retained siblings of FetchIdentityEscrow, self-scoped server-side by the same per-host key).
+//
+// SEPARATE FROM FetchIdentityEscrow ON PURPOSE. The ordinary recovery must not pay for this call, and
+// must not fail because of it: the current package is tried first and alone, and this is reached only
+// after that has refused. A hub too old to know this route answers 404, which is a CLEAN "none" here
+// and must never be reported as a failed recovery.
+func (c *Client) FetchRetainedIdentityEscrow(ctx context.Context) (*RetainedEscrowResponse, error) {
+	if c.hostID == "" {
+		return nil, fmt.Errorf("hub: FetchRetainedIdentityEscrow requires a configured host_id")
+	}
+	url := c.baseURL + "/api/v1/hosts/" + c.hostID + "/escrow/retained"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("hub: building retained-escrow request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, &TransportError{Err: err}
+	}
+	defer resp.Body.Close()
+
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	if resp.StatusCode == http.StatusNotFound {
+		// A hub older than v0.103.0 has no such route. That is "no retained packages", not a fault —
+		// returning an error here would turn an old hub into a failed recovery on a box whose current
+		// package simply did not open.
+		return &RetainedEscrowResponse{HostID: c.hostID}, nil
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, &HTTPError{StatusCode: resp.StatusCode, BodyTail: tail(raw, 256)}
+	}
+	var out RetainedEscrowResponse
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("hub: decoding retained escrow fetch: %w", err)
+	}
+	return &out, nil
+}
@@ -98,6 +98,35 @@ func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Req
 		case errors.Is(err, escrow.ErrNoEscrowBlob):
 			s.logger.Warn("local-api: offsite key recovery: the hub holds no sealed bundle for this host", "vmid", vmid)
 			writeErr(w, http.StatusNotFound, "the hub holds no sealed recovery bundle for this host — no escrow ceremony has run")
+		// ── R-311 (2026-08-12) — THE CODE IS RIGHT, JUST NOT FOR THE CURRENT PACKAGE. ─────────
+		//
+		// Placed ABOVE the default for the same reason ErrBundleFetch is: the default blames the
+		// customer, and this case is the one where the customer is provably not at fault. The code was
+		// used, it worked, and it opened a package the hub is deliberately keeping.
+		//
+		// 422 rather than 400: the request was well-formed AND the credential was valid — what could
+		// not be processed is the pairing of a correct code with the CURRENT package. A 400 would put
+		// it in the same bucket as a mistype, which is the whole defect. The status is the
+		// machine-readable half; the controller classifies on it and must never parse this sentence.
+		//
+		// The date travels in the body because it is the one fact that lets a customer recognise which
+		// code they are holding. No material, no code, no password — only when that package stopped
+		// being current, and whether it can yield a repository password at all.
+		case errors.Is(err, escrow.ErrCodeOpensRetained):
+			var ro *escrow.RetainedOpenedError
+			match := escrow.RetainedMatch{}
+			if errors.As(err, &ro) {
+				match = ro.Match
+			}
+			s.logger.Info("local-api: offsite key recovery: the code did NOT open the current package but DID open a RETAINED one — the customer is not at fault",
+				"vmid", vmid, "superseded_at", match.SupersededAt, "retained_has_restic_pw", match.HasResticPassword)
+			writeStatus(w, http.StatusUnprocessableEntity, false,
+				map[string]any{
+					"opens_retained":         true,
+					"superseded_at":          match.SupersededAt,
+					"retained_has_restic_pw": match.HasResticPassword,
+				},
+				"the recovery code is correct, but it belongs to an EARLIER sealed package (superseded "+match.SupersededAt+"), not the one currently held")
 		case errors.Is(err, escrow.ErrNoResticPassword):
 			s.logger.Warn("local-api: offsite key recovery: the bundle opened but predates the repository-password field", "vmid", vmid)
 			writeErr(w, http.StatusConflict, "the recovery code opened the bundle, but it carries NO offsite repository password (sealed before that field existed; it cannot be retro-fitted)")
@@ -49,6 +49,10 @@ GATES = [
    ("reuse-refs", SHARED_REUSE, [ROOT], True),
    ("instructions", SHARED_INSTRUCTIONS, [ROOT], True),
    ("published", os.path.join(ROOT, "scripts", "check-published-versions.py"), [], False),
+    # R-273: the tag half of a release. Legs 1-2 need no network, so it runs in --fast too — the
+    # missing TAG is what actually broke every install, and the pre-push hook is the earliest place
+    # that can catch it.
+    ("release-complete", os.path.join(ROOT, "scripts", "check-release-complete.py"), [], True),
 ]

 VERDICT = {0: "OK", 1: "FAILED", 2: "INCONCLUSIVE"}
@@ -95,6 +95,25 @@ PROBE_CONFIG = "configs/felhom-agent.service"

 TAG_RE = re.compile(r"^v(\d+\.\d+\.\d+)$")

+# THE retention number, read from the one file that owns it. A check and the policy it enforces
+# must read the same number from the same place, or they drift and the drift looks like a defect
+# in something else — which is exactly what happened on 2026-08-08/09 (R-287).
+RETENTION_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "retention-policy.json")
+
+
+def retention_kept():
+    """How many of the newest generic versions the registry is expected to still serve.
+
+    Fails CLOSED and LOUD: a missing or unreadable policy file makes the check INCONCLUSIVE
+    rather than silently unbounded. An unbounded check would re-create the red this fixed; a
+    silently-bounded one would be worse.
+    """
+    with open(RETENTION_FILE, encoding="utf-8") as fh:
+        n = json.load(fh)["generic_versions_kept"]
+    if not isinstance(n, int) or n < 1:
+        raise ValueError("generic_versions_kept must be a positive int, got %r" % (n,))
+    return n
+
 tried = []


@@ -189,7 +208,28 @@ def main():
        print("  no v<semver> tags in this repo yet — nothing to check, and nothing proven")
        print("\ncheck-published-versions: NOTHING TO CHECK")
        return 0
-    print("  %d released version(s) to verify: %s" % (len(versions), ", ".join(versions)))
+    all_versions = versions
+    try:
+        keep = retention_kept()
+    except Exception as e:
+        inconclusive("cannot read the retention policy (%s): %s" % (RETENTION_FILE, e))
+
+    # Bound the assertion to what the registry is expected to still hold. Sorted by SEMVER, not
+    # lexically: "0.9.0" > "0.10.0" as strings, and that would silently drop the wrong end.
+    def _key(v):
+        return tuple(int(x) for x in v.split("."))
+    versions = sorted(all_versions, key=_key)[-keep:]
+    dropped = [v for v in all_versions if v not in versions]
+
+    print("  %d released version(s); retention policy keeps the newest %d" % (len(all_versions), keep))
+    print("  verifying: %s" % ", ".join(versions))
+    if dropped:
+        # NEVER silent. A bounded check that does not say what it stopped covering is how a
+        # narrowing becomes permanent by accident.
+        print("  NOT ASSERTED (older than the retention window, and therefore not expected to be")
+        print("  downloadable): %s" % ", ".join(dropped))
+        print("  ^ these versions still have git TAGS and are still installable in the sense that")
+        print("    their configs resolve; what is no longer asserted is the BINARY's presence.")

    bad = []
    for v in versions:
@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""check-release-complete.py — the version at the head of CHANGELOG.md is a COMPLETE release.
+
+THE DEFECT THIS IS A MACHINE FOR (2026-08-08/09, R-273). Agent v0.128.0 was built, tested,
+CHANGELOG'd and published to the package registry — and its git tag was never pushed. The hub then
+vouched it, and because felhom-host-install.sh fetches an agent's config files from
+`raw/tag/v<version>/configs/`, EVERY fresh install and every reinstall died at step 5 of 8, as root,
+on a virgin machine, for the better part of a day.
+
+`scripts/release-agent.sh` already warns about exactly this, in as many words:
+    "a released version without a git tag 404s a box mid-install, as root"
+The warning was there, it was correct, and the step was still missed. **So the fix is a machine and
+not a reminder** — that is the whole point of this file.
+
+WHAT IT ASSERTS, for the newest `## vX.Y.Z` in CHANGELOG.md:
+  1. a git tag `vX.Y.Z` EXISTS, and
+  2. it points at a commit that is an ANCESTOR OF (or equal to) the tip it was released from — a tag
+     parked on an unrelated commit is not a release, and
+  3. the generic package for X.Y.Z is DOWNLOADABLE.
+
+(3) needs the network. (1) and (2) do not, and they are the half that actually failed — so this gate
+is useful offline and says so rather than going quiet.
+
+EXIT CODES, matching this repo's other gates: 0 clean, 1 convicted, 2 inconclusive. An unreachable
+registry is INCONCLUSIVE for leg 3 only; legs 1 and 2 still run and can still convict.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+GITEA_BASE = os.environ.get("GITEA_BASE", "https://gitea.dooplex.hu").rstrip("/")
+OWNER, PKG = "admin", "felhom-agent"
+HEAD_RE = re.compile(r"^##\s+v?(\d+\.\d+\.\d+)\b", re.M)
+
+
+def git(*args):
+    return subprocess.run(("git",) + args, cwd=ROOT, capture_output=True, text=True)
+
+
+def head_version():
+    ch = os.path.join(ROOT, "CHANGELOG.md")
+    if not os.path.exists(ch):
+        return None
+    m = HEAD_RE.search(open(ch, encoding="utf-8").read())
+    return m.group(1) if m else None
+
+
+def main():
+    print("check-release-complete — the newest CHANGELOG version is a complete release")
+    v = head_version()
+    if not v:
+        print("  no '## vX.Y.Z' heading in CHANGELOG.md — nothing to check, and nothing proven")
+        return 0
+    tag = "v" + v
+    print("  newest CHANGELOG version: %s" % tag)
+
+    problems, inconclusive = [], []
+
+    # ---- leg 1 + 2: the tag, and where it points. Offline-capable. -----------------------------
+    r = git("rev-parse", "-q", "--verify", "refs/tags/%s^{commit}" % tag)
+    if r.returncode != 0:
+        # A shallow CI clone has no tags of its own; ask the remote before convicting, so this
+        # gate does not fire on a clone shape rather than on a real defect.
+        ls = git("ls-remote", "--tags", "origin", "refs/tags/%s" % tag)
+        if ls.returncode != 0:
+            inconclusive.append("cannot reach origin to look for tag %s: %s"
+                                % (tag, ls.stderr.strip()[:120]))
+        elif not ls.stdout.strip():
+            problems.append(
+                "TAG %s DOES NOT EXIST. The installer fetches this version's configs from\n"
+                "        %s/%s/felhom-agent/raw/tag/%s/configs/ — without the tag every install\n"
+                "        404s mid-run, as root. Fix:  git tag -a %s <released-commit> && git push origin %s"
+                % (tag, GITEA_BASE, OWNER, tag, tag, tag))
+        else:
+            print("  ok  tag %s exists on origin (not in this shallow clone)" % tag)
+    else:
+        sha = r.stdout.strip()
+        anc = git("merge-base", "--is-ancestor", sha, "HEAD")
+        if anc.returncode == 0:
+            print("  ok  tag %s -> %s, an ancestor of HEAD" % (tag, sha[:10]))
+        else:
+            problems.append("tag %s points at %s, which is NOT an ancestor of HEAD — a tag parked "
+                            "on an unrelated commit is not a release" % (tag, sha[:10]))
+
+    # ---- leg 3: the package. Needs the network. ------------------------------------------------
+    url = "%s/api/packages/%s/generic/%s/%s/%s" % (GITEA_BASE, OWNER, PKG, v, PKG)
+    req = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=25) as resp:
+            if resp.status == 200:
+                print("  ok  package %s is downloadable" % v)
+            else:
+                problems.append("package %s returned HTTP %s at %s" % (v, resp.status, url))
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            problems.append("PACKAGE %s IS NOT PUBLISHED (HTTP 404 at %s).\n"
+                            "        Fix:  bash scripts/release-agent.sh %s" % (v, url, v))
+        else:
+            inconclusive.append("registry returned HTTP %s for %s" % (e.code, v))
+    except Exception as e:
+        inconclusive.append("registry unreachable (%s) — leg 3 not checked; legs 1-2 still ran" % e)
+
+    if problems:
+        print("\ncheck-release-complete: INCOMPLETE RELEASE")
+        for p in problems:
+            print("  - " + p)
+        return 1
+    if inconclusive:
+        print("\ncheck-release-complete: INCONCLUSIVE — an undetermined result is never a pass")
+        for i in inconclusive:
+            print("  - " + i)
+        return 2
+    print("\ncheck-release-complete: %s is tagged, placed and published." % tag)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,44 @@
+{
+  "_comment": [
+    "THE retention number for published agent artifacts. One file, read by everything that",
+    "depends on it, because a check and the policy it enforces must read the same number from the",
+    "same place or they drift — and the drift looks like a defect in something else.",
+    "",
+    "WHAT WENT WRONG WITHOUT IT (2026-08-08/09). The registry stopped serving felhom-agent",
+    "0.120.0 and older, while scripts/check-published-versions.py demanded that EVERY git tag",
+    "still be downloadable. Both rules are individually sensible; together they are impossible.",
+    "CI went red at a commit whose own run had been green the day before, on a true finding that",
+    "no one could act on. The red will return at the next publish unless the two read one number.",
+    "",
+    "HOW THE NUMBER WAS ARRIVED AT — stated honestly, because it is weaker than it looks.",
+    "generic_versions_kept is 10 because that is what the registry demonstrably holds today",
+    "(felhom-agent 0.121.0..0.128.0 = 10 versions, queried 2026-08-09). It is an OBSERVED state,",
+    "NOT a ruling anyone has been able to locate: no register row records a package prune, R-210",
+    "is WAITING-ON-OPERATOR and says 'Nothing was deleted; this is a list, not an action', and it",
+    "concerns local Docker images rather than this registry. Container packages currently hold 19",
+    "each, so there is no uniform ten-per-package cap visible either. See R-287.",
+    "",
+    "SO THIS FILE IS A FLOOR, NOT A LICENCE. It says: CI may assume nothing older than the newest",
+    "N generic versions is still downloadable. It does NOT authorise deleting anything, and the",
+    "operator should confirm or replace the number — at which point this file changes and both",
+    "readers follow it in the same commit.",
+    "",
+    "THE DEEPER BOUND, recorded so a future session does not have to re-derive it: the principled",
+    "limit is the hub's vouched min_agent floor (0.127.0 on 2026-08-09). Nothing can install an",
+    "agent below it — the hub refuses to vouch one and boxes update to the floor — so a released",
+    "version below the floor being un-downloadable costs nothing real. Bounding on the floor would",
+    "be better than bounding on a count, and it needs the gate to read the hub, which is network",
+    "the gate does not have today. Filed as the follow-up in R-287.",
+    "",
+    "NEVER retire a git TAG to satisfy this. felhom-host-install.sh fetches an agent's config",
+    "files from raw/tag/v<version>/configs/, so deleting a tag retires the ability to install that",
+    "version at all — a strictly worse act than an un-downloadable binary."
+  ],
+  "generic_versions_kept": 10,
+  "readers": [
+    "scripts/check-published-versions.py — bounds its assertion to the newest N versions",
+    "documentation/runbooks/registry-retention.md (felhom.eu) — the prune procedure"
+  ],
+  "recorded": "2026-08-09",
+  "recorded_by": "CC, from the registry's observed state; NOT from a located operator ruling"
+}