felhom-agent/REPORT.md

REPORT — felhom-agent v0.89.0 (agent train: R-22 self-grant + escrow live-reload + poke listener)

Date: 2026-07-16 · Baseline: v0.88.0 (c040c18) → v0.89.0 (a659e5d, pushed) Green gate: go build ./... && go vet ./... && go test ./... — all pass (full suite, local go1.26). Design contract for item 3: felhom.eu/documentation/audits/SPIKE-immediate-sync-transport-2026-07-16.md.

Items + landmarks as found at source

Item 1 — pbsdr self-grant (R-22, closes F4 from tests/VALIDATION-n100-baremetal)

• Where the pre-check lives: internal/pbsdr/manager.go Apply → m.px.StorageEntry(ctx, id) (GET /storage/<id>, token-auth). On a non-default storage id the agent token has no ACL there yet → 403; pre-fix the generic if err != nil { … return } aborted BEFORE the root-run wrapper grant (only reached via adopt/create) that creates that very ACL — a permanent self-deadlock.
• Fix: on an errors.As(err, *proxmox.APIError) with IsForbidden() ONLY, run felhom-pbs-apply grant <id> now (root, no secret, no pre-existing entry — pveum acl modify on a path is unconditional; verified in configs/felhom-pbs-apply grant)), re-read once, then flow the normal adoption/create path. Every other error stays transient. Grant-OK-but-still-403 → verify_failed loudly. The pre-check is KEPT (the spec's "don't drop it" — it short-circuits the happy path once the ACL exists). A benign extra grant on the adopt path is idempotent.
• Red-proof (run-fail-revert): TestSelfGrant_PreCheck403DoesNotAbortBeforeGrant. Pre-fix (forced if true abort): self-grant never ran … calls=[] → FAIL. Fixed: self-grant runs, converges (adopted), no secret consumed, 2 StorageEntry calls (403 + post-grant re-read) → PASS.

Item 2 — escrow config live-reload

• Two ends: the pbsdr bridge seeds escrow.pbs_storage_id into agent.json on convergence (manager.go finishConverged→seedEscrowStorageID); the reader is internal/localapi/escrow_ceremony.go handleEscrowPreflight, which read a daemon-start snapshot (EscrowCeremonyConfig.PBSStorageID) → stayed red until a service restart.
• Reload strategy chosen (stated per source shape): the preflight reads current disk state, via a new late-bound CurrentPBSStorageID func() string (mirrors the existing DRConfigured func() bool seam). cmd/felhom-agent/main.go wires it to config.Load(cfg.SourcePath).Escrow.PBSStorageID — exactly what the ceremony subprocess itself loads — so the row reflects the true state the bare --selftest=escrow-create one-liner will see. Falls back to the boot snapshot on read error / all-env config. Preferred over an in-memory push (no cross-component coupling, single source of truth = disk).
• Red-proof: TestEscrowPreflight_PBSStorageIDLiveReload — seed after boot, same process; pre-fix (static field) stays red → FAIL; fixed flips green + reports the seeded id → PASS.

Item 3 — agent-plane poke listener (Direction-2a)

• Trigger fired: the hub control loop's out-of-band report trigger (internal/hub/loop.go SetTrigger), the SAME cap-1 non-blocking channel the storage watchdog uses — fan-in, coalescing. An immediate collect→report cycle carries the advanced envelope generation → the desired-state syncer fetches → pbsdr/wg consumers apply.
• New internal/poke — Listener binds a contentless UDP socket EXCLUSIVELY to the box's WG /32 (wgtunnel.LoadAssignedAddr, new helper reading registered.json; never 0.0.0.0, never LAN) on the fixed port 51822; payload ignored; leading-edge debounce (DebounceWindow) coalesces a burst into ≤1 tick; enabled whenever wg_tunnel.enabled. Wired in main.go (goroutine + errc 7→8).
• Red-proofs (run-fail-revert): TestBindConfinement (wildcard bind → bound to :: / IsUnspecified → FAIL; fixed → the specific WG addr, datagram fires the trigger) and TestDebounceCoalescesBurst (guard removed → 10 fires for 10 pokes → FAIL; fixed → 1, then fires again after the window). Port registered in REUSE.md as a shared cross-repo constant.

Deviations from the spec's landmark guesses (source wins)

• The 403 pre-check is StorageEntry (GET /storage/<id>) exactly as ROADMAP R-22 states — no deviation; StorageActive would also 403 but the self-grant at the top fixes both.
• (Hub side, cross-repo) the MinAgent-floor save does not itself bump per-host desired generation — noted in the hub REPORT.

Live validation (Phase 5 — CC-ownable done; remainder operator-gated)

• Built + published agent 0.89.0 to Gitea (sha256 3969fd91…2609fb1a, round-trip verified) — the binary the floor-driven train (Scenario 4) fetches.
• Scenario 4 / Scenario 1 live leg / Scenario 3 latency require the demo agent to self-update to 0.89.0 via the floor train, which needs the operator-password-gated Day-0 manifest vouch + floor raise (CC cannot drive that UI). Demo agent is still 0.88.0. Direct binary replace is forbidden by the spec (the floor train IS the validation), so these legs are the operator follow-up.
• Scenario 1 rollback recorded FIRST (as required): current ACLs on the demo's /storage/felhom-offsite are FelhomAgentStore for felhom-agent@pve (user) and felhom-agent@pve!agent (token), propagate=1. Re-grant rollback = pveum acl modify /storage/felhom-offsite --users felhom-agent@pve --roles FelhomAgentStore + the --tokens 'felhom-agent@pve!agent' twin; the REVOKE that arms the deadlock is the same two with --delete. NOT run on 0.88.0 (pre-fix → no self-heal, would break the demo's pbsdr). The ep0 poke leg IS validated live — see the hub REPORT.

R-13

Item 3 is the FIRST concrete slice of the OOB/mutual-repair arc (the listener + trigger only). R-13 stays open; nothing beyond the poke channel was built.