fix: scope Vega support to VVD

Author: thymikee

CONTEXT.md

@@ -113,6 +113,11 @@ The perfect-shape refactor is complete and merged. Its end-state:
   `src/platforms/apple/os/<os>/`. The public wire stays non-breaking: `PUBLIC_PLATFORMS`
   (`src/kernel/device.ts`) still emits `ios`/`macos` leaf output. See
   [ADR 0009](docs/adr/0009-apple-platform-consolidation.md).
+- Vega platform model. Initial Vega OS support is deliberately **VVD-only**: discovery returns
+  `VirtualDevice`, and platform capability admission rejects physical Fire TV devices until durable
+  hardware evidence validates discovery, lifecycle, and the complete remote-control contract.
+  Vega capture, selector, inventory, install, logging, and performance backends remain separate
+  follow-up surfaces.
 - Folder DAG + layering lint. `scripts/layering/check.ts` enforces two different scopes in CI.
   GLOBALLY, across every production source file, it enforces the R1-R3 move rules
   (kernel-sink, commands-floor, platforms-seam) and rejects all production static value-import

README.md

@@ -15,7 +15,7 @@
 
 Let your coding agent verify its changes in the running app.
 
-`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, tvOS, Android TV, Amazon Vega OS TV, web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. Vega OS support currently covers discovery, app lifecycle, and complete TV-remote control; its capture and selector backends are still unsupported.
+`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported.
 
 Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked.
 
@@ -109,7 +109,7 @@ See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the com
 
 ## How it works
 
-`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, Vega CLI/VDA on Amazon Vega OS, a local helper on macOS, and AT-SPI on Linux.
+`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.
 
 Node.js apps can use the typed client or public subpaths. `agent-device/android-adb` provides the Android ADB provider interface, helpers for logcat, the clipboard, the keyboard, and apps, and port reverse management.
 

skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates Apple-platform apps (iOS, tvOS, macOS), Android devices, and Amazon Vega OS TVs. Use when navigating apps, taking snapshots/screenshots where supported, driving TV remotes, tapping, typing, scrolling, extracting UI info, collecting evidence, or planning agent-device CLI commands.
+description: Automates Apple-platform apps (iOS, tvOS, macOS), Android devices, and Amazon Vega OS TV apps in Vega Virtual Devices. Use when navigating apps, taking snapshots/screenshots where supported, driving TV remotes, tapping, typing, scrolling, extracting UI info, collecting evidence, or planning agent-device CLI commands.
 ---
 
 # agent-device

src/cli/parser/__tests__/cli-help-topics.test.ts

