pgserve 2.0.1 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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

@@ -251,7 +251,7 @@ export class PgserveDaemon extends EventEmitter {
 
     this.pgManager = options.pgManager || new PostgresManager({
       dataDir: this.baseDir,
-      port: options.pgPort || 5433,
+      port: options.pgPort ?? 0,
       logger: this.logger.child ? this.logger.child({ component: 'postgres' }) : this.logger,
       useRam: this.useRam,
       enablePgvector: options.enablePgvector || false,
@@ -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/fingerprint.js

@@ -6,7 +6,7 @@
  *
  *   1. SO_PEERCRED (Linux) / getpeereid + LOCAL_PEERPID (macOS)
  *      → kernel-attested {pid, uid, gid}
- *   2. /proc/$pid/cwd  → peer's current working directory (Linux only)
+ *   2. peer cwd lookup → /proc/$pid/cwd on Linux, lsof on macOS
  *   3. walk upward to the nearest package.json
  *   4. if found:  fingerprint = sha256(realpath \0 name \0 uid)[:12]   mode='package'
  *      else:      fingerprint = sha256(uid \0 cwd \0 cmdline[1])[:12]  mode='script'
@@ -29,6 +29,7 @@
  */
 
 import crypto from 'crypto';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { audit, AUDIT_EVENTS } from './audit.js';
@@ -175,17 +176,21 @@ function makeDarwinReader(symbols, ptr) {
 }
 
 // ---------------------------------------------------------------------------
-// /proc reads — Linux-only; macOS daemon support is best-effort
+// Peer process metadata reads
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the cwd of a peer process via /proc/$pid/cwd. Linux-only.
- * Returns null if the symlink cannot be read (process gone, EACCES, etc).
+ * Resolve the cwd of a peer process. Linux uses /proc/$pid/cwd; macOS has no
+ * /proc, so it shells out to the platform lsof binary and parses the cwd row.
+ * Returns null if the process disappeared, permissions deny the lookup, or the
+ * host does not expose a cwd for the peer.
  *
  * @param {number} pid
  * @returns {string | null}
  */
 export function readProcCwd(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (process.platform === 'darwin') return readDarwinCwd(pid);
   if (process.platform !== 'linux') return null;
   try {
     return fs.readlinkSync(`/proc/${pid}/cwd`);
@@ -194,6 +199,27 @@ export function readProcCwd(pid) {
   }
 }
 
+function readDarwinCwd(pid) {
+  const lsof = process.env.PGSERVE_LSOF_BIN || '/usr/sbin/lsof';
+  try {
+    const output = execFileSync(lsof, ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+      encoding: 'utf8',
+      timeout: 1000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parseDarwinLsofCwd(output);
+  } catch {
+    return null;
+  }
+}
+
+export function parseDarwinLsofCwd(output) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    if (line.startsWith('n') && line.length > 1) return line.slice(1);
+  }
+  return null;
+}
+
 /**
  * Read the peer's argv via /proc/$pid/cmdline (NUL-separated).
  * argv[0] is the exe; argv[1] is typically the script.

package/src/postgres.js

@@ -406,10 +406,23 @@ export function pgvectorMetaMatches(meta, runtime) {
   return true;
 }
 
+function findAvailableTcpPort() {
+  const server = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      data() {},
+    },
+  });
+  const port = server.port;
+  server.stop(true);
+  return port;
+}
+
 export class PostgresManager {
   constructor(options = {}) {
     this.dataDir = options.dataDir || null; // null = memory mode (temp dir)
-    this.port = options.port || 5433; // Internal PG port (router listens on different port)
+    this.port = options.port ?? 5433; // Internal PG port (router listens on different port)
     this.user = options.user || 'postgres';
     this.password = options.password || 'postgres';
     this.logger = options.logger;
@@ -465,6 +478,10 @@ export class PostgresManager {
     await fs.promises.chmod(this.binaries.initdb, '755');
     await fs.promises.chmod(this.binaries.postgres, '755');
 
+    if (this.port === 0) {
+      this.port = findAvailableTcpPort();
+    }
+
     // Determine data directory
     if (this.persistent) {
       this.databaseDir = this.dataDir;
@@ -568,7 +585,8 @@ export class PostgresManager {
       const initdbCmd = [
         this.binaries.initdb,
         `--pgdata=${this.databaseDir}`,
-        '--auth=password',
+        '--auth-local=trust',
+        '--auth-host=password',
         `--username=${this.user}`,
         `--pwfile=${passwordFile}`,
       ];
@@ -744,11 +762,13 @@ export class PostgresManager {
       // Whichever succeeds first wins
 
       const markReady = (method) => {
-        if (!started) {
-          started = true;
-          this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
-          resolve();
-        }
+        if (started || processExited) return true;
+        const socketPath = this.getSocketPath();
+        if (socketPath && !fs.existsSync(socketPath)) return false;
+        started = true;
+        this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
+        resolve();
+        return true;
       };
 
       // Read stderr - detect port binding in logs (locale-independent: just look for port number)
@@ -873,14 +893,19 @@ export class PostgresManager {
           if (processExited) return;
 
           try {
+            const socketPath = this.getSocketPath();
+            if (socketPath && fs.existsSync(socketPath)) {
+              markReady('unix-socket');
+              return;
+            }
             await tryConnect();
             // On Windows, TCP port opens before PostgreSQL is fully ready for protocol handshakes
             // Add delay to let PostgreSQL complete its startup sequence
             if (isWindows) {
               await Bun.sleep(2000); // 2 second delay for Windows
             }
-            markReady('tcp');
-            return;
+            if (processExited) return;
+            if (markReady('tcp')) return;
           } catch {
             await Bun.sleep(200);
           }

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/fingerprint.test.js

@@ -20,6 +20,8 @@ import {
   initFingerprintFfi,
   getPeerCred,
   findNearestPackageJson,
+  parseDarwinLsofCwd,
+  readProcCwd,
   readPackageName,
   derivePackageFingerprint,
   deriveScriptFingerprint,
@@ -80,6 +82,18 @@ test('getPeerCred reads kernel-attested pid/uid/gid via Unix socket pair', async
   expect(cred.gid).toBe(expectedGid);
 });
 
+test('macOS lsof parser extracts cwd field output', () => {
+  const cwd = path.join(scratch, 'project');
+  const output = `p12345\nn${cwd}\n`;
+  expect(parseDarwinLsofCwd(output)).toBe(cwd);
+  expect(parseDarwinLsofCwd('p12345\n')).toBeNull();
+});
+
+test('readProcCwd resolves the current process cwd on supported platforms', () => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') return;
+  expect(readProcCwd(process.pid)).toBe(process.cwd());
+});
+
 // ---------------------------------------------------------------------------
 // Pure-function tests on derivation surface
 // ---------------------------------------------------------------------------