verikun 0.29.1 → 0.32.0-rc.1

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

@@ -93,7 +93,9 @@ usually don't need a `wait` before an action — `vk tap @next` already polls fo
 `@next` to appear.
 
 - `vk tap <selector|index>`  ·  `vk tap --at x,y`
-- `vk text <selector> "the text" [--clear] [--enter]` — focus the field, then type
+- `vk text <selector> "the text" [--clear] [--enter]` — focus the field, then type. On
+  Android it reads the field back and exits `1` if the value did not land (after one
+  retype); a field that reformats or rejects input needs `vk tap` + `vk type` instead
 - `vk type "text" [--enter]` — type into the already-focused field
 - `vk swipe up|down|left|right [--on <selector>] [--distance f] [--duration ms]`
 - `vk swipe --from x,y --to x,y [--duration ms]`
@@ -437,6 +439,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
 - **`3` also means the device toolchain is broken**, checked *before* anything is compiled
   (missing `adb`/`idb`, no device, an ambiguous target) and again if it breaks mid-run. Treat
   it as "fix the machine", never as a failing test — the message carries the install hint.
+  Exception: over `--server`, a `--json` result with `evicted: true` means the server's device
+  left the pool mid-run — nothing is broken; run the test again.
 
 ## Run a suite of tests (vk suite)
 
@@ -487,7 +491,10 @@ vk suite tests/ --app com.example.app --servers http://a:8391,http://b:8391
   `totals.wallClockMs` (how long the gate took) from `totals.durationMs` (device-seconds).
 - `--concurrency N` caps how many run at once — more devices on one host can thrash it.
   `--max-suite-cost-usd N` stops the suite once total model spend crosses it (exit `1`).
-- A device that breaks retires; its tests move to the others. Exit `3` only when all are gone.
+- Local devices bench and rejoin after 45-second probes; server health owns remote membership. Typed loss reruns free on another device at most twice.
+- Over `--server`, a lane with no free device waits instead of failing tests, and a test whose
+  device left the pool re-runs without spending a retry. With no device for any lane the suite
+  stops after `VERIKUN_SUITE_DEVICE_WAIT_MIN` (default 10) with exit `3` and a `notRun` list.
 - `--ensure-device` is refused with `--devices` — start the pool with `vk devices start`.
 
 ## Drive a remote device (--server)
