verikun 0.10.0 → 0.11.0

package/README.md

@@ -233,6 +233,14 @@ like permission dialogs) and **bounded loops** (`repeat … until`, e.g. scroll
 row appears) — control flow a flat [`batch`](#batch) script can't express. Loops carry
 a hard iteration cap and stop early if the screen stops changing.
 
+An `if-present` guard **waits for its selector to settle** before deciding the optional UI
+isn't there, so a dialog that animates in a beat after the transition is still caught. The
+window guarantees at least two looks at the screen (wall clock alone isn't a usable unit —
+a UI dump ranges from ~200ms on a fast phone to ~2.5s on an emulator), so an absent guard
+costs about one extra dump. `VERIKUN_GUARD_SETTLE_MS` tunes it; `0` restores the old
+single-shot probe. A loop's own exit check never pays this window — it's absent on every
+iteration by construction, which is what makes it a loop.
+
 - **Progress streams to stderr** (so a CI job never goes silent); **stdout is the
   report path** (or a JSON summary with `--json`). The compiled plan is logged to the
   run before it executes, for troubleshooting.
@@ -367,7 +375,11 @@ 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.
+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").
 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.

package/dist/agent/claude.js

@@ -35,6 +35,12 @@ class ClaudeProvider {
                 JSON.stringify(input.seed, null, 2));
         }
         parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        if (input.retryFeedback) {
+            // Last, so it is the freshest thing in context: a previous compile of this same
+            // test lost something the prose stated. Naming it beats hoping the retry differs.
+            parts.push('YOUR PREVIOUS ATTEMPT AT THIS TEST WAS REJECTED. Fix this and emit the whole plan again:\n' +
+                input.retryFeedback);
+        }
         const { json, usage } = await this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA, 8192);
         return { plan: (0, ir_1.parsePlan)(json), usage };
     }

package/dist/agent/cli-provider.js

@@ -156,6 +156,12 @@ class CliProvider {
                 JSON.stringify(input.seed, null, 2));
         }
         parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        if (input.retryFeedback) {
+            // Last, so it is the freshest thing in context: a previous compile of this same
+            // test lost something the prose stated. Naming it beats hoping the retry differs.
+            parts.push('YOUR PREVIOUS ATTEMPT AT THIS TEST WAS REJECTED. Fix this and emit the whole plan again:\n' +
+                input.retryFeedback);
+        }
         const json = this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA);
         // usage:{} — a CLI is billed to the user's subscription, not per token, so cost is $0
         // (documented no-op for --max-cost-usd). The run is still bounded by maxRepairs + --timeout.

package/dist/agent/engine.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RUN_TIMEOUT_MS = void 0;
+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 errors_1 = require("../errors");
 const ir_1 = require("./ir");
@@ -13,23 +14,120 @@ const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map
  *  fails (a device hiccup on screencap) must never turn a green run red — see
  *  the guard in execLeaf. */
 const isScreenshotLeaf = (leaf) => leaf.command === 'screenshot' || leaf.command === 'shot';
-/** A structural fingerprint of the screen: sorted id+text+type set. Used for the
- *  loop no-progress check — deliberately NOT the raw hierarchy (its node ordering
- *  is nondeterministic between identical states, which would false-trip). */
+/** A structural fingerprint of the screen: a sorted id+text+desc+type set. Used for the
+ *  loop no-progress check — deliberately NOT the raw hierarchy (its node ordering is
+ *  nondeterministic between identical states, which would false-trip).
+ *
+ *  BOTH content fields are sampled, and that is load-bearing rather than belt-and-braces.
+ *  Sampling `text` alone made this blind on Flutter apps, which map `Semantics(label:)` to
+ *  Android's `contentDescription` — i.e. to `desc`, never to `text`. Measured on a live
+ *  Flutter screen: 14 elements, **0** carrying `text`, 8 carrying `desc`. The fingerprint
+ *  degenerated to `id||type` for the entire screen, so two completely different questions
+ *  hashed byte-identically and a loop answering them correctly was declared stalled.
+ *
+ *  Uses the full `id`, not `idShort` (the suffix after the last '/'), so elements from
+ *  different packages/namespaces cannot collide in what is meant to be a fingerprint.
+ *
+ *  When in doubt, sample MORE: an over-sensitive hash only costs a loop running to its cap;
+ *  an under-sensitive one fails a passing test, since a stalled loop is now fatal. */
 function structuralHash(els) {
     return els
-        .map((e) => `${e.idShort}|${e.text}|${e.type}`)
+        .map((e) => `${e.id}|${e.text}|${e.desc}|${e.type}`)
         .sort()
         .join('\n');
 }
+/** An unresolvable {{...}} placeholder. Terminal and never healed: the model cannot
+ *  repair a missing value, and substituting one would be inventing test data. */
+class CtxError extends Error {
+}
 function isHealable(outcome) {
     return (!!outcome.error &&
         (outcome.error instanceof errors_1.SelectorNotFoundError || outcome.error instanceof errors_1.AmbiguousSelectorError));
 }
 /** Default wall-clock ceiling for a whole `vk ai` run (overridable via --timeout). */
 exports.DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** How long a CONDITIONAL guard (`if-present`) waits for its selector to show up
