refactor(daemon): the admitted-plan token is a nominal, non-copyable object, not a branded literal

Review (P1): spreading a valid admission and overriding device or plan kept
the enumerable symbol brand and stayed assignable, so facts admitted for A
could bind B. The token is now a class whose payload lives in #private fields
behind getter-only accessors, minted only through a closure set in its static
block; the class value is not exported (only its type), so no module can name
the constructor. A spread is a plain object without the private members and
is not assignable; Object.assign / defineProperty on the frozen instance throw.
Planted reds: degrading the token to a plain public shape makes both
@ts-expect-error directives unused (2 tsc errors); the previous branded
literal fails the new runtime retarget test.

Author: thymikee

src/daemon/handlers/__tests__/session-runtime-admission.test.ts

@@ -35,13 +35,36 @@ test('throws when no facts inspection seam was supplied', async () => {
   );
 });
 
-test('the admission proof cannot be written down: only admitRuntimePlan mints it', () => {
+test('the admission cannot be written down, constructed, or copied: only admitRuntimePlan mints it', async () => {
   const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
-  // A planted red for the seam itself: delete the proof key from AdmittedRuntimePlan and this
-  // directive becomes unused, which tsc reports. The key is a module-private symbol, so no
-  // literal in any other module can satisfy the type — a route holds a token only by having
-  // called admitRuntimePlan (or by a type assertion, which the cutover gate rejects in src/daemon/).
-  // @ts-expect-error a literal without the module-private proof key is not an admission
-  const forged: AdmittedRuntimePlan<typeof plan> = { admitted: true, device: IOS_SIMULATOR, plan };
-  expect(forged.plan).toBe(plan);
+  const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
+  if (!admission.admitted) throw new Error('unreachable');
+  // Planted reds for the seam itself: each directive below becomes unused — and tsc fails — if
+  // the token loses its #private payload or its private constructor. A route holds a token only
+  // by having called admitRuntimePlan (or by a type assertion, which the cutover gate rejects in
+  // src/daemon/).
+  // @ts-expect-error a literal is not an admission: it lacks the #private payload
+  const literal: AdmittedRuntimePlan<typeof plan> = { admitted: true, device: IOS_SIMULATOR, plan };
+  // @ts-expect-error a spread of a real admission is a plain object without the #private payload
+  const retargeted: AdmittedRuntimePlan<typeof plan> = { ...admission, device: ANDROID_EMULATOR };
+  // The class value is not exported at all, so `new` is not even nameable from here — there is
+  // nothing to plant; the module's only runtime export that yields a token is admitRuntimePlan.
+  expect([literal, retargeted].length).toBe(2);
+});
+
+test('at runtime a token cannot be retargeted either: spreads carry nothing and assignment throws', async () => {
+  const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
+  const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
+  if (!admission.admitted) throw new Error('unreachable');
+  // The payload lives in #private fields behind getter-only accessors on the prototype: a spread
+  // copies own enumerable properties, of which there are none.
+  expect(Object.keys({ ...admission })).toEqual([]);
+  expect(({ ...admission } as { device?: unknown }).device).toBeUndefined();
+  // Getter-only + frozen: neither assignment nor redefinition can move the device.
+  expect(() => Object.assign(admission, { device: ANDROID_EMULATOR })).toThrow(TypeError);
+  expect(() => Object.defineProperty(admission, 'device', { value: ANDROID_EMULATOR })).toThrow(
+    TypeError,
+  );
+  expect(admission.device).toBe(IOS_SIMULATOR);
+  expect(admission.plan).toBe(plan);
 });

src/daemon/handlers/session-runtime-admission.ts

@@ -44,25 +44,61 @@ export type RuntimePlan = Readonly<{
   use: Readonly<{ required: readonly RuntimeOperationKey<PlatformRuntimeOperations>[] }>;
 }>;
 
-// The admission proof is a module-private symbol: no other module can name its type, so the
-// only way to hold an AdmittedRuntimePlan is to have received it from admitRuntimePlan (or to
-// forge one with a type assertion, which the cutover gate's manufactured-proof column rejects
-// in src/daemon/). A facts-first binder that requires the token therefore enforces
-// "admit before bind" at the seam, without inspecting the route's syntax.
-const admissionProof: unique symbol = Symbol('agent-device.runtime-plan-admitted');
+// Minted only inside the class's static block below: the constructor is private, so no other
+// module (or a spread, or Object.assign) can produce or retarget one — see the class doc.
+let mintAdmission: <Plan extends RuntimePlan>(
+  device: DeviceInfo,
+  plan: Plan,
+) => AdmittedRuntimePlanToken<Plan>;
 
 /**
  * Proof that every operation `plan.use` requires is available on `device`'s owner facts. The
  * token names the device the facts were read for, and a facts-first binder binds *that* device
  * from the token rather than taking one separately — so facts admitted for device A can never
  * bind device B.
+ *
+ * It is a nominal, non-copyable object rather than a branded literal: the payload lives in
+ * `#private` fields behind getter-only accessors, so a spread (`{ ...admission, device: other }`)
+ * yields a plain object that lacks the private members and is not assignable to this type, and
+ * `Object.assign(admission, { device })` throws on the getter-only property. The constructor is
+ * private and the class value is not exported — only its type is — so no other module can even
+ * name the constructor at runtime; the only caller is `admitRuntimePlan`, through a closure
+ * captured in the static block. What remains is a type assertion, which the cutover gate's
+ * manufactured-proof column rejects in src/daemon/. A facts-first binder that requires the token
+ * therefore enforces "admit before bind" — for this device, for this plan — at the seam.
  */
-export type AdmittedRuntimePlan<Plan extends RuntimePlan> = Readonly<{
-  admitted: true;
-  device: DeviceInfo;
-  plan: Plan;
-  readonly [admissionProof]: true;
-}>;
+class AdmittedRuntimePlanToken<Plan extends RuntimePlan> {
+  static {
+    mintAdmission = (device, plan) => {
+      const token = new AdmittedRuntimePlanToken(device, plan);
+      Object.freeze(token);
+      return token;
+    };
+  }
+
+  readonly #device: DeviceInfo;
+  readonly #plan: Plan;
+
+  private constructor(device: DeviceInfo, plan: Plan) {
+    this.#device = device;
+    this.#plan = plan;
+  }
+
+  get admitted(): true {
+    return true;
+  }
+
+  /** The device whose owner facts admitted the plan — the only bind target a binder may use. */
+  get device(): DeviceInfo {
+    return this.#device;
+  }
+
+  get plan(): Plan {
+    return this.#plan;
+  }
+}
+
+export type AdmittedRuntimePlan<Plan extends RuntimePlan> = AdmittedRuntimePlanToken<Plan>;
 
 export type RefusedRuntimePlan<Plan extends RuntimePlan> = Readonly<{
   admitted: false;
@@ -87,12 +123,7 @@ export async function admitRuntimePlan<const Plan extends RuntimePlan>(
     const fact = facts.operations[operation];
     if (!fact.available) return { admitted: false, operation, fact };
   }
-  return Object.freeze({
-    admitted: true,
-    device: params.device,
-    plan: params.plan,
-    [admissionProof]: true as const,
-  });
+  return mintAdmission(params.device, params.plan);
 }
 
 export function requireRuntimeBinding(