From 331a95faa41f8afee6c9845b5e859e1919b623cd Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:28:30 -0400
Subject: [PATCH 01/10] feat(expo): stop a run of failing tests early with
 --max-failures

A build whose app never reaches its home fails every test of
`integration/expo-native/` the same way. Each test waits 60 seconds for
the home, and CI tries it twice, so the run spent about two minutes on
each of its tests before it could say that the build is broken.

`run` now takes `--max-failures <n>` and passes it to e2e. e2e stops
once `n` tests have failed and reports the tests it did not start as
skipped by the limit. The CLI already turns such a skip into a failed
result that says `not run: failure-limit`, and a new test pins that, so
a test the limit stopped never counts as passed.

`run` starts e2e once for each settings group, so the limit counts the
failures of one group, and the groups after it still start.

The workflow passes 5 on each platform. None of its last 40 runs
failed, so a healthy build stays far below the limit. The changeset is
empty, as it is in the other pull requests of the stack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/expo-verify-e2e-small-fixes.md |  2 ++
 .claude/skills/verify-clerk-expo/SKILL.md |  4 ++--
 .github/workflows/verify-e2e.yml          |  2 +-
 integration/expo-native/src/core/MANIFEST |  6 ++---
 integration/expo-native/src/core/cli.ts   |  7 ++++--
 integration/expo-native/src/core/e2e.ts   |  1 +
 integration/expo-native/src/core/types.ts |  1 +
 integration/expo-native/test/cli.test.ts  |  2 ++
 integration/expo-native/test/e2e.test.ts  | 27 +++++++++++++++++++++--
 9 files changed, 42 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/expo-verify-e2e-small-fixes.md