+ *  before concluding "absent". Interstitials animate in: a permission dialog or promo
+ *  panel typically lands a few hundred ms after the transition that triggers it. Every
+ *  selector-resolving leaf command already auto-waits ~5s (cli.ts resolveOneWaiting),
+ *  so before this window existed a guard was strictly LESS patient than a bare `tap` —
+ *  and an optional dialog could be missed by the very construct meant to catch it.
+ *  Kept far below the leaf 5s because an ABSENT guard pays this window, every time, and
+ *  skipping fast is the common case.
+ *
+ *  NOTE the floor in present(): any non-zero window buys at least TWO looks at the screen.
+ *  Wall clock alone is not a usable unit here — a uiautomator dump measured ~2.4s on
+ *  emulator-5554 and can be ~10x faster on a physical device, so a pure time box gives a
+ *  fast phone a dozen looks and a slow emulator none. Set 0 to restore the old
+ *  single-shot probe. Override per run with VERIKUN_GUARD_SETTLE_MS (see cli.ts). */
+exports.DEFAULT_GUARD_SETTLE_MS = 1500;
+/** Re-dump cadence inside a guard's settle window. */
+const GUARD_POLL_MS = 150;
+/** Consecutive identical screen snapshots before a loop is believed to be stuck.
+ *
+ *  This check is a TIME SAVER and nothing more. A loop already fails when its exit
+ *  selector never appears, so stopping early buys no safety — it only decides how long we
+ *  wait before reaching the same verdict. That asymmetry is the whole design: a false
+ *  positive fails a passing test, while a false negative costs `cap` iterations of runtime.
+ *
+ *  Tuned from a measured false positive, twice over. At 2 strikes the same plan answered
+ *  17 questions on one run and bailed after 4 on the next — the loop bodies drive screen
+ *  transitions, and a single dump lands mid-transition often enough to produce a
+ *  coincidental pair of matching hashes.
+ *
+ *  4 discriminates well because the two cases differ in character, not just degree: a loop
+ *  genuinely at rest (a scrolled-to-the-bottom list — the case this exists for) yields
+ *  identical hashes indefinitely, whereas an animating screen rarely yields four in a row. */
+const NO_PROGRESS_STRIKES = 4;
 async function runPlan(plan, deps) {
     const maxRepairs = deps.maxRepairs ?? 3;
+    const guardSettleMs = deps.guardSettleMs ?? exports.DEFAULT_GUARD_SETTLE_MS;
+    // The run's mutable state, scoped to THIS runPlan call — never module-level. `vk suite`
+    // runs every test in one process, so a shared store would hand two sign-up tests the
+    // same {{uuid}} and recreate the collision it exists to prevent. Per-leaf generation
+    // would be equally wrong: a sign-up needs the same address in the email field, the
+    // confirm field, and a later assert.
+    const ctx = new Map(Object.entries(deps.initialCtx ?? {}));
+    const generated = new Map();
+    const runId = deps.runId ?? 'run';
+    /** Resolve {{...}} placeholders. A closed set on purpose — this is a template
+     *  substitution, not an expression language, so there is nothing to sandbox.
+     *  Unknown placeholders are left verbatim rather than blanked: a silent empty string
+     *  is how a typo becomes a false green. */
+    function interpolate(s) {
+        if (!s.includes('{{'))
+            return s;
+        return s.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g, (whole, name) => {
+            if (name.startsWith('ctx.')) {
+                const key = name.slice(4);
+                const v = ctx.get(key);
+                if (v === undefined)
+                    throw new CtxError(`{{${name}}} is not set — no earlier step stored it`);
+                return v;
+            }
+            if (name.startsWith('env.')) {
+                const key = name.slice(4);
+                const v = process.env[key];
+                // Loud, not empty: a missing CI secret must fail the step, not type "" into a field.
+                if (v === undefined || v === '')
+                    throw new CtxError(`{{${name}}} is not set in the environment`);
+                return v;
+            }
+            if (name === 'run_id')
+                return runId;
+            // uuid/timestamp are generated ONCE per run and memoized by placeholder name.
+            if (name === 'uuid' || name === 'timestamp') {
+                const existing = generated.get(name);
+                if (existing !== undefined)
+                    return existing;
+                const v = name === 'uuid' ? (0, node_crypto_1.randomUUID)() : String(Date.now());
+                generated.set(name, v);
+                return v;
+            }
+            return whole;
+        });
+    }
     const overDeadline = () => deps.deadline !== undefined && Date.now() >= deps.deadline;
     const improvements = [];
     let modelRepairs = 0;
@@ -44,24 +142,22 @@ async function runPlan(plan, deps) {
             return [];
         }
     };
