verikun 0.21.0 → 0.21.1

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

@@ -275,7 +275,13 @@ to set it up, then every read after is fast. Nothing to enable.
 It holds the device's single `UiAutomation` connection while it runs, so Appium and Layout
 Inspector cannot attach. If the user needs those, tell them `VERIKUN_COMPANION=0` or
 `vk companion stop` — don't disable it pre-emptively. A failure never breaks a run: verikun
-falls back to the slower stock read on its own.
+falls back to the slower stock read on its own, and retries the fast path a minute later.
+
+Over `--server` the same applies, but the setting lives on the **server**: reads execute
+there, so `VERIKUN_COMPANION` is read in the server's environment and `vk companion` has no
+`--server` form. If a remote run feels slow (~2.4s a step on Android), don't guess — ask:
+`curl -s "$VERIKUN_SERVER/v1/health" | jq .reads` reports the read path and why. Every
+`--server` run also prints it once at start.
 
 **Remember identifiers across runs.** After a flow succeeds, save the selectors
 you found to memory — the mapping from human intent to selector, plus the screen

package/CHANGELOG.md

@@ -6,6 +6,90 @@ 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

package/dist/cli.js

@@ -1603,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: {
@@ -1630,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 },
     };
 }
 /**
@@ -1934,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);
@@ -1942,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`).

package/dist/companion/manager.js

@@ -9,6 +9,7 @@
 // therefore gets the companion off the connection BEFORE the caller falls back.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Companion = void 0;
+exports.nullRootAction = nullRootAction;
 exports.companionJarPath = companionJarPath;
 exports.companionEnabled = companionEnabled;
 exports.releaseCompanionOn = releaseCompanionOn;
@@ -42,6 +43,64 @@ 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;
+/**
+ * How long a TRANSIENT stand-down suppresses the companion before it is retried.
+ *
+ * The point of a stand-down is that re-probing on every read would cost more than the stock
+ * dump it avoids — but "never again" is only correct for a process that exits after one
+ * command. `vk server` runs for days, and the companion shuts ITSELF down after 15 minutes
+ * idle, so a daemon that latched off permanently spent the rest of its life on the 2.4s path
+ * next to a perfectly healthy companion (issue #77). One retry a minute is cheap enough to be
+ * invisible and frequent enough that a suite recovers within its first test.
+ */
+const TRANSIENT_RETRY_MS = 60000;
+/**
+ * How long a run of null-root replies must last before the connection is suspected of being
+ * wedged rather than the screen being genuinely blank.
+ *
+ * A real mid-launch gap resolves in well under this; a stale UiAutomation connection never
+ * does. MEASURED on a Pixel 3a: after `vk launch` force-stops and restarts the app, the
+ * companion returned a null root for 30s+ while a stock dump read the same screen fine.
+ */
+const WEDGE_AFTER_MS = 3000;
+/**
+ * How long a null-root fallback suppresses the companion — much shorter than a companion
+ * failure, because the cause is different in kind.
+ *
+ * A fallback here means a freshly re-acquired connection still saw no window, which is most
+ * often an app that genuinely has not drawn yet. That clears the moment it does, so the 60s
+ * used for a real companion fault would spend the rest of a launch on the 2.4s path for no
+ * reason. Long enough to let the stock dump answer without immediately re-taking the
+ * connection from under it; short enough that the companion is back within one auto-wait.
+ */
+const NULL_ROOT_RETRY_MS = 2000;
+const NOT_RUNNING = 'not running';
+/**
+ * What to do about a null root, given how long the current run of them has lasted.
+ *
+ * Pure so the escalation can be unit-tested without a device. The order matters and each step
+ * is deliberately conservative:
+ *   - `propagate` — the normal case. A null root is the DEVICE having no window (mid-launch,
+ *     force-stopped), not a companion fault, so it goes up to the caller's auto-wait.
+ *   - `recycle`  — long enough to be suspicious. Release and re-acquire the connection, which
+ *     is exactly what unwedges it, and cheap (~1.05s) relative to being wrong.
+ *   - `fallback` — recycling did not help. Hand the connection back and let the stock dump
+ *     answer. It can read screens the wedged companion cannot, and a slow read beats a
+ *     selector command failing on a screen that is plainly there.
+ *
+ * Once a recycle has happened, the NEXT null root falls back immediately rather than waiting
+ * out another interval. The recycle IS the test — a connection that was just released and
+ * re-acquired has no staleness left to explain the answer — so more elapsed time tells us
+ * nothing new, and waiting for it is not free: selector commands default to a 5s auto-wait,
+ * so any second threshold beyond the ~1.05s recycle risks the window closing first. That
+ * would fail the command with "no window" on a readable screen without ever trying the stock
+ * dump, which is the exact failure this escalation exists to prevent.
+ */
+function nullRootAction(runMs, alreadyRecycled) {
+    if (alreadyRecycled)
+        return 'fallback';
+    return runMs < WEDGE_AFTER_MS ? 'propagate' : 'recycle';
+}
 /** 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. */
