@cedarjs/pg 0.2.0-beta.0 → 0.3.0

package/dist/{lifecycle-BvIx0xqq.mjs → lifecycle-2BZgSVz2.mjs}

@@ -1,5 +1,5 @@
-import { a as leaseDir, f as resolveWorktreeIdentity, i as isOrphanLease, l as readLease, m as PASSWORD_SALT_PREFIX, n as envPath, r as forgetLease, s as listRegistryLeases, u as writeLease } from "./lease-DS1SX8U_.mjs";
-import { existsSync, mkdirSync, readdirSync, rmSync, statfsSync, writeFileSync } from "node:fs";
+import { a as leaseDir, d as resolveRoot, f as resolveWorktreeIdentity, i as isOrphanLease, l as readLease, m as PASSWORD_SALT_PREFIX, n as envPath, p as CLI_NAME, r as forgetLease, s as listRegistryLeases, u as writeLease } from "./lease-DS1SX8U_.mjs";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, statfsSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
@@ -30,21 +30,28 @@ function buildDatabaseName(identity, mode) {
 	if (name.length > PG_MAX) return name.slice(0, PG_MAX);
 	return name;
 }
+/**
+* Append `suffix` to a database name, staying ≤63 chars. When it does not fit,
+* cut the readable head (`cpg_<repo>_<worktree>`) and keep the trailing
+* `_<mode>_<pathHash8>` whole: that hash is what keeps worktrees apart.
+*/
+function appendKeepingHash(databaseName, suffix) {
+	const full = `${databaseName}${suffix}`;
+	if (full.length <= PG_MAX) return full;
+	const tail = /_[^_]+_[^_]+$/.exec(databaseName)?.[0] ?? "";
+	return `${databaseName.slice(0, Math.max(0, PG_MAX - tail.length - suffix.length)).replace(/_+$/, "")}${tail}${suffix}`.slice(0, PG_MAX);
+}
+/** Role for a database name: `<databaseName>_role`, cut by `appendKeepingHash`. */
 function buildRoleName(databaseName) {
-	const suffix = "_role";
-	const maxBase = PG_MAX - 5;
-	return `${databaseName.slice(0, maxBase)}${suffix}`;
+	return appendKeepingHash(databaseName, "_role");
 }
 /**
 * Build a worker clone datname from a TEMPLATE database name.
-* Layout: `<template>_c_<suffix>` truncated to ≤63 chars (keeps suffix).
+* Layout: `<template>_c_<suffix>`, cut by `appendKeepingHash` (keeps mode, hash, and suffix).
 */
 function buildCloneDatabaseName(templateName, suffix) {
 	const safe = suffix.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 24);
-	const tag = safe.length > 0 ? safe : "w";
-	const sep = "_c_";
-	const maxTemplate = PG_MAX - 3 - tag.length;
-	return `${templateName.slice(0, Math.max(1, maxTemplate))}${sep}${tag}`.slice(0, PG_MAX);
+	return appendKeepingHash(templateName, `_c_${safe.length > 0 ? safe : "w"}`);
 }
 //#endregion
 //#region src/core/policy.ts
@@ -144,6 +151,8 @@ function resolveAcquireSkip(input = {}) {
 }
 //#endregion
 //#region src/providers/autopg.ts
+/** autopg release cedar-pg is tested against (`scripts/autopg-version`, inlined at build). */
+const AUTOPG_PINNED_VERSION = "v3.2.2";
 const INSTALL_HINT = "autopg is required. Install with:\n  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/main/install.sh | bash\nThen ensure ~/.local/bin is on PATH, or set AUTOPG_BIN.";
 /** Password scheme v2: sha256(PASSWORD_SALT_PREFIX + "\\0" + roleName) hex[:32]. Frozen for URL rebuild. */
 const ROLE_PASSWORD_SCHEME = "v2";
@@ -170,14 +179,19 @@ function requireAutopgBin() {
 	if (!bin) throw new Error(INSTALL_HINT);
 	return bin;
 }
