verikun 0.15.0 → 0.17.0

package/README.md

@@ -104,7 +104,7 @@ vk screenshot                   # -> ./.verikun/screen.png
 | Command | Description |
 |---|---|
 | `ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--cost-override in/out] [--effort e] [--package pkg] [--app-build id] [--server url] [--show-plan] [--recompile] [--json]` | Run a plain-English test: compile it to a deterministic plan once, replay it model-free, and self-heal failures via the model. Needs `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (per model), or no key with `--model codex-cli` / `cursor-cli` (a logged-in `codex` / `cursor-agent` CLI). See [AI](#ai--natural-language-tests). |
-| `suite <dir> [--app <id>] [--name n] [--server url] [--json]` (+ all `ai` flags) | Run every `*.md` in `<dir>` as one sequential suite with an overview report and a non-zero exit on failure — the CI gate. See [Suites](#suites--run-a-directory-of-tests). |
+| `suite <dir> [--app <id>] [--name n] [--retries n] [--server url] [--json]` (+ all `ai` flags) | Run every `*.md` in `<dir>` as one sequential suite with an overview report and a non-zero exit on failure — the CI gate. See [Suites](#suites--run-a-directory-of-tests). |
 
 ### Remote
 | Command | Description |
@@ -287,12 +287,29 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote devi
 - **Each test is a full `vk ai` run** — plan cache, self-healing, cost budget, and
   its own archived JUnit + HTML report under `./.verikun/runs/<id>/`. A test that
   fails (or errors) doesn't stop the suite; the rest still run.
-- **But a broken *environment* does stop it.** If a test dies from an environment
-  error (exit 3 — tool gone, device unplugged, server unreachable), the toolchain is
-  re-probed; only if it is *still* broken does the suite abort. That re-probe matters:
-  a transient `uiautomator` dump failure also exits 3, and shouldn't vaporize a
-  20-test run. Continuing on a genuinely dead box just produces one identical red row
-  per remaining test — noise that reads exactly like a mass regression.
+- **`--retries N` recovers from flakes.** A failed test is re-run up to N times
+  (default `0` — opt-in, so CI cost/time stay predictable). If a later attempt
+  passes, the suite exits `0` and the flake is a **warning**, not a hard failure.
+  Failed attempt archives stay linked from the suite overview (`attempts` on the
+  test row + a `warnings` list on the manifest), so flakiness remains visible.
+  Cost and duration sum across attempts.
+- **What earns a retry:** anything that might come out differently — a flaky
+  selector, a wedged app, and **a broken environment**, including a `vk server`
+  connection dropping mid-suite. The bias is intentional: an attempt costs one test,
+  giving up costs the whole suite plus a human rerunning it. Environment retries wait
+  a little longer each time (an outage that survives the health probe usually needs
+  seconds, not milliseconds) and each one lands in `warnings`, so riding out a wobble
+  is never silent. Exactly two failures are never retried, because a rerun cannot
+  change them: a **budget abort** (each attempt gets its own ceiling, so it would just
+  re-abort having spent twice) and a **usage error** (exit `2` — an unreadable test
+  file, a payload the server refuses).
+- **But a broken *environment* does stop it, once the attempts are gone.** If a test
+  dies from an environment error (exit 3 — tool gone, device unplugged, server
+  unreachable), the toolchain is re-probed; only if it is *still* broken **and** no
+  retries remain does the suite abort. That re-probe matters: a transient
+  `uiautomator` dump failure also exits 3, and shouldn't vaporize a 20-test run.
+  Continuing on a genuinely dead box just produces one identical red row per remaining
+  test — noise that reads exactly like a mass regression.
 - **The suite writes an overview** to `./.verikun/suites/<id>/`:
   - **`index.json`** — a stable, `schemaVersion`ed manifest: per-test pass/fail,
     steps, model repairs, cost, duration, and the run id, plus suite totals. This
@@ -300,17 +317,21 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote devi
     it (see the [CI recipe](#ci-recipe)) instead of verikun growing upload plugins.
     On an abort it also carries `aborted: {reason, notRun}`; the not-run tests get
     **no rows and no place in `totals`**, so `passed + failed === tests` still holds
-    and nothing downstream mistakes a skipped test for a regression.
+    and nothing downstream mistakes a skipped test for a regression. Retried flakes
+    add `flaky` / `attempts` on the test row and suite-level `warnings` (additive;
+    `schemaVersion` stays `1`).
   - **`index.html`** — a summary page linking every test's `report.html`, with a
-    banner naming the not-run tests when the suite aborted.
-- **Exit code is the CI gate:** `0` all green · `1` a test failed · `2` bad/empty
-  directory · `3` environment (the provider or the device toolchain is unavailable,
-  or the box broke mid-run). The `1`-vs-`3` split is the point: `1` is a regression
-  to investigate, `3` is a machine to fix. All `ai` flags (`--model`,
-  `--max-cost-usd`, `--timeout`, …) apply to every test; both the provider
-  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` / `cursor-agent` CLI for
-  `--model codex-cli` / `cursor-cli`) **and** the device toolchain (`adb` / `idb` +
-  a resolvable device) are checked up front, before anything is compiled.
+    banner naming the not-run tests when the suite aborted, and a warnings banner
+    when a flake recovered on retry (prior failed attempts stay linked).
+- **Exit code is the CI gate:** `0` all green (including flakes that recovered with
+  `--retries`) · `1` a test failed · `2` bad/empty directory · `3` environment (the
+  provider or the device toolchain is unavailable, or the box broke mid-run). The
+  `1`-vs-`3` split is the point: `1` is a regression to investigate, `3` is a
+  machine to fix. All `ai` flags (`--model`, `--max-cost-usd`, `--timeout`, …)
+  apply to every test; both the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`,
+  or the `codex` / `cursor-agent` CLI for `--model codex-cli` / `cursor-cli`)
+  **and** the device toolchain (`adb` / `idb` + a resolvable device) are checked up
+  front, before anything is compiled.
 
 ## Remote devices — `vk server`
 
@@ -390,15 +411,51 @@ class:Button    simplified type ("Button") or full class ("android.widget.Button
 ```
 
 Modifiers: `--contains` makes text/desc matches substring-based; `--index N`
-selects the Nth match (0-based) when a selector intentionally matches several;
-`--enabled` matches only a control that is **actionable right now** — use it for a
-Submit/Check button the app disables until a form is valid, since such a button is
-present long before it is usable and tapping presence taps a dead control (with
-auto-wait this reads as "wait until it is pressable").
+selects the Nth match (0-based) when a selector intentionally matches several.
 If a selector for an action matches more than one element and no `--index` is
 given, the command fails with exit code 2 and lists the candidates — it never
 taps a guess.
 
