yaver-feedback-react-native 0.9.0 → 0.9.3

package/src/__tests__/ReportIdentity.test.ts

@@ -0,0 +1,212 @@
+// resolveAppIdentity() has always fed /vibing/execute and /dev/reload-app so
+// the agent could route "vibe on THIS app" to the right repo, but nothing fed
+// /feedback — reports carried no identity at all, so the agent's fix router
+// had nothing to resolve and fell back to whatever directory it was sitting
+// in. resolveReportIdentity() closes that gap for the feedback path.
+
+const mockReactNative = {
+  Platform: { OS: 'ios' },
+  NativeModules: {},
+};
+const mockExpoModule: { default: Record<string, unknown> } = { default: {} };
+
+jest.mock('react-native', () => mockReactNative);
+jest.mock('expo-constants', () => mockExpoModule, { virtual: true });
+
+/** Mirrors mobile/app.json in the Talos repo — the SDK's first external consumer. */
+const EXPO_CONFIG = {
+  name: 'Talos',
+  slug: 'talos-mobile',
+  version: '1.9.157',
+  ios: { bundleIdentifier: 'works.talos.mobile', buildNumber: '427' },
+  android: { package: 'works.talos.mobile', versionCode: 423 },
+};
+
+function mockExpoConstants(expoConfig: unknown, extra: Record<string, unknown> = {}) {
+  mockExpoModule.default = { expoConfig, ...extra };
+}
+
+function loadResolve(): typeof import('../P2PClient').resolveReportIdentity {
+  let resolve!: typeof import('../P2PClient').resolveReportIdentity;
+  jest.isolateModules(() => {
+    jest.doMock('react-native', () => mockReactNative);
+    jest.doMock('expo-constants', () => mockExpoModule, { virtual: true });
+    resolve = require('../P2PClient').resolveReportIdentity;
+  });
+  return resolve;
+}
+
+beforeEach(() => {
+  // P2PClient is imported by many suites with different virtual RN/Expo
+  // modules. Re-evaluate it against this suite's mutable modules every time;
+  // an order-dependent green test is not an identity-routing guard.
+  jest.resetModules();
+  mockReactNative.Platform.OS = 'ios';
+  mockReactNative.NativeModules = {};
+  mockExpoModule.default = {};
+});
+
+describe('resolveReportIdentity', () => {
+  it('resolves app name and bundle id from the Expo config', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const resolve = loadResolve();
+
+    const identity = resolve();
+
+    // The agent's fix router reads DeviceInfo.AppName first.
+    expect(identity.appName).toBe('Talos');
+    // ...and resolves the project by bundle id, the only unambiguous key.
+    expect(identity.project?.bundleId).toBe('works.talos.mobile');
+    expect(identity.project?.projectName).toBe('Talos');
+    expect(identity.project?.appName).toBe('Talos');
+    expect(identity.project?.surface).toBe('mobile');
+    expect(identity.app.bundleId).toBe('works.talos.mobile');
+  });
+
+  it('never reports a project path', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const resolve = loadResolve();
+
+    // The agent ignores client-supplied paths on feedback reports (an
+    // untrusted guest could otherwise aim the fix task's CWD at ~/.ssh).
+    // Sending one would be misleading at best.
+    expect(resolve().project?.projectPath).toBeUndefined();
+  });
+
+  it('prefers the native runtime version over the manifest version', () => {
+    mockExpoConstants(EXPO_CONFIG, { nativeAppVersion: '1.9.158', nativeBuildVersion: '428' });
+    const resolve = loadResolve();
+
+    const identity = resolve();
+    // A stale manifest shouldn't misreport which build is actually running.
+    expect(identity.app.version).toBe('1.9.158');
+    expect(identity.app.buildNumber).toBe('428');
+  });
+
+  it('falls back to the manifest version when no native version is exposed', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const resolve = loadResolve();
+
+    const identity = resolve();
+    expect(identity.app.version).toBe('1.9.157');
+    expect(identity.app.buildNumber).toBe('427');
+  });
+
+  // Inside Yaver's container the ambient runtime IS Yaver. These are the
+  // cases where getting it wrong routes a fix task into yaver.io and edits
+  // the SDK instead of the app under test.
+  describe('inside the Yaver container (Hermes guest)', () => {
+    const YAVER_CONFIG = {
+      name: 'Yaver',
+      version: '1.99.306',
+      ios: { bundleIdentifier: 'io.yaver.mobile' },
+      android: { package: 'io.yaver.mobile' },
+    };
+
+    function mockContainer(yaverInfo: Record<string, unknown>) {
+      mockReactNative.NativeModules = { YaverInfo: { isYaver: true, ...yaverInfo } };
+      // The host's manifest — what expo-constants answers for a guest bundle.
+      mockExpoConstants(YAVER_CONFIG);
+    }
+
+    it("never reports the host's bundle id as the guest's", () => {
+      mockContainer({ inheritedGuestProjectName: 'talos / mobile' });
+      const resolve = loadResolve();
+
+      const identity = resolve();
+
+      // The agent routes on bundle id FIRST. Leaking io.yaver.mobile here
+      // would resolve to yaver.io and the project name would never be read.
+      expect(identity.project?.bundleId).toBeUndefined();
+      expect(identity.app.bundleId).toBeUndefined();
+      // Nor should the host's version masquerade as the guest's build.
+      expect(identity.app.version).toBeUndefined();
+    });
+
+    it('reports the guest project Yaver pinned', () => {
+      mockContainer({ inheritedGuestProjectName: 'talos / mobile' });
+      const resolve = loadResolve();
+
+      const identity = resolve();
+      expect(identity.appName).toBe('talos / mobile');
+      expect(identity.project?.projectName).toBe('talos / mobile');
+    });
+
+    it("lets the app's own declaration win over the pinned project", () => {
+      mockContainer({ inheritedGuestProjectName: 'something-else' });
+      const resolve = loadResolve();
+
+      // A bundle knows its own identity; nothing ambient should override it.
+      const identity = resolve({ projectName: 'Talos', bundleId: 'works.talos.mobile' });
+      expect(identity.appName).toBe('Talos');
+      expect(identity.project?.bundleId).toBe('works.talos.mobile');
+    });
+
+    it('reports nothing rather than something wrong when no project is pinned', () => {
+      mockContainer({});
+      const resolve = loadResolve();
+
+      // Better for the agent to reject/fall back than to confidently edit
+      // the wrong repo.
+      const identity = resolve();
+      expect(identity.project).toBeUndefined();
+      expect(identity.appName).toBeUndefined();
+      expect(identity.app).toEqual({});
+    });
+  });
+
+  it('lets an explicit declaration override the ambient identity', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const resolve = loadResolve();
+
+    const identity = resolve({ projectName: 'Override', bundleId: 'com.override.app' });
+    expect(identity.appName).toBe('Override');
+    expect(identity.project?.bundleId).toBe('com.override.app');
+  });
+
+  it('passes declared surfaces stacks and voice metadata through', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const resolve = loadResolve();
+
+    const identity = resolve({
+      projectName: 'Omni',
+      bundleId: 'io.example.omni',
+      surface: 'vision',
+      surfaces: ['mobile', 'web', 'watch', 'tv', 'car', 'vision'],
+      stack: 'react-native-expo',
+      stacks: ['react-native-expo', 'nextjs', 'yaver-xml'],
+      testSurfaces: ['rn-hermes', 'browser', 'visionos-simulator'],
+      feedbackSdk: 'yaver-feedback-react-native',
+      feedbackTransport: 'device-sdk',
+      voiceCapabilities: ['stt', 'tts', 'device-mic'],
+      sttProvider: 'deepgram',
+      ttsProvider: 'local',
+    });
+
+    expect(identity.project).toMatchObject({
+      surface: 'vision',
+      surfaces: ['mobile', 'web', 'watch', 'tv', 'car', 'vision'],
+      stack: 'react-native-expo',
+      stacks: ['react-native-expo', 'nextjs', 'yaver-xml'],
+      testSurfaces: ['rn-hermes', 'browser', 'visionos-simulator'],
+      feedbackSdk: 'yaver-feedback-react-native',
+      feedbackTransport: 'device-sdk',
+      voiceCapabilities: ['stt', 'tts', 'device-mic'],
+      sttProvider: 'deepgram',
+      ttsProvider: 'local',
+    });
+    expect(identity.project?.projectPath).toBeUndefined();
+  });
+
+  it('omits the project block when nothing identifies the app', () => {
+    // Bare RN with no expo-constants and no native modules. The report must
+    // still upload — the agent just resolves it by its own means.
+    mockExpoModule.default = {};
+    const resolve = loadResolve();
+
+    const identity = resolve();
+    expect(identity.project).toBeUndefined();
+    expect(identity.appName).toBeUndefined();
+    expect(identity.app).toEqual({});
+  });
+});

