verikun 0.21.0 → 0.22.1

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

@@ -275,7 +275,13 @@ to set it up, then every read after is fast. Nothing to enable.
 It holds the device's single `UiAutomation` connection while it runs, so Appium and Layout
 Inspector cannot attach. If the user needs those, tell them `VERIKUN_COMPANION=0` or
 `vk companion stop` — don't disable it pre-emptively. A failure never breaks a run: verikun
-falls back to the slower stock read on its own.
+falls back to the slower stock read on its own, and retries the fast path a minute later.
+
+Over `--server` the same applies, but the setting lives on the **server**: reads execute
+there, so `VERIKUN_COMPANION` is read in the server's environment and `vk companion` has no
+`--server` form. If a remote run feels slow (~2.4s a step on Android), don't guess — ask:
+`curl -s "$VERIKUN_SERVER/v1/health" | jq .reads` reports the read path and why. Every
+`--server` run also prints it once at start.
 
 **Remember identifiers across runs.** After a flow succeeds, save the selectors
 you found to memory — the mapping from human intent to selector, plus the screen
@@ -476,7 +482,7 @@ draft-first 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
 
@@ -492,7 +498,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,124 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [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
+- **`npm link` produced a `vk` that died with "permission denied".** `tsc` writes
+  `dist/bin/verikun.js` as 0644 and nothing set the executable bit, so the global symlink
+  `npm link` creates pointed straight at a non-executable file. It never showed up for
+  `npm install -g verikun`, because npm chmods `bin` targets itself while unpacking a
+  tarball — only a source checkout was affected, which is to say only contributors, on a
+  fresh clone, with an error that reads like a broken install rather than a missing mode bit.
+
+  A `postbuild` step (`scripts/chmod-bin.mjs`) now chmods every path named in `package.json`'s
+  `bin`, reading them from there so a renamed entry point cannot silently be left behind. It
+  is silent on success on purpose: `npm pack --json` runs the `prepare` hook and then expects
+  its own JSON on stdout, so a chatty build step is parsed as part of the pack result and
+  takes the release gate down with it.
+
+  `scripts/check-package-contents.mjs` now also asserts the packed tarball's `bin` is
+  executable, not merely present — the mode is exactly the kind of thing that regresses
+  without anyone noticing, since `npm install -g` keeps working either way.
+
+  (Shipping in this release rather than one of its own — it landed on `main` unreleased.)
+
+- **The companion no longer switches itself off for the rest of a long-lived process** — which
+  is why `vk server` got no speedup from 0.21.0 at all ([#77]). It engages there exactly as it
+  does locally; it just stopped at the first hiccup and never started again.
+
+  Measured on a Pixel 3a, one `vk server` process, the same 12-command flow each time:
+
+  | | assert avg | tap avg | flow total |
+  |---|--:|--:|--:|
+  | companion healthy | 0.33s | 0.89s | **7.7s** |
+  | companion dead — **was** | 3.35s | 3.52s | 42.6s |
+  | companion healthy again, same server — **was** | 3.33s | 3.49s | 42.5s |
+  | either case — **now** | 0.33s | 0.89s | **7.9s** |
+
+  The third row is the bug: a separate process had restarted the companion and `vk companion
+  status` read `ready app held` throughout, while the server sat next to it on the 2.4s path.
+  A stand-down was latched for the life of the process and `dims` was cached, so
+  `ensureReady()` — the only path that restarts the companion from its device note — became
+  unreachable after the first successful read. That is invisible when every command is its own
+  process (a fresh one recovers: measured 3.03s then 0.28s) and permanent in a daemon.
+
+  Three routine things reached it, all now retried after a minute rather than never:
+  the companion's **own 15-minute idle shutdown**, which any idle CI server outlives; a
+  **calibration mismatch**, which `calibrate()` already documents as usually just the screen
+  moving between two dumps; and a **released connection**, which the stock fallback causes by
+  design. Only facts that cannot change while the process runs — the device note saying
+  `unsupported`, or no jar to push — still stand it down for good.
+
+- **A stale `UiAutomation` connection no longer reports an empty screen forever.** After
+  `vk launch` force-stops and restarts an app, the companion could return "null root" for a
+  window that was plainly there — measured at 30s+ on a Pixel 3a while a stock `uiautomator
+  dump` read the same screen fine. Since a null root is deliberately *not* a stand-down (it is
+  normally the device mid-launch, and releasing the connection for it would drop every
+  `launch --clear` onto the slow path), nothing recovered it: every selector command burned its
+  full auto-wait and exited 1 on a readable screen. This one failed tests rather than slowing
+  them.
+
+  A run of null roots now escalates by duration — propagate, then recycle the connection once
+  (release + re-acquire, ~1.05s, the thing measured to clear it), then fall back to the stock
+  path if that did not help. Being slow always beats failing a selector on a screen that is
+  there. The escalation is per-process, so it recovers inside any command that auto-waits
+  (`tap`, `assert`, `text`, `find`, `wait`) and inside `vk server`; a bare single-shot `vk ui`
+  has only one read and cannot, so it still reports no window until the next such command.
+
+- **`vk server` hands the `UiAutomation` connection back on shutdown.** The companion outlives
+  the process that started it, so Ctrl-C used to leave Appium, Layout Inspector and TalkBack
+  locked out on that host for up to the full 15-minute idle window — with no obvious cause, and
+  no way to stop it from a `--server` client (`vk companion` has no `--server` form).
+
+### Added
+- **`vk server` says which read path it is using**, on startup (`[server] reads: companion
+  (ready app held)`) and as a `reads` field on `/v1/health`; a `--server` client echoes it once
+  at run start. Reads execute server-side, so this was the one end of the connection that knew
+  — and without it a companion that had silently stood down was indistinguishable from one that
+  never engaged, for a whole suite. Requested in [#77]; the field is optional, so an older
+  server simply omits it.
+- **A `--server` suite index records the server's verikun version and read path** (`server: {
+  url, verikun, reads }` in `index.json`). It previously recorded only the client's version, so
+  a remote artifact could not say which verikun actually drove the device — the first thing you
+  need to explain a suite that got slower after a server upgrade.
+
+[#77]: https://github.com/ddikman/verikun/issues/77
+
 ## [0.21.0] - 2026-08-13
 
 ### Added

package/README.md

@@ -62,10 +62,10 @@ 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
 

package/dist/cli.js

@@ -61,6 +61,7 @@ const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
 const adb_1 = require("./drivers/adb");
 const settings_1 = require("./device/settings");
+const claims_1 = require("./device/claims");
 const selector_1 = require("./ui/selector");
 const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
@@ -404,6 +405,15 @@ function cmdDevices(ctx) {
     catch (e) {
         (0, output_1.err)(`devices: iOS backend unavailable (${e.message})`);
     }
+    // Who is driving what. Read-only: listing the pool must never claim a device, which is
+    // what makes `vk devices` (and `vk doctor`) safe to run while surveying a busy host.
+    if ((0, claims_1.claimsEnabled)()) {
+        for (const d of allDevices) {
+            const claim = (0, claims_1.summarize)(d.serial);
+            if (claim)
+                d.claim = claim;
+        }
+    }
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
         (0, output_1.json)(allDevices);
         return 0;
@@ -431,6 +441,10 @@ function formatDeviceTable(devices) {
         { header: 'STATE', get: (d) => d.state },
         { header: 'MODEL', get: (d) => d.model ?? '', optional: true },
         { header: 'PRODUCT', get: (d) => d.product ?? '', optional: true },
+        // Optional like the rest, which is load-bearing twice over: nothing changes for a
+        // single-user host where no device is ever claimed, and `VERIKUN_NO_CLAIM=1` renders
+        // exactly the table it always did.
+        { header: 'USED BY', get: (d) => d.claim?.by ?? '', optional: true },
         { header: 'NOTE', get: (d) => d.note ?? '', optional: true },
     ];
     // Drop optional columns that no device populates (e.g. NOTE for an Android-only list).
@@ -493,17 +507,39 @@ async function cmdDoctor(ctx) {
         return 3;
     const devices = ctx.driver.listDevices();
     const usable = devices.filter((d) => d.state === 'device');
+    const claims = (0, claims_1.claimsEnabled)();
+    // Read-only, like `vk devices`: doctor surveys the host, it never takes a device.
+    const heldByOther = (serial) => {
+        const c = claims ? (0, claims_1.summarize)(serial) : undefined;
+        return c && !c.mine ? c : undefined;
+    };
     (0, output_1.out)(`devices: ${devices.length} attached, ${usable.length} usable`);
-    for (const d of devices)
-        (0, output_1.out)(`  ${d.serial} ${d.state}${d.model ? ` (${d.model})` : ''}`);
+    for (const d of devices) {
+        const claim = claims ? (0, claims_1.summarize)(d.serial) : undefined;
+        (0, output_1.out)(`  ${d.serial} ${d.state}${d.model ? ` (${d.model})` : ''}${claim ? `  [${claim.by}]` : ''}`);
+    }
     let ok = true;
-    if (usable.length !== 1 && !ctx.device) {
-        (0, output_1.err)(usable.length ? '  -> multiple devices: pass --device for interaction commands' : '  -> no usable device');
+    const free = usable.filter((d) => !heldByOther(d.serial));
+    if (!usable.length) {
+        (0, output_1.err)('  -> no usable device');
+        ok = false;
+    }
+    else if (!ctx.device && !free.length) {
+        // Every device is busy. Advisory-shaped but genuinely blocking, so it still fails:
+        // an interaction command run right now would exit 2, and doctor exists to say so first.
+        (0, output_1.err)('  -> every attached device is claimed by another job — `verikun devices` shows who');
         ok = false;
     }
-    if (usable.length === 1 || ctx.device) {
+    else if (!ctx.device && !claims && usable.length > 1) {
+        (0, output_1.err)('  -> multiple devices: pass --device for interaction commands');
+        ok = false;
+    }
+    // Check the device an interaction command would actually land on: the one named, else
+    // the first FREE one (which is what auto-selection picks), not merely the first attached.
+    const target = ctx.device || free[0]?.serial;
+    if (target) {
         try {
-            const serial = ctx.device || usable[0].serial;
+            const serial = target;
             const keys = ['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale'];
             const get = (k) => (0, exec_1.runText)(adb, ['-s', serial, 'shell', 'settings', 'get', 'global', k]).stdout.trim();
             const vals = keys.map(get);
@@ -979,7 +1015,7 @@ function cmdClear(ctx) {
 //    of applying dark mode and then dying — a half-applied device is worse than none.
 //  - SNAPSHOT FIRST. The pre-change value is persisted before the change is made, so
 //    `device reset` can undo it even from a later process.
-const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps\n' +
+const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps | device release [serial]\n' +
     `Keys: ${settings_1.SETTING_KEYS.join(', ')}`;
 function cmdDevice(ctx) {
     const sub = (ctx.positionals[0] ?? '').toLowerCase();
@@ -994,10 +1030,43 @@ function cmdDevice(ctx) {
             return deviceReset(ctx, rest);
         case 'caps':
             return deviceCaps(ctx);
+        case 'release':
+            return deviceRelease(ctx, rest);
         default:
             throw new errors_1.CliError((sub ? `Unknown 'device' subcommand '${sub}'.\n` : '') + DEVICE_USAGE, 2);
     }
 }
+/**
+ * Hand a device back to the pool. The break-glass named in every "in use by" refusal:
+ * a crashed job's claim expires on its own, but waiting out the TTL is the one thing an
+ * operator should never be forced to do just to get on with their run.
+ *
+ * Deliberately releases someone ELSE's claim too, naming them — you had to type the
+ * serial, and refusing here would leave no way to recover a stuck device at all. Resolves
+ * the device WITHOUT going through the driver, so it works even when the claim being
+ * cleared is the very thing that would refuse the resolve.
+ */
+function deviceRelease(ctx, args) {
+    const serial = args[0] || ctx.device;
+    if (!serial) {
+        throw new errors_1.CliError('Usage: verikun device release <serial>  (or pass --device / set VERIKUN_DEVICE)', 2);
+    }
+    if (!(0, claims_1.claimsEnabled)()) {
+        (0, output_1.err)('device claims are disabled (VERIKUN_NO_CLAIM) — nothing to release');
+        return 0;
+    }
+    const released = (0, claims_1.releaseClaim)(serial);
+    if ((0, args_1.flagBool)(ctx.flags, 'json')) {
+        (0, output_1.json)({ serial, released: !!released, ...(released ? { was: released } : {}) });
+    }
+    else if (released) {
+        (0, output_1.out)(`released ${serial} (was held by ${(0, claims_1.describeClaim)(released)})`);
+    }
+    else {
+        (0, output_1.out)(`${serial} was not claimed`);
+    }
+    return 0;
+}
 /** Render a setting value for humans/JSON; a platform that cannot answer says so. */
 const showValue = (v) => v ?? 'n/a';
 function deviceSet(ctx, args) {
@@ -1197,6 +1266,10 @@ function cmdRun(positionals, flags, platform, device) {
         case 'stop':
         case 'discard': {
             const cleared = run_1.Recorder.clear();
+            // The run is over, so the device goes back to the pool now rather than in TTL
+            // minutes. `mineOnly` because a run can only ever hand back its own device.
+            if (cleared?.device)
+                (0, claims_1.releaseClaim)(cleared.device, { mineOnly: true });
             if (asJson)
                 (0, output_1.json)({ cleared: cleared?.id ?? null });
             else
@@ -1226,6 +1299,9 @@ function cmdRun(positionals, flags, platform, device) {
                 }
             }
             const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive(positionals[1], { noLogs, fetchLogs });
+            // Archived means finished: release after log capture, which still needs the device.
+            if (state.device)
+                (0, claims_1.releaseClaim)(state.device, { mineOnly: true });
             const { passed, failed } = tally(state.steps);
             if (asJson) {
                 (0, output_1.json)({
@@ -1374,6 +1450,9 @@ async function cmdBatch(positionals, batchFlags) {
         (0, output_1.err)('[verikun] batch: no commands to run');
         return 0;
     }
+    // One process drives the whole batch, so its pid is exact evidence that the device is
+    // still in use — a `kill -9` hands it straight back instead of parking it for the TTL.
+    (0, claims_1.setProcessScoped)(true);
     // The finally is what makes `device set` safe to use in a batch: a line that fails
     // (or a ^C) still puts the device back, instead of leaving it offline or rotated.
     try {
@@ -1413,6 +1492,7 @@ async function cmdBatch(positionals, batchFlags) {
                 /* the device may be exactly why we are unwinding — never mask the real error */
             }
         }
+        (0, claims_1.releaseOwnClaims)();
     }
 }
 function parseAiOptions(flags) {
@@ -1603,6 +1683,12 @@ async function resolveBackend(platform, device, flags) {
     const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
     runCtx = { platform: health.platform, device: health.serial };
     (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial} · verikun ${health.version}`);
+    // Say the read path once, here. Reads execute server-side, so this is the only end of the
+    // connection that knows it — and without it a companion that had silently stood down was
+    // indistinguishable from one that never engaged, for a whole suite (issue #77). An older
+    // server omits the field; saying nothing is better than guessing.
+    if (health.reads)
+        (0, output_1.err)(`[verikun] server reads: ${health.reads.path} (${health.reads.detail})`);
     const remote = (0, remote_1.createRemoteBackend)(opts, health);
     return {
         backend: {
@@ -1630,7 +1716,7 @@ async function resolveBackend(platform, device, flags) {
         },
         platform: health.platform,
         device: health.serial,
-        remote: { url: server, version: health.version },
+        remote: { url: server, version: health.version, reads: health.reads },
     };
 }
 /**
@@ -1849,6 +1935,7 @@ async function cmdAi(positionals, flags) {
         throw new errors_1.CliError('Usage: verikun ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--server url] [--show-plan] [--recompile]', 2);
     }
     const opts = parseAiOptions(flags);
+    (0, claims_1.setProcessScoped)(true); // one process for the whole run — see claims.ts's isLive
     // --show-plan: compile (or cache-hit) and print the IR — no device, no backend.
     if ((0, args_1.flagBool)(flags, 'show-plan')) {
         const nl = readAiTest(file);
@@ -1869,6 +1956,7 @@ async function cmdAi(positionals, flags) {
         // otherwise an unattended run leaves the phone offline or in dark mode.
         await restoreDeviceOverrides(backend);
         await backend.close?.(); // frees a remote server's device lock for the next command
+        (0, claims_1.releaseOwnClaims)(); // and the host-level claim, so the next job can have the device
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
         (0, output_1.json)({
@@ -1928,13 +2016,14 @@ async function cmdSuiteEntry(positionals, flags) {
     if (!dirArg)
         throw new errors_1.CliError('Usage: verikun suite <dir> [--app <id>] [--server url] [--name n] [--retries n] [--json]', 2);
     const opts = parseAiOptions(flags);
+    (0, claims_1.setProcessScoped)(true); // one process for the whole suite — see claims.ts's isLive
     // Pre-flight the provider BEFORE touching any device/server: every test needs it
     // to compile (on a cache miss) or to repair at runtime.
     if (!providerAvailable(opts.model)) {
         throw new errors_1.CliError(`${providerRequirement(opts.model)} — needed to compile/repair tests (model ${opts.model}).`, 3);
     }
     const reqPlatform = platformFromFlags(flags);
-    const { backend, platform, device } = await resolveBackend(reqPlatform, deviceFromFlags(flags, reqPlatform), flags);
+    const { backend, platform, device, remote } = await resolveBackend(reqPlatform, deviceFromFlags(flags, reqPlatform), flags);
     const app = (0, args_1.flagStr)(flags, 'app');
     if (app)
         assertSafeAppId(app);
@@ -1942,6 +2031,9 @@ async function cmdSuiteEntry(positionals, flags) {
         return await (0, suite_1.cmdSuite)(dirArg, flags, {
             platform,
             device,
+            ...(remote
+                ? { server: { url: remote.url, verikun: remote.version, reads: remote.reads?.path } }
+                : {}),
             runTest: (file) => runAiTest(file, opts, backend, platform, device),
             // Reset app state between tests only when the app id is known; without --app,
             // each test is responsible for its own isolation (e.g. `launch --clear`).
@@ -1952,6 +2044,7 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
+        (0, claims_1.releaseOwnClaims)();
     }
 }
 // ---------------------------------------------------------------------------
@@ -2104,6 +2197,12 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
             catch {
                 /* surfaced by the command handler below */
             }
+            // Keep this job's device claim alive. Deliberately NOT gated on the recorder:
+            // `Recorder.beginStep` returns null under VERIKUN_NO_RUN=1 (which the e2e suite
+            // sets), and hanging the heartbeat off it would silently stop claims from being
+            // refreshed for exactly the runs that exercise them.
+            if (serial)
+                (0, claims_1.touchClaim)(serial, platform);
             recorder = run_1.Recorder.beginStep(command, positionals, flags, platform, device, serial, driver);
         }
     }
