fix(kanban): serialize DB initialization

hermes_cli/kanban_db.py

@@ -78,6 +78,7 @@ import secrets
 import sqlite3
 import subprocess
 import sys
+import threading
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -899,6 +900,7 @@ CREATE INDEX IF NOT EXISTS idx_notify_task           ON kanban_notify_subs(task_
 # ---------------------------------------------------------------------------
 
 _INITIALIZED_PATHS: set[str] = set()
+_INIT_LOCK = threading.RLock()
 
 
 def connect(
@@ -930,23 +932,30 @@ def connect(
         path = kanban_db_path(board=board)
     path.parent.mkdir(parents=True, exist_ok=True)
     resolved = str(path.resolve())
-    needs_init = resolved not in _INITIALIZED_PATHS
     conn = sqlite3.connect(str(path), isolation_level=None, timeout=30)
     conn.row_factory = sqlite3.Row
-    # WAL doesn't work on network filesystems (NFS/SMB/FUSE).  Shared helper
-    # falls back to DELETE with one WARNING so kanban stays usable there.
-    # See hermes_state._WAL_INCOMPAT_MARKERS for detection logic.
-    from hermes_state import apply_wal_with_fallback
-    apply_wal_with_fallback(conn, db_label=f"kanban.db ({path.name})")
-    conn.execute("PRAGMA synchronous=NORMAL")
-    conn.execute("PRAGMA foreign_keys=ON")
-    if needs_init:
-        # Idempotent: runs CREATE TABLE IF NOT EXISTS + the additive
-        # migrations. Cached so subsequent connect() calls in the same
-        # process are cheap.
-        conn.executescript(SCHEMA_SQL)
-        _migrate_add_optional_columns(conn)
-        _INITIALIZED_PATHS.add(resolved)
+    with _INIT_LOCK:
+        # WAL activation can take an exclusive lock while SQLite creates the
+        # sidecar files for a fresh database. Keep it in the same process-local
+        # critical section as schema initialization so concurrent gateway
+        # startup threads do not race before _INITIALIZED_PATHS is populated.
+        # WAL doesn't work on network filesystems (NFS/SMB/FUSE). Shared helper
+        # falls back to DELETE with one WARNING so kanban stays usable there.
+        # See hermes_state._WAL_INCOMPAT_MARKERS for detection logic.
+        from hermes_state import apply_wal_with_fallback
+        apply_wal_with_fallback(conn, db_label=f"kanban.db ({path.name})")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        conn.execute("PRAGMA foreign_keys=ON")
+        needs_init = resolved not in _INITIALIZED_PATHS
+        if needs_init:
+            # Idempotent: runs CREATE TABLE IF NOT EXISTS + the additive
+            # migrations. Cached so subsequent connect() calls in the same
+            # process are cheap. The lock prevents same-process dispatcher
+            # threads from racing through the additive ALTER TABLE pass with
+            # stale PRAGMA snapshots during gateway startup.
+            conn.executescript(SCHEMA_SQL)
+            _migrate_add_optional_columns(conn)
+            _INITIALIZED_PATHS.add(resolved)
     return conn
 
 
@@ -973,7 +982,8 @@ def init_db(
     resolved = str(path.resolve())
     # Clear the cache entry so the underlying connect() re-runs the
     # schema + migration pass unconditionally.
-    _INITIALIZED_PATHS.discard(resolved)
+    with _INIT_LOCK:
+        _INITIALIZED_PATHS.discard(resolved)
     with contextlib.closing(connect(path)):
         pass
     return path