refactor(contracts): drop the Limrun iOS denials its facts already make (#2815)

* refactor(contracts): make the springboard buttons optional members and drop the Limrun denials

ADR 0019 keeps a stub that throws `unsupported` out of an interactor: an owner with no
control says so with its facts, and the facts are what the binding consults. `home` and
`appSwitcher` reached the Limrun iOS direct session's interactor only through
`bindSystemButton`, which the catalog calls for exactly the buttons a binding's facts
admitted — and `limrunSystemButtonOperationFacts` refuses both cells on that leg
(`homeUnavailableIos`/`appSwitcherUnavailableIos`, or `liveSessionUnavailable` when no
session is live). The interactor denials were therefore unreachable code pretending to be
an implementation, and the fact hints already carried the identical wording.

Both members become optional, following #2715's `actionButton` shape: the system-button
binder already fails closed through `requireInteractorMethod`, so a fact that admits a
button its interactor cannot serve names the missing button instead of answering a silent
no-op. Apple, Android, HarmonyOS and the Vega TV leg keep their real mechanics.

* refactor(contracts): make the clipboard halves optional members and drop the Limrun denials

The Limrun iOS direct session's clipboard legs were unreachable code pretending to be an
implementation. `bindClipboardRead`/`bindClipboardWrite` are reached only through the
catalog, which binds a half exactly when the owner's fact admits it, and
`limrunClipboardOperationFacts` refuses both halves on that leg
(`clipboardUnavailableIos`, or `liveSessionUnavailable` with no live session). The
Android leg stays honest: it rides the same `createAndroidInteractor` the local family
binds, and its cells stay available.

Both members become optional and the binders now fail closed through
`requireInteractorMethod`, naming the half with the labels `CLIPBOARD_LEG_LABELS`
introduces and the catalog adopts — a fact that admits a half its interactor cannot
serve reports the missing method instead of resolving an absent member as a TypeError.
Apple, Android, Linux and the WebDriver clipboard extension keep their real mechanics.

* refactor(contracts): make the TV remote an optional member and drop the Limrun denial

The Limrun iOS direct session's remote leg was unreachable code pretending to be an
implementation. `bindTvRemote` is reached only through the catalog, which binds the press
exactly when the owner's fact admits it, and `limrunNavigationOperationFacts` refuses the
cell on that leg (`tvRemoteUnavailableIos`, or `liveSessionUnavailable` with no live
session) — a phone/tablet direct session has no remote receiver. The Android leg stays
honest: its cells gate on `device.target === 'tv'` and ride the real Android interactor.

The member becomes optional and the binder now fails closed through
`requireInteractorMethod`, naming the press with the label the catalog already used — a
fact that admits a press its interactor cannot serve reports the missing method instead
of resolving an absent member as a TypeError. Apple tvOS, the Android TV leaf, and Vega
keep their real mechanics.

* refactor(provider-limrun): drop the Limrun iOS gesture denial the facts already make

The iOS direct session refused every gesture tier through
`limrunGestureFacts` (`iosGestureUnavailable` on live sessions, the liveness cell
otherwise), and `bindGestureOperations` binds a tier only when its cell is available —
so the interactor's throwing `performGesture` could never run. The member is already
optional on `Interactor`, and the binder already escalates an advertised tier with no
executor to `invalidRuntimeContract` rather than a refusal (ADR 0019 §2), a path pinned
by `gesture-runtime.test.ts`. What remained was unreachable code pretending to be an
implementation; the fact cell is now the single source of the agent-facing wording.

* test(interactors): narrow the optional members at pinned implementation call sites

The Vega, Apple-runner-provider, and core interactor tests drive interactors that really
do carry home/appSwitcher/tvRemote/readClipboard/writeClipboard, but the factory hands
them an Interactor, and those members are optional now. Same `!` narrowing #2715 and
#2807 applied at their own pinned call sites: the assertion still runs the real method,
and an owner that ever stopped carrying it would fail in the factory's own test rather
than silently skipping the press.

Author: thymikee

packages/contracts/src/clipboard-runtime.test.ts

@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import {
   bindClipboardRead,
   bindClipboardWrite,
@@ -96,3 +97,31 @@ test('a local write binding hands the interactor the already-joined text', async
 
   expect(writeClipboard).toHaveBeenCalledWith('hello world');
 });
+
+// Facts admitted the half, so an interactor without it is an ownership bug the caller must see
+// rather than a refusal to degrade around. The label is the one the command already used.
+test('a clipboard half whose fact admitted but whose interactor cannot serve it fails closed', async () => {
+  const served = { readClipboard: vi.fn(async () => 'copied text') } as unknown as Interactor;
+  const signal = new AbortController().signal;
+  const missingWrite = local(async () => ({ ...served, writeClipboard: undefined }));
+  const missingRead = local(
+    async () => ({ writeClipboard: vi.fn(async () => undefined) }) as unknown as Interactor,
+  );
+
+  await expect(
+    bindClipboardWrite(signal, missingWrite).writeClipboard({ text: 'hello' }),
+  ).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('clipboard write'),
+  );
+  await expect(bindClipboardRead(signal, missingRead).readClipboard({})).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('clipboard read'),
+  );
+});

