verikun 0.22.1 → 0.23.0

package/dist/cli.js

@@ -50,6 +50,8 @@ exports.chooseLogOpts = chooseLogOpts;
 exports.evalAssert = evalAssert;
 exports.tokenizeLine = tokenizeLine;
 exports.withBatchGlobals = withBatchGlobals;
+exports.serverFromFlags = serverFromFlags;
+exports.ensureDeviceTarget = ensureDeviceTarget;
 exports.terminalFailure = terminalFailure;
 exports.executeForServer = executeForServer;
 exports.run = run;
@@ -60,6 +62,7 @@ const errors_1 = require("./errors");
 const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
 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 selector_1 = require("./ui/selector");
@@ -79,9 +82,9 @@ const cache_1 = require("./agent/cache");
 const cost_1 = require("./agent/cost");
 const remote_1 = require("./agent/remote");
 const suite_1 = require("./suite");
+const wait_1 = require("./wait");
 const version_1 = require("./version");
 const update_check_1 = require("./update-check");
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Exported for src/server.ts (which resolves its own platform/device at startup).
 function platformFromFlags(flags) {
     if ((0, args_1.flagBool)(flags, 'ios'))
@@ -217,7 +220,7 @@ async function matchWaiting(ctx, sel, opts = {}) {
         const res = (0, selector_1.matchElements)(readForPoll(ctx, opts), sel);
         if (res.matches.length > 0 || Date.now() >= deadline)
             return res;
-        await sleep(pollStep(ctx.flags, deadline));
+        await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
     }
 }
 /**
@@ -242,7 +245,7 @@ async function resolveOneWaiting(ctx, sel, opts = {}) {
             const waited = windowMs > 0 ? ` after ${(windowMs / 1000).toFixed(1)}s` : '';
             throw new errors_1.SelectorNotFoundError(`No element matched selector '${sel.raw}'${waited}. Run \`verikun ui\` to inspect the current screen.`);
         }
-        await sleep(pollStep(ctx.flags, deadline));
+        await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
     }
 }
 // --- Auto scroll-into-view --------------------------------------------------
@@ -299,7 +302,7 @@ async function scrollIntoView(ctx, sel, target, elements, screen, opts = {}) {
             break; // in view, or no swipe big enough to be worth making
         ctx.driver.swipe(plan.from.x, plan.from.y, plan.to.x, plan.to.y, (0, viewport_1.swipeDurationMs)(plan.distance));
         swipes++;
-        await sleep(SCROLL_SETTLE_MS);
+        await (0, wait_1.sleep)(SCROLL_SETTLE_MS);
         const before = current.bounds;
         snapshot = ctx.driver.getElements(opts);
         // An empty tree is a bad read, not a screen (the device returns partial dumps
@@ -312,7 +315,7 @@ async function scrollIntoView(ctx, sel, target, elements, screen, opts = {}) {
             // (half of it, to land between the two) and look once more before giving up.
             const mid = { x: Math.round((plan.from.x + plan.to.x) / 2), y: Math.round((plan.from.y + plan.to.y) / 2) };
             ctx.driver.swipe(plan.to.x, plan.to.y, mid.x, mid.y, (0, viewport_1.swipeDurationMs)(plan.distance / 2));
-            await sleep(SCROLL_SETTLE_MS);
+            await (0, wait_1.sleep)(SCROLL_SETTLE_MS);
             snapshot = ctx.driver.getElements(opts);
             if ((0, selector_1.matchElements)(snapshot, sel).matches.length === 0) {
                 throw new errors_1.SelectorNotFoundError(`'${sel.raw}' left the hierarchy while being scrolled into view (after ${swipes} swipe(s)) — ` +
@@ -388,10 +391,28 @@ async function resolveTappable(ctx, sel, opts = {}) {
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
-function cmdDevices(ctx) {
+function cmdDevices(flags) {
+    const all = (0, args_1.flagBool)(flags, 'all');
     const allDevices = [];
     try {
-        allDevices.push(...new drivers_1.AdbDriver().listDevices());
+        const android = new drivers_1.AdbDriver().listDevices();
+        // Name each running emulator by its AVD, so the listing shows the token you'd
+        // pass to `vk devices stop|restart`. Best-effort: the console may not answer.
+        for (const d of android) {
+            if (d.kind === 'emulator')
+                d.name = (0, adb_1.avdNameOf)(d.serial) || undefined;
+        }
+        allDevices.push(...android);
+        if (all) {
+            // Startable-but-not-running AVDs have no adb address yet — they are addressed
+            // by name, so `serial` stays empty rather than being invented.
+            const running = new Set(android.map((d) => (d.name ?? '').toLowerCase()).filter(Boolean));
+            for (const name of (0, adb_1.listAvds)()) {
+                if (running.has(name.toLowerCase()))
+                    continue;
+                allDevices.push({ serial: '', state: 'shutdown', platform: 'android', kind: 'emulator', name });
+            }
+        }
     }
     catch (e) {
         // adb not on PATH is the common (expected) case, but surface anything else so a real
@@ -399,8 +420,10 @@ function cmdDevices(ctx) {
         (0, output_1.err)(`devices: adb backend unavailable (${e.message})`);
     }
     try {
-        // Only include booted simulators; always include physical devices (they carry a note)
-        allDevices.push(...new drivers_1.IdbDriver().listDevices().filter((d) => d.state === 'booted' || d.note));
+        // By default only booted simulators (a shutdown one isn't drivable); physical
+        // devices always show (they carry a note). --all lists everything startable.
+        const ios = new drivers_1.IdbDriver().listDevices();
+        allDevices.push(...(all ? ios : ios.filter((d) => d.state === 'booted' || d.note)));
     }
     catch (e) {
         (0, output_1.err)(`devices: iOS backend unavailable (${e.message})`);
@@ -414,22 +437,140 @@ function cmdDevices(ctx) {
                 d.claim = claim;
         }
     }
-    if ((0, args_1.flagBool)(ctx.flags, 'json')) {
+    if ((0, args_1.flagBool)(flags, 'json')) {
         (0, output_1.json)(allDevices);
         return 0;
     }
     if (!allDevices.length) {
-        (0, output_1.err)('No devices found.');
+        (0, output_1.err)(all ? 'No devices or startable AVDs/simulators found.' : 'No devices found.');
         return 0;
     }
     for (const line of formatDeviceTable(allDevices))
         (0, output_1.out)(line);
     return 0;
 }
+/** Aliases for the lifecycle verbs, mirroring the top-level command aliases. */
+const DEVICE_VERBS = {
+    start: 'start',
+    boot: 'start',
+    stop: 'stop',
+    shutdown: 'stop',
+    kill: 'stop',
+    restart: 'restart',
+    reboot: 'restart',
+};
+/**
+ * `vk devices [list|start|stop|restart]`. Dispatched as a META-command (before the
+ * recording machinery) whenever a subcommand is present: lifecycle needs no local
+ * driver — it is what you run when there ISN'T one — and a `--server` invocation
+ * must not build one either. Bare `vk devices` keeps the ordinary path.
+ */
+async function cmdDevicesEntry(positionals, flags) {
+    const sub = String(positionals[0] ?? 'list').toLowerCase();
+    const server = serverFromFlags(flags);
+    if (sub === 'list')
+        return server ? cmdDevicesRemoteList(server, flags) : cmdDevices(flags);
+    const verb = DEVICE_VERBS[sub];
+    if (!verb) {
+        throw new errors_1.CliError(`Unknown 'devices' subcommand '${sub}'. Use: list | start | stop | restart.`, 2);
+    }
+    return server
+        ? cmdDevicesRemote(verb, positionals[1], server, flags)
+        : cmdDeviceLifecycle(verb, positionals[1], flags);
+}
+/**
+ * Refuse to power-cycle a device another job is actively driving.
+ *
+ * The local counterpart of the server's `409`: you may restart YOUR OWN device, never
+ * someone else's. Without this, device claims and device lifecycle would each work and
+ * together be a hole — one job could reboot the phone another job is mid-suite on,
+ * which is precisely the collision claims exist to prevent.
+ *
+ * `start` is exempt: it only ever brings up something that is not running, so there is
+ * nothing to pull out from under anyone.
+ */
+function assertNotClaimedByOthers(target, verb) {
+    if (verb === 'start' || !target.serial || !(0, claims_1.claimsEnabled)())
+        return;
+    const claim = (0, claims_1.summarize)(target.serial);
+    if (!claim || claim.mine)
+        return;
+    throw new errors_1.CliError(`${(0, lifecycle_1.targetLabel)(target)} (${target.serial}) is in use by ${claim.by} — ` +
+        `${verb} would pull the device out from under it.\n` +
+        `If that job is gone, hand the device back first: vk device release ${target.serial}`, 2);
+}
+async function cmdDeviceLifecycle(verb, rawTarget, flags) {
+    const wipe = (0, args_1.flagBool)(flags, 'wipe');
+    const wait = !(0, args_1.flagBool)(flags, 'no-wait');
+    const timeoutFlag = (0, args_1.flagStr)(flags, 'timeout');
+    const timeoutMs = timeoutFlag
+        ? parseDuration(timeoutFlag, 'timeout')
+        : verb === 'stop'
+            ? wait_1.DEFAULT_STOP_TIMEOUT_MS
+            : wait_1.DEFAULT_BOOT_TIMEOUT_MS;
+    // An explicit --ios/--android/--platform narrows the search; otherwise probe both
+    // backends, exactly as bare `vk devices` does, so `devices start Pixel_6_API_34`
+    // works without also naming the platform. A name that hits BOTH is still exit 2.
+    const explicitPlatform = (0, args_1.flagBool)(flags, 'ios') || (0, args_1.flagBool)(flags, 'android') || (0, args_1.flagStr)(flags, 'platform') !== undefined;
+    const lifecycles = explicitPlatform ? [(0, lifecycle_1.lifecycleFor)(platformFromFlags(flags))] : (0, lifecycle_1.allLifecycles)();
+    const targets = lifecycles.flatMap((l) => l.targets());
+    if (!rawTarget) {
+        const startable = targets.filter((t) => t.kind !== 'physical').map(lifecycle_1.targetLabel).filter(Boolean);
+        const hint = startable.length
+            ? `\nStartable: ${[...new Set(startable)].join(', ')}`
+            : '\nRun `vk devices --all` to list startable devices.';
+        throw new errors_1.CliError(`Usage: verikun devices ${verb} <name|serial> [--timeout <dur>]${hint}`, 2);
+    }
+    // `start` wants the one that ISN'T up; `stop`/`restart` want the live one.
+    const chosen = (0, lifecycle_1.chooseTarget)(targets, rawTarget, { prefer: verb === 'start' ? 'startable' : 'running' });
+    (0, lifecycle_1.assertActionable)(chosen, verb, { wipe });
+    assertNotClaimedByOthers(chosen, verb);
+    const lc = (0, lifecycle_1.lifecycleFor)(chosen.platform);
+    const onProgress = (m) => (0, output_1.err)(`[verikun] ${m}`);
+    const asJson = (0, args_1.flagBool)(flags, 'json');
+    if (verb === 'stop') {
+        const r = await lc.shutdown(chosen, { timeoutMs, onProgress });
+        if (asJson) {
+            (0, output_1.json)({ action: 'stop', requested: rawTarget, platform: chosen.platform, kind: chosen.kind, serial: r.serial, name: chosen.name, stopped: r.stopped });
+        }
+        else {
+            (0, output_1.err)(r.stopped ? `stopped ${(0, lifecycle_1.targetLabel)(chosen)}` : `${(0, lifecycle_1.targetLabel)(chosen)} was not running`);
+            (0, output_1.out)(r.serial);
+        }
+        return 0;
+    }
+    const opts = { timeoutMs, wait, wipe, onProgress };
+    const r = verb === 'restart'
+        ? await (0, lifecycle_1.restartTarget)(lc, chosen, opts)
+        : { ...(await lc.boot(chosen, opts)), stopped: false };
+    if (asJson) {
+        (0, output_1.json)({
+            action: verb,
+            requested: rawTarget,
+            platform: chosen.platform,
+            kind: chosen.kind,
+            serial: r.serial,
+            name: chosen.name,
+            started: r.started,
+            ready: r.ready,
+            waitedMs: r.waitedMs,
+            ...(r.logPath ? { logPath: r.logPath } : {}),
+        });
+    }
+    else {
+        if (verb === 'start' && !r.started)
+            (0, output_1.err)(`${(0, lifecycle_1.targetLabel)(chosen)} is already running`);
+        // stdout is the one machine-usable datum: the serial, so
+        // `vk -d "$(vk devices start X)" ui` composes. Under --no-wait on Android there
+        // is genuinely no serial yet, so print nothing rather than invent one.
+        (0, output_1.out)(r.serial ?? '');
+    }
+    return 0;
+}
 /**
  * Render the device list as an aligned, headed table (header line first, then one
- * line per device). Optional columns (MODEL/PRODUCT/NOTE) are dropped when no device
- * populates them; every shown cell is padded to its column width so columns line up
+ * line per device). Optional columns (KIND/NAME/MODEL/PRODUCT/NOTE) are dropped when no
+ * device populates them; every shown cell is padded to its column width so columns line up
  * regardless of which cells are empty — the previous `.filter(Boolean).join('\t')`
  * dropped empty cells, sliding later cells into earlier tab stops. Exported for unit
  * testing.
@@ -437,8 +578,10 @@ function cmdDevices(ctx) {
 function formatDeviceTable(devices) {
     const columns = [
         { header: 'PLATFORM', get: (d) => d.platform },
+        { header: 'KIND', get: (d) => d.kind ?? '', optional: true },
         { header: 'SERIAL', get: (d) => d.serial },
         { header: 'STATE', get: (d) => d.state },
+        { header: 'NAME', get: (d) => d.name ?? '', optional: true },
         { header: 'MODEL', get: (d) => d.model ?? '', optional: true },
         { header: 'PRODUCT', get: (d) => d.product ?? '', optional: true },
         // Optional like the rest, which is load-bearing twice over: nothing changes for a
@@ -650,13 +793,13 @@ async function cmdText(ctx) {
     });
     ctx.driver.tap(point.x, point.y);
     // Wait for field to be focused after tap
-    await sleep(100);
+    await (0, wait_1.sleep)(100);
     if ((0, args_1.flagBool)(ctx.flags, 'clear') && target.text) {
         ctx.driver.pressKey('move_end');
         for (let i = 0; i < target.text.length + 2; i++)
             ctx.driver.pressKey('del');
         // Wait for field to settle after clearing before typing
-        await sleep(200);
+        await (0, wait_1.sleep)(200);
     }
     // Prime the input method with a space, then delete it, to avoid losing first character
     // (workaround for adb input text behavior where first char is sometimes lost)
@@ -887,7 +1030,7 @@ async function cmdWait(ctx) {
                 (0, output_1.out)((0, format_1.formatCompact)(matches));
             return 0;
         }
-        await sleep(interval);
+        await (0, wait_1.sleep)(interval);
     }
     ctx.record?.note({ selector: sel, message: `timeout after ${timeout}ms${gone ? ' (still present)' : ' (never appeared)'}` });
     (0, output_1.err)(`timeout after ${timeout}ms waiting for '${sel.raw}'${gone ? ' to disappear' : ''}`);
@@ -938,7 +1081,7 @@ async function cmdAssert(ctx) {
     const deadline = Date.now() + waitWindowMs(ctx.flags);
     let result = evalAssert(readForPoll(ctx), sel, ctx.flags);
     while (!result.pass && Date.now() < deadline) {
-        await sleep(pollStep(ctx.flags, deadline));
+        await (0, wait_1.sleep)(pollStep(ctx.flags, deadline));
         result = evalAssert(readForPoll(ctx), sel, ctx.flags);
     }
     const { pass, reason, matches } = result;
@@ -1624,9 +1767,136 @@ async function obtainPlan(key, file, opts, cost, provider) {
     }
     return { plan: compiled.plan, cached: false };
 }
+/** 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) {
+    return (0, args_1.flagStr)(flags, 'server') || process.env.VERIKUN_SERVER || undefined;
+}
+function remoteOptsFrom(url, flags) {
+    return { url, authKey: (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined };
+}
+/**
+ * `--ensure-device[=<target>]` — the requested target, or `undefined` for the bare
+ * form, or `null` when the flag is absent. Exported for unit tests.
+ */
+function ensureDeviceTarget(flags) {
+    const raw = flags['ensure-device'];
+    if (raw === undefined || raw === false)
+        return null;
+    if (raw === true || raw === 'true')
+        return undefined;
+    return String(raw);
+}
+/** The one target that is startable without guessing, else exit 2 with the options. */
+function soleStartable(targets) {
+    const startable = targets.filter((t) => t.kind !== 'physical' && !(0, lifecycle_1.isRunning)(t));
+    if (startable.length === 1)
+        return startable[0];
+    const names = [...new Set(startable.map(lifecycle_1.targetLabel).filter(Boolean))];
+    throw new errors_1.CliError(startable.length === 0
+        ? '--ensure-device: no startable device found. Run `vk devices --all` to check the toolchain.'
+        : `--ensure-device: ${startable.length} devices could be started — name one, ` +
+            `e.g. --ensure-device="${names[0]}"\n  ${names.join('\n  ')}`, 2);
+}
+/**
+ * Boot a device before the first step, when `--ensure-device` asks for it. Runs here
+ * — inside resolveBackend, before runCtx is fixed — rather than inside `vk suite`,
+ * so the booted serial is the one every recorded step is attributed to. It is
+ * structurally unable to turn a red test green: it happens before any step executes,
+ * never between tests and never mid-run.
+ */
+async function ensureLocalDevice(platform, device, flags) {
+    const want = ensureDeviceTarget(flags);
+    if (want === null)
+        return;
+    try {
+        const serial = (0, drivers_1.getDriver)(platform, device).resolvedSerial();
+        // `--ensure-device=X` means "boot X if nothing is usable", not "make X the
+        // device" — so say so plainly when a different device is already serving,
+        // rather than reporting a serial the caller didn't ask for.
+        (0, output_1.err)(`[verikun] --ensure-device: ${serial} is already available${want ? ` — not booting '${want}'` : ''}`);
+        return;
+    }
+    catch (e) {
+        // Ambiguity (exit 2) is an operator error — booting another device makes it worse.
+        if (!(e instanceof errors_1.CliError) || e.exitCode !== 3)
+            throw e;
+    }
+    const lc = (0, lifecycle_1.lifecycleFor)(platform);
+    const targets = lc.targets();
+    const chosen = want ? (0, lifecycle_1.chooseTarget)(targets, want, { prefer: 'startable' }) : soleStartable(targets);
+    (0, lifecycle_1.assertActionable)(chosen, 'start');
+    (0, output_1.err)(`[verikun] --ensure-device: booting ${(0, lifecycle_1.targetLabel)(chosen)}…`);
+    await lc.boot(chosen, {
+        timeoutMs: wait_1.DEFAULT_BOOT_TIMEOUT_MS,
+        wait: true,
+        wipe: false,
+        onProgress: (m) => (0, output_1.err)(`[verikun] ${m}`),
+    });
+}
+/** The remote half of `--ensure-device`: ask the server to boot, then re-ping so the
+ *  run context carries the serial the device actually came up as. */
+async function ensureRemoteDevice(health, opts, url, flags) {
+    const want = ensureDeviceTarget(flags);
+    if (want === null)
+        return health;
+    if (health.serial) {
+        (0, output_1.err)(`[verikun] --ensure-device: ${health.serial} is already bound on ${url}${want ? ` — not booting '${want}'` : ''}`);
+        return health;
+    }
+    assertDeviceControl(health, url, want);
+    (0, output_1.err)(`[verikun] --ensure-device: asking ${url} to boot a device…`);
+    await (0, remote_1.remoteDeviceOp)(opts, 'start', want ? { target: want } : {});
+    return (0, remote_1.pingServer)(opts);
+}
+/** Feature-detect device control from /v1/health. Never compare versions: a client
+ *  cannot tell "old server" from "new server, flag off", and both need this answer. */
+function assertDeviceControl(health, url, target) {
+    if (!health.deviceControlEnabled) {
+        throw new errors_1.CliError(`device control is not available on the verikun server at ${url} (verikun ${health.version}). ` +
+            'Restart it with --allow-device-control.', 3);
+    }
+    if (target && !health.deviceNamingEnabled) {
+        throw new errors_1.CliError(`the server at ${url} was started with a bare --allow-device-control — it can only act on its own ` +
+            `device, not '${target}'. Restart it with --allow-device-control=<names>.`, 2);
+    }
+}
+async function cmdDevicesRemote(verb, target, url, flags) {
+    const opts = remoteOptsFrom(url, flags);
+    const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
+    assertDeviceControl(health, url, target);
+    const wipe = (0, args_1.flagBool)(flags, 'wipe');
+    (0, output_1.err)(`[verikun] ${verb} device on ${url}${target ? ` (${target})` : ''}${wipe ? ' with WIPE' : ''}…`);
+    const r = await (0, remote_1.remoteDeviceOp)(opts, verb, { ...(target ? { target } : {}), ...(wipe ? { wipe } : {}) });
+    (0, output_1.err)(`[verikun] ${r.changed ? `${verb} ok` : 'already running'} · ${r.serial ?? '(none)'} · ` +
+        `${(r.durationMs / 1000).toFixed(1)}s`);
+    if ((0, args_1.flagBool)(flags, 'json'))
+        (0, output_1.json)({ action: verb, server: url, ...r });
+    else
+        (0, output_1.out)(r.serial ?? '');
+    return 0;
+}
+async function cmdDevicesRemoteList(url, flags) {
+    const opts = remoteOptsFrom(url, flags);
+    const health = await (0, remote_1.pingServer)(opts);
+    assertDeviceControl(health, url);
+    const r = await (0, remote_1.remoteDeviceList)(opts);
+    if ((0, args_1.flagBool)(flags, 'json')) {
+        (0, output_1.json)({ server: url, ...r });
+        return 0;
+    }
+    if (r.devices.length)
+        for (const line of formatDeviceTable(r.devices))
+            (0, output_1.out)(line);
+    else
+        (0, output_1.err)('No devices visible on the server.');
+    (0, output_1.err)(`[verikun] bound: ${r.bound ?? '(none)'}${r.startable.length ? ` · startable: ${r.startable.join(', ')}` : ''}`);
+    return 0;
+}
 async function resolveBackend(platform, device, flags) {
-    const server = (0, args_1.flagStr)(flags, 'server') || process.env.VERIKUN_SERVER || undefined;
+    const server = serverFromFlags(flags);
     if (!server) {
+        await ensureLocalDevice(platform, device, flags);
         const driver = (0, drivers_1.getDriver)(platform, device);
         // Fail fast on a broken toolchain BEFORE any model spend — the mirror of the
         // remote branch's pingServer below. Without this, a missing `idb` isn't noticed
@@ -1680,9 +1950,13 @@ async function resolveBackend(platform, device, flags) {
         // so archive-time / vk log scoping works without a local driver.
         onStep: (step, artifacts, logStart) => run_1.Recorder.appendForeignStep(step, artifacts, { ...runCtx, logStart }),
     };
-    const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
-    runCtx = { platform: health.platform, device: health.serial };
-    (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial} · verikun ${health.version}`);
+    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
+    // into the run context and the returned device, so booting afterwards would
+    // 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}`);
     // 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
@@ -1715,7 +1989,7 @@ async function resolveBackend(platform, device, flags) {
             },
         },
         platform: health.platform,