+function optionalNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
 /**
-* Parse `autopg status --json` → the **registered** port. Throws only when the
-* output is not autopg status JSON.
+* Parse `autopg status --json` → the **registered** port (and data/socket/logs
+* dirs when present). Throws only when the output is not autopg status JSON.
 *
 * Registration is not liveness: autopg reports a port for a stopped host too,
-* and its `status` string is supervisor-specific (pm2 `online`, systemd-user /
-* launchd differ). Liveness is a TCP accept on the port, proven by the caller —
-* `acquire` does that before it connects.
+* and its `status` / `ready` describe the supervisor (autopg ≥ v3.2: `ready` needs
+* pm2 `online`; pm2's raw state is `supervisorStatus`). Neither, nor `runtime.live`,
+* is the attach gate — a bare postmaster (e.g. one cedar-pg revived) is
+* query-ready while status stays `stopped` / `ready: false`.
+* Liveness is a TCP accept on the port, proven by the caller (`acquire`).
 */
 function parseHostStatus(json) {
 	let parsed;
@@ -187,7 +201,16 @@ function parseHostStatus(json) {
 		throw new Error(`autopg status --json returned invalid JSON.\n${INSTALL_HINT}`);
 	}
 	if (typeof parsed.port !== "number") throw new Error(`autopg status --json missing numeric port.\n${INSTALL_HINT}`);
-	return { port: parsed.port };
+	const result = { port: parsed.port };
+	for (const key of [
+		"dataDir",
+		"socketDir",
+		"logsDir"
+	]) {
+		const value = optionalNonEmptyString(parsed[key]);
+		if (value) result[key] = value;
+	}
+	return result;
 }
 /**
 * Admin URL for an autopg host on `port`.
@@ -202,15 +225,44 @@ function parseHostStatus(json) {
 function adminUrlFor(port, env = process.env) {
 	return `postgresql://${encodeURIComponent(env.AUTOPG_PG_USER || env.PGSERVE_PG_USER || "postgres")}:${encodeURIComponent(env.AUTOPG_PG_PASSWORD || env.PGSERVE_PG_PASSWORD || "postgres")}@127.0.0.1:${port}/postgres`;
 }
+/** `[major, minor, patch]` from `autopg --version` output or a `vX.Y.Z` tag; `null` if absent. */
+function parseAutopgVersion(text) {
+	const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+	return m ? [
+		Number(m[1]),
+		Number(m[2]),
+		Number(m[3])
+	] : null;
+}
 /**
-* Discover the registered autopg host (port + admin URL) via `autopg status --json`.
-* Throws when autopg cannot be queried; does **not** prove a listener — probe TCP
-* (or use `acquire`, which does) before connecting.
+* Upgrade warning when `autopg --version` output is older than `pin`. `null` when
+* current, newer, or unreadable — never nag on what cannot be parsed. Upgrading
+* is the user's call: it restarts the host every worktree shares.
 */
