verikun 0.27.0 → 0.28.0

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

@@ -530,10 +530,12 @@ device that failed and is now on another one. What that means depends on the lin
   the failure was real on A, and B has none of the state your flow built up. Start the
   flow again from the top if you want it on B.
 
-The server rules the bad device out until it is power-cycled;
-`vk devices --server <url>` shows why in its `NOTE` column. On a pool the replacement
-joins the pool, so capacity holds — and the last device is never shed, so its own error
-keeps reaching you rather than a bare "no device attached".
+The server rules the bad device out; `vk devices --server <url>` shows why in its `NOTE`
+column, and a pooled server re-adopts a device that comes back within a minute. A device
+that is still attached keeps its place and is simply dealt last, so its own error keeps
+reaching you rather than a bare "no device attached". A device that is **gone** leaves the
+pool — so `capacity` can drop mid-job, and an install can come back `exit 0` having skipped
+it. That is a success: nothing can be dealt a device running the previous build.
 
 ## The device is missing or wedged
 
@@ -613,7 +615,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,43 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-09-14
+
+A device that has gone now leaves a pooled `vk server` instead of being dealt out until
+somebody notices.
+
+### Fixed
+- **`vk server --devices`** drops a device that is gone from the pool instead of dealing it
+  forever; the sweep readmits it when it returns. ([#139])
+- **`vk install --server`** exits `0` when some pooled devices take the build, naming the rest
+  as `skipped`; only a build that fails everywhere is an error. ([#139])
+- **A `--server` call that outlives Node's 300s fetch ceiling** now says so, and says the clock
+  was the client's, instead of a bare `fetch failed` the suite read as a dead device. ([#139])
+
+### Changed
+- **`/v1/health` `capacity` can now drop mid-job** on a pooled server, to `0`. A plain
+  `vk server` still keeps its only device and answers with that device's own error. ([#139])
+- **`POST /v1/install`** answers `200 {devices, skipped}` where it used to answer `500` on a
+  partial failure. Older clients see a success with an unknown field. ([#139])
+
+[#139]: https://github.com/ddikman/verikun/issues/139
+
+## [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/agent/remote.js

@@ -10,6 +10,7 @@
 // local one. Recording stays a caller concern: this module never touches ./.verikun.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeStatus = describeStatus;
+exports.transportReason = transportReason;
 exports.pingServer = pingServer;
 exports.remoteDeviceOp = remoteDeviceOp;
 exports.remoteDeviceList = remoteDeviceList;
@@ -18,16 +19,36 @@ const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const errors_1 = require("../errors");
+const output_1 = require("../output");
 const rpc_1 = require("../rpc");
+/**
+ * The ceiling NONE of the per-call timeouts below can exceed, whatever they say.
+ *
+ * Node's global `fetch` is undici, whose `headersTimeout` and `bodyTimeout` both default to
+ * 300s, and there is no dependency-free way to raise them: a `dispatcher` needs `undici`
+ * itself, which is bundled but not importable. The `AbortController` below is therefore a
+ * FLOOR on how long a call may take, never a ceiling — `EXEC_TIMEOUT_MS` says 600s and gets
+ * 300s.
+ *
+ * MEASURED on Node v20.20.2 against a server that held its headers for 310s: the fetch
+ * rejected at 301s with `TypeError: fetch failed`, cause `HeadersTimeoutError`, code
+ * `UND_ERR_HEADERS_TIMEOUT`. The bare `fetch failed` is the whole problem — `describeStatus`
+ * never sees it, the suite reads the resulting exit 3 as the DEVICE being unreachable, and a
+ * healthy phone gets retired for a client-side clock. Named in `request` below so it says so.
+ */
+const FETCH_HEADERS_CEILING_MS = 300_000;
 // Per-call ceilings. exec is generous: a single leaf may legitimately block for its
-// whole auto-wait window or an explicit `wait --timeout`, plus device time.
+// whole auto-wait window or an explicit `wait --timeout`, plus device time. Anything here
+// above FETCH_HEADERS_CEILING_MS is aspirational — see that constant.
 const HEALTH_TIMEOUT_MS = 10_000;
 const ELEMENTS_TIMEOUT_MS = 60_000;
 const EXEC_TIMEOUT_MS = 10 * 60_000;
 const INSTALL_TIMEOUT_MS = 15 * 60_000;
 const DEVICE_LIST_TIMEOUT_MS = 30_000;
-// Above the server's own 4-minute boot ceiling, so the SERVER reports why a boot
-// timed out rather than the client aborting into a generic "timed out after 300s".
+// Meant to sit above the server's own 4-minute boot ceiling, so the SERVER reports why a
+// boot timed out rather than the client aborting first. It is exactly AT
+// FETCH_HEADERS_CEILING_MS, so a boot that runs the full four minutes and then some is a
+// photo finish — which is survivable only because `transportReason` now names the loser.
 const DEVICE_START_TIMEOUT_MS = 5 * 60_000;
 const DEVICE_STOP_TIMEOUT_MS = 60_000;
 const trimUrl = (url) => url.replace(/\/+$/, '');
@@ -66,6 +87,28 @@ function describeStatus(status, body, url) {
     }
     return new errors_1.CliError(`verikun server error ${status} at ${url}${detail}`, exitCode);
 }
+/**
+ * Why the transport failed, in words an operator can act on. PURE — exported for the tests.
+ *
+ * The undici arm is the one that earns its keep. `fetch` reports its own header/body
+ * timeouts as a bare `TypeError: fetch failed` with the real cause one level down, and that
+ * string is indistinguishable from a server that is genuinely unreachable — which is how a
+ * five-minute install came to look like a dead phone, and how a lane came to be retired for
+ * it. Say which clock ran out, and say whose it was.
+ */
+function transportReason(e, timeoutMs) {
+    const ex = e;
+    if (ex?.name === 'AbortError')
+        return `timed out after ${Math.round(timeoutMs / 1000)}s`;
+    const code = ex?.cause?.code;
+    if (code === 'UND_ERR_HEADERS_TIMEOUT' || code === 'UND_ERR_BODY_TIMEOUT') {
+        const what = code === 'UND_ERR_HEADERS_TIMEOUT' ? 'send a response' : 'finish its response';
+        return (`the server did not ${what} within ${Math.round(FETCH_HEADERS_CEILING_MS / 1000)}s — ` +
+            "this is Node's own fetch ceiling on the CLIENT, not the device. " +
+            'The server may still be working; check its log before blaming the device');
+    }
+    return ex?.message ?? String(e);
+}
 async function readBody(res) {
     try {
         return (await res.json());
@@ -103,8 +146,7 @@ class RemoteTransport {
             });
         }
         catch (e) {
-            const reason = e.name === 'AbortError' ? `timed out after ${Math.round(timeoutMs / 1000)}s` : e.message;
-            throw new errors_1.CliError(`cannot reach verikun server at ${url} (${reason})`, 3);
+            throw new errors_1.CliError(`cannot reach verikun server at ${url} (${transportReason(e, timeoutMs)})`, 3);
         }
         finally {
             clearTimeout(timer);
@@ -229,6 +271,14 @@ function createRemoteBackend(opts, health) {
             // the build DID land — on a different device than the one we started with.
             if (res.deviceChanged)
                 opts.onDeviceChange?.(res.deviceChanged);
+            // A PARTIAL install is a success, and it must not be a silent one: capacity just
+            // dropped, and the operator's next question is which phone to go and look at.
+            if (res.skipped?.length) {
+                (0, output_1.err)(`[verikun] server installed on ${(res.devices ?? []).join(', ') || '(none)'}; ` +
+                    `${res.skipped.length} device(s) could not take this build and left the pool — ` +
+                    res.skipped.map((s) => `${s.serial} (${s.reason})`).join('; '));
+                opts.onInstallSkipped?.(res.skipped);
+            }
         },
         async reset(appId) {
             // Between-test housekeeping (vk suite): the step is deliberately NOT spliced

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.
@@ -2250,10 +2269,12 @@ async function resolveBackend(platform, device, flags) {
             // every recorded command, which beats a timer: it fires when work happens.
             grant: (0, grant_1.processClaimGrant)(device, claims_1.releaseOwnClaims),
             moves: [],
+            skipped: [],
         };
     }
     let runCtx = { platform, device };
     const moves = [];
+    const skipped = [];
     /** Set by the last move; the preflight below reads it to decide whether re-asking is
      *  warranted, then clears it. */
     let movedDuringCall;
@@ -2264,6 +2285,7 @@ async function resolveBackend(platform, device, flags) {
         // is identical to a local run's. logStart travels from the server's device clock
         // so archive-time / vk log scoping works without a local driver.
         onStep: (step, artifacts, logStart) => run_1.Recorder.appendForeignStep(step, artifacts, { ...runCtx, logStart }),
+        onInstallSkipped: (s) => skipped.push(...s),
         onDeviceChange: (c) => {
             moves.push(c);
             movedDuringCall = c;
@@ -2342,6 +2364,7 @@ async function resolveBackend(platform, device, flags) {
         grant: (0, grant_1.leaseGrant)(remote, serial),
         remote: { url: server, version: health.version, reads },
         moves,
+        skipped,
     };
 }
 /**
@@ -2640,7 +2663,7 @@ async function cmdInstall(positionals, flags) {
     if (!(0, node_fs_1.existsSync)(path))
         throw new errors_1.CliError(`install: '${appPath}' does not exist`, 2);
     const platform = platformFromFlags(flags);
-    const { backend, remote, moves } = await resolveBackend(platform, deviceFromFlags(flags, platform), flags);
+    const { backend, remote, moves, skipped } = await resolveBackend(platform, deviceFromFlags(flags, platform), flags);
     (0, output_1.err)(`[verikun] installing ${appPath}${remote ? ` via ${remote.url}` : ''}…`);
     try {
         await backend.install(path);
@@ -2657,11 +2680,22 @@ async function cmdInstall(positionals, flags) {
     // device than the one the run started against, and a caller acting on the old serial
     // (`adb -s … shell am start`) would be driving a phone without the build.
     const moved = moves.length ? moves[moves.length - 1] : undefined;
+    // A pooled server may have installed on some devices and dropped the rest. That is a
+    // SUCCESS — the ones that missed the build are no longer leasable, so no later lane can
+    // run the previous build and report green — but it is not a silent one: capacity changed.
     if ((0, args_1.flagBool)(flags, 'json')) {
-        (0, output_1.json)({ installed: appPath, ...(remote ? { server: remote.url } : {}), ...(moved ? { deviceChanged: moved } : {}) });
+        (0, output_1.json)({
+            installed: appPath,
+            ...(remote ? { server: remote.url } : {}),
+            ...(moved ? { deviceChanged: moved } : {}),
+            ...(skipped.length ? { skipped } : {}),
+        });
     }
     else {
         (0, output_1.out)(`installed ${appPath}${moved ? ` on ${moved.to}` : ''}`);
+        if (skipped.length) {
+            (0, output_1.out)(`skipped ${skipped.length} device(s), now out of the pool: ${skipped.map((s) => s.serial).join(', ')}`);
+        }
     }
     return 0;
 }

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

@@ -519,7 +519,26 @@ function buildServer(config) {
         : null;
     // Like the reconcile timer: must never hold the process open at Ctrl-C.
     recycleTimer?.unref?.();
-    const pickFailoverDevice = (failed, reason) => serializeFailover(() => pickFailoverDeviceLocked(failed, reason));
+    /**
+     * Is this failure grounds to REMOVE the device from the pool, rather than merely deal it
+     * last? Two conditions, and both are necessary.
+     *
+     * `unreachable` is the only kind that qualifies, because it is the only one that says the
+     * device is not there. Every other kind describes a device that is present and unhappy —
+     * a full disk, a wedged app, an exit 3 nobody has classified — and for those, demotion
+     * plus recovery-by-traffic is right and this must not change: they can still produce the
+     * traffic that clears them. An absent device cannot, which is the whole defect (#139): the
+     * demotion is a sort key (`leaseFor`), so "dealt last" is still dealt, every round, and
+     * `restoreDevice` can never fire for a device that will never answer again.
+     *
+     * And only on a POOLED server, because only a pooled server sweeps. `reconcileOnce`
+     * returns immediately without `poolSpec` (`wantedSerials`) and its timer is never even
+     * created — see `ServerConfig.poolSpec`, "deliberately does not reconcile". Shedding
+     * where nothing readmits would trade a device that fails loudly for a server that is
+     * empty until someone restarts it: a worse failure, and a new one.
+     */
+    const shedOnFailure = (kind) => kind === 'unreachable' && config.poolSpec !== undefined;
+    const pickFailoverDevice = (failed, reason, kind) => serializeFailover(() => pickFailoverDeviceLocked(failed, reason, kind));
     /**
      * Bring in a healthy replacement for `failed`. Returns the serial moved to, or null
      * when none remains (which is not an error here — the caller reports the ORIGINAL
@@ -533,7 +552,7 @@ function buildServer(config) {
      * only reports ready once its OWN `preflight()` has passed, so starting the worker IS
      * the probe, run on the thread that will go on to use it.
      */
-    const pickFailoverDeviceLocked = async (failed, reason) => {
+    const pickFailoverDeviceLocked = async (failed, reason, kind) => {
         const policy = config.failover;
         if (!policy)
             return null;
@@ -549,23 +568,29 @@ function buildServer(config) {
         // see and where the server will actually go cannot drift. A pool member's own driver
         // is not: it may be pointed at a corpse.
         /**
-         * Nothing healthier exists. Shed the failed device — continuing to hand it out is
-         * what makes a pool a coin flip per lease — but ONLY while another remains.
+         * Nothing healthier exists. Decide what becomes of the failed device itself — THREE
+         * outcomes, not two, and which one applies is `shedOnFailure`'s question:
          *
-         * The LAST device stays, deliberately. A server that shed it would answer every
-         * later request `503 no device attached`, replacing the device's own error (full
-         * disk, no space, whatever it actually was) with a message that names nothing. A
-         * caller stuck on one broken device is better served by the truth about it.
+         *  - GONE, on a pooled server — shed it. It cannot serve and cannot recover by
+         *    traffic, so leaving it in the pool means dealing it forever (#139). The sweep
+         *    owns readmission, so capacity comes back on its own.
+         *  - present but unhappy — demote it: worker, claim and slot kept, dealt last,
+         *    restored by the first command that works.
+         *  - already left on its own (its worker died) — nothing to remove, just clean up.
+         *
+         * The last two share a tail with the first, because "stop serving this device" has the
+         * same consequences however it came about.
          */
         const shrink = async () => {
             // A device whose worker DIED is already out of the pool, so there is nothing left to
             // shed — but its holder still has to be evicted and its claim and companion handed
-            // back, and the "last device stays" guard below must not skip that. Asking whether
-            // it is still a member is what separates the two cases.
+            // back. Asking whether it is still a member is what separates that case from a
+            // device we are removing ourselves.
             const serving = pool.serials().includes(failed);
-            if (serving) {
-                // DEMOTE, never shed. The device keeps its worker, its claim and its place in the
-                // pool; it is simply dealt last until it does some work (see `degradeDevice`).
+            if (serving && !shedOnFailure(kind)) {
+                // DEMOTE — the device is still THERE. It keeps its worker, its claim and its place
+                // in the pool; it is simply dealt last until it does some work (see
+                // `degradeDevice`). Contrast the shed below, which is only for a device that is not.
                 //
                 // This replaces "nothing healthier to move to — X left the pool". That rule read
                 // correctly on a SINGLE-device server, where it never actually fired (the last
@@ -573,10 +598,16 @@ function buildServer(config) {
                 // verdict — because a pool's own members are excluded from its candidate list, so
                 // "no candidate" is the normal case rather than the exceptional one. The argument
                 // for shedding was that continuing to hand out a broken device makes a pool a coin
-                // flip per lease; that is answered by ORDERING (a degraded device is chosen only
-                // when nothing else is free), which costs no capacity. And it is the same judgement
-                // the last-device branch already made out loud: a caller stuck on one broken device
-                // is better served by the truth about it than by a server that quietly halved.
+                // flip per lease; for a device that is PRESENT that is answered by ORDERING (a
+                // degraded device is chosen only when nothing else is free), which costs no
+                // capacity, and a caller that does reach it is better served by the truth about it
+                // than by a server that quietly halved.
+                //
+                // Ordering answers it only while the device can still come back, though. It cannot
+                // answer for a device that is GONE — "dealt last" is still dealt once the healthy
+                // devices are busy, which on a suite sized to the pool is every round, and no
+                // amount of ordering produces the traffic `restoreDevice` needs. That case is
+                // shed above, by `shedOnFailure`.
                 //
                 // The holder keeps its lease too: its device did not go anywhere, so there is no
                 // `deviceChanged` to send and nothing for the run to seal. The step that failed
@@ -585,7 +616,28 @@ function buildServer(config) {
                 degradeDevice(failed, reason);
                 return null;
             }
-            // NOT serving — its worker already died, so the device left on its own and there is
+            if (serving) {
+                // SHED. The device is gone and this server sweeps, so removing it is not the
+                // one-way ratchet it was before the sweep existed (#114): `reconcileOnce` lists it
+                // as missing from what `--devices` asked for, retries with backoff, and
+                // `rejoinDevice` readmits it — bringing it up to `lastInstall` first — the moment
+                // it answers again. Capacity returns without anyone restarting anything.
+                //
+                // It keeps its QUARANTINE, unlike the demote branch above, and that asymmetry is
+                // the point: quarantine means "not serving, and ruled out", degradation means
+                // "serving but suspect", and the two are disjoint precisely so `/v1/health` and
+                // `exhaustedNote` can be read. A shed device genuinely is not serving, so it
+                // belongs in the same list as one whose worker died — which is the tail below,
+                // reached from here. `rejoinDevice` clears it on evidence, never on a clock.
+                //
+                // `degraded` must be given up though: it is defined as pool MEMBERS that recently
+                // failed, and a non-member left in it would have `/v1/health` reporting a device it
+                // no longer serves, in a list whose whole meaning is that it still does.
+                pool.retire(failed);
+                degraded.delete(failed);
+                (0, output_1.err)(`[server] pool: ${failed} left the pool — ${reason} (the sweep readmits it when it answers again)`);
+            }
+            // NOT serving — its worker died, or the shed above just removed it, so there is
             // nothing to demote. The holder is EVICTED, not migrated: without a replacement there
             // is no `deviceChanged` to send, so the client never learns to seal its run — and
             // merely dropping the lease would let its next request silently draw some other device
@@ -690,7 +742,14 @@ function buildServer(config) {
      * Is this device actually gone? Two probes a second apart, because that gap is the only
      * thing separating a USB re-enumeration or a mid-`launch --clear` gap from a dead box —
      * and quarantining a healthy device is the expensive mistake here. Returns the reason
-     * when dead, undefined when it was a blip.
+     * AND the probe's own verdict kind when dead, undefined when it was a blip.
+     *
+     * The kind is carried out because the probe is often the better-classified of the two
+     * failures. The operation that brought us here may have failed with a string nothing
+     * recognises (an unclassified exit 3, which is what earns a probe in the first place),
+     * while `preflight` on a detached phone says `device '<serial>' not found` — the exact
+     * `UNREACHABLE_RULES` wording. Reporting the ORIGINAL verdict's kind there would decide
+     * "shed or demote" from the vaguer of two answers about the same device.
      */
     const deviceIsDead = async (handle) => {
         let last = '';
@@ -722,7 +781,7 @@ function buildServer(config) {
             (0, output_1.err)(`[server] probe on ${handle.serial}: ${verdict.reason} (${verdict.kind}) — a host problem, not this device`);
             return undefined;
         }
-        return last || 'the device stopped answering';
+        return { reason: last || 'the device stopped answering', kind: verdict.kind };
     };
     /**
      * A non-install operation failed. Move off the device if it is genuinely at fault —
@@ -761,6 +820,7 @@ function buildServer(config) {
         try {
             const verdict = (0, failover_1.classifyFailure)(e);
             let reason = verdict.reason;
+            let kind = verdict.kind;
             if (!verdict.move) {
                 // Only an unrecognised exit 3 earns a probe; `transient` and `toolchain` set
                 // probe:false precisely so a mid-launch gap or a missing adb cannot become a move.
@@ -777,15 +837,21 @@ function buildServer(config) {
                     (0, output_1.err)(`[server] ${what}: ${from} failed but probes healthy — staying (${verdict.reason})`);
                     return undefined; // a blip — the test rerun is the right answer, not a new device
                 }
-                reason = dead;
+                reason = dead.reason;
+                // The PROBE's verdict, not the original failure's. We are here because the
+                // operation failed with something nothing recognised; `preflight` on a detached
+                // phone says `device '<serial>' not found`, which is classified. Taking the vaguer
+                // of two answers about the same device is how a detachment that first showed up as
+                // an odd exit 3 would be demoted forever instead of shed.
+                kind = dead.kind;
                 noteVerdict({ ...verdict, move: true }, e, what);
             }
             (0, output_1.err)(`[server] ${what}: FAILED on ${from} — ${reason}`);
             quarantineDevice(from, reason);
-            // pickFailoverDevice has already said which of the two no-move outcomes happened —
-            // the device was shed, or it was the last one and stayed. A second line here would
-            // contradict one of them.
-            const to = await pickFailoverDevice(from, reason);
+            // pickFailoverDevice has already said which no-move outcome happened — the device
+            // was shed, or demoted, or had already left. A second line here would contradict
+            // one of them.
+            const to = await pickFailoverDevice(from, reason, kind);
             if (!to)
                 return undefined;
             return { from, to, reason, retried: false };
@@ -958,6 +1024,9 @@ function buildServer(config) {
             return new server_http_1.HttpError(409, 'the device this run was using left the pool and nothing healthy replaced it — ' +
                 'start a fresh run; this one cannot continue on another device', 3);
         }
+        // An empty pool never reaches here: the deviceless guard in the router answers 503 for
+        // every route that takes a lease, and it names `lostDevice` while doing it. So `n` is
+        // always >= 1 and this only ever describes CONTENTION, which is what 409 means.
         const n = pool.serials().length;
         return new server_http_1.HttpError(409, n > 1
             ? `all ${n} devices are leased by other active runs — retry when one finishes`
@@ -1197,9 +1266,9 @@ function buildServer(config) {
          * wrapper keeps no result on a throw), so dropping it leaves the operator holding a
          * serial the server has already left.
          */
-        const hopOrThrow = async (why, giveUp) => {
+        const hopOrThrow = async (why, giveUp, kind) => {
             quarantineDevice(from, why);
-            const to = await pickFailoverDevice(from, why);
+            const to = await pickFailoverDevice(from, why, kind);
             if (to === null) {
                 // A pool that emptied with nothing having moved keeps its own 503 — a more
                 // accurate status than a wrapped 500.
@@ -1224,7 +1293,9 @@ function buildServer(config) {
                 const gone = firstError ?? new server_http_1.HttpError(503, `device ${from} is no longer attached`, 3);
                 if (!config.failover || hop >= MAX_FAILOVER_HOPS)
                     throw gone;
-                from = await hopOrThrow('the device left the pool mid-install', gone);
+                // `unreachable` is the literal truth — it is not in the pool — and it is also
+                // inert here: `shrink` sees a non-member and takes its cleanup tail either way.
+                from = await hopOrThrow('the device left the pool mid-install', gone, 'unreachable');
                 continue;
             }
             try {
@@ -1241,7 +1312,7 @@ function buildServer(config) {
                 // hops: report the first failure unchanged, exactly as before this feature.
                 if (!verdict.move || !config.failover || hop >= MAX_FAILOVER_HOPS)
                     throw firstError;
-                from = await hopOrThrow(verdict.reason, firstError);
+                from = await hopOrThrow(verdict.reason, firstError, verdict.kind);
             }
         }
     }
@@ -1300,6 +1371,12 @@ function buildServer(config) {
             }));
             const failed = outcomes.filter((o) => o.error);
             const moved = outcomes.filter((o) => o.change);
+            // Where each outcome ENDED UP. An install that moved ran on its replacement, not on
+            // the serial it started from, so the device that holds this build — or conspicuously
+            // does not — is the last one it was on, never `o.serial`.
+            const landedOn = (o) => o.change?.to ?? o.serial;
+            const installed = outcomes.filter((o) => !o.error).map(landedOn);
+            let skipped = [];
             if (failed.length) {
                 // One artifact, many devices: if it failed everywhere the file is the suspect, so
                 // surface the FIRST device's error unchanged rather than a summary that buries it.
@@ -1316,26 +1393,69 @@ function buildServer(config) {
                     }
                     throw failed[0].error;
                 }
-                // Carry a move that DID happen even though the overall install failed: the
-                // client re-points its run context on `deviceChanged`, and dropping it here
-                // would leave the operator holding a serial the server has already left.
-                throw new server_http_1.HttpError(500, `install failed on ${failed.map((f) => `${f.serial} (${(0, server_http_1.firstLine)(f.error.message)})`).join('; ')}`, 3, moved[0]?.change);
+                // PARTIAL. Two healthy phones took the build and one did not. Answering 500 for the
+                // whole pool is what turned one detached device into a dead CI job (#139) — and it
+                // dies at the install step, so the run has already paid for an app build and tested
+                // nothing.
+                //
+                // What made the 500 defensible is the fan-out's own rule, one line up: a lane dealt
+                // a device that missed this build runs the PREVIOUS one and reports green, which is
+                // the worst result this server can produce. The answer is not to soften that rule
+                // but to SATISFY it — a device that did not take the build leaves the pool, so no
+                // lease can reach it. `rejoinDevice` already makes exactly this call out loud
+                // ("serving the wrong build is worse than not serving") and offers the same remedy:
+                // the sweep readmits it and installs `lastInstall` before it is dealt any work.
+                //
+                // Done regardless of `config.failover`. The kill switch governs MOVING BETWEEN
+                // devices; it was never a licence to serve a stale build, and the sweep that brings
+                // the device back is gated on `poolSpec`, not on failover.
+                skipped = failed.map((f) => {
+                    const serial = landedOn(f);
+                    const reason = (0, server_http_1.firstLine)(f.error.message);
+                    if (pool.serials().includes(serial)) {
+                        pool.retire(serial);
+                        // Same two rules as the shed in `shrink`: `degraded` is for MEMBERS, and a
+                        // device that is not serving belongs in `quarantine` — which `rejoinDevice`
+                        // clears on the evidence of a worker that started and a build that installed.
+                        degraded.delete(serial);
+                        quarantineDevice(serial, `did not take the current build — ${reason}`);
+                        evictHoldersOf(serial, `${serial} left the pool without the current build`);
+                        (0, manager_1.releaseCompanionOn)(serial);
+                        if ((0, claims_1.claimsEnabled)(claimEnv))
+                            (0, claims_1.releaseClaim)(serial, { ...claimOpts, mineOnly: true });
+                    }
+                    return { serial, reason };
+                });
+                (0, output_1.err)(`[server] install: partial — ${installed.join(', ')} took the build; ` +
+                    `removed from the pool: ${skipped.map((s) => `${s.serial} (${s.reason})`).join('; ')}`);
             }
             for (const m of moved)
                 (0, output_1.err)(`[server] install: ${m.serial} → ${m.change.to} (${m.moves} move(s))`);
-            (0, output_1.err)(`[server] install: done on ${pool.serials().join(', ')}`);
+            (0, output_1.err)(`[server] install: done on ${installed.join(', ')}`);
             // Retain the artifact so a device that rejoins later can be brought up to this build
             // (see `rejoinDevice`). Renamed out of the per-request temp name into one stable slot,
             // so at most one build is ever held and each install replaces the last.
+            //
+            // Reached on a PARTIAL install too, and load-bearing there: the devices just removed
+            // are precisely the ones the sweep will readmit, and `rejoinDevice` brings a returning
+            // device up to `lastInstall`. Retaining only on a clean sweep would hand each of them
+            // the PREVIOUS build on the way back in — and `rejoinDevice`'s own check would pass,
+            // because an install that succeeds is all it can see.
             retainInstall(tmpPath, ext);
             retained = true;
+            // Only a move whose destination SURVIVED is worth reporting. The client re-points its
+            // run context on `deviceChanged`, so naming a device the partial branch retired three
+            // lines ago would send its next step to a serial this server no longer serves.
+            const survivors = new Set(pool.serials());
+            const reportableMove = moved.map((m) => m.change).find((c) => survivors.has(c.to));
             const body = {
                 ok: true,
                 bytes: size,
                 sha256: digest,
-                devices: pool.serials(),
+                devices: installed,
+                ...(skipped.length ? { skipped } : {}),
                 // The wire field is singular; a pool that moved more than one device logs the rest.
-                ...(moved.length ? { deviceChanged: moved[0].change } : {}),
+                ...(reportableMove ? { deviceChanged: reportableMove } : {}),
             };
             (0, server_http_1.sendJson)(res, 200, body);
         }
@@ -1360,10 +1480,12 @@ function buildServer(config) {
      * phone another job is mid-test on. Refusing plainly beats a rule nobody can predict.
      * The GET listing stays available, because reading what is attached is safe.
      *
-     * KNOWN COST, stated in the refusal so nobody has to discover it: this is also the only
-     * thing that clears a quarantine, so on a pool a device ruled out by failover stays out
-     * until the server is restarted. That is the price of refusing rather than guessing;
-     * lifting it would mean letting a NAMED, allowlisted target act on one pool member.
+     * This used to carry a known cost — that it was the ONLY thing clearing a quarantine, so
+     * on a pool a device ruled out by failover stayed out until the server was restarted.
+     * That is no longer true and the refusal no longer says it: `rejoinDevice` clears the
+     * quarantine (and `degraded`, and `failedOver`) when the sweep readmits a device, on the
+     * evidence of a worker that started and a build that installed. The refusal itself stands
+     * — power-cycling one member of a pool another job is mid-test on is what it prevents.
      */
     function requireSingleDevice(op) {
         const n = pool.serials().length;

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

package/package.json

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