verikun 0.21.1 → 0.23.0

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

@@ -17,7 +17,9 @@ description: >-
   directory of natural-language tests as a gated suite with `vk suite <dir>`
   (overview report + non-zero exit on failure — the CI gate). A remote device is
   reachable via `--server <url>` (ai/suite/install) against a `vk server` running
-  next to it. iOS (--ios): full parity via idb (tap/type/swipe/`ui` +
+  next to it. If no device is available, or one has gone flaky, start or restart it
+  with `vk devices start|stop|restart <name>` (`vk devices --all` lists what is
+  startable). iOS (--ios): full parity via idb (tap/type/swipe/`ui` +
   screenshot/launch/stop), on simulators and devices; install idb and see
   `vk doctor --ios`.
 ---
@@ -427,9 +429,29 @@ 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. To expose a device from THIS machine: `vk server --allow-install`
+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).
 
+## The device is missing or wedged
+
+```sh
+vk devices --all                    # what's attached AND what could be started
+vk devices start Pixel_6_API_34     # boot it; prints the serial when drivable
+vk devices restart Pixel_6_API_34   # a live device gone flaky
+```
+
+Exit codes tell you whether to retry: **1** = unknown name, or the boot timed out
+(the device is still starting — retrying often works, and it is left running).
+**2** = ambiguous name (simulator names repeat across iOS runtimes — pass the UDID
+from `vk devices --all`), or the target is a physical device (never power-cycled).
+**3** = the toolchain is missing (set `VERIKUN_EMULATOR` to the SDK's `emulator`
+binary) — retrying will not help.
+
+`start` is idempotent, so it is safe to call when unsure. Add `--ensure-device` to
+`vk ai` / `vk suite` / `vk install` to boot once before the first step instead. Both
+work against a remote server (`--server <url>`) when it runs `--allow-device-control`.
+
 ## Test runs & reports
 
 Every action is **recorded into a test run** — one auto-starts on your first
@@ -471,18 +493,18 @@ identifier memory described above. Set `VERIKUN_NO_RUN=1` to disable recording.
 When **verikun itself** — not the app, not your selector — is the friction (a model heal on
 a *cached* replay: `[ai] plan cache hit` + a repair, or `"cached": true` with
 `modelRepairs > 0` in `--json`; a `drifted, not repaired` give-up; or a recurring gotcha in
-vk's own operation), use the **`suggest-verikun-improvement`** skill. It drafts a light,
+vk's own operation), use the **`suggest-verikun-improvement`** skill. It writes a light,
 TL;DR-first suggestion — **redacted** of every app-under-test specific (package, on-screen
-text, selector values, test prose, logs) — for you to **review before it's submitted** to
-`ddikman/verikun`. Don't hand-roll the issue: that skill owns the redaction and the
-draft-first flow.
+text, selector values, test prose, logs) — to a **local file for you to read and edit**, and
+files nothing to `ddikman/verikun` until you say so. Don't hand-roll the issue: that skill
+owns the redaction and the review-first flow.
 
 ## Exit codes — rely on these for control flow
 
 - `0` success / found / assertion passed
 - `1` not found / assertion failed / wait timeout
 - `2` usage error **or ambiguous selector** (refine it or add `--index N`)
-- `3` environment error (no device, adb/idb missing, hierarchy dump failed) — for
+- `3` environment error (no usable device, adb/idb missing, hierarchy dump failed) — for
   `ai`/`suite`/`install`/`server` the toolchain is verified up front, so this arrives
   immediately with an install hint rather than mid-flow
 
@@ -498,7 +520,12 @@ draft-first flow.
 - **`vk device set` from a plain shell stays applied.** Inside `batch`/`ai`/`suite` it is
   restored automatically even if the flow dies, but a one-off `vk device set airplane=on`
   is yours to `vk device reset` — don't strand someone's phone offline.
-- **One device auto-resolves.** Multiple → pass `-d <serial>` or set `VERIKUN_DEVICE`.
+- **The device picks itself, and won't collide with another agent.** With several attached,
+  `vk` takes one no other job is driving and notes it on stderr. Exit `2` means every device
+  is genuinely busy (the message names each holder) — pass `-d <serial>`, wait, or
+  `vk device release <serial>` if that job is gone. `vk devices` shows who holds what.
+  Naming a busy device with `-d` is refused, on purpose: two jobs on one phone corrupt both
+  runs, and it surfaces as a bogus assertion failure. `VERIKUN_NO_CLAIM=1` opts out entirely.
 - **`vk text` opens the keyboard.** Use `--enter` to submit, or `vk back` to
   dismiss it before re-inspecting (it can cover elements).
 - **Unicode/emoji** may not type via `adb input text` (an Android limitation);

