@synopackageland/cli 0.4.0 → 0.4.1

package/dist/templates/native-go/backend/internal/helper/s1r_actor_races_linux_test.go

@@ -0,0 +1,231 @@
+package helper
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+)
+
+func s1rActorRaces(t *testing.T, spec s1rActorSpec, kind string) {
+	root := spec.Root + "/race"
+	pin, code := pinReadOnlyRoot(root)
+	if code != "" {
+		t.Fatal(code)
+	}
+	defer pin.Close()
+	ctx := context.Background()
+	switch kind {
+	case "symlink":
+		for _, link := range []struct{ name, target string }{{"inside-link", "file"}, {"outside-link", "../bob/file"}, {"dir-link", "../bob"}} {
+			s1rMust(t, os.Symlink(link.target, root+"/"+link.name))
+		}
+		for _, action := range []Action{ActionStat, ActionRead, ActionList, ActionReadStream} {
+			segments := []string{"outside-link"}
+			if action == ActionList {
+				segments = []string{"dir-link"}
+			}
+			work := readWork(pin, segments...)
+			work.Action = action
+			if action == ActionList {
+				work.MaxBytes = 0
+				work.Limit = 20
+			}
+			if action == ActionStat {
+				work.MaxBytes = 0
+			}
+			if action == ActionReadStream {
+				x, r := openActorReadTransfer(ctx, pin, work, fixtureReadOnlyACL{})
+				if x != nil {
+					x.Close()
+				}
+				if r.Code != ErrDenied || r.Bytes != 0 {
+					t.Fatal("symlink stream", r)
+				}
+			} else {
+				r, b := executeReadOnly(ctx, pin, work, fixtureReadOnlyACL{})
+				if r.Code != ErrDenied || len(b) > 0 || r.Entry != nil || r.List != nil {
+					t.Fatal("symlink metadata/read", action, r)
+				}
+			}
+		}
+		r, b := executeReadOnly(ctx, pin, readWork(pin, "inside-link"), fixtureReadOnlyACL{})
+		if r.Code != ErrDenied || len(b) > 0 {
+			t.Fatal("internal symlink followed", r)
+		}
+		r, _ = executeReadOnly(ctx, pin, readOnlyWork{RootPath: root, Action: ActionList, Segments: []string{}, Limit: 20}, fixtureReadOnlyACL{})
+		if r.Code != "" || r.List == nil || len(r.List.Entries) != 1 || r.List.Entries[0].Name != "file" {
+			t.Fatal("symlink names leaked by list", r)
+		}
+		for _, segments := range [][]string{{"outside-link"}, {"dir-link", "new"}} {
+			x, c := openActorWriteTransfer(ctx, pin, writeWork{RootPath: root, Action: ActionCreate, Segments: segments, MaxBytes: 3}, fixtureReadOnlyACL{})
+			if x != nil {
+				x.Close()
+			}
+			if c != ErrDenied {
+				t.Fatal("symlink create", c)
+			}
+		}
+		t.Log("stat/list/read/stream/create reject symlinks; list filters symlink names")
+	case "stat-rename", "list-rename", "read-rename":
+		s1rMust(t, os.Mkdir(root+"/sub", 0700))
+		s1rMust(t, os.WriteFile(root+"/sub/file", []byte("original"), 0600))
+		mutated := false
+		acl := fixtureReadOnlyACL{hook: func() {
+			if mutated {
+				return
+			}
+			mutated = true
+			s1rMust(t, os.Rename(root+"/sub", root+"/moved"))
+			s1rMust(t, os.Mkdir(root+"/sub", 0700))
+			s1rMust(t, os.WriteFile(root+"/sub/file", []byte("foreign"), 0600))
+		}}
+		work := readWork(pin, "sub", "file")
+		if kind == "stat-rename" {
+			work.Action = ActionStat
+			work.MaxBytes = 0
+		}
+		if kind == "list-rename" {
+			work.Action = ActionList
+			work.MaxBytes = 0
+			work.Segments = []string{"sub"}
+			work.Limit = 20
+		}
+		r, b := executeReadOnly(ctx, pin, work, acl)
+		if r.Code != ErrStale || len(b) != 0 || r.Entry != nil || r.List != nil {
+			t.Fatal("renamed ancestry released bytes", r, string(b))
+		}
+		t.Log(kind + ": replacement after resolver open refuses bytes and metadata with stale")
+	case "stream-rename":
+		work := readWork(pin, "file")
+		work.Action = ActionReadStream
+		x, r := openActorReadTransfer(ctx, pin, work, fixtureReadOnlyACL{})
+		if r.Code != "" {
+			t.Fatal(r)
+		}
+		defer x.Close()
+		b, c := x.ReadChunk(ctx, 3)
+		if c != "" || string(b) != "can" {
+			t.Fatal(c, string(b))
+		}
+		s1rMust(t, os.Rename(root+"/file", root+"/old"))
+		s1rMust(t, os.Symlink("../bob/file", root+"/file"))
+		b, c = x.ReadChunk(ctx, 3)
+		if c != ErrDenied || len(b) != 0 {
+			t.Fatal("stream followed replacement", c, string(b))
+		}
+		t.Log("first fixed-FD stream chunk succeeds; symlink replacement refuses next chunk")
+	case "create-rename", "publish-rename", "publish-symlink":
+		s1rMust(t, os.Mkdir(root+"/sub", 0700))
+		staged := kind != "create-rename"
+		work := writeWork{RootPath: root, Action: ActionCreate, Segments: []string{"sub", "result"}, MaxBytes: 6}
+		if staged {
+			work.Action = ActionWriteStream
+			work.Staged = true
+		}
+		x, c := openActorWriteTransfer(ctx, pin, work, fixtureReadOnlyACL{})
+		if c != "" {
+			t.Fatal(c)
+		}
+		defer x.Close()
+		receipt, c := x.WriteChunk(ctx, []byte("abc"))
+		if c != "" || receipt.BytesWritten != 3 {
+			t.Fatal(receipt, c)
+		}
+		if kind == "publish-symlink" {
+			s1rMust(t, os.Symlink("../file", root+"/sub/result"))
+			receipt, c = x.Commit(ctx)
+			if c != ErrDenied || receipt.Published || receipt.Committed {
+				t.Fatal("publish replaced symlink", receipt, c)
+			}
+			target, e := os.Readlink(root + "/sub/result")
+			s1rMust(t, e)
+			if target != "../file" {
+				t.Fatal(target)
+			}
+		} else {
+			s1rMust(t, os.Rename(root+"/sub", root+"/moved"))
+			s1rMust(t, os.Mkdir(root+"/sub", 0700))
+			s1rMust(t, os.WriteFile(root+"/sub/result", []byte("foreign"), 0600))
+			if staged {
+				receipt, c = x.Commit(ctx)
+				if c != ErrStale || receipt.Published {
+					t.Fatal("publish after rename", receipt, c)
+				}
+			} else {
+				receipt, c = x.WriteChunk(ctx, []byte("def"))
+				if c != ErrPartial || receipt.BytesWritten != 3 {
+					t.Fatal("write after rename", receipt, c)
+				}
+			}
+			b, e := os.ReadFile(root + "/sub/result")
+			s1rMust(t, e)
+			if string(b) != "foreign" {
+				t.Fatal("foreign destination overwritten", string(b))
+			}
+			if staged {
+				if _, e := os.Stat(root + "/moved/result"); !os.IsNotExist(e) {
+					t.Fatal("anonymous stage became visible", e)
+				}
+			} else {
+				b, e = os.ReadFile(root + "/moved/result")
+				s1rMust(t, e)
+				if string(b) != "abc" {
+					t.Fatal("partial bytes changed", string(b))
+				}
+			}
+		}
+		t.Logf("%s: refusal=%s receipt=%+v; foreign destination preserved", kind, c, receipt)
+	case "publish-permission-loss":
+		work := writeWork{RootPath: root, Action: ActionWriteStream, Segments: []string{"result"}, MaxBytes: 3, Staged: true}
+		x, c := openActorWriteTransfer(ctx, pin, work, fixtureReadOnlyACL{})
+		if c != "" {
+			t.Fatal(c)
+		}
+		defer x.Close()
+		_, c = x.WriteChunk(ctx, []byte("abc"))
+		if c != "" {
+			t.Fatal(c)
+		}
+		s1rMust(t, os.Chmod(root, 0500))
+		defer os.Chmod(root, 0700)
+		r, c := x.Commit(ctx)
+		// Current S7 maps linkat EACCES to unsupported; require the exact behavior,
+		// report it, and preserve the fail-closed publish gate.
+		if c != ErrUnsupported || r.Published || r.Committed || r.BytesWritten != 3 {
+			t.Fatal("publish after parent chmod", r, c)
+		}
+		if _, e := os.Stat(root + "/result"); !os.IsNotExist(e) {
+			t.Fatal("publish wrote forbidden directory", e)
+		}
+		t.Log("parent write permission removed: kernel denies linkat; receipt retains staged bytes, published=false")
+	case "open-fd-write-permission-loss":
+		work := writeWork{RootPath: root, Action: ActionCreate, Segments: []string{"result"}, MaxBytes: 6}
+		x, c := openActorWriteTransfer(ctx, pin, work, fixtureReadOnlyACL{})
+		if c != "" {
+			t.Fatal(c)
+		}
+		defer x.Close()
+		r, c := x.WriteChunk(ctx, []byte("abc"))
+		if c != "" {
+			t.Fatal(c)
+		}
+		s1rMust(t, x.file.Chmod(0000))
+		defer x.file.Chmod(0600)
+		r, c = x.WriteChunk(ctx, []byte("def"))
+		if c != "" || r.BytesWritten != 6 {
+			t.Fatal("Linux open-FD semantics", r, c)
+		}
+		r, c = x.Commit(ctx)
+		if c != "" || !r.Committed {
+			t.Fatal(r, c)
+		}
+		b, e := os.ReadFile(root + "/result")
+		if !os.IsPermission(e) || len(b) != 0 {
+			t.Fatal("new open bypassed chmod", e, string(b))
+		}
+		t.Log("chmod 000 denies a new open; previously opened writer FD still writes/commits under Linux semantics")
+	default:
+		t.Fatal("unknown race", strings.TrimSpace(kind))
+	}
+}

