verikun 0.23.0 → 0.24.0

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

@@ -93,6 +93,8 @@ usually don't need a `wait` before an action — `vk tap @next` already polls fo
 - `vk swipe up|down|left|right [--on <selector>] [--distance f] [--duration ms]`
 - `vk swipe --from x,y --to x,y [--duration ms]`
 - `vk key <name|code>`  ·  `vk back`  ·  `vk home`  ·  `vk enter`
+  Named keys include `sleep` and `wakeup`. `power` is a **toggle**, so use `sleep`/`wakeup`
+  when you mean a direction.
 - `vk screenshot [--out path] [--more] [--max px] [--full]` — saves a PNG (default
   `./.verikun/screen.png`) and prints the path; then read that file to *see* the
   screen. It's **downscaled to a 700px longest edge by default** to save tokens
@@ -118,11 +120,15 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
 
   | key | values | Android | iOS simulator |
   |---|---|---|---|
+  | `animations` | `on\|off` | yes | **no** — nothing disables UIKit animation |
   | `airplane` | `on\|off` | yes | **no** — a simulator has no radio |
   | `dark` | `on\|off` | yes | yes |
   | `font-scale` | `0.5`–`3.0`, `default` | yes | yes (nearest Dynamic Type category) |
   | `rotation` | `portrait\|landscape\|portrait-reverse\|landscape-reverse\|auto` | yes | **no** |
   | `stay-awake` | `on\|off` | yes | no-op (simulators don't sleep) |
+  | `screen-timeout` | `30s` / `10m` / ms / `max` | yes | no-op (simulators don't sleep) |
+  | `dnd` | `on\|off` | yes | **no** — Focus is not scriptable |
+  | `doze` | `on\|off` | yes | no-op (no Doze equivalent) |
 
   Set several at once: `vk device set dark=on font-scale=1.3`. Each change is **verified by
   reading it back**, so success means it actually landed — these device commands silently
@@ -134,6 +140,14 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
   even when the flow *fails* — but a bare `vk device set` from a shell stays applied until
   you reset it, so don't leave someone's phone in airplane mode.
 
+- `vk device prep [--dry-run] [--revert]` — set a **test** device up once, stickily:
+  `animations=off stay-awake=on screen-timeout=max dnd=on doze=off`.
+
+  Unlike `device set`, prep **survives the run** and is undone only by `--revert`. A physical
+  device must be named (`--device <serial>`) — that requirement is deliberate, so prep can
+  never land on a personal phone that happened to be plugged in. Do not run it on a device
+  the user did not point you at. `vk doctor` reports whether a device is prepared.
+
   Two traps:
   - **`airplane=off` brings the radio back, not the internet.** Follow it with
     `vk assert <selector> --wait 10s`, never an immediate `tap`.
@@ -378,7 +392,12 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   failure).
 - **Bounded by default:** the run aborts if the estimated spend crosses **$3**
   (`--max-cost-usd`) or the wall-clock passes **15m** (`--timeout`), so a runaway
-  compile/repair loop can't spend or hang without limit.
+  compile/repair loop can't spend or hang without limit. The ceiling is **per test, not per
+  suite** — `vk suite` gives each `*.md` its own fresh budget, so 20 tests at the default can
+  reach $60; there is no suite-wide cap, so lower the per-test figure instead. A model is only
+  ever called to **compile** (once, on a cache miss) or to **repair** (≤3 per failing step);
+  replay is always $0, and every non-`ai` command is $0 always. Full mechanism, the estimate
+  formula and the cache multipliers: <https://ddikman.github.io/verikun/reference/cost/>.
 - Exit `0` pass · `1` a step failed (or the budget/timeout was hit) · `2` usage · `3` environment
   (e.g. the model's API key — `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` — unset, or the `codex` /
   `cursor-agent` CLI missing / not logged in for `--model codex-cli` / `cursor-cli`).
@@ -510,8 +529,13 @@ owns the redaction and the review-first flow.
 
 ## Gotchas
 
-- **Disable animations once** for reliable dumps: `vk doctor --fix`. Live
-  animations can make `vk ui` flaky (it already retries 3×).
+- **Prepare the device once** for reliable dumps: `vk device prep` (a physical device
+  needs `--device <serial>`). Live animations can make `vk ui` flaky (it already retries 3×).
+- **A slept device returns the LOCK SCREEN, not an error.** The dump succeeds and hands
+  back `com.android.systemui` — so selectors miss for a reason unrelated to the app.
+  verikun detects this, wakes the device and clears a *swipe* lock automatically; on a
+  PIN/pattern/password it exits **3** naming the lock rather than returning that dump.
+  Tell the user to remove the lock in Settings > Security — verikun never asks for a PIN.
 - **Ambiguous selector → exit 2**, never a random tap. `vk` prints the candidate
   matches; add `--index N` or use a more specific selector.
 - **Indexes are per-snapshot.** `vk tap 3` taps `[3]` from the *latest* dump;
@@ -549,13 +573,15 @@ owns the redaction and the review-first flow.
   use `xcrun simctl`. Run `vk doctor --ios` to check the toolchain. Caveats: `clear`
   is unsupported (no per-app reset), `current` is `(unknown)`, device logs are
   simulator-only, and `device set` is partial — `dark`/`font-scale` work on a simulator
-  while `airplane`/`rotation` do not exist there at all (`vk device caps --ios`). iOS
+  while `animations`/`airplane`/`rotation`/`dnd` do not exist there at all, and
+  `stay-awake`/`screen-timeout`/`doze` are no-ops (`vk device caps --ios`). That makes
+  `vk device prep` effectively Android-only: on iOS it applies nothing and says so. iOS
   accessibility ids are often unset, so prefer `text:`/`desc:` selectors there.
 
 ## Worked example — verify a login flow
 
 ```sh
-vk doctor --fix                              # deterministic UI
+vk doctor                                    # is the device set up? (read-only)
 vk launch com.example.app
 vk text @email_input "user@example.com"      # field lookup auto-waits up to 5s
 vk text @password_input "hunter2" --enter

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-08-20
+
+### Added
+- **`vk device prep`**: prepare a test device once — animations off, display awake, DND on, doze off.
+- **`vk device prep --revert`**: restore what prep changed, from a host-global snapshot that outlives the run.
+- **`vk device prep --dry-run`**: show each knob's current and target value without writing.
+- **`vk device set animations|screen-timeout|dnd|doze`**: four new keys, each verified by readback.
+- **`vk key sleep` / `vk key wakeup`**: directional screen keys; `power` remains a toggle.
+- **`vk doctor`**: reports whether the device is prepared and whether it has a screen lock.
+- **Docs site**: a `Cost & budget` reference page — when a model is called, the estimate formula,
+  and that `--max-cost-usd` is per test, not per suite. ([#94])
+
+### Changed
+- **`vk doctor --fix`**: now an alias for `device prep`, so a physical device must be named with `--device`.
+- **`vk doctor`**: read-only without `--fix`; it no longer writes animation scales directly.
+- **`vk batch|ai|suite`**: put a prepped device to sleep on teardown; `--no-sleep-when-idle` opts out.
+
+### Fixed
+- **UI reads**: a locked device returned the lock screen as a successful dump; now woken, unlocked if
+  the lock is a swipe, else exit `3` naming it.
+- **Docs site**: the `vk ai` cost line was printed in a format the CLI never emitted.
+
+[#94]: https://github.com/ddikman/verikun/issues/94
+
 ## [0.23.0] - 2026-08-17
 
 ### Added
@@ -30,6 +54,10 @@ All notable changes to this project are documented here. The format is based on
 - **`vk devices start --server`**: releases the device lock when it finishes, instead of `409`ing
   the run it just booted the device for.
 
+### Changed
+- **Docs site**: content column widened to 60rem, giving the reference tables more room on
+  large screens.
+
 ## [0.22.2] - 2026-08-17
 
 ### Changed

package/README.md

@@ -6,7 +6,7 @@
 
 - **Agent CLI** — `vk <command>`: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
-- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step.
+- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
 - **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it.
 
@@ -37,7 +37,8 @@ The package also carries the agent [`SKILL.md`](.claude/skills/verikun/SKILL.md)
 ## Quick start
 
 ```sh
-vk doctor --fix                 # check adb/device; disable animations for stable dumps
+vk doctor                       # check adb/device (read-only — never changes anything)
+vk device prep --device <id>    # set a TEST device up once: animations off, stays awake
 vk devices                      # list attached devices
 vk ui                           # semantic snapshot of the current screen
 vk tap @login_button            # tap by resource-id

package/dist/args.js

@@ -44,6 +44,9 @@ const BOOLEAN = new Set([
     'no-restart',
     'no-logs',
     'wipe',
+    'dry-run',
+    'revert',
+    'no-sleep-when-idle',
     'allow-install',
     'allow-unsafe-anonymous',
     // NOT here on purpose: 'allow-device-control' and 'ensure-device' are tri-state

package/dist/cli.js

@@ -65,6 +65,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 +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));
@@ -681,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')) {
@@ -1158,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();
@@ -1171,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':
@@ -1311,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];
@@ -1355,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;
@@ -1635,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)();
     }
 }
