verikun 0.26.3 → 0.27.0

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

@@ -37,15 +37,20 @@ examples below use `vk`.
 ## Before you start (once per session)
 
 Run `vk doctor` once before the first device command. Alongside the adb/device checks it
-reports version staleness on stderr — it never fails on that, so treat it as information:
+reports version staleness and host problems on stderr — it never fails on those, so treat
+them as information:
 
 - **`claude-code-plugin: … behind this CLI`** → **this skill file is out of date.** Trust
   `vk --help` over what you read here when they disagree, and tell the user to run
   `claude plugin update verikun@verikun` and restart Claude Code.
 - **`verikun: … npm has <newer>`** → tell the user `npm install -g verikun@latest`.
+- **`adb server: … leaking USB handles`** → **the host's adb server has rotted.** Devices
+  will drop mid-flow for reasons that look like your selectors failing. Tell the user to run
+  `adb kill-server && adb start-server` — safe, and devices reconnect in seconds.
 
 **Tell the user, don't run it.** Upgrading changes their machine, and the plugin path needs
-a Claude Code restart to take effect. Mention it once and move on.
+a Claude Code restart to take effect; restarting adb is host-wide and drops every device on
+the machine, not just yours. Mention it once and move on.
 
 ## The loop: act → inspect → assert
 

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-09-13
+
+### Added
+- **`vk doctor`** warns when the host's adb server has leaked USB handles, naming the restart that fixes it.
+- **`vk server`** restarts a rotted adb server while idle; `VERIKUN_NO_ADB_RECYCLE=1` opts out.
+
+### Changed
+- **Docs**: every page trimmed to what a reader needs; history and design rationale removed, gotchas kept, open issues linked.
+
 ## [0.26.3] - 2026-09-11
 
 A `vk ai` test's description is no longer compiled into steps of its own.

package/README.md

@@ -8,7 +8,7 @@
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
 - **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. A compile that does not cover its test is rejected rather than cached as a pass. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
-- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad.
+- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad — including restarting a host adb server that has started dropping them.
 
 ```
 $ vk ui

package/dist/adb-health.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Is the HOST's adb server healthy, or has it rotted?
+ *
+ * A long-lived adb server leaks IOKit Mach ports and never recovers. Measured on macOS
+ * 2026-09-12: a 9-day-old server logging EXC_GUARD `GUARD_TYPE_MACH_PORT` / `INVALID_NAME`
+ * at 2/sec — 27,983 in 7h, every one of them from the adb pid — having burned 92 minutes
+ * of CPU on the error loop. `adb kill-server && adb start-server` took it to zero and every
+ * device came back in ~5s.
+ *
+ * WHY VERIKUN CARES, rather than leaving this to the operator: adb rot DEFEATS DEVICE
+ * FAILOVER. `device/failover.ts` moves the server off a device that fails, but every
+ * candidate sits behind the same host adb — so when the transport is what broke, failover
+ * walks the pool retiring healthy phones for a host-side fault. That is the same polarity
+ * error `ARTIFACT_RULES` exists to prevent on the install path: enumerate the thing you can
+ * actually attribute, and never blame the open-ended side.
+ *
+ * THE RATE IS A LEAKED-HANDLE COUNTER, which is what makes this measurable rather than
+ * guessed. adb scans USB at ~1Hz and each STALE device handle throws one violation per
+ * pass, so the per-minute count reads directly as "how many handles adb has leaked". It
+ * stepped 59 -> 118/min at the exact second a device re-enumerated, and never came back
+ * down. A healthy server sits at exactly 0.
+ *
+ * EVIDENCE, NEVER AGE, is the trigger — see `adbServerRotting`. Age alone would restart a
+ * perfectly good server, which for a default-on behaviour is a new way to fail; the whole
+ * point of a measured signal is that a healthy host is never disturbed.
+ *
+ * macOS-only, and that is honest rather than lazy: EXC_GUARD and Mach ports do not exist on
+ * Linux, and the rot has not been measured there. Everywhere else this reports `undefined`
+ * and every caller degrades to doing nothing — never to a blind restart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIOLATION_WINDOW_MS = void 0;
+exports.parseEtime = parseEtime;
+exports.countViolations = countViolations;
+exports.adbServerRotting = adbServerRotting;
+exports.describeRot = describeRot;
+exports.adbRecycleEnabled = adbRecycleEnabled;
+exports.adbServerHealth = adbServerHealth;
+exports.adbHealthProbe = adbHealthProbe;
+exports.recycleAdbServer = recycleAdbServer;
+const node_os_1 = require("node:os");
+const exec_1 = require("./exec");
+/** The window we count violations over. Long enough that a ~1Hz loop is unmissable, short
+ *  enough that `log show` stays ~1s (measured: 1.2s for 2m). */
+exports.VIOLATION_WINDOW_MS = 2 * 60 * 1000;
+/**
+ * `log`'s own absolute path, not a bare `log`. Belt-and-braces against a shadowing shell
+ * function (the author hit exactly that while investigating: `log` was a zsh function and
+ * every query failed with "too many arguments"). We spawn without a shell so this cannot
+ * bite us today, but the absolute path costs nothing and documents the hazard.
+ */
+const LOG_BIN = '/usr/bin/log';
+/**
+ * Match the kernel's report of adb's guard violations, and NOTHING else.
+ *
+ * All three clauses are load-bearing. Without `process == "kernel"` this matches unrelated
+ * processes; without the `[adb:` clause it matches any process's guard violations, and a
+ * host with an unrelated misbehaving binary would be told its adb had rotted. The line the
+ * kernel actually emits:
+ *
+ *   ERROR: [adb:96399] EXC_GUARD AST: type=0x1 flavor=0x200 target=0x24d7 ...
+ */
+const VIOLATION_PREDICATE = 'process == "kernel" AND eventMessage CONTAINS "EXC_GUARD" AND eventMessage CONTAINS "[adb:"';
+/**
+ * `ps -o etime=` elapsed time -> ms. Formats, narrowest first: `MM:SS`, `HH:MM:SS`,
+ * `DD-HH:MM:SS`. Returns undefined rather than throwing on anything unrecognised — this
+ * feeds an advisory, and a parse failure must degrade to silence, never to a wrong number.
+ */
+function parseEtime(raw) {
+    const s = raw.trim();
+    if (!s)
+        return undefined;
+    const [days, clock] = s.includes('-') ? s.split('-', 2) : ['0', s];
+    const parts = clock.split(':');
+    if (parts.length < 2 || parts.length > 3)
+        return undefined;
+    // Test the DIGITS, not Number(): `Number('')` is 0, not NaN, so a leading '-' ("-5:00")
+    // would otherwise parse as a happy five minutes instead of being rejected.
+    const fields = [days, ...parts];
+    if (!fields.every((f) => /^\d+$/.test(f)))
+        return undefined;
+    const nums = fields.map((f) => Number(f));
+    const [d, ...rest] = nums;
+    const [h, m, sec] = rest.length === 3 ? rest : [0, ...rest];
+    return ((d * 24 + h) * 60 * 60 + m * 60 + sec) * 1000;
+}
+/**
+ * Count real events in `log show --style compact` output.
+ *
+ * It ALWAYS prints a `Timestamp Ty Process[PID:TID]` header, so a naive line count reports
+ * 1 on a perfectly healthy host — which would make every caller cry rot forever. Counting
+ * only lines that name adb is both the fix and a second guard on the predicate.
+ */
+function countViolations(stdout) {
+    return stdout.split('\n').filter((l) => l.includes('[adb:')).length;
+}
+/**
+ * Has this adb server rotted? Evidence only.
+ *
+ * A healthy server produces EXACTLY zero over the window (measured repeatedly on a freshly
+ * restarted one), and a rotted one produces 60-120 per minute — there is no middle ground
+ * to tune a threshold against, so any nonzero count is the signal. `undefined` violations
+ * (not macOS, or the query failed) is NEVER rot: we do not restart on a hunch.
+ */
+function adbServerRotting(health) {
+    return (health.violations ?? 0) > 0;
+}
+/** One line a human can act on, or undefined when there is nothing worth saying. */
+function describeRot(health) {
+    if (!adbServerRotting(health))
+        return undefined;
+    const perMin = Math.round((health.violations / (health.windowMs ?? exports.VIOLATION_WINDOW_MS)) * 60_000);
+    const age = health.ageMs !== undefined ? `, up ${Math.floor(health.ageMs / 3_600_000)}h` : '';
+    return `adb server is leaking USB handles (~${perMin} kernel guard violations/min${age}) — devices will drop`;
+}
+/**
+ * Is the idle adb-server recycle active? ONE definition, because two callers ask — the
+ * server's timer and its startup banner — and a banner that disagrees with the behaviour is
+ * worse than no banner at all.
+ *
+ * Android only: `adb` is the only transport that rots this way, so an iOS server never pays
+ * for the check. On by default (`vk server` is built to sit on a CI host for days, which is
+ * the condition that rots it); `VERIKUN_NO_ADB_RECYCLE=1` restores the previous behaviour
+ * exactly, for the rare host running other adb work alongside the server.
+ */
+function adbRecycleEnabled(platform) {
+    return platform === 'android' && process.env.VERIKUN_NO_ADB_RECYCLE !== '1';
+}
+/** The running adb server's pid. Undefined when there is none, or when `pgrep` is absent. */
+function adbServerPid() {
+    try {
+        // `adb -L tcp:5037 fork-server server` is the canonical argv; match loosely so a
+        // non-default port or an ADB_SERVER_SOCKET still resolves.
+        const r = (0, exec_1.runText)('pgrep', ['-f', 'adb.*fork-server'], { timeout: 5000 });
+        const pid = Number(r.stdout.split('\n')[0]?.trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How long pid has been running, via `ps -o etime=`. */
+function processAgeMs(pid) {
+    try {
+        const r = (0, exec_1.runText)('ps', ['-p', String(pid), '-o', 'etime='], { timeout: 5000 });
+        return parseEtime(r.stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Survey the host's adb server. Never throws: every probe is wrapped, and an unavailable
+ * signal comes back `undefined` so callers do nothing rather than something wrong.
+ */
+function adbServerHealth(windowMs = exports.VIOLATION_WINDOW_MS) {
+    const pid = adbServerPid();
+    const health = { pid, ageMs: pid ? processAgeMs(pid) : undefined };
+    if ((0, node_os_1.platform)() !== 'darwin' || !pid)
+        return health;
+    try {
+        const secs = Math.max(1, Math.round(windowMs / 1000));
+        const r = (0, exec_1.runText)(LOG_BIN, ['show', '--last', `${secs}s`, '--style', 'compact', '--predicate', VIOLATION_PREDICATE], {
+            timeout: 20000,
+        });
+        if (r.code !== 0)
+            return health;
+        return { ...health, violations: countViolations(r.stdout), windowMs };
+    }
+    catch {
+        return health; // log(1) missing, sandboxed, or slow — no opinion, not a failure
+    }
+}
+/**
+ * The `vk doctor` line. ADVISORY, always: a rotted adb server is a thing to fix, not a
+ * machine that cannot drive a device, and exit 3 is reserved for the latter. Returns null
+ * when there is nothing to say, so doctor stays quiet on a healthy host.
+ */
+function adbHealthProbe(health = adbServerHealth()) {
+    const detail = describeRot(health);
+    if (!detail)
+        return null;
+    return {
+        name: 'adb server',
+        ok: true,
+        advisory: true,
+        detail,
+        hint: 'restart it: `adb kill-server && adb start-server` (safe; devices reconnect in a few seconds)',
+    };
+}
+/**
+ * Restart the host's adb server. Returns whether it came back.
+ *
+ * HOST-GLOBAL and therefore never called speculatively — `kill-server` drops every
+ * transport on the machine, including devices this process does not own. Callers must have
+ * evidence (`adbServerRotting`) and, on the server, an idle pool.
+ */
+function recycleAdbServer(adb) {
+    try {
+        (0, exec_1.runText)(adb, ['kill-server'], { timeout: 20000 });
+        const r = (0, exec_1.runText)(adb, ['start-server'], { timeout: 30000 });
+        return r.code === 0;
+    }
+    catch {
+        return false; // never a new way to fail: the caller logs and carries on
+    }
+}

package/dist/cli.js

@@ -93,6 +93,7 @@ const suite_1 = require("./suite");
 const failover_1 = require("./device/failover");
 const wait_1 = require("./wait");
 const version_1 = require("./version");
+const adb_health_1 = require("./adb-health");
 const update_check_1 = require("./update-check");
 const auto_wait_1 = require("./commands/auto-wait");
 const batch_1 = require("./commands/batch");
@@ -475,6 +476,12 @@ async function cmdDoctor(ctx) {
     const adb = process.env.ADB || 'adb';
     if (!reportProbe((0, drivers_1.probeAdb)()))
         return 3;
+    // adb being PRESENT is not the same as adb being WELL: a long-lived server leaks USB
+    // handles and starts dropping devices mid-run, and no device-level remedy reaches it
+    // (see adb-health.ts). Advisory and evidence-only, so a healthy host stays silent.
+    const adbRot = (0, adb_health_1.adbHealthProbe)();
+    if (adbRot)
+        reportProbe(adbRot);
     const devices = ctx.driver.listDevices();
     const usable = devices.filter((d) => d.state === 'device');
     const claims = (0, claims_1.claimsEnabled)();

package/dist/server.js

@@ -58,6 +58,7 @@ const server_pool_1 = require("./server-pool");
 const ir_1 = require("./agent/ir");
 const rpc_1 = require("./rpc");
 const cli_1 = require("./cli");
+const adb_health_1 = require("./adb-health");
 const wait_1 = require("./wait");
 const version_1 = require("./version");
 /**
@@ -89,6 +90,10 @@ const LOCK_IDLE_MS = 5 * 60 * 1000;
 // comfortably inside the client's 15-minute install ceiling at ~1 minute an install,
 // while a farm of ten wedged emulators cannot burn ten installs inside one request.
 const MAX_FAILOVER_HOPS = 2;
+// How often to ask whether the host's adb server has rotted. Generous on purpose: the
+// check shells out to `log show` (~1s) and the condition it looks for accumulates over
+// DAYS, so a tight interval would buy nothing and spend host time on every idle server.
+const ADB_RECYCLE_CHECK_MS = 10 * 60 * 1000;
 // Gap between the two probes that separate a momentary blip from a dead device. Mirrors
 // suite.ts's stillBroken, and for the same reason: a flaky dump also surfaces as exit 3,
 // so acting on one probe would rotate the pool on ordinary flake.
@@ -448,6 +453,72 @@ function buildServer(config) {
     // The first timer this server has ever had, so this is the first thing that could hold the
     // process open after Ctrl-C. It must not.
     reconcileTimer?.unref?.();
+    // --- adb server recycle ----------------------------------------------------
+    //
+    // A long-lived adb server leaks USB handles until it drops devices mid-run, and only a
+    // restart cures it (the measurements: `adb-health.ts`). `vk server` is BUILT to sit on a
+    // CI host for days — precisely the condition that rots it — so this is ON by default:
+    // on a dedicated box, recycling a broken transport is the expected behaviour, not a
+    // surprise. `VERIKUN_NO_ADB_RECYCLE=1` opts out, for the rare host running other adb
+    // work beside the server; that restores today's behaviour exactly, the equivalence
+    // `VERIKUN_NO_CLAIM` and `VERIKUN_NO_FAILOVER` are held to.
+    //
+    // Three properties are what make a DEFAULT-ON, HOST-GLOBAL restart safe:
+    //
+    //   * EVIDENCE, NEVER AGE. A healthy server measures exactly zero violations, so a
+    //     healthy host is never touched. Age alone would restart a perfectly good server on
+    //     a timer — a new way to fail, which is the one thing this may not add.
+    //   * FULLY IDLE ONLY. `kill-server` drops every transport on the machine, so anything
+    //     mid-run vetoes. `othersActive` is the existing predicate for that and already
+    //     steps over an idle lease, so a crashed client cannot wedge this forever.
+    //   * ANDROID ONLY — and in practice macOS only, since `adbServerHealth` reports no
+    //     evidence elsewhere and no-evidence is never rot. An iOS server never pays for it.
+    //
+    // The residual race is a client arriving during the ~2s restart and getting a busy
+    // error. Accepted deliberately: we only ever get here when adb is ALREADY broken, so
+    // that client's alternative was a server that drops its device mid-suite. An honest
+    // refusal beats a half-dead transport. `exclusive` is held across the restart so the
+    // refusal is the clean one the lease layer already knows how to give.
+    const adbRecycleOn = (0, adb_health_1.adbRecycleEnabled)(config.platform);
+    const RECYCLE_TOKEN = '__adb-recycle__';
+    const recycleAdbIfRotten = async () => {
+        // Cheap gate first: never shell out to `log show` while the server is working.
+        if (othersActive(RECYCLE_TOKEN) || inFlight.size > 0)
+            return;
+        const health = (0, adb_health_1.adbServerHealth)();
+        if (!(0, adb_health_1.adbServerRotting)(health))
+            return;
+        await serializeFailover(async () => {
+            // Re-check inside the queue: the health probe shells out for ~1s, which is ample
+            // time for a run to start, and by here we are about to cut every transport.
+            if (othersActive(RECYCLE_TOKEN) || inFlight.size > 0)
+                return;
+            (0, output_1.err)(`[server] ${(0, adb_health_1.describeRot)(health)}`);
+            exclusive = RECYCLE_TOKEN;
+            try {
+                const ok = (0, adb_health_1.recycleAdbServer)(process.env.ADB || 'adb');
+                (0, output_1.err)(ok ? '[server] adb server restarted — devices reconnecting' : '[server] adb server restart failed — continuing');
+            }
+            finally {
+                exclusive = null;
+            }
+        });
+    };
+    let recycling = false;
+    const recycleTimer = adbRecycleOn
+        ? setInterval(() => {
+            if (recycling)
+                return;
+            recycling = true;
+            void recycleAdbIfRotten()
+                .catch((e) => (0, output_1.err)(`[server] adb recycle check failed — ${(0, server_http_1.firstLine)(e.message)}`))
+                .finally(() => {
+                recycling = false;
+            });
+        }, ADB_RECYCLE_CHECK_MS)
+        : null;
+    // Like the reconcile timer: must never hold the process open at Ctrl-C.
+    recycleTimer?.unref?.();
     const pickFailoverDevice = (failed, reason) => serializeFailover(() => pickFailoverDeviceLocked(failed, reason));
     /**
      * Bring in a healthy replacement for `failed`. Returns the serial moved to, or null
@@ -1679,6 +1750,8 @@ function buildServer(config) {
     server.on('close', () => {
         if (reconcileTimer)
             clearInterval(reconcileTimer);
+        if (recycleTimer)
+            clearInterval(recycleTimer);
         dropRetainedInstall();
     });
     return server;
@@ -1906,6 +1979,14 @@ async function cmdServer(positionals, flags) {
                 (0, output_1.err)('[server] NOTE: an authenticated client can now power-cycle AND erase this device.');
             }
             (0, output_1.err)(`[server] failover: ${failover.why}`);
+            // Announced in both states, like the failover kill switch. ON is worth saying because
+            // `adb kill-server` is host-global and an operator should not meet it as a surprise;
+            // OFF is worth saying because a rotted adb server is otherwise a baffling flake.
+            if (platform === 'android') {
+                (0, output_1.err)(`[server] adb recycle: ${(0, adb_health_1.adbRecycleEnabled)(platform)
+                    ? 'on — a rotted adb server is restarted while idle (VERIKUN_NO_ADB_RECYCLE=1 to disable)'
+                    : 'disabled (VERIKUN_NO_ADB_RECYCLE)'}`);
+            }
             (0, output_1.err)(serverLog
                 ? `[server] log: ${serverLog.path} (--log-file ${server_log_1.LOG_OFF} to disable)`
                 : `[server] log: stderr only (--log-file ${server_log_1.LOG_OFF})`);

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.26.3';
+exports.VERSION = '0.27.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.26.3",
+  "version": "0.27.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",