verikun 0.26.0-rc.5 → 0.26.1

package/.claude/skills/verikun/SKILL.md

@@ -390,7 +390,19 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   the flow. An `if-present` guard **waits for its selector to settle** (at least two looks
   at the screen) before deciding the optional UI is absent, so a dialog that animates in a
   beat after the transition is still caught. An absent guard costs about one extra UI dump;
-  `VERIKUN_GUARD_SETTLE_MS=0` restores the old single-shot probe.
+  `VERIKUN_GUARD_SETTLE_MS=0` restores the old single-shot probe. A guard that cannot read the
+  screen **at all** — the app force-stopped, mid-launch, or busy mid-transition — keeps looking
+  for up to 10s rather than aborting; still blind after that is exit `3`, never "absent".
+- **A compile has to cover the test.** Compilation is nondeterministic, and its worst outcome
+  is a plan that stops part-way: it asserts nothing after that point, so it *passes*, caches
+  green, and replays against later builds — a test exercising none of its subject reporting
+  success. A fresh compile is therefore checked against the prose (its size, and whether the
+  plan references what the test's closing steps name); a failure buys one guided recompile,
+  and a plan still short after that is **rejected at exit `1` and not cached**, so rerunning
+  compiles again rather than replaying it. Under `vk suite` that means `--retries` cannot turn
+  a truncated compile green. `VERIKUN_NO_COMPILE_CHECK=1` turns the check off. The stderr line
+  `compiled N top-level step(s)` (`planSteps` in `--json` and in a suite manifest row) is the
+  number to compare across runs of an unchanged test.
 - **Progress streams to stderr** (never silent in CI); **stdout is the report path**
   (`--json` for a structured summary). It records like any flow, so it ends with the
   same JUnit + HTML report — including the token/cost line and **suggested improvements**
@@ -409,7 +421,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   ever called to **compile** (once, on a cache miss) or to **repair** (≤3 per failing step);
   replay is always $0, and every non-`ai` command is $0 always. Full mechanism, the estimate
   formula and the cache multipliers: <https://ddikman.github.io/verikun/reference/cost/>.
-- Exit `0` pass · `1` a step failed (or the budget/timeout was hit) · `2` usage · `3` environment
+- Exit `0` pass · `1` a step failed (or the budget/timeout was hit, or the compile did not
+  cover the test) · `2` usage · `3` environment
   (e.g. the model's API key — `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` — unset, or the `codex` /
   `cursor-agent` CLI missing / not logged in for `--model codex-cli` / `cursor-cli`).
 - **`3` also means the device toolchain is broken**, checked *before* anything is compiled

package/CHANGELOG.md

@@ -6,43 +6,27 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.26.1] - 2026-09-07
+
+Fixes a `vk ai` run dying when the app is redrawing at the moment a guard checks the screen.
+
 ### Added