@@ -2144,6 +2243,10 @@ async function executeForServer(command, positionals, flags, driver, platform) {
     catch {
         /* surfaced by the command handler below */
     }
+    // A server holds one device for its whole life, but its claim still has to look alive
+    // to everyone else on the host — refresh it per request, the same as a local step.
+    if (serial)
+        (0, claims_1.touchClaim)(serial, platform);
     // Sample the device clock up front so the caller's run can set logStart (the
     // ephemeral recorder never persists RunState). Best-effort — empty/unavailable
     // just means archive / vk log fall back to last-N.
@@ -2281,6 +2384,9 @@ DEVICE STATE (change the device the app runs on, then put it back)
                                       equivalent where it doesn't
                                       Refuses \`airplane=on\` over wireless adb (it would cut
                                       this very connection); --allow-wireless overrides.
+  device release [serial] [--json]    Hand a claimed device back to the pool. Claims
+                                      expire on their own; this is for when you don't
+                                      want to wait. See \`devices\` for who holds what.
 
 BATCH (script many commands in one process)
   batch [--file path] [--quiet]       Run newline-separated commands — from --file,
@@ -2342,7 +2448,8 @@ SERVER (expose a locally-connected device to remote verikun clients)
   VERIKUN_SERVER_AUTH_KEY) to ai/suite/install. The server's device+platform apply.
 
 ENVIRONMENT
-  devices [--json]                    List attached devices/simulators
+  devices [--json]                    List attached devices/simulators, and which job is
+                                      already driving each (USED BY)
   doctor [--fix]                      Diagnose adb/device, and warn if this CLI or the
                                       Claude Code plugin is out of date (a warning only —
                                       it never changes the exit code). --fix disables

package/dist/companion/dump-match.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Does the companion's dump agree with the platform's own?
+ *
+ * This is the standard `calibrate()` holds the companion to before trusting a single one of
+ * its reads. It used to be plain string equality, and that is still the fast path — but
+ * equality turned out to be stricter than the property it was standing in for, and strictly
+ * enough to reject a companion that was right.
+ *
+ * The property that actually matters is TAP SAFETY: verikun taps the centre of a node the
+ * dump reported, so every node the companion serves must be one the platform would have
+ * served, with the same bounds. Byte equality implies that. It also demands something extra
+ * and unrelated — that the companion reproduce every node the platform emitted, including
+ * decor nobody can touch — and that is what broke.
+ *
+ * MEASURED (issue #79). Asking the accessibility layer for window information is what stops
+ * a long-lived connection serving a stale window, but it also makes Android clamp node
+ * bounds to the app window rather than the display. On a Pixel 6 emulator (Android 14) that
+ * drops exactly one node from the dump, `android:id/navigationBarBackground` at
+ * [0,2274][1080,2400] — not clickable, not focusable, and below every pixel the app owns.
+ * Every other node, root included, stayed byte-identical. Equality still said no, so the
+ * companion was benched and reads went from ~165ms to ~33s.
+ *
+ * So the rule is a subsequence with two guards:
+ *
+ *   1. every companion node is byte-identical to a platform node, in document order — this
+ *      is the tap-safety property, and it is not weakened at all;
+ *   2. every platform node the companion lacks is a LEAF and is neither clickable nor
+ *      focusable — so the companion can never quietly drop something tappable, nor a
+ *      container whose absence would re-nest the nodes under it.
+ *
+ * Guard 2 is deliberately stricter than the measurement requires: an unmatched container
+ * would still leave its children matchable, but the shapes that produces have not been seen
+ * on a real device, and the cost of refusing one is a slow read rather than a wrong tap.
+ *
+ * What this does NOT still guarantee is that a non-interactive leaf's bounds agree — such a
+ * node can differ and be treated as missing. That is the deliberate give: it cannot move a
+ * tap, because nothing reads it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dumpsAgree = dumpsAgree;
+const NODE_TAG = /<node\b[^>]*?\/?>/g;
+// A leading \s so `long-clickable="true"` cannot be read as `clickable="true"`.
+const CLICKABLE = /\sclickable="true"/;
+const FOCUSABLE = /\sfocusable="true"/;
+function nodes(xml) {
+    const out = [];
+    for (const m of xml.matchAll(NODE_TAG)) {
+        const raw = m[0];
+        out.push({
+            raw,
+            leaf: raw.endsWith('/>'),
+            interactive: CLICKABLE.test(raw) || FOCUSABLE.test(raw),
+        });
+    }
+    return out;
+}
+/** The `<hierarchy …>` element itself — its `rotation` is part of the contract. */
+function header(xml) {
+    return /<hierarchy\b[^>]*>/.exec(xml)?.[0] ?? '';
+}
+function dumpsAgree(stock, companion) {
+    const a = stock.trim();
+    const b = companion.trim();
+    if (a === b)
+        return { agree: true };
+    if (header(a) !== header(b)) {
+        return { agree: false, reason: 'the hierarchy header differs (rotation changed mid-capture?)' };
+    }
+    const stockNodes = nodes(a);
+    const compNodes = nodes(b);
+    let i = 0; // stock
+    for (const want of compNodes) {
+        // Skip platform nodes the companion did not emit, proving each is droppable as we go.
+        while (i < stockNodes.length && stockNodes[i].raw !== want.raw) {
+            const skipped = stockNodes[i];
+            if (skipped.interactive) {
+                return { agree: false, reason: 'the companion is missing a node the platform reports as tappable' };
+            }
+            if (!skipped.leaf) {
+                return { agree: false, reason: 'the companion is missing a container the platform reports' };
+            }
+            i++;
+        }
+        if (i === stockNodes.length) {
+            return { agree: false, reason: 'the companion reports a node the platform does not' };
+        }
+        i++; // consume the match
+    }
+    // Anything left over in the platform's dump must clear the same bar.
+    for (; i < stockNodes.length; i++) {
+        if (stockNodes[i].interactive) {
+            return { agree: false, reason: 'the companion is missing a node the platform reports as tappable' };
+        }
+        if (!stockNodes[i].leaf) {
+            return { agree: false, reason: 'the companion is missing a container the platform reports' };
+        }
+    }
+    return { agree: true };
+}