fix(gestures): reject removed swipe input at the Node/MCP boundary

Review findings on d88c6ed.

P1: `interactionDaemonWriters.swipe` hand-projects five fields, so a JavaScript
caller's `durationMs` was dropped before the daemon's `readSwipeInput` could
reject it and a default-duration fling ran instead — the exact silent
reinterpretation the guide promises does not happen. `gesture` was already safe
because its writer runs `readGestureInput` -> `readGesturePayload`, which
rejects the removed keys; `swipe` was the one surface with no reader of its own.
The rejection now lives in contracts and is shared by the client writer and the
daemon handler, so there is one rule and one message. The SDK regression covers
all four removed keys and asserts the transport is never reached; reverting the
writer call fails it on `swipe durationMs`.

P2: the preflight's retired-slot test required a numeric token, so
`swipe 197 650 197 300 ${DURATION}` fell back to bare usage text. An unresolved
`${VAR}` now counts as the retired slot and is carried into the pan rewrite,
while a stray flag or word stays a plain usage error.

P2: the removal shipped in 0.20.0, not 0.21 — removal commit 6d99914 is
contained in tag v0.20.0. The guide said 0.21 because the CHANGELOG still files
it under `Unreleased`; the tag is the truth (headings lag several releases
repo-wide, so that is pre-existing and left alone). The `.ad` grep recipe now
matches variable-backed durations too.

Author: thymikee

src/__tests__/client.test.ts

@@ -673,6 +673,55 @@ test('interactions.rotateGesture rejects partial centers on the client side', as
   assert.equal(setup.calls.length, 0);
 });
 