@@ -503,8 +510,9 @@ vk install ./app-debug.apk --server "$VERIKUN_SERVER"   # server needs --allow-i
 vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"
 ```
 
-A wrong URL/key fails fast with exit 3; `409` means every device is already
-leased by another run; `503` means the server has no device attached — boot one
+A wrong URL/key fails fast with exit 3. New clients wait in the server FIFO; a tagged
+`409` means the run lost its device and must restart. `503` after the wait means no device
+became available — boot one
 (below). To expose a device from THIS machine: `vk server --allow-install`
 (add `--bind <addr>` to leave loopback; auth key auto-generates if unset).
 
@@ -525,22 +533,17 @@ repairs always land on the same phone. `vk install --server` then installs on ev
 `vk devices start|restart|stop --server` is refused (`403`) — a pool has no single device
 to act on.
 
-**If you see `[verikun] server moved device: A → B` on stderr**, the server left a
-device that failed and is now on another one. What that means depends on the line:
-
-- `— retried there` (installs only): the build DID land, on **B**. Anything you go on
-  to do with an explicit serial must name B, not A.
-- `— this step failed on the old device; the next runs on the new one`: your step
-  failed on **A**. Do NOT re-run it expecting a different answer for the same reason —
-  the failure was real on A, and B has none of the state your flow built up. Start the
-  flow again from the top if you want it on B.
-
-The server rules the bad device out; `vk devices --server <url>` shows why in its `NOTE`
-column, and a pooled server re-adopts a device that comes back within a minute. A device
-that is still attached keeps its place and is simply dealt last, so its own error keeps
-reaching you rather than a bare "no device attached". A device that is **gone** leaves the
-pool — so `capacity` can drop mid-job, and an install can come back `exit 0` having skipped
-it. That is a success: nothing can be dealt a device running the previous build.
+Remote peers must support held leases and device supervision; upgrade them together.
+Compilation holds no lease. A heartbeat thread keeps the execution lease alive during
+synchronous model repair. Closing the socket or 30 seconds without bytes ends it and
+restores device settings before the next run. Every server, including capacity one,
+readmits wanted devices with boot/build checks before dealing. `--no-failover` disables
+spare recruitment, not readmission. `VERIKUN_NO_DEVICE_WATCH=1` disables supervision.
+
+`vk ai --json` exposes `outcome`; only lost-device gets free reruns. Env failures use normal
+retries. A remote suite checks installedSha between tests and refuses a changed build.
+A single `--server` accepts `--ensure-device`, once in the parent. Install waits for holders,
+returns successful devices plus skipped targets, and keeps stale builds out of dealing.
 
 ## The device is missing or wedged
 

package/CHANGELOG.md

@@ -6,6 +6,65 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.32.0-rc.1] - 2026-10-03
+
+### Added
+- **Docs site** links unfurl with a social card image built from the illustration.
+
+### Changed
+- **Server diagrams**: explain device reservations, test reruns and recovery in plain language.
+- **`vk server`**: fork one executor per device; confirmed failures kill its process group, including blocked adb/idb children.
+- **`vk server`**: supervise device health and readmit every pool; typed loss reruns free. Disable supervision with `VERIKUN_NO_DEVICE_WATCH`.
+- **Remote leases**: acquire after compilation; heartbeat holds, FIFO admission, and lease-end setting restoration release abandoned clients.
+- **Remote installs**: gate dealing by build SHA; return after first-success grace while failed targets catch up.
+- **`vk suite`**: use lanes at every remote capacity, bench local failures, and preserve archives with explicit JSON outcomes.
+- **Docs site and README** show the new verikun logo and an animated illustration, with light and
+  dark variants.
+- **Docs site** primary color is now black, off-white in dark mode.
+
+### Fixed
+- **Docs site** favicon no longer 404s; it shows the logo.
+- **Android actions**: surface device-shell failures and retry safe transport loss once; failed liveness confirmation opens a circuit breaker.
+- **Remote deadlines**: use native HTTP timers and keep draining executors out of dealing; any nonempty `VERIKUN_NO_ADB_RECYCLE` disables restart.
+
+### Removed
+- **Remote clients and servers**: upgrade both to versions supporting held leases and server-owned device health.
+- **Remote leases**: remove no-hold acquisition, implicit execution leases, five-minute takeover, and support for peers without holds and supervision.
+- **Remote RPC**: remove `evicted` and `deviceChanged` response fields; typed errors identify device loss.
+- **Suite children**: remove verdict inference for JSON without `outcome`; same-build results must supply it.
+
+## [0.31.0] - 2026-09-27
+
+### Fixed
+- **`vk text`** no longer re-taps a field that already has focus, which let SwiftKey drop the whole
+  value while `text` exited `0`. ([#151])
+
+### Changed
+- **`vk text` on Android** reads the field back, retypes once, and exits `1` if the value is still
+  missing; use `tap` + `type` for fields that reformat input. ([#151])
+
+[#151]: https://github.com/ddikman/verikun/issues/151
+
+## [0.30.0] - 2026-09-26
+
+### Fixed
+- **`vk suite --server`** waits for a free device instead of failing tests that never got one, and
+  a waiting lane resumes when the pool recovers. ([#147])
+
+### Added
+- **`vk suite --server`** re-runs a test whose device left the pool mid-run without spending a
+  retry, up to twice; needs the matching `vk server`. ([#147])
+- **`VERIKUN_SUITE_DEVICE_WAIT_MIN`** (default `10`) caps how long a pooled suite waits when no lane
+  gets a device, busy pools included, then exits `3`; `0` fails fast. ([#147])
+
+### Changed
+- **`--json` errors** name a refused `vk server` lease `NoFreeDeviceError` and an evicted run
+  `RunEvictedError` in `errorKind`; exit codes are unchanged. ([#147])
+- **`vk ai --json`** reports a run whose device left the pool as an environment abort with
+  `evicted: true` and its report, instead of a bare error. ([#147])
+
+[#147]: https://github.com/ddikman/verikun/issues/147
+
 ## [0.29.1] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -1,9 +1,23 @@
 # verikun
 
-> **Agent-driven, natural-language mobile tests — during agent development or in CI.** Self-healing and self-improving, with cost caps and test reports.
+<table>
+<tr>
+<td width="260" align="center" valign="middle">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="docs/readme/illustration-dark.svg">
+<img src="docs/readme/illustration-light.svg" alt="verikun" width="230">
+</picture>
+</td>
+<td valign="middle">
+
+**Agent-driven, natural-language mobile tests — during agent development or in CI.** Self-healing and self-improving, with cost caps and test reports.
 
 **📚 [Documentation](https://ddikman.github.io/verikun/)** — installation, guides, full command reference, and internals.
 
+</td>
+</tr>
+</table>
+
 - **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. 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.
@@ -22,6 +36,9 @@ $ vk tap @sign_in_btn
 tapped [3] Button "Sign in" @sign_in_btn (540,1020) tap
 ```
 
