lynkeus 0.2.0 → 0.4.0

package/lib/knowledge/lint.js

@@ -20,7 +20,7 @@ export const lintScreen = (screen, options = {}) => {
     for (const e of els) {
         const named = e.text ?? e.accessibilityLabel;
         if ((e.kind === 'button' || e.kind === 'switch') && named === undefined && e.testId === undefined) {
-            out.push({ rule: 'unlabeled-control', severity: 'warn', element: e.i, message: `${e.kind} with no text, label or testId` });
+            out.push({ rule: 'unlabeled-control', severity: 'warn', element: e.i, message: `${e.kind} with no text, label or testId`, subject: e.kind });
         }
         if ((e.kind === 'button' || e.kind === 'switch') && e.enabled !== false && e.frame) {
             const { w, h } = e.frame;
@@ -32,11 +32,12 @@ export const lintScreen = (screen, options = {}) => {
                     severity: iconOnly ? 'warn' : 'info',
                     element: e.i,
                     message: `${Math.round(w)}×${Math.round(h)}pt target (< ${minTouch}) ${label(e) ?? ''}`.trim(),
+                    subject: label(e) ?? e.kind,
                 });
             }
         }
         if (e.kind === 'text' && e.text && looksLikeI18nKey(e.text, options.i18nKeyPatterns ?? DEFAULT_I18N_KEY_PATTERNS)) {
-            out.push({ rule: 'untranslated', severity: 'warn', element: e.i, message: `"${e.text}" looks like an i18n key, not copy` });
+            out.push({ rule: 'untranslated', severity: 'warn', element: e.i, message: `"${e.text}" looks like an i18n key, not copy`, subject: e.text });
         }
         if ((e.kind === 'button' || e.kind === 'input' || e.kind === 'switch') && e.covered && e.enabled !== false) {
             out.push({
@@ -44,6 +45,7 @@ export const lintScreen = (screen, options = {}) => {
                 severity: 'info',
                 element: e.i,
                 message: `${e.kind} ${label(e) ?? ''} is covered; a tap would not reach it`.replace('  ', ' ').trim(),
+                subject: label(e) ?? e.kind,
             });
         }
         if (e.frame && win.w > 0 && label(e) !== undefined) {
@@ -54,6 +56,7 @@ export const lintScreen = (screen, options = {}) => {
                     severity: 'info',
                     element: e.i,
                     message: `${label(e)} extends past the ${win.w}×${win.h} window (x${Math.round(x)} y${Math.round(y)} ${Math.round(w)}×${Math.round(h)})`,
+                    subject: label(e),
                 });
             }
         }
@@ -63,6 +66,7 @@ export const lintScreen = (screen, options = {}) => {
                 severity: 'info',
                 element: e.i,
                 message: `"${e.text.slice(0, 30)}" has ${Math.round(e.frame.w)}×${Math.round(e.frame.h)} size`,
+                subject: e.text,
             });
         }
     }
@@ -76,7 +80,13 @@ export const lintScreen = (screen, options = {}) => {
     }
     for (const [id, at] of byTestId)
         if (at.length > 1)
-            out.push({ rule: 'duplicate-testid', severity: 'info', element: at[0], message: `testId "${id}" is on ${at.length} elements (${at.join(', ')})` });
+            out.push({
+                rule: 'duplicate-testid',
+                severity: 'info',
+                element: at[0],
+                message: `testId "${id}" is on ${at.length} elements (${at.join(', ')})`,
+                subject: id,
+            });
     return out;
 };
 export const describeFindings = (findings, route) => {

package/lib/mcp/server.js

@@ -59,9 +59,22 @@ const argvFor = (c, input) => {
     }
     return av;
 };