+test('removed gesture inputs are rejected client-side, never dropped from the projection', async () => {
+  const setup = createTransport(async () => {
+    throw new Error('transport should not run for invalid input');
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+  // A JavaScript caller (or a stale compiled build) can still reach these keys
+  // past the removed compile-time fields. `swipe` has no structured reader of
+  // its own, so before #1216 its writer silently dropped `durationMs` and ran a
+  // default-duration fling instead of failing.
+  const removed: Array<[string, () => Promise<unknown>, string]> = [
+    [
+      'swipe durationMs',
+      () =>
+        client.interactions.swipe({
+          from: { x: 197, y: 650 },
+          to: { x: 197, y: 300 },
+          durationMs: 300,
+        } as Parameters<typeof client.interactions.swipe>[0]),
+      'swipe does not accept durationMs; use gesture pan for timed movement',
+    ],
+    [
+      'fling durationMs',
+      () =>
+        client.interactions.fling({ direction: 'down', x: 100, y: 200, durationMs: 300 } as never),
+      'gesture fling does not accept durationMs; use gesture pan for timed movement',
+    ],
+    [
+      'gesture swipe durationMs',
+      () => client.interactions.swipeGesture({ preset: 'left', durationMs: 300 } as never),
+      'gesture swipe does not accept durationMs; use gesture pan for timed movement',
+    ],
+    [
+      'rotate velocity',
+      () => client.interactions.rotateGesture({ degrees: 35, velocity: 800 } as never),
+      'gesture rotate does not accept velocity; rotation pacing derives from degrees',
+    ],
+  ];
+
+  for (const [label, call, message] of removed) {
+    await assert.rejects(
+      call,
+      (error: unknown) =>
+        error instanceof AppError && error.code === 'INVALID_ARGS' && error.message === message,
+      label,
+    );
+  }
+  assert.equal(setup.calls.length, 0);
+});
+
 test('interactions.pan projects one- and two-finger requests through typed gesture input', async () => {
   const setup = createTransport(async () => ({ ok: true, data: { message: 'Panned' } }));
   const client = createAgentDeviceClient(setup.config, { transport: setup.transport });

src/commands/interaction/interactions.ts

@@ -11,7 +11,10 @@ import {
   readInteractionTargetFromPositionals,
 } from '../../core/interaction-positionals.ts';
 import { AppError } from '../../kernel/errors.ts';
-import { swipePayloadFromPositionals } from '../../contracts/gesture-normalization.ts';
+import {
+  assertNoRemovedSwipeInput,
+  swipePayloadFromPositionals,
+} from '../../contracts/gesture-normalization.ts';
 import type { ScrollInputDirection } from './runtime/gestures.ts';
 import {
   commonInputFromFlags,
@@ -124,14 +127,16 @@ export const interactionDaemonWriters = {
   longpress: direct(PUBLIC_COMMANDS.longPress, (input) =>
     longPressPositionals(input as LongPressOptions),
   ),
-  swipe: (input) =>
-    request(PUBLIC_COMMANDS.swipe, [], input, {
+  swipe: (input) => {
+    assertNoRemovedSwipeInput(input);
+    return request(PUBLIC_COMMANDS.swipe, [], input, {
       from: input.from,
       to: input.to,
       count: input.count,
       pauseMs: input.pauseMs,
       pattern: input.pattern,
-    }),
+    });
+  },
   focus: direct(PUBLIC_COMMANDS.focus, (input) => [String(input.x), String(input.y)]),
   type: direct(PUBLIC_COMMANDS.type, (input) => typePositionals(input as TypeTextOptions)),
   fill: direct(PUBLIC_COMMANDS.fill, (input) => fillPositionals(input as FillOptions)),

src/contracts/gesture-normalization.test.ts

@@ -87,6 +87,10 @@ test('a malformed line is a usage error rather than a migration claim', () => {
     code: 'INVALID_ARGS',
     message: 'swipe accepts 4 arguments: x1 y1 x2 y2.',
   });
+  assert.throws(() => swipePayloadFromPositionals(['1', '2', '3', '4', 'hello']), {
+    code: 'INVALID_ARGS',
+    message: 'swipe accepts 4 arguments: x1 y1 x2 y2.',
+  });
 });
 
 test('the .ad preflight names the offending line and leaves live syntax alone', () => {
@@ -101,6 +105,26 @@ test('the .ad preflight names the offending line and leaves live syntax alone',
   assert.equal(describeReplayGestureArityError('click', ['120', '240'], 'line 2'), undefined);
 });
 
+test('a variable-backed retired positional still gets the migration', () => {
+  assert.equal(
+    describeReplayGestureArityError('swipe', ['197', '650', '197', '300', '${DURATION}'], 'line 6'),
+    'swipe accepts 4 arguments: x1 y1 x2 y2 (line 6). The trailing durationMs positional was removed: use "gesture pan 197 650 0 -350 ${DURATION}" for the same timed drag, or "swipe 197 650 197 300" for a default-duration swipe.',
+  );
+  assert.equal(
+    describeReplayGestureArityError(
+      'swipe',
+      ['${X1}', '${Y1}', '${X2}', '${Y2}', '${DURATION}'],
+      'line 6',
+    ),
+    'swipe accepts 4 arguments: x1 y1 x2 y2 (line 6). The trailing durationMs positional was removed: use "gesture pan x1 y1 dx dy durationMs" for the same timed drag, or "swipe ${X1} ${Y1} ${X2} ${Y2}" for a default-duration swipe.',
+  );
+  assert.match(
+    describeReplayGestureArityError('gesture', ['rotate', '35', '195', '443', '${V}'], 'line 4') ??
+      '',
+    /trailing velocity positional was removed: use "gesture rotate 35 195 443"/,
+  );
+});
+
 test('the .ad preflight defers to dispatch for values it cannot know yet', () => {
   // `${VAR}` tokens resolve after planning, and interpolation never splits a
   // token, so only the argument count is decidable at parse time.

src/contracts/gesture-normalization.ts

@@ -114,9 +114,7 @@ function describeGestureArityError(
   const syntax = PUBLIC_GESTURE_SYNTAX[key];
   if (args.length <= syntax.max) return undefined;
   const retired = syntax.retired;
-  // A retired positional was always a number, so a single extra numeric
-  // argument is the pre-removal form rather than a malformed line.
-  if (!retired || args.length !== syntax.max + 1 || !isNumericArgument(args[syntax.max])) {
+  if (!retired || args.length !== syntax.max + 1 || !isRetiredSlotArgument(args[syntax.max])) {
     return { usage: syntax.usage };
   }
   const canonical = `${key} ${args.slice(0, syntax.max).join(' ')}`;
@@ -126,8 +124,30 @@ function describeGestureArityError(
   };
 }
 
-function isNumericArgument(value: string | undefined): boolean {
-  return value !== undefined && value.trim().length > 0 && Number.isFinite(Number(value));
+/**
+ * Whether one extra argument occupies the retired slot. A retired positional was
+ * always a number, and a `.ad` script may hold it as an unresolved `${VAR}`, so
+ * both report the migration while a stray flag or word stays a usage error.
+ */
+function isRetiredSlotArgument(value: string | undefined): boolean {
+  if (value === undefined || value.trim().length === 0) return false;
+  return value.startsWith('${') || Number.isFinite(Number(value));
+}
+
+/**
+ * `swipe` is the one public gesture surface whose structured input has no reader
+ * of its own — the daemon writer projects known fields — so a removed key would
+ * be dropped before the daemon could reject it and a default-duration fling
+ * would run instead. Rejecting here covers the Node and MCP boundaries at the
+ * same point `readGesturePayload` rejects the gesture kinds' removed keys.
+ */
+export function assertNoRemovedSwipeInput(input: unknown): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return;
+  if ((input as Record<string, unknown>).durationMs === undefined) return;
+  throw new AppError(
+    'INVALID_ARGS',
+    'swipe does not accept durationMs; use gesture pan for timed movement',
+  );
 }
 
 function formatGestureArityError(error: GestureArityError, source?: string): string {

src/daemon/handlers/interaction-gesture.ts

@@ -1,5 +1,6 @@
 import { readGesturePayload, type GesturePayload } from '../../contracts/gesture-input.ts';
 import {
+  assertNoRemovedSwipeInput,
   gesturePayloadToPositionals,
   normalizePublicGesture,
   normalizePublicSwipeMotion,
@@ -189,13 +190,8 @@ function readSwipeInput(input: unknown): SwipePayload {
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
     throw new AppError('INVALID_ARGS', 'swipe requires structured object input');
   }
+  assertNoRemovedSwipeInput(input);
   const record = input as Record<string, unknown>;
-  if (record.durationMs !== undefined) {
-    throw new AppError(
-      'INVALID_ARGS',
-      'swipe does not accept durationMs; use gesture pan for timed movement',
-    );
-  }
   const pattern = record.pattern;
   if (pattern !== undefined && pattern !== 'one-way' && pattern !== 'ping-pong') {
     throw new AppError('INVALID_ARGS', 'swipe pattern must be one-way or ping-pong');

website/docs/docs/migrating-gestures.md

@@ -4,7 +4,7 @@ title: Migrating Gestures
 
 # Migrating Gestures
 
-`agent-device` 0.21 removed the timed forms of `swipe`, `gesture fling`, and `gesture swipe`, and
+`agent-device` 0.20.0 removed the timed forms of `swipe`, `gesture fling`, and `gesture swipe`, and
 the `velocity` argument of `gesture rotate`. Nothing is silently reinterpreted: every removed form
 now fails with an `INVALID_ARGS` error that names its replacement.
 
@@ -61,7 +61,9 @@ for a default-duration swipe.
 
 `interactions.swipe`, `interactions.fling`, and `interactions.swipeGesture` no longer accept
 `durationMs`; `interactions.rotateGesture` no longer accepts `velocity`. Passing them is a type
-error at compile time and an `INVALID_ARGS` rejection at runtime.
+error at compile time and an `INVALID_ARGS` rejection at runtime — the rejection happens
+client-side, before the request reaches the daemon, so a plain JavaScript caller or a stale
+compiled build gets the error rather than a silently retimed gesture.
 
 ```ts
 // before
@@ -114,10 +116,13 @@ swipe 206 650 206 300 300 --count 2 --pause-ms 200 --pattern one-way
 swipe 206 650 206 300 --count 2 --pause-ms 200 --pattern one-way
 ```
 
+A duration held in a variable (`swipe 197 650 197 300 ${DURATION}`) is reported the same way — the
+preflight counts arguments, so it does not need the value.
+
 To find every affected line across a suite:
 
 ```bash
-grep -rnE '\bswipe +[-0-9.]+ +[-0-9.]+ +[-0-9.]+ +[-0-9.]+ +[-0-9.]+' --include='*.ad' .
+grep -rnE '\bswipe( +([-0-9.]+|\$\{[^}]*\})){5}' --include='*.ad' .
 ```
 
 Re-recording also produces a migrated script: the recorder writes the canonical form, so a fresh
@@ -154,7 +159,7 @@ to clear:
    that can appear in a saved recording, the rejection must fire at parse time and name the line, so
    a stale script never half-executes.
 
-The 0.21 removal completed all five steps.
+The 0.20.0 removal completed all five steps.
 
 ## Positional `.ad` syntax