Make e2e port claiming atomic: lock port per block, walk past collisions

The hash-derived block was only collision-unlikely (28 checkouts over 400
blocks is birthday-paradox territory), and probe-then-bind raced. Each block
now reserves its last port as a lock held for the suite's lifetime: claimPorts
binds the lock (atomic — two racing suites can't both win), probes the
remaining ports for squatters, and walks forward block-by-block until it owns
a fully free block, publishing the claimed ports via E2E_*_PORT env so test
workers agree. Explicit env pins skip claiming entirely. Verified by squatting
the preferred block's lock+selfhost ports and watching the suite relocate one
block over and pass 17/17.

Author: RhysSullivan

e2e/AGENTS.md

@@ -89,10 +89,13 @@ E2E_CLOUD_URL=http://127.0.0.1:<port> ../node_modules/.bin/vitest run --project
 E2E_SELFHOST_URL=http://localhost:<port> ../node_modules/.bin/vitest run --project selfhost <file>
 ```
 
-Ports are derived per checkout (hash of the repo root — see `src/ports.ts`),
-so suites in different worktrees never fight. If a port is somehow taken, the
-boot fails fast naming the squatting process; kill it or override with
-`E2E_CLOUD_PORT`-style env vars.
+Ports are claimed at boot (see `src/ports.ts`): each checkout hashes its repo
+root to a preferred block, atomically locks it (a held lock port makes races
+impossible), and walks to the next free block if it's locked or squatted — so
+concurrent suites in different worktrees can never collide or attach to each
+other's servers. `bun run ports` shows the preferred block; the boot log says
+if a suite moved. `E2E_*_PORT` env vars pin ports explicitly (no probing) and
+`E2E_<TARGET>_URL` attaches to a running instance.
 
 Each run writes `runs/<target>/<slug>/result.json` plus any browser artifacts
 (trace.zip / session.mp4 / screenshots). `bun run serve` hosts the scenario ×

e2e/scripts/ports.ts

@@ -1,5 +1,8 @@
-// Print this checkout's derived e2e ports (see src/ports.ts) so an agent or
-// human can curl the booted servers or attach with E2E_<TARGET>_URL.
+// Print this checkout's PREFERRED e2e ports (see src/ports.ts). These are
+// where a suite normally boots; if the block is locked or squatted at boot
+// time, claimPorts walks to the next free block and the suite logs the move.
+// When attaching mid-run, the booted vite's actual port is authoritative —
+// check the suite's log line or `ps | grep 'vite dev'`.
 import {
   AUTUMN_EMULATOR_PORT,
   CLOUD_DB_PORT,
@@ -9,7 +12,7 @@ import {
 import { SELFHOST_PORT } from "../targets/selfhost";
 import { repoRoot } from "../src/ports";
 
-console.log(`e2e ports for ${repoRoot}`);
+console.log(`preferred e2e ports for ${repoRoot}`);
 console.log(`  cloud           http://127.0.0.1:${CLOUD_PORT}`);
 console.log(`  cloud dev-db    ${CLOUD_DB_PORT}`);
 console.log(`  workos emulator ${WORKOS_EMULATOR_PORT}`);

e2e/setup/boot.ts

@@ -2,8 +2,7 @@
 // server, wait until it answers HTTP, and hand vitest a teardown. The apps own
 // what runs (their dev stack, their stub flags); this file only owns process
 // lifecycle, so it stays target-agnostic.
-import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import { connect } from "node:net";
+import { spawn, type ChildProcess } from "node:child_process";
 
 export interface BootedProcesses {
   readonly teardown: () => Promise<void>;
@@ -73,43 +72,6 @@ export const bootProcesses = (
   };
 };
 
-// A port already in LISTEN before we boot means waitForHttp would silently
-// attach to a FOREIGN server (a leaked dev server from another checkout or a
-// crashed prior run) — every scenario then fails with baffling auth errors
-// instead of one clear message. Fail fast and name the squatter.
-export const ensurePortsFree = async (
-  ports: ReadonlyArray<{ readonly port: number; readonly label: string }>,
-): Promise<void> => {
-  for (const { port, label } of ports) {
-    const inUse = await new Promise<boolean>((resolve) => {
-      const socket = connect({ port, host: "127.0.0.1" });
-      socket.once("connect", () => {
-        socket.destroy();
-        resolve(true);
-      });
-      socket.once("error", () => resolve(false));
-      socket.setTimeout(1_000, () => {
-        socket.destroy();
-        resolve(false);
-      });
-    });
-    if (!inUse) continue;
-    let owner = "(lsof unavailable)";
-    try {
-      owner = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
-        encoding: "utf8",
-      }).trim();
-    } catch {
-      // lsof failing is fine — the error below carries the essential fact.
-    }
-    throw new Error(
-      `e2e: port ${port} (${label}) is already in use — likely a leaked dev server ` +
-        `from another checkout or a previous run. Kill it or set the E2E_*_PORT/URL ` +
-        `env vars to relocate.\n${owner}`,
-    );
-  }
-};
-
 export const waitForHttp = async (
   url: string,
   options: { readonly timeoutMs?: number; readonly expectRedirect?: boolean } = {},

e2e/setup/cloud.globalsetup.ts

@@ -10,16 +10,9 @@ import { fileURLToPath } from "node:url";
 // Vendored fork import (same pattern as mcporter).
 import { createEmulator } from "@executor-js/emulate";
 
-import { bootProcesses, ensurePortsFree, waitForHttp } from "./boot";
-import {
-  CLOUD_BASE_URL,
-  CLOUD_DB_PORT,
-  CLOUD_PORT,
-  WORKOS_EMULATOR_PORT,
-  AUTUMN_EMULATOR_PORT,
-  E2E_WORKOS_CLIENT_ID,
-  E2E_COOKIE_PASSWORD,
-} from "../targets/cloud";
+import { claimPorts } from "../src/ports";
+import { E2E_COOKIE_PASSWORD, E2E_WORKOS_CLIENT_ID } from "../targets/cloud";
+import { bootProcesses, waitForHttp } from "./boot";
 
 const cloudDir = fileURLToPath(new URL("../../apps/cloud/", import.meta.url));
 
@@ -29,12 +22,19 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
     return;
   }
 