diff --git a/.changeset/expo-verify-e2e-small-fixes.md b/.changeset/expo-verify-e2e-small-fixes.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/expo-verify-e2e-small-fixes.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index 8b0cebbda83..6abeb72d1fc 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -110,7 +110,7 @@ $ integration/expo-native/bin/control-clerk-expo run native-auth-view native-js-
 $ integration/expo-native/bin/control-clerk-expo screen --platform ios                        # the UI tree that is on screen now; --png adds a screenshot
 ```
 
-`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a failed test again, up to `n` more times. The default is 0, so a run of your own change shows exactly what happened. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
+`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a failed test again, up to `n` more times. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
 
 For a JS change on a local device, edit the source and `run` the spec, with no `up` in between. For a change to a native input, the same `run` rebuilds the dev client first. On a remote device, commit and push, then `run`.
 
@@ -270,7 +270,7 @@ For a remote device, `down` ends the runner job and waits for it to finish, and
 - `src/host.ts`, `src/fixture.ts`, `src/native-build.ts`, and `src/freshness.ts` are this repository's own: the build of the test app, the native build that CI keeps between runs, the Metro ports, and the check that Metro serves current JS. `specs/app.ts` names the test app and its entry for a dev client, and `specs/native.ts` holds the per-platform locators for the native views and the locators of the home's links. Both are this repository's own too.
 - `npm test --prefix integration/expo-native` runs the CLI's unit tests, with no network, key, or device. `npm run typecheck --prefix integration/expo-native` runs `tsc`. The `Expo Native Runner Tests` job in `.github/workflows/ci.yml` runs both on Linux when a pull request changes the package, the test app, or a package the test app links.
 - `run --github-report` hands the results of the run to `@e2e-dev/github` as one report. The reporter writes the report to the job summary. With a `GITHUB_TOKEN` that may write pull request comments, it also posts one comment on the pull request and updates that comment on later runs. The reporter never changes the exit code, and nothing is reported for a run with a tainted file.
-- `.github/workflows/verify-e2e.yml`, the `Verify end-to-end tests` workflow, runs `up --backend local`, `run --all --retries 1 --github-report`, and `down` on a runner for each platform, with a device and a Clerk application for each. It starts on a pull request to `main` that changes the package, the test app, or one of the four packages the test app links. It runs for a pull request that is not a draft, and a draft or a pull request from a fork gets a notice instead. Start it by hand with `gh workflow run verify-e2e.yml --ref <branch>`. A failing spec shows on the pull request and is not required for a merge, and a test that fails and then passes on its one retry is `flaky` and does not fail the job. The runners are GitHub-hosted, `macos-26` and `ubuntu-24.04`, and the repository variables `VERIFY_CI_RUNNER_IOS` and `VERIFY_CI_RUNNER_ANDROID` name other labels. The Platform API key comes from the `MOBILE_VERIFICATION_PLATFORM_API_KEY` repository secret. The workflow sets `VERIFY_LOCAL_BUILD=standalone` and `VERIFY_NATIVE_CACHE` ([freshness.md](references/freshness.md)). It uploads each run's `run.json`, app log, driver logs, video, screenshots, and e2e's `report.json`, `junit.xml`, summary, and failure pages for three days, and only when no secret is found in the run. `bin/boot-ios-simulators.sh wait` waits until a booted simulator is ready, and this workflow and `.github/workflows/verify-remote.yml` call it.
+- `.github/workflows/verify-e2e.yml`, the `Verify end-to-end tests` workflow, runs `up --backend local`, `run --all --retries 1 --max-failures 5 --github-report`, and `down` on a runner for each platform, with a device and a Clerk application for each. It starts on a pull request to `main` that changes the package, the test app, or one of the four packages the test app links. It runs for a pull request that is not a draft, and a draft or a pull request from a fork gets a notice instead. Start it by hand with `gh workflow run verify-e2e.yml --ref <branch>`. A failing spec shows on the pull request and is not required for a merge, and a test that fails and then passes on its one retry is `flaky` and does not fail the job. The runners are GitHub-hosted, `macos-26` and `ubuntu-24.04`, and the repository variables `VERIFY_CI_RUNNER_IOS` and `VERIFY_CI_RUNNER_ANDROID` name other labels. The Platform API key comes from the `MOBILE_VERIFICATION_PLATFORM_API_KEY` repository secret. The workflow sets `VERIFY_LOCAL_BUILD=standalone` and `VERIFY_NATIVE_CACHE` ([freshness.md](references/freshness.md)). It uploads each run's `run.json`, app log, driver logs, video, screenshots, and e2e's `report.json`, `junit.xml`, summary, and failure pages for three days, and only when no secret is found in the run. `bin/boot-ios-simulators.sh wait` waits until a booted simulator is ready, and this workflow and `.github/workflows/verify-remote.yml` call it.
 - The `Expo` workflow, `.github/workflows/expo-native-build.yml`, runs nothing on a device. It builds the test app as a Release app on Expo SDK 54, 55, and 57 for each platform, and runs the Android unit tests of `@clerk/expo-biometrics`.
 - `.github/workflows/verify-attach.yml` publishes the evidence that `attach` hands to a session's runner, with `scripts/verify-attach.mjs`. It reads the manifest that `src/core/remote/handoff.ts` writes. It and `src/core/publish.ts` each replace the block the other wrote, each applies the same rules to the comments and to the start of the line, and each lays the files out in the same tables. The script is checked out alone, so it imports nothing from the package. So a change to the manifest, the comments, those rules, or the tables is a change in both places. `scripts/verify-attach.test.mjs` has its tests.
 - A remote session runs in `.github/workflows/verify-remote.yml`. `src/platform/session-device.ts` holds the steps that the session runs on its device, and `src/core/remote/` is the code on both ends of it. The runner installs the package with `npm ci`. A session keeps the code under `src/core/` from the commit it started on, so after a change to a file that `src/core/MANIFEST` lists, commit, push, `down`, then `up`.
diff --git a/.github/workflows/verify-e2e.yml b/.github/workflows/verify-e2e.yml
index 79abdf9d707..4ff977bdd09 100644
--- a/.github/workflows/verify-e2e.yml
+++ b/.github/workflows/verify-e2e.yml
@@ -239,7 +239,7 @@ jobs:
           CLERK_PLATFORM_API_KEY: ${{ secrets.MOBILE_VERIFICATION_PLATFORM_API_KEY }}
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          "$CLI" run --all --platform "$PLATFORM" --backend local --retries 1 --github-report
+          "$CLI" run --all --platform "$PLATFORM" --backend local --retries 1 --max-failures 5 --github-report
 
       - name: Release the device and delete the Clerk application
         if: always() && steps.install.outcome == 'success'
diff --git a/integration/expo-native/src/core/MANIFEST b/integration/expo-native/src/core/MANIFEST
index b78165fc7a5..eb888eab3cc 100644
--- a/integration/expo-native/src/core/MANIFEST
+++ b/integration/expo-native/src/core/MANIFEST
@@ -17,10 +17,10 @@ df955a42a2bd4ca1780f56837ebb9c832c68e97f74a35764d42a32e44b28286b  specs/support/
 d56c29efc8061adfd65b89f0f02465af3234ecd52289ef6d9f338483afeadeb5  src/core/broker.ts
 7c741449c755524bba80f1ce314554293003a34f7f7c30696015ba1c0c3dc1ab  src/core/claims.ts
 1fc59d13e7197e6c7099c0467744b978d498d1fe409c88254d44e2f99913a7b5  src/core/clerk.ts
-6eef5f3989f8e29771fb47ec1b3721699249ea272e5009ccf8e66ece9981c4e6  src/core/cli.ts
+8d0fb398aec4187b15b82ef88142b0a548f0ff4a0d26902c3e01ea0659283236  src/core/cli.ts
 4aeacea985f5ef80001e5695feec53182abb9695eb07130898568743755fc8af  src/core/devices.ts
 3ae461d6aa75a2cefac0392a9ad124aec4105ac25b9320371743e2ea90fe2202  src/core/driver.ts
-efc4cdabcd1b00e903bfcfeb077016f1654c07ef4926b6389d248227c12c0af5  src/core/e2e.ts
+14e74b156592a645ae579e3a8f900c5bb0a8be487adfacd4ff94ca268ce0dbdf  src/core/e2e.ts
 c9a29e27eb835d9c3fc9b0bd394ff55b5f1fcc2b2fc0d96da51197e5e7bca003  src/core/evidence.ts
 27bfd4ce59937aa8c97d9fd6849cf52f3da05626fbc9388385f4b5e684577d36  src/core/exec.ts
 e2075f17f52ded8dea64d8a2473820396ca5ac1a22db59f21a092da28e55911f  src/core/github-report.ts
@@ -47,6 +47,6 @@ d614ee5c98a85d15037b744a67404496273f62985fd7d6a049cacfd5ab335503  src/core/remot
 e734336ea3b345057b69193790e2efce9a662c67ec5b4a426c811f999b45ccdb  src/core/remote/tunnel.ts
 685eabf010c7f63d076cfd3da1a681b5cc8024720538c1bf3a99792b563d8b60  src/core/slot.ts
 a8838aaf1fa9e4a6bc4e350ea674079201da76c5962656039b96db2505591aed  src/core/state.ts
-25501a3117a814fb9e0cd4a00a4ecaf33a28e589b0a0e22679ab660736846b15  src/core/types.ts
+b242eff9cb23ed78af02190a7decd47d8299089996648b6f0c2540ca2fe4c0d1  src/core/types.ts
 79b822b663c1ac1748cf3c8ec390ef9204378f4c97531f4da9b0bf5736a20d36  src/core/verbs.ts
 9be1816773216373548ec9933978b53ace3d3bfdba17b72c1e5ed6d8aef80f62  src/core/workspace.ts
diff --git a/integration/expo-native/src/core/cli.ts b/integration/expo-native/src/core/cli.ts
index 3a03155f903..a288fe92ba7 100644
--- a/integration/expo-native/src/core/cli.ts
+++ b/integration/expo-native/src/core/cli.ts
@@ -31,7 +31,7 @@ const VERBS: readonly Verb[] = ['doctor', 'up', 'run', 'screen', 'attach', 'down
 const USAGE_FIX = [
   '{cli} doctor [--platform p] [--backend auto|local|remote] [--live [--runner <label>]]',
   '{cli} up [--platform p] [--backend auto|local|remote] [--runner <label>] [--wait <seconds>]',
-  '{cli} run <feature|feature/spec|path.e2e.ts>... | --all [--platform p] [--backend auto|local|remote] [--runner <label>] [--grep re] [--retries <n>] [--github-report] [--no-video] [--wait <seconds>]',
+  '{cli} run <feature|feature/spec|path.e2e.ts>... | --all [--platform p] [--backend auto|local|remote] [--runner <label>] [--grep re] [--retries <n>] [--max-failures <n>] [--github-report] [--no-video] [--wait <seconds>]',
   '{cli} screen [--platform p] [--png]',
   '{cli} attach <run-id> --pr <n> [--screenshot <label>]... [--video] [--before <run-id>], with at least one of --screenshot and --video',
   '{cli} down [--platform p] [--stale] [--dry-run]',
@@ -52,7 +52,7 @@ type FlagSpec = Readonly<Record<string, 'value' | 'bool' | 'list'>>;
 const FLAGS: Readonly<Record<Verb, FlagSpec>> = {
   doctor: { platform: 'value', backend: 'value', runner: 'value', live: 'bool' },
   up: { platform: 'value', backend: 'value', runner: 'value', wait: 'value' },
-  run: { platform: 'value', backend: 'value', runner: 'value', all: 'bool', grep: 'value', retries: 'value', 'github-report': 'bool', 'no-video': 'bool', wait: 'value' },
+  run: { platform: 'value', backend: 'value', runner: 'value', all: 'bool', grep: 'value', retries: 'value', 'max-failures': 'value', 'github-report': 'bool', 'no-video': 'bool', wait: 'value' },
   screen: { platform: 'value', png: 'bool' },
   attach: { pr: 'value', screenshot: 'list', video: 'bool', before: 'value' },
   down: { platform: 'value', stale: 'bool', 'dry-run': 'bool' },
@@ -145,6 +145,8 @@ export function parseArgv(argv: readonly string[]): Invocation {
       if (!all && positionals.length === 0) throw usage('{cli} run needs a feature, feature/spec, path.e2e.ts, or --all');
       const grep = values.get('grep');
       const retries = positiveInt('retries', values.get('retries'), 0);
+      const maxFailures = values.has('max-failures') ? positiveInt('max-failures', values.get('max-failures'), undefined) : undefined;
+      if (maxFailures === 0) throw usage('--max-failures must be 1 or more');
       command = {
         verb,
         ...base,
@@ -152,6 +154,7 @@ export function parseArgv(argv: readonly string[]): Invocation {
         ...(grep === undefined ? {} : { grep }),
         video: !bools.has('no-video'),
         retries,
+        ...(maxFailures === undefined ? {} : { maxFailures }),
         githubReport: bools.has('github-report'),
         waitSeconds: positiveInt('wait', values.get('wait'), 0),
       };
diff --git a/integration/expo-native/src/core/e2e.ts b/integration/expo-native/src/core/e2e.ts
index c473c6b9aa7..eea3a407921 100644
--- a/integration/expo-native/src/core/e2e.ts
+++ b/integration/expo-native/src/core/e2e.ts
@@ -100,6 +100,7 @@ export function planE2E(inputs: Inputs, specs: readonly SpecRef[], command: RunC
     '--retries',
     String(command.retries),
     ...(command.grep === undefined ? [] : ['--grep', command.grep]),
+    ...(command.maxFailures === undefined ? [] : ['--max-failures', String(command.maxFailures)]),
     '--pass-with-no-tests',
   ];
   return { args, env: { ...inputsEnv(inputs), AGENT_DEVICE_STATE_DIR: agentDeviceStateDir(join(packageDir, WORKSPACE_DIR)), E2E_TELEMETRY_DISABLED: '1' } };
diff --git a/integration/expo-native/src/core/types.ts b/integration/expo-native/src/core/types.ts
index 20a97f7c862..d51f6822b23 100644
--- a/integration/expo-native/src/core/types.ts
+++ b/integration/expo-native/src/core/types.ts
@@ -65,6 +65,7 @@ export type Command =
       readonly grep?: string;
       readonly video: boolean;
       readonly retries: number;
+      readonly maxFailures?: number;
       readonly githubReport: boolean;
       readonly waitSeconds: number;
     }
diff --git a/integration/expo-native/test/cli.test.ts b/integration/expo-native/test/cli.test.ts
index a3606f4723d..51e94d64113 100644
--- a/integration/expo-native/test/cli.test.ts
+++ b/integration/expo-native/test/cli.test.ts
@@ -47,6 +47,8 @@ describe('parseArgv', () => {
     assert.equal((parseArgv(['run', '--all', '--retries', '1']).command as Extract<Command, { verb: 'run' }>).retries, 1);
     assert.equal((parseArgv(['run', '--all', '--github-report']).command as Extract<Command, { verb: 'run' }>).githubReport, true);
     for (const bad of ['-1', 'once']) assert.throws(() => parseArgv(['run', '--all', '--retries', bad]), { code: 'USAGE' }, bad);
+    assert.equal((parseArgv(['run', '--all', '--max-failures', '5']).command as Extract<Command, { verb: 'run' }>).maxFailures, 5);
+    for (const bad of ['0', '-1', 'none']) assert.throws(() => parseArgv(['run', '--all', '--max-failures', bad]), { code: 'USAGE' }, bad);
     assert.deepEqual(parseArgv(['screen', '--png']).command, { verb: 'screen', png: true });
     assert.deepEqual(parseArgv(['attach', 'r20261002-141210-7c1e', '--pr', '412', '--screenshot', 'a', '--screenshot=b']).command, {
       verb: 'attach',
diff --git a/integration/expo-native/test/e2e.test.ts b/integration/expo-native/test/e2e.test.ts
index 34e68e03fb5..1a1ece31f00 100644
--- a/integration/expo-native/test/e2e.test.ts
+++ b/integration/expo-native/test/e2e.test.ts
@@ -34,11 +34,11 @@ describe('resolveSpecs', () => {
 
 describe('planE2E', () => {
   it('passes selection flags through and points output inside the run', () => {
-    const plan = planE2E(SAMPLE_INPUTS, [{ kind: 'committed', path: 'specs/features/a/b.e2e.ts', feature: null }], { verb: 'run', selection: { all: true }, grep: 'x', video: true, retries: 1, githubReport: false, waitSeconds: 0 }, '/package', e2eOutputDir('/package/.verify/runs/r20261002-141210-7c1e' as EvidencePath, 0));
+    const plan = planE2E(SAMPLE_INPUTS, [{ kind: 'committed', path: 'specs/features/a/b.e2e.ts', feature: null }], { verb: 'run', selection: { all: true }, grep: 'x', video: true, retries: 1, maxFailures: 5, githubReport: false, waitSeconds: 0 }, '/package', e2eOutputDir('/package/.verify/runs/r20261002-141210-7c1e' as EvidencePath, 0));
     assert.deepEqual(plan.args, [
       'run', 'specs/features/a/b.e2e.ts', '--config', 'e2e.config.ts', '--target', 'ios',
       '--output', '.verify/runs/r20261002-141210-7c1e/e2e', '--reporter', 'list,markdown,junit', '--retries', '1',
-      '--grep', 'x', '--pass-with-no-tests',
+      '--grep', 'x', '--max-failures', '5', '--pass-with-no-tests',
     ]);
     assert.deepEqual(plan.env, {
       CLERK_E2E_PLATFORM: 'ios',
@@ -54,6 +54,7 @@ describe('planE2E', () => {
     const later = planE2E(SAMPLE_INPUTS, [], { verb: 'run', selection: { all: true }, video: true, retries: 0, githubReport: false, waitSeconds: 0 }, '/package', e2eOutputDir('/package/.verify/runs/r20261002-141210-7c1e' as EvidencePath, 2));
     assert.equal(later.args[later.args.indexOf('--output') + 1], '.verify/runs/r20261002-141210-7c1e/e2e-3', 'a later group of the run writes beside the first');
     assert.equal(later.args[later.args.indexOf('--retries') + 1], '0', 'e2e retries once by default when CI is set, so the run always says how many it wants');
+    assert.equal(later.args.includes('--max-failures'), false, 'a run that names no limit runs every test');
     assert.equal(later.args.includes('--pass-with-no-tests'), true, 'every invocation is one group of a run, and a group with nothing left to run must not fail it');
   });
 });
@@ -148,6 +149,28 @@ describe('parseE2EReport', () => {
     assert.equal(results[4]!.failurePage, join(dir, 'failures', 'specs_explored_probe-fails-cccccccc.md'));
   });
 
+  it('reports a test that --max-failures stopped before it started as failed and not run, never as passed or skipped', () => {
+    const test = (id: string, file: string, rest: object) => ({ id, kind: 'test', titlePath: [id], file, platform: 'ios', tags: [], ...rest });
+    const stopped = {
+      schemaVersion: 'report-1',
+      run: {
+        results: [
+          test('aaaaaaaa11', 'specs/features/auth-start/opens.e2e.ts', { status: 'failed', attempts: [{ status: 'failed', durationMs: 60_000, error: { message: 'the app did not show the "Sign in" button on the home' } }] }),
+          test('bbbbbbbb22', 'specs/features/sign-up/complete.e2e.ts', { status: 'skipped', skip: { cause: 'failure-limit', reason: 'run stopped after 1 failure (--max-failures 1)' }, attempts: [] }),
+        ],
+      },
+    };
+    const specs = ['specs/features/auth-start/opens.e2e.ts', 'specs/features/sign-up/complete.e2e.ts'].map((path): SpecRef => ({ kind: 'committed', path, feature: null }));
+    const results = parseE2EReport(stopped, specs, mkdtempSync(join(tmpdir(), 'verify-report-')) as EvidencePath);
+    assert.deepEqual(
+      results.map((r) => ({ status: r.status, attempts: r.attempts, error: r.error, skipReason: r.skipReason })),
+      [
+        { status: 'failed', attempts: 1, error: 'the app did not show the "Sign in" button on the home', skipReason: null },
+        { status: 'failed', attempts: 0, error: 'not run: failure-limit run stopped after 1 failure (--max-failures 1)', skipReason: null },
+      ],
+    );
+  });
+
   it('refuses a report of another schema', () => {
     assert.throws(() => parseE2EReport({ schemaVersion: 'report-2', run: { results: [] } }, [], '/x' as EvidencePath), { code: 'E2E_CRASHED' });
   });

From a964a3786d74873ae71d6d666acf237382fa3757 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:28:44 -0400
Subject: [PATCH 02/10] docs(expo): say which failures --retries runs again

The skill said that `--retries <n>` runs a failed test again. e2e runs
a test again only when an assertion failed, the test threw an error, or
the test ran out of time (`isRetryEligible` in e2e 0.18.0). A failure
of the device driver gets one attempt, so a reader took a driver failure
that ran once for a test that failed twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index 6abeb72d1fc..753ec02e990 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -110,7 +110,7 @@ $ integration/expo-native/bin/control-clerk-expo run native-auth-view native-js-
 $ integration/expo-native/bin/control-clerk-expo screen --platform ios                        # the UI tree that is on screen now; --png adds a screenshot
 ```
 
