refactor(daemon): the admitted-plan token names its device; the snapshot binder binds only from the token

Review (P1): the token proved the plan but not the device, so a caller could
admit facts for device A and bind device B through the binder's separate
device argument. AdmittedRuntimePlan now carries the device the facts were
read for, bindSnapshotCaptureRuntime takes (bindDevice, admission) and binds
admission.device, and the route passes the token alone. Mismatched-device
binding is no longer expressible: a @ts-expect-error pins the removed
parameter (re-adding it fails tsc), and a recording binder proves the bind
target is the token's device.

Author: thymikee

src/daemon/__tests__/snapshot-runtime-binding.test.ts

@@ -1,25 +1,44 @@
 import { resolveSnapshotRuntimePlan } from '@agent-device/contracts/platform';
+import type { DeviceInfo } from '@agent-device/kernel/device';
 import { expect, test } from 'vitest';
-import { IOS_SIMULATOR } from '../../__tests__/test-utils/index.ts';
+import { ANDROID_EMULATOR, IOS_SIMULATOR } from '../../__tests__/test-utils/index.ts';
 import { admitRuntimePlan } from '../handlers/session-runtime-admission.ts';
+import type { BindDeviceRuntime } from '../request-runtime-binding.ts';
 import { bindSnapshotCaptureRuntime } from '../snapshot-runtime-binding.ts';
 import { snapshotRuntimeFixture } from './snapshot-runtime-fixture.ts';
 
