feat(agent): scaffold + proxmox interaction layer (slice 1)

Stand up the felhom-agent project (module gitea.dooplex.hu/admin/felhom-agent,
binary felhom-agent) and the internal/proxmox package: the typed library every
other agent module calls to talk to Proxmox.

- API-first Client (hand-rolled REST over net/http, PVEAPIToken auth) with typed
  read ops (version/nodes/status/lxc/config/storage) and async mutating ops
  (restore/vzdump/snapshot/rollback/delete-snapshot/setconfig/start/stop), each
  returning a UPID. WaitTask polls task status until stopped and asserts
  exitstatus OK (authz can surface at task exec, not the POST — phase1-2 §1.3).
- Fenced Privileged (root-CLI) backend for the THREE proven exceptions only
  (keyctl pct create, USB mount/fstab, SMART/sensors); each cites why it can't be
  the API. Fence is structural (Client never shells out, Privileged never HTTPs)
  and asserted in routing_test.go.
- TLS: SHA-256 leaf-cert pinning or CA file; insecure mode explicit + off by
  default. No blanket verification disable.
- 403 -> privilege-named APIError; failed task -> privilege-named TaskError.
- JSON config + env overrides (token never logged); slog logging.
- cmd/felhom-agent --selftest (read-only health report) + gated --selftest=task
  (reversible snapshot/rollback/delete exercise of WaitTask). No daemon loop yet.
- Types grounded in the spike findings and exact JSON shapes captured live from
  demo-felhom (PVE 9.2.2). Unit tests use a mock transport + runner.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

internal/proxmox/upid.go

@@ -0,0 +1,63 @@
+package proxmox
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// UPID is a parsed Proxmox task identifier. Long operations (vzdump, restore,
+// snapshot, ...) return a UPID rather than a result; the caller polls the task.
+//
+// Wire format (captured live, demo-felhom):
+//
+//	UPID:demo-felhom:00026454:004E3431:6A265E53:vzdestroy:9021:root@pam:
+//	     |node       |pid-hex |pstart-hx|start-hex |worker   |id   |user    |(trailing)
+type UPID struct {
+	Raw       string
+	Node      string
+	PID       uint64 // decoded from hex
+	PStart    uint64 // decoded from hex
+	StartTime uint64 // decoded from hex (unix seconds)
+	Worker    string // task type, e.g. "vzdump", "vzdestroy", "vzsnapshot"
+	ID        string // worker target, e.g. the vmid as a string
+	User      string // e.g. "root@pam" or "felhom-agent@pve!agent"
+}
+
+// ParseUPID parses a Proxmox UPID string. The user field may contain '@' and '!'
+// but never ':', so a plain colon-split is correct.
+func ParseUPID(s string) (UPID, error) {
+	if !strings.HasPrefix(s, "UPID:") {
+		return UPID{}, fmt.Errorf("proxmox: not a UPID: %q", s)
+	}
+	// UPID:node:pid:pstart:starttime:worker:id:user:  -> 9 fields, last empty
+	parts := strings.Split(s, ":")
+	if len(parts) < 8 {
+		return UPID{}, fmt.Errorf("proxmox: malformed UPID (%d fields): %q", len(parts), s)
+	}
+	pid, err := strconv.ParseUint(parts[2], 16, 64)
+	if err != nil {
+		return UPID{}, fmt.Errorf("proxmox: bad UPID pid %q: %w", parts[2], err)
+	}
+	pstart, err := strconv.ParseUint(parts[3], 16, 64)
+	if err != nil {
+		return UPID{}, fmt.Errorf("proxmox: bad UPID pstart %q: %w", parts[3], err)
+	}
+	start, err := strconv.ParseUint(parts[4], 16, 64)
+	if err != nil {
+		return UPID{}, fmt.Errorf("proxmox: bad UPID starttime %q: %w", parts[4], err)
+	}
+	return UPID{
+		Raw:       s,
+		Node:      parts[1],
+		PID:       pid,
+		PStart:    pstart,
+		StartTime: start,
+		Worker:    parts[5],
+		ID:        parts[6],
+		User:      parts[7],
+	}, nil
+}
+
+// String returns the original wire form.
+func (u UPID) String() string { return u.Raw }