+// What a model is told once, when it connects: the order things are done in, so "set lynkeus up" and "write me
+// a test for this" need nothing more from the person asking.
+const INSTRUCTIONS = `lynkeus drives a React Native app (bare or Expo) by what is on its screen, and runs cases written as readable steps.
+
+In a project you do not know, call status first: it lists what is set up and, for what is not, the one thing that fixes it.
+
+To set lynkeus up: call init (it installs lynkeus-agent, mounts it from the app's entry and makes the project's token; nobody sets a variable). The agent has native code, so the app must then be built again (npx react-native run-ios or run-android; npx expo run:ios or run:android, never Expo Go) with Metro restarted with --reset-cache. Do that with your shell if you have one, or ask the person to. Then status until an app is attached.
+
+To write a test: call case_init once if the project has no cases, and read the README.md it writes for the format. Go to the screen with press, type and wait, calling screen to see what is there; prefer testIDs (#id) over text. Write the case as a markdown file in the cases folder, then call case_run with that file. A failed step comes back with the screen it failed on: fix the case or report the app's bug, do not weaken the check.
+
+To test without a simulator: call headless_init (it installs what the Node host needs and writes its entry; an Expo Router app works too), then headless_doctor for the native modules still to mock, then case_run with host. The backend the app talks to must be local: set apiUrl in lynkeus.config.json.
+
+To share a run: case_run with out, screenshots and push uploads it and prints the report's address. That needs LYNKEUS_REPORTS_KEY in this server's environment.`;
 export const serve = async (session, options = {}) => {
     const { version } = createRequire(import.meta.url)('../../package.json');
-    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     const served = commands().filter((c) => overMcp(c, !!options.full));
     const byName = new Map(served.map((c) => [identifier(c.name), c]));
     // So a model reading the app's screens knows their language before it starts guessing.
@@ -107,5 +120,21 @@ export const serve = async (session, options = {}) => {
             return { ...text(`✗ ${r.error}${r.why ? `\n\nwhy:\n${r.why}` : ''}`), isError: true };
         return text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
     });
-    await server.connect(new StdioServerTransport());
+    // The client going away ends the server: the session holds the driver's port open, and a server left behind
+    // keeps the next one (or a case run) from binding it.
+    const transport = new StdioServerTransport();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void session
+            .stop()
+            .catch(() => undefined)
+            .finally(() => process.exit(0));
+    };
+    process.stdin.once('end', stop);
+    process.stdin.once('close', stop);
+    transport.onclose = stop;
+    await server.connect(transport);
 };

package/lib/registry.d.ts