-    const present = async (selector) => {
-        // Re-fetch on a dump FAILURE (uiautomator can throw transiently) so a flaky dump at
-        // a guard check doesn't silently read as "absent" and skip a body that should run.
-        // Once a dump SUCCEEDS (even if empty) we trust it — no slow re-poll, so a genuinely
-        // absent guard still skips fast (the common if-present case).
-        let els;
-        for (let i = 0; i < 2 && els === undefined; i++) {
-            try {
-                els = await deps.getElements();
-            }
-            catch {
-                /* transient dump failure — retry once before concluding "absent" */
-            }
-        }
-        if (els === undefined)
-            return false;
+    /** Is `selector` on screen? `settleMs` is how long to keep re-dumping while it is
+     *  absent before answering "no" — see DEFAULT_GUARD_SETTLE_MS.
+     *
+     *  Two retry behaviours here are deliberately ORTHOGONAL, and conflating them is the
+     *  bug this signature exists to prevent:
+     *    - a dump that THROWS is always retried once, even at settleMs=0, so a flaky
+     *      uiautomator call never silently reads as "absent" and skips a body that
+     *      should run;
+     *    - a dump that SUCCEEDS but does not match is re-polled only while settleMs
+     *      remains. At settleMs=0 that means exactly one pass — the fast, single-shot
+     *      probe a loop-exit check needs.
+     *  So one dump attempt always happens regardless of the window. */
+    const present = async (selector, settleMs) => {
+        let sel;
         try {
-            return (0, selector_1.matchElements)(els, (0, selector_1.parseSelector)(selector)).matches.length > 0;
+            sel = (0, selector_1.parseSelector)(selector);
         }
         catch (e) {
             // A guard selector that won't parse is a compiler/plan bug — surface it (then treat
@@ -69,14 +165,68 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] guard selector '${selector}' did not parse (${e.message}) — treating as not present`);
             return false;
         }
+        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
+        // a 1.5s window — so a purely time-boxed loop returns after a single dump and the
+        // window is a silent no-op on exactly the slow devices that need it most. Dump cost
+        // swings ~10x across devices, so "how long to wait" cannot be expressed in wall clock
+        // alone without making the guard's patience device-dependent.
+        let looks = 0;
+        const minLooks = settleMs > 0 ? 2 : 1;
+        for (;;) {
+            let els;
+            for (let i = 0; i < 2; i++) {
+                try {
+                    els = await deps.getElements();
+                }
+                catch {
+                    els = undefined; // transient dump failure — retry once before concluding "absent"
+                }
+                // An EMPTY tree is not a screen, it is a bad read: a live app always has nodes, and
+                // this device routinely returns a partial/blank dump mid-transition (measured: `ui`
+                // reported zero elements while `tap`'s auto-wait found its target 3.1s later).
+                // Trusting it means "absent" — which silently skips a guard, or sends a loop round
+                // again to tap something that already went away. Retry once even at settleMs=0,
+                // which is what the loop-exit check runs at.
+                if (els !== undefined && els.length > 0)
+                    break;
+            }
+            looks++;
+            if (els !== undefined && (0, selector_1.matchElements)(els, sel).matches.length > 0)
+                return true;
+            const remaining = deadline - Date.now();
+            if (looks >= minLooks && remaining <= 0)
+                return false;
+            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+        }
+    };
+    const runLeaf = (leaf) => {
+        const flags = (0, ir_1.leafToFlags)(leaf);
+        for (const k of Object.keys(flags))
+            flags[k] = interpolate(flags[k]);
+        return deps.exec(leaf.command, leaf.positionals.map(interpolate), flags);
     };
-    const runLeaf = (leaf) => deps.exec(leaf.command, leaf.positionals, (0, ir_1.leafToFlags)(leaf));
     /** Execute one leaf, healing a selector miss/ambiguity via the model up to the cap.
      *  `replace` writes a repaired leaf back into the plan so it persists on green. */
-    async function execLeaf(leaf, where, replace) {
+    async function execLeaf(leaf, where, replace, guard) {
         deps.log(`[ai] ${where}: ${describe(leaf)}`);
         let current = leaf;
         let outcome = await runLeaf(current);
+        // Guard raced the body: `if-present X { … tap X … }` checked X, X was there, and by
+        // the time the tap ran it had gone. That is not drift and there is nothing to repair —
+        // it is exactly the transient the guard exists to tolerate, and on a fast-transitioning
+        // app it happens routinely. Checked BEFORE the heal loop, because otherwise it costs
+        // three model calls to conclude that a thing which was optional is absent.
+        // Deliberately narrow: only the leaf that targets the guard's own selector, and only
+        // once the guard is confirmed false again.
+        if (guard !== undefined &&
+            outcome.error instanceof errors_1.SelectorNotFoundError &&
+            current.positionals.some((p) => interpolate(p) === interpolate(guard)) &&
+            !(await present(interpolate(guard), 0))) {
+            deps.log(`[ai] ${where}: '${interpolate(guard)}' disappeared after the guard matched — ending the guarded body`);
+            return { status: 'guard-gone' };
+        }
         let attempts = 0;
         while (isHealable(outcome) && attempts < maxRepairs) {
             if (deps.cost.exceeded()) {
@@ -154,49 +304,189 @@ async function runPlan(plan, deps) {
         const reason = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
         return { status: 'fail', where, reason };
     }
-    async function walkBody(body, parentWhere) {
+    async function walkBody(body, parentWhere, guard) {
         for (let j = 0; j < body.length; j++) {
-            const res = await execLeaf(body[j], `${parentWhere}.body[${j}]`, (l) => (body[j] = l));
+            const res = await walkNode(body[j], `${parentWhere}[${j}]`, (l) => (body[j] = l), guard);
+            // 'guard-gone' ends this body, not the run: the thing the guard matched went away
+            // mid-body, which is precisely the situation the guard exists to tolerate.
+            if (res.status === 'guard-gone')
+                return { status: 'ok' };
             if (res.status !== 'ok')
                 return res;
         }
         return { status: 'ok' };
     }
-    async function walkNode(node, where, replace) {
+    /** Capture a value from the live tree into ctx. Not routed through `exec`: the
+     *  ExecFn contract returns only {code,error}, so a leaf could never hand a value back. */
+    async function execRead(node, where) {
+        const selector = interpolate(node.selector);
+        let sel;
+        try {
+            sel = (0, selector_1.parseSelector)(selector);
+        }
+        catch (e) {
+            return { status: 'fail', where, reason: `read selector '${selector}' did not parse: ${e.message}` };
+        }
+        // Same patience as a conditional guard: the value may not have rendered yet.
+        const deadline = Date.now() + Math.max(0, guardSettleMs);
+        let looks = 0;
+        const minLooks = guardSettleMs > 0 ? 2 : 1;
+        for (;;) {
+            const els = await safeElements();
+            const { matches } = (0, selector_1.matchElements)(els, sel);
+            looks++;
+            if (matches.length > 0) {
+                const value = String(matches[0][node.field] ?? '');
+                ctx.set(node.into, value);
+                deps.log(`[ai] ${where}: read ${node.field} of '${selector}' → ctx.${node.into} = ${JSON.stringify(value)}`);
+                return { status: 'ok' };
+            }
+            const remaining = deadline - Date.now();
+            if (looks >= minLooks && remaining <= 0) {
+                // Terminal, not healable: a missing source value would silently propagate an
+                // empty string into every later {{ctx.*}} use, which is a false green waiting
+                // to happen. Fail where the information is.
+                return { status: 'fail', where, reason: `read found no element matching '${selector}' (nothing to store in ctx.${node.into})` };
+            }
+            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+        }
+    }
+    async function walkNode(node, where, replace, guard) {
+        try {
+            return await walkNodeInner(node, where, replace, guard);
+        }
+        catch (e) {
+            // An unresolvable placeholder is a plan defect, not a device failure: report it
+            // as this step's terminal failure rather than letting it abort the whole run as
+            // an "unexpected error" (exit 3).
+            if (e instanceof CtxError)
+                return { status: 'fail', where, reason: e.message };
+            throw e;
+        }
+    }
+    async function walkNodeInner(node, where, replace, guard) {
         switch (node.type) {
             case 'command':
-                return execLeaf(node, where, replace);
+                return execLeaf(node, where, replace, guard);
+            case 'read':
+                return execRead(node, where);
             case 'if-present': {
-                if (await present(node.selector)) {
-                    deps.log(`[ai] ${where}: if-present '${node.selector}' → present, running ${node.body.length} step(s)`);
-                    return walkBody(node.body, where);
+                const selector = interpolate(node.selector);
+                if (await present(selector, guardSettleMs)) {
+                    deps.log(`[ai] ${where}: if-present '${selector}' → present, running ${node.body.length} step(s)`);
+                    return walkBody(node.body, `${where}.body`, selector);
                 }
-                deps.log(`[ai] ${where}: if-present '${node.selector}' → absent, skipping`);
+                deps.log(`[ai] ${where}: if-present '${selector}' → absent, skipping`);
                 return { status: 'ok' };
             }
+            case 'when': {
+                for (let b = 0; b < node.branches.length; b++) {
+                    const selector = interpolate(node.branches[b].selector);
+                    // Ordered: first present branch wins, and only it runs. The settle window is
+                    // per NODE, spent on the first branch checked — re-polling every branch would
+                    // cost cap x branches x window inside a loop, and would let a slower-appearing
+                    // earlier branch beat an already-present later one (making dispatch depend on
+                    // timing rather than on order).
+                    if (await present(selector, b === 0 ? guardSettleMs : 0)) {
+                        deps.log(`[ai] ${where}: when → branch ${b} '${selector}' matched`);
+                        return walkBody(node.branches[b].body, `${where}.branches[${b}].body`);
+                    }
+                }
+                if (node.else) {
+                    deps.log(`[ai] ${where}: when → no branch matched, running else (${node.else.length} step(s))`);
+                    return walkBody(node.else, `${where}.else`);
+                }
+                // No branch, no else => FAIL. Skipping here is the false-green this node exists
+                // to prevent: inside a loop it would spin to the cap doing nothing and pass.
+                const tried = node.branches.map((b) => `'${interpolate(b.selector)}'`).join(', ');
+                return {
+                    status: 'fail',
+                    where,
+                    reason: `when: no branch matched (tried ${tried}) and no else was given — the screen is one this test does not handle`,
+                };
+            }
             case 'repeat': {
                 let prevHash = '';
-                for (let i = 0; i < node.cap; i++) {
+                let stalled = 0;
+                let satisfied = false;
+                let i = 0;
+                for (; i < node.cap; i++) {
                     if (overDeadline()) {
                         deps.log(`[ai] ${where}: run timeout reached — stopping repeat after ${i} iteration(s)`);
                         return { status: 'timeout' };
                     }
-                    if (await present(node.selector)) {
+                    // settleMs=0 on purpose: this guard is absent on EVERY iteration by construction
+                    // (that is what makes it a loop), so a settle window here would be paid `cap`
+                    // times — 25 × 1.5s ≈ 37s of dead wall-clock per loop — to discover something
+                    // we already expect. The interstitial case that needs patience is `if-present`.
+                    if (await present(interpolate(node.selector), 0)) {
+                        satisfied = true;
                         deps.log(`[ai] ${where}: repeat reached '${node.selector}' after ${i} iteration(s)`);
-                        return { status: 'ok' };
+                        break;
                     }
-                    const hash = structuralHash(await safeElements());
-                    if (i > 0 && hash === prevHash) {
-                        deps.log(`[ai] ${where}: repeat made no progress (screen unchanged) — stopping after ${i} iteration(s)`);
-                        return { status: 'ok' };
+                    // No-progress detection over a SINGLE un-settled dump is unreliable on a real
+                    // app: mid-transition frames read as empty (measured — `vk ui` reported zero
+                    // elements on a screen where `tap`'s auto-wait found its target 3.1s later).
+                    // Two such frames hash identically and look exactly like a stuck loop. Since a
+                    // stalled loop is now a FAILURE, a false positive here fails a passing test, so
+                    // this needs two independent guards:
+                    //   1. an empty dump is UNKNOWN, not "unchanged" — never a progress sample;
+                    //   2. require consecutive identical NON-EMPTY snapshots before believing it.
+                    const els = await safeElements();
+                    if (els.length === 0) {
+                        deps.log(`[ai] ${where}: screen read as empty (mid-transition?) — not counting it as progress either way`);
+                    }
+                    else {
+                        const hash = structuralHash(els);
+                        stalled = i > 0 && hash === prevHash ? stalled + 1 : 0;
+                        prevHash = hash;
+                        if (stalled >= NO_PROGRESS_STRIKES) {
+                            deps.log(`[ai] ${where}: repeat made no progress across ${stalled + 1} checks — stopping after ${i} iteration(s)`);
+                            break;
+                        }
                     }
-                    prevHash = hash;
                     deps.log(`[ai] ${where}: repeat iteration ${i + 1}/${node.cap}`);
-                    const res = await walkBody(node.body, `${where}#${i + 1}`);
+                    const res = await walkBody(node.body, `${where}#${i + 1}.body`);
+                    if (res.status !== 'ok')
+                        return res;
+                }
+                // A loop that stopped without ever seeing its target did NOT do its job. Both
+                // exits (cap exhausted, and the no-progress bail) used to return ok, which let a
+                // loop whose body did nothing report green — the reachable false green.
+                if (!satisfied && !(await present(interpolate(node.selector), guardSettleMs))) {
+                    return {
+                        status: 'fail',
+                        where,
+                        reason: `repeat stopped after ${i} iteration(s) without '${interpolate(node.selector)}' ever appearing`,
+                    };
+                }
+                return { status: 'ok' };
+            }
+            case 'while-present': {
+                if (node.bind)
+                    ctx.set(node.bind, '0');
+                let ran = 0;
+                for (let i = 0; i < node.cap; i++) {
+                    if (overDeadline()) {
+                        deps.log(`[ai] ${where}: run timeout reached — stopping while-present after ${i} iteration(s)`);
+                        return { status: 'timeout' };
+                    }
+                    const selector = interpolate(node.selector);
+                    // First check gets the settle window (the list may still be rendering); later
+                    // checks are single-shot, since by then the list is up and we are just walking it.
+                    if (!(await present(selector, i === 0 ? guardSettleMs : 0))) {
+                        deps.log(`[ai] ${where}: while-present '${selector}' → absent, loop done after ${ran} iteration(s)`);
+                        return { status: 'ok' };
+                    }
+                    deps.log(`[ai] ${where}: while-present iteration ${i + 1}/${node.cap} ('${selector}')`);
+                    const res = await walkBody(node.body, `${where}#${i + 1}.body`, selector);
                     if (res.status !== 'ok')
                         return res;
+                    ran++;
+                    if (node.bind)
+                        ctx.set(node.bind, String(Number(ctx.get(node.bind) ?? '0') + 1));
                 }
-                deps.log(`[ai] ${where}: repeat hit cap ${node.cap} without '${node.selector}' (continuing)`);
+                deps.log(`[ai] ${where}: while-present hit cap ${node.cap}`);
                 return { status: 'ok' };
             }
         }

