verikun 0.24.0 → 0.25.0

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

@@ -452,6 +452,19 @@ device; `503` means the server has no device attached — boot one (below). To
 expose a device from THIS machine: `vk server --allow-install`
 (add `--bind <addr>` to leave loopback; auth key auto-generates if unset).
 
+**If you see `[verikun] server moved device: A → B` on stderr**, the server left a
+device that failed and is now on another one. What that means depends on the line:
+
+- `— retried there` (installs only): the build DID land, on **B**. Anything you go on
+  to do with an explicit serial must name B, not A.
+- `— this step failed on the old device; the next runs on the new one`: your step
+  failed on **A**. Do NOT re-run it expecting a different answer for the same reason —
+  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.
+
 ## The device is missing or wedged
 
 ```sh

package/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-08-21
+
+### Added
+- **`vk server`**: moves to another attached healthy device when the bound one fails; only a pinned `--device` disables it. ([#99])
+- **`vk server --allow-failover[=serials]`**: re-enable failover on a pinned server, and bound where it may go.
+- **`vk server --no-failover`** / **`VERIKUN_NO_FAILOVER`**: disable failover outright.
+- **`/v1/health`**: adds `failoverEnabled` and `quarantined`, so a client can see which devices the server ruled out.
+- **`vk install --server`**: reports the device the build landed on when it differs from the one bound.
+
+### Changed
+- **`vk install --server`**: a device-attributable install failure retries on another healthy device.
+- **`/v1/exec`**, **`/v1/elements`**: report `deviceChanged` when the server moved device; the failing step is never replayed.
+
+### Fixed
+- **`/v1/logs`**: served the startup device's logs after a rebind instead of the bound device's.
+- **`/v1/health`**: reported the startup device's read path after a rebind.
+
+[#99]: https://github.com/ddikman/verikun/issues/99
+
 ## [0.24.0] - 2026-08-20
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
 - **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
-- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it.
+- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it, and moves to another attached device if that one goes bad.
 
 ```
 $ vk ui

package/dist/agent/remote.js

