v0.126.0: a fetch failure is not a wrong recovery code (R-224)

A hub the agent could not reach was reported to the customer as a bad recovery
code. Measured live 2026-08-05 (CAMPAIGN-11 F3): hub firewalled off, a CORRECT
current code, and the customer told it did not open their package — in 0.0556s
against ~1.0s for a real unseal. No unseal was attempted.

The discriminator existed here and this boundary threw it away: recover.go
fails at four distinguishable points and the local-api handler had cases for
two, with a default answering 'the recovery code did not open the sealed
bundle, OR the bundle could not be fetched'.

escrow.ErrBundleFetch now joins the fetch leg and the handler routes it to 502
with its own words — the code was NOT used. 502 not 4xx: the request was not
bad, an upstream dependency failed. Four situations, four statuses: 502 fetch /
400 fetched-and-refused / 404 no bundle / 409 predates the field. The
controller classifies on the STATUS and never parses the sentence.

A GREEN TEST NAMED THIS DEFECT AND DID NOT PREVENT IT.
TestRecoverOffsiteRepoPassword_FetchErrorIsDistinct has said since v0.125.0
that the operator must not be sent to re-read their code because the hub was
unreachable — and passed throughout, because it asserted this package's error
STRING one layer below the merge, and a string is not something a caller can
branch on. Re-pointed at the sentinel, with a consequence-level twin asserting
the status.

Red-proofs: removing the %w join fails the sentinel test; deleting the handler
case makes fetch and wrong-code both answer 400 with the wrong-code sentence.

29 packages ok, vet clean, agent gates OK.

internal/localapi/escrow_recover.go

@@ -75,6 +75,26 @@ func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Req
 	if err != nil {
 		// Each situation gets its own status and its own words. None of them names a secret.
 		switch {
+		// ── R-224 (2026-08-06) — THE FETCH FAILURE IS NOT A WRONG CODE. ────────────────────────
+		//
+		// This case did not exist, and its absence is the defect. A failed fetch fell through to the
+		// `default` below and was answered with "the recovery code did not open the sealed bundle" —
+		// so a hub that could not be reached was reported to the customer as a bad recovery code, on
+		// the one screen whose whole purpose is to be believed about their backups.
+		//
+		// Measured live 2026-08-05 (CAMPAIGN-11 F3 and F4): a CORRECT current code returned that
+		// message in 0.0556 s with the hub firewalled off, and in 0.0299 s with this agent stopped —
+		// against ~1.0 s for a genuine unseal. No unseal was attempted in either case.
+		//
+		// 502 rather than 400: 4xx says "your request was bad", and the request was not bad — an
+		// upstream dependency failed. The status is the machine-readable half; the controller
+		// classifies on it and must never parse this sentence.
+		//
+		// ⚠ THE CODE WAS NOT USED. Nothing may be said about it — not that it was wrong, and not
+		// that it was right.
+		case errors.Is(err, escrow.ErrBundleFetch):
+			s.logger.Warn("local-api: offsite key recovery: the sealed bundle could not be FETCHED — the recovery code was never used", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadGateway, "the sealed recovery bundle could not be fetched from the hub — the recovery code was NOT used and nothing was written")
 		case errors.Is(err, escrow.ErrNoEscrowBlob):
 			s.logger.Warn("local-api: offsite key recovery: the hub holds no sealed bundle for this host", "vmid", vmid)
 			writeErr(w, http.StatusNotFound, "the hub holds no sealed recovery bundle for this host — no escrow ceremony has run")
@@ -82,9 +102,11 @@ func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Req
 			s.logger.Warn("local-api: offsite key recovery: the bundle opened but predates the repository-password field", "vmid", vmid)
 			writeErr(w, http.StatusConflict, "the recovery code opened the bundle, but it carries NO offsite repository password (sealed before that field existed; it cannot be retro-fitted)")
 		default:
-			// Includes the fail-closed wrong-code case. The agent log records the STEP, never the code.
-			s.logger.Warn("local-api: offsite key recovery FAILED (wrong recovery code, or the blob could not be fetched)", "vmid", vmid, "err", err)
-			writeErr(w, http.StatusBadRequest, "the recovery code did not open the sealed bundle, or the bundle could not be fetched — nothing was written")
+			// The fail-closed WRONG-CODE case, and only it: the bundle was fetched and `age -d`
+			// refused it. Every other situation above has its own status. The agent log records the
+			// STEP, never the code.
+			s.logger.Warn("local-api: offsite key recovery: the fetched bundle did not open with the supplied recovery code", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadRequest, "the recovery code did not open the sealed bundle — nothing was written")
 		}
 		return
 	}