package/dist/agent/grammar.js

@@ -34,13 +34,75 @@ Each step is one of three node types:
    permission dialogs, "rate us" popups, cookie banners, A/B variants. This is how you
    keep a flow from breaking when an extra screen sometimes appears.
 
-3. REPEAT — { "type":"repeat", "selector":<sel>, "cap":<n>, "body":[<command leaves>] }
-   Repeat body until the selector appears, up to cap iterations. Use for "scroll until X
-   is visible". Always set a sane cap (e.g. 10). The engine also stops early if the screen
-   stops changing.
+3. REPEAT — { "type":"repeat", "selector":<sel>, "cap":<n>, "body":[<nodes>] }
+   Repeat body UNTIL the selector appears, up to cap iterations. Use for "scroll until X
+   is visible", or "keep answering until the results screen". Always set a sane cap (e.g.
+   10). The engine also stops early if the screen stops changing. A repeat that finishes
+   without its selector ever appearing FAILS the test — it did not do its job.
 
-NESTING: control-node bodies hold COMMAND leaves only — do NOT nest if-present/repeat
-inside another control node.
+4. WHEN — { "type":"when", "branches":[{ "selector":<sel>, "body":[<nodes>] }, ...],
+            "else":[<nodes>]  (optional) }
+   Ordered n-way dispatch: the FIRST branch whose selector is on screen runs, and only it.
+   Use when a screen is one of several KINDS that each need different handling —
+   "the question is multiple-choice, or match-the-pairs, or arrange-the-words".
+   If no branch matches and there is no "else", the test FAILS (the app showed something
+   this test does not handle — that is a real result, not something to skip past).
+   Use "else": [] to say explicitly "if none match, do nothing".
+   WHEN vs IF-PRESENT: if-present = "this may or may not be there, carry on either way".
+   when = "it is one of these; if it is none of them, that is a failure".
+
+5. WHILE-PRESENT — { "type":"while-present", "selector":<sel>, "bind":<name>,
+                     "cap":<n>, "body":[<nodes>] }
+   Repeat body WHILE the selector is present. With "bind", the named counter starts at 0
+   and increments after each iteration, and you reference it as {{ctx.<name>}} inside the
+   selector and the body. This is how you walk an index-addressed list whose LENGTH you
+   cannot know when compiling:
+     { "type":"while-present", "selector":"id:word_bubble_container_id_{{ctx.i}}",
+       "bind":"i", "cap":20,
+       "body":[ { "type":"command","command":"tap",
+                  "positionals":["id:word_bubble_container_id_{{ctx.i}}"],"flags":[] } ] }
+
+6. READ — { "type":"read", "selector":<sel>, "field":"text"|"desc"|"id"|"idShort",
+            "into":<name> }
+   Capture a value off the live screen into {{ctx.<name>}} for a later step to use. Use it
+   when the test must ACT ON a value it cannot know in advance — e.g. read the correct
+   answer's text, then type that text into a field.
+
+PLACEHOLDERS — any positional or flag value, and any control-node selector, may contain:
+  {{ctx.NAME}}   a value stored by read, or a while-present counter
+  {{env.NAME}}   an environment variable (use for credentials; never inline a secret)
+  {{uuid}}       a fresh id, generated once per run (same value everywhere in the run)
+  {{timestamp}}  epoch ms, once per run       {{run_id}}  this run's id
+Use {{uuid}} when the test needs data that must be unique per run, e.g. a signup email
+like "user-{{uuid}}@example.com" — never a hard-coded literal, which collides on rerun.
+
+NESTING: control nodes may nest ONE level — a control node inside a control node, whose
+body is command leaves. A repeat containing a when is the shape for "until the flow ends,
+handle whichever screen is showing", and it is legal. Three levels is not.
+EXCEPT: if-present and while-present may go one level deeper (their bodies are leaves), so
+  repeat { when { while-present { tap ... } } }     — walk an index-addressed list
+  repeat { when { if-present { tap ... } } }        — an optional step inside a branch
+are both legal. Use them rather than approximating.
+In particular: "if X appears, tap it" inside a branch is an if-present. Do NOT turn it
+into a bare wait + tap — wait FAILS the test when X never appears, and "if" means it
+might not. That mistake reads as a passing plan and fails on the first run where the app
+skips that step.
+
+Inside a "repeat until X" loop, GUARD a tap whose target is the thing that brings X about:
+  repeat until <form> { if-present <button> { tap <button> } ; screenshot }
+Once the transition starts, <button> is gone — so on the final iteration an unguarded tap
+misses and fails the whole run, even though the loop did its job. The guard makes that
+last lap a no-op instead of an error. Apply this whenever the prose says "tap ... until"
+or "repeatedly until".
+
+Do NOT flatten a branch into an unconditional sequence: emitting the taps for ALL the
+kinds of screen one after another is wrong — on any given iteration most of them are not
+there, and the test will fail on the first one that is missing. Use when.
+
+Do NOT hard-code a run of indices you were not told the length of. If the prose says
+"tap each pair", "until every pair is matched", or "tap the bubbles in order", the COUNT
+varies per run — emit a while-present over {{ctx.i}} rather than tap _0, _1, _2, _3.
+A hard-coded list is right only when the prose states the exact count.
 
 SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable identifiers):
   @login            resource-id 'login' (shorthand for id:login)
