verikun 0.20.0 → 0.21.1

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

@@ -251,10 +251,37 @@ outweigh dozens of `vk ui` calls. When you do, `vk` already downscales the PNG
 **Two uses of a screenshot — keep them apart.** The cost above is about *reading a
 screenshot back into context* to decide your next move; that is what to avoid (perceive
 and verify with the hierarchy instead). A screenshot taken purely as **report evidence
-and never read back** costs nothing at runtime. So when you drive a flow to produce a
-report, **do** `vk screenshot` around each significant transition (and before a risky or
-verification step) — then leave it in the report, don't read the PNG back. A visual trail
-makes post-run review far easier, and a failing step already auto-captures its own screen.
+and never read back** costs no tokens. So when you drive a flow to produce a report, **do**
+`vk screenshot` around each significant transition (and before a risky or verification step)
+— then leave it in the report, don't read the PNG back. A visual trail makes post-run review
+far easier, and a failing step already auto-captures its own screen.
+
+It is not free in wall clock, though: a capture is ~1.1s on a physical Android phone. That is
+cheap next to a hierarchy read (~2.4s — see below) but it is not zero, so screenshot the
+transitions worth reviewing rather than every step.
+
+**Most of a run's time is reading the UI hierarchy.** Every selector command (`tap`, `text`,
+`find`, `assert`, `swipe --on`) costs one read; measured on a physical mid-range Android
+phone, one read is ~2.4s, nearly all of it fixed per-invocation cost inside `uiautomator`
+that does not depend on how complex the screen is. iOS is ~10x cheaper. So prefer one
+`vk assert` over a `vk ui` you have to scan, batch a known flow with `vk batch` rather than
+re-checking between every step, and don't add a redundant `vk ui` just to confirm what an
+`assert` already proved.
+
+On Android this is handled for you: verikun keeps an accessibility connection alive on the
+device (the *companion*), which cuts a read to ~0.2s. The first read on a device costs ~5.8s
+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, 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

package/CHANGELOG.md