package/src/__tests__/SDKToken.test.ts

@@ -34,7 +34,7 @@ describe('SDK Token Auth', () => {
       const bundle = {
         metadata: {
           timestamp: '2026-03-25T00:00:00Z',
-          device: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
+          deviceInfo: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
           app: {},
         },
         screenshots: [],

package/src/__tests__/ShakeToggle.test.ts

@@ -0,0 +1,153 @@
+// Runtime shake toggling + init() idempotency.
+//
+// Host apps put the feedback SDK behind a settings switch, which means init /
+// enable / disable run repeatedly in one process. Two things used to break
+// there:
+//
+//   1. There was no way to turn the shake catcher off short of
+//      setEnabled(false) (which also stops the flight recorder and the agent
+//      command channel) or a full re-init. `trigger` is only read inside
+//      init(). setShakeEnabled() fills that gap.
+//
+//   2. init() registered a BlackBox command handler and threw away the
+//      unsubscribe, so each re-init stacked another. Two inits meant two
+//      reloads per agent command; destroy() never cleared them either.
+
+import { YaverFeedback } from '../YaverFeedback';
+import { BlackBox } from '../BlackBox';
+
+const mockShakeStart = jest.fn();
+const mockShakeStop = jest.fn();
+
+jest.mock('../ShakeDetector', () => ({
+  ShakeDetector: jest.fn().mockImplementation(() => ({
+    start: mockShakeStart,
+    stop: mockShakeStop,
+  })),
+}));
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+  DeviceEventEmitter: { emit: jest.fn(), addListener: jest.fn() },
+  NativeModules: {},
+}));
+
+const mockFetch = jest.fn(() =>
+  Promise.resolve({ ok: true, json: () => Promise.resolve({}) }),
+);
+global.fetch = mockFetch as any;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  YaverFeedback.destroy();
+});
+
+afterEach(() => {
+  YaverFeedback.destroy();
+});
+
+describe('setShakeEnabled', () => {
+  it('arms the shake listener on init when trigger is shake', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('disarms the listener without disabling the SDK', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+
+    YaverFeedback.setShakeEnabled(false);
+
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+    expect(mockShakeStop).toHaveBeenCalled();
+    // The point of a separate toggle: the rest of the SDK stays up.
+    expect(YaverFeedback.isEnabled()).toBe(true);
+  });
+
+  it('re-arms the listener', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.setShakeEnabled(false);
+    YaverFeedback.setShakeEnabled(true);
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('is idempotent — repeated calls do not stack detectors', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    mockShakeStart.mockClear();
+
+    YaverFeedback.setShakeEnabled(true);
+    YaverFeedback.setShakeEnabled(true);
+
+    expect(mockShakeStart).not.toHaveBeenCalled();
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('persists onto config so a later enable does not resurrect the listener', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.setShakeEnabled(false);
+
+    YaverFeedback.setEnabled(false);
+    YaverFeedback.setEnabled(true);
+
+    // The user said no shake. Cycling the master switch must not undo that.
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+    expect(YaverFeedback.getConfig()?.disableShakeGesture).toBe(true);
+  });
+
+  it('does not arm the listener for a non-shake trigger', () => {
+    YaverFeedback.init({ trigger: 'manual', agentUrl: 'http://x:18080', authToken: 't' });
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+
+    YaverFeedback.setShakeEnabled(true);
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+  });
+
+  it('no-ops before init rather than throwing', () => {
+    expect(() => YaverFeedback.setShakeEnabled(true)).not.toThrow();
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+  });
+});
+
+describe('init() command-handler registration', () => {
+  it('does not stack command handlers across re-inits', () => {
+    const cfg = { trigger: 'shake' as const, agentUrl: 'http://x:18080', authToken: 't' };
+
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+
+    // Three inits, one live handler. Before the fix this array grew by one
+    // each time, so a single agent 'reload' fired three reloads.
+    expect((BlackBox as any).commandHandlers.length).toBe(1);
+  });
+
+  it('fires a reload exactly once per command after repeated inits', () => {
+    // The user-visible symptom the count above stands in for.
+    const onReload = jest.fn();
+    const cfg = { trigger: 'shake' as const, agentUrl: 'http://x:18080', authToken: 't', onReload };
+
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+
+    for (const h of (BlackBox as any).commandHandlers) h({ command: 'reload' });
+
+    expect(onReload).toHaveBeenCalledTimes(1);
+  });
+
+  it('destroy() unregisters the command handler', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    const before = (BlackBox as any).commandHandlers.length;
+    expect(before).toBeGreaterThan(0);
+
+    YaverFeedback.destroy();
+
+    expect((BlackBox as any).commandHandlers.length).toBe(before - 1);
+  });
+
+  it('destroy() then init() leaves exactly one handler', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.destroy();
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+
+    expect((BlackBox as any).commandHandlers.length).toBe(1);
+  });
+});