+### State modifiers
+
+A selector can also require an element's a11y **state**, in both polarities:
+
+| Modifier | Matches | Negative form |
+|---|---|---|
+| `--enabled` | actionable right now | `--not-enabled` |
+| `--selected` | the current option of a segmented control / tab bar / mode picker | `--not-selected` |
+| `--checked` | a ticked checkbox / switch / radio | `--not-checked` |
+| `--focused` | the element holding input focus | `--not-focused` |
+
+Unset means *don't care*; these never narrow a selector you didn't ask them to.
+
+Reach for `--enabled` on a Submit/Check button the app disables until a form is
+valid: such a button is present long before it is usable, so tapping presence taps
+a dead control (with auto-wait this reads as "wait until it is pressable").
+
+The **negative** forms are what make a toggle drivable. A segmented control whose
+options share one handler *flips* on any tap, so "tap the option I want" lands on
+the other one whenever it was already chosen — exit 0, nothing to notice, and the
+run exercises the wrong mode. Guard it instead:
+
+```sh
+vk find "@mode_video --not-selected" --no-wait && vk tap @mode_video
+```
+
+A modifier can be written as a flag **or appended to the selector string**, as
+above. The string form exists because a `vk ai` control node (`if-present`,
+`when`, `repeat`, `while-present`, `read`) holds a bare selector with nowhere to
+put a flag — and a guard is exactly where the toggle case needs one:
+
+```
+if-present "id:mode_video --not-selected" { tap id:mode_video }
+```
+
+**`--selected` and `--focused` are Android-only.** `idb` reports no such
+attribute for iOS — not merely unset, the key does not exist in its output — so
+using them with `--ios` exits **3** rather than silently matching nothing.
+`--enabled` and `--checked` work on both.
+
 ### Auto scroll-into-view
 
 An element can be in the hierarchy without being reachable at the point a tap

package/dist/agent/engine.js

@@ -4,6 +4,7 @@ exports.DEFAULT_GUARD_SETTLE_MS = exports.DEFAULT_RUN_TIMEOUT_MS = void 0;
 exports.runPlan = runPlan;
 const node_crypto_1 = require("node:crypto");
 const selector_1 = require("../ui/selector");