-`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a failed test again, up to `n` more times. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
+`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure of the device driver or of e2e itself, such as a screenshot that agent-device could not take or a launch that timed out, gets one attempt whatever `n` is. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
 
 For a JS change on a local device, edit the source and `run` the spec, with no `up` in between. For a change to a native input, the same `run` rebuilds the dev client first. On a remote device, commit and push, then `run`.
 

From 87012327590968ea7fc90af0b2b1bfe7b6eb3fcd Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:29:06 -0400
Subject: [PATCH 03/10] test(expo): give each screenshot of the committed specs
 its own label

Three labels were used twice: `signed-in`, `signed-out` and
`restored-home`. A run keeps one file for a label, so `run --all` kept
one screenshot of each pair. One of each pair has a new label:
`signed-in-from-native` and `signed-out-from-native` in
`native-js-sync`, and `restored-home-after-relaunch` in
`token-cache-persistence`. The feature pages name the new labels.

A new test reads the committed specs and fails when two of them use one
label, and names the label and the files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../verify-clerk-expo/features/native-js-sync.md |  4 ++--
 .../features/token-cache-persistence.md          |  2 +-
 .../native-js-sync/sign-in-from-native.e2e.ts    |  2 +-
 .../native-js-sync/sign-out-from-native.e2e.ts   |  2 +-
 .../token-cache-persistence/relaunch.e2e.ts      |  2 +-
 integration/expo-native/test/e2e.test.ts         | 16 +++++++++++++++-
 6 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/.claude/skills/verify-clerk-expo/features/native-js-sync.md b/.claude/skills/verify-clerk-expo/features/native-js-sync.md
index 4dcabaf0be4..f356fcbb454 100644
--- a/.claude/skills/verify-clerk-expo/features/native-js-sync.md
+++ b/.claude/skills/verify-clerk-expo/features/native-js-sync.md
@@ -21,8 +21,8 @@ Preconditions:
 
 - Each spec seeds a `+clerk_test` user. The sign-out spec starts signed in through a ticket, because it tests no sign-in. The sign-in spec starts signed out and signs in through the real form.
 
-- **Native sign-out.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-out-from-native --platform ios`, and again with `--platform android`. The spec launches signed in, taps the UserButton, taps `Sign out` in the profile, and calls `host.expectSignedOut`. That waits for the home to show `Signed out` (from `useAuth`), with no `Signed in as` text and no user ID (from `useUser`) and no session ID (from `useSession`). Screenshots `before-sign-out` and `signed-out`.
-- **Native sign-in.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-in-from-native --platform ios`, and again with `--platform android`. Both tests seed a user with `host.seedUser({ password: true })`, tap `Sign in` on the home, and sign in with `signInWithPassword` from `specs/native.ts`. The first test expects the home to show the user and a session ID, relaunches with `keepStorage`, and expects the same user and the same session ID. Screenshots `signed-in` and `restored-home`. The second test signs out with the profile's `Sign out` row, signs in again, and expects the home to show the user. Screenshot `signed-in-again`.
+- **Native sign-out.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-out-from-native --platform ios`, and again with `--platform android`. The spec launches signed in, taps the UserButton, taps `Sign out` in the profile, and calls `host.expectSignedOut`. That waits for the home to show `Signed out` (from `useAuth`), with no `Signed in as` text and no user ID (from `useUser`) and no session ID (from `useSession`). Screenshots `before-sign-out` and `signed-out-from-native`.
+- **Native sign-in.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-in-from-native --platform ios`, and again with `--platform android`. Both tests seed a user with `host.seedUser({ password: true })`, tap `Sign in` on the home, and sign in with `signInWithPassword` from `specs/native.ts`. The first test expects the home to show the user and a session ID, relaunches with `keepStorage`, and expects the same user and the same session ID. Screenshots `signed-in-from-native` and `restored-home`. The second test signs out with the profile's `Sign out` row, signs in again, and expects the home to show the user. Screenshot `signed-in-again`.
 - **Proof.** `screenshots/signed-out.png` shows the home with `Signed out` and the `Sign in` button. The native profile closes by itself, because the UserButton that presented it leaves the home.
 
 ## Gotchas