@@ -89,8 +89,14 @@ class RemoteTransport {
         finally {
             clearTimeout(timer);
         }
-        if (!res.ok)
-            throw describeStatus(res.status, await readBody(res), url);
+        if (!res.ok) {
+            const body = await readBody(res);
+            // Before throwing: a failing request may still have moved the device, and that is
+            // exactly the case a caller must not miss (an exhausted install, a dead-device read).
+            if (body?.deviceChanged)
+                this.opts.onDeviceChange?.(body.deviceChanged);
+            throw describeStatus(res.status, body, url);
+        }
         const parsed = await readBody(res);
         if (parsed === null)
             throw new errors_1.CliError(`verikun server at ${url} returned a non-JSON response`, 3);
@@ -157,6 +163,9 @@ function createRemoteBackend(opts, health) {
         const res = await t.postJson('/v1/exec', req, EXEC_TIMEOUT_MS);
         if (record && res.step)
             opts.onStep?.(res.step, decodeArtifacts(res.artifacts), res.logStart);
+        // A failing step is a 200, so this is the ordinary path for a mid-run device death.
+        if (res.deviceChanged)
+            opts.onDeviceChange?.(res.deviceChanged);
         return { code: res.code, error: res.error ? (0, rpc_1.rebuildError)(res.error) : undefined };
     };
     return {
@@ -184,11 +193,15 @@ function createRemoteBackend(opts, health) {
                 throw new errors_1.CliError(`install: cannot read '${appPath}' (${e.message})`, 2);
             }
             const sha256 = (0, node_crypto_1.createHash)('sha256').update(buf).digest('hex');
-            await t.request('POST', '/v1/install', buf, INSTALL_TIMEOUT_MS, {
+            const res = await t.request('POST', '/v1/install', buf, INSTALL_TIMEOUT_MS, {
                 'content-type': 'application/octet-stream',
                 'x-verikun-ext': ext,
                 'x-verikun-sha256': sha256,
             });
+            // Install is the one operation the server replays elsewhere, so a move here means
+            // the build DID land — on a different device than the one we started with.
+            if (res.deviceChanged)
+                opts.onDeviceChange?.(res.deviceChanged);
         },
         async reset(appId) {
             // Between-test housekeeping (vk suite): the step is deliberately NOT spliced

package/dist/args.js

@@ -49,10 +49,12 @@ const BOOLEAN = new Set([
     'no-sleep-when-idle',
     'allow-install',
     'allow-unsafe-anonymous',
-    // NOT here on purpose: 'allow-device-control' and 'ensure-device' are tri-state
-    // (absent / on / on-with-a-value), and the inline `--flag=value` branch is checked
-    // BEFORE this set — listing them would make `--allow-device-control=Pixel_6` parse
-    // fine but `--ensure-device Pixel_6` silently become a boolean plus a positional.
+    'no-failover',
+    // NOT here on purpose: 'allow-device-control', 'allow-failover' and 'ensure-device'
+    // are tri-state (absent / on / on-with-a-value), and the inline `--flag=value` branch
+    // is checked BEFORE this set — listing them would make `--allow-device-control=Pixel_6`
+    // parse fine but `--ensure-device Pixel_6` silently become a boolean plus a positional.
+    // Its opposite, 'no-failover', never takes a value, so it DOES belong above.
     // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.
     // `enabled` was missing here until 0.15.0, and the omission was not cosmetic: a
     // non-BOOLEAN flag swallows the next token, so `vk tap --enabled @submit` bound

package/dist/cli.js

@@ -50,6 +50,7 @@ exports.chooseLogOpts = chooseLogOpts;
 exports.evalAssert = evalAssert;
 exports.tokenizeLine = tokenizeLine;
 exports.withBatchGlobals = withBatchGlobals;
+exports.retryAfterDeviceMove = retryAfterDeviceMove;
 exports.serverFromFlags = serverFromFlags;
 exports.ensureDeviceTarget = ensureDeviceTarget;
 exports.terminalFailure = terminalFailure;
@@ -1999,6 +2000,38 @@ async function obtainPlan(key, file, opts, cost, provider) {
     }
     return { plan: compiled.plan, cached: false };
 }
+// --- execution backend (local driver vs remote `vk server`) -----------------
+//
+// `vk ai`, `vk suite`, and `vk install` run their device work through an
+// ExecBackend. Local wraps one shared Driver; remote speaks HTTP to a `vk server`
+// beside the device (--server / VERIKUN_SERVER), where each validated leaf is ONE
+// round-trip (the auto-wait loop stays server-side). In remote mode the server
+// owns the device: its /v1/health platform+serial supersede the client's
+// --platform/--device, and no local driver is ever built.
+/**
+ * Run a remote read; if it failed AND the server reported it moved device, ask once more.
+ *
+ * This is the ONE place a failed remote read is re-asked, and the narrowness is the point.
+ * It is only ever wired to `preflight` — the connect probe at `vk ai`/`vk suite` startup and
+ * the suite's between-tests health check — where nothing has run yet on either device. A
+ * mid-flow read is never retried: the new device has none of the state the flow built up, so
+ * its screen would answer a different question than the one being asked.
+ *
+ * Gating on the move (rather than retrying every failure) also keeps the connect probe's
+ * fail-fast property: a device that is simply broken still fails on the first try.
+ *
+ * Exported solely so the unit suite can reach it.
+ */
+async function retryAfterDeviceMove(read, moved) {
+    try {
+        return await read();
+    }
+    catch (e) {
+        if (!moved())
+            throw e;
+        return read();
+    }
+}
 /** The `--server` URL, or VERIKUN_SERVER. Exported-shape helper so `resolveBackend`
  *  and `vk devices --server` can never disagree about what "remote" means. */
 function serverFromFlags(flags) {
@@ -2171,9 +2204,14 @@ async function resolveBackend(platform, device, flags) {
             },
             platform,
             device,
+            moves: [],
         };
     }
     let runCtx = { platform, device };
+    const moves = [];
+    /** Set by the last move; the preflight below reads it to decide whether re-asking is
+     *  warranted, then clears it. */
+    let movedDuringCall;
     const opts = {
         url: server,
         authKey: (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined,
@@ -2181,6 +2219,19 @@ 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 }),
+        onDeviceChange: (c) => {
+            moves.push(c);
+            movedDuringCall = c;
+            // Re-point the run context, so steps after the move are attributed to the device
+            // that actually ran them. This makes `rolloverReason` seal the device-A run and
+            // open a fresh one for B — intended: since a step is never replayed, no single run
+            // can contain steps from two devices, and a report that claimed otherwise would lie.
+            runCtx = { ...runCtx, device: c.to };
+            (0, output_1.err)(`[verikun] server moved device: ${c.from} → ${c.to} (${c.reason})` +
+                (c.retried
+                    ? ' — retried there'
+                    : ' — this step failed on the old device; the next runs on the new one'));
+        },
     };
     let health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
     // `--ensure-device` boots BEFORE runCtx is fixed: resolveBackend bakes the serial
@@ -2188,7 +2239,15 @@ async function resolveBackend(platform, device, flags) {
     // attribute every spliced step to a device that didn't exist yet.
     health = await ensureRemoteDevice(health, opts, server, flags);
     runCtx = { platform: health.platform, device: health.serial ?? undefined };
-    (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial ?? '(none)'} · verikun ${health.version}`);
+    (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial ?? '(none)'} · verikun ${health.version}` +
+        (health.failoverEnabled ? ' · failover: on' : ''));
+    // A pool the server has already ruled out explains a lot of otherwise-baffling
+    // behaviour ("why is it on THAT phone?"), so say it once, up front.
+    if (health.quarantined?.length) {
+        (0, output_1.err)(`[verikun] server has ruled out ${health.quarantined.length} device(s):`);
+        for (const q of health.quarantined)
+            (0, output_1.err)(`[verikun]   ${q.serial}  ${q.reason}`);
+    }
     // Say the read path once, here. Reads execute server-side, so this is the only end of the
     // connection that knows it — and without it a companion that had silently stood down was
     // indistinguishable from one that never engaged, for a whole suite (issue #77). An older
@@ -2206,7 +2265,8 @@ async function resolveBackend(platform, device, flags) {
             // healthy and keep grinding. One dump is the cheap call that actually proves it.
             preflight: async () => {
                 await (0, remote_1.pingServer)(opts);
-                await remote.getElements();
+                movedDuringCall = undefined;
+                await retryAfterDeviceMove(() => remote.getElements(), () => movedDuringCall !== undefined);
             },
             // Hierarchy only: the server exposes no screenshot route, so a remote run's
             // engine failure archives without a picture. Honest degrade over a protocol
@@ -2223,6 +2283,7 @@ async function resolveBackend(platform, device, flags) {
         platform: health.platform,
         device: health.serial ?? undefined,
         remote: { url: server, version: health.version, reads: health.reads },
+        moves,
     };
 }
 /**
@@ -2501,7 +2562,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 } = await resolveBackend(platform, deviceFromFlags(flags, platform), flags);
+    const { backend, remote, moves } = await resolveBackend(platform, deviceFromFlags(flags, platform), flags);
     (0, output_1.err)(`[verikun] installing ${appPath}${remote ? ` via ${remote.url}` : ''}…`);
     try {
         await backend.install(path);
@@ -2509,10 +2570,16 @@ async function cmdInstall(positionals, flags) {
     finally {
         await backend.close?.();
     }
-    if ((0, args_1.flagBool)(flags, 'json'))
-        (0, output_1.json)({ installed: appPath, ...(remote ? { server: remote.url } : {}) });
-    else
-        (0, output_1.out)(`installed ${appPath}`);
+    // Where it LANDED, not just that it landed: after a failover that is a different
+    // 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;
+    if ((0, args_1.flagBool)(flags, 'json')) {
+        (0, output_1.json)({ installed: appPath, ...(remote ? { server: remote.url } : {}), ...(moved ? { deviceChanged: moved } : {}) });
+    }
+    else {
+        (0, output_1.out)(`installed ${appPath}${moved ? ` on ${moved.to}` : ''}`);
+    }
     return 0;
 }
 // ---------------------------------------------------------------------------
@@ -2961,7 +3028,7 @@ SUITE (run a directory of natural-language tests as one gated suite)
 
 SERVER (expose a locally-connected device to remote verikun clients)
   server [--bind addr] [--port n] [--auth-key k] [--allow-install]
-         [--allow-device-control[=names]]
+         [--allow-device-control[=names]] [--allow-failover[=serials]|--no-failover]
          [--allow-unsafe-anonymous]  Serve THIS machine's device over HTTP+JSON for
                                       \`vk ai/suite/install --server <url>\`. Only
                                       verikun's validated action grammar is runnable
@@ -2979,6 +3046,12 @@ SERVER (expose a locally-connected device to remote verikun clients)
   the flag the server also starts even when no device is attached, so a client can
   boot one: \`vk devices start|stop|restart [name] --server <url>\`, or add
   --ensure-device[=name] to ai/suite/install to boot once before the first step.
+  Failover is ON by default: if the bound device cannot serve a request, the server
+  moves to another attached, healthy, unclaimed one and rules the bad one out until it
+  is power-cycled. An install is retried there; a mid-run step is NOT — it fails on the
+  device it ran on, and the next request lands on the healthy one. Passing --device
+  pins the binding and turns this off; --allow-failover[=serials] turns it back on (and
+  bounds where it may go), --no-failover / VERIKUN_NO_FAILOVER disables it outright.
 
 ENVIRONMENT
   devices [--all] [--json]            List attached devices/simulators, and which job is

package/dist/device/failover.js

@@ -0,0 +1,230 @@
+"use strict";
+// Should `vk server` move off the device it is bound to, and which device next?
+//
+// PURE — no fs, no spawn, no timers, no Driver. It classifies strings some driver has
+// already produced and filters a list somebody else enumerated, so the whole matrix is
+// unit-testable with no device. Platform-agnostic by design, like `device/settings.ts`
+// and `device/claims.ts`; the probing and the rebinding live in `server.ts`.
+//
+// THE POLARITY IS THE DESIGN, so read this before touching the tables.
+//
+// `install X onto Y` has exactly two operands, so a failure is about the FILE or about
+// the DEVICE — there is no third thing. The file-attributable set is small, closed and
+// decade-stable (a parser's verdict on a byte sequence is identical on every device).
+// The device-attributable set is open-ended, OEM-specific and unknowable in advance —
+// the failure that prompted this (issue #99) carried no `INSTALL_FAILED_*` code at all,
+// just a raw `java.io.IOException: Requested internal only, but not enough space`.
+//
+// So the ENUMERABLE side is the one we enumerate, and the default falls the other way:
+// an install failure moves unless it matches the artifact denylist. The named
+// device-state strings below are a FAST PATH and documentation, never the gate —
+// deleting one changes the reason text, never the decision. That is what makes this
+// survive phrasings nobody has met yet, and it is the property `tests/failover.test.ts`
+// pins by feeding the classifier pure gibberish and asserting it still moves.
+//
+// `exec`/`elements` keep the OPPOSITE default, and that asymmetry is deliberate rather
+// than sloppy: it is the same "which operand is at fault?" question with a different
+// answer. There the operand is the app under test, and the exit-3 population is
+// dominated by transient device noise (a flaky uiautomator dump, NoWindowError, a
+// keyguard read). Moving on those would rotate the pool on ordinary flake, so that arm
+// moves only on an unreachable device or one a probe confirms is dead.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyFailure = classifyFailure;
+exports.classifyInstallFailure = classifyInstallFailure;
+exports.failoverCandidates = failoverCandidates;
+const errors_1 = require("../errors");
+// --- the artifact denylist: the ONLY thing that blocks an install failover -----
+//
+// Every entry is a property of the FILE. A parser verdict on a byte sequence is the
+// same on every device, so a second attempt elsewhere is a guaranteed second failure.
+const ARTIFACT_RULES = [
+    // One prefix covers all ten INSTALL_PARSE_FAILED_* variants (NOT_APK, BAD_MANIFEST,
+    // NO_CERTIFICATES, INCONSISTENT_CERTIFICATES, MANIFEST_MALFORMED, …).
+    [/INSTALL_PARSE_FAILED_(\w+)/, 'the APK does not parse'],
+    [/INSTALL_FAILED_INVALID_APK/, 'the APK is not a valid package'],
+    [/INSTALL_FAILED_INVALID_URI/, 'the install path is not valid'],
+    [/INSTALL_FAILED_PACKAGE_CHANGED/, 'the APK changed between staging and commit (corrupt upload)'],
+    [/INSTALL_FAILED_TEST_ONLY/, 'the APK is marked test-only (needs `adb install -t`)'],
+    // Dexopt CAN OOM, but the dominant cause is a bad build, and a wrong move costs a
+    // full install per device and still ends red. Flip it if the field disagrees.
+    [/INSTALL_FAILED_DEXOPT/, 'the APK failed dexopt (usually a bad build)'],
+    // The server's OWN temp file, not the device's storage — a host bug. Moving would
+    // burn the whole pool on a problem no device can fix.
+    [/adb: failed to stat|can't find '[^']*\.(?:apk|ipa)'/i, 'the server could not read the uploaded file'],
+];
+/** Clears by itself; the device is not exhausted. */
+const TRANSIENT_RULES = [[/INSTALL_FAILED_ABORTED/, 'the install session was aborted']];
+// --- fast paths: name the reason and skip the probe. NEVER the gate. ----------
+const UNREACHABLE_RULES = [
+    [/device (?:'[^']*' )?not found/i, 'the device is not attached'],
+    [/no devices\/emulators found/i, 'no device is attached'],
+    [/device offline/i, 'the device is offline'],
+    [/device (?:still authorizing|unauthorized)/i, 'the device is not authorized'],
+    [/error: closed|protocol fault|failed to get feature set/i, 'the adb connection dropped'],
+    [/is not ready \(/, 'the device is not ready'],
+];
+const DEVICE_STATE_RULES = [
+    // Both spellings of a full disk. The second is the one from #99, and it arrives with
+    // NO INSTALL_FAILED_* code — which is precisely why the denylist, not this list, is
+    // what decides. Keep both: they only shape the message.
+    [/INSTALL_FAILED_INSUFFICIENT_STORAGE/, 'the device is out of space'],
+    [/Requested internal only, but not enough space|not enough space/i, 'the device is out of space'],
+    [/INSTALL_FAILED_UPDATE_INCOMPATIBLE/, 'a differently-signed build of this package is installed on the device'],
+    [/INSTALL_FAILED_VERSION_DOWNGRADE/, 'the device holds a newer build of this package'],
+    [/INSTALL_FAILED_ALREADY_EXISTS/, 'the package is already installed on the device'],
+    [/INSTALL_FAILED_DUPLICATE_PERMISSION/, 'another app on the device declares one of these permissions'],
+    [/INSTALL_FAILED_CONFLICTING_PROVIDER/, 'another app on the device owns one of these provider authorities'],
+    [/INSTALL_FAILED_UID_CHANGED|INSTALL_FAILED_SHARED_USER_INCOMPATIBLE/, "the existing install's identity on the device conflicts"],
+    [/INSTALL_FAILED_USER_RESTRICTED/, 'this device or profile disallows installs'],
+    [/INSTALL_FAILED_MEDIA_UNAVAILABLE/, "the device's storage is not mounted"],
+    [/INSTALL_FAILED_VERIFICATION_(?:FAILURE|TIMEOUT)/, "the device's package verifier rejected the build"],
+    // Device-RELATIVE, so another device genuinely takes it.
+    [/INSTALL_FAILED_MISSING_SHARED_LIBRARY/, 'the device lacks a shared library this build needs'],
+    [/INSTALL_FAILED_NO_MATCHING_ABIS/, "the build has no native code for this device's ABI"],
+    [/INSTALL_FAILED_OLDER_SDK/, "the build needs a newer Android than this device runs"],
+    [/INSTALL_FAILED_INTERNAL_ERROR/, "the device's package manager failed internally"],
+];
+/** adb/idb itself is missing or broken. Matched on the wording `exec.ts` and the tool
+ *  probes produce — a hint string is the reliable marker, since the detail varies. */
+const TOOLCHAIN_RULES = [
+    [/was not found on PATH/i, 'the device toolchain is not installed'],
+    [/install the Android platform-tools/i, 'adb is missing or broken'],
+    [/brew install idb-companion|xcode-select --install/i, 'the iOS toolchain is missing or broken'],
+];
+/** First matching rule, or undefined. */
+function firstMatch(message, rules) {
+    for (const [pattern, reason] of rules) {
+        const m = pattern.exec(message);
+        if (m)
+            return m[0].startsWith('INSTALL_') ? `${reason} (${m[0]})` : reason;
+    }
+    return undefined;
+}
+/** The exit code a thrown value carries, or 3 for a non-CliError (matching `run()`). */
+function exitCodeOf(e) {
+    return e instanceof errors_1.CliError ? e.exitCode : 3;
+}
+const messageOf = (e) => (e instanceof Error ? e.message : String(e ?? ''));
+/**
+ * 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' };
+    }
+    const code = exitCodeOf(e);
+    if (code === 0 || code === 1)
+        return { move: false, kind: 'app', reason: 'the app failed, not the device' };
+    if (code === 2)
+        return { move: false, kind: 'usage', reason: 'the request was refused, not the device' };
+    const message = messageOf(e);
+    const toolchain = firstMatch(message, TOOLCHAIN_RULES);
+    if (toolchain)
+        return { move: false, kind: 'toolchain', reason: toolchain };
+    const transient = firstMatch(message, TRANSIENT_RULES);
+    if (transient)
+        return { move: false, kind: 'transient', reason: transient };
+    const unreachable = firstMatch(message, UNREACHABLE_RULES);
+    if (unreachable)
+        return { move: true, kind: 'unreachable', reason: unreachable };
+    return { ...fallback };
+}
+/** Nothing matched, and the message has no opinion. Ask the device instead of guessing. */
+const UNKNOWN_STAY = {
+    move: false,
+    kind: 'unknown',
+    reason: 'the device may still be fine — asking it',
+    probe: true,
+    unclassified: true,
+};
+/**
+ * The generic arm: `exec`, `elements`, and anything that is not an install.
+ *
+ * STAY unless the device is provably unreachable, or a probe says so. Accepts `unknown`
+ * so a `catch (e)` binding passes straight in, mirroring `isEnvError`.
+ */
+function classifyFailure(e) {
+    return classify(e, UNKNOWN_STAY);
+}
+/**
+ * The install arm: MOVE unless the failure is provably about the FILE.
+ *
+ * `handleInstall` knows it just ran an install and calls this explicitly — sniffing the
+ * message to pick an arm would couple the classifier to a message format that is free
+ * to change.
+ */
+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)) {
+        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.
+        const artifact = firstMatch(message, ARTIFACT_RULES);
+        if (artifact)
+            return { move: false, kind: 'artifact', reason: artifact };
+        const toolchain = firstMatch(message, TOOLCHAIN_RULES);
+        if (toolchain)
+            return { move: false, kind: 'toolchain', reason: toolchain };
+        const transient = firstMatch(message, TRANSIENT_RULES);
+        if (transient)
+            return { move: false, kind: 'transient', reason: transient };
+        const unreachable = firstMatch(message, UNREACHABLE_RULES);
+        if (unreachable)
+            return { move: true, kind: 'unreachable', reason: unreachable };
+        const named = firstMatch(message, DEVICE_STATE_RULES);
+        if (named)
+            return { move: true, kind: 'device-state', reason: named };
+        // The inversion. Not in the denylist ⇒ it is about the device, even though we have
+        // never seen this wording. Bounded by MAX_FAILOVER_HOPS, and the caller reports the
+        // FIRST device's error on exhaustion, so a wrong guess costs time, not diagnosis.
+        return { move: true, kind: 'device-state', reason: 'the device could not install this build', unclassified: true };
+    }
+    return classify(e, UNKNOWN_STAY);
+}
+/**
+ * Which attached devices could take over, in preference order.
+ *
+ * Listing order is preserved for the same reason `selectAndClaim` documents it: a device
+ * that worked last time is the one most likeliest to work now, and round-robining would
+ * spread a flaky run across the whole pool.
+ *
+ * Claim status is deliberately NOT a filter — deciding "this one is free" and then
+ * claiming it is the exact read-then-write race `device/claims.ts` exists to prevent.
+ * The caller claims as it walks.
+ */
+function failoverCandidates(devices, opts) {
+    const excluded = new Set(opts.exclude.filter(Boolean));
+    const allow = opts.allow ?? [];
+    return devices.filter((d) => {
+        // An unbooted AVD is { serial: '', state: 'shutdown' } and has no adb address.
+        // Failover is lateral, never upward: booting is `vk devices start`'s job.
+        if (!d.serial)
+            return false;
+        if (!isUsableState(d.state))
+            return false;
+        if (excluded.has(d.serial))
+            return false;
+        // Name OR serial: an operator writes `Pixel_6_API_34` for an AVD and a raw serial
+        // for a phone, and being forced to know which is which is a papercut with teeth.
+        if (allow.length && !allow.includes(d.serial) && !(d.name && allow.includes(d.name)))
+            return false;
+        return true;
+    });
+}
+/**
+ * Is this device drivable right now? The two platforms spell it differently.
+ *
+ * Deliberately DUPLICATED from `isRunning` in drivers/lifecycle.ts rather than imported:
+ * that module imports adb.ts and ios.ts, so importing it here would drag both platform
+ * backends into a module whose whole value is being pure. One line of duplication is the
+ * cheaper side of that trade.
+ */
+function isUsableState(state) {
+    return state === 'device' || state === 'booted';
+}

package/dist/server.js

@@ -34,6 +34,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildServer = buildServer;
 exports.parseDeviceControl = parseDeviceControl;
+exports.parseFailover = parseFailover;
 exports.cmdServer = cmdServer;
 const node_http_1 = require("node:http");
 const node_crypto_1 = require("node:crypto");
@@ -47,6 +48,7 @@ const errors_1 = require("./errors");
 const drivers_1 = require("./drivers");
 const manager_1 = require("./companion/manager");
 const claims_1 = require("./device/claims");
+const failover_1 = require("./device/failover");
 const lifecycle_1 = require("./drivers/lifecycle");
 const output_1 = require("./output");
 const ir_1 = require("./agent/ir");
@@ -76,6 +78,15 @@ const INSTALL_BODY_CAP = 512 * 1024 * 1024; // 512 MB app build
 // to survive a client-side compile/repair pause, short enough that a crashed
 // caller doesn't wedge the device.
 const LOCK_IDLE_MS = 5 * 60 * 1000;
+// How many times ONE request may move device. 2 moves = 3 devices tried, which sits
+// comfortably inside the client's 15-minute install ceiling at ~1 minute an install,
+// while a farm of ten wedged emulators cannot burn ten installs inside one request.
+const MAX_FAILOVER_HOPS = 2;
+// Gap between the two probes that separate a momentary blip from a dead device. Mirrors
+// suite.ts's stillBroken, and for the same reason: a flaky dump also surfaces as exit 3,
+// so acting on one probe would rotate the pool on ordinary flake.
+const PROBE_RETRY_MS = 1000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Deliberately below the client's 5-minute ceiling, so a slow boot is reported by the
 // side that knows WHY ("did not finish booting within 240s") rather than as a generic
 // client-side abort.
@@ -84,13 +95,20 @@ const SERVER_BOOT_TIMEOUT_MS = 4 * 60 * 1000;
 class HttpError extends Error {
     status;
     exitCode;
-    constructor(status, message, exitCode = status === 400 || status === 404 || status === 413 ? 2 : 3) {
+    deviceChanged;
+    constructor(status, message, exitCode = status === 400 || status === 404 || status === 413 ? 2 : 3, 
+    /** Set when this request moved the server's device before failing — the client
+     *  needs to know the ground shifted even though the answer is an error. */
+    deviceChanged) {
         super(message);
         this.status = status;
         this.exitCode = exitCode;
+        this.deviceChanged = deviceChanged;
         this.name = 'HttpError';
     }
 }
+/** Errors here are multi-line (detail + hint); logs and reasons want the headline. */
+const firstLine = (m) => m.split('\n')[0].trim();
 function sendJson(res, status, payload) {
     const body = JSON.stringify(payload);
     res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
@@ -181,6 +199,8 @@ function buildServer(config) {
     const sha = (s) => (0, node_crypto_1.createHash)('sha256').update(s, 'utf8').digest();
     const lifecycle = config.lifecycle ?? realLifecycle;
     const makeDriver = config.makeDriver ?? drivers_1.getDriver;
+    const claimOpts = config.claimOpts ?? {};
+    const claimEnv = claimOpts.env ?? process.env;
     // The ONE piece of server state a request can change, and only via /v1/devices/*.
     // Everything in `config` is startup policy and is never written. Grep `bound =`
     // to find every rebind.
@@ -190,11 +210,170 @@ function buildServer(config) {
     // on a different port would leave a permanently dead instance. Always rebind to the
     // CONCRETE serial the lifecycle layer returned — never undefined, which would
     // auto-resolve and could silently latch onto a different attached device.
-    const rebind = (serial) => {
-        bound = serial === null ? { driver: bound.driver, serial: null } : { driver: makeDriver(config.platform, serial), serial };
+    //
+    // `driver` is passed when the caller has ALREADY built and probed one (failover), so
+    // the instance that answered the probe is the instance we go on to use.
+    const rebind = (serial, driver) => {
+        bound =
+            serial === null
+                ? { driver: bound.driver, serial: null }
+                : { driver: driver ?? makeDriver(config.platform, serial), serial };
         config.onRebind?.(serial);
         (0, output_1.err)(`[server] device: ${config.platform} · ${serial ?? '(none)'}`);
     };
+    // --- failover ---------------------------------------------------------------
+    //
+    // Devices this server has ruled out, and why. In-memory, PROCESS-LIFETIME, no TTL: a
+    // TTL would silently re-try a device that ran out of disk ten minutes ago and burn
+    // another full install on it, on a schedule nobody can see — precisely the minutes
+    // this feature exists to save. A power cycle is the fix, so a successful
+    // /v1/devices/{start,restart,stop} is what clears an entry (see handleDeviceOp).
+    const quarantine = new Map();
+    const quarantineDevice = (serial, reason) => {
+        if (!serial || quarantine.has(serial))
+            return;
+        quarantine.set(serial, { reason, at: Date.now() });
+        (0, output_1.err)(`[server] failover: ${serial} quarantined (${reason})`);
+    };
+    /** For /v1/health and the exhaustion message. */
+    const quarantineList = () => [...quarantine.entries()].map(([serial, q]) => ({ serial, reason: q.reason }));
+    /**
+     * Move to another healthy device. Returns the serial moved to, or null when none
+     * remains (which is not an error here — the caller reports the ORIGINAL failure).
+     *
+     * The walk order is load-bearing: claim-new -> probe -> commit -> release-old.
+     * Releasing the old claim first would leave this server bound to a device it no longer
+     * holds, and another job on the host would take it mid-request.
+     */
+    const pickFailoverDevice = () => {
+        const policy = config.failover;
+        if (!policy)
+            return null;
+        const from = bound.serial;
+        // lifecycle.list is the SAME source /v1/devices answers from, so what a client can
+        // see and where the server will actually go cannot drift. bound.driver is not: it
+        // may be pointed at a corpse.
+        let seen = [];
+        try {
+            seen = lifecycle.list(config.platform);
+        }
+        catch (e) {
+            (0, output_1.err)(`[server] failover: cannot enumerate devices (${firstLine(e.message)})`);
+            return null;
+        }
+        const candidates = (0, failover_1.failoverCandidates)(seen, {
+            exclude: [...(from ? [from] : []), ...quarantine.keys()],
+            allow: policy.allowedTargets,
+        });
+        if (!candidates.length)
+            return null;
+        (0, output_1.err)(`[server] failover: ${candidates.length} candidate(s) — ${candidates.map((d) => d.serial).join(', ')}`);
+        for (const c of candidates) {
+            // Claim BEFORE probing: deciding "this one is free" and then taking it is the
+            // read-then-write race device/claims.ts exists to prevent.
+            if ((0, claims_1.claimsEnabled)(claimEnv) && !(0, claims_1.claimDevice)(c.serial, config.platform, claimOpts).ok) {
+                (0, output_1.err)(`[server] failover: ${c.serial} is held by another job — skipping`);
+                continue;
+            }
+            const driver = makeDriver(config.platform, c.serial);
+            try {
+                // ONE probe per candidate, against TWO for the bound device on the unknown path.
+                // Deliberate: a false negative here just moves to the next candidate, while a
+                // false positive there quarantines a device that was fine.
+                driver.preflight();
+            }
+            catch (e) {
+                if ((0, claims_1.claimsEnabled)(claimEnv))
+                    (0, claims_1.releaseClaim)(c.serial, { ...claimOpts, mineOnly: true });
+                quarantineDevice(c.serial, `probe failed (${firstLine(e.message)})`);
+                continue;
+            }
+            (0, output_1.err)(`[server] failover: ${c.serial} probe ok — moving`);
+            if (from) {
+                // Hand back the old device's ONE UiAutomation connection, or it stays held for
+                // up to 15 minutes with nothing on the host able to explain why. Never throws.
+                (0, manager_1.releaseCompanionOn)(from);
+                if ((0, claims_1.claimsEnabled)(claimEnv))
+                    (0, claims_1.releaseClaim)(from, { ...claimOpts, mineOnly: true });
+            }
+            rebind(c.serial, driver);
+            return c.serial;
+        }
+        return null;
+    };
+    /** Why no move happened, in a form worth putting in front of an operator. */
+    const exhaustedNote = () => {
+        const rows = quarantineList().map((q) => `  ${q.serial}  ${q.reason}`);
+        return (`\n[failover] no working device remains${rows.length ? `; ruled out:\n${rows.join('\n')}` : ''}` +
+            '\n[failover] clear one with `vk devices restart <name> --server <url>`, or fix it and restart the server');
+    };
+    /** Announce an unrecognised move, so real-world strings reach a CI log and can be
+     *  promoted into device/failover.ts's tables deliberately rather than guessed at. */
+    const noteVerdict = (v, e, what) => {
+        if (v.unclassified && v.move) {
+            (0, output_1.err)(`[server] failover: unclassified ${what} failure, treating as device-attributable — ${firstLine(e.message)}`);
+        }
+    };
+    /**
+     * Is the bound 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.
+     */
+    const boundDeviceIsDead = async () => {
+        let last = '';
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (attempt > 0)
+                await sleep(PROBE_RETRY_MS);
+            try {
+                bound.driver.preflight();
+                return undefined;
+            }
+            catch (e) {
+                last = firstLine(e.message);
+            }
+        }
+        return last || 'the device stopped answering';
+    };
+    /**
+     * A non-install operation failed. Move off the device if it is genuinely at fault —
+     * but NEVER replay the operation there.
+     *
+     * That restraint is the whole point. A `vk ai` step twelve deep presupposes the eleven
+     * before it ran on THIS device; device B's app is at whatever an earlier run left
+     * behind. Replaying would either find something matching and go green (a false green
+     * that ships a regression) or wake the repair model against the wrong screen. So the
+     * failing operation still fails, honestly, with the ORIGINAL device's error — and it is
+     * the NEXT request that benefits from the move.
+     *
+     * Returns the change to report, or undefined when we stayed put.
+     */
+    const considerFailover = async (e, what) => {
+        if (!config.failover)
+            return undefined;
+        const verdict = (0, failover_1.classifyFailure)(e);
+        let reason = verdict.reason;
+        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.
+            if (!verdict.probe)
+                return undefined;
+            const dead = await boundDeviceIsDead();
+            if (!dead)
+                return undefined; // a blip — the test rerun is the right answer, not a new device
+            reason = dead;
+            noteVerdict({ ...verdict, move: true }, e, what);
+        }
+        (0, output_1.err)(`[server] ${what}: FAILED on ${bound.serial ?? '(none)'} — ${reason}`);
+        const from = bound.serial ?? '(none)';
+        quarantineDevice(bound.serial, reason);
+        const to = pickFailoverDevice();
+        if (!to) {
+            (0, output_1.err)(`[server] failover: nothing healthier to move to — staying on ${from}`);
+            return undefined;
+        }
+        return { from, to, reason, retried: false };
+    };
     const authorized = (req) => {
         if (!config.authKey)
             return true; // --allow-unsafe-anonymous
@@ -249,9 +428,13 @@ function buildServer(config) {
         const t0 = Date.now();
         const { code, error, step, artifacts, logStart } = await (0, cli_1.executeForServer)(node.command, node.positionals, (0, ir_1.leafToFlags)(node), bound.driver, config.platform);
         (0, output_1.err)(`[server] exec ${node.command} ${node.positionals.join(' ')} → exit ${code} (${Date.now() - t0}ms)`);
+        // The step keeps its own verdict whatever we decide here: the error below is the one
+        // THIS device produced, never a replay's. Only the binding moves.
+        const deviceChanged = code !== 0 && error ? await considerFailover(error, 'exec') : undefined;
         const payload = {
             code,
             ...(error ? { error: (0, rpc_1.describeError)(error) } : {}),
+            ...(deviceChanged ? { deviceChanged } : {}),
             ...(step ? { step } : {}),
             ...(artifacts && Object.keys(artifacts).length ? { artifacts: encodeArtifacts(artifacts) } : {}),
             ...(logStart ? { logStart } : {}),
@@ -260,8 +443,20 @@ function buildServer(config) {
     }
     async function handleElements(req, res) {
         await readBody(req, EXEC_BODY_CAP); // drain (the body is unused; keeps keep-alive sane)
-        const elements = bound.driver.getElements(); // CliError(3) on dump failure → 500 below
-        sendJson(res, 200, { elements });
+        try {
+            const elements = bound.driver.getElements(); // CliError(3) on dump failure → 500 below
+            sendJson(res, 200, { elements });
+        }
+        catch (e) {
+            // Move if the device is at fault, but NEVER answer with the new device's screen:
+            // this is the engine's `if-present` guard input and its repair context, and a
+            // hierarchy from somewhere else is worse than an error. The client's connect probe
+            // re-asks after a reported move — see remote.ts's preflight.
+            const deviceChanged = await considerFailover(e, 'read');
+            if (!deviceChanged)
+                throw e;
+            throw new HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, deviceChanged);
+        }
     }
     async function handleLogs(req, res) {
         const body = await readBody(req, EXEC_BODY_CAP);
@@ -293,7 +488,10 @@ function buildServer(config) {
                 : (() => {
                     throw new HttpError(400, `invalid appId '${String(parsed.appId)}'`);
                 })();
-        const logs = config.driver.getLogs({
+        // The BOUND driver, never config.driver: after a rebind (device control, or a
+        // failover) the startup driver is pinned to a serial that may be gone, and logs
+        // are evidence about the run that just failed — serving another device's is a lie.
+        const logs = bound.driver.getLogs({
             ...(lines !== undefined ? { lines } : {}),
             ...(parsed.since ? { since: parsed.since } : {}),
             ...(appId ? { appId } : {}),
@@ -302,6 +500,49 @@ function buildServer(config) {
         const payload = { logs };
         sendJson(res, 200, payload);
     }
+    /**
+     * Install, moving to another device when THIS one is at fault.
+     *
+     * Install is the one operation safe to REPLAY elsewhere: it is idempotent, carries no
+     * app session, and the uploaded bytes are still on the server's disk, so a retry costs
+     * one more `adb install` and no re-upload. Every other endpoint rebinds without
+     * replaying — see handleExec.
+     *
+     * On exhaustion it throws the FIRST device's error, never the last. That inversion is
+     * what makes move-by-default safe: a wrong move costs time, not the diagnosis.
+     */
+    function installWithFailover(tmpPath) {
+        let change;
+        let moves = 0;
+        let firstError;
+        for (let hop = 0;; hop++) {
+            const from = bound.serial ?? '(none)';
+            try {
+                bound.driver.install(tmpPath);
+                return { change, moves };
+            }
+            catch (e) {
+                if (firstError === undefined)
+                    firstError = e;
+                const verdict = (0, failover_1.classifyInstallFailure)(e);
+                (0, output_1.err)(`[server] install: FAILED on ${from} — ${verdict.reason}`);
+                noteVerdict(verdict, e, 'install');
+                // The artifact is broken / the caller is wrong / failover is off / we are out of
+                // hops: report the first failure unchanged, exactly as before this feature.
+                if (!verdict.move || !config.failover || hop >= MAX_FAILOVER_HOPS)
+                    throw firstError;
+                quarantineDevice(bound.serial, verdict.reason);
+                const to = pickFailoverDevice();
+                if (!to) {
+                    const original = firstError instanceof Error ? firstError.message : String(firstError);
+                    throw new HttpError(500, `${original}${exhaustedNote()}`, 3, change);
+                }
+                change = { from, to, reason: verdict.reason, retried: true };
+                moves++;
+                (0, output_1.err)(`[server] install: retrying on ${to}…`);
+            }
+        }
+    }
     async function handleInstall(req, res) {
         const ext = String(req.headers['x-verikun-ext'] ?? '').toLowerCase();
         if (ext !== 'apk' && ext !== 'ipa') {
@@ -333,9 +574,10 @@ function buildServer(config) {
                 throw new HttpError(400, `sha256 mismatch: upload arrived corrupted (got ${digest.slice(0, 12)}…, expected ${expected.slice(0, 12)}…)`);
             }
             (0, output_1.err)(`[server] install: received ${size} bytes (.${ext}), installing…`);
-            bound.driver.install(tmpPath);
-            (0, output_1.err)('[server] install: done');
-            sendJson(res, 200, { ok: true, bytes: size, sha256: digest });
+            const { change, moves } = installWithFailover(tmpPath);
+            (0, output_1.err)(`[server] install: done${change ? ` on ${change.to} (after ${moves} move${moves === 1 ? '' : 's'})` : ''}`);
+            const body = { ok: true, bytes: size, sha256: digest, ...(change ? { deviceChanged: change } : {}) };
+            sendJson(res, 200, body);
         }
         finally {
             try {
@@ -425,6 +667,12 @@ function buildServer(config) {
                 rebind(serial);
             result = { ok: true, platform: config.platform, serial, changed: started, durationMs: Date.now() - t0 };
         }
+        // A power cycle IS the fix for a quarantined device, and performing one is the
+        // assertion that it worked. Clear by both keys: a client names an AVD, the
+        // lifecycle layer answers with a serial.
+        for (const key of [result.serial, target])
+            if (key)
+                quarantine.delete(key);
         (0, output_1.err)(`[server] device ${op} → ${result.serial ?? '(none)'} (${result.durationMs}ms, changed=${result.changed})`);
         sendJson(res, 200, result);
     }
@@ -436,7 +684,7 @@ function buildServer(config) {
             if (config.authKey && req.headers.authorization && !authorized(req)) {
                 throw new HttpError(401, 'invalid auth key');
             }
-            const reads = safeHierarchySource(config.driver);
+            const reads = bound.serial === null ? null : safeHierarchySource(bound.driver);
             const health = {
                 ok: true,
                 version: version_1.VERSION,
@@ -446,6 +694,11 @@ function buildServer(config) {
                 ...(reads ? { reads } : {}),
                 deviceControlEnabled: config.deviceControl !== undefined,
                 deviceNamingEnabled: (config.deviceControl?.allowedTargets.length ?? 0) > 0,
+                failoverEnabled: config.failover !== undefined,
+                // Omitted when empty, so a CI job can assert on its ABSENCE. Unauthenticated
+                // like the rest of health, which is what makes "is the pool ok?" answerable
+                // without holding a run token.
+                ...(quarantine.size ? { quarantined: quarantineList() } : {}),
                 // Derived from `serial` right here, so the two can never drift apart.
                 deviceState: bound.serial === null ? 'none' : 'ready',
             };
@@ -498,13 +751,20 @@ function buildServer(config) {
             // Who is driving what, so a client can see "is it free" before committing to a run
             // rather than discovering it as a 409 mid-suite. Read-only, exactly like the local
             // listing — asking must never take a claim.
-            if ((0, claims_1.claimsEnabled)()) {
+            if ((0, claims_1.claimsEnabled)(claimEnv)) {
                 for (const d of seen) {
-                    const claim = (0, claims_1.summarize)(d.serial);
+                    const claim = (0, claims_1.summarize)(d.serial, claimOpts);
                     if (claim)
                         d.claim = claim;
                 }
             }
+            // `note` is the existing optional-caveat column formatDeviceTable already renders,
+            // so `vk devices --server` shows this with no wire change.
+            for (const d of seen) {
+                const q = quarantine.get(d.serial);
+                if (q)
+                    d.note = `quarantined: ${q.reason}`;
+            }
             const body = {
                 devices: policy.allowedTargets.length
                     ? seen.filter((d) => d.serial === bound.serial || policy.allowedTargets.includes(d.name ?? ''))
@@ -549,7 +809,11 @@ function buildServer(config) {
                     ? new HttpError(e.exitCode === 2 ? 400 : 500, e.message, e.exitCode)
                     : new HttpError(500, e.message || 'internal error', 3);
             if (!res.headersSent) {
-                const body = { error: mapped.message, exitCode: mapped.exitCode };
+                const body = {
+                    error: mapped.message,
+                    exitCode: mapped.exitCode,
+                    ...(mapped.deviceChanged ? { deviceChanged: mapped.deviceChanged } : {}),
+                };
                 sendJson(res, mapped.status, body);
             }
             else {
@@ -587,9 +851,59 @@ function parseDeviceControl(flags) {
     }
     return { allowedTargets: names };
 }
+/**
+ * Decide whether this server may move off a device that fails. PURE — exported for unit
+ * tests, and it takes `pinned`/`env` explicitly rather than reading `process.env` so the
+ * whole truth table is assertable.
+ *
+ * Precedence, and each step earns its place:
+ *  1. An explicit OFF wins over everything — a kill switch you can override is not one.
+ *     `VERIKUN_NO_FAILOVER` mirrors `VERIKUN_NO_CLAIM`: host-level policy for an operator
+ *     who cannot change every command line. It is announced at startup, so it can never
+ *     silently explain a server that "won't fail over".
+ *  2. `--allow-failover[=names]` turns it on, and OVERRIDES a `--device` pin — two flags
+ *     that appear to disagree are resolved by the later, more specific one, loudly.
+ *  3. A `--device` pin turns it off. The operator named the device; honour that.
+ *  4. Otherwise ON, unbounded. See FailoverPolicy for why that is the honest default.
+ *
+ * `flagBool` is deliberately NOT used for `allow-failover`, for the same reason as
+ * `parseDeviceControl`: it returns FALSE for `--allow-failover=emulator-5556`, silently
+ * disabling the feature for the exact spelling that bounds it.
+ */
+function parseFailover(flags, opts = {}) {
+    const raw = flags['allow-failover'];
+    const asked = raw !== undefined && raw !== false;
+    const refused = (0, args_1.flagBool)(flags, 'no-failover');
+    if (asked && refused) {
+        throw new errors_1.CliError('--allow-failover and --no-failover contradict each other — pass one.', 2);
+    }
+    if (refused)
+        return { why: 'disabled (--no-failover)' };
+    if ((opts.env ?? process.env).VERIKUN_NO_FAILOVER) {
+        return { why: 'disabled (VERIKUN_NO_FAILOVER)' };
+    }
+    if (asked) {
+        if (raw === true || raw === 'true') {
+            return { policy: { allowedTargets: [] }, why: 'ENABLED · any attached device on this host (--allow-failover)' };
+        }
+        const names = String(raw)
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean);
+        if (!names.length) {
+            throw new errors_1.CliError('--allow-failover=<serials> needs a comma-separated list of device serials or AVD/simulator names ' +
+                '(or pass a bare --allow-failover to permit any attached device).', 2);
+        }
+        return { policy: { allowedTargets: names }, why: `ENABLED · may move to: ${names.join(', ')}` };
+    }
+    if (opts.pinned) {
+        return { why: 'disabled (--device pins the binding; pass --allow-failover to permit moving)' };
+    }
+    return { policy: { allowedTargets: [] }, why: 'ENABLED · any attached device on this host' };
+}
 async function cmdServer(positionals, flags) {
     if (positionals.length > 0) {
-        throw new errors_1.CliError(`server: unexpected argument '${positionals[0]}'. Usage: verikun server [--bind addr] [--port n] [--auth-key k] [--allow-install] [--allow-device-control[=names]] [--allow-unsafe-anonymous]`, 2);
+        throw new errors_1.CliError(`server: unexpected argument '${positionals[0]}'. Usage: verikun server [--bind addr] [--port n] [--auth-key k] [--allow-install] [--allow-device-control[=names]] [--allow-failover[=serials]|--no-failover] [--allow-unsafe-anonymous]`, 2);
     }
     const platform = (0, cli_1.platformFromFlags)(flags);
     const device = (0, cli_1.deviceFromFlags)(flags, platform);
@@ -597,6 +911,8 @@ async function cmdServer(positionals, flags) {
     const port = (0, args_1.flagNum)(flags, 'port') ?? DEFAULT_PORT;
     const allowInstall = (0, args_1.flagBool)(flags, 'allow-install');
     const deviceControl = parseDeviceControl(flags);
+    // `device` is --device || VERIKUN_DEVICE || ANDROID_SERIAL: an env pin is still a pin.
+    const failover = parseFailover(flags, { pinned: device !== undefined });
     const anonymous = (0, args_1.flagBool)(flags, 'allow-unsafe-anonymous');
     // The env var is the documented channel for the key (keeps it out of argv/ps).
     let authKey = (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined;
@@ -663,7 +979,7 @@ async function cmdServer(positionals, flags) {
     // shutdown has to release the companion on whatever is bound then.
     let boundSerial = serial;
     const server = buildServer({
-        driver, platform, serial, authKey, allowInstall, deviceControl,
+        driver, platform, serial, authKey, allowInstall, deviceControl, failover: failover.policy,
         onRebind: (s) => { boundSerial = s; },
     });
     return new Promise((resolve, reject) => {
@@ -685,6 +1001,16 @@ async function cmdServer(positionals, flags) {
             if (deviceControl) {
                 (0, output_1.err)('[server] NOTE: an authenticated client can now power-cycle AND erase this device.');
             }
+            (0, output_1.err)(`[server] failover: ${failover.why}`);
+            // Two flags that appear to disagree. Permitted rather than refused — `--device X`
+            // alongside the other --allow-* flags is straight out of the docs, so refusing
+            // would break the commonest shape — but never silently: a bare --allow-failover
+            // means the pin governs only the INITIAL binding.
+            if (device && failover.policy && failover.policy.allowedTargets.length === 0) {
+                (0, output_1.err)(`[server] WARNING: --device ${device} pins only the INITIAL binding — a bare --allow-failover`);
+                (0, output_1.err)('[server]          permits moving to any other attached device on this host. Pass');
+                (0, output_1.err)('[server]          --allow-failover=<serials> to bound where it may go.');
+            }
             if (generated) {
                 (0, output_1.err)('[server] auth key generated for this session — clients pass it via VERIKUN_SERVER_AUTH_KEY or --auth-key:');
                 (0, output_1.err)(`[server]     ${authKey}`);

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.24.0';
+exports.VERSION = '0.25.0';

package/package.json

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