pgserve 1.1.9 → 1.2.0

package/SECURITY.md

@@ -0,0 +1,109 @@
+# Security Policy
+
+`pgserve` is maintained by [Automagik](https://automagik.dev). We take the security of this package seriously and appreciate responsible disclosure from the community.
+
+---
+
+## Reporting a Vulnerability
+
+**Please do not open public issues for security reports.**
+
+Send private reports to one of the following channels:
+
+| Channel | Address | Best for |
+|---------|---------|----------|
+| Security email | `privacidade@namastex.ai` | Anything security-related, including coordinated disclosure |
+| DPO (privacy + security officer) | `dpo@khal.ai` | Privacy, LGPD, data protection concerns |
+| Private GitHub advisory | [Report via GitHub](https://github.com/namastexlabs/pgserve/security/advisories/new) | Preferred for CVE assignment and coordinated release |
+
+**PGP** available on request.
+
+### Response SLA
+
+- Acknowledgement: **within 2 business hours** (UTC-3).
+- Initial triage and severity assessment: **within 24 hours**.
+- Fix or mitigation plan: **within 7 days** for critical/high severity.
+- Public disclosure: coordinated with reporter, typically within 30 days of fix.
+
+We will credit reporters publicly (with their permission) in the released advisory.
+
+---
+
+## Supported Versions
+
+| Version line | Status |
+|--------------|--------|
+| `1.1.10` and later clean releases | ✅ Supported — current |
+| `1.1.11` – `1.1.14` | ❌ **COMPROMISED — do not use** |
+| `1.1.0` – `1.1.9` | ⚠️ Legacy — security patches only |
+| `1.0.x` and earlier | ❌ End of life |
+
+Always install from the current stable line. Pin explicit versions in your `package.json` and avoid `latest` for supply-chain sensitive packages.
+
+---
+
+## Past Incidents
+
+### 2026-04 — CanisterWorm supply-chain compromise
+
+Between 2026-04-21 (~22:14 UTC) and 2026-04-22 (~14:00 UTC), versions `1.1.11`, `1.1.12`, `1.1.13`, and `1.1.14` were published to npm by a threat actor after a developer GitHub OAuth token was exfiltrated. The malicious versions contained a `TeamPCP` payload in `scripts/check-env.js` that executed via `postinstall` to harvest local credentials.
+
+- **Exposure window:** ~16 hours
+- **Detection-to-containment:** under 20 hours
+- **Current status:** malicious versions `npm unpublish`-ed and no longer installable
+
+**If you installed versions `1.1.11` – `1.1.14` between April 21–22, 2026, assume your machine is compromised.** Follow the remediation guide linked below.
+
+**Resources:**
+- 📖 [Full incident response manual](https://github.com/namastexlabs/genie-dpo/blob/main/knowledge/canisterworm-incident-response.md)
+- 🌐 [Public advisory (English)](https://automagik.dev/security)
+- 🌐 [Aviso público (Português)](https://automagik.dev/seguranca)
+- 🛡️ [GitHub Security Advisories](https://github.com/namastexlabs/pgserve/security/advisories) for this repository
+
+A full public post-mortem will be published within 30 days of containment.
+
+---
+
+## Acknowledgments
+
+We thank the researchers and organizations that identified and tracked this incident:
+
+- [**Socket Research Team**](https://socket.dev/blog/namastex-npm-packages-compromised-canisterworm) — primary discovery and continued tracking at [socket.dev/supply-chain-attacks/canistersprawl](https://socket.dev/supply-chain-attacks/canistersprawl).
+- **Endor Labs**, **Kodem Security**, **BleepingComputer**, **The Register**, **CSO Online**, **GBHackers**, **Cybersecurity News** — for coverage, analysis, and technical breakdowns that helped defenders respond quickly.
+
+We also thank the Automagik team that ran the end-to-end response during the incident window, and the broader open-source community whose scrutiny, tools, and unfiltered feedback keep this ecosystem healthy. We will keep earning it.
+
+---
+
+## Our Commitments
+
+Effective 2026-04-23, all `pgserve` releases are governed by:
+
+- **Provenance attestation** — every publication is signed with `npm --provenance` and verifiable via Sigstore.
+- **OIDC trusted publishing** — migrating to GitHub Actions OIDC publish, eliminating long-lived npm tokens. (in progress)
+- **Mandatory 2FA** on every maintainer account with publish rights.
+- **Environment protection** — production publishes require manual approval from a second maintainer.
+- **Quarterly token audit** — scope and permission review.
+- **External pentest** — scheduled ahead of the original roadmap.
+
+---
+
+## Hardening Recommendations for Consumers
+
+- Pin explicit versions, not `latest`: `"pgserve": "1.1.10"`.
+- Use `npm ci` in CI. It enforces lockfile-based installs by default.
+- Evaluate `--ignore-scripts` per-package for untrusted dependencies. The current `pgserve` release does not require any lifecycle script to function.
+- Verify package provenance: `npm view pgserve --json | jq '.dist.attestations'`.
+- Monitor advisories: subscribe to GitHub security alerts for this repository.
+
+---
+
+## Contact
+
+- **Security & incidents:** `privacidade@namastex.ai`
+- **Data Protection Officer (DPO):** Cezar Vasconcelos — `dpo@khal.ai`
+- **Security disclosure page:** [automagik.dev/security](https://automagik.dev/security)
+
+Namastex Labs Serviços em Tecnologia Ltda · CNPJ 46.156.854/0001-62
+
+*Last updated: 2026-04-23 · v1.0*

package/bin/pgserve-wrapper.cjs

@@ -53,8 +53,113 @@ if (!bunPath) {
   process.exit(1);
 }
 
+// Pre-flight health check: verify bun can actually execute.
+//
+// When pgserve is installed via `bun install` (as a global or transitive dep),
+// the nested `bun` npm package's postinstall can be skipped, leaving
+// `@oven/bun-<platform>/bin/bun` empty. The bun stub at `node_modules/bun/bin/bun`
+// then exits instantly with:
+//   Error: Bun's postinstall script was not run.
+//
+// pglite-server.js's TCP readiness poll can't distinguish this from a slow
+// startup, so users see a confusing 30s timeout. Detect the specific error
+// here, attempt the documented self-heal once (`node install.js`), and retry.
+// If self-heal also fails, surface the real error instead of hanging later.
+ensureBunHealthy(bunPath);
+
 const scriptPath = path.join(__dirname, 'pglite-server.js');
 
+/**
+ * Verify the selected bun binary can execute. If it fails with the known
+ * "postinstall script was not run" signature, attempt a one-shot repair via
+ * the bun npm package's install.js. Throws (with a useful message) rather
+ * than letting pglite-server.js hang on the TCP readiness poll for 30s.
+ */
+function ensureBunHealthy(bunExe) {
+  const probe = probeBun(bunExe);
+  if (probe.ok) return;
+
+  // Only attempt self-heal for the specific postinstall-not-run failure.
+  // Any other failure (corrupt binary, unsupported glibc, etc.) is surfaced
+  // as-is rather than silently papered over.
+  if (!isPostinstallMissingError(probe.output)) {
+    console.error('Error: bun runtime at', bunExe, 'failed to execute:');
+    console.error(probe.output || '(no output)');
+    process.exit(1);
+  }
+
+  const installJs = findBunInstallJs(bunExe);
+  if (!installJs) {
+    console.error('Error: bun runtime at', bunExe, 'is missing its platform binary,');
+    console.error('and the recovery script (node_modules/bun/install.js) could not be located.');
+    console.error('');
+    console.error('Try reinstalling pgserve, or run the fix manually:');
+    console.error('  cd <node_modules>/bun && node install.js');
+    process.exit(1);
+  }
+
+  console.error('[pgserve] bun runtime missing platform binary; attempting self-heal...');
+  try {
+    execSync(`node ${JSON.stringify(installJs)}`, { stdio: 'inherit' });
+  } catch {
+    // fall through to second probe
+  }
+
+  const second = probeBun(bunExe);
+  if (second.ok) {
+    console.error('[pgserve] bun runtime recovered.');
+    return;
+  }
+
+  console.error('Error: bun runtime still broken after self-heal attempt.');
+  console.error(second.output || '(no output)');
+  console.error('');
+  console.error('Manual fix:');
+  console.error(`  cd ${path.dirname(path.dirname(installJs))}/bun && node install.js`);
+  console.error('');
+  console.error('Upstream bug: https://github.com/namastexlabs/pgserve/issues/22');
+  process.exit(1);
+}
+
+function probeBun(bunExe) {
+  try {
+    const out = execSync(`${JSON.stringify(bunExe)} --version`, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 10000,
+      encoding: 'utf8'
+    });
+    return { ok: true, output: out };
+  } catch (err) {
+    const output = [err.stderr, err.stdout, err.message]
+      .filter(Boolean).map(String).join('\n');
+    return { ok: false, output };
+  }
+}
+
+function isPostinstallMissingError(output) {
+  return typeof output === 'string' &&
+    /Bun's postinstall script was not run/i.test(output);
+}
+
+function findBunInstallJs(bunExe) {
+  // Walk up from the bun binary toward a `bun` package dir containing install.js.
+  // Matches the wrapper's own location list - bun is always nested under a
+  // `bun` package directory (or its `bin/` subdir).
+  let cursor = path.dirname(path.resolve(bunExe));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(cursor, 'install.js');
+    if (fs.existsSync(candidate) && fs.existsSync(path.join(cursor, 'package.json'))) {
+      return candidate;
+    }
+    const nested = path.join(cursor, 'bun', 'install.js');
+    if (fs.existsSync(nested)) return nested;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
 // Platform-specific spawning strategy:
 // - Windows: Use pipes for explicit handle control (prevents EBUSY errors)
 // - Unix: Use inherit for simplicity (works fine)

package/knip.json

@@ -3,7 +3,7 @@
   "entry": ["src/index.js", "bin/pglite-server.js", "bin/pgserve-wrapper.cjs"],
   "project": ["src/**/*.js", "bin/**/*.js", "bin/**/*.cjs"],
   "ignore": ["tests/**", "helpers/**", "scripts/**"],
-  "ignoreBinaries": ["scripts/test-npx.sh", "make"],
+  "ignoreBinaries": ["scripts/test-npx.sh", "scripts/test-bun-self-heal.sh", "make"],
   "ignoreDependencies": ["bun"],
   "ignoreExportsUsedInFile": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -19,7 +19,8 @@
     "lint:fix": "eslint src/ bin/ --fix",
     "deadcode": "knip",
     "test:npx": "scripts/test-npx.sh",
-    "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx",
+    "test:bun-self-heal": "scripts/test-bun-self-heal.sh",
+    "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx && npm run test:bun-self-heal",
     "prepare": "husky"
   },
   "keywords": [

package/scripts/test-bun-self-heal.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Regression test for https://github.com/namastexlabs/pgserve/issues/22
+#
+# When pgserve is installed via `bun install`, the nested `bun` npm package's
+# postinstall can be skipped, leaving @oven/bun-<platform>/bin/bun empty.
+# The bun stub then refuses to run with "Bun's postinstall script was not run".
+# pgserve-wrapper.cjs must detect this and self-heal via `node install.js`.
+#
+# This test stages a synthetic broken install tree, runs the wrapper, and
+# asserts that it recovers and spawns pglite-server.
+
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+WRAPPER="$REPO_ROOT/bin/pgserve-wrapper.cjs"
+
+if [ ! -f "$WRAPPER" ]; then
+  echo "✗ wrapper not found: $WRAPPER"
+  exit 1
+fi
+
+# Use a real bun binary as the "recovered" payload so the healthy-path
+# assertion is meaningful. Falls back to any bun on PATH.
+REAL_BUN="${BUN_BIN:-$(command -v bun || true)}"
+if [ -z "$REAL_BUN" ] || [ ! -x "$REAL_BUN" ]; then
+  echo "✗ bun runtime not found on PATH (set BUN_BIN to override)"
+  exit 1
+fi
+
+FIXTURE=$(mktemp -d)
+trap "rm -rf $FIXTURE" EXIT
+
+mkdir -p "$FIXTURE/node_modules/bun/bin"
+mkdir -p "$FIXTURE/node_modules/@oven/bun-linux-x64/bin"   # empty, simulating the bug
+mkdir -p "$FIXTURE/node_modules/.bin"
+mkdir -p "$FIXTURE/node_modules/pgserve/bin"
+
+cp "$WRAPPER" "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs"
+
+# Stub pglite-server so we can detect a successful spawn without needing
+# postgres binaries in the fixture.
+cat > "$FIXTURE/node_modules/pgserve/bin/pglite-server.js" <<'EOF'
+console.log("pglite-server-spawned");
+process.exit(0);
+EOF
+
+# Fake bun install.js: copies the real bun into the expected @oven location,
+# mirroring what the real postinstall does.
+cat > "$FIXTURE/node_modules/bun/install.js" <<EOF
+const fs = require('fs');
+const path = require('path');
+const dst = path.resolve(__dirname, '..', '@oven', 'bun-linux-x64', 'bin', 'bun');
+fs.mkdirSync(path.dirname(dst), { recursive: true });
+fs.copyFileSync('$REAL_BUN', dst);
+fs.chmodSync(dst, 0o755);
+console.log('[test] install.js populated', dst);
+EOF
+echo '{"name":"bun","version":"1.3.12"}' > "$FIXTURE/node_modules/bun/package.json"
+
+# Broken bun stub: prints the postinstall error unless the @oven binary exists.
+cat > "$FIXTURE/node_modules/bun/bin/bun" <<'EOF'
+#!/bin/sh
+SELF=$(readlink -f "$0")
+TARGET="$(dirname "$SELF")/../../@oven/bun-linux-x64/bin/bun"
+if [ ! -x "$TARGET" ]; then
+  echo "Error: Bun's postinstall script was not run." >&2
+  echo "" >&2
+  echo "To fix this, run the postinstall script manually:" >&2
+  echo "  cd node_modules/bun && node install.js" >&2
+  exit 1
+fi
+exec "$TARGET" "$@"
+EOF
+chmod +x "$FIXTURE/node_modules/bun/bin/bun"
+
+ln -s ../bun/bin/bun "$FIXTURE/node_modules/.bin/bun"
+
+echo "=== Testing self-heal on broken install ==="
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1)
+EXIT=$?
+
+if [ $EXIT -ne 0 ]; then
+  echo "✗ wrapper exited non-zero: $EXIT"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "attempting self-heal"; then
+  echo "✗ wrapper did not attempt self-heal"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "bun runtime recovered"; then
+  echo "✗ wrapper did not report recovery"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
+  echo "✗ pglite-server was not spawned after self-heal"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ self-heal path: wrapper detected, repaired, and spawned pglite-server"
+
+echo ""
+echo "=== Testing healthy path is unaffected ==="
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1)
+EXIT=$?
+
+if [ $EXIT -ne 0 ]; then
+  echo "✗ wrapper exited non-zero on healthy path: $EXIT"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if echo "$OUTPUT" | grep -q "self-heal\|recovered"; then
+  echo "✗ wrapper logged self-heal messages on a healthy install"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
+  echo "✗ pglite-server was not spawned on healthy path"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ healthy path: wrapper was silent and spawned pglite-server directly"
+
+echo ""
+echo "=== Testing non-postinstall errors surface raw ==="
+# Replace stub with one that emits an unrelated error.
+cat > "$FIXTURE/node_modules/bun/bin/bun" <<'EOF'
+#!/bin/sh
+echo "Error: GLIBC_2.99 not found (libc mismatch)" >&2
+exit 127
+EOF
+chmod +x "$FIXTURE/node_modules/bun/bin/bun"
+
+# Clear the @oven healed binary so the stub is what runs.
+rm -f "$FIXTURE/node_modules/@oven/bun-linux-x64/bin/bun"
+
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1 || true)
+
+if echo "$OUTPUT" | grep -q "self-heal"; then
+  echo "✗ wrapper tried self-heal for a non-postinstall error"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "GLIBC_2.99"; then
+  echo "✗ wrapper did not surface the real error message"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ unrelated-error path: wrapper surfaced the raw error without self-heal"
+
+echo ""
+echo "=== bun self-heal test PASSED ==="

package/src/postgres.js

@@ -444,8 +444,20 @@ export class PostgresManager {
 
   /**
    * Start the embedded PostgreSQL instance
+   *
+   * Re-entry guard: if a previous start() left `this.process` or stale state
+   * behind, refuse silently rather than leaking another socketDir/databaseDir.
+   * Callers must call stop() first if they want to restart.
    */
   async start() {
+    if (this.process) {
+      this.logger?.warn(
+        { pid: this.process.pid, socketDir: this.socketDir },
+        'PostgresManager.start() called while already started — returning existing instance'
+      );
+      return this;
+    }
+
     // Get binary paths (may extract bundled binaries on first run)
     this.binaries = await getBinaryPaths();
 
@@ -773,12 +785,33 @@ export class PostgresManager {
       readStream(this.process.stdout);
 
       // Handle process exit
+      //
+      // When the postgres subprocess exits (normal stop OR crash), we must
+      // null `this.process` AND `this.socketDir`/`this.databaseDir` so that
+      // subsequent `getSocketPath()` calls do not return a path to a directory
+      // that no longer exists. This is the issue #24 root cause: the router
+      // was receiving stale socketPaths pointing to cleaned-up tmp dirs.
+      //
+      // NOTE: we do NOT null socketDir here if `stop()` is in flight, because
+      // stop() already handles cleanup+null. We only need to self-heal when
+      // the exit is unexpected (external kill, crash, OOM).
       this.process.exited.then((code) => {
         processExited = true;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
         this.process = null;
+        // On unexpected exit (not via stop()), reset cached paths so that
+        // getSocketPath() returns null and callers can fall back to TCP
+        // or force a fresh start().
+        if (!this._stopping) {
+          this.socketDir = null;
+          this.databaseDir = null;
+          this.logger?.warn(
+            { code },
+            'PostgreSQL subprocess exited unexpectedly — socketDir/databaseDir reset'
+          );
+        }
       });
 
       // Method 1: TCP connection polling (preferred, works on Linux/macOS)
@@ -1294,8 +1327,19 @@ export class PostgresManager {
 
   /**
    * Stop the PostgreSQL instance
+   *
+   * Cleanup order matters: we null `this.socketDir`/`this.databaseDir` AFTER
+   * the rmSync so any concurrent `getSocketPath()` call either sees the old
+   * path (while it still exists) or null (after cleanup) — never a path
+   * pointing to a deleted directory.
+   *
+   * The `_stopping` flag tells the process.exited handler to NOT redundantly
+   * null the paths (avoids a race where start() called immediately after
+   * stop() sees nulls that stop() was about to set anyway).
    */
   async stop() {
+    this._stopping = true;
+
     // Close admin pool first (Bun.sql)
     if (this.adminPool) {
       await this.adminPool.close();
@@ -1340,6 +1384,16 @@ export class PostgresManager {
         }
       }
     }
+
+    // Reset cached paths UNCONDITIONALLY after cleanup so getSocketPath()
+    // returns null for anyone still holding a reference to this instance.
+    // This is the core fix for issue #24.
+    this.socketDir = null;
+    if (!this.persistent) {
+      this.databaseDir = null;
+    }
+    this.createdDatabases.clear();
+    this._stopping = false;
   }
 
   /**

package/src/router.js

@@ -14,6 +14,7 @@
  * PERFORMANCE: Uses Bun.listen() and Bun.connect() for 2-3x throughput improvement
  */
 
+import fs from 'fs';
 import { PostgresManager } from './postgres.js';
 import { SyncManager } from './sync.js';
 import { RestoreManager } from './restore.js';
@@ -28,6 +29,14 @@ const SSL_REQUEST_CODE = 80877103;
 const GSSAPI_REQUEST_CODE = 80877104;
 const CANCEL_REQUEST_CODE = 80877102;
 
+// Maximum size for the pre-handshake startup buffer. A legitimate PG
+// startup message is at most a few hundred bytes; anything approaching
+// 1 MiB is a runaway client or an attempted buffer-growth DoS. Bound
+// this to stop the proxy from accumulating gigabytes of orphaned data
+// when a client sends garbage and the handshake never completes.
+// (Issue #18 root cause #2 — unbounded growth at state.buffer.)
+const MAX_STARTUP_BUFFER_SIZE = 1024 * 1024; // 1 MiB
+
 /**
  * Attempt to write a pending buffer to a target socket.
  * Returns remaining unwritten bytes, or null if fully flushed.
@@ -231,6 +240,12 @@ export class MultiTenantRouter extends EventEmitter {
       pgSocket: null,
       dbName: null,
       handshakeComplete: false,
+      // startupInProgress serializes processStartupMessage() against async
+      // reentrancy — without it, every data event fired while the previous
+      // processStartupMessage() is still awaiting createDatabase() would
+      // launch another async task on the same state, racing to overwrite
+      // state.pgSocket and leaking the losers (issue #18 root cause #1).
+      startupInProgress: false,
       pendingToPg: null,
       pendingToClient: null
     });
@@ -249,9 +264,13 @@ export class MultiTenantRouter extends EventEmitter {
 
     // If handshake complete, forward to PostgreSQL
     if (state.handshakeComplete && state.pgSocket) {
-      // If there's already pending data, append to it
+      // If there's already pending data, append and re-pause.
+      // (Re-pause is defensive: client should already be paused from the
+      //  earlier partial-write, but kernel-buffered data can still arrive
+      //  before the pause takes effect — issue #18 root cause #3.)
       if (state.pendingToPg) {
         state.pendingToPg = Buffer.concat([state.pendingToPg, data]);
+        socket.pause();
         return;
       }
       const written = state.pgSocket.write(data);
@@ -263,7 +282,20 @@ export class MultiTenantRouter extends EventEmitter {
       return;
     }
 
-    // Buffer data for startup message parsing
+    // Buffer data for startup message parsing.
+    // Bound the pre-handshake buffer so a client that never completes its
+    // startup (or sends garbage) cannot grow state.buffer without limit —
+    // the 74 GiB VmSize in the production deadlock report traces to this
+    // path (issue #18 root cause #2).
+    const incomingSize = state.buffer ? state.buffer.length + data.byteLength : data.byteLength;
+    if (incomingSize > MAX_STARTUP_BUFFER_SIZE) {
+      this.logger.warn(
+        { incomingSize, limit: MAX_STARTUP_BUFFER_SIZE },
+        'Pre-handshake buffer exceeded limit — closing connection'
+      );
+      socket.end();
+      return;
+    }
     if (state.buffer) {
       state.buffer = Buffer.concat([state.buffer, data]);
     } else {
@@ -275,9 +307,17 @@ export class MultiTenantRouter extends EventEmitter {
   }
 
   /**
-   * Process PostgreSQL startup message and establish proxy connection
+   * Process PostgreSQL startup message and establish proxy connection.
+   *
+   * Guarded against async reentrancy: multiple data events arriving while
+   * the first processStartupMessage() is still awaiting createDatabase()
+   * or Bun.connect() must not launch concurrent tasks on the same state —
+   * they would race to assign state.pgSocket, leaking the losing sockets
+   * and double-writing the startup message (issue #18 root cause #1).
    */
   async processStartupMessage(socket, state) {
+    if (state.startupInProgress) return;
+
     const buffer = state.buffer;
     if (!buffer || buffer.length < 8) return; // Need at least length + protocol
 
@@ -315,6 +355,11 @@ export class MultiTenantRouter extends EventEmitter {
     const dbName = extractDatabaseName(startupMessage);
     state.dbName = dbName;
 
+    // Claim the reentrancy guard BEFORE the first await so subsequent data
+    // events (buffered into state.buffer by handleSocketData) cannot launch
+    // a second async task on the same state.
+    state.startupInProgress = true;
+
     try {
       // Auto-provision database if needed
       if (this.autoProvision) {
@@ -328,9 +373,13 @@ export class MultiTenantRouter extends EventEmitter {
       // Shared handler for pgSocket (used by both unix and TCP paths)
       const pgHandler = {
         data(_pgSocket, pgData) {
-          // Forward PostgreSQL response to client with backpressure
+          // Forward PostgreSQL response to client with backpressure.
+          // Re-pause defensively when pendingToClient already exists —
+          // kernel-buffered PG data can arrive before the earlier pause()
+          // takes effect (issue #18 root cause #3).
           if (state.pendingToClient) {
             state.pendingToClient = Buffer.concat([state.pendingToClient, pgData]);
+            _pgSocket.pause();
             return;
           }
           const written = socket.write(pgData);
@@ -362,9 +411,18 @@ export class MultiTenantRouter extends EventEmitter {
         }
       };
 
-      if (socketPath) {
+      // Safety net for issue #24: if socketPath points to a directory that was
+      // cleaned up (e.g. pgManager was stopped+started, or the PG subprocess
+      // exited unexpectedly and socketDir was reset to null but a stale cached
+      // path is still hanging around), fall back to TCP instead of Bun.connect
+      // hanging on a missing unix socket.
+      const useUnix = socketPath && fs.existsSync(socketPath);
+      if (useUnix) {
         state.pgSocket = await Bun.connect({ unix: socketPath, socket: pgHandler });
       } else {
+        if (socketPath && !useUnix) {
+          this.logger.warn({ socketPath, dbName }, 'Unix socket path stale — falling back to TCP');
+        }
         state.pgSocket = await Bun.connect({ hostname: '127.0.0.1', port: this.pgPort, socket: pgHandler });
       }
 
@@ -373,6 +431,13 @@ export class MultiTenantRouter extends EventEmitter {
       this.logger.error({ dbName, err: error }, 'Connection error');
       socket.end();
       this.emit('connection-error', { error, dbName });
+    } finally {
+      // Release the reentrancy guard whether handshake succeeded or not.
+      // If it succeeded, handshakeComplete is now true and further data
+      // events will bypass processStartupMessage anyway (handleSocketData
+      // takes the handshakeComplete path). If it failed, socket.end()
+      // has been called and the connection is tearing down.
+      state.startupInProgress = false;
     }
   }