packages/contracts/src/clipboard-runtime.ts

@@ -69,6 +69,12 @@ export function clipboardRuntimeOperationFacts(
   });
 }
 
+/** How a fail-closed refusal names each clipboard half to the caller. */
+export const CLIPBOARD_LEG_LABELS = {
+  readClipboard: 'clipboard read',
+  writeClipboard: 'clipboard write',
+} as const;
+
 /**
  * Captures one selected owner's interactor authority for the lifetime of a request binding. The
  * owner is already chosen by the time a binder is called, so each entry point supplies its own
@@ -87,14 +93,28 @@ async function resolveClipboardInteractor(
   });
 }
 
+/**
+ * Resolves one clipboard half's member through the shared optional-member guard. Loaded on the
+ * call rather than at module evaluation because this facade's eager closure is held at its
+ * merge-base size (`eager-closure-budgets`); a static edge would grow it.
+ */
+async function requireClipboardMethod<Leg extends keyof typeof CLIPBOARD_LEG_LABELS>(
+  interactor: Interactor,
+  leg: Leg,
+): Promise<NonNullable<Interactor[Leg]>> {
+  const { requireInteractorMethod } = await import('./interactor-operation-binding.ts');
+  return requireInteractorMethod(interactor[leg], CLIPBOARD_LEG_LABELS[leg]);
+}
+
 export function bindClipboardRead(
   signal: AbortSignal,
   resolveInteractor: (runner: RunnerContext) => Promise<Interactor>,
 ): ClipboardReadRuntimeOperations {
   return Object.freeze({
     readClipboard: async (input: ClipboardReadInput) => {
       const interactor = await resolveClipboardInteractor(signal, resolveInteractor, input);
-      return await interactor.readClipboard();
+      const readClipboard = await requireClipboardMethod(interactor, 'readClipboard');
+      return await readClipboard.call(interactor);
     },
   });
 }
@@ -106,7 +126,8 @@ export function bindClipboardWrite(
   return Object.freeze({
     writeClipboard: async (input: ClipboardWriteInput) => {
       const interactor = await resolveClipboardInteractor(signal, resolveInteractor, input);
-      await interactor.writeClipboard(input.text);
+      const writeClipboard = await requireClipboardMethod(interactor, 'writeClipboard');
+      await writeClipboard.call(interactor, input.text);
     },
   });
 }

packages/contracts/src/interactor-operation-catalog.ts

@@ -2,11 +2,15 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
 import { ALERT_LEG_LABELS, bindAlertLeg } from './alert-runtime.ts';
 import { bindAppEvent } from './app-event-runtime.ts';
 import { bindBack } from './back-runtime.ts';
-import { bindClipboardRead, bindClipboardWrite } from './clipboard-runtime.ts';
+import {
+  CLIPBOARD_LEG_LABELS,
+  bindClipboardRead,
+  bindClipboardWrite,
+} from './clipboard-runtime.ts';
 import { KEYBOARD_ACTION_LABELS, bindKeyboardAction } from './keyboard-runtime.ts';
 import { bindOrientation } from './orientation-runtime.ts';
 import { bindReadSetting, bindSetSetting } from './settings-runtime.ts';