@@ -51,6 +113,11 @@ SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable ident
   "Sign in"         bare string == text:Sign in
 
 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.
 - 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.
 - Prefer resource-id / accessibility selectors over visible text where possible.

package/dist/agent/ir.js

@@ -18,10 +18,25 @@
 //    structured-output schemas can't express an arbitrary-key object. A pure boolean
 //    flag is value:"true" (flagBool reads 'true' as true; flagStr reads the string).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidPlanError = exports.REPAIR_DECISION_JSON_SCHEMA = exports.PLAN_JSON_SCHEMA = exports.DEFAULT_LOOP_CAP = exports.KNOWN_COMMANDS = void 0;
+exports.InvalidPlanError = exports.REPAIR_DECISION_JSON_SCHEMA = exports.PLAN_JSON_SCHEMA = exports.DEFAULT_LOOP_CAP = exports.KNOWN_COMMANDS = exports.isControlNode = exports.MAX_CONTROL_DEPTH = void 0;
+exports.bodiesOf = bodiesOf;
 exports.validateNode = validateNode;
 exports.parsePlan = parsePlan;
 exports.leafToFlags = leafToFlags;
+/** Max control-node nesting. 1 = a control node at top level whose body is leaves
+ *  (the v1 rule). 2 = a control node inside that body, whose own body is leaves —
+ *  i.e. `repeat { when { … } }`, the loop-that-branches shape a real dynamic flow
+ *  needs. The schema is hand-unrolled to exactly this depth, so raising it means
+ *  editing controlSchema()'s nesting as well as this constant. */
+exports.MAX_CONTROL_DEPTH = 2;
+const isControlNode = (n) => n.type === 'if-present' || n.type === 'when' || n.type === 'repeat' || n.type === 'while-present';
+exports.isControlNode = isControlNode;
+/** Every body a control node owns (a `when` owns one per branch, plus `else`). */
+function bodiesOf(n) {
+    if (n.type === 'when')
+        return [...n.branches.map((b) => b.body), ...(n.else ? [n.else] : [])];
+    return [n.body];
+}
 /** Commands a leaf step is allowed to carry — the agent-emittable ACTION/assertion verbs
  *  the grammar offers, a SUBSET of cli.ts's dispatch (inspection/diagnostic commands are
  *  excluded; see the note in the set). The engine validates every step — including a
@@ -47,10 +62,115 @@ exports.KNOWN_COMMANDS = new Set([
 exports.DEFAULT_LOOP_CAP = 25;
 /**
  * JSON Schema for `output_config.format` so the model returns a guaranteed-valid
- * Plan. Deliberately NON-RECURSIVE: control-node `body` arrays reference only the
- * leaf schema, so there is no `Plan -> node -> Plan` cycle (structured output
- * rejects recursive schemas). One nesting level, by design.
+ * Plan. Deliberately NON-RECURSIVE: instead of a `Plan -> node -> Plan` cycle
+ * (structured output rejects recursive schemas) the control levels are HAND-UNROLLED
+ * to MAX_CONTROL_DEPTH. Raising the depth means adding another unrolled level here.
  */
+const stepItems = (bodyItems) => ({
+    anyOf: [
+        leafSchema(),
+        readSchema(),
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'selector', 'body'],
+            properties: {
+                type: { type: 'string', enum: ['if-present'] },
+                selector: { type: 'string' },
+                body: { type: 'array', items: bodyItems },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'branches'],
+            properties: {
+                type: { type: 'string', enum: ['when'] },
+                branches: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['selector', 'body'],
+                        properties: { selector: { type: 'string' }, body: { type: 'array', items: bodyItems } },
+                    },
+                },
+                else: { type: 'array', items: bodyItems },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'selector', 'cap', 'body'],
+            properties: {
+                type: { type: 'string', enum: ['repeat'] },
+                selector: { type: 'string' },
+                cap: { type: 'integer' },
+                body: { type: 'array', items: bodyItems },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'selector', 'cap', 'body'],
+            properties: {
+                type: { type: 'string', enum: ['while-present'] },
+                selector: { type: 'string' },
+                bind: { type: 'string' },
+                cap: { type: 'integer' },
+                body: { type: 'array', items: bodyItems },
+            },
+        },
+    ],
+});
+/** The innermost level: leaves, reads, and the two SIMPLE control nodes — `if-present`
+ *  and `while-present` — restricted to leaf-only bodies so they cannot open a further
+ *  level.
+ *
+ *  Both were added from measured failures, and both are the same failure: when the model
+ *  needs a construct one level deeper than the grammar allows, it does not give up — it
+ *  DEGRADES to an unconditional approximation, which is exactly the bug #33 is about.
+ *    - Without `while-present` here, a compile of the dynamic-lesson repro produced
+ *      `repeat { when { … } }` correctly but HARD-CODED the index lists inside each branch
+ *      (pairs 0..3, bubbles 0..5) — broken the moment a question has a different count.
+ *    - Without `if-present` here, the same compile turned the prose "IF a Continue button
+ *      appears, tap it" into an unconditional `wait id:continue_button_id` inside every
+ *      branch. The app auto-advances and shows no Continue, so all three runs failed on
+ *      that wait — a conditional flattened into an assertion, one level down.
+ *
+ *  A full third level for every node would ~3x a 28KB schema (bad for OpenAI strict
+ *  limits, worse for cursor, which injects the schema as prompt text). Granting it to the
+ *  two leaf-bodied nodes is the cheap, bounded version. `when` and `repeat` stay at
+ *  MAX_CONTROL_DEPTH: they are the nodes whose bodies want to be deep, and allowing them
+ *  here is what would actually cost the schema. */
+const innerControls = () => {
+    const leafBody = { type: 'array', items: { anyOf: [leafSchema(), readSchema()] } };
+    return [
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'selector', 'body'],
+            properties: {
+                type: { type: 'string', enum: ['if-present'] },
+                selector: { type: 'string' },
+                body: leafBody,
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['type', 'selector', 'cap', 'body'],
+            properties: {
+                type: { type: 'string', enum: ['while-present'] },
+                selector: { type: 'string' },
+                bind: { type: 'string' },
+                cap: { type: 'integer' },
+                body: leafBody,
+            },
+        },
+    ];
+};
+const LEAF_ONLY_ITEMS = { anyOf: [leafSchema(), readSchema(), ...innerControls()] };
 exports.PLAN_JSON_SCHEMA = {
     type: 'object',
     additionalProperties: false,
@@ -61,32 +181,7 @@ exports.PLAN_JSON_SCHEMA = {
         platform: { type: 'string', enum: ['android', 'ios'] },
         steps: {
             type: 'array',
-            items: {
-                anyOf: [
-                    leafSchema(),
-                    {
-                        type: 'object',
-                        additionalProperties: false,
-                        required: ['type', 'selector', 'body'],
-                        properties: {
-                            type: { type: 'string', enum: ['if-present'] },
-                            selector: { type: 'string' },
-                            body: { type: 'array', items: leafSchema() },
-                        },
-                    },
-                    {
-                        type: 'object',
-                        additionalProperties: false,
-                        required: ['type', 'selector', 'cap', 'body'],
-                        properties: {
-                            type: { type: 'string', enum: ['repeat'] },
-                            selector: { type: 'string' },
-                            cap: { type: 'integer' },
-                            body: { type: 'array', items: leafSchema() },
-                        },
-                    },
-                ],
-            },
+            items: stepItems(stepItems(LEAF_ONLY_ITEMS)),
         },
     },
 };
