slice 8B (controller half): app-consistent backup quiesce loop (v0.36.0)

internal/quiesce: poll /backup/due -> quiesce (stop app stacks) -> POST /backup
-> poll /backup/status -> unquiesce (restart exactly those). Crash-safety:
persisted marker before stopping, guaranteed unquiesce (defer), max-quiesce
guard, startup Recover, single-flight. agentapi BackupDue/StartBackup/
BackupStatus; stacks.RunningAppStacks(); config QuiesceConfig; main wiring.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

controller/internal/agentapi/client.go

@@ -7,6 +7,7 @@
 package agentapi
 
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"crypto/tls"
@@ -102,6 +103,77 @@ func (c *Client) Storage(ctx context.Context) (StorageResponse, error) {
 	return out, nil
 }
 
+// ---- slice 8B: app-consistent backup (quiesce loop) -------------------------------------
+
+// DueResponse mirrors the agent's GET /backup/due payload.
+type DueResponse struct {
+	VMID   int    `json:"vmid"`
+	Due    bool   `json:"due"`
+	Reason string `json:"reason"`
+}
+
+// BackupResponse mirrors the agent's POST /backup payload.
+type BackupResponse struct {
+	VMID  int    `json:"vmid"`
+	JobID string `json:"job_id"`
+	Phase string `json:"phase"`
+}
+
+// StatusResponse mirrors the agent's GET /backup/status payload.
+type StatusResponse struct {
+	VMID  int    `json:"vmid"`
+	Phase string `json:"phase"` // idle | running | done | failed
+	JobID string `json:"job_id"`
+	Error string `json:"error"`
+}
+
+// Backup status phases (mirror the agent's vocabulary).
+const (
+	PhaseIdle    = "idle"
+	PhaseRunning = "running"
+	PhaseDone    = "done"
+	PhaseFailed  = "failed"
+)
+
+// BackupDue reports whether a policy-scheduled backup is due for this guest (the quiesce trigger).
+func (c *Client) BackupDue(ctx context.Context) (DueResponse, error) {
+	var out DueResponse
+	body, err := c.get(ctx, "/backup/due")
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("agentapi: decode /backup/due: %w", err)
+	}
+	return out, nil
+}
+
+// StartBackup enqueues a backup of this guest (the agent vzdump) and returns the job to poll.
+func (c *Client) StartBackup(ctx context.Context) (BackupResponse, error) {
+	var out BackupResponse
+	body, err := c.post(ctx, "/backup", struct{}{})
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("agentapi: decode POST /backup: %w", err)
+	}
+	return out, nil
+}
+
+// BackupStatus reports the current/last backup job phase for this guest.
+func (c *Client) BackupStatus(ctx context.Context) (StatusResponse, error) {
+	var out StatusResponse
+	body, err := c.get(ctx, "/backup/status")
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("agentapi: decode /backup/status: %w", err)
+	}
+	return out, nil
+}
+
 // get issues an authenticated GET and unwraps the {ok,data,error} envelope.
 func (c *Client) get(ctx context.Context, path string) (json.RawMessage, error) {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
@@ -128,6 +200,38 @@ func (c *Client) get(ctx context.Context, path string) (json.RawMessage, error)
 	return env.Data, nil
 }
 
+// post issues an authenticated JSON POST and unwraps the {ok,data,error} envelope. The agent
+// returns 200 or 202 for accepted requests.
+func (c *Client) post(ctx context.Context, path string, body any) (json.RawMessage, error) {
+	buf, err := json.Marshal(body)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(buf))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.token)
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("agentapi: POST %s: %w", path, err)
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
+		return nil, fmt.Errorf("agentapi: POST %s: HTTP %d", path, resp.StatusCode)
+	}
+	var env apiResponse
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, fmt.Errorf("agentapi: POST %s: bad envelope: %w", path, err)
+	}
+	if !env.OK {
+		return nil, fmt.Errorf("agentapi: POST %s: %s", path, env.Error)
+	}
+	return env.Data, nil
+}
+
 // normalizeFingerprint lowercases and strips ':'/' ' separators, requiring a 64-hex SHA-256.
 func normalizeFingerprint(fp string) (string, error) {
 	s := strings.ToLower(strings.NewReplacer(":", "", " ", "", "\t", "").Replace(strings.TrimSpace(fp)))