verikun 0.25.0 → 0.26.0-rc.1

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

@@ -141,7 +141,10 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
   you reset it, so don't leave someone's phone in airplane mode.
 
 - `vk device prep [--dry-run] [--revert]` — set a **test** device up once, stickily:
-  `animations=off stay-awake=on screen-timeout=max dnd=on doze=off`.
+  `animations=off stay-awake=off screen-timeout=1m dnd=on doze=off`. The display then sleeps by
+  itself a minute after the last command and is woken by the next one; `--no-sleep-when-idle`
+  keeps it lit for good (`stay-awake=on screen-timeout=max`), which is what a device with a
+  PIN/pattern lock needs, since verikun can only clear a *swipe* lock.
 
   Unlike `device set`, prep **survives the run** and is undone only by `--revert`. A physical
   device must be named (`--device <serial>`) — that requirement is deliberate, so prep can
@@ -394,7 +397,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   (`--max-cost-usd`) or the wall-clock passes **15m** (`--timeout`), so a runaway
   compile/repair loop can't spend or hang without limit. The ceiling is **per test, not per
   suite** — `vk suite` gives each `*.md` its own fresh budget, so 20 tests at the default can
-  reach $60; there is no suite-wide cap, so lower the per-test figure instead. A model is only
+  reach $60; lower the per-test figure, or set `vk suite --max-suite-cost-usd <n>` for an
+  aggregate cap (off by default; stops the suite at exit `1`). A model is only
   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/>.
@@ -434,6 +438,28 @@ vk suite tests/ --app com.example.app        # reset app data between tests
   are **not** counted as failures. So `3` = fix the machine and rerun; `1` = a real
   regression to investigate.
 
+### Across several devices
+
+Suite time is the **sum** of its tests on one device. Given a pool, the suite becomes a
+work queue instead — every device takes the next test as it frees up:
+
+```sh
+vk suite tests/ --app com.example.app --devices emulator-5554,emulator-5556
+vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # a pooled server
+vk suite tests/ --app com.example.app --servers http://a:8391,http://b:8391
+```
+
+- A `vk server --devices all` holds several devices behind one URL; a plain `--server`
+  suite reads its capacity and sizes itself. Nothing else about the command changes.
+- **File order stops sequencing tests** — they must be independent. Ordering becomes
+  longest-first, learned from the previous run's `index.json`.
+- Each row records **which device ran it**, and the manifest splits
+  `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.
+- `--ensure-device` is refused with `--devices` — start the pool with `vk devices start`.
+
 ## Drive a remote device (--server)
 
 If the device is attached to another machine running `vk server`, point
@@ -447,11 +473,17 @@ 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 another run holds the
-device; `503` means the server has no device attached — boot one (below). To
-expose a device from THIS machine: `vk server --allow-install`
+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
+(below). To expose a device from THIS machine: `vk server --allow-install`
 (add `--bind <addr>` to leave loopback; auth key auto-generates if unset).
 
+`vk server --devices all` (or `all-android` / `all-ios` / a serial list) serves a **pool**
+from one address. Each run leases one device for its whole life, so a run's steps and
+repairs always land on the same phone. `vk install --server` then installs on every device;
+`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:
 
@@ -463,7 +495,9 @@ device that failed and is now on another one. What that means depends on the lin
   flow again from the top if you want it on B.
 
 The server rules the bad device out until it is power-cycled;
-`vk devices --server <url>` shows why in its `NOTE` column.
+`vk devices --server <url>` shows why in its `NOTE` column. On a pool the replacement
+joins the pool, so capacity holds — and the last device is never shed, so its own error
+keeps reaching you rather than a bare "no device attached".
 
 ## The device is missing or wedged
 
@@ -549,6 +583,8 @@ owns the redaction and the review-first flow.
   verikun detects this, wakes the device and clears a *swipe* lock automatically; on a
   PIN/pattern/password it exits **3** naming the lock rather than returning that dump.
   Tell the user to remove the lock in Settings > Security — verikun never asks for a PIN.
+  Taps, swipes, typing and screenshots wake it the same way: a prepped display sleeps after a
+  minute idle, and an injected tap on a sleeping screen would otherwise do nothing and exit `0`.
 - **Ambiguous selector → exit 2**, never a random tap. `vk` prints the candidate
   matches; add `--index N` or use a more specific selector.
 - **Indexes are per-snapshot.** `vk tap 3` taps `[3]` from the *latest* dump;

package/CHANGELOG.md