@@ -1693,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) {
@@ -2230,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')) {
@@ -2318,6 +2551,7 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
+        parkPreparedDevices(platform);
         (0, claims_1.releaseOwnClaims)();
     }
 }
@@ -2665,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

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));

package/dist/device/prep.js

@@ -0,0 +1,156 @@
+"use strict";
+// Test-device provisioning — "make this phone a good place to run tests, once".
+//
+// The distinction that shapes everything here is PREP vs `device set`:
+//
+//   * `device set` is TRANSIENT. It snapshots into the run file and the `finally` in
+//     ai/suite/batch puts it back, because a test that goes offline must come back online.
+//   * PREP is STICKY. Turning animations off and the display timeout up is not part of a
+//     test, it is what makes tests readable at all — so it must survive the run that
+//     established it, and be undone only when someone explicitly asks.
+//
+// That is why the snapshot lives HOST-GLOBALLY here rather than in `RunState.deviceOverrides`,
+// and why no `finally` may touch it.
+//
+// Deliberately in its own directory (`~/.verikun/prepared/`) rather than beside the claims in
+// `~/.verikun/devices/`: claims are churn — created, taken over and deleted constantly, and
+// `rm ~/.verikun/devices/*` is a thing people genuinely do to clear a stuck one. A prep record
+// is the ONLY copy of the values needed to put a borrowed phone back, so it must not sit in
+// the directory whose contents are routinely swept.
+//
+// Platform-agnostic like `settings.ts` and `claims.ts`: it never touches adb/xcrun. The table
+// says what a knob is, this says which knobs prep establishes and what they used to be, and
+// the drivers know how.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREP_KNOBS = void 0;
+exports.prepDir = prepDir;
+exports.readPrep = readPrep;
+exports.isPrepared = isPrepared;
+exports.mergeOriginals = mergeOriginals;
+exports.writePrep = writePrep;
+exports.clearPrep = clearPrep;
+exports.newPrepRecord = newPrepRecord;
+exports.assertPreppable = assertPreppable;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+const version_1 = require("../version");
+const claims_1 = require("./claims");
+/**
+ * The prep set.
+ *
+ * Every entry has to name a failure `vk` actually has. This is not "sensible defaults for a
+ * phone" — it is the shortest list that makes a hierarchy read trustworthy, and anything that
+ * merely feels tidy belongs in the user's own `device set` call instead.
+ */
+exports.PREP_KNOBS = [
+    { key: 'animations', value: 'off', why: 'a live animation makes `uiautomator dump` return a stale or empty screen' },
+    // Measured: a slept device does NOT fail the read — it serves the lock screen as a
+    // successful dump. Keeping the display up is what stops that, and it is why these two
+    // knobs are in the set rather than being left to the recovery path in getElements().
+    { key: 'stay-awake', value: 'on', why: 'a slept display reads back as the LOCK SCREEN, not as an error' },
+    { key: 'screen-timeout', value: 'max', why: 'the same, for a device that is not plugged in' },
+    { key: 'dnd', value: 'on', why: 'a heads-up notification lands on top of the app and steals the next tap' },
+    { key: 'doze', value: 'off', why: 'battery idle suspends the background work a test is waiting on' },
+];
+function prepDir(o = {}) {
+    return (0, node_path_1.join)(o.home ?? (0, node_os_1.homedir)(), '.verikun', 'prepared');
+}
+function pathFor(serial, o) {
+    return (0, node_path_1.join)(prepDir(o), `${(0, claims_1.deviceFileStem)(serial)}.json`);
+}
+/**
+ * Read a device's prep record. Missing, unreadable or malformed all mean NOT PREPARED —
+ * the same tolerant posture as `readClaim` and the plan cache. A poisoned file must not be
+ * able to make a device permanently un-preppable.
+ */
+function readPrep(serial, o = {}) {
+    const p = pathFor(serial, o);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const r = JSON.parse((0, node_fs_1.readFileSync)(p, 'utf8'));
+        // Guard the field every decision reads. A file that parses as JSON but is not a prep
+        // record must not make `--revert` iterate undefined.
+        if (typeof r?.serial !== 'string' || typeof r?.original !== 'object' || r.original === null)
+            return null;
+        return r;
+    }
+    catch (e) {
+        (0, output_1.err)(`[verikun] ignoring unreadable prep record ${p} (${e.message})`);
+        return null;
+    }
+}
+function isPrepared(serial, o = {}) {
+    return readPrep(serial, o) !== null;
+}
+/**
+ * Earliest wins. Re-prepping a device (or prepping one whose knobs have drifted) must never
+ * overwrite the pre-prep value with a value prep itself established — that would make
+ * `--revert` restore the device to prepped, i.e. do nothing at all, silently.
+ */
+function mergeOriginals(prior, fresh) {
+    const merged = { ...prior };
+    for (const [k, v] of Object.entries(fresh)) {
+        if (!(k in merged) && v !== undefined)
+            merged[k] = v;
+    }
+    return merged;
+}
+/** Write atomically, so a concurrent reader sees the old record or the new one, never half. */
+function writePrep(rec, o = {}) {
+    const p = pathFor(rec.serial, o);
+    (0, node_fs_1.mkdirSync)(prepDir(o), { recursive: true });
+    const tmp = `${p}.tmp-${process.pid}`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(rec, null, 2));
+    (0, node_fs_1.renameSync)(tmp, p);
+}
+function clearPrep(serial, o = {}) {
+    try {
+        (0, node_fs_1.unlinkSync)(pathFor(serial, o));
+    }
+    catch {
+        /* already gone is the outcome we wanted */
+    }
+}
+function newPrepRecord(serial, platform, original, sleepWhenIdle, o = {}) {
+    return {
+        serial,
+        platform,
+        original,
+        sleepWhenIdle,
+        preparedAt: new Date(o.now ?? Date.now()).toISOString(),
+        version: version_1.VERSION,
+    };
+}
+// --- the explicitness gate --------------------------------------------------
+/**
+ * Refuse to prep a physical device that the caller did not name.
+ *
+ * Emulators and simulators are disposable; a physical phone might be the one in your pocket.
+ * `lifecycle.ts:203` already draws this exact line (it refuses to power-cycle a physical
+ * device), and this is the second caller — hence `DeviceKind` from types.ts rather than a
+ * parallel two-value type that would have to be kept in step with it.
+ *
+ * Naming the serial IS the opt-in — there is deliberately no `vk device trust` verb and no
+ * persisted allow-list. One less piece of state to go stale, and the thing you type names the
+ * phone you mean, which a flag like `--yes` never does: an agent would simply always pass it,
+ * and it would stop meaning anything (the same reason device claims have no `--force`).
+ *
+ * `writes` is how many knobs would actually be applied. When it is zero there is nothing to
+ * protect against — that is what makes `vk device prep` on iOS, where every knob is a noop or
+ * unsupported, report honestly instead of refusing for no reason.
+ *
+ * An UNKNOWN kind is treated as physical by the caller, deliberately: the fail-safe direction
+ * here is more gating, never less.
+ */
+function assertPreppable(kind, serial, named, writes) {
+    if (writes === 0 || kind !== 'physical' || named)
+        return;
+    throw new errors_1.CliError(`Refusing to prepare ${serial}: it is a physical device and was not named explicitly.\n` +
+        'Prep changes settings that outlive the run (animations, display timeout, Do Not Disturb), ' +
+        'so it must never land on a personal phone that happened to be plugged in.\n' +
+        `If this is a test device, say so by naming it:\n  verikun device prep --device ${serial}`, 2);
+}

