Skip to content

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

Open
Varshith-Kali wants to merge 1 commit into
e2e-inc:mainfrom
Varshith-Kali:fix/1637-stale-tap-after-dispatch
Open

Varshith-Kali wants to merge 1 commit into
e2e-inc:mainfrom
Varshith-Kali:fix/1637-stale-tap-after-dispatch

Conversation

@Varshith-Kali

@Varshith-Kali Varshith-Kali commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

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.

View guided diff

staleOr turned every agent-device stale-ref refusal into retryable NODE_STALE, including one raised after the press was sent (during the post-tap settle). performUntil then re-resolved the node, which the tap had already removed from the screen, and waited out the whole action timeout before failing with LOCATOR_NOT_FOUND.

A stale-ref refusal is retryable NODE_STALE only when agent-device proves nothing reached the device (details.dispatched: 'no'). When dispatch is unproven ('unknown' or missing), the gesture may already have landed, so the engine reports ACTION_MAY_HAVE_COMMITTED and the runner never sends it again, matching the engine contract in docs/reference/engine.mdx and the target_still_moving rule beside it.

This also changes the Android blocking-dialog recovery shape (a drag refused before the gesture but reported as dispatched: 'unknown'): the engine cannot prove the drag never ran, so it now fails closed the same way instead of retrying.

Tests: stale-ref refusals with unproven dispatch map to ACTION_MAY_HAVE_COMMITTED; a press failing that way through the engine is reported once and never re-sent.

Fixes e2e-inc#1637.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
@github-actions github-actions Bot added needs:compliance Community PR fails CONTRIBUTING.md#pull-requests, closed after 72h if not fixed size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile labels Nov 8, 2026

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 4 files

View guided diff | Re-trigger cubic

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review (agent-run triage).

Thanks for picking this up so fast, and for writing the tests first. Bad news, and it's on us: the root cause in our comment on #1637 was wrong, and this PR follows it. I'm correcting it there too.

Why this doesn't fix #1637

  • staleOr has one call site, packages/mobile/src/surface.ts:1186. It classifies by details.reason, not by text, and has done so since #801 (e2e 0.17). The "text pattern" premise is out of date.
  • In agent-device, every stale-ref reason (ref_not_found, ref_frame_expired, ...) is raised by the admission check, before the gesture runs. Press and fill mark that refusal dispatched: 'no'. No path raises a stale reason after the gesture.
  • So the new fixture (ref_frame_expired + dispatched: 'unknown' after a press) is a shape agent-device never sends for a landed tap. We still don't know which error #1637 actually hit.

Regression (must fix)

  • The only real stale-ref + unknown shape is Android blocking-dialog recovery. The ref is re-checked and the command returns before the gesture. unknown comes from the recovery tap on the dialog, not from the requested action. That's why main pinned it retryable (#1297, comment removed in this diff).
  • This PR turns that provably-not-sent case into a non-retryable ACTION_FAILED for press, fill and drag.
  • dispatched is the wrong signal here. The proper fix is upstream: agent-device should mark the dialog-recovery refusal dispatched: 'no'. After that, gating every stale reason on 'no' would be safe.

If the PR continues after #1637 has the real error

  • Collapse the two NODE_STALE constructions in errors.ts into one rule: retryable reasons gated on 'no', then the fallback.
  • The message suffix "so it was not sent again" describes runner behavior. The engine never re-sends, so drop it.
  • engine.test.ts toHaveLength(3) counts presses across the whole test, so it doesn't prove "sent once". A test should drive performUntil with the real failing shape.
  • Changeset: one short user-facing line, no internals.
  • Body: add ## Verified (pr-policy closes the PR after 72h without it).
  • Nits: the drawer explanation is repeated 4 times. The dispatched column in the errors.test.ts it.each is now constant. The doc table rows are misaligned.

Suggest parking this until the reporter shares the exact NODE_STALE message and the agent-device version on #1637. If that points to agent-device (a lost reply or replay path), the fix belongs there, not in staleOr.

@Varshith-Kali

Copy link
Copy Markdown
Contributor Author

Thanks for the correction, and for catching this before it merged. You are right: the premise I built on was wrong, and this change as written turns the Android dialog-recovery case (provably not sent, pinned retryable since #1297) into a non-retryable failure. That is a regression, so this PR should not merge in its current form.

Parking it as suggested until arekkubaczkowski shares the exact NODE_STALE message and the agent-device versions on #1637. Once that lands I will rework it along the lines in your review: collapse the two NODE_STALE constructions into one rule, drop the "so it was not sent again" suffix, drive performUntil with the real failing shape in the engine test, one short user-facing changeset line, and keep the ## Verified section I just added to the body. If the error turns out to be an agent-device lost reply or replay, the fix belongs there, not in staleOr, and I will say so rather than force this PR through.

@github-actions github-actions Bot removed the needs:compliance Community PR fails CONTRIBUTING.md#pull-requests, closed after 72h if not fixed label Nov 9, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile

Projects

None yet

Development

Successfully merging this pull request may close these issues.

performUntil retries a tap that already reached the app after NODE_STALE, then fails with LOCATOR_NOT_FOUND after the full timeout

2 participants