verikun 0.22.1 → 0.24.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,8 +62,10 @@ 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 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");
@@ -79,9 +83,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 +221,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 +246,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 +303,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 +316,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 +392,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 +421,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 +438,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 +579,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
@@ -513,10 +657,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));
@@ -538,25 +710,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')) {
@@ -650,13 +854,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 +1091,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 +1142,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;
@@ -1015,7 +1219,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();
@@ -1028,6 +1233,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':
@@ -1168,6 +1375,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];
@@ -1212,6 +1556,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;
@@ -1492,6 +1865,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)();
     }
 }
@@ -1550,8 +1924,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) {
@@ -1624,9 +1999,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 +2182,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 +2221,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 },
     };
 }
@@ -1956,6 +2462,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')) {
@@ -2044,6 +2551,7 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
+        parkPreparedDevices(platform);
         (0, claims_1.releaseOwnClaims)();
     }
 }
@@ -2094,8 +2602,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 +2786,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).
@@ -2380,6 +2899,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
@@ -2435,6 +2961,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 +2973,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)