verikun 0.20.0 → 0.21.0

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

@@ -251,10 +251,31 @@ 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.
 
 **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,72 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [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 +109,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 */
@@ -1933,6 +1956,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 +2005,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 +2347,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)

package/dist/companion/manager.js

@@ -0,0 +1,397 @@
+"use strict";
+// Lifecycle for the on-device companion: get one running, prove it agrees with the
+// platform, use it, and get out of its way the moment anything goes wrong.
+//
+// The whole design is shaped by one constraint, measured on-device: only ONE UiAutomation
+// may be connected per device, and the newcomer is SIGKILLed. So unlike `screenshotRaw()`,
+// this cannot be a per-call try/catch — while the companion holds the connection the stock
+// path is not merely slower, it is *unavailable* (exit 137). Every failure route here
+// therefore gets the companion off the connection BEFORE the caller falls back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Companion = void 0;
+exports.companionJarPath = companionJarPath;
+exports.companionEnabled = companionEnabled;
+exports.releaseCompanionOn = releaseCompanionOn;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const exec_1 = require("../exec");
+const output_1 = require("../output");
+const errors_1 = require("../errors");
+const version_1 = require("../version");
+const protocol_1 = require("./protocol");
+const DEVICE_JAR = '/data/local/tmp/verikun-companion.jar';
+/** What we learned about this device last time, kept ON the device because that is what the
+ *  knowledge is about — it survives every `vk` process, every working directory, and a
+ *  disposable CI runner. See readDeviceNote/writeDeviceNote. */
+const DEVICE_NOTE = '/data/local/tmp/verikun-companion.note';
+/** How long to let the process that claimed calibration finish before giving up on it.
+ *  Generous: calibration is ~5s, and being patient costs one slow read while being impatient
+ *  costs the mutual-SIGKILL contention the claim exists to prevent. */
+const CALIBRATION_WAIT_MS = 30000;
+const SOCKET = 'verikun-companion';
+const MAIN_CLASS = 'dev.verikun.companion.CompanionApp';
+/** uiautomator.jar supplies UiAutomationShellWrapper + AccessibilityNodeInfoDumper, which the
+ *  companion borrows so its XML is byte-identical to `uiautomator dump`'s. */
+const DEVICE_CLASSPATH = [
+    '/system/framework/android.test.runner.jar',
+    '/system/framework/uiautomator.jar',
+    DEVICE_JAR,
+].join(':');
+/** Cold start measured at ~1.5s on a physical SM-A415F; the margin is for slower devices. */
+const START_TIMEOUT_MS = 12000;
+/** The companion's way of saying getRootInActiveWindow() returned null. */
+const NULL_ROOT_REPLY = /null root node/i;
+const START_POLL_MS = 150;
+/** The packaged companion jar: shipped in the npm tarball, and present in a source checkout
+ *  once `tools/verikun-companion/build.sh` has run. Absent means "no companion available",
+ *  which is a normal state, not an error. */
+function companionJarPath() {
+    // dist/companion/manager.js → repo root is two levels up.
+    const candidate = (0, node_path_1.resolve)(__dirname, '..', '..', 'tools', 'verikun-companion', 'prebuilt', 'verikun-companion.jar');
+    return (0, node_fs_1.existsSync)(candidate) ? candidate : null;
+}
+/**
+ * ON by default; `VERIKUN_COMPANION=0` opts out.
+ *
+ * It started opt-in, and that was wrong: a hierarchy read is the dominant cost of every
+ * Android run, nobody discovers an environment variable they have not been told about, and
+ * the people who most need the speedup are the least likely to go looking for it. Being
+ * fast by default is the whole point.
+ *
+ * What makes that safe is that a failure cannot cost a test: the stock path is always there
+ * and every failure route hands the UiAutomation connection back before using it. What
+ * makes it not *slow* is the on-device note — a device where the companion cannot run says
+ * so once, and is never probed again.
+ *
+ * The real cost is that the companion holds the device's single UiAutomation connection
+ * while it runs, so Appium, Layout Inspector and TalkBack cannot attach. `VERIKUN_COMPANION=0`
+ * or `vk companion stop` hands it back.
+ */
+function companionEnabled() {
+    const v = (process.env.VERIKUN_COMPANION ?? '').trim().toLowerCase();
+    return !(v === '0' || v === 'false' || v === 'off' || v === 'no');
+}
+/**
+ * Ask any companion on this device to drop the UiAutomation connection, so a stock
+ * `uiautomator dump` can run. Best-effort and silent: no companion is the normal case.
+ *
+ * Called from the STOCK dump path when it fails, including when the caller never opted in.
+ * A companion started by an earlier `VERIKUN_COMPANION=1` command outlives that process, so
+ * a plain `vk tap` afterwards would otherwise be SIGKILLed for as long as the companion
+ * lives. verikun's own helper must never be the reason verikun cannot read the screen.
+ *
+ * `release`, not `quit`: the process stays warm, so the next opted-in command re-acquires in
+ * ~1s instead of paying a full cold start.
+ */
+function releaseCompanionOn(serial) {
+    try {
+        (0, protocol_1.requestSync)((0, protocol_1.portForSerial)(serial), 'release', 4000);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+class Companion {
+    deps;
+    port;
+    /** Latched off for the rest of this process once anything goes wrong: a companion that
+     *  has already failed is not worth re-probing per read, since the retry would cost more
+     *  than the stock dump it is trying to avoid. */
+    unusable = false;
+    dims;
+    constructor(deps) {
+        this.deps = deps;
+        this.port = (0, protocol_1.portForSerial)(deps.serial);
+    }
+    adb(args, timeout = 15000) {
+        return (0, exec_1.runText)(this.deps.adb, ['-s', this.deps.serial, ...args], { timeout });
+    }
+    /**
+     * What we concluded about this device last time: `<verikun version>|<app|real|unsupported>`.
+     *
+     * Kept on the DEVICE rather than in `.verikun/`, because it is a fact about the phone, not
+     * about a working directory — it survives a `cd`, and a disposable CI runner inherits it
+     * instead of starting cold. Keyed by verikun version so an upgrade re-tries a device that
+     * an older build could not use.
+     */
+    readDeviceNote() {
+        const r = this.adb(['shell', `cat ${DEVICE_NOTE} 2>/dev/null`], 5000);
+        const [version, verdict] = r.stdout.trim().split('|');
+        if (version !== version_1.VERSION)
+            return undefined;
+        if (verdict === 'unsupported' || verdict === 'app' || verdict === 'real')
+            return verdict;
+        return undefined;
+    }
+    writeDeviceNote(verdict) {
+        // Single-quoted, and every value here comes from a closed set — nothing caller-supplied
+        // reaches the device shell.
+        this.adb(['shell', `echo '${version_1.VERSION}|${verdict}' > ${DEVICE_NOTE}`], 5000);
+    }
+    /**
+     * The hierarchy XML, or null when the companion cannot serve it — in which case the
+     * UiAutomation connection has already been handed back, so the caller's stock dump will
+     * work rather than being SIGKILLed.
+     */
+    dump(idleMs) {
+        if (this.unusable)
+            return null;
+        try {
+            if (!this.dims) {
+                this.dims = this.ensureReady();
+                if (!this.dims)
+                    return null;
+            }
+            const reply = (0, protocol_1.requestSync)(this.port, (0, protocol_1.dumpCommand)(idleMs, this.dims));
+            if (!(0, protocol_1.isHierarchy)(reply)) {
+                // The companion reports its own failures as plain text (`ERROR …`, `released —
+                // call acquire first`). Those must never reach the XML parser as though they were
+                // a screen: an unparseable "hierarchy" reads as zero elements, which is the
+                // "absent" lie that silently skips a guard.
+                const detail = reply.toString('utf8').trim().slice(0, 200) || 'empty reply';
+                // A null root is the DEVICE having no window, not the companion malfunctioning.
+                // Standing down for it would release a perfectly healthy connection and drop the
+                // whole process onto the 2.4s path — measured after every `launch --clear`, which
+                // leaves exactly this gap.
+                if (NULL_ROOT_REPLY.test(detail)) {
+                    throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch).');
+                }
+                throw new Error(detail);
+            }
+            return reply.toString('utf8');
+        }
+        catch (e) {
+            if (e instanceof errors_1.NoWindowError)
+                throw e; // transient screen state — the companion is fine
+            this.standDown(`companion dump failed (${e.message})`);
+            return null;
+        }
+    }
+    /** Get a calibrated companion running, or give up for this process. */
+    ensureReady() {
+        // FAST PATH, and the only one that needs no coordination: a companion that is already
+        // running AND calibrated. Note the `dims` check — an uncalibrated companion is NOT ready,
+        // because calibrating it needs the UiAutomation connection exclusively, and that has to
+        // happen under the lock below like every other exclusive use.
+        const live = this.probeState();
+        if (live.usable && live.dims) {
+            // Alive but NOT holding the connection: something asked it to let go — the stock dump
+            // path does exactly that when it fails, and `vk companion stop` is not the only route.
+            // Take the connection back before using it, or every read here answers "released" and
+            // silently falls through to the 2.4s path for the rest of the run.
+            if (!live.held && !this.acquire())
+                return undefined;
+            return live.dims;
+        }
+        // Nothing listening. Before paying a start + calibration, ask the device what happened
+        // last time — this is what stops a phone the companion cannot run on from costing every
+        // single command a doomed start attempt now that this is on by default.
+        const note = this.readDeviceNote();
+        if (note === 'unsupported') {
+            this.unusable = true;
+            return undefined;
+        }
+        return this.startAndCalibrate(note, live);
+    }
+    /** Wait for the process that claimed calibration to publish its verdict. */
+    waitForCalibration() {
+        const deadline = Date.now() + CALIBRATION_WAIT_MS;
+        while (Date.now() < deadline) {
+            (0, exec_1.sleepSync)(START_POLL_MS);
+            const state = this.probeState();
+            if (!state.usable)
+                return undefined; // it died; our caller falls back
+            if (!state.dims)
+                continue; // still working — do NOT touch the connection
+            if (!state.held && !this.acquire())
+                return undefined;
+            return state.dims;
+        }
+        return undefined;
+    }
+    startAndCalibrate(note, state) {
+        if (!state.usable && !this.start()) {
+            // Only record "this phone cannot run it" when the phone is genuinely the problem, and
+            // only after looking once more. Two ways this verdict could otherwise be wrong, and it
+            // is STICKY — every later command on this device would skip straight to the 2.4s path:
+            //   - the jar is missing, which is a fault of THIS checkout, not of the device;
+            //   - several `vk` processes cold-started at once and collided, which is transient and
+            //     usually leaves a perfectly good companion running (started by whoever won).
+            if (companionJarPath() && !this.probeState().usable)
+                this.writeDeviceNote('unsupported');
+            this.unusable = true;
+            return undefined;
+        }
+        // A remembered verdict skips calibration entirely — worth ~4.7s of the cold start, and
+        // the companion idle-shuts-down every 15 minutes, so restarts are routine.
+        if (note === 'app' || note === 'real') {
+            try {
+                (0, protocol_1.requestSync)(this.port, `calibrated ${note}`, 4000);
+                return note;
+            }
+            catch {
+                /* fall through and calibrate properly */
+            }
+        }
+        // ONLY ONE PROCESS MAY CALIBRATE. It works by releasing the UiAutomation connection to
+        // take a real `uiautomator dump`, so a second process doing it concurrently SIGKILLs the
+        // first one's dump — MEASURED as five concurrent first reads exiting [3,3,0,3,3]. The
+        // claim is granted by the companion itself, whose single-threaded accept loop makes it
+        // genuinely atomic; the obvious host-side lock does not work, because Android's toybox
+        // `mkdir` SUCCEEDS on an existing directory and so grants itself to every caller.
+        const already = this.probeState();
+        if (already.dims)
+            return already.dims;
+        if (!this.claimCalibration())
+            return this.waitForCalibration();
+        return this.calibrate();
+    }
+    claimCalibration() {
+        try {
+            return (0, protocol_1.requestSync)(this.port, 'claim-calibration', 8000).toString('utf8').trim() === 'granted';
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Retake the UiAutomation connection. ~1.05s: the cold-bridge idle wait, paid once. */
+    acquire() {
+        try {
+            (0, protocol_1.requestSync)(this.port, 'acquire', 20000);
+            return true;
+        }
+        catch (e) {
+            this.standDown(`companion could not reacquire the connection (${e.message})`);
+            return false;
+        }
+    }
+    probeState() {
+        try {
+            return (0, protocol_1.parseState)((0, protocol_1.requestSync)(this.port, 'state', 4000));
+        }
+        catch {
+            return { usable: false, held: false };
+        }
+    }
+    /** Push the jar, forward the socket, spawn detached, wait for it to answer. */
+    start() {
+        const jar = companionJarPath();
+        if (!jar) {
+            // Nothing to push. A source checkout that has not run tools/verikun-companion/build.sh
+            // lands here, and so would a broken install — neither is a fact about the device.
+            return false;
+        }
+        // Look once more before tearing anything down. Between our probe and now, another `vk`
+        // process may have started a perfectly good companion — and stopStale() below would kill
+        // it, so two processes racing could ping-pong indefinitely, each killing the other's.
+        if (this.probeState().usable)
+            return true;
+        // A companion left by an older verikun answers with a different protocol number. It is
+        // not merely useless — it is still holding the connection, so it must be stopped.
+        this.stopStale();
+        if (this.adb(['push', jar, DEVICE_JAR], 30000).code !== 0)
+            return false;
+        if (this.adb(['forward', `tcp:${this.port}`, `localabstract:${SOCKET}`]).code !== 0)
+            return false;
+        // Detached, and stdio fully redirected: every `vk` call is its own process, so a
+        // companion tied to this adb shell would die before the next command could reuse it —
+        // which is the entire point of it existing.
+        this.adb(['shell', `nohup env CLASSPATH=${DEVICE_CLASSPATH} app_process / ${MAIN_CLASS} >/dev/null 2>&1 &`]);
+        const deadline = Date.now() + START_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (this.probeState().usable)
+                return true;
+            (0, exec_1.sleepSync)(START_POLL_MS);
+        }
+        (0, output_1.err)('[verikun] companion did not start; using the stock hierarchy dump');
+        return false;
+    }
+    stopStale() {
+        try {
+            (0, protocol_1.requestSync)(this.port, 'quit', 3000);
+        }
+        catch {
+            /* nothing listening, or it is wedged — killByName is the backstop */
+        }
+        this.killByName();
+    }
+    /**
+     * Prove the companion's dump matches the platform's own before trusting it.
+     *
+     * The dumper clips every node's bounds to a display size, and which size the platform
+     * uses varies by build: AOSP's `DumpCommand` reads `getRealSize()`, while a physical
+     * SM-A415F's stock dump matches `getSize()`. Guessing wrong does not fail loudly — it
+     * shifts every element near the bottom of the screen, and the resulting tap lands
+     * somewhere else while still reporting success, which is the worst failure a testing
+     * tool has. So do not guess: take one real `uiautomator dump` and adopt whichever
+     * source reproduces it byte for byte.
+     *
+     * Costs one stock dump (~2.4s) plus a reconnect (~1.05s), once per companion — not once
+     * per process, because the verdict is stored in the companion itself.
+     */
+    calibrate() {
+        try {
+            // The stock dump cannot run while we hold the connection — it would be SIGKILLed.
+            (0, protocol_1.requestSync)(this.port, 'release', 5000);
+            const stock = this.deps.stockDump().trim();
+            (0, protocol_1.requestSync)(this.port, 'acquire', 20000);
+            for (const dims of ['app', 'real']) {
+                const reply = (0, protocol_1.requestSync)(this.port, (0, protocol_1.dumpCommand)(0, dims));
+                if ((0, protocol_1.isHierarchy)(reply) && reply.toString('utf8').trim() === stock) {
+                    (0, protocol_1.requestSync)(this.port, `calibrated ${dims}`, 4000);
+                    this.writeDeviceNote(dims);
+                    return dims;
+                }
+            }
+            // Neither matched. Usually the screen simply moved between the two dumps, but it
+            // could equally be a device whose bounds we would get wrong — and being slow is
+            // strictly better than tapping the wrong pixel, so decline rather than pick one.
+            this.standDown('companion output did not match the platform dump; using the stock path');
+            return undefined;
+        }
+        catch (e) {
+            this.standDown(`companion calibration failed (${e.message})`);
+            return undefined;
+        }
+    }
+    /** Hand the UiAutomation connection back, and stop using the companion in this process. */
+    standDown(reason) {
+        this.unusable = true;
+        (0, output_1.err)(`[verikun] ${reason}`);
+        try {
+            (0, protocol_1.requestSync)(this.port, 'release', 4000);
+        }
+        catch {
+            // It cannot be asked, so it has to be taken: while it holds the connection the stock
+            // dump is SIGKILLed, and the caller is about to depend on the stock dump.
+            this.killByName();
+        }
+    }
+    /** Kill by command line rather than a remembered pid — the companion outlives the process
+     *  that started it, so whoever needs it gone usually never had the pid. */
+    killByName() {
+        this.adb(['shell', `pkill -f ${MAIN_CLASS}`], 5000);
+    }
+    /** Explicit teardown: `vk companion stop`. */
+    stop() {
+        try {
+            (0, protocol_1.requestSync)(this.port, 'quit', 4000);
+        }
+        catch {
+            this.killByName();
+        }
+        this.adb(['forward', '--remove', `tcp:${this.port}`]);
+    }
+    /** For `vk companion status`. */
+    describe() {
+        try {
+            const state = (0, protocol_1.requestSync)(this.port, 'state', 4000).toString('utf8').trim();
+            return `running on port ${this.port} (${state})`;
+        }
+        catch {
+            return 'not running';
+        }
+    }
+}
+exports.Companion = Companion;

package/dist/companion/protocol.js

@@ -0,0 +1,111 @@
+"use strict";
+// Wire protocol for the on-device companion (tools/verikun-companion).
+//
+// One request per connection: write a command line, read until EOF. Kept separate from
+// the lifecycle manager so the framing rules — which are where the sharp edges are —
+// can be unit-tested without a device.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionUnavailableError = exports.COMPANION_PROTOCOL = void 0;
+exports.isLiveReply = isLiveReply;
+exports.pingMatches = pingMatches;
+exports.parseState = parseState;
+exports.isHierarchy = isHierarchy;
+exports.dumpCommand = dumpCommand;
+exports.portForSerial = portForSerial;
+exports.requestSync = requestSync;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+/** Bumped in lockstep with PROTOCOL_VERSION in CompanionApp.java. A companion left running
+ *  by an older verikun answers `ping` with a different number and is restarted rather than
+ *  talked to, so a changed dump format can never be replayed by a stale process. */
+exports.COMPANION_PROTOCOL = '1';
+class CompanionUnavailableError extends Error {
+}
+exports.CompanionUnavailableError = CompanionUnavailableError;
+/**
+ * Is this reply from a live companion, or from nothing at all?
+ *
+ * Load-bearing: `adb forward` keeps the host port open whether or not anything is
+ * listening on the device end, so a companion that died answers with a successful
+ * connection and ZERO bytes rather than ECONNREFUSED. A client that only handles connect
+ * errors reads that as a valid empty hierarchy — which is exactly the "absent" lie that
+ * silently skips a guard. Treat an empty reply as unavailable, always.
+ */
+function isLiveReply(reply) {
+    return reply.length > 0;
+}
+/** Does this `ping` reply come from a companion we can speak to? */
+function pingMatches(reply) {
+    if (!isLiveReply(reply))
+        return false;
+    const [name, version] = reply.toString('utf8').trim().split(/\s+/);
+    return name === 'verikun-companion' && version === exports.COMPANION_PROTOCOL;
+}
+/**
+ * Parse a `state` reply: `verikun-companion <proto> (ready <dims>|uncalibrated) (held|released)`.
+ *
+ * One round trip answers all three questions, because each one costs a spawned client
+ * process on the host — and this runs before every read that has not already resolved.
+ */
+function parseState(reply) {
+    const unusable = { usable: false, held: false };
+    if (!isLiveReply(reply))
+        return unusable;
+    const parts = reply.toString('utf8').trim().split(/\s+/);
+    if (parts[0] !== 'verikun-companion' || parts[1] !== exports.COMPANION_PROTOCOL)
+        return unusable;
+    const dims = parts[2] === 'ready' ? parts[3] : undefined;
+    return { usable: true, dims, held: parts.includes('held') };
+}
+/** A dump reply is only usable if it is actually a hierarchy — the companion reports its
+ *  own failures as plain text (`ERROR …`, `released — call acquire first`), and those must
+ *  never reach the XML parser as if they were a screen. */
+function isHierarchy(reply) {
+    return isLiveReply(reply) && reply.toString('utf8', 0, 512).includes('<hierarchy');
+}
+/** The command line for a dump, given the idle window and the calibrated dimension source. */
+function dumpCommand(idleMs, dims) {
+    return `dump ${Math.max(0, Math.round(idleMs))} ${dims}`;
+}
+/**
+ * Local port for a device's companion. One companion per device (only one UiAutomation may
+ * be connected at a time), so ports are derived from the serial rather than allocated — two
+ * verikun processes driving the SAME device must land on the same forward, and two driving
+ * DIFFERENT devices must not collide.
+ */
+function portForSerial(serial, base = 8299, span = 200) {
+    let hash = 0;
+    for (let i = 0; i < serial.length; i++)
+        hash = (hash * 31 + serial.charCodeAt(i)) >>> 0;
+    return base + (hash % span);
+}
+/**
+ * Send one command and read the whole reply, synchronously.
+ *
+ * Synchronous because `Driver` is: every device call in verikun is a `spawnSync`, and
+ * making the hierarchy read async would ripple through cli.ts, run.ts and the engine for
+ * no behavioural gain. Node has no sync socket, so the socket work happens in a child
+ * process (`sock-client.js`) and we read its stdout — the same shape as shelling to `adb`.
+ * Measured cost of that indirection: 39ms per round trip, against 2400ms for the stock
+ * dump it replaces.
+ *
+ * Throws CompanionUnavailableError for every failure mode, so callers have exactly one
+ * thing to catch before handing the connection back and using the stock path.
+ */
+function requestSync(port, command, timeoutMs = 10000) {
+    const client = (0, node_path_1.join)(__dirname, 'sock-client.js');
+    const r = (0, node_child_process_1.spawnSync)(process.execPath, [client, String(port), ...command.split(' ')], {
+        timeout: timeoutMs,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.error)
+        throw new CompanionUnavailableError(r.error.message);
+    if (r.status !== 0)
+        throw new CompanionUnavailableError(`companion unreachable on port ${port}`);
+    const out = r.stdout ?? Buffer.alloc(0);
+    // `adb forward` keeps the host port open whether or not anything is listening on the
+    // device end, so a dead companion connects fine and returns nothing. See isLiveReply.
+    if (!isLiveReply(out))
+        throw new CompanionUnavailableError('companion is not running');
+    return out;
+}

package/dist/companion/sock-client.js

@@ -0,0 +1,22 @@
+"use strict";
+// One-shot socket client, run as its own process.
+//
+// It exists because `Driver` is entirely synchronous — every device call is a spawnSync —
+// and Node has no synchronous socket. Rather than make getElements() async and ripple that
+// through cli.ts, run.ts and the engine, the companion is reached the same way every other
+// device call is: by spawning something and reading its stdout.
+//
+// Measured on a physical SM-A415F: 39ms per round trip including this process's own
+// startup, against 2400ms for `uiautomator dump`. The process spawn is most of that 39ms
+// and is the price of staying synchronous — worth it at ~60x.
+//
+// Usage: node sock-client.js <port> <command...>   → reply on stdout, exit 3 if unreachable.
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_net_1 = require("node:net");
+const [portArg, ...command] = process.argv.slice(2);
+const chunks = [];
+const sock = (0, node_net_1.connect)(Number(portArg), '127.0.0.1');
+sock.on('connect', () => sock.write(command.join(' ') + '\n'));
+sock.on('data', (c) => chunks.push(c));
+sock.on('end', () => process.stdout.write(Buffer.concat(chunks)));
+sock.on('error', () => process.exit(3));

package/dist/drivers/adb.js

@@ -5,6 +5,7 @@ exports.probeAdb = probeAdb;
 exports.escapeText = escapeText;
 exports.adbTransport = adbTransport;
 exports.severanceRisk = severanceRisk;
+const manager_1 = require("../companion/manager");
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
@@ -68,6 +69,22 @@ const KEYCODES = {
     page_down: 93,
 };
 const DUMP_PATHS = ['/sdcard/window_dump.xml', '/data/local/tmp/window_dump.xml'];
+/** Idle window the companion waits for before dumping. Kept at the stock command's own
+ *  1000ms so behaviour is unchanged — and it is free: on a warm accessibility bridge the
+ *  screen has already been quiet, so waitForIdle returns at once (measured: `dump 1000`
+ *  costs the same ~10ms as `dump 0`). The stock path pays a full second for it only
+ *  because a freshly connected bridge has no history of quiet to draw on. */
+const COMPANION_IDLE_MS = 1000;
+/** What both capture paths say when there is no window to read: AOSP's DumpCommand prints
+ *  "ERROR: null root node returned by UiTestAutomationBridge." and writes no file, and the
+ *  companion reports the same condition from getRootInActiveWindow(). Transient — see
+ *  NoWindowError. */
+const NULL_ROOT = /null root node/i;
+/** Header sizes `screencap` writes before the pixels: width/height/format, plus a
+ *  colorspace word since Android 9. Newest first — see `screenshotRaw`. */
+const RAW_HEADER_SIZES = [16, 12];
+/** android.graphics.PixelFormat.RGBA_8888 */
+const PIXEL_FORMAT_RGBA_8888 = 1;
 const DEFAULT_LOG_LINES = 200;
 /**
  * Escape a string for `adb shell input text <arg>`. The argument is parsed twice
@@ -139,6 +156,8 @@ class AdbDriver {
     cachedScreen;
     /** Rotation of the most recent dump — see viewport(). */
     lastRotation;
+    /** undefined = not built yet, null = opted out. See companionOrNull(). */
+    companion;
     constructor(serial) {
         this.requested = serial;
     }
@@ -244,16 +263,69 @@ class AdbDriver {
         }
         return this.cachedScreen;
     }
+    /** The resident companion, when opted in. Built lazily so a run that never reads the
+     *  hierarchy never touches the device with it. */
+    companionOrNull() {
+        if (!(0, manager_1.companionEnabled)())
+            return null;
+        if (this.companion === undefined) {
+            this.companion = new manager_1.Companion({
+                adb: ADB,
+                serial: this.resolvedSerial(),
+                // Calibration compares the companion against exactly the dump the rest of verikun
+                // would otherwise have used, so pass the stock path itself.
+                stockDump: () => this.stockDumpXml(),
+            });
+        }
+        return this.companion;
+    }
     dumpXml() {
+        // The companion answers in ~40ms against ~2400ms for the stock path. A null here means
+        // it could not serve the read AND has already handed the UiAutomation connection back —
+        // which matters, because the stock dump below is SIGKILLed while it is held. A
+        // NoWindowError propagates instead: there is nothing for the stock path to read either,
+        // and re-asking it would only burn the caller's wait budget more slowly.
+        const fast = this.companionOrNull()?.dump(COMPANION_IDLE_MS);
+        if (fast)
+            return fast;
+        return this.stockDumpXml();
+    }
+    stockDumpXml() {
         let lastErr = '';
         for (let attempt = 0; attempt < 3; attempt++) {
             const path = DUMP_PATHS[Math.min(attempt, DUMP_PATHS.length - 1)];
-            const dump = (0, exec_1.runText)(ADB, this.withSerial(['shell', 'uiautomator', 'dump', path]), { timeout: 15000 });
+            // DELETE THE FILE FIRST, in the same device shell. `uiautomator dump` writes to a
+            // fixed path and leaves the PREVIOUS dump there whenever it fails — and it fails
+            // without saying so in the exit code: AOSP's DumpCommand prints "ERROR: could not get
+            // idle state" and returns normally when waitForIdle times out (an animating screen),
+            // and the whole process is SIGKILLed if something else holds the device's single
+            // UiAutomation connection. Reading the file back then returns a stale screen that is
+            // perfectly well-formed, so every check below passes and the caller taps coordinates
+            // from a screen that is minutes old. MEASURED: a dump killed at 18:46 happily served
+            // the 18:44 hierarchy. Removing it first makes that impossible — `cat` can only
+            // succeed if THIS dump wrote it.
+            const dump = (0, exec_1.runText)(ADB, this.withSerial(['shell', `rm -f ${path}; uiautomator dump ${path}`]), {
+                timeout: 15000,
+            });
             const cat = (0, exec_1.runBinary)(ADB, this.withSerial(['exec-out', 'cat', path]));
             const xml = cat.stdout.toString('utf8');
             if (xml.includes('<hierarchy'))
                 return xml;
             lastErr = `${dump.stdout} ${dump.stderr} ${cat.stderr}`.replace(/\s+/g, ' ').trim();
+            // No window is not a failed capture — it is a successful reading of a screen that has
+            // nothing on it yet. Retrying it here just spends someone else's wait budget three
+            // times as fast; hand it up to whoever knows how long they are willing to wait.
+            if (NULL_ROOT.test(lastErr)) {
+                throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch). ' +
+                    'Retry, or use a command that waits (`vk wait`, or any selector lookup).');
+            }
+            // A companion holds the device's ONE UiAutomation connection and SIGKILLs anything
+            // else that wants it — including this dump. It outlives the process that started it,
+            // so a later command that never opted in would fail for as long as it lives. Ask it
+            // to let go and try again: verikun's own helper must not be why verikun cannot read
+            // the screen. No companion running is the normal case and costs one refused connect.
+            if (attempt === 0)
+                (0, manager_1.releaseCompanionOn)(this.resolvedSerial());
         }
         throw new errors_1.CliError(`Failed to capture UI hierarchy after 3 attempts. ${lastErr}\n` +
             'Tip: disable animations (`verikun doctor --fix`) and ensure the screen is idle.', 3);
@@ -265,6 +337,38 @@ class AdbDriver {
         }
         return r.stdout;
     }
