pgserve 1.1.8 → 1.1.10

package/.genie/AGENTS.md

@@ -5,6 +5,8 @@ description: Global agents (orchestration, QA, analysis, maintenance)
 github_url: https://github.com/namastexlabs/automagik-genie/tree/main/.genie
 ---
 
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 # Base Genie Agents
 
 **Global agents available across all collectives.**

package/.genie/code/AGENTS.md

@@ -11,6 +11,8 @@ forge:
   OPENCODE: {}
 ---
 
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 ## Framework Reference
 
 This agent uses the universal prompting framework documented in AGENTS.md §Prompting Standards Framework:

package/AGENTS.md

@@ -1,3 +1,5 @@
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 # Genie Agent Framework
 
 ## Core Identity

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.8",
+  "version": "1.1.10",
   "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

@@ -385,6 +385,27 @@ function buildCommand(cmd, libDir) {
   return cmd;
 }
 
+/**
+ * Compare a persisted pgvector install metadata record against the currently
+ * detected PG major and postgres binary path. Returns `true` only when the
+ * metadata is a plain object, has the expected shape, and matches the
+ * runtime environment. Used by the pgvector auto-heal path to decide whether
+ * an already-present `vector.so` is safe to reuse or must be replaced.
+ *
+ * Exported for unit tests — keep this pure (no I/O, no `this`).
+ *
+ * @param {unknown} meta - Value parsed from `vector.meta.json`, or null.
+ * @param {{pgMajor: string, postgresPath: string}} runtime - Current env.
+ * @returns {boolean}
+ */
+export function pgvectorMetaMatches(meta, runtime) {
+  if (!meta || typeof meta !== 'object') return false;
+  if (typeof meta.pgMajor !== 'string' || meta.pgMajor !== runtime.pgMajor) return false;
+  // postgresPath is optional in older metadata — only compare when present.
+  if (meta.postgresPath && meta.postgresPath !== runtime.postgresPath) return false;
+  return true;
+}
+
 export class PostgresManager {
   constructor(options = {}) {
     this.dataDir = options.dataDir || null; // null = memory mode (temp dir)
@@ -953,62 +974,172 @@ export class PostgresManager {
       return;
     }
 
+    const paths = this._pgvectorPaths();
+
+    let pgMajor;
+    try {
+      pgMajor = await this._detectPgMajor();
+    } catch (error) {
+      this.logger.warn({ err: error.message }, 'Failed to detect PG major version for pgvector install (non-fatal)');
+      return;
+    }
+
+    // Proactive staleness check: if vector.so and vector.control both exist,
+    // trust them ONLY if the sidecar metadata file matches the current PG
+    // major and the current postgres binary path. Any mismatch — including a
+    // missing metadata file from a pre-auto-heal install — triggers a clean
+    // reinstall. This is what heals existing deployments that were shipped
+    // with the regex bug: on first run after upgrading pgserve, the stale
+    // PG17 .so will be detected (no metadata → mismatch) and replaced.
+    const filesPresent = fs.existsSync(paths.vectorSo) && fs.existsSync(paths.vectorControl);
+    if (filesPresent) {
+      const meta = this._readPgvectorMeta(paths.vectorMeta);
+      if (pgvectorMetaMatches(meta, { pgMajor, postgresPath: this.binaries.postgres })) {
+        return;
+      }
+      this.logger.warn(
+        {
+          detectedPgMajor: pgMajor,
+          metaPgMajor: meta?.pgMajor ?? null,
+          metaPresent: meta !== null,
+          vectorMeta: paths.vectorMeta,
+        },
+        'pgvector install metadata missing or mismatched — auto-healing stale install'
+      );
+      this._removePgvectorFiles(paths);
+    } else {
+      this.logger.info('pgvector extension files not found — downloading prebuilt binary...');
+    }
+
+    try {
+      await this._installPgvectorFromDeb({ pgMajor, ...paths });
+    } catch (error) {
+      this.logger.warn({ err: error.message }, 'Failed to install pgvector extension files (non-fatal)');
+    }
+  }
+
+  /**
+   * Compute the canonical pgvector file paths for this PG install.
+   * Extracted so proactive install, reactive heal, and cleanup all agree.
+   */
+  _pgvectorPaths() {
     const libDir = this.binaries.libDir;
     const binDir = this.binaries.binDir;
     const extDir = path.join(path.dirname(binDir), 'share', 'postgresql', 'extension');
-    const vectorSo = path.join(libDir, 'vector.so');
-    const vectorControl = path.join(extDir, 'vector.control');
+    return {
+      libDir,
+      extDir,
+      vectorSo: path.join(libDir, 'vector.so'),
+      vectorControl: path.join(extDir, 'vector.control'),
+      vectorMeta: path.join(libDir, 'vector.meta.json'),
+    };
+  }
 
-    // Already installed
-    if (fs.existsSync(vectorSo) && fs.existsSync(vectorControl)) return;
+  /**
+   * Parse `postgres --version` output and return the major version string.
+   * Throws on unparseable output so callers can fail loudly instead of
+   * silently downloading the wrong pgvector .deb.
+   */
+  async _detectPgMajor() {
+    // `postgres --version` output is `postgres (PostgreSQL) 18.2`, so the
+    // regex must tolerate the `)` that separates the product name from the
+    // version number. The previous pattern `/PostgreSQL (\d+)/` expected a
+    // digit immediately after `PostgreSQL ` and silently fell back to '17'
+    // on PG 14+, causing the wrong pgvector .deb to be downloaded and a
+    // later "incompatible library version mismatch" at CREATE EXTENSION time.
+    const { execSync } = await import('node:child_process');
+    const pgVersion = execSync(`${this.binaries.postgres} --version`, { encoding: 'utf-8' }).trim();
+    const majorMatch = pgVersion.match(/PostgreSQL\)?\s+(\d+)/);
+    if (!majorMatch) {
+      throw new Error(`Could not detect PostgreSQL major version from: ${JSON.stringify(pgVersion)}`);
+    }
+    this.logger.debug({ pgMajor: majorMatch[1], pgVersion }, 'Detected PostgreSQL major version');
+    return majorMatch[1];
+  }
 