-  await ensurePortsFree([
-    { port: CLOUD_PORT, label: "cloud vite dev" },
-    { port: CLOUD_DB_PORT, label: "cloud dev-db (PGlite)" },
-    { port: WORKOS_EMULATOR_PORT, label: "WorkOS emulator" },
-    { port: AUTUMN_EMULATOR_PORT, label: "Autumn emulator" },
+  // Claim a free port block (preferred block first, walk forward past
+  // squatters/colliding checkouts) and publish via env so the test workers —
+  // spawned after this — derive the same URLs. The imported targets/cloud
+  // constants were computed BEFORE the claim, so use the claimed values here.
+  const { ports, release } = await claimPorts([
+    { envVar: "E2E_CLOUD_PORT", offset: 0, label: "cloud vite dev" },
+    { envVar: "E2E_CLOUD_DB_PORT", offset: 1, label: "cloud dev-db (PGlite)" },
+    { envVar: "E2E_WORKOS_EMULATOR_PORT", offset: 2, label: "WorkOS emulator" },
+    { envVar: "E2E_AUTUMN_EMULATOR_PORT", offset: 3, label: "Autumn emulator" },
   ]);
+  const cloudPort = ports.E2E_CLOUD_PORT!;
+  const dbPort = ports.E2E_CLOUD_DB_PORT!;
+  const baseUrl = `http://127.0.0.1:${cloudPort}`;
 
   // Fresh dev DB per suite run — hermetic, like the selfhost data dir. The
   // WorkOS emulator mints org ids from a per-process counter, so a persisted
@@ -46,8 +46,8 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
   // MCP access tokens minted by the emulator's OAuth server must carry the
   // app's client id as audience (what the resource server verifies).
   process.env.EMULATE_WORKOS_AUDIENCE = E2E_WORKOS_CLIENT_ID;
-  const workos = await createEmulator({ service: "workos", port: WORKOS_EMULATOR_PORT });
-  const autumn = await createEmulator({ service: "autumn", port: AUTUMN_EMULATOR_PORT });
+  const workos = await createEmulator({ service: "workos", port: ports.E2E_WORKOS_EMULATOR_PORT! });
+  const autumn = await createEmulator({ service: "autumn", port: ports.E2E_AUTUMN_EMULATOR_PORT! });
 
   const env = {
     // Real client, emulated service.
@@ -58,16 +58,16 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
     WORKOS_COOKIE_PASSWORD: E2E_COOKIE_PASSWORD,
     AUTUMN_SECRET_KEY: "am_test_emulate",
     ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
-    DATABASE_URL: `postgresql://postgres:postgres@127.0.0.1:${CLOUD_DB_PORT}/postgres`,
+    DATABASE_URL: `postgresql://postgres:postgres@127.0.0.1:${dbPort}/postgres`,
     EXECUTOR_DIRECT_DATABASE_URL: "true",
     CLOUDFLARE_INCLUDE_PROCESS_ENV: "true",
-    VITE_PUBLIC_SITE_URL: CLOUD_BASE_URL,
+    VITE_PUBLIC_SITE_URL: baseUrl,
     // The AuthKit domain (MCP OAuth metadata + JWKS) is the emulator too.
     MCP_AUTHKIT_DOMAIN: workos.url,
-    MCP_RESOURCE_ORIGIN: CLOUD_BASE_URL,
+    MCP_RESOURCE_ORIGIN: baseUrl,
     ALLOW_LOCAL_NETWORK: "true",
     // Throwaway PGlite on its own port + dir so it never fights `bun dev`.
-    DEV_DB_PORT: String(CLOUD_DB_PORT),
+    DEV_DB_PORT: String(dbPort),
     DEV_DB_PATH: dbPath,
   };
 
@@ -76,7 +76,7 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
       { cmd: "bun", args: ["run", "scripts/dev-db.ts"], cwd: cloudDir, env },
       {
         cmd: "bunx",
-        args: ["vite", "dev", "--port", String(CLOUD_PORT), "--strictPort", "--host", "127.0.0.1"],
+        args: ["vite", "dev", "--port", String(cloudPort), "--strictPort", "--host", "127.0.0.1"],
         cwd: cloudDir,
         env,
       },
@@ -85,18 +85,20 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
   );
 
   try {
-    await waitForHttp(CLOUD_BASE_URL);
+    await waitForHttp(baseUrl);
     // The API plane is ready when login actually redirects to AuthKit.
-    await waitForHttp(`${CLOUD_BASE_URL}/api/auth/login`, { expectRedirect: true });
+    await waitForHttp(`${baseUrl}/api/auth/login`, { expectRedirect: true });
   } catch (error) {
     await procs.teardown();
     await workos.close();
     await autumn.close();
+    await release();
     throw error;
   }
   return async () => {
     await procs.teardown();
     await workos.close();
     await autumn.close();
+    await release();
   };
 }

