verikun 0.10.0 → 0.12.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.
@@ -278,16 +286,30 @@ 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.
 - **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
     is the **output contract for reporting** — upload/publish steps compose over
     it (see the [CI recipe](#ci-recipe)) instead of verikun growing upload plugins.
-  - **`index.html`** — a summary page linking every test's `report.html`.
-- **Exit code is the CI gate:** `1` if any test failed, `0` all green, `2` bad/empty
-  directory. All `ai` flags (`--model`, `--max-cost-usd`, `--timeout`, …) apply to
-  every test; the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` /
-  `cursor-agent` CLI for `--model codex-cli` / `cursor-cli`) is checked up front.
+    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.
+  - **`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.
 
 ## Remote devices — `vk server`
 
@@ -367,7 +389,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.
@@ -423,7 +449,7 @@ condition as a step in its own right.
 | `0` | success / found / assertion passed |
 | `1` | not found / assertion failed / wait timeout |
 | `2` | usage error or ambiguous selector (caller must refine) |
-| `3` | environment error (adb/simctl missing, no/multiple devices, dump failed) |
+| `3` | environment error (adb/idb/simctl missing, no/multiple devices, dump failed). `ai`, `suite`, `install` and `server` verify the toolchain up front, so this arrives immediately with an install hint instead of mid-flow — and a `suite` whose device dies mid-run stops with `3` rather than reporting the rest as failures |
 
 Data goes to stdout; diagnostics/errors go to stderr.
 

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,10 +1,34 @@
 "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");
+/** An outcome is environment-flavoured if it carries an exit-3 CliError, or simply
+ *  reported code 3 — the latter also catches a remote step whose error crossed the
+ *  wire as a plain Error (rebuildError drops exitCode) and a non-CliError throw,
+ *  both of which the top-level contract already maps to exit 3. Over-classifying is
+ *  safe here because `vk suite` re-probes before treating it as fatal. */
+const isEnvOutcome = (outcome) => outcome.code === 3 || (0, errors_1.isEnvError)(outcome.error);
+/**
+ * A control-flow guard could not read the screen even once, because the environment is
+ * broken (exit 3). Thrown out of `present()` and converted to a `status: 'env'` step
+ * result by the single catch in runPlan's step loop.
+ *
+ * A throw rather than a wider `present()` return type on purpose: `present()` has seven
+ * call sites across `if-present` / `when` / `repeat` / `while-present` / the guard-race
+ * check, and every one of them would need the same three-line env branch — repetition in
+ * the most intricate code here, and a silent false green at whichever site someone forgot.
+ * runPlan still RETURNS its result; this never escapes the engine.
+ */
+class GuardBlindError extends Error {
+    constructor(selector, cause) {
+        super(`could not read the screen to evaluate '${selector}': ${cause.message.split('\n')[0]}`);
+        this.name = 'GuardBlindError';
+    }
+}
 const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map((f) => (f.value === 'true' ? `--${f.name}` : `--${f.name} ${f.value}`))]
     .join(' ')
     .trim();
@@ -13,23 +37,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 +165,25 @@ 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.
+     *
+     *  Throws GuardBlindError when the window closes having NEVER once read the screen
+     *  and the failure was an environment error — see that class for why. */
+    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 +191,80 @@ 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;
+        // Did ANY dump in this whole call come back? A successful-but-empty tree counts: that
+        // is a bad read of a live screen, not a blind one, and it is already handled below.
+        let everRead = false;
+        let lastErr;
+        const minLooks = settleMs > 0 ? 2 : 1;
+        for (;;) {
+            let els;
+            for (let i = 0; i < 2; i++) {
+                try {
+                    els = await deps.getElements();
+                    everRead = true;
+                }
+                catch (e) {
+                    els = undefined; // transient dump failure — retry once before concluding "absent"
+                    lastErr = e;
+                }
+                // 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) {
+                // The window closed having NEVER once read the screen, because the environment is
+                // broken. Answering "absent" here is a lie that silently skips the body — and a
+                // guard-heavy plan would then finish fully GREEN having executed nothing.
+                if (!everRead && (0, errors_1.isEnvError)(lastErr))
+                    throw new GuardBlindError(selector, lastErr);
+                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()) {
@@ -150,53 +338,196 @@ async function runPlan(plan, deps) {
         if (isHealable(outcome)) {
             return { status: 'fail', where, reason: `unresolved after ${maxRepairs} repair attempt(s): ${outcome.error.message.split('\n')[0]}` };
         }
-        // Terminal: an assertion failure (exit 1, no throw) or an environment error.
+        // Terminal: an assertion failure (exit 1, no throw) or an environment error. The
+        // two are reported differently — an assertion failure is a regression to fix, an
+        // environment error means the harness is broken and nothing downstream is
+        // trustworthy, so the caller aborts rather than banking a red result.
         const reason = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
-        return { status: 'fail', where, reason };
+        return { status: isEnvOutcome(outcome) ? 'env' : '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;
                 }
-                deps.log(`[ai] ${where}: repeat hit cap ${node.cap} without '${node.selector}' (continuing)`);
+                // 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}: while-present hit cap ${node.cap}`);
                 return { status: 'ok' };
             }
         }
@@ -206,13 +537,28 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] run timeout reached before steps[${i}] — aborting`);
             return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
         }
-        const res = await walkNode(plan.steps[i], `steps[${i}]`, (l) => (plan.steps[i] = l));
+        // The one place a blind guard becomes a step result — see GuardBlindError.
+        let res;
+        try {
+            res = await walkNode(plan.steps[i], `steps[${i}]`, (l) => (plan.steps[i] = l));
+        }
+        catch (e) {
+            if (!(e instanceof GuardBlindError))
+                throw e;
+            res = { status: 'env', where: `steps[${i}]`, reason: e.message };
+        }
         if (res.status === 'budget') {
             return { ok: false, plan, modelRepairs, improvements, abortedForBudget: true };
         }
         if (res.status === 'timeout') {
             return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
         }
+        if (res.status === 'env') {
+            // `failure` is populated as well as the flag: the suite report still wants a row
+            // reason, and callers that only know about `failure` keep working unchanged.
+            deps.log(`[ai] ABORTED at ${res.where} — environment: ${res.reason}`);
+            return { ok: false, plan, modelRepairs, improvements, abortedForEnv: true, failure: { where: res.where, reason: res.reason } };
+        }
         if (res.status === 'fail') {
             deps.log(`[ai] FAILED at ${res.where}: ${res.reason}`);
             return { ok: false, plan, modelRepairs, improvements, failure: { where: res.where, reason: res.reason } };