package/src/__tests__/YaverFeedback.test.ts

@@ -1,3 +1,4 @@
+import { DeviceEventEmitter } from 'react-native';
 import { YaverFeedback } from '../YaverFeedback';
 
 // Mock react-native: DeviceEventEmitter for event dispatch + Platform so
@@ -34,13 +35,10 @@ jest.mock('../auth', () => ({
         needsAuth: false,
         runnerDown: false,
         lastHeartbeat: Date.now(),
-        isGuest: false,
-        accessScope: 'owner',
         quicHost: '127.0.0.1',
         quicPort: 18080,
       },
     ],
-    shared: [],
   })),
   DEFAULT_CONVEX_SITE_URL: 'https://example.convex.site',
 }));
@@ -54,6 +52,20 @@ beforeEach(() => {
 });
 
 describe('YaverFeedback', () => {
+  describe('Dogfood onboarding', () => {
+    it('starts with Yaver OAuth when the host has no session', () => {
+      YaverFeedback.init({ enabled: true });
+      YaverFeedback.beginDogfoodOnboarding({ appId: 'io.example.app', label: 'Example' });
+      expect(DeviceEventEmitter.emit).toHaveBeenCalledWith('yaverFeedback:startLogin');
+    });
+
+    it('asks for a machine after an existing OAuth session', () => {
+      YaverFeedback.init({ enabled: true, authToken: 'owner-token' });
+      YaverFeedback.beginDogfoodOnboarding({ appId: 'io.example.app', label: 'Example' });
+      expect(DeviceEventEmitter.emit).toHaveBeenCalledWith('yaverFeedback:startMachinePicker');
+    });
+  });
+
   describe('init()', () => {
     it('sets config correctly with defaults', () => {
       YaverFeedback.init({

package/src/__tests__/deviceDogfood.test.ts

@@ -0,0 +1,77 @@
+import nacl from 'tweetnacl';
+import { Buffer } from 'buffer';
+import { webcrypto } from 'crypto';
+import { YaverDeviceDogfood } from '../deviceDogfood';
+
+class MemorySecureStore {
+  values = new Map<string, string>();
+  async getItemAsync(key: string) { return this.values.get(key) ?? null; }
+  async setItemAsync(key: string, value: string) { this.values.set(key, value); }
+  async deleteItemAsync(key: string) { this.values.delete(key); }
+}
+
+function response(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+}
+
+describe('YaverDeviceDogfood', () => {
+  beforeAll(() => {
+    if (!(globalThis as any).crypto) (globalThis as any).crypto = webcrypto;
+  });
+
+  afterEach(() => { jest.restoreAllMocks(); });
+
+  test('keeps identity stable and proves possession rather than trusting the UUID', async () => {
+    const store = new MemorySecureStore();
+    const client = new YaverDeviceDogfood({ appId: 'io.example.test', secureStore: store, backendUrl: 'https://dogfood.test' });
+    const first = await client.enrollmentInfo();
+    const second = await client.enrollmentInfo();
+    expect(second).toEqual(first);
+
+    let proof: any;
+    jest.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+      const url = String(input);
+      if (url.endsWith('/dogfood/enroll/start')) return response({ status: 'pending', challenge: 'server-nonce' });
+      if (url.endsWith('/dogfood/enroll/prove')) { proof = JSON.parse(String(init?.body)); return response({ status: 'pending', proofVerified: true }); }
+      throw new Error(`unexpected URL ${url}`);
+    });
+    await client.enroll('ios');
+    const message = new TextEncoder().encode(`yaver-dogfood-enroll-v1\nio.example.test\n${first.installationId}\nserver-nonce`);
+    expect(nacl.sign.detached.verify(message, new Uint8Array(Buffer.from(proof.signature, 'base64')), new Uint8Array(Buffer.from(first.publicKey, 'base64')))).toBe(true);
+
+    const attacker = nacl.sign.keyPair();
+    expect(nacl.sign.detached.verify(message, new Uint8Array(Buffer.from(proof.signature, 'base64')), attacker.publicKey)).toBe(false);
+  });
+
+  test('re-register rotates key and installation while preserving only the logical slot', async () => {
+    const store = new MemorySecureStore();
+    const client = new YaverDeviceDogfood({ appId: 'io.example.test', secureStore: store, backendUrl: 'https://dogfood.test' });
+    const before = await client.enrollmentInfo();
+    jest.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+      if (String(input).endsWith('/dogfood/enroll/start')) return response({ status: 'pending', challenge: 'rotate-nonce' });
+      return response({ status: 'pending', proofVerified: true });
+    });
+    await client.reRegister('ios');
+    const after = await client.enrollmentInfo();
+    expect(after.registrationSlot).toBe(before.registrationSlot);
+    expect(after.installationId).not.toBe(before.installationId);
+    expect(after.publicKey).not.toBe(before.publicKey);
+  });
+
+  test('exchanges an approved key proof for a short-lived scoped session', async () => {
+    const client = new YaverDeviceDogfood({ appId: 'io.example.test', secureStore: new MemorySecureStore(), backendUrl: 'https://dogfood.test' });
+    const identity = await client.enrollmentInfo();
+    let sessionProof: any;
+    jest.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+      const url = String(input);
+      if (url.includes('/dogfood/enroll/status')) return response({ status: 'active' });
+      if (url.endsWith('/dogfood/session/challenge')) return response({ challenge: 'session-nonce' });
+      if (url.endsWith('/dogfood/session')) { sessionProof = JSON.parse(String(init?.body)); return response({ token: 'short-token', expiresAt: 123, scopes: ['feedback', 'blackbox'], projectSlug: 'example' }); }
+      throw new Error(`unexpected URL ${url}`);
+    });
+    const session = await client.session();
+    expect(session).toMatchObject({ active: true, token: 'short-token', scopes: ['feedback', 'blackbox'] });
+    const message = new TextEncoder().encode(`yaver-dogfood-session-v1\nio.example.test\n${identity.installationId}\nsession-nonce`);
+    expect(nacl.sign.detached.verify(message, new Uint8Array(Buffer.from(sessionProof.signature, 'base64')), new Uint8Array(Buffer.from(identity.publicKey, 'base64')))).toBe(true);
+  });
+});

package/src/__tests__/dogfoodPolicy.test.ts

@@ -0,0 +1,34 @@
+import { resolveSDKDogfood } from '../dogfoodPolicy';
+
+describe('resolveSDKDogfood', () => {
+  it('fails closed unless Dogfood is explicitly enabled', () => {
+    expect(resolveSDKDogfood({ accountIds: ['acct-1'], currentAccountId: 'acct-1' })).toMatchObject({
+      active: false,
+      code: 'SDK_DOGFOOD_DISABLED',
+    });
+  });
+
+  it('requires an exact approved app-account ID', () => {
+    expect(resolveSDKDogfood({ enabled: true, accountIds: ['acct-1'], currentAccountId: '' }).code)
+      .toBe('SDK_DOGFOOD_ACCOUNT_REQUIRED');
+    expect(resolveSDKDogfood({ enabled: true, accountIds: ['acct-1'], currentAccountId: 'acct-10' }).code)
+      .toBe('SDK_DOGFOOD_ACCOUNT_NOT_ALLOWED');
+    expect(resolveSDKDogfood({ enabled: true, accountIds: ['acct-1'], currentAccountId: 'acct-1' })).toMatchObject({
+      active: true,
+      code: 'SDK_DOGFOOD_ACTIVE',
+      accountId: 'acct-1',
+    });
+  });
+
+  it('supports a key-enrolled installation without an app account', () => {
+    expect(resolveSDKDogfood({ enabled: true, appId: 'io.example', installationStatus: 'active' }).code)
+      .toBe('SDK_DOGFOOD_INSTALLATION_REQUIRED');
+    expect(resolveSDKDogfood({ enabled: true, appId: 'io.example', installationId: 'install-1', installationStatus: 'pending' }).code)
+      .toBe('SDK_DOGFOOD_INSTALLATION_NOT_ACTIVE');
+    expect(resolveSDKDogfood({ enabled: true, appId: 'io.example', installationId: 'install-1', installationStatus: 'active' })).toMatchObject({
+      active: true,
+      code: 'SDK_DOGFOOD_ACTIVE',
+      accountId: 'install-1',
+    });
+  });
+});

package/src/__tests__/pickTargetDevice.test.ts

@@ -0,0 +1,101 @@
+// Target-device selection contract.
+//
+// This exists because pickTargetDevice used to silently reroute: when the
+// user's `preferredDeviceId` was absent from the list — or present but
+// carrying an empty `quicHost` — the preference block fell through to the
+// generic "first fresh machine" search. The user picked their Mac mini and
+// the fix landed on their laptop, with no error on either end.
+//
+// The contract now: an explicit preference is honoured by id alone, or the
+// pick fails. Not connecting is a better failure than connecting to the
+// wrong host.
+
+import { pickTargetDevice, isDeviceFresh } from '../_core/device';
+import { HEARTBEAT_STALE_MS } from '../_core/constants';
+import type { CoreDevice } from '../_core/device';
+
+const NOW = 1_700_000_000_000;
+
+function device(over: Partial<CoreDevice> & { deviceId: string }): CoreDevice {
+  return {
+    name: over.deviceId,
+    platform: 'darwin',
+    isOnline: true,
+    lastHeartbeat: NOW,
+    quicHost: '100.64.0.1',
+    quicPort: 18080,
+    ...over,
+  } as CoreDevice;
+}
+
+beforeEach(() => {
+  jest.spyOn(Date, 'now').mockReturnValue(NOW);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe('pickTargetDevice — explicit preference', () => {
+  it('returns the preferred device when it is fresh', () => {
+    const macmini = device({ deviceId: 'macmini' });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns the preferred device even when it is STALE, rather than rerouting', () => {
+    const macmini = device({
+      deviceId: 'macmini',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(isDeviceFresh(macmini)).toBe(false);
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns the preferred device even with NO quicHost — relay addresses it by id', () => {
+    // This is the off-LAN shape: no LAN address is published, and the relay
+    // route is `<relay>/d/<deviceId>`. An empty quicHost is not a reason to
+    // reroute; it is the normal remote case.
+    const macmini = device({ deviceId: 'macmini', quicHost: '' });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns null when the preferred id is absent — never falls through to another machine', () => {
+    const laptop = device({ deviceId: 'laptop' });
+    const desktop = device({ deviceId: 'desktop' });
+    expect(pickTargetDevice([laptop, desktop], 'macmini')).toBeNull();
+  });
+
+  it('returns null for an unknown preference even when exactly one healthy machine exists', () => {
+    // The tempting "well, there's only one, just use it" case. Still wrong:
+    // the user asked for a specific host.
+    expect(pickTargetDevice([device({ deviceId: 'laptop' })], 'macmini')).toBeNull();
+  });
+});
+
+describe('pickTargetDevice — no preference', () => {
+  it('prefers a fresh device with a quicHost over a stale one', () => {
+    const stale = device({
+      deviceId: 'stale',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    const fresh = device({ deviceId: 'fresh' });
+    expect(pickTargetDevice([stale, fresh])).toBe(fresh);
+  });
+
+  it('falls back to an online device with a quicHost when none are fresh', () => {
+    const offline = device({ deviceId: 'offline', isOnline: false });
+    const online = device({
+      deviceId: 'online',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    expect(pickTargetDevice([offline, online])).toBe(online);
+  });
+
+  it('returns null for an empty list', () => {
+    expect(pickTargetDevice([], 'macmini')).toBeNull();
+    expect(pickTargetDevice([])).toBeNull();
+  });
+});