@@ -19,6 +19,11 @@ export type Base = {
     err: (line: string) => void;
     /** Inside `lynkeus session` and over MCP: one connection, many commands. */
     attached: boolean;
+    /** The same, but waiting for its app on another port: one per host when several run side by side. */
+    forPort?: (port: number) => {
+        base: Base;
+        stop: () => Promise<void>;
+    };
 };
 export type Ctx = Base & {
     args: string[];

package/lib/targets.d.ts

@@ -1,13 +1,22 @@
 import type { Target } from 'lynkeus-protocol';
 export declare const TARGET_HELP = "#testId | \"text\" | 12 (index) | 100,200";
-/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+/**
+ * `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match.
+ * A text in quotes is that text and nothing else: `"12"` is not an index, and `"Next"` is not a route.
+ */
 export declare const parseTarget: (raw: string) => Target;
 /** A target narrowed to the match nearest another (`--in`) and to a position among the matches (`--nth`). */
 export declare const scopedTarget: (raw: string, flags: {
     in?: unknown;
     nth?: unknown;
 }) => Target;
+/**
+ * A word that starts with a capital is a route (`Home.Main`), as React Navigation names them. A router
+ * that names routes after files (Expo Router's `index`, `(tabs)/settings`) says so: `route:index`.
+ */
 export declare const isRoute: (raw: string) => boolean;
+/** The route a target names, without the prefix that marked it as one. */
+export declare const routeOf: (raw: string) => string;
 export type Expected = {
     testId?: string;
     text?: string;

package/lib/targets.js

@@ -1,6 +1,12 @@
 export const TARGET_HELP = '#testId | "text" | 12 (index) | 100,200';
-/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+/**
+ * `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match.
+ * A text in quotes is that text and nothing else: `"12"` is not an index, and `"Next"` is not a route.
+ */
 export const parseTarget = (raw) => {
+    const quoted = /^(["'])((?:(?!\1).)*)\1$/s.exec(raw);
+    if (quoted)
+        return { text: quoted[2] };
     const nth = /^(.+)\[(\d+)\]$/.exec(raw);
     if (nth && !/^\d+$/.test(nth[1])) {
         const base = parseTarget(nth[1]);
@@ -31,13 +37,20 @@ export const scopedTarget = (raw, flags) => {
         ...(typeof flags.nth === 'number' ? { nth: flags.nth } : {}),
     };
 };
-export const isRoute = (raw) => /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+const ROUTE_PREFIX = 'route:';
+/**
+ * A word that starts with a capital is a route (`Home.Main`), as React Navigation names them. A router
+ * that names routes after files (Expo Router's `index`, `(tabs)/settings`) says so: `route:index`.
+ */
+export const isRoute = (raw) => raw.startsWith(ROUTE_PREFIX) || /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+/** The route a target names, without the prefix that marked it as one. */
+export const routeOf = (raw) => (raw.startsWith(ROUTE_PREFIX) ? raw.slice(ROUTE_PREFIX.length) : raw);
 /** What a command was looking for, as `why` reads it. */
 export const expectedOf = (raw) => {
     if (!raw)
         return undefined;
     if (isRoute(raw))
-        return { route: raw };
+        return { route: routeOf(raw) };
     const t = parseTarget(raw);
     return 'testId' in t ? { testId: t.testId } : 'text' in t ? { text: t.text } : undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
   "type": "module",
   "bin": "./lib/cli.js",
@@ -14,7 +14,8 @@
   },
   "files": [
     "lib",
-    "src"
+    "src",
+    "!**/__tests__"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -25,14 +26,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "url": "git+https://github.com/lynkeushq/lynkeus.git",
     "directory": "packages/cli"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lynkeus-client": "^0.2.0",
-    "lynkeus-protocol": "^0.2.0",
+    "lynkeus-client": "^0.4.0",
+    "lynkeus-protocol": "^0.4.0",
     "pngjs": "^7.0.0",
     "ts-morph": "^24.0.0",
     "yaml": "^2"
@@ -43,5 +47,5 @@
     "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
-  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+  "homepage": "https://github.com/lynkeushq/lynkeus#readme"
 }

package/src/cases/ahead.ts

@@ -0,0 +1,111 @@
+/**
+ * Setups made ahead of their cases. `case prepare` runs, in the order a suite
+ * will, the setup of every case that needs only the project's fixtures, and
+ * leaves what it produced here, one file a case; `case run` takes the file
+ * when its case starts and goes straight to the steps.
+ *
+ * A case that starts before its setup is ready marks itself started, runs its
+ * own setup, and the preparer skips it. Files are taken with a rename, so two
+ * processes never get the same one.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Case } from './format.js';
+import type { Prepared } from './runner.js';
+
+// What a backend held a quarter of an hour ago may have moved on (a session, a rate).
+const MAX_AGE_MS = 15 * 60_000;
+
+type Kept = { setup: string; at: number; prepared: Prepared };
+
+/** Where setups made ahead wait for their cases: files for a preparer in another process, memory in the same one. */
+export type Store = {
+  start(c: Case): void;
+  started(c: Case): boolean;
+  keep(c: Case, prepared: Prepared): void;
+  take(c: Case): Prepared | undefined;
+  waiting(): number;
+};
+
+export class InMemory implements Store {
+  readonly #started = new Set<string>();
+  readonly #kept = new Map<string, Prepared>();
+
+  start(c: Case): void {
+    this.#started.add(c.id);
+  }
+
+  started(c: Case): boolean {
+    return this.#started.has(c.id);
+  }
+
+  keep(c: Case, prepared: Prepared): void {
+    if (!this.started(c)) this.#kept.set(c.id, prepared);
+  }
+
+  take(c: Case): Prepared | undefined {
+    const prepared = this.#kept.get(c.id);
+    this.#kept.delete(c.id);
+    return prepared;
+  }
+
+  waiting(): number {
+    return this.#kept.size;
+  }
+}
+
+export class Ahead implements Store {
+  constructor(private readonly dir: string) {}
+
+  #file(c: Case, suffix = '.json') {
+    return path.join(this.dir, `${c.id.replace(/[^\w.-]+/g, '_')}${suffix}`);
+  }
+
+  clear(): void {
+    fs.rmSync(this.dir, { recursive: true, force: true });
+    fs.mkdirSync(this.dir, { recursive: true });
+  }
+
+  start(c: Case): void {
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.#file(c, '.started'), '');
+  }
+
+  started(c: Case): boolean {
+    return fs.existsSync(this.#file(c, '.started'));
+  }
+
+  keep(c: Case, prepared: Prepared): void {
+    // Its case started while this was being made, and ran a setup of its own.
+    if (this.started(c)) return;
+    const file = this.#file(c);
+    const kept: Kept = { setup: JSON.stringify(c.setup), at: Date.now(), prepared };
+    fs.writeFileSync(`${file}.tmp`, JSON.stringify(kept));
+    fs.renameSync(`${file}.tmp`, file);
+  }
+
+  /** Setups made and not yet taken by a case that is still to start. */
+  waiting(): number {
+    return fs.readdirSync(this.dir).filter((f) => f.endsWith('.json') && !fs.existsSync(path.join(this.dir, f.replace(/\.json$/, '.started')))).length;
+  }
+
+  /** The case's setup if it was made, is recent and is the setup the case has now. */
+  take(c: Case): Prepared | undefined {
+    const file = this.#file(c);
+    const mine = `${file}.${process.pid}`;
+    try {
+      fs.renameSync(file, mine);
+    } catch {
+      return undefined;
+    }
+    try {
+      const kept = JSON.parse(fs.readFileSync(mine, 'utf8')) as Kept;
+      return kept.setup === JSON.stringify(c.setup) && Date.now() - kept.at < MAX_AGE_MS ? kept.prepared : undefined;
+    } catch {
+      return undefined;
+    } finally {
+      fs.rmSync(mine, { force: true });
+    }
+  }
+}

package/src/cases/fixtures.ts

@@ -8,6 +8,22 @@
  * — and one line out, the step's answer: any JSON object, `"ok": false` and an
  * `error` when it failed. `params` is the step as written; `env` is the same
  * flattened to upper-case strings, for a server that hands them to a script.
+ *
+ * Before the first case lynkeus asks what the server can do —
+ *
+ *   {"command": "lynkeus.describe", "params": {}, "env": {}}
+ *
+ * — and a server that knows answers `{"commands": ["create_user", …]}`. With
+ * that, a case naming a fixture nobody answers is refused before anything
+ * runs. A server that answers `"ok": false`, as one written before this did,
+ * is taken to describe nothing, and its cases run unchecked. A server that is
+ * running but cannot serve (its database is down) adds `"down": "<why>"`, and
+ * no case starts: every one would fail at its first fixture.
+ *
+ * A connection that makes cases' setups ahead of time (`case prepare`) says so
+ * first, with `lynkeus.ahead`, so a server may give its work a lower priority
+ * than the cases running meanwhile. A server that does not know it is free to
+ * answer anything.
  */
 import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
 import path from 'node:path';
@@ -17,6 +33,14 @@ export type FixturesConfig = { command: string; cwd?: string; env?: Record<strin
 
 export type Answer = Record<string, unknown>;
 
+/** The one command that is lynkeus's own and not the project's. */
+export const DESCRIBE = 'lynkeus.describe';
+
+export type Description = { commands: string[]; down?: string };
+
+/** lynkeus's second own command: this connection works ahead of the cases. */
+export const AHEAD = 'lynkeus.ahead';
+
 const envOf = (params: Record<string, unknown>): Record<string, string> =>
   Object.fromEntries(
     Object.entries(params)
@@ -90,6 +114,19 @@ export class Fixtures {
     return answer;
   }
 
+  /** What the server says it answers, or nothing when it does not say. */
+  async describe(): Promise<Description | undefined> {
+    const answer = await this.call(DESCRIBE, {}).catch(() => undefined);
+    const commands = answer?.commands;
+    if (!Array.isArray(commands) || !commands.every((c) => typeof c === 'string')) return undefined;
+    return typeof answer?.down === 'string' && answer.down ? { commands, down: answer.down } : { commands };
+  }
+
+  /** Says this connection works ahead of the cases being run. Whatever the server answers, it goes on. */
+  async ahead(): Promise<void> {
+    await this.call(AHEAD, {}).catch(() => undefined);
+  }
+
   close(): void {
     const child = this.#child;
     this.#child = null;

package/src/cases/flakes.ts

@@ -0,0 +1,67 @@
+/**
+ * How each case has done across runs, kept in one JSON file: the last results,
+ * how often it needed its second chance, the step it last died on. A case that
+ * passes and fails without anything changing is the one to look at first.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { CaseReport } from './runner.js';
+
+const KEPT = 20;
+
+export type Outcome = { at: string; result: CaseReport['result']; retried: boolean; ms?: number; step?: string; error?: string };
+export type Ledger = Record<string, { runs: number; failed: number; retried: number; last: Outcome[] }>;
+
+export class Flakes {
+  private readonly ledger: Ledger;
+
+  constructor(private readonly file: string) {
+    let read: Ledger = {};
+    try {
+      read = JSON.parse(fs.readFileSync(file, 'utf8')) as Ledger;
+    } catch {
+      // No ledger yet, or one this cannot read: start a new one.
+    }
+    this.ledger = read;
+  }
+
+  note(report: CaseReport & { retried?: boolean }, at = new Date()): void {
+    const entry = this.ledger[report.id] ?? { runs: 0, failed: 0, retried: 0, last: [] };
+    this.ledger[report.id] = entry;
+    const broke = report.steps.find((s) => s.status === 'failed');
+    entry.runs += 1;
+    if (report.result === 'failed') entry.failed += 1;
+    if (report.retried) entry.retried += 1;
+    entry.last = [
+      ...entry.last,
+      {
+        at: at.toISOString(),
+        result: report.result,
+        retried: !!report.retried,
+        ms: report.ms,
+        ...(broke ? { step: broke.step, error: broke.error?.split('\n')[0] } : {}),
+      },
+    ].slice(-KEPT);
+  }
+
+  /** How long a case took when it last passed, if the ledger has seen it pass. */
+  lastMs(id: string): number | undefined {
+    return [...(this.ledger[id]?.last ?? [])].reverse().find((o) => o.result === 'passed' && o.ms !== undefined)?.ms;
+  }
+
+  /** The cases among `ids` whose recent runs disagree with each other, worded for a summary. */
+  flaky(ids: string[]): string[] {
+    return ids.flatMap((id) => {
+      const last = this.ledger[id]?.last ?? [];
+      const shaky = last.filter((o) => o.result === 'failed' || o.retried).length;
+      if (shaky === 0 || shaky === last.length) return [];
+      return [`⚠ ${id} is flaky: ${shaky} of its last ${last.length} runs failed or needed a second chance`];
+    });
+  }
+
+  save(): void {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    fs.writeFileSync(this.file, `${JSON.stringify(this.ledger, null, 2)}\n`);
+  }
+}

package/src/cases/format.ts

@@ -106,21 +106,46 @@ export const dig = (json: unknown, dotted: string): unknown => {
   return current;
 };
 
+export type Scope = Record<string, unknown>;
+
+/** Where a seeded case keeps how far its random values have gone; no alias can be named this. */
+const SEED = '~seed';
+
+/**
+ * With LYNKEUS_SEED set, a case's `{{random.*}}` values are the same on every run: two runs of it then show
+ * the same names, which comparing their screens needs. Each case draws its own, so cases side by side differ.
+ */
+export const seeded = (scope: Scope, id: string): void => {
+  const seed = process.env.LYNKEUS_SEED;
+  if (!seed || scope[SEED] !== undefined) return;
+  let hash = 2166136261;
+  for (const char of `${seed}\n${id}`) hash = Math.imul(hash ^ char.charCodeAt(0), 16777619);
+  scope[SEED] = hash >>> 0;
+};
+
 const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
-const random = (kind: string): string | undefined => {
-  if (kind === 'letters') return Array.from({ length: 6 }, () => LETTERS[Math.floor(Math.random() * 26)]).join('');
-  if (kind === 'digits') return Array.from({ length: 6 }, () => Math.floor(Math.random() * 10)).join('');
+const random = (kind: string, scope: Scope): string | undefined => {
+  const next = (): number => {
+    if (typeof scope[SEED] !== 'number') return Math.random();
+    // mulberry32
+    const state = (scope[SEED] + 0x6d2b79f5) >>> 0;
+    scope[SEED] = state;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  if (kind === 'letters') return Array.from({ length: 6 }, () => LETTERS[Math.floor(next() * 26)]).join('');
+  if (kind === 'digits') return Array.from({ length: 6 }, () => Math.floor(next() * 10)).join('');
   return undefined;
 };
 
-export type Scope = Record<string, unknown>;
-
 /** `{{alias.path}}` from what earlier steps answered, `{{random.letters}}`, `{{env.NAME}}`. */
 export const interpolate = <T>(value: T, scope: Scope): T => {
   if (typeof value === 'string') {
     const whole = /^\{\{\s*([\w-]+)\.([\w.*-]+)\s*\}\}$/.exec(value);
     const lookup = (name: string, path: string): unknown => {
-      if (name === 'random') return random(path);
+      if (name === 'random') return random(path, scope);
       if (name === 'env') return process.env[path];
       if (!(name in scope)) throw new Error(`no alias '${name}' (add \`as: ${name}\` to the step that creates it)`);
       return dig(scope[name], path);

package/src/cases/portClaim.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const alive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+};
+
+/**
+ * A run lets go of its driver port between cases, and the app dials whichever driver is listening: two runs
+ * on one port take turns at the app, and each reports steps the other drove. A run claims its ports for as
+ * long as it lasts; what it answers is the release, or why another run holds one.
+ */
+export const claimPorts = (ports: number[], dir = os.tmpdir()): { release: () => void } | { refused: string } => {
+  const held: string[] = [];
+  const release = () => {
+    for (const file of held) {
+      try {
+        if (fs.readFileSync(file, 'utf8').trim() === String(process.pid)) fs.unlinkSync(file);
+      } catch {
+        // Already gone.
+      }
+    }
+  };
+  for (const port of ports) {
+    const file = path.join(dir, `lynkeus-port-${port}.pid`);
+    for (;;) {
+      try {
+        fs.writeFileSync(file, String(process.pid), { flag: 'wx' });
+        held.push(file);
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      }
+      const owner = Number(fs.readFileSync(file, 'utf8').trim());
+      if (Number.isInteger(owner) && owner > 0 && owner !== process.pid && alive(owner)) {
+        release();
+        return {
+          refused: `port ${port} is held by another lynkeus case run (pid ${owner}), which is probably still going: stop it, or give this run other --ports`,
+        };
+      }
+      // Left by a run that ended without letting go.
+      fs.rmSync(file, { force: true });
+    }
+  }
+  return { release };
+};