felhom-agent/REPORT.md

REPORT — felhom-agent v0.90.1 (R-39 hotfix: PBS reconcile must not pass --server)

Date: 2026-07-18 · Baseline: v0.90.0 → v0.90.1 · Scope: config-only. configs/felhom-pbs-apply (one argv line + its WHY) and one red-proof test. The Go binary is unchanged — this ships with the next agent deploy as a config artifact. Green: go build ./... && go vet ./... && go test ./... all pass.

What was wrong

reconcile built its argv as args=(--server "$server" --fingerprint "$fp"). PVE treats a PBS storage's server as a create-only parameter and rejects the whole pvesm set call — can't change value of fixed parameter 'server' — even when the value is byte-identical to the stored one. reconcile could therefore never succeed against an existing entry.

That is severe rather than cosmetic because the agent consumes the hub's one-time PBS token secret before invoking the wrapper. Every failed reconcile burned a credential:

hub "Re-issue PBS credentials"  →  fresh one-time secret minted
agent                           →  secret CONSUMED (single-use, now spent)
wrapper reconcile               →  exit 255, "fixed parameter 'server'"
storage entry                   →  still pinned to the REVOKED secret  →  401 forever

How it was found and proven

Live-diagnosed on the N100 demo host during the 2026-07-18 rehearsal wrap (felhom.eu/documentation/tests/VALIDATION-n100-rehearsal-2026-07-18.md finding F2, ROADMAP R-39). The box had been reporting pbsdr: converged state=applied while pvesm status returned 401 Unauthorized / inactive.

Proven directly on the live entry before any code was written:

Probe	Result
pvesm set felhom-pbs --server <same> --fingerprint <same>	rejected — can't change value of fixed parameter 'server'
pvesm set felhom-pbs --fingerprint <same>	rc 0 — accepted

The encryption key K (<id>.enc) and the .pw store were verified byte-untouched after the rejected call: PVE rejects atomically, so the set-only law held throughout.

The fix

Drop --server from the reconcile argv. The server address is immutable by construction — relocating a PBS endpoint requires a fresh create — so there was never anything for reconcile to reconcile there. --fingerprint (and --password when a secret is fed on stdin) remain, which is the mutable identity the verb exists to push.

Red-proof

TestReconcileNeverPassesServerToPvesmSet (internal/pbsdr/manager_test.go) isolates the reconcile) block from the shipped wrapper and asserts no --server reaches pvesm set, plus that --fingerprint is still pushed so the verb cannot be hollowed out. Verified RED against the unfixed wrapper and GREEN after the fix.

Two traps the proof handles explicitly, both of which would have made it pass vacuously — and both of which actually fired during authoring, which is the argument for running a proof red first:

• Line endings. This repo is cloned on Windows; the working copy carries CRLF, so an \n-only pattern matches nothing and the guard passes silently. The pattern is \r?\n throughout. The first run failed with "could not locate the reconcile) block" — the vacuous-pass failure mode, caught only because the test was run against the broken wrapper first.
• Comments. The WHY note above the fix necessarily quotes --server, the very flag the test forbids, so the suite went red after the fix was applied. Comment lines are now stripped before matching.

Deliberately NOT fixed here — each still open

1. R-39's primary half. The agent re-applies on a change of the descriptor hash (internal/pbsdr/manager.go ~L235: if mk := m.loadMarker(); mk != nil && mk.Hash == h && (cf == nil || cf.Hash != h) { return }). A hub credential re-issue leaves the descriptor byte-identical — same token_id, same fingerprint; only the side-table secret rotates — and bumps only desired_generation. So a converged agent short-circuits and never consumes the fresh secret. This wrapper fix makes the apply succeed once the agent is made to re-apply; it does not make it re-apply.
2. The verify-loop read. pbs: cannot read token secret … permission denied — the non-root agent reads /etc/pve/priv/storage/<id>.pw directly, a path it can only ever write through the root wrapper. /etc/pve/priv is 0700 root:www-data and sudoers exposes only create|reconcile|grant — there is no read verb. The loop is permanently blind to exactly the failure it exists to catch.

Both ride the spec'd R-39 agent train. Recorded, not improvised.

Live state of the demo box at hand-off

The wrapper is hotfixed on the N100 (/usr/local/sbin/felhom-pbs-apply, backup kept at .bak-20260718-preR39, bash -n clean) so the repo and the box agree.

The box is not yet healed, and cannot be by CC. During diagnosis the agent was made to re-apply (marker moved aside — never deleted, the R-22 precedent), which proved the mechanism but consumed the one pending secret against the still-unfixed wrapper. The agent parked correctly in consumed-failed.json with NOT retrying silently — no burn loop, the fail-safe worked.

Healing needs one password-gated operator action CC cannot perform:

Viktor: click "Re-issue PBS credentials" for demo-felhom on the hub.

The agent will then pick it up unaided — marker.json is absent, so the L235 short-circuit does not apply — consume the fresh secret, and the patched wrapper will now apply it. Verification to run afterwards: pvesm status shows felhom-pbs active, then one on-demand PBS backup of guest 9201 confirmed in the PBS-side listing (the tier's first real backup on the reborn box).

Nothing was destroyed: .pw, .enc (K), and the storage.cfg entry are all intact and verified.