verikun 0.27.1 → 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
 

package/CHANGELOG.md

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

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

@@ -2269,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;
@@ -2283,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;
@@ -2361,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,
     };
 }
 /**
@@ -2659,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);
@@ -2676,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/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.1';
+exports.VERSION = '0.28.0';

package/package.json

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