diff --git a/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md b/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
index d8745ef0c07..a777e1bc8cf 100644
--- a/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
+++ b/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
@@ -18,7 +18,7 @@ Preconditions:
 
 - The spec seeds a `+clerk_test` user and signs in with a ticket on the first launch.
 
-- **Relaunch.** Run `integration/expo-native/bin/control-clerk-expo run token-cache-persistence --platform android` (or `ios`). The spec launches signed in and reads the session ID on the home. It relaunches with `keepStorage: true` and no ticket, and expects the home to show the same user and the same session ID. Screenshot `restored-home`.
+- **Relaunch.** Run `integration/expo-native/bin/control-clerk-expo run token-cache-persistence --platform android` (or `ios`). The spec launches signed in and reads the session ID on the home. It relaunches with `keepStorage: true` and no ticket, and expects the home to show the same user and the same session ID. Screenshot `restored-home-after-relaunch`.
 - **Kept token.** On that relaunched home the test taps `Token cache` and expects `client token kept from the last launch: yes` and `user: <the seeded user ID>`. Screenshot `token-cache`.
 - **New scope.** The same test relaunches with a new storage scope, taps `Token cache` on the signed-out home, and expects `client token kept from the last launch: no` and `user: none`. Screenshot `new-scope`.
 - **Proof.** `screenshots/restored-home.png` shows the user and the session after a launch that had no ticket, and `screenshots/token-cache.png` shows the kept token.
diff --git a/integration/expo-native/specs/features/native-js-sync/sign-in-from-native.e2e.ts b/integration/expo-native/specs/features/native-js-sync/sign-in-from-native.e2e.ts
index 378db0ef68a..3912cbf6c8a 100644
--- a/integration/expo-native/specs/features/native-js-sync/sign-in-from-native.e2e.ts
+++ b/integration/expo-native/specs/features/native-js-sync/sign-in-from-native.e2e.ts
@@ -8,7 +8,7 @@ test('a native password sign-in reaches the JS hooks and survives a relaunch', a
   await signInWithPassword(host, screen, platform, user);
   await host.expectSignedInAs(user, 45_000);
   const session = (await host.app.sessionId.textContent()) ?? '';
-  await host.screenshot('signed-in');
+  await host.screenshot('signed-in-from-native');
 
   await host.launch({ keepStorage: true, landsOn: host.app.signedIn });
   await host.expectSignedInAs(user);
diff --git a/integration/expo-native/specs/features/native-js-sync/sign-out-from-native.e2e.ts b/integration/expo-native/specs/features/native-js-sync/sign-out-from-native.e2e.ts
index 2b8f1cf168a..7c85b175502 100644
--- a/integration/expo-native/specs/features/native-js-sync/sign-out-from-native.e2e.ts
+++ b/integration/expo-native/specs/features/native-js-sync/sign-out-from-native.e2e.ts
@@ -10,5 +10,5 @@ test('signing out in the native profile signs out the JS hooks', async ({ host,
   await host.screenshot('before-sign-out');
   await host.tap(profile.signOut);
   await host.expectSignedOut(20_000);
-  await host.screenshot('signed-out');
+  await host.screenshot('signed-out-from-native');
 });
diff --git a/integration/expo-native/specs/features/token-cache-persistence/relaunch.e2e.ts b/integration/expo-native/specs/features/token-cache-persistence/relaunch.e2e.ts
index 018515838c0..f0b28390ed5 100644
--- a/integration/expo-native/specs/features/token-cache-persistence/relaunch.e2e.ts
+++ b/integration/expo-native/specs/features/token-cache-persistence/relaunch.e2e.ts
@@ -15,7 +15,7 @@ test('the token cache keeps the session across a relaunch, and a new scope start
   await host.launch({ keepStorage: true, landsOn: host.app.signedIn });
   await host.expectSignedInAs(user);
   await expect(host.app.sessionId).toHaveText(session);
-  await host.screenshot('restored-home');
+  await host.screenshot('restored-home-after-relaunch');
 
   await host.tap(tokenCache);
   await expect(clientToken).toHaveText('client token kept from the last launch: yes', { timeout: 15_000 });
diff --git a/integration/expo-native/test/e2e.test.ts b/integration/expo-native/test/e2e.test.ts
index 1a1ece31f00..0b8a5c198fa 100644
--- a/integration/expo-native/test/e2e.test.ts
+++ b/integration/expo-native/test/e2e.test.ts
@@ -1,6 +1,6 @@
 import '../testing/git-env.ts';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, it } from 'node:test';
@@ -186,6 +186,20 @@ describe('parseE2EReport', () => {
   });
 });
 
