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 — ALL THREE LEGS PROVEN LIVE on the demo, 2026-07-17)

• Built + published agent 0.89.0 to Gitea (sha256 3969fd91…2609fb1a, round-trip verified).
• Scenario 4 — floor-driven A/B train (0.88→0.89), PROVEN LIVE. Operator vouched 0.89.0 + raised MinAgent to 0.89.0, then signed+enqueued the agent_update op (the self-update trigger — a per-box operator-signed op; the vouch+floor alone does NOT queue it; CC cannot sign, per DRILL-GL6). The box fetched it on its next report and self-updated: gate decision class=agent_update allowed=true reason=signed key_id=felhom-op-1 → download (sha 3969fd91… verified) → felhom-selfupdate-guarded apply (root A/B flip) → new daemon version=0.89.0 → 60 s dwell → selfupdate: update committed (no rollback). Poke listener bound clean: poke: listening … addr=10.77.0.2:51822; 63/63 caps.
• Scenario 1 — R-22 self-heal, PROVEN LIVE. Rollback re-grant recorded FIRST (pveum acl modify /storage/felhom-offsite --users felhom-agent@pve --roles FelhomAgentStore + the --tokens 'felhom-agent@pve!agent' twin — delete syntax is pveum acl delete). Faithful F4 reproduction: moved the pbsdr marker aside (the reinstall's fresh-state — revoke-alone is a no-op because the applied marker short-circuits Apply before any storage read; an important reproduction finding) + pveum acl delete both felhom-offsite ACLs. Next reconcile tick: 08:24:16 pbsdr: pre-check 403 … self-granting via the root wrapper … (R-22) storage_id=felhom-offsite → 08:24:19 pbsdr: converged state=adopted — ~3 s, no operator action. Verified: ACLs self-restored (user+token), marker rewritten (adopted), pvesm status felhom-offsite = active. Pre-fix = permanent 403→abort loop.
• Scenario 3 — poke → tick latency, MEASURED LIVE. ep0 send 06:28:55.765 UTC → box 08:28:55.796 poke received → triggering an immediate desired-state cycle from=10.77.0.1 → same instant out-of-band report triggered (watchdog/poke). ~31 ms ep0→box over the tunnel (spike ~29 ms), sub-ms to the report cycle; WG-confined (from 10.77.0.1, to the 10.77.0.2-bound socket). The hub-save→poke fire is separately live-proven (hub REPORT: real manifest save → sync-poke delivered to 10.77.0.2); full save→tick ≈ ~0.45 s (SSH-dominated), well under the ≤2–3 s target.

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.