@@ -95,15 +154,31 @@ function releaseCompanionOn(serial) {
 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;
+    /** Off for the rest of this process, for a reason that CANNOT change while it runs: this
+     *  device's note says the companion does not work here, or there is no jar to push. */
+    declined = false;
+    /** Off until this timestamp, for a reason that might. Re-probing per read would cost more
+     *  than the stock dump it avoids, but never retrying is only right for a process that
+     *  exits after one command — see TRANSIENT_RETRY_MS. */
+    retryAfter = 0;
     dims;
+    /** When the current unbroken run of null-root replies started (0 = not in one), and
+     *  whether this run has already spent its one connection recycle. See nullRootAction. */
+    nullRootSince = 0;
+    nullRootRecycled = false;
     constructor(deps) {
         this.deps = deps;
         this.port = (0, protocol_1.portForSerial)(deps.serial);
     }
+    /** Why the companion is not serving reads right now, for `/v1/health` and `vk companion
+     *  status`. Null when it is available (or would be on the next read). */
+    suppressedReason() {
+        if (this.declined)
+            return 'declined on this device';
+        if (Date.now() < this.retryAfter)
+            return 'standing by after a failure';
+        return null;
+    }
     adb(args, timeout = 15000) {
         return (0, exec_1.runText)(this.deps.adb, ['-s', this.deps.serial, ...args], { timeout });
     }
@@ -135,37 +210,97 @@ class Companion {
      * work rather than being SIGKILLed.
      */
     dump(idleMs) {
-        if (this.unusable)
+        if (this.declined || Date.now() < this.retryAfter)
             return null;
-        try {
-            if (!this.dims) {
-                this.dims = this.ensureReady();
-                if (!this.dims)
-                    return null;
+        // TWO attempts, because a dead companion is routine rather than exceptional: it shuts
+        // itself down after 15 minutes idle, which any long-lived process (`vk server`, a slow
+        // suite) will outlive. The first attempt can therefore fail purely because `dims` is
+        // cached from before that shutdown; clearing it sends the second attempt through
+        // ensureReady(), which restarts from the device note in ~2.1s. Without this the process
+        // stood down permanently and never touched the companion again (issue #77).
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                return this.attemptDump(idleMs);
             }
-            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).');
+            catch (e) {
+                if (e instanceof errors_1.NoWindowError)
+                    throw e; // the screen's state, not the companion's
+                if (attempt === 0 && this.dims) {
+                    this.dims = undefined;
+                    continue;
                 }
-                throw new Error(detail);
+                this.standDown(`companion dump failed (${e.message})`, 'transient');
+                return null;
             }
-            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;
+        return null;
+    }
+    /** One read attempt. Throws NoWindowError for a blank screen, anything else for a
+     *  companion that could not serve the read. */
+    attemptDump(idleMs) {
+        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';
+            if (NULL_ROOT_REPLY.test(detail))
+                return this.onNullRoot(idleMs);
+            throw new Error(detail);
+        }
+        // A hierarchy came back, so whatever run of null roots preceded it is over.
+        this.nullRootSince = 0;
+        this.nullRootRecycled = false;
+        return reply.toString('utf8');
+    }
+    /**
+     * A null root is USUALLY the device having no window — mid-launch, or force-stopped — and
+     * standing down for it would release a healthy connection and drop the whole process onto
+     * the 2.4s path after every `launch --clear`.
+     *
+     * But it is not always. A long-lived UiAutomation connection can go stale and return null
+     * forever for a window that is plainly there: MEASURED on a Pixel 3a, 30s+ of null roots
+     * after `vk launch` while a stock dump read the screen fine. Because this error propagates
+     * rather than standing down, that state never self-healed and every selector command burned
+     * its full auto-wait and failed on a readable screen. So escalate by duration.
+     */
+    onNullRoot(idleMs) {
+        const now = Date.now();
+        if (!this.nullRootSince)
+            this.nullRootSince = now;
+        switch (nullRootAction(now - this.nullRootSince, this.nullRootRecycled)) {
+            case 'recycle':
+                this.nullRootRecycled = true;
+                (0, output_1.err)('[verikun] companion has reported no window for a while; recycling the connection');
+                if (this.recycleConnection())
+                    return this.attemptDump(idleMs);
+                break;
+            case 'fallback':
+                // Recycling did not help and the stock dump may well read this screen. Being slow is
+                // always better than failing a selector on a screen that is there.
+                this.standDown('companion still reports no window after a recycle; using the stock path', 'screen');
+                return null;
+            case 'propagate':
+                break;
+        }
+        throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch).');
+    }
+    /** Hand the UiAutomation connection back and take it again. The one thing measured to clear
+     *  a stale connection — it is what the stock path's releaseCompanionOn() does by accident. */
+    recycleConnection() {
+        try {
+            (0, protocol_1.requestSync)(this.port, 'release', 5000);
+            (0, protocol_1.requestSync)(this.port, 'acquire', 20000);
+            return true;
+        }
+        catch {
+            return false;
         }
     }
     /** Get a calibrated companion running, or give up for this process. */