+**Remote compatibility in 1.0:** upgrade the CLI and server together. Remote execution requires
+a streaming held lease and device supervision; pre-hold peers are no longer supported.
+
 ## Install
 
 Requires Node ≥ 18 and the Android platform-tools (`adb`) on your `PATH`.
@@ -57,6 +74,10 @@ verikun ships as a skill and plugin, not an MCP server, and that is deliberate.
 
 There is also no need for an MCP here: verikun runs locally with all its dependencies, and the agent calls it through the plain `vk` CLI — no shared session, data, or authentication to broker.
 
+Remote suites acquire after compilation, wait in a server FIFO, and rerun typed device loss
+without spending a retry. Held leases release on client disappearance; recovering devices
+restore settings and verify the retained build before returning to service.
+
 ## Documentation
 
 | | |

package/dist/adb-health.js

@@ -8,12 +8,8 @@
  * of CPU on the error loop. `adb kill-server && adb start-server` took it to zero and every
  * device came back in ~5s.
  *
- * WHY VERIKUN CARES, rather than leaving this to the operator: adb rot DEFEATS DEVICE
- * FAILOVER. `device/failover.ts` moves the server off a device that fails, but every
- * candidate sits behind the same host adb — so when the transport is what broke, failover
- * walks the pool retiring healthy phones for a host-side fault. That is the same polarity
- * error `ARTIFACT_RULES` exists to prevent on the install path: enumerate the thing you can
- * actually attribute, and never blame the open-ended side.
+ * A host transport failure affects every device behind adb. The server supervises
+ * correlated losses together and recycles under a host lock, excluding foreign claims.
  *
  * THE RATE IS A LEAKED-HANDLE COUNTER, which is what makes this measurable rather than
  * guessed. adb scans USB at ~1Hz and each STALE device handle throws one violation per
