R-812 option A: the Proxmox package lane (layer pve) + the /etc/pve write gate

The wrapper gains layer "pve" (slow lane): the host's Proxmox userspace
packages only — origin "Proxmox Debian Repository", never a kernel / boot /
firmware / microcode name (R14), no removal, no undo, a new package only from
an allow-list; authority = a signed os_pve_step or the root-owned ring-0 mark.
The night leg runs it in ring 0 after a healthy host step; ring 1 only by a
signed job (PVEStepExecutor). While it runs, the agent's own /etc/pve writes
(every non-GET API call, pct config verbs, pvesm, pveum, felhom-pbs-apply)
wait on internal/pvegate. Health = the host rule + unchanged container ids +
pveversion reads the installed pve-manager.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS

internal/proxmox/client.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/pvegate"
 	"io"
 	"net/http"
 	"net/url"
@@ -105,6 +106,15 @@ func (c *Client) do(ctx context.Context, method, path string, body io.Reader, ou
 // doBody is the single HTTP chokepoint: builds the request, sets auth, executes,
 // maps non-2xx to APIError, and decodes the data envelope.
 func (c *Client) doBody(ctx context.Context, method, path string, body io.Reader, contentType string, out any) error {
+	// R-812 option A: every non-GET call may write /etc/pve — it waits while a Proxmox package step restarts pmxcfs
+	// (pvegate). Pinned by TestPVEGate_ClientWriteWaitsGetDoesNot.
+	if method != http.MethodGet {
+		release, _, gerr := pvegate.Write(ctx)
+		if gerr != nil {
+			return fmt.Errorf("proxmox: %s %s held back by a Proxmox package step: %w", method, path, gerr)
+		}
+		defer release()
+	}
 	req, err := http.NewRequestWithContext(ctx, method, c.base+path, body)
 	if err != nil {
 		return fmt.Errorf("proxmox: building request: %w", err)

internal/proxmox/privileged.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/pvegate"
 	"io"
 	"os/exec"
+	"path/filepath"
 	"strconv"
 )
 
@@ -59,6 +61,15 @@ func (r *ExecRunner) Run(ctx context.Context, name string, args ...string) ([]by
 // RunStdin is Run with the process stdin fed from stdin (nil = no stdin). The sudo-prefix/mode
 // handling is identical to Run — kept here so both paths share one place.
 func (r *ExecRunner) RunStdin(ctx context.Context, stdin io.Reader, name string, args ...string) ([]byte, []byte, error) {
+	// R-812 option A: a root CLI that writes /etc/pve waits while a Proxmox package step runs (pvegate).
+	// Pinned by TestPVEGate_ExecRunnerPctSetWaits / TestWritesEtcPVE.
+	if WritesEtcPVE(name, args) {
+		release, _, gerr := pvegate.Write(ctx)
+		if gerr != nil {
+			return nil, nil, fmt.Errorf("proxmox: %s held back by a Proxmox package step: %w", name, gerr)
+		}
+		defer release()
+	}
 	var cmd *exec.Cmd
 	if r.Mode == RunnerSudo {
 		sudo := r.SudoPath
@@ -77,6 +88,28 @@ func (r *ExecRunner) RunStdin(ctx context.Context, stdin io.Reader, name string,
 	return stdout.b, stderr.b, err
 }
 
+// WritesEtcPVE reports whether a root command writes /etc/pve: `pct` with a config-changing verb, `pvesm`, `pveum`,
+// and the PBS storage wrapper's create / reconcile verbs. `pct exec|status|list|config` and every other command do not
+// (the os-update wrapper itself must never wait on the gate its own step holds). Pinned by TestWritesEtcPVE.
+func WritesEtcPVE(name string, args []string) bool {
+	base := filepath.Base(name)
+	switch base {
+	case "pvesm", "pveum":
+		return true
+	case "pct":
+		if len(args) == 0 {
+			return false
+		}
+		switch args[0] {
+		case "set", "create", "destroy", "restore", "unlock", "resize", "snapshot", "delsnapshot", "rollback", "move-volume", "start", "stop", "reboot", "shutdown":
+			return true
+		}
+	case "felhom-pbs-apply":
+		return len(args) > 0 && (args[0] == "create" || args[0] == "reconcile")
+	}
+	return false
+}
+
 // Privileged is the root-CLI backend.
 type Privileged struct {
 	runner Runner

internal/proxmox/pvegate_test.go

@@ -0,0 +1,92 @@
+package proxmox
+
+import (
+	"context"
+	"net/http"
+	"testing"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/pvegate"
+)
+
+// R-812 option A: while a Proxmox package step holds the gate, a non-GET API call waits and a GET does not.
+//
+// COMPANION RED-PROOF (observed): delete the pvegate.Write block in doBody → this fails with "a PUT reached the API
+// while the Proxmox step held the gate". Restored. (audits/day-2026-10-07/B/red-pvegate-chokepoints.txt)
+func TestPVEGate_ClientWriteWaitsGetDoesNot(t *testing.T) {
+	d := &mockDoer{fn: func(*http.Request) (*http.Response, error) { return jsonResp(200, `{"data":null}`), nil }}
+	c := newTestClient(d)
+	end, err := pvegate.Step(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := c.get(context.Background(), "/nodes", nil); err != nil {
+		t.Fatalf("a GET must not wait on the gate: %v", err)
+	}
+	if d.calls != 1 {
+		t.Fatalf("the GET must reach the API, calls=%d", d.calls)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	err = c.postForm(ctx, http.MethodPut, "/nodes/x/lxc/9201/config", nil, nil)
+	if d.calls != 1 {
+		end()
+		t.Fatal("a PUT reached the API while the Proxmox step held the gate")
+	}
+	if err == nil {
+		end()
+		t.Fatal("a PUT held back past its deadline must fail")
+	}
+	end()
+	if err := c.postForm(context.Background(), http.MethodPut, "/nodes/x/lxc/9201/config", nil, nil); err != nil || d.calls != 2 {
+		t.Fatalf("after the step the PUT must go through (err=%v calls=%d)", err, d.calls)
+	}
+}
+
+// A root `pct set` waits on the gate; `pct exec` does not.
+//
+// COMPANION RED-PROOF (observed): delete the WritesEtcPVE block in RunStdin → this fails with "pct set ran while the
+// Proxmox step held the gate". Restored.
+func TestPVEGate_ExecRunnerPctSetWaits(t *testing.T) {
+	r := &ExecRunner{Mode: RunnerDirect}
+	end, err := pvegate.Step(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer end()
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, _, err = r.Run(ctx, "/nonexistent/pct", "set", "9201", "-mp8", "/x")
+	if err == nil || time.Since(start) < 90*time.Millisecond {
+		t.Fatalf("pct set ran while the Proxmox step held the gate (err=%v after %s)", err, time.Since(start))
+	}
+	start = time.Now()
+	_, _, _ = r.Run(context.Background(), "/nonexistent/pct", "exec", "9201", "--", "true")
+	if time.Since(start) > 80*time.Millisecond {
+		t.Fatal("pct exec must not wait on the gate")
+	}
+}
+
+func TestWritesEtcPVE(t *testing.T) {
+	for _, c := range []struct {
+		name string
+		args []string
+		want bool
+	}{
+		{"pct", []string{"set", "9201", "-mp8", "x"}, true},
+		{"/usr/sbin/pct", []string{"create", "9201"}, true},
+		{"pct", []string{"exec", "9201", "--", "true"}, false},
+		{"pct", []string{"status", "9201"}, false},
+		{"pvesm", []string{"add", "dir", "x"}, true},
+		{"pveum", []string{"acl", "modify"}, true},
+		{"/usr/local/sbin/felhom-pbs-apply", []string{"reconcile"}, true},
+		{"/usr/local/sbin/felhom-pbs-apply", []string{"read"}, false},
+		{"/usr/local/sbin/felhom-os-apply", []string{"--plan", "x"}, false},
+		{"pct", nil, false},
+	} {
+		if got := WritesEtcPVE(c.name, c.args); got != c.want {
+			t.Errorf("WritesEtcPVE(%s %v) = %v, want %v", c.name, c.args, got, c.want)
+		}
+	}
+}