package/dist/templates/native-go/backend/internal/helper/s1r_fixture_contract_linux_test.go

@@ -0,0 +1,18 @@
+package helper
+
+import (
+	"os"
+	"testing"
+)
+
+func TestS1RFixtureContract(t *testing.T) {
+	if os.Geteuid() != 0 {
+		t.Skip("disposable root VM only")
+	}
+	root := s1rFixture(t)
+	for _, name := range []string{"alice", "bob", "supplementary", "acl-allow", "acl-mask", "acl-file-mask", "inherit", "readonly", "race"} {
+		if _, err := os.Stat(root + "/" + name + "/file"); err != nil {
+			t.Fatal(name, err)
+		}
+	}
+}

package/dist/templates/native-go/backend/internal/helper/server_linux.go

@@ -1,6 +1,8 @@
 package helper
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"encoding/json"
 	"io"
 	"net"
@@ -13,7 +15,7 @@ import (
 
 func serveLinux(c Client) error {
 	r, err := readRecord(c.StateDir, 0)
-	if err != nil || !r.Enabled || r.Inventory != c.Expected {
+	if err != nil || !r.Enabled || r.Inventory != c.Expected || r.Lifecycle == nil || r.Lifecycle.Phase != "running" {
 		return errTrust
 	}
 	// Only the supervisor writes process.json.
@@ -76,8 +78,47 @@ func serveLinux(c Client) error {
 				return
 			}
 			r, err := readRecord(c.StateDir, 0)
-			disabled := err != nil || !r.Enabled || r.Inventory != c.Expected
-			json.NewEncoder(conn).Encode(Respond(c.Expected, disabled, req))
+			readiness := "fenced"
+			if err == nil && r.Enabled && r.Inventory == c.Expected && r.Lifecycle != nil && r.Lifecycle.Phase == "running" {
+				readiness = parentReadiness(c)
+			}
+			res := Respond(c.Expected, readiness != "ready", req)
+			if readiness != "ready" {
+				res.Error = readiness
+			}
+			json.NewEncoder(conn).Encode(res)
 		}()
 	}
 }