-- **`@include <path>`** in a `vk ai` test inlines another file's prose, so a shared preamble
-  lives in one place. Paths resolve relative to the including file. ([#112])
-- **`vk server --log-file <path|off>`** writes a rotating server log, on by default at
-  `~/.verikun/logs/server-<port>.log`. `VERIKUN_LOG_FILE` sets the same value.
-- **`vk server`** re-adopts pooled devices that come back, sweeping every 60s with backoff.
-- **`/v1/health`** reports `degraded`: pool members still serving but dealt last.
-- **`VERIKUN_NO_PLAN_LOCK=1`** turns off plan-compile locking, restoring the previous
-  compile-in-parallel behaviour. ([#117])
+- **`errorKind` on every `vk server` error response**: a device error keeps its class over the
+  wire, not only on `/v1/exec`. Absent from older servers. ([#80])
+
+### Fixed
+- **`vk ai` guards** now ride out a transient "no window" for up to 10s instead of aborting the
+  run. A bare `vk ui` still exits `3`. ([#80])
 
 ### Changed
-- **`vk suite`** skips `_`-prefixed `*.md` — those are shared fragments, not tests. ([#112])
-- **`vk ai`** compiles each chunk of an `@include`d test separately and caches it, so shared
-  prose is compiled once across a suite. ([#112])
-- **`vk suite`** lanes now wait for a shared `@include` fragment's first compile instead of
-  each paying for one. ([#117])
-- **`vk server`** demotes a failing pooled device instead of dropping it, so capacity no
-  longer ratchets down and never recovers.
-- **`vk server`** deals leases healthy-first, then least-recently-used, instead of first-fit.
-- **`vk server`** no longer blames a device when the probe itself fails for a host reason.
-- **`vk server`** keeps the pool intact when an install fails on every device — the build is
-  the suspect, not the phones.
-- **`vk server`** logs error bodies, run tokens, leased serials and every lease eviction.
-- **`vk install`** (Android) removes a differently-signed build of the same package and retries,
-  instead of failing. Its app data is lost; stderr says so. ([#96])
-- **`VERIKUN_CLAIM_TTL_MIN`** now also paces a parallel suite's claim heartbeat — a quarter of
-  the window, capped at 60s — so a short TTL no longer races it.
+- **"No window to read"** now names a busy main thread mid-transition as a cause, and no longer
+  suggests a command that waits. ([#80])
 
-### Fixed
-- **`vk server`** terminates a worker that stops answering, instead of holding its lease
-  forever while health still advertises the device.
+[#80]: https://github.com/ddikman/verikun/issues/80
 
-[#96]: https://github.com/ddikman/verikun/issues/96
-[#112]: https://github.com/ddikman/verikun/issues/112
-[#117]: https://github.com/ddikman/verikun/issues/117
+## [0.26.0] - 2026-09-05
 
-## [0.26.0] - 2026-08-24
+Runs a suite across a pool of devices, and shares prose between tests with `@include`.
 
 ### Added
 - **`vk suite --devices a,b` / `--servers u1,u2`**: run tests across a device pool, next free
@@ -61,6 +45,18 @@ All notable changes to this project are documented here. The format is based on
   working directory don't delete each other's state.
 - **`POST /v1/lease`** and `capacity` / `devices` on `/v1/health`: which device a run token holds,
   and how many the server has.
+- **`@include <path>`** in a `vk ai` test inlines another file's prose, so a shared preamble
+  lives in one place. Paths resolve relative to the including file. ([#112])
+- **`vk server --log-file <path|off>`** writes a rotating server log, on by default at
+  `~/.verikun/logs/server-<port>.log`. `VERIKUN_LOG_FILE` sets the same value.
+- **`vk server`** re-adopts pooled devices that come back, sweeping every 60s with backoff.
+- **`/v1/health`** reports `degraded`: pool members still serving but dealt last.
+- **`VERIKUN_NO_PLAN_LOCK=1`** turns off plan-compile locking, restoring the previous
+  compile-in-parallel behaviour. ([#117])
+- **`VERIKUN_NO_COMPILE_CHECK=1`** turns off the `vk ai` compile-coverage check, restoring
+  the previous accept-anything behaviour. ([#127])
+- **`planSteps`** in a suite manifest row and `vk ai --json`: the plan's compiled size, next
+  to `steps` (what executed). ([#127])
 
 ### Changed
 - **Suite manifest**: adds `totals.wallClockMs`, `concurrency` and a per-test `device`.
@@ -82,13 +78,44 @@ All notable changes to this project are documented here. The format is based on
   phone unasked.
 - **`vk server` failover on a pool**: a failed device is quarantined and a healthy one takes its
   place, so capacity holds. ([#39], [#99])
+- **`vk suite`** skips `_`-prefixed `*.md` — those are shared fragments, not tests. ([#112])
+- **`vk ai`** compiles each chunk of an `@include`d test separately and caches it, so shared
+  prose is compiled once across a suite. ([#112])
+- **`vk suite`** lanes now wait for a shared `@include` fragment's first compile instead of
+  each paying for one. ([#117])
+- **`vk server`** demotes a failing pooled device instead of dropping it, so capacity no
+  longer ratchets down and never recovers.
+- **`vk server`** deals leases healthy-first, then least-recently-used, instead of first-fit.
+- **`vk server`** no longer blames a device when the probe itself fails for a host reason.
+- **`vk server`** keeps the pool intact when an install fails on every device — the build is
+  the suspect, not the phones.
+- **`vk server`** logs error bodies, run tokens, leased serials and every lease eviction.
+- **`vk install`** (Android) removes a differently-signed build of the same package and retries,
+  instead of failing. Its app data is lost; stderr says so. ([#96])
+- **`VERIKUN_CLAIM_TTL_MIN`** now also paces a parallel suite's claim heartbeat — a quarter of
+  the window, capped at 60s — so a short TTL no longer races it.
+- **Contributor docs**: rules stated once, with the history left to the docs site; the companion
+  notes no longer describe it as a prototype.
+- **Docs site**: the contracts, core-principles, plan-engine and AI-plans pages state each rule
+  once and link the page that owns the detail.
+- **Docs site**: shorter remote-device, troubleshooting and cost guides; global flags now live on
+  the Commands page — the standalone page is gone.
 
 ### Fixed
 - **`--server` runs no longer fail with `fetch failed`** when a step follows a pause longer
   than 5s, such as a cold compile.
 - **`--server` screenshots and failure evidence** are no longer corrupted in the archived report.
+- **`vk ai`** rejects a compile that covers only the start of its test, instead of caching
+  and replaying the short plan as a pass. Exit `1`. ([#127])
+- **`vk ai`** no longer seeds a new compile from a cached plan that is itself truncated. ([#127])
+- **`vk server`** terminates a worker that stops answering, instead of holding its lease
+  forever while health still advertises the device.
 
 [#39]: https://github.com/ddikman/verikun/issues/39
+[#96]: https://github.com/ddikman/verikun/issues/96
+[#112]: https://github.com/ddikman/verikun/issues/112
+[#117]: https://github.com/ddikman/verikun/issues/117
+[#127]: https://github.com/ddikman/verikun/issues/127
 
 ## [0.25.1] - 2026-08-21
 

package/README.md

@@ -6,7 +6,7 @@
 
 - **Agent CLI** — `vk <command>`: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
-- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
+- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. A compile that does not cover its test is rejected rather than cached as a pass. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
 - **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad.
 
@@ -63,7 +63,7 @@ There is also no need for an MCP here: verikun runs locally with all its depende
 |---|---|
 | **Getting started** | [Installation](https://ddikman.github.io/verikun/getting-started/installation/) · [Your first test](https://ddikman.github.io/verikun/getting-started/your-first-test/) · [Using it from an AI agent](https://ddikman.github.io/verikun/getting-started/using-from-an-agent/) |
 | **Guides** | [Writing test cases](https://ddikman.github.io/verikun/guides/writing-test-cases/) · [Natural-language tests](https://ddikman.github.io/verikun/guides/natural-language-tests/) · [Suites](https://ddikman.github.io/verikun/guides/suites/) · [Remote devices & CI](https://ddikman.github.io/verikun/guides/remote-devices-and-ci/) · [iOS setup](https://ddikman.github.io/verikun/guides/ios-setup/) · [Platform support](https://ddikman.github.io/verikun/guides/platform-support/) · [Troubleshooting](https://ddikman.github.io/verikun/guides/troubleshooting/) |
-| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
+| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/commands/#global-flags) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
 | **Internals** | [Architecture](https://ddikman.github.io/verikun/internals/architecture/) · [Core principles](https://ddikman.github.io/verikun/internals/core-principles/) · [Plan IR & the replay engine](https://ddikman.github.io/verikun/internals/plan-ir-and-engine/) · [Contracts](https://ddikman.github.io/verikun/internals/contracts/) · [Contributing](https://ddikman.github.io/verikun/internals/contributing/) |
 
 **Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error, ambiguous selector, or a device another job is driving · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/). Parallel agents share a host-level [device claim](https://ddikman.github.io/verikun/reference/device-claims/) so two jobs do not silently land on the same phone.
@@ -83,17 +83,7 @@ npm test         # type-check + the unit suite (no device needed)
 npm link         # optional: put `verikun` and `vk` on your PATH
 ```
 
-Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing — is in [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
-
-To work on the [documentation site](https://ddikman.github.io/verikun/), which is an Astro Starlight project in `docs/` with its own dependencies (so `npm install` above does not cover it):
-
-```sh
-npm run docs:install   # once — installs the site's dependencies (needs Node >= 22.12)
-npm run docs           # dev server with live reload at http://localhost:4321/verikun/
-npm run docs:build     # production build; fails on a dead internal link
-```
-
-Open **http://localhost:4321/verikun/** — the site is served under a base path, so bare `localhost:4321` is a 404. Astro needs **Node ≥ 22.12** while the CLI supports Node ≥ 18, so `nvm use 22` first if your shell's Node is older.
+Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing, and running the documentation site locally — is [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
 
 ## License
 

package/dist/agent/claude.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeProvider = void 0;
 const errors_1 = require("../errors");
-const format_1 = require("../ui/format");
+const wait_1 = require("../wait");
 const ir_1 = require("./ir");
 const provider_1 = require("./provider");
 const grammar_1 = require("./grammar");
@@ -18,8 +18,6 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 // effort (output_config.effort) is rejected by Haiku 4.5; only send it for models
 // that accept it.
 const EFFORT_MODELS = new Set(['claude-opus-4-8', 'claude-sonnet-4-6', 'claude-fable-5']);
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 15000);
 class ClaudeProvider {
     opts;
     constructor(opts) {
@@ -30,27 +28,8 @@ class ClaudeProvider {
         return { plan: (0, ir_1.parsePlan)(json), usage };
     }
     async repair(ctx) {
-        const parts = [
-            'FAILED STEP: ' + JSON.stringify(ctx.failedStep),
-            'FAILURE: ' + ctx.reason,
-        ];
-        if (ctx.candidates && ctx.candidates.length) {
-            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
-        }
-        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
-        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA, 1024);
-        const decision = (json ?? {});
-        if (decision.decision === 'give_up') {
-            return {
-                replaceStep: null,
-                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
-                usage,
-            };
-        }
-        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against
-        // the grammar before splicing (it is the execution trust boundary and can't assume a
-        // provider validated). A missing/invalid step is rejected there as a failed repair.
-        return { replaceStep: (decision.step ?? null), usage };
+        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, (0, provider_1.repairUserPrompt)(ctx), ir_1.REPAIR_DECISION_JSON_SCHEMA, 1024);
+        return (0, provider_1.repairDecision)(json, usage);
     }
     async call(system, user, schema, maxTokens) {
         const outputConfig = { format: { type: 'json_schema', schema } };
@@ -111,7 +90,7 @@ class ClaudeProvider {
             catch (e) {
                 if (attempt++ >= maxRetries)
                     throw new errors_1.CliError(`Anthropic API request failed: ${e.message}`, 3);
-                await sleep(backoffMs(attempt));
+                await (0, wait_1.sleep)((0, wait_1.backoffMs)(attempt));
                 continue;
             }
             finally {
@@ -122,7 +101,7 @@ class ClaudeProvider {
             // Retry 429 + 5xx with backoff, honoring Retry-After (no SDK to do it for us).
             if ((res.status === 429 || res.status >= 500) && attempt++ < maxRetries) {
                 const retryAfter = Number(res.headers.get('retry-after'));
-                await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : backoffMs(attempt));
+                await (0, wait_1.sleep)(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : (0, wait_1.backoffMs)(attempt));
                 continue;
             }
             const errText = await res.text().catch(() => '');

package/dist/agent/cli-provider.js

@@ -8,7 +8,6 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const errors_1 = require("../errors");
-const format_1 = require("../ui/format");
 const ir_1 = require("./ir");
 const provider_1 = require("./provider");
 const grammar_1 = require("./grammar");
@@ -153,23 +152,8 @@ class CliProvider {
         return { plan: (0, ir_1.parsePlan)(json), usage: {} };
     }
     async repair(ctx) {
-        const parts = ['FAILED STEP: ' + JSON.stringify(ctx.failedStep), 'FAILURE: ' + ctx.reason];
-        if (ctx.candidates && ctx.candidates.length) {
-            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
-        }
-        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
-        const json = this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA);
-        const decision = (json ?? {});
-        if (decision.decision === 'give_up') {
-            return {
-                replaceStep: null,
-                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
-                usage: {},
-            };
-        }
-        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against the
-        // grammar before splicing (it is the execution trust boundary), exactly like the API providers.
-        return { replaceStep: (decision.step ?? null), usage: {} };
+        // usage:{} for the same reason as compile — billed to the subscription, not per token.
+        return (0, provider_1.repairDecision)(this.call(grammar_1.REPAIR_GRAMMAR, (0, provider_1.repairUserPrompt)(ctx), ir_1.REPAIR_DECISION_JSON_SCHEMA), {});
     }
     /** Spawn the CLI once and return the parsed JSON object it produced. Synchronous (spawnSync);
      *  the async method wrappers satisfy the Promise-returning AgentProvider seam. */

package/dist/agent/engine.js

@@ -6,6 +6,7 @@ const node_crypto_1 = require("node:crypto");
 const selector_1 = require("../ui/selector");
 const state_support_1 = require("../ui/state-support");
 const errors_1 = require("../errors");
+const wait_1 = require("../wait");
 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
@@ -70,11 +71,10 @@ function isHealable(outcome) {
 }
 /** 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),
+ *  selector-resolving leaf command already auto-waits ~5s (commands/auto-wait.ts),
  *  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
@@ -88,6 +88,32 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 exports.DEFAULT_GUARD_SETTLE_MS = 1500;
 /** Re-dump cadence inside a guard's settle window. */
 const GUARD_POLL_MS = 150;
+/**
+ * How long a guard keeps looking at a screen it cannot read at all, when the reason is
+ * NoWindowError — the app was force-stopped or is mid-launch and has genuinely not drawn.
+ *
+ * Separate from `settleMs`, which answers "how long before I believe this selector is
+ * absent?". This answers "how long before I believe there is no screen to ask?" — a
+ * different question, and the only one whose wrong answer aborts the whole run.
+ *
+ * MEASURED (issue #80), post-`vk launch`, time until the first hierarchy read succeeds:
+ *   emulator-5554 (stock reads ~2s):        2027-2379ms over 10 launches
+ *   SM-A415F, physical (companion ~0.3s):   4746-6219ms over 15 launches
+ * So the "clears within a second or two" in NoWindowError's own doc is optimistic by 2.5x on
+ * real hardware; the emulator only looks compliant because one slow read already outlasts the
+ * gap. 10s clears the worst observed by ~1.6x. Below that the constant sits INSIDE the
+ * measured distribution, which is the one place it must not be.
+ *
+ * Deliberately MORE patient than a leaf command's 5s auto-wait, which is the opposite of
+ * DEFAULT_GUARD_SETTLE_MS's reasoning, because the asymmetry is real: a leaf that needs
+ * longer takes `--wait`, whereas a guard's patience is internal and a test author cannot
+ * reach it. Being generous costs at most this long ONCE per present() call, on a run that is
+ * already failing — against a 15-minute default run timeout, and clamped by it.
+ *
+ * Not configurable on purpose: a dial here is one more thing to explain, and every value a
+ * user might pick is worse than the measurement.
+ */
+const NO_WINDOW_GRACE_MS = 10_000;
 /** 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
@@ -179,6 +205,11 @@ async function runPlan(plan, deps) {
      *      probe a loop-exit check needs.
      *  So one dump attempt always happens regardless of the window.
      *
+     *  A THIRD clock sits beside both: a screen that cannot be read because the app has not
+     *  drawn (NoWindowError) is retried against NO_WINDOW_GRACE_MS, not against `settleMs`.
+     *  That is deliberately independent — "is this selector absent?" and "is there a screen to
+     *  ask at all?" are different questions, and only the second one aborts the run.
+     *
      *  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) => {
@@ -198,6 +229,10 @@ async function runPlan(plan, deps) {
         if (deps.platform)
             (0, state_support_1.assertStateSupported)(sel, deps.platform);
         const deadline = Date.now() + Math.max(0, settleMs);
+        // A screen that cannot be read AT ALL gets its own, longer clock — see NO_WINDOW_GRACE_MS.
+        // Clamped by the run deadline so a guard can never push a run past --timeout: the grace
+        // exists to spend budget the caller already has, never to invent more.
+        const noWindowDeadline = Math.min(Date.now() + NO_WINDOW_GRACE_MS, deps.deadline ?? Infinity);
         // 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
@@ -235,14 +270,31 @@ async function runPlan(plan, deps) {
                 return true;
             const remaining = deadline - Date.now();
             if (looks >= minLooks && remaining <= 0) {
+                // Nothing has been readable yet, and the reason is that the app has not drawn. That is
+                // an observation about the SCREEN, not a broken machine, and it clears on its own — so
+                // keep looking on the no-window clock instead of killing the run. MEASURED (#80): the
+                // two attempts above span ~75ms against a gap of 4.7-6.2s on a physical device, so
+                // without this a `repeat` with minutes of budget gives up in under a tenth of a second.
+                //
+                // Gated on `everRead` so this can only ever extend patience for an UNREADABLE screen.
+                // One successful read — even an empty tree — and the ordinary semantics resume exactly:
+                // settleMs=0 is still a single-shot probe. It must never make a merely ABSENT selector
+                // more patient, or every guard silently costs 10s.
+                if (!everRead && lastErr instanceof errors_1.NoWindowError && Date.now() < noWindowDeadline) {
+                    await (0, wait_1.sleep)(GUARD_POLL_MS);
+                    continue;
+                }
                 // 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.
+                //
+                // A no-window that outlives its grace lands here too, and still aborts: at that point
+                // the app really is gone, and reporting "absent" would be the same false green.
                 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)));
+            await (0, wait_1.sleep)(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
         }
     };
     const runLeaf = (leaf) => {
@@ -397,7 +449,7 @@ async function runPlan(plan, deps) {
                 // 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)));
+            await (0, wait_1.sleep)(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
         }
     }
     async function walkNode(node, where, replace, guard) {

package/dist/agent/ir.js

@@ -63,6 +63,30 @@ exports.KNOWN_COMMANDS = new Set([
     // non-recordable selector-resolver here (e.g. `find`) would corrupt an unrelated step.
 ]);
 exports.DEFAULT_LOOP_CAP = 25;
+// The two SIMPLE control nodes appear at every unrolled level (see innerControls), so
+// their shape is written once. Key order is the wire format — keep it.
+const ifPresentSchema = (body) => ({
+    type: 'object',
+    additionalProperties: false,
+    required: ['type', 'selector', 'body'],
+    properties: {
+        type: { type: 'string', enum: ['if-present'] },
+        selector: { type: 'string' },
+        body,
+    },
+});
+const whilePresentSchema = (body) => ({
+    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,
+    },
+});
 /**
  * JSON Schema for `output_config.format` so the model returns a guaranteed-valid
  * Plan. Deliberately NON-RECURSIVE: instead of a `Plan -> node -> Plan` cycle
@@ -73,16 +97,7 @@ 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 },
-            },
-        },
+        ifPresentSchema({ type: 'array', items: bodyItems }),
         {
             type: 'object',
             additionalProperties: false,
@@ -112,18 +127,7 @@ const stepItems = (bodyItems) => ({
                 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 },
-            },
-        },
+        whilePresentSchema({ type: 'array', items: bodyItems }),
     ],
 });
 /** The innermost level: leaves, reads, and the two SIMPLE control nodes — `if-present`
@@ -148,30 +152,7 @@ const stepItems = (bodyItems) => ({
  *  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,
-            },
-        },
-    ];
+    return [ifPresentSchema(leafBody), whilePresentSchema(leafBody)];
 };
 const LEAF_ONLY_ITEMS = { anyOf: [leafSchema(), readSchema(), ...innerControls()] };
 exports.PLAN_JSON_SCHEMA = {