@@ -125,7 +121,7 @@ function describeRot(health) {
  * exactly, for the rare host running other adb work alongside the server.
  */
 function adbRecycleEnabled(platform) {
-    return platform === 'android' && process.env.VERIKUN_NO_ADB_RECYCLE !== '1';
+    return platform === 'android' && !process.env.VERIKUN_NO_ADB_RECYCLE;
 }
 /** The running adb server's pid. Undefined when there is none, or when `pgrep` is absent. */
 function adbServerPid() {

package/dist/agent/engine.js

@@ -190,7 +190,8 @@ async function runPlan(plan, deps) {
         try {
             return await deps.getElements();
         }
-        catch {
+        catch (e) {
+            (0, errors_1.rethrowIfLost)(e);
             return [];
         }
     };
@@ -247,6 +248,7 @@ async function runPlan(plan, deps) {
         // is a bad read of a live screen, not a blind one, and it is already handled below.
         let everRead = false;
         let lastErr;
+        let lostSince;
         const minLooks = settleMs > 0 ? 2 : 1;
         for (;;) {
             let els;
@@ -254,10 +256,18 @@ async function runPlan(plan, deps) {
                 try {
                     els = await deps.getElements();
                     everRead = true;
+                    lastErr = undefined;
+                    lostSince = undefined;
                 }
                 catch (e) {
+                    if (!(e instanceof errors_1.DeviceGoneError))
+                        (0, errors_1.rethrowIfLost)(e);
                     els = undefined; // transient dump failure — retry once before concluding "absent"
                     lastErr = e;
+                    if (e instanceof errors_1.DeviceGoneError)
+                        lostSince ??= Date.now();
+                    else
+                        lostSince = undefined;
                 }
                 // An EMPTY tree is not a screen, it is a bad read: a live app always has nodes, and
                 // this device routinely returns a partial/blank dump mid-transition (measured: `ui`
@@ -283,7 +293,7 @@ async function runPlan(plan, deps) {
                 // 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.TransientReadError && Date.now() < transientDeadline) {
+                if (((!everRead && lastErr instanceof errors_1.TransientReadError) || (lastErr instanceof errors_1.DeviceGoneError && Date.now() - (lostSince ?? Date.now()) < 8000)) && Date.now() < transientDeadline) {
                     await (0, wait_1.sleep)(GUARD_POLL_MS);
                     continue;
                 }
@@ -293,6 +303,8 @@ async function runPlan(plan, deps) {
                 //
                 // 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 ((0, errors_1.isDeviceLoss)(lastErr))
+                    throw lastErr;
                 if (!everRead && (0, errors_1.isEnvError)(lastErr))
                     throw new GuardBlindError(selector, lastErr);
                 return false;
@@ -366,6 +378,7 @@ async function runPlan(plan, deps) {
                 repaired = node;
             }
             catch (e) {
+                (0, errors_1.rethrowIfLost)(e);
                 const msg = e instanceof Error ? e.message : String(e);
                 return { status: 'fail', where, reason: `repair failed: ${msg}` };
             }
@@ -390,6 +403,8 @@ async function runPlan(plan, deps) {
         // sets status=passed/exitCode=0 and drops the failure evidence) so the report and
         // JUnit stay consistent with the green run, then continue. Scoped to screenshot/
         // shot — every other command's failure stays terminal.
+        if ((0, errors_1.isDeviceLoss)(outcome.error) || outcome.error instanceof errors_1.RunEvictedError)
+            (0, errors_1.rethrowIfLost)(outcome.error);
         if (isScreenshotLeaf(current)) {
             const why = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
             deps.log(`[ai] ${where}: screenshot capture failed (${why}) — continuing (best-effort review screenshot)`);

package/dist/agent/grammar.js

@@ -21,7 +21,10 @@ Each step is one of three node types:
                                   --no-restart skips the force-stop, just bringing it forward)
      stop <package>               — force-stop the app
      tap <selector>               — tap the element a selector resolves to (scrolls it into view first)
-     text <selector> <value...>   — focus a field and type value (--clear to clear first, --enter to submit)
+     text <selector> <value...>   — focus a field and type value (--clear to clear first, --enter to submit);
+                                  FAILS if the field does not then hold the value. For a field that
+                                  reformats or rejects input (masks, currency, invalid-input tests),
+                                  use tap <selector> then type <value...> instead
      type <value...>              — type into the already-focused field
      key <name> | back | home | enter
      swipe <up|down|left|right> [--on <selector>]  — scroll/swipe (up = scroll down the page)

package/dist/agent/lease-heartbeat.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_worker_threads_1 = require("node:worker_threads");
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+// Own the socket AND the timer: synchronous model repair on the main thread cannot
+// starve client-originated heartbeat bytes. Closing the process closes this hold too.
+const { url, headers, timeoutMs } = node_worker_threads_1.workerData;
+const endpoint = new URL(url);
+const send = endpoint.protocol === 'https:' ? node_https_1.request : node_http_1.request;
+let leased = false;
+let closing = false;
+const req = send(endpoint, { method: 'POST', headers }, res => {
+    let data = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+        data += chunk;
+        if (leased || !data.includes('\n'))
+            return;
+        if (res.statusCode === 200) {
+            try {
+                node_worker_threads_1.parentPort?.postMessage({ kind: 'leased', body: JSON.parse(data.split('\n')[0]) });
+                leased = true;
+            }
+            catch {
+                node_worker_threads_1.parentPort?.postMessage({ kind: 'error', message: 'invalid lease response' });
+                req.destroy();
+            }
+        }
+    });
+    res.on('end', () => {
+        if (!leased) {
+            let body;
+            try {
+                body = JSON.parse(data);
+            }
+            catch {
+                body = { error: data };
+            }
+            node_worker_threads_1.parentPort?.postMessage({ kind: 'status', status: res.statusCode, body });
+        }
+        else if (!closing)
+            node_worker_threads_1.parentPort?.postMessage({ kind: 'ended' });
+        stop();
+    });
+    res.on('error', e => { if (!closing)
+        node_worker_threads_1.parentPort?.postMessage({ kind: 'error', message: e.message }); stop(); });
+});
+const heartbeat = setInterval(() => { if (!req.destroyed)
+    req.write('.'); }, 10_000);
+const timeout = setTimeout(() => {
+    if (!leased)
+        req.destroy(new Error('lease acquisition timed out'));
+}, timeoutMs);
+function stop() { clearInterval(heartbeat); clearTimeout(timeout); req.destroy(); node_worker_threads_1.parentPort?.close(); }
+req.on('error', e => { if (!closing)
+    node_worker_threads_1.parentPort?.postMessage({ kind: 'error', message: e.message }); stop(); });
+node_worker_threads_1.parentPort?.on('message', m => { if (m === 'close') {
+    closing = true;
+    stop();
+} });
+req.flushHeaders();
+req.write('.');