verikun 0.23.0 → 0.25.0

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

@@ -93,6 +93,8 @@ usually don't need a `wait` before an action — `vk tap @next` already polls fo
 - `vk swipe up|down|left|right [--on <selector>] [--distance f] [--duration ms]`
 - `vk swipe --from x,y --to x,y [--duration ms]`
 - `vk key <name|code>`  ·  `vk back`  ·  `vk home`  ·  `vk enter`
+  Named keys include `sleep` and `wakeup`. `power` is a **toggle**, so use `sleep`/`wakeup`
+  when you mean a direction.
 - `vk screenshot [--out path] [--more] [--max px] [--full]` — saves a PNG (default
   `./.verikun/screen.png`) and prints the path; then read that file to *see* the
   screen. It's **downscaled to a 700px longest edge by default** to save tokens
@@ -118,11 +120,15 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
 
   | key | values | Android | iOS simulator |
   |---|---|---|---|
+  | `animations` | `on\|off` | yes | **no** — nothing disables UIKit animation |
   | `airplane` | `on\|off` | yes | **no** — a simulator has no radio |
   | `dark` | `on\|off` | yes | yes |
   | `font-scale` | `0.5`–`3.0`, `default` | yes | yes (nearest Dynamic Type category) |
   | `rotation` | `portrait\|landscape\|portrait-reverse\|landscape-reverse\|auto` | yes | **no** |
   | `stay-awake` | `on\|off` | yes | no-op (simulators don't sleep) |
+  | `screen-timeout` | `30s` / `10m` / ms / `max` | yes | no-op (simulators don't sleep) |
+  | `dnd` | `on\|off` | yes | **no** — Focus is not scriptable |
+  | `doze` | `on\|off` | yes | no-op (no Doze equivalent) |
 
   Set several at once: `vk device set dark=on font-scale=1.3`. Each change is **verified by
   reading it back**, so success means it actually landed — these device commands silently
@@ -134,6 +140,14 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
   even when the flow *fails* — but a bare `vk device set` from a shell stays applied until
   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`.
+
+  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
+  never land on a personal phone that happened to be plugged in. Do not run it on a device
+  the user did not point you at. `vk doctor` reports whether a device is prepared.
+
   Two traps:
   - **`airplane=off` brings the radio back, not the internet.** Follow it with
     `vk assert <selector> --wait 10s`, never an immediate `tap`.
@@ -378,7 +392,12 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   failure).
 - **Bounded by default:** the run aborts if the estimated spend crosses **$3**
   (`--max-cost-usd`) or the wall-clock passes **15m** (`--timeout`), so a runaway
-  compile/repair loop can't spend or hang without limit.
+  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
+  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/>.
 - Exit `0` pass · `1` a step failed (or the budget/timeout was hit) · `2` usage · `3` environment
   (e.g. the model's API key — `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` — unset, or the `codex` /
   `cursor-agent` CLI missing / not logged in for `--model codex-cli` / `cursor-cli`).
@@ -433,6 +452,19 @@ device; `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).
 
+**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 until it is power-cycled;
+`vk devices --server <url>` shows why in its `NOTE` column.
+
 ## The device is missing or wedged
 
 ```sh
@@ -510,8 +542,13 @@ owns the redaction and the review-first flow.
 
 ## Gotchas
 
-- **Disable animations once** for reliable dumps: `vk doctor --fix`. Live
-  animations can make `vk ui` flaky (it already retries 3×).
+- **Prepare the device once** for reliable dumps: `vk device prep` (a physical device
+  needs `--device <serial>`). Live animations can make `vk ui` flaky (it already retries 3×).
+- **A slept device returns the LOCK SCREEN, not an error.** The dump succeeds and hands
+  back `com.android.systemui` — so selectors miss for a reason unrelated to the app.
+  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.
 - **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;
@@ -549,13 +586,15 @@ owns the redaction and the review-first flow.
   use `xcrun simctl`. Run `vk doctor --ios` to check the toolchain. Caveats: `clear`
   is unsupported (no per-app reset), `current` is `(unknown)`, device logs are
   simulator-only, and `device set` is partial — `dark`/`font-scale` work on a simulator
-  while `airplane`/`rotation` do not exist there at all (`vk device caps --ios`). iOS
+  while `animations`/`airplane`/`rotation`/`dnd` do not exist there at all, and
+  `stay-awake`/`screen-timeout`/`doze` are no-ops (`vk device caps --ios`). That makes
+  `vk device prep` effectively Android-only: on iOS it applies nothing and says so. iOS
   accessibility ids are often unset, so prefer `text:`/`desc:` selectors there.
 
 ## Worked example — verify a login flow
 
 ```sh
-vk doctor --fix                              # deterministic UI
+vk doctor                                    # is the device set up? (read-only)
 vk launch com.example.app
 vk text @email_input "user@example.com"      # field lookup auto-waits up to 5s
 vk text @password_input "hunter2" --enter

package/CHANGELOG.md

@@ -6,6 +6,49 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-08-21
+
+### Added
+- **`vk server`**: moves to another attached healthy device when the bound one fails; only a pinned `--device` disables it. ([#99])
+- **`vk server --allow-failover[=serials]`**: re-enable failover on a pinned server, and bound where it may go.
+- **`vk server --no-failover`** / **`VERIKUN_NO_FAILOVER`**: disable failover outright.
+- **`/v1/health`**: adds `failoverEnabled` and `quarantined`, so a client can see which devices the server ruled out.
+- **`vk install --server`**: reports the device the build landed on when it differs from the one bound.
+
+### Changed
+- **`vk install --server`**: a device-attributable install failure retries on another healthy device.
+- **`/v1/exec`**, **`/v1/elements`**: report `deviceChanged` when the server moved device; the failing step is never replayed.
+
+### Fixed
+- **`/v1/logs`**: served the startup device's logs after a rebind instead of the bound device's.
+- **`/v1/health`**: reported the startup device's read path after a rebind.
+
+[#99]: https://github.com/ddikman/verikun/issues/99
+
+## [0.24.0] - 2026-08-20
+
+### Added
+- **`vk device prep`**: prepare a test device once — animations off, display awake, DND on, doze off.
+- **`vk device prep --revert`**: restore what prep changed, from a host-global snapshot that outlives the run.
+- **`vk device prep --dry-run`**: show each knob's current and target value without writing.
+- **`vk device set animations|screen-timeout|dnd|doze`**: four new keys, each verified by readback.
+- **`vk key sleep` / `vk key wakeup`**: directional screen keys; `power` remains a toggle.
+- **`vk doctor`**: reports whether the device is prepared and whether it has a screen lock.
+- **Docs site**: a `Cost & budget` reference page — when a model is called, the estimate formula,
+  and that `--max-cost-usd` is per test, not per suite. ([#94])
+
+### Changed
+- **`vk doctor --fix`**: now an alias for `device prep`, so a physical device must be named with `--device`.
+- **`vk doctor`**: read-only without `--fix`; it no longer writes animation scales directly.
+- **`vk batch|ai|suite`**: put a prepped device to sleep on teardown; `--no-sleep-when-idle` opts out.
+
+### Fixed
+- **UI reads**: a locked device returned the lock screen as a successful dump; now woken, unlocked if
+  the lock is a swipe, else exit `3` naming it.
+- **Docs site**: the `vk ai` cost line was printed in a format the CLI never emitted.
+
+[#94]: https://github.com/ddikman/verikun/issues/94
+
 ## [0.23.0] - 2026-08-17
 
 ### Added
@@ -30,6 +73,10 @@ All notable changes to this project are documented here. The format is based on
 - **`vk devices start --server`**: releases the device lock when it finishes, instead of `409`ing
   the run it just booted the device for.
 
+### Changed
+- **Docs site**: content column widened to 60rem, giving the reference tables more room on
+  large screens.
+
 ## [0.22.2] - 2026-08-17
 
 ### Changed

package/README.md

@@ -6,9 +6,9 @@
 
 - **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.
+- **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.
+- **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.
 
 ```
 $ vk ui
@@ -37,7 +37,8 @@ The package also carries the agent [`SKILL.md`](.claude/skills/verikun/SKILL.md)
 ## Quick start
 
 ```sh
-vk doctor --fix                 # check adb/device; disable animations for stable dumps
+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 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

@@ -89,8 +89,14 @@ class RemoteTransport {
         finally {
             clearTimeout(timer);
         }
-        if (!res.ok)
-            throw describeStatus(res.status, await readBody(res), url);
+        if (!res.ok) {
+            const body = await readBody(res);
+            // Before throwing: a failing request may still have moved the device, and that is
+            // exactly the case a caller must not miss (an exhausted install, a dead-device read).
+            if (body?.deviceChanged)
+                this.opts.onDeviceChange?.(body.deviceChanged);
+            throw describeStatus(res.status, body, url);
+        }
         const parsed = await readBody(res);
         if (parsed === null)
             throw new errors_1.CliError(`verikun server at ${url} returned a non-JSON response`, 3);
@@ -157,6 +163,9 @@ function createRemoteBackend(opts, health) {
         const res = await t.postJson('/v1/exec', req, EXEC_TIMEOUT_MS);
         if (record && res.step)
             opts.onStep?.(res.step, decodeArtifacts(res.artifacts), res.logStart);
+        // A failing step is a 200, so this is the ordinary path for a mid-run device death.
+        if (res.deviceChanged)
+            opts.onDeviceChange?.(res.deviceChanged);
         return { code: res.code, error: res.error ? (0, rpc_1.rebuildError)(res.error) : undefined };
     };
     return {
@@ -184,11 +193,15 @@ function createRemoteBackend(opts, health) {
                 throw new errors_1.CliError(`install: cannot read '${appPath}' (${e.message})`, 2);
             }
             const sha256 = (0, node_crypto_1.createHash)('sha256').update(buf).digest('hex');
-            await t.request('POST', '/v1/install', buf, INSTALL_TIMEOUT_MS, {
+            const res = await t.request('POST', '/v1/install', buf, INSTALL_TIMEOUT_MS, {
                 'content-type': 'application/octet-stream',
                 'x-verikun-ext': ext,
                 'x-verikun-sha256': sha256,
             });
+            // Install is the one operation the server replays elsewhere, so a move here means
+            // the build DID land — on a different device than the one we started with.
+            if (res.deviceChanged)
+                opts.onDeviceChange?.(res.deviceChanged);
         },
         async reset(appId) {
             // Between-test housekeeping (vk suite): the step is deliberately NOT spliced

package/dist/args.js

@@ -44,12 +44,17 @@ const BOOLEAN = new Set([
     'no-restart',
     'no-logs',
     'wipe',
+    'dry-run',
+    'revert',
+    'no-sleep-when-idle',
     'allow-install',
     'allow-unsafe-anonymous',
-    // NOT here on purpose: 'allow-device-control' and 'ensure-device' are tri-state
-    // (absent / on / on-with-a-value), and the inline `--flag=value` branch is checked
-    // BEFORE this set — listing them would make `--allow-device-control=Pixel_6` parse
-    // fine but `--ensure-device Pixel_6` silently become a boolean plus a positional.
+    'no-failover',
+    // NOT here on purpose: 'allow-device-control', 'allow-failover' and 'ensure-device'
+    // are tri-state (absent / on / on-with-a-value), and the inline `--flag=value` branch
+    // is checked BEFORE this set — listing them would make `--allow-device-control=Pixel_6`
+    // parse fine but `--ensure-device Pixel_6` silently become a boolean plus a positional.
+    // Its opposite, 'no-failover', never takes a value, so it DOES belong above.
     // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.
     // `enabled` was missing here until 0.15.0, and the omission was not cosmetic: a
     // non-BOOLEAN flag swallows the next token, so `vk tap --enabled @submit` bound