mixdog 0.7.17 → 0.8.0

package/src/runtime/memory/lib/pg/adapter.mjs

@@ -0,0 +1,314 @@
+const __mixdogMemoryStderrWrite = process.stderr.write.bind(process.stderr);
+function __mixdogMemoryLog(...args) {
+  if (process.env.MIXDOG_QUIET_MEMORY_LOG) return true;
+  return __mixdogMemoryStderrWrite(...args);
+}
+
+// pg-adapter.mjs — PG connection manager for mixdog 0.4.0
+// Single owner: supervisor-pg.ensurePgInstance(dataDir) starts PG.
+// pg-adapter calls supervisor-pg — never pg-process directly.
+//
+// Public API:
+//   ensurePgInstance(dataDir, { schema? }) → { db, pool, host, port, runtimeDir, pgdataDir }
+//   closePgInstance(dataDir)               → void
+//
+// The returned `db` exposes the native PG query surface:
+//   db.query(sql, params?)          → { rows, rowCount }
+//   db.exec(sql)                    → multi-statement; resolves on completion
+//   db.transaction(async tx => …)  → auto BEGIN/COMMIT, ROLLBACK on throw
+
+import { resolve } from 'path'
+import { ensurePgInstance as supervisorEnsure } from './supervisor.mjs'
+
+// ---------------------------------------------------------------------------
+// One-shot bootstrap guard — keyed by resolved dataDir (cluster-level, not schema)
+// ---------------------------------------------------------------------------
+
+const _bootstrapped = new Set()
+
+// ---------------------------------------------------------------------------
+// Cross-process advisory-lock keys (two-int4 form: classid + objid).
+//
+// pg advisory locks are CLUSTER-global regardless of which database the session
+// is connected to, so a single shared classid namespaces all mixdog first-boot
+// locks; distinct objids separate the CREATE DATABASE race from the per-cluster
+// extension/schema DDL race. Fixed app-specific keys → concurrent first-boot
+// workers serialize on the exact same lock rather than racing the DDL path.
+// ---------------------------------------------------------------------------
+
+const ADVISORY_LOCK_CLASSID = 0x6d696478 // "midx" — mixdog bootstrap namespace
+const ADVISORY_OBJID_CREATE_DB = 1       // CREATE DATABASE mixdog
+export const ADVISORY_OBJID_SCHEMA_BOOTSTRAP = 2 // extensions + schema DDL
+
+// ---------------------------------------------------------------------------
+// In-process cache
+// ---------------------------------------------------------------------------
+
+const instances = new Map() // `${dataDir}|${schema}` → instance handle
+const opening   = new Map() // same key → Promise (dedupe concurrent calls)
+
+// ---------------------------------------------------------------------------
+// Per-connection init — WeakSet-guarded so settings run exactly once per client
+// ---------------------------------------------------------------------------
+
+const _clientInited = new WeakSet()
+
+async function _initClient(client, schema) {
+  if (_clientInited.has(client)) return
+  // Set search_path so unqualified table names resolve to the correct schema.
+  //
+  // CROSS-SCHEMA QUERY RULE: search_path is per-connection and biases every
+  // unqualified table reference toward the connection's primary schema. Any
+  // query that intentionally touches the OTHER schema (e.g. orphan sweep on
+  // memory.entries from a trace-schema connection, or recall × trace JOIN
+  // analytics) MUST use fully-qualified names (memory.entries / trace.trace_events).
+  // Relying on search_path silently in cross-schema code = bug magnet.
+  const sp = schema === 'trace' ? 'trace, public' : 'memory, public'
+  await client.query(`SET search_path = ${sp}`)
+  // pg_trgm similarity threshold: session-local, must be set per connection.
+  await client.query(`SELECT set_limit(0.10)`)
+  await client.query(`SET default_transaction_isolation TO 'read committed'`)
+  // Mark seen only after all init statements succeed; failure leaves client
+  // unmarked so the next checkout retries init.
+  _clientInited.add(client)
+}
+
+// Wrapper around pool.connect() that runs per-client init before returning.
+// Exported so external callers (e.g. trace-store.insertBridgeCalls) can obtain
+// a connection with search_path already set; raw _pool.connect() leaves it at
+// the PG default and unqualified table lookups resolve in the wrong schema.
+export async function checkedConnect(pgPool, schema) {
+  const client = await pgPool.connect()
+  try {
+    await _initClient(client, schema)
+  } catch (e) {
+    client.release()
+    throw e
+  }
+  return client
+}
+const _checkedConnect = checkedConnect
+
+// ---------------------------------------------------------------------------
+// native PG db shim
+// ---------------------------------------------------------------------------
+
+function makeCompatDb(pgPool, schema) {
+  const db = {
+    // query: use pool directly for single-statement queries
+    query: async (sql, params) => {
+      const client = await _checkedConnect(pgPool, schema)
+      try {
+        return await client.query(sql, params)
+      } finally {
+        client.release()
+      }
+    },
+
+    // exec: multi-statement SQL (semicolon-separated); single client for session state
+    exec: async (sql) => {
+      const client = await _checkedConnect(pgPool, schema)
+      try {
+        await client.query(sql)
+      } finally {
+        client.release()
+      }
+    },
+
+    // transaction: check out one client, BEGIN, run callback(tx), COMMIT or ROLLBACK
+    transaction: async (fn) => {
+      const client = await _checkedConnect(pgPool, schema)
+      try {
+        await client.query('BEGIN')
+        const tx = {
+          query: (sql, params) => client.query(sql, params),
+          exec:  (sql)         => client.query(sql),
+        }
+        const result = await fn(tx)
+        await client.query('COMMIT')
+        return result
+      } catch (err) {
+        try { await client.query('ROLLBACK') } catch {}
+        throw err
+      } finally {
+        client.release()
+      }
+    },
+
+    // close: drain pool
+    close: () => pgPool.end(),
+
+    // Internal access for callers that need raw pool
+    _pool: pgPool,
+  }
+  return db
+}
+
+// ---------------------------------------------------------------------------
+// Instance bootstrap — extensions + schemas (idempotent)
+// ---------------------------------------------------------------------------
+
+// Run `fn` while holding the cluster-global schema-bootstrap advisory lock on a
+// dedicated client. Concurrent first-boot workers across processes serialize on
+// the fixed key so the CREATE TYPE / CREATE EXTENSION / schema DDL path is never
+// raced. The lock is session-scoped (held by this client) and released in
+// finally; `fn`'s own DDL may run on other pool connections — the lock only has
+// to provide cross-process mutual exclusion, not cover the same session.
+export async function withSchemaBootstrapLock(pgPool, fn) {
+  const client = await pgPool.connect()
+  // Tracks whether the advisory lock is provably released. Stays false until a
+  // successful pg_advisory_unlock; any failure/uncertainty keeps it false so we
+  // never return a still-locked session to the pool.
+  let unlockErr = new Error('schema-bootstrap advisory lock release not attempted')
+  try {
+    await client.query(`SELECT pg_advisory_lock($1, $2)`, [
+      ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_SCHEMA_BOOTSTRAP,
+    ])
+    try {
+      return await fn()
+    } finally {
+      try {
+        await client.query(`SELECT pg_advisory_unlock($1, $2)`, [
+          ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_SCHEMA_BOOTSTRAP,
+        ])
+        unlockErr = null // lock provably released → client is clean to reuse
+      } catch (err) {
+        unlockErr = err instanceof Error ? err : new Error(String(err))
+      }
+    }
+  } finally {
+    // A client whose advisory-lock state is uncertain must never be reused:
+    // release(truthy) makes node-pg destroy it instead of pooling it.
+    client.release(unlockErr || undefined)
+  }
+}
+
+async function bootstrapInstance(pgPool, dataDirKey) {
+  if (_bootstrapped.has(dataDirKey)) return
+  // Serialize the cluster-level DDL across concurrent first-boot processes.
+  await withSchemaBootstrapLock(pgPool, async () => {
+    // Use a raw client bypassing per-client schema settings (bootstrap targets
+    // the cluster level, not a specific schema).
+    const client = await pgPool.connect()
+    try {
+      await client.query(`CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA public`)
+      await client.query(`CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public`)
+      await client.query(`CREATE SCHEMA IF NOT EXISTS memory`)
+      await client.query(`CREATE SCHEMA IF NOT EXISTS trace`)
+    } finally {
+      client.release()
+    }
+  })
+  _bootstrapped.add(dataDirKey)
+}
+
+// ---------------------------------------------------------------------------
+// ensurePgInstance — public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure a live PG instance and return a native PG db handle.
+ *
+ * @param {string} dataDir      Plugin data directory.
+ * @param {{ schema?: 'memory' | 'trace' }} [opts]
+ * @returns {Promise<{ db, pool, host, port, runtimeDir, pgdataDir }>}
+ */
+export async function ensurePgInstance(dataDir, opts = {}) {
+  const schema = opts.schema ?? 'memory'
+  const key    = `${resolve(dataDir)}|${schema}`
+
+  if (instances.has(key)) return instances.get(key)
+  if (opening.has(key))   return opening.get(key)
+
+  const promise = (async () => {
+    // 1. Let supervisor-pg own PG startup and health-checking.
+    //    Returns { host, port, runtimeDir, pgdataDir }.
+    const { host, port, runtimeDir, pgdataDir } = await supervisorEnsure(dataDir)
+
+    // 2. Connect via node-postgres; auto-create the mixdog database if absent.
+    const { default: pg } = await import('pg')
+
+    const PG_USER = 'postgres'
+    const PG_DB   = 'mixdog'
+
+    const adminPool = new pg.Pool({
+      host, port, user: PG_USER, database: 'postgres',
+      password: '', max: 1, idleTimeoutMillis: 5_000,
+    })
+    try {
+      // CREATE DATABASE cannot run inside a transaction, so guard the
+      // check-then-create with a session-level advisory lock held on a single
+      // dedicated client. Concurrent first-boot workers block on the same
+      // cluster-global key here and only one issues the CREATE; the rest see
+      // the row present after the holder releases. Released in finally.
+      const adminClient = await adminPool.connect()
+      // Same invariant as withSchemaBootstrapLock: only reuse the client if the
+      // advisory lock is provably released.
+      let unlockErr = new Error('create-db advisory lock release not attempted')
+      try {
+        await adminClient.query(`SELECT pg_advisory_lock($1, $2)`, [
+          ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_CREATE_DB,
+        ])
+        try {
+          const r = await adminClient.query(`SELECT 1 FROM pg_database WHERE datname = $1`, [PG_DB])
+          if (r.rows.length === 0) {
+            await adminClient.query(`CREATE DATABASE ${PG_DB}`)
+            __mixdogMemoryLog(`[pg-adapter] created database ${PG_DB}\n`)
+          }
+        } finally {
+          try {
+            await adminClient.query(`SELECT pg_advisory_unlock($1, $2)`, [
+              ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_CREATE_DB,
+            ])
+            unlockErr = null // lock provably released → client is clean to reuse
+          } catch (err) {
+            unlockErr = err instanceof Error ? err : new Error(String(err))
+          }
+        }
+      } finally {
+        // Uncertain advisory-lock state → destroy the client (truthy release arg)
+        // so a still-locked session never re-enters the admin pool.
+        adminClient.release(unlockErr || undefined)
+      }
+    } finally {
+      await adminPool.end()
+    }
+
+    // 3. Production pool.
+    const pgPool = new pg.Pool({
+      host, port, user: PG_USER, database: PG_DB,
+      password: '', max: 5, idleTimeoutMillis: 30_000,
+      connectionTimeoutMillis: 10_000,
+    })
+
+    // 4. Bootstrap extensions + schemas once (idempotent).
+    await bootstrapInstance(pgPool, resolve(dataDir))
+
+    // 5. Build the compat db shim.
+    const db = makeCompatDb(pgPool, schema)
+
+    const result = { db, pool: pgPool, host, port, runtimeDir, pgdataDir }
+    instances.set(key, result)
+    return result
+  })()
+
+  opening.set(key, promise)
+  try {
+    return await promise
+  } finally {
+    opening.delete(key)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// closePgInstance — drain pool
+// ---------------------------------------------------------------------------
+
+export async function closePgInstance(dataDir, opts = {}) {
+  const schema = opts.schema ?? 'memory'
+  const key    = `${resolve(dataDir)}|${schema}`
+  const inst   = instances.get(key)
+  if (!inst) return
+  try { await inst.pool.end() } catch {}
+  instances.delete(key)
+}

package/src/runtime/memory/lib/pg/process.mjs

@@ -0,0 +1,366 @@
+const __mixdogMemoryStderrWrite = process.stderr.write.bind(process.stderr);
+function __mixdogMemoryLog(...args) {
+  if (process.env.MIXDOG_QUIET_MEMORY_LOG) return true;
+  return __mixdogMemoryStderrWrite(...args);
+}
+
+// pg-process.mjs — lower-level PG lifecycle helpers for mixdog 0.4.0
+// Track B can wire these into the supervisor; pg-adapter calls them directly.
+//
+// Public API:
+//   startPg({ runtimeDir, pgdataDir, port?, logPath? }) → { pid, port }
+//   stopPg({ runtimeDir, pgdataDir })                   → void
+//   healthcheckPg({ port, host? })                      → boolean
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import { createConnection } from 'net'
+import { createServer } from 'net'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function pgBin(runtimeDir, name) {
+  const ext = process.platform === 'win32' ? '.exe' : ''
+  return join(runtimeDir, 'bin', `${name}${ext}`)
+}
+
+function libEnv(runtimeDir) {
+  // Bundled shared libraries must be visible to the PG binaries at runtime.
+  const libDir = join(runtimeDir, 'lib')
+  if (process.platform === 'linux') {
+    return { ...process.env, LD_LIBRARY_PATH: libDir }
+  }
+  if (process.platform === 'darwin') {
+    return { ...process.env, DYLD_LIBRARY_PATH: libDir }
+  }
+  // win32: DLLs live in bin/ — add to PATH.
+  return { ...process.env, PATH: `${join(runtimeDir, 'bin')};${process.env.PATH}` }
+}
+
+// ---------------------------------------------------------------------------
+// Free port detection
+// ---------------------------------------------------------------------------
+
+function isTcpPortFree(port) {
+  return new Promise(resolve => {
+    const srv = createServer()
+    srv.once('error', () => resolve(false))
+    srv.once('listening', () => { srv.close(); resolve(true) })
+    srv.listen(port, '127.0.0.1')
+  })
+}
+
+const PG_PORT_MIN = 55432
+const PG_PORT_MAX = 55632
+
+async function findFreePort(preferred) {
+  // I2: clamp out-of-range callers to the valid window.
+  if (preferred < PG_PORT_MIN || preferred > PG_PORT_MAX) preferred = PG_PORT_MIN
+  if (await isTcpPortFree(preferred)) return preferred
+  for (let p = preferred + 1; p <= PG_PORT_MAX; p++) {
+    if (await isTcpPortFree(p)) return p
+  }
+  throw new Error(`[pg-process] no free port found in range ${preferred}–${PG_PORT_MAX}`)
+}
+
+// ---------------------------------------------------------------------------
+// postgresql.conf v2 reconcile — appended on every startPg call so existing
+// pgdata directories pick up the bgwriter / checkpoint-distribution tuning
+// without requiring a fresh initdb.
+// ---------------------------------------------------------------------------
+
+const MIXDOG_CONF_V2_MARKER = '# mixdog overrides v2 — bgwriter / checkpoint distribution'
+
+// Lines emitted into postgresql.conf for v2. effective_io_concurrency is
+// posix_fadvise-only; PG rejects non-zero values on Windows with an invalid-
+// parameter error on every reload. Skip it there.
+function buildV2Block() {
+  const lines = [
+    '',
+    MIXDOG_CONF_V2_MARKER,
+    'checkpoint_completion_target = 0.9',  // spread checkpoint write across 90% of timeout window
+    'bgwriter_lru_maxpages = 1000',        // up to 1000 dirty pages per round (default 100)
+    'bgwriter_delay = 50ms',               // wake bgwriter every 50ms (default 200ms)
+  ]
+  if (process.platform !== 'win32') {
+    lines.push('effective_io_concurrency = 32')  // I/O concurrency hint (POSIX only)
+  }
+  return lines.join('\n') + '\n'
+}
+
+// Migration: an earlier v2 always emitted effective_io_concurrency. On Windows
+// that line is invalid — strip it so pg_ctl reload stops logging a parse error
+// every cycle.
+function stripWindowsInvalidLines(conf) {
+  if (process.platform !== 'win32') return conf
+  return conf.replace(/^effective_io_concurrency\s*=\s*\d+\s*\r?\n/m, '')
+}
+
+function ensureConfV2(pgdataDir) {
+  const confPath = join(pgdataDir, 'postgresql.conf')
+  if (!existsSync(confPath)) return false
+  const original = readFileSync(confPath, 'utf8')
+  let conf = stripWindowsInvalidLines(original)
+  const stripped = conf !== original
+  const hasMarker = conf.includes(MIXDOG_CONF_V2_MARKER)
+  if (hasMarker && !stripped) return false
+  if (!hasMarker) conf = conf + buildV2Block()
+  writeFileSync(confPath, conf)
+  return true
+}
+
+// Public reconcile: idempotent conf v2 append + pg_ctl reload on a running
+// instance. Single source of truth for v2 application — supervisor and other
+// callers route through this rather than re-implementing the conf/reload pair.
+// All v2 settings are reload-applicable (no restart required).
+export function reconcileConfV2(runtimeDir, pgdataDir) {
+  const applied = ensureConfV2(pgdataDir)
+  if (!applied) return { applied: false, reloaded: false }
+  const reload = spawnSync(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
+    env: libEnv(runtimeDir), stdio: 'pipe', timeout: 5_000, windowsHide: true,
+  })
+  const reloaded = reload.status === 0
+  if (reloaded) {
+    __mixdogMemoryLog('[pg-process] postgresql.conf v2 overrides applied via pg_ctl reload\n')
+  } else {
+    __mixdogMemoryLog(`[pg-process] pg_ctl reload after v2 append failed (non-fatal): ${reload.stderr?.toString() || ''}\n`)
+  }
+  return { applied, reloaded }
+}
+
+// ---------------------------------------------------------------------------
+// startPg
+// ---------------------------------------------------------------------------
+
+export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 55432, logPath }) {
+  mkdirSync(pgdataDir, { recursive: true })
+
+  if (process.platform === 'darwin') {
+    try { writeFileSync(join(pgdataDir, '.metadata_never_index'), '') } catch {}
+  }
+
+  // Idempotent v2 conf reconcile — runs before attach/init. Returns true if
+  // the block was just appended (so the attach path can trigger pg_ctl reload).
+  // Fresh-init path falls through to confAppend below which already includes v2.
+  const v2Applied = ensureConfV2(pgdataDir)
+
+  // Pre-check: if postmaster.pid exists and the instance is reachable, attach
+  // rather than attempting a second pg_ctl start (which would crash the worker).
+  const postmasterPidPath = join(pgdataDir, 'postmaster.pid')
+  if (existsSync(postmasterPidPath)) {
+    try {
+      const lines = readFileSync(postmasterPidPath, 'utf8').split('\n')
+      const existingPid  = parseInt(lines[0], 10)
+      // Line 4 (index 3) in postmaster.pid holds the port number.
+      const existingPort = parseInt(lines[3], 10)
+      if (existingPid > 0 && existingPort > 0) {
+        // Liveness must be confirmed by pg_isready (status 0). A bare open TCP
+        // port is insufficient: any unrelated listener that happened to grab
+        // this port would be mistaken for our PG instance, causing a false
+        // attach. pg_isready performs a real PG protocol handshake, so a
+        // non-Postgres listener returns non-zero and we correctly fall through
+        // to normal startup (which reclaims the stale postmaster.pid).
+        const pgIsReady = pgBin(runtimeDir, 'pg_isready')
+        const probe = spawnSync(pgIsReady, ['-h', '127.0.0.1', '-p', String(existingPort)], {
+          env: libEnv(runtimeDir), stdio: 'pipe', timeout: 3_000, windowsHide: true,
+        })
+        const alive = probe.status === 0
+        if (alive) {
+          __mixdogMemoryLog(`[pg-process] attaching to existing PG pid=${existingPid} port=${existingPort}\n`)
+          // Route through the single reconcile entry point so v1 → v2 conf
+          // upgrades land on already-running instances without restart.
+          if (v2Applied) reconcileConfV2(runtimeDir, pgdataDir)
+          return { pid: existingPid, port: existingPort, attached: true }
+        }
+        // Dead instance — fall through to normal startup; pg_ctl will reclaim stale lock.
+      }
+    } catch {}
+  }
+
+  const env    = libEnv(runtimeDir)
+  const initdb = pgBin(runtimeDir, 'initdb')
+  const pgctl  = pgBin(runtimeDir, 'pg_ctl')
+
+  // initdb if pgdata is not yet initialised (no PG_VERSION file).
+  const pgVersionFile = join(pgdataDir, 'PG_VERSION')
+  if (!existsSync(pgVersionFile)) {
+    __mixdogMemoryLog(`[pg-process] initdb → ${pgdataDir}\n`)
+    const r = spawnSync(initdb, [
+      '-D', pgdataDir,
+      '--auth-local=trust',
+      '--no-locale',
+      '-E', 'UTF8',
+      '-U', 'postgres',
+    ], { env, stdio: 'pipe', windowsHide: true })
+
+    if (r.status !== 0) {
+      const detail = r.error?.message
+        || r.stderr?.toString()
+        || r.stdout?.toString()
+        || `status=${r.status} signal=${r.signal} (no captured output)`
+      throw new Error(`[pg-process] initdb failed: ${detail}`)
+    }
+
+    // Append mixdog-specific postgresql.conf overrides.
+    // default_transaction_isolation: native PG default is read committed.
+    // Native PG does not default to serializable; set isolation level explicitly
+    // so behaviour is unambiguous across PG major versions.
+    const confPath   = join(pgdataDir, 'postgresql.conf')
+    const confAppend = [
+      '',
+      '# mixdog overrides — appended by pg-process.mjs',
+      "default_transaction_isolation = 'read committed'",
+      "listen_addresses = '127.0.0.1'",
+      'log_min_messages = warning',
+      'log_line_prefix = \'%t [%p]: \'',
+      '',
+      '# Defender/AV latency mitigations',
+      'synchronous_commit = off',          // defers fsync ack; trade-off: crash → latest async commits since last WAL flush may be lost; acceptable for local memory store
+      'checkpoint_timeout = 15min',        // halves checkpoint frequency vs 5min default; fewer sync storms
+      'max_wal_size = 2GB',                // suppresses forced checkpoints driven by WAL volume
+      'wal_compression = on',              // smaller WAL segments; fewer bytes for Defender to scan per segment
+      'wal_init_zero = off',               // skips zero-fill on new WAL segment; cuts Defender contact at segment creation
+      'wal_recycle = off',                 // disables WAL rename/recycle loop; eliminates rename-storm EPERM pattern in pgdata
+    ].join('\n') + '\n' + buildV2Block()
+
+    try {
+      const existing = readFileSync(confPath, 'utf8')
+      writeFileSync(confPath, existing + confAppend)
+    } catch (e) {
+      __mixdogMemoryLog(`[pg-process] postgresql.conf append failed: ${e?.message}\n`)
+    }
+
+    if (process.platform === 'win32') {
+      __mixdogMemoryLog(
+        `[pg-process] Windows tip: if startup feels slow, add the data folder to Defender exclusions.\n` +
+        `  Folder: ${pgdataDir}\n` +
+        `  PowerShell (run as admin): Add-MpPreference -ExclusionPath '${pgdataDir}'\n`
+      )
+    }
+  }
+
+  // Choose a free port (guards against stale postmaster from prior crash).
+  const port    = await findFreePort(preferredPort)
+  const logFile = logPath ?? join(pgdataDir, 'pg.log')
+
+  __mixdogMemoryLog(`[pg-process] pg_ctl start -D ${pgdataDir} -p ${port}\n`)
+
+  const r = spawnSync(pgctl, [
+    'start', '-w',
+    '-D', pgdataDir,
+    '-l', logFile,
+    '-o', `-p ${port} -h 127.0.0.1`,
+  ], { env, stdio: 'pipe', timeout: 30_000, windowsHide: true })
+
+  if (r.status !== 0) {
+    const errText = r.stderr?.toString() || r.stdout?.toString() || ''
+    // "another server might be running" — try status + immediate stop before failing.
+    if (errText.includes('another server might be running')) {
+      __mixdogMemoryLog(`[pg-process] pg_ctl start: "another server might be running" — probing status\n`)
+      const statusR = spawnSync(pgctl, ['status', '-D', pgdataDir], { env, stdio: 'pipe', timeout: 3_000, windowsHide: true })
+      __mixdogMemoryLog(`[pg-process] pg_ctl status: ${statusR.stdout?.toString() || statusR.stderr?.toString() || 'no output'}\n`)
+      const stopR = spawnSync(pgctl, ['stop', '-m', 'immediate', '-D', pgdataDir], { env, stdio: 'pipe', timeout: 3_000, windowsHide: true })
+      if (stopR.status === 0) {
+        // Retry start once after clearing the stale instance.
+        const r2 = spawnSync(pgctl, [
+          'start', '-w',
+          '-D', pgdataDir,
+          '-l', logPath ?? join(pgdataDir, 'pg.log'),
+          '-o', `-p ${port} -h 127.0.0.1`,
+        ], { env, stdio: 'pipe', timeout: 30_000, windowsHide: true })
+        if (r2.status === 0) {
+          let pid = null
+          try {
+            const pidFile = join(pgdataDir, 'postmaster.pid')
+            if (existsSync(pidFile)) pid = parseInt(readFileSync(pidFile, 'utf8').split('\n')[0], 10) || null
+          } catch {}
+          return { pid, port }
+        }
+        __mixdogMemoryLog(`[pg-process] retry start after stop also failed: ${r2.stderr?.toString() || ''}\n`)
+      } else {
+        __mixdogMemoryLog(`[pg-process] immediate stop failed: ${stopR.stderr?.toString() || ''} — treating as degraded\n`)
+      }
+    }
+    throw new Error(`[pg-process] pg_ctl start failed: ${errText}`)
+  }
+
+  // Read PID from postmaster.pid (first line).
+  let pid = null
+  try {
+    const pidFile = join(pgdataDir, 'postmaster.pid')
+    if (existsSync(pidFile)) {
+      pid = parseInt(readFileSync(pidFile, 'utf8').split('\n')[0], 10) || null
+    }
+  } catch {}
+
+  return { pid, port }
+}
+
+// ---------------------------------------------------------------------------
+// stopPg
+// ---------------------------------------------------------------------------
+
+export async function stopPg({ runtimeDir, pgdataDir }) {
+  const pgctl = pgBin(runtimeDir, 'pg_ctl')
+  const env   = libEnv(runtimeDir)
+
+  const r = spawnSync(pgctl, ['stop', '-m', 'fast', '-w', '-D', pgdataDir], {
+    env,
+    stdio: 'pipe',
+    timeout: 15_000,
+    windowsHide: true,
+  })
+
+  if (r.status !== 0) {
+    const msg = r.stderr?.toString() || r.stdout?.toString() || ''
+    // Stale postmaster.pid — PG is already down; clean up and continue.
+    if (
+      msg.includes('no server running') ||
+      msg.includes('PID file') ||
+      msg.includes('not running')
+    ) {
+      __mixdogMemoryLog(`[pg-process] stopPg: already stopped (${msg.slice(0, 80)})\n`)
+      try { rmSync(join(pgdataDir, 'postmaster.pid'), { force: true }) } catch {}
+    } else {
+      __mixdogMemoryLog(`[pg-process] pg_ctl stop warning: ${msg}\n`)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// healthcheckPg
+// ---------------------------------------------------------------------------
+
+export async function healthcheckPg({ port, host = '127.0.0.1' }) {
+  // Phase 1: TCP listen check (fast, no PG client dependency).
+  const tcpOk = await new Promise(resolve => {
+    const sock = createConnection({ host, port })
+    sock.setTimeout(1000)
+    sock.once('connect', () => { sock.destroy(); resolve(true) })
+    sock.once('error',   () => { sock.destroy(); resolve(false) })
+    sock.once('timeout', () => { sock.destroy(); resolve(false) })
+  })
+  if (!tcpOk) return false
+
+  // Phase 2: SELECT 1 via a transient pg client.
+  let client
+  try {
+    const { default: pg } = await import('pg')
+    client = new pg.Client({
+      host, port, user: 'postgres', database: 'postgres', password: '',
+      connectionTimeoutMillis: 2000,
+    })
+    await client.connect()
+    await client.query('SELECT 1')
+    return true
+  } catch {
+    return false
+  } finally {
+    if (client) {
+      try { await client.end() } catch {}
+    }
+  }
+}