mixdog 0.9.21 → 0.9.23

package/src/runtime/channels/lib/worker-main.mjs

@@ -67,6 +67,7 @@ import { createParentBridge } from "./parent-bridge.mjs";
 import { createInboundRouting } from "./inbound-routing.mjs";
 import { createToolDispatch } from "./tool-dispatch.mjs";
 import { createOwnerHeartbeat } from "./owner-heartbeat.mjs";
+import { createSeatLock } from "./seat-lock.mjs";
 import { createTranscriptBinding } from "./transcript-binding.mjs";
 import { isNetworkError, retryOnNetwork } from "./network-retry.mjs";
 import { runWorkerIpc } from "./worker-ipc.mjs";
@@ -138,6 +139,9 @@ let config = loadConfig();
 let backend = createBackend(config);
 const INSTANCE_ID = makeInstanceId();
 const TERMINAL_LEAD_PID = getTerminalLeadPid();
+// OS-enforced bridge-seat singleton. Ownership TRUTH is holding this listener;
+// a holder crash auto-releases it and takeover is an explicit release message.
+const seatLock = createSeatLock({ runtimeRoot: RUNTIME_ROOT, instanceId: INSTANCE_ID });
 runWorkerBootstrap({
   instanceId: INSTANCE_ID,
   isWorkerMode: _isWorkerMode,
@@ -324,13 +328,8 @@ const {
   logOwnership,
   currentOwnerState,
   getBridgeOwnershipSnapshot,
-  claimBridgeOwnership,
-  startOwnerHeartbeat,
-  stopOwnerHeartbeat,
 } = createOwnerHeartbeat({
-  getInstanceId: () => INSTANCE_ID,
-  readActiveInstance,
-  refreshActiveInstance,
+  isSeatHeld: () => seatLock.isSeatHeld(),
 });
 // ── Owned-runtime lifecycle ─────────────────────────────────────────────────
 // Extracted -> lib/owned-runtime.mjs. Owns its own start/stop/refresh in-flight
@@ -364,9 +363,10 @@ const {
   statusState,
   logOwnership,
   currentOwnerState,
-  claimBridgeOwnership,
-  startOwnerHeartbeat,
-  stopOwnerHeartbeat,
+  acquireSeat: (opts) => seatLock.acquireSeat(opts),
+  closeSeatServer: () => seatLock.closeSeatServer(),
+  isSeatHeld: () => seatLock.isSeatHeld(),
+  onTakeover: (cb) => seatLock.onTakeover(cb),
   bindPersistedTranscriptIfAny,
   cancelPendingTranscriptRearm,
   schedulePendingTranscriptRearm,
@@ -634,10 +634,38 @@ const {
     setChannelBridgeActive: (v) => { channelBridgeActive = v; },
     writeBridgeState,
     stopServerTyping,
-    claimBridgeOwnership,
     notifyRemoteAcquired,
     refreshBridgeOwnership,
     bindPersistedTranscriptIfAny,
+    // Lead-pushed repoint: bind the exact transcript the lead just created
+    // (auto-acquire / newSession / resume / clear) instead of waiting for the
+    // next inbound parent-chain steal. Idempotent + best-effort: same binding
+    // path as the inbound steal (rebindTranscriptContext -> applyTranscriptBinding).
+    rebindCurrentTranscript: async (transcriptPath) => {
+      const cleanPath = typeof transcriptPath === "string" ? transcriptPath.trim() : "";
+      if (!cleanPath) return;
+      const channelId = statusState.read().channelId || config.channelId;
+      if (!channelId) return;
+      // Fail-closed: a malformed / not-yet-on-disk path must NEVER fall through
+      // to rebindTranscriptContext's discovery loop (which would mutate the
+      // binding onto a different session). Only an existing regular file binds;
+      // otherwise log + return so the current binding is left untouched.
+      let exists = false;
+      try { exists = fs.statSync(cleanPath).isFile(); } catch { exists = false; }
+      if (!exists) {
+        process.stderr.write(`mixdog: rebind_current_transcript: ignoring non-existent path ${cleanPath}\n`);
+        return;
+      }
+      // Idempotent: already bound to this exact transcript => no-op. In
+      // particular do NOT re-run recoverUnsyncedTail, which is only meaningful
+      // when the binding actually changes.
+      if (forwarder.hasBinding() && sameResolvedPath(forwarder.transcriptPath, cleanPath)) return;
+      // Binding changed: same path as the inbound steal's applyTranscriptBinding.
+      applyTranscriptBinding(channelId, cleanPath, {
+        persistStatus: true,
+        recoverUnsyncedTail: true,
+      });
+    },
     stopOwnedRuntime,
     reloadRuntimeConfig,
   },
@@ -745,7 +773,10 @@ async function stop() {
   }
 }
 // ── IPC worker mode ──────────────────────────────────────────────
-if (_isWorkerMode && process.send) {
+// Skipped under the machine-global daemon (MIXDOG_CHANNEL_DAEMON=1): the
+// daemon entry (src/standalone/channel-daemon.mjs) drives start()/stop() and
+// its own HTTP+SSE transport instead of the parent node-IPC call/notify loop.
+if (_isWorkerMode && process.send && process.env.MIXDOG_CHANNEL_DAEMON !== '1') {
   runWorkerIpc({
     start,
     stop,

package/src/runtime/memory/index.mjs

@@ -134,6 +134,10 @@ const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
 
 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
@@ -248,7 +252,14 @@ function deregisterClient(clientPid) {
 
 function advertiseMemoryPort(boundPort, attempt = 0) {
   if (!Number.isFinite(boundPort) || boundPort <= 0) return
-  _currentAdvertisedPort = boundPort
+  // 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(() => {
@@ -284,12 +295,24 @@ function advertiseMemoryPort(boundPort, attempt = 0) {
         updatedAt: Date.now(),
       }
       return next
-    }, { compact: true, fsyncDir: true, renameFallback: 'truncate' })
+    }, { compact: true, fsyncDir: true, renameFallback: 'truncate', timeoutMs: 1000 })
+    if (generation === _advertiseGeneration) _advertiseRetryTimer = null
   } catch (e) {
-    const transient = e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES'
-    if (transient && attempt < 3) {
-      const retryTimer = setTimeout(() => advertiseMemoryPort(boundPort, attempt + 1), 50 * (attempt + 1))
-      retryTimer.unref?.()
+    // 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`)
@@ -454,10 +477,23 @@ async function _initStore() {
   if (dimsResolved) {
     primeEmbeddingDims(dimsResolved)
     assertSecondaryPgAttachable()
+    // Start embedding + kiwi warmup NOW so they run on their worker threads
+    // during the PG ensure I/O-wait window below: openDatabase spawns/awaits
+    // Postgres (I/O-bound, not CPU), so overlapping warmup there is safe and
+    // lands a cold boot's first recall dense instead of lexical-fallback.
+    // Both are fire-and-forget; the boot-complete fireDeferred/initKoMorph edge
+    // stays an idempotent no-op fallback. schedule() respects canStart
+    // (secondary/env-disabled skip → fireDeferred no-op); kiwi skips secondary.
+    _embeddingWarmup.schedule(EMBEDDING_META_PATH, metaKey)
+    memoryProfile('embedding:warmup:fire')
+    _embeddingWarmup.fireDeferred()
+    if (!memorySecondaryMode()) {
+      memoryProfile('ko-morph:warmup:fire')
+      initKoMorph(DATA_DIR, __mixdogMemoryLog).catch(() => {})
+    }
     const openStartedAt = performance.now()
     db = await openDatabase(DATA_DIR, dimsResolved)
     memoryProfile('open-db:done', { ms: (performance.now() - openStartedAt).toFixed(1), dims: dimsResolved })
-    _embeddingWarmup.schedule(EMBEDDING_META_PATH, metaKey)
   } else {
     if (!embeddingWarmupCanStart()) {
       throw new Error('memory-service: embedding dims unavailable while warmup is disabled')
@@ -469,6 +505,12 @@ async function _initStore() {
     memoryProfile('embedding:cold-warmup:done', { ms: (performance.now() - warmupStartedAt).toFixed(1) })
     dimsResolved = Number(getEmbeddingDims())
     assertSecondaryPgAttachable()
+    // Embedding is already warm (awaited above); still fire kiwi during the PG
+    // ensure I/O-wait so the first recall's FTS path is morph-aware too.
+    if (!memorySecondaryMode()) {
+      memoryProfile('ko-morph:warmup:fire')
+      initKoMorph(DATA_DIR, __mixdogMemoryLog).catch(() => {})
+    }
     const openStartedAt = performance.now()
     db = await openDatabase(DATA_DIR, dimsResolved)
     memoryProfile('open-db:done', { ms: (performance.now() - openStartedAt).toFixed(1), dims: dimsResolved })
@@ -798,6 +840,11 @@ export async function stop() {
       try { clearInterval(_periodicAdvertiseTimer) } catch {}
       _periodicAdvertiseTimer = null
     }
+    if (_advertiseRetryTimer) {
+      try { clearTimeout(_advertiseRetryTimer) } catch {}
+      _advertiseRetryTimer = null
+    }
+    _advertiseGeneration++
     _periodicAdvertiseInstalled = false
     _currentAdvertisedPort = null
     _embeddingWarmup.reset()

package/src/runtime/memory/lib/embedding-warmup.mjs

@@ -16,11 +16,16 @@ export function createEmbeddingWarmup({
   log = () => {},
 }) {
   let _pending = null
+  // Fired latch: an init() retry after the early (PG-wait-edge) fire must not
+  // re-schedule and run the warmup twice (double ONNX session create +
+  // double embedding-meta persist). reset() clears it for true re-inits.
+  let _fired = false
 
   // Queue the warmup; fireDeferred() runs it once boot completes. Re-queuing
   // overwrites any prior pending closure (matches the original single-slot
   // module var). MIXDOG_EMBED_WARMUP=0 (checked via canStart) disables it.
   function schedule(metaPath, metaKey) {
+    if (_fired) return
     if (!canStart()) {
       // Silent skip here previously made "warmup never ran" boots
       // indistinguishable from failed warmups. One line, boot-edge only.
@@ -50,11 +55,13 @@ export function createEmbeddingWarmup({
     const fire = _pending
     if (!fire) return
     _pending = null
+    _fired = true
     fire()
   }
 
   function reset() {
     _pending = null
+    _fired = false
   }
 
   return { schedule, fireDeferred, reset }

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

@@ -14,7 +14,7 @@ function __mixdogMemoryLog(...args) {
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { spawnSync } from 'child_process'
+import { spawn, spawnSync } from 'child_process'
 import { createConnection } from 'net'
 import { createServer } from 'net'
 
@@ -248,55 +248,100 @@ export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 554
 
   __mixdogMemoryLog(`[pg-process] pg_ctl start -D ${pgdataDir} -p ${port}\n`)
 
-  const r = spawnSync(pgctl, [
-    'start', '-w',
+  const pgIsReady = pgBin(runtimeDir, 'pg_isready')
+  const startArgs = [
+    'start',
     '-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`)
+  // 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() {
+    try {
+      const pidFile = join(pgdataDir, 'postmaster.pid')
+      if (!existsSync(pidFile)) return null
+      const lines  = readFileSync(pidFile, 'utf8').split('\n')
+      const pid    = parseInt(lines[0], 10)
+      const pmPort = parseInt(lines[3], 10)
+      if (pid > 0 && pmPort === port) return { pid }
+      return null
+    } catch { return null }
+  }
+
+  // pg_isready can succeed a beat before postmaster.pid is fully written; give
+  // it a brief window to appear (and confirm the port matches) before trusting.
+  async function confirmPid() {
+    for (let i = 0; i < 5; i++) {
+      const pm = readPostmaster()
+      if (pm) return pm.pid
+      await sleep(100)
+    }
+    return null
+  }
+
+  // Spawn pg_ctl asynchronously (no -w) and poll readiness ourselves. On
+  // AV-throttled boxes pg_ctl can lag ~30s behind actual postmaster readiness,
+  // so we return the instant pg_isready succeeds rather than waiting on pg_ctl.
+  // Only the long-lived child handle is unref'd; poll timers stay ref'd.
+  async function startAndWaitReady() {
+    const child = spawn(pgctl, startArgs, { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    child.unref?.()
+    let stdout = '', stderr = '', closed = false, exitCode = null
+    child.stdout?.on('data', d => { stdout += d.toString() })
+    child.stderr?.on('data', d => { stderr += d.toString() })
+    child.stdout?.unref?.(); child.stderr?.unref?.()
+    child.on('error', err => { closed = true; exitCode = -1; stderr += (err?.message || String(err)) })
+    // Use 'close' (stdio flushed), not 'exit', so captured stderr is complete
+    // and the "another server might be running" match below never truncates.
+    child.on('close', code => { closed = true; exitCode = code })
+
+    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) {
+        const pid = await confirmPid()
+        // pid confirmed with matching port → ready. Otherwise keep polling until
+        // the cap (postmaster.pid not yet written or port mismatch).
+        if (pid != null) return { ready: true, pid }
       }
+      // 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)
     }
-    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
+  const r = await startAndWaitReady()
+  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.
+  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`)
     }
-  } catch {}
+  }
 
-  return { pid, port }
+  const detail = errText || (r.timeout ? '(readiness probe timed out after 30s; no pg_ctl output)' : '(no captured output)')
+  throw new Error(`[pg-process] pg_ctl start failed: ${detail}`)
 }
 
 // ---------------------------------------------------------------------------

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

@@ -182,24 +182,85 @@ const _RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
   : join(tmpdir(), 'mixdog');
 const _ACTIVE_FILE = join(_RUNTIME_ROOT, 'active-instance.json');
 
-function patchActiveInstance(fields) {
+// Lock contention codes thrown by withFileLockSync when the active-instance
+// lock cannot be acquired within timeoutMs (or try-once contention).
+const _LOCK_CONTENTION_CODES = new Set(['ELOCKTIMEOUT', 'ELOCKCONTENDED']);
+
+function _applyActiveInstancePatch(fields, timeoutMs) {
+  updateJsonAtomicSync(_ACTIVE_FILE, (curRaw) => {
+    // Drop stale fields (pid/startedAt) written by older server versions.
+    const { pid: _legacyPid, startedAt: _legacyStartedAt, ...cur } = curRaw ?? {};
+    // Omit null-valued fields (clean removal when pg is stopped).
+    const merged = { ...cur, updatedAt: Date.now() };
+    for (const [k, v] of Object.entries(fields)) {
+      if (v == null) delete merged[k];
+      else merged[k] = v;
+    }
+    return merged;
+  }, { compact: true, fsyncDir: true, renameFallback: 'truncate', timeoutMs });
+}
+
+// Single module-level background-retry slot: a delayed retry must NEVER replay
+// stale `fields` over newer state (e.g. a stale clear deleting a fresh pg_port,
+// or a stale start resurrecting pg_port after shutdown). Every patch bumps the
+// generation and cancels any pending chain, so only the newest fields replay.
+let _patchGeneration = 0;
+let _pendingPatchRetry = null; // { timer, generation }
+
+function _cancelPendingPatchRetry() {
+  if (_pendingPatchRetry) {
+    try { clearTimeout(_pendingPatchRetry.timer); } catch {}
+    _pendingPatchRetry = null;
+  }
+}
+
+function _tryPatchInBackground(fields, timeoutMs, generation, attempt) {
+  // A newer patch has superseded this chain — abandon (last write wins).
+  if (generation !== _patchGeneration) return;
   try {
-    updateJsonAtomicSync(_ACTIVE_FILE, (curRaw) => {
-      // Drop stale fields (pid/startedAt) written by older server versions.
-      const { pid: _legacyPid, startedAt: _legacyStartedAt, ...cur } = curRaw ?? {};
-      // Omit null-valued fields (clean removal when pg is stopped).
-      const merged = { ...cur, updatedAt: Date.now() };
-      for (const [k, v] of Object.entries(fields)) {
-        if (v == null) delete merged[k];
-        else merged[k] = v;
-      }
-      return merged;
-    }, { compact: true, fsyncDir: true, renameFallback: 'truncate' });
+    _applyActiveInstancePatch(fields, timeoutMs);
+    if (_pendingPatchRetry?.generation === generation) _pendingPatchRetry = null;
   } catch (e) {
+    if (_LOCK_CONTENTION_CODES.has(e?.code) && attempt < 5) {
+      const delay = Math.min(2000, 100 * 2 ** attempt);
+      const timer = setTimeout(
+        () => _tryPatchInBackground(fields, timeoutMs, generation, attempt + 1),
+        delay,
+      );
+      timer.unref?.();
+      _pendingPatchRetry = { timer, generation };
+      return;
+    }
+    if (_pendingPatchRetry?.generation === generation) _pendingPatchRetry = null;
     __mixdogMemoryLog(`[supervisor-pg] patchActiveInstance failed: ${e?.message}\n`);
   }
 }
 
+// Boot-path advertise writes (pg_port et al.) must never serially block init on
+// the 8s default lock wait. Callers pass { timeoutMs, background, syncRetries }:
+//   background:true  — short lock timeout; on contention schedule unref'd,
+//                      backed-off, bounded bg retries of the NEWEST fields only.
+//   background:false — synchronous best-effort with `syncRetries` extra sync
+//                      attempts on lock timeout (shutdown clear path).
+function patchActiveInstance(fields, opts = {}) {
+  const { timeoutMs = 8000, background = false, syncRetries = 0 } = opts;
+  // Supersede any in-flight background retry: last write wins per process.
+  _patchGeneration++;
+  _cancelPendingPatchRetry();
+  if (background) {
+    _tryPatchInBackground(fields, timeoutMs, _patchGeneration, 0);
+    return;
+  }
+  for (let i = 0; ; i++) {
+    try { _applyActiveInstancePatch(fields, timeoutMs); return; }
+    catch (e) {
+      if (_LOCK_CONTENTION_CODES.has(e?.code) && i < syncRetries) continue;
+      __mixdogMemoryLog(`[supervisor-pg] patchActiveInstance failed: ${e?.message}\n`);
+      return;
+    }
+  }
+}
+
 // ── postmaster.pid helpers ───────────────────────────────────────────────────
 
 function readPostmasterPid(pgdata) {
@@ -276,7 +337,7 @@ async function _startFresh(dataDir, pgdata, port, runtimeDir) {
   patchActiveInstance({
     pg_port: actualPort, pg_started_at: Date.now(),
     pg_pgdata: pgdata, pg_runtime_dir: runtimeDir,
-  });
+  }, { timeoutMs: 1000, background: true });
   __mixdogMemoryLog(`[supervisor-pg] ${proc?.attached ? 'attached to' : 'started'} PG port=${actualPort} pgdata=${pgdata}\n`);
   return { host: '127.0.0.1', port: actualPort, runtimeDir, pgdataDir };
 }
@@ -314,7 +375,7 @@ async function tryReusePgInstance({ pgdata, runtimeDir, healthcheckPg, source =
           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 };
       }
     } catch {}
@@ -429,7 +490,7 @@ async function _doEnsure(dataDir) {
         try { unlinkSync(join(pgdata, 'postmaster.pid')); } catch {}
       }
       // Clear stale pg fields before restart
-      patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null });
+      patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null }, { timeoutMs: 1000, background: true });
     }
 
     // ── Allocate a fresh port and spawn ───────────────────────────────────
@@ -490,7 +551,9 @@ export async function stopPgForShutdown() {
     } catch (e) {
       __mixdogMemoryLog(`[supervisor-pg] stopPg error on shutdown (no _live): ${e?.message}\n`);
     }
-    patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null });
+    // Bounded sync clear (<=4s: 2s + one 2s retry). A residual stale pg_port is
+    // tolerated — readers healthcheck-verify the port before reuse.
+    patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null }, { timeoutMs: 2000, syncRetries: 1 });
     return;
   }
   const snap = _live;
@@ -503,5 +566,7 @@ export async function stopPgForShutdown() {
   } catch (e) {
     __mixdogMemoryLog(`[supervisor-pg] stopPg error on shutdown: ${e?.message}\n`);
   }
-  patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null });
+  // Bounded sync clear (<=4s: 2s + one 2s retry). A residual stale pg_port is
+  // tolerated — readers healthcheck-verify the port before reuse.
+  patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null }, { timeoutMs: 2000, syncRetries: 1 });
 }

package/src/runtime/shared/atomic-file.mjs

@@ -38,6 +38,22 @@ function sleepSync(ms) {
   }
 }
 
+// Best-effort holder snapshot for lock-failure diagnostics: pid/token/age
+// read from the lock file AT THROW TIME, so ELOCKTIMEOUT/ELOCKCONTENDED
+// messages identify the culprit without needing a live repro. Never throws.
+function _describeLockHolder(lockPath) {
+  try {
+    const st = statSync(lockPath);
+    const owner = _readLockOwner(lockPath);
+    const ageMs = Math.max(0, Math.round(Date.now() - st.mtimeMs));
+    const live = owner.pid === null ? 'unknown' : (_ownerIsLive(owner) ? 'live' : 'dead');
+    const token = owner.token === null ? '?' : String(owner.token).slice(0, 8);
+    return `holder pid=${owner.pid ?? '?'} token=${token} age=${ageMs}ms ${live}`;
+  } catch {
+    return 'holder unknown (lock file unreadable/absent)';
+  }
+}
+
 export function renameWithRetrySync(src, dst, opts = {}) {
   const backoffs = Array.isArray(opts.backoffs) && opts.backoffs.length > 0
     ? opts.backoffs
@@ -76,7 +92,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
       // the main loop is never blocked by Atomics.wait. No stale-reclaim,
       // since reclaim would require waiting on the guard.
       if (timeoutMs <= 0) {
-        const contErr = new Error(`atomic lock contended (try-once): ${lockPath}`);
+        const contErr = new Error(`atomic lock contended (try-once): ${lockPath} [${_describeLockHolder(lockPath)}]`);
         contErr.code = 'ELOCKCONTENDED';
         contErr.cause = err;
         throw contErr;
@@ -118,7 +134,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
       } catch {}
     }
   }
-  const timeoutErr = new Error(`atomic lock timeout after ${timeoutMs}ms: ${lockPath}`);
+  const timeoutErr = new Error(`atomic lock timeout after ${timeoutMs}ms: ${lockPath} [${_describeLockHolder(lockPath)}]`);
   timeoutErr.code = 'ELOCKTIMEOUT';
   timeoutErr.cause = lastErr;
   throw timeoutErr;
@@ -278,8 +294,24 @@ function _reclaimGuardMatchesToken(guardPath, token) {
   }
 }
 
-function _unlinkReclaimGuardIfPidMatches(guardPath, pid) {
-  if (_readLockOwnerPid(guardPath) !== pid) return false;
+function _readGuardContent(guardPath) {
+  try { return readFileSync(guardPath, 'utf8'); } catch { return null; }
+}
+
+function _parseStampPid(raw) {
+  if (raw === null) return null;
+  const tok = String(raw).trim().split(/\s+/)[0];
+  const pid = Number.parseInt(tok, 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+// Unlink the guard only if its FULL content (pid ts token) is still the
+// exact content the stale/dead decision was made against. A regenerated
+// guard — even one whose pid was recycled to the same value (same-pid
+// ABA) — carries a fresh ts+token and therefore never matches, so a
+// fresh guard is never removed by a stale decision.
+function _unlinkReclaimGuardIfContentMatches(guardPath, content) {
+  if (_readGuardContent(guardPath) !== content) return false;
   try { unlinkSync(guardPath); return true; } catch { return false; }
 }
 
@@ -289,10 +321,12 @@ function _unlinkUnreadableStaleReclaimGuard(guardPath, staleMs) {
 }
 
 function _tryClearStaleReclaimGuard(guardPath, staleMs) {
-  const guardPid = _readLockOwnerPid(guardPath);
+  const guardContent = _readGuardContent(guardPath);
+  const guardPid = _parseStampPid(guardContent);
   if (guardPid !== null) {
-    // Re-read the guard immediately before unlinking so a regenerated
-    // guard with a different owner is not removed by a stale decision.
+    // Re-read the guard's full content immediately before unlinking so a
+    // regenerated guard (different owner OR same-pid ABA) is not removed
+    // by a stale decision.
     // This is still not a serialized primitive: correctness comes from
     // the lockPath owner-token reverify before unlinking lockPath, not
     // from making guard cleanup itself authoritative.
@@ -304,7 +338,7 @@ function _tryClearStaleReclaimGuard(guardPath, staleMs) {
     let guardStale = false;
     try { guardStale = Date.now() - statSync(guardPath).mtimeMs > staleMs; } catch {}
     if (_pidIsDead(guardPid) || guardStale) {
-      _unlinkReclaimGuardIfPidMatches(guardPath, guardPid);
+      _unlinkReclaimGuardIfContentMatches(guardPath, guardContent);
     }
     return;
   }
@@ -365,7 +399,7 @@ export async function withFileLock(lockPath, fn, opts = {}) {
       lastErr = err;
       if (!LOCK_WAIT_CODES.has(err?.code)) throw err;
       if (timeoutMs <= 0) {
-        const contErr = new Error(`atomic lock contended (try-once): ${lockPath}`);
+        const contErr = new Error(`atomic lock contended (try-once): ${lockPath} [${_describeLockHolder(lockPath)}]`);
         contErr.code = 'ELOCKCONTENDED';
         contErr.cause = err;
         throw contErr;
@@ -394,7 +428,7 @@ export async function withFileLock(lockPath, fn, opts = {}) {
       } catch {}
     }
   }
-  const timeoutErr = new Error(`atomic lock timeout after ${timeoutMs}ms: ${lockPath}`);
+  const timeoutErr = new Error(`atomic lock timeout after ${timeoutMs}ms: ${lockPath} [${_describeLockHolder(lockPath)}]`);
   timeoutErr.code = 'ELOCKTIMEOUT';
   timeoutErr.cause = lastErr;
   throw timeoutErr;