verikun 0.26.2 → 0.27.0

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

@@ -37,15 +37,20 @@ examples below use `vk`.
 ## Before you start (once per session)
 
 Run `vk doctor` once before the first device command. Alongside the adb/device checks it
-reports version staleness on stderr — it never fails on that, so treat it as information:
+reports version staleness and host problems on stderr — it never fails on those, so treat
+them as information:
 
 - **`claude-code-plugin: … behind this CLI`** → **this skill file is out of date.** Trust
   `vk --help` over what you read here when they disagree, and tell the user to run
   `claude plugin update verikun@verikun` and restart Claude Code.
 - **`verikun: … npm has <newer>`** → tell the user `npm install -g verikun@latest`.
+- **`adb server: … leaking USB handles`** → **the host's adb server has rotted.** Devices
+  will drop mid-flow for reasons that look like your selectors failing. Tell the user to run
+  `adb kill-server && adb start-server` — safe, and devices reconnect in seconds.
 
 **Tell the user, don't run it.** Upgrading changes their machine, and the plugin path needs
-a Claude Code restart to take effect. Mention it once and move on.
+a Claude Code restart to take effect; restarting adb is host-wide and drops every device on
+the machine, not just yours. Mention it once and move on.
 
 ## The loop: act → inspect → assert
 
@@ -386,7 +391,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   including file; a fragment may include another. Name a fragment `_something.md` — `vk suite`
   skips `_`-prefixed files, so a fragment never runs as a test of its own. Each chunk compiles
   and caches separately, so editing a shared fragment recompiles the fragment, not every test
-  that uses it.
+  that uses it. A title or a description states no step, so it is folded into the chunk of its
+  own file that does, rather than compiled as a test of its own — put it wherever reads best.
 - The plan expresses **conditions** (`if-present`, for optional interstitials like a
   permission dialog) and **bounded loops** (`repeat … until`, e.g. scroll-until) —
   control flow `vk batch` cannot, so a flaky popup or a scroll-to-find no longer breaks