@@ -6,7 +6,156 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [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
+- **An on-device companion that makes an Android UI-hierarchy read ~12x faster** — `vk ui`
+  goes from **2.44s to 0.18s** end to end on a physical SM-A415F, with **identical** output.
+  Reading the hierarchy is the dominant cost of any suite, so this moves the whole runtime,
+  not a rounding error. Every selector command benefits, not just `vk ui`: `find` 12.3x,
+  `assert` 12.0x, `wait` 11.5x, `tap` 8.1x, `text` 3.6x (the remainder is `adb shell input`,
+  which does not go through the companion yet).
+
+  **On by default; `VERIKUN_COMPANION=0` opts out.** It shipped opt-in first and that was
+  wrong — nobody discovers an environment variable they were never told about, and the
+  people who most need the speedup are the least likely to go looking for it.
+
+  It also makes auto-wait honour its window: a 5s wait for an element that never appears takes
+  ~6.4s rather than ~10.8s, because the stock path's final 2.4s read starts just before the
+  deadline and overshoots.
+
+  The first read on a device costs ~6s to push, start and calibrate. The verdict is then
+  remembered **on the device** (`/data/local/tmp/verikun-companion.note`, keyed by verikun
+  version), so a restart after the 15-minute idle shutdown reuses it and costs ~2.1s. The
+  same note records a device the companion could not start on at all, so that phone falls
+  straight through to the stock read instead of paying a doomed startup on every command —
+  which is what makes being on by default safe rather than merely fast.
+
+  Profiling `adb shell uiautomator dump` showed only ~0.10s of its ~2.4s is work. The rest is
+  paid fresh every call: ~1.22s starting ART and loading `uiautomator.jar`, and ~1.00s in
+  `waitForIdle(1000, 10000)`. That second one is not a flat sleep — it waits for the
+  accessibility event stream to have been *quiet* for a second, and a freshly connected
+  bridge has no history of quiet, so it must observe one. A long-lived connection already
+  does. The companion therefore keeps the full idle semantics and still returns in
+  milliseconds; it is not trading safety for speed.
+
+  It is Java compiled to dex (4KB), pushed to `/data/local/tmp` and run by the phone's own
+  runtime via `app_process` — scrcpy's approach. **Nothing is installed**: no APK, no root,
+  package list untouched. It shuts itself down after 15 minutes idle. It does **not** cache
+  the hierarchy — every read walks the live tree; only the *connection* is kept, so the
+  "re-capture fresh every command" rule is intact. It borrows the platform's own serialiser,
+  so its XML is byte-identical to `uiautomator dump`'s.
+
+  **A device has exactly one `UiAutomation` connection and the companion holds it** — while
+  it runs, `uiautomator dump` is SIGKILLed, and Appium, Layout Inspector and TalkBack cannot
+  attach. That is the one real cost, and the reason for the opt-out: `VERIKUN_COMPANION=0`,
+  or `vk companion stop` to hand it back once. `vk companion status` reports it.
+
+  It cannot fail a test. Every failure route releases the connection *before* falling back,
+  because the stock path is not merely slower while the companion holds it — it is
+  unavailable. A dead companion frees the connection by dying; one that cannot be asked
+  nicely is killed. A fallback read costs ~3.4s against 2.4s if the companion had never
+  existed.
+
+  Before trusting it, verikun takes **one** real `uiautomator dump` and checks the companion
+  reproduces it byte for byte, then remembers the answer on the device. The dumper clips node
+  bounds to a display size, and **which size the platform uses changed between Android
+  versions** — measured on three devices: a Samsung SM-A415F and a Google Pixel 3a, both on
+  Android 12, clip to the app window; a Pixel 6 emulator on Android 14 clips to the physical
+  display. The boundary is in AOSP itself — `DumpCommand` reads `getSize()` on the
+  `android12-release` and `android13-release` branches and `getRealSize()` from
+  `android14-release` onward — so it is the platform version, not the vendor, and a
+  hard-coded choice is wrong on one side of it whichever side you pick. The gap (44–254px)
+  would not fail loudly: it would shift every element near the bottom of the screen and land
+  taps elsewhere while still reporting success. If neither candidate
+  matches, the companion is declined and the stock path is used.
+
+  New: `vk companion <status|stop>`, `VERIKUN_COMPANION`, `tools/` for on-device programs,
+  and a [companion guide](https://ddikman.github.io/verikun/guides/companion/).
 - **A `Self-healing in CI` docs page, and a plan-cache step in the reference workflow.** The
   question it answers came from a team running verikun in CI: *should it be allowed to heal a
   drifted step, or should that just fail the build?* The answer was spread across five pages,
@@ -44,7 +193,85 @@ All notable changes to this project are documented here. The format is based on
 
   No version bump: no CLI behaviour changed.
 
+### Changed
+- **Android screenshots are about twice as fast**, and byte-for-byte identical. `screencap -p`
+  makes the *phone* PNG-encode a full-resolution image, which we then immediately decode and
+  shrink — so the encode was pure waste. Captures now come off the device as raw pixels
+  (`screencap`, no `-p`) and are encoded here, at the size we actually keep. Measured on a
+  physical SM-A415F: **`vk screenshot` 2.60s → 1.12s**, and `--full` 2.60s → 1.19s. The larger
+  transfer is not the problem it looks like — 10MB of RGBA box-downscales in ~10ms and deflates
+  in ~110ms on the host, against ~1.4s of on-device encoding avoided. Verified on-device: the
+  PNG the old and new paths produce is identical byte-for-byte.
+
+  This is a new **optional** `Driver.screenshotRaw()`, and `null` is a first-class answer: a
+  backend without a raw path (iOS — `simctl` is already ~0.2s, so there is nothing to win) or a
+  capture whose header we do not recognise falls back to `screenshot()`. Failure-evidence
+  captures take the same route and stay full-resolution. An OEM laying the framebuffer out
+  differently gets the old speed, never a wrong image.
+
 ### Fixed
+- **Several `vk` processes starting on one device at once could fail outright.** Calibration
+  works by *releasing* the device's single `UiAutomation` connection to take a real
+  `uiautomator dump` — so two processes calibrating at once SIGKILL each other's dump.
+  MEASURED: five concurrent first-ever reads on one device gave exit codes `[3,3,0,3,3]`,
+  each reporting `Killed`.
+
+  Calibration is now claimed, and the claim is granted by the **companion itself**, whose
+  single-threaded accept loop makes it genuinely atomic. A process that does not get the
+  claim waits for the verdict and never touches the connection meanwhile — waiting processes
+  used to "helpfully" acquire it during the window the holder had deliberately released it,
+  killing the very dump they were waiting for. A claim from a process that then dies goes
+  stale after 45s, so nothing can wedge a device permanently.
+
+  The obvious host-side lock does **not** work and is worth recording: Android's toybox
+  `mkdir` **succeeds on an existing directory** (exit `0`, unlike POSIX), so a `mkdir` mutex
+  silently grants itself to every caller. Five concurrent attempts all reported success.
+  After the fix, five concurrent first-ever reads are `[0,0,0,0,0]`.
+
+- **A transient or local problem could permanently mark a device as unable to run the
+  companion.** That verdict is sticky — every later command on that phone would skip to the
+  2.4s path — and two things could write it wrongly: a checkout that had not built the jar
+  (a fault of *this* working copy, not of the device), and a startup collision (transient,
+  and usually leaving a perfectly good companion running). It is now only recorded when the
+  jar exists *and* a second look still finds nothing. `start()` also re-probes before
+  stopping anything, so two racing processes can no longer kill each other's companion.
+
+- **A command with a 120-second wait budget could abort after 20, because the app had not
+  drawn yet.** `launch` force-stops the app before starting it (and `--clear` wipes its data
+  too), leaving a gap of a second or two with no window at all. The platform correctly
+  reports a null root for that gap, and the capture layer escalated it to a fatal environment
+  error (exit `3`) after three attempts — throwing away a budget the caller had explicitly
+  asked for. Measured before the fix: `wait --timeout 120000` aborted at ~20s on roughly half
+  of the runs, with ~100 seconds unspent.
+
+  A null root is now `NoWindowError`: an observation about the screen, not a broken machine.
+  Every polling caller — `wait`, `find`, `assert`, `tap`, `text`, and the `vk ai` engine's
+  guards — treats it as "nothing on screen yet" and keeps polling to its own deadline. Every
+  *other* capture failure still surfaces immediately, because a missing adb or a wedged
+  dumper is a machine to fix and polling it for two minutes helps nobody. A caller with no
+  wait budget (a bare `vk ui`) still gets exit `3`, unchanged.
+
+  The companion made this visible rather than causing it: with the stock dump's 2.4s latency
+  the three attempts spanned 7-14s and usually outlasted the gap by accident, so the bug was
+  being masked by being slow. It also no longer stands the companion *down* for a null root —
+  that is the device's state, not a companion fault, and releasing the connection dropped the
+  whole process onto the slow path for the rest of its life. After the fix: 0/5 aborts, and
+  the companion stays connected across `launch --clear`.
+
+- **A failed `uiautomator dump` could silently return the PREVIOUS screen.** `dumpXml` ran
+  `uiautomator dump <path>` and then `cat <path>`, accepting anything containing
+  `<hierarchy>` — but it never checked that *this* dump had written the file. The dump writes
+  to a fixed path and leaves the last successful result there whenever it fails, and it fails
+  without saying so in its exit code: AOSP's `DumpCommand` prints `ERROR: could not get idle
+  state` and returns normally when `waitForIdle` times out on an animating screen. The stale
+  XML is perfectly well-formed, so every check passed and the caller resolved selectors —
+  and tapped coordinates — from a screen that could be minutes old. Measured: a dump killed
+  at 18:46 happily served the 18:44 hierarchy.
+
+  The file is now removed in the same device shell immediately before the dump, so `cat` can
+  only succeed if this dump produced it; a genuinely failed capture now fails loudly (exit
+  `3`) instead of quietly lying. Pre-existing — the companion below made it easy to hit, and
+  is how it was found.
 - **The release gate stopped understanding `npm pack --json`, which blocked the 0.20.0
   publish.** `scripts/check-package-contents.mjs` read the pack result as
   `JSON.parse(raw)[0]`, but **npm 12 returns an object keyed by package name** where npm ≤ 11

package/dist/capture.js

@@ -0,0 +1,29 @@
+"use strict";
+// Screen capture: the one place that decides HOW a screenshot is obtained.
+//
+// Sits between the driver (device I/O) and image.ts (pure image math) because it
+// needs both, and lives apart from cli.ts so run.ts's failure-evidence capture can
+// share it without an import cycle.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capturePng = capturePng;
+const image_1 = require("./image");
+/**
+ * Capture the screen as a PNG whose longest edge is at most `maxEdge` px
+ * (`null` = full size). `buf` is always the image to write.
+ *
+ * Prefers the driver's raw path — pixels straight off the device, PNG-encoded here —
+ * which avoids an on-device encode of an image we are about to shrink anyway, and is
+ * roughly 2x faster end to end on Android. A backend without a raw path, or one whose
+ * capture came back in a shape we do not recognize, falls back to `screenshot()`, so
+ * the only observable difference is how long it took.
+ */
+function capturePng(driver, maxEdge) {
+    const raw = driver.screenshotRaw?.() ?? null;
+    if (raw)
+        return (0, image_1.pngFromRaw)(raw, maxEdge);
+    const png = driver.screenshot();
+    if (maxEdge === null) {
+        return { buf: png, width: 0, height: 0, scaled: false, origWidth: 0, origHeight: 0, reason: 'full size requested' };
+    }
+    return (0, image_1.downscalePng)(png, maxEdge);
+}

package/dist/cli.js

@@ -67,7 +67,8 @@ const format_1 = require("./ui/format");
 const viewport_1 = require("./ui/viewport");
 const output_1 = require("./output");
 const run_1 = require("./run");
-const image_1 = require("./image");
+const capture_1 = require("./capture");
+const manager_1 = require("./companion/manager");
 const engine_1 = require("./agent/engine");
 const lint_1 = require("./agent/lint");
 const claude_1 = require("./agent/claude");
@@ -182,6 +183,29 @@ function pollStep(flags, deadline) {
     const interval = (0, args_1.flagNum)(flags, 'interval') ?? DEFAULT_POLL_MS;
     return Math.min(interval, Math.max(0, deadline - Date.now()));
 }
+/**
+ * Read the hierarchy for a caller that is polling, treating "no window yet" as "nothing on
+ * screen yet" rather than a fatal environment error.
+ *
+ * A `NoWindowError` means the device genuinely had nothing to show — `launch --clear` and
+ * `launch` both leave a gap where the app has been stopped and has not drawn. That clears in
+ * a second or two, so a caller that has a wait budget should keep polling; escalating to
+ * exit 3 throws away the budget it was explicitly given. MEASURED: a `wait --timeout 120000`
+ * used to abort at ~20s with 100 seconds unspent.
+ *
+ * Every OTHER capture failure still propagates untouched — a missing adb, an unauthorised
+ * device or a wedged dumper is a machine to fix, and polling it for two minutes helps nobody.
+ */
+function readForPoll(ctx, opts = {}) {
+    try {
+        return ctx.driver.getElements(opts);
+    }
+    catch (e) {
+        if (e instanceof errors_1.NoWindowError)
+            return [];
+        throw e;
+    }
+}
 /**
  * matchElements with auto-wait: re-capture + re-match until at least one element
  * matches or the window elapses. Returns the final result either way (empty on miss).
@@ -189,7 +213,7 @@ function pollStep(flags, deadline) {
 async function matchWaiting(ctx, sel, opts = {}) {
     const deadline = Date.now() + waitWindowMs(ctx.flags);
     for (;;) {
-        const res = (0, selector_1.matchElements)(ctx.driver.getElements(opts), sel);
+        const res = (0, selector_1.matchElements)(readForPoll(ctx, opts), sel);
         if (res.matches.length > 0 || Date.now() >= deadline)
             return res;
         await sleep(pollStep(ctx.flags, deadline));
@@ -205,7 +229,7 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
     const start = Date.now();
     const deadline = start + windowMs;
     for (;;) {
-        const els = ctx.driver.getElements(opts);
+        const els = readForPoll(ctx, opts);
         if ((0, selector_1.matchElements)(els, sel).matches.length >= 1) {
             const { element, tier } = (0, selector_1.resolveOne)(els, sel); // 1 → resolved; >1 → throws ambiguity
             // The snapshot rides along: scroll-into-view needs the scrollable containers
@@ -731,32 +755,31 @@ function assertSafeAppId(appId) {
     return appId;
 }
 function cmdScreenshot(ctx) {
-    const raw = ctx.driver.screenshot();
     // Precedence: --full (original) > --max <px> (explicit) > --more (preset) > default.
     const maxEdge = (0, args_1.flagNum)(ctx.flags, 'max') ?? ((0, args_1.flagBool)(ctx.flags, 'more') ? MORE_SHOT_MAX_EDGE : shotMaxEdge());
-    const res = (0, args_1.flagBool)(ctx.flags, 'full') ? null : (0, image_1.downscalePng)(raw, maxEdge);
-    const buf = res?.scaled ? res.buf : raw;
+    const res = (0, capture_1.capturePng)(ctx.driver, (0, args_1.flagBool)(ctx.flags, 'full') ? null : maxEdge);
+    const buf = res.buf;
     const outFlag = (0, args_1.flagStr)(ctx.flags, 'out');
     const path = outFlag ? confineToCwd(outFlag) : (0, output_1.defaultScreenshotPath)();
     (0, node_fs_1.writeFileSync)(path, buf);
     ctx.record?.attachImage(buf);
-    ctx.record?.note({ message: res?.scaled ? `${path} (${res.width}×${res.height})` : path });
+    ctx.record?.note({ message: res.scaled ? `${path} (${res.width}×${res.height})` : path });
     // Surface the one case worth knowing about: we wanted to shrink but couldn't.
-    if (res && !res.scaled && res.reason?.startsWith('unsupported')) {
+    if (!res.scaled && res.reason?.startsWith('unsupported')) {
         (0, output_1.err)(`screenshot not downscaled: ${res.reason}`);
     }
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
         (0, output_1.json)({
             path,
             bytes: buf.length,
-            ...(res?.scaled
+            ...(res.scaled
                 ? { width: res.width, height: res.height, scaledFrom: { width: res.origWidth, height: res.origHeight } }
                 : {}),
         });
     }
     else {
         (0, output_1.out)(path);
-        if (res?.scaled)
+        if (res.scaled)
             (0, output_1.err)(`scaled ${res.origWidth}×${res.origHeight} -> ${res.width}×${res.height} (max edge ${maxEdge}px; --more for detail, --full for original)`);
     }
     return 0;
@@ -819,7 +842,7 @@ async function cmdWait(ctx) {
     const interval = (0, args_1.flagNum)(ctx.flags, 'interval') ?? 400;
     const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
-        const { matches, tier } = (0, selector_1.matchElements)(ctx.driver.getElements(), sel);
+        const { matches, tier } = (0, selector_1.matchElements)(readForPoll(ctx), sel);
         if (gone ? matches.length === 0 : matches.length > 0) {
             ctx.record?.note({ selector: sel, tier, element: matches[0], message: gone ? 'gone' : `${matches.length} match(es)` });
             if (gone)
@@ -877,10 +900,10 @@ async function cmdAssert(ctx) {
     // Auto-wait subsumes the common "wait then assert": poll until the assertion
     // passes or the window elapses. `--gone` therefore waits for disappearance.
     const deadline = Date.now() + waitWindowMs(ctx.flags);
-    let result = evalAssert(ctx.driver.getElements(), sel, ctx.flags);
+    let result = evalAssert(readForPoll(ctx), sel, ctx.flags);
     while (!result.pass && Date.now() < deadline) {
         await sleep(pollStep(ctx.flags, deadline));
-        result = evalAssert(ctx.driver.getElements(), sel, ctx.flags);
+        result = evalAssert(readForPoll(ctx), sel, ctx.flags);
     }
     const { pass, reason, matches } = result;
     ctx.record?.note({ selector: sel, element: matches[0], message: `${pass ? 'PASS' : 'FAIL'} — ${reason}` });
@@ -1550,7 +1573,7 @@ async function resolveBackend(platform, device, flags) {
                     // vice versa), and neither is allowed to derail recording the failure.
                     const out = {};
                     try {
-                        out.png = driver.screenshot();
+                        out.png = (0, capture_1.capturePng)(driver, null).buf;
                     }
                     catch {
                         /* device may be gone — that may be why we failed */
@@ -1580,6 +1603,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: {
@@ -1607,7 +1636,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 },
     };
 }
 /**
@@ -1911,7 +1940,7 @@ async function cmdSuiteEntry(positionals, flags) {
         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);
@@ -1919,6 +1948,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`).
@@ -1933,6 +1965,48 @@ async function cmdSuiteEntry(positionals, flags) {
 }
 // ---------------------------------------------------------------------------
 // Dispatch
+/**
+ * Inspect or stop the on-device companion (`tools/verikun-companion`).
+ *
+ * `stop` exists because the companion holds the device's ONE UiAutomation connection for as
+ * long as it runs, which locks out Appium, Layout Inspector and a second verikun. Without a
+ * way to hand that back, the only recourse would be `adb shell pkill`.
+ */
+function cmdCompanion(ctx) {
+    const action = ctx.positionals[0] ?? 'status';
+    if (action !== 'status' && action !== 'stop') {
+        throw new errors_1.CliError(`Usage: verikun companion <status|stop>`, 2);
+    }
+    if (ctx.platform !== 'android') {
+        throw new errors_1.CliError('The companion is Android-only; iOS reads the hierarchy through idb, which is already fast.', 3);
+    }
+    const companion = new manager_1.Companion({
+        adb: process.env.ADB || 'adb',
+        serial: ctx.driver.resolvedSerial(),
+        // `status`/`stop` never calibrate, so this is unreachable — but a throwing stub is
+        // honest about that, where a silent no-op would hide a future miswiring.
+        stockDump: () => {
+            throw new errors_1.CliError('the companion command never calibrates', 3);
+        },
+    });
+    if (action === 'stop') {
+        companion.stop();
+        if ((0, args_1.flagBool)(ctx.flags, 'json'))
+            (0, output_1.json)({ companion: 'stopped' });
+        else
+            (0, output_1.out)('companion stopped');
+        return 0;
+    }
+    const state = companion.describe();
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)({ companion: state, enabled: (0, manager_1.companionEnabled)() });
+    else {
+        (0, output_1.out)(state);
+        if (!(0, manager_1.companionEnabled)())
+            (0, output_1.err)('note: disabled by VERIKUN_COMPANION — hierarchy reads use the slower stock dump');
+    }
+    return 0;
+}
 // ---------------------------------------------------------------------------
 async function executeCommand(command, ctx) {
     switch (command) {
@@ -1940,6 +2014,8 @@ async function executeCommand(command, ctx) {
             return cmdDevices(ctx);
         case 'doctor':
             return cmdDoctor(ctx);
+        case 'companion':
+            return cmdCompanion(ctx);
         case 'ui':
         case 'dump':
             return cmdUi(ctx);
@@ -2280,6 +2356,8 @@ ENVIRONMENT
                                       Claude Code plugin is out of date (a warning only —
                                       it never changes the exit code). --fix disables
                                       animations. VERIKUN_NO_UPDATE_CHECK skips the check
+  companion <status|stop> [--json]    On-device hierarchy reader (Android, on by default;
+                                      VERIKUN_COMPANION=0 opts out)
 
 TEST RUNS (actions are recorded; a run auto-starts on first action)
   run start [name] [--force]          Begin a named run (else one starts implicitly)