felhom-controller/REPORT.md

REPORT — v0.101.0: campaign findings F3 (sync deadline) + F2 evidence gap (agent refusal surfacing)

Date: 2026-07-06 · Class: implementation (code + tests + deploy + live validation) Baseline: main @ af7ea0b (v0.100.0, matched the task's confirmed baseline exactly). Provenance: felhom.eu/documentation/audits/CAMPAIGN-nomercy-2026-07-06.md findings F3, F2. Companion repos: catalog d86e256 (F1 vaultwarden fix); felhom.eu audit addendum (F1/F2/F3 verdicts).

What changed

F3 — git subprocess deadline (internal/sync/sync.go)

runGitInDir took no context; a hung remote parked the sync goroutine in cmd.Run(), the doSync defer never ran, syncing stayed true, and every subsequent manual + periodic sync was refused ("Szinkronizálás már folyamatban") until a controller restart. Now: const gitCmdTimeout = 120s; a gitCmd wrapper derives a fresh per-command context.WithTimeout; runGitInDir takes a context.Context and uses exec.CommandContext; on ctx.Err() the error names the timeout + the masked git args. All three call sites (clone via runGit, fetch, reset) route through it. Debounce and failed-sync-arms-debounce semantics unchanged.

F2 evidence gap — agent refusal surfacing (internal/agentapi/client.go)

EjectDisk + Decommission used c.post, which drops any non-2xx body, flattening the agent's informative refusal to a bare HTTP 403 (the exact campaign evidence: agentapi: POST /disks/decommission: HTTP 403). Both switched to the purpose-built postWithStatus + a new shared refusalError(path, status, env) that returns agentapi: POST <path>: HTTP <code>: <agent reason, truncated ~300> (and handles the ok:false-on-2xx business-refusal case). truncateErr mirrors stacks.truncateStr. The generic post and every other caller are untouched. internal/web/storage_handlers.go already wraps the client error into its Hungarian message ("a meghajtó leszerelése sikertelen: %w" / eject err.Error()), so the role reason now reaches the UI/API response verbatim — verified by reading the handler paths (no re-truncation layer).

Tests + red-proofs (non-hollow)

Test	Asserts	Red-proof (pre-fix shape)
TestRunGitInDir_CancelledContextKillsSubprocess (T-C1)	cancelled ctx → error names the ctx cause + "deadline/killed", returns < 5s	reverted to exec.Command → FAIL: "got nil (git --version ran to completion — the pre-fix behavior)"
TestTriggerSync_FailureReleasesSyncingAndAllowsRetry (T-C2)	failed sync carries "Git hiba", syncing false after, immediate retry hits debounce, post-debounce retry EXECUTES	(behavioral; guards the lockup)
TestDecommission_RefusalReasonSurfaced (T-D1)	error contains "(role: system)" + "HTTP 403"	reverted to c.post → FAIL: "agent refusal reason discarded — operator sees only: agentapi: POST /disks/decommission: HTTP 403"
TestEjectDisk_RefusalReasonSurfaced (T-D2)	error contains "(role: backup)"	—
TestDecommission_SuccessUnchanged (T-D3)	200 envelope decodes to result	—
TestDecommission_OkFalseBusinessRefusal	ok:false-on-2xx reason surfaced	—

Both red-proofs demonstrated live (revert → FAIL with the wrong value shown → restore → pass; git diff clean). Green gate go build ./... && go vet ./... && go test ./... = PASS (exit 0); 30 passing tests across internal/sync + internal/agentapi (+2 new test files, +6 new tests).

Deploy + live validation (executed, real UI pipeline)

• Built + pushed gitea.dooplex.hu/admin/felhom-controller:0.101.0 on 180; deployed to guest 9201 via golden/bootstrap → docker ps :0.101.0 Up (healthy).
• Catalog synced (startup sync pulled the F1 template; grep _ENABLE_SMTP present in the guest docker-compose.yml + .felhom.yml).
• Scenario A (F1 acceptance): stopped + removed the crash-looping vaultwarden via the UI /stop + /remove endpoints (remove correctly 409'd until stopped — "still running"); fresh POST /api/stacks/vaultwarden/deploy (app-email default off) → 202 → running in ~70s, docker inspect restarts=0; env: _ENABLE_SMTP=false, SMTP_HOST=, SMTP_FROM= (empty). No crash-loop — the pre-fix instance that was Restarting is gone.
• Scenario B (regression): POST /stacks/vaultwarden/app-email app_email_enabled=on → recreate → healthy, restarts=0, _ENABLE_SMTP=true, SMTP_HOST=felhom-controller, SMTP_FROM=vaultwarden@felhom.eu; then app_email_enabled=false → healthy, _ENABLE_SMTP=false. Left OFF. The send-tested ON path is unchanged.
• Sync smoke (F3): POST /api/sync → HTTP 200 ("Sablonok naprakészek") — the deadline change is transparent on the healthy path.

F2 verdict (real finding — agent fix deferred)

Campaign-time agent journal (persistent, survived the P6 reboots): "local-api: protected — decommission refused by role" where=/mnt/teszt_enroll role=system. roleForMountPath (agent disks.go:1031) fail-safe-returns system when no PVE storage target matches the mount — but /disks already classifies teszt_enroll as user-data. Two role paths disagree; a bind-mounted user-data drive that isn't a standalone PVE storage can't be decommissioned. Over-refusal (fail-safe), not a hole → MEDIUM. Full write-up: felhom.eu audit addendum. Agent untouched (read-only per scope); fix is a separate follow-up task.

NOT yet live-validated

Clean backup/restore (F3-volume-tar / C2 Tier-2) coverage on the now-healthy vaultwarden — awaits the separate targeted P1–P3 campaign re-run (a runbook, not this task).

Not changed

felhom-agent (read-only; F2 is diagnosis only). The generic agentapi.post error format, the sync debounce, and the other five smtp-mapped catalog templates.