verikun 0.29.1 → 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,26 @@ 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

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/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;
@@ -2457,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);
@@ -2495,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).
@@ -2543,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 {
@@ -2604,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) {
@@ -2661,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) {
@@ -2956,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
@@ -3000,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
@@ -3215,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.
@@ -3700,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]

package/dist/errors.js

@@ -6,7 +6,7 @@
 //   2  usage error, ambiguous selector, or a device another job is driving (caller must refine)
 //   3  environment error (adb/simctl missing, no usable device, dump failed)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AmbiguousSelectorError = exports.DUMP_KILLED_MESSAGE = exports.dumpKilledMessage = exports.DumpKilledError = exports.NO_WINDOW_MESSAGE = exports.NoWindowError = exports.TransientReadError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
+exports.AmbiguousSelectorError = exports.RunEvictedError = exports.NoFreeDeviceError = exports.DUMP_KILLED_MESSAGE = exports.dumpKilledMessage = exports.DumpKilledError = exports.NO_WINDOW_MESSAGE = exports.NoWindowError = exports.TransientReadError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.usageError = exports.CliError = void 0;
 exports.isEnvError = isEnvError;
 class CliError extends Error {
     exitCode;
@@ -140,6 +140,44 @@ exports.dumpKilledMessage = dumpKilledMessage;
 exports.DUMP_KILLED_MESSAGE = 'The UI hierarchy dump was killed before it could answer — the device reclaiming memory ' +
     'while an app starts, or another tool holding the one UiAutomation connection. This ' +
     'normally clears within seconds.';
+// --- Remote leases: a run that never got a device, and one that lost its device --------
+//
+// Both are exit 3 like any other environment failure — the exit-code contract does not move
+// and `isEnvError` still holds. They are classes only so a PARALLEL suite can tell them apart
+// from a broken box across a process boundary (`errorKind` in a lane child's --json). Read as
+// ordinary environment failures they were issue #147: a pool that lost one phone recorded
+// failures for tests that never ran, and retired a lane the server would have fed again
+// minutes later.
+/**
+ * A `vk server` refused this run a device: every device is leased (409) or none is serving
+ * (503). Built ONLY for `/v1/lease`, the call a run makes before it does anything, so it
+ * always means the test never started. `vk suite` hands such a test back to its queue and
+ * waits for a device instead of recording a failure.
+ */
+class NoFreeDeviceError extends CliError {
+    constructor(message) {
+        super(message, 3);
+        this.name = 'NoFreeDeviceError';
+    }
+}
+exports.NoFreeDeviceError = NoFreeDeviceError;
+/**
+ * The server ended this run part-way: its device left the pool, was taken over while the run
+ * sat idle, or was power-cycled — and a run is never re-homed onto another phone, because its
+ * earlier steps ran on this one. Only the server knows, so it TAGS the 409 (`errorKind`); an
+ * older server's eviction stays an ordinary environment failure.
+ *
+ * Nothing in the `vk ai` engine may absorb it: every later call is refused the same way, so a
+ * catch that treats it as a transient read turns a lost phone into an "absent" guard or a
+ * failed repair. `vk suite` re-runs the test as a fresh run without spending a retry.
+ */
+class RunEvictedError extends CliError {
+    constructor(message) {
+        super(message, 3);
+        this.name = 'RunEvictedError';
+    }
+}
+exports.RunEvictedError = RunEvictedError;
 /** Selector matched >1 element. Exit 2. Carries the candidates so the agent runner
  *  can ask the model to disambiguate (a heal trigger) instead of aborting. */
 class AmbiguousSelectorError extends CliError {

package/dist/report.js

@@ -278,7 +278,8 @@ const SUITE_STYLE = `
 function suiteAttemptLinks(attempts, linkBase) {
     const links = attempts
         .map((a, i) => {
-        const label = `attempt ${i + 1}`;
+        // Said outright, so nobody goes looking for a flake in a test whose phone was unplugged.
+        const label = `attempt ${i + 1}${a.evicted ? ' (device left the pool)' : ''}`;
         if (!a.id)
             return htmlEsc(label);
         return `<a href="${htmlEsc(`${linkBase}runs/${encodeURIComponent(a.id)}/report.html`)}">${htmlEsc(label)}</a>`;

package/dist/rpc.js

@@ -34,6 +34,15 @@ function describeError(e) {
     if (e instanceof errors_1.NoWindowError) {
         return { kind: 'NoWindowError', name: e.name, message: e.message, exitCode: e.exitCode };
     }
+    // Also before the CliError arm, for a different reader: `mapError` puts this kind in a
+    // lane child's --json, and it is how a parallel suite tells "never got a device" and "lost
+    // its device" from a broken box (#147). The server only ever SENDS the eviction.
+    if (e instanceof errors_1.NoFreeDeviceError) {
+        return { kind: 'NoFreeDeviceError', name: e.name, message: e.message, exitCode: e.exitCode };
+    }
+    if (e instanceof errors_1.RunEvictedError) {
+        return { kind: 'RunEvictedError', name: e.name, message: e.message, exitCode: e.exitCode };
+    }
     if (e instanceof errors_1.CliError) {
         return { kind: 'CliError', name: e.name, message: e.message, exitCode: e.exitCode };
     }
@@ -51,6 +60,10 @@ function rebuildError(d) {
             return new errors_1.NoWindowError(d.message);
         case 'DumpKilledError':
             return new errors_1.DumpKilledError(d.message);
+        case 'NoFreeDeviceError':
+            return new errors_1.NoFreeDeviceError(d.message);
+        case 'RunEvictedError':
+            return new errors_1.RunEvictedError(d.message);
         case 'CliError':
             return new errors_1.CliError(d.message, d.exitCode);
         default: {

package/dist/server-http.js

@@ -15,6 +15,7 @@ class HttpError extends Error {
     exitCode;
     deviceChanged;
     errorKind;
+    evicted;
     constructor(status, message, exitCode = status === 400 || status === 404 || status === 413 ? 2 : 3, 
     /** Set when this request moved the server's device before failing — the client
      *  needs to know the ground shifted even though the answer is an error. */
@@ -23,12 +24,15 @@ class HttpError extends Error {
      *  HttpError is how the identity used to be lost: only `.message` and `.exitCode` were
      *  copied across, so a `NoWindowError` reached the client as a bare `CliError`. Carry it
      *  here and the outer catch can put it on the wire. */
-    errorKind) {
+    errorKind, 
+    /** This request's failure evicted the caller's run (see ExecResponse.evicted). */
+    evicted) {
         super(message);
         this.status = status;
         this.exitCode = exitCode;
         this.deviceChanged = deviceChanged;
         this.errorKind = errorKind;
+        this.evicted = evicted;
         this.name = 'HttpError';
     }
 }

package/dist/server.js

@@ -891,11 +891,14 @@ function buildServer(config) {
      * phone that is now gone, so continuing it elsewhere would produce a run whose steps
      * came from two devices while the report named one. A new run token (a rerun) is served
      * normally — this only closes the door on the run that was interrupted.
+     *
+     * Each keeps what it lost and why, because the run is TOLD: its 409 names the device, and a
+     * parallel suite's warning then names the phone that left rather than a lane slot (#147).
      */
-    const evicted = new Set();
+    const evicted = new Map();
     /**
      * Bounded, because on a long-lived CI server every interrupted run leaves an entry and
-     * only its own `/v1/release` ever removes one. A Set iterates in insertion order, so
+     * only its own `/v1/release` ever removes one. A Map iterates in insertion order, so
      * the front is the stalest — a client that died long ago and will never ask again.
      */
     const EVICTED_CAP = 512;
@@ -906,17 +909,17 @@ function buildServer(config) {
     function evict(token, why) {
         const had = leases.get(token);
         leases.delete(token);
-        evicted.add(token);
+        evicted.set(token, { serial: had?.serial, why });
         // Every eviction is announced. This is the direct cause of the 409 a client then reads
-        // as an environment failure — and of the lane a suite retires over it — and it used to
-        // be the one lease transition that happened in complete silence, so a degrading run
-        // showed a burst of unexplained 409s with nothing anywhere connecting them to the
-        // device that left.
+        // (a parallel suite re-runs the test as a fresh run; an older client read it as an
+        // environment failure and retired a lane over it), and it used to be the one lease
+        // transition that happened in complete silence, so a degrading run showed a burst of
+        // unexplained 409s with nothing anywhere connecting them to the device that left.
         if (had)
             (0, output_1.err)(`[server] lease: run ${token.slice(0, 8)}… evicted from ${had.serial} — ${why}`);
         // `if`, not `while`: this adds exactly one entry, so at most one can be over.
         if (evicted.size > EVICTED_CAP)
-            evicted.delete(evicted.values().next().value);
+            evicted.delete(evicted.keys().next().value);
     }
     function evictHoldersOf(serial, why) {
         for (const [token, lease] of leases)
@@ -1025,11 +1028,14 @@ function buildServer(config) {
      */
     let exclusive = null;
     function busyError(token) {
-        if (token !== undefined && evicted.has(token)) {
+        const lost = token === undefined ? undefined : evicted.get(token);
+        if (lost) {
             // Named plainly, because "device is busy" would send the operator looking for a
-            // racing job that does not exist.
-            return new server_http_1.HttpError(409, 'the device this run was using left the pool and nothing healthy replaced it — ' +
-                'start a fresh run; this one cannot continue on another device', 3);
+            // racing job that does not exist. TAGGED, because the client cannot tell an eviction
+            // from contention any other way: a parallel suite re-runs an evicted test as a fresh
+            // run without spending a retry, but must never do that for a busy pool (#147).
+            return new server_http_1.HttpError(409, `this run lost its device${lost.serial ? ` (${lost.serial})` : ''}: ${lost.why} — ` +
+                'start a fresh run; this one cannot continue on another device', 3, undefined, 'RunEvictedError');
         }
         // An empty pool never reaches here: the deviceless guard in the router answers 503 for
         // every route that takes a lease, and it names `lostDevice` while doing it. So `n` is
@@ -1119,7 +1125,7 @@ function buildServer(config) {
             evict(t, why);
         }
     }
-    async function handleExec(handle, req, res) {
+    async function handleExec(handle, req, res, token) {
         const body = await (0, server_http_1.readBody)(req, EXEC_BODY_CAP);
         let parsed;
         try {
@@ -1160,7 +1166,12 @@ function buildServer(config) {
         }
         catch (e) {
             const changed = await considerFailover(e, 'exec', handle);
-            throw changed ? new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, changed) : e;
+            // Evicted by the failover this very failure triggered: say so on the error itself (#147).
+            const lost = evicted.has(token);
+            if (lost && !changed) {
+                throw new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, undefined, (0, rpc_1.describeError)(e).kind, true);
+            }
+            throw changed ? new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, changed, undefined, lost || undefined) : e;
         }
         const { code, error, step, artifacts, logStart } = outcome;
         (0, output_1.err)(`[server] ${handle.serial} exec ${node.command} ${node.positionals.join(' ')} → exit ${code} (${Date.now() - t0}ms)`);
@@ -1177,13 +1188,17 @@ function buildServer(config) {
             code,
             ...(error ? { error } : {}),
             ...(deviceChanged ? { deviceChanged } : {}),
+            // The failover this failure triggered shed the device and evicted this run. MEASURED on
+            // hardware: this response is the only one that knows — the client's next request is
+            // usually its release, which clears the mark (#147).
+            ...(evicted.has(token) ? { evicted: true } : {}),
             ...(step ? { step } : {}),
             ...(artifacts && Object.keys(artifacts).length ? { artifacts: (0, server_http_1.encodeArtifacts)(artifacts) } : {}),
             ...(logStart ? { logStart } : {}),
         };
         (0, server_http_1.sendJson)(res, 200, payload);
     }
-    async function handleElements(handle, req, res) {
+    async function handleElements(handle, req, res, token) {
         await (0, server_http_1.readBody)(req, EXEC_BODY_CAP); // drain (the body is unused; keeps keep-alive sane)
         try {
             const elements = await handle.elements(); // CliError(3) on dump failure → 500 below
@@ -1198,12 +1213,13 @@ function buildServer(config) {
             // hierarchy from somewhere else is worse than an error. The client's connect probe
             // re-asks after a reported move — see remote.ts's preflight.
             const deviceChanged = await considerFailover(e, 'read', handle);
-            if (!deviceChanged)
+            const lost = evicted.has(token);
+            if (!deviceChanged && !lost)
                 throw e;
             // describeError, not just .message/.exitCode: this wrap is on the path a mid-launch
             // NoWindowError takes, and the engine's guard tells "still drawing" from "box broken"
             // by class alone (issue #80).
-            throw new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, deviceChanged, (0, rpc_1.describeError)(e).kind);
+            throw new server_http_1.HttpError(500, e.message, e instanceof errors_1.CliError ? e.exitCode : 3, deviceChanged, (0, rpc_1.describeError)(e).kind, lost || undefined);
         }
     }
     async function handleLogs(handle, req, res) {
@@ -1771,6 +1787,13 @@ function buildServer(config) {
             (0, server_http_1.sendJson)(res, 200, body);
             return;
         }
+        // A run that was EVICTED is told so first, however empty the pool has since become: it
+        // lost its phone part-way, which is not the same as a new run finding none, and a
+        // parallel suite re-runs only the former as a fresh run (#147). Shedding a pool's last
+        // device is exactly when both are true at once.
+        if (served.size === 0 && evicted.has(token) && (path === '/v1/exec' || path === '/v1/elements' || path === '/v1/logs')) {
+            throw busyError(token);
+        }
         // A deviceless server must not silently fail every command. In-memory check, so
         // the normal path is untouched. NOTE this fires only when the server NEVER
         // resolved a device — one that DIED mid-run still has a non-null binding and keeps
@@ -1811,9 +1834,9 @@ function buildServer(config) {
             return holdingLease(token, () => fn(h));
         };
         if (req.method === 'POST' && path === '/v1/exec')
-            return onLeasedDevice((h) => handleExec(h, req, res));
+            return onLeasedDevice((h) => handleExec(h, req, res, token));
         if (req.method === 'POST' && path === '/v1/elements')
-            return onLeasedDevice((h) => handleElements(h, req, res));
+            return onLeasedDevice((h) => handleElements(h, req, res, token));
         if (req.method === 'POST' && path === '/v1/logs')
             return onLeasedDevice((h) => handleLogs(h, req, res));
         if (req.method === 'POST' && path === '/v1/install') {
@@ -1891,6 +1914,7 @@ function buildServer(config) {
                     exitCode: mapped.exitCode,
                     ...(errorKind ? { errorKind } : {}),
                     ...(mapped.deviceChanged ? { deviceChanged: mapped.deviceChanged } : {}),
+                    ...(mapped.evicted ? { evicted: true } : {}),
                 };
                 (0, server_http_1.sendJson)(res, mapped.status, body);
             }

package/dist/suite.js

@@ -21,6 +21,7 @@
 // The lane itself is executed by cli.ts as a child PROCESS, because exec.ts is spawnSync
 // throughout: tests awaited inside one process would not overlap device I/O at all.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceWaitMs = deviceWaitMs;
 exports.sortTestFiles = sortTestFiles;
 exports.orderTests = orderTests;
 exports.readDurationHints = readDurationHints;
@@ -41,12 +42,40 @@ const wait_1 = require("./wait");
 const version_1 = require("./version");
 /** The implicit single lane, so serial and parallel share one code path. */
 const SERIAL_LANE = { id: '', label: '' };
+/** Default for `VERIKUN_SUITE_DEVICE_WAIT_MIN`. Long enough for the server to take over a
+ *  crashed client's idle lease (5 min) and for its sweep's first few readmission attempts. */
+const DEFAULT_DEVICE_WAIT_MIN = 10;
+/**
+ * How long a suite waits when NO lane can get a device — every phone left the pool, or other
+ * runs hold them all — before it stops with exit 3 and the unrun tests in `notRun`. `0` stops
+ * at once. A lane that waits while another lane is still working is never bounded by this:
+ * the queue drains through the working lane. Mirrors `claimTtlMs`, except that an empty
+ * value means "unset" rather than zero. Exported for the unit suite.
+ */
+function deviceWaitMs(env = process.env) {
+    const raw = env.VERIKUN_SUITE_DEVICE_WAIT_MIN?.trim();
+    const n = raw ? Number(raw) : NaN;
+    return (Number.isFinite(n) && n >= 0 ? n : DEFAULT_DEVICE_WAIT_MIN) * 60_000;
+}
 /** 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;
 /** How often an idle lane re-checks the queue while another lane is still working.
  *  Only reached on the tail of a suite, and only when a requeue is still possible. */
 const IDLE_POLL_MS = 25;
+/** A lane waiting for a device re-checks at the probe cadence, doubling up to this many
+ *  cadences between checks — 30s in production, which is how quickly a readmitted phone is
+ *  noticed. Derived from `probeRetryMs` so the unit suite's cadence shrinks with it. */
+const PARK_BACKOFF_STEPS = 30;
+/** How long a lane that is LOOKING for a device holds a test's header. Whether the look got
+ *  a phone is only known when the child answers, and a refusal answers in well under a second
+ *  (one health read, one lease): printed at once, every refused look announced a test that
+ *  never started. */
+const PROBE_HEADER_DELAY_MS = 2_000;
+/** How many times ONE test may be re-run, without spending a retry, because the server
+ *  evicted it. Enough for two independent blips; a phone that keeps vanishing under the same
+ *  test is a problem worth a red row, so the next eviction counts as an ordinary attempt. */
+const MAX_FREE_RERUNS = 2;
 /**
  * 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
@@ -183,6 +212,7 @@ function toSuiteResult(file, r, durationMs) {
         ...(r.planSteps === undefined ? {} : { planSteps: r.planSteps }),
         modelRepairs: r.modelRepairs,
         ...(r.ok ? {} : { failure: failure ?? 'failed' }),
+        ...(r.evicted ? { evicted: true } : {}),
     };
 }
 /** Compact one attempt for the `attempts` evidence array (pure). */
@@ -193,6 +223,7 @@ function toSuiteAttempt(r) {
         durationMs: r.durationMs,
         costUsd: r.costUsd,
         ...(r.failure ? { failure: r.failure } : {}),
+        ...(r.evicted ? { evicted: true } : {}),
     };
 }
 /**
@@ -208,7 +239,9 @@ function mergeSuiteAttempts(attempts) {
         return last;
     const round = (n) => Number(n.toFixed(4));
     const prior = attempts.slice(0, -1).map(toSuiteAttempt);
-    const flaky = last.ok && prior.some((a) => !a.ok);
+    // An eviction is not a flake: the phone left, the test did not fail. Counting it would send
+    // someone to stabilise a test whose only fault was being mid-run when a cable came loose.
+    const flaky = last.ok && prior.some((a) => !a.ok && !a.evicted);
     return {
         ...last,
         durationMs: attempts.reduce((a, t) => a + t.durationMs, 0),
@@ -302,6 +335,10 @@ function laneCount(available, tests, flags) {
     // Never open a lane with nothing to run — it only adds a device to the report.
     return Math.max(1, Math.min(available, tests, n ?? available));
 }
+/** A wait, for a human: `10m`, `4.2m`, `12s`. */
+function duration(ms) {
+    return ms >= 60_000 ? `${Math.round(ms / 6_000) / 10}m` : `${Math.round(ms / 100) / 10}s`;
+}
 /** Consecutive environment failures that retire a lane even when the probe says the
  *  box is fine. The backstop for a POOL: `deps.preflight` on a remote lane can only ask
  *  whether the SERVER answers, so one dead device behind a healthy server would
@@ -344,6 +381,18 @@ async function cmdSuite(dirArg, flags, deps) {
     let spentUsd = 0;
     let retiredLanes = 0;
     let started = 0;
+    /**
+     * Attempts that travel WITH a file when a lane hands it back for want of a device, so the
+     * lane that picks it up carries on where it stopped: the same attempt count, the same
+     * evidence, the same free re-runs used. Deleted the moment a lane takes the file again.
+     */
+    const carried = new Map();
+    /** Lease slots this suite has in flight, per server — our own half of the device gate. */
+    const reserved = new Map();
+    /** When an attempt last got a device and finished. With no lane busy, a suite whose last
+     *  progress is `waitMs` old is waiting on a device that is not coming. */
+    let lastProgressAt = Date.now();
+    const waitMs = deps.deviceWaitMs ?? deviceWaitMs();
     const tag = (lane) => (parallel && lane.label ? `[suite ${lane.label}]` : '[suite]');
     async function resetApp(lane, label) {
         // Returns the abort reason when the lane should stop (confirmed env break during reset).
@@ -376,21 +425,62 @@ async function cmdSuite(dirArg, flags, deps) {
         (0, output_1.err)(`${tag(lane)} WARN ${warn}`);
         await (0, wait_1.sleep)((deps.probeRetryMs ?? PROBE_RETRY_MS) * (attempt + 1));
     }
-    /** Every attempt at one file, on one lane. */
-    async function runOneTest(file, lane) {
-        // Bounded: a lane that retires re-queues its file, so a plain dispatch counter can
-        // print "(9/8)". Clamp rather than drop the position — it is the only progress signal
-        // a parallel run gives, and an occasional repeat reads better than a lie.
-        (0, output_1.err)(`${tag(lane)} ── (${Math.min(++started, files.length)}/${files.length}) ${file} ──`);
-        const attemptRows = [];
+    /** Every attempt at one file, on one lane. `probing`: the lane is waiting for a device, and
+     *  this dispatch is a look — see PROBE_HEADER_DELAY_MS. */
+    async function runOneTest(file, lane, probing = false) {
+        // A SERVER lane is a slot, not a device: whether a phone is free for it is the server's
+        // answer, asked before every dispatch (see SuiteDeps.serverSlots). Keyed on the wiring,
+        // never on `parallel` — `--concurrency 1` against a pooled server still leases per test.
+        const gated = !!(deps.serverSlots && lane.server);
+        const prior = carried.get(file);
+        carried.delete(file);
+        let announced = false;
+        const announce = () => {
+            if (announced)
+                return;
+            announced = true;
+            // Bounded: a lane that retires re-queues its file, so a plain dispatch counter can
+            // print "(9/8)". Clamp rather than drop the position — it is the only progress signal
+            // a parallel run gives, and an occasional repeat reads better than a lie. A file picked
+            // back up after a hand-back was counted when it first ran.
+            if (prior)
+                (0, output_1.err)(`${tag(lane)} ── ${file} (continued) ──`);
+            else
+                (0, output_1.err)(`${tag(lane)} ── (${Math.min(++started, files.length)}/${files.length}) ${file} ──`);
+        };
+        // A gated lane says nothing until it has a device, or a lane waiting for one would print
+        // a header every time it looked.
+        if (!gated)
+            announce();
+        const attemptRows = prior?.rows ?? [];
+        let freeReruns = prior?.freeReruns ?? 0;
+        /** The attempt whose "retry k/N" line a gated lane has printed — the header is said once
+         *  per test, the retry line once per attempt. */
+        let saidFor = -1;
         let envFlavoured = false;
         const merge = () => attemptRows.length ? mergeSuiteAttempts(attemptRows) : undefined;
-        for (let attempt = 0; attempt <= retries; attempt++) {
+        /** Did any attempt on THIS dispatch get a device and run? */
+        let ranHere = false;
+        /** No device for this attempt: nothing is recorded and nothing is spent — not a retry, not
+         *  a streak tick — and whatever came before rides back to the queue with the file (#147). */
+        const handBack = (attempt, reason) => {
+            if (attemptRows.length || attempt > 0 || freeReruns > 0)
+                carried.set(file, { rows: attemptRows, attempt, freeReruns });
+            // A dispatch that never ran never held a place in the run order.
+            if (announced && !prior && !attemptRows.length)
+                started -= 1;
+            return { handBack: reason, ...(ranHere ? { ran: true } : {}) };
+        };
+        for (let attempt = prior?.attempt ?? 0; attempt <= retries; attempt++) {
             // The last attempt is where a retryable failure becomes the verdict: a confirmed
             // env break retires the lane, anything else stands as this test's failed row.
             const lastAttempt = attempt === retries;
-            if (attempt > 0)
-                (0, output_1.err)(`${tag(lane)} retry ${attempt}/${retries} for ${file}`);
+            const retryLine = () => {
+                if (attempt > 0)
+                    (0, output_1.err)(`${tag(lane)} retry ${attempt}/${retries} for ${file}`);
+            };
+            if (!gated)
+                retryLine();
             // Re-isolate before EVERY attempt — between tests and between retries alike.
             const resetBreak = await resetApp(lane, attempt > 0 ? ' (retry)' : '');
             if (resetBreak) {
@@ -401,11 +491,71 @@ async function cmdSuite(dirArg, flags, deps) {
                 // With no attempt row this test never ran, so the caller re-queues it.
                 return { row: merge(), envBreak: `reset failed: ${resetBreak}` };
             }
+            let slot;
+            if (gated) {
+                const server = lane.server;
+                const slots = await deps.serverSlots(lane);
+                const inUse = reserved.get(server) ?? 0;
+                // Check and reserve with NO `await` in between: two lanes waking together must not
+                // both see the one free phone and both ask for it, because the loser's lease request
+                // is exactly what lets the server take over a quiet sibling's phone.
+                if (slots && slots.capacity <= inUse)
+                    return handBack(attempt, slots.note);
+                reserved.set(server, inUse + 1);
+                slot = server;
+            }
+            const say = () => {
+                announce();
+                if (saidFor === attempt)
+                    return;
+                saidFor = attempt;
+                retryLine();
+            };
+            // A look says nothing until its child has plainly got a phone; any other gated dispatch
+            // announces now, before the child's own output starts streaming.
+            const held = gated && probing ? setTimeout(say, PROBE_HEADER_DELAY_MS) : undefined;
+            if (gated && !probing)
+                say();
             const t0 = Date.now();
             try {
-                const r = await deps.runTest((0, node_path_1.join)(dir, file), lane);
+                let r;
+                try {
+                    r = await deps.runTest((0, node_path_1.join)(dir, file), lane);
+                }
+                finally {
+                    clearTimeout(held);
+                    // Only the child holds a lease; the re-probes below do not, so neither does the slot.
+                    if (slot) {
+                        const n = (reserved.get(slot) ?? 1) - 1;
+                        if (n > 0)
+                            reserved.set(slot, n);
+                        else
+                            reserved.delete(slot);
+                    }
+                }
+                // Refused at the lease (the gate raced another run, or a job outside this suite holds
+                // the phones). The test never started, so this was never an attempt.
+                if (r.noDevice)
+                    return handBack(attempt, r.failure?.reason ?? 'the server had no free device');
+                if (gated)
+                    say(); // a look that got its phone, and finished inside the header's hold
+                ranHere = true;
+                lastProgressAt = Date.now();
                 attemptRows.push(toSuiteResult(file, r, Date.now() - t0));
                 envFlavoured = !!r.abortedForEnv;
+                // The server ended this run because its phone left the pool. Neither the test's fault
+                // nor this lane's: start it again as a fresh run without spending a retry. Only on a
+                // server lane, where each attempt is a new run token — the serial path's single token
+                // is as dead as its phone, and aborts on the re-probe below exactly as it did.
+                if (r.evicted && lane.server && freeReruns < MAX_FREE_RERUNS) {
+                    freeReruns += 1;
+                    const warn = `${file}: its device ${r.device ?? '(unknown)'} left the pool mid-run — re-run as a fresh run ` +
+                        `(${freeReruns}/${MAX_FREE_RERUNS}, not counted toward --retries)`;
+                    warnings.push(warn);
+                    (0, output_1.err)(`${tag(lane)} WARN ${warn}`);
+                    attempt -= 1;
+                    continue;
+                }
                 if (r.abortedForEnv) {
                     const broken = await stillBroken(deps, lane);
                     if (broken) {
@@ -423,6 +573,10 @@ async function cmdSuite(dirArg, flags, deps) {
                     break;
             }
             catch (e) {
+                if (gated)
+                    say(); // a look whose child threw inside the header's hold still ran a test
+                ranHere = true;
+                lastProgressAt = Date.now();
                 // 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. Out of attempts, a confirmed env break retires the lane.
@@ -466,6 +620,47 @@ async function cmdSuite(dirArg, flags, deps) {
         }
         stop ??= { reason, kind: 'environment' };
     }
+    /**
+     * Wait for this lane's next look at the queue, re-checking every IDLE_POLL_MS whether to
+     * stop waiting altogether — so a waiting lane neither holds a finished suite open nor
+     * sleeps through its end. 'look' means try the queue again.
+     */
+    async function waitForDevice(park) {
+        for (;;) {
+            if (stop)
+                return 'done';
+            // Nothing left to run and nobody running: the suite finished without this lane.
+            if (!queue.length && busyLanes === 0)
+                return 'done';
+            // Nobody is running, and nothing has for the whole wait: every lane is waiting on a
+            // device that is not coming. That stops the SUITE, with one reason — not one retirement
+            // per lane, each claiming its tests "move to the others" who are waiting too.
+            if (busyLanes === 0 && Date.now() - lastProgressAt >= waitMs) {
+                // One last look first, unless one has happened since the deadline: backed off, the
+                // previous look may be half the wait old, and a phone that came back in between would
+                // otherwise never be seen — the suite exiting 3 to say none became free.
+                if (queue.length && park.lastLookAt < lastProgressAt + waitMs)
+                    return 'look';
+                stop ??= {
+                    reason: `no device became free${waitMs > 0 ? ` for ${duration(waitMs)}` : ''} — ${park.reason}`,
+                    kind: 'environment',
+                };
+                return 'done';
+            }
+            if (queue.length && Date.now() >= park.nextAt)
+                return 'look';
+            await (0, wait_1.sleep)(IDLE_POLL_MS);
+        }
+    }
+    /** One warning per waiting spell, not one per look: how long, and the server's reason.
+     *  `ran` is the test the lane finally got a device for — reported once it is over, which is
+     *  the first moment the spell is known to have ended. */
+    function endPark(lane, park, ran) {
+        const waited = duration(Date.now() - park.since);
+        const warn = `${lane.label || 'the suite'} waited ${waited} for a free device — ${park.reason}`;
+        warnings.push(warn);
+        (0, output_1.err)(`${tag(lane)} ${ran ? `${ran} ran after this lane waited ${waited} for a free device` : `stopped waiting for a device after ${waited}`}`);
+    }
     /**
      * One lane, pulling from the shared queue until it is empty, the lane is retired, or
      * the suite stops. This — not a fixed partition — is what absorbs the duration spread:
@@ -474,9 +669,23 @@ async function cmdSuite(dirArg, flags, deps) {
     let busyLanes = 0;
     async function laneWorker(lane) {
         let envStreak = 0;
+        // Set while this lane has no device to run on. A PARKED lane is not busy and holds no
+        // file: whatever it could not start went back to the front of the queue for any lane.
+        let park;
+        const cadence = Math.max(IDLE_POLL_MS, deps.probeRetryMs ?? PROBE_RETRY_MS);
         for (;;) {
-            if (stop)
+            if (stop) {
+                if (park)
+                    endPark(lane, park);
                 return;
+            }
+            if (park) {
+                if ((await waitForDevice(park)) === 'done') {
+                    endPark(lane, park);
+                    return;
+                }
+                park.lastLookAt = Date.now();
+            }
             const file = queue.shift();
             if (file === undefined) {
                 // An empty queue is NOT the end while another lane is still working: a lane that
@@ -485,8 +694,12 @@ async function cmdSuite(dirArg, flags, deps) {
                 // is the one outcome a gate must never produce. Poll rather than signal: the
                 // wait only ever happens on the tail of a suite, and a condition variable here
                 // would be more machinery than the case is worth.
-                if (busyLanes === 0)
+                if (busyLanes === 0) {
+                    // A waiting lane whose look lost the last file to a sibling still reports its wait.
+                    if (park)
+                        endPark(lane, park);
                     return;
+                }
                 await (0, wait_1.sleep)(IDLE_POLL_MS);
                 continue;
             }
@@ -494,7 +707,7 @@ async function cmdSuite(dirArg, flags, deps) {
             let outcome;
             const startedTest = Date.now();
             try {
-                outcome = await runOneTest(file, lane);
+                outcome = await runOneTest(file, lane, park !== undefined);
             }
             catch (e) {
                 // The file is already off the queue, so an escaping throw would erase this test
@@ -507,6 +720,35 @@ async function cmdSuite(dirArg, flags, deps) {
             finally {
                 busyLanes -= 1;
             }
+            if (outcome.handBack !== undefined) {
+                // No device: back to the FRONT, so whichever lane frees first runs it next and the
+                // longest-first order holds. This lane waits, backing off; it neither fails the test
+                // nor pulls the next one only to be refused again (#147).
+                queue.unshift(file);
+                const now = Date.now();
+                // A look that RAN a test was working, not waiting: that spell is over, and a new one
+                // starts — its run time is not waiting time.
+                if (park && outcome.ran) {
+                    endPark(lane, park, file);
+                    park = undefined;
+                }
+                if (!park) {
+                    park = { since: now, reason: outcome.handBack, delayMs: cadence, nextAt: now + cadence, lastLookAt: now };
+                    (0, output_1.err)(`${tag(lane)} no free device — ${outcome.handBack}; ${file} goes back to the queue and this lane waits for one`);
+                }
+                else {
+                    // The LATEST reason: the pool may have changed since the spell began, and the give-up
+                    // and the warning should name what the server says now.
+                    park.reason = outcome.handBack;
+                    park.delayMs = Math.min(park.delayMs * 2, cadence * PARK_BACKOFF_STEPS);
+                    park.nextAt = now + park.delayMs;
+                }
+                continue;
+            }
+            if (park) {
+                endPark(lane, park, file);
+                park = undefined;
+            }
             if (outcome.row) {
                 results.push(outcome.row);
                 spentUsd += outcome.row.costUsd;
@@ -526,6 +768,8 @@ async function cmdSuite(dirArg, flags, deps) {
             // Only a ceiling that actually STOPS something is an abort. Without the queue
             // check, a suite whose last test tips the total over its budget reports ABORTED
             // with an empty `notRun` and exits 1 — a red gate on a run where every test passed.
+            // (A file handed back mid-retry carries its spend with it, so that spend is counted
+            // when its row lands — at most one attempt late.)
             if (maxSuiteCost !== undefined && spentUsd >= maxSuiteCost && queue.length > 0) {
                 stop ??= {
                     reason: `suite cost ceiling $${maxSuiteCost} reached (spent $${spentUsd.toFixed(4)})`,
@@ -546,6 +790,16 @@ async function cmdSuite(dirArg, flags, deps) {
         warnings.push(warn);
         (0, output_1.err)(`[suite] WARN ${warn}`);
     }
+    // A file handed back with attempts already on it RAN, so it is a row — it is only still
+    // queued because the suite stopped before any lane could take it again, and a file must be
+    // in exactly one of `tests` and `notRun`.
+    for (const [file, c] of carried) {
+        const at = queue.indexOf(file);
+        if (at < 0 || !c.rows.length)
+            continue;
+        queue.splice(at, 1);
+        results.push(mergeSuiteAttempts(c.rows));
+    }
     // Belt and braces: work left in the queue with nothing explaining why would be a
     // silently short suite. Every real path (retirement, budget) has already set `stop`.
     if (!stop && queue.length) {

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.29.1';
+exports.VERSION = '0.30.0';

package/package.json

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