fix(gestures): fail pre-removal gesture forms at .ad parse time (#1216)

#1315 removed the timed forms of `swipe`, `gesture fling`, and `gesture swipe`
and `gesture rotate`'s `velocity`, but shipped without the migration guide, the
repository sweep, or the parse-time error that issue #1216's own checklist
gates a removal on. The sweep finds what that left behind: both
`06-swipe-gestures.ad` integration fixtures still carried the 5-argument swipe
and would fail at replay, two tests still asserted the removed shapes, and two
branches still read the retired positional.

Argument arity for every public gesture syntax now lives in one table keyed off
the canonical `GESTURE_KINDS`, so a new kind cannot skip it and a form removed
from the CLI is removed from `.ad` in the same edit. Both callers read it: the
CLI argv parse, and a new `.ad` preflight. A stale script now fails when it is
parsed — before the replay executes any device action — naming the line and
computing its rewrite, instead of running up to that step and failing as a
repairable divergence. The preflight checks arity only: `${VAR}` tokens resolve
after planning, and interpolation never splits a token, so the count is
decidable while the values are not.

Deleting the dead duration read in `readSwipeGeometry` would have left
`replay export` emitting no duration, handing Maestro's 400ms default to a
gesture the script runs at 100ms, so the export now states `duration: 100`.

`.ad` positional gesture parsing is NOT removed. Its only remaining callers are
the CLI argv parse and the `.ad` line parse, both the current public syntax
rather than a bridge to an older one, so there is nothing to migrate off. ADR
0013 records that and drops the "compatibility" framing that made it read as
debt.

Both migrated fixtures verified on real devices with the repo's own CLI: iOS
simulator 34.9s, Android emulator 45.9s.

Author: thymikee

CHANGELOG.md

@@ -13,6 +13,9 @@
   - `gesture swipe preset` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
   - `gesture rotate degrees [x] [y]` no longer accepts a trailing `velocity` positional; rotation pacing is derived from `degrees`.
   - MCP/Node schemas no longer advertise `velocity` or `durationMs` on `swipe`/`fling`/`gesture swipe`; `durationMs` remains on `gesture pan` and `gesture transform`.
+  - A `.ad` script that still carries a removed positional now fails when the script is parsed, before the replay executes any device action, naming the line and its rewrite (for example `swipe accepts 4 arguments: x1 y1 x2 y2 (line 6). The trailing durationMs positional was removed: use "gesture pan 197 650 0 -350 300" ...`). Previously the script ran up to that step and then failed as a replay divergence.
+  - Published the [gesture migration guide](https://agent-device.dev/docs/migrating-gestures) covering CLI, Node.js, MCP, and saved `.ad` recordings, plus the deprecation policy the next such removal follows (#1216).
+  - `replay export` now writes an explicit `duration: 100` for `swipe` — the canonical fling duration — instead of omitting it and letting Maestro apply its own 400ms default. Maestro flows replayed by `agent-device` are unaffected; a timed Maestro `swipe` still normalizes to `gesture pan` with the `endpoint-hold` profile.
 - Breaking: the deprecated `rotate` CLI command alias has been removed. Use `orientation` instead; invoking `rotate` now fails with `rotate was renamed to orientation; for the two-finger gesture use: gesture rotate`.
 - Breaking (ADR 0014, session ref-frame lifetime): a mutation through an `@ref` now expires the session's ref frame, so a later ref mutation without a fresh observation fails closed with a typed `details.reason` (`ref_frame_expired`, `ref_generation_mismatch`, `plain_ref_requires_complete_frame`, or `ref_not_issued`) instead of acting on a possibly-navigated screen. A ref-oriented sequence that performs several mutations must re-`snapshot` between them, consume an honestly issued `--settle` ref in pinned `@eN~s<gen>` form, or use selectors. Enforcement applies on every platform, not just iOS. Legacy hand-written `.ad` scripts that reuse several bare refs from one snapshot must capture between mutations or use selectors.
 - Ref reads resolve against the authorized ref frame's source tree, so an internal read-only capture (including Android freshness) can no longer retarget an admitted `@ref` by positional coincidence. Read-only ref consumers keep the structured staleness warning while the frame retains the ref's evidence.

docs/adr/0013-unified-gesture-plans.md

@@ -96,9 +96,25 @@ Platform adapters consume the canonical plan:
 The `Interactor` and backend expose one compositional `performGesture(plan)` primitive instead of a
 method per semantic alias. The old scalar Apple and Android multi-touch executors and the
 public-command alias-to-positionals-to-reparse route are deleted. `.ad` keeps its established
-positional syntax through one named replay compatibility codec; CLI, Node.js, and MCP send
-structured input. Providers should compose transport/device bindings with the shared platform
-adapter rather than reimplement the interaction runtime.
+positional syntax through one named codec; CLI, Node.js, and MCP send structured input. Providers
+should compose transport/device bindings with the shared platform adapter rather than reimplement
+the interaction runtime.
+
+That `.ad` codec is the script format's own syntax, not a compatibility shim, and is not scheduled
+for removal (amended 2026-07, issue #1216). Its only remaining callers are the CLI argv parse and
+the `.ad` line parse — both the current public syntax — so there is nothing left to migrate off.
+A structured `.ad` gesture payload was rejected: it would make recordings unreadable and ungreppable
+for no behavioral gain.
+
+Argument arity for both callers comes from one table (`PUBLIC_GESTURE_SYNTAX`), so a form removed
+from the CLI is removed from `.ad` in the same edit. A `.ad` script that still carries a removed
+positional fails when the script is parsed, before the replay executes any device action, with the
+offending line and its rewrite. Arity is the only thing checked at parse time: `${VAR}` tokens
+resolve after planning, and interpolation never splits a token, so the count is decidable while the
+values are not. The removal process these inputs follow — announce, warn for one minor release,
+publish the migration guide, prove the repository is clean, then remove the branch and its tests —
+is documented in the public
+[gesture migration guide](https://agent-device.dev/docs/migrating-gestures).
 
 Repeated coordinate swipes are bounded at the public command contract and daemon trust boundary.
 Individual count and pause limits prevent pathological fields, while the combined planned gesture

src/compat/maestro/__tests__/export-flow.test.ts

@@ -43,7 +43,7 @@ screenshot "./artifacts/checkout"
   test('exports coordinate gestures and sleep waits with warnings', () => {
     const result = exportReplayScriptToMaestro(`open com.example.app
 click 120 240
-swipe 200 700 200 200 300 --count 2
+swipe 200 700 200 200 --count 2
 wait 500
 `);
 
@@ -52,8 +52,8 @@ wait 500
       [
         'launchApp',
         { tapOn: { point: '120,240' } },
-        { swipe: { start: '200,700', end: '200,200', duration: 300 } },
-        { swipe: { start: '200,700', end: '200,200', duration: 300 } },
+        { swipe: { start: '200,700', end: '200,200', duration: 100 } },
+        { swipe: { start: '200,700', end: '200,200', duration: 100 } },
         { waitForAnimationToEnd: { timeout: 500 } },
       ],
     ]);

src/compat/maestro/export-flow.ts

@@ -1,4 +1,5 @@
 import type { SessionAction } from '../../daemon/types.ts';
+import { GESTURE_FLING_DURATION_MS } from '../../contracts/gesture-plan.ts';
 import { parseSelectorChain, type Selector } from '../../selectors/index.ts';
 import type { SelectorTerm } from '../../selectors/parse.ts';
 import { AppError } from '../../kernel/errors.ts';
@@ -39,7 +40,7 @@ type ActionConverter = (action: SessionAction) => ConvertedAction;
 type SwipeGeometry = {
   start: string;
   end: string;
-  duration?: number;
+  duration: number;
 };
 
 const TEXT_SELECTOR_KEYS = new Set<string>(MAESTRO_TEXT_SELECTOR_KEYS);
@@ -362,13 +363,18 @@ function convertSwipeAction(action: SessionAction): ConvertedAction {
   };
 }
 
+/**
+ * `swipe` carries no duration positional, so the export states the canonical
+ * fling duration rather than letting Maestro apply its own 400 ms default to a
+ * gesture the script runs at 100 ms.
+ */
 function readSwipeGeometry(action: SessionAction): SwipeGeometry | undefined {
-  const [x1, y1, x2, y2, duration] = action.positionals;
+  const [x1, y1, x2, y2] = action.positionals;
   if (!isNumber(x1) || !isNumber(y1) || !isNumber(x2) || !isNumber(y2)) return undefined;
   return {
     start: formatMaestroPoint(x1, y1),
     end: formatMaestroPoint(x2, y2),
-    ...(duration && isNumber(duration) ? { duration: Number(duration) } : {}),
+    duration: GESTURE_FLING_DURATION_MS,
   };
 }
 

src/contracts/gesture-normalization.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import {
+  describeReplayGestureArityError,
   gesturePayloadFromPositionals,
   gesturePayloadToPositionals,
   normalizePublicGesture,
@@ -57,6 +58,62 @@ test('gesture recording codec round-trips fling with distance', () => {
   assert.deepEqual(gesturePayloadFromPositionals(gesturePayloadToPositionals(payload)), payload);
 });
 
+test('a retired trailing positional reports its migration, not a bare usage line', () => {
+  assert.throws(() => swipePayloadFromPositionals(['197', '650', '197', '300', '300']), {
+    code: 'INVALID_ARGS',
+    message:
+      'swipe accepts 4 arguments: x1 y1 x2 y2. The trailing durationMs positional was removed: use "gesture pan 197 650 0 -350 300" for the same timed drag, or "swipe 197 650 197 300" for a default-duration swipe.',
+  });
+  assert.throws(() => gesturePayloadFromPositionals(['fling', 'down', '100', '200', '80', '500']), {
+    code: 'INVALID_ARGS',
+    message: /trailing durationMs positional was removed: use "gesture fling down 100 200 80"/,
+  });
+  assert.throws(() => gesturePayloadFromPositionals(['swipe', 'left', '500']), {
+    code: 'INVALID_ARGS',
+    message: /trailing durationMs positional was removed: use "gesture swipe left"/,
+  });
+  assert.throws(() => gesturePayloadFromPositionals(['rotate', '35', '100', '200', '800']), {
+    code: 'INVALID_ARGS',
+    message: /trailing velocity positional was removed: use "gesture rotate 35 100 200"/,
+  });
+});
+
+test('a malformed line is a usage error rather than a migration claim', () => {
+  assert.throws(() => swipePayloadFromPositionals(['1', '2', '3', '4', '5', '6']), {
+    code: 'INVALID_ARGS',
+    message: 'swipe accepts 4 arguments: x1 y1 x2 y2.',
+  });
+  assert.throws(() => swipePayloadFromPositionals(['1', '2', '3', '4', '--unknown']), {
+    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', () => {
+  assert.equal(
+    describeReplayGestureArityError('swipe', ['197', '650', '197', '300', '300'], '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 300" for the same timed drag, or "swipe 197 650 197 300" for a default-duration swipe.',
+  );
+  assert.equal(
+    describeReplayGestureArityError('gesture', ['pan', '110', '443', '48', '0', '500'], 'line 2'),
+    undefined,
+  );
+  assert.equal(describeReplayGestureArityError('click', ['120', '240'], 'line 2'), undefined);
+});
+
+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.
+  assert.equal(
+    describeReplayGestureArityError('swipe', ['${X1}', '${Y1}', '${X2}', '${Y2}'], 'line 3'),
+    undefined,
+  );
+  assert.equal(
+    describeReplayGestureArityError('gesture', ['${KIND}', '1', '2', '3'], 'line 4'),
+    undefined,
+  );
+});
+
 test('pinch and rotate syntax rejects a partial origin', () => {
   assert.throws(() => gesturePayloadFromPositionals(['pinch', '1.5', '100']), {
     code: 'INVALID_ARGS',