pgserve 1.2.0 → 2.0.1

package/src/gc.js

@@ -0,0 +1,351 @@
+/**
+ * pgserve GC — 3-layer lifecycle sweep (Group 5).
+ *
+ * Decides which user databases to reap based on:
+ *   1. `persist=true` — exempt from GC, audited as `db_persist_honored`.
+ *   2. Liveness — if `liveness_pid` points at a running process, slide
+ *      `last_connection_at` forward to "now" (the peer is alive, the row is
+ *      a heartbeat) and never reap.
+ *   3. TTL — peer is gone AND `now - last_connection_at > ttlMs` (default
+ *      24h) → `DROP DATABASE`, delete the meta row, audit reap event.
+ *
+ * Audit reap event is `db_reaped_liveness` when the row had a non-null
+ * liveness_pid that is now dead, otherwise `db_reaped_ttl` (the row never
+ * registered a liveness_pid — pure idle expiry).
+ *
+ * `installSweepTriggers(daemon, …)` wires the three call sites:
+ *   - boot: a single sweep right after the daemon is listening, with a
+ *     summary log line so operators see GC activity at startup.
+ *   - hourly `setInterval` (configurable via `intervalMs`).
+ *   - on-connect sampling: subscribe to the daemon's `'accept'` event and
+ *     fire `gcSweep` async at rate 1/N where `N = max(1, dbCount/10)`. The
+ *     listener never awaits the sweep, so accept latency is unaffected.
+ */
+
+import { audit, AUDIT_EVENTS } from './audit.js';
+import { forEachReapable, deleteMetaRow, touchLastConnection } from './control-db.js';
+
+const TTL_MS_DEFAULT = 24 * 60 * 60 * 1000;
+const HOURLY_MS = 60 * 60 * 1000;
+
+/**
+ * Default liveness probe — POSIX `kill(pid, 0)` returns 0 if the process is
+ * alive, throws ESRCH if gone, EPERM if owned by another user (still alive).
+ *
+ * @param {number|null|undefined} pid
+ * @returns {boolean}
+ */
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * @typedef {object} GcSweepOptions
+ * @property {{query: Function}} adminClient — pgserve admin DB connection
+ * @property {{adminPool: any, createdDatabases?: Set<string>}} [pgManager] —
+ *   optional; used to evict from the in-process createdDatabases cache after
+ *   a successful DROP. Tests can omit; gcSweep always falls back to the
+ *   adminClient's `query()` for the actual DROP.
+ * @property {number|Date} [now]
+ * @property {number} [ttlMs] — defaults to 24h
+ * @property {boolean} [dryRun] — when true, never DROP / DELETE / audit reap
+ * @property {(pid: number|null|undefined) => boolean} [isProcessAlive]
+ * @property {{warn?: Function, info?: Function, error?: Function, debug?: Function}} [logger]
+ */
+
+/**
+ * @typedef {object} GcSweepResult
+ * @property {number} examined
+ * @property {number} reaped
+ * @property {number} kept
+ * @property {number} persistSkipped
+ * @property {number} aliveSkipped
+ * @property {string[]} reapedNames
+ */
+
+/**
+ * Run one GC sweep. Returns counts so callers can log a summary or assert
+ * in tests.
+ *
+ * @param {GcSweepOptions} opts
+ * @returns {Promise<GcSweepResult>}
+ */
+export async function gcSweep({
+  adminClient,
+  pgManager = null,
+  now = new Date(),
+  ttlMs = TTL_MS_DEFAULT,
+  dryRun = false,
+  isProcessAlive = defaultIsProcessAlive,
+  logger,
+} = {}) {
+  if (!adminClient) throw new Error('gcSweep: adminClient required');
+
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) throw new Error('gcSweep: now must be Date or numeric ms');
+
+  const result = {
+    examined: 0,
+    reaped: 0,
+    kept: 0,
+    persistSkipped: 0,
+    aliveSkipped: 0,
+    reapedNames: [],
+  };
+
+  // Snapshot so we don't iterate while we DELETE — pg's async iterator
+  // protocols vary across drivers, but materialising 240 rows is cheap and
+  // sidesteps any cursor-vs-DELETE quirks.
+  const candidates = [];
+  for await (const row of forEachReapable(adminClient)) {
+    candidates.push(row);
+  }
+
+  for (const row of candidates) {
+    result.examined += 1;
+
+    // Persist=true rows never appear from forEachReapable (the query filters
+    // them out), but if the schema changes that contract we still defend
+    // here — and emit the audit event the wish promises.
+    if (row.persist) {
+      result.persistSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        audit(AUDIT_EVENTS.DB_PERSIST_HONORED, {
+          database: row.databaseName,
+          fingerprint: row.fingerprint,
+        });
+      }
+      continue;
+    }
+
+    const livenessPid = row.livenessPid;
+    const hadLivenessPid = Number.isInteger(livenessPid) && livenessPid > 0;
+    const alive = hadLivenessPid && isProcessAlive(livenessPid);
+
+    if (alive) {
+      result.aliveSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        // Slide the window: an alive process means the row is effectively
+        // current, even if the pgserve_meta last_connection_at value lags.
+        try {
+          await touchLastConnection(adminClient, {
+            databaseName: row.databaseName,
+            livenessPid,
+          });
+        } catch (err) {
+          logger?.warn?.(
+            { err: err?.message || String(err), database: row.databaseName },
+            'gcSweep: touchLastConnection failed for live row (non-fatal)',
+          );
+        }
+      }
+      continue;
+    }
+
+    const lastMs = row.lastConnectionAt instanceof Date
+      ? row.lastConnectionAt.getTime()
+      : Number(row.lastConnectionAt);
+    const ageMs = Number.isFinite(lastMs) ? nowMs - lastMs : Infinity;
+
+    if (ageMs <= ttlMs) {
+      result.kept += 1;
+      continue;
+    }
+
+    if (dryRun) {
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+      continue;
+    }
+
+    try {
+      await dropDatabaseSafely(adminClient, row.databaseName, logger);
+      pgManager?.createdDatabases?.delete(row.databaseName);
+      await deleteMetaRow(adminClient, row.databaseName);
+      const reapEvent = hadLivenessPid
+        ? AUDIT_EVENTS.DB_REAPED_LIVENESS
+        : AUDIT_EVENTS.DB_REAPED_TTL;
+      audit(reapEvent, {
+        database: row.databaseName,
+        fingerprint: row.fingerprint,
+        last_connection_at: row.lastConnectionAt instanceof Date
+          ? row.lastConnectionAt.toISOString()
+          : row.lastConnectionAt,
+        liveness_pid: livenessPid ?? null,
+        age_ms: Number.isFinite(ageMs) ? ageMs : null,
+      });
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err), database: row.databaseName },
+        'gcSweep: failed to reap database',
+      );
+    }
+  }
+
+  return result;
+}
+
+async function dropDatabaseSafely(adminClient, databaseName, logger) {
+  const escaped = `"${databaseName.replace(/"/g, '""')}"`;
+  // Terminate any lingering backends so DROP DATABASE doesn't refuse with
+  // 55006 (object_in_use). The peer's pgserve daemon socket is already gone
+  // (liveness dead) but Postgres can hold idle backends a while longer.
+  try {
+    await adminClient.query(
+      `SELECT pg_terminate_backend(pid)
+       FROM pg_stat_activity
+       WHERE datname = $1 AND pid <> pg_backend_pid()`,
+      [databaseName],
+    );
+  } catch (err) {
+    logger?.debug?.(
+      { err: err?.message || String(err), database: databaseName },
+      'gcSweep: pg_terminate_backend failed (non-fatal)',
+    );
+  }
+  await adminClient.query(`DROP DATABASE IF EXISTS ${escaped}`);
+}
+
+/**
+ * Wire the three sweep call sites onto a running daemon.
+ *
+ * Returns a `{stop()}` handle so tests (and `daemon.stop()`) can detach.
+ *
+ * @param {object} daemon — PgserveDaemon instance
+ * @param {object} [opts]
+ * @param {{query: Function}} [opts.adminClient] — defaults to daemon._adminClient
+ * @param {number} [opts.intervalMs] — hourly default; pass 0 to disable
+ * @param {number} [opts.ttlMs]
+ * @param {(pid: number) => boolean} [opts.isProcessAlive]
+ * @param {() => Promise<number>|number} [opts.getDbCount] — defaults to a
+ *   COUNT(*) query against pgserve_meta
+ * @param {boolean} [opts.bootSweep=true]
+ * @returns {{stop: () => Promise<void>, sweep: () => Promise<GcSweepResult>}}
+ */
+export function installSweepTriggers(daemon, opts = {}) {
+  const adminClient = opts.adminClient || daemon._adminClient;
+  if (!adminClient) {
+    throw new Error('installSweepTriggers: daemon has no admin client');
+  }
+  const intervalMs = opts.intervalMs == null ? HOURLY_MS : opts.intervalMs;
+  const ttlMs = opts.ttlMs == null ? TTL_MS_DEFAULT : opts.ttlMs;
+  const logger = daemon.logger;
+  const pgManager = daemon.pgManager;
+  const isProcessAlive = opts.isProcessAlive || defaultIsProcessAlive;
+  const getDbCount = opts.getDbCount || (async () => {
+    try {
+      const r = await adminClient.query('SELECT count(*)::int AS n FROM pgserve_meta');
+      return r.rows?.[0]?.n ?? 0;
+    } catch {
+      return 0;
+    }
+  });
+
+  let stopped = false;
+  let inflight = false;
+  let lastDbCount = 0;
+
+  const runSweep = async () => {
+    if (stopped) return null;
+    if (inflight) return null;
+    inflight = true;
+    try {
+      const res = await gcSweep({
+        adminClient,
+        pgManager,
+        now: new Date(),
+        ttlMs,
+        isProcessAlive,
+        logger,
+      });
+      lastDbCount = Math.max(0, lastDbCount - res.reaped);
+      return res;
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err) },
+        'gcSweep failed',
+      );
+      return null;
+    } finally {
+      inflight = false;
+    }
+  };
+
+  let timer = null;
+  if (intervalMs > 0) {
+    timer = setInterval(() => {
+      void runSweep();
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  const acceptListener = () => {
+    // Sample 1/N where N = max(1, ceil(dbCount/10)). Always async and
+    // detached so accept latency isn't blocked.
+    const n = Math.max(1, Math.ceil(lastDbCount / 10));
+    if (n === 1 || Math.random() * n < 1) {
+      setImmediate(() => {
+        if (stopped) return;
+        // Refresh count opportunistically before each sweep so on-connect
+        // sampling tracks the live row count without polling.
+        Promise.resolve(getDbCount())
+          .then((c) => { lastDbCount = Number(c) || 0; })
+          .then(runSweep)
+          .catch(() => { /* swallowed by runSweep */ });
+      });
+    }
+  };
+  daemon.on?.('accept', acceptListener);
+
+  const handle = {
+    sweep: runSweep,
+    async stop() {
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      daemon.off?.('accept', acceptListener);
+    },
+  };
+
+  if (opts.bootSweep !== false) {
+    // Boot sweep + count refresh + summary log. Detached so we don't block
+    // start() — the daemon is already listening at this point.
+    setImmediate(async () => {
+      try {
+        lastDbCount = Number(await getDbCount()) || 0;
+        const res = await runSweep();
+        if (res) {
+          logger?.info?.(
+            {
+              examined: res.examined,
+              reaped: res.reaped,
+              kept: res.kept,
+              persist_skipped: res.persistSkipped,
+              alive_skipped: res.aliveSkipped,
+            },
+            'pgserve GC: boot sweep complete',
+          );
+        }
+      } catch (err) {
+        logger?.warn?.(
+          { err: err?.message || String(err) },
+          'pgserve GC: boot sweep failed',
+        );
+      }
+    });
+  }
+
+  return handle;
+}

package/src/index.js

@@ -13,6 +13,37 @@ export { RestoreManager } from './restore.js';
 export { Dashboard } from './dashboard.js';
 export { StatsCollector } from './stats-collector.js';
 export { StatsDashboard } from './stats-dashboard.js';
+export {
+  PgserveDaemon,
+  startDaemon,
+  stopDaemon,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+  resolvePidLockPath,
+  resolveLibpqCompatPath,
+  acquirePidLock,
+  isProcessAlive,
+} from './daemon.js';
+export {
+  buildDaemonArgs,
+  daemonClientOptions,
+  ensureDaemon,
+  probeDaemon,
+  resolveBundledCliBin,
+} from './sdk.js';
+export {
+  derivePackageFingerprint,
+  deriveScriptFingerprint,
+  fingerprintFromCred,
+  findNearestPackageJson,
+  readPackageName,
+  readPersistFlag,
+} from './fingerprint.js';
+export {
+  hashToken,
+  mintToken,
+  parseTcpAuth,
+} from './tokens.js';
 
 // Default export
 export { startMultiTenantServer as default } from './router.js';

package/src/protocol.js

@@ -133,6 +133,137 @@ export function extractDatabaseName(data) {
   }
 }
 
+/**
+ * Extract `application_name` from a startup message buffer. Returns null when
+ * absent or when the buffer is malformed (callers fall back to no-auth).
+ *
+ * @param {Buffer} data
+ * @returns {string|null}
+ */
+export function extractApplicationName(data) {
+  try {
+    const params = parseStartupMessage(data, /* fastPath */ false);
+    return typeof params.application_name === 'string' ? params.application_name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return a new startup-message buffer with the `database` parameter replaced
+ * by `newDbName`. All other parameters (and their order) are preserved by
+ * default; pass `dropParams: ['application_name', ...]` to strip noisy
+ * fields the daemon would rather not forward to PG verbatim. The 4-byte
+ * length prefix at the start of the buffer is recomputed.
+ *
+ * Group 6 uses this on TCP-authenticated connections so a peer that presents
+ * a token for fingerprint X is forced into fingerprint X's database, even
+ * if the libpq client requested a different one.
+ *
+ * @param {Buffer} data — original startup message
+ * @param {string} newDbName
+ * @param {{dropParams?: string[]}} [opts]
+ * @returns {Buffer}
+ */
+export function rewriteDatabaseName(data, newDbName, opts = {}) {
+  if (!Buffer.isBuffer(data)) throw new Error('rewriteDatabaseName: buffer required');
+  if (typeof newDbName !== 'string' || newDbName.length === 0) {
+    throw new Error('rewriteDatabaseName: non-empty newDbName required');
+  }
+  const length = data.readInt32BE(0);
+  const version = data.readInt32BE(4);
+  const drop = new Set(opts.dropParams || []);
+
+  // Walk parameters; build a list of (key, value) pairs replacing 'database'.
+  const pairs = [];
+  let offset = 8;
+  let sawDatabase = false;
+  while (offset < length - 1) {
+    const keyEnd = data.indexOf(0, offset);
+    if (keyEnd === -1 || keyEnd >= length) break;
+    const key = data.toString('utf8', offset, keyEnd);
+    offset = keyEnd + 1;
+    const valueEnd = data.indexOf(0, offset);
+    if (valueEnd === -1 || valueEnd >= length) break;
+    const value = data.toString('utf8', offset, valueEnd);
+    offset = valueEnd + 1;
+    if (drop.has(key)) continue;
+    if (key === 'database') {
+      pairs.push(['database', newDbName]);
+      sawDatabase = true;
+    } else {
+      pairs.push([key, value]);
+    }
+  }
+  if (!sawDatabase) pairs.push(['database', newDbName]);
+
+  // Compute new buffer size: 4 (length) + 4 (version) + sum(key+1 + value+1) + 1 (terminator).
+  let bodyLen = 0;
+  for (const [k, v] of pairs) {
+    bodyLen += Buffer.byteLength(k, 'utf8') + 1 + Buffer.byteLength(v, 'utf8') + 1;
+  }
+  const total = 4 + 4 + bodyLen + 1;
+  const out = Buffer.alloc(total);
+  out.writeInt32BE(total, 0);
+  out.writeInt32BE(version, 4);
+  let cur = 8;
+  for (const [k, v] of pairs) {
+    cur += out.write(k, cur, 'utf8');
+    out[cur++] = 0;
+    cur += out.write(v, cur, 'utf8');
+    out[cur++] = 0;
+  }
+  out[cur++] = 0; // final terminator
+  return out;
+}
+
+/**
+ * Build a PostgreSQL ErrorResponse (`'E'`) frame.
+ *
+ * Used by the daemon to reject cross-fingerprint connection attempts
+ * with SQLSTATE `28P01 invalid_authorization_specification` before the
+ * peer's startup message ever reaches the underlying PG instance.
+ *
+ * Frame layout (PG protocol v3):
+ *   'E' (1 byte) | length (4 bytes, includes itself) | <fields...> | '\0'
+ *
+ * Each field: type-byte | utf8 string | '\0'
+ * Required fields per PG docs: 'S' (Severity), 'C' (SQLSTATE), 'M' (Message).
+ * 'V' (localized severity, server >= 9.6) is included for parity with the
+ * frames real Postgres emits — psql / pg drivers parse both transparently.
+ *
+ * @param {{severity?: string, sqlstate: string, message: string}} args
+ * @returns {Buffer}
+ */
+export function buildErrorResponse({ severity = 'FATAL', sqlstate, message }) {
+  if (typeof sqlstate !== 'string' || sqlstate.length !== 5) {
+    throw new TypeError('buildErrorResponse: sqlstate must be a 5-character string');
+  }
+  if (typeof message !== 'string' || message.length === 0) {
+    throw new TypeError('buildErrorResponse: message must be a non-empty string');
+  }
+  const field = (typeChar, value) => {
+    const valBytes = Buffer.byteLength(value, 'utf8');
+    const buf = Buffer.alloc(1 + valBytes + 1);
+    buf.writeUInt8(typeChar.charCodeAt(0), 0);
+    buf.write(value, 1, 'utf8');
+    buf.writeUInt8(0, 1 + valBytes);
+    return buf;
+  };
+  const body = Buffer.concat([
+    field('S', severity),
+    field('V', severity),
+    field('C', sqlstate),
+    field('M', message),
+    Buffer.from([0]),
+  ]);
+  const frameLength = 4 + body.length;
+  const header = Buffer.alloc(5);
+  header.writeUInt8(0x45, 0); // 'E'
+  header.writeUInt32BE(frameLength, 1);
+  return Buffer.concat([header, body]);
+}
+
 // Pre-allocated buffer pool for startup message parsing (avoids allocation per connection)
 const STARTUP_BUFFER_SIZE = 8192; // Max startup message is typically < 1KB
 const bufferPool = [];

package/src/router.js

@@ -12,6 +12,14 @@
  * - Memory mode (default) or persistent storage
  *
  * PERFORMANCE: Uses Bun.listen() and Bun.connect() for 2-3x throughput improvement
+ *
+ * v2 NOTE: The MultiTenantRouter is the **direct-embed** path — callers that
+ * spawn their own PostgresManager and bind a TCP port get a per-pid Unix
+ * socket from `pgManager.getSocketPath()` (preserved by PR #24). The new
+ * **daemon** path (`src/daemon.js`) binds a singleton control socket at
+ * `$XDG_RUNTIME_DIR/pgserve/control.sock` and is the v2 default for the
+ * `pgserve daemon` CLI subcommand. Both paths coexist; direct-embed callers
+ * are not affected by daemon mode.
  */
 
 import fs from 'fs';

package/src/sdk.js

@@ -0,0 +1,137 @@
+/**
+ * Public SDK helpers for applications that want to consume the singleton
+ * pgserve daemon without shelling out themselves.
+ *
+ * The intended flow is:
+ *   1. App calls ensureDaemon() during install/startup.
+ *   2. App connects with daemonClientOptions().
+ *   3. pgserve derives the app identity from the Unix-socket peer creds and
+ *      routes it to that app's fingerprinted database.
+ */
+
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  isProcessAlive,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+  resolveLibpqCompatPath,
+  resolvePidLockPath,
+} from './daemon.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function probeDaemon({ controlSocketDir = resolveControlSocketDir() } = {}) {
+  const socketPath = resolveControlSocketPath(controlSocketDir);
+  const libpqSocketPath = resolveLibpqCompatPath(controlSocketDir);
+  const pidLockPath = resolvePidLockPath(controlSocketDir);
+  const socketPresent = fs.existsSync(socketPath);
+  const libpqSocketPresent = fs.existsSync(libpqSocketPath);
+  let pid = null;
+
+  try {
+    const raw = fs.readFileSync(pidLockPath, 'utf8').trim();
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isInteger(parsed) && parsed > 0) pid = parsed;
+  } catch {
+    // Missing/unreadable pid file means no live daemon can be trusted.
+  }
+
+  const pidAlive = pid !== null && isProcessAlive(pid);
+  const running = pidAlive && socketPresent && libpqSocketPresent;
+  return {
+    running,
+    pid: pidAlive ? pid : null,
+    socketPresent,
+    libpqSocketPresent,
+    controlSocketDir,
+    controlSocketPath: socketPath,
+    libpqSocketPath,
+    pidLockPath,
+    reason: running ? null : explainProbeMiss({ pid, pidAlive, socketPresent, libpqSocketPresent }),
+  };
+}
+
+function explainProbeMiss({ pid, pidAlive, socketPresent, libpqSocketPresent }) {
+  if (pid === null && !socketPresent && !libpqSocketPresent) return 'no daemon';
+  if (pid !== null && !pidAlive) return 'stale pid';
+  if (!socketPresent) return 'control socket missing';
+  if (!libpqSocketPresent) return 'libpq socket missing';
+  return 'not running';
+}
+
+export function daemonClientOptions({
+  controlSocketDir = resolveControlSocketDir(),
+  database = 'postgres',
+  username = 'postgres',
+} = {}) {
+  return {
+    host: controlSocketDir,
+    port: 5432,
+    database,
+    username,
+    password: '',
+  };
+}
+
+export function buildDaemonArgs({
+  dataDir,
+  ram = false,
+  logLevel,
+  noProvision = false,
+  listens = [],
+  pgvector = false,
+} = {}) {
+  const args = ['daemon'];
+  if (dataDir) args.push('--data', dataDir);
+  if (ram) args.push('--ram');
+  if (logLevel) args.push('--log', logLevel);
+  if (noProvision) args.push('--no-provision');
+  if (pgvector) args.push('--pgvector');
+  for (const listen of Array.isArray(listens) ? listens : [listens]) {
+    if (listen) args.push('--listen', String(listen));
+  }
+  return args;
+}
+
+export async function ensureDaemon(options = {}) {
+  const controlSocketDir = options.controlSocketDir || resolveControlSocketDir();
+  const initial = probeDaemon({ controlSocketDir });
+  if (initial.running) return initial;
+
+  const bin = options.bin || resolveBundledCliBin();
+  const env = { ...process.env, ...envForControlSocketDir(controlSocketDir), ...(options.env || {}) };
+  const child = spawn(bin, buildDaemonArgs(options), {
+    detached: true,
+    stdio: 'ignore',
+    env,
+  });
+  child.unref();
+
+  const timeoutMs = options.timeoutMs || 16000;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = probeDaemon({ controlSocketDir });
+    if (state.running) return state;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  const state = probeDaemon({ controlSocketDir });
+  const err = new Error(`pgserve daemon did not become ready within ${timeoutMs}ms (${state.reason})`);
+  err.code = 'EPGSERVE_DAEMON_TIMEOUT';
+  err.state = state;
+  throw err;
+}
+
+export function resolveBundledCliBin() {
+  return path.join(__dirname, '..', 'bin', 'pgserve-wrapper.cjs');
+}
+
+function envForControlSocketDir(controlSocketDir) {
+  if (path.basename(controlSocketDir) !== 'pgserve') {
+    throw new Error('ensureDaemon: controlSocketDir must be a pgserve runtime directory ending in /pgserve');
+  }
+  return { XDG_RUNTIME_DIR: path.dirname(controlSocketDir) };
+}