verikun 0.18.1 → 0.19.0

package/README.md

@@ -95,6 +95,16 @@ vk screenshot                   # -> ./.verikun/screen.png
 | `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS unsupported: there is no per-app data reset. |
 | `install <app.apk\|.ipa> [--server url]` | Install a build on the device (`adb install -r` / `idb install`). With `--server`, the file is uploaded to a remote [`vk server`](#remote-devices--vk-server) started with `--allow-install` (single-file `.apk`/`.ipa`, sha256-verified). |
 
+### Device state
+| Command | Description |
+|---|---|
+| `device set <key>=<value> …` | Change the *device* the app runs on, snapshotting each original first. Keys: `airplane`, `dark`, `font-scale`, `rotation`, `stay-awake`. Every change is **verified by reading it back** — `svc`/`cmd`/`settings put` are fire-and-forget and silently no-op on some OEM skins, so trusting the exit code would report success for a change that never happened. Refuses `airplane=on` over a wireless adb link (it would cut the connection carrying the next command); `--allow-wireless` overrides. |
+| `device get [key] [--json]` | Current values; `n/a` where the platform can't answer. |
+| `device reset [key …]` | Restore what this run changed. `batch`, `ai` and `suite` also do this automatically when the flow ends **or fails**, so a dead test can't leave your phone offline or rotated. |
+| `device caps [--json]` | What the active platform supports, and the manual equivalent where it doesn't. |
+
+See [Device state](#device-state-1) for the per-platform matrix.
+
 ### Batch
 | Command | Description |
 |---|---|
@@ -608,6 +618,58 @@ at runtime, so driving a flow to a report should capture liberally around transi
 `vk ai` does this automatically (see [AI](#ai--natural-language-tests)); when driving by
 hand, `vk screenshot` around each screen change and leave the PNG in the report.
 
+## Device state
+
+Some behaviour only appears when the *device* changes underneath the app: the offline
+banner, the retry path, dark theme, a layout that breaks at accessibility text sizes,
+landscape. `vk device set` changes those, verifies each one landed, and — this is the part
+that makes it safe to point at your own phone — **puts them back**.
+
+```sh
+vk device set airplane=on                              # go offline
+vk tap @retry
+vk assert text:"No connection"
+vk device reset                                        # back online
+
+vk device set dark=on font-scale=1.3 rotation=landscape  # several at once
+vk device get --json
+vk device caps                                         # what this platform supports
+```
+
+| key | values | Android | iOS simulator | iOS device |
+|---|---|---|---|---|
+| `airplane` | `on\|off` | ✅ | ❌ no radio to switch off | ❌ |
+| `dark` | `on\|off` | ✅ | ✅ | ❌ |
+| `font-scale` | `0.5`–`3.0`, or `default` | ✅ | ✅ mapped to the nearest Dynamic Type category | ❌ |
+| `rotation` | `portrait\|landscape\|portrait-reverse\|landscape-reverse\|auto` | ✅ | ❌ neither simctl nor idb rotates | ❌ |
+| `stay-awake` | `on\|off` | ✅ | ⊘ no-op — simulators don't sleep | ❌ |
+
+An unsupported key exits **3 before any device I/O**, naming the manual equivalent, so a
+test asking for something the platform can't do fails on the first step rather than
+half-way through a half-modified device. `vk device caps --json` is the same matrix for
+whatever platform you're pointed at.
+
+**Restore is the point.** `device set` records what each setting held *before* it changed
+it, in the run file rather than in memory — so `vk device reset` works from a later process
+too. `batch`, `ai` and `suite` restore automatically in a `finally`, which is what stops a
+test that dies between `airplane=on` and `airplane=off` from leaving your phone offline.
+A bare `vk device set` from your shell stays applied until you reset it, deliberately.
+
+Three things worth knowing:
+
+- **`airplane=on` is verified by effect, not by the flag.** Android remembers a user who
+  re-enabled wifi during a previous flight, so `airplane-mode enable` can leave wifi *up*.
+  `vk` reads the device's own `airplane_mode_toggleable_radios` — the radios that can
+  survive the flag — confirms each actually went down, and forces any survivor. Reporting
+  "offline" while the app is still online would make an offline test pass for the wrong
+  reason. (Cellular is not in that list, and `mobile_data` is a stored preference rather
+  than live radio state, so it is deliberately not probed.)
+- **`airplane=off` re-enables the radio, not the internet.** Follow it with
+  `vk assert <selector> --wait 10s` rather than tapping straight away.
+- **Wireless adb is refused for `airplane=on`.** It would cut the very link carrying the
+  next command, and nothing could turn it back on remotely. Exit 2; `--allow-wireless` if
+  you mean it.
+
 ## How it works
 
 ```
@@ -658,6 +720,10 @@ your setup with `vk doctor --ios`. `vk --ios tap`, `vk --ios ui`, etc. then work
 - `log` capture is simulator-only (via `log show`); for a physical device use
   Console.app or `idb log` directly.
 - `--tree` renders flat — idb's accessibility list has no nesting depth.