@@ -107,6 +202,19 @@ exports.REPAIR_DECISION_JSON_SCHEMA = {
         reason: { type: 'string' },
     },
 };
+function readSchema() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['type', 'selector', 'field', 'into'],
+        properties: {
+            type: { type: 'string', enum: ['read'] },
+            selector: { type: 'string' },
+            field: { type: 'string', enum: ['text', 'desc', 'id', 'idShort'] },
+            into: { type: 'string' },
+        },
+    };
+}
 function leafSchema() {
     return {
         type: 'object',
@@ -141,11 +249,49 @@ function isFlagSpecArray(v) {
     return (Array.isArray(v) &&
         v.every((f) => f && typeof f === 'object' && typeof f.name === 'string' && typeof f.value === 'string'));
 }
-/** Validate a single node (used for both compile output and a spliced repair). */
-function validateNode(node, where) {
+const READ_FIELDS = new Set(['text', 'desc', 'id', 'idShort']);
+/** ctx keys are interpolated into selectors as {{ctx.NAME}}; keep them boring so a
+ *  name can never smuggle regex/template metacharacters into a selector. */
+const CTX_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Validate a single node (used for both compile output and a spliced repair).
+ *
+ *  `depth` is how many control nodes enclose this one. It is the ONLY thing bounding
+ *  nesting at runtime, and it must agree with PLAN_JSON_SCHEMA's hand-unrolled levels
+ *  — the schema stops a compliant model, this stops everything else (a repair, a
+ *  hand-edited plan, a poisoned cache entry). */
+function validateNode(node, where, depth = 0) {
     if (!node || typeof node !== 'object')
         throw new InvalidPlanError(`${where}: not an object`);
     const n = node;
+    /** Validate one control body. `allowEmpty` is true only for `when`'s `else`. */
+    const validateBody = (raw, label, allowEmpty = false) => {
+        if (!Array.isArray(raw))
+            throw new InvalidPlanError(`${label}: body must be an array`);
+        if (raw.length === 0 && !allowEmpty) {
+            // Silence must never read as success — same rule parsePlan applies to the plan.
+            throw new InvalidPlanError(`${label}: body is empty (a control body must do something; use when's "else": [] to mean "do nothing")`);
+        }
+        return raw.map((b, i) => validateNode(b, `${label}[${i}]`, depth + 1));
+    };
+    /** `if-present` and `while-present` are allowed one level deeper than the branching
+     *  nodes: they are the conditional and the index-walk an innermost branch body needs,
+     *  and because their own bodies are leaves they cannot open a further level. Blocking
+     *  them here does not make the model simplify — it makes it emit an unconditional
+     *  approximation instead. See LEAF_ONLY_ITEMS. */
+    const guardDepth = (extra = 0) => {
+        const limit = exports.MAX_CONTROL_DEPTH + extra;
+        if (depth >= limit) {
+            throw new InvalidPlanError(`${where}: control nodes may nest ${limit} deep at most (got ${depth + 1}) — flatten this or lift it to an outer step`);
+        }
+    };
+    const selectorOf = () => {
+        if (typeof n.selector !== 'string' || !n.selector)
+            throw new InvalidPlanError(`${where}: ${n.type} needs a selector`);
+        return n.selector;
+    };
+    // OpenAI/codex strict mode forces every property into `required` and nullifies the
+    // optional ones, so an absent `else`/`bind` arrives as null rather than missing.
+    const optional = (v, pick) => v === undefined || v === null ? undefined : pick(v);
     switch (n.type) {
         case 'command': {
             if (typeof n.command !== 'string' || !exports.KNOWN_COMMANDS.has(n.command)) {
@@ -158,22 +304,50 @@ function validateNode(node, where) {
                 throw new InvalidPlanError(`${where}: flags must be {name,value}[]`);
             return { type: 'command', command: n.command, positionals: n.positionals, flags: n.flags };
         }
-        case 'if-present':
-        case 'repeat': {
-            if (typeof n.selector !== 'string' || !n.selector)
-                throw new InvalidPlanError(`${where}: ${n.type} needs a selector`);
-            if (!Array.isArray(n.body))
-                throw new InvalidPlanError(`${where}: ${n.type} body must be an array`);
-            const body = n.body.map((b, i) => {
-                const leaf = validateNode(b, `${where}.body[${i}]`);
-                if (leaf.type !== 'command')
-                    throw new InvalidPlanError(`${where}.body[${i}]: only leaf commands allowed (no nesting in v1)`);
-                return leaf;
+        case 'read': {
+            const selector = selectorOf();
+            if (typeof n.field !== 'string' || !READ_FIELDS.has(n.field)) {
+                throw new InvalidPlanError(`${where}: read needs field one of ${[...READ_FIELDS].join('|')} (got ${JSON.stringify(n.field)})`);
+            }
+            if (typeof n.into !== 'string' || !CTX_NAME_RE.test(n.into)) {
+                throw new InvalidPlanError(`${where}: read "into" must be a plain identifier (got ${JSON.stringify(n.into)})`);
+            }
+            return { type: 'read', selector, field: n.field, into: n.into };
+        }
+        case 'if-present': {
+            guardDepth(1);
+            return { type: 'if-present', selector: selectorOf(), body: validateBody(n.body, `${where}.body`) };
+        }
+        case 'when': {
+            guardDepth();
+            if (!Array.isArray(n.branches) || n.branches.length === 0) {
+                throw new InvalidPlanError(`${where}: when needs at least one branch`);
+            }
+            const branches = n.branches.map((b, i) => {
+                const br = b;
+                if (!br || typeof br !== 'object' || typeof br.selector !== 'string' || !br.selector) {
+                    throw new InvalidPlanError(`${where}.branches[${i}]: needs a selector`);
+                }
+                return { selector: br.selector, body: validateBody(br.body, `${where}.branches[${i}].body`) };
             });
-            if (n.type === 'if-present')
-                return { type: 'if-present', selector: n.selector, body };
+            const els = optional(n.else, (v) => validateBody(v, `${where}.else`, true));
+            return { type: 'when', branches, ...(els ? { else: els } : {}) };
+        }
+        case 'repeat':
+        case 'while-present': {
+            guardDepth(n.type === 'while-present' ? 1 : 0);
+            const selector = selectorOf();
             const cap = typeof n.cap === 'number' && n.cap > 0 ? Math.floor(n.cap) : exports.DEFAULT_LOOP_CAP;
-            return { type: 'repeat', selector: n.selector, cap, body };
+            const body = validateBody(n.body, `${where}.body`);
+            if (n.type === 'repeat')
+                return { type: 'repeat', selector, cap, body };
+            const bind = optional(n.bind, (v) => {
+                if (typeof v !== 'string' || !CTX_NAME_RE.test(v)) {
+                    throw new InvalidPlanError(`${where}: while-present "bind" must be a plain identifier (got ${JSON.stringify(v)})`);
+                }
+                return v;
+            });
+            return { type: 'while-present', selector, cap, body, ...(bind ? { bind } : {}) };
         }
         default:
             throw new InvalidPlanError(`${where}: unknown node type ${JSON.stringify(n.type)}`);

package/dist/agent/lint.js

@@ -0,0 +1,77 @@
+"use strict";
+// Compile-fidelity lint: does the plan the model produced still say what the prose said?
+//
+// The model is a compiler, and this is the compiler's own sanity check. It exists because
+// compilation is NONDETERMINISTIC in a way that is invisible until a run fails, and two
+// failure modes showed up repeatedly against a real suite:
+//
+//   1. An explicit directive silently vanishes. The same prose ("Launch the app WITH ITS
+//      DATA CLEARED so it starts logged-out") compiled to `launch <pkg> --clear` on one
+//      run and plain `launch <pkg>` on the next. The plan looked fine and the test failed
+//      several steps later, on a screen that only appears when you are already logged in.
+//   2. Conditional prose compiles to an unconditional step. "IF a Continue button appears,
+//      tap it" becomes `wait` + `tap`, which FAILS on every run where the app skips it.
+//
+// Both are cheap to detect and cheap to fix: hand the finding back to the model and let it
+// compile once more. That is far better than the alternative, which is a plan that is
+// quietly wrong and burns a device run to say so.
+//
+// Deliberately CONSERVATIVE — a false positive costs a wasted recompile, so every rule
+// requires a fairly unambiguous phrase and checks for a specific structural counterpart.
+// It never edits the plan; the model gets the feedback and stays the author.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintPlan = lintPlan;
+const ir_1 = require("./ir");
+/** Walk every node in the plan, including control-node bodies. */
+function* walk(nodes) {
+    for (const n of nodes) {
+        yield n;
+        if ((0, ir_1.isControlNode)(n))
+            for (const body of (0, ir_1.bodiesOf)(n))
+                yield* walk(body);
+    }
+}
+const hasControlNode = (plan) => {
+    for (const n of walk(plan.steps))
+        if ((0, ir_1.isControlNode)(n))
+            return true;
+    return false;
+};
+const hasLeafWithFlag = (plan, command, flag) => {
+    for (const n of walk(plan.steps)) {
+        if (n.type === 'command' && n.command === command && n.flags.some((f) => f.name === flag))
+            return true;
+    }
+    return false;
+};
+/** Phrases that state the app must start from a clean slate. Kept tight on purpose:
+ *  "clear" alone is far too common (clearing a text field, a clear button). */
+const FRESH_START_RE = /\b(data cleared|cleared data|clear its data|with its data cleared|freshly installed|logged[- ]out|logged out|clean state|from scratch)\b/i;
+/** Phrases that make a step conditional. These are the ones that produced an
+ *  unconditional step in practice; vaguer hedges ("should", "normally") are excluded. */
+const CONDITIONAL_RE = /\b(if (?:a|an|the|any)\b|may appear|might appear|sometimes|optionally|if present|if shown|if it appears|dismiss any)\b/i;
+/**
+ * Check a compiled plan against the prose it came from.
+ *
+ * @param nl   the natural-language test, verbatim
+ * @param plan the plan the model just produced
+ * @returns findings; empty means the plan is consistent with the prose
+ */
+function lintPlan(nl, plan) {
+    const findings = [];
+    if (FRESH_START_RE.test(nl) && !hasLeafWithFlag(plan, 'launch', 'clear')) {
+        findings.push({
+            message: 'The test says the app must start from cleared data / logged out, but no step launches it with --clear. ' +
+                'Emit `launch <package> --clear` so the run does not inherit the previous run\'s session.',
+        });
+    }
+    if (CONDITIONAL_RE.test(nl) && !hasControlNode(plan)) {
+        findings.push({
+            message: 'The test describes something that may or may not appear ("if ...", "may appear", "dismiss any ..."), ' +
+                'but the plan has no if-present/when node — every step is unconditional. An unconditional step for ' +
+                'optional UI fails on every run where that UI does not show. Put the optional part behind if-present ' +
+                '(skip when absent), or behind when (when the screen is one of several known kinds).',
+        });
+    }
+    return findings;
+}

package/dist/agent/openai.js

@@ -116,6 +116,12 @@ class OpenAiProvider {
                 JSON.stringify(input.seed, null, 2));
         }
         parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        if (input.retryFeedback) {
+            // Last, so it is the freshest thing in context: a previous compile of this same
+            // test lost something the prose stated. Naming it beats hoping the retry differs.
+            parts.push('YOUR PREVIOUS ATTEMPT AT THIS TEST WAS REJECTED. Fix this and emit the whole plan again:\n' +
+                input.retryFeedback);
+        }
         // Generous completion budget: on reasoning models the plan JSON shares this ceiling
         // with reasoning tokens, so leave headroom (a 'length' finish is surfaced as an error).
         const { json, usage } = await this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA, 16384);

package/dist/cli.js

@@ -41,6 +41,7 @@ exports.parseDuration = parseDuration;
 exports.waitWindowMs = waitWindowMs;
 exports.waitNote = waitNote;
 exports.formatDeviceTable = formatDeviceTable;
+exports.guardSettleMs = guardSettleMs;
 exports.confineToCwd = confineToCwd;
 exports.assertSafeAppId = assertSafeAppId;
 exports.chooseLogOpts = chooseLogOpts;
@@ -61,6 +62,7 @@ const output_1 = require("./output");
 const run_1 = require("./run");
 const image_1 = require("./image");
 const engine_1 = require("./agent/engine");
+const lint_1 = require("./agent/lint");
 const claude_1 = require("./agent/claude");
 const openai_1 = require("./agent/openai");
 const cli_provider_1 = require("./agent/cli-provider");
@@ -93,7 +95,11 @@ function buildSelector(raw, flags) {
     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') });
+    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'),
+    });
 }
 function parsePoint(s) {
     const m = /^(-?\d+)\s*,\s*(-?\d+)$/.exec(s.trim());
@@ -510,6 +516,19 @@ function shotMaxEdge() {
     }
     return DEFAULT_SHOT_MAX_EDGE;
 }
+/** How long a `vk ai` `if-present` guard waits for its selector before deciding the
+ *  optional UI is absent. `VERIKUN_GUARD_SETTLE_MS` overrides the engine default so the
+ *  window can be tuned against a real app without a rebuild (0 restores the old
+ *  single-shot probe). Exported for unit tests. */
+function guardSettleMs() {
+    const env = process.env.VERIKUN_GUARD_SETTLE_MS;
+    if (env !== undefined && env !== '') {
+        const n = Number(env);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    return engine_1.DEFAULT_GUARD_SETTLE_MS;
+}
 /** Resolve an `--out` path and confine it to the working directory. A host-side write
  *  (a screenshot PNG, captured device logs) must never land outside cwd via a `..`
  *  traversal or an absolute path — including when driven by `vk ai` model output, whose
@@ -654,10 +673,20 @@ function evalAssert(els, sel, flags) {
     }
     else if (wantText !== undefined) {
         const contains = (0, args_1.flagBool)(flags, 'contains');
-        pass = matches.some((m) => contains
-            ? m.text.toLowerCase().includes(wantText.toLowerCase())
-            : m.text.trim().toLowerCase() === wantText.trim().toLowerCase());
-        reason = pass ? 'text matched' : `found, but text != ${JSON.stringify(wantText)} (got ${JSON.stringify(matches.map((m) => m.text))})`;
+        // Compare against text OR content-desc, mirroring what the selector layer already
+        // does (a `text:` selector falls back to desc when nothing matches on text). Without
+        // the fallback this could never pass on a Flutter app, which maps Semantics(label:)
+        // to contentDescription and leaves `text` empty on every node — while `text:Foo` as a
+        // SELECTOR resolved fine, so the contradiction was silent and read as a real failure.
+        // Strictly widening: it only turns false negatives into passes.
+        const content = (m) => [m.text, m.desc].filter((v) => v !== '');
+        const hit = (v) => contains
+            ? v.toLowerCase().includes(wantText.toLowerCase())
+            : v.trim().toLowerCase() === wantText.trim().toLowerCase();
+        pass = matches.some((m) => content(m).some(hit));
+        reason = pass
+            ? 'text matched'
+            : `found, but text != ${JSON.stringify(wantText)} (got ${JSON.stringify(matches.flatMap(content))})`;
     }
     else {
         pass = true;
@@ -1039,8 +1068,38 @@ async function obtainPlan(key, file, opts, cost, provider) {
     if (seed)
         (0, output_1.err)(`[ai] no exact cache; seeding from a prior plan (build ${seed.build ?? 'unknown'})`);
     (0, output_1.err)(`[ai] compiling '${file}' with ${opts.model} (effort ${opts.effort ?? 'default'})…`);
-    const compiled = await provider.compile({ nl: key.nl, pkg: key.pkg, platform: key.platform, seed: seed?.plan });
+    let compiled = await provider.compile({ nl: key.nl, pkg: key.pkg, platform: key.platform, seed: seed?.plan });
     cost.add(compiled.usage, 'compile');
+    // Compilation is nondeterministic: the same prose has produced `launch --clear` on one
+    // run and plain `launch` on the next, silently dropping something the test stated. One
+    // guided retry is much cheaper than discovering it as a device-run failure several steps
+    // later. Budget is re-checked HERE because the first attempt has already been billed.
+    const findings = (0, lint_1.lintPlan)(key.nl, compiled.plan);
+    if (findings.length > 0) {
+        const feedback = findings.map((f) => `- ${f.message}`).join('\n');
+        (0, output_1.err)(`[ai] compiled plan does not match the test — recompiling once:\n${feedback}`);
+        if (cost.exceeded()) {
+            (0, output_1.err)('[ai] cost ceiling reached — keeping the first plan rather than paying for a retry');
+        }
+        else {
+            const retry = await provider.compile({
+                nl: key.nl,
+                pkg: key.pkg,
+                platform: key.platform,
+                seed: seed?.plan,
+                retryFeedback: feedback,
+            });
+            cost.add(retry.usage, 'compile');
+            const still = (0, lint_1.lintPlan)(key.nl, retry.plan);
+            // Keep the retry either way: it was compiled with strictly more information. If it
+            // still trips the lint, say so rather than pretending the plan is clean.
+            if (still.length > 0)
+                (0, output_1.err)(`[ai] the retry still does not match the test — running it anyway:\n${still.map((f) => `- ${f.message}`).join('\n')}`);
+            else
+                (0, output_1.err)('[ai] recompile matches the test');
+            compiled = retry;
+        }
+    }
     (0, output_1.err)(`[ai] compiled ${compiled.plan.steps.length} top-level step(s) · ${cost.summaryLine()}`);
     try {
         (0, cache_1.writePlan)(key, compiled.plan);
@@ -1132,7 +1191,7 @@ async function runAiTest(file, opts, backend, platform, device) {
         const sealed = run_1.Recorder.archive();
         (0, output_1.err)(`[ai] archived the active run ('${existing.name}', ${existing.steps.length} step(s)) → ${sealed.dir}`);
     }
-    run_1.Recorder.start(`ai: ${(0, node_path_1.basename)(file)}`, platform, device, true);
+    const started = run_1.Recorder.start(`ai: ${(0, node_path_1.basename)(file)}`, platform, device, true);
     // Suppress per-step `out()` so stdout stays the one final result; progress -> stderr.
     const prevQuiet = (0, output_1.setOutputQuiet)(true);
     let result;
@@ -1145,6 +1204,8 @@ async function runAiTest(file, opts, backend, platform, device) {
             log: (m) => (0, output_1.err)(m),
             markHealed: (m) => run_1.Recorder.markLastStepHealed(m),
             maxRepairs: 3,
+            guardSettleMs: guardSettleMs(),
+            runId: started.id,
             deadline,
         });
     }
@@ -1649,6 +1710,8 @@ AUTO-WAIT (selector lookups retry until they resolve)
   up to 5s when a lookup misses, so a settling UI needs no explicit \`wait\`.
   --wait <dur>   override the window: 8s, 800ms, or bare ms (3000); 0 disables
   --no-wait      fail fast on the first miss (same as --wait 0)
+  A \`vk ai\` plan's if-present guard has its own smaller settle window (>=2 looks at
+  the screen); VERIKUN_GUARD_SETTLE_MS tunes it, 0 = old single-shot probe.
   Ambiguity is never waited on (the elements are already there). The \`wait\`
   command stays for explicit polling, including --gone, with --timeout/--interval.
 

package/dist/ui/selector.js

@@ -21,8 +21,20 @@ 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, raw };
+    return { kind, value, contains: !!opts.contains, index: opts.index, enabled: opts.enabled, raw };
 }
+/** Is this element actionable right now?
+ *
+ *  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;
 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. */
@@ -77,6 +89,10 @@ function tiers(sel) {
     return sel.contains ? list.filter((t) => t.tier !== 'exact') : list;
 }
 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);
     for (const { tier, test } of tiers(sel)) {
         const found = elements.filter(test);
         if (found.length === 0)

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.10.0';
+exports.VERSION = '0.11.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.10.0",
+  "version": "0.11.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",