create-cmp-cli 0.13.0 → 0.14.1

package/packages/harness/src/lib/component-stories.mjs

@@ -0,0 +1,183 @@
+// component-stories.mjs — the component ↔ story parity gate (the IMP-1
+// screen↔registry parity idea, applied at component granularity).
+//
+// Every `@Composable fun` in `composeApp/src/commonMain/**/presentation/
+// components/*.kt` must have a preview-registry story whose id is
+// `component.<kebab-case-of-the-composable-name>` (AppHeader →
+// "component.app-header"), registered in the desktopMain inspector sources
+// (ComponentStories.kt, or PreviewRegistry.kt for generated conditional
+// components like PlaceholderScreen). The gate fails BOTH directions, like
+// specCoverage: a component with no story (the render pipeline is blind to
+// it) and a story id with no component (a stale story surviving a rename).
+//
+// Detection is a pragmatic source scan, not a Kotlin front-end — the same
+// stance as the console's components scan (inspector/mcp/src/lib/
+// components.mjs, whose @Composable-window heuristic and kebab derivation
+// this file mirrors; keep the two in sync).
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** PascalCase/camelCase → kebab-case: AppHeader → app-header, ListItemCard → list-item-card. */
+export function kebabCase(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/** The registry story id a component of this name must register. */
+export function componentStoryId(name) {
+  return `component.${kebabCase(name)}`;
+}
+
+// How far past an `@Composable` occurrence to look for the `fun Name(` it
+// governs — mirrors the console scan's FUN_SEARCH_WINDOW.
+const FUN_SEARCH_WINDOW = 500;
+
+/**
+ * Every `@Composable fun Name(` declaration name in one file's text —
+ * includes private/internal composables (the console's Components page lists
+ * them, so the parity gate covers them too).
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function findComposableNames(text) {
+  const names = [];
+  const composableRe = /@Composable\b/g;
+  let m;
+  while ((m = composableRe.exec(text))) {
+    const window = text.slice(m.index, m.index + FUN_SEARCH_WINDOW);
+    const funMatch = window.match(/fun\s+(?:<[^>]*>\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/);
+    if (funMatch) names.push(funMatch[1]);
+  }
+  return names;
+}
+
+function walkDirs(root, wanted) {
+  const out = [];
+  (function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const p = path.join(dir, e.name);
+      if (e.name === wanted) out.push(p);
+      else walk(p);
+    }
+  })(root);
+  return out;
+}
+
+function ktFilesIn(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith(".kt"))
+    .map((e) => path.join(dir, e.name));
+}
+
+function walkKtFilesDeep(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkKtFilesDeep(p));
+    else if (e.name.endsWith(".kt")) out.push(p);
+  }
+  return out;
+}
+
+const STORY_ID_RE = /"component\.([a-z0-9][a-z0-9.-]*)"/g;
+
+/**
+ * Evaluate component ↔ story parity for a project root.
+ * SKIPs (never fails) when the surface doesn't exist: no components dir, or
+ * no desktopMain inspector dir (the `--no-inspector` scaffold has no preview
+ * registry to hold stories).
+ * @param {string} root project root (contains composeApp/)
+ * @returns {{verdict: "PASS"|"FAIL"|"SKIP", reason?: string, details?: object}}
+ */
+export function evaluateComponentStoryParity(root) {
+  const commonRoot = path.join(root, "composeApp", "src", "commonMain", "kotlin");
+  const desktopRoot = path.join(root, "composeApp", "src", "desktopMain", "kotlin");
+
+  const componentsDirs = walkDirs(commonRoot, "presentation")
+    .map((p) => path.join(p, "components"))
+    .filter((p) => fs.existsSync(p));
+  if (componentsDirs.length === 0) {
+    return { verdict: "SKIP", reason: "no presentation/components directory under commonMain — nothing to check" };
+  }
+
+  const inspectorDirs = walkDirs(desktopRoot, "inspector");
+  if (inspectorDirs.length === 0) {
+    return {
+      verdict: "SKIP",
+      reason: "no desktopMain inspector sources (preview harness not included) — no story registry to check against",
+    };
+  }
+
+  // Components: every @Composable in the registry dir (direct children only —
+  // the same surface the console's Components page scans).
+  const components = []; // { name, file }
+  for (const dir of componentsDirs) {
+    for (const file of ktFilesIn(dir)) {
+      const rel = path.relative(root, file).split(path.sep).join("/");
+      for (const name of findComposableNames(fs.readFileSync(file, "utf8"))) {
+        components.push({ name, file: rel });
+      }
+    }
+  }
+
+  // Stories: every quoted "component.<kebab>" id in the inspector sources.
+  const storyIds = new Set();
+  for (const dir of inspectorDirs) {
+    for (const file of walkKtFilesDeep(dir)) {
+      const text = fs.readFileSync(file, "utf8");
+      for (const match of text.matchAll(STORY_ID_RE)) {
+        storyIds.add(`component.${match[1]}`);
+      }
+    }
+  }
+
+  const expectedIds = new Map(components.map((c) => [componentStoryId(c.name), c]));
+  const missing = [...expectedIds.entries()].filter(([id]) => !storyIds.has(id));
+  const orphans = [...storyIds].filter((id) => !expectedIds.has(id)).sort();
+
+  const details = {
+    components: components.length,
+    stories: storyIds.size,
+    missing: missing.map(([id]) => id),
+    orphans,
+  };
+
+  if (missing.length === 0 && orphans.length === 0) {
+    return { verdict: "PASS", details };
+  }
+
+  const lines = ["Component ↔ story parity broken — the components registry and its preview stories have drifted apart:"];
+  for (const [id, c] of missing) {
+    lines.push(
+      `  [${c.name}] ${c.file} — no component story registered. Add ScreenPreview("${id}", …) to composeApp/src/desktopMain/**/inspector/ComponentStories.kt (kebab-case of the composable name).`,
+    );
+  }
+  for (const id of orphans) {
+    lines.push(
+      `  ["${id}"] story id has no matching @Composable in presentation/components — remove the stale story or fix the id.`,
+    );
+  }
+  return { verdict: "FAIL", reason: lines.join("\n"), details };
+}

package/packages/harness/src/lib/determinism.mjs

@@ -0,0 +1,179 @@
+// determinism.mjs — the comparison half of the lane's determinism probe.
+//
+// ARCH-13 statically bans ambient time reads (Clock.System, LocalDate.now,
+// TimeZone.currentSystemDefault) in APP code — but a library the app calls
+// can still read the wall clock, and a golden test can still depend on the
+// machine's timezone through a seam the static net cannot see. This project
+// family has already been bitten: a golden tree green at 23:00 and red by
+// morning, because a ViewModel was constructed without its injected clock.
+//
+// The probe (verify.mjs stepDeterminism) runs the JVM test tier TWICE under
+// maximally-shifted timezones and fails iff the two runs' OUTCOMES differ.
+// This module owns the two judgments that make that comparison honest:
+//
+//   - WHAT COUNTS AS AN OUTCOME: a test's verdict (pass/fail/error/skip)
+//     and its failure output — never its duration. Durations are not parsed
+//     at all, so a timing wobble is structurally incapable of tripping the
+//     probe (the brief-level rule "duration is not a difference" is enforced
+//     by construction, not by filtering).
+//
+//   - WHAT THE FAILURE MESSAGE MUST SAY: which test, which lane step owns
+//     it, and the observable difference between the two runs — never a bare
+//     "nondeterministic". A probe whose red is unactionable just teaches
+//     people to turn it off.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The two probe timezones — chosen so the two legs NEVER share a calendar
+ * date, at any instant:
+ *
+ *   Etc/GMT+12 = UTC-12  (POSIX sign convention: Etc/GMT+N means UTC-N)
+ *   Etc/GMT-14 = UTC+14  (the highest real-world offset, Line Islands)
+ *
+ * The offsets are 26 hours apart — more than a full day — so the two legs'
+ * local dates differ at EVERY moment of every day, and any date-derived
+ * value (a "today" default, a day-boundary bucket, a formatted date in a
+ * golden tree) is guaranteed to differ between the legs. A UTC-vs-UTC+14
+ * pair would NOT have this property: those legs share a date for ten hours
+ * of every day, so the probe's power would depend on what time you ran it —
+ * the exact class of flakiness it exists to hunt.
+ */
+export const DETERMINISM_TIMEZONES = [
+  { tz: "Etc/GMT+12", label: "UTC-12" },
+  { tz: "Etc/GMT-14", label: "UTC+14" },
+];
+
+const XML_ENTITIES = { "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&amp;": "&" };
+
+function unescapeXml(s) {
+  return s
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+    .replace(/&(lt|gt|quot|apos|amp);/g, (m) => XML_ENTITIES[m]);
+}
+
+function attr(attrs, name) {
+  const m = attrs.match(new RegExp(`${name}="([^"]*)"`));
+  return m ? unescapeXml(m[1]) : null;
+}
+
+/**
+ * Parse one Gradle JUnit results directory into per-test outcomes.
+ * DELIBERATELY parses only verdict-bearing content: testcase identity,
+ * status, and failure/error text. `time="…"` attributes are never read, so
+ * two runs that differ only in duration produce identical outcome maps.
+ *
+ * @param {string} dir a test-results directory (TEST-*.xml files, flat)
+ * @returns {Record<string, {status: "pass"|"fail"|"error"|"skip", messages: string[]}>}
+ *   keyed by `classname.name`; empty object when the directory is absent
+ *   (the caller decides what an empty leg means — this parser never guesses)
+ */
+export function parseJUnitOutcomes(dir) {
+  const outcomes = {};
+  if (!fs.existsSync(dir)) return outcomes;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.startsWith("TEST-") || !entry.endsWith(".xml")) continue;
+    const xml = fs.readFileSync(path.join(dir, entry), "utf8");
+    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    for (const m of xml.matchAll(caseRe)) {
+      const attrs = m[1];
+      const body = m[2] ?? "";
+      const classname = attr(attrs, "classname") ?? "";
+      const name = attr(attrs, "name") ?? "";
+      if (!classname && !name) continue;
+      let status = "pass";
+      const messages = [];
+      const childRe = /<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/g;
+      for (const c of body.matchAll(childRe)) {
+        status = c[1] === "error" ? "error" : "fail";
+        const message = attr(c[2], "message");
+        const text = c[3] ? unescapeXml(c[3]).trim() : "";
+        messages.push(message ?? text.split("\n")[0] ?? "");
+      }
+      if (status === "pass" && /<skipped\b/.test(body)) status = "skip";
+      outcomes[`${classname}.${name}`] = { status, messages };
+    }
+  }
+  return outcomes;
+}
+
+/**
+ * Which lane step owns a test class — so the probe's failure message names
+ * the step a reader would re-run, not just a class name. The patterns are
+ * the same filters the lane's own gradleTestStep calls use.
+ * @param {string} classname fully-qualified test class
+ * @returns {"goldenTrees"|"conformance"|"a11y"|"unitTests"}
+ */
+export function laneStepForTestClass(classname) {
+  if (/GoldenTreeTest$/.test(classname)) return "goldenTrees";
+  if (/ArchitectureConformanceTest$/.test(classname)) return "conformance";
+  if (/A11yConformanceTest$/.test(classname)) return "a11y";
+  return "unitTests";
+}
+
+function classnameOf(testId) {
+  // testId is `classname.name`; the class is everything before the last dot
+  // segment that starts the (possibly backticked, space-bearing) test name.
+  // Kotlin test names contain dots rarely but spaces often — the classname
+  // never contains a space, so split at the first segment containing one,
+  // falling back to the last dot.
+  const spaceIdx = testId.indexOf(" ");
+  const scope = spaceIdx === -1 ? testId : testId.slice(0, spaceIdx);
+  const lastDot = scope.lastIndexOf(".");
+  return lastDot === -1 ? testId : testId.slice(0, lastDot);
+}
+
+/**
+ * Compare two legs' outcomes. Returns one entry per observable difference,
+ * each carrying everything the failure message must name: the test, the
+ * owning lane step, and what differed between the legs.
+ *
+ * Kinds:
+ *   verdict-flip           different status (pass/fail/error/skip)
+ *   only-in-one-leg        the test executed in one leg only
+ *   failure-text-changed   failed in BOTH legs, but with different output —
+ *                          a date-dependent assertion message is still a
+ *                          timezone leak even when both legs are red
+ *
+ * @param {Record<string, {status: string, messages: string[]}>} a leg A outcomes
+ * @param {Record<string, {status: string, messages: string[]}>} b leg B outcomes
+ * @param {string} labelA human label for leg A (e.g. "TZ=Etc/GMT+12 (UTC-12)")
+ * @param {string} labelB human label for leg B
+ * @returns {Array<{test: string, step: string, kind: string, detail: string}>}
+ */
+export function compareOutcomes(a, b, labelA, labelB) {
+  const diffs = [];
+  const ids = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  for (const id of ids) {
+    const step = laneStepForTestClass(classnameOf(id));
+    const inA = a[id];
+    const inB = b[id];
+    if (!inA || !inB) {
+      const where = inA ? labelA : labelB;
+      const missing = inA ? labelB : labelA;
+      diffs.push({ test: id, step, kind: "only-in-one-leg", detail: `executed under ${where} but produced no result under ${missing}` });
+      continue;
+    }
+    if (inA.status !== inB.status) {
+      const firstLine = (inA.status === "pass" ? inB : inA).messages[0]?.split("\n")[0] ?? "";
+      diffs.push({
+        test: id,
+        step,
+        kind: "verdict-flip",
+        detail: `${inA.status.toUpperCase()} under ${labelA}, ${inB.status.toUpperCase()} under ${labelB}${firstLine ? `: ${firstLine}` : ""}`,
+      });
+      continue;
+    }
+    if (inA.status !== "pass" && inA.messages.join("\n") !== inB.messages.join("\n")) {
+      diffs.push({
+        test: id,
+        step,
+        kind: "failure-text-changed",
+        detail: `failed under both, with different output — ${labelA}: "${inA.messages[0]?.split("\n")[0] ?? ""}" vs ${labelB}: "${inB.messages[0]?.split("\n")[0] ?? ""}"`,
+      });
+    }
+  }
+  return diffs;
+}

