mixdog 0.9.51 → 0.9.53

package/src/runtime/memory/index.mjs

@@ -90,6 +90,8 @@ import { createQueryHandlers } from './lib/query-handlers.mjs'
 import { createSessionIngestRuntime } from './lib/session-ingest-runtime.mjs'
 import { createMemoryActionHandlers } from './lib/memory-action-handlers.mjs'
 import { createHttpRouter } from './lib/http-router.mjs'
+import { createMemoryPortAdvertiser } from './lib/memory-port-advertiser.mjs'
+import { createMemoryDaemonLifecycle } from './lib/memory-daemon-lifecycle.mjs'
 import {
   readMainConfig,
   readRecapEnabled,
@@ -141,189 +143,31 @@ const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
   ? path.resolve(process.env.MIXDOG_RUNTIME_ROOT)
   : path.join(os.tmpdir(), 'mixdog')
 
-let _periodicAdvertiseInstalled = false
-let _periodicAdvertiseTimer = null
-// Single module-level advertise retry chain. A newer advertiseMemoryPort call
-// cancels the older chain so a delayed retry never replays a stale boundPort.
-let _advertiseRetryTimer = null
-let _advertiseGeneration = 0
-// Track the most recently advertised port so the periodic tick re-reads it
-// every interval. Without this the setInterval closure binds the FIRST port
-// (the upstream we proxied to) and keeps re-advertising the dead upstream
-// port after fork-proxy promotion swaps in our own locally-bound port.
-let _currentAdvertisedPort = null
-
 const MEMORY_SERVER_PID = parsePositivePid(process.env.MIXDOG_SERVER_PID) ?? process.pid
 const _isPidAliveLocal = isPidAliveLocal
+const _memoryPortAdvertiser = createMemoryPortAdvertiser({
+  readServiceAdvert: _readServiceAdvert,
+  writeServiceAdvert: _writeServiceAdvert,
+  parsePositivePid,
+  isPidAliveLocal: _isPidAliveLocal,
+  memoryServerPid: MEMORY_SERVER_PID,
+  log: __mixdogMemoryLog,
+})
+const { advertiseMemoryPort } = _memoryPortAdvertiser
 const MEMORY_DAEMON_MODE = process.env.MIXDOG_MEMORY_DAEMON === '1'
 const MEMORY_IDLE_TTL_MS = Math.max(0, Number(process.env.MIXDOG_MEMORY_IDLE_TTL_MS) || 10 * 60_000)
-let _idleShutdownTimer = null
-
-function touchDaemonIdleTimer(reason = 'activity') {
-  if (!MEMORY_DAEMON_MODE || MEMORY_IDLE_TTL_MS <= 0) return
-  if (_idleShutdownTimer) {
-    try { clearTimeout(_idleShutdownTimer) } catch {}
-    _idleShutdownTimer = null
-  }
-  _idleShutdownTimer = setTimeout(() => {
-    __mixdogMemoryLog(`[memory-service] daemon idle TTL elapsed after ${reason}; shutting down\n`)
-    stop()
-      .then(() => process.exit(0))
-      .catch((e) => {
-        __mixdogMemoryLog(`[memory-service] daemon idle shutdown failed: ${e?.message || e}\n`)
-        process.exit(1)
-      })
-  }, MEMORY_IDLE_TTL_MS)
-  _idleShutdownTimer.unref?.()
-}
-
-// ── Connected-client tracking + prompt shutdown ───────────────────────────
-// The daemon is shared by multiple proxy clients (TUI host + channels worker,
-// potentially several sessions). Each client registers/deregisters over HTTP
-// (see /client/register, /client/deregister in lib/http-router.mjs). When the
-// last client goes away we arm a short grace timer (default 10s) so a quick
-// reconnect keeps the daemon warm, but an actually-closed CLI reaps the daemon
-// in seconds instead of waiting out the 10-minute idle TTL (kept as backstop).
 const MEMORY_CLIENT_GRACE_MS = Math.max(0, Number(process.env.MIXDOG_MEMORY_CLIENT_GRACE_MS) || 10_000)
-const _connectedClients = new Map() // clientPid -> lastSeenMs
-let _everHadClient = false
-let _clientGraceTimer = null
-let _clientSweepTimer = null
-
-function _clientShutdownEnabled() {
-  return MEMORY_DAEMON_MODE && MEMORY_CLIENT_GRACE_MS > 0
-}
-
-function pruneDeadClients() {
-  for (const pid of [..._connectedClients.keys()]) {
-    if (!_isPidAliveLocal(pid)) _connectedClients.delete(pid)
-  }
-}
-
-function cancelClientGrace() {
-  if (_clientGraceTimer) {
-    try { clearTimeout(_clientGraceTimer) } catch {}
-    _clientGraceTimer = null
-  }
-}
-
-function armClientGrace(reason = 'last client gone') {
-  if (!_clientShutdownEnabled() || _clientGraceTimer) return
-  _clientGraceTimer = setTimeout(() => {
-    _clientGraceTimer = null
-    pruneDeadClients()
-    if (_connectedClients.size > 0) return
-    __mixdogMemoryLog(`[memory-service] daemon client grace elapsed (${reason}); shutting down\n`)
-    stop()
-      .then(() => process.exit(0))
-      .catch((e) => {
-        __mixdogMemoryLog(`[memory-service] daemon client-grace shutdown failed: ${e?.message || e}\n`)
-        process.exit(1)
-      })
-  }, MEMORY_CLIENT_GRACE_MS)
-  _clientGraceTimer.unref?.()
-}
-
-function startClientSweep() {
-  if (_clientSweepTimer || !_clientShutdownEnabled()) return
-  // Reap clients that died without deregistering so a crashed CLI still frees
-  // the daemon in grace-scale time rather than waiting for the idle TTL.
-  const interval = Math.max(1000, Math.min(MEMORY_CLIENT_GRACE_MS, 5000))
-  _clientSweepTimer = setInterval(() => {
-    pruneDeadClients()
-    if (_everHadClient && _connectedClients.size === 0) armClientGrace('all clients gone (sweep)')
-  }, interval)
-  _clientSweepTimer.unref?.()
-}
-
-function registerClient(clientPid) {
-  const pid = parsePositivePid(clientPid)
-  if (!pid) return true
-  // Reject registration once shutdown has begun. stop() sets _stopPromise
-  // synchronously (before its first await) and, in daemon mode, always ends
-  // in process.exit — so a daemon that is draining will never revive. Signal
-  // the proxy (via a distinct 503) to respawn a fresh daemon instead of
-  // binding to this dying one, which would fail the subsequent /api/tool.
-  if (_stopPromise) return false
-  _connectedClients.set(pid, Date.now())
-  _everHadClient = true
-  cancelClientGrace()
-  startClientSweep()
-  return true
-}
-
-function deregisterClient(clientPid) {
-  const pid = parsePositivePid(clientPid)
-  if (pid) _connectedClients.delete(pid)
-  pruneDeadClients()
-  if (_everHadClient && _connectedClients.size === 0) armClientGrace('last client deregistered')
-}
-
-function advertiseMemoryPort(boundPort, attempt = 0) {
-  if (!Number.isFinite(boundPort) || boundPort <= 0) return
-  // A fresh top-level advertise (attempt 0) supersedes any pending retry chain:
-  // last write wins, so a delayed retry never clobbers a newer boundPort.
-  if (attempt === 0) {
-    _currentAdvertisedPort = boundPort
-    _advertiseGeneration++
-    if (_advertiseRetryTimer) { try { clearTimeout(_advertiseRetryTimer) } catch {} ; _advertiseRetryTimer = null }
-  }
-  const generation = _advertiseGeneration
-  if (!_periodicAdvertiseInstalled) {
-    _periodicAdvertiseInstalled = true
-    _periodicAdvertiseTimer = setInterval(() => {
-      try {
-        if (_currentAdvertisedPort != null) {
-          advertiseMemoryPort(_currentAdvertisedPort)
-        }
-      } catch {}
-    }, 30_000)
-    _periodicAdvertiseTimer.unref?.()
-  }
-  try {
-    // Single-writer discovery file (discovery/memory.json), plain atomic rename
-    // with NO .lock: memory_port discovery can never be starved by the shared
-    // active-instance.json lock. Conflict guard preserved: a live OTHER memory
-    // owner advertising a different port is not clobbered.
-    const cur = _readServiceAdvert('memory')
-    const curMemPort = Number(cur?.port)
-    const curMemPid = parsePositivePid(cur?.pid)
-    const portConflict = Number.isFinite(curMemPort) && curMemPort > 0 && curMemPort !== boundPort
-    const otherOwnerAlive =
-      curMemPid != null &&
-      curMemPid !== MEMORY_SERVER_PID &&
-      _isPidAliveLocal(curMemPid)
-    if (portConflict && otherOwnerAlive) {
-      __mixdogMemoryLog(`[memory-service] skip memory_port advertise port=${boundPort} curMemPort=${curMemPort} curMemPid=${curMemPid} memoryServerPid=${MEMORY_SERVER_PID}\n`)
-      if (generation === _advertiseGeneration) _advertiseRetryTimer = null
-      return
-    }
-    _writeServiceAdvert('memory', {
-      port: boundPort,
-      ...(MEMORY_SERVER_PID ? { pid: MEMORY_SERVER_PID } : {}),
-    })
-    if (generation === _advertiseGeneration) _advertiseRetryTimer = null
-  } catch (e) {
-    // Boot path must not serially block on the default 8s lock wait: use a short
-    // lock timeout and treat lock contention/timeout as transient so pg_port /
-    // memory_port still eventually publish via unref'd, backed-off bg retries.
-    const transient =
-      e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES' ||
-      e?.code === 'ELOCKTIMEOUT' || e?.code === 'ELOCKCONTENDED'
-    if (transient && attempt < 5 && generation === _advertiseGeneration) {
-      const delay = Math.min(2000, 50 * 2 ** attempt)
-      // Fire-time generation re-check: even if clearTimeout was missed, a
-      // retry from a superseded chain must never republish an old boundPort.
-      _advertiseRetryTimer = setTimeout(() => {
-        if (generation !== _advertiseGeneration) return
-        advertiseMemoryPort(boundPort, attempt + 1)
-      }, delay)
-      _advertiseRetryTimer.unref?.()
-      return
-    }
-    __mixdogMemoryLog(`[memory-service] active-instance memory_port advertise failed: ${e?.message || e}\n`)
-  }
-}
+const _daemonLifecycle = createMemoryDaemonLifecycle({
+  daemonMode: MEMORY_DAEMON_MODE,
+  idleTtlMs: MEMORY_IDLE_TTL_MS,
+  clientGraceMs: MEMORY_CLIENT_GRACE_MS,
+  parsePositivePid,
+  isPidAlive: _isPidAliveLocal,
+  isStopping: () => _stopPromise != null,
+  stop,
+  log: __mixdogMemoryLog,
+})
+const { touchDaemonIdleTimer, registerClient, deregisterClient } = _daemonLifecycle
 
 const LOCK_FILE = path.join(DATA_DIR, '.memory-service.lock')
 // Owner-election lock. Separate from LOCK_FILE so single-instance mode keeps
@@ -853,27 +697,9 @@ export async function stop() {
   if (_stopPromise) return _stopPromise
   _stopPromise = (async () => {
     _stopCycles()
-    if (_periodicAdvertiseTimer) {
-      try { clearInterval(_periodicAdvertiseTimer) } catch {}
-      _periodicAdvertiseTimer = null
-    }
-    if (_advertiseRetryTimer) {
-      try { clearTimeout(_advertiseRetryTimer) } catch {}
-      _advertiseRetryTimer = null
-    }
-    _advertiseGeneration++
-    _periodicAdvertiseInstalled = false
-    _currentAdvertisedPort = null
+    _memoryPortAdvertiser.reset()
     _embeddingWarmup.reset()
-    if (_idleShutdownTimer) {
-      try { clearTimeout(_idleShutdownTimer) } catch {}
-      _idleShutdownTimer = null
-    }
-    cancelClientGrace()
-    if (_clientSweepTimer) {
-      try { clearInterval(_clientSweepTimer) } catch {}
-      _clientSweepTimer = null
-    }
+    _daemonLifecycle.reset()
     await stopLlmWorker()
     resetHttpListenErrorHandler()
     if (_httpBoundPort != null || _httpReadyPromise) {
@@ -1009,12 +835,14 @@ if (process.env.MIXDOG_WORKER_MODE === '1' && process.send) {
   // removes port file) then exit(0). Prevents taskkill /F from bypassing
   // graceful shutdown and leaving pgdata in an inconsistent checkpoint state.
   let _stopInFlight = false
+  let _syncPgStopRequested = false
   const _workerSignalHandler = (sig) => {
     if (_stopInFlight) {
       __mixdogMemoryLog(`[memory-worker] ${sig} — stop already in flight, ignoring\n`)
       return
     }
     _stopInFlight = true
+    _syncPgStopRequested = true
     __mixdogMemoryLog(`[memory-worker] received ${sig} — calling stop() for clean shutdown\n`)
     const _exitTimer = setTimeout(() => {
       __mixdogMemoryLog(`[memory-worker] stop() timed out after 6000ms — forcing exit(2)\n`)
@@ -1037,7 +865,14 @@ if (process.env.MIXDOG_WORKER_MODE === '1' && process.send) {
   // stop() path runs, orphaning PG mid-write. Best-effort sync pg_ctl stop on
   // exit (no-op after a completed graceful stop). Skip in secondary mode — we
   // do not own the shared PG there.
-  if (!memorySecondaryMode()) process.on('exit', () => { try { stopPgForShutdownSync() } catch {} })
+  if (!memorySecondaryMode()) process.on('exit', () => {
+    // Do not stop shared PG on an unexpected Memory crash. The singleton proxy
+    // will respawn a daemon that can attach to the still-healthy cluster. The
+    // sync stop is only a last resort after an explicit shutdown signal began.
+    if (_syncPgStopRequested) {
+      try { stopPgForShutdownSync() } catch {}
+    }
+  })
 
   // callId → AbortController for in-flight IPC calls (cancel handler uses this).
   const _inFlightCalls = new Map()
@@ -1112,9 +947,18 @@ if (IS_MEMORY_ENTRY && process.env.MIXDOG_WORKER_MODE !== '1') {
   ;(async () => {
     acquireLock()
     process.on('exit', releaseLock)
-    if (!memorySecondaryMode()) process.on('exit', () => { try { stopPgForShutdownSync() } catch {} })
-    process.on('SIGINT', () => { stop().finally(() => process.exit(0)) })
-    process.on('SIGTERM', () => { stop().finally(() => process.exit(0)) })
+    let syncPgStopRequested = false
+    if (!memorySecondaryMode()) process.on('exit', () => {
+      if (syncPgStopRequested) {
+        try { stopPgForShutdownSync() } catch {}
+      }
+    })
+    const stopFromSignal = () => {
+      syncPgStopRequested = true
+      stop().finally(() => process.exit(0))
+    }
+    process.on('SIGINT', stopFromSignal)
+    process.on('SIGTERM', stopFromSignal)
     await init()
     const transport = new StdioServerTransport()
     await mcp.connect(transport)

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

@@ -38,6 +38,7 @@ import {
 import { resolveProjectId, resolveProjectScope } from './project-id-resolver.mjs'
 import { resolvePluginData } from '../../shared/plugin-paths.mjs'
 import { getMetaValue, isBootstrapComplete } from './memory.mjs'
+import { createToolCallHandler } from './tool-call-handler.mjs'
 
 export function createMemoryActionHandlers({
   getDb,
@@ -879,59 +880,7 @@ export function createMemoryActionHandlers({
     return { text: `unknown memory action: ${action}`, isError: true }
   }
 
-  async function handleToolCall(name, args, signal) {
-    try {
-      if (name === 'search_memories') {
-        const result = await handleSearch(args || {}, signal)
-        return { ...result, content: [{ type: 'text', text: result.text }], isError: result.isError || false }
-      }
-      if (name === 'recall') {
-        // recall is aiWrapped in the unified build; in standalone mode map it to
-        // search_memories so the advertised tool name actually works. Forward
-        // every advertised arg so id/limit/offset/sort/includeArchived/
-        // includeMembers/includeRaw reach handleSearch instead of being dropped.
-        const a = args || {}
-        const hasQuery = Array.isArray(a.query)
-          ? a.query.some((value) => String(value || '').trim())
-          : String(a.query ?? '').trim() !== ''
-        const recallIds = hasQuery
-          ? []
-          : (Array.isArray(a.id) ? a.id : [a.id])
-              .map((value) => Number(value))
-              .filter((value) => Number.isInteger(value) && value > 0)
-        const searchArgs = {
-          ...(a.query !== undefined ? { query: a.query } : {}),
-          ...(recallIds.length > 0 ? { ids: recallIds } : {}),
-          ...(a.period ? { period: a.period } : {}),
-          ...(a.limit !== undefined ? { limit: a.limit } : {}),
-          ...(a.offset !== undefined ? { offset: a.offset } : {}),
-          ...(a.sort !== undefined ? { sort: a.sort } : {}),
-          ...(a.category !== undefined ? { category: a.category } : {}),
-          ...(a.includeArchived !== undefined ? { includeArchived: a.includeArchived } : {}),
-          ...(a.includeMembers !== undefined ? { includeMembers: a.includeMembers } : {}),
-          ...(a.includeRaw !== undefined ? { includeRaw: a.includeRaw } : {}),
-          ...(a.cwd ? { cwd: a.cwd } : {}),
-          ...(a.projectScope ? { projectScope: a.projectScope } : {}),
-          ...(a.sessionId ? { sessionId: a.sessionId } : {}),
-          ...(a.session_id ? { session_id: a.session_id } : {}),
-          ...(a.currentSession !== undefined ? { currentSession: a.currentSession } : {}),
-          // Hint only — never a filter. Marks the caller's own session as
-          // "(current)" in the multi-session grouped browse output.
-          ...(a.currentSessionId ? { currentSessionId: a.currentSessionId } : {}),
-        }
-        const result = await handleSearch(searchArgs, signal)
-        return { ...result, content: [{ type: 'text', text: result.text }], isError: result.isError || false }
-      }
-      if (name === 'memory') {
-        const result = await handleMemoryAction(args || {}, signal)
-        return { ...result, content: [{ type: 'text', text: result.text }], isError: result.isError || false }
-      }
-      return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      return { content: [{ type: 'text', text: `${name} failed: ${msg}` }], isError: true }
-    }
-  }
+  const handleToolCall = createToolCallHandler({ handleSearch, handleMemoryAction })
 
   return { handleMemoryAction, handleToolCall }
 }

package/src/runtime/memory/lib/memory-daemon-lifecycle.mjs

@@ -0,0 +1,115 @@
+// Idle and connected-client lifecycle for the shared memory daemon.
+// Timer and client state live here; the facade injects shutdown ownership.
+
+export function createMemoryDaemonLifecycle({
+  daemonMode,
+  idleTtlMs,
+  clientGraceMs,
+  parsePositivePid,
+  isPidAlive,
+  isStopping,
+  stop,
+  log,
+}) {
+  let _idleShutdownTimer = null
+  const _connectedClients = new Map()
+  let _everHadClient = false
+  let _clientGraceTimer = null
+  let _clientSweepTimer = null
+
+  function touchDaemonIdleTimer(reason = 'activity') {
+    if (!daemonMode || idleTtlMs <= 0) return
+    if (_idleShutdownTimer) {
+      try { clearTimeout(_idleShutdownTimer) } catch {}
+      _idleShutdownTimer = null
+    }
+    _idleShutdownTimer = setTimeout(() => {
+      log(`[memory-service] daemon idle TTL elapsed after ${reason}; shutting down\n`)
+      stop()
+        .then(() => process.exit(0))
+        .catch((e) => {
+          log(`[memory-service] daemon idle shutdown failed: ${e?.message || e}\n`)
+          process.exit(1)
+        })
+    }, idleTtlMs)
+    _idleShutdownTimer.unref?.()
+  }
+
+  function clientShutdownEnabled() {
+    return daemonMode && clientGraceMs > 0
+  }
+
+  function pruneDeadClients() {
+    for (const pid of [..._connectedClients.keys()]) {
+      if (!isPidAlive(pid)) _connectedClients.delete(pid)
+    }
+  }
+
+  function cancelClientGrace() {
+    if (_clientGraceTimer) {
+      try { clearTimeout(_clientGraceTimer) } catch {}
+      _clientGraceTimer = null
+    }
+  }
+
+  function armClientGrace(reason = 'last client gone') {
+    if (!clientShutdownEnabled() || _clientGraceTimer) return
+    _clientGraceTimer = setTimeout(() => {
+      _clientGraceTimer = null
+      pruneDeadClients()
+      if (_connectedClients.size > 0) return
+      log(`[memory-service] daemon client grace elapsed (${reason}); shutting down\n`)
+      stop()
+        .then(() => process.exit(0))
+        .catch((e) => {
+          log(`[memory-service] daemon client-grace shutdown failed: ${e?.message || e}\n`)
+          process.exit(1)
+        })
+    }, clientGraceMs)
+    _clientGraceTimer.unref?.()
+  }
+
+  function startClientSweep() {
+    if (_clientSweepTimer || !clientShutdownEnabled()) return
+    const interval = Math.max(1000, Math.min(clientGraceMs, 5000))
+    _clientSweepTimer = setInterval(() => {
+      pruneDeadClients()
+      if (_everHadClient && _connectedClients.size === 0) armClientGrace('all clients gone (sweep)')
+    }, interval)
+    _clientSweepTimer.unref?.()
+  }
+
+  function registerClient(clientPid) {
+    const pid = parsePositivePid(clientPid)
+    if (!pid) return true
+    if (isStopping()) return false
+    _connectedClients.set(pid, Date.now())
+    _everHadClient = true
+    cancelClientGrace()
+    startClientSweep()
+    return true
+  }
+
+  function deregisterClient(clientPid) {
+    const pid = parsePositivePid(clientPid)
+    if (pid) _connectedClients.delete(pid)
+    pruneDeadClients()
+    if (_everHadClient && _connectedClients.size === 0) armClientGrace('last client deregistered')
+  }
+
+  function reset() {
+    if (_idleShutdownTimer) {
+      try { clearTimeout(_idleShutdownTimer) } catch {}
+      _idleShutdownTimer = null
+    }
+    cancelClientGrace()
+    if (_clientSweepTimer) {
+      try { clearInterval(_clientSweepTimer) } catch {}
+      _clientSweepTimer = null
+    }
+    _connectedClients.clear()
+    _everHadClient = false
+  }
+
+  return { touchDaemonIdleTimer, registerClient, deregisterClient, reset }
+}

package/src/runtime/memory/lib/memory-port-advertiser.mjs

@@ -0,0 +1,105 @@
+// Memory service discovery advertisement lifecycle.
+// Owns the retry/periodic timer state so there is exactly one advertise chain.
+
+export function createMemoryPortAdvertiser({
+  readServiceAdvert,
+  writeServiceAdvert,
+  parsePositivePid,
+  isPidAliveLocal,
+  memoryServerPid,
+  log,
+}) {
+  let _periodicAdvertiseInstalled = false
+  let _periodicAdvertiseTimer = null
+  // Single module-level advertise retry chain. A newer advertiseMemoryPort call
+  // cancels the older chain so a delayed retry never replays a stale boundPort.
+  let _advertiseRetryTimer = null
+  let _advertiseGeneration = 0
+  // Track the most recently advertised port so the periodic tick re-reads it
+  // every interval. Without this the setInterval closure binds the FIRST port
+  // (the upstream we proxied to) and keeps re-advertising the dead upstream
+  // port after fork-proxy promotion swaps in our own locally-bound port.
+  let _currentAdvertisedPort = null
+
+  function advertiseMemoryPort(boundPort, attempt = 0) {
+    if (!Number.isFinite(boundPort) || boundPort <= 0) return
+    // A fresh top-level advertise (attempt 0) supersedes any pending retry chain:
+    // last write wins, so a delayed retry never clobbers a newer boundPort.
+    if (attempt === 0) {
+      _currentAdvertisedPort = boundPort
+      _advertiseGeneration++
+      if (_advertiseRetryTimer) { try { clearTimeout(_advertiseRetryTimer) } catch {} ; _advertiseRetryTimer = null }
+    }
+    const generation = _advertiseGeneration
+    if (!_periodicAdvertiseInstalled) {
+      _periodicAdvertiseInstalled = true
+      _periodicAdvertiseTimer = setInterval(() => {
+        try {
+          if (_currentAdvertisedPort != null) {
+            advertiseMemoryPort(_currentAdvertisedPort)
+          }
+        } catch {}
+      }, 30_000)
+      _periodicAdvertiseTimer.unref?.()
+    }
+    try {
+      // Single-writer discovery file (discovery/memory.json), plain atomic rename
+      // with NO .lock: memory_port discovery can never be starved by the shared
+      // active-instance.json lock. Conflict guard preserved: a live OTHER memory
+      // owner advertising a different port is not clobbered.
+      const cur = readServiceAdvert('memory')
+      const curMemPort = Number(cur?.port)
+      const curMemPid = parsePositivePid(cur?.pid)
+      const portConflict = Number.isFinite(curMemPort) && curMemPort > 0 && curMemPort !== boundPort
+      const otherOwnerAlive =
+        curMemPid != null &&
+        curMemPid !== memoryServerPid &&
+        isPidAliveLocal(curMemPid)
+      if (portConflict && otherOwnerAlive) {
+        log(`[memory-service] skip memory_port advertise port=${boundPort} curMemPort=${curMemPort} curMemPid=${curMemPid} memoryServerPid=${memoryServerPid}\n`)
+        if (generation === _advertiseGeneration) _advertiseRetryTimer = null
+        return
+      }
+      writeServiceAdvert('memory', {
+        port: boundPort,
+        ...(memoryServerPid ? { pid: memoryServerPid } : {}),
+      })
+      if (generation === _advertiseGeneration) _advertiseRetryTimer = null
+    } catch (e) {
+      // Boot path must not serially block on the default 8s lock wait: use a short
+      // lock timeout and treat lock contention/timeout as transient so pg_port /
+      // memory_port still eventually publish via unref'd, backed-off bg retries.
+      const transient =
+        e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES' ||
+        e?.code === 'ELOCKTIMEOUT' || e?.code === 'ELOCKCONTENDED'
+      if (transient && attempt < 5 && generation === _advertiseGeneration) {
+        const delay = Math.min(2000, 50 * 2 ** attempt)
+        // Fire-time generation re-check: even if clearTimeout was missed, a
+        // retry from a superseded chain must never republish an old boundPort.
+        _advertiseRetryTimer = setTimeout(() => {
+          if (generation !== _advertiseGeneration) return
+          advertiseMemoryPort(boundPort, attempt + 1)
+        }, delay)
+        _advertiseRetryTimer.unref?.()
+        return
+      }
+      log(`[memory-service] active-instance memory_port advertise failed: ${e?.message || e}\n`)
+    }
+  }
+
+  function reset() {
+    if (_periodicAdvertiseTimer) {
+      try { clearInterval(_periodicAdvertiseTimer) } catch {}
+      _periodicAdvertiseTimer = null
+    }
+    if (_advertiseRetryTimer) {
+      try { clearTimeout(_advertiseRetryTimer) } catch {}
+      _advertiseRetryTimer = null
+    }
+    _advertiseGeneration++
+    _periodicAdvertiseInstalled = false
+    _currentAdvertisedPort = null
+  }
+
+  return { advertiseMemoryPort, reset }
+}