+
+// No lifecycle mutations: only the exact owned child can request admission.
+func parentReadiness(c Client) string {
+	p, err := readProcess(c.RunDir, 0)
+	if err != nil || p.PID != os.Getppid() {
+		return "fenced"
+	}
+	actual, err := inspectSupervisor(p.PID, c.Expected)
+	if err != nil || actual != p {
+		return "fenced"
+	}
+	conn, err := net.DialTimeout("unix", filepath.Join(c.RunDir, "supervisor.sock"), 100*time.Millisecond)
+	if err != nil {
+		return "fenced"
+	}
+	defer conn.Close()
+	peer, err := peerCredentials(conn.(*net.UnixConn))
+	if err != nil || peer.Uid != 0 || int(peer.Pid) != p.PID {
+		return "fenced"
+	}
+	conn.SetDeadline(time.Now().Add(200 * time.Millisecond))
+	var nonce [32]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return "fenced"
+	}
+	req := supervisorRequest{Process: p, Op: "admit", Nonce: hex.EncodeToString(nonce[:])}
+	if json.NewEncoder(conn).Encode(req) != nil {
+		return "fenced"
+	}
+	res, err := decodeSupervisorReply(conn, c.Expected, req.Nonce)
+	return supervisorReadiness(res, err)
+}

