orez 0.0.46 → 0.0.47

package/src/cli.ts

@@ -750,6 +750,11 @@ const main = defineCommand({
       description: 'use native @rocicorp/zero-sqlite3 instead of wasm bedrock-sqlite',
       default: false,
     },
+    'log-env': {
+      type: 'boolean',
+      description: 'log ZERO_* and related environment variables on startup',
+      default: false,
+    },
     'on-db-ready': {
       type: 'string',
       description: 'command to run after db+proxy are ready, before zero-cache starts',
@@ -760,6 +765,21 @@ const main = defineCommand({
       description: 'command to run once all services are healthy',
       default: '',
     },
+    admin: {
+      type: 'boolean',
+      description: 'start admin web ui',
+      default: false,
+    },
+    'admin-port': {
+      type: 'string',
+      description: 'admin ui port (default: auto)',
+      default: '0',
+    },
+    'admin-logs': {
+      type: 'boolean',
+      description: 'write logs to .orez/logs/ (default: true when --admin)',
+      default: true,
+    },
   },
   subCommands: {
     s3: s3Command,
@@ -767,7 +787,8 @@ const main = defineCommand({
     pg_restore: pgRestoreCommand,
   },
   async run({ args }) {
-    const { config, stop } = await startZeroLite({
+    const startTime = Date.now()
+    const { config, stop, logStore, zeroEnv, actions, httpLogStore } = await startZeroLite({
       pgPort: Number(args['pg-port']),
       zeroPort: Number(args['zero-port']),
       dataDir: args['data-dir'],
@@ -778,7 +799,11 @@ const main = defineCommand({
       skipZeroCache: args['skip-zero-cache'],
       disableWasmSqlite: args['disable-wasm-sqlite'],
       logLevel: (args['log-level'] as 'error' | 'warn' | 'info' | 'debug') || undefined,
+      logEnv: args['log-env'],
       onDbReady: args['on-db-ready'],
+      admin: args.admin,
+      adminPort: Number(args['admin-port']),
+      adminLogs: args['admin-logs'],
     })
 
     let s3Server: import('node:http').Server | null = null
@@ -790,6 +815,27 @@ const main = defineCommand({
       })
     }
 
+    let adminServer: import('node:http').Server | null = null
+    if (args.admin && logStore) {
+      const { findPort } = await import('./port.js')
+      const adminPort = Number(args['admin-port']) || (config.zeroPort + 2)
+      const resolvedPort = await findPort(adminPort)
+      const { startAdminServer } = await import('./admin/server.js')
+      adminServer = await startAdminServer({
+        port: resolvedPort,
+        logStore,
+        config,
+        zeroEnv,
+        actions,
+        startTime,
+        httpLog: httpLogStore || undefined,
+      })
+      log.orez(`admin: http://127.0.0.1:${resolvedPort}`)
+      if (args['admin-logs']) {
+        log.orez(`logs: ${resolve(args['data-dir'], 'logs', 'orez.log')}`)
+      }
+    }
+
     log.orez('ready')
     log.orez(
       `pg: postgresql://${config.pgUser}:${config.pgPassword}@127.0.0.1:${config.pgPort}/postgres`
@@ -817,11 +863,13 @@ const main = defineCommand({
     }
 
     process.on('SIGINT', async () => {
+      adminServer?.close()
       s3Server?.close()
       await stop()
       process.exit(0)
     })
     process.on('SIGTERM', async () => {
+      adminServer?.close()
       s3Server?.close()
       await stop()
       process.exit(0)

package/src/config.ts

@@ -14,8 +14,12 @@ export interface ZeroLiteConfig {
   disableWasmSqlite: boolean
   logLevel: LogLevel
   pgliteOptions: Partial<PGliteOptions>
+  logEnv: boolean
   onDbReady: string
   beforeZero: ((db: import('@electric-sql/pglite').PGlite) => Promise<void>) | null
+  admin: boolean
+  adminPort: number
+  adminLogs: boolean
 }
 
 export function getConfig(overrides: Partial<ZeroLiteConfig> = {}): ZeroLiteConfig {
@@ -31,8 +35,12 @@ export function getConfig(overrides: Partial<ZeroLiteConfig> = {}): ZeroLiteConf
     disableWasmSqlite: overrides.disableWasmSqlite ?? false,
     logLevel: overrides.logLevel || 'warn',
     pgliteOptions: overrides.pgliteOptions || {},
+    logEnv: overrides.logEnv ?? false,
     onDbReady: overrides.onDbReady || '',
     beforeZero: overrides.beforeZero || null,
+    admin: overrides.admin ?? false,
+    adminPort: overrides.adminPort || 0,
+    adminLogs: overrides.adminLogs ?? true,
   }
 }
 

package/src/index.ts

@@ -7,21 +7,23 @@
  */
 
 import { spawn, type ChildProcess } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { totalmem } from 'node:os'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { getConfig, getConnectionString } from './config.js'
-import { log, port, setLogLevel } from './log.js'
+import { log, port, setLogLevel, addLogListener } from './log.js'
 import { startPgProxy } from './pg-proxy.js'
-import { createPGliteInstances, runMigrations } from './pglite-manager.js'
+import { createInstance, createPGliteInstances, runMigrations } from './pglite-manager.js'
 import { findPort } from './port.js'
 import { installChangeTracking } from './replication/change-tracker.js'
 
 import type { ZeroLiteConfig } from './config.js'
 import type { PGlite } from '@electric-sql/pglite'
+import type { LogStore } from './admin/log-store.js'
+import type { HttpLogStore } from './admin/http-proxy.js'
 
 export { getConfig, getConnectionString } from './config.js'
 export type { LogLevel, ZeroLiteConfig } from './config.js'
@@ -43,6 +45,21 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
   const config = getConfig(overrides)
   setLogLevel(config.logLevel)
 
+  // when admin ui enabled, create log store and capture all log output
+  const SOURCE_MAP: Record<string, string> = {
+    'orez': 'orez', 'pglite': 'pglite', 'pg-proxy': 'proxy',
+    'zero': 'zero', 'zero-cache': 'zero', 'orez/s3': 's3',
+  }
+  let logStore: LogStore | null = null
+  let removeLogListener: (() => void) | null = null
+  if (config.admin) {
+    const { createLogStore } = await import('./admin/log-store.js')
+    logStore = createLogStore(config.dataDir, config.adminLogs)
+    removeLogListener = addLogListener((source, level, msg) => {
+      logStore!.push(SOURCE_MAP[source] || source, level, msg)
+    })
+  }
+
   // find available ports
   const pgPort = await findPort(config.pgPort)
   const zeroPort = config.skipZeroCache
@@ -73,7 +90,7 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
   // start tcp proxy (routes connections to correct instance by database name)
   const pgServer = await startPgProxy(instances, config)
 
-  log.orez(`db up ${port(pgPort, 'green')}`)
+  log.pglite(`postgres up ${port(pgPort, 'green')}`)
   if (migrationsApplied > 0)
     log.orez(
       `${migrationsApplied} migration${migrationsApplied === 1 ? '' : 's'} applied`
@@ -128,18 +145,121 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
   // clean up stale lock files from previous crash (keep replica for fast restart)
   cleanupStaleLockFiles(config)
 
-  // start zero-cache
+  // http proxy for admin traffic logging
+  let httpLogStore: HttpLogStore | null = null
+  let httpProxyServer: import('node:http').Server | null = null
+  let zeroInternalPort = zeroPort
+  if (config.admin && !config.skipZeroCache) {
+    const { createHttpLogStore } = await import('./admin/http-proxy.js')
+    httpLogStore = createHttpLogStore()
+    zeroInternalPort = await findPort(zeroPort + 100)
+  }
+
+  // start zero-cache with auto-recovery for stale change db
   let zeroCacheProcess: ChildProcess | null = null
+  let zeroEnv: Record<string, string> = {}
+  const cdbResets = { count: 0, lastReset: 0 }
+  const MAX_CDB_RESETS = 10
+  const MIN_RESET_INTERVAL_MS = 60_000
+
   if (!config.skipZeroCache) {
-    zeroCacheProcess = await startZeroCache(config)
-    await waitForZeroCache(config)
+    let currentResult = await startZeroCache(config, zeroInternalPort)
+    zeroCacheProcess = currentResult.child
+    zeroEnv = currentResult.env
+
+    // watch for stale changeLog crashes and auto-recover
+    const attachCdbRecovery = (result: typeof currentResult) => {
+      result.child.on('exit', async (code) => {
+        if (code === 0 || code === null) return
+        if (!result.stderrBuf.includes('changeLog_pkey')) return
+
+        const now = Date.now()
+        if (cdbResets.count >= MAX_CDB_RESETS) {
+          log.zero('change db reset limit reached, not retrying')
+          return
+        }
+        const elapsed = now - cdbResets.lastReset
+        if (elapsed < MIN_RESET_INTERVAL_MS) {
+          log.zero(`change db reset too soon (${Math.round(elapsed / 1000)}s ago), not retrying`)
+          return
+        }
+
+        cdbResets.count++
+        cdbResets.lastReset = now
+        log.zero(`stale change db detected, resetting (${cdbResets.count}/${MAX_CDB_RESETS})`)
+
+        try {
+          await instances.cdb.close()
+          const cdbPath = resolve(config.dataDir, 'pgdata-cdb')
+          rmSync(cdbPath, { recursive: true, force: true })
+          instances.cdb = await createInstance(config, 'cdb', false)
+
+          currentResult = await startZeroCache(config, zeroInternalPort)
+          zeroCacheProcess = currentResult.child
+          attachCdbRecovery(currentResult)
+          await waitForZeroCache(config, undefined, zeroInternalPort)
+          log.zero(`recovered, ready ${port(config.zeroPort, 'magenta')}`)
+        } catch (err) {
+          log.zero(`recovery failed: ${err}`)
+        }
+      })
+    }
+
+    attachCdbRecovery(currentResult)
+    await waitForZeroCache(config, undefined, zeroInternalPort)
     log.zero(`ready ${port(config.zeroPort, 'magenta')}`)
+
+    // start http proxy for admin traffic logging
+    if (httpLogStore) {
+      const { startHttpProxy } = await import('./admin/http-proxy.js')
+      httpProxyServer = await startHttpProxy({
+        listenPort: zeroPort,
+        targetPort: zeroInternalPort,
+        httpLog: httpLogStore,
+      })
+    }
   } else {
     log.orez('skip zero-cache')
   }
 
+  // admin action handlers
+  const actions = {
+    restartZero: config.skipZeroCache ? undefined : async () => {
+      if (zeroCacheProcess && !zeroCacheProcess.killed) {
+        zeroCacheProcess.kill('SIGTERM')
+        await new Promise<void>((r) => {
+          const t = setTimeout(() => { zeroCacheProcess?.kill('SIGKILL'); r() }, 3000)
+          zeroCacheProcess!.on('exit', () => { clearTimeout(t); r() })
+        })
+      }
+      const zc = await startZeroCache(config, zeroInternalPort)
+      zeroCacheProcess = zc.child
+      await waitForZeroCache(config, undefined, zeroInternalPort)
+      log.zero(`restarted ${port(config.zeroPort, 'magenta')}`)
+    },
+    resetZero: config.skipZeroCache ? undefined : async () => {
+      if (zeroCacheProcess && !zeroCacheProcess.killed) {
+        zeroCacheProcess.kill('SIGTERM')
+        await new Promise<void>((r) => {
+          const t = setTimeout(() => { zeroCacheProcess?.kill('SIGKILL'); r() }, 3000)
+          zeroCacheProcess!.on('exit', () => { clearTimeout(t); r() })
+        })
+      }
+      const replicaPath = resolve(config.dataDir, 'zero-replica.db')
+      for (const suffix of ['', '-wal', '-shm', '-wal2']) {
+        try { if (existsSync(replicaPath + suffix)) unlinkSync(replicaPath + suffix) } catch {}
+      }
+      const zc = await startZeroCache(config, zeroInternalPort)
+      zeroCacheProcess = zc.child
+      await waitForZeroCache(config, undefined, zeroInternalPort)
+      log.zero(`reset and restarted ${port(config.zeroPort, 'magenta')}`)
+    },
+  }
+
   const stop = async () => {
     log.debug.orez('shutting down')
+    removeLogListener?.()
+    httpProxyServer?.close()
     if (zeroCacheProcess && !zeroCacheProcess.killed) {
       zeroCacheProcess.kill('SIGTERM')
       // wait up to 3s for graceful exit, then force kill
@@ -165,7 +285,7 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
     log.debug.orez('stopped')
   }
 
-  return { config, stop, db, instances, pgPort: config.pgPort, zeroPort: config.zeroPort }
+  return { config, stop, db, instances, pgPort: config.pgPort, zeroPort: config.zeroPort, logStore, zeroEnv, actions, httpLogStore }
 }
 
 function cleanupStaleLockFiles(config: ZeroLiteConfig): void {
@@ -244,7 +364,7 @@ function writeSqliteShim(): string {
   return registerPath
 }
 
-async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
+async function startZeroCache(config: ZeroLiteConfig, portOverride?: number): Promise<{ child: ChildProcess; env: Record<string, string>; stderrBuf: string }> {
   // resolve @rocicorp/zero entry for finding zero-cache modules
   const zeroEntry = resolvePackage('@rocicorp/zero')
 
@@ -263,7 +383,7 @@ async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
   // defaults that can be overridden by user env
   const defaults: Record<string, string> = {
     NODE_ENV: 'development',
-    ZERO_LOG_LEVEL: config.logLevel,
+    ZERO_LOG_LEVEL: 'info',
     ZERO_NUM_SYNC_WORKERS: '1',
     // disable query planner — it relies on scanStatus which causes infinite
     // loops with wasm sqlite and has caused freezes with native too.
@@ -289,7 +409,7 @@ async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
     ZERO_CVR_DB: cvrUrl,
     ZERO_CHANGE_DB: cdbUrl,
     ZERO_REPLICA_FILE: resolve(config.dataDir, 'zero-replica.db'),
-    ZERO_PORT: String(config.zeroPort),
+    ZERO_PORT: String(portOverride || config.zeroPort),
   }
 
   const zeroCacheBin = resolve(zeroEntry, '..', 'cli.js')
@@ -313,31 +433,82 @@ async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
     env.NODE_OPTIONS = `--max-old-space-size=${heapMB} ${existing}`.trim()
   }
 
+  // log env vars if --log-env was passed
+  if (config.logEnv) {
+    const zeroVars = Object.entries(env)
+      .filter(([key]) => key.startsWith('ZERO_') || key === 'NODE_ENV')
+      .sort(([a], [b]) => a.localeCompare(b))
+    log.orez('zero-cache env:')
+    for (const [key, value] of zeroVars) {
+      log.orez(`  ${key}=${value}`)
+    }
+  }
+
   const child = spawn(zeroCacheBin, [], {
     env,
     stdio: ['ignore', 'pipe', 'pipe'],
   })
 
+  // zero-cache uses structured logging when piped (not a tty).
+  // multiline format: timestamp + "[" on one line, context lines, "] message" on another.
+  // single-line format: timestamp + [ context ] message, or timestamp + key=val,... message
+  // we buffer multiline blocks and extract just the message.
+  const timestampRe = /^\d{4}-\d{2}-\d{2}T[\d:.+\-Z]+\s*/
+  let inBlock = false
+  const zeroLog = (line: string) => {
+    let stripped = line.replace(timestampRe, '')
+
+    // start of multiline context block: line ends with "[" (possibly after timestamp)
+    if (!inBlock && /^\[?\s*$/.test(stripped)) {
+      inBlock = true
+      return
+    }
+
+    // inside multiline block: skip context lines, look for "] message"
+    if (inBlock) {
+      const closeMatch = stripped.match(/^\]\s*(.*)$/)
+      if (closeMatch) {
+        inBlock = false
+        const msg = closeMatch[1].trim()
+        if (msg) log.zero(msg)
+      }
+      // context continuation lines like "'pid=8278'," — skip
+      return
+    }
+
+    // single-line: strip inline [ context ] and key=val prefixes
+    stripped = stripped.replace(/\[.*?\]\s*/g, '')
+    stripped = stripped.replace(/^(?:\w+=\S+,)*\w+=\S+\s+/, '')
+    stripped = stripped.trim()
+
+    if (!stripped || /^[\[\]',\s]*$/.test(stripped)) return
+
+    log.zero(stripped)
+  }
+
   child.stdout?.on('data', (data: Buffer) => {
     const lines = data.toString().trim().split('\n')
     for (const line of lines) {
-      log.debug.zero(line)
+      zeroLog(line)
     }
   })
 
-  let stderrBuf = ''
+  const result = { child, env, stderrBuf: '' }
+
   child.stderr?.on('data', (data: Buffer) => {
     const chunk = data.toString()
-    stderrBuf += chunk
+    result.stderrBuf += chunk
     const lines = chunk.trim().split('\n')
     for (const line of lines) {
-      log.debug.zero(line)
+      zeroLog(line)
     }
   })
 
   child.on('exit', (code) => {
     if (code !== 0 && code !== null) {
-      if (stderrBuf.includes('Could not locate the bindings file')) {
+      // changeLog_pkey errors are handled by the recovery logic in startZeroLite
+      if (result.stderrBuf.includes('changeLog_pkey')) return
+      if (result.stderrBuf.includes('Could not locate the bindings file')) {
         log.zero(
           'native @rocicorp/zero-sqlite3 not found — native deps were not compiled.\n' +
             'either:\n' +
@@ -346,7 +517,7 @@ async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
             '    or add "trustedDependencies": ["@rocicorp/zero-sqlite3"] to package.json'
         )
       } else {
-        const lastLines = stderrBuf.trim().split('\n').slice(-5).join('\n')
+        const lastLines = result.stderrBuf.trim().split('\n').slice(-5).join('\n')
         if (lastLines) {
           log.zero(`exited with code ${code}:\n${lastLines}`)
         } else {
@@ -356,15 +527,16 @@ async function startZeroCache(config: ZeroLiteConfig): Promise<ChildProcess> {
     }
   })
 
-  return child
+  return result
 }
 
 async function waitForZeroCache(
   config: ZeroLiteConfig,
-  timeoutMs = 120000
+  timeoutMs = 120000,
+  portOverride?: number,
 ): Promise<void> {
   const start = Date.now()
-  const url = `http://127.0.0.1:${config.zeroPort}/`
+  const url = `http://127.0.0.1:${portOverride || config.zeroPort}/`
 
   while (Date.now() - start < timeoutMs) {
     try {

package/src/log.ts

@@ -25,6 +25,17 @@ export function setLogLevel(level: LogLevel) {
   currentLevel = level
 }
 
+type LogListener = (source: string, level: LogLevel, msg: string) => void
+const listeners: LogListener[] = []
+
+export function addLogListener(fn: LogListener) {
+  listeners.push(fn)
+  return () => {
+    const idx = listeners.indexOf(fn)
+    if (idx !== -1) listeners.splice(idx, 1)
+  }
+}
+
 function prefix(label: string, color: string): string {
   return `${BOLD}${color}[${label}]${RESET}`
 }
@@ -37,6 +48,12 @@ export function port(n: number, color: keyof typeof COLORS): string {
 function makeLogger(label: string, color: string, level: LogLevel = 'info') {
   const p = prefix(label, color)
   return (...args: unknown[]) => {
+    // always notify listeners (they capture everything for admin ui)
+    if (listeners.length > 0) {
+      const msg = args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ')
+      for (const fn of listeners) fn(label, level, msg)
+    }
+    // only print to terminal if level passes filter
     if (LEVEL_PRIORITY[level] <= LEVEL_PRIORITY[currentLevel]) {
       console.info(p, ...args)
     }
@@ -47,8 +64,15 @@ export const log = {
   orez: makeLogger('orez', COLORS.cyan, 'warn'),
   pglite: makeLogger('pglite', COLORS.green, 'warn'),
   proxy: makeLogger('pg-proxy', COLORS.yellow, 'warn'),
-  zero: makeLogger('zero-cache', COLORS.magenta, 'warn'),
+  zero: makeLogger('zero', COLORS.magenta, 'warn'),
   s3: makeLogger('orez/s3', COLORS.blue, 'warn'),
+  info: {
+    orez: makeLogger('orez', COLORS.cyan, 'info'),
+    pglite: makeLogger('pglite', COLORS.green, 'info'),
+    proxy: makeLogger('pg-proxy', COLORS.yellow, 'info'),
+    zero: makeLogger('zero', COLORS.magenta, 'info'),
+    s3: makeLogger('orez/s3', COLORS.blue, 'info'),
+  },
   debug: {
     orez: makeLogger('orez', COLORS.cyan, 'debug'),
     pglite: makeLogger('pglite', COLORS.green, 'debug'),

package/src/pg-proxy.ts

@@ -464,6 +464,14 @@ async function performHandshake(
   return { params }
 }
 
+// ── connection tracking ──
+
+// per-database active connection count. pglite is single-session so all
+// connections share one transaction context. we skip ROLLBACK on close when
+// other connections are still active to avoid killing their transactions.
+const activeConns: Record<string, number> = {}
+let connCounter = 0
+
 // ── message loop ──
 
 // process messages from a connected, authenticated client.
@@ -674,6 +682,7 @@ export async function startPgProxy(
 
     let dbName = 'postgres'
     let isReplicationConnection = false
+    const connId = ++connCounter
 
     try {
       // perform startup handshake
@@ -682,18 +691,29 @@ export async function startPgProxy(
       dbName = params.database || 'postgres'
       isReplicationConnection = params.replication === 'database'
 
-      log.debug.proxy(
-        `connection: db=${dbName} user=${params.user} replication=${params.replication || 'none'}`
-      )
+      // track active connections per database
+      activeConns[dbName] = (activeConns[dbName] || 0) + 1
+
+      console.info(`[orez-proxy#${connId}] connect db=${dbName} repl=${params.replication || 'none'}`)
 
       const { db } = getDbContext(dbName)
       await db.waitReady
 
       // clean up pglite session state when client disconnects.
-      // pglite is single-session — all connections share one session, so SET
-      // commands from one connection (e.g. pg_restore setting search_path='')
-      // bleed into subsequent connections. reset on close to prevent this.
+      // pglite is single-session — all connections share one session.
+      // only ROLLBACK + reset when this is the LAST connection for this db,
+      // to avoid killing another connection's active transaction.
       socket.on('close', async () => {
+        activeConns[dbName] = Math.max(0, (activeConns[dbName] || 1) - 1)
+        const remaining = activeConns[dbName]
+        const shouldRollback = remaining === 0
+
+        console.info(
+          `[orez-proxy#${connId}] close [${dbName}] (remaining=${remaining}, shouldRollback=${shouldRollback})`
+        )
+
+        if (!shouldRollback) return
+
         const { db: closeDb, mutex: closeMutex } = getDbContext(dbName)
         await closeMutex.acquire()
         try {

package/src/pglite-manager.ts

@@ -16,7 +16,7 @@ export interface PGliteInstances {
 }
 
 // create a single pglite instance with given dataDir suffix
-async function createInstance(
+export async function createInstance(
   config: ZeroLiteConfig,
   name: string,
   withExtensions: boolean

package/src/replication/handler.ts

@@ -33,6 +33,9 @@ import {
 import type { Mutex } from '../mutex.js'
 import type { PGlite } from '@electric-sql/pglite'
 
+// track concurrent replication handlers to detect reconnect-purge race
+let activeHandlerCount = 0
+
 export interface ReplicationWriter {
   write(data: Uint8Array): void
 }
@@ -263,6 +266,9 @@ export async function handleStartReplication(
   db: PGlite,
   mutex: Mutex
 ): Promise<void> {
+  activeHandlerCount++
+  const handlerId = activeHandlerCount
+  console.info(`[orez-repl#${handlerId}] START_REPLICATION (active handlers: ${activeHandlerCount})`)
   log.debug.proxy('replication: entering streaming mode')
 
   // send CopyBothResponse to enter streaming mode
@@ -457,6 +463,8 @@ export async function handleStartReplication(
     mutex.release()
   }
 
+  console.info(`[orez-repl#${handlerId}] setup complete, starting poll (lastWatermark=${lastWatermark})`)
+
   // track which tables we've sent RELATION messages for
   const sentRelations = new Set<string>()
   let txCounter = 1
@@ -469,6 +477,7 @@ export async function handleStartReplication(
   const purgeEveryN = 10
   let running = true
   let pollsSincePurge = 0
+  let lastIdleLog = 0
 
   const poll = async () => {
     while (running) {
@@ -483,6 +492,8 @@ export async function handleStartReplication(
         }
 
         if (changes.length > 0) {
+          const tables = [...new Set(changes.map(c => c.table_name))].join(',')
+          console.info(`[orez-repl#${handlerId}] found ${changes.length} changes [${tables}] (wm ${lastWatermark}→${changes[changes.length - 1].watermark}, type=${typeof changes[0].watermark})`)
           await streamChanges(
             changes,
             writer,
@@ -502,12 +513,19 @@ export async function handleStartReplication(
             try {
               const purged = await purgeConsumedChanges(db, lastWatermark)
               if (purged > 0) {
-                log.debug.proxy(`purged ${purged} consumed changes`)
+                console.info(`[orez-repl#${handlerId}] purged ${purged} changes (wm<=${lastWatermark})`)
               }
             } finally {
               mutex.release()
             }
           }
+        } else {
+          // throttled idle logging (every 10s)
+          const now = Date.now()
+          if (now - lastIdleLog > 10000) {
+            lastIdleLog = now
+            console.info(`[orez-repl#${handlerId}] idle (lastWatermark=${lastWatermark}, type=${typeof lastWatermark})`)
+          }
         }
 
         // send keepalive
@@ -531,7 +549,8 @@ export async function handleStartReplication(
 
   log.debug.proxy('replication: starting poll loop')
   await poll()
-  log.debug.proxy('replication: poll loop exited')
+  activeHandlerCount--
+  console.info(`[orez-repl#${handlerId}] poll loop exited (remaining handlers: ${activeHandlerCount})`)
 }
 
 async function streamChanges(