feat: add deterministic device selection resolver (#2020)

* feat: add deterministic device selection resolver

* test: adapt open selection harnesses

* chore: keep context glossary within budget

* fix: separate device identity from selection filters

* refactor: make the selection resolver the sole owner of selection provenance

Simplifies the deterministic device-selection resolver (net -114 lines vs the
previous head) while fixing the outstanding app-aware provenance finding:

- Move the booted-simulator app-affinity narrowing into the resolver behind an
  appleSimulatorAppTarget param, with its own typed reason
  'single-app-installed-local' (candidateCount 1). This removes the
  selectedDevice escape hatch that reported 'preferred-local' with
  candidateCount 2 for the app-narrowed pick, and gives the app-match errors
  the same platform-aware retry selectors as every other selection failure.
- Delete dead code: the allowBootableLocal param (no caller ever passed it, so
  the eligibleDevices filter was unreachable), the hasExplicitProviderIdentity
  alias, the duplicated deviceCandidateDetails in dispatch-resolve, and the
  double candidate computation.
- Shrink the public selection contract to what #1777 specifies: drop `booted`
  (it contradicted its own doc comment once markSelectionBootedAfterPreparation
  flipped it; bootOccurred plus the reason codes carry the same information)
  and drop `retrySelectors` from success metadata (the daemon only ever emits
  retry selectors inside error details). DeviceSelectionRetrySelector leaves
  the contracts facade.
- Replace the typeof-import lazy seam and resolver threading through four
  context objects with one lazy forwarding wrapper; the dispatch eager closure
  stays at 83.
- Collapse the Apple path to resolve -> optional simulator fallback; the
  provider branch goes through the generic resolver call directly.
- Consolidate the five copy-pasted resolveTargetDeviceSelection test mocks
  into one shared stub (selectionFromResolveTargetDevice).
- Add the requested regression: two booted simulators with the app on one now
  assert typed selection metadata through resolveTargetDeviceSelection, plus a
  resolver-level app-affinity provenance test.

Validation: typecheck, oxlint, oxfmt, layering (184-check guard OK), DI seams,
fallow changed-files, eager-closure 235/235, daemon suite 323 files / 2287
tests, core/commands/mcp/client suites 255 files / 2133 tests.

Author: thymikee

packages/contracts/src/client-app.ts

@@ -15,6 +15,26 @@ import type {
 } from './client-connection.ts';
 import type { AgentDeviceSessionDevice, StartupPerfSample } from './client-device-view.ts';
 
+export type DeviceSelectionReason =
+  | 'explicit-selector'
+  | 'existing-session'
+  | 'single-booted-local'
+  | 'single-bootable-local'
+  | 'single-app-installed-local'
+  | 'preferred-local'
+  | 'single-provider-device';
+
+export type DeviceSelectionSource = 'session' | 'local' | 'provider';
+
+/** Deterministic device-selection evidence shared by daemon responses and the published client. */
+export type DeviceSelectionMetadata = {
+  reason: DeviceSelectionReason;
+  source: DeviceSelectionSource;
+  candidateCount: number;
+  /** Whether this request booted a previously stopped local virtual target during open. */
+  bootOccurred: boolean;
+};
+
 export type AppInstallOptions = AgentDeviceRequestOverrides &
   AgentDeviceSelectionOptions & {
     app?: string;
@@ -73,6 +93,7 @@ export type AppOpenResult = {
   appId?: string;
   startup?: StartupPerfSample;
   runtime?: SessionRuntimeHints;
+  selection?: DeviceSelectionMetadata;
   device?: AgentDeviceSessionDevice;
   /**
    * Initial interactive snapshot captured immediately after an open that

packages/contracts/src/facades/client.ts

@@ -11,6 +11,9 @@ export type {
   AppOpenResult,
   AppPushOptions,
   AppTriggerEventOptions,
+  DeviceSelectionMetadata,
+  DeviceSelectionReason,
+  DeviceSelectionSource,
   MaterializationReleaseOptions,
   MaterializationReleaseResult,
 } from '../client-app.ts';

packages/kernel/src/device.ts

@@ -68,6 +68,15 @@ export type DeviceSelector = {
   serial?: string;
 };
 
+/** Device identity is narrower than platform/target filtering for precedence decisions. */
+export function hasExplicitDeviceIdentitySelector(
+  selector: Pick<DeviceSelector, 'deviceName' | 'udid' | 'serial'>,
+): boolean {
+  return [selector.deviceName, selector.udid, selector.serial].some(
+    (value) => typeof value === 'string' && value.trim().length > 0,
+  );
+}
+
 type DeviceSelectionContext = {
   simulatorSetPath?: string;
 };

src/__tests__/cli-help.test.ts

@@ -82,6 +82,9 @@ test('help workflow prints the compact workflow card with a version header and s
   assert.match(result.stdout, /no CSS selectors/);
   assert.match(result.stdout, /help scripting/);
   assert.match(result.stdout, /help gestures/);
+  assert.match(result.stdout, /Selection: explicit --device\/--udid\/--serial/);
+  assert.match(result.stdout, /--platform\/--target only filter/);
+  assert.match(result.stdout, /bounded retry selectors/);
 });
 
 test('help workflow encourages chaining confident steps and requires the end state to be on screen', async () => {
@@ -141,7 +144,7 @@ test('help workflow advertises open --foreground and snapshot -i --actions', asy
   assert.equal(result.calls.length, 0);
   assert.match(
     result.stdout,
-    /Known app: open <app> --foreground -> snapshot\. Bare form needs one running app on one iOS sim; capture failure keeps session open/,
+    /open --foreground -> snapshot\. Selection: explicit --device\/--udid\/--serial/,
   );
   assert.match(
     result.stdout,

src/__tests__/client-normalizers.test.ts

@@ -2,6 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import {
   normalizeDevice,
+  normalizeDeviceSelection,
   normalizeOpenDevice,
   normalizeSession,
 } from '../client/client-normalizers.ts';
@@ -24,6 +25,32 @@ test('normalizeOpenDevice accepts exactly the canonical leaf platforms', () => {
   );
 });
 
+test('normalizeDeviceSelection preserves structured resolver evidence and rejects malformed data', () => {
+  assert.deepEqual(
+    normalizeDeviceSelection({
+      reason: 'single-app-installed-local',
+      source: 'local',
+      candidateCount: 1,
+      bootOccurred: false,
+    }),
+    {
+      reason: 'single-app-installed-local',
+      source: 'local',
+      candidateCount: 1,
+      bootOccurred: false,
+    },
+  );
+  assert.equal(
+    normalizeDeviceSelection({
+      reason: 'single-booted-local',
+      source: 'local',
+      candidateCount: -1,
+      bootOccurred: false,
+    }),
+    undefined,
+  );
+});
+
 test('normalizeOpenDevice rejects the apple selector and unknown platforms', () => {
   // `apple` is a selector, not a concrete device platform, so it must be rejected here.
   assert.equal(

src/agent-device-client.ts

@@ -42,6 +42,7 @@ import {
   buildMeta,
   normalizeDeployResult,
   normalizeDevice,
+  normalizeDeviceSelection,
   normalizeOpenForegroundComposition,
   normalizeInstallFromSourceResult,
   normalizeMaterializationReleaseResult,
@@ -277,6 +278,7 @@ export function createAgentDeviceClient(
           appName: readOptionalString(data, 'appName'),
           appBundleId,
           appId,
+          selection: normalizeDeviceSelection(data.selection),
           startup: normalizeStartupSample(data.startup),
           runtime: normalizeRuntimeHints(data.runtime),
           device,

src/cli-schema/cli-help-topics.test.ts

@@ -138,7 +138,7 @@ test('usageForCommand resolves workflow help topic', async () => {
   assert.match(help, /Shapes and platform quirks: help gestures/);
   assert.match(
     help,
-    /Known app: open <app> --foreground -> snapshot\. Bare form needs one running app on one iOS sim; capture failure keeps session open/,
+    /open --foreground -> snapshot\. Selection: explicit --device\/--udid\/--serial, then session, booted\/bootable local, or one provider; --platform\/--target only filter\./,
   );
   assert.match(help, /Never open artifact paths or invent package ids/);
   assert.match(

src/cli-schema/cli-help.ts

@@ -134,9 +134,7 @@ Command shape:
   Gestures: scroll/swipe for lists/flicks; gesture pan|fling|pinch|rotate|transform|drag for multi-touch. Shapes and platform quirks: help gestures.
 
 Bootstrap:
-  agent-device devices --platform ios
-  agent-device open MyApp --platform ios --device "iPhone 17 Pro"
-  Known app: open <app> --foreground -> snapshot. Bare form needs one running app on one iOS sim; capture failure keeps session open.
+  open --foreground -> snapshot. Selection: explicit --device/--udid/--serial, then session, booted/bootable local, or one provider; --platform/--target only filter. Ambiguous/empty fails with bounded retry selectors; providers never fall back.
   Install arguments are app/package id then artifact path: agent-device install com.example.app ./dist/app.apk --platform android, then open <id> --relaunch for fresh state. Use reinstall only when explicitly requested.
   Unknown app id: devices, then apps, then open <discovered-app-id>. Never open artifact paths or invent package ids; ask if lookup misses the target.
   Apple CI: prepare ios-runner after boot/install, before replay/test (help prepare). Remote/cloud: connect -> open -> commands -> close -> disconnect (help remote). Reusable scripts, secret-safe fills, replay repair: help scripting.

src/client/client-normalizers.ts

@@ -7,6 +7,7 @@ import type {
   InternalRequestOptions,
   MaterializationReleaseResult,
   StartupPerfSample,
+  DeviceSelectionMetadata,
 } from '@agent-device/contracts/client';
 import type { TargetShutdownResult } from '@agent-device/contracts/device';
 import {
@@ -228,6 +229,43 @@ export function normalizeOpenDevice(
   };
 }
 
+const DEVICE_SELECTION_REASONS: readonly DeviceSelectionMetadata['reason'][] = [
+  'explicit-selector',
+  'existing-session',
+  'single-booted-local',
+  'single-bootable-local',
+  'single-app-installed-local',
+  'preferred-local',
+  'single-provider-device',
+];
+
+const DEVICE_SELECTION_SOURCES: readonly DeviceSelectionMetadata['source'][] = [
+  'session',
+  'local',
+  'provider',
+];
+
+export function normalizeDeviceSelection(value: unknown): DeviceSelectionMetadata | undefined {
+  if (!isRecord(value)) return undefined;
+  const { reason, source, candidateCount, bootOccurred } = value;
+  if (
+    !DEVICE_SELECTION_REASONS.includes(reason as DeviceSelectionMetadata['reason']) ||
+    !DEVICE_SELECTION_SOURCES.includes(source as DeviceSelectionMetadata['source']) ||
+    typeof candidateCount !== 'number' ||
+    !Number.isInteger(candidateCount) ||
+    candidateCount < 0 ||
+    typeof bootOccurred !== 'boolean'
+  ) {
+    return undefined;
+  }
+  return {
+    reason: reason as DeviceSelectionMetadata['reason'],
+    source: source as DeviceSelectionMetadata['source'],
+    candidateCount,
+    bootOccurred,
+  };
+}
+
 export function normalizeStartupSample(value: unknown): StartupPerfSample | undefined {
   if (!isRecord(value)) return undefined;
   if (

src/commands/management/output.test.ts

@@ -46,6 +46,28 @@ describe('openCliOutput', () => {
     expect(output.text).toBe(`Opened: authoring\nWarning: ${warning}`);
   });
 
+  test('preserves device-selection evidence in the CLI payload', () => {
+    const output = openCliOutput({
+      session: 'selected',
+      selection: {
+        reason: 'single-booted-local',
+        source: 'local',
+        candidateCount: 2,
+        bootOccurred: false,
+      },
+      identifiers: { session: 'selected' },
+    });
+
+    expect(output.data).toMatchObject({
+      selection: {
+        reason: 'single-booted-local',
+        source: 'local',
+        candidateCount: 2,
+        bootOccurred: false,
+      },
+    });
+  });
+
   // #1671 P1: the composed open --foreground snapshot must render on default
   // stdout through the PRODUCTION formatter route (the family-registry entry
   // the CLI resolves, not a helper mock), printing the same interactive tree