REPORT: the burn-down night (2026-10-06)

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

CHANGELOG.md

@@ -1,4 +1,29 @@
-## unreleased (to be released as v0.147.0) — the recovery recipe spells the root namespace the way PBS does; a removed drive no longer shows the root disk's size; a rotated-out token stops at once; the dnsmasq check looks at the right package (burn-down round 2: R-124, R-118, R-269, R-317) (2026-10-05)
+## unreleased
+
+- R-426: scripts/test_gate_decoys.py (new) — the published gate judged against a fake Gitea (127.0.0.1, via GITEA_BASE; never the real registry): 11 cases; COVERS published — `felhom-agent/published` leaves the decoy-coverage EXEMPT list.
+- R-426: release-complete gate — 10 decoy cases (scratch clone + scratch bare origin + fake Gitea); COVERS release-complete — `felhom-agent/release-complete` leaves the decoy-coverage EXEMPT list.
+- R-426: the shared reuse-refs/instructions/observations gates get agent-side decoys (9 cases on a scratch clone of this repo); COVERS reuse-refs, instructions, observations — three `felhom-agent/*` entries leave the decoy-coverage EXEMPT list.
+- **Fixed without a row:** `configs/test_felhom_config_bundle.py` read the two ISO first-boot files that installer 1.32.0 now NAMES under KEPT (R-275) as files the installer writes — `go test ./internal/osupdate` was red on DooPlex from 21:25 to 01:55 (felhom.eu `85de3f9b`); they are listed with why. Test only; agent v0.148.0's code is unaffected.
+
+## v0.148.0 — the host report names the running binary's sha; the format answer carries the new filesystem's UUID (burn-down night: R-349, R-25 agent halves) (2026-10-06)
+
+Released by `scripts/release-agent.sh`: binary sha256 `3e68a0870e0e2ce262cb4819294edddeb0a73e8c558a31611a20329a6d9ee283`
+config bundle sha256 `a6fa4f589d184b58c9911303bd087e300be1e75b3647e4302c9594df6989c4de` (tag `v0.148.0` = `861d32a`).
+Delivery order as for v0.147.0: signed `agent_update`, then signed `agent_config_update`.
+
+- **R-349:** the host report carries `agent_sha256`, the sha256 of the running agent binary (read once from
+  `/proc/self/exe`; empty = unknown), so a hand-built binary under the vouched version name becomes visible. The hub
+  comparison is a separate hub change. Test `TestCollect_AgentSHA256IsTheRunningBinary`; red-proved.
+- **R-25 (agent half):** `POST /disks/format` and `GET /disks/format/status` return `fs_uuid`, the new filesystem's UUID
+  read back after mkfs only when the bound durable id still resolves to the formatted device and the superblock is the
+  requested type (empty = not verified); `DeviceProbe` gains `FSUUID` from blkid. Tests `TestFormat_*FSUUID*`; three
+  red-proofs. The controller half (mount that UUID) is a controller change.
+
+## v0.147.0 — the recovery recipe spells the root namespace the way PBS does; a removed drive no longer shows the root disk's size; a rotated-out token stops at once; the dnsmasq check looks at the right package (burn-down round 2: R-124, R-118, R-269, R-317) (2026-10-05)
+
+Released by `scripts/release-agent.sh`: binary sha256 `642c4d196c48671c14ff653118303c5903af1670b7abb550edeaf73e701cd5b8`,
+config bundle sha256 `326527d0993c9a62df2f790c7700ca645cedbf0673dcfb6dc1768d8610b8007d` (tag `v0.147.0` = `f1b9b41`).
+Delivery order as for v0.146.1: signed `agent_update`, then signed `agent_config_update`.
 
 MinAgent impact: none (the controller needs nothing new from this agent). Config bundle content unchanged from v0.146.1.
 

REPORT.md

@@ -1,7 +1,16 @@
-# REPORT — 2026-10-05 burn-down: two record corrections (no release)
+# REPORT — agent v0.148.0 (2026-10-06, the burn-down night)
 
-Full session report: `felhom.eu/REPORT-burndown-2026-10-05.md`. Baseline `e06ed97` (v0.146.1). No binary, bundle or
+Full session report: `felhom.eu/REPORT-burndown3-2026-10-06.md`. Baseline `208fac8` (v0.147.0).
-version change; `go build`, `go vet ./internal/backup/`, `agent_gates.py --fast` green.
 
-- R-291 — `scripts/retention-policy.json`: the source of the number (R-267 newest-10 prune, R-287) and readers corrected.
+**Released:** v0.148.0 (tag = `861d32a`; binary sha256 `3e68a087…`, bundle `a6fa4f58…`, verified by download). R-349
-- R-348 — `internal/backup/store.go`: the restart comment says what a restart really blanks.
+(the host report carries `agent_sha256` — the hub's host pages read „matches vouched” for all three boxes) and R-25's
+agent half (the format answer carries the verified `fs_uuid`). **Delivered** by signed `agent_update` (all three on
+0.148.0 by 22:50Z) and `agent_config_update` (root files 0.148.0 by 22:58Z) to demo-hp, demo-felhom, Tester 1. Tester 2:
+nothing sent (off).
+
+**On main, unreleased:** R-426 decoys (new `scripts/test_gate_decoys.py`: published against a fake Gitea,
+release-complete, the shared reuse-refs/instructions/observations).
+
+**Said plainly:** `go test ./internal/osupdate` was red on DooPlex from 21:25 to 01:55 — `configs/test_felhom_config_bundle.py`
+read the installer 1.32.0 KEPT names as installer-written files. The v0.148.0 binary was released inside that window;
+its code is unaffected (a test-only sibling coupling; CI has no Go). Fixed in `b2b82ae`.

REUSE.md

@@ -66,7 +66,7 @@
 |---|---|---|---|---|
 | `IntentStore` (`Get/SetEnrolled/SetEjected/SetDecommissioned/OnAbsent`) | internal/storage/intent.go | `OpenIntentStore(path)` | drive intent (4-state self-heal) | Keyed by durable-id only; `OnAbsent` is the ONLY ejected→enrolled path; refuses empty ids |
 | `GuestBindStore` (`Record/Remove/Guests`) | internal/localapi/guestbindstore.go | `OpenGuestBindStore(path)` | per-guest enrolled binds (F9 re-assert) | Same tmp+rename 0600 pattern as IntentStore |
-| `FormatJobStore` + `startFormatDetached` + `RecoverFormatJob` | internal/localapi/formatjob.go | `startFormatDetached(device, durableID, fstype, blank) <-chan error` | detached, restart-surviving mkfs (F20-BUG3) | Runs off `s.baseCtx` (60-min bound) so a request deadline can't SIGKILL mkfs; recovery re-resolves by durable id; blank jobs re-check STILL-blank |
+| `FormatJobStore` + `startFormatDetached` + `RecoverFormatJob` | internal/localapi/formatjob.go | `startFormatDetached(device, durableID, fstype, blank) (*formatJob, <-chan error)` | detached, restart-surviving mkfs (F20-BUG3) | Runs off `s.baseCtx` (60-min bound) so a request deadline can't SIGKILL mkfs; recovery re-resolves by durable id; blank jobs re-check STILL-blank; on success `job.FSUUID` = the new filesystem's UUID, read back only when the durable id still resolves to the formatted device (R-25) — read it only after `done` delivers |
 | `TokenStore.Mint` / `Lookup` | internal/localapi/tokenstore.go | `Mint(vmid) (plaintext, error)` | per-guest local-API tokens | Only the SHA-256 hash persists (fsync'd append log); constant-time compare on lookup; plaintext returned exactly once. Lookup stats the file on EVERY call and reloads BEFORE answering when the append-only log grew (R-269; was reload-on-miss only, v0.63.0 B3, which let a token rotated out by another process keep authorizing as a map hit): the one-shot provisioner mints into the same file the daemon indexes — cross-process coherence both ways without a restart; unchanged size = no re-read. Pinned by `TestTokenStore_RotatedOutTokenRejectedFirst` |
 | `FileNonceStore.SeenOrRecord` | internal/authz/noncestore.go | `SeenOrRecord(nonce, exp) bool` | durable anti-replay | fsync'd before returning false; prune only after exp |
 | `Journal` (`Append/Latest/InFlight/AlreadyApplied`) | internal/reconcile/journal.go | `OpenJournal(path)` | op journal + idempotency + crash recovery | `Recover` consumes `InFlight()`; scratch entries special-cased |

configs/test_felhom_config_bundle.py

@@ -546,7 +546,10 @@ class Builder(unittest.TestCase):
                                r"/etc/felhom/[a-z.-]+)", text))
         agent_writes = {"/usr/local/sbin/felhom-shared-parent", "/etc/systemd/system/felhom-shared-parent.service"}
         trust = {osapply.TRUST_FILE, osapply.TRUST_SIGNERS, osapply.TRUST_SIGNERS + ".tmp", osapply.BUNDLE_RECORD}
