verikun 0.11.0 → 0.12.0

package/README.md

@@ -286,16 +286,30 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote devi
 - **Each test is a full `vk ai` run** — plan cache, self-healing, cost budget, and
   its own archived JUnit + HTML report under `./.verikun/runs/<id>/`. A test that
   fails (or errors) doesn't stop the suite; the rest still run.
+- **But a broken *environment* does stop it.** If a test dies from an environment
+  error (exit 3 — tool gone, device unplugged, server unreachable), the toolchain is
+  re-probed; only if it is *still* broken does the suite abort. That re-probe matters:
+  a transient `uiautomator` dump failure also exits 3, and shouldn't vaporize a
+  20-test run. Continuing on a genuinely dead box just produces one identical red row
+  per remaining test — noise that reads exactly like a mass regression.
 - **The suite writes an overview** to `./.verikun/suites/<id>/`:
   - **`index.json`** — a stable, `schemaVersion`ed manifest: per-test pass/fail,
     steps, model repairs, cost, duration, and the run id, plus suite totals. This
     is the **output contract for reporting** — upload/publish steps compose over
     it (see the [CI recipe](#ci-recipe)) instead of verikun growing upload plugins.
-  - **`index.html`** — a summary page linking every test's `report.html`.
-- **Exit code is the CI gate:** `1` if any test failed, `0` all green, `2` bad/empty
-  directory. All `ai` flags (`--model`, `--max-cost-usd`, `--timeout`, …) apply to
-  every test; the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` /
-  `cursor-agent` CLI for `--model codex-cli` / `cursor-cli`) is checked up front.
+    On an abort it also carries `aborted: {reason, notRun}`; the not-run tests get
+    **no rows and no place in `totals`**, so `passed + failed === tests` still holds
+    and nothing downstream mistakes a skipped test for a regression.
+  - **`index.html`** — a summary page linking every test's `report.html`, with a
+    banner naming the not-run tests when the suite aborted.
+- **Exit code is the CI gate:** `0` all green · `1` a test failed · `2` bad/empty
+  directory · `3` environment (the provider or the device toolchain is unavailable,
+  or the box broke mid-run). The `1`-vs-`3` split is the point: `1` is a regression
+  to investigate, `3` is a machine to fix. All `ai` flags (`--model`,
+  `--max-cost-usd`, `--timeout`, …) apply to every test; both the provider
+  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` / `cursor-agent` CLI for
+  `--model codex-cli` / `cursor-cli`) **and** the device toolchain (`adb` / `idb` +
+  a resolvable device) are checked up front, before anything is compiled.
 
 ## Remote devices — `vk server`
 
@@ -435,7 +449,7 @@ condition as a step in its own right.
 | `0` | success / found / assertion passed |
 | `1` | not found / assertion failed / wait timeout |
 | `2` | usage error or ambiguous selector (caller must refine) |
-| `3` | environment error (adb/simctl missing, no/multiple devices, dump failed) |
+| `3` | environment error (adb/idb/simctl missing, no/multiple devices, dump failed). `ai`, `suite`, `install` and `server` verify the toolchain up front, so this arrives immediately with an install hint instead of mid-flow — and a `suite` whose device dies mid-run stops with `3` rather than reporting the rest as failures |
 
 Data goes to stdout; diagnostics/errors go to stderr.
 

package/dist/agent/engine.js

@@ -6,6 +6,29 @@ const node_crypto_1 = require("node:crypto");
 const selector_1 = require("../ui/selector");
 const errors_1 = require("../errors");
 const ir_1 = require("./ir");
+/** An outcome is environment-flavoured if it carries an exit-3 CliError, or simply
+ *  reported code 3 — the latter also catches a remote step whose error crossed the
+ *  wire as a plain Error (rebuildError drops exitCode) and a non-CliError throw,
+ *  both of which the top-level contract already maps to exit 3. Over-classifying is
+ *  safe here because `vk suite` re-probes before treating it as fatal. */
+const isEnvOutcome = (outcome) => outcome.code === 3 || (0, errors_1.isEnvError)(outcome.error);
+/**
+ * A control-flow guard could not read the screen even once, because the environment is
+ * broken (exit 3). Thrown out of `present()` and converted to a `status: 'env'` step
+ * result by the single catch in runPlan's step loop.
+ *
+ * A throw rather than a wider `present()` return type on purpose: `present()` has seven
+ * call sites across `if-present` / `when` / `repeat` / `while-present` / the guard-race
+ * check, and every one of them would need the same three-line env branch — repetition in
+ * the most intricate code here, and a silent false green at whichever site someone forgot.
+ * runPlan still RETURNS its result; this never escapes the engine.
+ */
+class GuardBlindError extends Error {
+    constructor(selector, cause) {
+        super(`could not read the screen to evaluate '${selector}': ${cause.message.split('\n')[0]}`);
+        this.name = 'GuardBlindError';
+    }
+}
 const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map((f) => (f.value === 'true' ? `--${f.name}` : `--${f.name} ${f.value}`))]
     .join(' ')
     .trim();
