refactor(contracts): state the scroll keyboard refusal details once and keep the runner's message

The Apple scroll owner rebuilt the refusal per command, discarding the
runner's measured message and carrying an unmeasured variant of the
error builder for it. The shared reason and hint are now one frozen
object in scroll-gesture; the Apple owner adds it to the runner's own
error (matched on the typed runner code, transport details kept), and
the error builder takes a plain measured occlusion, which only Android
produces in-process. The help text names the behaviour in one clause;
the hint carries the recovery at the moment it matters.

Author: thymikee

packages/contracts/src/scroll-gesture.test.ts

@@ -306,7 +306,6 @@ test('an unusable keyboard frame fails open instead of refusing every scroll', (
 
 test('the occlusion refusal is keyed on its reason, not on its message', () => {
   const error = scrollKeyboardOccludesSurfaceError('down', {
-    kind: 'occluded',
     keyboardMinY: 564,
     visibleHeight: 40,
     viewportHeight: 874,
@@ -319,20 +318,3 @@ test('the occlusion refusal is keyed on its reason, not on its message', () => {
   assert.equal(error.details?.viewportHeight, 874);
   assert.match(String(error.details?.hint), /keyboard dismiss/);
 });
-
-test('an unmeasured refusal still names the same reason, so error text never gates recovery', () => {
-  // The iOS runner refuses in its own coordinate space and reports only its typed runner code, so
-  // the Apple owner rebuilds this error without numbers. Matching on `reason` has to yield the
-  // same key with or without a measurement, or the message becomes the discriminator.
-  const unmeasured = scrollKeyboardOccludesSurfaceError('down');
-  const measured = scrollKeyboardOccludesSurfaceError('down', {
-    kind: 'occluded',
-    keyboardMinY: 564,
-    visibleHeight: 40,
-    viewportHeight: 874,
-  });
-  assert.equal(unmeasured.details?.reason, measured.details?.reason);
-  assert.equal(unmeasured.details?.keyboardMinY, undefined);
-  assert.equal(unmeasured.details?.visibleHeight, undefined);
-  assert.ok(!String(unmeasured.message).includes('px of'), 'no fabricated measurement may appear');
-});

packages/contracts/src/scroll-gesture.ts

@@ -359,12 +359,23 @@ export const SCROLL_KEYBOARD_MIN_VISIBLE_FRACTION = 0.15;
 export const SCROLL_KEYBOARD_ACCESSORY_ALLOWANCE = 12;
 
 /**
- * The one reason a directional scroll refuses to swipe at all (#2500). The iOS runner answers with
- * its own runner error code for the same condition; that code is the Apple runner's wire
- * vocabulary and lives with it, not here, because Android raises this reason locally.
+ * The one reason a directional scroll refuses to swipe at all (#2500), with the hint every owner
+ * publishes beside it: Android measures the occlusion in this process, and the iOS runner answers
+ * with its own runner code that the Apple scroll owner joins to these same details, so a
+ * caller branches on `reason` and reads one hint whichever owner refused. Avoidance never dismisses
+ * the keyboard: a dismiss drops focus, which breaks a `type`/`scroll`/`type` loop, is not idempotent
+ * across platforms, and mutates state session-action provenance does not record. So the hint names
+ * the tradeoff instead of paying it.
  */
 export const SCROLL_KEYBOARD_OCCLUDES_SURFACE_REASON = 'scroll_keyboard_occludes_surface';
 
+export const SCROLL_KEYBOARD_OCCLUDES_SURFACE_DETAILS = Object.freeze({
+  reason: SCROLL_KEYBOARD_OCCLUDES_SURFACE_REASON,
+  hint:
+    'The on-screen keyboard covers the surface this scroll would swipe, so it cannot reach it. ' +
+    'Run `keyboard dismiss` and retry, accepting that it drops focus (re-tap the field to keep typing), or scroll before focusing the field.',
+});
+
 export type ScrollKeyboardClip =
   /** No keyboard, or one that does not own this surface: swipe the whole viewport. */
   | { kind: 'unobstructed' }
@@ -377,8 +388,10 @@ export type ScrollKeyboardClip =
    */
   | { kind: 'occluded'; keyboardMinY: number; visibleHeight: number };
 
-/** The numbers a refusing owner can name about the surface it declined to swipe. */
-export type ScrollKeyboardOcclusion = Extract<ScrollKeyboardClip, { kind: 'occluded' }> & {
+/** The numbers a refusing owner names about the surface it declined to swipe. */
+export type ScrollKeyboardOcclusion = {
+  keyboardMinY: number;
+  visibleHeight: number;
   viewportHeight: number;
 };
 
@@ -421,38 +434,26 @@ export function clipScrollViewportAboveKeyboard(
 }
 
 /**
- * The refusal a scroll reports when the keyboard owns the surface. `avoidanceNeverDismisses` is the
- * point: a dismiss drops focus, which breaks a `type`/`scroll`/`type` loop, is not idempotent
- * across platforms (Android's ESC loop can throw `UNSUPPORTED_OPERATION`), and mutates state
- * session-action provenance does not record. So the caller names the tradeoff instead of paying it.
- *
- * `occlusion` is optional because the owner that measured the frame may be the runner rather than
- * this process: the iOS XCTest runner refuses in its own coordinate space and reports the typed
- * runner code, and re-deriving its numbers here would be a second source of truth.
+ * The refusal an owner that measured the keyboard in this process reports. The iOS runner measures
+ * in its own coordinate space and answers with its runner code instead; the Apple scroll owner
+ * adds the same `SCROLL_KEYBOARD_OCCLUDES_SURFACE_DETAILS` to that error.
  */
 export function scrollKeyboardOccludesSurfaceError(
   direction: ScrollDirection,
-  occlusion?: ScrollKeyboardOcclusion,
+  occlusion: ScrollKeyboardOcclusion,
 ): AppError {
   const percent = Math.round(SCROLL_KEYBOARD_MIN_VISIBLE_FRACTION * 100);
-  const measured =
-    occlusion === undefined
-      ? 'the keyboard leaves too little visible surface for a swipe'
-      : `the keyboard leaves ${occlusion.visibleHeight}px of ${occlusion.viewportHeight}px visible, below the ${percent}% needed for a swipe`;
-  return new AppError('COMMAND_FAILED', `scroll ${direction} refused: ${measured}`, {
-    reason: SCROLL_KEYBOARD_OCCLUDES_SURFACE_REASON,
-    ...(occlusion === undefined
-      ? {}
-      : {
-          keyboardMinY: occlusion.keyboardMinY,
-          visibleHeight: occlusion.visibleHeight,
-          viewportHeight: occlusion.viewportHeight,
-        }),
-    minVisibleFraction: SCROLL_KEYBOARD_MIN_VISIBLE_FRACTION,
-    hint:
-      'The on-screen keyboard covers the surface this scroll would swipe, so it cannot reach it. ' +
-      'Run `keyboard dismiss` and retry, accepting that it drops focus (re-tap the field to keep typing), or scroll before focusing the field.',
-  });
+  return new AppError(
+    'COMMAND_FAILED',
+    `scroll ${direction} refused: the keyboard leaves ${occlusion.visibleHeight}px of ${occlusion.viewportHeight}px visible, below the ${percent}% needed for a swipe`,
+    {
+      keyboardMinY: occlusion.keyboardMinY,
+      visibleHeight: occlusion.visibleHeight,
+      viewportHeight: occlusion.viewportHeight,
+      minVisibleFraction: SCROLL_KEYBOARD_MIN_VISIBLE_FRACTION,
+      ...SCROLL_KEYBOARD_OCCLUDES_SURFACE_DETAILS,
+    },
+  );
 }
 
 function isMeasurableRect(rect: Rect): boolean {

packages/platform-apple/src/core/__tests__/scroll.test.ts

@@ -7,19 +7,6 @@ import {
   withAppleScrollKeyboardOcclusion,
 } from '../scroll.ts';
 
-const RUNNER_OCCLUSION_CODE = 'SCROLL_KEYBOARD_OCCLUDES_SURFACE';
-
-function runnerOcclusionError(): AppError {
-  return new AppError(
-    'COMMAND_FAILED',
-    'scroll down refused: the keyboard leaves 28pt of surface',
-    {
-      runnerErrorCode: RUNNER_OCCLUSION_CODE,
-      logPath: '/tmp/runner.log',
-    },
-  );
-}
-
 test('a clipped runner frame yields travel and evidence for the band actually swiped', () => {
   // The runner clips the interaction frame above the keyboard and reports the clipped axis, so the
   // TS recomputation of `pixels` must be honest about the shorter travel (#2500). Reading the
@@ -76,34 +63,29 @@ test('avoidance from a runner that reports no keyboard edge is still avoidance',
   assert.equal('keyboardMinY' in result, false);
 });
 
-test('the runner keyboard refusal becomes the typed reason a caller can branch on', () => {
-  const mapped = withAppleScrollKeyboardOcclusion(runnerOcclusionError(), 'down');
+test('the runner keyboard refusal gains the shared reason and hint and keeps its own message', () => {
+  const runnerError = new AppError(
+    'COMMAND_FAILED',
+    'scroll down refused: the keyboard leaves 28pt of visible surface above it',
+    { runnerErrorCode: 'SCROLL_KEYBOARD_OCCLUDES_SURFACE', logPath: '/tmp/runner.log' },
+  );
+  const mapped = withAppleScrollKeyboardOcclusion(runnerError);
   assert.ok(mapped instanceof AppError);
   assert.equal(mapped.code, 'COMMAND_FAILED');
+  assert.equal(mapped.message, runnerError.message);
   assert.equal(mapped.details?.reason, SCROLL_KEYBOARD_OCCLUDES_SURFACE_REASON);
   assert.match(String(mapped.details?.hint), /keyboard dismiss/);
-});
-
-test('the mapped refusal keeps the transport diagnostics the original error carried', () => {
-  const mapped = withAppleScrollKeyboardOcclusion(runnerOcclusionError(), 'down');
-  assert.ok(mapped instanceof AppError);
   assert.equal(mapped.details?.logPath, '/tmp/runner.log');
-  assert.equal(mapped.details?.runnerErrorCode, RUNNER_OCCLUSION_CODE);
+  assert.equal(mapped.details?.runnerErrorCode, 'SCROLL_KEYBOARD_OCCLUDES_SURFACE');
 });
 
-test('the nearest negatives stay untouched, so only the refusal code renames an error', () => {
-  // Same code, different classification: a generic scroll failure must not read as an occlusion, or
-  // the caller would be told to dismiss a keyboard that is not in the way.
-  const generic = new AppError(
-    'COMMAND_FAILED',
-    'scroll could not resolve a usable interaction frame',
-    {
-      logPath: '/tmp/runner.log',
-    },
-  );
-  assert.equal(withAppleScrollKeyboardOcclusion(generic, 'down'), generic);
-  const transport = new Error('socket hang up');
-  assert.equal(withAppleScrollKeyboardOcclusion(transport, 'down'), transport);
+test('only the refusal code is renamed, so a generic scroll failure never reads as an occlusion', () => {
+  const generic = new AppError('COMMAND_FAILED', 'scroll could not resolve a usable frame', {
+    logPath: '/tmp/runner.log',
+  });
+  assert.equal(withAppleScrollKeyboardOcclusion(generic), generic);
   const alert = new AppError('COMMAND_FAILED', 'no alert', { runnerErrorCode: 'ALERT_NOT_FOUND' });
-  assert.equal(withAppleScrollKeyboardOcclusion(alert, 'down'), alert);
+  assert.equal(withAppleScrollKeyboardOcclusion(alert), alert);
+  const transport = new Error('socket hang up');
+  assert.equal(withAppleScrollKeyboardOcclusion(transport), transport);
 });

packages/platform-apple/src/core/scroll.ts

@@ -6,8 +6,8 @@ import {
 } from '@agent-device/contracts/scroll-command';
 import {
   type ScrollDirection,
+  SCROLL_KEYBOARD_OCCLUDES_SURFACE_DETAILS,
   buildScrollGesturePlan,
-  scrollKeyboardOccludesSurfaceError,
 } from '@agent-device/contracts/scroll-gesture';
 import { AppError } from '@agent-device/kernel/errors';
 import { SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE } from '../runner/runner-contract.ts';
@@ -22,26 +22,19 @@ export type NormalizedScrollOptions = {
 export type AppleScrollOptions = ScrollExecutionOptions;
 
 /**
- * Turns the runner's keyboard-occlusion refusal into the reason a caller acts on (#2500).
- *
- * The runner owns the live keyboard frame and declines to place a swipe it cannot keep above the
- * keys; it answers with a typed runner code rather than prose so nothing here has to read an error
- * message. The numbers stay on the runner's side of the boundary — re-deriving them from a frame
- * this process does not hold would be a second source of truth — so the reason and hint are the
- * evidence, joined to whatever the transport already recorded (`logPath`, `runnerErrorCode`).
+ * Gives the runner's keyboard-occlusion refusal the shared reason and hint (#2500). The runner
+ * measured the keyboard in its own coordinate space, so its message and transport details
+ * (`runnerErrorCode`, `logPath`) are kept as they are; only the details every platform publishes
+ * are added, matched on the typed runner code rather than on error text.
  */
-export function withAppleScrollKeyboardOcclusion(
-  error: unknown,
-  direction: ScrollDirection,
-): unknown {
+export function withAppleScrollKeyboardOcclusion(error: unknown): unknown {
   if (!(error instanceof AppError)) return error;
   if (error.details?.['runnerErrorCode'] !== SCROLL_KEYBOARD_OCCLUDES_SURFACE_RUNNER_CODE) {
     return error;
   }
-  const refusal = scrollKeyboardOccludesSurfaceError(direction);
-  return new AppError(refusal.code, refusal.message, {
-    ...(error.details ?? {}),
-    ...(refusal.details ?? {}),
+  return new AppError(error.code, error.message, {
+    ...error.details,
+    ...SCROLL_KEYBOARD_OCCLUDES_SURFACE_DETAILS,
   });
 }
 

packages/platform-apple/src/interactions.ts

@@ -445,7 +445,7 @@ async function runAppleScroll(
       runnerOpts,
     );
   } catch (error) {
-    throw withAppleScrollKeyboardOcclusion(error, direction);
+    throw withAppleScrollKeyboardOcclusion(error);
   }
 
   return normalizeAppleScrollResultWithResolvedFrame(runnerResult, direction, iosOptions);

src/commands/interaction/metadata.ts

@@ -68,7 +68,7 @@ const interactionCommandDescriptions = {
     'Move input focus to explicit screen coordinates without entering text. Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus.',
   type: 'Append text to the currently focused input. Use fill when the existing field value should be replaced, and focus first when no input is active.',
   scroll:
-    'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band rather than dismissing it, which lowers the reported pixels; when too little surface is left to swipe, the command refuses with scroll_keyboard_occludes_surface and leaves focus alone.',
+    'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface.',
   get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
   is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
   find: 'Find by text/label/value/role/id and run action',