-function discoverHost(bin = requireAutopgBin()) {
-	let status;
+function outdatedAutopgWarning(versionOutput, pin = AUTOPG_PINNED_VERSION) {
+	const have = parseAutopgVersion(versionOutput);
+	const want = parseAutopgVersion(pin);
+	if (!have || !want) return null;
+	if ((have[0] - want[0] || have[1] - want[1] || have[2] - want[2]) >= 0) return null;
+	return `[cedar-pg] warning: autopg ${have.join(".")} is older than ${pin}, the version @cedarjs/pg is tested with.\nUpgrade (restarts the shared host; open connections from other worktrees drop):
+  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/${pin}/install.sh | AUTOPG_VERSION=${pin} bash\n  autopg update
+`;
+}
+/** `autopg --version` stdout; `""` when it cannot run (treated as unknown). */
+function readAutopgVersion(bin) {
+	return spawnSync(bin, ["--version"], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		],
+		timeout: 5e3
+	}).stdout ?? "";
+}
+function readStatusJson(bin) {
 	try {
-		status = execFileSync(bin, ["status", "--json"], {
+		return execFileSync(bin, ["status", "--json"], {
 			encoding: "utf8",
 			stdio: [
 				"ignore",
@@ -222,22 +274,70 @@ function discoverHost(bin = requireAutopgBin()) {
 		const detail = err instanceof Error ? err.message : String(err);
 		throw new Error(`Failed to query autopg status.\n${detail}\n${INSTALL_HINT}`);
 	}
-	const { port } = parseHostStatus(status);
+}
+/**
+* Discover the registered autopg host (attach target + reported data/socket/logs
+* dirs) via `autopg status --json`. Throws when autopg cannot be queried; does
+* **not** prove a listener — probe TCP (or use `acquire`, which does) before connecting.
+*/
+function discoverRegistration(bin = requireAutopgBin()) {
+	const { port, ...paths } = parseHostStatus(readStatusJson(bin));
 	return {
-		port,
-		adminUrl: adminUrlFor(port),
-		bin
+		host: {
+			port,
+			adminUrl: adminUrlFor(port),
+			bin
+		},
+		...paths
 	};
 }
+/**
+* Discover the registered autopg host (port + admin URL) via `autopg status --json`.
+* Throws when autopg cannot be queried; does **not** prove a listener — probe TCP
+* (or use `acquire`, which does) before connecting.
+*/
+function discoverHost(bin = requireAutopgBin()) {
+	return discoverRegistration(bin).host;
+}
 function quoteIdent(name) {
 	return `"${name.replace(/"/g, "\"\"")}"`;
 }
 function quoteLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
+/** Grace for a postmaster that accepts TCP but still answers 57P03 (startup / recovery). */
+const ADMIN_CONNECT_READY_MS = 3e4;
+const ADMIN_CONNECT_POLL_MS = 200;
+/**
+* Retry `connect` while Postgres answers `57P03` (cannot_connect_now: "the
+* database system is starting up" / in recovery). TCP accept — the host
+* liveness gate — comes before query-ready, so a freshly revived or crash-
+* recovering postmaster needs this. Any other error is thrown immediately.
+*/
+async function connectWhileStartingUp(connect, opts = {}) {
+	const now = opts.now ?? Date.now;
+	const pause = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const deadline = now() + (opts.readyMs ?? ADMIN_CONNECT_READY_MS);
+	for (;;) {
+		try {
+			return await connect();
+		} catch (err) {
+			if (err.code !== "57P03" || now() >= deadline) throw err;
+		}
+		await pause(opts.pollMs ?? ADMIN_CONNECT_POLL_MS);
+	}
+}
 async function withAdminClient(adminUrl, fn) {
-	const client = new pg.Client({ connectionString: adminUrl });
-	await client.connect();
+	const client = await connectWhileStartingUp(async () => {
+		const attempt = new pg.Client({ connectionString: adminUrl });
+		try {
+			await attempt.connect();
+			return attempt;
+		} catch (err) {
+			await attempt.end().catch(() => {});
+			throw err;
+		}
+	});
 	try {
 		return await fn(client);
 	} finally {
@@ -276,18 +376,59 @@ async function setDatabaseIsTemplate(opts) {
 		await client.query(`ALTER DATABASE ${quoteIdent(opts.databaseName)} WITH IS_TEMPLATE ${flag}`);
 	});
 }
+/** Postgres `duplicate_database`: CREATE DATABASE hit an existing datname. */
+const DUPLICATE_DATABASE = "42P04";
 /**
 * CREATE DATABASE … TEMPLATE … OWNER via admin connection.
 * Test roles are LOGIN-only; workers cannot CREATE DATABASE themselves.
+*
+* With `reuse`, an existing `databaseName` owned by `roleName` is kept as-is:
+* a worker clone made earlier in this run by another test file.
+* An existing datname owned by any other role always fails: it is not ours.
 */
 async function cloneDatabaseFromTemplate(opts) {
 	await withAdminClient(opts.adminUrl, async (client) => {
 		const tmpl = await client.query(`SELECT datistemplate FROM pg_database WHERE datname = $1`, [opts.templateName]);
 		if (!tmpl.rowCount) throw new Error(`template database not found: ${opts.templateName}`);
 		if (!tmpl.rows[0]?.datistemplate) throw new Error(`database is not a TEMPLATE; run markTemplate first: ${opts.templateName}`);
-		const exists = await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [opts.databaseName]);
-		if (exists.rowCount && exists.rowCount > 0) throw new Error(`database already exists: ${opts.databaseName}`);
-		await client.query(`CREATE DATABASE ${quoteIdent(opts.databaseName)} WITH TEMPLATE ${quoteIdent(opts.templateName)} OWNER ${quoteIdent(opts.roleName)}`);
+		try {
+			await client.query(`CREATE DATABASE ${quoteIdent(opts.databaseName)} WITH TEMPLATE ${quoteIdent(opts.templateName)} OWNER ${quoteIdent(opts.roleName)}`);
+			return;
+		} catch (err) {
+			if (err.code !== DUPLICATE_DATABASE) throw err;
+		}
+		const owner = (await client.query(`SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1`, [opts.databaseName])).rows[0]?.owner;
+		if (opts.reuse && owner === opts.roleName) return;
+		throw new Error(`database already exists: ${opts.databaseName} (owned by ${owner ?? "unknown"})`);
+	});
+}
+/**
+* Empty every user table in `databaseName` with one
+* `TRUNCATE … RESTART IDENTITY`, so serial / identity columns start at 1 again.
+*
+* Runs as admin against that database. Skips system schemas, temp tables, and
+* tables an extension owns (e.g. PostGIS `spatial_ref_sys`); partitions are covered by
+* their parent. No `CASCADE`: every user table is in the one statement, so no
+* FK target is missing from it.
+*/
+async function truncateUserTables(opts) {
+	const url = new URL(opts.adminUrl);
+	url.pathname = `/${opts.databaseName}`;
+	return withAdminClient(url.toString(), async (client) => {
+		const tables = (await client.query(`SELECT format('%I.%I', n.nspname, c.relname) AS name
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE c.relkind IN ('r', 'p')
+         AND NOT c.relispartition
+         AND c.relpersistence <> 't'
+         AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+         AND NOT EXISTS (
+           SELECT 1 FROM pg_depend d
+           WHERE d.classid = 'pg_class'::regclass AND d.objid = c.oid AND d.deptype = 'e'
+         )
+       ORDER BY 1`)).rows.map((r) => r.name);
+		if (tables.length > 0) await client.query(`TRUNCATE TABLE ${tables.join(", ")} RESTART IDENTITY`);
+		return tables;
 	});
 }
 async function listOwnedDatnames(client, roleName) {
@@ -344,37 +485,20 @@ function buildDatabaseUrl(opts) {
 const EPHEMERAL_PORT = 55432;
 const HOST_READY_MS = 3e4;
 const HOST_POLL_MS = 200;
-/**
-* autopg verbs that can bring the *registered* local host up, cheapest fix first.
-*
-* `restart` exit 0 is not evidence of a listener: when pm2 is missing or does not
-* list `autopg-server`, autopg still prints "respawned daemon" and returns 0.
-* That is why every verb is followed by a TCP wait, not trusted on exit status.
-*
-* `install` covers a never-registered machine (postinstall ships the binary only)
-* and a reboot whose pm2 list is empty (`pm2 start`). On an already-registered
-* host it is a no-op for the server process but may `pm2 start` the autopg UI —
-* so it runs only after `restart` failed to produce a listener.
-*/
-const LOCAL_START = [{
-	argv: ["restart"],
-	readyMs: 1e4
-}, {
-	argv: ["install"],
-	readyMs: HOST_READY_MS
-}];
+/** `autopg restart` exits 0 only once ready; grace covers older autopg that returned early. */
+const LOCAL_RESTART_READY_MS = 1e4;
 /** Soft minimum free bytes on /dev/shm before RAM-backed ephemeral start (warns only). */
 const EPHEMERAL_SHM_MIN_FREE_BYTES = 512 * 1024 * 1024;
 /**
 * Hint when ephemeral `--ram` initdb fails for space / leftover dirs under `/dev/shm`.
 * Cloud VMs often ship with a tiny default tmpfs (e.g. 64MB).
 */
-const EPHEMERAL_SHM_HINT = "Ephemeral autopg uses /dev/shm with --ram. If initdb fails with Disk quota / No space (Postgres 53100):\n  1. Enlarge tmpfs (cloud VMs often default to ~64MB): sudo mount -o remount,size=6G /dev/shm\n  2. Clear leftovers from OOM-killed runs (your test data only):\n     rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*";
+const EPHEMERAL_SHM_HINT = "Ephemeral autopg uses /dev/shm with --ram. If initdb fails with Disk quota / No space (Postgres 53100):\n  1. Enlarge tmpfs (cloud VMs often default to ~64MB): sudo mount -o remount,size=6G /dev/shm\n  2. cedar-pg already removes its own leftover dir (/dev/shm/cedar-pg-<uid>) on cold start.\n     Never rm /dev/shm/PostgreSQL.*: those segments belong to every running Postgres,\n     and deleting a live one breaks new connections to that host (58P01).";
 /**
 * Resolve how to start a host when none is listening.
 *
 * - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral owned postmaster
-* - `CEDAR_PG_EPHEMERAL_HOST=0` → never own a postmaster, local autopg only (even in CI)
+* - `CEDAR_PG_EPHEMERAL_HOST=0` → never own an ephemeral postmaster, local registered host only (even in CI)
 * - unset + `CI=true` → ephemeral
 * - otherwise → local
 */
@@ -424,38 +548,6 @@ function looksLikeShmSpaceError(text) {
 function formatHostStartError(detail, useRamShm = false) {
 	return `Failed to start autopg host.\n${detail}\n${INSTALL_HINT}${useRamShm && looksLikeShmSpaceError(detail) ? `\n${EPHEMERAL_SHM_HINT}` : ""}`;
 }
-/**
-* Remove leftover ephemeral data dirs under `/dev/shm` (and the recipe dataDir).
-* Safe for OOM-killed CI/cloud runs that leave `cedar-pg-*` / `pgserve-*` /
-* `PostgreSQL.*` filling tmpfs.
-*
-* Only called on ephemeral cold start, i.e. when the recipe port has no listener —
-* never while a host owns those dirs.
-*/
-function pruneStaleEphemeralDataDirs(opts) {
-	const removed = [];
-	const tryRm = (path) => {
-		if (!existsSync(path)) return;
-		try {
-			rmSync(path, {
-				recursive: true,
-				force: true
-			});
-			removed.push(path);
-		} catch {}
-	};
-	tryRm(opts.dataDir);
-	const shmRoot = opts.shmRoot ?? (existsSync("/dev/shm") ? "/dev/shm" : void 0);
-	if (!shmRoot) return removed;
-	let entries = [];
-	try {
-		entries = readdirSync(shmRoot);
-	} catch {
-		return removed;
-	}
-	for (const name of entries) if (name.startsWith("cedar-pg-") || name.startsWith("pgserve-") || name.startsWith("PostgreSQL.")) tryRm(join(shmRoot, name));
-	return removed;
-}
 /** Free bytes on `path`, or `null` if unavailable. */
 function freeBytesOn(path) {
 	try {
@@ -477,7 +569,8 @@ function runAutopg(bin, argv) {
 	});
 	if (result.error) return result.error.message;
 	if (result.status === 0) return null;
-	return `exit ${result.status}\n${(result.stderr || result.stdout || "").trim()}`.trim();
+	const output = `${result.stderr ?? ""}${result.stdout ?? ""}`;
+	return `exit ${result.status}\n${output.trim()}`.trim();
 }
 /** True when something accepts TCP on 127.0.0.1:port (postmaster live, not just admin.json). */
 function canConnect(port) {
@@ -545,25 +638,182 @@ async function attachLiveHost(bin, readyMs = 0) {
 		readyMs
 	}) ? discovered : null;
 }
+/** Appended by the revived registered postmaster (next to autopg's own pm2 logs). */
+const REVIVED_POSTMASTER_LOG = "cedarpg-postmaster.log";
+function errorDetail(err) {
+	return err instanceof Error ? err.message : String(err);
+}
 /**
-* Bring the user's registered autopg host up and attach to it — same port, same
-* `~/.autopg/data`, still there after this process exits. cedar-pg never runs a
-* second local Postgres.
+* Live PID from `<dataDir>/postmaster.pid`, else `null`. Postgres writes it before
+* binding, so a live owner means another postmaster (pm2 still recovering, or a
+* concurrent acquire) already holds the data dir — wait for it, never compete.
 */
-async function startLocalHost(bin, registeredPort) {
-	const failures = [];
-	for (const { argv, readyMs } of LOCAL_START) {
-		const label = `autopg ${argv.join(" ")}`;
-		const failure = runAutopg(bin, [...argv]);
-		if (failure) {
-			failures.push(`${label}: ${failure}`);
-			continue;
+function liveDataDirOwner(dataDir) {
+	return livePidIn(join(dataDir, "postmaster.pid"));
+}
+/** Live PID from the first line of `file`, else `null` (missing, garbage, or dead). */
+function livePidIn(file) {
+	let pid;
+	try {
+		pid = Number.parseInt(readFileSync(file, "utf8"), 10);
+	} catch {
+		return null;
+	}
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		process.kill(pid, 0);
+		return pid;
+	} catch (err) {
+		return err.code === "EPERM" ? pid : null;
+	}
+}
+/**
+* Exclusive cold-start lock `<dataDir>.lock` holding our PID. Returns `null` once
+* we hold it, else the live holder's PID. `postmaster.pid` alone cannot guard an
+* ephemeral cold start: it does not exist yet while a peer runs initdb, which is
+* exactly when a second `rm -rf` would destroy the peer's cluster.
+*
+* The PID is written to a private file and hard-linked into place, so the lock
+* never exists without its PID. A dead holder's lock is stale and taken over.
+*/
+function tryColdStartLock(lockPath) {
+	const mine = `${lockPath}.${process.pid}`;
+	writeFileSync(mine, String(process.pid));
+	try {
+		for (;;) {
+			try {
+				linkSync(mine, lockPath);
+				return null;
+			} catch (err) {
+				if (err.code !== "EEXIST") throw err;
+			}
+			const holder = livePidIn(lockPath);
+			if (holder != null) return holder;
+			rmSync(lockPath, { force: true });
 		}
-		const attached = await attachLiveHost(bin, readyMs);
+	} finally {
+		rmSync(mine, { force: true });
+	}
+}
+/**
+* Detached `autopg postmaster`. Success: child is unref'd (survives this process).
+* Failure: child is killed, throws a one-line detail (caller wraps / aggregates).
+* `logFile` (appended) keeps output from a postmaster nothing else supervises;
+* otherwise stdio is fully ignored (caller exit must not close pipes under it).
+*/
+async function spawnDetachedPostmaster(opts) {
+	const { readyMs } = opts;
+	const logFd = opts.logFile ? openSync(opts.logFile, "a") : null;
+	let child;
+	try {
+		child = spawn(opts.bin, opts.args, {
+			detached: true,
+			stdio: logFd == null ? "ignore" : [
+				"ignore",
+				logFd,
+				logFd
+			]
+		});
+	} finally {
+		if (logFd != null) closeSync(logFd);
+	}
+	let died = null;
+	child.on("error", (err) => {
+		died = /* @__PURE__ */ new Error(`Failed to spawn autopg postmaster.\n${err.message}`);
+	});
+	child.on("exit", (code, signal) => {
+		died ??= /* @__PURE__ */ new Error(`autopg postmaster exited before ready (code=${code}, signal=${signal}).`);
+	});
+	try {
+		if (!await waitForListener({
+			port: opts.port,
+			readyMs,
+			failure: () => died
+		})) throw new Error(`autopg postmaster did not accept 127.0.0.1:${opts.port} within ${readyMs}ms.`);
+	} catch (err) {
+		killOwnedChild(child);
+		throw err;
+	}
+	child.unref();
+}
+/**
+* Detached `autopg postmaster` on the registered port / data dir (socket dir when
+* autopg reports one; otherwise the postmaster resolves autopg's own default).
+* Returns failure detail, or `null` once TCP accepts.
+*
+* No reported `dataDir` → not attempted: a postmaster without `--data` is not
+* persistent, and guessing autopg's path is how a second Postgres happens.
+*/
+async function reviveRegisteredPostmaster(bin, reg) {
+	const { dataDir, socketDir, logsDir } = reg;
+	const { port } = reg.host;
+	if (!dataDir) return "autopg postmaster: not attempted (autopg status --json reports no dataDir)";
+	const args = [
+		"postmaster",
+		"--port",
+		String(port),
+		"--data",
+		dataDir,
+		...socketDir ? ["--socket-dir", socketDir] : []
+	];
+	const label = `autopg ${args.join(" ")}`;
+	const logFile = logsDir ? join(logsDir, REVIVED_POSTMASTER_LOG) : void 0;
+	if (liveDataDirOwner(dataDir) == null) try {
+		mkdirSync(dataDir, {
+			recursive: true,
+			mode: 448
+		});
+		if (logsDir) mkdirSync(logsDir, { recursive: true });
+		await spawnDetachedPostmaster({
+			bin,
+			args,
+			port,
+			readyMs: HOST_READY_MS,
+			...logFile ? { logFile } : {}
+		});
+		return null;
+	} catch (err) {
+		if (liveDataDirOwner(dataDir) == null) return `${label}: ${errorDetail(err)}${logFile ? `\nPostmaster log: ${logFile}` : ""}`;
+	}
+	if (await waitForListener({
+		port,
+		readyMs: HOST_READY_MS
+	})) return null;
+	return `${label}: postmaster pid ${liveDataDirOwner(dataDir) ?? "?"} owns ${dataDir} but did not accept 127.0.0.1:${port} within ${HOST_READY_MS}ms`;
+}
+/**
+* Revive the user's registered autopg host — same port, same `~/.autopg/data`,
+* still running after this process exits. Never a second local Postgres.
+*
+* `restart` drives pm2 only and exits 0 once ready; without pm2 (or under another
+* supervisor) it exits 1. Either way TCP is the gate: if still dark,
+* {@link reviveRegisteredPostmaster} on the registered port/data. Do not
+* `install` on an already-registered host (wants pm2, refuses a port change).
+* `install` is only for a never-registered machine.
+*/
+async function startLocalHost(bin, registered) {
+	const failures = [];
+	const restartFailure = runAutopg(bin, ["restart"]);
+	if (restartFailure) failures.push(`autopg restart: ${restartFailure}`);
+	else {
+		const attached = await attachLiveHost(bin, LOCAL_RESTART_READY_MS);
 		if (attached) return attached;
-		failures.push(`${label}: no listener within ${readyMs}ms`);
+		failures.push(`autopg restart: no listener within ${LOCAL_RESTART_READY_MS}ms`);
+	}
+	if (registered) {
+		const failure = await reviveRegisteredPostmaster(bin, registered);
+		if (!failure) return registered.host;
+		failures.push(failure);
+	} else {
+		const installFailure = runAutopg(bin, ["install"]);
+		if (installFailure) failures.push(`autopg install: ${installFailure}`);
+		else {
+			const attached = await attachLiveHost(bin, HOST_READY_MS);
+			if (attached) return attached;
+			failures.push(`autopg install: no listener within ${HOST_READY_MS}ms`);
+		}
 	}
-	const where = registeredPort != null ? `autopg host is registered on 127.0.0.1:${registeredPort} but nothing is listening.\n` : "";
+	const where = registered != null ? `autopg host is registered on 127.0.0.1:${registered.host.port} but nothing is listening.\n` : "";
 	throw new Error(formatHostStartError(`${where}${failures.join("\n")}`));
 }
 /**
@@ -572,53 +822,71 @@ async function startLocalHost(bin, registeredPort) {
 *
 * Never runs `autopg install` — that rewrites `~/.autopg/admin.json` and fails
 * with `supervisor mismatch` next to a local pm2 install. Reuses a listener
-* already on the recipe port, and prunes stale RAM dirs before a cold start.
+* already on the recipe port. Concurrent cold starts (Nx running several
+* `db:ready` on one runner) serialize on {@link tryColdStartLock}: only the
+* holder prunes and starts; everyone else waits for the listener.
 */
-async function startEphemeralHost(bin) {
-	const recipe = ephemeralHostRecipe();
-	if (await canConnect(recipe.port)) return discoveryFromRecipe(bin, recipe);
+async function startEphemeralHost(bin, recipe = ephemeralHostRecipe()) {
+	const { dataDir, port } = recipe;
+	if (await canConnect(port)) return discoveryFromRecipe(bin, recipe);
 	const useRamShm = recipe.postmasterArgs.includes("--ram");
-	pruneStaleEphemeralDataDirs({ dataDir: recipe.dataDir });
+	const lockPath = `${dataDir}.lock`;
+	const holder = tryColdStartLock(lockPath);
+	if (holder == null) try {
+		if (!await canConnect(port) && liveDataDirOwner(dataDir) == null) await coldStartEphemeral(bin, recipe, useRamShm);
+	} finally {
+		rmSync(lockPath, { force: true });
+	}
+	if (await waitForListener({
+		port,
+		readyMs: HOST_READY_MS
+	})) return discoveryFromRecipe(bin, recipe);
+	const owner = holder != null ? `cold start pid ${holder}` : `postmaster pid ${liveDataDirOwner(dataDir) ?? "?"}`;
+	throw new Error(formatHostStartError(`${owner} owns ${dataDir} but did not accept 127.0.0.1:${port} within ${HOST_READY_MS}ms`, useRamShm));
+}
+/** Prune our dead leftover data dir and start the postmaster. Caller holds the cold-start lock. */
+async function coldStartEphemeral(bin, recipe, useRamShm) {
+	rmSync(recipe.dataDir, {
+		recursive: true,
+		force: true
+	});
 	if (useRamShm) {
 		const free = freeBytesOn("/dev/shm");
 		if (free != null && free < 536870912) process.stderr.write(`[cedar-pg] warning: /dev/shm has ~${Math.round(free / (1024 * 1024))}MB free (recommend ≥${Math.round(EPHEMERAL_SHM_MIN_FREE_BYTES / (1024 * 1024))}MB for --ram).\n${EPHEMERAL_SHM_HINT}\n`);
 	}
 	mkdirSync(recipe.dataDir, { recursive: true });
-	const child = spawn(bin, recipe.postmasterArgs, {
-		detached: true,
-		stdio: "ignore"
-	});
-	let died = null;
-	child.on("error", (err) => {
-		died = new Error(formatHostStartError(`Failed to spawn autopg postmaster.\n${err.message}`, useRamShm));
-	});
-	child.on("exit", (code, signal) => {
-		died ??= new Error(formatHostStartError(`autopg postmaster exited before ready (code=${code}, signal=${signal}).`, useRamShm));
-	});
 	try {
-		if (!await waitForListener({
+		await spawnDetachedPostmaster({
+			bin,
+			args: recipe.postmasterArgs,
 			port: recipe.port,
-			readyMs: HOST_READY_MS,
-			failure: () => died
-		})) throw new Error(formatHostStartError(`autopg postmaster did not accept 127.0.0.1:${recipe.port} within ${HOST_READY_MS}ms.`, useRamShm));
+			readyMs: HOST_READY_MS
+		});
 	} catch (err) {
-		killOwnedChild(child);
-		throw err;
+		if (liveDataDirOwner(recipe.dataDir) != null) return;
+		throw new Error(formatHostStartError(errorDetail(err), useRamShm));
 	}
-	child.unref();
-	return discoveryFromRecipe(bin, recipe);
+}
+let autopgVersionChecked = false;
+/** Once per process: warn (never fail, never upgrade) when autopg is older than the pin. */
+function warnIfAutopgOutdated(bin) {
+	if (autopgVersionChecked) return;
+	autopgVersionChecked = true;
+	const warning = outdatedAutopgWarning(readAutopgVersion(bin));
+	if (warning) process.stderr.write(warning);
 }
 /**
 * Attach to a listening autopg host, else start one per
 * {@link resolveHostStartPolicy}. Internal: callers use `acquire` / `adminUrl`.
 */
 async function ensureHostRunning(bin = requireAutopgBin()) {
+	warnIfAutopgOutdated(bin);
 	let registered = null;
 	try {
-		registered = discoverHost(bin);
+		registered = discoverRegistration(bin);
 	} catch {}
-	if (registered && await waitForListener({ port: registered.port })) return registered;
-	return resolveHostStartPolicy() === "ephemeral" ? startEphemeralHost(bin) : startLocalHost(bin, registered?.port);
+	if (registered && await waitForListener({ port: registered.host.port })) return registered.host;
+	return resolveHostStartPolicy() === "ephemeral" ? startEphemeralHost(bin) : startLocalHost(bin, registered);
 }
 //#endregion
 //#region src/core/lifecycle.ts
@@ -661,8 +929,14 @@ async function acquire(options) {
 	const identity = resolveWorktreeIdentity(options.root);
 	const mode = options.mode;
 	const databaseName = buildDatabaseName(identity, mode);
-	const roleName = buildRoleName(databaseName);
+	const leased = readLease(identity.root, mode);
+	const roleName = leased?.databaseName === databaseName ? leased.roleName : buildRoleName(databaseName);
 	const host = await ensureHostRunning();
+	if (options.fresh) await dropDatabasesOwnedByRole({
+		adminUrl: host.adminUrl,
+		roleName,
+		preferLast: databaseName
+	});
 	await ensureDatabase({
 		adminUrl: host.adminUrl,
 		databaseName,
@@ -709,6 +983,23 @@ async function acquire(options) {
 	};
 }
 /**
+* Attach-only: connection info from the lease a prior `acquire` wrote. Never
+* acquires, never runs role/database DDL, never starts or revives the host —
+* safe for many concurrent children after one `db:ready`. Throws when there is
+* no lease or nothing accepts TCP on the leased port.
+*/
+async function attach(options) {
+	const root = resolveRoot(options.root);
+	const { mode } = options;
+	const lease = readLease(root, mode);
+	if (!lease) throw new Error(`no ${mode} lease in ${root}; run \`${CLI_NAME} acquire --mode=${mode}\` (or your db:ready target) first — attach never acquires`);
+	if (!await waitForListener({ port: lease.port })) throw new Error(`${mode} lease ${lease.databaseName} points at 127.0.0.1:${lease.port}, but nothing is listening; re-run \`${CLI_NAME} acquire --mode=${mode}\` to bring the host back`);
+	return {
+		lease,
+		databaseUrl: urlFromLease(lease)
+	};
+}
+/**
 * Resolve skip policy then acquire. Single entry for hosts (Cedar CLI, Jest, Vitest).
 * On external-url skip, applies DATABASE_URL / TEST_DATABASE_URL when `setEnv` is not false.
 */
@@ -716,7 +1007,8 @@ async function acquireIfNeeded(options) {
 	const outcome = await runIfNeeded(options, () => acquire({
 		root: options.root,
 		mode: options.mode,
-		setEnv: options.setEnv
+		setEnv: options.setEnv,
+		fresh: options.fresh
 	}));
 	if (outcome.status === "skipped") return outcome;
 	return {
@@ -732,9 +1024,8 @@ async function acquireIfNeeded(options) {
 * If the host is unavailable, leaves the lease so dispose/gc can retry.
 */
 async function dispose(options = {}) {
-	const identity = resolveWorktreeIdentity(options.root);
 	const mode = options.mode ?? "test";
-	const lease = readLease(identity.root, mode);
+	const lease = readLease(resolveRoot(options.root), mode);
 	if (!lease) return {
 		dropped: false,
 		reason: "no-lease"
@@ -776,6 +1067,6 @@ async function gc() {
 	return { dropped };
 }
 //#endregion
-export { buildCloneDatabaseName as C, runIfNeeded as S, buildRoleName as T, setDatabaseIsTemplate as _, urlFromLease as a, isExternalDatabaseEscapeHatch as b, ROLE_PASSWORD_SCHEME as c, discoverHost as d, dropDatabase as f, rolePasswordFor as g, resolveAutopgBin as h, gc as i, buildDatabaseUrl as l, requireAutopgBin as m, acquireIfNeeded as n, ensureHostRunning as o, parseHostStatus as p, dispose as r, INSTALL_HINT as s, acquire as t, cloneDatabaseFromTemplate as u, applyDatabaseUrlEnv as v, buildDatabaseName as w, resolveAcquireSkip as x, isCedarPgManagedUrl as y };
+export { resolveAcquireSkip as C, buildRoleName as D, buildDatabaseName as E, isExternalDatabaseEscapeHatch as S, buildCloneDatabaseName as T, rolePasswordFor as _, gc as a, applyDatabaseUrlEnv as b, ROLE_PASSWORD_SCHEME as c, cloneDatabaseFromTemplate as d, discoverHost as f, resolveAutopgBin as g, requireAutopgBin as h, dispose as i, adminUrlFor as l, parseHostStatus as m, acquireIfNeeded as n, urlFromLease as o, dropDatabase as p, attach as r, INSTALL_HINT as s, acquire as t, buildDatabaseUrl as u, setDatabaseIsTemplate as v, runIfNeeded as w, isCedarPgManagedUrl as x, truncateUserTables as y };
 
-//# sourceMappingURL=lifecycle-BvIx0xqq.mjs.map
+//# sourceMappingURL=lifecycle-2BZgSVz2.mjs.map