verikun 0.26.0 → 0.26.1

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

@@ -390,7 +390,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,24 @@ 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
+- **`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/companion/manager.js

@@ -290,7 +290,7 @@ 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. */

package/dist/drivers/adb.js

@@ -835,8 +835,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/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.1';

package/package.json

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