@cedarjs/pg 0.2.0-beta.0 → 0.3.0

package/dist/{lifecycle-BbrvFQvg.cjs → lifecycle-BCeM96tI.cjs}

@@ -53,21 +53,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
@@ -167,6 +174,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";
@@ -193,14 +202,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;
@@ -210,7 +224,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`.
@@ -225,15 +248,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 (0, node_child_process.spawnSync)(bin, ["--version"], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		],
+		timeout: 5e3
+	}).stdout ?? "";
+}
+function readStatusJson(bin) {
 	try {
-		status = (0, node_child_process.execFileSync)(bin, ["status", "--json"], {
+		return (0, node_child_process.execFileSync)(bin, ["status", "--json"], {
 			encoding: "utf8",
 			stdio: [
 				"ignore",
@@ -245,22 +297,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.default.Client({ connectionString: adminUrl });
-	await client.connect();
+	const client = await connectWhileStartingUp(async () => {
+		const attempt = new pg.default.Client({ connectionString: adminUrl });
+		try {
+			await attempt.connect();
+			return attempt;
+		} catch (err) {
+			await attempt.end().catch(() => {});
+			throw err;
+		}
+	});
 	try {
 		return await fn(client);
 	} finally {
@@ -299,18 +399,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) {
@@ -367,37 +508,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
 */
@@ -447,38 +571,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 (!(0, node_fs.existsSync)(path)) return;
-		try {
-			(0, node_fs.rmSync)(path, {
-				recursive: true,
-				force: true
-			});
-			removed.push(path);
-		} catch {}
-	};
-	tryRm(opts.dataDir);
-	const shmRoot = opts.shmRoot ?? ((0, node_fs.existsSync)("/dev/shm") ? "/dev/shm" : void 0);
-	if (!shmRoot) return removed;
-	let entries = [];
-	try {
-		entries = (0, node_fs.readdirSync)(shmRoot);
-	} catch {
-		return removed;
-	}
-	for (const name of entries) if (name.startsWith("cedar-pg-") || name.startsWith("pgserve-") || name.startsWith("PostgreSQL.")) tryRm((0, node_path.join)(shmRoot, name));
-	return removed;
-}
 /** Free bytes on `path`, or `null` if unavailable. */
 function freeBytesOn(path) {
 	try {
@@ -500,7 +592,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) {
@@ -568,25 +661,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((0, node_path.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((0, node_fs.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}`;
+	(0, node_fs.writeFileSync)(mine, String(process.pid));
+	try {
+		for (;;) {
+			try {
+				(0, node_fs.linkSync)(mine, lockPath);
+				return null;
+			} catch (err) {
+				if (err.code !== "EEXIST") throw err;
+			}
+			const holder = livePidIn(lockPath);
+			if (holder != null) return holder;
+			(0, node_fs.rmSync)(lockPath, { force: true });
 		}
-		const attached = await attachLiveHost(bin, readyMs);
+	} finally {
+		(0, node_fs.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 ? (0, node_fs.openSync)(opts.logFile, "a") : null;
+	let child;
+	try {
+		child = (0, node_child_process.spawn)(opts.bin, opts.args, {
+			detached: true,
+			stdio: logFd == null ? "ignore" : [
+				"ignore",
+				logFd,
+				logFd
+			]
+		});
+	} finally {
+		if (logFd != null) (0, node_fs.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 ? (0, node_path.join)(logsDir, REVIVED_POSTMASTER_LOG) : void 0;
+	if (liveDataDirOwner(dataDir) == null) try {
+		(0, node_fs.mkdirSync)(dataDir, {
+			recursive: true,
+			mode: 448
+		});
+		if (logsDir) (0, node_fs.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")}`));
 }
 /**
@@ -595,53 +845,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 {
+		(0, node_fs.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) {
+	(0, node_fs.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`);
 	}
 	(0, node_fs.mkdirSync)(recipe.dataDir, { recursive: true });
-	const child = (0, node_child_process.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
@@ -684,8 +952,14 @@ async function acquire(options) {
 	const identity = require_lease.resolveWorktreeIdentity(options.root);
 	const mode = options.mode;
 	const databaseName = buildDatabaseName(identity, mode);
-	const roleName = buildRoleName(databaseName);
+	const leased = require_lease.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,
@@ -732,6 +1006,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 = require_lease.resolveRoot(options.root);
+	const { mode } = options;
+	const lease = require_lease.readLease(root, mode);
+	if (!lease) throw new Error(`no ${mode} lease in ${root}; run \`${require_lease.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 \`${require_lease.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.
 */
@@ -739,7 +1030,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 {
@@ -755,9 +1047,8 @@ async function acquireIfNeeded(options) {
 * If the host is unavailable, leaves the lease so dispose/gc can retry.
 */
 async function dispose(options = {}) {
-	const identity = require_lease.resolveWorktreeIdentity(options.root);
 	const mode = options.mode ?? "test";
-	const lease = require_lease.readLease(identity.root, mode);
+	const lease = require_lease.readLease(require_lease.resolveRoot(options.root), mode);
 	if (!lease) return {
 		dropped: false,
 		reason: "no-lease"
@@ -823,12 +1114,24 @@ Object.defineProperty(exports, "acquireIfNeeded", {
 		return acquireIfNeeded;
 	}
 });
+Object.defineProperty(exports, "adminUrlFor", {
+	enumerable: true,
+	get: function() {
+		return adminUrlFor;
+	}
+});
 Object.defineProperty(exports, "applyDatabaseUrlEnv", {
 	enumerable: true,
 	get: function() {
 		return applyDatabaseUrlEnv;
 	}
 });
+Object.defineProperty(exports, "attach", {
+	enumerable: true,
+	get: function() {
+		return attach;
+	}
+});
 Object.defineProperty(exports, "buildCloneDatabaseName", {
 	enumerable: true,
 	get: function() {
@@ -877,12 +1180,6 @@ Object.defineProperty(exports, "dropDatabase", {
 		return dropDatabase;
 	}
 });
-Object.defineProperty(exports, "ensureHostRunning", {
-	enumerable: true,
-	get: function() {
-		return ensureHostRunning;
-	}
-});
 Object.defineProperty(exports, "gc", {
 	enumerable: true,
 	get: function() {
@@ -943,6 +1240,12 @@ Object.defineProperty(exports, "setDatabaseIsTemplate", {
 		return setDatabaseIsTemplate;
 	}
 });
+Object.defineProperty(exports, "truncateUserTables", {
+	enumerable: true,
+	get: function() {
+		return truncateUserTables;
+	}
+});
 Object.defineProperty(exports, "urlFromLease", {
 	enumerable: true,
 	get: function() {
@@ -950,4 +1253,4 @@ Object.defineProperty(exports, "urlFromLease", {
 	}
 });
 
-//# sourceMappingURL=lifecycle-BbrvFQvg.cjs.map
+//# sourceMappingURL=lifecycle-BCeM96tI.cjs.map