verikun 0.25.1 → 0.26.0-rc.2

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

@@ -397,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/>.
@@ -437,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
@@ -450,11 +473,23 @@ 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 install` on Android replaces a build signed by a different key.** Android refuses
+to update a package across signing keys, so verikun removes the installed build and
+installs again, warning on stderr that **that build's app data is gone**. A same-key
+install still keeps its data. Do not treat the warning as a failure — it is how the
+install succeeded. iOS has no equivalent recovery; the install just fails there.
+
+`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:
 
@@ -466,7 +501,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
 

package/CHANGELOG.md

@@ -6,6 +6,62 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Changed
+- **`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.
+
+[#96]: https://github.com/ddikman/verikun/issues/96
+
+## [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

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

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;