fix(mobile): report a stale ref after dispatch as possibly committed

VA
7d ago
+72-12

Fixes #1637, following the direction in the maintainer review.

The mobile engine broke the perform contract in docs/reference/engine.mdx. staleOr (packages/mobile/src/errors.ts) wrapped the whole perform call and turned any agent-device error matching a stale-ref text pattern into retryable NODE_STALE, including errors raised after the press was sent, for example during the post-tap settle. performUntil then re-resolved a node the tap had already removed and waited out the whole action timeout before failing LOCATOR_NOT_FOUND, even though the tap had succeeded.

The fix classifies a stale-ref refusal as retryable NODE_STALE only when agent-device proves nothing reached the device (details.dispatched: no). When dispatch is unproven (unknown or missing), the engine reports ACTION_MAY_HAVE_COMMITTED, which performUntil already never repeats, so the tap is sent once and the step fails at once instead of burning the timeout. No change to packages/e2e was needed.

Honest limitation: when the tap landed but the stale report arrived, the step still fails, just fast and honestly (ACTION_FAILED, naming the possible commit). Agent-device reports dispatched: unknown, so it cannot prove the tap landed and the engine must not claim success. The caller observes the device and decides.

One deliberate tradeoff: the Android dialog-recovery drag (dispatched: unknown, pinned retryable since #1297) now fails closed the same way, since the engine cannot prove that drag never ran.

Tests: 3 new regression tests, written first, failed on unmodified code and pass with the fix (2 in errors.test.ts, 1 in engine.test.ts), including a fake agent-device press throwing ref_frame_expired with dispatched: unknown returning ACTION_MAY_HAVE_COMMITTED, non-retryable, with the press sent exactly once. Full @e2e-dev/mobile unit suite: 20 files, 501 tests, all pass. tsc clean, oxlint clean on the changed files. Changeset added (patch bump for @e2e-dev/mobile).

Verified

  • 3 new regression tests, written first: failed on unmodified code (2 in errors.test.ts, 1 in engine.test.ts), pass with the fix.
  • Full @e2e-dev/mobile unit suite: 20 files, 501 tests, all pass.
  • packages/e2e unit (locator-engine + engine-error suites): 94 tests, all pass.
  • tsc --noEmit clean; oxlint clean on the changed files.
  • No live device run: the regression tests use the repo's fake agent-device client.