+    /**
+     * `screencap` without `-p`: the framebuffer as-is, skipping the on-device PNG
+     * encode that dominates a capture (MEASURED on an SM-A415F: 2.50s with `-p`,
+     * 1.04s without — the bigger transfer is far cheaper than the deflate it avoids).
+     *
+     * Returns null rather than throwing on anything unexpected, so an OEM or Android
+     * version that lays the buffer out differently silently falls back to the PNG
+     * path. Getting a wrong-but-plausible image would be far worse than being slow.
+     */
+    screenshotRaw() {
+        const r = (0, exec_1.runBinary)(ADB, this.withSerial(['exec-out', 'screencap']));
+        const buf = r.stdout;
+        if (buf.length < RAW_HEADER_SIZES[0])
+            return null;
+        const width = buf.readUInt32LE(0);
+        const height = buf.readUInt32LE(4);
+        const format = buf.readUInt32LE(8);
+        // Only RGBA_8888 — the one format every `screencap` we have seen emits, and the
+        // only one whose channel order we can assume without guessing.
+        if (format !== PIXEL_FORMAT_RGBA_8888)
+            return null;
+        if (width < 1 || height < 1)
+            return null;
+        const pixelBytes = width * height * 4;
+        // Android 9 added a colorspace word, so the header is 16 bytes on anything
+        // modern and 12 before that. Pick whichever the payload length agrees with
+        // rather than branching on an OS version we would have to go and ask for.
+        const header = RAW_HEADER_SIZES.find((size) => buf.length - size === pixelBytes);
+        if (header === undefined)
+            return null;
+        return { width, height, ch: 4, pixels: buf.subarray(header) };
+    }
     screenSize() {
         const out = this.shell(['wm', 'size']);
         const lines = out.split('\n');

package/dist/errors.js

@@ -6,7 +6,7 @@
 //   2  usage error or ambiguous selector (caller must refine)
 //   3  environment error (adb/simctl missing, no/multiple devices, dump failed)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousSelectorError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
+exports.AmbiguousSelectorError = exports.NoWindowError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
 exports.isEnvError = isEnvError;
 class CliError extends Error {
     exitCode;
@@ -53,6 +53,28 @@ class SelectorNotFoundError extends CliError {
     }
 }
 exports.SelectorNotFoundError = SelectorNotFoundError;
+/**
+ * There is no window to read right now — the app was just force-stopped, or is mid-launch
+ * and has not drawn yet. `getRootInActiveWindow()` returns null and the platform says so.
+ *
+ * This is an OBSERVATION about the screen, not a broken machine, and the difference matters:
+ * it clears on its own within a second or two. Every caller that has a wait budget absorbs it
+ * and polls again; only a caller with no budget lets it surface (exit 3, unchanged).
+ *
+ * MEASURED, and this class exists because of it: `launch --clear` leaves a gap with no
+ * window, and the old code escalated that to a fatal environment error after three capture
+ * attempts. With the slow stock dump those three attempts spanned 7-14s and usually outlasted
+ * the gap by accident; once the companion made a read ~0.2s they were spent in under a second,
+ * and a `wait --timeout 120000` would abort at ~20s with 100 seconds of its budget unspent.
+ * The retry belongs to the caller that knows how long it is willing to wait.
+ */
+class NoWindowError extends CliError {
+    constructor(message) {
+        super(message, 3);
+        this.name = 'NoWindowError';
+    }
+}
+exports.NoWindowError = NoWindowError;
 /** Selector matched >1 element. Exit 2. Carries the candidates so the agent runner
  *  can ask the model to disambiguate (a heal trigger) instead of aborting. */
 class AmbiguousSelectorError extends CliError {

package/dist/image.js

@@ -12,9 +12,14 @@
 // (palette, 16-bit, interlaced) is left untouched and reported via `reason`,
 // so a screenshot is never corrupted, only (sometimes) not shrunk.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.pngFromRaw = pngFromRaw;
 exports.downscalePng = downscalePng;
 const node_zlib_1 = require("node:zlib");
 const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** PNG color type for a channel count, mirroring `channelsFor`. */
+function colorTypeFor(ch) {
+    return ch === 1 ? 0 : ch === 2 ? 4 : ch === 3 ? 2 : 6;
+}
 /** Channel count for a supported PNG color type, or 0 if unsupported (e.g. palette). */
 function channelsFor(colorType) {
     switch (colorType) {
@@ -142,6 +147,41 @@ function buildPng(w, h, bitDepth, colorType, idat) {
     // compression, filter, interlace methods are all 0 (the only standard values)
     return Buffer.concat([PNG_SIG, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);
 }
+/**
+ * Encode raw pixels to a PNG, box-downscaling to `maxEdge` first when the image is
+ * bigger (`null` = encode at full size). The counterpart to `downscalePng` for a
+ * backend that can hand over pixels directly.
+ *
+ * Skipping the device-side PNG encode is the point, and it is worth much more than
+ * the compression: MEASURED on an SM-A415F, `screencap -p` costs 2.50s while raw
+ * `screencap` costs 1.04s — the phone spends ~1.4s deflating an image we then
+ * immediately re-encode smaller anyway. Moving that work to the host costs almost
+ * nothing (10MB of RGBA box-downscales in ~10ms and deflates in ~110ms), so both
+ * the default and `--full` paths come out well ahead.
+ */
+function pngFromRaw(img, maxEdge) {
+    const { width, height, ch, pixels } = img;
+    const colorType = colorTypeFor(ch);
+    const encode = (w, h, px) => buildPng(w, h, 8, colorType, (0, node_zlib_1.deflateSync)(applyNoneFilter(px, w, h, ch)));
+    const full = (reason) => ({
+        buf: encode(width, height, pixels),
+        width, height, scaled: false, origWidth: width, origHeight: height, reason,
+    });
+    if (maxEdge === null)
+        return full();
+    if (!(maxEdge >= 1))
+        return full('no target size');
+    if (Math.max(width, height) <= maxEdge)
+        return full('already within target');
+    const scale = maxEdge / Math.max(width, height);
+    const tw = Math.max(1, Math.round(width * scale));
+    const th = Math.max(1, Math.round(height * scale));
+    const small = boxDownscale(pixels, width, height, tw, th, ch);
+    return {
+        buf: encode(tw, th, small),
+        width: tw, height: th, scaled: true, origWidth: width, origHeight: height,
+    };
+}
 /**
  * Downscale a PNG so its longest edge is at most `maxEdge` px (never upscales).
  * Returns the original buffer unchanged when it is already small enough or is in

package/dist/run.js

@@ -16,6 +16,7 @@ const format_1 = require("./ui/format");
 const errors_1 = require("./errors");
 const output_1 = require("./output");
 const report_1 = require("./report");
+const capture_1 = require("./capture");
 // Commands that become a recorded step (a JUnit testcase). Inspection commands
 // (ui, find, devices, doctor, current) are deliberately excluded — they are how
 // an agent decides what to do, not assertions about the app. `log` is the one
@@ -477,7 +478,9 @@ class Recorder {
         if (!driver)
             return;
         try {
-            this.writeArtifact(failImagePath(this.step.index), driver.screenshot());
+            // Full resolution on purpose — a human reads this in the report — but via the
+            // raw path, which reaches the same PNG without the device-side encode.
+            this.writeArtifact(failImagePath(this.step.index), (0, capture_1.capturePng)(driver, null).buf);
             this.step.failImage = failImagePath(this.step.index);
         }
         catch (e) {

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.20.0';
+exports.VERSION = '0.21.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",
@@ -30,7 +30,8 @@
     "dist",
     "CHANGELOG.md",
     ".claude/skills/verikun/SKILL.md",
-    "example/*.md"
+    "example/*.md",
+    "tools/verikun-companion/prebuilt/*.jar"
   ],
   "scripts": {
     "prebuild": "node scripts/gen-version.mjs",