+describe('the screenshot labels of the committed specs', () => {
+  it('are each used once, because a run keeps one screenshot for a label', () => {
+    const features = join(import.meta.dirname, '..', 'specs', 'features');
+    const takenIn = new Map<string, string[]>();
+    for (const file of readdirSync(features, { recursive: true, encoding: 'utf8' }).filter((path) => path.endsWith('.e2e.ts'))) {
+      const source = readFileSync(join(features, file), 'utf8');
+      const labels = [...source.matchAll(/\.screenshot\('([^']+)'\)/g)].map((match) => match[1]!);
+      assert.equal(labels.length, source.split('.screenshot(').length - 1, `${file} takes a screenshot whose label is not a plain string`);
+      for (const label of labels) takenIn.set(label, [...(takenIn.get(label) ?? []), file]);
+    }
+    assert.deepEqual([...takenIn].filter(([, files]) => files.length > 1), []);
+  });
+});
+
 describe('MANIFEST', () => {
   it('matches the files, so doctor reports no drift', () => {
     assert.deepEqual(manifestDrift(), []);

From b19bb198e335208e725dfd768173229abb228a5e Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:29:08 -0400
Subject: [PATCH 04/10] test(expo): add host.expectVisible to the fixture

`host.expectVisible(locator, timeoutMs?)` is the wait that
`host.expectSignedInAs` already uses, for any element. It fails at once
on the app's error screen, and on iOS it taps "Not Now" when the "Save
Password?" sheet is in front.

clerk-ios uses it in place of two loops with sleeps in one spec. No
spec here calls it yet. The fixture is one file in clerk-ios,
clerk-android and clerk/javascript, so it changes in all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md      | 2 +-
 integration/expo-native/specs/fixtures.ts      | 2 ++
 integration/expo-native/specs/support/types.ts | 1 +
 integration/expo-native/src/core/MANIFEST      | 4 ++--
 4 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index 753ec02e990..3f88a2b1191 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -139,7 +139,7 @@ test('the home UserButton opens the profile of the signed-in user', async ({ hos
 - `host.seedUser({ phone?, password? })` creates a `+clerk_test` user in the worktree's application. With `password: true` the user also has a password that the run generated for that user, and `user.password` holds it. Pass it to `host.fill`, as `host.fill(field, user.password!)`, and to nothing else. It prints as `<secret:password>`, `run` redacts its value from the logs it writes, and `attach` refuses a run whose files hold it. For a sign-up through the form, `host.newEmail()` returns a new address of this run, and `host.newPhone()` returns a 555-01xx number that no user holds. `host.newEmail()` calls nothing and records nothing. After the tests, `run` finds the user by the run's prefix in the address.
 - `host.launch({ signedInAs?, authMode?, keepStorage?, landsOn? })` relaunches the test app and waits up to 60 seconds for its home. Every launch opens on the home, and a spec taps from there to the screen it needs, as a user does. `authMode` is the mode of every AuthView the home opens: `signIn`, `signUp`, or `signInOrUp`. A launch starts with fresh storage unless `keepStorage` is true, so a launch with no `signedInAs` is signed out and lands on the home's `Sign in` button. `host.launch()` with no argument is that launch. A launch with `signedInAs` lands on the home, which must show that user's email and user ID. When the home should show anything else, pass its locator as `landsOn`. A launch that keeps storage and has no `signedInAs` needs it. `host.launch` fails at once when the test app shows its error screen, and the error has the message on that screen.
 - The home lists a link to each of the test app's other screens. Signed out, it has `Sign in` (`host.app.signIn`, AuthView in a modal), `Sign in with a logo` (the same modal with a React Native logo), `Sign in full screen` (`host.app.signInFullScreen`, AuthView with no close button), `Sign in full screen with a close button`, `Custom sign-in`, `Custom sign-up`, and `Native modules`. Signed in, it has `Embedded profile` (UserProfileView inline). `Token cache` shows in both states. `homeLinks(screen)` in `specs/native.ts` has the locator of each link that `host.app` does not hold. A new screen goes in `screens/destinations.ts` and `verify/VerifyHost.tsx` of the test app and in `homeLinks`.
-- `host.expectSignedInAs(user, timeoutMs?)` waits for the home to show `Signed in as <email>`, the user's ID, and a session ID. Pass the email alone for a user that the sign-up form created. `host.expectSignedOut(timeoutMs?)` waits for the home to show `Signed out` with no user ID and no session ID. Use them for the outcome of a flow that returns to the home. When one of these waits or the wait of `host.launch` runs out, its message says what the home showed at the last reading, how many passes and screen reads the wait made, how long the slowest read took, and the error of a read that failed.
+- `host.expectSignedInAs(user, timeoutMs?)` waits for the home to show `Signed in as <email>`, the user's ID, and a session ID. Pass the email alone for a user that the sign-up form created. `host.expectSignedOut(timeoutMs?)` waits for the home to show `Signed out` with no user ID and no session ID. Use them for the outcome of a flow that returns to the home. `host.expectVisible(locator, timeoutMs?)` is the same wait for an element of an SDK view. On iOS, use it for the first element a spec waits for after it submits a password, because iOS may cover the app with its `Save Password?` sheet then. When one of these waits or the wait of `host.launch` runs out, its message says what the home showed at the last reading, how many passes and screen reads the wait made, how long the slowest read took, and the error of a read that failed.
 - `host.app` has the locators of the home: `signIn`, `signInFullScreen`, `signedOut`, `signedIn`, `userId`, `sessionId`, `signOut`, and `error` for the error screen. `host.runId` is the id of the run, for a password that must be new in each run.
 - `host.tap(locator)` is `locator.tap()` with the assertion timeout, and `host.fill(locator, text)` taps a field and types into it. When the first tap left no field focused, it taps the field once more before it types. Fill the text fields of the native views with `host.fill`. On iOS a native text field shows no text input until it has focus, so a plain `locator.fill()` on it fails with "no text input found at the provided coordinates to clear". After it types, `host.fill` reads the focused text input back. When the screen tree marks no text input as focused, as it does on iOS for a while after a slow snapshot, it reads the value that the node the locator names shows. It sends a long text sixteen characters to a command, because the iOS runner abandons a command after 30 seconds. If the input is still empty after two seconds and the screen shows no text that it did not show before the typing, `host.fill` taps it and types once more, and it fails with "the text never reached the field" if the input is empty again. A screen that shows new text has taken the typed text and moved on, as a code screen does when its code is complete, so `host.fill` types nothing more there. For this it compares the letters of the screen's text only, so the seconds that a code screen counts down beside `Resend` are not new text. If the input holds something other than the text, `host.fill` replaces the input's contents with the text once, and it fails with "the field does not hold the typed text" if the input is still wrong. It compares letters and digits only, so the formatting a field adds does not count. A password field withholds its value, so a password is typed once and is not confirmed. When the iOS runner refuses a tap, a typing command, or a screenshot because it is still finishing an earlier command, `host.tap`, `host.fill`, and `host.screenshot` wait five seconds and try the step again, up to six times, and then fail with the refusal. After a refused typing command, `host.fill` replaces the input's contents with the text and does not type that command again, so characters that did land are not typed twice. On iOS an empty React Native field of the test app reads as its placeholder, which `host.fill` treats as any other value that is not the text.
 - `host.screenshot(label)` writes `screenshots/<label>.png` in the run directory.
diff --git a/integration/expo-native/specs/fixtures.ts b/integration/expo-native/specs/fixtures.ts
index 8126e640c71..195318f5845 100644
--- a/integration/expo-native/specs/fixtures.ts
+++ b/integration/expo-native/specs/fixtures.ts
@@ -32,6 +32,7 @@ const POLL_MS = 400;
 const TYPING_DELAY_MS = 40;
 const CONFIRM_READS = 5;
 const ONLY_E2E_WORKER_SLOT = 0;
+const NAMED_IN_EXPECT_VISIBLE = 'the element the spec names in expectVisible';
 
 const RUN = readRun(process.env);
 
@@ -119,6 +120,7 @@ export const test = base.extend<{ host: HostFixture }>({
       },
       expectSignedInAs: (who, timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(signedInAs(app, who), describeSignedIn(who), timeoutMs),
       expectSignedOut: (timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(signedOut(app), '"Signed out" and no user ID or session ID on the home', timeoutMs),
+      expectVisible: (target, timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(onScreen(target, NAMED_IN_EXPECT_VISIBLE), NAMED_IN_EXPECT_VISIBLE, timeoutMs),
       async screenshot(label) {
         await onceTheRunnerIsFree(() => e2eApp.screenshot(label), runnerBusy());
       },
diff --git a/integration/expo-native/specs/support/types.ts b/integration/expo-native/specs/support/types.ts
index e0489652374..c269bce7ab2 100644
--- a/integration/expo-native/specs/support/types.ts
+++ b/integration/expo-native/specs/support/types.ts
@@ -88,6 +88,7 @@ export interface HostFixture {
   launch(options?: LaunchOptions): Promise<void>;
   expectSignedInAs(who: SeededUser | TestEmail, timeoutMs?: number): Promise<void>;
   expectSignedOut(timeoutMs?: number): Promise<void>;
+  expectVisible(target: Locator, timeoutMs?: number): Promise<void>;
   screenshot(label: string): Promise<void>;
   tap(target: Locator): Promise<void>;
   fill(target: Locator, text: string | SecretLike): Promise<void>;
diff --git a/integration/expo-native/src/core/MANIFEST b/integration/expo-native/src/core/MANIFEST
index eb888eab3cc..e39eb63eff0 100644
--- a/integration/expo-native/src/core/MANIFEST
+++ b/integration/expo-native/src/core/MANIFEST
@@ -1,5 +1,5 @@
 0ec17d3e3a153410d40bd6cc57ddb259745c77403fa681c6670a3aa6456aa826  e2e.config.ts
-e563089e9dcaf8a1edda603b7816d313ca634db078289829e21f5db4d7f1ce3f  specs/fixtures.ts
+8a932ba619f4b6c7b5a35ec7d8d3f02eea7793b8975dae9ba447ea2175d04545  specs/fixtures.ts
 38e8e99663059810b616b591dfd79bdcc7781f72b7269875294f3702b3edde84  specs/support/agent.ts
 6d1ef7700a89e19d0b1214d5a6815ba757d02857c555b8bf108f2e0c9a64aad3  specs/support/busy-runner.ts
 153cda5ccf3ad0e38a35e238a52c64633a9b8de9e2086ff060ddb661a2438b1d  specs/support/clerk.ts
@@ -10,7 +10,7 @@ cec7a42bf8d35e174fd3387cbcc638c01bacda74fc15ea1b14eda8abaa200d34  specs/support/
 27a69309a568e90dc06b8d04abfb6efe7dadd16f4374a19f61d0ebf0a99a87fc  specs/support/launch.ts
 2065bc90a33659fd8f5a6e54e8b0fa57a50edc415063d4ac7e0dab744972e1b7  specs/support/secret.ts
 7446b59792b957f2ace72e6c2eceb305bde25378d1f879e2884706c3d7f9f3a4  specs/support/tapping.ts
-df955a42a2bd4ca1780f56837ebb9c832c68e97f74a35764d42a32e44b28286b  specs/support/types.ts
+a0405794fe509d2ed27800878de12aafb849511513b5d37768bd974dd969f20f  specs/support/types.ts
 7bdb018b337d923e96ada265abfebafd75c6fd07188ab313117effdc893e32d7  specs/support/typing.ts
 10bcf31d87a05655fc263ed810a0e10c0b63a77265720d7f22f3720052f67c38  specs/support/waiting.ts
 792ec6414c7e95446346abe2db850f6e4cc865a7c83a21892166fae969654277  src/core/agent.ts

From 13b21b396ee4671f52d72267ee24ce7e9f865c43 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:29:09 -0400
Subject: [PATCH 05/10] test(expo): fail when a spec file sits where run --all
 does not look

`run --all` runs the spec files under `specs/features/`, and a scratch
spec under `specs/explored/` runs by its path. A `*.e2e.ts` file in any
other folder under `specs/`, such as one left in `specs/golden/` by a
branch that was cut before the rename, is skipped with no message, so
the release gate would pass without it.

A new test fails when such a file exists and names it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 integration/expo-native/test/e2e.test.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/integration/expo-native/test/e2e.test.ts b/integration/expo-native/test/e2e.test.ts
index 0b8a5c198fa..7a180db44ce 100644
--- a/integration/expo-native/test/e2e.test.ts
+++ b/integration/expo-native/test/e2e.test.ts
@@ -186,6 +186,14 @@ describe('parseE2EReport', () => {
   });
 });
 
+describe('the spec files', () => {
+  it('all sit under specs/features/ or specs/explored/, because run --all skips a spec anywhere else and says nothing', () => {
+    const specs = join(import.meta.dirname, '..', 'specs');
+    const stray = readdirSync(specs, { recursive: true, encoding: 'utf8' }).filter((path) => path.endsWith('.e2e.ts') && !/^(features|explored)\//.test(path));
+    assert.deepEqual(stray, [], `run --all would skip specs/${stray.join(' and specs/')}: move it under specs/features/<feature>/ or specs/explored/`);
+  });
+});
+
 describe('the screenshot labels of the committed specs', () => {
   it('are each used once, because a run keeps one screenshot for a label', () => {
     const features = join(import.meta.dirname, '..', 'specs', 'features');

From 718ec8ebe7fcc7cabee8f156e8bc6716788085b7 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:43:09 -0400
Subject: [PATCH 06/10] docs(expo): name the driver timeout that --retries does
 not retry

The skill gave "a launch that timed out" as a failure that gets one
attempt. That reads as the 60-second wait in `host.launch`, which throws
a plain error, so e2e counts it as a test failure and runs it again. What
gets one attempt is a command agent-device timed out on, such as `open`
or a screenshot (`isRetryEligible` in e2e 0.18.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index 3f88a2b1191..db42e0d58c0 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -110,7 +110,7 @@ $ integration/expo-native/bin/control-clerk-expo run native-auth-view native-js-
 $ integration/expo-native/bin/control-clerk-expo screen --platform ios                        # the UI tree that is on screen now; --png adds a screenshot
 ```
 
-`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure of the device driver or of e2e itself, such as a screenshot that agent-device could not take or a launch that timed out, gets one attempt whatever `n` is. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
+`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure of the device driver or of e2e itself, such as an `open` or screenshot command that agent-device timed out on, gets one attempt whatever `n` is. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
 
 For a JS change on a local device, edit the source and `run` the spec, with no `up` in between. For a change to a native input, the same `run` rebuilds the dev client first. On a remote device, commit and push, then `run`.
 

From 264423d3267952fbd60a53ba360f39c52e2db5c0 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:44:02 -0400
Subject: [PATCH 07/10] docs(expo): point the Proof lines at the renamed
 screenshots

The Proof lines of `native-js-sync` and `token-cache-persistence` still
named `signed-out.png` and `restored-home.png`. Those specs now write
`signed-out-from-native` and `restored-home-after-relaunch`; the old
labels belong to other specs. No other feature page in clerk-ios,
clerk-android or clerk/javascript names a label its feature's specs do
not write.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/features/native-js-sync.md     | 2 +-
 .../verify-clerk-expo/features/token-cache-persistence.md       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/verify-clerk-expo/features/native-js-sync.md b/.claude/skills/verify-clerk-expo/features/native-js-sync.md
index f356fcbb454..1766ea2ebd9 100644
--- a/.claude/skills/verify-clerk-expo/features/native-js-sync.md
+++ b/.claude/skills/verify-clerk-expo/features/native-js-sync.md
@@ -23,7 +23,7 @@ Preconditions:
 
 - **Native sign-out.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-out-from-native --platform ios`, and again with `--platform android`. The spec launches signed in, taps the UserButton, taps `Sign out` in the profile, and calls `host.expectSignedOut`. That waits for the home to show `Signed out` (from `useAuth`), with no `Signed in as` text and no user ID (from `useUser`) and no session ID (from `useSession`). Screenshots `before-sign-out` and `signed-out-from-native`.
 - **Native sign-in.** Run `integration/expo-native/bin/control-clerk-expo run native-js-sync/sign-in-from-native --platform ios`, and again with `--platform android`. Both tests seed a user with `host.seedUser({ password: true })`, tap `Sign in` on the home, and sign in with `signInWithPassword` from `specs/native.ts`. The first test expects the home to show the user and a session ID, relaunches with `keepStorage`, and expects the same user and the same session ID. Screenshots `signed-in-from-native` and `restored-home`. The second test signs out with the profile's `Sign out` row, signs in again, and expects the home to show the user. Screenshot `signed-in-again`.
-- **Proof.** `screenshots/signed-out.png` shows the home with `Signed out` and the `Sign in` button. The native profile closes by itself, because the UserButton that presented it leaves the home.
+- **Proof.** `screenshots/signed-out-from-native.png` shows the home with `Signed out` and the `Sign in` button. The native profile closes by itself, because the UserButton that presented it leaves the home.
 
 ## Gotchas
 
diff --git a/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md b/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
index a777e1bc8cf..063256c184d 100644
--- a/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
+++ b/.claude/skills/verify-clerk-expo/features/token-cache-persistence.md
@@ -21,7 +21,7 @@ Preconditions:
 - **Relaunch.** Run `integration/expo-native/bin/control-clerk-expo run token-cache-persistence --platform android` (or `ios`). The spec launches signed in and reads the session ID on the home. It relaunches with `keepStorage: true` and no ticket, and expects the home to show the same user and the same session ID. Screenshot `restored-home-after-relaunch`.
 - **Kept token.** On that relaunched home the test taps `Token cache` and expects `client token kept from the last launch: yes` and `user: <the seeded user ID>`. Screenshot `token-cache`.
 - **New scope.** The same test relaunches with a new storage scope, taps `Token cache` on the signed-out home, and expects `client token kept from the last launch: no` and `user: none`. Screenshot `new-scope`.
-- **Proof.** `screenshots/restored-home.png` shows the user and the session after a launch that had no ticket, and `screenshots/token-cache.png` shows the kept token.
+- **Proof.** `screenshots/restored-home-after-relaunch.png` shows the user and the session after a launch that had no ticket, and `screenshots/token-cache.png` shows the kept token.
 
 ## Gotchas
 

From f6c9a0e9d388e2961e64239159cc8fb6441473f5 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:48:12 -0400
Subject: [PATCH 08/10] test(expo): name the element in host.expectVisible's
 timeout message

When `host.expectVisible` ran out, its message said that the app did not
show "the element the spec names in expectVisible", so a reader of a red
run had to find the line from the stack. It now takes `what`, the name
of the element, and the message says that name, as the messages of
`host.expectSignedInAs` and `host.launch` already do. clerk-ios has the one
caller; the fixture is shared, so it changes here too.

The wait moves into `untilVisible` in `specs/support/waiting.ts`, so a
unit test can run it on the simulated screen and assert the message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md        |  2 +-
 integration/expo-native/specs/fixtures.ts        |  8 ++++----
 integration/expo-native/specs/support/types.ts   |  2 +-
 integration/expo-native/specs/support/waiting.ts |  2 ++
 integration/expo-native/src/core/MANIFEST        |  6 +++---
 integration/expo-native/test/waiting.test.ts     | 11 ++++++++++-
 6 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index db42e0d58c0..8686fd76684 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -139,7 +139,7 @@ test('the home UserButton opens the profile of the signed-in user', async ({ hos
 - `host.seedUser({ phone?, password? })` creates a `+clerk_test` user in the worktree's application. With `password: true` the user also has a password that the run generated for that user, and `user.password` holds it. Pass it to `host.fill`, as `host.fill(field, user.password!)`, and to nothing else. It prints as `<secret:password>`, `run` redacts its value from the logs it writes, and `attach` refuses a run whose files hold it. For a sign-up through the form, `host.newEmail()` returns a new address of this run, and `host.newPhone()` returns a 555-01xx number that no user holds. `host.newEmail()` calls nothing and records nothing. After the tests, `run` finds the user by the run's prefix in the address.
 - `host.launch({ signedInAs?, authMode?, keepStorage?, landsOn? })` relaunches the test app and waits up to 60 seconds for its home. Every launch opens on the home, and a spec taps from there to the screen it needs, as a user does. `authMode` is the mode of every AuthView the home opens: `signIn`, `signUp`, or `signInOrUp`. A launch starts with fresh storage unless `keepStorage` is true, so a launch with no `signedInAs` is signed out and lands on the home's `Sign in` button. `host.launch()` with no argument is that launch. A launch with `signedInAs` lands on the home, which must show that user's email and user ID. When the home should show anything else, pass its locator as `landsOn`. A launch that keeps storage and has no `signedInAs` needs it. `host.launch` fails at once when the test app shows its error screen, and the error has the message on that screen.
 - The home lists a link to each of the test app's other screens. Signed out, it has `Sign in` (`host.app.signIn`, AuthView in a modal), `Sign in with a logo` (the same modal with a React Native logo), `Sign in full screen` (`host.app.signInFullScreen`, AuthView with no close button), `Sign in full screen with a close button`, `Custom sign-in`, `Custom sign-up`, and `Native modules`. Signed in, it has `Embedded profile` (UserProfileView inline). `Token cache` shows in both states. `homeLinks(screen)` in `specs/native.ts` has the locator of each link that `host.app` does not hold. A new screen goes in `screens/destinations.ts` and `verify/VerifyHost.tsx` of the test app and in `homeLinks`.
-- `host.expectSignedInAs(user, timeoutMs?)` waits for the home to show `Signed in as <email>`, the user's ID, and a session ID. Pass the email alone for a user that the sign-up form created. `host.expectSignedOut(timeoutMs?)` waits for the home to show `Signed out` with no user ID and no session ID. Use them for the outcome of a flow that returns to the home. `host.expectVisible(locator, timeoutMs?)` is the same wait for an element of an SDK view. On iOS, use it for the first element a spec waits for after it submits a password, because iOS may cover the app with its `Save Password?` sheet then. When one of these waits or the wait of `host.launch` runs out, its message says what the home showed at the last reading, how many passes and screen reads the wait made, how long the slowest read took, and the error of a read that failed.
+- `host.expectSignedInAs(user, timeoutMs?)` waits for the home to show `Signed in as <email>`, the user's ID, and a session ID. Pass the email alone for a user that the sign-up form created. `host.expectSignedOut(timeoutMs?)` waits for the home to show `Signed out` with no user ID and no session ID. Use them for the outcome of a flow that returns to the home. `host.expectVisible(locator, what, timeoutMs?)` is the same wait for an element of an SDK view, and its message names the element with `what`. On iOS, use it for the first element a spec waits for after it submits a password, because iOS may cover the app with its `Save Password?` sheet then. When one of these waits or the wait of `host.launch` runs out, its message says what the home showed at the last reading, how many passes and screen reads the wait made, how long the slowest read took, and the error of a read that failed.
 - `host.app` has the locators of the home: `signIn`, `signInFullScreen`, `signedOut`, `signedIn`, `userId`, `sessionId`, `signOut`, and `error` for the error screen. `host.runId` is the id of the run, for a password that must be new in each run.
 - `host.tap(locator)` is `locator.tap()` with the assertion timeout, and `host.fill(locator, text)` taps a field and types into it. When the first tap left no field focused, it taps the field once more before it types. Fill the text fields of the native views with `host.fill`. On iOS a native text field shows no text input until it has focus, so a plain `locator.fill()` on it fails with "no text input found at the provided coordinates to clear". After it types, `host.fill` reads the focused text input back. When the screen tree marks no text input as focused, as it does on iOS for a while after a slow snapshot, it reads the value that the node the locator names shows. It sends a long text sixteen characters to a command, because the iOS runner abandons a command after 30 seconds. If the input is still empty after two seconds and the screen shows no text that it did not show before the typing, `host.fill` taps it and types once more, and it fails with "the text never reached the field" if the input is empty again. A screen that shows new text has taken the typed text and moved on, as a code screen does when its code is complete, so `host.fill` types nothing more there. For this it compares the letters of the screen's text only, so the seconds that a code screen counts down beside `Resend` are not new text. If the input holds something other than the text, `host.fill` replaces the input's contents with the text once, and it fails with "the field does not hold the typed text" if the input is still wrong. It compares letters and digits only, so the formatting a field adds does not count. A password field withholds its value, so a password is typed once and is not confirmed. When the iOS runner refuses a tap, a typing command, or a screenshot because it is still finishing an earlier command, `host.tap`, `host.fill`, and `host.screenshot` wait five seconds and try the step again, up to six times, and then fail with the refusal. After a refused typing command, `host.fill` replaces the input's contents with the text and does not type that command again, so characters that did land are not typed twice. On iOS an empty React Native field of the test app reads as its placeholder, which `host.fill` treats as any other value that is not the text.
 - `host.screenshot(label)` writes `screenshots/<label>.png` in the run directory.
diff --git a/integration/expo-native/specs/fixtures.ts b/integration/expo-native/specs/fixtures.ts
index 195318f5845..e9f18ac3090 100644
--- a/integration/expo-native/specs/fixtures.ts
+++ b/integration/expo-native/specs/fixtures.ts
@@ -23,7 +23,7 @@ import {
   type SeededUser,
   type TestEmail,
 } from './support/types.ts';
-import { errorScreenElseSavePasswordPrompt, onScreen, signedInAs, signedOut, until, type Sight, type WaitScreen } from './support/waiting.ts';
+import { errorScreenElseSavePasswordPrompt, onScreen, signedInAs, signedOut, until, untilVisible, type Sight, type WaitPace, type WaitScreen } from './support/waiting.ts';
 
 export { expect, CLERK_TEST_CODE };
 
@@ -32,7 +32,6 @@ const POLL_MS = 400;
 const TYPING_DELAY_MS = 40;
 const CONFIRM_READS = 5;
 const ONLY_E2E_WORKER_SLOT = 0;
-const NAMED_IN_EXPECT_VISIBLE = 'the element the spec names in expectVisible';
 
 const RUN = readRun(process.env);
 
@@ -88,7 +87,8 @@ export const test = base.extend<{ host: HostFixture }>({
       errorScreenElsePrompt: device.locator(errorScreenElseSavePasswordPrompt(APP_ELEMENT_IDS.error)),
       dismissPrompt: () => screen.getByRole('button', { name: 'Not Now' }).tap({ timeout: ASSERTION_TIMEOUT_MS }),
     };
-    const waitFor = (sight: Sight, what: string, timeoutMs: number): Promise<void> => until(sight, what, waitScreen, { timeoutMs, now: Date.now, wait: () => sleep(POLL_MS) });
+    const pace = (timeoutMs: number): WaitPace => ({ timeoutMs, now: Date.now, wait: () => sleep(POLL_MS) });
+    const waitFor = (sight: Sight, what: string, timeoutMs: number): Promise<void> => until(sight, what, waitScreen, pace(timeoutMs));
 
     const describeSignedIn = (who: SeededUser | TestEmail): string =>
       typeof who === 'string' ? `"${signedInText(who)}" with a user ID and a session ID on the home` : `"${signedInText(who.email)}" with user ID ${who.id} and a session ID on the home`;
@@ -120,7 +120,7 @@ export const test = base.extend<{ host: HostFixture }>({
       },
       expectSignedInAs: (who, timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(signedInAs(app, who), describeSignedIn(who), timeoutMs),
       expectSignedOut: (timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(signedOut(app), '"Signed out" and no user ID or session ID on the home', timeoutMs),
-      expectVisible: (target, timeoutMs = ASSERTION_TIMEOUT_MS) => waitFor(onScreen(target, NAMED_IN_EXPECT_VISIBLE), NAMED_IN_EXPECT_VISIBLE, timeoutMs),
+      expectVisible: (target, what, timeoutMs = ASSERTION_TIMEOUT_MS) => untilVisible(target, what, waitScreen, pace(timeoutMs)),
       async screenshot(label) {
         await onceTheRunnerIsFree(() => e2eApp.screenshot(label), runnerBusy());
       },
diff --git a/integration/expo-native/specs/support/types.ts b/integration/expo-native/specs/support/types.ts
index c269bce7ab2..baff380e7c4 100644
--- a/integration/expo-native/specs/support/types.ts
+++ b/integration/expo-native/specs/support/types.ts
@@ -88,7 +88,7 @@ export interface HostFixture {
   launch(options?: LaunchOptions): Promise<void>;
   expectSignedInAs(who: SeededUser | TestEmail, timeoutMs?: number): Promise<void>;
   expectSignedOut(timeoutMs?: number): Promise<void>;
-  expectVisible(target: Locator, timeoutMs?: number): Promise<void>;
+  expectVisible(target: Locator, what: string, timeoutMs?: number): Promise<void>;
   screenshot(label: string): Promise<void>;
   tap(target: Locator): Promise<void>;
   fill(target: Locator, text: string | SecretLike): Promise<void>;
diff --git a/integration/expo-native/specs/support/waiting.ts b/integration/expo-native/specs/support/waiting.ts
index 4bddfd3bbc4..a19f9ffa7bd 100644
--- a/integration/expo-native/specs/support/waiting.ts
+++ b/integration/expo-native/specs/support/waiting.ts
@@ -86,6 +86,8 @@ export const onScreen =
   async (see) =>
     shown(await see(what, element));
 
+export const untilVisible = (element: ScreenElement, what: string, screen: WaitScreen, pace: WaitPace): Promise<void> => until(onScreen(element, what), what, screen, pace);
+
 async function homeShows(read: ReadHome): Promise<string> {
   const heading = await read('signedIn');
   const userId = await read('userId');
diff --git a/integration/expo-native/src/core/MANIFEST b/integration/expo-native/src/core/MANIFEST
index e39eb63eff0..e0c43057e7a 100644
--- a/integration/expo-native/src/core/MANIFEST
+++ b/integration/expo-native/src/core/MANIFEST
@@ -1,5 +1,5 @@
 0ec17d3e3a153410d40bd6cc57ddb259745c77403fa681c6670a3aa6456aa826  e2e.config.ts
-8a932ba619f4b6c7b5a35ec7d8d3f02eea7793b8975dae9ba447ea2175d04545  specs/fixtures.ts
+6bb1bf55ef36d59453d31e1cd449fba8bfe0e4be433be86136f26d46000d7717  specs/fixtures.ts
 38e8e99663059810b616b591dfd79bdcc7781f72b7269875294f3702b3edde84  specs/support/agent.ts
 6d1ef7700a89e19d0b1214d5a6815ba757d02857c555b8bf108f2e0c9a64aad3  specs/support/busy-runner.ts
 153cda5ccf3ad0e38a35e238a52c64633a9b8de9e2086ff060ddb661a2438b1d  specs/support/clerk.ts
@@ -10,9 +10,9 @@ cec7a42bf8d35e174fd3387cbcc638c01bacda74fc15ea1b14eda8abaa200d34  specs/support/
 27a69309a568e90dc06b8d04abfb6efe7dadd16f4374a19f61d0ebf0a99a87fc  specs/support/launch.ts
 2065bc90a33659fd8f5a6e54e8b0fa57a50edc415063d4ac7e0dab744972e1b7  specs/support/secret.ts
 7446b59792b957f2ace72e6c2eceb305bde25378d1f879e2884706c3d7f9f3a4  specs/support/tapping.ts
-a0405794fe509d2ed27800878de12aafb849511513b5d37768bd974dd969f20f  specs/support/types.ts
+7492e917cb05c4f0aa2c3cb76de34c05b0891f080832e76eb5fee6e4b7a04cf5  specs/support/types.ts
 7bdb018b337d923e96ada265abfebafd75c6fd07188ab313117effdc893e32d7  specs/support/typing.ts
-10bcf31d87a05655fc263ed810a0e10c0b63a77265720d7f22f3720052f67c38  specs/support/waiting.ts
+56099f0c1d14d794ac08e782bb920445b5600d83ed18443e5142e1e6f8b68d02  specs/support/waiting.ts
 792ec6414c7e95446346abe2db850f6e4cc865a7c83a21892166fae969654277  src/core/agent.ts
 d56c29efc8061adfd65b89f0f02465af3234ecd52289ef6d9f338483afeadeb5  src/core/broker.ts
 7c741449c755524bba80f1ce314554293003a34f7f7c30696015ba1c0c3dc1ab  src/core/claims.ts
diff --git a/integration/expo-native/test/waiting.test.ts b/integration/expo-native/test/waiting.test.ts
index f915e819375..865dc121f9a 100644
--- a/integration/expo-native/test/waiting.test.ts
+++ b/integration/expo-native/test/waiting.test.ts
@@ -2,7 +2,7 @@ import '../testing/git-env.ts';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { newTestEmail } from '../specs/support/clerk.ts';
-import { SAVE_PASSWORD_PROMPT, errorScreenElseSavePasswordPrompt, onScreen, signedInAs, signedOut, until, type Home, type ScreenElement, type Sight, type WaitPace, type WaitScreen } from '../specs/support/waiting.ts';
+import { SAVE_PASSWORD_PROMPT, errorScreenElseSavePasswordPrompt, onScreen, signedInAs, signedOut, until, untilVisible, type Home, type ScreenElement, type Sight, type WaitPace, type WaitScreen } from '../specs/support/waiting.ts';
 import type { SeededUser } from '../src/core/types.ts';
 import { SAMPLE_RUN } from '../testing/sample-inputs.ts';
 
@@ -96,6 +96,7 @@ function device(start: Showing, simulated: Simulated = {}) {
     dismissals: () => dismissals,
     waits: () => waits,
     wait: (sight: Sight, timeoutMs = 30_000): Promise<void> => until(sight, WAITING_FOR, screen, pace(timeoutMs)),
+    waitVisible: (element: ScreenElement, what: string, timeoutMs: number): Promise<void> => untilVisible(element, what, screen, pace(timeoutMs)),
   };
 }
 
@@ -317,6 +318,14 @@ describe('a wait for a launch to land on a control', () => {
   });
 });
 
+describe('a wait for an element the spec names', () => {
+  it('names the element in its message when it runs out', async () => {
+    const phone = device(SIGNED_IN);
+    const message = await failure(phone.waitVisible(phone.signIn, 'the "Sign in" button', 1_000));
+    assert.equal(message, `the app did not show the "Sign in" button within 1000ms; the home shows "${HEADING}", user ID user_1, session ID sess_1; passes: 3; reads: 10, the slowest 100ms (the "Sign in" button)`);
+  });
+});
+
 describe('the selector that reads the error screen and the save-password prompt in one capture', () => {
   it('names the error screen first, so the prompt is read only when the app shows no error screen', () => {
     assert.equal(errorScreenElseSavePasswordPrompt('e2e.launch.error'), 'id="e2e.launch.error" || label="Save Password?"');

From 513a2d6e0784af404a48f02fcb1b397f9fcf8018 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Wed, 14 Oct 2026 08:29:05 -0400
Subject: [PATCH 09/10] docs(verify): say which device errors are retried

e2e 0.18.0 reports some driver errors as test errors (a stale node, an
action that timed out), and --retries reruns those. Only failures it counts
as infrastructure, such as ENGINE_FAILURE, get one attempt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index 8686fd76684..bb02d4f50c8 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -110,7 +110,7 @@ $ integration/expo-native/bin/control-clerk-expo run native-auth-view native-js-
 $ integration/expo-native/bin/control-clerk-expo screen --platform ios                        # the UI tree that is on screen now; --png adds a screenshot
 ```
 
-`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure of the device driver or of e2e itself, such as an `open` or screenshot command that agent-device timed out on, gets one attempt whatever `n` is. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
+`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure e2e counts as its own or the machine's, such as an `ENGINE_FAILURE` when an `open` or a screenshot timed out in agent-device, gets one attempt whatever `n` is. A driver error e2e reports as a test error, such as a stale node or an action that timed out, is retried like any other. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
 
 For a JS change on a local device, edit the source and `run` the spec, with no `up` in between. For a change to a native input, the same `run` rebuilds the dev client first. On a remote device, commit and push, then `run`.
 

From 735ed2950e4e675ccbdd33a19b0aaad46ae94a94 Mon Sep 17 00:00:00 2001
From: Mike Pitre <12040919+mikepitre@users.noreply.github.com>
Date: Wed, 14 Oct 2026 08:38:12 -0400
Subject: [PATCH 10/10] docs(verify): state plainly which failures get one
 attempt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/verify-clerk-expo/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/skills/verify-clerk-expo/SKILL.md b/.claude/skills/verify-clerk-expo/SKILL.md
index bb02d4f50c8..853ca906ccb 100644
--- a/.claude/skills/verify-clerk-expo/SKILL.md
+++ b/.claude/skills/verify-clerk-expo/SKILL.md
@@ -110,7 +110,7 @@ $ integration/expo-native/bin/control-clerk-expo run native-auth-view native-js-
 $ integration/expo-native/bin/control-clerk-expo screen --platform ios                        # the UI tree that is on screen now; --png adds a screenshot
 ```
 
-`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A failure e2e counts as its own or the machine's, such as an `ENGINE_FAILURE` when an `open` or a screenshot timed out in agent-device, gets one attempt whatever `n` is. A driver error e2e reports as a test error, such as a stale node or an action that timed out, is retried like any other. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
+`run --all` runs every committed spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--max-failures <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a test again, up to `n` more times, when an assertion failed, the test threw an error, or the test ran out of time. A test that e2e reports as a machine failure, such as an `ENGINE_FAILURE` when an `open` or a screenshot times out in agent-device, gets one attempt whatever `n` is. A driver error e2e reports as a test error, such as a stale node or an action that timed out, is retried like any other. The default is 0, so a run of your own change shows exactly what happened. `--max-failures <n>` stops a settings group once `n` of its tests have failed. A test that the limit stopped before it started prints `FAIL` with `not run: failure-limit`, and `run` exits 1. Without the flag, a run has no limit. The wait covers a free lane and another `run` in this worktree that holds the device. A spec limited to one platform with `test(title, { platforms: ['ios'] }, fn)` reports as skipped on the other.
 
 For a JS change on a local device, edit the source and `run` the spec, with no `up` in between. For a change to a native input, the same `run` rebuilds the dev client first. On a remote device, commit and push, then `run`.