verikun 0.29.0 → 0.30.0

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

@@ -437,6 +437,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
 - **`3` also means the device toolchain is broken**, checked *before* anything is compiled
   (missing `adb`/`idb`, no device, an ambiguous target) and again if it breaks mid-run. Treat
   it as "fix the machine", never as a failing test — the message carries the install hint.
+  Exception: over `--server`, a `--json` result with `evicted: true` means the server's device
+  left the pool mid-run — nothing is broken; run the test again.
 
 ## Run a suite of tests (vk suite)
 
@@ -488,6 +490,9 @@ vk suite tests/ --app com.example.app --servers http://a:8391,http://b:8391
 - `--concurrency N` caps how many run at once — more devices on one host can thrash it.
   `--max-suite-cost-usd N` stops the suite once total model spend crosses it (exit `1`).
 - A device that breaks retires; its tests move to the others. Exit `3` only when all are gone.
+- Over `--server`, a lane with no free device waits instead of failing tests, and a test whose
+  device left the pool re-runs without spending a retry. With no device for any lane the suite
+  stops after `VERIKUN_SUITE_DEVICE_WAIT_MIN` (default 10) with exit `3` and a `notRun` list.
 - `--ensure-device` is refused with `--devices` — start the pool with `vk devices start`.
 
 ## Drive a remote device (--server)