package/dist/device/settings.js

@@ -70,6 +70,42 @@ function parseFontScale(raw) {
     // Canonicalize so '1.30', '1.3' and '1.300' all snapshot/compare identically.
     return canonicalFontScale(n);
 }
+// --- screen timeout ---------------------------------------------------------
+/**
+ * Android stores `screen_off_timeout` as a signed 32-bit int of MILLISECONDS, so this is
+ * as close to "never" as the setting can express. `max` is offered as a name because the
+ * number is meaningless to read and nobody should have to remember it.
+ */
+const SCREEN_TIMEOUT_MAX_MS = 2147483647;
+/** Below a second the display would blank between two steps of the same tap. A value
+ *  that low is a typo, not an intent — refuse it here rather than after it is written. */
+const SCREEN_TIMEOUT_MIN_MS = 1000;
+/**
+ * Canonical form is the raw millisecond string, NOT a pretty duration, because the
+ * device stores and reads back milliseconds. A snapshot has to round-trip through
+ * `setDeviceSetting` unchanged, and `30s` vs `30000` would compare unequal for the same
+ * value and report a perfectly good restore as refused — the same trap
+ * `canonicalFontScale` exists to close.
+ */
+function parseScreenTimeout(raw) {
+    const t = raw.trim().toLowerCase();
+    if (t === 'max' || t === 'never')
+        return String(SCREEN_TIMEOUT_MAX_MS);
+    const m = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(t);
+    if (!m) {
+        throw new errors_1.CliError(`Invalid value '${raw}' for 'screen-timeout': expected a duration like 30s, 10m, ` +
+            "a bare number of milliseconds, or 'max'.", 2);
+    }
+    // A bare number is milliseconds, matching what the device stores and what
+    // `parseDuration` does everywhere else in the CLI.
+    const unit = m[2] ?? 'ms';
+    const n = Number(m[1]);
+    const ms = Math.round(unit === 'm' ? n * 60000 : unit === 's' ? n * 1000 : n);
+    if (ms < SCREEN_TIMEOUT_MIN_MS || ms > SCREEN_TIMEOUT_MAX_MS) {
+        throw new errors_1.CliError(`Invalid value '${raw}' for 'screen-timeout': must be between ${SCREEN_TIMEOUT_MIN_MS}ms and 'max'.`, 2);
+    }
+    return String(ms);
+}
 /** Android `user_rotation` values, by the name we expose. */
 const ROTATIONS = {
     portrait: 0,
@@ -145,6 +181,19 @@ function contentSizeToFontScale(category) {
 }
 // --- the table --------------------------------------------------------------
 exports.SETTINGS = {
+    animations: {
+        key: 'animations',
+        describe: 'Window/transition/animator scales — live animations are the main cause of flaky dumps',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('animations', raw),
+        support: { android: 'supported', ios: 'unsupported' },
+        manual: {
+            ios: 'Neither `simctl` nor `idb` can disable UIKit animation. The Simulator menu offers only ' +
+                'Debug > Slow Animations, which is the opposite of what a test wants — prefer `vk` selector ' +
+                'auto-wait, which polls until the screen settles.',
+        },
+        note: {},
+    },
     airplane: {
         key: 'airplane',
         describe: 'Airplane mode — cut the radios to test offline/retry handling',
@@ -200,6 +249,39 @@ exports.SETTINGS = {
         manual: {},
         note: { ios: 'simulators do not sleep, so there is nothing to keep awake' },
     },
+    'screen-timeout': {
+        key: 'screen-timeout',
+        describe: "How long the display stays on when idle — 'max' is the test-device setting",
+        values: "a duration like 30s or 10m, a bare number of milliseconds, or 'max'",
+        parse: parseScreenTimeout,
+        support: { android: 'supported', ios: 'noop' },
+        manual: {},
+        note: { ios: 'simulators do not sleep, so there is no display timeout to extend' },
+    },
+    dnd: {
+        key: 'dnd',
+        describe: 'Do Not Disturb — stops a heads-up notification stealing a tap mid-run',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('dnd', raw),
+        support: { android: 'supported', ios: 'unsupported' },
+        manual: {
+            ios: '`simctl ui` exposes only appearance/content_size/increase_contrast, and neither it ' +
+                "nor `idb` can reach Focus. Turn it on inside the simulator: Settings > Focus > Do Not Disturb.",
+        },
+        note: {},
+    },
+    doze: {
+        key: 'doze',
+        describe: 'Battery idle/Doze — leave it off on a test device so background work is not suspended',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('doze', raw),
+        support: { android: 'supported', ios: 'noop' },
+        manual: {},
+        note: {
+            ios: 'iOS has no scriptable Doze equivalent, and a simulator does not idle-suspend ' +
+                'the app the way Android does — there is nothing to turn off',
+        },
+    },
 };
 exports.SETTING_KEYS = Object.keys(exports.SETTINGS);
 function isSettingKey(v) {

package/dist/drivers/adb.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdbDriver = void 0;
 exports.probeAdb = probeAdb;
+exports.parseLockKind = parseLockKind;
+exports.looksLikeSystemUi = looksLikeSystemUi;
+exports.lockKindOf = lockKindOf;
 exports.escapeText = escapeText;
 exports.adbTransport = adbTransport;
 exports.severanceRisk = severanceRisk;
@@ -46,6 +49,90 @@ function probeAdb() {
         return { name: 'adb', ok: false, detail: e.message, hint: ADB_HINT };
     }
 }
+/**
+ * What kind of screen lock a `dumpsys lock_settings` dump describes. Pure, and exported so
+ * the two measured rules below are unit-testable without a device.
+ *
+ *   * MATCH CASE-INSENSITIVELY. The string changed between releases — `CredentialType: Pin`
+ *     on API 32, `CredentialType: PIN` on API 35.
+ *   * NEVER read the neighbouring `Quality` field. It reported 196608 on API 32 and 0 on API
+ *     35 for two devices that BOTH had a PIN set, so trusting it would report a locked phone
+ *     as unlocked — and "no lock" is exactly what licenses us to walk past a keyguard.
+ *
+ * Anything unrecognized is `unknown`, never `none`: a failed read must not be able to grant
+ * permission that a successful read would have withheld.
+ *
+ * MEASURED GAP: API 29 does not print `CredentialType` at all — its dump is just
+ * `SP Enabled` / `SP Handle` / `SID` — so this returns `unknown` there and `vk doctor` stays
+ * silent about the lock. That is the honest degrade and it costs nothing important, because
+ * the read-time protection in `AdbDriver.onKeyguard` keys off `dumpsys trust`'s `deviceLocked`,
+ * which works on API 29. `SID` looks like a usable substitute but is not: only the
+ * credential-present case has been observed, so reading it could only ever be a guess.
+ */
+function parseLockKind(dump) {
+    const m = /CredentialType:\s*(\w+)/i.exec(dump);
+    switch (m?.[1].toLowerCase()) {
+        case 'none':
+            return 'none';
+        case 'pin':
+            return 'pin';
+        case 'pattern':
+            return 'pattern';
+        case 'password':
+            return 'password';
+        default:
+            return 'unknown';
+    }
+}
+const SYSTEMUI_ID_PREFIX = 'com.android.systemui:id/';
+/** The platform's own namespace. Neutral evidence — see `looksLikeSystemUi`. */
+const FRAMEWORK_ID_PREFIX = 'android:id/';
+/**
+ * Is every package-qualified resource-id in this hierarchy the system's rather than an app's?
+ *
+ * The free half of the keyguard check (see `AdbDriver.onKeyguard`). Pure, and exported so the
+ * discriminator is unit-testable without a device.
+ *
+ * Two rules, both measured on a locked Pixel 3a (API 32):
+ *
+ *   * Nodes with no package-qualified id are SKIPPED, not counted either way. Most nodes have
+ *     no resource-id at all, and a Flutter app has none anywhere, so the answer hinges on
+ *     whether any APP id appears rather than on a ratio.
+ *   * `android:` is NEUTRAL, not disqualifying. The lock screen inflates framework notification
+ *     layouts inside SystemUI's rows — `android:id/status_bar_latest_event_content`,
+ *     `android:id/icon` — so treating the platform namespace as "this must be an app" made the
+ *     check pass on a bare keyguard and fail once a notification was on it. One third-party
+ *     package id is proof we are looking at an app; none, plus at least one SystemUI id, is the
+ *     keyguard's signature.
+ *
+ * False positives are cheap and safe: they cost one `dumpsys trust`, which then reports the
+ * device unlocked and the elements are returned untouched.
+ */
+function looksLikeSystemUi(els) {
+    let sawSystemUi = false;
+    for (const e of els) {
+        if (!e.id.includes(':id/'))
+            continue;
+        if (e.id.startsWith(SYSTEMUI_ID_PREFIX)) {
+            sawSystemUi = true;
+            continue;
+        }
+        if (e.id.startsWith(FRAMEWORK_ID_PREFIX))
+            continue;
+        return false;
+    }
+    return sawSystemUi;
+}
+/** Screen-lock kind for a serial WITHOUT building a driver — and therefore without taking a
+ *  claim, which is what lets `vk doctor` report it while staying the read-only survey it is. */
+function lockKindOf(serial) {
+    try {
+        return parseLockKind((0, exec_1.runText)(ADB, ['-s', serial, 'shell', 'dumpsys', 'lock_settings']).stdout);
+    }
+    catch {
+        return 'unknown';
+    }
+}
 /** Short probes only — a boot poll must not block the event loop (see wait.ts). */
 const PROBE_TIMEOUT_MS = 5000;
 /** The boot animation lags sys.boot_completed; waiting it out makes dumps less flaky,
@@ -76,7 +163,11 @@ const KEYCODES = {
     dpad_left: 21,
     dpad_right: 22,
     dpad_center: 23,
+    // `power` is a TOGGLE, so it cannot express "make sure the screen is on". sleep/wakeup
+    // are the directional pair, and they are what the wake-before-dump path below uses.
     power: 26,
+    sleep: 223,
+    wakeup: 224,
     app_switch: 187,
     recents: 187,
     volume_up: 24,
@@ -166,6 +257,12 @@ function severanceRisk(transport, key, value) {
  *  local writes, so they land in well under a second or not at all. */
 const VERIFY_TIMEOUT_MS = 4000;
 const VERIFY_INTERVAL_MS = 200;
+/** How long to let the screen settle after a wakeup before reading it. Long enough for
+ *  the unlock/wake animation, short enough that it is noise next to the dump it precedes. */
+const WAKE_SETTLE_MS = 600;
+/** The three `global` scales behind the `animations` setting. All must be zero for it to
+ *  read `off` — one live scale is enough to make a dump flaky. */
+const ANIMATION_SCALES = ['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale'];
 /**
  * Parse `adb devices -l` output into DeviceInfo[]. PURE — exported for unit tests
  * and reused by the device-lifecycle layer, which needs the attached-device list
@@ -511,12 +608,89 @@ class AdbDriver {
         return (0, exec_1.runText)(ADB, this.withSerial(['shell', ...args]), { timeout }).stdout;
     }
     getElements(opts = {}) {
+        // Ask whether the display is even on BEFORE dumping. Measured at ~85ms against a 278ms
+        // read, and it pays for itself twice over when the answer is "no": the dump that would
+        // have returned the wrong screen is skipped entirely rather than done and discarded.
+        //
+        // It cannot be deferred to "only if the hierarchy looks wrong", which is what this
+        // originally did. A dozing device does not reliably show SystemUI: a Motorola on API 29
+        // serves its VENDOR always-on display (`@clock`, `@date`, `@battery_progress`, package
+        // `com.motorola.*`), which no package heuristic can tell from an app. The display being
+        // off is the only signal that generalises — if it is off, the app is not on screen,
+        // whoever drew what is there.
+        if (this.readWakefulness() === false) {
+            (0, output_1.err)('note: the display is off — waking the device before reading the screen');
+            this.wakeAndUnlock();
+        }
+        const els = this.captureElements(opts);
+        // Second net, for a device that is awake but still behind the keyguard.
+        if (!this.keyguardReason(els))
+            return els;
+        (0, output_1.err)('note: the app is not on screen — trying to dismiss the keyguard');
+        this.wakeAndUnlock();
+        const after = this.captureElements(opts);
+        const reason = this.keyguardReason(after);
+        if (!reason)
+            return after;
+        const lock = this.readLockKind();
+        const what = reason === 'locked'
+            ? `The device is on the lock screen${lock === 'unknown' ? '' : ` (${lock})`}`
+            : "The device's display will not stay on";
+        throw new errors_1.CliError(`${what}, so this read would return the keyguard rather than the app — which would look ` +
+            'like a successful read of the wrong screen.\n' +
+            (reason === 'locked'
+                ? 'Remove the screen lock on your test device (Settings > Security), then `verikun device ' +
+                    'prep` to stop the display sleeping in the first place.\n' +
+                    'verikun never asks for or stores a device PIN, so it cannot unlock this for you.'
+                : 'Keep the display awake with `verikun device prep`, or wake it with `verikun key wakeup`.'), 3);
+    }
+    captureElements(opts) {
         const xml = this.dumpXml();
         // Read off the dump we already have: free, and it refreshes every capture, so a
         // device rotated mid-run is handled without re-asking for the screen size.
         this.lastRotation = (0, android_parse_1.parseRotation)(xml);
         return (0, android_parse_1.parseHierarchy)(xml, { ...opts, screen: this.screenOrNull() ?? undefined });
     }
+    /**
+     * Why is the system UI what we just read, rather than the app? `null` means it isn't — we
+     * are looking at the app and the elements are good.
+     *
+     * MEASURED, and the reason this check exists at all: a sleeping display does not reliably
+     * fail the read. The companion serves a hierarchy quite happily while the device is
+     * `Dozing`, so the dump SUCCEEDS and hands back a perfectly well-formed tree of
+     * `com.android.systemui` — a false green, which is worse than the hang it was assumed to be.
+     *
+     * TWO reasons, not one. `deviceLocked` alone is not enough: it is only true behind a SECURE
+     * credential, so a phone with no lock (or a swipe lock) reports `deviceLocked=0` while
+     * dozing and still shows the ambient keyguard rather than the app. Measured on a Pixel 3a
+     * once its PIN was removed — exit 0 with 36 SystemUI nodes, the same false green again.
+     *
+     * Staged so the happy path costs nothing: `looksLikeSystemUi` reads only ids we already
+     * have, and the `dumpsys` round-trips run ONLY when that says the whole screen belongs to
+     * the system. That ordering is also what stops this hijacking a notification shade the
+     * caller deliberately opened — the shade looks identical, but the device is neither locked
+     * nor asleep, so both reasons come back false and the elements are returned untouched.
+     */
+    keyguardReason(els) {
+        if (!looksLikeSystemUi(els))
+            return null;
+        if (this.deviceLocked() === true)
+            return 'locked';
+        if (this.readWakefulness() === false)
+            return 'display-off';
+        return null;
+    }
+    /** `dumpsys trust` reports `deviceLocked=1` while the keyguard is up. `null` = could not tell,
+     *  which never triggers a refusal — an unreadable probe must not block a legitimate read. */
+    deviceLocked() {
+        try {
+            const m = /deviceLocked=(\d)/.exec(this.shell(['dumpsys', 'trust']));
+            return m ? m[1] === '1' : null;
+        }
+        catch {
+            return null;
+        }
+    }
     viewport() {
         const screen = this.screenOrNull();
         return screen ? (0, viewport_1.viewportFor)(screen, this.lastRotation) : null;
@@ -602,16 +776,21 @@ class AdbDriver {
                 throw new errors_1.NoWindowError('No window to read: the app has not drawn yet (force-stopped, or mid-launch). ' +
                     'Retry, or use a command that waits (`vk wait`, or any selector lookup).');
             }
-            // A companion holds the device's ONE UiAutomation connection and SIGKILLs anything
-            // else that wants it — including this dump. It outlives the process that started it,
-            // so a later command that never opted in would fail for as long as it lives. Ask it
-            // to let go and try again: verikun's own helper must not be why verikun cannot read
-            // the screen. No companion running is the normal case and costs one refused connect.
-            if (attempt === 0)
+            if (attempt === 0) {
+                // A sleeping display is the other documented cause of a failed read, so it is checked
+                // here, lazily, where it costs nothing until something has already gone wrong.
+                this.wakeIfAsleep();
+                // A companion holds the device's ONE UiAutomation connection and SIGKILLs anything
+                // else that wants it — including this dump. It outlives the process that started it,
+                // so a later command that never opted in would fail for as long as it lives. Ask it
+                // to let go and try again: verikun's own helper must not be why verikun cannot read
+                // the screen. No companion running is the normal case and costs one refused connect.
                 (0, manager_1.releaseCompanionOn)(this.resolvedSerial());
+            }
         }
         throw new errors_1.CliError(`Failed to capture UI hierarchy after 3 attempts. ${lastErr}\n` +
-            'Tip: disable animations (`verikun doctor --fix`) and ensure the screen is idle.', 3);
+            'Tip: prepare the device once with `verikun device prep` (disables animations, keeps the ' +
+            'display awake) and ensure the screen is idle.', 3);
     }
     screenshot() {
         const r = (0, exec_1.runBinary)(ADB, this.withSerial(['exec-out', 'screencap', '-p']));
@@ -864,6 +1043,14 @@ class AdbDriver {
     }
     getDeviceSetting(key) {
         switch (key) {
+            case 'animations': {
+                // Three separate scales, one knob: any of them still animating is enough to make a
+                // dump flaky, so `off` means all three are zero and anything else reads as `on`.
+                const vals = ANIMATION_SCALES.map((k) => this.readSetting('global', k));
+                if (vals.some((v) => v === null))
+                    return null;
+                return vals.every((v) => Number(v) === 0) ? 'off' : 'on';
+            }
             case 'airplane':
                 return this.readSetting('global', 'airplane_mode_on') === '1' ? 'on' : 'off';
             case 'dark': {
@@ -896,10 +1083,44 @@ class AdbDriver {
                 const v = this.readSetting('global', 'stay_on_while_plugged_in');
                 return v === null ? 'off' : v !== '0' ? 'on' : 'off';
             }
+            case 'screen-timeout':
+                // Unset is not a meaningful default here (unlike font_scale, whose absence means
+                // 1.0) — the device always has one. Report null so a snapshot declines rather than
+                // restoring to a number we invented.
+                return this.readSetting('system', 'screen_off_timeout');
+            case 'dnd': {
+                // zen_mode: 0 = off, 1 = priority only, 2 = total silence, 3 = alarms only. Our
+                // on|off domain only claims "is anything suppressing notifications", so any
+                // non-zero mode is `on` — and `set` below picks one specific mode to turn it on.
+                const v = this.readSetting('global', 'zen_mode');
+                return v === null ? 'off' : v !== '0' ? 'on' : 'off';
+            }
+            case 'doze': {
+                // `dumpsys deviceidle enabled` prints a bare 1/0. Note this is whether the idle
+                // MANAGER is enabled, not the momentary idle state (`get deep`, which reports
+                // ACTIVE/IDLE and swings on its own) — only the former is a setting we can hold.
+                const v = this.shell(['dumpsys', 'deviceidle', 'enabled']).trim();
+                if (v === '1')
+                    return 'on';
+                if (v === '0')
+                    return 'off';
+                return null;
+            }
         }
     }
     setDeviceSetting(key, value) {
         switch (key) {
+            case 'animations':
+                return this.applyAndVerify(`animations=${value}`, () => {
+                    // One shell per scale, but only the LAST result is reported — every write here
+                    // is the same command against the same namespace, so a failure looks identical
+                    // whichever of the three refused, and the readback below is the real contract.
+                    let last;
+                    for (const k of ANIMATION_SCALES) {
+                        last = this.shellFull(['settings', 'put', 'global', k, value === 'on' ? '1' : '0']);
+                    }
+                    return last;
+                }, () => this.getDeviceSetting('animations'), (v) => v === value, 'Writing global settings requires an unrestricted adb shell.');
             case 'airplane':
                 return this.setAirplane(value === 'on');
             case 'dark':
@@ -910,6 +1131,16 @@ class AdbDriver {
                 return this.setRotation(value);
             case 'stay-awake':
                 return this.applyAndVerify(`stay-awake=${value}`, () => this.shellFull(['svc', 'power', 'stayon', value === 'on' ? 'true' : 'false']), () => this.getDeviceSetting('stay-awake'), (v) => v === value, 'Some devices restrict `svc power` while a battery-saver profile is active.');
+            case 'screen-timeout':
+                return this.applyAndVerify(`screen-timeout=${value}`, () => this.shellFull(['settings', 'put', 'system', 'screen_off_timeout', value]), () => this.getDeviceSetting('screen-timeout'), (v) => v === value, 'Writing system settings requires an unrestricted adb shell.');
+            case 'dnd':
+                // `priority` rather than `on`/`none`: total silence also suppresses ALARMS, which
+                // would be a surprising thing for a testing tool to leave on a borrowed phone.
+                // Priority-only is enough to stop a heads-up notification stealing a tap.
+                return this.applyAndVerify(`dnd=${value}`, () => this.shellFull(['cmd', 'notification', 'set_dnd', value === 'on' ? 'priority' : 'off']), () => this.getDeviceSetting('dnd'), (v) => v === value, 'Setting Do Not Disturb needs `cmd notification` (API 28+); some OEM skins gate it behind ' +
+                    'notification-policy access.');
+            case 'doze':
+                return this.applyAndVerify(`doze=${value}`, () => this.shellFull(['dumpsys', 'deviceidle', value === 'on' ? 'enable' : 'disable']), () => this.getDeviceSetting('doze'), (v) => v === value, '`dumpsys deviceidle` is refused on some locked-down builds.');
         }
     }
     /**
@@ -961,5 +1192,66 @@ class AdbDriver {
         const target = String((0, settings_1.rotationToUserRotation)(value));
         this.applyAndVerify(`rotation=${value}`, () => this.shellFull(['settings', 'put', 'system', 'user_rotation', target]), () => this.readSetting('system', 'user_rotation'), (v) => v === target, 'Writing system settings requires an unrestricted adb shell.');
     }
+    // --- screen + lock state --------------------------------------------------
+    /** Best-effort, never throws: this sits on the READ path, and a probe that could fail
+     *  a dump would be worse than the hang it exists to prevent. */
+    screenState() {
+        return { awake: this.readWakefulness(), lock: this.readLockKind() };
+    }
+    readWakefulness() {
+        try {
+            const m = /mWakefulness=(\w+)/.exec(this.shell(['dumpsys', 'power']));
+            return m ? m[1].toLowerCase() === 'awake' : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readLockKind() {
+        try {
+            return parseLockKind(this.shell(['dumpsys', 'lock_settings']));
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /** Wake the display and clear a non-secure keyguard, then let the screen settle. Never
+     *  throws — deciding whether the result is good enough is `getElements`' job. */
+    wakeAndUnlock() {
+        this.pressKey('wakeup');
+        (0, exec_1.sleepSync)(WAKE_SETTLE_MS);
+        this.dismissKeyguard();
+        (0, exec_1.sleepSync)(WAKE_SETTLE_MS);
+    }
+    /** Only ever clears a SWIPE lock. On a secure keyguard `wm dismiss-keyguard` raises the
+     *  credential prompt instead, which is why callers must check `lock` first. */
+    dismissKeyguard() {
+        try {
+            this.shell(['wm', 'dismiss-keyguard']);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Wake a sleeping display before retrying a dump that already failed.
+     *
+     * Best-effort and never throws: refusing is `getElements`' job, which owns the ONE decision
+     * about whether we are looking at the app or the keyguard. This only handles the narrower
+     * case where the stock dump genuinely could not read a sleeping screen at all.
+     *
+     * Called lazily, after the first attempt has failed, so the happy path pays nothing — an
+     * extra `dumpsys power` on every read would tax every command in the CLI to help the rare one.
+     */
+    wakeIfAsleep() {
+        // `null` means the probe could not tell. Do nothing — the dump may well be failing for an
+        // unrelated reason, and pressing wakeup at random is not a fix.
+        if (this.screenState().awake !== false)
+            return;
+        (0, output_1.err)('note: the display was asleep — waking it before retrying the read');
+        this.pressKey('wakeup');
+        (0, exec_1.sleepSync)(WAKE_SETTLE_MS);
+    }
 }
 exports.AdbDriver = AdbDriver;

package/dist/drivers/ios.js

@@ -635,9 +635,13 @@ class IdbDriver {
                     const scale = (0, settings_1.contentSizeToFontScale)(this.simctlUi('content_size'));
                     return scale === null ? null : (0, settings_1.canonicalFontScale)(scale);
                 }
+                case 'animations':
                 case 'airplane':
                 case 'rotation':
                 case 'stay-awake':
+                case 'screen-timeout':
+                case 'dnd':
+                case 'doze':
                     return null;
             }
         }
@@ -674,6 +678,22 @@ class IdbDriver {
             case 'rotation':
                 return this.unsupportedSetting(key, 'Neither `simctl ui` (appearance/content_size/increase_contrast only) nor `idb ui` ' +
                     'exposes orientation. Rotate the Simulator window by hand (Cmd+Left / Cmd+Right).');
+            case 'screen-timeout':
+                // Same honest no-op as stay-awake, and for the same reason.
+                this.assertSimulator(key);
+                (0, output_1.err)('note: screen-timeout is a no-op on iOS — simulators do not sleep');
+                return;
+            case 'doze':
+                this.assertSimulator(key);
+                (0, output_1.err)('note: doze is a no-op on iOS — there is no Doze equivalent to turn off');
+                return;
+            case 'dnd':
+                return this.unsupportedSetting(key, '`simctl ui` exposes only appearance/content_size/increase_contrast, and neither it nor ' +
+                    '`idb` can reach Focus. Turn it on inside the simulator: Settings > Focus > Do Not Disturb.');
+            case 'animations':
+                return this.unsupportedSetting(key, 'Neither `simctl` nor `idb` can disable UIKit animation. The Simulator menu offers only ' +
+                    'Debug > Slow Animations, which is the opposite of what a test wants — rely on selector ' +
+                    'auto-wait, which polls until the screen settles.');
         }
     }
 }

package/dist/run.js

@@ -40,8 +40,10 @@ function isRecordable(command, positionals = []) {
     // the environment the app runs in and belong in the report, while `get`/`caps` are
     // pure inspection — recording those would auto-start a test run just for asking what
     // the device supports, exactly the noise `ui`/`find` are excluded to avoid.
+    // `prep` joins set/reset: it changes the device the app runs on, and a report showing a
+    // flaky read without "we turned animations off mid-suite" would be missing the cause.
     if (command === 'device')
-        return ['set', 'reset'].includes((positionals[0] ?? '').toLowerCase());
+        return ['set', 'reset', 'prep'].includes((positionals[0] ?? '').toLowerCase());
     return RECORDABLE.has(command);
 }
 const HIERARCHY_CAP = 24000; // chars of failure hierarchy kept inline in run.json

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.23.0';
+exports.VERSION = '0.24.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",