-    this.logger.info('pgvector extension files not found — downloading prebuilt binary...');
+  /**
+   * Read and parse the pgvector install metadata sidecar, if present.
+   * Returns null on missing file or any parse error (caller treats both as
+   * "unknown, needs reinstall").
+   */
+  _readPgvectorMeta(metaPath) {
+    try {
+      if (!fs.existsSync(metaPath)) return null;
+      return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
 
+  /**
+   * Write the pgvector install metadata sidecar. Best-effort — failure to
+   * write metadata should not crash the install; it just means the next
+   * startup will trigger a re-heal (idempotent).
+   */
+  _writePgvectorMeta(metaPath, data) {
     try {
-      // Detect PG major version from the postgres binary.
-      // `postgres --version` output is `postgres (PostgreSQL) 18.2`, so the
-      // regex must tolerate the `)` that separates the product name from the
-      // version number. The previous pattern `/PostgreSQL (\d+)/` expected a
-      // digit immediately after `PostgreSQL ` and silently fell back to '17'
-      // on PG 14+, causing the wrong pgvector .deb to be downloaded and a
-      // later "incompatible library version mismatch" at CREATE EXTENSION time.
-      const { execSync } = await import('node:child_process');
-      const pgVersion = execSync(`${this.binaries.postgres} --version`, { encoding: 'utf-8' }).trim();
-      const majorMatch = pgVersion.match(/PostgreSQL\)?\s+(\d+)/);
-      if (!majorMatch) {
-        throw new Error(
-          `Could not detect PostgreSQL major version from: ${JSON.stringify(pgVersion)}`
-        );
-      }
-      const pgMajor = majorMatch[1];
-      this.logger.info({ pgMajor, pgVersion }, 'Detected PostgreSQL major version for pgvector install');
-
-      // Detect architecture — fail explicitly on unsupported platforms
-      const nodeArch = os.arch();
-      let arch;
-      if (nodeArch === 'x64') arch = 'amd64';
-      else if (nodeArch === 'arm64') arch = 'arm64';
-      else {
-        this.logger.warn({ arch: nodeArch }, 'Unsupported architecture for pgvector auto-install. Supported: x64, arm64');
-        return;
+      fs.writeFileSync(metaPath, JSON.stringify(data, null, 2));
+    } catch (error) {
+      this.logger.warn({ err: error.message, metaPath }, 'Failed to write pgvector metadata sidecar');
+    }
+  }
+
+  /**
+   * Remove all pgvector files (vector.so, vector.meta.json, and any
+   * vector*.sql / vector.control files in the extension dir) so that a
+   * subsequent install starts from a clean slate. Used by the auto-heal
+   * paths — never call this while PG is mid-transaction.
+   */
+  _removePgvectorFiles(paths) {
+    const { libDir, extDir, vectorSo, vectorMeta } = paths;
+    const toRemove = [vectorSo, vectorMeta];
+    if (fs.existsSync(extDir)) {
+      for (const f of fs.readdirSync(extDir)) {
+        if (f.startsWith('vector')) toRemove.push(path.join(extDir, f));
       }
+    }
+    for (const p of toRemove) {
+      try { fs.rmSync(p, { force: true }); } catch { /* ignore */ }
+    }
+    this.logger.info({ libDir, extDir }, 'Removed stale pgvector files');
+  }
 
-      // Download prebuilt pgvector .deb from apt.postgresql.org (HTTPS)
-      // Version 0.8.1-2 — update when new releases ship
-      const debUrl = `https://apt.postgresql.org/pub/repos/apt/pool/main/p/pgvector/postgresql-${pgMajor}-pgvector_0.8.1-2.pgdg%2B1_${arch}.deb`;
-      this.logger.info({ url: debUrl }, 'Downloading pgvector...');
+  /**
+   * Download + extract + install pgvector from apt.postgresql.org for the
+   * given PG major. Writes a metadata sidecar on success so future starts
+   * can detect staleness without re-downloading.
+   */
+  async _installPgvectorFromDeb({ pgMajor, extDir, vectorSo, vectorControl, vectorMeta }) {
+    const { execSync } = await import('node:child_process');
+
+    // Detect architecture — fail explicitly on unsupported platforms
+    const nodeArch = os.arch();
+    let arch;
+    if (nodeArch === 'x64') arch = 'amd64';
+    else if (nodeArch === 'arm64') arch = 'arm64';
+    else {
+      this.logger.warn({ arch: nodeArch }, 'Unsupported architecture for pgvector auto-install. Supported: x64, arm64');
+      return;
+    }
+
+    // Download prebuilt pgvector .deb from apt.postgresql.org (HTTPS)
+    // Version 0.8.1-2 — update when new releases ship
+    const pgvectorVersion = '0.8.1-2';
+    const debUrl = `https://apt.postgresql.org/pub/repos/apt/pool/main/p/pgvector/postgresql-${pgMajor}-pgvector_${pgvectorVersion}.pgdg%2B1_${arch}.deb`;
+    this.logger.info({ url: debUrl, pgMajor }, 'Downloading pgvector...');
 
-      const res = await fetch(debUrl);
-      if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+    const res = await fetch(debUrl);
+    if (!res.ok) throw new Error(`Download failed: ${res.status}`);
 
-      const buffer = Buffer.from(await res.arrayBuffer());
+    const buffer = Buffer.from(await res.arrayBuffer());
 
-      // Extract .deb (it's an ar archive containing data.tar.xz)
-      const tmpDir = path.join(os.tmpdir(), `pgserve-pgvector-${process.pid}-${Date.now()}`);
-      fs.mkdirSync(tmpDir, { recursive: true });
-      const debPath = path.join(tmpDir, 'pgvector.deb');
-      fs.writeFileSync(debPath, buffer);
+    // Extract .deb (it's an ar archive containing data.tar.xz)
+    const tmpDir = path.join(os.tmpdir(), `pgserve-pgvector-${process.pid}-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    const debPath = path.join(tmpDir, 'pgvector.deb');
+    fs.writeFileSync(debPath, buffer);
 
+    try {
       // Use dpkg-deb or ar to extract
       try {
         execSync(`dpkg-deb -x ${debPath} ${tmpDir}/extracted`, { stdio: 'pipe' });
@@ -1018,12 +1149,13 @@ export class PostgresManager {
         execSync(`cd ${tmpDir} && ar x pgvector.deb && tar xf data.tar.* -C ${tmpDir}/extracted 2>/dev/null || tar xf data.tar.xz -C ${tmpDir}/extracted`, { stdio: 'pipe' });
       }
 
-      // Copy .so file
+      // Copy .so file — fail loudly if missing so we don't silently ship broken
       const soSrc = path.join(tmpDir, 'extracted', 'usr', 'lib', 'postgresql', pgMajor, 'lib', 'vector.so');
-      if (fs.existsSync(soSrc)) {
-        fs.copyFileSync(soSrc, vectorSo);
-        this.logger.info({ path: vectorSo }, 'Installed vector.so');
+      if (!fs.existsSync(soSrc)) {
+        throw new Error(`Extracted .deb missing expected vector.so at ${soSrc}`);
       }
+      fs.copyFileSync(soSrc, vectorSo);
+      this.logger.info({ path: vectorSo }, 'Installed vector.so');
 
       // Copy extension SQL + control files
       const extSrc = path.join(tmpDir, 'extracted', 'usr', 'share', 'postgresql', pgMajor, 'extension');
@@ -1049,29 +1181,55 @@ export class PostgresManager {
         this.logger.info('Patched vector.control with absolute module path');
       }
 
-      // Cleanup
+      // Write metadata sidecar so future starts can detect staleness
+      this._writePgvectorMeta(vectorMeta, {
+        pgMajor,
+        pgvectorVersion,
+        sourceUrl: debUrl,
+        postgresPath: this.binaries.postgres,
+        installedAt: new Date().toISOString(),
+      });
+
+      this.logger.info({ pgMajor, pgvectorVersion }, 'pgvector extension installed successfully');
+    } finally {
+      // Always clean up tmpdir, even on failure
       fs.rmSync(tmpDir, { recursive: true, force: true });
-      this.logger.info('pgvector extension installed successfully');
-    } catch (error) {
-      this.logger.warn({ err: error.message }, 'Failed to install pgvector extension files (non-fatal)');
     }
   }
 
+  /**
+   * Tear down an existing pgvector install and reinstall from scratch.
+   * Called reactively when CREATE EXTENSION surfaces an ABI mismatch —
+   * this is the last-resort heal for deployments that somehow bypassed
+   * the proactive staleness check (e.g. metadata file got corrupted, or
+   * the files were placed by an older pgserve that didn't write metadata).
+   */
+  async _healStalePgvector() {
+    if (!this.binaries?.libDir || os.platform() !== 'linux') return;
+    const paths = this._pgvectorPaths();
+    this._removePgvectorFiles(paths);
+    // _doEnsurePgvectorFiles is serialized via _pgvectorInstallPromise;
+    // this call goes through the mutex wrapper to stay race-safe.
+    await this.ensurePgvectorFiles();
+  }
+
   /**
    * Enable pgvector extension on a database
-   * Creates a temporary connection to the specific database to run CREATE EXTENSION
+   * Creates a temporary connection to the specific database to run CREATE EXTENSION.
+   * If the CREATE hits an ABI mismatch (stale vector.so from an older pgserve
+   * install that shipped the wrong PG major), auto-heal the install and retry
+   * once. This is the reactive safety net for deployments that already have a
+   * broken vector.so on disk when this version of pgserve first starts.
    * @param {string} dbName - Database name to enable pgvector on
    */
   async enablePgvectorExtension(dbName) {
-    // Ensure extension files are installed first
+    // Ensure extension files are installed first (proactive path)
     await this.ensurePgvectorFiles();
 
     const { SQL } = await import('bun');
-    let dbPool = null;
 
-    try {
-      // Create temporary connection to the specific database
-      dbPool = new SQL({
+    const tryCreateExtension = async () => {
+      const dbPool = new SQL({
         hostname: '127.0.0.1',
         port: this.port,
         database: dbName,
@@ -1081,17 +1239,47 @@ export class PostgresManager {
         idleTimeout: 5,
         connectionTimeout: 5,
       });
+      try {
+        await dbPool.unsafe('CREATE EXTENSION IF NOT EXISTS vector');
+      } finally {
+        await dbPool.close().catch(() => {});
+      }
+    };
 
-      // Enable pgvector extension
-      await dbPool.unsafe('CREATE EXTENSION IF NOT EXISTS vector');
+    try {
+      await tryCreateExtension();
       this.logger.info({ dbName }, 'pgvector extension enabled');
+      return;
     } catch (error) {
-      // Log but don't fail database creation - pgvector might not be available
-      this.logger.warn({ dbName, err: error.message }, 'Failed to enable pgvector extension (non-fatal)');
-    } finally {
-      // Always close the temporary connection
-      if (dbPool) {
-        await dbPool.close().catch(() => {});
+      const msg = error?.message || '';
+      // Postgres surfaces stale .so as "incompatible library version" or
+      // "version mismatch" depending on the nature of the ABI break.
+      // PG_MODULE_MAGIC mismatches show the same symptoms.
+      const abiMismatch = /version mismatch|incompatible library version|PG_MODULE_MAGIC/i.test(msg);
+      if (!abiMismatch) {
+        this.logger.warn({ dbName, err: msg }, 'Failed to enable pgvector extension (non-fatal)');
+        return;
+      }
+
+      this.logger.warn(
+        { dbName, err: msg },
+        'pgvector ABI mismatch detected — auto-healing stale install and retrying'
+      );
+      try {
+        await this._healStalePgvector();
+      } catch (healError) {
+        this.logger.error({ dbName, err: healError.message }, 'pgvector auto-heal failed during reinstall');
+        return;
+      }
+
+      try {
+        await tryCreateExtension();
+        this.logger.info({ dbName }, 'pgvector auto-heal successful — extension enabled');
+      } catch (retryError) {
+        this.logger.error(
+          { dbName, err: retryError.message },
+          'pgvector still failing after auto-heal — manual intervention required'
+        );
       }
     }
   }

package/tests/pg-version-regex.test.js

@@ -13,8 +13,9 @@
  */
 
 import { test, expect, describe } from 'bun:test';
+import { pgvectorMetaMatches } from '../src/postgres.js';
 
-// Keep this in sync with `ensurePgvectorFiles()` in src/postgres.js
+// Keep this in sync with `_detectPgMajor()` in src/postgres.js
 const PG_VERSION_REGEX = /PostgreSQL\)?\s+(\d+)/;
 
 function detectMajor(versionString) {
@@ -46,3 +47,83 @@ describe('PG major version detection for pgvector auto-install', () => {
     expect(detectMajor('mysql 8.0')).toBeNull();
   });
 });
+
+/**
+ * Staleness detection tests for the pgvector auto-heal path.
+ *
+ * `pgvectorMetaMatches` decides whether an already-present vector.so on
+ * disk can be trusted (return true → reuse) or must be torn down and
+ * reinstalled (return false → heal). Getting this wrong in either
+ * direction is a production bug:
+ *
+ *  - False positive (matches when it shouldn't) → stale PG17 .so stays on
+ *    disk, CREATE EXTENSION dies with "incompatible library version" on
+ *    PG18, brain-ingest blows up mid-run.
+ *  - False negative (doesn't match when it should) → pgserve re-downloads
+ *    pgvector on every start, wasting bandwidth and triggering
+ *    apt.postgresql.org rate limits.
+ *
+ * These tests pin the exact matching semantics so the auto-heal doesn't
+ * silently regress.
+ */
+describe('pgvectorMetaMatches — pgvector install staleness detection', () => {
+  const RUNTIME = {
+    pgMajor: '18',
+    postgresPath: '/home/user/.pgserve/bin/linux-x64/bin/postgres',
+  };
+
+  test('matches when metadata pgMajor and postgresPath agree with runtime', () => {
+    const meta = {
+      pgMajor: '18',
+      pgvectorVersion: '0.8.1-2',
+      postgresPath: '/home/user/.pgserve/bin/linux-x64/bin/postgres',
+      installedAt: '2026-04-10T18:00:00.000Z',
+    };
+    expect(pgvectorMetaMatches(meta, RUNTIME)).toBe(true);
+  });
+
+  test('matches when postgresPath is absent (older metadata format)', () => {
+    const meta = { pgMajor: '18', pgvectorVersion: '0.8.1-2' };
+    expect(pgvectorMetaMatches(meta, RUNTIME)).toBe(true);
+  });
+
+  test('rejects when pgMajor differs — this is the PG17→PG18 regression we are healing', () => {
+    const stalePg17Meta = {
+      pgMajor: '17',
+      pgvectorVersion: '0.8.1-2',
+      postgresPath: '/home/user/.pgserve/bin/linux-x64/bin/postgres',
+    };
+    expect(pgvectorMetaMatches(stalePg17Meta, RUNTIME)).toBe(false);
+  });
+
+  test('rejects when postgresPath points at a different binary (pgserve upgraded)', () => {
+    const meta = {
+      pgMajor: '18',
+      postgresPath: '/opt/old-pgserve/bin/postgres',
+    };
+    expect(pgvectorMetaMatches(meta, RUNTIME)).toBe(false);
+  });
+
+  test('rejects null metadata (pre-auto-heal install without sidecar)', () => {
+    // This is the case that heals every existing broken deployment: they
+    // have vector.so on disk but no vector.meta.json, so match returns
+    // false → reinstall fires.
+    expect(pgvectorMetaMatches(null, RUNTIME)).toBe(false);
+  });
+
+  test('rejects non-object metadata (corrupted sidecar)', () => {
+    expect(pgvectorMetaMatches('18', RUNTIME)).toBe(false);
+    expect(pgvectorMetaMatches(42, RUNTIME)).toBe(false);
+    expect(pgvectorMetaMatches([], RUNTIME)).toBe(false);
+  });
+
+  test('rejects metadata missing pgMajor field', () => {
+    expect(pgvectorMetaMatches({ pgvectorVersion: '0.8.1' }, RUNTIME)).toBe(false);
+  });
+
+  test('rejects metadata where pgMajor is not a string', () => {
+    // JSON could hand us a number — match must be strict about type to
+    // avoid `18 == '18'` false positives masking a corrupted file.
+    expect(pgvectorMetaMatches({ pgMajor: 18 }, RUNTIME)).toBe(false);
+  });
+});