-test('the snapshot binder takes an admission, never a bare plan', () => {
+test('the snapshot binder takes an admission, never a bare plan and never a separate device', async () => {
+  const { inspectFacts } = snapshotRuntimeFixture();
   const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
-  // Type-level proof that admit-before-bind is enforced at the seam: the binder's parameter is
-  // AdmittedRuntimePlan<SnapshotRuntimePlan>, which only admitRuntimePlan produces. Widening it
-  // back to SnapshotRuntimePlan makes this directive unused and tsc fails.
+  const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
+  // Type-level proof that admit-before-bind is enforced at the seam: the binder's only
+  // input besides the request-scope binder is AdmittedRuntimePlan<SnapshotRuntimePlan>, which
+  // only admitRuntimePlan produces and which names the device it was admitted for. Widening the
+  // parameter back to a plan, or re-adding a device parameter, makes a directive below unused
+  // and tsc fails.
   // @ts-expect-error the facts-first binder requires the admission token, not the plan
-  const bindBarePlan = () => bindSnapshotCaptureRuntime(undefined, IOS_SIMULATOR, plan);
-  expect(bindBarePlan).toBeTypeOf('function');
+  const bindBarePlan = () => bindSnapshotCaptureRuntime(undefined, plan);
+  // @ts-expect-error there is no separate device argument: the token's device is the bind target
+  const bindOtherDevice = () => bindSnapshotCaptureRuntime(undefined, ANDROID_EMULATOR, admission);
+  expect([bindBarePlan, bindOtherDevice].every((fn) => typeof fn === 'function')).toBe(true);
 });
 
-test('binds the operation the admitted plan selected and nothing wider', async () => {
+test('binds exactly the device the facts were admitted for, and only the plan’s operation', async () => {
   const { inspectFacts, bindDevice } = snapshotRuntimeFixture();
+  const boundDevices: DeviceInfo[] = [];
+  const recordingBind: BindDeviceRuntime = async (device, use) => {
+    boundDevices.push(device);
+    return await bindDevice(device, use);
+  };
   const plan = resolveSnapshotRuntimePlan({ customActions: false, hasActiveApp: true });
   const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
   if (!admission.admitted) throw new Error('fixture admits captureSnapshot on an iOS simulator');
-  const runtime = await bindSnapshotCaptureRuntime(bindDevice, IOS_SIMULATOR, admission);
+
+  const runtime = await bindSnapshotCaptureRuntime(recordingBind, admission);
+
+  // Whatever a caller holds besides the token (a session, another device) is irrelevant to the
+  // bind: the request-scope binder only ever sees the token's own device.
+  expect(boundDevices).toEqual([IOS_SIMULATOR]);
+  expect(admission.device).toBe(IOS_SIMULATOR);
   expect(Object.keys(runtime)).toEqual(['captureSnapshot']);
 });

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

@@ -11,9 +11,11 @@ test('admits the plan whose required operations the owner facts report available
   const admission = await admitRuntimePlan({ device: IOS_SIMULATOR, plan, inspectFacts });
   expect(admission.admitted).toBe(true);
   if (!admission.admitted) throw new Error('unreachable');
-  // The token carries the very plan that was admitted, so a binder that takes the token
-  // binds exactly the use the facts were checked against.
+  // The token carries the very plan and the very device that were admitted, so a binder that
+  // takes the token binds exactly the use the facts were checked against, on exactly the device
+  // the facts were read for.
   expect(admission.plan).toBe(plan);
+  expect(admission.device).toBe(IOS_SIMULATOR);
 });
 
 test('refuses on the first required operation the owner facts report unavailable', async () => {
@@ -40,6 +42,6 @@ test('the admission proof cannot be written down: only admitRuntimePlan mints it
   // 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, plan };
+  const forged: AdmittedRuntimePlan<typeof plan> = { admitted: true, device: IOS_SIMULATOR, plan };
   expect(forged.plan).toBe(plan);
 });

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

@@ -51,9 +51,15 @@ export type RuntimePlan = Readonly<{
 // "admit before bind" at the seam, without inspecting the route's syntax.
 const admissionProof: unique symbol = Symbol('agent-device.runtime-plan-admitted');
 
-/** Proof that every operation `plan.use` requires is available on the device's owner facts. */
+/**
+ * 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.
+ */
 export type AdmittedRuntimePlan<Plan extends RuntimePlan> = Readonly<{
   admitted: true;
+  device: DeviceInfo;
   plan: Plan;
   readonly [admissionProof]: true;
 }>;
@@ -81,7 +87,12 @@ 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, plan: params.plan, [admissionProof]: true as const });
+  return Object.freeze({
+    admitted: true,
+    device: params.device,
+    plan: params.plan,
+    [admissionProof]: true as const,
+  });
 }
 
 export function requireRuntimeBinding(

src/daemon/snapshot-runtime-binding.ts

@@ -17,17 +17,16 @@ import {
 import { errorResponse } from './handlers/response.ts';
 
 /**
- * Binds only an admitted plan: the token is minted by `admitRuntimePlan` alone, so a route
- * cannot reach the capture operations without the facts-first admission having run for the
- * very plan whose use is bound here.
+ * Binds only an admitted plan, and only the device it was admitted for: the token is minted by
+ * `admitRuntimePlan` alone and carries both, so a route cannot reach the capture operations
+ * without the facts-first admission having run for the very plan and device bound here.
  */
 export async function bindSnapshotCaptureRuntime(
   bindDevice: BindDeviceRuntime | undefined,
-  device: SessionState['device'],
   admission: AdmittedRuntimePlan<SnapshotRuntimePlan>,
 ): Promise<Readonly<{ captureSnapshot(input: CaptureSnapshotInput): Promise<SnapshotResult> }>> {
   const bind = requireRuntimeBinding(bindDevice);
-  const { plan } = admission;
+  const { device, plan } = admission;
   switch (plan.kind) {
     case 'active-app': {
       const runtime = await bind(device, plan.use);

src/daemon/snapshot-runtime.ts

@@ -73,7 +73,7 @@ export async function dispatchSnapshotViaRuntime(params: {
       device,
     });
   }
-  const runtime = await bindSnapshotCaptureRuntime(params.bindDevice, device, admission);
+  const runtime = await bindSnapshotCaptureRuntime(params.bindDevice, admission);
   return await withSessionlessRunnerCleanup(
     session,
     device,