verikun 0.21.1 → 0.22.1

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

@@ -482,7 +482,7 @@ draft-first flow.
 - `0` success / found / assertion passed
 - `1` not found / assertion failed / wait timeout
 - `2` usage error **or ambiguous selector** (refine it or add `--index N`)
-- `3` environment error (no device, adb/idb missing, hierarchy dump failed) — for
+- `3` environment error (no usable device, adb/idb missing, hierarchy dump failed) — for
   `ai`/`suite`/`install`/`server` the toolchain is verified up front, so this arrives
   immediately with an install hint rather than mid-flow
 
@@ -498,7 +498,12 @@ draft-first flow.
 - **`vk device set` from a plain shell stays applied.** Inside `batch`/`ai`/`suite` it is
   restored automatically even if the flow dies, but a one-off `vk device set airplane=on`
   is yours to `vk device reset` — don't strand someone's phone offline.
-- **One device auto-resolves.** Multiple → pass `-d <serial>` or set `VERIKUN_DEVICE`.
+- **The device picks itself, and won't collide with another agent.** With several attached,
+  `vk` takes one no other job is driving and notes it on stderr. Exit `2` means every device
+  is genuinely busy (the message names each holder) — pass `-d <serial>`, wait, or
+  `vk device release <serial>` if that job is gone. `vk devices` shows who holds what.
+  Naming a busy device with `-d` is refused, on purpose: two jobs on one phone corrupt both
+  runs, and it surfaces as a bogus assertion failure. `VERIKUN_NO_CLAIM=1` opts out entirely.
 - **`vk text` opens the keyboard.** Use `--enter` to submit, or `vk back` to
   dismiss it before re-inspecting (it can cover elements).
 - **Unicode/emoji** may not type via `adb input text` (an Android limitation);

package/CHANGELOG.md

