verikun 0.23.0 → 0.25.0

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;
@@ -65,6 +66,7 @@ const adb_1 = require("./drivers/adb");
 const lifecycle_1 = require("./drivers/lifecycle");
 const settings_1 = require("./device/settings");
 const claims_1 = require("./device/claims");
+const prep_1 = require("./device/prep");
 const selector_1 = require("./ui/selector");
 const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
@@ -656,10 +658,38 @@ async function cmdDoctor(ctx) {
         const c = claims ? (0, claims_1.summarize)(serial) : undefined;
         return c && !c.mine ? c : undefined;
     };
+    // Blank lines separate doctor's three blocks — toolchain, device inventory, target detail.
+    // Without them the target's indented lines read as a continuation of the last device row.
+    (0, output_1.out)('');
     (0, output_1.out)(`devices: ${devices.length} attached, ${usable.length} usable`);
-    for (const d of devices) {
+    // Probe each device, not just the one an interaction command would land on: "is there a
+    // screen lock" and "is this prepared" are facts about a PHONE, and a host driving three of
+    // them cannot act on an answer that does not say which. The lock read is one `dumpsys` per
+    // device and the prep read is a local file, which is affordable in an explicit setup check.
+    const locks = new Map();
+    const rows = devices.map((d) => {
+        const facts = [];
+        if (d.state === 'device') {
+            facts.push((0, prep_1.readPrep)(d.serial) ? 'prepared' : 'not prepared');
+            const lock = (0, adb_1.lockKindOf)(d.serial);
+            locks.set(d.serial, lock);
+            if (lock !== 'none' && lock !== 'unknown')
+                facts.push(`screen lock: ${lock}`);
+        }
         const claim = claims ? (0, claims_1.summarize)(d.serial) : undefined;
-        (0, output_1.out)(`  ${d.serial} ${d.state}${d.model ? ` (${d.model})` : ''}${claim ? `  [${claim.by}]` : ''}`);
+        return {
+            serial: d.serial,
+            what: `${d.state}${d.model ? ` (${d.model})` : ''}`,
+            facts: facts.join(' · '),
+            claim: claim ? `[${claim.by}]` : '',
+        };
+    });
+    // Pad each column to its widest cell so the per-device facts line up and can be scanned
+    // down; trimEnd so a device with no facts and no claim leaves no trailing whitespace.
+    const w = (pick) => Math.max(...rows.map((r) => pick(r).length), 0);
+    const [wSerial, wWhat, wFacts] = [w((r) => r.serial), w((r) => r.what), w((r) => r.facts)];
+    for (const r of rows) {
+        (0, output_1.out)(`  ${r.serial.padEnd(wSerial)}  ${r.what.padEnd(wWhat)}  ${r.facts.padEnd(wFacts)}  ${r.claim}`.trimEnd());
     }
     let ok = true;
     const free = usable.filter((d) => !heldByOther(d.serial));
@@ -681,25 +711,57 @@ async function cmdDoctor(ctx) {
     // the first FREE one (which is what auto-selection picks), not merely the first attached.
     const target = ctx.device || free[0]?.serial;
     if (target) {
-        try {
-            const serial = target;
-            const keys = ['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale'];
-            const get = (k) => (0, exec_1.runText)(adb, ['-s', serial, 'shell', 'settings', 'get', 'global', k]).stdout.trim();
-            const vals = keys.map(get);
-            const off = vals.every((v) => v === '0' || v === '0.0');
-            (0, output_1.out)(`animations: ${vals.join('/')} ${off ? '(off, good)' : '(ON — flaky dumps; run `verikun doctor --fix`)'}`);
-            if ((0, args_1.flagBool)(ctx.flags, 'fix') && !off) {
-                for (const k of keys)
-                    (0, exec_1.runText)(adb, ['-s', serial, 'shell', 'settings', 'put', 'global', k, '0']);
-                (0, output_1.out)('animations: disabled (good)');
-            }
-        }
-        catch {
-            (0, output_1.err)('animations: could not read device settings');
+        reportTargetStatus(target, adb, locks.get(target) ?? 'unknown');
+        // `--fix` is now an alias for `device prep`, so it inherits prep's gate: on a physical
+        // device it refuses unless the serial was named. That refusal is the point — the old
+        // `--fix` wrote permanently to whichever phone happened to be unclaimed, with no undo.
+        if ((0, args_1.flagBool)(ctx.flags, 'fix')) {
+            const prepFlags = (0, args_1.flagBool)(ctx.flags, 'no-sleep-when-idle') ? { 'no-sleep-when-idle': true } : {};
+            return devicePrep({ ...ctx, flags: prepFlags });
         }
     }
     return ok ? 0 : 3;
 }
+/**
+ * The extra detail for the ONE device an interaction command would land on. Every line names
+ * that serial, because the listing above may have shown several and an advisory you cannot
+ * attribute to a phone is not actionable.
+ *
+ * Reads NOTHING through `ctx.driver`, deliberately — resolving a driver claims the device, and
+ * doctor surveys the host without taking anything (see the note at the device listing above).
+ * The prep record is a plain file read; the animation probe goes through `adb -s <serial>`
+ * directly. `lock` is passed in rather than re-probed, so the listing's read is the only one.
+ */
+function reportTargetStatus(serial, adb, lock) {
+    (0, output_1.out)('');
+    (0, output_1.out)(`target: ${serial} — the device an interaction command would use`);
+    const rec = (0, prep_1.readPrep)(serial);
+    const when = rec?.preparedAt ? ` (${rec.preparedAt.slice(0, 10)})` : '';
+    (0, output_1.out)(rec
+        ? `  prepared${when} — undo with \`verikun device prep --revert --device ${serial}\``
+        : `  not prepared — run \`verikun device prep --device ${serial}\``);
+    // Animations are still called out by name rather than folded into "not prepared": they are
+    // the single most common cause of a flaky dump, and a device can be prepped and then drift.
+    try {
+        const vals = ['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale'].map((k) => (0, exec_1.runText)(adb, ['-s', serial, 'shell', 'settings', 'get', 'global', k]).stdout.trim());
+        const off = vals.every((v) => Number(v) === 0);
+        (0, output_1.out)(`  animations: ${vals.join('/')} ${off ? '(off, good)' : '(ON — flaky dumps; run `verikun device prep`)'}`);
+    }
+    catch {
+        (0, output_1.err)(`  animations: could not read settings on ${serial}`);
+    }
+    // Advisory, never a failure: a screen lock is a property of someone's phone, not a broken
+    // machine. It is worth saying because of what a slept device actually does — the read
+    // SUCCEEDS and returns the keyguard, so selectors miss for a reason unrelated to the app.
+    if (lock !== 'none' && lock !== 'unknown') {
+        // Indented to sit with the target's other lines, but it still NAMES the serial: this goes
+        // to stderr (it is a diagnostic, not data), so under `vk doctor > out.txt` it appears on
+        // its own with no `target:` header above it to say which phone it means.
+        (0, output_1.err)(`  screen lock on ${serial} (${lock}) — while it is up, a read returns the lock screen ` +
+            'rather than the app.\n' +
+            '    Remove it on a test device (Settings > Security). verikun never asks for a PIN.');
+    }
+}
 function cmdUi(ctx) {
     const els = ctx.driver.getElements({ all: (0, args_1.flagBool)(ctx.flags, 'all') });
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
@@ -1158,7 +1220,8 @@ function cmdClear(ctx) {
 //    of applying dark mode and then dying — a half-applied device is worse than none.
 //  - SNAPSHOT FIRST. The pre-change value is persisted before the change is made, so
 //    `device reset` can undo it even from a later process.
-const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps | device release [serial]\n' +
+const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | ' +
+    'device prep [--revert] [--dry-run] | device caps | device release [serial]\n' +
     `Keys: ${settings_1.SETTING_KEYS.join(', ')}`;
 function cmdDevice(ctx) {
     const sub = (ctx.positionals[0] ?? '').toLowerCase();
@@ -1171,6 +1234,8 @@ function cmdDevice(ctx) {
             return deviceGet(ctx, rest);
         case 'reset':
             return deviceReset(ctx, rest);
+        case 'prep':
+            return devicePrep(ctx);
         case 'caps':
             return deviceCaps(ctx);
         case 'release':
@@ -1311,6 +1376,143 @@ function deviceReset(ctx, args) {
         (0, output_1.out)(summary ? `device reset ${summary}` : 'device reset: nothing to restore');
     return 0;
 }
+/**
+ * `vk device prep` — establish the test-device knob set, stickily.
+ *
+ * The whole point is that this OUTLIVES the run, so unlike `deviceSet` the snapshot does not
+ * go into the run file (which `ai`/`suite`/`batch` auto-restore from a `finally`) but into the
+ * host-global prep store. See device/prep.ts for why the two stores exist.
+ *
+ * Unsupported and no-op knobs are SKIPPED with a note rather than failing the command, which
+ * is the difference between prep and `device set`: `set` was told which key to change and must
+ * refuse if it cannot, while prep means "establish what this platform can" — so on iOS, where
+ * every knob is a noop or unsupported, it honestly reports doing nothing instead of erroring.
+ */
+function devicePrep(ctx) {
+    const asJson = (0, args_1.flagBool)(ctx.flags, 'json');
+    const dryRun = (0, args_1.flagBool)(ctx.flags, 'dry-run');
+    const serial = ctx.driver.resolvedSerial();
+    if ((0, args_1.flagBool)(ctx.flags, 'revert'))
+        return devicePrepRevert(ctx, serial, dryRun, asJson);
+    // 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) {
+        const spec = settings_1.SETTINGS[knob.key];
+        const support = spec.support[ctx.platform];
+        if (support === 'unsupported') {
+            skipped.push({ key: knob.key, reason: spec.manual[ctx.platform] ?? `not supported on ${ctx.platform}` });
+            continue;
+        }
+        if (support === 'noop') {
+            skipped.push({ key: knob.key, reason: spec.note[ctx.platform] ?? 'already satisfied on this platform' });
+            continue;
+        }
+        // parse() so the target compares equal to a readback (`max` -> the millisecond string).
+        applicable.push({
+            key: knob.key,
+            target: spec.parse(knob.value),
+            current: ctx.driver.getDeviceSetting(knob.key),
+            why: knob.why,
+        });
+    }
+    const changes = applicable.filter((k) => k.current !== k.target);
+    // `--dry-run` is deliberately NOT gated: it writes nothing, and refusing it would mean you
+    // could not find out what prep would do to a phone without first asserting it is a test one.
+    if (dryRun) {
+        if (asJson) {
+            (0, output_1.json)({ serial, prepared: (0, prep_1.isPrepared)(serial), dryRun: true, changes, skipped });
+        }
+        else {
+            (0, output_1.out)(`device prep ${serial} (dry run — nothing written)`);
+            for (const k of applicable) {
+                const state = k.current === k.target ? 'already' : `${showValue(k.current)} -> ${k.target}`;
+                (0, output_1.out)(`  ${k.key.padEnd(15)} ${state}`);
+                if (k.current !== k.target)
+                    (0, output_1.out)(`  ${' '.repeat(15)} ${k.why}`);
+            }
+            for (const s of skipped)
+                (0, output_1.out)(`  ${s.key.padEnd(15)} skipped: ${s.reason.replace(/\n/g, ' ')}`);
+        }
+        return 0;
+    }
+    // The gate, immediately before the first write. `!!ctx.device` is true for --device AND
+    // VERIKUN_DEVICE: both are a deliberate act naming one phone, which is the property asked for.
+    const kind = ctx.driver.listDevices().find((d) => d.serial === serial)?.kind ?? 'physical';
+    (0, prep_1.assertPreppable)(kind, serial, !!ctx.device, applicable.length);
+    const original = {};
+    for (const k of applicable) {
+        // Snapshot even a knob already at target: `--revert` has to put back what the device
+        // held before prep, and "it was already off" is exactly as much a fact as a change.
+        if (k.current !== null)
+            original[k.key] = k.current;
+        if (k.current !== k.target)
+            ctx.driver.setDeviceSetting(k.key, k.target);
+    }
+    // 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)` });
+    if (asJson) {
+        (0, output_1.json)({ serial, applied, changed: changes.map((c) => c.key), skipped, sleepWhenIdle });
+    }
+    else {
+        (0, output_1.out)(`device prep ${serial}: ${changes.length ? changes.map((c) => `${c.key}=${c.target}`).join(' ') : 'already prepared'}`);
+        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)(`undo with: verikun device prep --revert --device ${serial}`);
+    }
+    return 0;
+}
+/** 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);
+    if (!rec) {
+        if (asJson)
+            (0, output_1.json)({ serial, prepared: false, restored: {} });
+        else
+            (0, output_1.out)(`device prep --revert ${serial}: not prepared, nothing to restore`);
+        return 0;
+    }
+    const entries = Object.entries(rec.original);
+    if (dryRun) {
+        if (asJson)
+            (0, output_1.json)({ serial, prepared: true, dryRun: true, wouldRestore: rec.original });
+        else {
+            (0, output_1.out)(`device prep --revert ${serial} (dry run — nothing written)`);
+            for (const [key, value] of entries)
+                (0, output_1.out)(`  ${key.padEnd(15)} ${showValue(ctx.driver.getDeviceSetting(key))} -> ${value}`);
+        }
+        return 0;
+    }
+    const restored = {};
+    const failed = [];
+    for (const [key, value] of entries) {
+        try {
+            ctx.driver.setDeviceSetting(key, value);
+            restored[key] = value;
+        }
+        catch (e) {
+            // Best-effort, like `device reset`: one stubborn knob must not strand the rest.
+            failed.push(`${key} (${e instanceof Error ? e.message.split('\n')[0] : String(e)})`);
+        }
+    }
+    // Forget the device even if a knob refused. Keeping the record would leave `vk doctor`
+    // reporting it as prepped forever, and the values that DID go back are already back.
+    (0, prep_1.clearPrep)(serial);
+    ctx.record?.note({ message: `device prep --revert ${serial}` });
+    if (failed.length)
+        (0, output_1.err)(`warning: could not restore ${failed.join(', ')}`);
+    if (asJson)
+        (0, output_1.json)({ serial, restored, ...(failed.length ? { failed } : {}) });
+    else
+        (0, output_1.out)(`device prep --revert ${serial}: ${Object.entries(restored).map(([k, v]) => `${k}=${v}`).join(' ') || 'nothing to restore'}`);
+    return 0;
+}
 function deviceCaps(ctx) {
     const rows = settings_1.SETTING_KEYS.map((key) => {
         const spec = settings_1.SETTINGS[key];
@@ -1355,6 +1557,35 @@ 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;
@@ -1635,6 +1866,7 @@ 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)();
     }
 }
@@ -1693,8 +1925,9 @@ function providerRequirement(model) {
     return id === 'openai' ? 'OPENAI_API_KEY is not set' : 'ANTHROPIC_API_KEY is not set';
 }
 /** Route the model to its backend. HTTP providers read their own key; a CLI provider shells
- *  out to its logged-in binary. Unavailable → null (compile/repair off), the same graceful
- *  degradation as before: a cached plan can still replay for free without any provider.
+ *  out to its logged-in binary. Unavailable → null (compile/repair off). That is NOT a free
+ *  replay path: runAiTest turns a null provider into exit 3 even at a 100% cache hit, because
+ *  it must be able to repair a drifted step at runtime — only --show-plan degrades gracefully.
  *  CLI providers get no `model`, so the CLI picks its own default — the "I just have a
  *  subscription" path; --effort is likewise inapplicable to them. */
 function makeProvider(opts) {
@@ -1767,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) {
@@ -1939,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,
@@ -1949,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
@@ -1956,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
@@ -1974,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
@@ -1991,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,
     };
 }
 /**
@@ -2230,6 +2523,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
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
@@ -2268,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);
@@ -2276,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;
 }
 // ---------------------------------------------------------------------------
@@ -2318,6 +2618,7 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
+        parkPreparedDevices(platform);
         (0, claims_1.releaseOwnClaims)();
     }
 }
@@ -2665,6 +2966,13 @@ DEVICE STATE (change the device the app runs on, then put it back)
   device reset [key ...]              Restore what this run changed. batch/ai/suite also
                                       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.
+  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
                                       Refuses \`airplane=on\` over wireless adb (it would cut
@@ -2720,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
@@ -2738,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/claims.js

@@ -31,11 +31,13 @@
 // 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;
 exports.claimTtlMs = claimTtlMs;
 exports.claimsDir = claimsDir;
+exports.deviceFileStem = deviceFileStem;
 exports.isMine = isMine;
 exports.isLive = isLive;
 exports.readClaim = readClaim;
@@ -71,6 +73,11 @@ 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 = [];
@@ -116,9 +123,12 @@ function claimsDir(o = {}) {
  * two serials that sanitize alike (`192.168.1.5:5555` vs `192.168.1.5_5555`) can never
  * collide onto one file and silently share a claim.
  */
-function fileFor(serial) {
+function deviceFileStem(serial) {
     const safe = serial.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 48);
-    return `${safe}-${(0, node_crypto_1.createHash)('sha1').update(serial).digest('hex').slice(0, 8)}.json`;
+    return `${safe}-${(0, node_crypto_1.createHash)('sha1').update(serial).digest('hex').slice(0, 8)}`;
+}
+function fileFor(serial) {
+    return `${deviceFileStem(serial)}.json`;
 }
 function pathFor(serial, o) {
     return (0, node_path_1.join)(claimsDir(o), fileFor(serial));