-        missing = sorted(p for p in found if p not in osapply.BUNDLE_DESTS and p not in agent_writes | trust)
+        # Written by the appliance ISO's first boot (felhom.eu scripts/iso/felhom-bootstrap.sh), never by the installer:
+        # since installer 1.32.0 (R-275) the uninstall only NAMES them under KEPT.
+        iso_writes = {"/etc/felhom/.bootstrap-done", "/etc/felhom/appliance-pairing-code"}
+        missing = sorted(p for p in found if p not in osapply.BUNDLE_DESTS and p not in agent_writes | trust | iso_writes)
         self.assertEqual(missing, [], "the installer writes these root files, but the bundle does not carry them")
         # the limits drop-in is named through $AGENT_UNIT in the installer
         self.assertIn("/etc/systemd/system/felhom-agent.service.d/felhom-agent-limits.conf", osapply.BUNDLE_DESTS)

internal/hub/collect.go

@@ -10,6 +10,7 @@ import (
 	"log/slog"
 	"os"
 	"strings"
+	"sync"
 	"time"
 
 	"gitea.dooplex.hu/admin/felhom-agent/internal/capability"
@@ -115,6 +116,7 @@ type Collector struct {
 	backupTarget     func() ConfiguredBackupTarget                 // R-109: primary backup tier id (nil → recipe records unknown)
 	hostID           string
 	agentVersion     string
+	selfSHA          func() string // R-349: sha256 of the running binary; default runningBinarySHA256
 	logger           *slog.Logger
 	now              func() time.Time
 }
@@ -135,6 +137,7 @@ func NewCollector(px proxmoxReader, cf CloudflaredProber, storage StorageObserve
 		temp:         SysfsTempReader{}, // slice 9: real sysfs reader by default; tests inject a fake
 		hostID:       hostID,
 		agentVersion: agentVersion,
+		selfSHA:      runningBinarySHA256,
 		logger:       logger,
 		now:          func() time.Time { return time.Now().UTC() },
 	}
@@ -337,6 +340,7 @@ func (c *Collector) Collect(ctx context.Context) (*HostReport, error) {
 		HostID:       c.hostID,
 		ReportedAt:   c.now().Format(time.RFC3339),
 		AgentVersion: c.agentVersion,
+		AgentSHA256:  c.agentSHA256(),
 		Host:         host,
 		Guests:       c.collectGuests(ctx),
 		// storage_targets populated this slice (slice 5) via the observer; the rest stay
@@ -431,8 +435,28 @@ const pbsWrapperPath = "/usr/local/sbin/felhom-pbs-apply"
 // unreadable file yields "", which the hub reads as UNKNOWN rather than as drift — a host that
 // legitimately has no DR wrapper must not light up amber. The file is 0755, so no privilege is
 // needed to read it.
-func pbsWrapperSHA256() string {
+func pbsWrapperSHA256() string { return fileSHA256(pbsWrapperPath) }
-	f, err := os.Open(pbsWrapperPath)
+
+// selfExePath is the running binary as the kernel holds it. /proc/self/exe, not the installed path:
+// after an A/B flip the file at /usr/local/bin/felhom-agent may already be the NEXT binary while this
+// process still runs the old one, and the report must describe what runs (R-349). Test seam.
+var selfExePath = "/proc/self/exe"
+
+// runningBinarySHA256 hashes the running binary ONCE per process — the bytes cannot change under a
+// running process, and re-hashing ~20 MB every report cycle buys nothing. A failed read is cached as
+// "" (UNKNOWN); it never fails the report.
+var runningBinarySHA256 = sync.OnceValue(func() string { return fileSHA256(selfExePath) })
+
+func (c *Collector) agentSHA256() string {
+	if c.selfSHA == nil {
+		return ""
+	}
+	return c.selfSHA()
+}
+
+// fileSHA256 is the hex sha256 of a file's bytes, or "" when it cannot be read.
+func fileSHA256(path string) string {
+	f, err := os.Open(path)
 	if err != nil {
 		return ""
 	}

internal/hub/collect_agentsha_test.go

@@ -0,0 +1,64 @@
+package hub
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// R-349: the report carries the sha256 of the binary that is RUNNING, so the hub can tell a
+// hand-built proof binary from the vouched artifact of the same version string. The consequence
+// asserted: the wire field equals the hash of this very test binary's bytes (read independently via
+// os.Executable, a different channel from /proc/self/exe), and it is on the wire as agent_sha256.
+func TestCollect_AgentSHA256IsTheRunningBinary(t *testing.T) {
+	exe, err := os.Executable()
+	if err != nil {
+		t.Skipf("os.Executable: %v", err)
+	}
+	raw, err := os.ReadFile(exe)
+	if err != nil {
+		t.Fatalf("read own binary: %v", err)
+	}
+	sum := sha256.Sum256(raw)
+	want := hex.EncodeToString(sum[:])
+
+	px := &fakePx{node: "n", ns: newTestNodeStatus()}
+	c := NewCollector(px, fakeProber{status: "running"}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
+	r, err := c.Collect(context.Background())
+	if err != nil {
+		t.Fatalf("Collect: %v", err)
+	}
+	if r.AgentSHA256 != want {
+		t.Fatalf("agent_sha256 = %q, want the running binary's %q", r.AgentSHA256, want)
+	}
+	b, err := json.Marshal(r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(b), `"agent_sha256":"`+want+`"`) {
+		t.Fatalf("agent_sha256 not on the wire: %s", b)
+	}
+}
+
+// An unreadable binary is UNKNOWN (empty, omitted) — never a made-up hash, never a failed report.
+func TestFileSHA256_UnreadableIsEmpty(t *testing.T) {
+	if got := fileSHA256(filepath.Join(t.TempDir(), "absent")); got != "" {
+		t.Fatalf("absent file hashed to %q, want empty", got)
+	}
+	px := &fakePx{node: "n", ns: newTestNodeStatus()}
+	c := NewCollector(px, fakeProber{status: "running"}, nil, nil, nil, nil, "h", "0.3.0", quietLogger())
+	c.selfSHA = func() string { return "" }
+	r, err := c.Collect(context.Background())
+	if err != nil {
+		t.Fatalf("Collect must not fail on an unreadable binary: %v", err)
+	}
+	b, _ := json.Marshal(r)
+	if strings.Contains(string(b), "agent_sha256") {
+		t.Fatalf("empty agent_sha256 must be omitted: %s", b)
+	}
+}

internal/hub/report.go

@@ -18,6 +18,16 @@ type HostReport struct {
 	HostID       string `json:"host_id"`     // echoes config.Hub.HostID
 	ReportedAt   string `json:"reported_at"` // RFC3339, agent clock
 	AgentVersion string `json:"agent_version"`
+	// AgentSHA256 is the sha256 of the binary this process is RUNNING (read through /proc/self/exe,
+	// once per process), R-349. The version string cannot tell a hand-built proof binary from the
+	// published, vouched artifact of the same version — same source, different bytes (`-trimpath
+	// -buildvcs=false` in release-agent.sh) — so self-update sees "already installed" and never
+	// corrects it. Reporting the bytes lets the hub compare against the vouched agent_sha256, the
+	// same mechanism host.wrapper_sha256 is for the PBS wrapper (R-50b(a)).
+	//
+	// Empty = unreadable, which the hub must treat as UNKNOWN, never as drift. Pinned by
+	// TestCollect_AgentSHA256IsTheRunningBinary.
+	AgentSHA256 string `json:"agent_sha256,omitempty"`
 
 	Host   HostMetrics `json:"host"`
 	Guests []Guest     `json:"guests"`

internal/localapi/disks.go

@@ -768,6 +768,11 @@ type FormatResponse struct {
 	// signature — the customer authorizes the wipe of their own data drive.
 	NeedsConfirmation bool   `json:"needs_confirmation,omitempty"`
 	DurableID         string `json:"durable_id,omitempty"` // the durable id to confirm against (user-data)
+	// FSUUID (on Formatted) is the UUID of the filesystem the agent just made, verified against the
+	// bound durable id after mkfs (R-25). The caller mounts THIS — re-resolving a UUID from the /dev
+	// path later can name another disk if /dev re-enumerated. "" = not verified: the caller must not
+	// substitute a path-resolved guess silently.
+	FSUUID string `json:"fs_uuid,omitempty"`
 	// PendingOp is set on a SYSTEM/BACKUP data-bearing refusal — the exact op the operator must sign.
 	PendingOp *PendingOp `json:"pending_op,omitempty"`
 }
@@ -815,7 +820,7 @@ func (s *Server) handleDiskFormatStatus(w http.ResponseWriter, r *http.Request,
 	writeOK(w, map[string]any{
 		"vmid": vmid, "phase": job.Phase, "device": job.Device, "fstype": job.FSType,
 		"durable_id": job.DurableID, "error": job.Error, "started_at": job.StartedAt, "updated_at": job.UpdatedAt,
-		"job_id": job.JobID,
+		"job_id": job.JobID, "fs_uuid": job.FSUUID, // R-25: "" until done + verified
 	})
 }
 
@@ -878,7 +883,7 @@ func (s *Server) handleDiskFormat(w http.ResponseWriter, r *http.Request, vmid i
 				"format refused (device may have changed since inspection): "+rerr.Error())
 			return
 		}
-		done := s.startFormatDetached(device, blankDurable, req.FSType, true)
+		job, done := s.startFormatDetached(device, blankDurable, req.FSType, true)
 		if err := s.awaitFormat(r.Context(), done, vmid, device); err != nil {
 			if err == errFormatClientGone {
 				return // client gone; mkfs continues detached + the job record records the outcome
@@ -887,7 +892,7 @@ func (s *Server) handleDiskFormat(w http.ResponseWriter, r *http.Request, vmid i
 			writeErr(w, http.StatusBadGateway, "format failed: "+err.Error())
 			return
 		}
-		writeOK(w, FormatResponse{VMID: vmid, Device: device, Formatted: true, DataBearing: false, DurableID: blankDurable, Reason: "blank device formatted " + req.FSType})
+		writeOK(w, FormatResponse{VMID: vmid, Device: device, Formatted: true, DataBearing: false, DurableID: blankDurable, FSUUID: job.FSUUID, Reason: "blank device formatted " + req.FSType})
 		return
 	}
 
@@ -924,7 +929,7 @@ func (s *Server) handleDiskFormat(w http.ResponseWriter, r *http.Request, vmid i
 		// F20-BUG3: run the destructive mkfs DETACHED off s.baseCtx (bound durable id recorded for
 		// restart-recovery), so a request/client deadline can never SIGKILL it mid-write and corrupt the
 		// disk. We still wait to return the synchronous result (backward-compatible with the controller).
-		done := s.startFormatDetached(device, deviceDurable, req.FSType, false)
+		job, done := s.startFormatDetached(device, deviceDurable, req.FSType, false)
 		if err := s.awaitFormat(r.Context(), done, vmid, device); err != nil {
 			if err == errFormatClientGone {
 				return // client gone; the wipe continues detached + survives a restart via the job record
@@ -936,7 +941,7 @@ func (s *Server) handleDiskFormat(w http.ResponseWriter, r *http.Request, vmid i
 		s.logger.Warn("local-api: USER-DATA data-bearing format — CUSTOMER CONFIRMED (no operator signature)",
 			"vmid", vmid, "device", device, "durable_id", deviceDurable, "fstype", req.FSType, "why", probe.Reason())
 		writeOK(w, FormatResponse{VMID: vmid, Device: device, Formatted: true, DataBearing: true,
-			Role: string(role), DurableID: deviceDurable, Reason: "customer-confirmed wipe (" + probe.Reason() + ")"})
+			Role: string(role), DurableID: deviceDurable, FSUUID: job.FSUUID, Reason: "customer-confirmed wipe (" + probe.Reason() + ")"})
 		return
 	}
 

internal/localapi/disks_test.go

@@ -28,6 +28,7 @@ type fakeDiskOps struct {
 	unmountCalls []string
 	candidates   []storage.CandidateDisk // returned by ListCandidateDisks
 	candErr      error
+	afterFormat  *storage.DeviceProbe // R-25: when set, InspectDevice returns it once a format ran
 }
 
 func (f *fakeDiskOps) ListCandidateDisks(_ context.Context) ([]storage.CandidateDisk, error) {
@@ -35,7 +36,12 @@ func (f *fakeDiskOps) ListCandidateDisks(_ context.Context) ([]storage.Candidate
 }
 
 func (f *fakeDiskOps) InspectDevice(_ context.Context, device string) (storage.DeviceProbe, error) {
+	f.mu.Lock()
 	p := f.probe
+	if f.afterFormat != nil && len(f.formatCalls) > 0 {
+		p = *f.afterFormat
+	}
+	f.mu.Unlock()
 	p.Device = device
 	return p, f.inspectErr
 }

internal/localapi/format_fsuuid_test.go

@@ -0,0 +1,96 @@
+package localapi
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"sync"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/storage"
+)
+
+// R-25: the format answer carries the UUID of the filesystem the agent JUST made, verified against the
+// bound durable id after mkfs, so the controller mounts that filesystem rather than whatever the /dev
+// path resolves to a few requests later. The consequence asserted: the UUID on the wire (and in the
+// polled job record) is the new superblock's — and is EMPTY whenever the binding cannot be re-proved.
+
+const newFSUUID = "0fc63daf-8483-4772-8e79-3d69d8477de4"
+
+func confirmedFormat(t *testing.T, d *fakeDiskOps, srv *Server, fj *FormatJobStore) (string, *formatJob) {
+	t.Helper()
+	w := do(t, srv.Handler(), "POST", "/disks/format", "A", `{"device":"/dev/sdb1","fstype":"ext4","confirmed":true,"durable_id":"byid:wwn-/dev/sdb1"}`)
+	if w.Code != http.StatusOK {
+		t.Fatalf("confirmed format: %d (%s)", w.Code, w.Body.String())
+	}
+	var resp struct {
+		Data FormatResponse `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v (%s)", err, w.Body.String())
+	}
+	if !resp.Data.Formatted {
+		t.Fatalf("not formatted: %s", w.Body.String())
+	}
+	return resp.Data.FSUUID, waitFormatPhase(t, fj, formatPhaseDone)
+}
+
+func confirmedGate() *fakeGate {
+	return &fakeGate{decision: WipeDecision{Allowed: true, Tier: "customer_confirmable", Reason: "customer_confirmed"}}
+}
+
+func TestFormat_ReportsNewFilesystemUUID(t *testing.T) {
+	d := &fakeDiskOps{probe: deviceProbeDataBearing(),
+		afterFormat: &storage.DeviceProbe{Probed: true, HasFilesystem: true, FSType: "ext4", FSUUID: newFSUUID}}
+	fj := tempFormatStore(t)
+	srv := formatServer(t, d, confirmedGate(), fj)
+
+	got, job := confirmedFormat(t, d, srv, fj)
+	if got != newFSUUID {
+		t.Fatalf("response fs_uuid = %q, want the new filesystem's %q", got, newFSUUID)
+	}
+	if job.FSUUID != newFSUUID {
+		t.Fatalf("job record fs_uuid = %q, want %q (the polled status path)", job.FSUUID, newFSUUID)
+	}
+}
+
+// The node moved between mkfs and the read-back: the bound durable id now resolves elsewhere. The
+// UUID must NOT be reported — reading it would name the other disk's filesystem.
+func TestFormat_FSUUIDWithheldWhenDurableIDMoved(t *testing.T) {
+	d := &fakeDiskOps{probe: deviceProbeDataBearing(),
+		afterFormat: &storage.DeviceProbe{Probed: true, HasFilesystem: true, FSType: "ext4", FSUUID: newFSUUID}}
+	fj := tempFormatStore(t)
+	srv := formatServer(t, d, confirmedGate(), fj)
+	var mu sync.Mutex
+	calls := 0
+	srv.reresolveWipe = func(_ context.Context, _ string) (string, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		calls++
+		if calls == 1 {
+			return "/dev/sdb", nil // the pre-mkfs anti-retarget re-resolve
+		}
+		return "/dev/sdc", nil // after mkfs: the durable id now names another node
+	}
+
+	got, job := confirmedFormat(t, d, srv, fj)
+	if got != "" || job.FSUUID != "" {
+		t.Fatalf("fs_uuid reported after the durable id moved (response %q, job %q) — must be empty", got, job.FSUUID)
+	}
+	if calls < 2 {
+		t.Fatalf("the post-mkfs re-resolve never ran (calls=%d)", calls)
+	}
+}
+
+// The superblock did not read back as the requested filesystem → not verified → empty.
+func TestFormat_FSUUIDWithheldOnFSTypeMismatch(t *testing.T) {
+	d := &fakeDiskOps{probe: deviceProbeDataBearing(),
+		afterFormat: &storage.DeviceProbe{Probed: true, HasFilesystem: true, FSType: "xfs", FSUUID: newFSUUID}}
+	fj := tempFormatStore(t)
+	srv := formatServer(t, d, confirmedGate(), fj)
+
+	got, job := confirmedFormat(t, d, srv, fj)
+	if got != "" || job.FSUUID != "" {
+		t.Fatalf("fs_uuid reported for a superblock of the wrong type (response %q, job %q)", got, job.FSUUID)
+	}
+}

internal/localapi/formatjob.go

@@ -22,6 +22,10 @@ type formatJob struct {
 	Blank     bool   `json:"blank,omitempty"` // audit D3: blank (benign) format — recovery re-checks STILL-blank, not data-bearing
 	Phase     string `json:"phase"`           // running | done | failed
 	Error     string `json:"error,omitempty"`
+	// FSUUID is the filesystem UUID of the NEW filesystem, read by the agent right after mkfs on the
+	// device the bound durable id still resolves to (R-25). "" = not verified (the controller must not
+	// read that as a UUID). Set only on phase done.
+	FSUUID    string `json:"fs_uuid,omitempty"`
 	StartedAt string `json:"started_at"`
 	UpdatedAt string `json:"updated_at"`
 }
@@ -96,7 +100,10 @@ func (s *FormatJobStore) save(j *formatJob) error {
 // runs to completion and records the outcome. device is the ALREADY anti-retarget-resolved device; the
 // record carries durableID so a restart can re-resolve + re-run. blank marks a benign (blank-device)
 // format, so restart recovery re-checks STILL-blank rather than data-bearing (audit D3).
-func (s *Server) startFormatDetached(device, durableID, fstype string, blank bool) <-chan error {
+//
+// The returned job may be read (FSUUID) only AFTER a value arrives on done — the goroutine writes it
+// before the send, which is the happens-before edge.
+func (s *Server) startFormatDetached(device, durableID, fstype string, blank bool) (*formatJob, <-chan error) {
 	base := s.baseCtx
 	if base == nil {
 		base = context.Background()
@@ -116,10 +123,39 @@ func (s *Server) startFormatDetached(device, durableID, fstype string, blank boo
 		ctx, cancel := context.WithTimeout(base, 60*time.Minute)
 		defer cancel()
 		err := s.disks.Format(ctx, device, fstype)
+		if err == nil {
+			job.FSUUID = s.formattedFSUUID(ctx, device, durableID, fstype)
+		}
 		s.finishFormatJob(job, err)
 		done <- err
 	}()
-	return done
+	return job, done
+}
+
+// formattedFSUUID reads the UUID of the filesystem the agent has JUST made (R-25). The caller used to
+// re-resolve the UUID from the mutable /dev path afterwards, over separate requests — a re-enumeration
+// in that window could hand it ANOTHER disk's filesystem to mount. Here the bound durable id must still
+// resolve to the very device that was formatted (and re-derive to the same id), and the superblock must
+// carry the fstype that was asked for; anything else returns "" (not verified), never a guess.
+func (s *Server) formattedFSUUID(ctx context.Context, device, durableID, fstype string) string {
+	if durableID == "" || s.reresolveWipe == nil {
+		return ""
+	}
+	// The device now holds a filesystem, so the data-bearing anti-retarget re-resolve is the right one.
+	now, err := s.reresolveWipe(ctx, durableID)
+	if err != nil || now != device {
+		s.logger.Warn("format: new filesystem UUID NOT reported — bound durable id no longer resolves to the formatted device",
+			"device", device, "durable_id", durableID, "resolves_to", now, "err", err)
+		return ""
+	}
+	probe, err := s.disks.InspectDevice(ctx, device)
+	if err != nil || !probe.Probed || probe.FSType != fstype || probe.FSUUID == "" {
+		s.logger.Warn("format: new filesystem UUID NOT reported — superblock did not read back as the requested filesystem",
+			"device", device, "want_fstype", fstype, "got_fstype", probe.FSType, "has_uuid", probe.FSUUID != "", "err", err)
+		return ""
+	}
+	s.logger.Info("format: new filesystem bound to its durable id", "device", device, "durable_id", durableID, "fs_uuid", probe.FSUUID)
+	return probe.FSUUID
 }
 
 // finishFormatJob updates the persisted record to done/failed.
@@ -172,7 +208,7 @@ func (s *Server) RecoverFormatJob(ctx context.Context) {
 		return
 	}
 	s.logger.Warn("format-job recover: re-running interrupted format detached", "durable_id", job.DurableID, "device", device, "fstype", job.FSType, "blank", job.Blank)
-	_ = s.startFormatDetached(device, job.DurableID, job.FSType, job.Blank) // detached; updates the record on completion
+	_, _ = s.startFormatDetached(device, job.DurableID, job.FSType, job.Blank) // detached; updates the record on completion
 }
 
 // nowFn returns the server clock (testable), defaulting to time.Now.

internal/storage/hostops.go

@@ -57,6 +57,10 @@ type DeviceProbe struct {
 	HasPartitions     bool   `json:"has_partitions"`      // child partitions present (lsblk)
 	Mounted           bool   `json:"mounted"`             // currently mounted somewhere
 	FSType            string `json:"fstype,omitempty"`
+	// FSUUID is the filesystem UUID blkid read from the on-disk superblock (`blkid -p`, no cache),
+	// "" when there is none. R-25: the format path reports it so the caller mounts the filesystem the
+	// agent just made, not whatever a /dev path resolves to later.
+	FSUUID string `json:"fs_uuid,omitempty"`
 }
 
 // DataBearing is the conservative verdict: any signature / partition table / partition / mount —
@@ -423,6 +427,8 @@ func (h *SudoHostOps) InspectDevice(ctx context.Context, device string) (DeviceP
 			probe.FSType = v
 		case "PTTYPE":
 			probe.HasPartitionTable = true
+		case "UUID":
+			probe.FSUUID = v
 		case "USAGE":
 			if v != "" {
 				probe.HasFilesystem = true // filesystem/raid/crypto member = data-bearing

internal/storage/hostops_disk_test.go

@@ -208,3 +208,17 @@ func TestFormat_RejectsBadArgs(t *testing.T) {
 		t.Fatalf("mkfs ran despite invalid input: %v", r.calls)
 	}
 }
+
+// R-25: the probe carries the superblock's filesystem UUID so the format path can report the new one.
+func TestInspect_ReadsFilesystemUUID(t *testing.T) {
+	r := &scriptedRunner{
+		outputs: map[string][]byte{
+			"blkid": []byte("DEVNAME=/dev/sdb\nUUID=0fc63daf-8483-4772-8e79-3d69d8477de4\nTYPE=ext4\nUSAGE=filesystem\n"),
+			"lsblk": []byte(`{"blockdevices":[{"name":"sdb","fstype":"ext4","pttype":null,"mountpoint":null}]}`),
+		},
+	}
+	p, _ := newSudo(r).InspectDevice(context.Background(), "/dev/sdb")
+	if p.FSUUID != "0fc63daf-8483-4772-8e79-3d69d8477de4" {
+		t.Fatalf("FSUUID = %q, want the blkid UUID", p.FSUUID)
+	}
+}

scripts/test_gate_decoys.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""test_gate_decoys.py — can this repo's gates be fooled by a LABEL? (R-421, R-426)
+
+The same instrument as `felhom.eu/scripts/test_gate_decoys.py`: a decoy is the LABEL without the
+FACT, and a gate that passes on the label alone — or refuses the genuine article — is a live hole.
+Every gate is asserted in BOTH directions: the decoy must be convicted, the genuine article passed.
+
+Covered here (the `COVERS` literal is AST-read by `felhom.eu/scripts/decoy_coverage_gate.py`, which
+never imports this file):
+
+  published         check-published-versions.py, against a FAKE Gitea (see below).
+  release-complete  check-release-complete.py, in a scratch clone whose `origin` is a scratch bare
+                    repository, against the same fake Gitea.
+  reuse-refs, instructions, observations
+                    the three SHARED felhom.eu scripts, run against a scratch clone of THIS repo —
+                    so the decoy is planted in the agent's own REUSE.md / CLAUDE.md / REPORT.md and
+                    coverage is per input, not per script.
+
+NEVER THE REAL GITEA. Both network gates read `GITEA_BASE` from the environment (CI already sets it
+to the in-cluster URL); here it points at an `http.server` bound to 127.0.0.1 inside this process,
+and every proxy variable is removed from the child's environment so urllib cannot route around it.
+A test that asked the real registry would pass or fail on whatever was published that day — the
+constant-for-measurement shape — and would reach the network from a hook.
+
+NEVER THE REAL TREE. Every planted file lives in a scratch directory: a workspace that holds a
+clone of this repo beside symlinks to the sibling clones the shared scripts reach across to.
+
+Run from the repo root:  python3 scripts/test_gate_decoys.py
+Exit 0 every decoy judged correctly · 1 a decoy passed or a genuine article was refused.
+"""
+import http.server
+import io
+import json
+import os
+import shutil
+import socketserver
+import subprocess
+import sys
+import tempfile
+import threading
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PARENT = os.path.dirname(ROOT)
+# DECOY_SHARED_DIR exists for ONE purpose: the red-proof. It lets a mutated COPY of the shared scripts
+# be judged without editing the felhom.eu clone. Unset, the suite judges the real shared scripts.
+SHARED = os.environ.get("DECOY_SHARED_DIR") or os.path.join(PARENT, "felhom.eu", "scripts")
+
+# ── WHAT THIS FILE COVERS ────────────────────────────────────────────────────────────────────────
+# Read by felhom.eu/scripts/decoy_coverage_gate.py, which AST-parses this literal. A gate named here
+# MUST have a decoy below that has been seen to fail.
+COVERS = {
+    "published": "against a FAKE Gitea: a tag whose package 404s, a tag whose tree lacks the configs, a package one "
+                 "version past the newest tag (published, never tagged), a patch-gap orphan, a missing package that "
+                 "lexical sorting would drop out of the retention window (0.9.x vs 0.10.x); a tags api answering 500 "
+                 "or a non-JSON 200 is INCONCLUSIVE, never a pass - vs a clean registry, a non-semver tag and a version "
+                 "older than the retention window (not asserted, BY DESIGN) (R-426)",
+    "release-complete": "the newest `## vX.Y.Z` with no tag anywhere, a tag parked on an unrelated commit, a tag "
+                        "with no package; a registry 500 is INCONCLUSIVE - vs the genuine release, an `## Unreleased` "
+                        "heading above it, a newer version named only in prose or under `###`, a tag that only "
+                        "origin has (the shallow-CI shape); a LOCAL-only tag passes BY DESIGN (CI's fresh clone "
+                        "and the published gate's converse probe are what see it) (R-426)",
+    "reuse-refs": "a cited .go and a cited .md path that do not exist, planted in THIS repo's REUSE.md - vs the "
+                  "real file (R-426)",
+    "instructions": "a component version literal in THIS repo's CLAUDE.md effective text - vs the same sentence "
+                    "inside an HTML comment (R-426)",
+    "observations": "R-419 in THIS repo's REPORT.md: an Observations note SAYING it carries no marker - vs the "
+                    "two genuine markers (R-426)",
+}
+
+fails = []
+ran = 0
+
+
+def report(name, rc, out, expect_rc, must=()):
+    global ran
+    ran += 1
+    missing = [m for m in must if m not in out]
+    if rc == expect_rc and not missing:
+        print("  ok  %-62s rc=%d (expected %d)" % (name, rc, expect_rc))
+    else:
+        hole = expect_rc != 0 and rc == 0
+        fails.append("%s: rc=%d expected %d%s; missing %s\n%s" % (
+            name, rc, expect_rc, " - LIVE HOLE" if hole else "", missing, out[-900:]))
+
+
+# ── the fake Gitea ───────────────────────────────────────────────────────────────────────────────
+class Fake(object):
+    """What the fake registry serves. Reset per case."""
+
+    def reset(self):
+        self.tags = []            # tag names, as the tags api lists them
+        self.packages = set()     # versions whose generic package downloads
+        self.raw = set()          # versions whose tag tree serves the probe config
+        self.tags_status = 200
+        self.tags_body = None     # override bytes for the tags api
+        self.pkg_status = None    # override status for EVERY package request
+        self.hits = []
+
+
+FAKE = Fake()
+FAKE.reset()
+PKG_PREFIX = "/api/packages/admin/generic/felhom-agent/"
+RAW_PREFIX = "/admin/felhom-agent/raw/tag/v"
+
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def _answer(self, status, body=b""):
+        self.send_response(status)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(body)
+
+    def do_GET(self):
+        p = self.path
+        FAKE.hits.append(p)
+        if p.startswith("/api/v1/repos/admin/felhom-agent/tags"):
+            body = FAKE.tags_body if FAKE.tags_body is not None else \
+                json.dumps([{"name": t} for t in FAKE.tags]).encode()
+            return self._answer(FAKE.tags_status, body)
+        if p.startswith(PKG_PREFIX):
+            if FAKE.pkg_status is not None:
+                return self._answer(FAKE.pkg_status)
+            v = p[len(PKG_PREFIX):].split("/", 1)[0]
+            return self._answer(200, b"ELF") if v in FAKE.packages else self._answer(404)
+        if p.startswith(RAW_PREFIX):
+            v = p[len(RAW_PREFIX):].split("/", 1)[0]
+            ok = v in FAKE.raw and p.endswith("/configs/felhom-agent.service")
+            return self._answer(200, b"[Unit]\n") if ok else self._answer(404)
+        return self._answer(404)
+
+    do_HEAD = do_GET
+
+
+class Server(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    daemon_threads = True
+
+
+def child_env(base):
+    env = {k: v for k, v in os.environ.items() if "proxy" not in k.lower()}
+    env["GITEA_BASE"] = base
+    env["NO_PROXY"] = env["no_proxy"] = "127.0.0.1,localhost"
+    return env
+
+
+def run(argv, cwd, env=None):
+    # input="" — a child must never inherit (and block on) this process's stdin
+    p = subprocess.run(argv, cwd=cwd, env=env, capture_output=True, text=True, input="")
+    return p.returncode, p.stdout + p.stderr
+
+
+def sh(argv, cwd):
+    rc, out = run(argv, cwd)
+    if rc != 0:
+        raise SystemExit("setup command failed (%s): %s" % (" ".join(argv), out))
+    return out.strip()
+
+
+# ── published ────────────────────────────────────────────────────────────────────────────────────
+def published_cases(base):
+    gate = os.path.join(ROOT, "scripts", "check-published-versions.py")
+    keep = json.load(io.open(os.path.join(ROOT, "scripts", "retention-policy.json"),
+                             encoding="utf-8"))["generic_versions_kept"]
+    TAGS = ["v0.150.%d" % i for i in range(3)]          # inside any retention window >= 3
+    VERS = [t[1:] for t in TAGS]
+
+    def case(name, setup, expect_rc, must=()):
+        FAKE.reset()
+        FAKE.tags = list(TAGS)
+        FAKE.packages = set(VERS)
+        FAKE.raw = set(VERS)
+        setup()
+        rc, out = run([sys.executable, gate], ROOT, child_env(base))
+        if not FAKE.hits:
+            fails.append("published/%s: the gate never asked the fake Gitea - the seam is not wired" % name)
+        report("published: " + name, rc, out, expect_rc, must)
+
+    case("GENUINE: every tag downloadable and serving its configs", lambda: None, 0,
+         ("ALL RELEASED VERSIONS INSTALLABLE",))
+    case("GENUINE: a non-semver tag is not a release", lambda: FAKE.tags.append("v0.150.2-rc1"), 0,
+         ("ALL RELEASED VERSIONS INSTALLABLE",))
+    case("FACT: a tag whose package 404s", lambda: FAKE.packages.discard("0.150.1"), 1,
+         ("FAIL v0.150.1", "binary NOT downloadable"))
+    case("FACT: a tag whose tree does not serve the configs", lambda: FAKE.raw.discard("0.150.2"), 1,
+         ("FAIL v0.150.2", "does not serve"))
+    case("FACT: published one patch past the newest tag, never tagged",
+         lambda: FAKE.packages.add("0.150.3"), 1, ("PUBLISHED VERSION(S) WITH NO TAG", "v0.150.3"))
+    case("FACT: published in a patch GAP between two tags",
+         lambda: (FAKE.tags.remove("v0.150.1"),), 1, ("v0.150.1 is downloadable", "has no git tag"))
+
+    def lexical():
+        # keep+1 tags: 0.9.0 and 0.10.0..0.10.<keep-1>. By SEMVER the oldest is 0.9.0 (dropped); by
+        # STRING sort "0.10.0" is the smallest and would be the one dropped - so its missing package
+        # is convicted only if the window is cut by semver.
+        FAKE.tags = ["v0.9.0"] + ["v0.10.%d" % i for i in range(keep)]
+        FAKE.packages = set(t[1:] for t in FAKE.tags) - {"0.10.0"}
+        FAKE.raw = set(t[1:] for t in FAKE.tags)
+    case("FACT: a missing package lexical sorting would drop (0.10.0 vs 0.9.0)", lexical, 1,
+         ("FAIL v0.10.0",))
+
+    def retired():
+        FAKE.tags = ["v0.9.0"] + ["v0.10.%d" % i for i in range(keep)]
+        FAKE.packages = set(t[1:] for t in FAKE.tags) - {"0.9.0"}
+        FAKE.raw = set(t[1:] for t in FAKE.tags)
+    case("BY DESIGN: a version older than the retention window is not asserted", retired, 0,
+         ("NOT ASSERTED", "0.9.0"))
+
+    def five_hundred():
+        FAKE.tags_status = 500
+    case("INCONCLUSIVE: the tags api answers 500", five_hundred, 2, ("INCONCLUSIVE",))
+
+    def html():
+        FAKE.tags_body = b"<html>sign in</html>"
+    case("INCONCLUSIVE: the tags api answers a 200 that is not JSON", html, 2, ("INCONCLUSIVE",))
+
+    # an unreachable Gitea: a port nothing listens on
+    s = Server(("127.0.0.1", 0), Handler)
+    dead = "http://127.0.0.1:%d" % s.server_address[1]
+    s.server_close()
+    rc, out = run([sys.executable, gate], ROOT, child_env(dead))
+    report("published: INCONCLUSIVE: Gitea unreachable", rc, out, 2, ("INCONCLUSIVE", "URLs tried"))
+
+
+# ── release-complete ─────────────────────────────────────────────────────────────────────────────
+def release_cases(base, ws):
+    bare = os.path.join(ws, "origin.git")
+    work = os.path.join(ws, "rc-work")
+    sh(["git", "clone", "-q", "--bare", "--no-tags", "file://" + ROOT, bare], ws)
+    sh(["git", "clone", "-q", "--no-tags", "file://" + bare, work], ws)
+    sh(["git", "config", "user.email", "decoy@gate.invalid"], work)
+    sh(["git", "config", "user.name", "decoy"], work)
+    # the WORKING-TREE gate, so the file under test is the one being edited, not HEAD's
+    shutil.copy(os.path.join(ROOT, "scripts", "check-release-complete.py"),
+                os.path.join(work, "scripts", "check-release-complete.py"))
+    sh(["git", "add", "scripts/check-release-complete.py"], work)
+    sh(["git", "commit", "-q", "--allow-empty", "-m", "the gate under test"], work)
+    base_sha = sh(["git", "rev-parse", "HEAD"], work)
+    ch = os.path.join(work, "CHANGELOG.md")
+    original = io.open(ch, encoding="utf-8").read()
+    V = "9.9.9"
+
+    def case(name, top, expect_rc, must=(), tag=None, origin_tag=False, packaged=True, pkg_status=None):
+        FAKE.reset()
+        if packaged:
+            FAKE.packages = {V}
+        FAKE.pkg_status = pkg_status
+        try:
+            io.open(ch, "w", encoding="utf-8").write(top + original)
+            sh(["git", "commit", "-q", "-am", name], work)
+            if tag == "head":
+                sh(["git", "tag", "-a", "v" + V, "-m", "decoy", "HEAD"], work)
+            elif tag == "unrelated":
+                empty = sh(["git", "mktree"], work)   # stdin is "" — the empty tree, written to this repo
+                orphan = sh(["git", "commit-tree", "-m", "unrelated", empty], work)
+                sh(["git", "tag", "-a", "v" + V, "-m", "decoy", orphan], work)
+            if origin_tag:
+                sh(["git", "push", "-q", "origin", "HEAD:refs/tags/v" + V], work)
+            rc, out = run([sys.executable, os.path.join(work, "scripts", "check-release-complete.py")],
+                          work, child_env(base))
+            report("release-complete: " + name, rc, out, expect_rc, must)
+        finally:
+            run(["git", "tag", "-d", "v" + V], work)
+            run(["git", "push", "-q", "origin", ":refs/tags/v" + V], work)
+            sh(["git", "reset", "-q", "--hard", base_sha], work)
+
+    HEAD = "## v%s — 2026-10-06\n\n- decoy release\n\n" % V
+    case("GENUINE: tagged at HEAD and published", HEAD, 0,
+         ("newest CHANGELOG version: v9.9.9", "is tagged, placed and published"), tag="head")
+    case("GENUINE: an `## Unreleased` heading above the release", "## Unreleased\n\n- wip\n\n" + HEAD, 0,
+         ("newest CHANGELOG version: v9.9.9",), tag="head")
+    case("GENUINE: a newer version named only in prose and under ###",
+         "The `## v10.0.0` heading is not written yet.\n### v10.0.0 notes\n\n" + HEAD, 0,
+         ("newest CHANGELOG version: v9.9.9",), tag="head")
+    case("GENUINE: the tag only on origin (the shallow-CI shape)", HEAD, 0,
+         ("exists on origin",), origin_tag=True)
+    case("BY DESIGN: a LOCAL-only tag passes (CI's fresh clone sees only origin)", HEAD, 0,
+         ("an ancestor of HEAD",), tag="head")
+    case("FACT: the newest heading has no tag anywhere", HEAD, 1, ("DOES NOT EXIST",))
+    case("FACT: a tag parked on an unrelated commit", HEAD, 1, ("NOT an ancestor",), tag="unrelated")
+    case("FACT: tagged, never published", HEAD, 1, ("IS NOT PUBLISHED",), tag="head", packaged=False)
+    case("INCONCLUSIVE: the registry answers 500", HEAD, 2, ("INCONCLUSIVE",), tag="head", pkg_status=500)
+    case("FACT beats INCONCLUSIVE: no tag AND the registry answers 500", HEAD, 1, ("DOES NOT EXIST",),
+         pkg_status=500)
+
+
+# ── the shared felhom.eu scripts, against THIS repo's inputs ─────────────────────────────────────
+def shared_cases(ws):
+    """A scratch WORKSPACE: a clone of this repo beside symlinks to the siblings, because the shared
+    scripts reach across (REUSE.md cites hub paths; instructions_gate reads the workspace CLAUDE.md)."""
+    for g in ("reuse_refs_check.py", "instructions_gate.py", "observations_gate.py"):
+        if not os.path.isfile(os.path.join(SHARED, g)):
+            fails.append("shared gate %s is MISSING beside this clone (tried %s) - a failure, never a skip"
+                         % (g, SHARED))
+            return
+    space = os.path.join(ws, "workspace")
+    os.makedirs(space)
+    for entry in sorted(os.listdir(PARENT)):
+        if entry in ("felhom.eu", "felhom-controller", "app-catalog-felhom.eu", "homelab-manifests",
+                     "CLAUDE.md", ".claude-memory"):
+            os.symlink(os.path.join(PARENT, entry), os.path.join(space, entry))
+    repo = os.path.join(space, "felhom-agent")
+    sh(["git", "clone", "-q", "--no-tags", "file://" + ROOT, repo], ws)
+    # the WORKING-TREE inputs the plants go into, so a case judges today's file
+    for f in ("REUSE.md", "CLAUDE.md", "REPORT.md"):
+        shutil.copy(os.path.join(ROOT, f), os.path.join(repo, f))
+
+    def case(name, gate, relpath, extra, expect_rc, must=()):
+        p = os.path.join(repo, relpath)
+        backup = io.open(p, encoding="utf-8").read()
+        try:
+            if extra:
+                io.open(p, "w", encoding="utf-8").write(backup + extra)
+            rc, out = run([sys.executable, os.path.join(SHARED, gate), repo], repo)
+            report(name, rc, out, expect_rc, must)
+        finally:
+            io.open(p, "w", encoding="utf-8").write(backup)
+
+    case("reuse-refs: GENUINE: this repo's REUSE.md", "reuse_refs_check.py", "REUSE.md", "", 0, ("FAILED 0",))
+    case("reuse-refs: FACT: a cited .go path that does not exist", "reuse_refs_check.py", "REUSE.md",
+         u"\n- see `internal/localapi/does_not_exist.go`\n", 1, ("does_not_exist.go",))
+    case("reuse-refs: FACT: a cited .md path that does not exist", "reuse_refs_check.py", "REUSE.md",
+         u"\n- see `docs/99-does-not-exist.md`\n", 1, ("99-does-not-exist.md",))
+    case("instructions: GENUINE: this repo's CLAUDE.md", "instructions_gate.py", "CLAUDE.md", "", 0,
+         ("instructions_gate: OK",))
+    case("instructions: FACT: a version literal in effective text", "instructions_gate.py", "CLAUDE.md",
+         u"\nThe agent runs v0.148.0 today.\n", 1, ("v0.148.0",))
+    case("instructions: GENUINE: the same sentence in an HTML comment", "instructions_gate.py", "CLAUDE.md",
+         u"\n<!--\nThe agent ran v0.148.0 on 2026-10-06.\n-->\n", 0, ("instructions_gate: OK",))
+    case("observations: FACT: R-419, prose SAYING it has no marker", "observations_gate.py", "REPORT.md",
+         u"\n## Observations\n\n1. **A real finding.** It carries no `FILED:` marker and no "
+         u"`NOT-A-FINDING:` marker, deliberately.\n", 1)
+    case("observations: GENUINE: a FILED marker", "observations_gate.py", "REPORT.md",
+         u"\n## Observations\n\n1. **A real finding.** Something broke. **FILED: R-419**\n", 0)
+    case("observations: GENUINE: a NOT-A-FINDING marker", "observations_gate.py", "REPORT.md",
+         u"\n## Observations\n\n1. **A real finding.** Odd. **NOT-A-FINDING: my own typo, corrected in "
+         u"the same minute.**\n", 0)
+
+
+def main():
+    srv = Server(("127.0.0.1", 0), Handler)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    base = "http://127.0.0.1:%d" % srv.server_address[1]
+    ws = tempfile.mkdtemp(prefix="agent-decoys-")
+    print("agent gate decoys — fake Gitea at %s, scratch %s" % (base, ws))
+    try:
+        published_cases(base)
+        release_cases(base, ws)
+        shared_cases(ws)
+    finally:
+        srv.shutdown()
+        srv.server_close()
+        shutil.rmtree(ws, ignore_errors=True)
+    if fails:
+        print()
+        for f in fails:
+            print("FAIL: %s" % f)
+        return 1
+    print("\nagent gate decoys OK — %d case(s), every label judged on its fact (R-421)" % ran)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())