@@ -6,6 +6,40 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.22.1] - 2026-08-15
+
+### Added
+- **The Flutter fixture raises a real system permission dialog** (`@vk_permission`, Android
+  only), so [#79] reproduces on demand.
+
+### Fixed
+- **Hierarchy reads now see a window another app opens on top** — a runtime-permission dialog is
+  no longer invisible to the companion. ([#79])
+
+[#79]: https://github.com/ddikman/verikun/issues/79
+
+## [0.22.0] - 2026-08-15
+
+### Added
+- **Device claims**: `vk` now picks a device no other job is driving; a busy one is refused
+  with exit `2`. Writes `~/.verikun/devices/`; `VERIKUN_NO_CLAIM=1` opts out. ([#49])
+- **`vk devices`**: a `USED BY` column names the job holding each device; `--json` gains
+  `claim`. ([#49])
+- **`vk device release [serial]`**: hands a device back without waiting for its claim to go
+  stale. ([#49])
+
+### Changed
+- **Several attached devices no longer exits `2`** — a free one is auto-selected. Pass
+  `--device` to pin it, as before. ([#49])
+- **Changelog entries are now one line each**, per the new `changelog-entry` skill — root cause,
+  benchmarks and rationale move to the PR body and `docs/`.
+
+### Fixed
+- **Failure evidence**: a step that could not resolve a device printed its error three times;
+  capture is now skipped when there is no screen to photograph.
+
+[#49]: https://github.com/ddikman/verikun/issues/49
+
 ## [0.21.1] - 2026-08-13
 
 ### Fixed

package/README.md

@@ -62,10 +62,10 @@ There is also no need for an MCP here: verikun runs locally with all its depende
 |---|---|
 | **Getting started** | [Installation](https://ddikman.github.io/verikun/getting-started/installation/) · [Your first test](https://ddikman.github.io/verikun/getting-started/your-first-test/) · [Using it from an AI agent](https://ddikman.github.io/verikun/getting-started/using-from-an-agent/) |
 | **Guides** | [Writing test cases](https://ddikman.github.io/verikun/guides/writing-test-cases/) · [Natural-language tests](https://ddikman.github.io/verikun/guides/natural-language-tests/) · [Suites](https://ddikman.github.io/verikun/guides/suites/) · [Remote devices & CI](https://ddikman.github.io/verikun/guides/remote-devices-and-ci/) · [iOS setup](https://ddikman.github.io/verikun/guides/ios-setup/) · [Platform support](https://ddikman.github.io/verikun/guides/platform-support/) · [Troubleshooting](https://ddikman.github.io/verikun/guides/troubleshooting/) |
-| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
+| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
 | **Internals** | [Architecture](https://ddikman.github.io/verikun/internals/architecture/) · [Core principles](https://ddikman.github.io/verikun/internals/core-principles/) · [Plan IR & the replay engine](https://ddikman.github.io/verikun/internals/plan-ir-and-engine/) · [Contracts](https://ddikman.github.io/verikun/internals/contracts/) · [Contributing](https://ddikman.github.io/verikun/internals/contributing/) |
 
-**Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error or ambiguous selector · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/).
+**Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error, ambiguous selector, or a device another job is driving · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/). Parallel agents share a host-level [device claim](https://ddikman.github.io/verikun/reference/device-claims/) so two jobs do not silently land on the same phone.
 
 ## Feedback — help improve verikun
 

package/dist/cli.js

@@ -61,6 +61,7 @@ const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
 const adb_1 = require("./drivers/adb");
 const settings_1 = require("./device/settings");
+const claims_1 = require("./device/claims");
 const selector_1 = require("./ui/selector");
 const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
@@ -404,6 +405,15 @@ function cmdDevices(ctx) {
     catch (e) {
         (0, output_1.err)(`devices: iOS backend unavailable (${e.message})`);
     }
+    // Who is driving what. Read-only: listing the pool must never claim a device, which is
+    // what makes `vk devices` (and `vk doctor`) safe to run while surveying a busy host.
+    if ((0, claims_1.claimsEnabled)()) {
+        for (const d of allDevices) {
+            const claim = (0, claims_1.summarize)(d.serial);
+            if (claim)
+                d.claim = claim;
+        }
+    }
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
         (0, output_1.json)(allDevices);
         return 0;
@@ -431,6 +441,10 @@ function formatDeviceTable(devices) {
         { header: 'STATE', get: (d) => d.state },
         { header: 'MODEL', get: (d) => d.model ?? '', optional: true },
         { header: 'PRODUCT', get: (d) => d.product ?? '', optional: true },
+        // Optional like the rest, which is load-bearing twice over: nothing changes for a
+        // single-user host where no device is ever claimed, and `VERIKUN_NO_CLAIM=1` renders
+        // exactly the table it always did.
+        { header: 'USED BY', get: (d) => d.claim?.by ?? '', optional: true },
         { header: 'NOTE', get: (d) => d.note ?? '', optional: true },
     ];
     // Drop optional columns that no device populates (e.g. NOTE for an Android-only list).
@@ -493,17 +507,39 @@ async function cmdDoctor(ctx) {
         return 3;
     const devices = ctx.driver.listDevices();
     const usable = devices.filter((d) => d.state === 'device');
+    const claims = (0, claims_1.claimsEnabled)();
+    // Read-only, like `vk devices`: doctor surveys the host, it never takes a device.
+    const heldByOther = (serial) => {
+        const c = claims ? (0, claims_1.summarize)(serial) : undefined;
+        return c && !c.mine ? c : undefined;
+    };
     (0, output_1.out)(`devices: ${devices.length} attached, ${usable.length} usable`);
-    for (const d of devices)
-        (0, output_1.out)(`  ${d.serial} ${d.state}${d.model ? ` (${d.model})` : ''}`);
+    for (const d of devices) {
+        const claim = claims ? (0, claims_1.summarize)(d.serial) : undefined;
+        (0, output_1.out)(`  ${d.serial} ${d.state}${d.model ? ` (${d.model})` : ''}${claim ? `  [${claim.by}]` : ''}`);
+    }
     let ok = true;
-    if (usable.length !== 1 && !ctx.device) {
-        (0, output_1.err)(usable.length ? '  -> multiple devices: pass --device for interaction commands' : '  -> no usable device');
+    const free = usable.filter((d) => !heldByOther(d.serial));
+    if (!usable.length) {
+        (0, output_1.err)('  -> no usable device');
+        ok = false;
+    }
+    else if (!ctx.device && !free.length) {
+        // Every device is busy. Advisory-shaped but genuinely blocking, so it still fails:
+        // an interaction command run right now would exit 2, and doctor exists to say so first.
+        (0, output_1.err)('  -> every attached device is claimed by another job — `verikun devices` shows who');
         ok = false;
     }
-    if (usable.length === 1 || ctx.device) {
+    else if (!ctx.device && !claims && usable.length > 1) {
+        (0, output_1.err)('  -> multiple devices: pass --device for interaction commands');
+        ok = false;
+    }
+    // Check the device an interaction command would actually land on: the one named, else
+    // the first FREE one (which is what auto-selection picks), not merely the first attached.
+    const target = ctx.device || free[0]?.serial;
+    if (target) {
         try {
-            const serial = ctx.device || usable[0].serial;
+            const serial = target;
             const keys = ['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale'];
             const get = (k) => (0, exec_1.runText)(adb, ['-s', serial, 'shell', 'settings', 'get', 'global', k]).stdout.trim();
             const vals = keys.map(get);
@@ -979,7 +1015,7 @@ function cmdClear(ctx) {
 //    of applying dark mode and then dying — a half-applied device is worse than none.
 //  - SNAPSHOT FIRST. The pre-change value is persisted before the change is made, so
 //    `device reset` can undo it even from a later process.
-const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps\n' +
+const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps | device release [serial]\n' +
     `Keys: ${settings_1.SETTING_KEYS.join(', ')}`;
 function cmdDevice(ctx) {
     const sub = (ctx.positionals[0] ?? '').toLowerCase();
@@ -994,10 +1030,43 @@ function cmdDevice(ctx) {
             return deviceReset(ctx, rest);
         case 'caps':
             return deviceCaps(ctx);
+        case 'release':
+            return deviceRelease(ctx, rest);
         default:
             throw new errors_1.CliError((sub ? `Unknown 'device' subcommand '${sub}'.\n` : '') + DEVICE_USAGE, 2);
     }
 }
+/**
+ * Hand a device back to the pool. The break-glass named in every "in use by" refusal:
+ * a crashed job's claim expires on its own, but waiting out the TTL is the one thing an
+ * operator should never be forced to do just to get on with their run.
+ *
+ * Deliberately releases someone ELSE's claim too, naming them — you had to type the
+ * serial, and refusing here would leave no way to recover a stuck device at all. Resolves
+ * the device WITHOUT going through the driver, so it works even when the claim being
+ * cleared is the very thing that would refuse the resolve.
+ */
+function deviceRelease(ctx, args) {
+    const serial = args[0] || ctx.device;
+    if (!serial) {
+        throw new errors_1.CliError('Usage: verikun device release <serial>  (or pass --device / set VERIKUN_DEVICE)', 2);
+    }
+    if (!(0, claims_1.claimsEnabled)()) {
+        (0, output_1.err)('device claims are disabled (VERIKUN_NO_CLAIM) — nothing to release');
+        return 0;
+    }
+    const released = (0, claims_1.releaseClaim)(serial);
+    if ((0, args_1.flagBool)(ctx.flags, 'json')) {
+        (0, output_1.json)({ serial, released: !!released, ...(released ? { was: released } : {}) });
+    }
+    else if (released) {
+        (0, output_1.out)(`released ${serial} (was held by ${(0, claims_1.describeClaim)(released)})`);
+    }
+    else {
+        (0, output_1.out)(`${serial} was not claimed`);
+    }
+    return 0;
+}
 /** Render a setting value for humans/JSON; a platform that cannot answer says so. */
 const showValue = (v) => v ?? 'n/a';
 function deviceSet(ctx, args) {
@@ -1197,6 +1266,10 @@ function cmdRun(positionals, flags, platform, device) {
         case 'stop':
         case 'discard': {
             const cleared = run_1.Recorder.clear();
+            // The run is over, so the device goes back to the pool now rather than in TTL
+            // minutes. `mineOnly` because a run can only ever hand back its own device.
+            if (cleared?.device)
+                (0, claims_1.releaseClaim)(cleared.device, { mineOnly: true });
             if (asJson)
                 (0, output_1.json)({ cleared: cleared?.id ?? null });
             else
@@ -1226,6 +1299,9 @@ function cmdRun(positionals, flags, platform, device) {
                 }
             }
             const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive(positionals[1], { noLogs, fetchLogs });
+            // Archived means finished: release after log capture, which still needs the device.
+            if (state.device)
+                (0, claims_1.releaseClaim)(state.device, { mineOnly: true });
             const { passed, failed } = tally(state.steps);
             if (asJson) {
                 (0, output_1.json)({
@@ -1374,6 +1450,9 @@ async function cmdBatch(positionals, batchFlags) {
         (0, output_1.err)('[verikun] batch: no commands to run');
         return 0;
     }
+    // One process drives the whole batch, so its pid is exact evidence that the device is
+    // still in use — a `kill -9` hands it straight back instead of parking it for the TTL.
+    (0, claims_1.setProcessScoped)(true);
     // The finally is what makes `device set` safe to use in a batch: a line that fails
     // (or a ^C) still puts the device back, instead of leaving it offline or rotated.
     try {
@@ -1413,6 +1492,7 @@ async function cmdBatch(positionals, batchFlags) {
                 /* the device may be exactly why we are unwinding — never mask the real error */
             }
         }
+        (0, claims_1.releaseOwnClaims)();
     }
 }
 function parseAiOptions(flags) {
@@ -1855,6 +1935,7 @@ async function cmdAi(positionals, flags) {
         throw new errors_1.CliError('Usage: verikun ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--server url] [--show-plan] [--recompile]', 2);
     }
     const opts = parseAiOptions(flags);
+    (0, claims_1.setProcessScoped)(true); // one process for the whole run — see claims.ts's isLive
     // --show-plan: compile (or cache-hit) and print the IR — no device, no backend.
     if ((0, args_1.flagBool)(flags, 'show-plan')) {
         const nl = readAiTest(file);
@@ -1875,6 +1956,7 @@ async function cmdAi(positionals, flags) {
         // otherwise an unattended run leaves the phone offline or in dark mode.
         await restoreDeviceOverrides(backend);
         await backend.close?.(); // frees a remote server's device lock for the next command
+        (0, claims_1.releaseOwnClaims)(); // and the host-level claim, so the next job can have the device
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
         (0, output_1.json)({
@@ -1934,6 +2016,7 @@ async function cmdSuiteEntry(positionals, flags) {
     if (!dirArg)
         throw new errors_1.CliError('Usage: verikun suite <dir> [--app <id>] [--server url] [--name n] [--retries n] [--json]', 2);
     const opts = parseAiOptions(flags);
+    (0, claims_1.setProcessScoped)(true); // one process for the whole suite — see claims.ts's isLive
     // Pre-flight the provider BEFORE touching any device/server: every test needs it
     // to compile (on a cache miss) or to repair at runtime.
     if (!providerAvailable(opts.model)) {
@@ -1961,6 +2044,7 @@ async function cmdSuiteEntry(positionals, flags) {
     finally {
         await restoreDeviceOverrides(backend);
         await backend.close?.();
+        (0, claims_1.releaseOwnClaims)();
     }
 }
 // ---------------------------------------------------------------------------
@@ -2113,6 +2197,12 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
             catch {
                 /* surfaced by the command handler below */
             }
+            // Keep this job's device claim alive. Deliberately NOT gated on the recorder:
+            // `Recorder.beginStep` returns null under VERIKUN_NO_RUN=1 (which the e2e suite
+            // sets), and hanging the heartbeat off it would silently stop claims from being
+            // refreshed for exactly the runs that exercise them.
+            if (serial)
+                (0, claims_1.touchClaim)(serial, platform);
             recorder = run_1.Recorder.beginStep(command, positionals, flags, platform, device, serial, driver);
         }
     }
@@ -2153,6 +2243,10 @@ async function executeForServer(command, positionals, flags, driver, platform) {
     catch {
         /* surfaced by the command handler below */
     }
+    // A server holds one device for its whole life, but its claim still has to look alive
+    // to everyone else on the host — refresh it per request, the same as a local step.
+    if (serial)
+        (0, claims_1.touchClaim)(serial, platform);
     // Sample the device clock up front so the caller's run can set logStart (the
     // ephemeral recorder never persists RunState). Best-effort — empty/unavailable
     // just means archive / vk log fall back to last-N.
@@ -2290,6 +2384,9 @@ DEVICE STATE (change the device the app runs on, then put it back)
                                       equivalent where it doesn't
                                       Refuses \`airplane=on\` over wireless adb (it would cut
                                       this very connection); --allow-wireless overrides.
+  device release [serial] [--json]    Hand a claimed device back to the pool. Claims
+                                      expire on their own; this is for when you don't
+                                      want to wait. See \`devices\` for who holds what.
 
 BATCH (script many commands in one process)
   batch [--file path] [--quiet]       Run newline-separated commands — from --file,
@@ -2351,7 +2448,8 @@ SERVER (expose a locally-connected device to remote verikun clients)
   VERIKUN_SERVER_AUTH_KEY) to ai/suite/install. The server's device+platform apply.
 
 ENVIRONMENT
-  devices [--json]                    List attached devices/simulators
+  devices [--json]                    List attached devices/simulators, and which job is
+                                      already driving each (USED BY)
   doctor [--fix]                      Diagnose adb/device, and warn if this CLI or the
                                       Claude Code plugin is out of date (a warning only —
                                       it never changes the exit code). --fix disables

package/dist/companion/dump-match.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Does the companion's dump agree with the platform's own?
+ *
+ * This is the standard `calibrate()` holds the companion to before trusting a single one of
+ * its reads. It used to be plain string equality, and that is still the fast path — but
+ * equality turned out to be stricter than the property it was standing in for, and strictly
+ * enough to reject a companion that was right.
+ *
+ * The property that actually matters is TAP SAFETY: verikun taps the centre of a node the
+ * dump reported, so every node the companion serves must be one the platform would have
+ * served, with the same bounds. Byte equality implies that. It also demands something extra
+ * and unrelated — that the companion reproduce every node the platform emitted, including
+ * decor nobody can touch — and that is what broke.
+ *
+ * MEASURED (issue #79). Asking the accessibility layer for window information is what stops
+ * a long-lived connection serving a stale window, but it also makes Android clamp node
+ * bounds to the app window rather than the display. On a Pixel 6 emulator (Android 14) that
+ * drops exactly one node from the dump, `android:id/navigationBarBackground` at
+ * [0,2274][1080,2400] — not clickable, not focusable, and below every pixel the app owns.
+ * Every other node, root included, stayed byte-identical. Equality still said no, so the
+ * companion was benched and reads went from ~165ms to ~33s.
+ *
+ * So the rule is a subsequence with two guards:
+ *
+ *   1. every companion node is byte-identical to a platform node, in document order — this
+ *      is the tap-safety property, and it is not weakened at all;
+ *   2. every platform node the companion lacks is a LEAF and is neither clickable nor
+ *      focusable — so the companion can never quietly drop something tappable, nor a
+ *      container whose absence would re-nest the nodes under it.
+ *
+ * Guard 2 is deliberately stricter than the measurement requires: an unmatched container
+ * would still leave its children matchable, but the shapes that produces have not been seen
+ * on a real device, and the cost of refusing one is a slow read rather than a wrong tap.
+ *
+ * What this does NOT still guarantee is that a non-interactive leaf's bounds agree — such a
+ * node can differ and be treated as missing. That is the deliberate give: it cannot move a
+ * tap, because nothing reads it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dumpsAgree = dumpsAgree;
+const NODE_TAG = /<node\b[^>]*?\/?>/g;
+// A leading \s so `long-clickable="true"` cannot be read as `clickable="true"`.
+const CLICKABLE = /\sclickable="true"/;
+const FOCUSABLE = /\sfocusable="true"/;
+function nodes(xml) {
+    const out = [];
+    for (const m of xml.matchAll(NODE_TAG)) {
+        const raw = m[0];
+        out.push({
+            raw,
+            leaf: raw.endsWith('/>'),
+            interactive: CLICKABLE.test(raw) || FOCUSABLE.test(raw),
+        });
+    }
+    return out;
+}
+/** The `<hierarchy …>` element itself — its `rotation` is part of the contract. */
+function header(xml) {
+    return /<hierarchy\b[^>]*>/.exec(xml)?.[0] ?? '';
+}
+function dumpsAgree(stock, companion) {
+    const a = stock.trim();
+    const b = companion.trim();
+    if (a === b)
+        return { agree: true };
+    if (header(a) !== header(b)) {
+        return { agree: false, reason: 'the hierarchy header differs (rotation changed mid-capture?)' };
+    }
+    const stockNodes = nodes(a);
+    const compNodes = nodes(b);
+    let i = 0; // stock
+    for (const want of compNodes) {
+        // Skip platform nodes the companion did not emit, proving each is droppable as we go.
+        while (i < stockNodes.length && stockNodes[i].raw !== want.raw) {
+            const skipped = stockNodes[i];
+            if (skipped.interactive) {
+                return { agree: false, reason: 'the companion is missing a node the platform reports as tappable' };
+            }
+            if (!skipped.leaf) {
+                return { agree: false, reason: 'the companion is missing a container the platform reports' };
+            }
+            i++;
+        }
+        if (i === stockNodes.length) {
+            return { agree: false, reason: 'the companion reports a node the platform does not' };
+        }
+        i++; // consume the match
+    }
+    // Anything left over in the platform's dump must clear the same bar.
+    for (; i < stockNodes.length; i++) {
+        if (stockNodes[i].interactive) {
+            return { agree: false, reason: 'the companion is missing a node the platform reports as tappable' };
+        }
+        if (!stockNodes[i].leaf) {
+            return { agree: false, reason: 'the companion is missing a container the platform reports' };
+        }
+    }
+    return { agree: true };
+}

package/dist/companion/manager.js

@@ -19,6 +19,7 @@ const exec_1 = require("../exec");
 const output_1 = require("../output");
 const errors_1 = require("../errors");
 const version_1 = require("../version");
+const dump_match_1 = require("./dump-match");
 const protocol_1 = require("./protocol");
 const DEVICE_JAR = '/data/local/tmp/verikun-companion.jar';
 /** What we learned about this device last time, kept ON the device because that is what the
@@ -471,7 +472,11 @@ class Companion {
      * shifts every element near the bottom of the screen, and the resulting tap lands
      * somewhere else while still reporting success, which is the worst failure a testing
      * tool has. So do not guess: take one real `uiautomator dump` and adopt whichever
-     * source reproduces it byte for byte.
+     * source reproduces it.
+     *
+     * "Reproduces it" is `dumpsAgree()`, not string equality — see the reasoning there for
+     * why equality rejected a companion that was right, and exactly what the relaxed rule
+     * still guarantees about anything verikun can tap.
      *
      * Costs one stock dump (~2.4s) plus a reconnect (~1.05s), once per companion — not once
      * per process, because the verdict is stored in the companion itself.
@@ -484,7 +489,7 @@ class Companion {
             (0, protocol_1.requestSync)(this.port, 'acquire', 20000);
             for (const dims of ['app', 'real']) {
                 const reply = (0, protocol_1.requestSync)(this.port, (0, protocol_1.dumpCommand)(0, dims));
-                if ((0, protocol_1.isHierarchy)(reply) && reply.toString('utf8').trim() === stock) {
+                if ((0, protocol_1.isHierarchy)(reply) && (0, dump_match_1.dumpsAgree)(stock, reply.toString('utf8')).agree) {
                     (0, protocol_1.requestSync)(this.port, `calibrated ${dims}`, 4000);
                     this.writeDeviceNote(dims);
                     return dims;

package/dist/companion/protocol.js

@@ -15,10 +15,16 @@ exports.portForSerial = portForSerial;
 exports.requestSync = requestSync;
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
-/** Bumped in lockstep with PROTOCOL_VERSION in CompanionApp.java. A companion left running
- *  by an older verikun answers `ping` with a different number and is restarted rather than
- *  talked to, so a changed dump format can never be replayed by a stale process. */
-exports.COMPANION_PROTOCOL = '1';
+/** Bumped in lockstep with PROTOCOL_VERSION in CompanionApp.java — `tests/companion-protocol
+ *  .test.ts` reads the Java source and fails if they drift. A companion left running by an
+ *  older verikun answers `ping` with a different number and is restarted rather than talked
+ *  to, so a changed dump format can never be replayed by a stale process.
+ *
+ *  2 — the companion asks for window information, so it tracks a window another app opens on
+ *  top ([#79]) and its dump omits decor outside the app's own window. MEASURED: without this
+ *  bump an upgraded verikun reused the running daemon, never pushed the new jar, and went on
+ *  reading 0 nodes of a permission dialog the stock path saw all 5 of — silently, exit 0. */
+exports.COMPANION_PROTOCOL = '2';
 class CompanionUnavailableError extends Error {
 }
 exports.CompanionUnavailableError = CompanionUnavailableError;

package/dist/device/claims.js

@@ -0,0 +1,594 @@
+"use strict";
+// The device claim store — "which attached device is another job already driving?".
+//
+// Parallel agents (separate worktrees of one repo) share one pool of phones, emulators
+// and simulators. Nothing coordinated the assignment, so two jobs would land on the same
+// device and BOTH die: one `install` of the same package with a different build silently
+// replaces the app under the other's feet, and it presents as an ordinary assertion
+// failure, indistinguishable from a real regression until someone goes digging.
+//
+// A claim is a small JSON file per device under `~/.verikun/devices/`, saying who is
+// driving it and when they were last seen. HOST-global, not workspace-local: run state
+// lives in `./.verikun/` because it describes a working directory, but a device is a fact
+// about the machine, and the jobs that collide are in DIFFERENT directories by definition.
+//
+// Load-bearing properties, each of which has a failure mode behind it:
+//
+//   * ONE FILE PER SERIAL, never one shared map. The whole premise is concurrent writers;
+//     independent files make every write atomic with no read-modify-write race.
+//   * ACQUISITION IS `wx`. An exclusive create is the only way two agents starting at the
+//     same instant don't both pick the first free device. Losing that race is not an
+//     error — the caller just moves to the next candidate.
+//   * READS ARE TOLERANT. An unreadable or corrupt claim reads as UNCLAIMED (same posture
+//     as run.ts's loadState and the plan cache): a poisoned file must never be able to
+//     brick a device permanently.
+//   * LIVENESS IS PID-FIRST WHERE IT CAN BE. See `isLive` — a timeout alone is either too
+//     short (steals a device mid-run) or too long (parks a crashed job's phone).
+//   * `VERIKUN_NO_CLAIM=1` DISABLES READS AND WRITES, restoring the pre-claim behaviour
+//     exactly — including the old exit-2-on-multiple-devices — and making this job
+//     invisible to others. That equivalence is the thing to preserve when debugging.
+//
+// Platform-agnostic by design, like `device/settings.ts` and `ui/`: it never touches
+// adb/xcrun. The drivers know which devices exist; this knows which are taken.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releaseOwnClaims = releaseOwnClaims;
+exports.setProcessScoped = setProcessScoped;
+exports.claimsEnabled = claimsEnabled;
+exports.claimTtlMs = claimTtlMs;
+exports.claimsDir = claimsDir;
+exports.isMine = isMine;
+exports.isLive = isLive;
+exports.readClaim = readClaim;
+exports.listClaims = listClaims;
+exports.claimDevice = claimDevice;
+exports.touchClaim = touchClaim;
+exports.releaseClaim = releaseClaim;
+exports.describeClaim = describeClaim;
+exports.selectAndClaim = selectAndClaim;
+exports.assertClaimable = assertClaimable;
+exports.summarize = summarize;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+const version_1 = require("../version");
+/** Default TTL for a claim whose owner is not a single long-lived process, in minutes. */
+const DEFAULT_TTL_MIN = 5;
+/**
+ * Ceiling on trusting a pid, however alive it looks. Pids are recycled, and a
+ * process-scoped run heartbeats every step, so a genuinely running job is never anywhere
+ * near this old — it only stops a recycled pid resurrecting an abandoned claim forever.
+ */
+const PID_TRUST_MAX_MS = 6 * 60 * 60 * 1000;
+// --- process-wide latch -----------------------------------------------------
+let processScoped = false;
+/**
+ * Serials this process has successfully claimed, so a teardown can hand them all back
+ * without threading a driver handle through every `finally`. `cmdBatch` in particular
+ * never holds a Driver — it dispatches through `executeParsed` — so asking the claim
+ * store what it took is the only way it can release anything.
+ */
+const acquired = new Set();
+/** Give back every device this process claimed. Best-effort; teardown must never throw. */
+function releaseOwnClaims(o = {}) {
+    const released = [];
+    for (const serial of [...acquired]) {
+        if (releaseClaim(serial, { ...o, mineOnly: true }))
+            released.push(serial);
+    }
+    return released;
+}
+/**
+ * Declare that this process owns its device for its whole run — `ai`, `suite`, `batch`,
+ * `server`. That turns the owning pid into EXACT liveness evidence (see `isLive`), so a
+ * `kill -9` frees the device immediately instead of parking it until the TTL expires.
+ *
+ * A process-wide latch rather than a parameter because the claim is acquired lazily, deep
+ * inside `Driver.resolvedSerial()`, long after the command that knows this was dispatched.
+ * `setOutputQuiet` in output.ts is the same shape for the same reason.
+ */
+function setProcessScoped(v) {
+    const prev = processScoped;
+    processScoped = v;
+    return prev;
+}
+// --- environment ------------------------------------------------------------
+/** Claims are on unless `VERIKUN_NO_CLAIM` is set to anything non-empty (mirrors VERIKUN_NO_RUN). */
+function claimsEnabled(env = process.env) {
+    return !env.VERIKUN_NO_CLAIM;
+}
+/** How long a one-off command's claim survives without a heartbeat. `0` disables the TTL. */
+function claimTtlMs(env = process.env) {
+    const raw = env.VERIKUN_CLAIM_TTL_MIN;
+    if (raw === undefined)
+        return DEFAULT_TTL_MIN * 60000;
+    const n = Number(raw);
+    return (Number.isFinite(n) && n >= 0 ? n : DEFAULT_TTL_MIN) * 60000;
+}
+// --- paths ------------------------------------------------------------------
+function claimsDir(o = {}) {
+    return (0, node_path_1.join)(o.home ?? (0, node_os_1.homedir)(), '.verikun', 'devices');
+}
+/**
+ * Filename for a serial: readable enough to eyeball the directory, with a hash suffix so
+ * two serials that sanitize alike (`192.168.1.5:5555` vs `192.168.1.5_5555`) can never
+ * collide onto one file and silently share a claim.
+ */
+function fileFor(serial) {
+    const safe = serial.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 48);
+    return `${safe}-${(0, node_crypto_1.createHash)('sha1').update(serial).digest('hex').slice(0, 8)}.json`;
+}
+function pathFor(serial, o) {
+    return (0, node_path_1.join)(claimsDir(o), fileFor(serial));
+}
+// --- identity ---------------------------------------------------------------
+/** Session identity, same source `run.ts` uses for rollover. Absent in a fresh shell. */
+function currentSession(env) {
+    return env.VERIKUN_SESSION || env.TERM_SESSION_ID || undefined;
+}
+/**
+ * Is this claim the current job's?
+ *
+ * EITHER the session matches OR the working directory does — deliberately forgiving,
+ * because the only unsafe error here is falsely accusing your own job. An agent harness
+ * may run every command in a fresh shell with no stable session id (which is why session
+ * alone will not do), and two terminals deliberately sharing one checkout are one job
+ * (which is why cwd alone will not do either).
+ */
+function isMine(c, o = {}) {
+    const env = o.env ?? process.env;
+    const session = currentSession(env);
+    if (session && c.session && c.session === session)
+        return true;
+    return c.cwd === (o.cwd ?? process.cwd());
+}
+/** Whether a pid is running. EPERM means it exists but belongs to someone else — alive. */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+function ageMs(c, now) {
+    const t = Date.parse(c.heartbeat);
+    // An unparseable heartbeat reads as ancient, so a malformed claim is takeable rather
+    // than immortal — the same direction every other tolerance in this file leans.
+    return Number.isNaN(t) ? Number.POSITIVE_INFINITY : now - t;
+}
+/**
+ * Is somebody still driving this device?
+ *
+ * Two signals, because a heartbeat can only fire BETWEEN commands and neither signal
+ * alone covers both owners:
+ *
+ *   * A LIVE PID always means live. The heartbeat cannot tick during a single long
+ *     command — a large `install`, a `wait --timeout 600000`, a `vk ai` model repair
+ *     round-trip — so without this a run would lose its device midway through work it
+ *     had no opportunity to report. The pid only ever EXTENDS liveness here.
+ *   * PROCESS-SCOPED owners (`ai`/`suite`/`batch`/`server`) are one process for the whole
+ *     job, so a dead pid also means DONE: the device comes back the instant a `kill -9`
+ *     lands, rather than being parked until a timer expires. This is the only case where
+ *     the pid shortens liveness, and it is sound precisely because the process outlives
+ *     every command in the job.
+ *
+ * Everything else falls back to idle time. A one-off command's process is gone the moment
+ * it printed, so the TTL covers the only gap left: an agent thinking between two commands.
+ * One minute is too tight for that (read a screenshot, decide, tap again); five is enough
+ * while still handing a crashed job's phone back quickly.
+ */
+function isLive(c, o = {}) {
+    const age = ageMs(c, o.now ?? Date.now());
+    const ours = c.host === (o.host ?? (0, node_os_1.hostname)()) && c.pid > 0;
+    // The ceiling is what stops a RECYCLED pid resurrecting an abandoned claim forever; a
+    // job that is genuinely working heartbeats nowhere near this often.
+    const running = ours && age <= PID_TRUST_MAX_MS && pidAlive(c.pid);
+    if (c.processScoped && ours)
+        return running;
+    const ttl = claimTtlMs(o.env ?? process.env);
+    return running || (ttl > 0 && age <= ttl);
+}
+// --- store ------------------------------------------------------------------
+/** Read one device's claim. Missing, unreadable or malformed all mean UNCLAIMED. */
+function readClaim(serial, o = {}) {
+    return readClaimAt(pathFor(serial, o));
+}
+function readClaimAt(p) {
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const c = JSON.parse((0, node_fs_1.readFileSync)(p, 'utf8'));
+        // Guard the two fields every decision reads. A file that parses as JSON but is not a
+        // claim must not make `isMine`/`isLive` throw deep inside device resolution.
+        if (typeof c?.serial !== 'string' || typeof c?.cwd !== 'string')
+            return null;
+        return c;
+    }
+    catch (e) {
+        (0, output_1.err)(`[verikun] ignoring unreadable device claim ${p} (${e.message})`);
+        return null;
+    }
+}
+/** Every claim on this host. Powers `vk devices`, and is the list a parallel scheduler reads. */
+function listClaims(o = {}) {
+    const dir = claimsDir(o);
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const out = [];
+    try {
+        for (const name of (0, node_fs_1.readdirSync)(dir)) {
+            if (!name.endsWith('.json'))
+                continue;
+            const c = readClaimAt((0, node_path_1.join)(dir, name));
+            if (c)
+                out.push(c);
+        }
+    }
+    catch {
+        /* an unreadable directory is "nothing claimed", never a failure */
+    }
+    return out;
+}
+function record(serial, platform, o, since) {
+    const env = o.env ?? process.env;
+    const iso = new Date(o.now ?? Date.now()).toISOString();
+    return {
+        serial,
+        platform,
+        session: currentSession(env),
+        cwd: o.cwd ?? process.cwd(),
+        pid: process.pid,
+        host: o.host ?? (0, node_os_1.hostname)(),
+        processScoped,
+        since: since ?? iso,
+        heartbeat: iso,
+        version: version_1.VERSION,
+    };
+}
+let tmpSeq = 0;
+/** A scratch path in the store directory. Never ends in `.json`, so `listClaims` and
+ *  `findSeed`-style scans skip it even if one is ever left behind. */
+function tmpPath(p) {
+    return `${p}.tmp-${process.pid}-${(tmpSeq += 1)}`;
+}
+/** Replace a claim we are already entitled to. `rename` is atomic on POSIX, so a
+ *  concurrent reader sees the old content or the new one, never a half-written file. */
+function writeAtomic(p, c) {
+    const tmp = tmpPath(p);
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(c, null, 2));
+    (0, node_fs_1.renameSync)(tmp, p);
+}
+/**
+ * Create a claim ONLY if the device is unclaimed, and make it appear fully-formed.
+ *
+ * Write-then-link, not `writeFileSync(…, {flag:'wx'})`. Both are exclusive — `link()` fails
+ * EEXIST just as `wx` does — but `wx` creates the file EMPTY and fills it a moment later,
+ * while `link()` publishes an already-written file in one step. That difference decides who
+ * owns the device, because a racer landing in the gap reads zero bytes, the tolerant reader
+ * correctly calls that corrupt, and corrupt-is-takeable hands it the device too.
+ *
+ * The gap is microseconds on an idle box and does not reproduce there — it was observed
+ * with `wx` under real load (two e2e suites plus an emulator), where six processes racing
+ * for one device produced THREE winners. Load is exactly when parallel agents contend, so
+ * closing it structurally beats relying on the scheduler.
+ */
+function writeExclusive(p, c) {
+    const tmp = tmpPath(p);
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(c, null, 2));
+    try {
+        (0, node_fs_1.linkSync)(tmp, p);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return false;
+        throw e;
+    }
+    finally {
+        try {
+            (0, node_fs_1.unlinkSync)(tmp);
+        }
+        catch {
+            /* the link succeeded or never happened; either way the scratch file is disposable */
+        }
+    }
+}
+/**
+ * Take the device, or report who has it.
+ *
+ * The happy path is an exclusive publish (`writeExclusive`): if no claim existed, we now own
+ * it, and no concurrent starter can have won the same device. Only when that fails do we
+ * look at who is there — and taking over a dead claim goes unlink-then-publish for the same
+ * reason, so exactly one of several racing takers wins instead of two overwriting each other
+ * and both believing they own it.
+ */
+function claimDevice(serial, platform, o = {}) {
+    const r = claimDeviceInner(serial, platform, o);
+    if (r.ok)
+        acquired.add(serial);
+    return r;
+}
+/**
+ * How many times to re-race for a device whose claim keeps being cleared under us. Each
+ * extra round costs one exclusive create against a device nobody live holds, so this is a
+ * bound on pathological churn, not a retry budget anyone should hit.
+ */
+const CLAIM_ATTEMPTS = 4;
+/**
+ * Run `fn` holding the exclusive right to replace this device's claim, or return null if
+ * another taker holds it.
+ *
+ * Why a token at all: POSIX offers no "remove this file only if it is still the one I
+ * read". So "the claim is dead, unlink it and publish mine" is unsound on its own — between
+ * the read and the unlink another taker can publish, and the unlink then deletes a LIVE
+ * claim, handing the device to two jobs. Measured, not theoretical: 16 racers over one dead
+ * claim produced two winners.
+ *
+ * `link()` gives a sound absent-to-present CAS, so it can elect a single taker. Holding that
+ * token, the winner is the only writer of `p` and may replace it atomically — no unlink, no
+ * window. The token is held across three syscalls and no I/O, so the only way to strand one
+ * is to die inside it; liveness is therefore the owning PID alone, which is exact. That is
+ * the difference that matters: a dead CLAIM is the routine steady state (every finished job
+ * leaves one), whereas a dead TOKEN needs a crash inside a microsecond window.
+ */
+function withTakeover(p, serial, platform, o, fn) {
+    const tok = `${p}.takeover`;
+    const me = record(serial, platform, o);
+    if (!writeExclusive(tok, me)) {
+        const other = readClaimAt(tok);
+        if (other && !tokenAbandoned(other, o))
+            return null; // a live taker is mid-takeover
+        try {
+            (0, node_fs_1.unlinkSync)(tok);
+        }
+        catch {
+            /* another racer cleared it first */
+        }
+        if (!writeExclusive(tok, me))
+            return null;
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            (0, node_fs_1.unlinkSync)(tok);
+        }
+        catch {
+            /* best effort: a stray token is cleared by the next taker */
+        }
+    }
+}
+/** A takeover token outlives its process only if that process died holding it. Judged on the
+ *  PID alone — no TTL — because it is never held across anything slow. */
+function tokenAbandoned(t, o) {
+    if (t.host !== (o.host ?? (0, node_os_1.hostname)()))
+        return false; // not ours to judge; leave it alone
+    return !pidAlive(t.pid);
+}
+function claimDeviceInner(serial, platform, o) {
+    const p = pathFor(serial, o);
+    try {
+        (0, node_fs_1.mkdirSync)(claimsDir(o), { recursive: true });
+    }
+    catch (e) {
+        return uncoordinated(serial, platform, p, e, o);
+    }
+    // PUBLISH FIRST, then judge. The invariant this shape exists to hold is: `ok: true` is
+    // returned only when an EXCLUSIVE create actually succeeded, or the claim on disk is
+    // already ours. Deciding first and writing afterwards cannot hold it — between the
+    // decision and the write another racer can publish, and both would report success.
+    for (let attempt = 0; attempt < CLAIM_ATTEMPTS; attempt++) {
+        const fresh = record(serial, platform, o);
+        try {
+            if (writeExclusive(p, fresh))
+                return { ok: true, claim: fresh };
+        }
+        catch (e) {
+            return uncoordinated(serial, platform, p, e, o);
+        }
+        // Something is there. Note that `held === null` covers BOTH "corrupt" and "vanished a
+        // microsecond ago", which is why neither may be treated as ours: the only proof of
+        // ownership is a create that succeeded.
+        const held = readClaimAt(p);
+        if (held && isMine(held, o)) {
+            // Keep `since` — how long this job has held the device is the interesting number.
+            const refreshed = record(serial, platform, o, held.since);
+            try {
+                writeAtomic(p, refreshed);
+            }
+            catch {
+                /* the file is ours either way; a failed refresh only ages the heartbeat */
+            }
+            return { ok: true, claim: refreshed };
+        }
+        if (held && isLive(held, o))
+            return { ok: false, held };
+        // Dead, or unreadable (a claim nobody can parse would otherwise hold a device forever).
+        // Replacing it must be serialized — see `withTakeover` for why unlink-then-create is
+        // not enough. Losing the token is not an error; the next attempt re-reads and finds
+        // whoever won.
+        const taken = withTakeover(p, serial, platform, o, () => {
+            // Re-read INSIDE the token. Another taker may have legitimately claimed the device
+            // between our judgement and our turn, and this is the only point at which that
+            // answer cannot change under us.
+            const now = readClaimAt(p);
+            if (now && isMine(now, o))
+                return { ok: true, claim: now };
+            if (now && isLive(now, o))
+                return { ok: false, held: now };
+            // We are the sole writer of `p` while the token is held, so an atomic replace is
+            // safe here — no unlink, and therefore no window in which it could delete a claim
+            // newer than the one we judged dead.
+            const mine = record(serial, platform, o);
+            writeAtomic(p, mine);
+            return { ok: true, claim: mine };
+        });
+        if (taken)
+            return taken;
+    }
+    // Beaten every round. Refusing is the only safe answer left: reporting success here,
+    // without a published claim, is precisely how two jobs end up on one device.
+    const last = readClaimAt(p);
+    if (last && isMine(last, o))
+        return { ok: true, claim: last };
+    return { ok: false, held: last };
+}
+/**
+ * The store is unusable — unwritable home, full disk, a permissions problem. Coordination
+ * is a convenience, so this degrades to "drive the device anyway" rather than becoming a
+ * new way for a run to fail. The caller proceeds UNCOORDINATED, which is the honest state:
+ * no claim was published, and this job is invisible to others.
+ */
+function uncoordinated(serial, platform, p, e, o) {
+    (0, output_1.err)(`[verikun] could not write device claim ${p} (${e.message}) — continuing unclaimed`);
+    return { ok: true, claim: record(serial, platform, o) };
+}
+/** Refresh my heartbeat. Never throws, never steals: a claim that became someone else's is left alone. */
+function touchClaim(serial, platform, o = {}) {
+    if (!claimsEnabled(o.env ?? process.env))
+        return;
+    try {
+        const held = readClaim(serial, o);
+        if (held && !isMine(held, o))
+            return;
+        if (!held) {
+            claimDevice(serial, platform, o);
+            return;
+        }
+        writeAtomic(pathFor(serial, o), record(serial, platform, o, held.since));
+    }
+    catch {
+        /* bookkeeping must never fail a command */
+    }
+}
+/**
+ * Drop a claim. `mineOnly` is what the automatic paths (run archive, the `ai`/`batch`/
+ * `suite` teardown) pass, so a job can only ever hand back its own device; `vk device
+ * release` omits it and says so on stderr, because that is the deliberate break-glass.
+ */
+function releaseClaim(serial, o = {}) {
+    try {
+        const held = readClaim(serial, o);
+        if (!held)
+            return null;
+        if (!isMine(held, o) && o.mineOnly)
+            return null;
+        (0, node_fs_1.unlinkSync)(pathFor(serial, o));
+        acquired.delete(serial);
+        return held;
+    }
+    catch {
+        return null;
+    }
+}
+// --- selection --------------------------------------------------------------
+/** Column form for a table: `workspace 'islamabad' · 3m ago`, or `this job` for our own. */
+function describeClaim(c, o = {}) {
+    if (isMine(c, o))
+        return 'this job';
+    return `${holderLabel(c)} · ${fmtAge(ageMs(c, o.now ?? Date.now()))} ago`;
+}
+/** What to say when a device is demonstrably contended but no holder could be read — a
+ *  claim being cleared and retaken faster than it can be observed. Rare, and honest. */
+const CONTENDED = 'another job (claim contended)';
+/** Sentence form, for a refusal that reads as prose rather than as a cell. */
+function describeHolder(c, o) {
+    return `${holderLabel(c)} (last seen ${fmtAge(ageMs(c, o.now ?? Date.now()))} ago)`;
+}
+function holderLabel(c) {
+    const dir = (0, node_path_1.basename)(c.cwd || '');
+    if (dir && dir !== '/' && dir !== '.')
+        return `workspace '${dir}'`;
+    return c.session ? `session ${c.session}` : 'another job';
+}
+/** Local copy of run.ts's private age formatter — five lines, and importing run.ts here
+ *  would drag the whole recorder into the drivers' dependency graph for a string. */
+function fmtAge(ms) {
+    if (!Number.isFinite(ms))
+        return 'unknown';
+    const m = Math.floor(ms / 60000);
+    if (m < 1)
+        return `${Math.max(0, Math.floor(ms / 1000))}s`;
+    if (m < 60)
+        return `${m}m`;
+    return `${Math.floor(m / 60)}h${m % 60}m`;
+}
+function label(c) {
+    return c.model ? `${c.serial} (${c.model})` : c.serial;
+}
+/**
+ * Pick a device nobody else is driving, and claim it in the same breath.
+ *
+ * Candidates are tried in the backend's own listing order, so an unclaimed phone keeps
+ * being reused across runs rather than round-robined — a device that worked last time is
+ * the one most likely to work now. A lost `wx` race is simply the next candidate's turn.
+ *
+ * Throws exit 2 when every candidate is held: the shape is "you must choose", the same as
+ * its sibling `Multiple devices connected`, and `--device` is the fix. Not exit 3 — the
+ * machine is fine, it is just busy.
+ */
+function selectAndClaim(candidates, platform, o = {}) {
+    const skipped = [];
+    for (const candidate of candidates) {
+        const r = claimDevice(candidate.serial, platform, o);
+        if (r.ok)
+            return { serial: candidate.serial, skipped, total: candidates.length };
+        skipped.push({ candidate, held: r.held });
+    }
+    const width = Math.max(...skipped.map((s) => label(s.candidate).length), 0);
+    const rows = skipped
+        .map((s) => `  ${label(s.candidate).padEnd(width)}  ${s.held ? describeClaim(s.held, o) : CONTENDED}`)
+        .join('\n');
+    throw new errors_1.CliError(`Every attached device is in use:\n${rows}\n` +
+        'Wait for one, free it with `verikun device release <serial>`, ' +
+        'or set VERIKUN_NO_CLAIM=1 to ignore claims.', 2);
+}
+/**
+ * Claim the device the caller named explicitly, or refuse.
+ *
+ * `alternatives` is a THUNK because the Android fast path never lists devices when
+ * `--device` is given — it spawns nothing at all — and paying for an `adb devices` round
+ * trip only to decorate an error we are not going to raise would tax every run to help
+ * the rare one. On the failure path the extra call is free in comparison.
+ */
+function assertClaimable(serial, platform, alternatives = () => [], o = {}) {
+    const r = claimDevice(serial, platform, o);
+    if (r.ok)
+        return;
+    // Decorating an error must never be able to replace it. Listing alternatives means
+    // asking the platform what is attached, which throws its own exit 3 when nothing is
+    // (a plausible state here: the device you named is claimed AND now unplugged).
+    let free = [];
+    try {
+        free = alternatives().filter((c) => c.serial !== serial && !isHeldByOther(c.serial, o));
+    }
+    catch {
+        /* no suggestions, then — the refusal below is the message that matters */
+    }
+    const lines = [
+        `${serial} is in use by ${r.held ? describeHolder(r.held, o) : CONTENDED}.`,
+        ...(free.length ? [`  free now:             ${free.map(label).join(', ')}`] : []),
+        `  if that job is gone:  verikun device release ${serial}`,
+        '  to ignore claims:     VERIKUN_NO_CLAIM=1',
+    ];
+    throw new errors_1.CliError(lines.join('\n'), 2);
+}
+function isHeldByOther(serial, o) {
+    const c = readClaim(serial, o);
+    return !!c && !isMine(c, o) && isLive(c, o);
+}
+/** Resolve a device list into `vk devices` rows: who holds what, and is it me. */
+function summarize(serial, o = {}) {
+    const c = readClaim(serial, o);
+    if (!c || !isLive(c, o))
+        return undefined;
+    const mine = isMine(c, o);
+    return { ...c, mine, by: mine ? 'this job' : describeClaim(c, o) };
+}

package/dist/drivers/adb.js

@@ -11,6 +11,7 @@ const exec_1 = require("../exec");
 const android_parse_1 = require("../ui/android-parse");
 const viewport_1 = require("../ui/viewport");
 const settings_1 = require("../device/settings");
+const claims_1 = require("../device/claims");
 const output_1 = require("../output");
 const ADB = process.env.ADB || 'adb';
 const ADB_HINT = 'install the Android platform-tools (`brew install --cask android-platform-tools`), or point ADB at the binary';
@@ -214,9 +215,35 @@ class AdbDriver {
         if (this.cachedSerial)
             return this.cachedSerial;
         if (this.requested) {
+            // An explicit --device is trusted verbatim and costs no `adb devices` round trip —
+            // so the claim check here is one small file read, and the list of free alternatives
+            // for the refusal message is only paid for if we are actually going to refuse.
+            if ((0, claims_1.claimsEnabled)())
+                (0, claims_1.assertClaimable)(this.requested, 'android', () => this.usableDevices());
             this.cachedSerial = this.requested;
             return this.cachedSerial;
         }
+        const usable = this.usableDevices();
+        if (!(0, claims_1.claimsEnabled)()) {
+            if (usable.length > 1) {
+                const list = usable.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
+                throw new errors_1.CliError(`Multiple devices connected; pass --device <serial> (or set VERIKUN_DEVICE):\n${list}`, 2);
+            }
+            this.cachedSerial = usable[0].serial;
+            return this.cachedSerial;
+        }
+        // Claims turn "ambiguous, you decide" into "one is free, take it" — and a single
+        // attached device still goes through here, because "someone else is on the only
+        // phone" is exactly where being told beats finding out twenty minutes later.
+        const picked = (0, claims_1.selectAndClaim)(usable, 'android');
+        if (picked.total > 1) {
+            (0, output_1.err)(`[verikun] auto-selected ${picked.serial} — ${picked.total} attached, ${picked.skipped.length} held by another job`);
+        }
+        this.cachedSerial = picked.serial;
+        return this.cachedSerial;
+    }
+    /** Attached devices in a drivable state, or the honest exit-3 explanation of why none is. */
+    usableDevices() {
         const all = this.listDevices();
         const usable = all.filter((d) => d.state === 'device');
         if (usable.length === 0) {
@@ -226,12 +253,7 @@ class AdbDriver {
             }
             throw new errors_1.CliError('No Android devices/emulators connected. Start one, then `verikun devices`.', 3);
         }
-        if (usable.length > 1) {
-            const list = usable.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
-            throw new errors_1.CliError(`Multiple devices connected; pass --device <serial> (or set VERIKUN_DEVICE):\n${list}`, 2);
-        }
-        this.cachedSerial = usable[0].serial;
-        return this.cachedSerial;
+        return usable;
     }
     withSerial(args) {
         return ['-s', this.resolvedSerial(), ...args];

package/dist/drivers/ios.js

@@ -12,6 +12,7 @@ const exec_1 = require("../exec");
 const ios_parse_1 = require("../ui/ios-parse");
 const viewport_1 = require("../ui/viewport");
 const settings_1 = require("../device/settings");
+const claims_1 = require("../device/claims");
 const output_1 = require("../output");
 // iOS driver. `xcrun simctl` / `devicectl` cover device discovery and — on a
 // simulator — screenshots, app lifecycle, and logs (no extra install needed).
@@ -217,6 +218,8 @@ class IdbDriver {
         const sims = this.simulators();
         const simUdids = new Set(sims.map((d) => d.serial));
         if (this.requested) {
+            if ((0, claims_1.claimsEnabled)())
+                (0, claims_1.assertClaimable)(this.requested, 'ios', () => this.claimCandidates(sims));
             this.cachedSerial = this.requested;
             this.cachedIsSim = simUdids.has(this.requested);
             return this.cachedSerial;
@@ -225,19 +228,39 @@ class IdbDriver {
         // drivable target, so prefer it. Only weigh physical devices when no simulator
         // is booted — and only genuinely "connected" ones (devicectl also lists paired-
         // but-idle devices as "available (paired)", which must not count as active).
-        const bootedSims = sims.filter((d) => d.state === 'booted');
-        const candidates = bootedSims.length > 0 ? bootedSims : listPhysicalDevices().filter((d) => /connected/i.test(d.state));
+        const candidates = this.claimCandidates(sims);
         if (candidates.length === 0) {
             throw new errors_1.CliError('No booted iOS simulator or connected device. Boot one (Simulator.app / `xcrun simctl boot`), then `verikun devices`.', 3);
         }
-        if (candidates.length > 1) {
-            const list = candidates.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
-            throw new errors_1.CliError(`Multiple iOS targets; pass --device <udid> (or set VERIKUN_DEVICE):\n${list}`, 2);
+        let serial;
+        if (!(0, claims_1.claimsEnabled)()) {
+            if (candidates.length > 1) {
+                const list = candidates.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
+                throw new errors_1.CliError(`Multiple iOS targets; pass --device <udid> (or set VERIKUN_DEVICE):\n${list}`, 2);
+            }
+            serial = candidates[0].serial;
         }
-        this.cachedSerial = candidates[0].serial;
-        this.cachedIsSim = simUdids.has(candidates[0].serial);
+        else {
+            const picked = (0, claims_1.selectAndClaim)(candidates, 'ios');
+            if (picked.total > 1) {
+                (0, output_1.err)(`[verikun] auto-selected ${picked.serial} — ${picked.total} available, ${picked.skipped.length} held by another job`);
+            }
+            serial = picked.serial;
+        }
+        this.cachedSerial = serial;
+        this.cachedIsSim = simUdids.has(serial);
         return this.cachedSerial;
     }
+    /**
+     * The targets auto-resolution will consider, in preference order. A booted simulator is
+     * the first-class, unambiguously drivable target, so prefer it; only weigh physical
+     * devices when no simulator is booted — and only genuinely "connected" ones (devicectl
+     * also lists paired-but-idle devices as "available (paired)", which must not count).
+     */
+    claimCandidates(sims) {
+        const bootedSims = sims.filter((d) => d.state === 'booted');
+        return bootedSims.length > 0 ? bootedSims : listPhysicalDevices().filter((d) => /connected/i.test(d.state));
+    }
     udid() {
         return this.resolvedSerial();
     }

package/dist/errors.js

@@ -3,8 +3,8 @@
 // stable, agent-readable exit statuses:
 //   0  success / found / assertion passed
 //   1  not found / assertion failed / wait timeout
-//   2  usage error or ambiguous selector (caller must refine)
-//   3  environment error (adb/simctl missing, no/multiple devices, dump failed)
+//   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.NoWindowError = exports.SelectorNotFoundError = exports.probeFailure = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
 exports.isEnvError = isEnvError;

package/dist/run.js

@@ -477,6 +477,16 @@ class Recorder {
     capture(driver, quiet = false) {
         if (!driver)
             return;
+        // No device, no evidence. When resolution itself is what failed — nothing attached,
+        // or another job holds every device — there is no screen to photograph, and both
+        // attempts below would re-raise that same error and print it again. Staying silent
+        // here is what keeps ONE failure reading as one message instead of three.
+        try {
+            driver.resolvedSerial();
+        }
+        catch {
+            return;
+        }
         try {
             // Full resolution on purpose — a human reads this in the report — but via the
             // raw path, which reaches the same PNG without the device-side encode.

package/dist/server.js

@@ -36,6 +36,7 @@ const args_1 = require("./args");
 const errors_1 = require("./errors");
 const drivers_1 = require("./drivers");
 const manager_1 = require("./companion/manager");
+const claims_1 = require("./device/claims");
 const output_1 = require("./output");
 const ir_1 = require("./agent/ir");
 const rpc_1 = require("./rpc");
@@ -376,6 +377,9 @@ async function cmdServer(positionals, flags) {
     // toolchain can't drive it — before binding a port. preflight() covers resolving the
     // device AND the tools; without it the server happily listens on a box with no idb
     // and then 500s every /v1/exec.
+    // The server owns its device for as long as it listens, so its pid is exact liveness
+    // evidence — set before resolving, since that is where the claim is taken.
+    (0, claims_1.setProcessScoped)(true);
     const driver = (0, drivers_1.getDriver)(platform, device);
     driver.preflight();
     const serial = driver.resolvedSerial();

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.21.1';
+exports.VERSION = '0.22.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.21.1",
+  "version": "0.22.1",
   "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",