§H.12 step 3: session_set_pinned/session_is_pinned pin-authority choke point

session_is_pinned() reads Session.pinned directly (authoritative, no
Stadium re-derivation); session_set_pinned() writes both Session.pinned
and the mirrored STADIUM_FLAG_PIN bit on the session's own patron cell,
keeping Stadium's internal eviction/admission logic (which must stay
self-contained) in sync without it calling back into session.c.

Added Session.stadium_cell (index into stadium_cells()) -- necessary
plumbing not in the original H.2 field list; the choke point can't reach
the right patron header without it. Moved STADIUM_FLAG_PIN from a
stadium.c-private #define to stadium.h (public) so session.c can
reference it without a duplicate definition.

Verified 3-arch boot to ok> (amd64/aarch64/riscv64).

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

include/starkernel/session.h

@@ -59,6 +59,7 @@
 #ifdef __STARKERNEL__
 
 #include <stdint.h>
+#include <stddef.h>
 
 #include "starkernel/vm_uuid.h"
 #include "starkernel/vm_identity.h"
@@ -67,6 +68,13 @@
  * magnitude for the same kind of data (a short human-readable VM name). */
 #define SESSION_NAME_BUF 64
 
+/* Sentinel meaning "no Stadium cell recorded yet" -- same shape as
+ * STADIUM_CELL_NONE (stadium.c), duplicated here rather than pulled in via
+ * stadium.h to avoid this header depending on Stadium's internal cell-index
+ * type. Session's own callers set stadium_cell after their own
+ * stadium_admit() call returns a real index (§H.12 step 3 doc). */
+#define SESSION_STADIUM_CELL_NONE ((size_t)-1)
+
 typedef struct {
     VMUuid     vm_id;                    /* the patron this session references */
     int        pinned;                   /* authoritative over STADIUM_FLAG_PIN; see
@@ -74,6 +82,15 @@ typedef struct {
     VMUuid     parent;                   /* who birthed this session */
     char       name[SESSION_NAME_BUF];   /* canonical human-readable name */
     VMIdentity identity;                 /* embedded, not referenced -- see vm_identity.h */
+    size_t     stadium_cell;             /* index of this session's own patron cell in
+                                           * stadium_cells() -- SESSION_STADIUM_CELL_NONE
+                                           * until the caller that admits this session's
+                                           * patron (stadium_admit()'s return value) sets it.
+                                           * session_set_pinned()/session_is_pinned() need
+                                           * this to reach the right patron header; added
+                                           * §H.12 step 3, not part of the original H.2 field
+                                           * list -- necessary plumbing, not a new session-
+                                           * level concept, so not itself renegotiated. */
 } Session;
 
 /*
@@ -124,6 +141,29 @@ Session *session_find(VMUuid vm_id);
  */
 Session *session_register(VMUuid vm_id, VMUuid parent, const char *name);
 
+/*
+ * session_set_pinned / session_is_pinned - The pin-authority choke point
+ * (FABRIC-3.md §H.2/§H.10, decided 2026-09-02: "full choke point at the
+ * session level, both directions"). Session is authoritative for every
+ * EXTERNAL reader -- nothing else, including existing Stadium code, reads
+ * or writes STADIUM_FLAG_PIN on a patron header directly anymore.
+ *
+ * session_is_pinned() answers from the session's own `pinned` field
+ * directly (the authoritative copy) -- it does not re-derive the answer
+ * from Stadium. session_set_pinned() writes both: the session's own
+ * `pinned` field (authoritative) AND the mirrored STADIUM_FLAG_PIN bit on
+ * the session's own patron header (stadium_cells()[session->stadium_cell]),
+ * so the Stadium engine's own internal eviction/admission logic -- which
+ * must stay self-contained and cannot call back into session.c -- keeps
+ * seeing a correct, in-sync bit.
+ *
+ * Both no-op (return 0 / do nothing) if vm_id has no registered session, or
+ * if stadium_cell is still SESSION_STADIUM_CELL_NONE (patron not admitted
+ * yet) for the set path.
+ */
+void session_set_pinned(VMUuid vm_id, int pinned);
+int  session_is_pinned(VMUuid vm_id);
+
 #endif /* __STARKERNEL__ */
 
 #endif /* STARKERNEL_SESSION_H */

include/starkernel/vm/stadium.h

@@ -46,6 +46,16 @@
  * conflating "contains Hera" with "contains nothing." */
 #define STADIUM_CONTAINS_NONE ((uint32_t)-1)
 
+/* `flags` bit 0 -- pinned, exempt from eviction/reap. Moved here from a
+ * stadium.c-private #define (FABRIC-3.md §H.12 step 3) so session.c's pin-
+ * authority choke point (session_set_pinned()/session_is_pinned()) can
+ * write/read this same bit without a duplicate definition. Session is
+ * authoritative for every EXTERNAL reader (FABRIC-3.md §H.10) -- this bit
+ * on the raw patron header stays a mirrored copy purely for the Stadium
+ * engine's own internal eviction/admission logic (stadium.c), which must
+ * stay self-contained and not call back into session.c. */
+#define STADIUM_FLAG_PIN 0x01u
+
 /*
  * StadiumPatronHeader - one member of the closed two-valued cell union
  * (FABRIC.md §3). Nine wires: identity, heat, TTL, pin (a bit in `flags`),