@@ -6,6 +6,70 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Changed
+- **`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.
+
+## [0.26.0] - 2026-08-24
+
+### Added
+- **`vk suite --devices a,b` / `--servers u1,u2`**: run tests across a device pool, next free
+  device takes the next test. One merged report. ([#39])
+- **`vk suite --server`**: sizes itself automatically from a pooled server's capacity — one URL,
+  one secret, unchanged CI line. ([#39])
+- **`vk server --devices all | all-android | all-ios | a,b`**: serve several devices from one
+  address, one lease per run. ([#39])
+- **`vk suite --devices all | all-android | all-ios`**: same spelling as `vk server --devices`. ([#39])
+- **`vk suite --concurrency n`**: cap how many devices run at once, below the pool's size. ([#39])
+- **`vk suite --max-suite-cost-usd n`**: stop the suite once total model spend crosses it
+  (exit `1`). Off by default. ([#39])
+- **`vk ai --reset-app <id>`**: clear (iOS: force-stop) the app before the first step, on the run's
+  own device.
+- **`VERIKUN_LANE`**: moves the active run to `./.verikun/run-<lane>/` so concurrent tests in one
+  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.
+
+### Changed
+- **Suite manifest**: adds `totals.wallClockMs`, `concurrency` and a per-test `device`.
+  `totals.durationMs` is unchanged but is now labelled device time. `schemaVersion` stays `1`.
+- **`vk install --server`** installs on **every** device of a pooled server, not one.
+- **Release workflow**: a prerelease tag takes its GitHub release notes from the version it is a candidate for (`v1.0.0-rc.1` → `## [1.0.0]`).
+- **`vk suite --devices`**: file order no longer sequences tests, and longest-first ordering is
+  taken from the previous run's manifest. A serial suite is unchanged. ([#39])
+- **`vk server --devices`**: `/v1/devices/{start,restart,stop}` answer `403` on a pool — there is
+  no single device to act on. `--ensure-device` is likewise refused with `--devices`.
+- **`vk suite --devices` with `--server`** is a usage error (exit `2`): it would have tested local
+  devices and reported green.
+- **`vk suite --servers u1,u2`**: opens one lane per device each server has, not one per URL.
+- **`vk server`**: a lease is broken only when another run needs that device, so a paused run
+  keeps its own phone.
+- **`--json` errors** carry `errorKind`, the error's class, so a caller need not match on message
+  text.
+- **`vk server --devices all`** and failover prefer virtual devices, so neither enlists an attached
+  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])
+
+### 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.
+
+[#39]: https://github.com/ddikman/verikun/issues/39
+
+## [0.25.1] - 2026-08-21
+
+### Changed
+- **`vk device prep`**: gives the display a 1-minute timeout instead of keeping it lit forever; `--no-sleep-when-idle` keeps the old behaviour. ([#101])
+- **`vk batch|ai|suite`**: no longer switch a prepped device's display off at teardown — it now sleeps by itself.
+- **`vk tap|type|key|swipe|screenshot`**: wake a sleeping display first; an injected tap on a dozing screen did nothing and exited `0`.
+
+### Added
+- **`vk device prep`**: warns when a device that will now sleep is behind a PIN/pattern lock.
+
+[#101]: https://github.com/ddikman/verikun/issues/101
+
 ## [0.25.0] - 2026-08-21
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@
 - **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. [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; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it, and moves to another attached device if that one goes bad.
+- **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 swaps out any that goes bad.
 
 ```
 $ vk ui
@@ -38,7 +38,7 @@ The package also carries the agent [`SKILL.md`](.claude/skills/verikun/SKILL.md)
 
 ```sh
 vk doctor                       # check adb/device (read-only — never changes anything)
-vk device prep --device <id>    # set a TEST device up once: animations off, stays awake
+vk device prep --device <id>    # set a TEST device up once: animations off, sane display timeout
 vk devices                      # list attached devices
 vk ui                           # semantic snapshot of the current screen
 vk tap @login_button            # tap by resource-id

package/dist/agent/remote.js

@@ -170,6 +170,13 @@ function createRemoteBackend(opts, health) {
     };
     return {
         exec: (command, positionals, flags) => execRaw({ command, positionals, flags }, true),
+        async lease() {
+            // Feature-detect on a FIELD, never on the version: `capacity` and /v1/lease landed
+            // together, and a client cannot otherwise tell "old server" from "new server".
+            if (health.capacity === undefined)
+                return null;
+            return t.postJson('/v1/lease', {}, HEALTH_TIMEOUT_MS);
+        },
         async getElements() {
             const res = await t.postJson('/v1/elements', {}, ELEMENTS_TIMEOUT_MS);
             return res.elements;