verikun 0.26.3 → 0.27.1

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
 
@@ -608,7 +613,7 @@ owns the redaction and the review-first flow.
 ## Gotchas
 
 - **Prepare the device once** for reliable dumps: `vk device prep` (a physical device
-  needs `--device <serial>`). Live animations can make `vk ui` flaky (it already retries 3×).
+  needs `--device <serial>`). Live animations can make `vk ui` flaky.
 - **A slept device returns the LOCK SCREEN, not an error.** The dump succeeds and hands
   back `com.android.systemui` — so selectors miss for a reason unrelated to the app.
   verikun detects this, wakes the device and clears a *swipe* lock automatically; on a

package/CHANGELOG.md

@@ -6,6 +6,31 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.27.1] - 2026-09-14
+
+A hierarchy read the device killed is now waited out instead of ending the test.
+
+### Fixed
+- **Hierarchy reads** ride out a dump the device killed, for the caller's full wait budget,
+  instead of aborting after three fast retries. ([#137])
+- **`assert --gone` / `wait --gone`** no longer count a killed read as an absence; a window of
+  only killed reads exits `3` instead of reporting a miss. ([#137])
+
+### Changed
+- **A killed dump** names memory pressure and is never failed over or retired — the device is
+  busy, not broken. ([#137])
+
+[#137]: https://github.com/ddikman/verikun/issues/137
+
+## [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/agent/engine.js

@@ -89,8 +89,10 @@ exports.DEFAULT_GUARD_SETTLE_MS = 1500;
 /** Re-dump cadence inside a guard's settle window. */
 const GUARD_POLL_MS = 150;
 /**
- * How long a guard keeps looking at a screen it cannot read at all, when the reason is
- * NoWindowError — the app was force-stopped or is mid-launch and has genuinely not drawn.
+ * How long a guard keeps looking at a screen it cannot read at all, when the reason is one
+ * that CLEARS ON ITS OWN (`TransientReadError`): the app force-stopped or mid-launch and not
+ * yet drawn (`NoWindowError`), or the dumper SIGKILLed under memory pressure
+ * (`DumpKilledError`, issue #137).
  *
  * Separate from `settleMs`, which answers "how long before I believe this selector is
  * absent?". This answers "how long before I believe there is no screen to ask?" — a
@@ -113,7 +115,7 @@ const GUARD_POLL_MS = 150;
  * Not configurable on purpose: a dial here is one more thing to explain, and every value a
  * user might pick is worse than the measurement.
  */
-const NO_WINDOW_GRACE_MS = 10_000;
+const TRANSIENT_READ_GRACE_MS = 10_000;
 /** Consecutive identical screen snapshots before a loop is believed to be stuck.
  *
  *  This check is a TIME SAVER and nothing more. A loop already fails when its exit
@@ -205,8 +207,9 @@ async function runPlan(plan, deps) {
      *      probe a loop-exit check needs.
      *  So one dump attempt always happens regardless of the window.
      *
-     *  A THIRD clock sits beside both: a screen that cannot be read because the app has not
-     *  drawn (NoWindowError) is retried against NO_WINDOW_GRACE_MS, not against `settleMs`.
+     *  A THIRD clock sits beside both: a screen that is not READABLE AT ALL for a reason that
+     *  clears on its own (a TransientReadError) is retried against TRANSIENT_READ_GRACE_MS,
+     *  not against `settleMs`.
      *  That is deliberately independent — "is this selector absent?" and "is there a screen to
      *  ask at all?" are different questions, and only the second one aborts the run.
      *
@@ -229,10 +232,10 @@ async function runPlan(plan, deps) {
         if (deps.platform)
             (0, state_support_1.assertStateSupported)(sel, deps.platform);
         const deadline = Date.now() + Math.max(0, settleMs);
-        // A screen that cannot be read AT ALL gets its own, longer clock — see NO_WINDOW_GRACE_MS.
+        // A screen that cannot be read AT ALL gets its own, longer clock — see TRANSIENT_READ_GRACE_MS.
         // Clamped by the run deadline so a guard can never push a run past --timeout: the grace
         // exists to spend budget the caller already has, never to invent more.
-        const noWindowDeadline = Math.min(Date.now() + NO_WINDOW_GRACE_MS, deps.deadline ?? Infinity);
+        const transientDeadline = Math.min(Date.now() + TRANSIENT_READ_GRACE_MS, deps.deadline ?? Infinity);
         // A non-zero window must buy at least one SECOND look, independent of the clock.
         // Measured on emulator-5554: one uiautomator dump costs ~2.4s, which already exceeds
         // a 1.5s window — so a purely time-boxed loop returns after a single dump and the
@@ -280,7 +283,7 @@ async function runPlan(plan, deps) {
                 // One successful read — even an empty tree — and the ordinary semantics resume exactly:
                 // settleMs=0 is still a single-shot probe. It must never make a merely ABSENT selector
                 // more patient, or every guard silently costs 10s.
-                if (!everRead && lastErr instanceof errors_1.NoWindowError && Date.now() < noWindowDeadline) {
+                if (!everRead && lastErr instanceof errors_1.TransientReadError && Date.now() < transientDeadline) {
                     await (0, wait_1.sleep)(GUARD_POLL_MS);
                     continue;
                 }

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)();
@@ -910,10 +917,13 @@ async function cmdWait(ctx) {
     const timeout = (0, args_1.flagNum)(ctx.flags, 'timeout') ?? 10000;
     const interval = (0, args_1.flagNum)(ctx.flags, 'interval') ?? 400;
     const deadline = Date.now() + timeout;
-    const barrier = new auto_wait_1.BarrierTally(ctx);
+    const barrier = new auto_wait_1.ReadTally(ctx);
     while (Date.now() < deadline) {
-        const { matches, tier } = (0, selector_1.matchElements)(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel);
-        if (gone ? matches.length === 0 : matches.length > 0) {
+        const { matches, tier } = (0, selector_1.matchElements)((0, auto_wait_1.readForPoll)(ctx, barrier), sel);
+        // A read that did not happen proves nothing, and `--gone` is satisfied by an EMPTY one —
+        // so without this a kill storm answers "gone" on its first poll, exit 0. Absence has to be
+        // observed. (Measured on a Pixel 3a while fixing #137.)
+        if (!barrier.lastWasBlind() && (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)
                 (0, output_1.out)(`gone: '${sel.raw}'`);
@@ -923,6 +933,11 @@ async function cmdWait(ctx) {
         }
         await (0, wait_1.sleep)(interval);
     }
+    // A window that never once READ the screen has no timeout to report — it has an environment
+    // failure, and it throws (issue #137) rather than reaching the `return 1` below. That is also
+    // what a killed dump did before this fix, so the recorded step keeps its `error` shape
+    // instead of turning into a `failure`.
+    barrier.rethrowIfBlind();
     // A barrier can only explain a miss: with --gone the element is absent and the wait passed above.
     const why = withStop(gone ? '' : barrier.clause());
     ctx.record?.note({ selector: sel, message: `timeout after ${timeout}ms${gone ? ' (still present)' : ' (never appeared)'}${why}` });
@@ -972,12 +987,23 @@ 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() + (0, auto_wait_1.waitWindowMs)(ctx.flags);
-    const barrier = new auto_wait_1.BarrierTally(ctx);
-    let result = evalAssert(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel, ctx.flags);
+    const barrier = new auto_wait_1.ReadTally(ctx);
+    // A verdict is only worth banking if the read behind it happened. `--gone` (and `--count 0`)
+    // pass on an EMPTY tree, which is exactly what an absorbed transient hands back — so a single
+    // killed dump mid-window could otherwise bank a green the screen never showed. Poll again
+    // instead; `rethrowIfBlind()` below handles a window that stayed blind to the end.
+    const look = () => {
+        const result = evalAssert((0, auto_wait_1.readForPoll)(ctx, barrier), sel, ctx.flags);
+        return barrier.lastWasBlind() ? { ...result, pass: false } : result;
+    };
+    let result = look();
     while (!result.pass && Date.now() < deadline) {
         await (0, wait_1.sleep)((0, auto_wait_1.pollStep)(ctx.flags, deadline));
-        result = evalAssert(barrier.note((0, auto_wait_1.readForPoll)(ctx)), sel, ctx.flags);
+        result = look();
     }
+    // `--gone` PASSES on an empty read, so a window of nothing but killed dumps would report a
+    // green earned from a screen nobody could read. Checked before `pass` is consumed (issue #137).
+    barrier.rethrowIfBlind();
     const { pass, matches } = result;
     // Only a "not found" can be explained by a barrier: `--gone` passed if the tree was
     // barrier-only, and a text mismatch found the element.

package/dist/commands/auto-wait.js

@@ -10,7 +10,7 @@
 // waiting lives here. The rules a new selector-resolving command must follow are in
 // CLAUDE.md, "Selector auto-wait".
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BarrierTally = void 0;
+exports.ReadTally = void 0;
 exports.parseDuration = parseDuration;
 exports.waitWindowMs = waitWindowMs;
 exports.waitNote = waitNote;
@@ -53,48 +53,63 @@ function pollStep(flags, deadline) {
     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.
+ * Read the hierarchy for a caller that is polling, treating a read that will clear on its own
+ * as "nothing on screen yet" rather than as 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
+ * A `TransientReadError` means the device could not answer *right now* — `launch --clear` and
+ * `launch` both leave a gap where the app has been stopped and has not drawn (`NoWindowError`),
+ * and a memory-pressured phone SIGKILLs the dumper outright (`DumpKilledError`, issue #137).
+ * Both clear in seconds, 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.
+ * used to abort at ~20s with 100 seconds unspent, and a `wait --timeout 30000` at 2.5s.
  *
  * 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.
+ *
+ * Pass the tally so the window can tell "the screen said nothing was there" from "nobody ever
+ * read the screen"; see `ReadTally.rethrowIfBlind`.
  */
-function readForPoll(ctx, opts = {}) {
+function readForPoll(ctx, tally, opts = {}) {
     try {
-        return ctx.driver.getElements(opts);
+        const els = ctx.driver.getElements(opts);
+        return tally ? tally.note(els) : els;
     }
     catch (e) {
-        if (e instanceof errors_1.NoWindowError)
+        if (e instanceof errors_1.TransientReadError) {
+            tally?.noteBlind(e);
             return [];
+        }
         throw e;
     }
 }
 /**
- * Keeps track of whether the snapshots a poll loop read were barrier-only trees (see
- * ui/barrier.ts), so the failure at the end can say so instead of "never appeared".
+ * What every read in ONE poll window saw. This is the only layer that sees all of them, so
+ * both of the things a miss message needs to be honest about live here.
+ *
+ * **Was the tree barrier-only?** (issue #131) A sheet's barrier that outlives the whole wait
+ * made the step report "never appeared", sending the reader looking for a missing identifier
+ * in app code. Naming the barrier is the cheap half of that fix.
  *
- * A sheet's barrier that outlives the whole wait is the report behind issue #131: the
- * step waited 30s on a painted sheet and the message sent the reader looking for a missing
- * identifier in app code. Naming the barrier is the cheap half of that fix, and it belongs
- * to whoever owns the wait — this is the only layer that saw every read.
+ * **Did anyone ever read the screen at all?** (issue #137) An absorbed `DumpKilledError` costs
+ * a read and yields no elements, and a window made entirely of those has no grounds to call
+ * anything absent — see `rethrowIfBlind`.
  */
-class BarrierTally {
+class ReadTally {
     ctx;
     reads = 0;
+    okReads = 0;
     barrierReads = 0;
     last = null;
+    blind;
+    lastBlind = false;
     constructor(ctx) {
         this.ctx = ctx;
     }
     /** Record one snapshot. Returns it, so it can wrap a read in place. */
     note(els) {
         this.reads++;
+        this.okReads++;
+        this.lastBlind = false;
         this.last = (0, barrier_1.modalBarrierOnly)(els, this.ctx.driver.viewport());
         if (this.last)
             this.barrierReads++;
@@ -106,8 +121,47 @@ class BarrierTally {
             return '';
         return (0, barrier_1.barrierClause)(this.last, this.barrierReads === this.reads);
     }
+    /** Record a read that never happened — a transient failure `readForPoll` absorbed as `[]`. */
+    noteBlind(e) {
+        this.reads++;
+        this.blind = e;
+        this.lastBlind = true;
+        this.last = null; // a read that did not happen is not a barrier, and must not read as one
+    }
+    /**
+     * Did the most recent read fail to happen? Then it proves NOTHING, and least of all an
+     * absence — which `--gone` counts as a pass.
+     *
+     * Separate from `rethrowIfBlind`, and it has to be: that one asks about the whole window and
+     * fires at the deadline, but a `--gone` predicate is satisfied by the FIRST empty read and
+     * returns from inside the poll loop, so a window-level check never runs. MEASURED on a
+     * Pixel 3a while fixing #137: `wait --gone` under a kill storm exited 0 reporting "gone".
+     *
+     * Both `NoWindowError` and `DumpKilledError` count here. Unlike the deadline rule, the two
+     * need no asymmetry: an absorbed read yielded no elements to judge either way, so polling
+     * once more is right for both and costs a merely-absent selector nothing.
+     */
+    lastWasBlind() {
+        return this.lastBlind;
+    }
+    /**
+     * Refuse to report an absence this window never actually observed (issue #137).
+     *
+     * ONLY for a killed dump. The asymmetry is the point: a null root is the device ANSWERING
+     * "nothing is drawn", so "the selector is absent" is a true reading of it and
+     * `NoWindowError` keeps its existing behaviour exactly. A kill is no answer at all — and
+     * `assert --gone` turns "absent" into a PASS, so absorbing it silently would manufacture a
+     * green from a screen nobody could read.
+     *
+     * Gated on `okReads === 0`, the same `everRead` rule the engine's guard grace uses: one good
+     * read anywhere in the window means the screen was legible and an ordinary miss is honest.
+     */
+    rethrowIfBlind() {
+        if (this.okReads === 0 && this.blind instanceof errors_1.DumpKilledError)
+            throw this.blind;
+    }
 }
-exports.BarrierTally = BarrierTally;
+exports.ReadTally = ReadTally;
 /**
  * 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),
@@ -115,11 +169,16 @@ exports.BarrierTally = BarrierTally;
  */
 async function matchWaiting(ctx, sel, opts = {}) {
     const deadline = Date.now() + waitWindowMs(ctx.flags);
-    const barrier = new BarrierTally(ctx);
+    const barrier = new ReadTally(ctx);
     for (;;) {
-        const res = (0, selector_1.matchElements)(barrier.note(readForPoll(ctx, opts)), sel);
-        if (res.matches.length > 0 || Date.now() >= deadline)
+        const res = (0, selector_1.matchElements)(readForPoll(ctx, barrier, opts), sel);
+        if (res.matches.length > 0)
             return { ...res, barrier };
+        if (Date.now() >= deadline) {
+            // Before ANY caller can read this as an absence — `assert --gone` calls it a pass.
+            barrier.rethrowIfBlind();
+            return { ...res, barrier };
+        }
         await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
     }
 }
@@ -132,9 +191,9 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
     const windowMs = waitWindowMs(ctx.flags);
     const start = Date.now();
     const deadline = start + windowMs;
-    const barrier = new BarrierTally(ctx);
+    const barrier = new ReadTally(ctx);
     for (;;) {
-        const els = barrier.note(readForPoll(ctx, opts));
+        const els = readForPoll(ctx, barrier, 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
@@ -143,6 +202,7 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
             return { element, tier, waitedMs: Date.now() - start, elements: els };
         }
         if (Date.now() >= deadline) {
+            barrier.rethrowIfBlind();
             const waited = windowMs > 0 ? ` after ${(windowMs / 1000).toFixed(1)}s` : '';
             throw new errors_1.SelectorNotFoundError(`No element matched selector '${sel.raw}'${waited}.${barrier.clause()} Run \`verikun ui\` to inspect the current screen.`);
         }

package/dist/device/failover.js

@@ -84,16 +84,22 @@ function exitCodeOf(e) {
     return e instanceof errors_1.CliError ? e.exitCode : 3;
 }
 const messageOf = (e) => (e instanceof Error ? e.message : String(e ?? ''));
+/** Why this device stays. Named per class so the operator reads the actual cause, not
+ *  "transient" — the two want different responses (wait vs free some memory). */
+const transientReason = (e) => e instanceof errors_1.DumpKilledError
+    ? 'the hierarchy dump was killed — the device is under memory pressure, not broken'
+    : 'the app has not drawn yet — this clears on its own';
 /**
  * The arms share everything except what an unrecognised exit-3 means, so they share
  * this and differ only in `fallback`.
  */
 function classify(e, fallback) {
-    // Identity first, never message text: NoWindowError is exit 3 and its wording could
-    // plausibly be matched by another rule, and getting this one wrong means rotating the
-    // pool every time an app is mid-launch.
-    if (e instanceof errors_1.NoWindowError) {
-        return { move: false, kind: 'transient', reason: 'the app has not drawn yet — this clears on its own' };
+    // Identity first, never message text: both transient reads are exit 3 and their wording could
+    // plausibly be matched by another rule, and getting this one wrong means rotating the pool
+    // every time an app is mid-launch — or, for a killed dump, retiring a phone for being busy
+    // (issue #137).
+    if (e instanceof errors_1.TransientReadError) {
+        return { move: false, kind: 'transient', reason: transientReason(e) };
     }
     const code = exitCodeOf(e);
     if (code === 0 || code === 1)
@@ -140,7 +146,7 @@ function classifyInstallFailure(e) {
     const code = exitCodeOf(e);
     // Only an environment failure is ever the device's fault; a usage error (a rejected
     // extension, an unreadable path) is the caller's and no device fixes it.
-    if (code === 3 && !(e instanceof errors_1.NoWindowError)) {
+    if (code === 3 && !(e instanceof errors_1.TransientReadError)) {
         const message = messageOf(e);
         // Same order as `classify` below, so the two arms can only ever differ in their
         // DEFAULT — which is the one difference between them that is meant to exist.

package/dist/drivers/adb.js

@@ -5,6 +5,7 @@ exports.probeAdb = probeAdb;
 exports.parseLockKind = parseLockKind;
 exports.looksLikeSystemUi = looksLikeSystemUi;
 exports.lockKindOf = lockKindOf;
+exports.dumpWasKilled = dumpWasKilled;
 exports.escapeText = escapeText;
 exports.adbTransport = adbTransport;
 exports.severanceRisk = severanceRisk;
@@ -204,6 +205,26 @@ const BARRIER_SETTLE_MS = 300;
  *  companion reports the same condition from getRootInActiveWindow(). Transient — see
  *  NoWindowError. */
 const NULL_ROOT = /null root node/i;
+/** 128 + SIGKILL — what a shell reports for a command the kernel killed outright. */
+const EXIT_SIGKILL = 137;
+/** The device shell's word for it, when the shell itself survived to say so. */
+const KILLED_TEXT = /\bKilled\b/;
+/**
+ * Was this read SIGKILLed rather than merely unsuccessful? (issue #137)
+ *
+ * THE EXIT CODE IS THE PRIMARY SIGNAL, not the text. MEASURED on a Pixel 3a: in the
+ * `adb shell '<cmd>'` form the device shell prints NOTHING when it is killed — both streams
+ * come back empty and only the status says 137. That is why the old message read
+ * "Failed to capture UI hierarchy after 3 attempts." with nothing after it. The word "Killed"
+ * does appear on some shells (issue #137 was reported with it), so it is kept as a second
+ * signal for an adb too old to propagate the remote status — but a matcher built on the text
+ * alone would have missed the very device this was reported from.
+ *
+ * Pure and exported for the unit suite only; nothing else imports it.
+ */
+function dumpWasKilled(code, text) {
+    return code === EXIT_SIGKILL || KILLED_TEXT.test(text);
+}
 /** 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];
@@ -898,6 +919,16 @@ class AdbDriver {
             if (NULL_ROOT.test(lastErr)) {
                 throw new errors_1.NoWindowError();
             }
+            // A KILLED dump is the same deal, with one difference: attempt 0 has a real cure for
+            // one of its two causes (a companion holding the UiAutomation connection SIGKILLs a
+            // competing dump), so it still gets the remedy below and one more try. Once THAT is
+            // killed too, stop — a third back-to-back attempt is a third sample of the same instant
+            // (#137 measured all three losing), and the caller's poll interval is the spacing that
+            // actually helps. Judged on the DUMP's own result, never the combined text: a `cat` that
+            // reports a missing file is the kill's consequence, not evidence of one.
+            if (attempt > 0 && dumpWasKilled(dump.code, `${dump.stdout} ${dump.stderr}`)) {
+                throw new errors_1.DumpKilledError((0, errors_1.dumpKilledMessage)(lastErr));
+            }
             if (attempt === 0) {
                 // A sleeping display is the other documented cause of a failed read. `ensureAwake` ran
                 // before the dump, so reaching here means its answer went stale during a slow read (or

package/dist/errors.js

@@ -6,7 +6,7 @@
 //   2  usage error, ambiguous selector, or a device another job is driving (caller must refine)
 //   3  environment error (adb/simctl missing, no usable device, dump failed)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousSelectorError = exports.NO_WINDOW_MESSAGE = exports.NoWindowError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
+exports.AmbiguousSelectorError = exports.DUMP_KILLED_MESSAGE = exports.dumpKilledMessage = exports.DumpKilledError = exports.NO_WINDOW_MESSAGE = exports.NoWindowError = exports.TransientReadError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
 exports.isEnvError = isEnvError;
 class CliError extends Error {
     exitCode;
@@ -51,6 +51,21 @@ class SelectorNotFoundError extends CliError {
     }
 }
 exports.SelectorNotFoundError = SelectorNotFoundError;
+/**
+ * A hierarchy read that failed for a reason which CLEARS ON ITS OWN within seconds.
+ *
+ * The base exists so the three layers that mean "ride this out" — `readForPoll`, the engine's
+ * guard grace, and the failover classifier — say so once, by class, instead of listing
+ * subclasses they would each have to be remembered to update. Everything narrower than "this
+ * is transient" keeps checking the concrete class (the companion only stands down for a
+ * NoWindowError, not for a kill it had nothing to do with).
+ *
+ * Still exit 3, so a caller with NO budget is unaffected: an unabsorbed one exits exactly as
+ * it did before. What the class buys is the right to be polled through, not a softer exit.
+ */
+class TransientReadError extends CliError {
+}
+exports.TransientReadError = TransientReadError;
 /**
  * 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.
@@ -66,7 +81,7 @@ exports.SelectorNotFoundError = SelectorNotFoundError;
  * 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 {
+class NoWindowError extends TransientReadError {
     constructor(message = exports.NO_WINDOW_MESSAGE) {
         super(message, 3);
         this.name = 'NoWindowError';
@@ -86,6 +101,45 @@ exports.NoWindowError = NoWindowError;
  */
 exports.NO_WINDOW_MESSAGE = 'No window to read: the app has no drawn window right now — force-stopped, mid-launch, or ' +
     'its main thread is busy mid-transition. This normally clears within a few seconds.';
+/**
+ * The dump process was SIGKILLed before it could answer (issue #137).
+ *
+ * NOT the same signal as NoWindowError, and the difference is the whole reason this is its own
+ * class. A null root is the device ANSWERING "nothing is drawn", so "the selector is absent" is
+ * a true reading of it. A kill is no answer at all, so calling the selector absent would be a
+ * fabrication — which is why a poll window that never once read the screen re-throws this
+ * instead of reporting a miss (`ReadTally.rethrowIfBlind`).
+ *
+ * MEASURED on a 4 GB-class phone (#137): the OS reaps the dumper while an app cold-starts, and
+ * the driver's three attempts fired back-to-back all landed inside the same second — so a
+ * `wait` holding a two-minute budget aborted at ~2.5s with 117 seconds unspent. Same rule as
+ * NoWindowError: the driver hands it up, the caller spends its own clock on it.
+ */
+class DumpKilledError extends TransientReadError {
+    constructor(message = exports.DUMP_KILLED_MESSAGE) {
+        super(message, 3);
+        this.name = 'DumpKilledError';
+    }
+}
+exports.DumpKilledError = DumpKilledError;
+/** The wording plus whatever the device actually said, for the one thrower that has evidence.
+ *  Separate from the constructor so the wire codec can rebuild a message losslessly rather
+ *  than re-prefixing one that already carries its detail. */
+const dumpKilledMessage = (detail) => detail ? `${exports.DUMP_KILLED_MESSAGE} (${detail})` : exports.DUMP_KILLED_MESSAGE;
+exports.dumpKilledMessage = dumpKilledMessage;
+/**
+ * Names the CAUSE, because "the dump was killed" and "the device left adb" both used to arrive
+ * as `Failed to capture UI hierarchy after 3 attempts` and want opposite responses from whoever
+ * reads the report — wait vs go and find the phone.
+ *
+ * Both causes are named because both are real and the fix for each is different: memory pressure
+ * (wait, or test on a device with more headroom) and a competing UiAutomation client (stop it).
+ * verikun's own companion is the second one, and the driver already tries to clear that itself
+ * before this is ever thrown.
+ */
+exports.DUMP_KILLED_MESSAGE = 'The UI hierarchy dump was killed before it could answer — the device reclaiming memory ' +
+    'while an app starts, or another tool holding the one UiAutomation connection. This ' +
+    'normally clears within seconds.';
 /** 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/rpc.js

@@ -22,11 +22,15 @@ function describeError(e) {
     if (e instanceof errors_1.SelectorNotFoundError) {
         return { kind: 'SelectorNotFoundError', name: e.name, message: e.message, exitCode: e.exitCode };
     }
-    // BEFORE the CliError arm — NoWindowError extends it, so a subclass check must come
-    // first or the identity is flattened away. device/failover.ts classifies on
-    // `instanceof NoWindowError` deliberately ("identity first, never message text"), and
-    // losing it turns every mid-launch gap into an unknown that costs two device probes and
-    // can quarantine a perfectly healthy phone.
+    // BEFORE the CliError arm — both transient reads extend it, so a subclass check must come
+    // first or the identity is flattened away. device/failover.ts classifies on the CLASS
+    // deliberately ("identity first, never message text"), and losing it turns every mid-launch
+    // gap into an unknown that costs two device probes and can quarantine a perfectly healthy
+    // phone. Flattening DumpKilledError also costs a poller its ride-out, which is the whole of
+    // issue #137 — and #137 was reported through a pooled `vk server`, i.e. across this wire.
+    if (e instanceof errors_1.DumpKilledError) {
+        return { kind: 'DumpKilledError', name: e.name, message: e.message, exitCode: e.exitCode };
+    }
     if (e instanceof errors_1.NoWindowError) {
         return { kind: 'NoWindowError', name: e.name, message: e.message, exitCode: e.exitCode };
     }
@@ -45,6 +49,8 @@ function rebuildError(d) {
             return new errors_1.SelectorNotFoundError(d.message);
         case 'NoWindowError':
             return new errors_1.NoWindowError(d.message);
+        case 'DumpKilledError':
+            return new errors_1.DumpKilledError(d.message);
         case 'CliError':
             return new errors_1.CliError(d.message, d.exitCode);
         default: {

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.1';

package/package.json

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