verikun 0.24.0 → 0.25.1

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

@@ -141,7 +141,10 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
   you reset it, so don't leave someone's phone in airplane mode.
 
 - `vk device prep [--dry-run] [--revert]` — set a **test** device up once, stickily:
-  `animations=off stay-awake=on screen-timeout=max dnd=on doze=off`.
+  `animations=off stay-awake=off screen-timeout=1m dnd=on doze=off`. The display then sleeps by
+  itself a minute after the last command and is woken by the next one; `--no-sleep-when-idle`
+  keeps it lit for good (`stay-awake=on screen-timeout=max`), which is what a device with a
+  PIN/pattern lock needs, since verikun can only clear a *swipe* lock.
 
   Unlike `device set`, prep **survives the run** and is undone only by `--revert`. A physical
   device must be named (`--device <serial>`) — that requirement is deliberate, so prep can
@@ -452,6 +455,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
@@ -536,6 +552,8 @@ owns the redaction and the review-first flow.
   verikun detects this, wakes the device and clears a *swipe* lock automatically; on a
   PIN/pattern/password it exits **3** naming the lock rather than returning that dump.
   Tell the user to remove the lock in Settings > Security — verikun never asks for a PIN.
+  Taps, swipes, typing and screenshots wake it the same way: a prepped display sleeps after a
+  minute idle, and an injected tap on a sleeping screen would otherwise do nothing and exit `0`.
 - **Ambiguous selector → exit 2**, never a random tap. `vk` prints the candidate
   matches; add `--index N` or use a more specific selector.
 - **Indexes are per-snapshot.** `vk tap 3` taps `[3]` from the *latest* dump;

package/CHANGELOG.md

