verikun 0.26.0 → 0.26.2

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

@@ -233,6 +233,9 @@ round-trips and tokens.
   away (the elements are already there); add `--index N` or refine the selector.
 - **`vk assert <sel> --gone` waits for *disappearance*** — it polls until the
   element is absent, so you don't need a separate `wait --gone`.
+- **A modal's barrier is not an absence.** Reads settle through a sheet or dialog opening or
+  closing on their own. A miss saying *the hierarchy held only a modal barrier* means a modal
+  is still up — dismiss it (`vk tap desc:Scrim`, or `vk key back`); the selector is fine.
 
 When you *do* want to block on a condition as an explicit step (e.g. a long
 network wait beyond 5s), the `wait` command is still there with its own
@@ -390,7 +393,9 @@ 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

package/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.26.2] - 2026-09-10
+
+Android hierarchy reads no longer mistake a sheet's or dialog's barrier for an empty screen.
+
+### Fixed
+- **Android hierarchy reads** re-read a tree holding only a sheet's or dialog's barrier before
+  trusting it, `vk ui` included; a barrier that persists still misses. ([#131])
+
+### Changed
+- **Selector misses** (`tap`, `find`, `assert`, `wait`) name a modal barrier that was all the read
+  could see, instead of "never appeared". ([#131])
+
+[#131]: https://github.com/ddikman/verikun/issues/131
+
+## [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
+- **`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
+- **"No window to read"** now names a busy main thread mid-transition as a cause, and no longer
+  suggests a command that waits. ([#80])
+
+[#80]: https://github.com/ddikman/verikun/issues/80
+
 ## [0.26.0] - 2026-09-05
 
 Runs a suite across a pool of devices, and shares prose between tests with `@include`.

package/dist/agent/engine.js

@@ -88,6 +88,32 @@ exports.DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
 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,9 +270,26 @@ 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;

package/dist/agent/remote.js

@@ -9,6 +9,7 @@
 // into the CALLER's local run — so a remote run archives a report identical to a
 // local one. Recording stays a caller concern: this module never touches ./.verikun.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeStatus = describeStatus;
 exports.pingServer = pingServer;
 exports.remoteDeviceOp = remoteDeviceOp;
 exports.remoteDeviceList = remoteDeviceList;
@@ -30,6 +31,19 @@ const DEVICE_LIST_TIMEOUT_MS = 30_000;
 const DEVICE_START_TIMEOUT_MS = 5 * 60_000;
 const DEVICE_STOP_TIMEOUT_MS = 60_000;
 const trimUrl = (url) => url.replace(/\/+$/, '');
+/**
+ * Turn a non-2xx into the error the caller sees.
+ *
+ * The 401/409/503 arms come FIRST and stay class-free on purpose: those describe the
+ * TRANSPORT (wrong key, device leased, nothing attached), not something a driver threw, so
+ * there is no device-error identity to restore and their wording is what a user acts on.
+ *
+ * Everything else prefers the server's `errorKind`. That field is what stops a `--server` run
+ * reading a mid-launch `NoWindowError` as a fatal environment error: the class survives the
+ * worker→main hop server-side, and this is where it used to be replaced by an anonymous
+ * `CliError` (issue #80). No field — an older server, or a failure with no class worth
+ * naming — falls through to exactly the previous behaviour.
+ */
 function describeStatus(status, body, url) {
     const detail = body?.error ? `: ${body.error}` : '';
     if (status === 401) {
@@ -44,6 +58,12 @@ function describeStatus(status, body, url) {
     // The server sends the intended exit code (usage 2 / env 3) in the body; fall
     // back on the HTTP class when it didn't.
     const exitCode = body?.exitCode ?? (status === 400 || status === 404 || status === 413 ? 2 : 3);
+    if (body?.errorKind) {
+        // The server's own message, NOT the `verikun server error 500 at <url>` wrapper: this is
+        // a device error that happens to have travelled, and it reads (and matches) the same as
+        // the local one. The same shape /v1/exec's 200-with-descriptor path already produces.
+        return (0, rpc_1.rebuildError)({ kind: body.errorKind, name: body.errorKind, message: body.error, exitCode });
+    }
     return new errors_1.CliError(`verikun server error ${status} at ${url}${detail}`, exitCode);
 }
 async function readBody(res) {

package/dist/cli.js

@@ -596,13 +596,16 @@ function cmdUi(ctx) {
     (0, output_1.out)((0, args_1.flagBool)(ctx.flags, 'tree') ? (0, format_1.formatTree)(els) : (0, format_1.formatCompact)(els));
     return 0;
 }
+/** A barrier clause joined onto a message that had no full stop of its own — and nothing at
+ *  all when there is no clause, so the ordinary message stays byte-identical. */
+const withStop = (clause) => (clause ? `.${clause}` : '');
 async function cmdFind(ctx) {
     const sel = buildSelector(ctx, ctx.positionals[0]);
-    const { matches, tier } = await (0, auto_wait_1.matchWaiting)(ctx, sel, { all: (0, args_1.flagBool)(ctx.flags, 'all') });
+    const { matches, tier, barrier } = await (0, auto_wait_1.matchWaiting)(ctx, sel, { all: (0, args_1.flagBool)(ctx.flags, 'all') });
     if ((0, args_1.flagBool)(ctx.flags, 'json'))
         (0, output_1.json)(matches.map(format_1.toJsonShape));
     else if (!matches.length)
-        (0, output_1.err)(`no match for '${sel.raw}'`);
+        (0, output_1.err)(`no match for '${sel.raw}'${withStop(barrier.clause())}`);
     else {
         (0, output_1.out)((0, format_1.formatCompact)(matches));
         if (tier && tier !== 'exact')
@@ -907,8 +910,9 @@ async function cmdWait(ctx) {
     const timeout = (0, args_1.flagNum)(ctx.flags, 'timeout') ?? 10000;
     const interval = (0, args_1.flagNum)(ctx.flags, 'interval') ?? 400;
     const deadline = Date.now() + timeout;
+    const barrier = new auto_wait_1.BarrierTally(ctx);
     while (Date.now() < deadline) {
-        const { matches, tier } = (0, selector_1.matchElements)((0, auto_wait_1.readForPoll)(ctx), sel);
+        const { matches, tier } = (0, selector_1.matchElements)(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel);
         if (gone ? matches.length === 0 : matches.length > 0) {
             ctx.record?.note({ selector: sel, tier, element: matches[0], message: gone ? 'gone' : `${matches.length} match(es)` });
             if (gone)
@@ -919,8 +923,10 @@ async function cmdWait(ctx) {
         }
         await (0, wait_1.sleep)(interval);
     }
-    ctx.record?.note({ selector: sel, message: `timeout after ${timeout}ms${gone ? ' (still present)' : ' (never appeared)'}` });
-    (0, output_1.err)(`timeout after ${timeout}ms waiting for '${sel.raw}'${gone ? ' to disappear' : ''}`);
+    // A barrier can only explain a miss: with --gone the element is absent and the wait passed above.
+    const why = withStop(gone ? '' : barrier.clause());
+    ctx.record?.note({ selector: sel, message: `timeout after ${timeout}ms${gone ? ' (still present)' : ' (never appeared)'}${why}` });
+    (0, output_1.err)(`timeout after ${timeout}ms waiting for '${sel.raw}'${gone ? ' to disappear' : ''}${why}`);
     return 1;
 }
 /** Evaluate an assertion against a single captured snapshot. */
@@ -966,12 +972,16 @@ async function cmdAssert(ctx) {
     // Auto-wait subsumes the common "wait then assert": poll until the assertion
     // passes or the window elapses. `--gone` therefore waits for disappearance.
     const deadline = Date.now() + (0, auto_wait_1.waitWindowMs)(ctx.flags);
-    let result = evalAssert((0, auto_wait_1.readForPoll)(ctx), sel, ctx.flags);
+    const barrier = new auto_wait_1.BarrierTally(ctx);
+    let result = evalAssert(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel, ctx.flags);
     while (!result.pass && Date.now() < deadline) {
         await (0, wait_1.sleep)((0, auto_wait_1.pollStep)(ctx.flags, deadline));
-        result = evalAssert((0, auto_wait_1.readForPoll)(ctx), sel, ctx.flags);
+        result = evalAssert(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel, ctx.flags);
     }
-    const { pass, reason, matches } = result;
+    const { pass, matches } = result;
+    // Only a "not found" can be explained by a barrier: `--gone` passed if the tree was
+    // barrier-only, and a text mismatch found the element.
+    const reason = !pass && result.reason === 'not found' ? `not found${withStop(barrier.clause())}` : result.reason;
     ctx.record?.note({ selector: sel, element: matches[0], message: `${pass ? 'PASS' : 'FAIL'} — ${reason}` });
     if ((0, args_1.flagBool)(ctx.flags, 'json'))
         (0, output_1.json)({ pass, selector: sel.raw, reason, matches: matches.map(format_1.toJsonShape) });

package/dist/commands/auto-wait.js

@@ -10,6 +10,7 @@
 // waiting lives here. The rules a new selector-resolving command must follow are in
 // CLAUDE.md, "Selector auto-wait".
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BarrierTally = void 0;
 exports.parseDuration = parseDuration;
 exports.waitWindowMs = waitWindowMs;
 exports.waitNote = waitNote;
@@ -19,6 +20,7 @@ exports.matchWaiting = matchWaiting;
 exports.resolveOneWaiting = resolveOneWaiting;
 const args_1 = require("../args");
 const errors_1 = require("../errors");
+const barrier_1 = require("../ui/barrier");
 const selector_1 = require("../ui/selector");
 const wait_1 = require("../wait");
 const DEFAULT_WAIT_MS = 5000;
@@ -73,16 +75,51 @@ function readForPoll(ctx, opts = {}) {
         throw e;
     }
 }
+/**
+ * Keeps track of whether the snapshots a poll loop read were barrier-only trees (see
+ * ui/barrier.ts), so the failure at the end can say so instead of "never appeared".
+ *
+ * A sheet's barrier that outlives the whole wait is the report behind issue #131: the
+ * step waited 30s on a painted sheet and the message sent the reader looking for a missing
+ * identifier in app code. Naming the barrier is the cheap half of that fix, and it belongs
+ * to whoever owns the wait — this is the only layer that saw every read.
+ */
+class BarrierTally {
+    ctx;
+    reads = 0;
+    barrierReads = 0;
+    last = null;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Record one snapshot. Returns it, so it can wrap a read in place. */
+    note(els) {
+        this.reads++;
+        this.last = (0, barrier_1.modalBarrierOnly)(els, this.ctx.driver.viewport());
+        if (this.last)
+            this.barrierReads++;
+        return els;
+    }
+    /** The clause to append to a miss, or '' when the last read was not barrier-only. */
+    clause() {
+        if (!this.last)
+            return '';
+        return (0, barrier_1.barrierClause)(this.last, this.barrierReads === this.reads);
+    }
+}
+exports.BarrierTally = BarrierTally;
 /**
  * matchElements with auto-wait: re-capture + re-match until at least one element
- * matches or the window elapses. Returns the final result either way (empty on miss).
+ * matches or the window elapses. Returns the final result either way (empty on miss),
+ * plus the barrier tally so the caller's miss message can name a barrier.
  */
 async function matchWaiting(ctx, sel, opts = {}) {
     const deadline = Date.now() + waitWindowMs(ctx.flags);
+    const barrier = new BarrierTally(ctx);
     for (;;) {
-        const res = (0, selector_1.matchElements)(readForPoll(ctx, opts), sel);
+        const res = (0, selector_1.matchElements)(barrier.note(readForPoll(ctx, opts)), sel);
         if (res.matches.length > 0 || Date.now() >= deadline)
-            return res;
+            return { ...res, barrier };
         await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
     }
 }
@@ -95,8 +132,9 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
     const windowMs = waitWindowMs(ctx.flags);
     const start = Date.now();
     const deadline = start + windowMs;
+    const barrier = new BarrierTally(ctx);
     for (;;) {
-        const els = readForPoll(ctx, opts);
+        const els = barrier.note(readForPoll(ctx, opts));
         if ((0, selector_1.matchElements)(els, sel).matches.length >= 1) {
             const { element, tier } = (0, selector_1.resolveOne)(els, sel); // 1 → resolved; >1 → throws ambiguity
             // The snapshot rides along: scroll-into-view needs the scrollable containers
@@ -106,7 +144,7 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
         }
         if (Date.now() >= deadline) {
             const waited = windowMs > 0 ? ` after ${(windowMs / 1000).toFixed(1)}s` : '';
-            throw new errors_1.SelectorNotFoundError(`No element matched selector '${sel.raw}'${waited}. Run \`verikun ui\` to inspect the current screen.`);
+            throw new errors_1.SelectorNotFoundError(`No element matched selector '${sel.raw}'${waited}.${barrier.clause()} Run \`verikun ui\` to inspect the current screen.`);
         }
         await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
     }

package/dist/companion/manager.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Companion = void 0;
 exports.nullRootAction = nullRootAction;
+exports.barrierRecycleDue = barrierRecycleDue;
 exports.companionJarPath = companionJarPath;
 exports.companionEnabled = companionEnabled;
 exports.releaseCompanionOn = releaseCompanionOn;
@@ -102,6 +103,24 @@ function nullRootAction(runMs, alreadyRecycled) {
         return 'fallback';
     return runMs < WEDGE_AFTER_MS ? 'propagate' : 'recycle';
 }
+/**
+ * Is a run of barrier-only reads (see ui/barrier.ts) long enough to suspect the CONNECTION
+ * rather than the screen?
+ *
+ * Same clock as a null root, for the same reason: a held UiAutomation connection is the one
+ * component that can keep serving a stale answer after the screen has moved on, and a
+ * release + acquire is the one thing measured to clear it (a null root for a live window
+ * on a Pixel 3a; a foreign window, issue #79). A barrier that outlives the sheet's own
+ * entrance by this much is either a modal the test should have dismissed — in which case a
+ * recycle costs ~1s once — or that same staleness wearing a different hierarchy. The report
+ * behind this (issue #131) waited 30s on a painted sheet; it did not reproduce here, so the
+ * recycle is the cheap insurance and not a measured cure.
+ *
+ * Once per run: the recycle IS the test, so a second one would only prove it again.
+ */
+function barrierRecycleDue(runMs, alreadyRecycled) {
+    return !alreadyRecycled && runMs >= WEDGE_AFTER_MS;
+}
 /** The packaged companion jar: shipped in the npm tarball, and present in a source checkout
  *  once `tools/verikun-companion/build.sh` has run. Absent means "no companion available",
  *  which is a normal state, not an error. */
@@ -290,10 +309,12 @@ class Companion {
             case 'propagate':
                 break;
         }
-        throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch).');
+        throw new errors_1.NoWindowError();
     }
     /** Hand the UiAutomation connection back and take it again. The one thing measured to clear
-     *  a stale connection — it is what the stock path's releaseCompanionOn() does by accident. */
+     *  a stale connection — it is what the stock path's releaseCompanionOn() does by accident.
+     *  Public for ONE caller besides onNullRoot: the driver's barrier settle (see
+     *  `AdbDriver.settleBarrier`), which has the same suspicion for a different hierarchy. */
     recycleConnection() {
         try {
             (0, protocol_1.requestSync)(this.port, 'release', 5000);

package/dist/drivers/adb.js

@@ -27,6 +27,7 @@ const manager_1 = require("../companion/manager");
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
+const barrier_1 = require("../ui/barrier");
 const viewport_1 = require("../ui/viewport");
 const settings_1 = require("../device/settings");
 const claims_1 = require("../device/claims");
@@ -188,6 +189,16 @@ const DUMP_PATHS = ['/sdcard/window_dump.xml', '/data/local/tmp/window_dump.xml'
  *  costs the same ~10ms as `dump 0`). The stock path pays a full second for it only
  *  because a freshly connected bridge has no history of quiet to draw on. */
 const COMPANION_IDLE_MS = 1000;
+/**
+ * How long to let a barrier-only tree settle before reading it again (see `settleBarrier`).
+ *
+ * MEASURED on a physical SM-A415F and a motorola one, companion on: the read issued the
+ * moment `tap @vk_sheet_open` returned (+0.3-0.45s) held only the barrier, and the next one
+ * held the sheet. The re-read itself absorbs the rest — the companion's idle wait sees the
+ * entrance's accessibility events and returns once they stop (~1.05s against ~0.2s for a
+ * quiet screen) — so this only has to outlast the gap between the two.
+ */
+const BARRIER_SETTLE_MS = 300;
 /** What both capture paths say when there is no window to read: AOSP's DumpCommand prints
  *  "ERROR: null root node returned by UiTestAutomationBridge." and writes no file, and the
  *  companion reports the same condition from getRootInActiveWindow(). Transient — see
@@ -592,6 +603,9 @@ class AdbDriver {
     lastRotation;
     /** undefined = not built yet, null = opted out. See companionOrNull(). */
     companion;
+    /** When the current run of barrier-only reads began (0 = not in one). See settleBarrier. */
+    barrierSince = 0;
+    barrierRecycled = false;
     /** Until when `ensureAwake` may skip its probe. See AWAKE_FRESH_MS. */
     awakeUntil = 0;
     constructor(serial) {
@@ -686,13 +700,13 @@ class AdbDriver {
         const els = this.captureElements(opts);
         // Second net, for a device that is awake but still behind the keyguard.
         if (!this.keyguardReason(els))
-            return els;
+            return this.settleBarrier(els, opts);
         (0, output_1.err)('note: the app is not on screen — trying to dismiss the keyguard');
         this.wakeAndUnlock();
         const after = this.captureElements(opts);
         const reason = this.keyguardReason(after);
         if (!reason)
-            return after;
+            return this.settleBarrier(after, opts);
         const lock = this.readLockKind();
         const what = reason === 'locked'
             ? `The device is on the lock screen${lock === 'unknown' ? '' : ` (${lock})`}`
@@ -742,6 +756,53 @@ class AdbDriver {
             return 'display-off';
         return null;
     }
+    /**
+     * Third net: a tree that holds only a modal barrier is read again before it is believed.
+     *
+     * A sheet's barrier blocks the route beneath it from the accessibility tree, and this
+     * dumper skips the sheet's own contents until they are on screen — so for the length of
+     * the entrance the hierarchy is the barrier and nothing else, exit 0 (issue #131; the
+     * shape is ui/barrier.ts). It lives HERE, not in the pollers, because every consumer
+     * meets it: the auto-wait, the `vk ai` guards, `/v1/elements`, the failure-evidence
+     * capture. One re-read after BARRIER_SETTLE_MS clears the measured case; a run that
+     * outlives that gets the companion connection recycled ONCE (barrierRecycleDue) and is
+     * then returned whatever it holds — a modal the test should have dismissed is still a
+     * modal, and the caller's message names it. Checked on the INTERESTING nodes even under
+     * `--all`, so the two views of one screen cannot disagree about whether it has settled.
+     */
+    settleBarrier(els, opts) {
+        const barrier = this.barrierIn(els, opts);
+        if (!barrier) {
+            this.barrierSince = 0;
+            this.barrierRecycled = false;
+            return els;
+        }
+        if (!this.barrierSince)
+            this.barrierSince = Date.now();
+        (0, exec_1.sleepSync)(BARRIER_SETTLE_MS);
+        let settled = this.captureElements(opts);
+        if (!this.barrierIn(settled, opts))
+            return this.settleBarrier(settled, opts); // resets the run
+        if ((0, manager_1.barrierRecycleDue)(Date.now() - this.barrierSince, this.barrierRecycled)) {
+            this.barrierRecycled = true;
+            // ONLY when the companion is what served these reads. A recycle re-acquires the
+            // device's single UiAutomation connection, and a companion that had stood down would
+            // then SIGKILL the very stock dump the next read depends on.
+            const companion = this.hierarchySource().path === 'companion' ? this.companionOrNull() : null;
+            if (companion?.recycleConnection()) {
+                (0, output_1.err)(`[verikun] the hierarchy has held only a modal barrier (${(0, barrier_1.describeBarrier)(barrier)}) for a while; ` +
+                    'recycling the companion connection in case it is stale');
+                settled = this.captureElements(opts);
+                if (!this.barrierIn(settled, opts))
+                    return this.settleBarrier(settled, opts);
+            }
+        }
+        return settled;
+    }
+    /** The barrier when `els` is a barrier-only tree, else null. */
+    barrierIn(els, opts) {
+        return (0, barrier_1.modalBarrierOnly)(opts.all ? els.filter(android_parse_1.isInteresting) : els, this.viewport());
+    }
     /** `dumpsys trust` reports `deviceLocked=1` while the keyguard is up. `null` = could not tell,
      *  which never triggers a refusal — an unreadable probe must not block a legitimate read. */
     deviceLocked() {
@@ -835,8 +896,7 @@ class AdbDriver {
             // nothing on it yet. Retrying it here just spends someone else's wait budget three
             // times as fast; hand it up to whoever knows how long they are willing to wait.
             if (NULL_ROOT.test(lastErr)) {
-                throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch). ' +
-                    'Retry, or use a command that waits (`vk wait`, or any selector lookup).');
+                throw new errors_1.NoWindowError();
             }
             if (attempt === 0) {
                 // A sleeping display is the other documented cause of a failed read. `ensureAwake` ran

package/dist/errors.js

@@ -6,7 +6,7 @@
 //   2  usage error, ambiguous selector, or a device another job is driving (caller must refine)
 //   3  environment error (adb/simctl missing, no usable device, dump failed)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousSelectorError = exports.NoWindowError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
+exports.AmbiguousSelectorError = exports.NO_WINDOW_MESSAGE = exports.NoWindowError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
 exports.isEnvError = isEnvError;
 class CliError extends Error {
     exitCode;
@@ -67,12 +67,25 @@ exports.SelectorNotFoundError = SelectorNotFoundError;
  * The retry belongs to the caller that knows how long it is willing to wait.
  */
 class NoWindowError extends CliError {
-    constructor(message) {
+    constructor(message = exports.NO_WINDOW_MESSAGE) {
         super(message, 3);
         this.name = 'NoWindowError';
     }
 }
 exports.NoWindowError = NoWindowError;
+/**
+ * The one wording for "there is no window", shared by both Android read paths so they cannot
+ * drift — the companion and the stock dumper are reporting the same device state.
+ *
+ * It names THREE causes, not two. `getRootInActiveWindow()` also returns null while the app's
+ * main thread is busy mid-transition, and issue #80 was reported against a build that listed
+ * only force-stop and mid-launch: the reporter went looking at app startup for a screen that
+ * was drawn, present, and merely busy (device logs showed 32-121 dropped frames in the same
+ * window). It also no longer ends in "use a command that waits" — every caller that hit this
+ * in the wild was already doing exactly that.
+ */
+exports.NO_WINDOW_MESSAGE = 'No window to read: the app has no drawn window right now — force-stopped, mid-launch, or ' +
+    'its main thread is busy mid-transition. This normally clears within a few seconds.';
 /** Selector matched >1 element. Exit 2. Carries the candidates so the agent runner
  *  can ask the model to disambiguate (a heal trigger) instead of aborting. */
 class AmbiguousSelectorError extends CliError {

package/dist/server-http.js

@@ -14,14 +14,21 @@ class HttpError extends Error {
     status;
     exitCode;
     deviceChanged;
+    errorKind;
     constructor(status, message, exitCode = status === 400 || status === 404 || status === 413 ? 2 : 3, 
     /** Set when this request moved the server's device before failing — the client
      *  needs to know the ground shifted even though the answer is an error. */
-    deviceChanged) {
+    deviceChanged, 
+    /** The CLASS of the error this wraps, when it wraps one. Wrapping a driver error in an
+     *  HttpError is how the identity used to be lost: only `.message` and `.exitCode` were
+     *  copied across, so a `NoWindowError` reached the client as a bare `CliError`. Carry it
+     *  here and the outer catch can put it on the wire. */
+    errorKind) {
         super(message);
         this.status = status;
         this.exitCode = exitCode;
         this.deviceChanged = deviceChanged;
+        this.errorKind = errorKind;
         this.name = 'HttpError';
     }
 }

package/dist/server.js

@@ -1053,7 +1053,10 @@ function buildServer(config) {
             const deviceChanged = await considerFailover(e, 'read', handle);
             if (!deviceChanged)
                 throw e;
-            throw new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, deviceChanged);
+            // describeError, not just .message/.exitCode: this wrap is on the path a mid-launch
+            // NoWindowError takes, and the engine's guard tells "still drawing" from "box broken"
+            // by class alone (issue #80).
+            throw new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, deviceChanged, (0, rpc_1.describeError)(e).kind);
         }
     }
     async function handleLogs(handle, req, res) {
@@ -1629,9 +1632,16 @@ function buildServer(config) {
             // back why a suite degraded.
             failure = ` — ${(0, server_http_1.firstLine)(mapped.message)}`;
             if (!res.headersSent) {
+                // The class comes from the ORIGINAL throw, never from `mapped`: the HttpError
+                // mapping above keeps only message + exit code, which is precisely how a
+                // NoWindowError used to reach the client as an anonymous CliError (issue #80). An
+                // HttpError raised by the server itself (auth, validation, a lock) has no wrapped
+                // class and simply omits the field, which older clients already tolerate.
+                const errorKind = e instanceof server_http_1.HttpError ? e.errorKind : (0, rpc_1.describeError)(e).kind;
                 const body = {
                     error: mapped.message,
                     exitCode: mapped.exitCode,
+                    ...(errorKind ? { errorKind } : {}),
                     ...(mapped.deviceChanged ? { deviceChanged: mapped.deviceChanged } : {}),
                 };
                 (0, server_http_1.sendJson)(res, mapped.status, body);

package/dist/ui/barrier.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_BARRIER_COVERAGE = void 0;
+exports.isInert = isInert;
+exports.isBarrierShaped = isBarrierShaped;
+exports.modalBarrierOnly = modalBarrierOnly;
+exports.describeBarrier = describeBarrier;
+exports.barrierClause = barrierClause;
+// A modal barrier — the scrim a sheet or dialog puts in front of everything else — and
+// the one tree shape it produces that reads as "empty" while the screen is plainly full.
+//
+// Pure functions over Element[] (no device, no time, no platform), like ui/selector.ts,
+// so the shape is unit-testable and the two consumers cannot drift: the Android driver
+// re-reads a tree of this shape before trusting it, and the selector commands name the
+// barrier in their failure message when it outlived their wait.
+//
+// WHY THIS EXISTS (issue #131). Flutter's ModalBarrier is a BlockSemantics around one
+// full-screen Semantics(label:, onTap:) node. BlockSemantics DROPS every node painted
+// before it — the whole route underneath — on purpose: a screen reader must not reach
+// content the user cannot touch. The sheet's own content joins the tree only once it is
+// on screen, and Android's dumper skips what it considers invisible, so for the length
+// of the entrance the hierarchy is the barrier and nothing else. MEASURED on a physical
+// SM-A415F and a motorola one: the first read after `tap @vk_sheet_open` returned
+// (+0.3-0.45s) held `android:id/content` and `Scrim`; the next read held the sheet.
+//
+// Detection is STRUCTURAL, never by label. The label is `MaterialLocalizations.scrimLabel`
+// — "Scrim" in English and Swedish, "Gitter" in German, "Fond" in French, "スクリム" in
+// Japanese — and `modalBarrierDismissLabel` ("Dismiss") for a dialog, so a label match
+// would work on exactly the devices it was written on. What is stable is the shape: a
+// clickable, id-less node with no text, large enough to be the thing you tap to dismiss.
+/**
+ * How much of the viewport a lone tap target must cover to read as a barrier.
+ *
+ * Loose on purpose. A sheet's barrier is CLIPPED to the area above the sheet once the
+ * sheet is up (measured: 1620 of 2184 view px on the SM-A415F, ~68% of the 2400px display),
+ * and a dialog's covers everything — so "covers the screen" would miss the sheet. What the
+ * floor has to exclude is a lone ordinary button on an otherwise empty screen, which is a
+ * few percent at most.
+ */
+exports.MIN_BARRIER_COVERAGE = 0.4;
+/** Input classes `isInteresting()` keeps even when empty — a field is never inert. */
+const INPUT_CLASS = /EditText|AutoComplete|TextField|Edit$/;
+/**
+ * Nothing to read and nothing to act on: a layout container, with or without an id.
+ *
+ * An id alone does not make a node readable — `android:id/content` is in every Android
+ * dump and says nothing about the app — which is why this looks at content and actions
+ * and ignores `id`. The report behind this listed "thirteen unlabelled containers".
+ */
+function isInert(el) {
+    if (el.text.trim() || el.desc.trim())
+        return false;
+    if (el.clickable || el.longClickable || el.checkable || el.scrollable)
+        return false;
+    return !INPUT_CLASS.test(el.class);
+}
+/**
+ * Is this node shaped like a modal barrier: clickable (it dismisses on tap), no id (a
+ * framework node, not one the app named), no text, and — when the viewport is known —
+ * covering at least MIN_BARRIER_COVERAGE of it? A label is allowed but not required: an
+ * app can raise a barrier with no `semanticsLabel`, and the node then has an action and
+ * nothing else.
+ *
+ * With no viewport (the driver could not read a screen size) the size check is skipped:
+ * a wrong "barrier" costs one extra read, a wrong "not a barrier" costs the false miss
+ * this exists to prevent.
+ */
+function isBarrierShaped(el, vp) {
+    if (!el.clickable || el.id || el.text.trim())
+        return false;
+    if (!vp || vp.width <= 0 || vp.height <= 0)
+        return true;
+    const w = Math.max(0, Math.min(el.bounds.x2, vp.width) - Math.max(el.bounds.x1, 0));
+    const h = Math.max(0, Math.min(el.bounds.y2, vp.height) - Math.max(el.bounds.y1, 0));
+    return (w * h) / (vp.width * vp.height) >= exports.MIN_BARRIER_COVERAGE;
+}
+/**
+ * The barrier, when the tree holds one or more barrier-shaped nodes and nothing else that
+ * could be read or acted on; null for any other tree — including an EMPTY one, which is a
+ * different signal (a bad read) and is handled where it is met.
+ *
+ * Two barriers at once are one shape, not two: a dialog raised over a sheet has the
+ * dialog's barrier and the sheet's in the same tree mid-transition.
+ */
+function modalBarrierOnly(els, vp) {
+    let barrier = null;
+    for (const el of els) {
+        if (isInert(el))
+            continue;
+        if (!isBarrierShaped(el, vp))
+            return null;
+        barrier ??= el;
+    }
+    return barrier;
+}
+/** How a message names the barrier: its label when it has one, else its shape. */
+function describeBarrier(el) {
+    const label = el.desc.trim();
+    return label ? `desc=${JSON.stringify(label)}` : 'an unlabelled full-screen tap target';
+}
+/**
+ * The clause a selector failure appends when the barrier was what it kept reading.
+ *
+ * `every` says whether EVERY read during the wait was barrier-only (the report's case:
+ * "waited 30s, never appeared") or only the last one (a sheet or dialog opened late in
+ * the window). Both are worth naming; they send the reader to different places.
+ */
+function barrierClause(barrier, every) {
+    const when = every ? 'for the whole wait' : 'on the last read';
+    return (` The hierarchy held only a modal barrier (${describeBarrier(barrier)}) ${when}: a sheet ` +
+        'or dialog is up and nothing inside it has reached the accessibility tree. Dismiss it, ' +
+        'or wait for its contents, before this step.');
+}

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.26.0';
+exports.VERSION = '0.26.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "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",