pgserve 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `pgserve` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.4
+
+### Fixed
+
+- `_startPostgres()` now removes a stale `postmaster.pid` from the data
+  directory before spawning postgres. Previously, an unclean shutdown
+  (SIGKILL, machine reboot, OOM) left a `postmaster.pid` whose recorded
+  PID was no longer alive, and postgres refused to start with
+  `FATAL: lock file "postmaster.pid" already exists` on the next boot.
+  Operators had to `rm postmaster.pid` manually to recover. A live PID
+  is never touched, so a real concurrent postmaster still surfaces the
+  normal lock conflict. ([#46](https://github.com/namastexlabs/pgserve/pull/46),
+  fixes [#45](https://github.com/namastexlabs/pgserve/issues/45))
+
 ## 2.0.0 — Unreleased
 
 > The release date will replace "Unreleased" when the v2.0.0 release workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/src/admin-client.js

@@ -36,7 +36,9 @@ import path from 'path';
  * @param {string} [args.user='postgres']
  * @param {string} [args.password='postgres']
  * @param {number} [args.max=2]
- * @returns {Promise<{query: (text: string, params?: any[]) => Promise<{rows: any[], rowCount: number}>, end: () => Promise<void>, sql: any}>}
+ * @param {number} [args.idleTimeout=300]
+ * @param {number} [args.queryTimeoutMs=0]
+ * @returns {Promise<{supportsQueryOptions: boolean, query: (text: string, params?: any[], opts?: {timeoutMs?: number}) => Promise<{rows: any[], rowCount: number}>, end: () => Promise<void>, sql: any}>}
  */
 export async function createAdminClient({
   socketDir: _socketDir = null,
@@ -46,25 +48,37 @@ export async function createAdminClient({
   user = 'postgres',
   password = 'postgres',
   max = 2,
+  idleTimeout = 300,
+  queryTimeoutMs = 0,
 } = {}) {
   if (typeof port !== 'number') throw new Error('createAdminClient: port required');
-  const sql = new SQL({
+  const options = {
     hostname: host,
     port,
     database,
     username: user,
     password,
     max,
-    // TODO #38: investigate GC perf for 240-orphan sweep on shared CI runners;
-    // bumped 10s→30s during Felipe deadline 2026-04-29 to unblock pgserve v2.0 ship.
-    idleTimeout: 30,
-  });
+    idleTimeout,
+  };
+  let sql = new SQL(options);
   // Light probe so a misconfigured daemon fails loudly here rather than at
   // first query.
   await sql`SELECT 1`;
+
+  async function reopen() {
+    const closing = sql;
+    sql = new SQL(options);
+    void closing.close().catch(() => { /* swallow */ });
+    await sql`SELECT 1`;
+  }
+
   return {
-    sql,
-    async query(text, params = []) {
+    supportsQueryOptions: true,
+    get sql() {
+      return sql;
+    },
+    async query(text, params = [], opts = {}) {
       // control-db.js is written for the pg npm module's contract, which
       // requires JSON-stringified payloads bound to JSONB parameters.
       // Bun.SQL goes the other way: it stringifies JS objects when they
@@ -73,12 +87,14 @@ export async function createAdminClient({
       // it represents). Bridge the impedance mismatch here so the same
       // call sites work against either driver.
       const adapted = params.map(coerceJsonbParam);
-      const rows = await sql.unsafe(text, adapted);
-      // Bun returns an Array of plain objects with `count` set on it; turn
-      // JSONB columns back into JS values so control-db.js's parseTokens
-      // sees the array-of-objects shape it would receive from pg.
-      const out = Array.from(rows).map(decodeJsonColumns);
-      return { rows: out, rowCount: rows.count ?? rows.length ?? 0 };
+      const timeoutMs = opts.timeoutMs ?? queryTimeoutMs;
+      try {
+        return await runQueryWithTimeout(sql, text, adapted, timeoutMs);
+      } catch (err) {
+        if (!isRetriableAdminQueryError(err)) throw err;
+        await reopen();
+        return await runQueryWithTimeout(sql, text, adapted, timeoutMs);
+      }
     },
     async end() {
       try { await sql.close(); } catch { /* swallow */ }
@@ -86,6 +102,42 @@ export async function createAdminClient({
   };
 }
 
+async function runQueryWithTimeout(sql, text, params, queryTimeoutMs) {
+  const query = runQuery(sql, text, params);
+  return withTimeout(query, queryTimeoutMs);
+}
+
+async function runQuery(sql, text, params) {
+  const rows = await sql.unsafe(text, params);
+  // Bun returns an Array of plain objects with `count` set on it; turn
+  // JSONB columns back into JS values so control-db.js's parseTokens
+  // sees the array-of-objects shape it would receive from pg.
+  const out = Array.from(rows).map(decodeJsonColumns);
+  return { rows: out, rowCount: rows.count ?? rows.length ?? 0 };
+}
+
+function withTimeout(promise, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const err = new Error(`admin query timed out after ${timeoutMs}ms`);
+      err.code = 'EADMINQUERYTIMEOUT';
+      reject(err);
+    }, timeoutMs);
+    timer.unref?.();
+  });
+  promise.catch(() => { /* handled by the race winner */ });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+function isRetriableAdminQueryError(err) {
+  const code = err?.code;
+  if (['EADMINQUERYTIMEOUT', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ConnectionClosed'].includes(code)) return true;
+  const message = err?.message || String(err);
+  return /connection (?:closed|terminated|reset)|socket closed|timeout|CONNECTION_ENDED|CONNECTION_DESTROYED/i.test(message);
+}
+
 /**
  * Strings shaped like a JSON array or object are unwrapped so Bun.SQL's
  * automatic JSONB serialiser sees the JS value (not a quoted JSON string).

package/src/cluster.js

@@ -256,6 +256,7 @@ class ClusterRouter extends EventEmitter {
     if (code === SSL_REQUEST_CODE || code === GSSAPI_REQUEST_CODE) {
       socket.write(Buffer.from('N'));
       state.buffer = buffer.length > messageLength ? buffer.subarray(messageLength) : null;
+      if (state.buffer) await this.processStartupMessage(socket, state);
       return;
     }
 

package/src/control-db.js

@@ -35,6 +35,13 @@ const REAPABLE_QUERY = `
   ORDER BY last_connection_at ASC
 `;
 
+function query(client, text, params = [], opts = {}) {
+  if (client.supportsQueryOptions && opts && Object.keys(opts).length > 0) {
+    return client.query(text, params, opts);
+  }
+  return client.query(text, params);
+}
+
 /**
  * Create the `pgserve_meta` table if it does not already exist.
  * Safe to call repeatedly — used at daemon boot and in tests.
@@ -88,12 +95,13 @@ export async function recordDbCreated(client, {
   packageRealpath = null,
   livenessPid = null,
   persist = false,
-}) {
+}, opts = {}) {
   if (!databaseName) throw new Error('recordDbCreated: databaseName required');
   if (!fingerprint) throw new Error('recordDbCreated: fingerprint required');
   if (typeof peerUid !== 'number') throw new Error('recordDbCreated: peerUid must be number');
 
-  await client.query(
+  await query(
+    client,
     `
     INSERT INTO pgserve_meta
       (database_name, fingerprint, peer_uid, package_realpath, liveness_pid, persist)
@@ -107,6 +115,7 @@ export async function recordDbCreated(client, {
       last_connection_at = now()
     `,
     [databaseName, fingerprint, peerUid, packageRealpath, livenessPid, persist],
+    opts,
   );
 }
 
@@ -117,9 +126,10 @@ export async function recordDbCreated(client, {
  * @param {{query: Function}} client
  * @param {{databaseName: string, livenessPid?: number|null}} args
  */
-export async function touchLastConnection(client, { databaseName, livenessPid = null }) {
+export async function touchLastConnection(client, { databaseName, livenessPid = null }, opts = {}) {
   if (!databaseName) throw new Error('touchLastConnection: databaseName required');
-  await client.query(
+  await query(
+    client,
     `
     UPDATE pgserve_meta
     SET last_connection_at = now(),
@@ -127,6 +137,7 @@ export async function touchLastConnection(client, { databaseName, livenessPid =
     WHERE database_name = $1
     `,
     [databaseName, livenessPid],
+    opts,
   );
 }
 
@@ -137,11 +148,13 @@ export async function touchLastConnection(client, { databaseName, livenessPid =
  * @param {string} databaseName
  * @param {boolean} value
  */
-export async function markPersist(client, databaseName, value) {
+export async function markPersist(client, databaseName, value, opts = {}) {
   if (!databaseName) throw new Error('markPersist: databaseName required');
-  await client.query(
+  await query(
+    client,
     `UPDATE pgserve_meta SET persist = $2 WHERE database_name = $1`,
     [databaseName, !!value],
+    opts,
   );
 }
 
@@ -203,12 +216,14 @@ export async function deleteMetaRow(client, databaseName) {
  * @param {string} fingerprint — 12 hex chars
  * @returns {Promise<{databaseName: string, fingerprint: string, peerUid: number, allowedTokens: Array<{id: string, hash: string, issued_at: string}>} | null>}
  */
-export async function findRowByFingerprint(client, fingerprint) {
+export async function findRowByFingerprint(client, fingerprint, opts = {}) {
   if (!fingerprint) throw new Error('findRowByFingerprint: fingerprint required');
-  const r = await client.query(
+  const r = await query(
+    client,
     `SELECT database_name, fingerprint, peer_uid, allowed_tokens
      FROM pgserve_meta WHERE fingerprint = $1 LIMIT 1`,
     [fingerprint],
+    opts,
   );
   if (r.rows.length === 0) return null;
   const row = r.rows[0];
@@ -239,12 +254,12 @@ function parseTokens(raw) {
  * @returns {Promise<{databaseName: string}>}
  * @throws if the fingerprint has no pgserve_meta row
  */
-export async function addAllowedToken(client, { fingerprint, tokenId, tokenHash }) {
+export async function addAllowedToken(client, { fingerprint, tokenId, tokenHash }, opts = {}) {
   if (!fingerprint) throw new Error('addAllowedToken: fingerprint required');
   if (!tokenId) throw new Error('addAllowedToken: tokenId required');
   if (!tokenHash) throw new Error('addAllowedToken: tokenHash required');
 
-  const row = await findRowByFingerprint(client, fingerprint);
+  const row = await findRowByFingerprint(client, fingerprint, opts);
   if (!row) {
     const err = new Error(
       `addAllowedToken: no pgserve_meta row for fingerprint ${fingerprint}; ` +
@@ -259,11 +274,13 @@ export async function addAllowedToken(client, { fingerprint, tokenId, tokenHash
     hash: tokenHash,
     issued_at: new Date().toISOString(),
   };
-  await client.query(
+  await query(
+    client,
     `UPDATE pgserve_meta
      SET allowed_tokens = allowed_tokens || $2::jsonb
      WHERE database_name = $1`,
     [row.databaseName, JSON.stringify([entry])],
+    opts,
   );
   return { databaseName: row.databaseName };
 }
@@ -302,10 +319,10 @@ export async function revokeAllowedToken(client, tokenId) {
  * @param {{fingerprint: string, tokenHash: string}} args
  * @returns {Promise<{tokenId: string, databaseName: string} | null>}
  */
-export async function verifyToken(client, { fingerprint, tokenHash }) {
+export async function verifyToken(client, { fingerprint, tokenHash }, opts = {}) {
   if (!fingerprint) throw new Error('verifyToken: fingerprint required');
   if (!tokenHash) throw new Error('verifyToken: tokenHash required');
-  const row = await findRowByFingerprint(client, fingerprint);
+  const row = await findRowByFingerprint(client, fingerprint, opts);
   if (!row) return null;
   const match = row.allowedTokens.find((t) => timingSafeEqual(t.hash, tokenHash));
   if (!match) return null;

package/src/daemon-control.js

@@ -130,6 +130,7 @@ async function processStartupMessage(socket, state) {
   if (code === SSL_REQUEST_CODE || code === GSSAPI_REQUEST_CODE) {
     socket.write(Buffer.from('N'));
     state.buffer = buffer.length > messageLength ? buffer.subarray(messageLength) : null;
+    if (state.buffer) await processStartupMessage.call(this, socket, state);
     return;
   }
 
@@ -268,10 +269,11 @@ async function resolveTenantDatabase(state, requestedDb) {
   }
 
   const { fingerprint, name, uid, pid, packageRealpath } = fp;
+  const lookupOpts = { timeoutMs: this.adminLookupTimeoutMs };
 
   let row = null;
   try {
-    row = await findRowByFingerprint(this._adminClient, fingerprint);
+    row = await findRowByFingerprint(this._adminClient, fingerprint, lookupOpts);
   } catch (err) {
     this.logger.warn?.(
       { err: err?.message || String(err), fingerprint },
@@ -296,7 +298,7 @@ async function resolveTenantDatabase(state, requestedDb) {
         packageRealpath: packageRealpath || null,
         livenessPid: typeof pid === 'number' && pid > 0 ? pid : null,
         persist: persistRequested,
-      });
+      }, lookupOpts);
       audit(AUDIT_EVENTS.DB_CREATED, {
         database: newName,
         fingerprint,
@@ -319,7 +321,7 @@ async function resolveTenantDatabase(state, requestedDb) {
       await touchLastConnection(this._adminClient, {
         databaseName: row.databaseName,
         livenessPid: typeof pid === 'number' && pid > 0 ? pid : null,
-      });
+      }, lookupOpts);
     } catch (err) {
       this.logger.warn?.(
         { err: err?.message || String(err), database: row.databaseName },
@@ -330,7 +332,7 @@ async function resolveTenantDatabase(state, requestedDb) {
     // flag between connections — the previous run might have started without
     // persist:true and the operator just added it (or vice versa).
     try {
-      await markPersist(this._adminClient, row.databaseName, persistRequested);
+      await markPersist(this._adminClient, row.databaseName, persistRequested, lookupOpts);
     } catch (err) {
       this.logger.warn?.(
         { err: err?.message || String(err), database: row.databaseName },

package/src/daemon-tcp.js

@@ -126,6 +126,7 @@ async function processTcpStartupMessage(socket, state) {
   if (code === SSL_REQUEST_CODE || code === GSSAPI_REQUEST_CODE) {
     socket.write(Buffer.from('N'));
     state.buffer = buffer.length > messageLength ? buffer.subarray(messageLength) : null;
+    if (state.buffer) await processTcpStartupMessage.call(this, socket, state);
     return;
   }
   if (code === CANCEL_REQUEST_CODE) {
@@ -153,7 +154,7 @@ async function processTcpStartupMessage(socket, state) {
       validated = await verifyToken(this._adminClient, {
         fingerprint: auth.fingerprint,
         tokenHash,
-      });
+      }, { timeoutMs: this.adminLookupTimeoutMs });
     }
   } catch (err) {
     this.logger.warn?.({ err: err.message }, 'verifyToken failed');

package/src/daemon.js

@@ -266,6 +266,9 @@ export class PgserveDaemon extends EventEmitter {
     this._stopping = false;
     // Lazy-initialised admin DB client (Group 6 token validation).
     this._adminClient = null;
+    this.adminIdleTimeout = options.adminIdleTimeout ?? 300;
+    this.adminQueryTimeoutMs = options.adminQueryTimeoutMs ?? 0;
+    this.adminLookupTimeoutMs = options.adminLookupTimeoutMs ?? 5000;
     // Group 5: GC sweep handle ({stop, sweep}). Installed once the admin
     // client is up and torn down on stop().
     this._gcHandle = null;
@@ -411,6 +414,8 @@ export class PgserveDaemon extends EventEmitter {
       this._adminClient = await createAdminClient({
         socketDir: this.pgManager.socketDir,
         port: this.pgManager.port,
+        idleTimeout: this.adminIdleTimeout,
+        queryTimeoutMs: this.adminQueryTimeoutMs,
       });
       await ensureMetaSchema(this._adminClient);
       writeAdminDiscovery({

package/src/postgres.js

@@ -709,11 +709,57 @@ export class PostgresManager {
     }
   }
 
+  /**
+   * Detect and remove a stale postmaster.pid that postgres would otherwise
+   * refuse to start against. Stale = the PID written into the file is not
+   * alive on this host. Called at the top of _startPostgres so that crash
+   * / SIGKILL / unclean reboot recovery is automatic.
+   *
+   * Real running backends are NEVER touched — if the PID is alive we leave
+   * the file alone and let postgres surface its normal "lock file already
+   * exists" error so the operator sees the conflict.
+   */
+  async _ensureNoStalePostmasterLock() {
+    const pidFile = path.join(this.databaseDir, 'postmaster.pid');
+    let raw;
+    try {
+      raw = await fs.promises.readFile(pidFile, 'utf-8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    const firstLine = (raw.split('\n')[0] ?? '').trim();
+    const pid = Number.parseInt(firstLine, 10);
+    if (!Number.isInteger(pid) || pid <= 0) {
+      this.logger.warn(
+        { pidFile, firstLine },
+        'postmaster.pid is unparseable; removing as stale'
+      );
+      await fs.promises.unlink(pidFile).catch(() => {});
+      return;
+    }
+    let alive = false;
+    try {
+      process.kill(pid, 0);
+      alive = true;
+    } catch (err) {
+      // EPERM = process exists but we can't signal it — still alive.
+      alive = err.code === 'EPERM';
+    }
+    if (alive) return;
+    this.logger.info(
+      { pidFile, stalePid: pid },
+      'Removing stale postmaster.pid (PID not running) before postgres start'
+    );
+    await fs.promises.unlink(pidFile).catch(() => {});
+  }
+
   /**
    * Start the PostgreSQL server process
    * Uses Bun.spawn() for ~40% faster process startup
    */
   async _startPostgres() {
+    await this._ensureNoStalePostmasterLock();
     return new Promise((resolve, reject) => {
       // Build PostgreSQL arguments
       const pgArgs = [

package/src/router.js

@@ -342,6 +342,7 @@ export class MultiTenantRouter extends EventEmitter {
       socket.write(Buffer.from('N'));
       // Remove this request from buffer, wait for real startup
       state.buffer = buffer.length > messageLength ? buffer.subarray(messageLength) : null;
+      if (state.buffer) await this.processStartupMessage(socket, state);
       return;
     }
 

package/tests/daemon-control.test.js

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import net from 'net';
+import path from 'path';
+
+import {
+  PgserveDaemon,
+  resolveControlSocketPath,
+  resolvePidLockPath,
+} from '../src/daemon.js';
+import { createLogger } from '../src/logger.js';
+
+const SSL_REQUEST_CODE = 80877103;
+const PROTOCOL_VERSION_3 = 196608;
+
+function silentLogger() {
+  return createLogger({ level: process.env.PGSERVE_TEST_LOG || 'warn' });
+}
+
+function makeIsolated(tag) {
+  const dir = path.join('/tmp', `pgs-${tag}-${process.pid}-${Date.now()}`);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function freeTcpPort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+function sslRequest() {
+  const buf = Buffer.alloc(8);
+  buf.writeUInt32BE(8, 0);
+  buf.writeUInt32BE(SSL_REQUEST_CODE, 4);
+  return buf;
+}
+
+function startupMessage({ user = 'postgres', database = 'postgres' } = {}) {
+  const params = Buffer.from(`user\0${user}\0database\0${database}\0client_encoding\0UTF8\0\0`);
+  const buf = Buffer.alloc(8 + params.length);
+  buf.writeUInt32BE(buf.length, 0);
+  buf.writeUInt32BE(PROTOCOL_VERSION_3, 4);
+  params.copy(buf, 8);
+  return buf;
+}
+
+function passwordMessage(password = 'postgres') {
+  const body = Buffer.from(`${password}\0`);
+  const buf = Buffer.alloc(1 + 4 + body.length);
+  buf.write('p', 0);
+  buf.writeUInt32BE(4 + body.length, 1);
+  body.copy(buf, 5);
+  return buf;
+}
+
+async function connectWithCoalescedStartup(socketPath) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = Buffer.alloc(0);
+    let sawSslReject = false;
+    let sawAuthOk = false;
+
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error('timed out waiting for ReadyForQuery after coalesced startup'));
+    }, 5000);
+    timer.unref();
+
+    const done = (err, result) => {
+      clearTimeout(timer);
+      socket.destroy();
+      if (err) reject(err);
+      else resolve(result);
+    };
+
+    const pump = () => {
+      if (!sawSslReject) {
+        if (buffer.length < 1) return;
+        if (buffer[0] !== 78) {
+          done(new Error(`expected SSL reject byte N, got ${buffer[0]}`));
+          return;
+        }
+        sawSslReject = true;
+        buffer = buffer.subarray(1);
+      }
+
+      while (buffer.length >= 5) {
+        const type = String.fromCharCode(buffer[0]);
+        const length = buffer.readUInt32BE(1);
+        if (buffer.length < 1 + length) return;
+
+        const payload = buffer.subarray(5, 1 + length);
+        buffer = buffer.subarray(1 + length);
+
+        if (type === 'R') {
+          const authCode = payload.readUInt32BE(0);
+          if (authCode === 3) socket.write(passwordMessage());
+          if (authCode === 0) sawAuthOk = true;
+        } else if (type === 'E') {
+          done(new Error(`postgres error response: ${payload.toString('utf8')}`));
+          return;
+        } else if (type === 'Z') {
+          done(null, { sawSslReject, sawAuthOk });
+          return;
+        }
+      }
+    };
+
+    socket.on('connect', () => {
+      socket.write(Buffer.concat([sslRequest(), startupMessage()]));
+    });
+    socket.on('data', (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      pump();
+    });
+    socket.on('error', done);
+  });
+}
+
+describe('daemon Unix control protocol', () => {
+  test('processes startup already buffered behind SSLRequest', async () => {
+    const dir = makeIsolated('coalesced');
+    const daemon = new PgserveDaemon({
+      controlSocketDir: dir,
+      controlSocketPath: resolveControlSocketPath(dir),
+      pidLockPath: resolvePidLockPath(dir),
+      pgPort: await freeTcpPort(),
+      logger: silentLogger(),
+    });
+
+    await daemon.start();
+    try {
+      const result = await connectWithCoalescedStartup(resolveControlSocketPath(dir));
+      expect(result).toEqual({ sawSslReject: true, sawAuthOk: true });
+    } finally {
+      await daemon.stop();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('processes startup after the admin client idles out', async () => {
+    const dir = makeIsolated('admin-idle');
+    const daemon = new PgserveDaemon({
+      controlSocketDir: dir,
+      controlSocketPath: resolveControlSocketPath(dir),
+      pidLockPath: resolvePidLockPath(dir),
+      pgPort: await freeTcpPort(),
+      adminIdleTimeout: 1,
+      adminLookupTimeoutMs: 1000,
+      logger: silentLogger(),
+    });
+
+    await daemon.start();
+    try {
+      await connectWithCoalescedStartup(resolveControlSocketPath(dir));
+      await Bun.sleep(1500);
+      const result = await connectWithCoalescedStartup(resolveControlSocketPath(dir));
+      expect(result).toEqual({ sawSslReject: true, sawAuthOk: true });
+    } finally {
+      await daemon.stop();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/tests/stale-postmaster-pid.test.js

@@ -0,0 +1,85 @@
+/**
+ * Stale postmaster.pid cleanup
+ *
+ * Verifies that PostgresManager._ensureNoStalePostmasterLock removes
+ * a postmaster.pid file whose recorded PID is no longer alive, and
+ * leaves alone a postmaster.pid whose recorded PID is alive.
+ *
+ * Regression coverage: postgres refuses to start when postmaster.pid
+ * exists, even if the writer crashed. After unclean shutdowns this
+ * required manual `rm` to recover.
+ */
+
+import { PostgresManager } from '../src/postgres.js';
+import { test, expect } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+function makeMgr(dataDir) {
+  const mgr = new PostgresManager({ dataDir });
+  mgr.databaseDir = dataDir;
+  mgr.logger = {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  };
+  return mgr;
+}
+
+function makePidFile(dir, contents) {
+  fs.mkdirSync(dir, { recursive: true });
+  const pidFile = path.join(dir, 'postmaster.pid');
+  fs.writeFileSync(pidFile, contents, 'utf-8');
+  return pidFile;
+}
+
+test('removes postmaster.pid when recorded PID is dead', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-stale-'));
+  try {
+    // PID 999999999 will not exist on any sane system
+    const pidFile = makePidFile(dir, '999999999\n/some/data\n123\n');
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('keeps postmaster.pid when recorded PID is the current (alive) process', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-alive-'));
+  try {
+    const pidFile = makePidFile(dir, `${process.pid}\n/some/data\n123\n`);
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('removes postmaster.pid when first line is unparseable', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-garbage-'));
+  try {
+    const pidFile = makePidFile(dir, 'garbage\nnot-a-pid\n');
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('no-ops when postmaster.pid does not exist', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-missing-'));
+  try {
+    const mgr = makeMgr(dir);
+    // Should resolve without throwing
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(path.join(dir, 'postmaster.pid'))).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});