e2e/setup/selfhost.globalsetup.ts

@@ -6,8 +6,9 @@ import { rmSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { bootProcesses, ensurePortsFree, waitForHttp } from "./boot";
-import { SELFHOST_ADMIN, SELFHOST_BASE_URL, SELFHOST_PORT } from "../targets/selfhost";
+import { claimPorts } from "../src/ports";
+import { SELFHOST_ADMIN } from "../targets/selfhost";
+import { bootProcesses, waitForHttp } from "./boot";
 
 const selfhostDir = fileURLToPath(new URL("../../apps/host-selfhost/", import.meta.url));
 
@@ -17,7 +18,15 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
     return;
   }
 
-  await ensurePortsFree([{ port: SELFHOST_PORT, label: "selfhost vite dev" }]);
+  // Claim a free port (preferred block first, walk forward past squatters)
+  // and publish via env so the test workers derive the same URL. The imported
+  // targets/selfhost constants were computed BEFORE the claim — don't use them
+  // for ports/URLs here.
+  const { ports, release } = await claimPorts([
+    { envVar: "E2E_SELFHOST_PORT", offset: 4, label: "selfhost vite dev" },
+  ]);
+  const port = ports.E2E_SELFHOST_PORT!;
+  const baseUrl = `http://localhost:${port}`;
 
   // Fresh data dir per suite run — hermetic; in-suite isolation comes from
   // fresh identities, not resets.
@@ -28,14 +37,14 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
     [
       {
         cmd: "bunx",
-        args: ["--bun", "vite", "dev", "--port", String(SELFHOST_PORT), "--strictPort"],
+        args: ["--bun", "vite", "dev", "--port", String(port), "--strictPort"],
         cwd: selfhostDir,
         env: {
           EXECUTOR_DATA_DIR: dataDir,
           BETTER_AUTH_SECRET: "executor-selfhost-e2e-secret-0123456789",
           EXECUTOR_BOOTSTRAP_ADMIN_EMAIL: SELFHOST_ADMIN.email,
           EXECUTOR_BOOTSTRAP_ADMIN_PASSWORD: SELFHOST_ADMIN.password,
-          EXECUTOR_WEB_BASE_URL: SELFHOST_BASE_URL,
+          EXECUTOR_WEB_BASE_URL: baseUrl,
           // The harness boots loopback MCP/OAuth test servers and points the
           // instance at them; the hosted SSRF guard would otherwise block
           // outbound probes/dials to localhost. Hermetic test instance only.
@@ -47,10 +56,14 @@ export default async function setup(): Promise<(() => Promise<void>) | void> {
   );
 
   try {
-    await waitForHttp(SELFHOST_BASE_URL);
+    await waitForHttp(baseUrl);
   } catch (error) {
     await procs.teardown();
+    await release();
     throw error;
   }
-  return procs.teardown;
+  return async () => {
+    await procs.teardown();
+    await release();
+  };
 }