Problem

An agent step like agent.act('open the first post in the "Your inbox" list') taps a row that shares its test id with every other row. Recorded on Android with @e2e-dev/mobile 0.12.2 and e2e 0.21.1, the target is:

{ "role": "group", "testId": "inbox-item", "selector": "id=inbox-item", "within": "<title of the first post>" }

Each row sits in its own wrapper, so containerKey keys it by the row's own title and describePosition counts one match inside it, so no position is recorded. The recording means "the row titled X", while the instruction meant "the first row". Once a new post tops the inbox, the step hands off as target-not-found. Without within it would fare no better: the test id matches every row, and a recorded position holds only while the row count stays the same. Against a live backend the top of the inbox changes often, so the step keeps going back to the model. "Reply to the last message" in a thread has the same shape.

That fail-closed behaviour is deliberate, and I agree with it as the default. A recording can't tell "the first row" from "the row that happened to be first", and #637 explains why a lone survivor of a recorded set is ambiguous. What's missing is a way for the test author to say the step means a position.

For comparison, Maestro makes position part of the selector: index: 0 takes the first match in y-then-x order, a negative index counts from the end, and the match count is never checked. Trailblaze's index selector is also a plain position at replay.

Proposed API

await agent.act('open the first post in the feed', { position: 'first' });
await agent.act('reply to the last message', { position: 'last' });

The option is recorded with the entry, and the target is recorded without within. On replay it resolves to the first (or last) node carrying that test id, in document order, whatever their count. Without the option, nothing changes. A config key for the whole suite would also work, if you'd rather not widen act.

If this would fit better as a rung in #805, that works for us too.

Which surface

public types (SDK), report or cache format