-import { bindTvRemote } from './tv-remote-runtime.ts';
+import { TV_REMOTE_LABEL, bindTvRemote } from './tv-remote-runtime.ts';
 import {
   localInteractorSource,
   providerInteractorSource,
@@ -58,7 +62,7 @@ export const INTERACTOR_OPERATIONS = [
     bind: (signal, resolve) => bindSystemButton('home', signal, resolve),
   },
   { operation: 'setOrientation', label: 'orientation', bind: bindOrientation },
-  { operation: 'tvRemote', label: 'tv-remote', bind: bindTvRemote },
+  { operation: 'tvRemote', label: TV_REMOTE_LABEL, bind: bindTvRemote },
   {
     operation: 'keyboardStatus',
     label: KEYBOARD_ACTION_LABELS.keyboardStatus,
@@ -74,8 +78,16 @@ export const INTERACTOR_OPERATIONS = [
     label: KEYBOARD_ACTION_LABELS.keyboardEnter,
     bind: (signal, resolve) => bindKeyboardAction('keyboardEnter', signal, resolve),
   },
-  { operation: 'readClipboard', label: 'clipboard read', bind: bindClipboardRead },
-  { operation: 'writeClipboard', label: 'clipboard write', bind: bindClipboardWrite },
+  {
+    operation: 'readClipboard',
+    label: CLIPBOARD_LEG_LABELS.readClipboard,
+    bind: bindClipboardRead,
+  },
+  {
+    operation: 'writeClipboard',
+    label: CLIPBOARD_LEG_LABELS.writeClipboard,
+    bind: bindClipboardWrite,
+  },
   {
     operation: 'appSwitcher',
     label: SYSTEM_BUTTON_LABELS.appSwitcher,

packages/contracts/src/interactor-types.ts

@@ -356,11 +356,29 @@ export type Interactor = {
   }>;
   gestureViewport?(): Promise<Rect>;
   back(mode?: BackMode): Promise<void>;
-  home(): Promise<void>;
+  /**
+   * Optional (parity with `actionButton`): opens the springboard, a control not every owner
+   * carries. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the system-button binder fails closed rather than resolving an absent member as a
+   * successful no-op.
+   */
+  home?(): Promise<void>;
   setOrientation(orientation: DeviceRotation): Promise<{ orientation?: DeviceRotation } | void>;
   performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
-  appSwitcher(): Promise<void>;
-  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
+  /**
+   * Optional (parity with `home`): opens the recents surface, a control not every owner carries.
+   * An owner without it leaves it undefined; its fact refuses the press before binding, and the
+   * system-button binder fails closed rather than resolving an absent member as a successful
+   * no-op.
+   */
+  appSwitcher?(): Promise<void>;
+  /**
+   * Optional (parity with `home`): presses one TV remote key, a control only TV-capable owners
+   * carry. An owner without it leaves it undefined; its fact refuses the press before binding,
+   * and the TV remote binder fails closed rather than resolving an absent member as a silent
+   * no-op.
+   */
+  tvRemote?(button: TvRemoteButton, durationMs?: number): Promise<void>;
   /**
    * Optional (parity with `keyboardDismiss`): presses the iPhone/iPad Action Button, hardware only
    * the Apple owner carries. An owner without the button leaves it undefined; its fact refuses the
@@ -374,8 +392,17 @@ export type Interactor = {
   keyboardDismiss?(): Promise<KeyboardDismissResult>;
   /** Optional: platforms with no keyboard-return concept leave it undefined. */
   keyboardEnter?(): Promise<KeyboardEnterResult>;
-  readClipboard(): Promise<string>;
-  writeClipboard(text: string): Promise<void>;
+  /**
+   * Optional (parity with `readSetting`): the owner's pasteboard read. An owner with no clipboard
+   * surface leaves both halves undefined; its fact refuses the half before binding, and the
+   * clipboard binder fails closed rather than resolving an absent member as an empty answer.
+   */
+  readClipboard?(): Promise<string>;
+  /**
+   * Optional (parity with `readClipboard`): the owner's pasteboard write, with the same
+   * fact-then-guard contract as the read.
+   */
+  writeClipboard?(text: string): Promise<void>;
   setSetting(
     setting: string,
     state: string,

packages/contracts/src/tv-remote-runtime.test.ts

@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
 import { bindTvRemote, tvRemoteRuntimeOperationFacts } from './tv-remote-runtime.ts';
 import type { Interactor } from './interactor-types.ts';
 import { localInteractorSource } from './interactor-operation-binding.ts';
@@ -39,3 +40,21 @@ test('a local binding drives the interactor with the button and duration', async
   // durationMs is the one transposition a point-shaped assertion would not catch.
   expect(tvRemote).toHaveBeenCalledWith('down', 250);
 });
+
+// Facts admitted the press, so an interactor without the member is an ownership bug the caller
+// must see rather than a refusal to degrade around. The label is the one the command used.
+test('a press whose fact admitted but whose interactor cannot serve it fails closed', async () => {
+  const resolveInteractor = vi.fn(async () => ({}) as unknown as Interactor);
+
+  const operations = bindTvRemote(
+    new AbortController().signal,
+    localInteractorSource({ device, resolveInteractor }),
+  );
+  await expect(operations.tvRemote({ button: 'up' })).rejects.toSatisfy(
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.details?.['reason'] === 'interactor-method-missing' &&
+      error.message.includes('tv-remote'),
+  );
+});

packages/contracts/src/tv-remote-runtime.ts

@@ -35,6 +35,9 @@ export function tvRemoteRuntimeOperationFacts(
   return Object.freeze({ tvRemote: input.tvRemote });
 }
 
+/** How a fail-closed refusal names the TV remote to the caller, matching the command. */
+export const TV_REMOTE_LABEL = 'tv-remote';
+
 /**
  * Captures one selected owner's interactor authority for the lifetime of a request binding. The
  * owner is already chosen by the time a binder is called, so each entry point supplies its own
@@ -52,7 +55,11 @@ export function bindTvRemote(
         appBundleId: input.options?.appBundleId,
         signal,
       });
-      await interactor.tvRemote(input.button, input.durationMs);
+      // Loaded on the call rather than at module evaluation because this facade's eager closure
+      // is held at its merge-base size (`eager-closure-budgets`); a static edge would grow it.
+      const { requireInteractorMethod } = await import('./interactor-operation-binding.ts');
+      const tvRemote = requireInteractorMethod(interactor.tvRemote, TV_REMOTE_LABEL);
+      await tvRemote.call(interactor, input.button, input.durationMs);
     },
   });
 }

packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts

@@ -71,11 +71,11 @@ const RUNNER_TRANSPORT_METHODS: Record<
   },
   findText: { invoke: (i) => i.findText!('Ready'), runnerCommand: 'findText' },
   back: { invoke: (i) => i.back(), runnerCommand: 'backInApp' },
-  home: { invoke: (i) => i.home(), runnerCommand: 'home' },
+  home: { invoke: (i) => i.home!(), runnerCommand: 'home' },
   setOrientation: { invoke: (i) => i.setOrientation('portrait'), runnerCommand: 'rotate' },
-  appSwitcher: { invoke: (i) => i.appSwitcher(), runnerCommand: 'appSwitcher' },
+  appSwitcher: { invoke: (i) => i.appSwitcher!(), runnerCommand: 'appSwitcher' },
   actionButton: { invoke: (i) => i.actionButton!(), runnerCommand: 'actionButton' },
-  tvRemote: { invoke: (i) => i.tvRemote('select'), runnerCommand: 'remotePress' },
+  tvRemote: { invoke: (i) => i.tvRemote!('select'), runnerCommand: 'remotePress' },
   keyboardDismiss: { invoke: (i) => i.keyboardDismiss!(), runnerCommand: 'keyboardDismiss' },
   keyboardEnter: { invoke: (i) => i.keyboardEnter!(), runnerCommand: 'keyboardReturn' },
   // R59: same reading as `readTextAtPoint` — the macOS-helper branch is reachable only for a
@@ -92,8 +92,8 @@ const LOCAL_TOOL_METHODS: Record<string, (interactor: Interactor) => Promise<unk
   openDevice: (i) => i.openDevice(),
   close: (i) => i.close('com.example.app'),
   screenshot: (i) => i.screenshot('/dev/null'),
-  readClipboard: (i) => i.readClipboard(),
-  writeClipboard: (i) => i.writeClipboard('hi'),
+  readClipboard: (i) => i.readClipboard!(),
+  writeClipboard: (i) => i.writeClipboard!('hi'),
   setSetting: (i) => i.setSetting('wifi', 'on'),
   // `simctl ui ... content_size` is local Apple tooling like the write leg beside it, so a provider-owned
   // device has no way to answer a text-size read.

packages/platform-vega/src/__tests__/interactor.test.ts

@@ -42,9 +42,9 @@ beforeEach(() => {
 test('tvRemote, back, and home share the Vega remote primitive', async () => {
   const interactor = createVegaInteractor(VEGA_VVD, {});
 
-  await interactor.tvRemote('left', 250);
+  await interactor.tvRemote!('left', 250);
   await interactor.back('system');
-  await interactor.home();
+  await interactor.home!();
 
   assert.deepEqual(mockPressVegaTvRemote.mock.calls, [
     [VEGA_VVD, 'left', 250],
@@ -129,9 +129,9 @@ test('required unproven Vega operations share typed unsupported behavior', async
     ['screenshot', () => interactor.screenshot('/tmp/vega.png')],
     ['snapshot', () => interactor.snapshot()],
     ['setOrientation', () => interactor.setOrientation('portrait')],
-    ['appSwitcher', () => interactor.appSwitcher()],
-    ['readClipboard', () => interactor.readClipboard()],
-    ['writeClipboard', () => interactor.writeClipboard('text')],
+    ['appSwitcher', () => interactor.appSwitcher!()],
+    ['readClipboard', () => interactor.readClipboard!()],
+    ['writeClipboard', () => interactor.writeClipboard!('text')],
     ['setSetting', () => interactor.setSetting('wifi', 'on')],
   ];
 

packages/provider-limrun/src/interaction-operations.ts

@@ -44,9 +44,9 @@ import { setTimeout as sleep } from 'node:timers/promises';
 
 const available = Object.freeze({ available: true } as const);
 /**
- * Limrun's iOS direct session drives text and touch but exposes no portable gesture execution —
- * its interactor's own `performGesture` refuses with this wording. Stating it as a fact refuses at
- * admission instead of mid-execution (ADR 0019 §6), keeping the agent-facing hint identical.
+ * Limrun's iOS direct session drives text and touch but exposes no portable gesture execution.
+ * Stating it as a fact refuses at admission instead of mid-execution (ADR 0019 §6), and it is
+ * the only refusal the caller sees: the leg's interactor carries no gesture member at all.
  */
 const iosGestureUnavailable = Object.freeze({
   available: false,
@@ -228,8 +228,9 @@ export function bindLimrunInteractionOperations(
  * `back`/`orientation`/`tvRemote` differ by direct-session platform, unlike focus/type:
  * the Android leg rides `session.dependencies.android.createInteractor` (`android.ts`) — the
  * SAME factory the local Android family binds, so it carries the identical cell table (parity
- * with the local owner, including the `device.target === 'tv'` gate for `tvRemote`). The iOS leg
- * (`ios.ts`) implements `back`/`setOrientation` but explicitly refuses `tvRemote`.
+ * with the local owner, including the `device.target === 'tv'` gate for `tvRemote`). The iOS
+ * direct session is a phone/tablet surface with no remote receiver, so its fact refuses
+ * `tvRemote` and its interactor carries no such member.
  */
 export function limrunNavigationOperationFacts(
   device: DeviceInfo,
@@ -267,8 +268,7 @@ export function limrunNavigationOperationFacts(
  * `clipboard` shares the split its siblings have: the Android leg rides
  * `session.dependencies.android.createInteractor` — the SAME factory the local Android family
  * binds, so `cmd clipboard get/set text` reaches the device exactly as it does locally — while
- * the iOS leg's own `readClipboard`/`writeClipboard` throw, so both cells stay unavailable there
- * and carry the interactor's wording.
+ * the iOS direct session has no pasteboard transport, so both cells stay unavailable there.
  */
 export function limrunClipboardOperationFacts(
   device: DeviceInfo,

packages/provider-limrun/src/ios.ts

@@ -322,10 +322,6 @@ class LimrunIosInteractor implements Interactor {
     await this.session.client.pressKey('escape');
   }
 
-  async home(): Promise<never> {
-    throw unsupported('home', 'Limrun iOS direct sessions do not expose home yet.');
-  }
-
   async setOrientation(orientation: DeviceRotation): Promise<void> {
     if (orientation === 'portrait-upside-down') {
       throw unsupported(
@@ -336,29 +332,6 @@ class LimrunIosInteractor implements Interactor {
     await this.session.client.setOrientation(orientation === 'portrait' ? 'Portrait' : 'Landscape');
   }
 
-  async performGesture(): Promise<never> {
-    throw unsupported(
-      'gesture',
-      'Limrun iOS direct sessions do not expose portable gesture execution yet.',
-    );
-  }
-
-  async appSwitcher(): Promise<never> {
-    throw unsupported('app-switcher', 'Limrun iOS direct sessions do not expose app switcher yet.');
-  }
-
-  async tvRemote(): Promise<never> {
-    throw unsupported('tv-remote', 'Limrun iOS direct sessions do not expose tv remote control.');
-  }
-
-  async readClipboard(): Promise<never> {
-    throw unsupported('clipboard', 'Limrun iOS direct sessions do not expose clipboard read yet.');
-  }
-
-  async writeClipboard(): Promise<never> {
-    throw unsupported('clipboard', 'Limrun iOS direct sessions do not expose clipboard write yet.');
-  }
-
   async setSetting(): Promise<never> {
     throw unsupported('settings', 'Limrun iOS direct sessions do not expose settings changes yet.');
   }