-        device: health.serial,
+        device: health.serial ?? undefined,
         remote: { url: server, version: health.version, reads: health.reads },
     };
 }
@@ -2094,8 +2368,6 @@ function cmdCompanion(ctx) {
 // ---------------------------------------------------------------------------
 async function executeCommand(command, ctx) {
     switch (command) {
-        case 'devices':
-            return cmdDevices(ctx);
         case 'doctor':
             return cmdDoctor(ctx);
         case 'companion':
@@ -2280,6 +2552,19 @@ async function executeParsed(command, positionals, flags) {
         return cmdRun(positionals, flags, platform, device);
     if (command === 'batch')
         return cmdBatch(positionals, flags);
+    // `devices` is wholly a meta-command: it must not build a local driver. Lifecycle is
+    // what you run when there ISN'T one, a `--server` call needs no local device at all,
+    // and even the bare listing probes both backends itself rather than using ctx.driver.
+    // Dispatched in exactly one place on purpose — a command split across the switch AND
+    // this chain reads as two commands to anything parsing the dispatch (tests/docs-coverage).
+    if (command === 'devices') {
+        try {
+            return await cmdDevicesEntry(positionals, flags);
+        }
+        catch (e) {
+            return mapError(e, flags);
+        }
+    }
     // `ai`/`suite`/`install`/`server` orchestrate their own steps; map their thrown
     // CliErrors to exit codes here (usage 2 / env 3 / …) so they honor the exit-code
     // contract instead of escaping to the top-level "Fatal" handler (exit 3).
@@ -2435,6 +2720,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-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
@@ -2446,16 +2732,31 @@ SERVER (expose a locally-connected device to remote verikun clients)
                                       Env: VERIKUN_SERVER_AUTH_KEY (keeps it off argv).
   Clients: pass --server <url> (or VERIKUN_SERVER) + --auth-key (or
   VERIKUN_SERVER_AUTH_KEY) to ai/suite/install. The server's device+platform apply.
+  --allow-device-control lets a client restart/stop the server's OWN device (for a
+  device gone flaky mid-suite); --allow-device-control=<avd,sim> additionally lets it
+  START one of those named targets — and, with it, ERASE the device (--wipe). With
+  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.
 
 ENVIRONMENT
-  devices [--json]                    List attached devices/simulators, and which job is
-                                      already driving each (USED BY)
+  devices [--all] [--json]            List attached devices/simulators, and which job is
+                                      already driving each (USED BY); --all also lists
+                                      startable (not-yet-booted) AVDs/simulators
+  devices start <name> [--wipe]       Boot an AVD/simulator; prints its serial. Already
+        [--timeout dur] [--no-wait]   running = a no-op. --wipe erases its data first
+  devices stop <name|serial>          Shut a running emulator/simulator down
+  devices restart <name> [--wipe]     Stop then boot (use for a wedged/flaky device)
   doctor [--fix]                      Diagnose adb/device, and warn if this CLI or the
                                       Claude Code plugin is out of date (a warning only —
                                       it never changes the exit code). --fix disables
                                       animations. VERIKUN_NO_UPDATE_CHECK skips the check
   companion <status|stop> [--json]    On-device hierarchy reader (Android, on by default;
                                       VERIKUN_COMPANION=0 opts out)
+  Note: \`devices stop\` powers a DEVICE off; \`stop <appId>\` force-stops an APP, and
+  \`device set\` (singular) changes settings on the device you are driving.
+  Physical devices are never power-cycled. Env: VERIKUN_EMULATOR (path to the SDK's
+  \`emulator\` binary, if it isn't on PATH or under \$ANDROID_HOME).
 
 TEST RUNS (actions are recorded; a run auto-starts on first action)
   run start [name] [--force]          Begin a named run (else one starts implicitly)