package/dist/templates/native-go/backend/internal/helper/status.go

@@ -25,6 +25,7 @@ type Inventory struct {
 	Protocol       int    `json:"protocol"`
 	PayloadDigest  string `json:"payloadDigest"`
 	RegistryDigest string `json:"registryDigest"`
+	DataAccess     string `json:"dataAccess,omitempty"`
 }
 
 var digestPattern = regexp.MustCompile(`^[a-f0-9]{64}$`)
@@ -32,13 +33,16 @@ var packagePattern = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]{1,63}$`)
 var versionPattern = regexp.MustCompile(`^\d+(\.\d+){0,3}-\d{4}$`)
 
 func (i Inventory) Valid() bool {
-	return packagePattern.MatchString(i.Package) && versionPattern.MatchString(i.Version) && i.Protocol > 0 && digestPattern.MatchString(i.PayloadDigest) && digestPattern.MatchString(i.RegistryDigest)
+	mode := i.DataAccess == "" || i.Protocol == DataProtocol && (i.DataAccess == "unavailable" || i.DataAccess == "relaxed")
+	return mode && packagePattern.MatchString(i.Package) && versionPattern.MatchString(i.Version) && (i.Protocol == 1 || i.Protocol == DataProtocol) && digestPattern.MatchString(i.PayloadDigest) && digestPattern.MatchString(i.RegistryDigest)
 }
 
 type Record struct {
-	Inventory Inventory `json:"inventory"`
-	Enabled   bool      `json:"enabled"`
-	Residual  bool      `json:"residual,omitempty"`
+	Schema    int        `json:"schema,omitempty"`
+	Lifecycle *Lifecycle `json:"lifecycle,omitempty"`
+	Inventory Inventory  `json:"inventory"`
+	Enabled   bool       `json:"enabled"`
+	Residual  bool       `json:"residual,omitempty"`
 }
 type Request struct {
 	Inventory Inventory `json:"inventory"`
@@ -161,14 +165,16 @@ func readRecord(dir string, owner uint32) (Record, error) {
 	d := json.NewDecoder(io.LimitReader(f, 4097))
 	d.DisallowUnknownFields()
 	var decoded struct {
-		Inventory Inventory `json:"inventory"`
-		Enabled   *bool     `json:"enabled"`
-		Residual  bool      `json:"residual,omitempty"`
+		Schema    int        `json:"schema,omitempty"`
+		Lifecycle *Lifecycle `json:"lifecycle,omitempty"`
+		Inventory Inventory  `json:"inventory"`
+		Enabled   *bool      `json:"enabled"`
+		Residual  bool       `json:"residual,omitempty"`
 	}
-	if d.Decode(&decoded) != nil || d.Decode(new(any)) != io.EOF || !decoded.Inventory.Valid() || decoded.Enabled == nil {
+	if d.Decode(&decoded) != nil || d.Decode(new(any)) != io.EOF || !decoded.Inventory.Valid() || decoded.Enabled == nil || !decoded.Lifecycle.valid() || (decoded.Schema != 0 && decoded.Schema != 2) {
 		return r, errTrust
 	}
-	r = Record{Inventory: decoded.Inventory, Enabled: *decoded.Enabled, Residual: decoded.Residual}
+	r = Record{Schema: decoded.Schema, Inventory: decoded.Inventory, Enabled: *decoded.Enabled, Residual: decoded.Residual, Lifecycle: decoded.Lifecycle}
 	return r, nil
 }
 
@@ -201,6 +207,36 @@ func (c Client) Status(ctx context.Context) State {
 		s.Cleanup = "required"
 		return s
 	}
+	if err == nil && r.Lifecycle != nil && r.Lifecycle.Phase != "running" {
+		if e := protected(c.RunDir, c.Owner, true); e != nil && !errors.Is(e, fs.ErrNotExist) {
+			return result("incompatible", "untrusted-runtime")
+		}
+		if r.Lifecycle.Completion != "" {
+			path := filepath.Join(c.StateDir, "completion-"+r.Lifecycle.Epoch+".json")
+			st, e := os.Lstat(path)
+			ok := e == nil && st.Mode().IsRegular() && st.Mode().Perm() == 0600
+			if ok {
+				s, valid := st.Sys().(*syscall.Stat_t)
+				ok = valid && s.Uid == c.Owner
+			}
+			if ok && uint32(os.Geteuid()) == c.Owner {
+				_, e = completionRecord(c, r)
+				ok = e == nil
+			}
+			if !ok {
+				s := result("failed", "invalid-completion")
+				s.Cleanup = "required"
+				return s
+			}
+		}
+
+		if !runtimeAbsent(c) {
+			s := result("failed", "incomplete-transition")
+			s.Cleanup = "required"
+			return s
+		}
+		return result("stopped", "admin-recover-required")
+	}
 	// Conflict has precedence over missing approval. Even an unapproved leftover
 	// socket is probed before claiming that authorization alone can fix it.
 	if e := protected(c.RunDir, c.Owner, true); e != nil && !errors.Is(e, fs.ErrNotExist) {
@@ -215,7 +251,24 @@ func (c Client) Status(ctx context.Context) State {
 		}
 		state, reason := c.probe(ctx, socket)
 		if state != "ready" {
-			return result(state, reason)
+			s := result(state, reason)
+			if state == "pending" {
+				if err == nil && r.Lifecycle != nil && r.Lifecycle.Phase == "running" {
+					s.PackageRunning = "running"
+					return s
+				}
+				s.State, s.Reason = "failed", "health-refused"
+			}
+			if r.Lifecycle != nil {
+				if _, err := readProcess(c.RunDir, c.Owner); err == nil {
+					s.State = "failed"
+					s.Cleanup = "required"
+				}
+			}
+			if reason == "lifecycle-fenced" {
+				s.Cleanup = "required"
+			}
+			return s
 		}
 	} else if !errors.Is(e, fs.ErrNotExist) {
 		return result("failed", "runtime-unreadable")
@@ -226,7 +279,11 @@ func (c Client) Status(ctx context.Context) State {
 	if e != nil {
 		return result("stopped", "runtime-missing")
 	}
-	return result("ready", "live-handshake")
+	s := result("ready", "live-handshake")
+	if r.Lifecycle != nil {
+		s.PackageRunning = "running"
+	}
+	return s
 }
 
 func (c Client) probe(ctx context.Context, socket string) (string, string) {
@@ -264,6 +321,12 @@ func (c Client) probe(ctx context.Context, socket string) (string, string) {
 	if res.Nonce != req.Nonce || res.Inventory != c.Expected || res.Error == "incompatible" {
 		return "incompatible", "handshake-mismatch"
 	}
+	if !res.OK && res.Error == "reload-revalidating" {
+		return "pending", "reload-revalidating"
+	}
+	if !res.OK && res.Error == "fenced" {
+		return "failed", "lifecycle-fenced"
+	}
 	if !res.OK || res.Error != "" {
 		return "failed", "health-refused"
 	}

package/dist/templates/native-go/backend/internal/helper/status_test.go

@@ -203,3 +203,86 @@ func TestProcessRecordIsNotReadableByOrdinaryOSUsers(t *testing.T) {
 		t.Fatalf("process record permissions: %v %v", s, err)
 	}
 }
+
+func TestS8InventoryHealthRejectsUnknownProtocol(t *testing.T) {
+	c := fixture(t)
+	for _, protocol := range []int{1, 2} {
+		i := c.Expected
+		i.Protocol = protocol
+		if !i.Valid() || !Respond(i, false, Request{Inventory: i, Op: "health", Nonce: strings.Repeat("c", 64)}).OK {
+			t.Fatal("supported protocol", protocol)
+		}
+	}
+	for _, protocol := range []int{0, 3, 99} {
+		i := c.Expected
+		i.Protocol = protocol
+		res := Respond(i, false, Request{Inventory: i, Op: "health", Nonce: strings.Repeat("c", 64)})
+		if i.Valid() || res.OK || res.Error != "incompatible" {
+			t.Fatal("unknown protocol accepted", protocol, res)
+		}
+	}
+}
+
+func TestPendingHealthRequiresTrustedRunningApproval(t *testing.T) {
+	for _, kind := range []string{"running", "missing", "legacy", "disabled", "residual", "fenced", "nonce", "inventory", "contradictory"} {
+		t.Run(kind, func(t *testing.T) {
+			c := fixture(t)
+			r := Record{Inventory: c.Expected, Enabled: true, Lifecycle: testLifecycle("running")}
+			switch kind {
+			case "legacy":
+				r.Lifecycle = nil
+			case "disabled":
+				r.Enabled = false
+			case "residual":
+				r.Residual = true
+			case "fenced":
+				r.Lifecycle.Phase = "fenced"
+			}
+			if kind != "missing" {
+				record(t, c, r)
+			}
+			live(t, c, c.Expected, func(req Request) Response {
+				res := Response{Inventory: c.Expected, Nonce: req.Nonce, Error: "reload-revalidating"}
+				switch kind {
+				case "nonce":
+					res.Nonce = "replay"
+				case "inventory":
+					res.Inventory.Protocol++
+				case "contradictory":
+					res.OK = true
+				}
+				return res
+			})
+			got := c.Status(context.Background())
+			if kind == "running" {
+				if got.State != "pending" || got.Reason != "reload-revalidating" || got.Cleanup != "" || got.PackageRunning != "running" {
+					t.Fatalf("%+v", got)
+				}
+				if c.CheckStopped(context.Background()) == nil {
+					t.Fatal("pending accepted as stopped")
+				}
+			} else if got.State == "pending" || got.State == "ready" {
+				t.Fatalf("untrusted pending: %+v", got)
+			}
+		})
+	}
+}
+
+func TestS1RInventoryModeIsProtocolTwoOnly(t *testing.T) {
+	i := Inventory{Package: "Fixture", Version: "1.0.0-0001", Protocol: 2, PayloadDigest: strings.Repeat("a", 64), RegistryDigest: strings.Repeat("b", 64)}
+	for _, mode := range []string{"", "unavailable", "relaxed"} {
+		i.DataAccess = mode
+		if !i.Valid() {
+			t.Fatal("known mode refused", mode)
+		}
+	}
+	i.DataAccess = "active"
+	if i.Valid() {
+		t.Fatal("unknown mode accepted")
+	}
+	i.DataAccess = "relaxed"
+	i.Protocol = 1
+	if i.Valid() {
+		t.Fatal("protocol 1 accepted relaxed")
+	}
+}

package/dist/templates/native-go/backend/internal/helper/supervision.go

@@ -70,15 +70,38 @@ func stopChild(ctx context.Context, child supervisedChild, grace time.Duration)
 // Read to actual connection EOF. A LimitReader's synthetic EOF at the size
 // cap can never certify supervisor exit, so reaching that cap is a refusal.
 func readSupervisorReply(reader io.Reader, want Inventory, nonce string) error {
-	b, err := io.ReadAll(io.LimitReader(reader, 4097))
-	if err != nil || len(b) > 4096 {
+	res, err := decodeSupervisorReply(reader, want, nonce)
+	if err != nil || !res.OK || res.Error != "" {
 		return errTrust
 	}
+	return nil
+}
+
+// Parsing authenticates the entire bounded reply; readiness and stop ACKs
+// retain separate acceptance rules. No refusal can certify supervisor exit.
+func decodeSupervisorReply(reader io.Reader, want Inventory, nonce string) (Response, error) {
 	var res Response
+	b, err := io.ReadAll(io.LimitReader(reader, 4097))
+	if err != nil || len(b) > 4096 {
+		return res, errTrust
+	}
 	d := json.NewDecoder(bytes.NewReader(b))
 	d.DisallowUnknownFields()
-	if d.Decode(&res) != nil || d.Decode(new(any)) != io.EOF || !res.OK || res.Error != "" || res.Inventory != want || res.Nonce != nonce {
-		return errTrust
+	if d.Decode(&res) != nil || d.Decode(new(any)) != io.EOF || res.Inventory != want || res.Nonce != nonce {
+		return Response{}, errTrust
 	}
-	return nil
+	return res, nil
+}
+
+// A pending health refusal cannot be used as a successful admission or stop ACK.
+func supervisorReadiness(res Response, err error) string {
+	if err == nil {
+		if res.OK && res.Error == "" {
+			return "ready"
+		}
+		if !res.OK && res.Error == "reload-revalidating" {
+			return res.Error
+		}
+	}
+	return "fenced"
 }

package/dist/templates/native-go/backend/internal/helper/supervisor_frame.go

@@ -0,0 +1,76 @@
+package helper
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"io"
+	"net"
+	"time"
+)
+
+type supervisorRequest struct {
+	Process Process         `json:"process"`
+	Op      string          `json:"op"`
+	Nonce   string          `json:"nonce"`
+	Data    json.RawMessage `json:"data,omitempty"`
+}
+
+// Legacy M1 requests do not half-close; grant controls MUST half-close. Count
+// the entire v2 frame (including whitespace), reject duplicates and trailing
+// frames, and bound both time and memory. The outer process binds this socket.
+func decodeSupervisorRequest(reader io.Reader) (supervisorRequest, Code) {
+	var req supervisorRequest
+	limited := &io.LimitedReader{R: reader, N: MaxControlBytes + 1}
+	d := json.NewDecoder(limited)
+	var raw json.RawMessage
+	if d.Decode(&raw) != nil {
+		return req, ErrInvalid
+	}
+	if code := decodeDataObject(bytes.NewReader(raw), &req, MaxControlBytes); code != "" {
+		return req, code
+	}
+	if req.Op == "grants" {
+		rest, err := io.ReadAll(io.MultiReader(d.Buffered(), limited))
+		if err != nil {
+			return req, ErrInvalid
+		}
+		if limited.N <= 0 {
+			return req, ErrLimit
+		}
+		if len(bytes.TrimSpace(rest)) != 0 {
+			return req, ErrInvalid
+		}
+	} else if d.InputOffset() > 4096 || len(req.Data) > 0 {
+		return req, ErrInvalid
+	}
+	if !allReferences(req.Nonce) || (req.Op != "admit" && req.Op != "stop" && req.Op != "grants") {
+		return req, ErrInvalid
+	}
+	return req, ""
+}
+
+const supervisorAttestationWait = time.Second
+const supervisorFrameBudget = 100 * time.Millisecond
+
+// The caller sends no frame bytes until its full post-connect hash succeeds.
+// Separate the bounded wait for that computation from the fixed frame budget.
+func receiveSupervisorRequest(conn net.Conn) (supervisorRequest, Code) {
+	firstDeadline := time.Now().Add(supervisorAttestationWait)
+	if err := conn.SetReadDeadline(firstDeadline); err != nil {
+		return supervisorRequest{}, ErrInvalid
+	}
+	reader := bufio.NewReader(conn)
+	if _, err := reader.Peek(1); err != nil || !time.Now().Before(firstDeadline) {
+		return supervisorRequest{}, ErrInvalid
+	}
+	frameDeadline := time.Now().Add(supervisorFrameBudget)
+	if err := conn.SetDeadline(frameDeadline); err != nil {
+		return supervisorRequest{}, ErrInvalid
+	}
+	req, code := decodeSupervisorRequest(reader)
+	if !time.Now().Before(frameDeadline) {
+		return supervisorRequest{}, ErrInvalid
+	}
+	return req, code
+}