verikun 0.27.0 → 0.27.1

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

@@ -613,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,22 @@ 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

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

@@ -917,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}'`);
@@ -930,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}` });
@@ -979,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/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.27.0';
+exports.VERSION = '0.27.1';

package/package.json

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