@@ -189,7 +324,10 @@ class Companion {
         // single command a doomed start attempt now that this is on by default.
         const note = this.readDeviceNote();
         if (note === 'unsupported') {
-            this.unusable = true;
+            // TERMINAL: this is a recorded fact about the phone, and it cannot become false while
+            // this process runs. Retrying it would be the doomed start attempt per command that the
+            // note exists to prevent.
+            this.declined = true;
             return undefined;
         }
         return this.startAndCalibrate(note, live);
@@ -218,9 +356,17 @@ class Companion {
             //   - 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)
+            const jar = companionJarPath();
+            const deviceIsAtFault = jar && !this.probeState().usable;
+            if (deviceIsAtFault)
                 this.writeDeviceNote('unsupported');
-            this.unusable = true;
+            // Only the two facts that cannot change under a running process are terminal. A start
+            // that failed for any OTHER reason — most often the cold-start collision above — must
+            // stay retryable, or one unlucky moment costs a daemon every read it will ever do.
+            if (deviceIsAtFault || !jar)
+                this.declined = true;
+            else
+                this.retryAfter = Date.now() + TRANSIENT_RETRY_MS;
             return undefined;
         }
         // A remembered verdict skips calibration entirely — worth ~4.7s of the cold start, and
@@ -262,7 +408,7 @@ class Companion {
             return true;
         }
         catch (e) {
-            this.standDown(`companion could not reacquire the connection (${e.message})`);
+            this.standDown(`companion could not reacquire the connection (${e.message})`, 'transient');
             return false;
         }
     }
@@ -347,17 +493,37 @@ class Companion {
             // 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');
+            // TRANSIENT precisely because "the screen moved" is the usual cause: a daemon that
+            // treated one moving screen as a permanent verdict spent its whole life on the stock
+            // path, which is the likeliest origin of issue #77's "no speedup at all".
+            this.standDown('companion output did not match the platform dump; using the stock path', 'transient');
             return undefined;
         }
         catch (e) {
-            this.standDown(`companion calibration failed (${e.message})`);
+            this.standDown(`companion calibration failed (${e.message})`, 'transient');
             return undefined;
         }
     }
