@cedarjs/pg 0.2.0-alpha.0 → 0.3.0

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

@@ -20,8 +20,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_constants = require("./constants-Ct8myrEn.cjs");
-const require_lease = require("./lease-Bq9wKwQa.cjs");
+const require_lease = require("./lease-WlmOnNDi.cjs");
 let node_fs = require("node:fs");
 let node_os = require("node:os");
 let node_path = require("node:path");
@@ -54,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
@@ -168,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";
@@ -194,8 +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` output. Requires a numeric port and running !== false.
+* 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` / `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;
@@ -205,8 +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}`);
-	if (parsed.running === false) throw new Error(`autopg host is not running.\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`.
@@ -221,13 +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 a live autopg host via `autopg status --json`. Throws if the host is not proven live.
+* 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",
@@ -239,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 {
@@ -269,7 +375,7 @@ async function withAdminClient(adminUrl, fn) {
 * same role keep working when `buildDatabaseUrl` is called with a new database.
 */
 function rolePasswordFor(roleName) {
-	return (0, node_crypto.createHash)("sha256").update(`${require_constants.PASSWORD_SALT_PREFIX}\0${roleName}`).digest("hex").slice(0, 32);
+	return (0, node_crypto.createHash)("sha256").update(`${require_lease.PASSWORD_SALT_PREFIX}\0${roleName}`).digest("hex").slice(0, 32);
 }
 /**
 * Idempotently CREATE ROLE + CREATE DATABASE with cedar-pg owned names.
@@ -293,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) {
@@ -358,29 +505,33 @@ function buildDatabaseUrl(opts) {
 }
 //#endregion
 //#region src/providers/host.ts
-/** Fixed CI TCP port so install registration and postmaster listen on the same port. */
 const EPHEMERAL_PORT = 55432;
-const OWNED_POSTMASTER_READY_MS = 3e4;
-const OWNED_POSTMASTER_POLL_MS = 200;
+const HOST_READY_MS = 3e4;
+const HOST_POLL_MS = 200;
+/** `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;
 /**
-* Resolve whether to start an owned ephemeral postmaster or use local pm2 install.
+* 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. 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
-* - `CEDAR_PG_EPHEMERAL_HOST=0` → local (even when `CI=true`)
+* - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral owned postmaster
+* - `CEDAR_PG_EPHEMERAL_HOST=0` → never own an ephemeral postmaster, local registered host only (even in CI)
 * - unset + `CI=true` → ephemeral
 * - otherwise → local
 */
-function resolveEphemeralHostPolicy(env = process.env) {
+function resolveHostStartPolicy(env = process.env) {
 	const force = env.CEDAR_PG_EPHEMERAL_HOST;
 	if (force === "1") return "ephemeral";
 	if (force === "0") return "local";
 	if (env.CI === "true") return "ephemeral";
 	return "local";
 }
-/**
-* Fixed CI recipe: shared `--port` on install + postmaster, `--no-pm2 --no-ui`,
-* and `--ram` + `/dev/shm/cedar-pg-<uid>` on Linux when shm exists.
-*/
 function ephemeralHostRecipe(ctx = {}) {
 	const platform = ctx.platform ?? process.platform;
 	const shmAvailable = ctx.shmAvailable ?? (platform === "linux" && (0, node_fs.existsSync)("/dev/shm"));
@@ -391,15 +542,6 @@ function ephemeralHostRecipe(ctx = {}) {
 	return {
 		dataDir,
 		port,
-		installArgs: [
-			"install",
-			"--no-pm2",
-			"--no-ui",
-			"--port",
-			String(port),
-			"--data",
-			dataDir
-		],
 		postmasterArgs: [
 			"postmaster",
 			...useRam ? ["--ram"] : [],
@@ -412,7 +554,6 @@ function ephemeralHostRecipe(ctx = {}) {
 		]
 	};
 }
-/** Discovery from the recipe port — TCP readiness is the authority, not `autopg status`. */
 function discoveryFromRecipe(bin, recipe) {
 	return {
 		port: recipe.port,
@@ -423,8 +564,25 @@ function discoveryFromRecipe(bin, recipe) {
 function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function runInstall(bin, args) {
-	const install = (0, node_child_process.spawnSync)(bin, args, {
+/** True when stderr/stdout looks like a /dev/shm quota or ENOSPC failure. */
+function looksLikeShmSpaceError(text) {
+	return /Disk quota exceeded|No space left on device|ENOSPC|\b53100\b/i.test(text);
+}
+function formatHostStartError(detail, useRamShm = false) {
+	return `Failed to start autopg host.\n${detail}\n${INSTALL_HINT}${useRamShm && looksLikeShmSpaceError(detail) ? `\n${EPHEMERAL_SHM_HINT}` : ""}`;
+}
+/** Free bytes on `path`, or `null` if unavailable. */
+function freeBytesOn(path) {
+	try {
+		const s = (0, node_fs.statfsSync)(path);
+		return Number(s.bavail) * Number(s.bsize);
+	} catch {
+		return null;
+	}
+}
+/** Run a one-shot autopg verb. Returns failure detail, or `null` on exit 0. */
+function runAutopg(bin, argv) {
+	const result = (0, node_child_process.spawnSync)(bin, argv, {
 		encoding: "utf8",
 		stdio: [
 			"ignore",
@@ -432,7 +590,10 @@ function runInstall(bin, args) {
 			"pipe"
 		]
 	});
-	if (install.status !== 0) throw new Error(`Failed to start autopg host (exit ${install.status}).\n${install.stderr || install.stdout || ""}\n${INSTALL_HINT}`);
+	if (result.error) return result.error.message;
+	if (result.status === 0) return null;
+	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) {
@@ -449,7 +610,6 @@ function canConnect(port) {
 		});
 	});
 }
-/** Kill a detached owned postmaster (process group when possible) and drop our handle. */
 function killOwnedChild(child) {
 	const pid = child.pid;
 	if (pid != null) try {
@@ -462,89 +622,294 @@ function killOwnedChild(child) {
 	child.unref();
 }
 /**
-* Poll until TCP accepts on port, or throw on timeout / {@link WaitForOwnedPostmasterOptions.failure}.
-* Exported for tests — the readiness seam for owned ephemeral start.
+* The single liveness primitive: TCP accept on 127.0.0.1:port.
+*
+* Resolves `true` as soon as something is listening, `false` when the grace
+* period expires, and throws only what {@link WaitForListenerOptions.failure}
+* returns. Used for attach (one probe), local restart, and ephemeral start.
 */
-async function waitForOwnedPostmaster(opts) {
+async function waitForListener(opts) {
 	const probe = opts.canConnect ?? canConnect;
 	const now = opts.now ?? Date.now;
 	const pause = opts.sleep ?? sleep;
-	const readyMs = opts.readyMs ?? OWNED_POSTMASTER_READY_MS;
-	const pollMs = opts.pollMs ?? OWNED_POSTMASTER_POLL_MS;
-	const deadline = now() + readyMs;
-	let lastDetail = "TCP not accepting";
-	while (now() < deadline) {
+	const pollMs = opts.pollMs ?? HOST_POLL_MS;
+	const deadline = now() + (opts.readyMs ?? 0);
+	for (;;) {
 		const fail = opts.failure?.();
 		if (fail) throw fail;
-		if (await probe(opts.port)) return;
-		lastDetail = `127.0.0.1:${opts.port} not accepting connections`;
+		if (await probe(opts.port)) return true;
+		if (now() >= deadline) return false;
 		await pause(pollMs);
 	}
-	throw new Error(`Timed out waiting for autopg host after ${readyMs}ms.\n${lastDetail}\n${INSTALL_HINT}`);
 }
 /**
-* Install + detached postmaster with fully ignored stdio so the CI job owns lifetime
-* (caller exit must not close pipes under the daemon).
+* Attach to the registered autopg host once TCP accepts on its port.
 *
-* Readiness is TCP accept on the recipe port — not `autopg status`, which succeeds
-* after `install --no-pm2` before postmaster is listening. On success, discovery is
-* recipe-derived (same port). On failure, the spawned child is killed.
+* Registration is not liveness: a stopped pm2 host still reports a port, and
+* attaching to it is the `ECONNREFUSED 127.0.0.1:25432` bug. `readyMs` > 0 is
+* the grace period after asking autopg to start.
 */
-async function startEphemeralHost(bin) {
-	const recipe = ephemeralHostRecipe();
-	(0, node_fs.mkdirSync)(recipe.dataDir, { recursive: true });
-	runInstall(bin, recipe.installArgs);
-	const state = {
-		exit: null,
-		spawnError: null
-	};
-	const child = (0, node_child_process.spawn)(bin, recipe.postmasterArgs, {
-		detached: true,
-		stdio: "ignore"
-	});
+async function attachLiveHost(bin, readyMs = 0) {
+	let discovered;
+	try {
+		discovered = discoverHost(bin);
+	} catch {
+		return null;
+	}
+	return await waitForListener({
+		port: discovered.port,
+		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);
+}
+/**
+* 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.
+*/
+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 });
+		}
+	} 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) => {
-		state.spawnError = err;
+		died = /* @__PURE__ */ new Error(`Failed to spawn autopg postmaster.\n${err.message}`);
 	});
 	child.on("exit", (code, signal) => {
-		state.exit = {
-			code,
-			signal
-		};
+		died ??= /* @__PURE__ */ new Error(`autopg postmaster exited before ready (code=${code}, signal=${signal}).`);
 	});
 	try {
-		await waitForOwnedPostmaster({
-			port: recipe.port,
-			failure: () => {
-				if (state.spawnError) return /* @__PURE__ */ new Error(`Failed to spawn autopg postmaster.\n${state.spawnError.message}\n${INSTALL_HINT}`);
-				if (state.exit) return /* @__PURE__ */ new Error(`autopg postmaster exited before ready (code=${state.exit.code}, signal=${state.exit.signal}).\nautopg is required. Install with:
-  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/main/install.sh | bash
-Then ensure ~/.local/bin is on PATH, or set AUTOPG_BIN.`);
-				return null;
-			}
-		});
+		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();
-	return discoveryFromRecipe(bin, recipe);
 }
 /**
-* Ensure the host postmaster is up.
+* 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.
 *
-* - Attaches when `autopg status --json` shows a live host.
-* - Otherwise starts from {@link resolveEphemeralHostPolicy}: local pm2 `install`,
-*   or opinionated ephemeral (`--no-pm2 --no-ui` + detached postmaster).
-* - CI job owns ephemeral postmaster lifetime on success (no cedar-pg host dispose).
-* - Failed ephemeral start kills the spawned child so ensure is atomic for the caller.
+* 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(`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 = 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")}`));
+}
+/**
+* Ephemeral host owned by this process/job: detached `autopg postmaster` with
+* fully ignored stdio (caller exit must not close pipes under the daemon).
+*
+* 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. 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, recipe = ephemeralHostRecipe()) {
+	const { dataDir, port } = recipe;
+	if (await canConnect(port)) return discoveryFromRecipe(bin, recipe);
+	const useRamShm = recipe.postmasterArgs.includes("--ram");
+	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 });
+	try {
+		await spawnDetachedPostmaster({
+			bin,
+			args: recipe.postmasterArgs,
+			port: recipe.port,
+			readyMs: HOST_READY_MS
+		});
+	} catch (err) {
+		if (liveDataDirOwner(recipe.dataDir) != null) return;
+		throw new Error(formatHostStartError(errorDetail(err), useRamShm));
+	}
+}
+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 {
-		return discoverHost(bin);
+		registered = discoverRegistration(bin);
 	} catch {}
-	if (resolveEphemeralHostPolicy() === "ephemeral") return startEphemeralHost(bin);
-	runInstall(bin, ["install"]);
-	return discoverHost(bin);
+	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
@@ -587,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,
@@ -635,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.
 */
@@ -642,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 {
@@ -658,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"
@@ -726,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() {
@@ -780,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() {
@@ -846,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() {
@@ -853,4 +1253,4 @@ Object.defineProperty(exports, "urlFromLease", {
 	}
 });
 
-//# sourceMappingURL=lifecycle-DEJ4GgWV.cjs.map
+//# sourceMappingURL=lifecycle-BCeM96tI.cjs.map