@@ -153,7 +176,10 @@ async function runPlan(plan, deps) {
      *    - a dump that SUCCEEDS but does not match is re-polled only while settleMs
      *      remains. At settleMs=0 that means exactly one pass — the fast, single-shot
      *      probe a loop-exit check needs.
-     *  So one dump attempt always happens regardless of the window. */
+     *  So one dump attempt always happens regardless of the window.
+     *
+     *  Throws GuardBlindError when the window closes having NEVER once read the screen
+     *  and the failure was an environment error — see that class for why. */
     const present = async (selector, settleMs) => {
         let sel;
         try {
@@ -173,15 +199,21 @@ async function runPlan(plan, deps) {
         // swings ~10x across devices, so "how long to wait" cannot be expressed in wall clock
         // alone without making the guard's patience device-dependent.
         let looks = 0;
+        // Did ANY dump in this whole call come back? A successful-but-empty tree counts: that
+        // is a bad read of a live screen, not a blind one, and it is already handled below.
+        let everRead = false;
+        let lastErr;
         const minLooks = settleMs > 0 ? 2 : 1;
         for (;;) {
             let els;
             for (let i = 0; i < 2; i++) {
                 try {
                     els = await deps.getElements();
+                    everRead = true;
                 }
-                catch {
+                catch (e) {
                     els = undefined; // transient dump failure — retry once before concluding "absent"
+                    lastErr = e;
                 }
                 // An EMPTY tree is not a screen, it is a bad read: a live app always has nodes, and
                 // this device routinely returns a partial/blank dump mid-transition (measured: `ui`
@@ -196,8 +228,14 @@ async function runPlan(plan, deps) {
             if (els !== undefined && (0, selector_1.matchElements)(els, sel).matches.length > 0)
                 return true;
             const remaining = deadline - Date.now();
-            if (looks >= minLooks && remaining <= 0)
+            if (looks >= minLooks && remaining <= 0) {
+                // The window closed having NEVER once read the screen, because the environment is
+                // broken. Answering "absent" here is a lie that silently skips the body — and a
+                // guard-heavy plan would then finish fully GREEN having executed nothing.
+                if (!everRead && (0, errors_1.isEnvError)(lastErr))
+                    throw new GuardBlindError(selector, lastErr);
                 return false;
+            }
             await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
         }
     };
@@ -300,9 +338,12 @@ async function runPlan(plan, deps) {
         if (isHealable(outcome)) {
             return { status: 'fail', where, reason: `unresolved after ${maxRepairs} repair attempt(s): ${outcome.error.message.split('\n')[0]}` };
         }
-        // Terminal: an assertion failure (exit 1, no throw) or an environment error.
+        // Terminal: an assertion failure (exit 1, no throw) or an environment error. The
+        // two are reported differently — an assertion failure is a regression to fix, an
+        // environment error means the harness is broken and nothing downstream is
+        // trustworthy, so the caller aborts rather than banking a red result.
         const reason = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
-        return { status: 'fail', where, reason };
+        return { status: isEnvOutcome(outcome) ? 'env' : 'fail', where, reason };
     }
     async function walkBody(body, parentWhere, guard) {
         for (let j = 0; j < body.length; j++) {
@@ -496,13 +537,28 @@ async function runPlan(plan, deps) {
             deps.log(`[ai] run timeout reached before steps[${i}] — aborting`);
             return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
         }
-        const res = await walkNode(plan.steps[i], `steps[${i}]`, (l) => (plan.steps[i] = l));
+        // The one place a blind guard becomes a step result — see GuardBlindError.
+        let res;
+        try {
+            res = await walkNode(plan.steps[i], `steps[${i}]`, (l) => (plan.steps[i] = l));
+        }
+        catch (e) {
+            if (!(e instanceof GuardBlindError))
+                throw e;
+            res = { status: 'env', where: `steps[${i}]`, reason: e.message };
+        }
         if (res.status === 'budget') {
             return { ok: false, plan, modelRepairs, improvements, abortedForBudget: true };
         }
         if (res.status === 'timeout') {
             return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
         }
+        if (res.status === 'env') {
+            // `failure` is populated as well as the flag: the suite report still wants a row
+            // reason, and callers that only know about `failure` keep working unchanged.
+            deps.log(`[ai] ABORTED at ${res.where} — environment: ${res.reason}`);
+            return { ok: false, plan, modelRepairs, improvements, abortedForEnv: true, failure: { where: res.where, reason: res.reason } };
+        }
         if (res.status === 'fail') {
             deps.log(`[ai] FAILED at ${res.where}: ${res.reason}`);
             return { ok: false, plan, modelRepairs, improvements, failure: { where: res.where, reason: res.reason } };

package/dist/cli.js

@@ -238,54 +238,41 @@ function formatDeviceTable(devices) {
     // Pad every cell except the last shown column (no trailing whitespace); join with 2 spaces.
     return rows.map((r) => r.map((cell, i) => (i === r.length - 1 ? cell : cell.padEnd(widths[i]))).join('  ').trimEnd());
 }
+/** Render one shared ToolProbe the way doctor always has: present -> stdout, failure +
+ *  hint -> stderr. Unlike `Driver.preflight()` (which throws on the first failure),
+ *  doctor reports every probe so one run lists everything that needs fixing. */
+function reportProbe(p) {
+    if (p.ok) {
+        // A multi-line detail (simctl's booted-device listing) reads as its own block
+        // rather than smashed onto the `name:` line.
+        if (p.detail.includes('\n')) {
+            (0, output_1.out)(`${p.name}: present`);
+            (0, output_1.out)(p.detail);
+        }
+        else {
+            (0, output_1.out)(`${p.name}: ${p.detail}`);
+        }
+    }
+    else {
+        (0, output_1.err)(`${p.name}: ${p.detail}`);
+        if (p.hint)
+            (0, output_1.err)(`  ${p.hint}`);
+    }
+    return p.ok;
+}
 function cmdDoctor(ctx) {
     if (ctx.platform === 'ios') {
-        try {
-            const r = (0, exec_1.runText)('xcrun', ['simctl', 'list', 'devices', 'booted']);
-            (0, output_1.out)('xcrun: present');
-            (0, output_1.out)(r.stdout.trim() || '(no booted simulators)');
-        }
-        catch (e) {
-            // Not necessarily missing: runText also throws on a spawn timeout or other exec
-            // failure, so surface the real reason rather than always claiming "NOT FOUND".
-            (0, output_1.err)(`xcrun: ${e.message}`);
-            (0, output_1.err)('  (if the Xcode command-line tools are not installed: `xcode-select --install`)');
+        // xcrun is the floor: without it there is no device list to reason about.
+        if (!reportProbe((0, drivers_1.probeXcrun)()))
             return 3;
-        }
         // idb (+ its companion) powers everything interactive: ui/tap/text/swipe/key/logs.
-        const idb = process.env.IDB || 'idb';
-        let idbOk = true;
-        try {
-            (0, exec_1.runText)(idb, ['--help']); // idb has no --version; --help confirms the binary runs
-            (0, output_1.out)('idb: present');
-        }
-        catch (e) {
-            (0, output_1.err)(`idb: ${e.message}`);
-            (0, output_1.err)('  needed for ui/tap/text/swipe/key/logs — install: `brew install idb-companion` then `pip install fb-idb`');
-            idbOk = false;
-        }
-        try {
-            (0, exec_1.runText)('idb_companion', ['--help']);
-            (0, output_1.out)('idb_companion: present');
-        }
-        catch (e) {
-            (0, output_1.err)(`idb_companion: ${e.message}`);
-            (0, output_1.err)('  install: `brew install idb-companion`');
-            idbOk = false;
-        }
+        const idbOk = [(0, drivers_1.probeIdb)(), (0, drivers_1.probeIdbCompanion)()].map(reportProbe).every(Boolean);
         (0, output_1.out)('note: simulator screenshots + launch/stop work via simctl; ui/tap/text/swipe/key/logs use idb.');
         return idbOk ? 0 : 3;
     }
     const adb = process.env.ADB || 'adb';
-    try {
-        (0, output_1.out)('adb: ' + (0, exec_1.runText)(adb, ['version']).stdout.split('\n')[0]);
-    }
-    catch (e) {
-        // Not necessarily missing: runText also throws on a spawn timeout or other exec
-        // failure — surface the real reason rather than always claiming "NOT FOUND".
-        (0, output_1.err)(`adb: ${e.message}`);
+    if (!reportProbe((0, drivers_1.probeAdb)()))
         return 3;
-    }
     const devices = ctx.driver.listDevices();
     const usable = devices.filter((d) => d.state === 'device');
     (0, output_1.out)(`devices: ${devices.length} attached, ${usable.length} usable`);
@@ -1113,6 +1100,11 @@ async function resolveBackend(platform, device, flags) {
     const server = (0, args_1.flagStr)(flags, 'server') || process.env.VERIKUN_SERVER || undefined;
     if (!server) {
         const driver = (0, drivers_1.getDriver)(platform, device);
+        // Fail fast on a broken toolchain BEFORE any model spend — the mirror of the
+        // remote branch's pingServer below. Without this, a missing `idb` isn't noticed
+        // until the first step that reads the hierarchy (launch/screenshot go through
+        // simctl on a simulator), by which point every test in a suite has been compiled.
+        driver.preflight();
         return {
             backend: {
                 exec: (command, positionals, f) => executeOutcome(command, positionals, f, driver),
@@ -1126,6 +1118,7 @@ async function resolveBackend(platform, device, flags) {
                     else
                         driver.clearApp(appId);
                 },
+                preflight: () => driver.preflight(),
             },
             platform,
             device,
@@ -1142,8 +1135,20 @@ async function resolveBackend(platform, device, flags) {
     const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
     runCtx = { platform: health.platform, device: health.serial };
     (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial} · verikun ${health.version}`);
+    const remote = (0, remote_1.createRemoteBackend)(opts, health);
     return {
-        backend: (0, remote_1.createRemoteBackend)(opts, health),
+        backend: {
+            ...remote,
+            // Ping first (URL, key, version), then fetch the hierarchy once. The ping alone
+            // is NOT enough as a health probe: /v1/health answers from config captured at
+            // server startup and never touches the device, so it cannot see a phone that was
+            // unplugged next to the server — the suite's mid-run re-probe would call it
+            // healthy and keep grinding. One dump is the cheap call that actually proves it.
+            preflight: async () => {
+                await (0, remote_1.pingServer)(opts);
+                await remote.getElements();
+            },
+        },
         platform: health.platform,
         device: health.serial,
         remote: { url: server, version: health.version },
@@ -1249,7 +1254,9 @@ async function runAiTest(file, opts, backend, platform, device) {
             ? `ABORTED — cost ceiling $${opts.maxCostUsd} reached`
             : result.abortedForTimeout
                 ? `ABORTED — run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`
-                : `FAIL at ${result.failure?.where}: ${result.failure?.reason}`;
+                : result.abortedForEnv
+                    ? `ABORTED — environment: ${result.failure?.reason}`
+                    : `FAIL at ${result.failure?.where}: ${result.failure?.reason}`;
     (0, output_1.err)(`[ai] ${status} · ${costLine}`);
     (0, output_1.err)(`[ai] report: ${htmlPath}`);
     if (result.improvements.length) {
@@ -1271,6 +1278,7 @@ async function runAiTest(file, opts, backend, platform, device) {
         ...(result.failure ? { failure: result.failure } : {}),
         ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
         ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
+        ...(result.abortedForEnv ? { abortedForEnv: true } : {}),
     };
 }
 async function cmdAi(positionals, flags) {
@@ -1311,12 +1319,15 @@ async function cmdAi(positionals, flags) {
             ...(result.failure ? { failure: result.failure } : {}),
             ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
             ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
+            ...(result.abortedForEnv ? { abortedForEnv: true } : {}),
         });
     }
     else if (result.reportHtml) {
         (0, output_1.out)(result.reportHtml); // primary machine result: the report path
     }
-    return result.ok ? 0 : 1;
+    // An environment failure is exit 3, not 1: the box is broken, not the app. Exit 1
+    // here would be indistinguishable from a real regression and page the wrong person.
+    return result.abortedForEnv ? 3 : result.ok ? 0 : 1;
 }
 // ---------------------------------------------------------------------------
 // install — put an app build on the device (local driver or remote vk server)
@@ -1369,6 +1380,7 @@ async function cmdSuiteEntry(positionals, flags) {
             // Reset app state between tests only when the app id is known; without --app,
             // each test is responsible for its own isolation (e.g. `launch --clear`).
             reset: app ? () => backend.reset(app) : undefined,
+            preflight: () => backend.preflight?.(),
         });
     }
     finally {

package/dist/drivers/adb.js

@@ -1,11 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdbDriver = void 0;
+exports.probeAdb = probeAdb;
 exports.escapeText = escapeText;
 const errors_1 = require("../errors");
 const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
 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
+ *  the two can't drift on what "the Android toolchain works" means. */
+function probeAdb() {
+    try {
+        const r = (0, exec_1.runText)(ADB, ['version']);
+        // runText only throws when the binary can't be SPAWNED, so a broken-but-present adb
+        // needs its exit code checked too — otherwise it reports as healthy.
+        if (r.code !== 0) {
+            return { name: 'adb', ok: false, detail: `adb version exited ${r.code}: ${r.stderr.trim()}`, hint: ADB_HINT };
+        }
+        return { name: 'adb', ok: true, detail: r.stdout.split('\n')[0] };
+    }
+    catch (e) {
+        // Not necessarily missing: runText also throws on a spawn timeout or other exec
+        // failure — surface the real reason rather than always claiming "NOT FOUND".
+        return { name: 'adb', ok: false, detail: e.message, hint: ADB_HINT };
+    }
+}
 // Named keys -> Android keycodes. Numeric codes are also accepted directly.
 const KEYCODES = {
     enter: 66,
@@ -79,6 +99,27 @@ class AdbDriver {
     constructor(serial) {
         this.requested = serial;
     }
+    preflight() {
+        const adb = probeAdb();
+        if (!adb.ok)
+            throw (0, errors_1.probeFailure)(adb);
+        // Resolving the serial is the other half of "can I drive anything?": it throws
+        // exit 3 with no device attached and exit 2 when several are and none was chosen.
+        const serial = this.resolvedSerial();
+        // …but that answer is cached, so ask the device itself. That is what lets a suite's
+        // mid-run re-probe notice a phone that was unplugged or an emulator that died,
+        // rather than replaying the resolution it made before anything went wrong.
+        const state = (0, exec_1.runText)(ADB, ['-s', serial, 'get-state']);
+        const got = state.stdout.trim();
+        if (state.code !== 0 || got !== 'device') {
+            throw (0, errors_1.probeFailure)({
+                name: 'adb',
+                ok: false,
+                detail: `device ${serial} is not ready (${got || state.stderr.trim().split('\n')[0] || `adb get-state exited ${state.code}`})`,
+                hint: 'reconnect it (check `verikun devices`); an unauthorized device needs the USB-debugging prompt accepted',
+            });
+        }
+    }
     listDevices() {
         const { stdout } = (0, exec_1.runText)(ADB, ['devices', '-l']);
         const devices = [];

package/dist/drivers/index.js

@@ -1,13 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IdbDriver = exports.AdbDriver = void 0;
+exports.probeIdbCompanion = exports.probeIdb = exports.probeXcrun = exports.IdbDriver = exports.probeAdb = exports.AdbDriver = void 0;
 exports.getDriver = getDriver;
 const adb_1 = require("./adb");
 const ios_1 = require("./ios");
 var adb_2 = require("./adb");
 Object.defineProperty(exports, "AdbDriver", { enumerable: true, get: function () { return adb_2.AdbDriver; } });
+Object.defineProperty(exports, "probeAdb", { enumerable: true, get: function () { return adb_2.probeAdb; } });
 var ios_2 = require("./ios");
 Object.defineProperty(exports, "IdbDriver", { enumerable: true, get: function () { return ios_2.IdbDriver; } });
+Object.defineProperty(exports, "probeXcrun", { enumerable: true, get: function () { return ios_2.probeXcrun; } });
+Object.defineProperty(exports, "probeIdb", { enumerable: true, get: function () { return ios_2.probeIdb; } });
+Object.defineProperty(exports, "probeIdbCompanion", { enumerable: true, get: function () { return ios_2.probeIdbCompanion; } });
 function getDriver(platform, device) {
     return platform === 'ios' ? new ios_1.IdbDriver(device) : new adb_1.AdbDriver(device);
 }

package/dist/drivers/ios.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IdbDriver = void 0;
+exports.probeXcrun = probeXcrun;
+exports.probeIdb = probeIdb;
+exports.probeIdbCompanion = probeIdbCompanion;
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
@@ -21,6 +24,50 @@ const ios_parse_1 = require("../ui/ios-parse");
 // never feed back into a tap.)
 const XCRUN = 'xcrun';
 const IDB = process.env.IDB || 'idb';
+// Tool probes, shared by `vk doctor --ios` (which renders every one and keeps going)
+// and IdbDriver.preflight() (which throws on the first failure) so the two can't drift
+// on what "the iOS toolchain works" means — or on the install hints.
+const IDB_HINT = 'needed for ui/tap/text/swipe/key/logs — install: `brew install idb-companion` then `pip install fb-idb`';
+const XCRUN_HINT = 'if the Xcode command-line tools are not installed: `xcode-select --install`';
+function probeXcrun() {
+    try {
+        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'booted']);
+        // runText only throws when the binary can't be SPAWNED, so a tool that exists but
+        // fails (broken install, missing Xcode selection) needs the exit code checked too.
+        if (r.code !== 0) {
+            return { name: 'xcrun', ok: false, detail: `xcrun simctl exited ${r.code}: ${r.stderr.trim()}`, hint: XCRUN_HINT };
+        }
+        return { name: 'xcrun', ok: true, detail: r.stdout.trim() || '(no booted simulators)' };
+    }
+    catch (e) {
+        // Not necessarily missing: runText also throws on a spawn timeout or other exec
+        // failure, so surface the real reason rather than always claiming "NOT FOUND".
+        return { name: 'xcrun', ok: false, detail: e.message, hint: XCRUN_HINT };
+    }
+}
+function probeIdb() {
+    try {
+        const r = (0, exec_1.runText)(IDB, ['--help']); // idb has no --version; --help confirms the binary runs
+        if (r.code !== 0)
+            return { name: 'idb', ok: false, detail: `idb --help exited ${r.code}: ${r.stderr.trim()}`, hint: IDB_HINT };
+        return { name: 'idb', ok: true, detail: 'present' };
+    }
+    catch (e) {
+        return { name: 'idb', ok: false, detail: e.message, hint: IDB_HINT };
+    }
+}
+function probeIdbCompanion() {
+    try {
+        // Spawn-only on purpose: idb_companion prints its usage to stderr and exits 1 for
+        // --help, so its exit code says nothing about health. Presence is all we can cheaply
+        // assert here — idb itself is the probe that has to actually work.
+        (0, exec_1.runText)('idb_companion', ['--help']);
+        return { name: 'idb_companion', ok: true, detail: 'present' };
+    }
+    catch (e) {
+        return { name: 'idb_companion', ok: false, detail: e.message, hint: 'install: `brew install idb-companion`' };
+    }
+}
 const DEFAULT_LOG_LINES = 200;
 const DEFAULT_LOG_WINDOW = '5m';
 // Named keys -> USB-HID keyboard usage IDs, handed to `idb ui key <code>`. Numeric
@@ -104,6 +151,34 @@ class IdbDriver {
         // 'booted' is a simctl-only alias idb can't address, so treat it as "auto-resolve".
         this.requested = device && device !== 'booted' ? device : undefined;
     }
+    preflight() {
+        // resolvedSerial() shells to simctl, so it already covers a missing xcrun, no
+        // booted simulator / connected device, and an ambiguous target (exit 2).
+        this.resolvedSerial();
+        // idb is required to drive iOS AT ALL — simulator or not. simctl covers launch,
+        // stop and screenshots, so without this a missing idb goes unnoticed until the
+        // first step that reads the hierarchy, long after a compile has been paid for.
+        //
+        // `describe` rather than doctor's `idb --help`: one round-trip that proves idb runs
+        // AND that the target is still reachable through its companion. That second half is
+        // what lets `vk suite`'s mid-run re-probe notice a simulator that died — `--help`
+        // would keep answering happily with the device long gone. (doctor keeps `--help`
+        // because it must report on idb with no device booted at all.)
+        let r;
+        try {
+            // Default 30s timeout, same as screenSize()'s identical call: preflight is the
+            // FIRST idb call of the process, so it is the one that pays idb_companion's
+            // cold start — the last place to shave the budget.
+            r = (0, exec_1.runText)(IDB, ['describe', '--udid', this.udid()]);
+        }
+        catch (e) {
+            throw (0, errors_1.probeFailure)({ name: 'idb', ok: false, detail: e.message, hint: IDB_HINT });
+        }
+        if (r.code !== 0) {
+            const why = r.stderr.trim().split('\n')[0] || `exit code ${r.code}`;
+            throw (0, errors_1.probeFailure)({ name: 'idb', ok: false, detail: `idb cannot reach ${this.udid()}: ${why}`, hint: IDB_HINT });
+        }
+    }
     /** All available simulators (booted or shutdown) via simctl. Tolerates odd output. */
     simulators() {
         const devices = [];

package/dist/errors.js

@@ -6,7 +6,8 @@
 //   2  usage error or ambiguous selector (caller must refine)
 //   3  environment error (adb/simctl missing, no/multiple devices, dump failed)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousSelectorError = exports.SelectorNotFoundError = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
+exports.AmbiguousSelectorError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
+exports.isEnvError = isEnvError;
 class CliError extends Error {
     exitCode;
     constructor(message, exitCode) {
@@ -22,6 +23,20 @@ const notFound = (m) => new CliError(m, 1);
 exports.notFound = notFound;
 const envError = (m) => new CliError(m, 3);
 exports.envError = envError;
+/**
+ * An environment failure (exit 3): a tool missing from PATH, no/ambiguous device, a
+ * hierarchy dump or capture that failed. The one predicate every layer shares to tell
+ * "the box is broken" from "the app is broken" — the agent runner aborts on it instead
+ * of recording a regression, and `vk suite` stops rather than reporting N phantom
+ * failures. Accepts `unknown` so `catch (e)` blocks can pass their binding directly.
+ */
+function isEnvError(e) {
+    return e instanceof CliError && e.exitCode === 3;
+}
+/** Turn a failed tool probe into the environment error both drivers' preflight throws,
+ *  so the install hint reads the same whether it came from `vk doctor` or a preflight. */
+const probeFailure = (p) => (0, exports.envError)(`${p.detail}${p.hint ? `\n  ${p.hint}` : ''}`);
+exports.probeFailure = probeFailure;
 // --- Selector-resolution errors (heal triggers for the agent runner) --------
 //
 // A selector miss (zero matches) and an ambiguous match (>1) are still ordinary

package/dist/report.js

@@ -206,6 +206,9 @@ const SUITE_STYLE = `
   table.tests td.num { text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap; }
   table.tests a { color:inherit; }
   .fail-reason { color:var(--fail); font-size:12px; margin-top:2px; }
+  .aborted { background:#fff4e5; border:1px solid #f0b429; border-radius:8px; padding:12px 14px; margin:0 0 14px; font-size:13px; }
+  .aborted strong { color:#8a5300; }
+  .aborted ul { margin:6px 0 0; padding-left:20px; color:var(--muted); }
 `;
 function suiteTestRow(t, linkBase) {
     // A test that errored before its run started (id '') has no report to link.
@@ -233,10 +236,22 @@ function toSuiteHtml(suite, opts = {}) {
     const chips = [
         `<span class="chip pass">${t.passed} passed</span>`,
         t.failed ? `<span class="chip fail">${t.failed} failed</span>` : '',
+        suite.aborted ? `<span class="chip fail">ABORTED</span>` : '',
         `<span class="chip muted">${t.tests} tests &middot; ${t.steps} steps &middot; ${fmtDuration(t.durationMs)} &middot; $${t.costUsd.toFixed(4)}</span>`,
     ]
         .filter(Boolean)
         .join('\n      ');
+    // The banner, not a table row per skipped file: a not-run test is not a result, and
+    // faking a FAIL row for one would be the very "phantom regression" this prevents.
+    const abortedBanner = suite.aborted
+        ? `  <div class="aborted">
+    <strong>Suite aborted — the device environment broke mid-run.</strong>
+    <div>${htmlEsc(suite.aborted.reason)}</div>
+${suite.aborted.notRun.length
+            ? `    <ul>${suite.aborted.notRun.map((f) => `<li>${htmlEsc(f)} — not run</li>`).join('')}</ul>\n`
+            : ''}  </div>
+`
+        : '';
     const metaBits = [
         `<code>${htmlEsc(suite.id)}</code>`,
         htmlEsc(suite.platform) + (suite.device ? ` · ${htmlEsc(suite.device)}` : ''),
@@ -259,7 +274,7 @@ function toSuiteHtml(suite, opts = {}) {
   <div class="summary">
       ${chips}
   </div>
-  <table class="tests">
+${abortedBanner}  <table class="tests">
     <thead><tr><th></th><th>Test</th><th>Steps</th><th>Repairs</th><th>Cost</th><th>Duration</th></tr></thead>
     <tbody>
 ${suite.tests.map((x) => suiteTestRow(x, linkBase)).join('\n')}

package/dist/run.js

@@ -340,12 +340,15 @@ class Recorder {
         this.step.status = exitCode === 1 ? 'failed' : 'error';
         if (!this.step.message)
             this.step.message = e.message;
-        this.capture(driver);
+        // The step failed BECAUSE the environment is broken, so evidence capture is
+        // near-certain to fail the same way. Still attempt it (a screencap can succeed
+        // where a dump doesn't), but don't narrate two more copies of the same error.
+        this.capture(driver, (0, errors_1.isEnvError)(e));
         this.commit();
     }
     // Best-effort: grab a screenshot and the UI hierarchy of the failing page.
     // The device may be unreachable (that may be why we failed) — swallow errors.
-    capture(driver) {
+    capture(driver, quiet = false) {
         if (!driver)
             return;
         try {
@@ -355,14 +358,16 @@ class Recorder {
         catch (e) {
             // Best-effort evidence: the device may be gone (often why the step failed). Surface
             // it so a screenshot bug isn't hidden, but never let it derail failure recording.
-            (0, output_1.err)(`[verikun] could not capture failure screenshot (${e.message})`);
+            if (!quiet)
+                (0, output_1.err)(`[verikun] could not capture failure screenshot (${e.message})`);
         }
         try {
             const text = (0, format_1.formatCompact)(driver.getElements({ all: false }));
             this.step.failHierarchy = text.length > HIERARCHY_CAP ? text.slice(0, HIERARCHY_CAP) + '\n…(truncated)' : text;
         }
         catch (e) {
-            (0, output_1.err)(`[verikun] could not capture failure hierarchy (${e.message})`);
+            if (!quiet)
+                (0, output_1.err)(`[verikun] could not capture failure hierarchy (${e.message})`);
         }
     }
     writeArtifact(rel, buf) {

package/dist/server.js

@@ -310,9 +310,12 @@ async function cmdServer(positionals, flags) {
         authKey = (0, node_crypto_1.randomBytes)(32).toString('base64url');
         generated = true;
     }
-    // Build the ONE driver the server will ever use, and fail fast (exit 2/3) if no
-    // device resolves — before binding a port.
+    // Build the ONE driver the server will ever use, and fail fast (exit 2/3) if the
+    // toolchain can't drive it — before binding a port. preflight() covers resolving the
+    // device AND the tools; without it the server happily listens on a box with no idb
+    // and then 500s every /v1/exec.
     const driver = (0, drivers_1.getDriver)(platform, device);
+    driver.preflight();
     const serial = driver.resolvedSerial();
     // Handlers print "tapped …" confirmations via out(); a server's stdout is not a
     // data channel, so silence them — request logging goes to stderr instead.

package/dist/suite.js

@@ -22,6 +22,38 @@ const output_1 = require("./output");
 const run_1 = require("./run");
 const report_1 = require("./report");
 const version_1 = require("./version");
+/** Gap between the two health probes below. Long enough to outlast a USB
+ *  re-enumeration or a simulator relaunch, short enough not to pad a real abort. */
+const PROBE_RETRY_MS = 1000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * An environment-flavoured failure is only FATAL if the toolchain is STILL broken when
+ * we re-probe. This distinction is load-bearing: a transient uiautomator dump failure
+ * also surfaces as exit 3 (matchWaiting/resolveOneWaiting don't catch a thrown
+ * getElements), so aborting on the exit code alone would let one flaky dump vaporize a
+ * 20-test suite. Returns the reason when broken, undefined when it was transient.
+ */
+async function stillBroken(deps) {
+    if (!deps.preflight)
+        return undefined; // not wired -> preserve continue-on-failure
+    // Two attempts a second apart, because the probe is the ONLY thing separating a
+    // momentary blip from a dead box, and killing a 20-test suite is the expensive
+    // mistake. A USB re-enumeration or a simulator mid-relaunch can fail one probe and
+    // pass the next; a genuinely missing tool fails both in a few milliseconds.
+    let last = '';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        if (attempt > 0)
+            await sleep(deps.probeRetryMs ?? PROBE_RETRY_MS);
+        try {
+            await deps.preflight();
+            return undefined;
+        }
+        catch (e) {
+            last = e.message.split('\n')[0];
+        }
+    }
+    return last;
+}
 /** Lexicographic order, so authors sequence flows with 01-…, 02-… prefixes. */
 function sortTestFiles(files) {
     return [...files].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
@@ -45,13 +77,15 @@ function listTestFiles(dir) {
 function toSuiteResult(file, r, durationMs) {
     const steps = r.state?.steps ?? [];
     const passedSteps = steps.filter((s) => s.status === 'passed').length;
-    const failure = r.failure
-        ? `FAIL at ${r.failure.where}: ${r.failure.reason}`
-        : r.abortedForBudget
-            ? 'aborted: cost ceiling reached'
-            : r.abortedForTimeout
-                ? 'aborted: run timeout reached'
-                : undefined;
+    const failure = r.abortedForEnv
+        ? `aborted: environment — ${r.failure?.reason ?? 'device unavailable'}`
+        : r.failure
+            ? `FAIL at ${r.failure.where}: ${r.failure.reason}`
+            : r.abortedForBudget
+                ? 'aborted: cost ceiling reached'
+                : r.abortedForTimeout
+                    ? 'aborted: run timeout reached'
+                    : undefined;
     return {
         id: r.runDir ? (0, node_path_1.basename)(r.runDir) : '',
         file,
@@ -80,7 +114,8 @@ async function cmdSuite(dirArg, flags, deps) {
     const startedAt = new Date().toISOString();
     (0, output_1.err)(`[suite] '${name}': ${files.length} test(s) from ${dirArg} (${deps.platform}${deps.device ? ` · ${deps.device}` : ''})`);
     const results = [];
-    for (let i = 0; i < files.length; i++) {
+    let aborted;
+    for (let i = 0; i < files.length && !aborted; i++) {
         const file = files[i];
         (0, output_1.err)(`[suite] ── (${i + 1}/${files.length}) ${file} ──`);
         if (deps.reset) {
@@ -89,8 +124,16 @@ async function cmdSuite(dirArg, flags, deps) {
                 (0, output_1.err)('[suite] app state reset');
             }
             catch (e) {
-                // Surface but continue: a flaky reset should not zero out the whole suite —
-                // the test itself will fail loudly if the stale state actually matters.
+                // A reset that failed because the BOX is broken means nothing after it is
+                // trustworthy — but only if a re-probe agrees. Otherwise surface and continue:
+                // a flaky reset should not zero out the whole suite, and the test itself will
+                // fail loudly if the stale state actually matters.
+                const broken = (0, errors_1.isEnvError)(e) ? await stillBroken(deps) : undefined;
+                if (broken) {
+                    // This test never ran, so it gets no row — notRun starts at the CURRENT file.
+                    aborted = { reason: `reset failed: ${broken}`, notRun: files.slice(i) };
+                    break;
+                }
                 (0, output_1.err)(`[suite] reset failed (${e.message}) — continuing`);
             }
         }
@@ -98,11 +141,19 @@ async function cmdSuite(dirArg, flags, deps) {
         try {
             const r = await deps.runTest((0, node_path_1.join)(dir, file));
             results.push(toSuiteResult(file, r, Date.now() - t0));
+            // The test itself reported an environment abort (exit 3 mid-plan). Same rule:
+            // fatal only if the box is still broken. This test HAS a row and a real report,
+            // so notRun starts after it.
+            if (r.abortedForEnv) {
+                const broken = await stillBroken(deps);
+                if (broken)
+                    aborted = { reason: broken, notRun: files.slice(i + 1) };
+            }
         }
         catch (e) {
-            // A test that THREW (env error: device gone, server unreachable, bad file)
-            // still becomes a failed row — one broken test must not vaporize the suite
-            // report for the tests that already ran.
+            // A test that THREW (device gone, server unreachable, bad file) still becomes a
+            // failed row — one broken test must not vaporize the suite report for the tests
+            // that already ran. But if it threw because the environment is gone, stop.
             const msg = e instanceof Error ? e.message : String(e);
             (0, output_1.err)(`[suite] ${file} errored: ${msg}`);
             results.push({
@@ -118,8 +169,14 @@ async function cmdSuite(dirArg, flags, deps) {
                 modelRepairs: 0,
                 failure: msg.split('\n')[0],
             });
+            const broken = (0, errors_1.isEnvError)(e) ? await stillBroken(deps) : undefined;
+            if (broken)
+                aborted = { reason: broken, notRun: files.slice(i + 1) };
         }
     }
+    if (aborted) {
+        (0, output_1.err)(`[suite] ABORTED — environment: ${aborted.reason} (${aborted.notRun.length} test(s) not run)`);
+    }
     const suite = {
         schemaVersion: 1,
         id: suiteId,
@@ -131,6 +188,7 @@ async function cmdSuite(dirArg, flags, deps) {
         verikun: version_1.VERSION,
         totals: (0, report_1.suiteTotals)(results),
         tests: results,
+        ...(aborted ? { aborted } : {}),
     };
     // .verikun/suites/<id>/ sits beside .verikun/runs/<id>/, so index.html reaches a
     // test report at ../../runs/<id>/report.html — the linkBase below.
@@ -147,6 +205,8 @@ async function cmdSuite(dirArg, flags, deps) {
         (0, output_1.json)(suite);
     else
         (0, output_1.out)(outDir); // primary machine result: the suite directory
-    // The CI gate: any failed test fails the invocation (mirrors `vk run archive`).
-    return t.failed > 0 ? 1 : 0;
+    // The CI gate: any failed test fails the invocation (mirrors `vk run archive`). An
+    // environment abort exits 3 instead, so CI can tell "the runner is broken" from "the
+    // app regressed" — the whole point of stopping early.
+    return aborted ? 3 : t.failed > 0 ? 1 : 0;
 }

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.11.0';
+exports.VERSION = '0.12.0';

package/package.json

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