mixdog 0.9.51 → 0.9.53

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

@@ -4,8 +4,70 @@ function __mixdogMemoryLog(...args) {
   return __mixdogMemoryStderrWrite(...args);
 }
 
-function installPoolErrorHandler(pool, label) {
+const _poolClientErrorHandlers = new WeakMap()
+
+export function isPgConnectionLossError(err) {
+  const seen = new Set()
+  let cur = err
+  for (let depth = 0; cur && depth < 5 && !seen.has(cur); depth++) {
+    seen.add(cur)
+    const code = String(cur?.code || cur?.errno || '').toUpperCase()
+    const msg = String(cur?.message || cur || '')
+    if (
+      code === 'ECONNREFUSED'
+      || code === 'ECONNRESET'
+      || code === 'EPIPE'
+      || code === 'ENETRESET'
+      || code === '57P01'
+      || code === '57P02'
+      || code === '57P03'
+      || /connection terminated(?: unexpectedly)?/i.test(msg)
+      || /server closed the connection unexpectedly/i.test(msg)
+      || /read ECONNRESET|socket hang up|connect ECONNREFUSED/i.test(msg)
+      || /cannot use a pool after calling end/i.test(msg)
+    ) return true
+    cur = cur?.cause
+  }
+  return false
+}
+
+function isSafePreDispatchRetryError(err) {
+  const code = String(err?.code || err?.errno || '').toUpperCase()
+  const msg = String(err?.message || err || '')
+  return code === 'ECONNREFUSED'
+    || /connect ECONNREFUSED/i.test(msg)
+    || /cannot use a pool after calling end/i.test(msg)
+}
+
+export function installPoolErrorHandler(pool, label, { onConnectionLoss } = {}) {
   if (!pool || typeof pool.on !== 'function') return pool
+  // pg-pool deliberately removes its idle error listener while a Client is
+  // checked out. Long-running advisory-lock owners (cycle1/2/3) can therefore
+  // receive a socket-end `error` between queries with no listener at all,
+  // which Node treats as an uncaught exception. Give every physical Client a
+  // permanent last-resort listener; pg-pool's own idle listener still owns
+  // eviction when the Client is back in the pool.
+  pool.on('connect', (client) => {
+    if (!client || typeof client.on !== 'function' || _poolClientErrorHandlers.has(client)) return
+    const handler = (err) => {
+      const code = err?.code || err?.errno || ''
+      const msg = err?.message || String(err || 'unknown error')
+      const pid = client?.processID ? ` pid=${client.processID}` : ''
+      const suffix = code ? ` ${code}` : ''
+      __mixdogMemoryLog(`[pg-adapter] ${label} client error${suffix}${pid}: ${msg}\n`)
+      if (isPgConnectionLossError(err) && typeof onConnectionLoss === 'function') {
+        try {
+          Promise.resolve(onConnectionLoss(err, client)).catch((recoverErr) => {
+            __mixdogMemoryLog(`[pg-adapter] ${label} client-error recovery failed: ${recoverErr?.message || recoverErr}\n`)
+          })
+        } catch (recoverErr) {
+          __mixdogMemoryLog(`[pg-adapter] ${label} client-error recovery failed: ${recoverErr?.message || recoverErr}\n`)
+        }
+      }
+    }
+    _poolClientErrorHandlers.set(client, handler)
+    client.on('error', handler)
+  })
   pool.on('error', (err, client) => {
     const code = err?.code || err?.errno || ''
     const msg = err?.message || String(err || 'unknown error')
@@ -139,7 +201,7 @@ function makeCompatDb(pgPool, schema, dataDir) {
           client.release()
         }
       } catch (err) {
-        if (err?.code === 'ECONNREFUSED') _recoverPgConnection(dataDir, schema).catch(() => {})
+        if (isPgConnectionLossError(err)) _recoverPgConnection(dataDir, schema).catch(() => {})
         throw err
       }
     },
@@ -152,8 +214,10 @@ function makeCompatDb(pgPool, schema, dataDir) {
       // side effects. Recover in the background for the next caller and
       // propagate the original error immediately.
       const pool = instances.get(`${resolve(dataDir)}|${schema}`)?.pool ?? pgPool
-      const client = await _checkedConnect(pool, schema)
+      let client = null
+      let releaseErr = null
       try {
+        client = await _checkedConnect(pool, schema)
         await client.query('BEGIN')
         const tx = {
           query: (sql, params) => client.query(sql, params),
@@ -163,11 +227,16 @@ function makeCompatDb(pgPool, schema, dataDir) {
         await client.query('COMMIT')
         return result
       } catch (err) {
-        try { await client.query('ROLLBACK') } catch {}
-        if (err?.code === 'ECONNREFUSED') _recoverPgConnection(dataDir, schema).catch(() => {})
+        if (client) {
+          try { await client.query('ROLLBACK') } catch {}
+        }
+        if (isPgConnectionLossError(err)) {
+          releaseErr = err instanceof Error ? err : new Error(String(err))
+          _recoverPgConnection(dataDir, schema).catch(() => {})
+        }
         throw err
       } finally {
-        client.release()
+        if (client) client.release(releaseErr || undefined)
       }
     },
 
@@ -228,7 +297,7 @@ async function _recoverPgConnection(dataDir, schema) {
 
   const p = (async () => {
     _lastRecoverAt.set(dataDirKey, Date.now())
-    __mixdogMemoryLog(`[pg-adapter] ECONNREFUSED on pool query — recovering PG for dataDir=${dataDirKey}\n`)
+    __mixdogMemoryLog(`[pg-adapter] connection loss — recovering PG for dataDir=${dataDirKey}\n`)
     // memory + trace schemas share one PG cluster/port; discard every cached
     // pool for this dataDir so a dead-port pool is never reused after restart.
     // Track every schema whose pool was actually closed here so ALL of them
@@ -275,9 +344,12 @@ async function withPgRetry(dataDir, schema, fn) {
   try {
     return await fn(pool0)
   } catch (err) {
-    if (err?.code !== 'ECONNREFUSED') throw err
+    if (!isPgConnectionLossError(err)) throw err
     const recovered = await _recoverPgConnection(dataDir, schema)
-    if (!recovered) throw err
+    // Only retry failures proven to happen before dispatch. ECONNRESET and
+    // server-termination errors can arrive after PostgreSQL applied a write;
+    // replaying a generic query would risk duplicate side effects.
+    if (!recovered || !isSafePreDispatchRetryError(err)) throw err
     const pool1 = instances.get(key)?.pool
     if (!pool1) throw err
     return await fn(pool1)
@@ -422,7 +494,9 @@ export async function ensurePgInstance(dataDir, opts = {}) {
       password: '', max: 5, idleTimeoutMillis: 30_000,
       connectionTimeoutMillis: 10_000,
     })
-    installPoolErrorHandler(pgPool, `pool:${schema}`)
+    installPoolErrorHandler(pgPool, `pool:${schema}`, {
+      onConnectionLoss: () => _recoverPgConnection(dataDir, schema),
+    })
 
     // 4. Bootstrap extensions + schemas once (idempotent).
     await bootstrapInstance(pgPool, resolve(dataDir))

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

@@ -55,6 +55,51 @@ function isTcpPortFree(port) {
 
 const PG_PORT_MIN = 55432
 const PG_PORT_MAX = 55632
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err?.code === 'EPERM'
+  }
+}
+
+function readPostmasterInfo(pgdataDir) {
+  try {
+    const lines = readFileSync(join(pgdataDir, 'postmaster.pid'), 'utf8').split('\n')
+    const pid = parseInt(lines[0], 10)
+    const port = parseInt(lines[3], 10)
+    return {
+      pid: Number.isInteger(pid) && pid > 0 ? pid : null,
+      port: Number.isInteger(port) && port > 0 ? port : null,
+    }
+  } catch {
+    return { pid: null, port: null }
+  }
+}
+
+function pgIsReady(runtimeDir, env, port) {
+  const probe = spawnSync(pgBin(runtimeDir, 'pg_isready'), ['-h', '127.0.0.1', '-p', String(port)], {
+    env, stdio: 'pipe', timeout: 3_000, windowsHide: true,
+  })
+  return probe.status === 0
+}
+
+async function awaitExistingPostmaster({ runtimeDir, pgdataDir, env, waitMs }) {
+  const deadline = Date.now() + Math.max(0, Number(waitMs) || 0)
+  let info = readPostmasterInfo(pgdataDir)
+  while (info.pid && info.port) {
+    if (pgIsReady(runtimeDir, env, info.port)) return { state: 'ready', ...info }
+    if (!isPidAlive(info.pid)) return { state: 'dead', ...info }
+    if (Date.now() >= deadline) return { state: 'alive-not-ready', ...info }
+    await delay(250)
+    info = readPostmasterInfo(pgdataDir)
+  }
+  return { state: 'missing', ...info }
+}
 
 async function findFreePort(preferred) {
   // I2: clamp out-of-range callers to the valid window.
@@ -135,7 +180,13 @@ export function reconcileConfV2(runtimeDir, pgdataDir) {
 // startPg
 // ---------------------------------------------------------------------------
 
-export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 55432, logPath }) {
+export async function startPg({
+  runtimeDir,
+  pgdataDir,
+  port: preferredPort = 55432,
+  logPath,
+  existingWaitMs = 15_000,
+}) {
   mkdirSync(pgdataDir, { recursive: true })
 
   if (process.platform === 'darwin') {
@@ -146,41 +197,35 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
   // 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)
+  const env = libEnv(runtimeDir)
 
   // 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 existing = await awaitExistingPostmaster({
+      runtimeDir, pgdataDir, env, waitMs: existingWaitMs,
+    })
+    if (existing.state === 'ready') {
+      __mixdogMemoryLog(`[pg-process] attaching to existing PG pid=${existing.pid} port=${existing.port}\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: existing.pid, port: existing.port, attached: true }
+    }
+    if (existing.state === 'alive-not-ready') {
+      // A postmaster in startup/shutdown still owns this pgdata even when it no
+      // longer accepts connections. Starting the same directory on a "free"
+      // alternate port produces the observed endless "another server might be
+      // running" loop and can corrupt lifecycle state. The supervisor may
+      // finish a graceful stop, but this lower layer must never race it.
+      throw new Error(
+        `[pg-process] existing PG pid=${existing.pid} port=${existing.port} is alive but not ready; refusing concurrent start`,
+      )
+    }
+    // Dead instance — fall through to normal startup; pg_ctl reclaims the stale lock.
   }
 
-  const env    = libEnv(runtimeDir)
   const initdb = pgBin(runtimeDir, 'initdb')
   const pgctl  = pgBin(runtimeDir, 'pg_ctl')
 
@@ -248,7 +293,6 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
 
   __mixdogMemoryLog(`[pg-process] pg_ctl start -D ${pgdataDir} -p ${port}\n`)
 
-  const pgIsReady = pgBin(runtimeDir, 'pg_isready')
   const startArgs = [
     'start',
     '-D', pgdataDir,
@@ -258,8 +302,6 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
 
   // Poll-sleep is intentionally NOT unref'd: while startPg is awaiting readiness
   // it must keep the process alive even if the event loop would otherwise drain.
-  const sleep = ms => new Promise(res => setTimeout(res, ms))
-
   // Read pid + port from postmaster.pid (line 1 = pid, line 4 = port). Returns
   // null unless the file exists, pid > 0, and its port matches ours.
   function readPostmaster() {
@@ -280,7 +322,7 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
     for (let i = 0; i < 5; i++) {
       const pm = readPostmaster()
       if (pm) return pm.pid
-      await sleep(100)
+      await delay(100)
     }
     return null
   }
@@ -312,10 +354,7 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
     const deadline = Date.now() + 30_000
     // eslint-disable-next-line no-constant-condition
     while (true) {
-      const probe = spawnSync(pgIsReady, ['-h', '127.0.0.1', '-p', String(port)], {
-        env, stdio: 'pipe', timeout: 3_000, windowsHide: true,
-      })
-      if (probe.status === 0) {
+      if (pgIsReady(runtimeDir, env, port)) {
         const pid = await confirmPid()
         // pid confirmed with matching port → ready. Otherwise keep polling until
         // the cap (postmaster.pid not yet written or port mismatch).
@@ -324,7 +363,7 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
       // pg_ctl exited nonzero before PG became reachable — real startup failure.
       if (closed && exitCode !== 0) return { ready: false, exited: true, stdout, stderr }
       if (Date.now() >= deadline) return { ready: false, timeout: true, stdout, stderr }
-      await sleep(250)
+      await delay(250)
     }
   }
 
@@ -332,19 +371,19 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
   if (r.ready) return { pid: r.pid, port }
 
   const errText = r.stderr || r.stdout || ''
-  // "another server might be running" — try status + immediate stop before failing.
+  // A cross-process race can still land after the pre-check. Re-probe and
+  // attach if that winner becomes ready; never immediate-stop an unknown live
+  // postmaster, because synchronous_commit=off makes a crash-stop lossy.
   if (r.exited && 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 = await startAndWaitReady()
-      if (r2.ready) return { pid: r2.pid, port }
-      __mixdogMemoryLog(`[pg-process] retry start after stop also failed: ${r2.stderr || ''}\n`)
-    } else {
-      __mixdogMemoryLog(`[pg-process] immediate stop failed: ${stopR.stderr?.toString() || ''} — treating as degraded\n`)
+    const existing = await awaitExistingPostmaster({
+      runtimeDir, pgdataDir, env, waitMs: existingWaitMs,
+    })
+    if (existing.state === 'ready') {
+      __mixdogMemoryLog(`[pg-process] attaching to race winner pid=${existing.pid} port=${existing.port}\n`)
+      return { pid: existing.pid, port: existing.port, attached: true }
     }
   }
 
@@ -419,6 +458,11 @@ export async function healthcheckPg({ port, host = '127.0.0.1' }) {
       host, port, user: 'postgres', database: 'postgres', password: '',
       connectionTimeoutMillis: 2000,
     })
+    // A socket can terminate after SELECT 1 resolves but before client.end()
+    // finishes. Raw pg.Client instances have no pool-level error listener, so
+    // keep this transient health probe from turning that narrow race into an
+    // uncaught EventEmitter error.
+    client.on('error', () => {})
     await client.connect()
     await client.query('SELECT 1')
     return true

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

@@ -341,10 +341,6 @@ function patchActiveInstance(fields, opts = {}) {
 
 // ── postmaster.pid helpers ───────────────────────────────────────────────────
 
-function readPostmasterPid(pgdata) {
-  return readPostmasterInfo(pgdata).pid;
-}
-
 function readPostmasterInfo(pgdata) {
   try {
     const raw = readFileSync(join(pgdata, 'postmaster.pid'), 'utf8');
@@ -399,6 +395,18 @@ async function isPostmasterAlive(pid) {
   return isPostgresPid(pid);
 }
 
+async function waitForPostmasterReady({ pid, port, healthcheckPg, timeoutMs = 30_000 }) {
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (isPidAlive(pid)) {
+    try {
+      if (await healthcheckPg({ port })) return 'ready';
+    } catch {}
+    if (Date.now() >= deadline) return 'alive-not-ready';
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return 'dead';
+}
+
 // ── Internal: spawn a fresh PG instance ─────────────────────────────────────
 
 async function _startFresh(dataDir, pgdata, port, runtimeDir) {
@@ -473,7 +481,7 @@ async function tryReusePgInstance({ pgdata, runtimeDir, healthcheckPg, source =
 // ── Internal: full ensure logic (runs exclusively via _ensureInFlight) ────────
 
 async function _doEnsure(dataDir) {
-  const { healthcheckPg, stopPg } = await _getPgProc();
+  const { healthcheckPg } = await _getPgProc();
   const pgdata = join(dataDir, 'pgdata');
 
   // Resolve runtimeDir via runtime-fetcher (cache-hits immediately when already downloaded).
@@ -563,22 +571,47 @@ async function _doEnsure(dataDir) {
       __mixdogMemoryLog(
         `[supervisor-pg] pg_port=${existingPort} recorded but healthcheck failed — recovering\n`,
       );
-      const pmPid = readPostmasterPid(pgdata);
-      if (pmPid && await isPostmasterAlive(pmPid)) {
-        // postmaster alive but unhealthy: attempt graceful stop first
-        __mixdogMemoryLog(`[supervisor-pg] postmaster PID ${pmPid} alive — attempting graceful stopPg\n`);
-        try { await stopPg({ runtimeDir, pgdataDir: pgdata }); } catch (e) {
-          __mixdogMemoryLog(`[supervisor-pg] graceful stopPg failed: ${e?.message} — continuing to fresh start\n`);
-        }
-      } else if (pmPid) {
-        // postmaster dead: remove stale postmaster.pid so initdb/start is not blocked
-        __mixdogMemoryLog(`[supervisor-pg] postmaster PID ${pmPid} dead — removing stale postmaster.pid\n`);
-        try { unlinkSync(join(pgdata, 'postmaster.pid')); } catch {}
-      }
       // Clear stale pg fields before restart
       patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null }, { timeoutMs: 1000, background: true });
     }
 
+    // postmaster.pid is the authoritative pgdata owner even when the discovery
+    // advert is absent/stale. The old path checked it only inside the
+    // `existingPort` branch, then allocated 55433 and tried to start the SAME
+    // pgdata while a recovering/rejecting server still owned 55432. Give crash
+    // recovery a bounded chance to finish and attach if it does. Never issue a
+    // stop from an ensure path: an alive postmaster owns the data directory,
+    // and interrupting recovery can turn a transient outage into a restart loop.
+    const pm = readPostmasterInfo(pgdata);
+    if (pm.pid && pm.port && await isPostmasterAlive(pm.pid)) {
+      __mixdogMemoryLog(`[supervisor-pg] postmaster PID ${pm.pid} alive but not ready — awaiting recovery\n`);
+      const state = await waitForPostmasterReady({
+        pid: pm.pid,
+        port: pm.port,
+        healthcheckPg,
+      });
+      if (state === 'ready') {
+        __mixdogMemoryLog(`[supervisor-pg] attaching to recovered PG pid=${pm.pid} port=${pm.port}\n`);
+        _live = { port: pm.port, pgdata, runtimeDir, proc: null };
+        patchActiveInstance({
+          pg_port: pm.port,
+          pg_started_at: ai?.pg_started_at ?? Date.now(),
+          pg_pgdata: pgdata,
+          pg_runtime_dir: runtimeDir,
+        }, { timeoutMs: 1000, background: true });
+        return { host: '127.0.0.1', port: pm.port, runtimeDir, pgdataDir: pgdata };
+      }
+      if (state === 'alive-not-ready') {
+        throw new Error(
+          `[supervisor-pg] existing postmaster PID ${pm.pid} remains alive but unhealthy; refusing concurrent start`,
+        );
+      }
+    }
+    if (pm.pid) {
+      __mixdogMemoryLog(`[supervisor-pg] postmaster PID ${pm.pid} dead — removing stale postmaster.pid\n`);
+      try { unlinkSync(join(pgdata, 'postmaster.pid')); } catch {}
+    }
+
     // ── Allocate a fresh port and spawn ───────────────────────────────────
     const port = await allocatePort();
     return await _startFresh(dataDir, pgdata, port, runtimeDir);

package/src/runtime/memory/lib/query-handlers.mjs

@@ -24,8 +24,8 @@ import { searchRelevantHybrid } from './memory-recall-store.mjs'
 import { fetchEntriesByIdsScoped } from './memory-recall-id-patch.mjs'
 import { retrieveEntries } from './memory-retrievers.mjs'
 import { buildPromotedExclusionClauses } from './memory-recall-scope-filter.mjs'
-import { cleanMemoryText } from './memory.mjs'
 import { insertTraceEvents } from './trace-store.mjs'
+import { createQueryMaintenanceHandlers } from './query-maintenance-handlers.mjs'
 import {
   embedText,
   embedTexts,
@@ -45,6 +45,7 @@ export function createQueryHandlers({
   // instance (one memory runtime = one factory) so the 10s de-dup window
   // behaves exactly as it did when it was a top-level `let` in index.mjs.
   let _embeddingColdRecallLogAt = 0
+  const { dumpSessionRootChunks, entryStats } = createQueryMaintenanceHandlers({ getDb })
 
   // Raw-row priority lookup for narrow-window queries. Raw rows (is_root=0,
   // chunk_root IS NULL) are inserted immediately by ingestTranscriptFile before
@@ -866,127 +867,6 @@ export function createQueryHandlers({
     return { text: recallCapPrefix + renderSessionGroupedLines(sliced, { currentSessionId: _currentSessionHint, recencyOrder: sort === 'date' }) }
   }
 
-  async function dumpSessionRootChunks(args = {}) {
-    const db = getDb()
-    const sessionId = String(args.sessionId || args.session_id || '').trim()
-    if (!sessionId) return { text: '(no current session)', rows: [], chunks: [], isError: true }
-    const includeRaw = args.includeRaw !== false
-    const limit = Math.max(1, Math.min(1000, Number(args.limit) || 1000))
-    const rootRows = (await db.query(`
-      SELECT id, ts, role, content, session_id, source_turn, chunk_root, is_root,
-             element, category, summary, status, score, last_seen_at, project_id
-      FROM entries
-      WHERE session_id = $1 AND is_root = 1
-      ORDER BY COALESCE(source_turn, 2147483647) ASC, ts ASC, id ASC
-      LIMIT $2
-    `, [sessionId, limit])).rows
-    const roots = rootRows.map((r) => ({ ...r, members: [] }))
-    const rootIds = roots.map((r) => Number(r.id)).filter((id) => Number.isFinite(id))
-    const memberRows = rootIds.length > 0
-      ? (await db.query(`
-          SELECT id, ts, role, content, session_id, source_turn, chunk_root, is_root, project_id
-          FROM entries
-          WHERE chunk_root = ANY($1::bigint[]) AND is_root = 0
-          ORDER BY chunk_root ASC, COALESCE(source_turn, 2147483647) ASC, ts ASC, id ASC
-        `, [rootIds])).rows
-      : []
-    const byRoot = new Map(roots.map((r) => [Number(r.id), r]))
-    for (const m of memberRows) {
-      const root = byRoot.get(Number(m.chunk_root))
-      if (root) root.members.push(m)
-    }
-    let rawRows = []
-    if (includeRaw) {
-      rawRows = (await db.query(`
-        SELECT id, ts, role, content, session_id, source_turn, chunk_root, is_root, project_id
-        FROM entries
-        WHERE session_id = $1
-          AND is_root = 0
-          AND (chunk_root IS NULL OR chunk_root = id)
-        ORDER BY COALESCE(source_turn, 2147483647) ASC, ts ASC, id ASC
-        LIMIT $2
-      `, [sessionId, limit])).rows
-    }
-    const chunks = []
-    for (const root of roots) {
-      const memberText = root.members
-        .map((m) => `${m.role === 'assistant' ? 'assistant' : m.role === 'user' ? 'user' : m.role}: ${cleanMemoryText(String(m.content ?? ''))}`)
-        .filter(Boolean)
-        .join('\n')
-      const summary = [root.element, root.summary].map((v) => String(v || '').trim()).filter(Boolean).join(' — ')
-      chunks.push({
-        id: Number(root.id),
-        kind: 'root',
-        ts: Number(root.ts) || 0,
-        sourceTurn: root.source_turn ?? null,
-        category: root.category || null,
-        summary,
-        text: memberText || cleanMemoryText(String(root.content ?? '')),
-        members: root.members,
-      })
-    }
-    for (const raw of rawRows) {
-      chunks.push({
-        id: Number(raw.id),
-        kind: 'raw',
-        chunkRoot: raw.chunk_root ?? null,
-        ts: Number(raw.ts) || 0,
-        sourceTurn: raw.source_turn ?? null,
-        category: null,
-        summary: '',
-        text: `${raw.role === 'assistant' ? 'assistant' : raw.role === 'user' ? 'user' : raw.role}: ${cleanMemoryText(String(raw.content ?? ''))}`,
-        members: [],
-      })
-    }
-    chunks.sort((a, b) => {
-      const at = Number.isFinite(Number(a.sourceTurn)) ? Number(a.sourceTurn) : 2147483647
-      const bt = Number.isFinite(Number(b.sourceTurn)) ? Number(b.sourceTurn) : 2147483647
-      return (at - bt) || ((a.ts || 0) - (b.ts || 0)) || ((a.id || 0) - (b.id || 0))
-    })
-    const text = chunks.length
-      ? chunks.map((chunk, idx) => {
-          const label = chunk.kind === 'root'
-            ? `# chunk ${idx + 1} root=${chunk.id}${chunk.category ? ` category=${chunk.category}` : ''}`
-            : `${chunk.chunkRoot == null ? '# raw_pending' : '# raw_terminal'} ${idx + 1} id=${chunk.id}`
-          const summary = chunk.summary ? `summary: ${chunk.summary}\n` : ''
-          return `${label}\n${summary}${chunk.text}`.trim()
-        }).join('\n\n')
-      : '(no results)'
-    return { text, rows: [...roots, ...rawRows], chunks }
-  }
-
-  async function entryStats() {
-    const db = getDb()
-    return await db.transaction(async (tx) => {
-      const total               = (await tx.query(`SELECT COUNT(*) c FROM entries`)).rows[0].c
-      const roots               = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE is_root = 1`)).rows[0].c
-      const active_roots        = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE is_root = 1 AND status = 'active'`)).rows[0].c
-      const archived_roots      = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE is_root = 1 AND status = 'archived'`)).rows[0].c
-      const unchunked_leaves    = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE chunk_root IS NULL`)).rows[0].c
-      const cycle2_pending_roots = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE is_root = 1 AND status = 'pending'`)).rows[0].c
-      const core_entries        = (await tx.query(`SELECT COUNT(*) c FROM core_entries`)).rows[0].c
-      const core_embed_null     = (await tx.query(`SELECT COUNT(*) c FROM core_entries WHERE embedding IS NULL`)).rows[0].c
-      const active_core_summaries = (await tx.query(`SELECT COUNT(*) c FROM entries WHERE is_root = 1 AND status = 'active' AND core_summary IS NOT NULL`)).rows[0].c
-      const active_core_summary_missing = (await tx.query(`
-        SELECT COUNT(*) c
-        FROM entries
-        WHERE is_root = 1
-          AND status = 'active'
-          AND (core_summary IS NULL OR btrim(core_summary) = '')
-      `)).rows[0].c
-      const byStatus            = (await tx.query(`SELECT status, COUNT(*) c FROM entries WHERE is_root = 1 GROUP BY status`)).rows
-      const byCategory          = (await tx.query(`SELECT category, COUNT(*) c FROM entries WHERE is_root = 1 AND status = 'active' GROUP BY category ORDER BY c DESC`)).rows
-      const mvRows              = (await tx.query(`SELECT relispopulated FROM pg_class WHERE relname = 'mv_hot_active' LIMIT 1`)).rows
-      const mv_hot_active_populated = mvRows.length ? Boolean(mvRows[0].relispopulated) : null
-      return {
-        total, roots, active_roots, archived_roots, unchunked_leaves, cycle2_pending_roots,
-        core_entries, core_embed_null, active_core_summaries, active_core_summary_missing,
-        mv_hot_active_populated,
-        byStatus, byCategory,
-      }
-    })
-  }
-
   return {
     readRawRowsInWindow,
     recallSessionRows,