package/CHANGELOG.md

@@ -6,6 +6,74 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-08-17
+
+### Added
+- **`npm run docs` / `docs:install` / `docs:build`**: run the documentation site from the repo
+  root; README covers the local setup.
+- **`vk devices start|stop|restart <name>`**: boot, shut down or power-cycle an Android AVD or iOS
+  simulator. `start` is idempotent and waits until the device is actually drivable.
+- **`vk devices --all`**: also lists startable (not-yet-booted) AVDs and simulators.
+- **`vk devices start|restart --wipe`**: erase the device's data first (`-wipe-data` / `simctl erase`).
+- **`vk server --allow-device-control[=names]`**: let a client restart/stop the server's device;
+  `=names` also permits starting those targets. The server may then listen with no device bound.
+- **`--ensure-device[=name]`** on `ai`/`suite`/`install`: boot a device once before the first step.
+- **`VERIKUN_EMULATOR`**: path to the SDK `emulator` binary when it is not on `PATH`.
+
+### Changed
+- **`vk devices`**: gains `KIND` and `NAME` columns, so an emulator shows the AVD name you pass to
+  `stop`/`restart`.
+- **`/v1/health`**: `serial` may now be `null`; adds `deviceControlEnabled`, `deviceNamingEnabled`
+  and `deviceState` for feature detection.
+
+### Fixed
+- **`vk devices start --server`**: releases the device lock when it finishes, instead of `409`ing
+  the run it just booted the device for.
+
+## [0.22.2] - 2026-08-17
+
+### Changed
+- **`suggest-verikun-improvement`**: the draft is written to `.context/` for review; nothing is
+  filed until you say so. ([#66])
+- **Improvement reports**: `Shape of the fix` becomes a short `Proposed fix` — a few bullets,
+  not a spec. ([#66])
+
+[#66]: https://github.com/ddikman/verikun/issues/66
+
+## [0.22.1] - 2026-08-15
+
+### Added
+- **The Flutter fixture raises a real system permission dialog** (`@vk_permission`, Android
+  only), so [#79] reproduces on demand.
+
+### Fixed
+- **Hierarchy reads now see a window another app opens on top** — a runtime-permission dialog is
+  no longer invisible to the companion. ([#79])
+
+[#79]: https://github.com/ddikman/verikun/issues/79
+
+## [0.22.0] - 2026-08-15
+
+### Added
+- **Device claims**: `vk` now picks a device no other job is driving; a busy one is refused
+  with exit `2`. Writes `~/.verikun/devices/`; `VERIKUN_NO_CLAIM=1` opts out. ([#49])
+- **`vk devices`**: a `USED BY` column names the job holding each device; `--json` gains
+  `claim`. ([#49])
+- **`vk device release [serial]`**: hands a device back without waiting for its claim to go
+  stale. ([#49])
+
+### Changed
+- **Several attached devices no longer exits `2`** — a free one is auto-selected. Pass
+  `--device` to pin it, as before. ([#49])
+- **Changelog entries are now one line each**, per the new `changelog-entry` skill — root cause,
+  benchmarks and rationale move to the PR body and `docs/`.
+
+### Fixed
+- **Failure evidence**: a step that could not resolve a device printed its error three times;
+  capture is now skipped when there is no screen to photograph.
+
+[#49]: https://github.com/ddikman/verikun/issues/49
+
 ## [0.21.1] - 2026-08-13
 
 ### Fixed
@@ -403,22 +471,6 @@ All notable changes to this project are documented here. The format is based on
   e2e fixture app, 74 files of Gradle/Xcode/PNG that no end user installing the CLI should download.
 - `publish.yml` also verifies `package-lock.json` is in sync with `package.json`'s version. `npm ci`
   does not catch this — it errors only on dependency drift, never on the root `version` field.
-
-### Fixed
-- **The Claude Code plugin no longer ships the contributor-only `create-pr` skill.** The manifest
-  pointed `skills` at the container `.claude/skills/`, and that field only ever *adds* to the scan,
-  so every skill in it reached end users — costing roughly 260 always-on tokens per session for one
-  they cannot use. It now lists the two user-facing skills explicitly. Naming a single skill would
-  not do: that drops `suggest-verikun-improvement`, which the main skill hands off to.
-
-- **`CHANGELOG.md` is now included in the published npm package.** `package.json`'s `"files"` is an
-  allowlist, and npm force-includes only `package.json`, `README`, `LICENSE`, the `main` file and the
-  `bin` file(s) — a changelog is *not* on that list (npm 5/6 included one; modern npm does not).
-  Every release up to 0.19.0 therefore published without a changelog, and did so silently: the
-  publish succeeded, CI was green, and nothing anywhere reported the omission.
-  `tests/package-files.test.ts` now guards the allowlist, including against an entry whose path no
-  longer exists.
-
 ## [0.19.0] - 2026-08-08
 
 ### Added

package/README.md

@@ -62,16 +62,16 @@ There is also no need for an MCP here: verikun runs locally with all its depende
 |---|---|
 | **Getting started** | [Installation](https://ddikman.github.io/verikun/getting-started/installation/) · [Your first test](https://ddikman.github.io/verikun/getting-started/your-first-test/) · [Using it from an AI agent](https://ddikman.github.io/verikun/getting-started/using-from-an-agent/) |
 | **Guides** | [Writing test cases](https://ddikman.github.io/verikun/guides/writing-test-cases/) · [Natural-language tests](https://ddikman.github.io/verikun/guides/natural-language-tests/) · [Suites](https://ddikman.github.io/verikun/guides/suites/) · [Remote devices & CI](https://ddikman.github.io/verikun/guides/remote-devices-and-ci/) · [iOS setup](https://ddikman.github.io/verikun/guides/ios-setup/) · [Platform support](https://ddikman.github.io/verikun/guides/platform-support/) · [Troubleshooting](https://ddikman.github.io/verikun/guides/troubleshooting/) |
-| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
+| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
 | **Internals** | [Architecture](https://ddikman.github.io/verikun/internals/architecture/) · [Core principles](https://ddikman.github.io/verikun/internals/core-principles/) · [Plan IR & the replay engine](https://ddikman.github.io/verikun/internals/plan-ir-and-engine/) · [Contracts](https://ddikman.github.io/verikun/internals/contracts/) · [Contributing](https://ddikman.github.io/verikun/internals/contributing/) |
 
-**Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error or ambiguous selector · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/).
+**Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error, ambiguous selector, or a device another job is driving · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/). Parallel agents share a host-level [device claim](https://ddikman.github.io/verikun/reference/device-claims/) so two jobs do not silently land on the same phone.
 
 ## Feedback — help improve verikun
 
 verikun improves from the rough edges people hit while driving it. When verikun *itself* is the friction — a step that heals on every cached replay (an unstable compiled selector, often a label-only control with no resource-id), a repair "give-up", or a gotcha in its own operation — that's worth an issue at [github.com/ddikman/verikun/issues](https://github.com/ddikman/verikun/issues).
 
-Driving verikun with an AI agent + the [skill](.claude/skills/verikun/SKILL.md)? It hands off to the **`suggest-verikun-improvement`** skill, which drafts a short, TL;DR-first suggestion, **reviews it with you before anything is submitted**, and **redacts every app-under-test specific** (package, on-screen text, selector values, test prose, logs) so no client code or logic can leak.
+Driving verikun with an AI agent + the [skill](.claude/skills/verikun/SKILL.md)? It hands off to the **`suggest-verikun-improvement`** skill, which writes a short, TL;DR-first suggestion **to a local file for you to read and edit**, **files nothing until you say so**, and **redacts every app-under-test specific** (package, on-screen text, selector values, test prose, logs) so no client code or logic can leak.
 
 ## Contributing
 
@@ -84,6 +84,16 @@ npm link         # optional: put `verikun` and `vk` on your PATH
 
 Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing — is in [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
 
+To work on the [documentation site](https://ddikman.github.io/verikun/), which is an Astro Starlight project in `docs/` with its own dependencies (so `npm install` above does not cover it):
+
+```sh
+npm run docs:install   # once — installs the site's dependencies (needs Node >= 22.12)
+npm run docs           # dev server with live reload at http://localhost:4321/verikun/
+npm run docs:build     # production build; fails on a dead internal link
+```
+
+Open **http://localhost:4321/verikun/** — the site is served under a base path, so bare `localhost:4321` is a 404. Astro needs **Node ≥ 22.12** while the CLI supports Node ≥ 18, so `nvm use 22` first if your shell's Node is older.
+
 ## License
 
 [MIT](LICENSE)

package/dist/agent/remote.js

@@ -10,6 +10,8 @@
 // local one. Recording stays a caller concern: this module never touches ./.verikun.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pingServer = pingServer;
+exports.remoteDeviceOp = remoteDeviceOp;
+exports.remoteDeviceList = remoteDeviceList;
 exports.createRemoteBackend = createRemoteBackend;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -22,6 +24,11 @@ const HEALTH_TIMEOUT_MS = 10_000;
 const ELEMENTS_TIMEOUT_MS = 60_000;
 const EXEC_TIMEOUT_MS = 10 * 60_000;
 const INSTALL_TIMEOUT_MS = 15 * 60_000;
+const DEVICE_LIST_TIMEOUT_MS = 30_000;
+// Above the server's own 4-minute boot ceiling, so the SERVER reports why a boot
+// timed out rather than the client aborting into a generic "timed out after 300s".
+const DEVICE_START_TIMEOUT_MS = 5 * 60_000;
+const DEVICE_STOP_TIMEOUT_MS = 60_000;
 const trimUrl = (url) => url.replace(/\/+$/, '');
 function describeStatus(status, body, url) {
     const detail = body?.error ? `: ${body.error}` : '';
@@ -31,6 +38,9 @@ function describeStatus(status, body, url) {
     if (status === 409) {
         return new errors_1.CliError(`verikun server device is busy (409)${detail || ' — another run holds the device; retry when it finishes'}.`, 3);
     }
+    if (status === 503) {
+        return new errors_1.CliError(`verikun server has no device attached (503)${detail}.`, 3);
+    }
     // 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);
@@ -89,6 +99,15 @@ class RemoteTransport {
     postJson(path, payload, timeoutMs) {
         return this.request('POST', path, JSON.stringify(payload), timeoutMs, { 'content-type': 'application/json' });
     }
+    /** Best-effort: give the device lock back. A lock we fail to release ages out. */
+    async release() {
+        try {
+            await this.postJson('/v1/release', {}, HEALTH_TIMEOUT_MS);
+        }
+        catch {
+            /* the idle takeover covers it */
+        }
+    }
 }
 /** GET /v1/health — the `--server` preflight. Reachability, the server's platform +
  *  serial (which become the run's context), and — when a key is supplied — an auth
@@ -101,6 +120,31 @@ async function pingServer(opts) {
     }
     return health;
 }
+/**
+ * POST /v1/devices/{start,restart,stop}. Standalone beside pingServer rather than on
+ * the ExecBackend seam: that seam is the engine's DEVICE WORK (exec/getElements/
+ * install/reset), and adding administration to it would oblige the local backend to
+ * implement a verb nothing in the engine ever calls.
+ */
+async function remoteDeviceOp(opts, op, body = {}) {
+    const t = new RemoteTransport(opts);
+    const timeout = op === 'stop' ? DEVICE_STOP_TIMEOUT_MS : DEVICE_START_TIMEOUT_MS;
+    try {
+        return await t.postJson(`/v1/devices/${op}`, body, timeout);
+    }
+    finally {
+        // This is a one-shot administrative call under its own run token, not a run —
+        // so hand the device lock straight back. Without this, `vk devices start
+        // --server` (and the --ensure-device preflight, which uses its own token) would
+        // 409 the very run it just booted the device for, until the 5-minute idle takeover.
+        await t.release();
+    }
+}
+/** GET /v1/devices — what the server can see and what it will boot on request. */
+async function remoteDeviceList(opts) {
+    const t = new RemoteTransport(opts);
+    return t.request('GET', '/v1/devices', undefined, DEVICE_LIST_TIMEOUT_MS);
+}
 function decodeArtifacts(encoded) {
     const out = {};
     for (const [rel, b64] of Object.entries(encoded ?? {}))

package/dist/args.js

@@ -43,8 +43,13 @@ const BOOLEAN = new Set([
     'no-cache',
     'no-restart',
     'no-logs',
+    'wipe',
     '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.
     // 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