@@ -6,6 +6,37 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.25.1] - 2026-08-21
+
+### Changed
+- **`vk device prep`**: gives the display a 1-minute timeout instead of keeping it lit forever; `--no-sleep-when-idle` keeps the old behaviour. ([#101])
+- **`vk batch|ai|suite`**: no longer switch a prepped device's display off at teardown — it now sleeps by itself.
+- **`vk tap|type|key|swipe|screenshot`**: wake a sleeping display first; an injected tap on a dozing screen did nothing and exited `0`.
+
+### Added
+- **`vk device prep`**: warns when a device that will now sleep is behind a PIN/pattern lock.
+
+[#101]: https://github.com/ddikman/verikun/issues/101
+
+## [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
@@ -38,7 +38,7 @@ The package also carries the agent [`SKILL.md`](.claude/skills/verikun/SKILL.md)
 
 ```sh
 vk doctor                       # check adb/device (read-only — never changes anything)
-vk device prep --device <id>    # set a TEST device up once: animations off, stays awake
+vk device prep --device <id>    # set a TEST device up once: animations off, sane display timeout
 vk devices                      # list attached devices
 vk ui                           # semantic snapshot of the current screen
 vk tap @login_button            # tap by resource-id

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;
@@ -1393,10 +1394,12 @@ function devicePrep(ctx) {
     const serial = ctx.driver.resolvedSerial();
     if ((0, args_1.flagBool)(ctx.flags, 'revert'))
         return devicePrepRevert(ctx, serial, dryRun, asJson);
+    // Which display policy: sleeps by itself after PREP_SCREEN_TIMEOUT, or never turns off.
+    const sleepWhenIdle = !(0, args_1.flagBool)(ctx.flags, 'no-sleep-when-idle');
     // Partition by what this platform can actually do, so the gate below counts real writes.
     const skipped = [];
     const applicable = [];
-    for (const knob of prep_1.PREP_KNOBS) {
+    for (const knob of (0, prep_1.prepKnobs)(sleepWhenIdle)) {
         const spec = settings_1.SETTINGS[knob.key];
         const support = spec.support[ctx.platform];
         if (support === 'unsupported') {
@@ -1450,7 +1453,6 @@ function devicePrep(ctx) {
     }
     // Earliest wins across re-preps, or `--revert` would restore the device to prepped.
     const prior = (0, prep_1.readPrep)(serial);
-    const sleepWhenIdle = !(0, args_1.flagBool)(ctx.flags, 'no-sleep-when-idle');
     (0, prep_1.writePrep)((0, prep_1.newPrepRecord)(serial, ctx.platform, (0, prep_1.mergeOriginals)(prior?.original ?? {}, original), sleepWhenIdle));
     const applied = Object.fromEntries(applicable.map((k) => [k.key, k.target]));
     ctx.record?.note({ message: `device prep ${serial} (${changes.length} changed)` });
@@ -1462,11 +1464,32 @@ function devicePrep(ctx) {
         for (const s of skipped)
             (0, output_1.err)(`note: ${s.key} skipped — ${s.reason.replace(/\n/g, ' ')}`);
         if (sleepWhenIdle)
-            (0, output_1.err)('note: this device will be put to sleep when a run using it finishes');
+            (0, output_1.err)(`note: the display sleeps by itself after ${prep_1.PREP_SCREEN_TIMEOUT} idle, and is woken on the next read`);
+        warnSecureLock(ctx.platform, serial, sleepWhenIdle);
         (0, output_1.err)(`undo with: verikun device prep --revert --device ${serial}`);
     }
     return 0;
 }
+/**
+ * Say so, once, when a device that will now sleep is behind a SECURE lock.
+ *
+ * The wake on the read path can only clear a *swipe* keyguard; a PIN/pattern/password one makes
+ * `getElements` exit 3 rather than hand back the lock screen. That is honest, but it is a
+ * failure, and prep — an explicit setup command that already resolved the serial — is where you
+ * want to hear about it, not twenty minutes into a suite. It only warns: refusing would make a
+ * perfectly usable device un-preppable, and `--no-sleep-when-idle` is the way out.
+ */
+function warnSecureLock(platform, serial, sleepWhenIdle) {
+    if (!sleepWhenIdle || platform !== 'android')
+        return;
+    const lock = (0, adb_1.lockKindOf)(serial);
+    if (lock === 'none' || lock === 'unknown')
+        return;
+    (0, output_1.err)(`warning: this device has a screen lock (${lock}), so a read after the display sleeps can land ` +
+        'on the keyguard (verikun can only clear a swipe lock, and never asks for a PIN).\n' +
+        'Remove it in Settings > Security, or keep the display lit with `verikun device prep ' +
+        `--no-sleep-when-idle --device ${serial}\`.`);
+}
 /** Put a prepared device back the way it was found, and forget it. */
 function devicePrepRevert(ctx, serial, dryRun, asJson) {
     const rec = (0, prep_1.readPrep)(serial);
@@ -1556,35 +1579,6 @@ function requireSettingKey(v) {
  * same code. (Remote is a known gap: the overrides live in the *server's* run file, so
  * a locally-empty snapshot means this correctly skips — see the issue's Out of scope.)
  */
-/**
- * Park prepared devices when the flow that used them ends — #97's "in sleep mode when they're
- * not [in use]".
- *
- * Three properties worth keeping:
- *
- *   * It can only ever touch a device you explicitly PREPPED, and only if that prep did not
- *     pass `--no-sleep-when-idle`. A borrowed phone that was never prepped is never slept.
- *   * It goes through the driver rather than the command dispatcher, so it does not appear as
- *     a `key sleep` testcase in the report. Parking is host hygiene, not a test step.
- *   * `ownClaimedSerials()` is empty in `--server` mode (the local process never resolves a
- *     device), so the remote path degrades to doing nothing on its own, with no branch here.
- *     Managing a remote device's power is `--allow-device-control`'s job.
- *
- * Must run BEFORE `releaseOwnClaims()`, which is what it reads its serials from.
- */
-function parkPreparedDevices(platform) {
-    for (const serial of (0, claims_1.ownClaimedSerials)()) {
-        if (!(0, prep_1.readPrep)(serial)?.sleepWhenIdle)
-            continue;
-        try {
-            (0, output_1.err)(`[verikun] parking prepared device ${serial} (sleep)`);
-            (0, drivers_1.getDriver)(platform, serial).pressKey('sleep');
-        }
-        catch {
-            /* teardown must never throw — the device may be exactly why we are unwinding */
-        }
-    }
-}
 async function restoreDeviceOverrides(backend) {
     if (!run_1.Recorder.hasDeviceOverrides())
         return;
@@ -1865,7 +1859,6 @@ async function cmdBatch(positionals, batchFlags) {
                 /* the device may be exactly why we are unwinding — never mask the real error */
             }
         }
-        parkPreparedDevices(platformFromFlags(batchFlags));
         (0, claims_1.releaseOwnClaims)();
     }
 }
@@ -1999,6 +1992,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 +2196,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 +2211,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 +2231,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 +2257,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 +2275,7 @@ async function resolveBackend(platform, device, flags) {
         platform: health.platform,
         device: health.serial ?? undefined,
         remote: { url: server, version: health.version, reads: health.reads },
+        moves,
     };
 }
 /**
@@ -2462,8 +2515,7 @@ async function cmdAi(positionals, flags) {
         // otherwise an unattended run leaves the phone offline or in dark mode.
         await restoreDeviceOverrides(backend);
         await backend.close?.(); // frees a remote server's device lock for the next command
-        parkPreparedDevices(platform); // a prepped device goes back to sleep between runs
-        (0, claims_1.releaseOwnClaims)(); // and the host-level claim, so the next job can have the device
+        (0, claims_1.releaseOwnClaims)(); // the host-level claim, so the next job can have the device
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
         (0, output_1.json)({
@@ -2501,7 +2553,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 +2561,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;
 }
 // ---------------------------------------------------------------------------
@@ -2551,7 +2609,6 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
-        parkPreparedDevices(platform);
         (0, claims_1.releaseOwnClaims)();
     }
 }
@@ -2900,11 +2957,11 @@ DEVICE STATE (change the device the app runs on, then put it back)
                                       do this automatically when the flow ends OR fails,
                                       so a dead test can't leave the phone offline.
   device prep [--dry-run] [--json]    Prepare a TEST device once, stickily: animations off,
-                                      display kept awake, Do Not Disturb on, battery idle off.
-                                      Survives the run (unlike \`device set\`), so it is undone
-                                      only by \`--revert\`. A PHYSICAL device must be named with
-                                      --device — prep must never land on a personal phone.
-                                      --no-sleep-when-idle keeps the screen on after a run.
+                                      display timeout ${prep_1.PREP_SCREEN_TIMEOUT}, Do Not Disturb on,
+                                      battery idle off. Survives the run (unlike \`device set\`),
+                                      so it is undone only by \`--revert\`. A PHYSICAL device must
+                                      be named with --device — prep must never land on a personal
+                                      phone. --no-sleep-when-idle keeps the display on for good.
   device prep --revert [--dry-run]    Put a prepared device back the way it was found
   device caps [--json]                What this platform supports, and the manual
                                       equivalent where it doesn't
@@ -2961,7 +3018,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 +3036,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/claims.js

@@ -31,7 +31,6 @@
 // Platform-agnostic by design, like `device/settings.ts` and `ui/`: it never touches
 // adb/xcrun. The drivers know which devices exist; this knows which are taken.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ownClaimedSerials = ownClaimedSerials;
 exports.releaseOwnClaims = releaseOwnClaims;
 exports.setProcessScoped = setProcessScoped;
 exports.claimsEnabled = claimsEnabled;
@@ -73,11 +72,6 @@ let processScoped = false;
  * store what it took is the only way it can release anything.
  */
 const acquired = new Set();
-/** Which devices this process took. Read by the prep teardown, which has to act on them
- *  BEFORE `releaseOwnClaims` empties this — see `parkPreparedDevices` in cli.ts. */
-function ownClaimedSerials() {
-    return [...acquired];
-}
 /** Give back every device this process claimed. Best-effort; teardown must never throw. */
 function releaseOwnClaims(o = {}) {
     const released = [];