§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>

FABRIC-3.md

@@ -3955,8 +3955,19 @@ work, not new invention.
    must run after `stadium_boot_init()`. Added `session.c` to `Makefile.starkernel`'s explicit
    `LOADER_EXTRA_SRCS`/`KERNEL_EXTRA_SRCS` list (not a wildcard build). No callers yet.
    Verified 3-arch boot to `ok>`.
-3. `session_set_pinned()`/`session_is_pinned()` — the pin-authority choke point (H.2/H.10):
-   writes/reads `Session.pinned`, syncs `STADIUM_FLAG_PIN` on that VM's patron cell.
+3. **DONE 2026-09-03, one addition found necessary.** `session_set_pinned()`/
+   `session_is_pinned()` implemented — the pin-authority choke point (H.2/H.10).
+   `session_is_pinned()` answers from `Session.pinned` directly (the authoritative copy, no
+   Stadium re-derivation); `session_set_pinned()` writes both `Session.pinned` and the
+   mirrored `STADIUM_FLAG_PIN` bit on the session's own patron header, so Stadium's own
+   internal eviction/admission logic (which must stay self-contained, no call back into
+   session.c) keeps seeing a correct bit. **Addition**: `Session` needed a `stadium_cell`
+   field (index into `stadium_cells()`) that wasn't in the original §H.2 field list — the
+   choke point can't reach the right patron header without it. Necessary plumbing, not a new
+   session-level concept, so not treated as reopening §H.2's design. Also moved
+   `STADIUM_FLAG_PIN`'s `#define` from a `stadium.c`-private constant to `stadium.h` (public)
+   so `session.c` can reference it without duplicating the definition. Verified 3-arch boot to
+   `ok>`.
 4. Rewire `stadium_birth_hera()` to register through `session_register()`/
    `session_set_pinned()` instead of setting `STADIUM_FLAG_PIN` directly — Hera becomes
    session zero.

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-09-03T10:01:35Z -->
+<!-- Generated by mkcapsule --manifest  2026-09-03T10:08:29Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

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`),

src/starkernel/vm/session.c

@@ -22,7 +22,7 @@
  */
 
 /**
- * session.c - Per-VM session bookkeeping (FABRIC-3.md §H.12 step 2)
+ * session.c - Per-VM session bookkeeping (FABRIC-3.md §H.12 steps 2-3)
  *
  * Slot table sized from stadium_max_vm_count() at session_boot_init() time,
  * mirroring stadium.c's own StadiumVMQuota table (kmalloc'd to a
@@ -31,6 +31,10 @@
  * settled). No callers yet; wiring into the boot sequence and into
  * stadium_birth_hera()/capsule_birth.c's admission path are later
  * §H.12 steps.
+ *
+ * session_set_pinned()/session_is_pinned() (step 3) are the pin-authority
+ * choke point -- see their own doc comments in session.h for the
+ * authoritative-session-mirrored-Stadium-bit split.
  */
 
 #ifdef __STARKERNEL__
@@ -99,9 +103,10 @@ Session *session_register(VMUuid vm_id, VMUuid parent, const char *name)
     }
     if (!slot) return (Session *)0; /* table full */
 
-    slot->vm_id  = vm_id;
-    slot->parent = parent;
-    slot->pinned = 0;
+    slot->vm_id       = vm_id;
+    slot->parent      = parent;
+    slot->pinned      = 0;
+    slot->stadium_cell = SESSION_STADIUM_CELL_NONE;
 
     {
         size_t j = 0;
@@ -121,4 +126,32 @@ Session *session_register(VMUuid vm_id, VMUuid parent, const char *name)
     return slot;
 }
 
+void session_set_pinned(VMUuid vm_id, int pinned)
+{
+    Session *s = session_find(vm_id);
+    StadiumCell *cells;
+
+    if (!s) return;
+    s->pinned = pinned ? 1 : 0;
+
+    if (s->stadium_cell == SESSION_STADIUM_CELL_NONE) return;
+    if (s->stadium_cell >= stadium_cell_count()) return;
+
+    cells = stadium_cells();
+    if (!cells) return;
+
+    if (pinned) {
+        cells[s->stadium_cell].header.flags |= STADIUM_FLAG_PIN;
+    } else {
+        cells[s->stadium_cell].header.flags &= (uint8_t)~STADIUM_FLAG_PIN;
+    }
+}
+
+int session_is_pinned(VMUuid vm_id)
+{
+    Session *s = session_find(vm_id);
+    if (!s) return 0;
+    return s->pinned;
+}
+
 #endif /* __STARKERNEL__ */

src/starkernel/vm/stadium.c

@@ -335,7 +335,8 @@ uint64_t stadium_density(size_t cell_index) {
     return header->heat / (uint64_t)header->mass;
 }
 
-#define STADIUM_FLAG_PIN 0x01u
+/* STADIUM_FLAG_PIN moved to stadium.h (FABRIC-3.md §H.12 step 3) -- see its
+ * doc comment there for why. */
 
 static int bitmap_get(size_t cell_index) {
     return (stadium_bitmap[cell_index / 8u] >> (cell_index % 8u)) & 1u;