package/CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-09-26
+
+### Fixed
+- **`vk suite --server`** waits for a free device instead of failing tests that never got one, and
+  a waiting lane resumes when the pool recovers. ([#147])
+
+### Added
+- **`vk suite --server`** re-runs a test whose device left the pool mid-run without spending a
+  retry, up to twice; needs the matching `vk server`. ([#147])
+- **`VERIKUN_SUITE_DEVICE_WAIT_MIN`** (default `10`) caps how long a pooled suite waits when no lane
+  gets a device, busy pools included, then exits `3`; `0` fails fast. ([#147])
+
+### Changed
+- **`--json` errors** name a refused `vk server` lease `NoFreeDeviceError` and an evicted run
+  `RunEvictedError` in `errorKind`; exit codes are unchanged. ([#147])
+- **`vk ai --json`** reports a run whose device left the pool as an environment abort with
+  `evicted: true` and its report, instead of a bare error. ([#147])
+
+[#147]: https://github.com/ddikman/verikun/issues/147
+
+## [0.29.1] - 2026-09-26
+
+### Fixed
+- **`vk ai`** no longer guesses `id:` selectors; an element the test names only by label compiles
+  to `text:` — write the id into the test to pin it. ([#148])
+
+[#148]: https://github.com/ddikman/verikun/issues/148
+
 ## [0.29.0] - 2026-09-16
 
 ### Changed

package/dist/agent/engine.js

@@ -31,6 +31,17 @@ class GuardBlindError extends Error {
         this.name = 'GuardBlindError';
     }
 }
+/**
+ * A run the server EVICTED cannot continue: its phone left the pool, and every later call is
+ * refused the same way. So the catches below that absorb a failed READ — a guard's retry, the
+ * empty-tree fallback, a repair that could not be made — must let it through. Absorbed, a lost
+ * phone read as an absent guard, a "read found no element" FAIL or a failed repair, and a
+ * parallel suite lost the class it needs to re-run the test as a fresh run (#147).
+ */
+const rethrowIfEvicted = (e) => {
+    if (e instanceof errors_1.RunEvictedError)
+        throw e;
+};
 const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map((f) => (f.value === 'true' ? `--${f.name}` : `--${f.name} ${f.value}`))]
     .join(' ')
     .trim();
@@ -190,7 +201,8 @@ async function runPlan(plan, deps) {
         try {
             return await deps.getElements();
         }
-        catch {
+        catch (e) {
+            rethrowIfEvicted(e);
             return [];
         }
     };
@@ -256,6 +268,7 @@ async function runPlan(plan, deps) {
                     everRead = true;
                 }
                 catch (e) {
+                    rethrowIfEvicted(e);
                     els = undefined; // transient dump failure — retry once before concluding "absent"
                     lastErr = e;
                 }
@@ -366,6 +379,7 @@ async function runPlan(plan, deps) {
                 repaired = node;
             }
             catch (e) {
+                rethrowIfEvicted(e);
                 const msg = e instanceof Error ? e.message : String(e);
                 return { status: 'fail', where, reason: `repair failed: ${msg}` };
             }

package/dist/agent/grammar.js

@@ -118,7 +118,7 @@ Do NOT hard-code a run of indices you were not told the length of. If the prose
 varies per run — emit a while-present over {{ctx.i}} rather than tap _0, _1, _2, _3.
 A hard-coded list is right only when the prose states the exact count.
 
-SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable identifiers):
+SELECTORS (the engine auto-heals case/whitespace/partial, so prefer an id the test gives you):
   @login            resource-id 'login' (shorthand for id:login)
   id:login          resource-id (full, suffix, or short)
   text:Sign in      visible text (case-insensitive)
@@ -156,7 +156,17 @@ RULES:
   below the fold — that is now redundant. Emit an explicit swipe only when the SCROLLING
   ITSELF is what the test asks for ("scroll the feed three times"), or to reveal content
   that is not in the hierarchy until it is built (an infinite/lazy list).
-- Prefer resource-id / accessibility selectors over visible text where possible.
+- IDS COME FROM THE TEST. Use @x / id:x only with an id the test writes (or one a PRIOR PLAN
+  shown to you already uses). You cannot see the app, so never compose an id from a label, a
+  description, or the pattern of the app's other ids: a made-up id matches nothing, and a
+  wait/assert on it FAILS the test with no repair. An element the test names only by what it
+  says ("tap Sign in", "the Home tab") is text:<those words> — forgiving, and it also matches an
+  accessibility label.
+- An outcome the test states ("the tab bar (Home, Search, Profile) appears") is checked on what
+  it NAMES — the id it gives, or the words it quotes or lists — never on an id you made up. A
+  description that names nothing you could select without inventing it ("it shows the
+  signed-in user's name") is context, not a step; so is rationale (why a step exists, what a
+  field already holds).
 - Translate the test literally and minimally: do not invent ACTION steps (tap/text/swipe/key/assert)
   the prose does not imply. The ONE exception is screenshot — insert screenshot steps liberally as
   post-run review evidence: after each screen transition (launch, a navigation tap, a submit, a

package/dist/agent/lint.js

@@ -2,7 +2,7 @@
 // Compile-fidelity lint: does the plan the model produced still say what the prose said?
 //
 // The model is a compiler, and this is the compiler's own sanity check. It exists because
-// compilation is NONDETERMINISTIC in a way that is invisible until a run fails, and three
+// compilation is NONDETERMINISTIC in a way that is invisible until a run fails, and four
 // failure modes showed up repeatedly against a real suite:
 //
 //   1. An explicit directive silently vanishes. The same prose ("Launch the app WITH ITS
@@ -18,8 +18,12 @@
 //      against later builds. A test exercising none of its subject reporting success is the
 //      worst failure mode a testing tool has, which is why the two rules that detect it are
 //      the only FATAL findings here.
+//   4. A selector names an id the test never gave (issue #148). The compiler cannot see the
+//      app, so it composed one from the app's naming pattern, and 3 of 4 such guesses named
+//      nothing in the app. A wait/assert is never repaired, so the test went red — and each
+//      recompile guessed differently, so it flaked.
 //
-// 1 and 2 are cheap to detect and cheap to fix: hand the finding back to the model and let
+// 1, 2 and 4 are cheap to detect and cheap to fix: hand the finding back to the model and let
 // it compile once more. That is far better than the alternative, which is a plan that is
 // quietly wrong and burns a device run to say so. 3 gets the same guided recompile, but a
 // plan that STILL does not cover its test must never run — see `fatal` below.
@@ -34,9 +38,11 @@ exports.instructionLines = instructionLines;
 exports.instructionUnits = instructionUnits;
 exports.actionNodes = actionNodes;
 exports.tailAnchors = tailAnchors;
+exports.ungroundedIds = ungroundedIds;
 exports.lintPlan = lintPlan;
 exports.looksTruncated = looksTruncated;
 const ir_1 = require("./ir");
+const selector_1 = require("../ui/selector");
 /** Walk every node in the plan, including control-node bodies. */
 function* walk(nodes) {
     for (const n of nodes) {
@@ -257,15 +263,95 @@ function planMentions(tokens, anchor) {
         return b.length >= 3 && (b.includes(a) || a.includes(b));
     });
 }
+// --- ids: does every id the plan selects by come from the prose? (issue #148) ------------
+/** Commands whose FIRST positional is a selector. The rest of `text`'s positionals, and every
+ *  positional of `type`/`launch`/…, is data — `type @handle` types a handle, it selects nothing. */
+const SELECTOR_FIRST = new Set(['tap', 'click', 'text', 'wait', 'assert']);
+/** Every string the engine resolves as a selector — unlike `planTokens`, which also returns data. */
+function selectorsOf(plan) {
+    const out = [];
+    for (const n of walk(plan.steps)) {
+        if (n.type === 'command') {
+            if (SELECTOR_FIRST.has(n.command) && n.positionals[0])
+                out.push(n.positionals[0]);
+            if (n.command === 'swipe' || n.command === 'scroll') {
+                for (const f of n.flags)
+                    if (f.name === 'on')
+                        out.push(f.value);
+            }
+        }
+        else if (n.type === 'when') {
+            out.push(...n.branches.map((b) => b.selector));
+        }
+        else {
+            out.push(n.selector);
+        }
+    }
+    return out;
+}
+/** The id values (`@x` / `id:x`) the plan selects by, parsed by the engine's own parser so the
+ *  two can never disagree about what an id selector is — trailing state modifiers included. */
+function planIds(plan) {
+    const out = [];
+    for (const raw of selectorsOf(plan)) {
+        let sel;
+        try {
+            sel = (0, selector_1.parseSelector)(raw);
+        }
+        catch {
+            continue; // an empty value or contradictory modifiers: a runtime error, not a guess
+        }
+        if (sel.kind === 'id' && !out.includes(sel.value))
+            out.push(sel.value);
+    }
+    return out;
+}
+/** `com.app:id/login` and `login` name the same element. */
+const RESOURCE_PKG_RE = /^[\w.]+:id\//;
+/** `{{ctx.i}}` / `{{env.X}}` are filled at run time, so they are never part of a guess. */
+const PLACEHOLDER_RE = /\{\{[^}]*\}\}/;
+/** The literal parts of an id worth judging. Under three characters a substring matches
+ *  anything, so a part that short has no opinion. */
+const idParts = (id) => id
+    .replace(RESOURCE_PKG_RE, '')
+    .split(PLACEHOLDER_RE)
+    .map(normToken)
+    .filter((p) => p.length >= 3);
+/** Every word of the prose, and every quoted span whole — an iOS identifier may hold spaces. */
+function proseTokens(nl) {
+    const out = [];
+    for (const m of nl.matchAll(ANCHOR_RE))
+        out.push(m[1] ?? m[2] ?? m[3] ?? '');
+    out.push(...nl.split(/[\s`"“”'‘’()[\]{}<>,;!?]+/));
+    return out.map(normToken).filter((t) => t.length > 0);
+}
+/**
+ * The ids the plan selects by that neither the prose nor `seed` gives — each one a guess.
+ *
+ * LENIENT on purpose, since a false positive costs a recompile: an id is grounded when every
+ * literal part of it (package qualifier and placeholders dropped, case and punctuation ignored)
+ * sits inside ONE token of the prose, so `@spinner` is grounded by `vk_spinner` and
+ * `id:option_{{ctx.i}}` by `option_0`. One token, never two: `settings_tab` built from the words
+ * "Settings tab" is precisely how a guess is made.
+ *
+ * `seed` is a prior plan the compiler was told to reuse. A green run re-persists the HEALED plan
+ * and a repair takes its id off a live screen, so an id a seed already uses is grounded too —
+ * pass one only where it can hold a repair (see `compileFromSegments` in ../cli.ts).
+ */
+function ungroundedIds(nl, plan, seed) {
+    const ground = [...proseTokens(nl), ...(seed ? planIds(seed).flatMap(idParts) : [])];
+    return planIds(plan).filter((id) => idParts(id).some((part) => !ground.some((t) => t.includes(part))));
+}
 /**
  * Check a compiled plan against the prose it came from.
  *
  * @param nl   the natural-language test, verbatim
  * @param plan the plan the model just produced
+ * @param seed the prior plan the model was handed to adapt, if any — its ids are not guesses
  * @returns findings; empty means the plan is consistent with the prose. A finding with
  *          `fatal` set means the plan does not cover the test and must not be run.
  */
-function lintPlan(nl, plan) {
+function lintPlan(nl, plan, seed) {
     const findings = [];
     if (FRESH_START_RE.test(nl) && !hasLeafWithFlag(plan, 'launch', 'clear')) {
         findings.push({
@@ -281,6 +367,21 @@ function lintPlan(nl, plan) {
                 '(skip when absent), or behind when (when the screen is one of several known kinds).',
         });
     }
+    // Not fatal: a guess that happens to be right still runs, and a wrong one fails its step
+    // loudly, so the guided recompile is the remedy. The exception is an ABSENCE check (`--gone`,
+    // a guard that skips): it passes on any selector that never matches, a wrong label as much as
+    // a guessed id, so making this rule fatal would not close it.
+    const guessed = ungroundedIds(nl, plan, seed);
+    if (guessed.length > 0) {
+        const named = guessed.slice(0, 5).map((id) => JSON.stringify(id)).join(', ');
+        findings.push({
+            message: `The plan selects by id ${named}${guessed.length > 5 ? ` and ${guessed.length - 5} more` : ''}, but the test ` +
+                `never gives ${guessed.length === 1 ? 'that id' : 'those ids'}. You cannot see the app, so an id the test does not state is a guess — it matches ` +
+                'nothing, and a wait/assert on it fails the test with no repair. Use an id only when the test writes it; ' +
+                'select an element the test names by its label with text:<label>, and do not check something the test ' +
+                'names nothing selectable for.',
+        });
+    }
     if (!coverageChecksEnabled())
         return findings;
     const units = instructionUnits(nl);

package/dist/agent/remote.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeStatus = describeStatus;
 exports.transportReason = transportReason;
 exports.pingServer = pingServer;
+exports.poolNote = poolNote;
 exports.remoteDeviceOp = remoteDeviceOp;
 exports.remoteDeviceList = remoteDeviceList;
 exports.createRemoteBackend = createRemoteBackend;
@@ -105,9 +106,18 @@ function requestWithNodeHttp(url, method, headers, body, timeoutMs) {
 /**
  * Turn a non-2xx into the error the caller sees.
  *
- * The 401/409/503 arms come FIRST and stay class-free on purpose: those describe the
+ * The 401/409/503 arms come FIRST and never rebuild a driver error: those describe the
  * TRANSPORT (wrong key, device leased, nothing attached), not something a driver threw, so
  * there is no device-error identity to restore and their wording is what a user acts on.
+ * Two of them do carry a class of their own, because a parallel suite has to act on the
+ * difference (#147) — both still exit 3:
+ *
+ *  - on the LEASE route (`opts.lease`), 409 and 503 are `NoFreeDeviceError`: the run never
+ *    started. The route decides, not the body — every run mints a fresh token, so a lease can
+ *    be refused but never evicted.
+ *  - elsewhere, a 409 the server tagged `RunEvictedError` is one: the run lost its device
+ *    part-way. That is the ONLY kind a 409 honours. Anything else a body carries is ignored,
+ *    and an untagged 409 (an older server) stays the plain error it always was.
  *
  * Everything else prefers the server's `errorKind`. That field is what stops a `--server` run
  * reading a mid-launch `NoWindowError` as a fatal environment error: the class survives the
@@ -115,16 +125,22 @@ function requestWithNodeHttp(url, method, headers, body, timeoutMs) {
  * `CliError` (issue #80). No field — an older server, or a failure with no class worth
  * naming — falls through to exactly the previous behaviour.
  */
-function describeStatus(status, body, url) {
+function describeStatus(status, body, url, opts = {}) {
     const detail = body?.error ? `: ${body.error}` : '';
     if (status === 401) {
         return new errors_1.CliError(`verikun server rejected the auth key (401)${detail}. Check --auth-key / VERIKUN_SERVER_AUTH_KEY.`, 3);
     }
     if (status === 409) {
-        return new errors_1.CliError(`verikun server device is busy (409)${detail || ' — another run holds the device; retry when it finishes'}.`, 3);
+        const busy = `verikun server device is busy (409)${detail || ' — another run holds the device; retry when it finishes'}.`;
+        if (opts.lease)
+            return new errors_1.NoFreeDeviceError(busy);
+        if (body?.errorKind === 'RunEvictedError')
+            return new errors_1.RunEvictedError(`verikun server ended this run (409)${detail}.`);
+        return new errors_1.CliError(busy, 3);
     }
     if (status === 503) {
-        return new errors_1.CliError(`verikun server has no device attached (503)${detail}.`, 3);
+        const none = `verikun server has no device attached (503)${detail}.`;
+        return opts.lease ? new errors_1.NoFreeDeviceError(none) : new errors_1.CliError(none, 3);
     }
     // The server sends the intended exit code (usage 2 / env 3) in the body; fall
     // back on the HTTP class when it didn't.
@@ -172,6 +188,9 @@ class RemoteTransport {
     base;
     /** One token per backend = one logical run holding the server's device lock. */
     runToken = (0, node_crypto_1.randomUUID)();
+    /** The server has said this run was evicted. Latched, because the request that hears it is
+     *  usually not the step that failed — see ExecBackend.wasEvicted. */
+    evicted = false;
     constructor(opts) {
         this.opts = opts;
         this.base = trimUrl(opts.url);
@@ -214,7 +233,10 @@ class RemoteTransport {
             // exactly the case a caller must not miss (an exhausted install, a dead-device read).
             if (body?.deviceChanged)
                 this.opts.onDeviceChange?.(body.deviceChanged);
-            throw describeStatus(res.status, body, url);
+            const error = describeStatus(res.status, body, url, { lease: path === '/v1/lease' });
+            if (error instanceof errors_1.RunEvictedError || body?.evicted)
+                this.evicted = true;
+            throw error;
         }
         const parsed = await readBody(res);
         if (parsed === null)
@@ -245,6 +267,21 @@ async function pingServer(opts) {
     }
     return health;
 }
+/**
+ * What a `vk server` is serving, and what it has ruled out, in one line from one
+ * `/v1/health`. Carried on every "no free device" so the reader learns WHICH phone left and
+ * the server's own reason, not the lane slot (`host:port#1`) that happened to notice (#147).
+ * A device the server shed keeps its quarantine, which is what makes it nameable here.
+ */
+function poolNote(health) {
+    const serving = health.devices ?? (health.serial ? [health.serial] : []);
+    const count = health.capacity ?? serving.length;
+    const out = serving.length ? ` (${serving.join(', ')})` : '';
+    const ruledOut = health.quarantined?.length
+        ? `; ruled out: ${health.quarantined.map((q) => `${q.serial} (${q.reason})`).join(', ')}`
+        : '';
+    return `pool: ${count} serving${out}${ruledOut}`;
+}
 /**
  * POST /v1/devices/{start,restart,stop}. Standalone beside pingServer rather than on
  * the ExecBackend seam: that seam is the engine's DEVICE WORK (exec/getElements/
@@ -285,6 +322,10 @@ function createRemoteBackend(opts, health) {
         // A failing step is a 200, so this is the ordinary path for a mid-run device death.
         if (res.deviceChanged)
             opts.onDeviceChange?.(res.deviceChanged);
+        // …and for the eviction that death caused: the step keeps the phone's own error, and this
+        // response is the only one that says the run is over (see ExecResponse.evicted).
+        if (res.evicted)
+            t.evicted = true;
         return { code: res.code, error: res.error ? (0, rpc_1.rebuildError)(res.error) : undefined };
     };
     return {
@@ -294,7 +335,16 @@ function createRemoteBackend(opts, health) {
             // together, and a client cannot otherwise tell "old server" from "new server".
             if (health.capacity === undefined)
                 return null;
-            return t.postJson('/v1/lease', {}, HEALTH_TIMEOUT_MS);
+            try {
+                return await t.postJson('/v1/lease', {}, HEALTH_TIMEOUT_MS);
+            }
+            catch (e) {
+                // Say what the pool looks like. `health` was read moments ago, on the way here, and
+                // it is what names a phone that left — the refusal itself only counts devices.
+                if (e instanceof errors_1.NoFreeDeviceError)
+                    throw new errors_1.NoFreeDeviceError(`${e.message} [${poolNote(health)}]`);
+                throw e;
+            }
         },
         async getElements() {
             const res = await t.postJson('/v1/elements', {}, ELEMENTS_TIMEOUT_MS);
@@ -346,6 +396,7 @@ function createRemoteBackend(opts, health) {
             if (code !== 0)
                 throw error ?? new errors_1.CliError(`reset (${command} ${appId}) failed on the server (exit ${code})`, 3);
         },
+        wasEvicted: () => t.evicted,
         async close() {
             // Free the server's device lock so the next command (a fresh run token, e.g.
             // `vk install` then `vk suite` in one CI job) isn't 409'd until the idle

package/dist/cli.js

@@ -48,6 +48,7 @@ exports.compileFromSegments = compileFromSegments;
 exports.obtainPlan = obtainPlan;
 exports.retryAfterDeviceMove = retryAfterDeviceMove;
 exports.terminalFailure = terminalFailure;
+exports.runAiTest = runAiTest;
 exports.laneArgv = laneArgv;
 exports.laneEnv = laneEnv;
 exports.lanesFromFlags = lanesFromFlags;
@@ -1905,7 +1906,14 @@ async function compileFromSegments(segments, key, opts, cost, provider) {
             // FREE, and refusing it over a ceiling we were never about to spend against would fail
             // a test for somebody else's tokens.
             assertBudgetForCompile(cost, opts.maxCostUsd, `compiling ${where} — the test is only partly compiled`);
-            const seed = seedPlan(segKey, where);
+            // A section's entry is only ever raw compile output — a green run re-persists the WHOLE
+            // test's key, never a section's — so an id in it that its own prose never gives can only be
+            // a guess (issue #148), and handing it back as "reuse this" would keep it alive.
+            let seed = seedPlan(segKey, where);
+            if (seed && (0, lint_1.ungroundedIds)(seg.text, seed.plan).length > 0) {
+                (0, output_1.err)(`[ai] ${where}: ignoring a prior plan that guesses ids its prose never gives — compiling fresh`);
+                seed = null;
+            }
             (0, output_1.err)(`[ai] ${where}: compiling with ${opts.model}…${lock.degraded ? ` (${lock.degraded})` : ''}`);
             let compiled;
             try {
@@ -1939,6 +1947,14 @@ async function compileFromSegments(segments, key, opts, cost, provider) {
                 (0, output_1.err)(`[ai] ${where}: the compiled section does not cover its prose (${compiled.plan.steps.length} step(s)) — not caching it; compiling the test as one instead`);
                 return null; // the finally below releases the lock
             }
+            // A guessed id in a FRAGMENT is issue #148 spliced into every test that includes it. Same
+            // answer as a short section: keep it out of the cache and compile the test whole, where the
+            // lint hands the guess back for one guided recompile.
+            const guessed = (0, lint_1.ungroundedIds)(seg.text, compiled.plan);
+            if (guessed.length > 0) {
+                (0, output_1.err)(`[ai] ${where}: the compiled section selects by ids its prose never gives (${guessed.join(', ')}) — not caching it; compiling the test as one instead`);
+                return null; // the finally below releases the lock
+            }
             // INSIDE the lock and before the release: a waiter re-reads the cache the instant the
             // lock disappears, so releasing first would hand it a miss and buy the second compile
             // this whole mechanism exists to prevent.
@@ -2013,7 +2029,10 @@ async function obtainPlan(key, file, opts, cost, provider, segments = []) {
     // sometimes only the test's opening compiles at all. One guided retry is much cheaper
     // than discovering it as a device-run failure several steps later, or (worse, for a
     // truncation) as a pass. Budget is re-checked HERE: the first attempt is already billed.
-    let remaining = (0, lint_1.lintPlan)(key.nl, compiled.plan);
+    //
+    // The seed goes in too: a green run re-persists the HEALED plan, whose repaired ids came off a
+    // live screen, so flagging them would push every new build off a selector the device confirmed.
+    let remaining = (0, lint_1.lintPlan)(key.nl, compiled.plan, seed?.plan);
     if (remaining.length > 0) {
         const feedback = remaining.map((f) => `- ${f.message}`).join('\n');
         (0, output_1.err)(`[ai] compiled plan does not match the test — recompiling once:\n${feedback}`);
@@ -2029,7 +2048,7 @@ async function obtainPlan(key, file, opts, cost, provider, segments = []) {
                 retryFeedback: feedback,
             });
             cost.add(retry.usage, 'compile');
-            const still = (0, lint_1.lintPlan)(key.nl, retry.plan);
+            const still = (0, lint_1.lintPlan)(key.nl, retry.plan, seed?.plan);
             // Keep the retry either way: it was compiled with strictly more information. If it
             // still trips the lint, say so rather than pretending the plan is clean — and for a
             // coverage finding, do not claim it will run, because the gate below rejects it.
@@ -2439,6 +2458,7 @@ async function prefetchArchiveLogs(backend, noLogs = false) {
  * Run one natural-language test through a backend and return DATA — no stdout
  * writes (stdout stays the caller's one result; progress streams to stderr).
  * `vk ai` wraps it with its --json/report output; `vk suite` calls it per test.
+ * Exported for the unit suite.
  */
 async function runAiTest(file, opts, backend, platform, device) {
     const { nl, segments } = readAiTest(file);
@@ -2477,7 +2497,19 @@ async function runAiTest(file, opts, backend, platform, device) {
     // (exit 3 for a broken device), which is what a caller reads as an environment
     // abort — the same verdict `vk suite`'s own reset failure produces.
     if (opts.resetApp) {
-        await backend.reset(opts.resetApp);
+        try {
+            await backend.reset(opts.resetApp);
+        }
+        catch (e) {
+            // The phone this run was dealt had left the pool while idle, and the reset is the first
+            // request to find out — the one the server marks. That is the server's eviction, not a
+            // broken box: a suite re-runs it as a fresh run (#147). Thrown, because no run exists yet
+            // to carry a result.
+            if ((0, errors_1.isEnvError)(e) && !(e instanceof errors_1.RunEvictedError) && backend.wasEvicted?.()) {
+                throw new errors_1.RunEvictedError(`the device this run was dealt had left the pool: ${e.message.split('\n')[0]}`);
+            }
+            throw e;
+        }
         (0, output_1.err)(`[ai] app state reset (${opts.resetApp})`);
     }
     // One explicit run for the whole flow (so rollover can't split the test).
@@ -2525,15 +2557,45 @@ async function runAiTest(file, opts, backend, platform, device) {
             reason: e.message,
             kind: (0, errors_1.isEnvError)(e) ? 'env' : 'fail',
         });
+        let sealed;
         try {
             await prefetchArchiveLogs(backend);
-            run_1.Recorder.archive();
+            sealed = run_1.Recorder.archive();
         }
         catch (sealErr) {
             // Best-effort seal in an error path; surface a failure (the run state may itself be
             // unreadable) but still throw the ORIGINAL error below.
             (0, output_1.err)(`[ai] could not archive the run after a mid-run error (${sealErr.message})`);
         }
+        // An EVICTION is the one mid-run throw that is a RESULT, not an error. The server ended
+        // this run because its phone left the pool — the run is not broken, it is over — and the
+        // caller needs what a result carries: the archive (how far it got, which phone) and the
+        // flag. A parallel suite re-runs it as a fresh run without spending a retry (#147); thrown,
+        // it reached the suite as a bare error with no report and no device. Still exit 3.
+        // An environment throw on a run the server evicted counts too: a worker that died mid-step
+        // answers with an error rather than a result, and the server marks that response.
+        if (e instanceof errors_1.RunEvictedError || ((0, errors_1.isEnvError)(e) && backend.wasEvicted?.())) {
+            const reason = e.message.split('\n')[0];
+            (0, output_1.err)(`[ai] ABORTED — environment: ${reason}`);
+            if (sealed)
+                (0, output_1.err)(`[ai] report: ${sealed.htmlPath}`);
+            return {
+                ok: false,
+                cached,
+                costUsd: Number(cost.usd().toFixed(4)),
+                costLine: cost.summaryLine(),
+                modelRepairs: 0,
+                improvements: [],
+                planSteps: plan.steps.length,
+                runDir: sealed?.dir ?? '',
+                reportHtml: sealed?.htmlPath ?? '',
+                junitXml: sealed?.xmlPath ?? '',
+                state: sealed?.state ?? null,
+                failure: { where: 'run', reason },
+                abortedForEnv: true,
+                evicted: true,
+            };
+        }
         throw e;
     }
     finally {
@@ -2586,6 +2648,11 @@ async function runAiTest(file, opts, backend, platform, device) {
         ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
         ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
         ...(result.abortedForEnv ? { abortedForEnv: true } : {}),
+        // The step that was running when the phone vanished failed with the phone's own error, and
+        // the server shed the phone while answering it: the eviction is heard only by the requests
+        // after it (the failure evidence and the log fetch above). Asked now, and only of an
+        // environment abort — an assertion that failed first is a regression whatever happened next.
+        ...(result.abortedForEnv && backend.wasEvicted?.() ? { evicted: true } : {}),
     };
 }
 async function cmdAi(positionals, flags) {
@@ -2643,6 +2710,8 @@ async function cmdAi(positionals, flags) {
             ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
             ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
             ...(result.abortedForEnv ? { abortedForEnv: true } : {}),
+            // The server ended the run because its phone left: start it again as a fresh run.
+            ...(result.evicted ? { evicted: true } : {}),
         });
     }
     else if (result.reportHtml) {
@@ -2938,6 +3007,12 @@ function laneResult(code, parsed, detail, lane) {
     const str = (k) => (typeof parsed?.[k] === 'string' ? parsed[k] : undefined);
     const num = (k) => (typeof parsed?.[k] === 'number' ? parsed[k] : undefined);
     const yes = (k) => parsed?.[k] === true;
+    // The two lease outcomes a parallel suite must NOT read as a broken box (#147), both exit 3.
+    // Gated on the code too: the exit code is the verdict, and a kind never overrides it.
+    //  - refused at /v1/lease: the child never started a run, so it is no attempt at all;
+    //  - evicted part-way: usually a result document (the run archived), or a thrown one.
+    const noDevice = code === 3 && str('errorKind') === 'NoFreeDeviceError';
+    const evicted = code === 3 && (yes('evicted') || str('errorKind') === 'RunEvictedError');
     const raw = parsed?.failure;
     // A budget / timeout / environment abort comes back as a bare FLAG with no `failure`
     // object — the engine returns it that way, and `toSuiteResult` composes its own wording
@@ -2982,9 +3057,11 @@ function laneResult(code, parsed, detail, lane) {
         // check a TypeError in a new code path reads as an environment failure: the suite
         // probes the lane, finds it healthy, retries, and two in a row retire a perfectly good
         // device via ENV_STREAK_LIMIT.
-        ...((yes('abortedForEnv') || code === 3 || code === 127) && str('errorKind') !== 'Error'
+        ...((yes('abortedForEnv') || code === 3 || code === 127) && str('errorKind') !== 'Error' && !noDevice
             ? { abortedForEnv: true }
             : {}),
+        ...(noDevice ? { noDevice: true } : {}),
+        ...(evicted ? { evicted: true } : {}),
         // Exit 2 is verikun's USAGE code — a flag the child rejected, an unreadable test, a
         // payload the server refused. The serial path reaches this verdict from the thrown
         // CliError (`isRetryableThrow`); across a process boundary the throw is only an exit
@@ -3197,6 +3274,21 @@ async function cmdSuiteParallel(dirArg, flags, pool) {
             claimLanes: (used) => grantLanes(used, platform, pool.elastic, grants),
             runTest: (file, lane) => runLaneTest(file, lane, flags, platform, app),
             preflight: (lane) => lanePreflight(lane, flags, platform),
+            // Is a phone free for this server lane? Asked of /v1/health, which leases nothing: a
+            // lease request that finds nothing free lets the server take over a sibling lane's
+            // quiet lease (see SuiteDeps.serverSlots). A server that does not answer is left for
+            // the lane's own child to report, exactly as before.
+            serverSlots: async (lane) => {
+                if (!lane.server)
+                    return undefined;
+                try {
+                    const health = await (0, remote_1.pingServer)(remoteOptsFrom(lane.server, flags));
+                    return { capacity: health.capacity ?? 1, note: (0, remote_1.poolNote)(health) };
+                }
+                catch {
+                    return undefined;
+                }
+            },
             // `reset` is deliberately NOT wired: against a pooled server a reset issued from
             // here would take its own lease and could land on a different device than the test
             // that follows. `vk ai --reset-app` does it inside the test's own lease instead.
@@ -3682,6 +3774,11 @@ SUITE (run a directory of natural-language tests as one gated suite)
                                       stops the suite once total model spend crosses
                                       it (exit 1). One merged report either way, with
                                       wall-clock reported apart from device time.
+                                      Over --server a lane with no free device waits
+                                      for one; a test whose device left the pool
+                                      re-runs without spending a retry. With no device
+                                      for any lane it stops after
+                                      VERIKUN_SUITE_DEVICE_WAIT_MIN (default 10; exit 3).
 
 SERVER (expose a locally-connected device to remote verikun clients)
   server [--bind addr] [--port n] [--auth-key k] [--devices all|all-android|all-ios|a,b]