fix: auto-create sessions DB on first use + atomic state file writes

Two fixes for CI workflow failures:

1. history/_connection.py: _connect() now creates sessions.db and runs
   migrations when the file doesn't exist, instead of returning None.
   This fixes all 60+ UAT test timeouts on fresh CI runners where no
   DB existed. Follows the same self-healing pattern as review_db.py.

2. session_state.py: write_session_state() now uses a threading.Lock
   around the read-merge-write cycle and writes via temp file +
   os.replace() for atomic file replacement. Fixes the sidebar
   test_p_toggles_pause race condition where the poll thread and
   pause action could produce concatenated JSON objects.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: NetDevAutomate

packages/studyctl/src/studyctl/history/_connection.py

@@ -1,25 +1,53 @@
-"""Shared database connection helpers for the history package."""
+"""Shared database connection helpers for the history package.
+
+Auto-creates the sessions DB and applies migrations on first use,
+so ``studyctl study`` works on a fresh machine without ``studyctl doctor``
+or any other bootstrap step.
+"""
 
 from __future__ import annotations
 
+import logging
 import sqlite3
-from typing import TYPE_CHECKING
 
 from ..settings import load_settings
 
-if TYPE_CHECKING:
-    from pathlib import Path
+logger = logging.getLogger(__name__)
 
 
-def _find_db() -> Path | None:
-    db = load_settings().session_db
-    return db if db.exists() else None
+def _get_db_path():
+    """Return the configured sessions DB path (always a Path, never None)."""
+    return load_settings().session_db
 
 
 def _connect() -> sqlite3.Connection | None:
-    db = _find_db()
-    if not db:
-        return None
+    """Open a connection to sessions.db, creating it if necessary.
+
+    On first use the file and all tables are created via the
+    agent-session-tools migration chain.  Returns ``None`` only if
+    the migration import is unavailable (agent-session-tools not
+    installed).
+    """
+    db = _get_db_path()
+    db.parent.mkdir(parents=True, exist_ok=True)
+
+    is_new = not db.exists()
     conn = sqlite3.connect(db, timeout=5)
     conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+
+    if is_new:
+        try:
+            from agent_session_tools.migrations import migrate
+
+            migrate(conn)
+            logger.info("Created sessions DB at %s", db)
+        except ImportError:
+            logger.debug("agent-session-tools not installed — skipping migrations")
+        except Exception:
+            logger.exception("Failed to initialise sessions DB")
+            conn.close()
+            return None
+
     return conn

packages/studyctl/src/studyctl/session_state.py

@@ -8,6 +8,7 @@
 
 import json
 import os
+import threading
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -51,18 +52,33 @@ def _ensure_session_dir() -> None:
 
 
 def _write_file_secure(path: Path, content: str) -> None:
-    """Write content to a file with 0600 permissions (owner-only read/write)."""
-    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    """Write content atomically with 0600 permissions.
+
+    Writes to a temp file then replaces the target, preventing partial
+    reads and the truncation race where two concurrent O_TRUNC opens
+    leave trailing bytes from the longer write.
+    """
+    tmp = str(path) + ".tmp"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
     with os.fdopen(fd, "w") as f:
         f.write(content)
+    os.replace(tmp, str(path))
+
+
+_state_lock = threading.Lock()
 
 
 def write_session_state(updates: dict) -> None:
-    """Atomic read-merge-write of session state. Creates file if missing."""
+    """Atomic read-merge-write of session state. Creates file if missing.
+
+    Thread-safe: a lock serialises concurrent updates from the poll
+    thread and action handlers to prevent read-merge-write clobbering.
+    """
     _ensure_session_dir()
-    current = read_session_state()
-    current.update(updates)
-    _write_file_secure(STATE_FILE, json.dumps(current, indent=2, default=str))
+    with _state_lock:
+        current = read_session_state()
+        current.update(updates)
+        _write_file_secure(STATE_FILE, json.dumps(current, indent=2, default=str))
 
 
 def parse_topics_file() -> list[TopicEntry]:

packages/studyctl/tests/test_cli.py

@@ -1,9 +1,9 @@
 """Tests for studyctl CLI commands using Click's CliRunner.
 
 Strategy: Most commands depend on history functions that need a live sessions.db.
-We monkeypatch `studyctl.history._find_db` to return None, which makes `_connect()`
-return None, and each history function returns its empty/default sentinel.
-Commands are designed to handle this gracefully with user-friendly messages.
+We monkeypatch `_connect` to return None, and each history function returns its
+empty/default sentinel.  Commands are designed to handle this gracefully with
+user-friendly messages.
 
 Note on `review`: With no DB, `spaced_repetition_due` still returns entries for
 configured topics (marked "New topic") because `last_studied()` returns None when
@@ -35,7 +35,7 @@ def _no_db(monkeypatch: pytest.MonkeyPatch) -> None:
     """Ensure no real database is ever touched during CLI tests."""
     import studyctl.history._connection as _conn
 
-    monkeypatch.setattr(_conn, "_find_db", lambda: None)
+    monkeypatch.setattr(_conn, "_connect", lambda: None)
 
 
 # ---------------------------------------------------------------------------

packages/studyctl/tests/test_cli_session.py

@@ -49,11 +49,9 @@ def session_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     conn.close()
 
     # Patch DB path for history, parking, and settings modules.
-    # history.py uses _find_db() → load_settings().session_db → checks .exists()
-    # so we must patch _find_db directly to return the test DB path.
     monkeypatch.setattr("studyctl.settings.get_db_path", lambda: db_path)
     monkeypatch.setattr("studyctl.parking.get_db_path", lambda: db_path)
-    monkeypatch.setattr("studyctl.history._connection._find_db", lambda: db_path)
+    monkeypatch.setattr("studyctl.history._connection._get_db_path", lambda: db_path)
 
     # Patch session state paths to use temp dir
     session_dir = tmp_path / "session"

packages/studyctl/tests/test_history.py

@@ -146,7 +146,7 @@ def test_no_db_candidates_attribute(self):
             "_DB_CANDIDATES should not exist — load_settings() must not be called at import time"
         )
 
-    def test_find_db_uses_settings(self, tmp_path, monkeypatch):
+    def test_get_db_path_uses_settings(self, tmp_path, monkeypatch):
         db_path = tmp_path / "sessions.db"
         db_path.touch()
 
@@ -158,7 +158,7 @@ class FakeSettings:
 
         monkeypatch.setattr(_conn, "load_settings", lambda: FakeSettings())
 
-        result = _conn._find_db()
+        result = _conn._get_db_path()
         assert result == db_path