package/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-09-13
+
+### Added
+- **`vk doctor`** warns when the host's adb server has leaked USB handles, naming the restart that fixes it.
+- **`vk server`** restarts a rotted adb server while idle; `VERIKUN_NO_ADB_RECYCLE=1` opts out.
+
+### Changed
+- **Docs**: every page trimmed to what a reader needs; history and design rationale removed, gotchas kept, open issues linked.
+
+## [0.26.3] - 2026-09-11
+
+A `vk ai` test's description is no longer compiled into steps of its own.
+
+### Fixed
+- **`vk ai`** no longer compiles a title or description above an `@include` as a test of its
+  own, inventing steps that then ran first. ([#133])
+
+[#133]: https://github.com/ddikman/verikun/issues/133
+
 ## [0.26.2] - 2026-09-10
 
 Android hierarchy reads no longer mistake a sheet's or dialog's barrier for an empty screen.

package/README.md

@@ -8,7 +8,7 @@
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
 - **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. A compile that does not cover its test is rejected rather than cached as a pass. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
-- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad.
+- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad — including restarting a host adb server that has started dropping them.
 
 ```
 $ vk ui

package/dist/adb-health.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Is the HOST's adb server healthy, or has it rotted?
+ *
+ * A long-lived adb server leaks IOKit Mach ports and never recovers. Measured on macOS
+ * 2026-09-12: a 9-day-old server logging EXC_GUARD `GUARD_TYPE_MACH_PORT` / `INVALID_NAME`
+ * at 2/sec — 27,983 in 7h, every one of them from the adb pid — having burned 92 minutes
+ * of CPU on the error loop. `adb kill-server && adb start-server` took it to zero and every
+ * device came back in ~5s.
+ *
+ * WHY VERIKUN CARES, rather than leaving this to the operator: adb rot DEFEATS DEVICE
+ * FAILOVER. `device/failover.ts` moves the server off a device that fails, but every
+ * candidate sits behind the same host adb — so when the transport is what broke, failover
+ * walks the pool retiring healthy phones for a host-side fault. That is the same polarity
+ * error `ARTIFACT_RULES` exists to prevent on the install path: enumerate the thing you can
+ * actually attribute, and never blame the open-ended side.
+ *
+ * THE RATE IS A LEAKED-HANDLE COUNTER, which is what makes this measurable rather than
+ * guessed. adb scans USB at ~1Hz and each STALE device handle throws one violation per
+ * pass, so the per-minute count reads directly as "how many handles adb has leaked". It
+ * stepped 59 -> 118/min at the exact second a device re-enumerated, and never came back
+ * down. A healthy server sits at exactly 0.
+ *
+ * EVIDENCE, NEVER AGE, is the trigger — see `adbServerRotting`. Age alone would restart a
+ * perfectly good server, which for a default-on behaviour is a new way to fail; the whole
+ * point of a measured signal is that a healthy host is never disturbed.
+ *
+ * macOS-only, and that is honest rather than lazy: EXC_GUARD and Mach ports do not exist on
+ * Linux, and the rot has not been measured there. Everywhere else this reports `undefined`
+ * and every caller degrades to doing nothing — never to a blind restart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIOLATION_WINDOW_MS = void 0;
+exports.parseEtime = parseEtime;
+exports.countViolations = countViolations;
+exports.adbServerRotting = adbServerRotting;
+exports.describeRot = describeRot;
+exports.adbRecycleEnabled = adbRecycleEnabled;
+exports.adbServerHealth = adbServerHealth;
+exports.adbHealthProbe = adbHealthProbe;
+exports.recycleAdbServer = recycleAdbServer;
+const node_os_1 = require("node:os");
+const exec_1 = require("./exec");
+/** The window we count violations over. Long enough that a ~1Hz loop is unmissable, short
+ *  enough that `log show` stays ~1s (measured: 1.2s for 2m). */
+exports.VIOLATION_WINDOW_MS = 2 * 60 * 1000;
+/**
+ * `log`'s own absolute path, not a bare `log`. Belt-and-braces against a shadowing shell
+ * function (the author hit exactly that while investigating: `log` was a zsh function and
+ * every query failed with "too many arguments"). We spawn without a shell so this cannot
+ * bite us today, but the absolute path costs nothing and documents the hazard.
+ */
+const LOG_BIN = '/usr/bin/log';
+/**
+ * Match the kernel's report of adb's guard violations, and NOTHING else.
+ *
+ * All three clauses are load-bearing. Without `process == "kernel"` this matches unrelated
+ * processes; without the `[adb:` clause it matches any process's guard violations, and a
+ * host with an unrelated misbehaving binary would be told its adb had rotted. The line the
+ * kernel actually emits:
+ *
+ *   ERROR: [adb:96399] EXC_GUARD AST: type=0x1 flavor=0x200 target=0x24d7 ...
+ */
+const VIOLATION_PREDICATE = 'process == "kernel" AND eventMessage CONTAINS "EXC_GUARD" AND eventMessage CONTAINS "[adb:"';
+/**
+ * `ps -o etime=` elapsed time -> ms. Formats, narrowest first: `MM:SS`, `HH:MM:SS`,
+ * `DD-HH:MM:SS`. Returns undefined rather than throwing on anything unrecognised — this
+ * feeds an advisory, and a parse failure must degrade to silence, never to a wrong number.
+ */
+function parseEtime(raw) {
+    const s = raw.trim();
+    if (!s)
+        return undefined;
+    const [days, clock] = s.includes('-') ? s.split('-', 2) : ['0', s];
+    const parts = clock.split(':');
+    if (parts.length < 2 || parts.length > 3)
+        return undefined;
+    // Test the DIGITS, not Number(): `Number('')` is 0, not NaN, so a leading '-' ("-5:00")
+    // would otherwise parse as a happy five minutes instead of being rejected.
+    const fields = [days, ...parts];
+    if (!fields.every((f) => /^\d+$/.test(f)))
+        return undefined;
+    const nums = fields.map((f) => Number(f));
+    const [d, ...rest] = nums;
+    const [h, m, sec] = rest.length === 3 ? rest : [0, ...rest];
+    return ((d * 24 + h) * 60 * 60 + m * 60 + sec) * 1000;
+}
+/**
+ * Count real events in `log show --style compact` output.
+ *
+ * It ALWAYS prints a `Timestamp Ty Process[PID:TID]` header, so a naive line count reports
+ * 1 on a perfectly healthy host — which would make every caller cry rot forever. Counting
+ * only lines that name adb is both the fix and a second guard on the predicate.
+ */
+function countViolations(stdout) {
+    return stdout.split('\n').filter((l) => l.includes('[adb:')).length;
+}
+/**
+ * Has this adb server rotted? Evidence only.
+ *
+ * A healthy server produces EXACTLY zero over the window (measured repeatedly on a freshly
+ * restarted one), and a rotted one produces 60-120 per minute — there is no middle ground
+ * to tune a threshold against, so any nonzero count is the signal. `undefined` violations
+ * (not macOS, or the query failed) is NEVER rot: we do not restart on a hunch.
+ */
+function adbServerRotting(health) {
+    return (health.violations ?? 0) > 0;
+}
+/** One line a human can act on, or undefined when there is nothing worth saying. */
+function describeRot(health) {
+    if (!adbServerRotting(health))
+        return undefined;
+    const perMin = Math.round((health.violations / (health.windowMs ?? exports.VIOLATION_WINDOW_MS)) * 60_000);
+    const age = health.ageMs !== undefined ? `, up ${Math.floor(health.ageMs / 3_600_000)}h` : '';
+    return `adb server is leaking USB handles (~${perMin} kernel guard violations/min${age}) — devices will drop`;
+}
+/**
+ * Is the idle adb-server recycle active? ONE definition, because two callers ask — the
+ * server's timer and its startup banner — and a banner that disagrees with the behaviour is
+ * worse than no banner at all.
+ *
+ * Android only: `adb` is the only transport that rots this way, so an iOS server never pays
+ * for the check. On by default (`vk server` is built to sit on a CI host for days, which is
+ * the condition that rots it); `VERIKUN_NO_ADB_RECYCLE=1` restores the previous behaviour
+ * exactly, for the rare host running other adb work alongside the server.
+ */
+function adbRecycleEnabled(platform) {
+    return platform === 'android' && process.env.VERIKUN_NO_ADB_RECYCLE !== '1';
+}
+/** The running adb server's pid. Undefined when there is none, or when `pgrep` is absent. */
+function adbServerPid() {
+    try {
+        // `adb -L tcp:5037 fork-server server` is the canonical argv; match loosely so a
+        // non-default port or an ADB_SERVER_SOCKET still resolves.
+        const r = (0, exec_1.runText)('pgrep', ['-f', 'adb.*fork-server'], { timeout: 5000 });
+        const pid = Number(r.stdout.split('\n')[0]?.trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How long pid has been running, via `ps -o etime=`. */
+function processAgeMs(pid) {
+    try {
+        const r = (0, exec_1.runText)('ps', ['-p', String(pid), '-o', 'etime='], { timeout: 5000 });
+        return parseEtime(r.stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Survey the host's adb server. Never throws: every probe is wrapped, and an unavailable
+ * signal comes back `undefined` so callers do nothing rather than something wrong.
+ */
+function adbServerHealth(windowMs = exports.VIOLATION_WINDOW_MS) {
+    const pid = adbServerPid();
+    const health = { pid, ageMs: pid ? processAgeMs(pid) : undefined };
+    if ((0, node_os_1.platform)() !== 'darwin' || !pid)
+        return health;
+    try {
+        const secs = Math.max(1, Math.round(windowMs / 1000));
+        const r = (0, exec_1.runText)(LOG_BIN, ['show', '--last', `${secs}s`, '--style', 'compact', '--predicate', VIOLATION_PREDICATE], {
+            timeout: 20000,
+        });
+        if (r.code !== 0)
+            return health;
+        return { ...health, violations: countViolations(r.stdout), windowMs };
+    }
+    catch {
+        return health; // log(1) missing, sandboxed, or slow — no opinion, not a failure
+    }
+}
+/**
+ * The `vk doctor` line. ADVISORY, always: a rotted adb server is a thing to fix, not a
+ * machine that cannot drive a device, and exit 3 is reserved for the latter. Returns null
+ * when there is nothing to say, so doctor stays quiet on a healthy host.
+ */
+function adbHealthProbe(health = adbServerHealth()) {
+    const detail = describeRot(health);
+    if (!detail)
+        return null;
+    return {
+        name: 'adb server',
+        ok: true,
+        advisory: true,
+        detail,
+        hint: 'restart it: `adb kill-server && adb start-server` (safe; devices reconnect in a few seconds)',
+    };
+}
+/**
+ * Restart the host's adb server. Returns whether it came back.
+ *
+ * HOST-GLOBAL and therefore never called speculatively — `kill-server` drops every
+ * transport on the machine, including devices this process does not own. Callers must have
+ * evidence (`adbServerRotting`) and, on the server, an idle pool.
+ */
+function recycleAdbServer(adb) {
+    try {
+        (0, exec_1.runText)(adb, ['kill-server'], { timeout: 20000 });
+        const r = (0, exec_1.runText)(adb, ['start-server'], { timeout: 30000 });
+        return r.code === 0;
+    }
+    catch {
+        return false; // never a new way to fail: the caller logs and carries on
+    }
+}

package/dist/agent/include.js

@@ -9,25 +9,30 @@
 // because the preamble is conditional ("dismiss whichever of these six screens is present"),
 // which is exactly the part only `vk ai` can express.
 //
-// Two properties make the mechanism honest:
+// Three properties make the mechanism honest:
 //
 //  - **The resolved text is the cache key.** Callers hash `nl` (fragments already inlined),
 //    so editing a fragment invalidates every test that includes it. Keying on the top-level
 //    file would silently replay stale plans for all of them.
 //  - **A fragment is not a test.** `vk suite` skips `_`-prefixed files and never recurses
 //    into subdirectories, so a fragment gets no report row and no `--app` data reset.
+//  - **A chunk is a whole prompt, so a chunk that is not a test must not become one.** Prose
+//    that only describes the test is folded into the chunk of its own file that states the
+//    steps it describes, never compiled alone (groupDescriptions, issue #133).
 //
-// `segments` is what makes the compile CHEAP as well as short: each contiguous chunk of
-// prose is compiled on its own and cached under its own key, so a preamble shared by nine
-// tests is compiled ONCE (see compileFromSegments in cli.ts). Splicing happens at the plan
-// level, which the shallow IR allows — a plan is a flat list of steps.
+// `segments` is what makes the compile CHEAP as well as short: each chunk of prose is
+// compiled on its own and cached under its own key, so a preamble shared by nine tests is
+// compiled ONCE (see compileFromSegments in cli.ts). Splicing happens at the plan level,
+// which the shallow IR allows — a plan is a flat list of steps.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasInstruction = hasInstruction;
+exports.statesInstruction = statesInstruction;
 exports.resolveIncludes = resolveIncludes;
 exports.segmentLabel = segmentLabel;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const errors_1 = require("../errors");
+const lint_1 = require("./lint");
 /** An include directive: `@include <path>` alone on a line (leading space allowed).
  *  Deliberately a whole-line form — a path is everything after the keyword, so it needs
  *  no quoting and can contain spaces. */
@@ -47,6 +52,47 @@ function hasInstruction(text) {
     const bare = text.replace(/<!--[\s\S]*?-->/g, '');
     return bare.split('\n').some((line) => line.trim() !== '' && !DECORATION_RE.test(line));
 }
+/** A list item of ANY kind — ordered or bulleted. `lint.ts` counts only ORDERED items, because
+ *  there an unordered bullet carrying explanation would inflate the expected plan size and
+ *  manufacture a rejection. Here the polarity is reversed: a bulleted preamble
+ *  ("- Launch the app with its data cleared.") is a list of steps, and missing it is what would
+ *  do damage. */
+const LIST_ITEM_RE = /^\s*(?:\d+[.)]|[-*+])\s+/;
+/**
+ * Does this chunk STATE a step, or only DESCRIBE the test?
+ *
+ * Deliberately NOT `lint.ts`'s `instructionUnits(text) > 0`, even though that counter answers a
+ * neighbouring question. It is documented as biased to UNDERCOUNT, which is safe where it is
+ * used ("an undercount only weakens detection, while an overcount would reject a correct plan")
+ * and exactly backwards here, where an undercount means calling a real step a description.
+ * Measured, all scoring zero units: a bulleted preamble, "First, launch the app.", and this
+ * repo's own `_launch-to-home.md` reworded to open with its subject instead of its verb.
+ *
+ * So this asks for POSITIVE EVIDENCE and errs the other way — a list item of any kind, or one
+ * of the same verbs `lint.ts` knows appearing ANYWHERE in a line rather than only at its start.
+ * Every misreading it can still make is the safe one: a description that happens to contain
+ * "check" or "wait" reads as a step and is compiled alone, which is what happened before this
+ * existed. Nothing regresses; some things stop being fabricated.
+ *
+ * Exported solely so the unit suite can reach it.
+ */
+function statesInstruction(text) {
+    let fenced = false;
+    for (const line of text.replace(/<!--[\s\S]*?-->/g, '').split('\n')) {
+        if (FENCE_RE.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        if (LIST_ITEM_RE.test(line))
+            return true;
+        for (const word of line.toLowerCase().match(/[a-z]+/g) ?? [])
+            if (lint_1.IMPERATIVES.has(word))
+                return true;
+    }
+    return false;
+}
 const endWithNewline = (s) => (s.endsWith('\n') ? s : `${s}\n`);
 const readFile = (path) => (0, node_fs_1.readFileSync)(path, 'utf8');
 /**
@@ -58,17 +104,21 @@ const readFile = (path) => (0, node_fs_1.readFileSync)(path, 'utf8');
  * otherwise expand until it ran out of memory.
  */
 function resolveIncludes(file, read = readFile) {
-    const segments = [];
-    const nl = expand((0, node_path_1.resolve)(process.cwd(), file), [], segments, read, null);
-    return { nl, segments };
+    const ex = { out: [], read, units: 0 };
+    // `nl` is assembled from `parts`, independently of `ex.out`, so regrouping the chunks below
+    // cannot change the resolved text — and therefore cannot change the whole-test cache key, nor
+    // what the assembled-plan lint is asked about.
+    const nl = expand((0, node_path_1.resolve)(process.cwd(), file), [], ex, null);
+    return { nl, segments: groupDescriptions(ex.out) };
 }
-function expand(path, stack, out, read, from) {
+function expand(path, stack, ex, from) {
+    const unit = ex.units++;
     if (stack.includes(path)) {
         throw new errors_1.CliError(`ai: include cycle — ${[...stack, path].map((p) => shortName(p)).join(' → ')}`, 2);
     }
     let text;
     try {
-        text = read(path);
+        text = ex.read(path);
     }
     catch (e) {
         const where = from ? ` (included from ${from})` : '';
@@ -91,8 +141,9 @@ function expand(path, stack, out, read, from) {
         // The label points at the chunk's first real line, not at the blank line that
         // separated it from the include above it.
         const lead = buf.findIndex((l) => l.trim() !== '');
-        if (lead >= 0)
-            out.push({ text: chunk, source: path, startLine: bufStart + lead, compilable: hasInstruction(chunk) });
+        if (lead >= 0) {
+            ex.out.push({ text: chunk, source: path, startLine: bufStart + lead, compilable: hasInstruction(chunk), unit });
+        }
         buf = [];
     };
     lines.forEach((line, i) => {
@@ -106,11 +157,87 @@ function expand(path, stack, out, read, from) {
             return;
         }
         flush();
-        parts.push(endWithNewline(expand((0, node_path_1.resolve)((0, node_path_1.dirname)(path), m[1]), [...stack, path], out, read, `${shortName(path)}:${i + 1}`)));
+        parts.push(endWithNewline(expand((0, node_path_1.resolve)((0, node_path_1.dirname)(path), m[1]), [...stack, path], ex, `${shortName(path)}:${i + 1}`)));
     });
     flush();
     return parts.join('');
 }
+/**
+ * The chunk a description folds into: the next chunk of its OWN expansion that states a step,
+ * else the previous one. `-1` when that expansion states no step anywhere.
+ *
+ * Scanning by EXPANSION rather than by path is what keeps a fragment included twice identical in
+ * both places. Scanning by FILE rather than simply "the next chunk" is the load-bearing half:
+ * the next chunk is normally the fragment the `@include` pulled in, and folding a per-test
+ * description into it would change the FRAGMENT's cache key per test, destroying the
+ * compiled-once property `@include` exists for. Another expansion's chunks are skipped OVER, not
+ * stopped at — reaching across the include to the file's own next chunk is the entire point.
+ */
+function hostFor(raw, describes, i) {
+    const usable = (j) => raw[j].unit === raw[i].unit && raw[j].compilable && !describes[j];
+    for (let j = i + 1; j < raw.length; j++)
+        if (usable(j))
+            return j;
+    for (let j = i - 1; j >= 0; j--)
+        if (usable(j))
+            return j;
+    return -1;
+}
+const plain = ({ text, source, startLine, compilable }) => ({ text, source, startLine, compilable });
+/**
+ * Fold a chunk that only DESCRIBES the test into the chunk of the same file that states the
+ * steps it describes (issue #133).
+ *
+ * A title and a summary paragraph written above the first `@include` used to become a chunk of
+ * its own — and a chunk is a whole prompt. Compiled alone, the summary IS the test, so the model
+ * invents a plan for it and those steps are spliced AHEAD of the launch the include was there to
+ * perform; the reported case was 34 fabricated steps whose first act was to tap a login button on
+ * the Android launcher. `SECTION_NOTE` has told the model since `@include` shipped that a summary
+ * is not an instruction, and it still went the wrong way on 5 of 14 tests in one run: whether
+ * prose reads as a spec is a model judgement, so the fix has to be deterministic.
+ *
+ * A STRICT IMPROVEMENT, deliberately: every chunk either folds into a neighbour or is left
+ * exactly as it was. There is no third disposition, and in particular nothing is DROPPED — prose
+ * this pass discarded would be prose the model never sees, and a fragment wrongly discarded is a
+ * suite that silently stops launching its app. No coverage rule could catch that: the floor and
+ * the tail anchors both measure `nl`, which this pass does not touch.
+ */
+function groupDescriptions(raw) {
+    const describes = raw.map((s) => s.compilable && !statesInstruction(s.text));
+    const host = raw.map((_, i) => (describes[i] ? hostFor(raw, describes, i) : -1));
+    // The overwhelmingly common case — no description, or one with nowhere to go — allocates
+    // nothing and is byte-identical to the behaviour before this pass existed.
+    if (host.every((h) => h < 0))
+        return raw.map(plain);
+    const out = [];
+    const slot = new Map(); // index in `raw` -> index in `out`
+    raw.forEach((s, i) => {
+        if (host[i] >= 0)
+            return; // folded into its host below
+        slot.set(i, out.length);
+        out.push(plain(s));
+    });
+    // Prepends run BACKWARDS and appends run FORWARDS. Not a style choice: each fold lands at the
+    // host's edge, so whichever is written LAST ends up nearest the host. A file with two
+    // descriptions separated by two includes has to come out in the order its author wrote them,
+    // and a single pass in either direction reverses one of those two chains.
+    for (let i = raw.length - 1; i >= 0; i--) {
+        if (host[i] <= i)
+            continue;
+        const at = slot.get(host[i]);
+        // The earlier line, so `segmentLabel` names where the folded text now begins. That label is
+        // the accounting for the fold: a chunk that printed as `t.md:8` prints as `t.md:1`, and the
+        // "assembled from N chunk(s)" line drops by one. No prose moves unannounced.
+        out[at] = { ...out[at], text: raw[i].text + out[at].text, startLine: Math.min(out[at].startLine, raw[i].startLine) };
+    }
+    for (let i = 0; i < raw.length; i++) {
+        if (host[i] < 0 || host[i] > i)
+            continue;
+        const at = slot.get(host[i]);
+        out[at] = { ...out[at], text: out[at].text + raw[i].text };
+    }
+    return out;
+}
 /** A path as a human reads it: relative to the cwd when it is below it. */
 function shortName(path) {
     const cwd = `${process.cwd()}/`;

package/dist/agent/lint.js

@@ -28,6 +28,7 @@
 // rule requires a fairly unambiguous phrase and checks for a specific structural counterpart.
 // It never edits the plan; the model gets the feedback and stays the author.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPERATIVES = void 0;
 exports.coverageChecksEnabled = coverageChecksEnabled;
 exports.instructionLines = instructionLines;
 exports.instructionUnits = instructionUnits;
@@ -87,8 +88,15 @@ const FENCE_RE = /^\s*(```|~~~)/;
  * Verbs that open an instruction. A CLOSED set, and a tight one — every entry here raises
  * the expected plan size, so a loose entry costs a false rejection while a missing one only
  * costs detection. The floor below is generous enough to absorb the resulting undercount.
+ *
+ * Exported for ONE other consumer, `agent/include.ts`, which asks a different question of the
+ * same vocabulary: not "how many steps does this prose state" but "does it state one at all".
+ * Shared rather than copied for the reason `pidAlive` is shared with `agent/plan-lock.ts` — a
+ * second list of verbs drifts from this one invisibly. Note that it is NOT part of
+ * `COMPILER_FINGERPRINT`, so an edit here moves a chunk boundary as well as a lint threshold;
+ * the version bump such an edit already requires is what rotates the fingerprint.
  */
-const IMPERATIVES = new Set([
+exports.IMPERATIVES = new Set([
     'tap', 'press', 'click', 'type', 'enter', 'fill',
     'launch', 'open', 'start', 'restart', 'relaunch', 'stop', 'close',
     'confirm', 'verify', 'assert', 'check', 'ensure',
@@ -121,7 +129,7 @@ function instructionLines(nl) {
         const body = (ordered ? raw.replace(ORDERED_ITEM_RE, '') : raw).trim();
         if (!body)
             continue;
-        if (ordered || IMPERATIVES.has((/^([A-Za-z]+)/.exec(body)?.[1] ?? '').toLowerCase()))
+        if (ordered || exports.IMPERATIVES.has((/^([A-Za-z]+)/.exec(body)?.[1] ?? '').toLowerCase()))
             out.push(body);
     }
     return out;

package/dist/cli.js

@@ -93,6 +93,7 @@ const suite_1 = require("./suite");
 const failover_1 = require("./device/failover");
 const wait_1 = require("./wait");
 const version_1 = require("./version");
+const adb_health_1 = require("./adb-health");
 const update_check_1 = require("./update-check");
 const auto_wait_1 = require("./commands/auto-wait");
 const batch_1 = require("./commands/batch");
@@ -475,6 +476,12 @@ async function cmdDoctor(ctx) {
     const adb = process.env.ADB || 'adb';
     if (!reportProbe((0, drivers_1.probeAdb)()))
         return 3;
+    // adb being PRESENT is not the same as adb being WELL: a long-lived server leaks USB
+    // handles and starts dropping devices mid-run, and no device-level remedy reaches it
+    // (see adb-health.ts). Advisory and evidence-only, so a healthy host stays silent.
+    const adbRot = (0, adb_health_1.adbHealthProbe)();
+    if (adbRot)
+        reportProbe(adbRot);
     const devices = ctx.driver.listDevices();
     const usable = devices.filter((d) => d.state === 'device');
     const claims = (0, claims_1.claimsEnabled)();

package/dist/server.js

@@ -58,6 +58,7 @@ const server_pool_1 = require("./server-pool");
 const ir_1 = require("./agent/ir");
 const rpc_1 = require("./rpc");
 const cli_1 = require("./cli");
+const adb_health_1 = require("./adb-health");
 const wait_1 = require("./wait");
 const version_1 = require("./version");
 /**
@@ -89,6 +90,10 @@ const LOCK_IDLE_MS = 5 * 60 * 1000;
 // comfortably inside the client's 15-minute install ceiling at ~1 minute an install,
 // while a farm of ten wedged emulators cannot burn ten installs inside one request.
 const MAX_FAILOVER_HOPS = 2;
+// How often to ask whether the host's adb server has rotted. Generous on purpose: the
+// check shells out to `log show` (~1s) and the condition it looks for accumulates over
+// DAYS, so a tight interval would buy nothing and spend host time on every idle server.
+const ADB_RECYCLE_CHECK_MS = 10 * 60 * 1000;
 // Gap between the two probes that separate a momentary blip from a dead device. Mirrors
 // suite.ts's stillBroken, and for the same reason: a flaky dump also surfaces as exit 3,
 // so acting on one probe would rotate the pool on ordinary flake.
@@ -448,6 +453,72 @@ function buildServer(config) {
     // The first timer this server has ever had, so this is the first thing that could hold the
     // process open after Ctrl-C. It must not.
     reconcileTimer?.unref?.();
+    // --- adb server recycle ----------------------------------------------------
+    //
+    // A long-lived adb server leaks USB handles until it drops devices mid-run, and only a
+    // restart cures it (the measurements: `adb-health.ts`). `vk server` is BUILT to sit on a
+    // CI host for days — precisely the condition that rots it — so this is ON by default:
+    // on a dedicated box, recycling a broken transport is the expected behaviour, not a
+    // surprise. `VERIKUN_NO_ADB_RECYCLE=1` opts out, for the rare host running other adb
+    // work beside the server; that restores today's behaviour exactly, the equivalence
+    // `VERIKUN_NO_CLAIM` and `VERIKUN_NO_FAILOVER` are held to.
+    //
+    // Three properties are what make a DEFAULT-ON, HOST-GLOBAL restart safe:
+    //
+    //   * EVIDENCE, NEVER AGE. A healthy server measures exactly zero violations, so a
+    //     healthy host is never touched. Age alone would restart a perfectly good server on
+    //     a timer — a new way to fail, which is the one thing this may not add.
+    //   * FULLY IDLE ONLY. `kill-server` drops every transport on the machine, so anything
+    //     mid-run vetoes. `othersActive` is the existing predicate for that and already
+    //     steps over an idle lease, so a crashed client cannot wedge this forever.
+    //   * ANDROID ONLY — and in practice macOS only, since `adbServerHealth` reports no
+    //     evidence elsewhere and no-evidence is never rot. An iOS server never pays for it.
+    //
+    // The residual race is a client arriving during the ~2s restart and getting a busy
+    // error. Accepted deliberately: we only ever get here when adb is ALREADY broken, so
+    // that client's alternative was a server that drops its device mid-suite. An honest
+    // refusal beats a half-dead transport. `exclusive` is held across the restart so the
+    // refusal is the clean one the lease layer already knows how to give.
+    const adbRecycleOn = (0, adb_health_1.adbRecycleEnabled)(config.platform);
+    const RECYCLE_TOKEN = '__adb-recycle__';
+    const recycleAdbIfRotten = async () => {
+        // Cheap gate first: never shell out to `log show` while the server is working.
+        if (othersActive(RECYCLE_TOKEN) || inFlight.size > 0)
+            return;
+        const health = (0, adb_health_1.adbServerHealth)();
+        if (!(0, adb_health_1.adbServerRotting)(health))
+            return;
+        await serializeFailover(async () => {
+            // Re-check inside the queue: the health probe shells out for ~1s, which is ample
+            // time for a run to start, and by here we are about to cut every transport.
+            if (othersActive(RECYCLE_TOKEN) || inFlight.size > 0)
+                return;
+            (0, output_1.err)(`[server] ${(0, adb_health_1.describeRot)(health)}`);
+            exclusive = RECYCLE_TOKEN;
+            try {
+                const ok = (0, adb_health_1.recycleAdbServer)(process.env.ADB || 'adb');
+                (0, output_1.err)(ok ? '[server] adb server restarted — devices reconnecting' : '[server] adb server restart failed — continuing');
+            }
+            finally {
+                exclusive = null;
+            }
+        });
+    };
+    let recycling = false;
+    const recycleTimer = adbRecycleOn
+        ? setInterval(() => {
+            if (recycling)
+                return;
+            recycling = true;
+            void recycleAdbIfRotten()
+                .catch((e) => (0, output_1.err)(`[server] adb recycle check failed — ${(0, server_http_1.firstLine)(e.message)}`))
+                .finally(() => {
+                recycling = false;
+            });
+        }, ADB_RECYCLE_CHECK_MS)
+        : null;
+    // Like the reconcile timer: must never hold the process open at Ctrl-C.
+    recycleTimer?.unref?.();
     const pickFailoverDevice = (failed, reason) => serializeFailover(() => pickFailoverDeviceLocked(failed, reason));
     /**
      * Bring in a healthy replacement for `failed`. Returns the serial moved to, or null
@@ -1679,6 +1750,8 @@ function buildServer(config) {
     server.on('close', () => {
         if (reconcileTimer)
             clearInterval(reconcileTimer);
+        if (recycleTimer)
+            clearInterval(recycleTimer);
         dropRetainedInstall();
     });
     return server;
@@ -1906,6 +1979,14 @@ async function cmdServer(positionals, flags) {
                 (0, output_1.err)('[server] NOTE: an authenticated client can now power-cycle AND erase this device.');
             }
             (0, output_1.err)(`[server] failover: ${failover.why}`);
+            // Announced in both states, like the failover kill switch. ON is worth saying because
+            // `adb kill-server` is host-global and an operator should not meet it as a surprise;
+            // OFF is worth saying because a rotted adb server is otherwise a baffling flake.
+            if (platform === 'android') {
+                (0, output_1.err)(`[server] adb recycle: ${(0, adb_health_1.adbRecycleEnabled)(platform)
+                    ? 'on — a rotted adb server is restarted while idle (VERIKUN_NO_ADB_RECYCLE=1 to disable)'
+                    : 'disabled (VERIKUN_NO_ADB_RECYCLE)'}`);
+            }
             (0, output_1.err)(serverLog
                 ? `[server] log: ${serverLog.path} (--log-file ${server_log_1.LOG_OFF} to disable)`
                 : `[server] log: stderr only (--log-file ${server_log_1.LOG_OFF})`);

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.26.2';
+exports.VERSION = '0.27.0';

package/package.json

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