felhom-agent/REPORT.md

REPORT — v0.41.0: provisioned customer guests auto-start after a host reboot (onboot:1, F3)

Repo: felhom-agent · Version: v0.40.0 → v0.41.0 · Date: 2026-06-24 Baseline: main @ db95d51 (version var 0.40.0), trunk-based, no branches. Class: risky/supervised — touches the provisioning chain (back-half).

Finding (F3, from TEST-REPORT-stable-path-sysdrive-restart-2026-06-23.md)

The golden bakes --onboot 0 (configs/build-golden.sh:63, template safety) and the provision back-half never overrode it → every provisioned customer guest was onboot:0. After a host reboot/power-cut the customer's whole home-server (controller + all apps) stays down until a manual pct start. Confirmed live in the campaign (Phase 4.1: host rebooted → pct status 9201 = stopped).

The fix

internal/provision/backhalf.go, BackHalf.Provision: added a fatal step right after the config-mount attach (and before the guest-hook install):

if err := b.run(ctx, "pct", "set", strconv.Itoa(in.VMID), "-onboot", "1"); err != nil {
    return Result{}, fmt.Errorf("provision: set onboot: %w", err)
}

• Locus = the back-half, not the golden. build-golden.sh --onboot 0 is unchanged — a template must not auto-start; onboot is a per-guest property the back-half is the right place to set.
• Fatal, like the config-mount attach (a guest that won't auto-recover is a provisioning defect).
• No startup/boot-order/delay (operator decision): the v0.75 mountpoint-gate already covers the drive-bind race at boot (Phase 4.4). The agent never auto-pct starts anything — this is config only.

Test + red-proof

internal/provision/backhalf_test.go:

• Added TestProvision_SetsOnbootOne — asserts the exact pct set 8200 -onboot 1 invocation was recorded by the fake runner (via a new recRunner.hasExact helper, since several pct calls are now recorded and find only returns the first).
• Red-proof (run/confirm/revert): removed the b.run(... -onboot 1) call → TestProvision_SetsOnbootOne FAILED (expected 'pct set 8200 -onboot 1' to be issued) → restored the call → green.
• Existing back-half tests stay green (chown-failure-stops still holds: onboot is after the config-mount attach, so a chown failure never reaches it).
• Green gate: go build ./... ✓ · go vet ./... ✓ · go test ./... ✓ (all packages ok).

Deploy + remediate + verify

A. Build + deploy agent v0.41.0 on the build server (-ldflags -X main.version=0.41.0), scp to felhom-pve, back up the prior binary, install, restart the service. — filled below

B. Demo remediation (9201 was provisioned pre-fix → onboot:0): pct set 9201 -onboot 1 (non-destructive, config-only) → pct config 9201 | grep onboot → filled below

C. Back-half fix proper — NOT yet live-validated. The unit test + pct config 9201 → onboot:1 cover the immediate state, but the back-half path itself (a fresh provision emitting onboot:1 with no manual set) awaits the deferred supervised capstone re-provision (destroy + re-provision 9201 with the new agent) — operator-gated, needs the golden volid + retrieval passphrase.

Optional (operator-gated): reboot felhom-pve → confirm 9201 auto-starts (pct status 9201 = running without a manual pct start) — the exact Phase-4.1 failure, now expected to pass.