+- `device set` is partial: `dark` and `font-scale` work on a **simulator** (`simctl ui`),
+  `stay-awake` is a no-op (simulators don't sleep), and `airplane`/`rotation` are
+  unsupported — neither `simctl ui` nor `idb ui` exposes a radio or an orientation.
+  A physical device supports none of them. Run `vk device caps --ios` for the live matrix.
 
 ## Using it from an AI agent
 

package/dist/agent/grammar.js

@@ -28,6 +28,20 @@ Each step is one of three node types:
      assert <selector> [--text <s>] [--gone]       — assert presence/text/absence (FAILS the test if false)
      wait <selector> [--gone] [--timeout <ms>]     — block until present/absent
      screenshot                   — capture the screen into the report
+     device <set|get|reset|caps>  — change the DEVICE (not the app) to test how the app
+                                  copes. The command name is EXACTLY "device"; the
+                                  subcommand is the FIRST POSITIONAL, never part of the
+                                  command name. Each assignment is one positional:
+                                    {"command":"device","positionals":["set","dark=on","font-scale=1.3"]}
+                                    {"command":"device","positionals":["reset"]}
+                                  Keys: airplane=on|off (go offline — for retry/error
+                                  handling), dark=on|off, font-scale=<0.5-3.0>,
+                                  rotation=portrait|landscape|portrait-reverse|
+                                  landscape-reverse|auto, stay-awake=on|off.
+                                  ALWAYS finish the scenario with a "reset" step. Do NOT
+                                  tap immediately after airplane=off — the radio is back
+                                  but the network is not; follow it with a wait/assert.
+                                  Android only for airplane + rotation.
 
 2. IF-PRESENT — { "type":"if-present", "selector":<sel>, "body":[<command leaves>] }
    Run body ONLY if the selector is on screen now. Use for OPTIONAL interstitials:

package/dist/agent/ir.js

@@ -23,6 +23,8 @@ exports.bodiesOf = bodiesOf;
 exports.validateNode = validateNode;
 exports.parsePlan = parsePlan;
 exports.leafToFlags = leafToFlags;
+const errors_1 = require("../errors");
+const settings_1 = require("../device/settings");
 /** Max control-node nesting. 1 = a control node at top level whose body is leaves
  *  (the v1 rule). 2 = a control node inside that body, whose own body is leaves —
  *  i.e. `repeat { when { … } }`, the loop-that-branches shape a real dynamic flow
@@ -50,6 +52,7 @@ exports.KNOWN_COMMANDS = new Set([
     'screenshot', 'shot',
     'wait', 'assert',
     'launch', 'open', 'stop', 'clear',
+    'device',
     // Inspection/diagnostic commands (`current`, `ui`, `find`, `log`, `logs`) are
     // deliberately NOT here: they are not test actions (the grammar never offers them), so
     // a plan or repair must never emit them — and `log`'s flags reach a device shell
@@ -253,6 +256,47 @@ const READ_FIELDS = new Set(['text', 'desc', 'id', 'idShort']);
 /** ctx keys are interpolated into selectors as {{ctx.NAME}}; keep them boring so a
  *  name can never smuggle regex/template metacharacters into a selector. */
 const CTX_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Fold `{command: "device set"}` back into `{command: "device", positionals: ["set", …]}`.
+ *
+ * `device` is the only verb in the grammar with a subcommand, and every other one is a
+ * single word — so the model reliably writes the pair as one command name. That is an
+ * unambiguous spelling of a REAL command, not a hallucination, so normalizing it is the
+ * same kind of leniency as the `click`/`tap` aliases rather than a hole in the
+ * allowlist: an unknown subcommand still falls through and is rejected below.
+ */
+function normalizeLeaf(command, positionals) {
+    const m = /^device[\s:_-]+(set|get|reset|caps)$/i.exec(command.trim());
+    return m ? { command: 'device', positionals: [m[1].toLowerCase(), ...positionals] } : { command, positionals };
+}
+/**
+ * Check a `device` leaf's subcommand and assignments at PLAN-VALIDATION time.
+ *
+ * Every other command is validated only by name, because a bad selector is a runtime
+ * fact the engine can heal. A device setting is different: whether it exists, and
+ * whether the value is legal, are known statically — so catching it here means a
+ * suite that asks for an unknown key fails before the first tap instead of twenty
+ * steps in, on a device it has already half-modified.
+ */
+function validateDeviceStep(positionals, where) {
+    const sub = (positionals[0] ?? '').toLowerCase();
+    if (!['set', 'get', 'reset', 'caps'].includes(sub)) {
+        throw new InvalidPlanError(`${where}: device subcommand must be set|get|reset|caps, got ${JSON.stringify(sub)}`);
+    }
+    const rest = positionals.slice(1);
+    try {
+        if (sub === 'set')
+            (0, settings_1.parseDeviceAssignments)(rest);
+        else
+            for (const k of rest) {
+                if (!(0, settings_1.isSettingKey)(k.trim().toLowerCase()))
+                    throw new errors_1.CliError(`unknown device setting '${k}'`, 2);
+            }
+    }
+    catch (e) {
+        throw new InvalidPlanError(`${where}: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}`);
+    }
+}
 /** Validate a single node (used for both compile output and a spliced repair).
  *
  *  `depth` is how many control nodes enclose this one. It is the ONLY thing bounding
@@ -294,15 +338,20 @@ function validateNode(node, where, depth = 0) {
     const optional = (v, pick) => v === undefined || v === null ? undefined : pick(v);
     switch (n.type) {
         case 'command': {
-            if (typeof n.command !== 'string' || !exports.KNOWN_COMMANDS.has(n.command)) {
+            if (typeof n.command !== 'string')
                 throw new InvalidPlanError(`${where}: unknown command ${JSON.stringify(n.command)}`);
-            }
             if (!Array.isArray(n.positionals) || !n.positionals.every((p) => typeof p === 'string')) {
                 throw new InvalidPlanError(`${where}: positionals must be a string[]`);
             }
+            const { command, positionals } = normalizeLeaf(n.command, n.positionals);
+            if (!exports.KNOWN_COMMANDS.has(command)) {
+                throw new InvalidPlanError(`${where}: unknown command ${JSON.stringify(n.command)}`);
+            }
             if (!isFlagSpecArray(n.flags))
                 throw new InvalidPlanError(`${where}: flags must be {name,value}[]`);
-            return { type: 'command', command: n.command, positionals: n.positionals, flags: n.flags };
+            if (command === 'device')
+                validateDeviceStep(positionals, where);
+            return { type: 'command', command, positionals, flags: n.flags };
         }
         case 'read': {
             const selector = selectorOf();

package/dist/args.js

@@ -58,6 +58,7 @@ const BOOLEAN = new Set([
     'not-selected',
     'not-checked',
     'not-focused',
+    'allow-wireless',
 ]);
 function parseArgs(argv) {
     const positionals = [];

package/dist/cli.js

@@ -59,6 +59,8 @@ const args_1 = require("./args");
 const errors_1 = require("./errors");
 const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
+const adb_1 = require("./drivers/adb");
+const settings_1 = require("./device/settings");
 const selector_1 = require("./ui/selector");
 const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
@@ -924,6 +926,194 @@ function cmdClear(ctx) {
         (0, output_1.out)(`cleared ${appId}`);
     return 0;
 }
+// ---------------------------------------------------------------------------
+// device — control the device the app runs on (see device/settings.ts)
+// ---------------------------------------------------------------------------
+//
+// The capability table is the single source of truth: it validates values, decides
+// what each platform supports, and prints itself via `device caps`. Two properties
+// are load-bearing:
+//
+//  - FAIL EARLY. Every assignment is parsed and capability-checked before ANY device
+//    I/O, so `device set dark=on rotation=landscape` on iOS refuses up front instead
+//    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\n' +
+    `Keys: ${settings_1.SETTING_KEYS.join(', ')}`;
+function cmdDevice(ctx) {
+    const sub = (ctx.positionals[0] ?? '').toLowerCase();
+    const rest = ctx.positionals.slice(1);
+    switch (sub) {
+        case 'set':
+            return deviceSet(ctx, rest);
+        case 'get':
+        case 'status':
+            return deviceGet(ctx, rest);
+        case 'reset':
+            return deviceReset(ctx, rest);
+        case 'caps':
+            return deviceCaps(ctx);
+        default:
+            throw new errors_1.CliError((sub ? `Unknown 'device' subcommand '${sub}'.\n` : '') + DEVICE_USAGE, 2);
+    }
+}
+/** Render a setting value for humans/JSON; a platform that cannot answer says so. */
+const showValue = (v) => v ?? 'n/a';
+function deviceSet(ctx, args) {
+    const assignments = (0, settings_1.parseDeviceAssignments)(args);
+    // Gate 1: capability, for EVERY key, before touching the device.
+    const support = new Map();
+    for (const { key } of assignments)
+        support.set(key, (0, settings_1.checkSupport)(key, ctx.platform));
+    // Gate 2: would this cut the wire we are talking over? Only wireless adb is at
+    // risk, and only from the radios. A stderr warning would be useless here — the
+    // command that reads it is the one that just lost its transport — so refuse, and
+    // require an explicit opt-in to accept losing the link.
+    if (ctx.platform === 'android') {
+        const transport = (0, adb_1.adbTransport)(ctx.driver.resolvedSerial());
+        for (const { key, value } of assignments) {
+            if ((0, adb_1.severanceRisk)(transport, key, value) && !(0, args_1.flagBool)(ctx.flags, 'allow-wireless')) {
+                throw new errors_1.CliError(`Refusing to set ${key}=${value} over a wireless adb connection (${ctx.driver.resolvedSerial()}): ` +
+                    'it would cut the link carrying this session, and nothing could turn it back on remotely.\n' +
+                    'Connect over USB, or pass --allow-wireless to accept losing the connection.', 2);
+            }
+        }
+    }
+    const applied = {};
+    for (const { key, value } of assignments) {
+        // A no-op key has nothing to put back, so it is never snapshotted.
+        if (support.get(key) !== 'noop')
+            snapshotSetting(ctx, key);
+        ctx.driver.setDeviceSetting(key, value);
+        applied[key] = value;
+    }
+    const summary = assignments.map((a) => `${a.key}=${a.value}`).join(' ');
+    ctx.record?.note({ message: `device set ${summary}` });
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)({ set: applied });
+    else
+        (0, output_1.out)(`device set ${summary}`);
+    return 0;
+}
+/** Persist what a setting held before we change it. Warns rather than fails when the
+ *  value can't be captured — the change still happens, it just can't be auto-undone. */
+function snapshotSetting(ctx, key) {
+    if (!ctx.record) {
+        // Recording disabled (VERIKUN_NO_RUN=1): there is nowhere to persist the original,
+        // so this change is one-way. Say so rather than implying reset will handle it.
+        (0, output_1.err)(`warning: run recording is off, so '${key}' was not snapshotted — \`device reset\` cannot restore it`);
+        return;
+    }
+    const original = ctx.driver.getDeviceSetting(key);
+    if (original === null) {
+        (0, output_1.err)(`warning: could not read the current '${key}' — \`device reset\` will not restore it`);
+        return;
+    }
+    ctx.record.rememberDeviceOverride(key, original);
+}
+function deviceGet(ctx, args) {
+    const keys = args.length ? args.map(requireSettingKey) : settings_1.SETTING_KEYS;
+    const values = {};
+    for (const key of keys) {
+        values[key] = settings_1.SETTINGS[key].support[ctx.platform] === 'unsupported'
+            ? 'n/a'
+            : showValue(ctx.driver.getDeviceSetting(key));
+    }
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)(values);
+    else
+        for (const key of keys)
+            (0, output_1.out)(`${key.padEnd(12)} ${values[key]}`);
+    return 0;
+}
+function deviceReset(ctx, args) {
+    // Read from the recorder's in-flight state, not from disk: this step's own commit()
+    // will write that state back, so a disk-level delete here would be undone.
+    const overrides = ctx.record?.deviceOverrides() ?? {};
+    const wanted = args.length ? args.map(requireSettingKey) : Object.keys(overrides);
+    const restored = {};
+    const failed = [];
+    for (const key of wanted) {
+        const original = overrides[key];
+        if (original === undefined)
+            continue; // never changed by this run — leave it alone
+        try {
+            ctx.driver.setDeviceSetting(key, original);
+            restored[key] = original;
+        }
+        catch (e) {
+            // Best-effort by design: reset is usually reached while cleaning up after a
+            // failure, and one stubborn setting must not stop the rest being put back.
+            failed.push(`${key} (${e instanceof Error ? e.message.split('\n')[0] : String(e)})`);
+        }
+    }
+    ctx.record?.forgetDeviceOverrides(Object.keys(restored));
+    const summary = Object.entries(restored).map(([k, v]) => `${k}=${v}`).join(' ');
+    ctx.record?.note({ message: summary ? `device reset ${summary}` : 'device reset (nothing to restore)' });
+    if (failed.length)
+        (0, output_1.err)(`warning: could not restore ${failed.join(', ')}`);
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)({ restored, ...(failed.length ? { failed } : {}) });
+    else
+        (0, output_1.out)(summary ? `device reset ${summary}` : 'device reset: nothing to restore');
+    return 0;
+}
+function deviceCaps(ctx) {
+    const rows = settings_1.SETTING_KEYS.map((key) => {
+        const spec = settings_1.SETTINGS[key];
+        const support = spec.support[ctx.platform];
+        return {
+            key,
+            values: spec.values,
+            support,
+            describe: spec.describe,
+            ...(support === 'unsupported' && spec.manual[ctx.platform] ? { manual: spec.manual[ctx.platform] } : {}),
+            ...(spec.note[ctx.platform] ? { note: spec.note[ctx.platform] } : {}),
+        };
+    });
+    if ((0, args_1.flagBool)(ctx.flags, 'json')) {
+        (0, output_1.json)({ platform: ctx.platform, settings: rows });
+        return 0;
+    }
+    (0, output_1.out)(`device settings on ${ctx.platform}:`);
+    for (const r of rows) {
+        (0, output_1.out)(`  ${r.key.padEnd(12)} ${r.support.padEnd(12)} ${r.values}`);
+        (0, output_1.out)(`  ${' '.repeat(12)} ${r.describe}`);
+        if (r.manual)
+            (0, output_1.out)(`  ${' '.repeat(12)} unsupported: ${r.manual.replace(/\n/g, ' ')}`);
+        if (r.note)
+            (0, output_1.out)(`  ${' '.repeat(12)} note: ${r.note}`);
+    }
+    return 0;
+}
+function requireSettingKey(v) {
+    const k = v.trim().toLowerCase();
+    if (!(0, settings_1.isSettingKey)(k)) {
+        throw new errors_1.CliError(`Unknown device setting '${v}'. Known: ${settings_1.SETTING_KEYS.join(', ')}.`, 2);
+    }
+    return k;
+}
+/**
+ * Put back every device setting this run changed. Best-effort and silent about
+ * "nothing to do", because it runs from a `finally` — the flow may well be unwinding
+ * from the very failure that left the device in a modified state.
+ *
+ * Runs through the backend rather than a Driver so the local and remote paths are the
+ * 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.)
+ */
+async function restoreDeviceOverrides(backend) {
+    if (!run_1.Recorder.hasDeviceOverrides())
+        return;
+    try {
+        (0, output_1.err)('[verikun] restoring device settings changed by this run…');
+        await backend.exec('device', ['reset'], {});
+    }
+    catch {
+        /* the device may be exactly why we are unwinding — never mask the real error */
+    }
+}
 function cmdCurrent(ctx) {
     (0, output_1.out)(ctx.driver.currentApp());
     return 0;
@@ -1144,31 +1334,46 @@ async function cmdBatch(positionals, batchFlags) {
         (0, output_1.err)('[verikun] batch: no commands to run');
         return 0;
     }
-    for (const { n, text } of commands) {
-        let code;
-        try {
-            const { command, positionals: pos, flags } = (0, args_1.parseArgs)(tokenizeLine(text));
-            if (!command)
-                continue; // tokens were all flags — nothing to run
-            if (command === 'batch') {
-                throw new errors_1.CliError(`batch: a batch line may not itself be 'batch' (line ${n})`, 2);
+    // The finally is what makes `device set` safe to use in a batch: a line that fails
+    // (or a ^C) still puts the device back, instead of leaving it offline or rotated.
+    try {
+        for (const { n, text } of commands) {
+            let code;
+            try {
+                const { command, positionals: pos, flags } = (0, args_1.parseArgs)(tokenizeLine(text));
+                if (!command)
+                    continue; // tokens were all flags — nothing to run
+                if (command === 'batch') {
+                    throw new errors_1.CliError(`batch: a batch line may not itself be 'batch' (line ${n})`, 2);
+                }
+                if (!quiet)
+                    (0, output_1.err)(`[verikun] batch ${n}: ${text}`);
+                code = await executeParsed(command, pos, withBatchGlobals(flags, batchFlags));
+            }
+            catch (e) {
+                // A malformed line (bad quoting, nested batch) is itself an error to halt on.
+                code = mapError(e, batchFlags);
+            }
+            if (code !== 0) {
+                (0, output_1.err)(`[verikun] batch stopped at line ${n} (\`${text}\`) — exit ${code}`);
+                return code;
             }
-            if (!quiet)
-                (0, output_1.err)(`[verikun] batch ${n}: ${text}`);
-            code = await executeParsed(command, pos, withBatchGlobals(flags, batchFlags));
-        }
-        catch (e) {
-            // A malformed line (bad quoting, nested batch) is itself an error to halt on.
-            code = mapError(e, batchFlags);
         }
-        if (code !== 0) {
-            (0, output_1.err)(`[verikun] batch stopped at line ${n} (\`${text}\`) — exit ${code}`);
-            return code;
+        if (!quiet)
+            (0, output_1.err)(`[verikun] batch: ${commands.length} command(s) ok`);
+        return 0;
+    }
+    finally {
+        if (run_1.Recorder.hasDeviceOverrides()) {
+            (0, output_1.err)('[verikun] restoring device settings changed by this batch…');
+            try {
+                await executeParsed('device', ['reset'], withBatchGlobals({}, batchFlags));
+            }
+            catch {
+                /* the device may be exactly why we are unwinding — never mask the real error */
+            }
         }
     }
-    if (!quiet)
-        (0, output_1.err)(`[verikun] batch: ${commands.length} command(s) ok`);
-    return 0;
 }
 function parseAiOptions(flags) {
     const model = (0, cost_1.resolveModel)((0, args_1.flagStr)(flags, 'model'));
@@ -1620,6 +1825,9 @@ async function cmdAi(positionals, flags) {
         result = await runAiTest(file, opts, backend, platform, device);
     }
     finally {
+        // Undo any device setting the test changed, INCLUDING when it failed part-way —
+        // 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
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
@@ -1702,6 +1910,7 @@ async function cmdSuiteEntry(positionals, flags) {
         });
     }
     finally {
+        await restoreDeviceOverrides(backend);
         await backend.close?.();
     }
 }
@@ -1751,6 +1960,8 @@ async function executeCommand(command, ctx) {
             return cmdStop(ctx);
         case 'clear':
             return cmdClear(ctx);
+        case 'device':
+            return cmdDevice(ctx);
         case 'current':
             return cmdCurrent(ctx);
         case 'log':
@@ -1793,7 +2004,7 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
     // Recordable commands open a step (auto-starting an implicit run if needed);
     // the step is finalized with the outcome — and, on failure, screenshot + UI
     // hierarchy of the page are captured — whether the command returns or throws.
-    const recordable = (0, run_1.isRecordable)(command);
+    const recordable = (0, run_1.isRecordable)(command, positionals);
     let driver = sharedDriver;
     let recorder = null;
     try {
@@ -1971,6 +2182,22 @@ ACT
                                       idb install). With --server, uploads the file to a
                                       remote vk server (which must run --allow-install)
 
+DEVICE STATE (change the device the app runs on, then put it back)
+  device set <key>=<value> ...        Apply settings, snapshotting each original first.
+                                      Keys: ${settings_1.SETTING_KEYS.join(', ')}
+                                      e.g. \`device set airplane=on\` to test offline handling,
+                                      \`device set dark=on font-scale=1.3 rotation=landscape\`.
+                                      Each change is verified by reading it back — the
+                                      underlying device commands silently no-op on some skins.
+  device get [key] [--json]           Show current values ('n/a' where unsupported)
+  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 caps [--json]                What this platform supports, and the manual
+                                      equivalent where it doesn't
+                                      Refuses \`airplane=on\` over wireless adb (it would cut
+                                      this very connection); --allow-wireless overrides.
+
 BATCH (script many commands in one process)
   batch [--file path] [--quiet]       Run newline-separated commands — from --file,
                                       else piped stdin — each exactly as its own
@@ -2094,5 +2321,7 @@ EXIT CODES
 
 iOS (--ios): full parity via idb — ui/tap/text/swipe/key + screenshot/launch/stop.
   Needs idb (\`brew install idb-companion\` + \`pip install fb-idb\`); see \`vk doctor --ios\`.
-  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.`;
+  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.
+  \`device set\`: dark + font-scale work on a SIMULATOR (font-scale maps to the nearest
+  Dynamic Type category); airplane and rotation are unsupported — run \`vk device caps --ios\`.`;
 }

package/dist/device/settings.js

@@ -0,0 +1,252 @@
+"use strict";
+// The device-settings capability table — what `vk device set` can change, on which
+// platform, and what a value is allowed to be.
+//
+// This module is DATA plus pure functions, and it is deliberately platform-agnostic:
+// like ui/ and image.ts it never touches adb/xcrun. The table says *what* is supported
+// and *why not*; the drivers know *how*. That split is what lets one place drive all
+// four consumers — argument validation, the driver switch, `vk device caps`, and the
+// `vk ai` plan validator — so a new setting is a table row rather than an edit in five
+// files, and a platform gap can never be documented in one place and forgotten in another.
+//
+// Load-bearing rule: a gap is declared, never silently absorbed. Every 'unsupported'
+// entry carries the MANUAL EQUIVALENT the user should reach for instead, and every
+// 'noop' carries the reason it was unnecessary. A test that believes it went offline
+// while the app is still online is the worst outcome a testing tool can produce, so
+// there is no fourth state that means "we tried".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETTING_KEYS = exports.SETTINGS = exports.ROTATION_VALUES = exports.ROTATION_AUTO = void 0;
+exports.canonicalFontScale = canonicalFontScale;
+exports.rotationToUserRotation = rotationToUserRotation;
+exports.userRotationToRotation = userRotationToRotation;
+exports.fontScaleToContentSize = fontScaleToContentSize;
+exports.contentSizeToFontScale = contentSizeToFontScale;
+exports.isSettingKey = isSettingKey;
+exports.parseDeviceAssignments = parseDeviceAssignments;
+exports.checkSupport = checkSupport;
+const errors_1 = require("../errors");
+// --- value parsers ----------------------------------------------------------
+const ON_OFF_ALIASES = {
+    on: 'on', off: 'off',
+    true: 'on', false: 'off',
+    yes: 'on', no: 'off',
+    enable: 'on', disable: 'off',
+    enabled: 'on', disabled: 'off',
+    '1': 'on', '0': 'off',
+};
+function parseOnOff(key, raw) {
+    const v = ON_OFF_ALIASES[raw.trim().toLowerCase()];
+    if (!v)
+        throw new errors_1.CliError(`Invalid value '${raw}' for '${key}': expected on|off.`, 2);
+    return v;
+}
+// Bounds, not taste: below ~0.5 the UI is unreadable and above ~3.0 Android's own
+// accessibility slider stops, so a stray `font-scale=100` is far likelier to be a typo
+// than an intent — and it would leave the device unusable enough to be hard to undo
+// through the UI. Refuse it here rather than after it has been written.
+const FONT_SCALE_MIN = 0.5;
+const FONT_SCALE_MAX = 3.0;
+/**
+ * Canonical string form of a scale. EVERY path that produces a font-scale value —
+ * parse, the 'default' alias, and the driver's readback — must go through this, or a
+ * write and its verification would compare unequal strings for the same number
+ * ('1.0' vs '1') and report a perfectly good change as refused.
+ */
+function canonicalFontScale(n) {
+    return String(n);
+}
+const FONT_SCALE_DEFAULT = 1.0;
+function parseFontScale(raw) {
+    const t = raw.trim().toLowerCase();
+    if (t === 'default')
+        return canonicalFontScale(FONT_SCALE_DEFAULT);
+    if (!/^\d+(\.\d+)?$/.test(t)) {
+        throw new errors_1.CliError(`Invalid value '${raw}' for 'font-scale': expected a number like 1.3, or 'default'.`, 2);
+    }
+    const n = Number(t);
+    if (n < FONT_SCALE_MIN || n > FONT_SCALE_MAX) {
+        throw new errors_1.CliError(`Invalid value '${raw}' for 'font-scale': must be between ${FONT_SCALE_MIN} and ${FONT_SCALE_MAX}.`, 2);
+    }
+    // Canonicalize so '1.30', '1.3' and '1.300' all snapshot/compare identically.
+    return canonicalFontScale(n);
+}
+/** Android `user_rotation` values, by the name we expose. */
+const ROTATIONS = {
+    portrait: 0,
+    landscape: 1,
+    'portrait-reverse': 2,
+    'landscape-reverse': 3,
+};
+/** Auto-rotate (accelerometer_rotation=1), where no fixed orientation applies.
+ *  It is a real value rather than a separate key so a snapshot can restore a device
+ *  that was on auto-rotate to auto-rotate, instead of pinning it to whatever
+ *  orientation it happened to be held in when the run started. */
+exports.ROTATION_AUTO = 'auto';
+exports.ROTATION_VALUES = [...Object.keys(ROTATIONS), exports.ROTATION_AUTO];
+function parseRotation(raw) {
+    const t = raw.trim().toLowerCase();
+    // A bare integer is rejected on purpose: `rotation=2` is meaningless to someone
+    // reading the run report, and the number-to-orientation mapping is Android's, not ours.
+    if (t !== exports.ROTATION_AUTO && !(t in ROTATIONS)) {
+        throw new errors_1.CliError(`Invalid value '${raw}' for 'rotation': expected ${exports.ROTATION_VALUES.join('|')}.`, 2);
+    }
+    return t;
+}
+/** The fixed orientation a name pins to. Throws for `auto`, which has no fixed
+ *  value — callers must branch on it before asking. */
+function rotationToUserRotation(name) {
+    const v = ROTATIONS[name.trim().toLowerCase()];
+    if (v === undefined) {
+        throw new errors_1.CliError(`Invalid rotation '${name}': expected ${Object.keys(ROTATIONS).join('|')}.`, 2);
+    }
+    return v;
+}
+function userRotationToRotation(value) {
+    const hit = Object.entries(ROTATIONS).find(([, v]) => String(v) === value.trim());
+    return hit ? hit[0] : null;
+}
+// --- font-scale <-> iOS content size ----------------------------------------
+// iOS takes a named Dynamic Type category where Android takes a float, so the two
+// domains have to be reconciled somewhere. The float is canonical (it is the more
+// precise of the two, and what Android natively stores); iOS maps to the nearest
+// category and the driver echoes which one it applied, so a caller is never guessing.
+//
+// Scales are the real UIKit body point size for each category divided by 17pt (the
+// `large` default), which is what makes 1.0 land exactly on `large` on both platforms.
+const CONTENT_SIZES = [
+    { category: 'extra-small', scale: 0.82 },
+    { category: 'small', scale: 0.88 },
+    { category: 'medium', scale: 0.94 },
+    { category: 'large', scale: 1.0 },
+    { category: 'extra-large', scale: 1.12 },
+    { category: 'extra-extra-large', scale: 1.24 },
+    { category: 'extra-extra-extra-large', scale: 1.35 },
+    { category: 'accessibility-medium', scale: 1.65 },
+    { category: 'accessibility-large', scale: 1.94 },
+    { category: 'accessibility-extra-large', scale: 2.35 },
+    { category: 'accessibility-extra-extra-large', scale: 2.76 },
+    { category: 'accessibility-extra-extra-extra-large', scale: 3.12 },
+];
+/** Nearest Dynamic Type category for a font scale. Clamps rather than throwing —
+ *  the value was already range-checked by parse(), so out-of-table just means the
+ *  extreme end of the scale, not a caller error. */
+function fontScaleToContentSize(scale) {
+    let best = CONTENT_SIZES[0];
+    for (const c of CONTENT_SIZES) {
+        if (Math.abs(c.scale - scale) < Math.abs(best.scale - scale))
+            best = c;
+    }
+    return best.category;
+}
+/** Inverse, for readback. `unknown` / `unsupported` (both real simctl outputs) → null. */
+function contentSizeToFontScale(category) {
+    const hit = CONTENT_SIZES.find((c) => c.category === category.trim().toLowerCase());
+    return hit ? hit.scale : null;
+}
+// --- the table --------------------------------------------------------------
+exports.SETTINGS = {
+    airplane: {
+        key: 'airplane',
+        describe: 'Airplane mode — cut the radios to test offline/retry handling',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('airplane', raw),
+        support: { android: 'supported', ios: 'unsupported' },
+        manual: {
+            ios: 'A simulator has no radio to switch off (`simctl status_bar override --wifiMode failed` ' +
+                'only repaints the status bar). Use Xcode > Open Developer Tool > Network Link Conditioner, ' +
+                "or toggle the host Mac's own network — the simulator shares it.",
+        },
+        note: {},
+    },
+    dark: {
+        key: 'dark',
+        describe: 'Dark mode / night theme',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('dark', raw),
+        support: { android: 'supported', ios: 'supported' },
+        manual: {},
+        note: { ios: 'simulator only — a physical iOS device has no scriptable appearance switch' },
+    },
+    'font-scale': {
+        key: 'font-scale',
+        describe: 'Text scaling factor — catches layout overflow at accessibility sizes',
+        values: "a number 0.5-3.0 (e.g. 1.3), or 'default'",
+        parse: parseFontScale,
+        support: { android: 'supported', ios: 'supported' },
+        manual: {},
+        note: {
+            ios: 'simulator only, and mapped to the nearest Dynamic Type category ' +
+                '(iOS has named sizes, not a float) — the applied category is printed',
+        },
+    },
+    rotation: {
+        key: 'rotation',
+        describe: 'Screen orientation (a fixed value also pins auto-rotate off, so it stays put)',
+        values: exports.ROTATION_VALUES.join('|'),
+        parse: parseRotation,
+        support: { android: 'supported', ios: 'unsupported' },
+        manual: {
+            ios: 'Neither `simctl ui` (appearance/content_size/increase_contrast only) nor `idb ui` ' +
+                'exposes orientation. Rotate the Simulator window by hand (Cmd+Left / Cmd+Right).',
+        },
+        note: {},
+    },
+    'stay-awake': {
+        key: 'stay-awake',
+        describe: 'Keep the screen on while charging — a sleeping display hangs UI hierarchy dumps',
+        values: 'on|off',
+        parse: (raw) => parseOnOff('stay-awake', raw),
+        support: { android: 'supported', ios: 'noop' },
+        manual: {},
+        note: { ios: 'simulators do not sleep, so there is nothing to keep awake' },
+    },
+};
+exports.SETTING_KEYS = Object.keys(exports.SETTINGS);
+function isSettingKey(v) {
+    return Object.prototype.hasOwnProperty.call(exports.SETTINGS, v);
+}
+/**
+ * Parse `key=value` positionals into validated assignments.
+ *
+ * `key=value` rather than `set <key> <value>` so several settings can be established in
+ * one call (each needs its own snapshot entry), and so the `vk ai` compiler model has a
+ * single unambiguous form to emit.
+ */
+function parseDeviceAssignments(positionals) {
+    if (positionals.length === 0) {
+        throw new errors_1.CliError(`Usage: verikun device set <key>=<value> [<key>=<value> ...]\nKeys: ${exports.SETTING_KEYS.join(', ')}`, 2);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const raw of positionals) {
+        const eq = raw.indexOf('=');
+        if (eq <= 0) {
+            throw new errors_1.CliError(`Invalid assignment '${raw}': expected <key>=<value>, e.g. 'dark=on'.`, 2);
+        }
+        const key = raw.slice(0, eq).trim().toLowerCase();
+        const value = raw.slice(eq + 1);
+        if (!isSettingKey(key)) {
+            throw new errors_1.CliError(`Unknown device setting '${key}'. Known: ${exports.SETTING_KEYS.join(', ')}.`, 2);
+        }
+        if (seen.has(key)) {
+            throw new errors_1.CliError(`Duplicate device setting '${key}' — it can only be set once per call.`, 2);
+        }
+        seen.add(key);
+        out.push({ key, value: exports.SETTINGS[key].parse(value) });
+    }
+    return out;
+}
+/**
+ * The capability gate, applied BEFORE any device I/O so an unsupported setting fails on
+ * the first step rather than midway through a flow. Returns the support state so the
+ * caller can print the 'noop' note; throws CliError(…, 3) for 'unsupported'.
+ */
+function checkSupport(key, platform) {
+    const spec = exports.SETTINGS[key];
+    const support = spec.support[platform];
+    if (support === 'unsupported') {
+        const manual = spec.manual[platform];
+        throw new errors_1.CliError(`Device setting '${key}' is not supported on ${platform}.` + (manual ? `\n${manual}` : ''), 3);
+    }
+    return support;
+}

package/dist/drivers/adb.js

@@ -3,10 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdbDriver = void 0;
 exports.probeAdb = probeAdb;
 exports.escapeText = escapeText;
+exports.adbTransport = adbTransport;
+exports.severanceRisk = severanceRisk;
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
 const viewport_1 = require("../ui/viewport");
+const settings_1 = require("../device/settings");
+const output_1 = require("../output");
 const ADB = process.env.ADB || 'adb';
 const ADB_HINT = 'install the Android platform-tools (`brew install --cask android-platform-tools`), or point ADB at the binary';
 /** Is `adb` present and runnable? Shared by `vk doctor` and AdbDriver.preflight() so
@@ -93,6 +97,39 @@ function escapeText(s) {
         // `input` maps the literal token %s back to a space, so encode spaces last.
         .replace(/ /g, '%s');
 }
+/**
+ * Classify a device serial by transport. Exported for the unit suite.
+ *
+ * Load-bearing default: an UNRECOGNIZED shape is `usb`. USB serials are the
+ * open-ended set (any vendor string), while TCP serials have exactly two forms —
+ * `host:port` and Android 11+ wireless-debugging mDNS names. This classifier only
+ * feeds a foot-gun guard, not a security boundary, so the failure we must avoid is
+ * misreading a real USB serial as wireless and blocking a legitimate run.
+ */
+function adbTransport(serial) {
+    const s = serial.trim();
+    // An emulator is reached over a host-local console port, not through the guest's
+    // network stack, so cutting the guest's wifi cannot sever it.
+    if (/^emulator-\d+$/.test(s))
+        return 'emulator';
+    if (/_adb-tls-(connect|pairing)\._tcp\.?$/.test(s))
+        return 'tcp';
+    if (/:\d+$/.test(s))
+        return 'tcp';
+    return 'usb';
+}
+/**
+ * Would applying this setting sever adb's own link to the device? Only cutting the
+ * radios over a wireless transport does: the command would kill the channel carrying
+ * the next command, and nothing could turn it back on remotely.
+ */
+function severanceRisk(transport, key, value) {
+    return transport === 'tcp' && key === 'airplane' && value === 'on';
+}
+/** How long a written setting has to read back before we call it refused. These are
+ *  local writes, so they land in well under a second or not at all. */
+const VERIFY_TIMEOUT_MS = 4000;
+const VERIFY_INTERVAL_MS = 200;
 class AdbDriver {
     platform = 'android';
     requested;
@@ -397,5 +434,145 @@ class AdbDriver {
             return '';
         }
     }
+    // --- device settings ------------------------------------------------------
+    //
+    // Every device token below is a constant (the value domain is a closed enum in
+    // device/settings.ts), so no caller-supplied string reaches the device shell and
+    // no escaping gate is needed. The one non-constant, font-scale's number, has
+    // already been reduced to /^\d+(\.\d+)?$/ by the table's parse().
+    /** Like shell(), but keeps stderr and the exit code — needed because a refusal
+     *  ("Permission denial", "cmd: Can't find service") arrives on stderr and would
+     *  otherwise be invisible in the error we raise. */
+    shellFull(args, timeout) {
+        return (0, exec_1.runText)(ADB, this.withSerial(['shell', ...args]), { timeout });
+    }
+    /** `settings get <ns> <key>`, with Android's literal "null" (unset) mapped to null. */
+    readSetting(ns, key) {
+        const v = this.shell(['settings', 'get', ns, key]).trim();
+        return v === '' || v === 'null' ? null : v;
+    }
+    /** Poll a readback until it satisfies `ok`. Returns the final value (or null). */
+    pollSetting(read, ok) {
+        const deadline = Date.now() + VERIFY_TIMEOUT_MS;
+        let last = read();
+        while (!ok(last) && Date.now() < deadline) {
+            (0, exec_1.sleepSync)(VERIFY_INTERVAL_MS);
+            last = read();
+        }
+        return last;
+    }
+    /** Apply a change, then prove it landed. `svc` / `cmd` / `settings put` are all
+     *  fire-and-forget and are silently ignored on some OEM skins, so the readback is
+     *  the actual contract — without it we would report success for a no-op. */
+    applyAndVerify(what, mutate, read, ok, hint) {
+        const r = mutate();
+        const final = this.pollSetting(read, ok);
+        if (ok(final))
+            return;
+        const why = `${r.stderr}\n${r.stdout}`.replace(/\s+/g, ' ').trim();
+        throw new errors_1.CliError(`Failed to set ${what}: the command ran but the device still reports ${JSON.stringify(final)} ` +
+            `after ${VERIFY_TIMEOUT_MS}ms.` +
+            (why ? `\nDevice said: ${why}` : '') +
+            `\n${hint}`, 3);
+    }
+    getDeviceSetting(key) {
+        switch (key) {
+            case 'airplane':
+                return this.readSetting('global', 'airplane_mode_on') === '1' ? 'on' : 'off';
+            case 'dark': {
+                // `cmd uimode night` prints e.g. "Night mode: no". Some builds also report
+                // "auto"/"custom", which our on|off domain cannot express — report null
+                // rather than guessing, so a snapshot declines to restore it.
+                const out = this.shell(['cmd', 'uimode', 'night']).trim().toLowerCase();
+                if (/\byes\b/.test(out))
+                    return 'on';
+                if (/\bno\b/.test(out))
+                    return 'off';
+                return null;
+            }
+            case 'font-scale': {
+                // Unset means Android's default of 1.0 (the setting row simply doesn't exist
+                // yet). Report the effective value, not the absence, so restore is correct.
+                const raw = this.readSetting('system', 'font_scale');
+                const n = raw === null ? 1.0 : Number(raw);
+                return Number.isFinite(n) ? (0, settings_1.canonicalFontScale)(n) : null;
+            }
+            case 'rotation': {
+                if (this.readSetting('system', 'accelerometer_rotation') === '1')
+                    return settings_1.ROTATION_AUTO;
+                const v = this.readSetting('system', 'user_rotation');
+                return v === null ? null : (0, settings_1.userRotationToRotation)(v);
+            }
+            case 'stay-awake': {
+                // A bitmask of the charging types it applies to (1=AC, 2=USB, 4=wireless);
+                // any non-zero value means "stays on", which is all our on|off domain claims.
+                const v = this.readSetting('global', 'stay_on_while_plugged_in');
+                return v === null ? 'off' : v !== '0' ? 'on' : 'off';
+            }
+        }
+    }
+    setDeviceSetting(key, value) {
+        switch (key) {
+            case 'airplane':
+                return this.setAirplane(value === 'on');
+            case 'dark':
+                return this.applyAndVerify(`dark=${value}`, () => this.shellFull(['cmd', 'uimode', 'night', value === 'on' ? 'yes' : 'no']), () => this.getDeviceSetting('dark'), (v) => v === value, 'Some OEM skins override night mode from their own theme engine.');
+            case 'font-scale':
+                return this.applyAndVerify(`font-scale=${value}`, () => this.shellFull(['settings', 'put', 'system', 'font_scale', value]), () => this.getDeviceSetting('font-scale'), (v) => v === value, 'Writing system settings requires an unrestricted adb shell.');
+            case 'rotation':
+                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.');
+        }
+    }
+    /**
+     * Airplane mode, reconciled against the radios that can actually survive it.
+     *
+     * Android publishes `airplane_mode_toggleable_radios` — the radios a user is allowed
+     * to switch back ON while airplane mode is active (typically `bluetooth,wifi,nfc`) —
+     * and it REMEMBERS that choice. So on a phone where wifi was once re-enabled mid-
+     * flight, `airplane-mode enable` leaves wifi UP. Reporting "offline" while the app is
+     * still online would make an offline test pass for the wrong reason, which is the
+     * worst failure mode a testing tool has. So: flip the flag, then force any toggleable
+     * radio that ignored it.
+     *
+     * Only radios in that list are reconciled. Cellular is not one of them — the flag
+     * cuts it outright — and `mobile_data` is a stored user PREFERENCE rather than live
+     * radio state, so it keeps reading 1 on a SIM-less device that is plainly offline.
+     * Probing it would fail a perfectly good offline state.
+     *
+     * The inverse is symmetric: a radio we forced off by hand will not come back on its
+     * own, so leaving airplane mode re-enables it. That can turn a radio back on that the
+     * user had off before the run, so it is announced on stderr rather than done quietly.
+     */
+    setAirplane(on) {
+        this.applyAndVerify(`airplane=${on ? 'on' : 'off'}`, () => this.shellFull(['cmd', 'connectivity', 'airplane-mode', on ? 'enable' : 'disable']), () => this.readSetting('global', 'airplane_mode_on'), (v) => v === (on ? '1' : '0'), 'Airplane mode is settable via `cmd connectivity` on API 30+; older devices need root.');
+        // Read the toggleable list from the device rather than assuming it — it varies by
+        // build, and a device that does not let wifi survive airplane mode needs no fixup.
+        const toggleable = (this.readSetting('global', 'airplane_mode_toggleable_radios') ?? '')
+            .split(',')
+            .map((s) => s.trim().toLowerCase());
+        if (!toggleable.includes('wifi'))
+            return;
+        // wifi_on is tri-state on some builds (2 = on, pending airplane-mode exit), so ask
+        // "is it off?" rather than comparing against a single expected value.
+        const isOff = (v) => v === null || v === '0';
+        const settled = this.pollSetting(() => this.readSetting('global', 'wifi_on'), (v) => isOff(v) === on);
+        if (isOff(settled) === on)
+            return;
+        (0, output_1.err)(`note: wifi was still ${on ? 'up' : 'down'} after airplane mode ${on ? 'on' : 'off'} — ` +
+            `forcing it ${on ? 'off' : 'on'} so the device state matches the request`);
+        this.applyAndVerify(`wifi ${on ? 'off' : 'on'}`, () => this.shellFull(['svc', 'wifi', on ? 'disable' : 'enable']), () => this.readSetting('global', 'wifi_on'), (v) => isOff(v) === on, '`svc wifi` is refused by some OEM skins; toggle it in Settings instead.');
+    }
+    /** A fixed orientation also pins auto-rotate off, or the accelerometer would
+     *  immediately undo it the moment the device moves. */
+    setRotation(value) {
+        if (value === settings_1.ROTATION_AUTO) {
+            return this.applyAndVerify('rotation=auto', () => this.shellFull(['settings', 'put', 'system', 'accelerometer_rotation', '1']), () => this.readSetting('system', 'accelerometer_rotation'), (v) => v === '1', 'Writing system settings requires an unrestricted adb shell.');
+        }
+        this.applyAndVerify('auto-rotate off', () => this.shellFull(['settings', 'put', 'system', 'accelerometer_rotation', '0']), () => this.readSetting('system', 'accelerometer_rotation'), (v) => v === '0', 'Writing system settings requires an unrestricted adb shell.');
+        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.');
+    }
 }
 exports.AdbDriver = AdbDriver;

package/dist/drivers/ios.js

@@ -11,6 +11,8 @@ const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const ios_parse_1 = require("../ui/ios-parse");
 const viewport_1 = require("../ui/viewport");
+const settings_1 = require("../device/settings");
+const output_1 = require("../output");
 // iOS driver. `xcrun simctl` / `devicectl` cover device discovery and — on a
 // simulator — screenshots, app lifecycle, and logs (no extra install needed).
 // Everything interactive (UI hierarchy, tap, type, swipe, keys, screen size) and
@@ -459,5 +461,90 @@ class IdbDriver {
             return '';
         }
     }
+    // --- device settings ------------------------------------------------------
+    //
+    // Only two of the five keys exist on iOS, and only on a SIMULATOR: `simctl ui`
+    // offers appearance / content_size / increase_contrast and nothing else, while
+    // `idb ui` is purely interaction (tap/text/key/swipe/describe). A physical device
+    // has no scriptable settings surface at all. Rather than fake the gap — a
+    // status-bar override would repaint the wifi glyph without cutting any traffic —
+    // the unsupported keys refuse with exit 3 and name the manual equivalent, the way
+    // clearApp does.
+    /** `simctl ui <udid> <option>` with no argument reads the current value. */
+    simctlUi(option, value) {
+        const args = ['simctl', 'ui', this.udid(), option, ...(value ? [value] : [])];
+        const r = (0, exec_1.runText)(XCRUN, args);
+        if (r.code !== 0) {
+            throw new errors_1.CliError(`simctl ui ${option} failed: ${r.stderr.trim() || `exit code ${r.code}`}`, 3);
+        }
+        return r.stdout.trim();
+    }
+    /** Shared refusal for a key iOS cannot honor. */
+    unsupportedSetting(key, detail) {
+        throw new errors_1.CliError(`Device setting '${key}' is not supported on iOS.\n${detail}`, 3);
+    }
+    assertSimulator(key) {
+        if (!this.isSimulator()) {
+            this.unsupportedSetting(key, 'A physical iOS device exposes no scriptable settings surface (simctl drives simulators ' +
+                'only, and idb covers interaction, not preferences). Change it by hand in Settings.');
+        }
+    }
+    getDeviceSetting(key) {
+        // Best-effort by contract: never throw, so a snapshot of a key this platform
+        // cannot answer simply declines to restore it rather than aborting the run.
+        try {
+            if (!this.isSimulator())
+                return null;
+            switch (key) {
+                case 'dark': {
+                    const v = this.simctlUi('appearance').toLowerCase();
+                    return v === 'dark' ? 'on' : v === 'light' ? 'off' : null;
+                }
+                case 'font-scale': {
+                    // simctl also answers 'unknown' / 'unsupported'; both map to null.
+                    const scale = (0, settings_1.contentSizeToFontScale)(this.simctlUi('content_size'));
+                    return scale === null ? null : (0, settings_1.canonicalFontScale)(scale);
+                }
+                case 'airplane':
+                case 'rotation':
+                case 'stay-awake':
+                    return null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    setDeviceSetting(key, value) {
+        switch (key) {
+            case 'dark': {
+                this.assertSimulator(key);
+                this.simctlUi('appearance', value === 'on' ? 'dark' : 'light');
+                return;
+            }
+            case 'font-scale': {
+                this.assertSimulator(key);
+                // iOS has named Dynamic Type categories where Android has a float, so the
+                // value is mapped — and the category we actually applied is echoed, because
+                // silently landing on a different size than asked for would be a lie.
+                const category = (0, settings_1.fontScaleToContentSize)(Number(value));
+                this.simctlUi('content_size', category);
+                (0, output_1.err)(`note: font-scale ${value} applied on iOS as content size '${category}'`);
+                return;
+            }
+            case 'stay-awake':
+                // Honest no-op: a simulator never sleeps, so the intent is already satisfied.
+                this.assertSimulator(key);
+                (0, output_1.err)('note: stay-awake is a no-op on iOS — simulators do not sleep');
+                return;
+            case 'airplane':
+                return this.unsupportedSetting(key, 'A simulator has no radio to switch off (`simctl status_bar override --wifiMode failed` ' +
+                    'only repaints the status bar). Use Xcode > Open Developer Tool > Network Link ' +
+                    "Conditioner, or toggle the host Mac's own network — the simulator shares it.");
+            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).');
+        }
+    }
 }
 exports.IdbDriver = IdbDriver;

package/dist/exec.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleepSync = sleepSync;
 exports.runText = runText;
 exports.commandExists = commandExists;
 exports.runBinary = runBinary;
@@ -8,6 +9,17 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const errors_1 = require("./errors");
 const MAX_BUFFER = 64 * 1024 * 1024; // screenshots can be a few MB
+/**
+ * Block the calling thread for `ms`. Needed because the Driver interface is entirely
+ * synchronous (every device call is a spawnSync), so a readback poll cannot await a
+ * timer. Uses Atomics.wait on a throwaway SharedArrayBuffer — a Node builtin, keeping
+ * with the zero-runtime-dependency rule, and cheaper than spawning `sleep`.
+ */
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function describeError(cmd, args, err) {
     if (err.code === 'ENOENT') {
         return new errors_1.CliError(`'${cmd}' was not found on PATH. Is it installed and on your PATH?`, 3);

package/dist/run.js

@@ -30,8 +30,17 @@ const RECORDABLE = new Set([
     'wait', 'assert',
     'launch', 'open', 'stop', 'clear',
     'log', 'logs',
+    // `device` changes the environment the app runs in. A report showing "checkout
+    // failed" without "we cut the network two steps earlier" would be misleading.
+    'device',
 ]);
-function isRecordable(command) {
+function isRecordable(command, positionals = []) {
+    // `device` is the one command that is recordable only in part: `set`/`reset` change
+    // 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.
+    if (command === 'device')
+        return ['set', 'reset'].includes((positionals[0] ?? '').toLowerCase());
     return RECORDABLE.has(command);
 }
 const HIERARCHY_CAP = 24000; // chars of failure hierarchy kept inline in run.json
@@ -226,6 +235,10 @@ function stepName(command, positionals, flags) {
         case 'home':
         case 'enter':
             return command;
+        case 'device':
+            // The payload IS the story here — "device set" alone would tell a report
+            // reader nothing about what changed, so keep the whole assignment list.
+            return `device ${p.join(' ')}`.trim();
         default:
             return `${command} ${p[0] ?? ''}`.trim();
     }
@@ -260,9 +273,30 @@ class Recorder {
         const session = currentSession();
         let rolledOver = false;
         // Close a stale / context-mismatched run before continuing.
+        let carriedOverrides;
         if (state) {
             const reason = rolloverReason(state, serial, session);
             if (reason) {
+                // A sealed run takes its deviceOverrides with it, and `device reset` reads the
+                // ACTIVE run — so without this the device silently stays modified and reset
+                // cheerfully reports "nothing to restore". Same device: carry the snapshot into
+                // the fresh run so reset still works. Different device: we cannot drive the old
+                // one from here, so say exactly what was left changed and where.
+                const stranded = state.deviceOverrides ?? {};
+                if (Object.keys(stranded).length > 0) {
+                    // Same predicate as the log-attribution check: "is the device in front of us
+                    // still the one this run was bound to?"
+                    const sameDevice = rolloverLogsSameDevice(state.device, serial);
+                    if (sameDevice) {
+                        carriedOverrides = stranded;
+                    }
+                    else {
+                        const listed = Object.entries(stranded).map(([k, v]) => `${k} (was ${v})`).join(', ');
+                        (0, output_1.err)(`[verikun] WARNING: run for device ${state.device} is being closed while it still has ` +
+                            `device settings applied: ${listed}. That device was NOT restored — put it back with ` +
+                            `\`vk device set ${Object.entries(stranded).map(([k, v]) => `${k}=${v}`).join(' ')} --device ${state.device}\``);
+                    }
+                }
                 try {
                     // Only reuse this step's driver when it still targets the run's device.
                     // A device-change rollover must not write the new device's logcat into
@@ -290,6 +324,9 @@ class Recorder {
                 device: serial || deviceReq,
                 session,
                 implicit: true,
+                // Survives a same-device rollover, so `device reset` can still undo what an
+                // earlier run applied to the device now in front of us.
+                ...(carriedOverrides ? { deviceOverrides: carriedOverrides } : {}),
                 steps: [],
             };
             if (!rolledOver) {
@@ -567,6 +604,42 @@ class Recorder {
     static status() {
         return loadState(activeDir());
     }
+    // --- device overrides ---------------------------------------------------
+    //
+    // These are INSTANCE methods on purpose. A recorder holds the run state in memory
+    // for the duration of a step and writes the whole thing in commit(), so a static
+    // that loaded-mutated-saved the file mid-step would be silently overwritten a
+    // moment later by that commit — the snapshot would vanish and `device reset` would
+    // have nothing to undo. Mutating this.state lets commit() persist it.
+    /**
+     * Record what a device setting held BEFORE this run changed it. Keeps the EARLIEST
+     * original: setting `dark` twice must still restore to the pre-run appearance, not
+     * to the intermediate value.
+     */
+    rememberDeviceOverride(key, original) {
+        this.state.deviceOverrides ??= {};
+        if (!(key in this.state.deviceOverrides))
+            this.state.deviceOverrides[key] = original;
+    }
+    /** The pre-run values of every device setting this run changed. */
+    deviceOverrides() {
+        return this.state.deviceOverrides ?? {};
+    }
+    /** Drop override records once they have been restored (all, or a named subset). */
+    forgetDeviceOverrides(keys) {
+        if (!this.state.deviceOverrides)
+            return;
+        if (keys)
+            for (const k of keys)
+                delete this.state.deviceOverrides[k];
+        else
+            this.state.deviceOverrides = {};
+    }
+    /** Whether the run on disk has anything to restore. Used OUTSIDE a step — by the
+     *  batch/ai/suite teardown deciding whether a `device reset` is worth issuing. */
+    static hasDeviceOverrides() {
+        return Object.keys(Recorder.status()?.deviceOverrides ?? {}).length > 0;
+    }
     /** Merge a patch into the active run (used by `vk ai` to attach its summary
      *  before archiving). No-op if there is no active run. */
     static annotateRun(patch) {

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.18.1';
+exports.VERSION = '0.19.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.18.1",
+  "version": "0.19.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",