package/packages/harness/src/lib/device-lease.mjs

@@ -0,0 +1,249 @@
+// The machine-global device lease — mutual exclusion for the ONE Android
+// device/emulator a machine typically has.
+//
+// WHY THIS EXISTS: the lane marker (composeApp/build/.cmp-lane-in-progress) is
+// per-PROJECT, but the device is machine-GLOBAL. A scratch app stamped in /tmp
+// and the real app are different roots sharing one emulator: each stamps its
+// own marker, neither sees the other, and two concurrent device drivers produce
+// exactly the observed failure class — wedged adbd, `device offline` while
+// `adb devices` looks fine, crossed app state between sessions, false-red runs.
+// The lease is keyed by the DEVICE (its adb serial), not the project, so the
+// primitive finally matches the scarce resource it protects.
+//
+// ── ON-DISK CONTRACT ────────────────────────────────────────────────────────
+// This exact contract is implemented independently by the create-cmp
+// inspector MCP (inspector/mcp/src/lib/device-lease.mjs in the create-cmp
+// repo — a check-only reader for connect_live / navigate_and_inspect). The two
+// codebases ship separately and cannot import each other, so the contract
+// lives verbatim in BOTH file headers, each pointing at the other. Changing
+// anything below means changing it there too.
+//
+//   Location    <os.tmpdir()>/create-cmp/device-leases/<sanitized-serial>.json
+//               tmpdir on purpose: a lease must never survive a reboot.
+//   Sanitizing  serial chars outside [A-Za-z0-9._-] become "_"
+//               ("emulator-5554"    → emulator-5554.json,
+//                "192.168.1.5:5555" → 192.168.1.5_5555.json).
+//   Shape       { "pid": number, "holder": string, "root": string,
+//                 "serial": string, "acquiredAt": ISO-8601 string }
+//               `holder` is a human/agent-readable label naming WHO is driving
+//               ("verify lane e2eSmoke", "connect_live", "fleet-check scratch
+//               lane"); `root` is the holder's project root.
+//   Staleness   a lease is DEAD (silently reclaimable) when EITHER
+//                 - its pid is not alive — process.kill(pid, 0) throws ESRCH.
+//                   EPERM means the process EXISTS under another user: ALIVE.
+//                 - OR acquiredAt is older than MAX_LEASE_AGE_MS.
+//               An unparseable lease file (torn write from a crashed holder)
+//               counts as dead. Readers treat dead as free; only acquirers
+//               delete/overwrite.
+//   Writes      atomic — temp file in the same directory + rename. After the
+//               rename the acquirer re-reads and confirms its OWN pid is in
+//               the file: two simultaneous renames resolve last-writer-wins,
+//               and the loser reports contention instead of believing it holds
+//               the device.
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Dependency-free Node. Every function takes an optional { dir } override so
+// tests exercise real files in a temp dir without touching the machine's
+// actual leases, and an optional { killImpl } so the EPERM-means-alive branch
+// is testable without a foreign-user process.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// 30 minutes: the longest legitimate single holder is a full release-profile
+// device phase on a cold emulator (installDebug + Maestro smoke +
+// connectedDebugAndroidTest + installRelease + release smoke), observed in the
+// low tens of minutes — a live holder is protected by the pid check anyway, so
+// this cap only decides how long a crashed holder whose pid was RECYCLED by an
+// unrelated long-lived process can wedge the device. 30 min bounds that to
+// roughly one lane-length: long enough never to reclaim under a healthy run,
+// short enough that the machine heals itself within the hour.
+export const MAX_LEASE_AGE_MS = 30 * 60 * 1000;
+
+/** Serial → safe file stem: anything outside [A-Za-z0-9._-] becomes "_". */
+export function sanitizeSerial(serial) {
+  return String(serial).replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/** The machine-global lease directory (override with { dir } in tests only). */
+export function leaseDir(dir) {
+  return dir || path.join(os.tmpdir(), "create-cmp", "device-leases");
+}
+
+/** Absolute path of the lease file for one serial. */
+export function leasePath(serial, { dir } = {}) {
+  return path.join(leaseDir(dir), `${sanitizeSerial(serial)}.json`);
+}
+
+/**
+ * Is a pid alive? ESRCH = no such process → dead. EPERM = the process exists
+ * but belongs to another user → ALIVE (killing rights are not liveness).
+ * Any other error is treated as alive — when in doubt, never steal a lease.
+ */
+export function pidAlive(pid, { killImpl = process.kill.bind(process) } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    killImpl(pid, 0);
+    return true;
+  } catch (err) {
+    return !(err && err.code === "ESRCH");
+  }
+}
+
+function readLeaseFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null; // missing OR unparseable — both mean "no live lease here"
+  }
+}
+
+function describeLease(lease, nowMs) {
+  const acquiredMs = Date.parse(lease.acquiredAt);
+  return {
+    holder: lease.holder ?? "unknown",
+    pid: lease.pid ?? null,
+    root: lease.root ?? null,
+    acquiredAt: lease.acquiredAt ?? null,
+    ageMs: Number.isFinite(acquiredMs) ? Math.max(0, nowMs - acquiredMs) : Number.POSITIVE_INFINITY,
+  };
+}
+
+function leaseDead(lease, nowMs, { killImpl } = {}) {
+  if (!pidAlive(lease.pid, { ...(killImpl ? { killImpl } : {}) })) return true;
+  const acquiredMs = Date.parse(lease.acquiredAt);
+  if (!Number.isFinite(acquiredMs)) return true; // no readable birth time — unverifiable, dead
+  return nowMs - acquiredMs >= MAX_LEASE_AGE_MS;
+}
+
+/** `"verify lane e2eSmoke" (pid 4711, /tmp/scratch-x, 2m ago)` — for reasons/errors. */
+export function formatHolder(heldBy) {
+  if (!heldBy) return "an unknown holder";
+  const age =
+    !Number.isFinite(heldBy.ageMs) ? "age unknown"
+    : heldBy.ageMs < 60_000 ? `${Math.max(1, Math.round(heldBy.ageMs / 1000))}s ago`
+    : `${Math.round(heldBy.ageMs / 60_000)}m ago`;
+  return `"${heldBy.holder}" (pid ${heldBy.pid ?? "?"}, ${heldBy.root ?? "unknown root"}, ${age})`;
+}
+
+/**
+ * Read the live lease on a serial, if any. Dead/stale leases read as null
+ * (free) — reading never deletes; reclaim-by-overwrite is the acquirer's job.
+ *
+ * @returns {{holder,pid,root,acquiredAt,ageMs}|null}
+ */
+export function readDeviceLease(serial, { dir, killImpl, now = Date.now } = {}) {
+  const lease = readLeaseFile(leasePath(serial, { dir }));
+  if (!lease) return null;
+  const nowMs = now();
+  if (leaseDead(lease, nowMs, { killImpl })) return null;
+  return describeLease(lease, nowMs);
+}
+
+/**
+ * Acquire the machine-global lease on one device serial.
+ *
+ * @param {{serial: string, holder: string, root: string, dir?: string,
+ *   killImpl?: Function, now?: () => number}} opts
+ * @returns {{ok: true, handle: {file, serial, pid, acquiredAt}, reclaimed: object|null}
+ *   | {ok: false, heldBy: {holder, pid, root, acquiredAt, ageMs}}}
+ *   `reclaimed` names the dead lease this acquire silently replaced (a crashed
+ *   run must never wedge the machine forever) so the acquiring run can note it
+ *   in its own output.
+ */
+export function acquireDeviceLease({ serial, holder, root, dir, killImpl, now = Date.now } = {}) {
+  if (!serial) throw new Error("acquireDeviceLease: serial is required");
+  const d = leaseDir(dir);
+  fs.mkdirSync(d, { recursive: true });
+  const file = leasePath(serial, { dir });
+  const nowMs = now();
+
+  let reclaimed = null;
+  const existing = readLeaseFile(file);
+  if (existing) {
+    if (!leaseDead(existing, nowMs, { killImpl })) {
+      return { ok: false, heldBy: describeLease(existing, nowMs) };
+    }
+    reclaimed = describeLease(existing, nowMs); // dead — reclaim silently
+  } else if (fs.existsSync(file)) {
+    reclaimed = { holder: "unreadable lease (torn write)", pid: null, root: null, acquiredAt: null, ageMs: Number.POSITIVE_INFINITY };
+  }
+
+  const lease = {
+    pid: process.pid,
+    holder: String(holder || "unknown"),
+    root: String(root || process.cwd()),
+    serial: String(serial),
+    acquiredAt: new Date(nowMs).toISOString(),
+  };
+  // Atomic claim: temp file + rename means no reader ever sees a half-written
+  // lease, and two simultaneous acquirers cannot interleave bytes.
+  const tmp = path.join(d, `.${sanitizeSerial(serial)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(lease, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+
+  // Last-writer-wins detection: both racers reached the rename; whoever's bytes
+  // survived owns the device. Re-read and confirm it is US — the loser reports
+  // contention instead of driving a device someone else holds.
+  const confirm = readLeaseFile(file);
+  if (!confirm || confirm.pid !== lease.pid || confirm.acquiredAt !== lease.acquiredAt || confirm.holder !== lease.holder) {
+    return {
+      ok: false,
+      heldBy: confirm
+        ? describeLease(confirm, now())
+        : { holder: "unknown (lease vanished mid-acquire)", pid: null, root: null, acquiredAt: null, ageMs: Number.POSITIVE_INFINITY },
+    };
+  }
+  return { ok: true, handle: { file, serial: lease.serial, pid: lease.pid, acquiredAt: lease.acquiredAt }, reclaimed };
+}
+
+/**
+ * Release a held lease. Idempotent and safe: missing file is fine, and a file
+ * that no longer carries OUR pid+acquiredAt belongs to a newer holder (they
+ * reclaimed us as stale, or won a race) — another holder's lease is NEVER
+ * deleted.
+ */
+export function releaseDeviceLease(handle) {
+  if (!handle || !handle.file) return;
+  const current = readLeaseFile(handle.file);
+  if (!current) return; // already gone (or unreadable — not provably ours, leave it)
+  if (current.pid !== handle.pid || current.acquiredAt !== handle.acquiredAt) return; // someone else's now
+  try {
+    fs.rmSync(handle.file, { force: true });
+  } catch {
+    /* releasing is best-effort; staleness reclaim is the backstop */
+  }
+}
+
+/**
+ * Run `fn(handle)` under the lease, releasing in a finally. Sync or async fn.
+ * A refused acquire is returned as-is ({ok:false, heldBy}) — the caller decides
+ * what contention means (the verify lane turns it into a SKIP, never a FAIL).
+ */
+export function withDeviceLease(opts, fn) {
+  const res = acquireDeviceLease(opts);
+  if (!res.ok) return res;
+  let out;
+  try {
+    out = fn(res.handle);
+  } catch (err) {
+    releaseDeviceLease(res.handle);
+    throw err;
+  }
+  if (out && typeof out.then === "function") {
+    return out.then(
+      (value) => {
+        releaseDeviceLease(res.handle);
+        return { ok: true, result: value, reclaimed: res.reclaimed };
+      },
+      (err) => {
+        releaseDeviceLease(res.handle);
+        throw err;
+      },
+    );
+  }
+  releaseDeviceLease(res.handle);
+  return { ok: true, result: out, reclaimed: res.reclaimed };
+}