@@ -156,7 +156,7 @@ test('usage includes agent workflows, config, environment, and examples footers'
   );
   assert.match(
     usageText,
-    /agent-device help tv\s+Use when navigating Android TV, tvOS, or Vega OS focus-first surfaces/,
+    /agent-device help tv\s+Use when navigating Android TV, tvOS, or Vega VVD focus-first surfaces/,
   );
   assert.match(
     usageText,
@@ -335,7 +335,8 @@ test('usageForCommand resolves tv help topic', async () => {
   assert.match(help, /agent-device devices --platform vega --target tv/);
   assert.match(help, /Vega OS uses the exact hold duration through inputd-cli/);
   assert.match(help, /Use --platform vega --target tv/);
-  assert.match(help, /Remote-button control requires Developer Mode/);
+  assert.match(help, /Initial Vega OS support is VVD-only/);
+  assert.match(help, /Physical Fire TV.*report unsupported/);
 });
 
 test('usageForCommand resolves web help topic', async () => {

src/cli/parser/cli-help.ts

@@ -39,7 +39,7 @@ const AGENT_WORKFLOWS = [
   },
   {
     label: 'agent-device help tv',
-    description: 'Use when navigating Android TV, tvOS, or Vega OS focus-first surfaces',
+    description: 'Use when navigating Android TV, tvOS, or Vega VVD focus-first surfaces',
   },
   {
     label: 'agent-device help react-native',
@@ -426,17 +426,17 @@ Escalate:
   help dogfood         exploratory QA report workflow
   help validate        engineering self-validation loops
   help debugging       logs, network, alerts, traces, flaky runtime failures
-  help tv              Android TV, tvOS, and Vega OS focus-first remote navigation
+  help tv              Android TV, tvOS, and Vega VVD focus-first remote navigation
   help react-devtools  React Native performance, profiling, props/state/hooks, slow renders, rerenders
   help react-native   React Native app automation hazards, overlays, Metro/Re.Pack, and routing
   help remote          remote/cloud config, tenant, lease, local service tunnels
   help macos           desktop, frontmost-app, menu bar surfaces`,
   },
   tv: {
-    summary: 'Android TV, tvOS, and Vega OS focus-first remote navigation',
+    summary: 'Android TV, tvOS, and Vega VVD focus-first remote navigation',
     body: `agent-device help tv
 
-Use this when the target is Android TV, Apple TV/tvOS, or Amazon Fire TV on Vega OS. TV surfaces are focus-first: move focus with remote/D-pad buttons, then activate the focused control.
+Use this when the target is Android TV, Apple TV/tvOS, or an Amazon Vega OS TV app running in the Vega Virtual Device (VVD). TV surfaces are focus-first: move focus with remote/D-pad buttons, then activate the focused control.
 
 Core loop:
   agent-device open Settings --platform android --target tv --session tv
@@ -462,7 +462,7 @@ Buttons:
   ok, center, and enter are input aliases for select; command output still reports button: "select".
   longpress is CLI sugar for --duration-ms 500. --duration-ms overrides that preset.
   --duration-ms holds a tvOS or Vega OS remote button for that exact duration. On Android TV, any positive duration maps to the ADB longpress form because Android input keyevent has no exact hold duration.
-  Vega OS uses the exact hold duration through inputd-cli on a developer-mode device.
+  Vega OS uses the exact hold duration through inputd-cli in the VVD.
 
 Android TV:
   Android TV uses ADB keyevents behind agent-device tv-remote. Keep command plans on agent-device; do not switch to raw adb keyevent.
@@ -475,17 +475,16 @@ tvOS:
 
 Vega OS:
   Vega OS is driven through the SDK-matched Vega CLI and VDA, not ADB.
-  Use --platform vega --target tv for a Vega Virtual Device or physical Vega Fire TV.
+  Initial Vega OS support is VVD-only. Use --platform vega --target tv for a running Vega Virtual Device.
   Use a component ID from the app package or Vega SDK tooling; agent-device app inventory is not yet supported.
-  Use --serial when more than one Vega VVD or physical TV is connected.
+  Use --serial VirtualDevice for explicit VVD selection.
   Start and stop the local emulator with vega virtual-device start|stop; agent-device does not boot the VVD implicitly.
-  Remote-button control requires Developer Mode on the selected device.
-  Initial support covers discovery, app open/close, back, home, and tv-remote. App inventory, snapshot, screenshot, selectors, install, touch/text/gesture, logs, and performance commands report unsupported until their Vega backends are implemented.
+  Initial support covers VVD discovery, app open/close, back, home, and tv-remote. Physical Fire TV, app inventory, snapshot, screenshot, selectors, install, touch/text/gesture, logs, and performance commands report unsupported until their Vega backends are validated and implemented.
 
 Focus and visual truth:
   On Android TV and tvOS, if snapshot -i exposes a focused node, verify it with is focused <selector>.
   Use wait focused=true only when repeated snapshots preserve focus metadata for the app.
-  If the app exposes only a surface view, or focus metadata is transient, use screenshot --overlay-refs, screenshot, or diff snapshot as visual truth and keep moving focus with tv-remote. On Vega OS, use the VVD or physical display as visual truth until capture support lands.
+  If the app exposes only a surface view, or focus metadata is transient, use screenshot --overlay-refs, screenshot, or diff snapshot as visual truth and keep moving focus with tv-remote. On Vega OS, use the VVD display as visual truth until capture support lands.
   Do not assume press/click @ref works on Android TV, tvOS, or Vega OS until the desired element is focused.`,
   },
   debugging: {

src/commands/cli-grammar/flag-definitions-target.ts

@@ -39,7 +39,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--serial'],
     type: 'string',
     usageLabel: '--serial <serial>',
-    usageDescription: 'Android or Vega device serial',
+    usageDescription: 'Android device or Vega VVD serial',
   },
   {
     key: 'surface',

src/commands/command-input.ts

@@ -585,7 +585,7 @@ function commonProperties(): Record<string, JsonSchema> {
     },
     device: { type: 'string', description: 'Device name selector.' },
     udid: { type: 'string', description: 'iOS device UDID selector.' },
-    serial: { type: 'string', description: 'Android or Vega device serial selector.' },
+    serial: { type: 'string', description: 'Android device or Vega VVD serial selector.' },
     iosSimulatorDeviceSet: {
       type: 'string',
       description: 'iOS simulator device-set path used for device resolution.',

src/contracts/device-inventory.test.ts

@@ -19,24 +19,16 @@ test('inventory counts Vega as its own platform family', () => {
   const devices: DeviceInfo[] = [
     {
       platform: 'vega',
-      id: 'vega-emulator',
-      name: 'Vega TV Emulator',
+      id: 'VirtualDevice',
+      name: 'Vega Virtual Device',
       kind: 'emulator',
       target: 'tv',
       booted: true,
     },
-    {
-      platform: 'vega',
-      id: 'vega-device',
-      name: 'Vega TV',
-      kind: 'device',
-      target: 'tv',
-      booted: false,
-    },
   ];
 
   const counts = countDeviceInventoryByGroup(devices);
 
-  assert.deepEqual(counts.vega, { available: 2, booted: 1 });
+  assert.deepEqual(counts.vega, { available: 1, booted: 1 });
   assert.deepEqual(counts.android, { available: 0, booted: 0 });
 });

src/core/__tests__/capability-plugin-routing-parity.test.ts

@@ -165,7 +165,7 @@ const CAPABILITY_BUCKET_BY_PLATFORM: Record<Platform, keyof CommandCapability> =
   linux: 'linux',
   web: 'web',
 };
-const VEGA_TV_ONLY_COMMANDS_REF = new Set(['open', 'close', 'back', 'home', 'tv-remote']);
+const VEGA_VVD_ONLY_COMMANDS_REF = new Set(['open', 'close', 'back', 'home', 'tv-remote']);
 
 // Independent reference for `isCommandSupportedOnDevice` over NON-WEB platforms,
 // reproducing the BEFORE pipeline exactly: hardcoded bucket selection (b.1 oracle)
@@ -178,8 +178,8 @@ function isSupportedReference(command: string, device: DeviceInfo): boolean {
   const byPlatform = capability[CAPABILITY_BUCKET_BY_PLATFORM[device.platform]];
   if (!byPlatform) return false;
   const supports =
-    device.platform === 'vega' && VEGA_TV_ONLY_COMMANDS_REF.has(command)
-      ? (candidate: DeviceInfo) => candidate.target === 'tv'
+    device.platform === 'vega' && VEGA_VVD_ONLY_COMMANDS_REF.has(command)
+      ? (candidate: DeviceInfo) => candidate.kind === 'emulator' && candidate.target === 'tv'
       : SUPPORTS_REF[command];
   if (supports && !supports(device)) return false;
   const kind = (device.kind ?? 'unknown') as keyof NonNullable<CommandCapability['apple']>;
@@ -219,10 +219,10 @@ test('(b.2) unsupportedHint closures are verbatim across the full device matrix'
     const reference = HINT_REF[command];
     for (const device of SAMPLE_DEVICES) {
       const expected =
-        device.platform === 'vega' && VEGA_TV_ONLY_COMMANDS_REF.has(command)
-          ? device.target === 'tv'
+        device.platform === 'vega' && VEGA_VVD_ONLY_COMMANDS_REF.has(command)
+          ? device.kind === 'emulator' && device.target === 'tv'
             ? undefined
-            : `${command} is supported only on Vega TV targets.`
+            : `${command} currently supports only Vega Virtual Devices.`
           : reference?.(device);
       assert.equal(
         unsupportedHintForDevice(command, device),

src/core/command-descriptor/registry.ts

@@ -162,7 +162,7 @@ function readOnlySubactionRecordingEffect(
 
 const APPLE_SIM_AND_DEVICE = { simulator: true, device: true };
 const ANDROID_ALL = { emulator: true, device: true, unknown: true };
-const VEGA_ALL = { emulator: true, device: true };
+const VEGA_VVD = { emulator: true };
 const LINUX_DEVICE = { device: true };
 const LINUX_NONE = {};
 
@@ -174,7 +174,7 @@ const ALL_DEVICE_COMMAND_CAPABILITY = {
 const APP_RUNTIME_CAPABILITY = ALL_DEVICE_COMMAND_CAPABILITY;
 const VEGA_APP_RUNTIME_CAPABILITY = {
   ...APP_RUNTIME_CAPABILITY,
-  vega: VEGA_ALL,
+  vega: VEGA_VVD,
 } satisfies CommandCapability;
 const APP_INVENTORY_CAPABILITY = {
   apple: APPLE_SIM_AND_DEVICE,
@@ -993,7 +993,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
     ...GENERIC_MUTATING_LINUX_DEVICE_COMMAND_TRAITS,
     capability: {
       ...GENERIC_MUTATING_LINUX_DEVICE_COMMAND_TRAITS.capability,
-      vega: VEGA_ALL,
+      vega: VEGA_VVD,
     },
   },
   {
@@ -1018,7 +1018,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
     ...GENERIC_MUTATING_LINUX_DEVICE_COMMAND_TRAITS,
     capability: {
       ...GENERIC_MUTATING_LINUX_DEVICE_COMMAND_TRAITS.capability,
-      vega: VEGA_ALL,
+      vega: VEGA_VVD,
     },
   },
   {
@@ -1036,7 +1036,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
     capability: {
       apple: APPLE_SIM_AND_DEVICE,
       android: ANDROID_ALL,
-      vega: VEGA_ALL,
+      vega: VEGA_VVD,
       linux: LINUX_NONE,
     },
     timeoutPolicy: DEFAULT_TIMEOUT_POLICY,