-    /** Hand the UiAutomation connection back, and stop using the companion in this process. */
-    standDown(reason) {
-        this.unusable = true;
+    /**
+     * Hand the UiAutomation connection back, and stop using the companion — for as long as the
+     * cause plausibly lasts:
+     *   - `terminal`  — for the rest of the process; the cause cannot change while it runs.
+     *   - `transient` — a minute; the companion itself failed.
+     *   - `screen`    — a couple of seconds; the *screen* had no window, which clears on its own.
+     *
+     * Releasing FIRST is the load-bearing half: while the companion holds the connection the
+     * stock dump is not slower, it is SIGKILLed, and the caller is about to depend on it.
+     */
+    standDown(reason, kind) {
+        if (kind === 'terminal')
+            this.declined = true;
+        else
+            this.retryAfter = Date.now() + (kind === 'screen' ? NULL_ROOT_RETRY_MS : TRANSIENT_RETRY_MS);
+        // Force a fresh ensureReady() on the retry: whatever `dims` said is exactly what stopped
+        // working, and the note-based restart is what recovers it.
+        this.dims = undefined;
+        this.nullRootSince = 0;
+        this.nullRootRecycled = false;
         (0, output_1.err)(`[verikun] ${reason}`);
         try {
             (0, protocol_1.requestSync)(this.port, 'release', 4000);
@@ -385,12 +551,17 @@ class Companion {
     }
     /** For `vk companion status`. */
     describe() {
+        const state = this.stateSummary();
+        return state === NOT_RUNNING ? state : `running on port ${this.port} (${state})`;
+    }
+    /** Just the device-side state (`ready app held`, or `not running`), for embedding in a
+     *  one-line read-path report. */
+    stateSummary() {
         try {
-            const state = (0, protocol_1.requestSync)(this.port, 'state', 4000).toString('utf8').trim();
-            return `running on port ${this.port} (${state})`;
+            return (0, protocol_1.requestSync)(this.port, 'state', 4000).toString('utf8').trim();
         }
         catch {
-            return 'not running';
+            return NOT_RUNNING;
         }
     }
 }

package/dist/drivers/adb.js

@@ -279,6 +279,18 @@ class AdbDriver {
         }
         return this.companion;
     }
+    /** Which read path the next getElements() will take. See `Driver.hierarchySource`. */
+    hierarchySource() {
+        if (!(0, manager_1.companionEnabled)())
+            return { path: 'stock', detail: 'companion off (VERIKUN_COMPANION)' };
+        const companion = this.companionOrNull();
+        if (!companion)
+            return { path: 'stock', detail: 'companion unavailable' };
+        const suppressed = companion.suppressedReason();
+        if (suppressed)
+            return { path: 'stock', detail: `companion ${suppressed}` };
+        return { path: 'companion', detail: companion.stateSummary() };
+    }
     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 —

package/dist/server.js

@@ -35,11 +35,28 @@ const promises_1 = require("node:stream/promises");
 const args_1 = require("./args");
 const errors_1 = require("./errors");
 const drivers_1 = require("./drivers");
+const manager_1 = require("./companion/manager");
 const output_1 = require("./output");
 const ir_1 = require("./agent/ir");
 const rpc_1 = require("./rpc");
 const cli_1 = require("./cli");
 const version_1 = require("./version");
+/**
+ * A driver's read path, or null when the backend has no opinion (iOS reads through idb, one
+ * way only) or the probe failed.
+ *
+ * Best-effort on purpose. It is reported on `/v1/health`, which is also how a client checks
+ * the server is reachable at all — a companion probe must never be the reason that answer
+ * cannot be given.
+ */
+function safeHierarchySource(driver) {
+    try {
+        return driver.hierarchySource?.() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 const DEFAULT_PORT = 8391;
 const EXEC_BODY_CAP = 1024 * 1024; // 1 MB of JSON is far beyond any leaf command
 const INSTALL_BODY_CAP = 512 * 1024 * 1024; // 512 MB app build
@@ -262,12 +279,14 @@ function buildServer(config) {
             if (config.authKey && req.headers.authorization && !authorized(req)) {
                 throw new HttpError(401, 'invalid auth key');
             }
+            const reads = safeHierarchySource(config.driver);
             const health = {
                 ok: true,
                 version: version_1.VERSION,
                 platform: config.platform,
                 serial: config.serial,
                 installEnabled: config.allowInstall,
+                ...(reads ? { reads } : {}),
             };
             sendJson(res, 200, health);
             return;
@@ -369,6 +388,11 @@ async function cmdServer(positionals, flags) {
         server.listen(port, bind, () => {
             (0, output_1.err)(`[server] verikun ${version_1.VERSION} listening on http://${bind}:${port}`);
             (0, output_1.err)(`[server] device: ${platform} · ${serial}`);
+            // Say the read path out loud. It is the difference between a suite that takes 8s and
+            // one that takes 43s, and it used to be invisible from both ends (issue #77).
+            const reads = safeHierarchySource(driver);
+            if (reads)
+                (0, output_1.err)(`[server] reads: ${reads.path} (${reads.detail})`);
             (0, output_1.err)(`[server] install endpoint: ${allowInstall ? 'ENABLED (--allow-install)' : 'disabled (pass --allow-install to accept builds)'}`);
             if (generated) {
                 (0, output_1.err)('[server] auth key generated for this session — clients pass it via VERIKUN_SERVER_AUTH_KEY or --auth-key:');
@@ -386,6 +410,11 @@ async function cmdServer(positionals, flags) {
         });
         const close = () => {
             (0, output_1.err)('[server] shutting down');
+            // Hand the device's ONE UiAutomation connection back. The companion outlives the
+            // process that started it and would otherwise keep the connection for up to its full
+            // 15-minute idle window, blocking Appium, Layout Inspector and TalkBack on this host —
+            // with no obvious cause, and no way to stop it from a `--server` client.
+            (0, manager_1.releaseCompanionOn)(serial);
             server.close();
             resolve(0);
         };

package/dist/suite.js

@@ -310,6 +310,7 @@ async function cmdSuite(dirArg, flags, deps) {
         platform: deps.platform,
         device: deps.device,
         verikun: version_1.VERSION,
+        ...(deps.server ? { server: deps.server } : {}),
         totals: (0, report_1.suiteTotals)(results),
         tests: results,
         ...(aborted ? { aborted } : {}),

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.21.0';
+exports.VERSION = '0.21.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "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",
@@ -36,6 +36,7 @@
   "scripts": {
     "prebuild": "node scripts/gen-version.mjs",
     "build": "tsc",
+    "postbuild": "node scripts/chmod-bin.mjs",
     "dev": "tsc --watch",
     "verikun": "node dist/bin/verikun.js",
     "test": "tsc -p tsconfig.test.json && node --test --test-reporter=spec .test-build/tests/*.test.js",