+const state_support_1 = require("../ui/state-support");
 const errors_1 = require("../errors");
 const ir_1 = require("./ir");
 /** An outcome is environment-flavoured if it carries an exit-3 CliError, or simply
@@ -191,6 +192,11 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] guard selector '${selector}' did not parse (${e.message}) — treating as not present`);
             return false;
         }
+        // Outside the catch on purpose. A guard pinning state this platform cannot report
+        // would match nothing forever, so "not present" is a lie that silently skips the
+        // body — the plan is unrunnable HERE and must say so, not quietly do nothing.
+        if (deps.platform)
+            (0, state_support_1.assertStateSupported)(sel, deps.platform);
         const deadline = Date.now() + Math.max(0, settleMs);
         // A non-zero window must buy at least one SECOND look, independent of the clock.
         // Measured on emulator-5554: one uiautomator dump costs ~2.4s, which already exceeds
@@ -368,6 +374,8 @@ async function runPlan(plan, deps) {
         catch (e) {
             return { status: 'fail', where, reason: `read selector '${selector}' did not parse: ${e.message}` };
         }
+        if (deps.platform)
+            (0, state_support_1.assertStateSupported)(sel, deps.platform);
         // Same patience as a conditional guard: the value may not have rendered yet.
         const deadline = Date.now() + Math.max(0, guardSettleMs);
         let looks = 0;

package/dist/agent/grammar.js

@@ -112,12 +112,29 @@ SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable ident
   class:Button      type or class
   "Sign in"         bare string == text:Sign in
 
+A selector may also pin ELEMENT STATE, in both polarities:
+  --enabled  / --not-enabled     actionable right now
+  --selected / --not-selected    current option of a segmented control / tab bar / mode picker
+  --checked  / --not-checked     checkbox / switch / radio state
+  --focused  / --not-focused     holds input focus
+On a command leaf write it as a flag. On a CONTROL NODE append it to the selector string —
+that is the only place one can go, and it is what makes a state-conditional guard possible:
+  { "type":"if-present", "selector":"id:mode_video --not-selected",
+    "body":[ { "type":"command","command":"tap","positionals":["id:mode_video"],"flags":[] } ] }
+
 RULES:
 - --enabled on a tap makes it match only a control that is ACTIONABLE right now, and (with
   auto-wait) wait until it becomes so. Use it for any button that the app disables until
   something else is done — a Check/Submit/Continue that only lights up once an answer is
   selected or a form is valid. Without it the step taps a dead control, does nothing, and
   the failure surfaces later as a confusing timeout on the NEXT step.
+- A picker or toggle whose options share ONE handler FLIPS on any tap, so an unconditional
+  "tap the option you want" lands on the option you did NOT want whenever it was already
+  chosen — and its starting state is usually content-driven, so you cannot know it now.
+  Guard it: if-present "id:<option> --not-selected" { tap id:<option> }. The guard makes an
+  already-correct state a no-op instead of a flip. Unguarded, the flow completes either way
+  and the test PASSES having exercised the opposite mode — a false green, worse than a fail.
+  Same shape for a checkbox that toggles: guard with --not-checked / --checked.
 - assert is for VERIFICATION only and is terminal — never use it as a step you expect to
   fail. Put genuinely-optional UI behind if-present.
 - tap/text SCROLL THEIR TARGET INTO VIEW automatically, so "scroll down to X and tap it"

package/dist/args.js

@@ -44,6 +44,19 @@ const BOOLEAN = new Set([
     'no-restart',
     'allow-install',
     'allow-unsafe-anonymous',
+    // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.
+    // `enabled` was missing here until 0.15.0, and the omission was not cosmetic: a
+    // non-BOOLEAN flag swallows the next token, so `vk tap --enabled @submit` bound
+    // the SELECTOR as the flag's value and died with "Missing selector". Only the
+    // trailing form worked. Any new modifier must be listed here.
+    'enabled',
+    'selected',
+    'checked',
+    'focused',
+    'not-enabled',
+    'not-selected',
+    'not-checked',
+    'not-focused',
 ]);
 function parseArgs(argv) {
     const positionals = [];

package/dist/cli.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.platformFromFlags = platformFromFlags;
 exports.deviceFromFlags = deviceFromFlags;
+exports.stateFromFlags = stateFromFlags;
 exports.parsePoint = parsePoint;
 exports.healNote = healNote;
 exports.parseDuration = parseDuration;
@@ -58,6 +59,7 @@ const errors_1 = require("./errors");
 const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
 const selector_1 = require("./ui/selector");
+const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
 const viewport_1 = require("./ui/viewport");
 const output_1 = require("./output");
@@ -93,15 +95,42 @@ function deviceFromFlags(flags, platform) {
         (platform === 'android' ? process.env.ANDROID_SERIAL : undefined) ||
         undefined);
 }
-function buildSelector(raw, flags) {
+/**
+ * Read the `--enabled` / `--not-enabled` / `--selected` / … pairs off the flags.
+ *
+ * An ABSENT flag must stay `undefined`, never `false`: these modifiers are tri-state
+ * ("must be" / "must not be" / "don't care"), so passing `flagBool()` straight through —
+ * which is what this replaced — would quietly turn every selector on every command into
+ * "must be disabled, unselected, unchecked and unfocused".
+ */
+function stateFromFlags(flags) {
+    const state = {};
+    for (const attr of selector_1.STATE_ATTRS) {
+        const yes = (0, args_1.flagBool)(flags, attr);
+        const no = (0, args_1.flagBool)(flags, `not-${attr}`);
+        if (yes && no)
+            throw new errors_1.CliError(`Cannot combine --${attr} with --not-${attr}.`, 2);
+        if (yes)
+            state[attr] = true;
+        else if (no)
+            state[attr] = false;
+    }
+    return state;
+}
+function buildSelector(ctx, raw) {
     if (!raw) {
         throw new errors_1.CliError('Missing selector. e.g. `@login_button`, `text:Login`, `desc:Submit`.', 2);
     }
-    return (0, selector_1.parseSelector)(raw, {
-        contains: (0, args_1.flagBool)(flags, 'contains'),
-        index: (0, args_1.flagNum)(flags, 'index'),
-        enabled: (0, args_1.flagBool)(flags, 'enabled'),
+    const sel = (0, selector_1.parseSelector)(raw, {
+        contains: (0, args_1.flagBool)(ctx.flags, 'contains'),
+        index: (0, args_1.flagNum)(ctx.flags, 'index'),
+        ...stateFromFlags(ctx.flags),
     });
+    // Every command's selector — and so every `vk ai` leaf, which reaches these handlers
+    // through executeOutcome — funnels through here, which is why the platform check lives
+    // at this seam rather than in the (platform-free) selector layer.
+    (0, state_support_1.assertStateSupported)(sel, ctx.platform);
+    return sel;
 }
 function parsePoint(s) {
     const m = /^(-?\d+)\s*,\s*(-?\d+)$/.exec(s.trim());
@@ -458,7 +487,7 @@ function cmdUi(ctx) {
     return 0;
 }
 async function cmdFind(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const { matches, tier } = await matchWaiting(ctx, sel, { all: (0, args_1.flagBool)(ctx.flags, 'all') });
     if ((0, args_1.flagBool)(ctx.flags, 'json'))
         (0, output_1.json)(matches.map(format_1.toJsonShape));
@@ -511,7 +540,7 @@ async function cmdTap(ctx) {
         ctx.record?.note({ element: target, message: `tapped by index [${idx}]` });
     }
     else {
-        const sel = buildSelector(raw, ctx.flags);
+        const sel = buildSelector(ctx, raw);
         ({ element: target, tier, waitedMs, swipes, point } = await resolveTappable(ctx, sel, {
             all: (0, args_1.flagBool)(ctx.flags, 'all'),
         }));
@@ -530,7 +559,7 @@ async function cmdText(ctx) {
     if (ctx.positionals.length < 2) {
         throw new errors_1.CliError('Usage: verikun text <selector> <text...>  (use -- before text starting with "-")', 2);
     }
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const value = ctx.positionals.slice(1).join(' ');
     const { element: target, tier, waitedMs, swipes, point } = await resolveTappable(ctx, sel);
     ctx.record?.note({
@@ -606,7 +635,9 @@ async function cmdSwipe(ctx) {
     let waitedMs = 0;
     const on = (0, args_1.flagStr)(ctx.flags, 'on');
     if (on) {
-        const onSel = (0, selector_1.parseSelector)(on, { contains: (0, args_1.flagBool)(ctx.flags, 'contains') });
+        // Through buildSelector, not parseSelector: --on used to see only --contains, so
+        // `swipe --on X --enabled` silently ignored the modifier it was given.
+        const onSel = buildSelector(ctx, on);
         const { element, waitedMs: w } = await resolveOneWaiting(ctx, onSel);
         waitedMs = w;
         ctx.record?.note({ selector: onSel, element });
@@ -762,7 +793,7 @@ function cmdLog(ctx) {
     return 0;
 }
 async function cmdWait(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     const gone = (0, args_1.flagBool)(ctx.flags, 'gone');
     const timeout = (0, args_1.flagNum)(ctx.flags, 'timeout') ?? 10000;
     const interval = (0, args_1.flagNum)(ctx.flags, 'interval') ?? 400;
@@ -822,7 +853,7 @@ function evalAssert(els, sel, flags) {
     return { pass, reason, matches };
 }
 async function cmdAssert(ctx) {
-    const sel = buildSelector(ctx.positionals[0], ctx.flags);
+    const sel = buildSelector(ctx, ctx.positionals[0]);
     // Auto-wait subsumes the common "wait then assert": poll until the assertion
     // passes or the window elapses. `--gone` therefore waits for disappearance.
     const deadline = Date.now() + waitWindowMs(ctx.flags);
@@ -1353,6 +1384,9 @@ async function runAiTest(file, opts, backend, platform, device) {
             guardSettleMs: guardSettleMs(),
             runId: started.id,
             deadline,
+            // The RESOLVED platform — for --server that is the server's, which supersedes
+            // the client's --platform (leaves are gated server-side; guards run here).
+            platform,
         });
     }
     catch (e) {
@@ -1503,7 +1537,7 @@ async function cmdInstall(positionals, flags) {
 async function cmdSuiteEntry(positionals, flags) {
     const dirArg = positionals[0];
     if (!dirArg)
-        throw new errors_1.CliError('Usage: verikun suite <dir> [--app <id>] [--server url] [--name n] [--json]', 2);
+        throw new errors_1.CliError('Usage: verikun suite <dir> [--app <id>] [--server url] [--name n] [--retries n] [--json]', 2);
     const opts = parseAiOptions(flags);
     // Pre-flight the provider BEFORE touching any device/server: every test needs it
     // to compile (on a cache miss) or to repair at runtime.
@@ -1815,14 +1849,19 @@ AI (run a natural-language test — compile once, replay model-free, self-heal)
                                       codex-cli | cursor-cli.
 
 SUITE (run a directory of natural-language tests as one gated suite)
-  suite <dir> [--app <id>] [--name n] [--json]  (+ all \`ai\` flags, incl. --server)
+  suite <dir> [--app <id>] [--name n] [--retries n] [--json]
+                                      (+ all \`ai\` flags, incl. --server)
                                       Run every *.md in <dir> (lexicographic order —
                                       prefix 01-, 02- to sequence; README.md skipped)
                                       through \`vk ai\`. With --app, app data is reset
-                                      between tests (iOS: force-stop). Writes a suite
-                                      overview to ./.verikun/suites/<id>/{index.json,
-                                      index.html} linking each test's report. Exits 1
-                                      if any test failed — the CI gate.
+                                      between tests (iOS: force-stop). --retries N
+                                      re-runs a failed test up to N times; a later
+                                      pass recovers the suite (exit 0) and surfaces a
+                                      warning, keeping failed-attempt evidence in the
+                                      report. Writes a suite overview to
+                                      ./.verikun/suites/<id>/{index.json, index.html}
+                                      linking each test's report. Exits 1 if any test
+                                      failed — the CI gate.
 
 SERVER (expose a locally-connected device to remote verikun clients)
   server [--bind addr] [--port n] [--auth-key k] [--allow-install]
@@ -1859,6 +1898,15 @@ SELECTORS
   class:Button    type or full class name
   "Sign in"       bare string == text:"Sign in"
   Modifiers: --contains (substring), --index N (pick Nth match)
+  State:     --enabled / --selected / --checked / --focused, each with a --not-
+             form (--not-selected). Unset = don't care. Use the negative to guard
+             a toggle: tapping a picker whose options share a handler FLIPS it, so
+             an unconditional tap lands on the wrong mode and still exits 0.
+             May be written as a flag or appended to the selector string
+             ("@mode_video --not-selected") — the latter is how a \`vk ai\`
+             if-present/when/repeat guard carries one.
+             --selected and --focused are Android-only (idb reports neither);
+             on iOS they exit 3 rather than matching nothing.
 
 AUTO-WAIT (selector lookups retry until they resolve)
   Selector commands (tap, text, find, assert, swipe --on) re-poll the screen for

package/dist/report.js

@@ -118,6 +118,7 @@ const STYLE = `
   .summary { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-bottom: 20px; }
   .chip { font-weight:600; font-size:13px; padding:4px 10px; border-radius:999px; color:#fff; }
   .chip.pass{background:var(--pass)} .chip.fail{background:var(--fail)} .chip.err{background:var(--err)}
+  .chip.warn{background:var(--err)}
   .chip.muted{ background:#eaeef2; color:var(--muted); }
   ol.steps { list-style:none; margin:0; padding:0; }
   li.step { background:#fff; border:1px solid var(--line); border-left-width:4px; border-radius:8px; margin-bottom:10px; padding:12px 14px; }
@@ -206,19 +207,40 @@ const SUITE_STYLE = `
   table.tests td.num { text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap; }
   table.tests a { color:inherit; }
   .fail-reason { color:var(--fail); font-size:12px; margin-top:2px; }
+  .flake-note { color:var(--err); font-size:12px; margin-top:2px; }
+  .attempts { margin-top:4px; font-size:12px; color:var(--muted); }
+  .attempts a { color:var(--fail); }
   .aborted { background:#fff4e5; border:1px solid #f0b429; border-radius:8px; padding:12px 14px; margin:0 0 14px; font-size:13px; }
   .aborted strong { color:#8a5300; }
   .aborted ul { margin:6px 0 0; padding-left:20px; color:var(--muted); }
+  .warnings { background:#fff8c5; border:1px solid #d4a72c; border-radius:8px; padding:12px 14px; margin:0 0 14px; font-size:13px; }
+  .warnings strong { color:#7d4e00; }
+  .warnings ul { margin:6px 0 0; padding-left:20px; color:var(--muted); }
 `;
+function suiteAttemptLinks(attempts, linkBase) {
+    const links = attempts
+        .map((a, i) => {
+        const label = `attempt ${i + 1}`;
+        if (!a.id)
+            return htmlEsc(label);
+        return `<a href="${htmlEsc(`${linkBase}runs/${encodeURIComponent(a.id)}/report.html`)}">${htmlEsc(label)}</a>`;
+    })
+        .join(', ');
+    return `<div class="attempts">prior failed: ${links}</div>`;
+}
 function suiteTestRow(t, linkBase) {
     // A test that errored before its run started (id '') has no report to link.
     const label = t.id
         ? `<a href="${htmlEsc(`${linkBase}runs/${encodeURIComponent(t.id)}/report.html`)}">${htmlEsc(t.name)}</a>`
         : htmlEsc(t.name);
     const failure = t.failure ? `<div class="fail-reason">${htmlEsc(t.failure)}</div>` : '';
+    const flake = t.flaky ? `<div class="flake-note">passed on retry (flake)</div>` : '';
+    const prior = t.attempts?.length ? suiteAttemptLinks(t.attempts, linkBase) : '';
+    const status = t.flaky ? 'FLAKY' : t.ok ? 'PASS' : 'FAIL';
+    const statusClass = t.ok ? 'passed' : 'failed';
     return `  <tr>
-    <td><span class="st ${t.ok ? 'passed' : 'failed'}">${t.ok ? 'PASS' : 'FAIL'}</span></td>
-    <td>${label}${failure}</td>
+    <td><span class="st ${statusClass}">${status}</span></td>
+    <td>${label}${flake}${failure}${prior}</td>
     <td class="num">${t.passedSteps}/${t.steps}${t.failedSteps ? ` (${t.failedSteps} failed)` : ''}</td>
     <td class="num">${t.modelRepairs || ''}</td>
     <td class="num">$${t.costUsd.toFixed(4)}</td>
@@ -233,9 +255,11 @@ function suiteTestRow(t, linkBase) {
 function toSuiteHtml(suite, opts = {}) {
     const linkBase = opts.linkBase ?? '../../';
     const t = suite.totals;
+    const flaky = suite.tests.filter((x) => x.flaky).length;
     const chips = [
         `<span class="chip pass">${t.passed} passed</span>`,
         t.failed ? `<span class="chip fail">${t.failed} failed</span>` : '',
+        flaky ? `<span class="chip warn">${flaky} flaky</span>` : '',
         suite.aborted ? `<span class="chip fail">ABORTED</span>` : '',
         `<span class="chip muted">${t.tests} tests &middot; ${t.steps} steps &middot; ${fmtDuration(t.durationMs)} &middot; $${t.costUsd.toFixed(4)}</span>`,
     ]
@@ -250,6 +274,13 @@ function toSuiteHtml(suite, opts = {}) {
 ${suite.aborted.notRun.length
             ? `    <ul>${suite.aborted.notRun.map((f) => `<li>${htmlEsc(f)} — not run</li>`).join('')}</ul>\n`
             : ''}  </div>
+`
+        : '';
+    const warningsBanner = suite.warnings?.length
+        ? `  <div class="warnings">
+    <strong>Warnings</strong>
+    <ul>${suite.warnings.map((w) => `<li>${htmlEsc(w)}</li>`).join('')}</ul>
+  </div>
 `
         : '';
     const metaBits = [
@@ -274,7 +305,7 @@ ${suite.aborted.notRun.length
   <div class="summary">
       ${chips}
   </div>
-${abortedBanner}  <table class="tests">
+${abortedBanner}${warningsBanner}  <table class="tests">
     <thead><tr><th></th><th>Test</th><th>Steps</th><th>Repairs</th><th>Cost</th><th>Duration</th></tr></thead>
     <tbody>
 ${suite.tests.map((x) => suiteTestRow(x, linkBase)).join('\n')}

package/dist/suite.js

@@ -13,6 +13,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sortTestFiles = sortTestFiles;
 exports.listTestFiles = listTestFiles;
 exports.toSuiteResult = toSuiteResult;
+exports.toSuiteAttempt = toSuiteAttempt;
+exports.mergeSuiteAttempts = mergeSuiteAttempts;
 exports.cmdSuite = cmdSuite;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -100,6 +102,64 @@ function toSuiteResult(file, r, durationMs) {
         ...(r.ok ? {} : { failure: failure ?? 'failed' }),
     };
 }
+/** Compact one attempt for the `attempts` evidence array (pure). */
+function toSuiteAttempt(r) {
+    return {
+        id: r.id,
+        ok: r.ok,
+        durationMs: r.durationMs,
+        costUsd: r.costUsd,
+        ...(r.failure ? { failure: r.failure } : {}),
+    };
+}
+/**
+ * Merge a sequence of attempt rows into the final suite row: primary `id` is the last
+ * attempt (winning green, or last red), cost/duration/repairs sum across attempts, and
+ * prior attempts are retained as flake evidence.
+ */
+function mergeSuiteAttempts(attempts) {
+    if (attempts.length === 0)
+        throw new Error('mergeSuiteAttempts: empty');
+    const last = attempts[attempts.length - 1];
+    if (attempts.length === 1)
+        return last;
+    const round = (n) => Number(n.toFixed(4));
+    const prior = attempts.slice(0, -1).map(toSuiteAttempt);
+    const flaky = last.ok && prior.some((a) => !a.ok);
+    return {
+        ...last,
+        durationMs: attempts.reduce((a, t) => a + t.durationMs, 0),
+        costUsd: round(attempts.reduce((a, t) => a + t.costUsd, 0)),
+        modelRepairs: attempts.reduce((a, t) => a + t.modelRepairs, 0),
+        attempts: prior,
+        ...(flaky ? { flaky: true } : {}),
+    };
+}
+// What --retries will and won't spend an attempt on. The bias is deliberate and
+// asymmetric: a retry costs one test, while giving up costs the whole suite plus a
+// human rerunning it. So the rule is *retry unless a rerun provably cannot change the
+// outcome* — the two predicates below are the only "provably" cases, everything else
+// (flaky selector, wedged app, a wobbling network to `vk server`) earns another go.
+/** Budget aborts won't heal on retry: each attempt gets its own cost ceiling, so a
+ *  rerun just re-aborts at the same place having spent the money twice. */
+function isRetryable(r) {
+    return !r.ok && !r.abortedForBudget;
+}
+/** A thrown USAGE error (exit 2) is the one throw a rerun cannot change — an unreadable
+ *  test file, a payload the server refuses, a flag it doesn't understand. Everything
+ *  else, including every environment error, is retried while attempts remain. */
+function isRetryableThrow(e) {
+    return !(e instanceof errors_1.CliError && e.exitCode === 2);
+}
+function parseRetries(flags) {
+    const n = (0, args_1.flagNum)(flags, 'retries');
+    if (n === undefined)
+        return 0;
+    if (!Number.isInteger(n) || n < 0) {
+        throw new errors_1.CliError(`--retries must be a non-negative integer, got '${n}'`, 2);
+    }
+    return n;
+}
 async function cmdSuite(dirArg, flags, deps) {
     const dir = (0, node_path_1.resolve)(process.cwd(), dirArg);
     if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory()) {
@@ -109,69 +169,133 @@ async function cmdSuite(dirArg, flags, deps) {
     if (files.length === 0) {
         throw new errors_1.CliError(`suite: no test files (*.md) in '${dirArg}'`, 2);
     }
+    const retries = parseRetries(flags);
     const suiteId = (0, run_1.runId)();
     const name = (0, args_1.flagStr)(flags, 'name') || (0, node_path_1.basename)(dir);
     const startedAt = new Date().toISOString();
-    (0, output_1.err)(`[suite] '${name}': ${files.length} test(s) from ${dirArg} (${deps.platform}${deps.device ? ` · ${deps.device}` : ''})`);
+    (0, output_1.err)(`[suite] '${name}': ${files.length} test(s) from ${dirArg} (${deps.platform}${deps.device ? ` · ${deps.device}` : ''})${retries > 0 ? ` · up to ${retries} retry(ies) on failure` : ''}`);
     const results = [];
+    const warnings = [];
     let aborted;
+    async function resetApp(label) {
+        // Returns the abort reason when the suite should stop (confirmed env break during reset).
+        if (!deps.reset)
+            return undefined;
+        try {
+            await deps.reset();
+            (0, output_1.err)(`[suite] app state reset${label}`);
+            return undefined;
+        }
+        catch (e) {
+            // A reset that failed because the BOX is broken means nothing after it is
+            // trustworthy — but only if a re-probe agrees. Otherwise surface and continue:
+            // a flaky reset should not zero out the whole suite, and the test itself will
+            // fail loudly if the stale state actually matters.
+            const broken = (0, errors_1.isEnvError)(e) ? await stillBroken(deps) : undefined;
+            if (broken)
+                return broken;
+            (0, output_1.err)(`[suite] reset failed (${e.message}) — continuing`);
+            return undefined;
+        }
+    }
+    /** A confirmed env break with attempts left: say so, pause, and let the loop retry.
+     *  The pause matters — the failures this rides out (a server restart, a wifi drop, a
+     *  USB re-enumeration) clear in seconds, and retrying into the same dead socket
+     *  immediately would burn every attempt inside the outage. */
+    async function noteEnvRetry(file, attempt, reason) {
+        const warn = `${file}: environment error on attempt ${attempt + 1} (${reason}) — retried`;
+        warnings.push(warn);
+        (0, output_1.err)(`[suite] WARN ${warn}`);
+        await sleep((deps.probeRetryMs ?? PROBE_RETRY_MS) * (attempt + 1));
+    }
     for (let i = 0; i < files.length && !aborted; i++) {
         const file = files[i];
         (0, output_1.err)(`[suite] ── (${i + 1}/${files.length}) ${file} ──`);
-        if (deps.reset) {
+        const attemptRows = [];
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            // The last attempt is where a retryable failure becomes the verdict: a confirmed
+            // env break aborts the suite, anything else stands as this test's failed row.
+            const lastAttempt = attempt === retries;
+            if (attempt > 0)
+                (0, output_1.err)(`[suite] retry ${attempt}/${retries} for ${file}`);
+            // Re-isolate before EVERY attempt — between tests and between retries alike.
+            const resetBreak = await resetApp(attempt > 0 ? ' (retry)' : '');
+            if (resetBreak) {
+                if (!lastAttempt) {
+                    await noteEnvRetry(file, attempt, `reset failed: ${resetBreak}`);
+                    continue;
+                }
+                // With no attempt row this test never ran, so notRun starts at the CURRENT file.
+                aborted = {
+                    reason: `reset failed: ${resetBreak}`,
+                    notRun: files.slice(attemptRows.length ? i + 1 : i),
+                };
+                break;
+            }
+            const t0 = Date.now();
             try {
-                await deps.reset();
-                (0, output_1.err)('[suite] app state reset');
+                const r = await deps.runTest((0, node_path_1.join)(dir, file));
+                attemptRows.push(toSuiteResult(file, r, Date.now() - t0));
+                if (r.abortedForEnv) {
+                    const broken = await stillBroken(deps);
+                    if (broken) {
+                        if (!lastAttempt) {
+                            // Even a CONFIRMED break is worth an attempt: the probe window is a couple
+                            // of seconds, which a server restart outlives — and aborting costs the run.
+                            await noteEnvRetry(file, attempt, broken);
+                            continue;
+                        }
+                        aborted = { reason: broken, notRun: files.slice(i + 1) };
+                        break;
+                    }
+                    // Transient env blip: retryable like any other failure.
+                }
+                if (r.ok || !isRetryable(r) || lastAttempt)
+                    break;
             }
             catch (e) {
-                // A reset that failed because the BOX is broken means nothing after it is
-                // trustworthy — but only if a re-probe agrees. Otherwise surface and continue:
-                // a flaky reset should not zero out the whole suite, and the test itself will
-                // fail loudly if the stale state actually matters.
+                // A test that THREW (device gone, server unreachable, bad file) still becomes a
+                // failed row — one broken test must not vaporize the suite report for the tests
+                // that already ran. Out of attempts, a confirmed env break stops the suite.
+                const msg = e instanceof Error ? e.message : String(e);
+                (0, output_1.err)(`[suite] ${file} errored: ${msg}`);
+                attemptRows.push({
+                    id: '',
+                    file,
+                    name: (0, node_path_1.basename)(file, (0, node_path_1.extname)(file)),
+                    ok: false,
+                    durationMs: Date.now() - t0,
+                    costUsd: 0,
+                    steps: 0,
+                    passedSteps: 0,
+                    failedSteps: 0,
+                    modelRepairs: 0,
+                    failure: msg.split('\n')[0],
+                });
                 const broken = (0, errors_1.isEnvError)(e) ? await stillBroken(deps) : undefined;
-                if (broken) {
-                    // This test never ran, so it gets no row — notRun starts at the CURRENT file.
-                    aborted = { reason: `reset failed: ${broken}`, notRun: files.slice(i) };
+                if (lastAttempt) {
+                    if (broken)
+                        aborted = { reason: broken, notRun: files.slice(i + 1) };
                     break;
                 }
-                (0, output_1.err)(`[suite] reset failed (${e.message}) — continuing`);
-            }
-        }
-        const t0 = Date.now();
-        try {
-            const r = await deps.runTest((0, node_path_1.join)(dir, file));
-            results.push(toSuiteResult(file, r, Date.now() - t0));
-            // The test itself reported an environment abort (exit 3 mid-plan). Same rule:
-            // fatal only if the box is still broken. This test HAS a row and a real report,
-            // so notRun starts after it.
-            if (r.abortedForEnv) {
-                const broken = await stillBroken(deps);
+                if (!isRetryableThrow(e))
+                    break;
                 if (broken)
-                    aborted = { reason: broken, notRun: files.slice(i + 1) };
+                    await noteEnvRetry(file, attempt, broken);
             }
         }
-        catch (e) {
-            // A test that THREW (device gone, server unreachable, bad file) still becomes a
-            // failed row — one broken test must not vaporize the suite report for the tests
-            // that already ran. But if it threw because the environment is gone, stop.
-            const msg = e instanceof Error ? e.message : String(e);
-            (0, output_1.err)(`[suite] ${file} errored: ${msg}`);
-            results.push({
-                id: '',
-                file,
-                name: (0, node_path_1.basename)(file, (0, node_path_1.extname)(file)),
-                ok: false,
-                durationMs: Date.now() - t0,
-                costUsd: 0,
-                steps: 0,
-                passedSteps: 0,
-                failedSteps: 0,
-                modelRepairs: 0,
-                failure: msg.split('\n')[0],
-            });
-            const broken = (0, errors_1.isEnvError)(e) ? await stillBroken(deps) : undefined;
-            if (broken)
-                aborted = { reason: broken, notRun: files.slice(i + 1) };
+        if (attemptRows.length === 0) {
+            // Every attempt was blocked by a failing reset, so the test never ran and gets no
+            // row — `aborted.notRun` (set above) already names it. Nothing to merge.
+            break;
+        }
+        const merged = mergeSuiteAttempts(attemptRows);
+        results.push(merged);
+        if (merged.flaky) {
+            const n = merged.attempts?.length ?? 0;
+            const warn = `${file} passed on retry after ${n} failed attempt${n === 1 ? '' : 's'}`;
+            warnings.push(warn);
+            (0, output_1.err)(`[suite] WARN ${warn}`);
         }
     }
     if (aborted) {
@@ -189,6 +313,7 @@ async function cmdSuite(dirArg, flags, deps) {
         totals: (0, report_1.suiteTotals)(results),
         tests: results,
         ...(aborted ? { aborted } : {}),
+        ...(warnings.length ? { warnings } : {}),
     };
     // .verikun/suites/<id>/ sits beside .verikun/runs/<id>/, so index.html reaches a
     // test report at ../../runs/<id>/report.html — the linkBase below.
@@ -198,8 +323,12 @@ async function cmdSuite(dirArg, flags, deps) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'index.html'), (0, report_1.toSuiteHtml)(suite, { linkBase: '../../' }));
     const t = suite.totals;
     (0, output_1.err)(`[suite] ${t.passed}/${t.tests} passed · ${t.steps} steps · $${t.costUsd.toFixed(4)} · ${(t.durationMs / 1000).toFixed(1)}s`);
-    for (const r of results)
-        (0, output_1.err)(`  ${r.ok ? 'PASS' : 'FAIL'} ${r.file}${r.failure ? ` — ${r.failure}` : ''}`);
+    for (const r of results) {
+        const tag = r.flaky ? 'FLAKY' : r.ok ? 'PASS' : 'FAIL';
+        (0, output_1.err)(`  ${tag} ${r.file}${r.failure ? ` — ${r.failure}` : r.flaky ? ' — passed on retry' : ''}`);
+    }
+    if (warnings.length)
+        (0, output_1.err)(`[suite] ${warnings.length} warning(s)`);
     (0, output_1.err)(`[suite] overview: ${(0, node_path_1.join)(outDir, 'index.html')}`);
     if ((0, args_1.flagBool)(flags, 'json'))
         (0, output_1.json)(suite);
@@ -207,6 +336,7 @@ async function cmdSuite(dirArg, flags, deps) {
         (0, output_1.out)(outDir); // primary machine result: the suite directory
     // The CI gate: any failed test fails the invocation (mirrors `vk run archive`). An
     // environment abort exits 3 instead, so CI can tell "the runner is broken" from "the
-    // app regressed" — the whole point of stopping early.
+    // app regressed" — the whole point of stopping early. A flake that recovered is ok
+    // (exit 0) with a warning — that is the whole point of --retries.
     return aborted ? 3 : t.failed > 0 ? 1 : 0;
 }

package/dist/ui/ios-parse.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IOS_UNREPORTED_STATE = void 0;
 exports.isInteresting = isInteresting;
 exports.parseIosHierarchy = parseIosHierarchy;
 const viewport_1 = require("./viewport");
@@ -13,6 +14,23 @@ const TAPPABLE_TYPES = new Set([
 const SCROLLABLE_TYPES = new Set(['ScrollView', 'Table', 'TableView', 'CollectionView', 'WebView']);
 const CHECKABLE_TYPES = new Set(['Switch', 'Toggle', 'CheckBox', 'RadioButton']);
 const TEXT_INPUT_TYPES = new Set(['TextField', 'SecureTextField', 'SearchField', 'TextView']);
+/**
+ * State attributes idb does not report, so `Element` can only ever say `false`.
+ *
+ * MEASURED against the Flutter fixture's `@vk_state` screen on an iPhone 17 Pro simulator
+ * (iOS 26.5): a selected and an unselected segment came back byte-identical apart from
+ * label and frame, and a focused text field was indistinguishable from an unfocused one.
+ * The key is not merely unset — `idb ui describe-all` has no such key in its schema at all
+ * (it emits AXFrame, AXLabel, AXUniqueId, AXValue, content_required, custom_actions,
+ * enabled, frame, help, role, role_description, subrole, title, type, and nothing else),
+ * so no app can supply it and there is nothing to derive it from.
+ *
+ * Exported so `--selected` / `--focused` can be REJECTED on iOS rather than silently
+ * matching nothing — a filter that can never match is exactly the false-green failure the
+ * modifier exists to prevent. Keep this list next to the hard-coded `false`s below; if idb
+ * ever starts reporting one, delete it from here in the same change that parses it.
+ */
+exports.IOS_UNREPORTED_STATE = ['selected', 'focused'];
 function str(v) {
     return typeof v === 'string' ? v : v == null ? '' : String(v);
 }
@@ -81,6 +99,7 @@ function buildElement(raw) {
         checkable,
         checked: checkable && isTrue(raw.AXValue),
         focusable: false,
+        // `focused` and `selected` are not derivable — see IOS_UNREPORTED_STATE above.
         focused: false,
         scrollable: SCROLLABLE_TYPES.has(type),
         enabled: raw.enabled === undefined ? true : isTrue(raw.enabled),

package/dist/ui/selector.js

@@ -1,19 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_ATTRS = void 0;
 exports.parseSelector = parseSelector;
 exports.matchElements = matchElements;
 exports.resolveOne = resolveOne;
 const errors_1 = require("../errors");
 const format_1 = require("./format");
+/**
+ * The element state a selector can require. Each is TRI-STATE on a Selector:
+ * unset = don't care, `true` = must be, `false` = must NOT be.
+ *
+ * The negative half is not symmetry for its own sake. A segmented control whose
+ * options share one handler *flips* on any tap, so "tap it unless it is already
+ * selected" is the only safe way to land on a known option — and a plan that
+ * cannot say that taps blind, completes either way, and passes having exercised
+ * the opposite mode.
+ */
+exports.STATE_ATTRS = ['enabled', 'selected', 'checked', 'focused'];
+/** Trailing ` --selected` / ` --not-checked` / … on a selector STRING. */
+const STATE_MODIFIER = new RegExp(`\\s+--(not-)?(${exports.STATE_ATTRS.join('|')})\\s*$`, 'i');
+/**
+ * Peel state modifiers off the END of a selector string.
+ *
+ * Flags normally arrive as flags, but a control node's selector has nowhere to put
+ * one: `if-present` / `when` / `repeat` / `while-present` / `read` all hold a bare
+ * `selector: string` (and `swipe --on` is a flag value). Guards are exactly where
+ * "tap it only if it is not already selected" needs to be expressed, so the string
+ * itself carries them and every caller converges on this one parser:
+ *
+ *     if-present "id:mode_video --not-selected" { tap id:mode_video }
+ *
+ * Only these modifiers, only at the end, and only after whitespace — so `text:--selected`
+ * and `text:a --selected b` are still plain values. A `text:` value that genuinely ENDS
+ * in " --selected" would be misread; use `--contains` on a shorter substring if you ever
+ * meet one. Note the engine interpolates `{{ctx.…}}` before parsing, so a value captured
+ * by `read` could in principle end in a modifier — end-anchoring plus the required space
+ * is what keeps that from being a practical concern.
+ */
+function splitStateModifiers(raw) {
+    const state = {};
+    let rest = raw;
+    for (;;) {
+        const m = STATE_MODIFIER.exec(rest);
+        if (!m)
+            return { rest, state };
+        const attr = m[2].toLowerCase();
+        const want = !m[1];
+        if (state[attr] !== undefined && state[attr] !== want) {
+            throw new errors_1.CliError(`Selector '${raw}' asks for both --${attr} and --not-${attr}.`, 2);
+        }
+        state[attr] = want;
+        rest = rest.slice(0, m.index);
+    }
+}
 function parseSelector(raw, opts = {}) {
+    const { rest, state } = splitStateModifiers(raw);
     let kind = 'text';
-    let value = raw;
-    if (raw.startsWith('@')) {
+    let value = rest;
+    if (rest.startsWith('@')) {
         kind = 'id';
-        value = raw.slice(1);
+        value = rest.slice(1);
     }
     else {
-        const m = /^(id|text|desc|class):([\s\S]*)$/.exec(raw);
+        const m = /^(id|text|desc|class):([\s\S]*)$/.exec(rest);
         if (m) {
             kind = m[1];
             value = m[2];
@@ -21,20 +70,35 @@ function parseSelector(raw, opts = {}) {
     }
     if (!value)
         throw new errors_1.CliError(`Empty selector value in '${raw}'`, 2);
-    return { kind, value, contains: !!opts.contains, index: opts.index, enabled: opts.enabled, raw };
+    const sel = { kind, value, contains: !!opts.contains, index: opts.index, raw };
+    for (const attr of exports.STATE_ATTRS) {
+        // An explicit flag beats one embedded in the string; absent means absent, not false.
+        const want = opts[attr] !== undefined ? opts[attr] : state[attr];
+        if (want !== undefined)
+            sel[attr] = want;
+    }
+    return sel;
 }
-/** Is this element actionable right now?
+/** Keep only elements whose state matches every attribute the selector pins.
  *
- *  Just `enabled` — the a11y attribute, matching what Maestro's `enabled: true` means.
- *  An earlier version also required `clickable || longClickable`, reasoning that a
- *  disabled Button might report clickable=false. That was speculation and it was wrong in
- *  the direction that hurts: plenty of legitimate tap targets are CONTAINERS whose own
- *  clickable flag is false (the tappable child is inside), so the extra conjunct filtered
- *  out real elements and turned `--enabled` into a source of phantom "not found" misses —
- *  which then burned model repairs. Prefer under-filtering here: a tap on a present-but-
- *  odd element fails loudly, whereas a selector that silently matches nothing looks like
- *  app drift and sends the heal loop chasing it. */
-const isActionable = (e) => e.enabled;
+ *  Each predicate is exactly the one a11y attribute and nothing else — `--enabled` is
+ *  `enabled`, matching what Maestro's `enabled: true` means. An earlier version also
+ *  required `clickable || longClickable`, reasoning that a disabled Button might report
+ *  clickable=false. That was speculation and it was wrong in the direction that hurts:
+ *  plenty of legitimate tap targets are CONTAINERS whose own clickable flag is false (the
+ *  tappable child is inside), so the extra conjunct filtered out real elements and turned
+ *  `--enabled` into a source of phantom "not found" misses — which then burned model
+ *  repairs. Prefer under-filtering here: a tap on a present-but-odd element fails loudly,
+ *  whereas a selector that silently matches nothing looks like app drift and sends the
+ *  heal loop chasing it. Same rule for any attribute added to STATE_ATTRS — do not
+ *  strengthen a predicate with a conjunct the platform reports unreliably (`--not-checked`
+ *  deliberately does NOT also require `checkable`). */
+function filterByState(elements, sel) {
+    const pinned = exports.STATE_ATTRS.filter((attr) => sel[attr] !== undefined);
+    if (pinned.length === 0)
+        return elements;
+    return elements.filter((el) => pinned.every((attr) => el[attr] === sel[attr]));
+}
 const norm = (s) => s.trim().toLowerCase();
 const strip = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '');
 /** The ordered match tiers for a selector. First tier with a hit wins. */
@@ -91,8 +155,7 @@ function tiers(sel) {
 function matchElements(elements, sel) {
     // Applied BEFORE the tier ladder, not after: filtering the candidate pool keeps a
     // disabled exact match from shadowing an enabled partial one.
-    if (sel.enabled)
-        elements = elements.filter(isActionable);
+    elements = filterByState(elements, sel);
     for (const { tier, test } of tiers(sel)) {
         const found = elements.filter(test);
         if (found.length === 0)

package/dist/ui/state-support.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsupportedStateAttrs = unsupportedStateAttrs;
+exports.assertStateSupported = assertStateSupported;
+const errors_1 = require("../errors");
+const selector_1 = require("./selector");
+const ios_parse_1 = require("./ios-parse");
+// Which state attributes a platform's accessibility backend can actually answer for.
+//
+// A state modifier narrows the candidate pool, so one the platform never populates does
+// not fail — it matches NOTHING, quietly, after burning the full auto-wait window, and
+// then reports "No element matched selector", which is a claim about the screen that
+// isn't true. That is the same false-signal failure mode `--selected` was added to fix,
+// so it is refused here instead: an unsupported modifier is an environment error (exit
+// 3), the way `clearApp` and `currentApp` already refuse on iOS rather than pretending.
+//
+// This is a capability table, not device I/O — the per-platform truth lives with the
+// parser that hard-codes the value (see IOS_UNREPORTED_STATE), so the two cannot drift.
+const UNREPORTED = {
+    android: [], // uiautomator dumps all four as real node attributes
+    ios: ios_parse_1.IOS_UNREPORTED_STATE,
+};
+/** State attributes this selector pins that the platform cannot report. */
+function unsupportedStateAttrs(sel, platform) {
+    const blind = UNREPORTED[platform];
+    if (blind.length === 0)
+        return [];
+    return selector_1.STATE_ATTRS.filter((attr) => sel[attr] !== undefined && blind.includes(attr));
+}
+/** Throw unless every state modifier on `sel` means something on `platform`. */
+function assertStateSupported(sel, platform) {
+    const bad = unsupportedStateAttrs(sel, platform);
+    if (bad.length === 0)
+        return;
+    // Name both polarities: --not-selected is refused for the same reason as --selected,
+    // and echoing only the attribute reads as though the wrong flag was typed.
+    const named = bad.map((a) => `--${a}/--not-${a}`).join(' and ');
+    throw new errors_1.CliError(`${named} cannot be used on ${platform}: its accessibility backend does not report ` +
+        `${bad.join(' or ')}, so the selector could only ever match nothing. ` +
+        `Match on ${platform === 'ios' ? '@id, text or --enabled/--checked' : 'another attribute'} instead.`, 3);
+}

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.15.0';
+exports.VERSION = '0.17.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",