studyctl 2.2.0__tar.gz → 2.3.0__tar.gz

{studyctl-2.2.0 → studyctl-2.3.0}/.gitignore

@@ -500,6 +500,7 @@ eval-results.tsv
 .pytest-junit.xml
 docs/reports/
 docs/brainstorms/
+packages/studyctl/tests/results/
 
 # Dev-only tooling (autoresearch eval harness — not shipped to users)
 dev/

{studyctl-2.2.0 → studyctl-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: studyctl
-Version: 2.2.0
+Version: 2.3.0
 Summary: AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline
 Project-URL: Homepage, https://github.com/NetDevAutomate/socratic-study-mentor
 Project-URL: Repository, https://github.com/NetDevAutomate/socratic-study-mentor

{studyctl-2.2.0 → studyctl-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "studyctl"
-version = "2.2.0"
+version = "2.3.0"
 description = "AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline"
 requires-python = ">=3.12"
 readme = "README.md"

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/cli/_study.py

@@ -616,7 +616,7 @@ def _handle_start(
         start_web_background(session_name, lan=lan, password=lan_password)
 
     # Start ttyd if installed (allows iPad/LAN terminal access)
-    start_ttyd_background(session_name, lan=lan)
+    start_ttyd_background(session_name, lan=lan, username=lan_username, password=lan_password)
 
     # Persist LAN info to session state so it's visible after os.execvp
     if lan:

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/session/cleanup.py

@@ -140,11 +140,12 @@ def end_session_common(
         oneline.unlink()
 
     # Kill background processes (web dashboard, ttyd).
-    # Verify PID identity before killing to guard against PID recycling:
-    # if the process exited and its PID was reused by an unrelated process,
-    # we'd kill the wrong thing.
+    # Strategy: kill by PID first (fast), then by port as fallback
+    # to catch processes started by a different code path.
     import subprocess as _sp
 
+    # PID-based kill — check command matches to guard against PID recycling.
+    # "studyctl" matches both the binary and "python -m studyctl.cli".
     pid_checks = {"web_pid": "studyctl", "ttyd_pid": "ttyd"}
     for pid_key, expected in pid_checks.items():
         pid = state.get(pid_key)
@@ -162,6 +163,16 @@ def end_session_common(
         except (OSError, _sp.TimeoutExpired):
             pass
 
+    # Port-based kill — fallback for orphaned processes whose PIDs we lost.
+    from studyctl.session.orchestrator import _kill_port_occupant
+
+    ttyd_port = state.get("ttyd_port")
+    if ttyd_port:
+        _kill_port_occupant(int(ttyd_port), expected_cmd="ttyd")
+    web_port = state.get("web_port")
+    if web_port:
+        _kill_port_occupant(int(web_port), expected_cmd="studyctl")
+
     # Kill all study tmux sessions
     with contextlib.suppress(Exception):
         kill_all_study_sessions(current_session=session_name)

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/session/orchestrator.py

@@ -237,6 +237,9 @@ def start_web_background(session_name: str, *, lan: bool = False, password: str
 
     port = _get_web_port()
 
+    # Kill any stale web server left over from a previous session
+    _kill_port_occupant(port, expected_cmd="studyctl")
+
     studyctl_bin = shutil.which("studyctl")
     cmd = (
         [studyctl_bin, "web", "--port", str(port)]
@@ -255,12 +258,53 @@ def start_web_background(session_name: str, *, lan: bool = False, password: str
         )
         from studyctl.session_state import write_session_state
 
-        write_session_state({"web_pid": proc.pid})
+        write_session_state({"web_pid": proc.pid, "web_port": port})
         _open_browser(f"http://127.0.0.1:{port}/session")
     except Exception:
         console.print("[yellow]Could not start web dashboard.[/yellow]")
 
 
+def _kill_port_occupant(port: int, expected_cmd: str = "") -> None:
+    """Kill any process listening on *port*.
+
+    If *expected_cmd* is given, only kill when the process command contains
+    that string (safety guard against killing unrelated processes).
+    """
+    import signal
+    import time as _time
+
+    killed = False
+    try:
+        result = subprocess.run(
+            ["lsof", "-ti", f":{port}"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if not result.stdout.strip():
+            return
+        for pid_str in result.stdout.strip().splitlines():
+            pid = int(pid_str)
+            if expected_cmd:
+                ps_result = subprocess.run(
+                    ["ps", "-p", str(pid), "-o", "command="],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if expected_cmd not in ps_result.stdout:
+                    continue
+            with __import__("contextlib").suppress(OSError):
+                os.kill(pid, signal.SIGTERM)
+                killed = True
+    except (subprocess.TimeoutExpired, ValueError, OSError):
+        pass
+
+    # Wait for the port to be released after killing
+    if killed:
+        _time.sleep(0.5)
+
+
 def _get_web_port() -> int:
     """Read web port from config, default 8567."""
     try:
@@ -339,10 +383,18 @@ def _get_ttyd_port() -> int:
         return 7681
 
 
-def start_ttyd_background(session_name: str, *, lan: bool = False) -> None:
+def start_ttyd_background(
+    session_name: str,
+    *,
+    lan: bool = False,
+    username: str = "",
+    password: str = "",
+) -> None:
     """Start ttyd to expose the tmux session over HTTP.
 
     Attaches a writable ttyd client to the study tmux session.
+    When credentials are provided, passes ``-c username:password``
+    so ttyd enforces HTTP Basic Auth on direct connections.
     Skips silently if ttyd is not installed.
     """
     from studyctl.session_state import write_session_state
@@ -354,6 +406,9 @@ def start_ttyd_background(session_name: str, *, lan: bool = False) -> None:
     host = "0.0.0.0" if lan else "127.0.0.1"
     port = _get_ttyd_port()
 
+    # Kill any stale ttyd left over from a previous session
+    _kill_port_occupant(port, expected_cmd="ttyd")
+
     cmd = [
         ttyd_bin,
         "-W",  # writable (user interacts with the agent)
@@ -361,12 +416,21 @@ def start_ttyd_background(session_name: str, *, lan: bool = False) -> None:
         host,
         "-p",
         str(port),
-        "tmux",
-        "attach",
-        "-t",
-        session_name,
     ]
 
+    # Enforce auth on ttyd when credentials are available
+    if username and password:
+        cmd.extend(["-c", f"{username}:{password}"])
+
+    cmd.extend(
+        [
+            "tmux",
+            "attach",
+            "-t",
+            session_name,
+        ]
+    )
+
     try:
         proc = subprocess.Popen(
             cmd,

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/session_state.py

@@ -13,7 +13,7 @@ import threading
 from dataclasses import dataclass
 from pathlib import Path
 
-SESSION_DIR = Path.home() / ".config" / "studyctl"
+SESSION_DIR = Path(os.environ.get("STUDYCTL_SESSION_DIR", Path.home() / ".config" / "studyctl"))
 STATE_FILE = SESSION_DIR / "session-state.json"
 TOPICS_FILE = SESSION_DIR / "session-topics.md"
 PARKING_FILE = SESSION_DIR / "session-parking.md"

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/settings.py

@@ -103,6 +103,16 @@ class LocalLLMConfig:
     base_url: str = ""
 
 
+@dataclass
+class PomodoroConfig:
+    """Configuration for the Pomodoro timer (web UI + TUI sidebar)."""
+
+    focus: int = 25  # minutes
+    short_break: int = 5
+    long_break: int = 15
+    cycles: int = 4  # long break after this many focus blocks
+
+
 @dataclass
 class AgentsConfig:
     """Configuration for AI agent detection and priority."""
@@ -143,6 +153,7 @@ class Settings:
     ttyd_port: int = 7681
     web_port: int = 8567
     browser: str = ""  # empty = system default; or "chrome", "safari", "firefox", "brave"
+    pomodoro: PomodoroConfig = field(default_factory=PomodoroConfig)
     lan_username: str = "study"  # username for HTTP Basic Auth when using --lan
     lan_password: str = ""  # password for HTTP Basic Auth when using --lan (empty = auto-generate)
 
@@ -222,6 +233,16 @@ def load_settings() -> Settings:
             ),
         )
 
+    # Pomodoro timer configuration
+    pomo = raw.get("pomodoro", {})
+    if pomo:
+        settings.pomodoro = PomodoroConfig(
+            focus=int(pomo.get("focus", 25)),
+            short_break=int(pomo.get("short_break", 5)),
+            long_break=int(pomo.get("long_break", 15)),
+            cycles=int(pomo.get("cycles", 4)),
+        )
+
     # Content pipeline configuration
     ct = raw.get("content", {})
     if ct:
@@ -362,6 +383,15 @@ topics:
 #     - domain: cooking
 #       anchors: ["mise en place", "flavour balancing"]
 
+# Pomodoro timer (web UI + TUI sidebar)
+# Adjust focus/break durations and cycle length.
+# These are defaults — can also be changed in the web UI per-session.
+# pomodoro:
+#   focus: 25            # Focus duration in minutes
+#   short_break: 5       # Short break in minutes
+#   long_break: 15       # Long break in minutes (after 'cycles' focus blocks)
+#   cycles: 4            # Number of focus blocks before a long break
+
 # LAN access credentials (for --lan mode)
 # Set these to avoid auto-generated passwords each session.
 # If lan_password is empty and --lan is used, a random password is generated.

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/tui/sidebar.py

@@ -96,17 +96,35 @@ def _timer_phase(elapsed_secs: int, energy: int) -> str:
     return "red"
 
 
-# Pomodoro cycle: 25 focus, 5 break, repeated 4 times, then 15 long break.
-# All durations in seconds.
-POMODORO_FOCUS = 25 * 60
-POMODORO_SHORT_BREAK = 5 * 60
-POMODORO_LONG_BREAK = 15 * 60
-POMODORO_CYCLE_LENGTH = 4  # long break after this many focus blocks
+# Pomodoro defaults (overridden by config via load_settings().pomodoro).
+_POMO_FOCUS = 25 * 60
+_POMO_SHORT_BREAK = 5 * 60
+_POMO_LONG_BREAK = 15 * 60
+_POMO_CYCLES = 4
 
 
-def _pomodoro_state(elapsed_secs: int) -> tuple[str, int, int, int]:
+def _load_pomodoro_config() -> tuple[int, int, int, int]:
+    """Load pomodoro durations from settings. Returns (focus, short, long, cycles) in seconds."""
+    try:
+        from studyctl.settings import load_settings
+
+        pomo = load_settings().pomodoro
+        return (pomo.focus * 60, pomo.short_break * 60, pomo.long_break * 60, pomo.cycles)
+    except Exception:
+        return (_POMO_FOCUS, _POMO_SHORT_BREAK, _POMO_LONG_BREAK, _POMO_CYCLES)
+
+
+def _pomodoro_state(
+    elapsed_secs: int,
+    focus: int = 0,
+    short_break: int = 0,
+    long_break: int = 0,
+    cycles: int = 0,
+) -> tuple[str, int, int, int]:
     """Compute pomodoro state from total elapsed seconds.
 
+    If durations are not passed (0), loads from config.
+
     Returns:
         (phase, remaining_secs, cycle_number, block_in_cycle)
         phase: "focus" | "short_break" | "long_break"
@@ -114,36 +132,33 @@ def _pomodoro_state(elapsed_secs: int) -> tuple[str, int, int, int]:
         cycle_number: which full cycle (1-based)
         block_in_cycle: which focus block within the cycle (1-4)
     """
-    # One full cycle = 4x(focus + short_break) - last short_break + long_break
-    # = 4*25 + 3*5 + 15 = 130 min
-    single_block = POMODORO_FOCUS + POMODORO_SHORT_BREAK  # 30 min
-    full_cycle = (single_block * POMODORO_CYCLE_LENGTH) - POMODORO_SHORT_BREAK + POMODORO_LONG_BREAK
+    if not focus:
+        focus, short_break, long_break, cycles = _load_pomodoro_config()
+
+    single_block = focus + short_break
+    full_cycle = (single_block * cycles) - short_break + long_break
 
     cycle_number = elapsed_secs // full_cycle + 1
     pos_in_cycle = elapsed_secs % full_cycle
 
-    # Walk through the blocks in the cycle
-    for block_idx in range(POMODORO_CYCLE_LENGTH):
-        # Focus phase
-        if pos_in_cycle < POMODORO_FOCUS:
-            remaining = POMODORO_FOCUS - pos_in_cycle
+    for block_idx in range(cycles):
+        if pos_in_cycle < focus:
+            remaining = focus - pos_in_cycle
             return ("focus", remaining, cycle_number, block_idx + 1)
-        pos_in_cycle -= POMODORO_FOCUS
+        pos_in_cycle -= focus
 
-        # Break phase (short for blocks 1-3, long for block 4)
-        if block_idx < POMODORO_CYCLE_LENGTH - 1:
-            if pos_in_cycle < POMODORO_SHORT_BREAK:
-                remaining = POMODORO_SHORT_BREAK - pos_in_cycle
+        if block_idx < cycles - 1:
+            if pos_in_cycle < short_break:
+                remaining = short_break - pos_in_cycle
                 return ("short_break", remaining, cycle_number, block_idx + 1)
-            pos_in_cycle -= POMODORO_SHORT_BREAK
+            pos_in_cycle -= short_break
         else:
-            if pos_in_cycle < POMODORO_LONG_BREAK:
-                remaining = POMODORO_LONG_BREAK - pos_in_cycle
+            if pos_in_cycle < long_break:
+                remaining = long_break - pos_in_cycle
                 return ("long_break", remaining, cycle_number, block_idx + 1)
-            pos_in_cycle -= POMODORO_LONG_BREAK
+            pos_in_cycle -= long_break
 
-    # Shouldn't reach here, but safety: start a new focus
-    return ("focus", POMODORO_FOCUS, cycle_number + 1, 1)
+    return ("focus", focus, cycle_number + 1, 1)
 
 
 # ---------------------------------------------------------------------------
@@ -156,7 +171,7 @@ class TimerWidget(Static):
 
     Two modes:
     - **elapsed**: counts up, colour transitions at energy thresholds
-    - **pomodoro**: 25/5/25/5/25/5/25/15 cycle, counts down within each phase
+    - **pomodoro**: configurable focus/break cycles, counts down within each phase
     """
 
     elapsed: reactive[int] = reactive(0)
@@ -164,6 +179,17 @@ class TimerWidget(Static):
     energy: reactive[int] = reactive(5)
     timer_mode: reactive[str] = reactive("elapsed")
 
+    # Pomodoro durations (seconds) — loaded from config on mount
+    pomo_focus: int = 25 * 60
+    pomo_short_break: int = 5 * 60
+    pomo_long_break: int = 15 * 60
+    pomo_cycles: int = 4
+
+    def on_mount(self) -> None:
+        self.pomo_focus, self.pomo_short_break, self.pomo_long_break, self.pomo_cycles = (
+            _load_pomodoro_config()
+        )
+
     def render(self) -> str:
         indicator = " [bold red]PAUSED[/]" if self.paused else ""
 
@@ -182,12 +208,18 @@ class TimerWidget(Static):
 
     def _render_pomodoro(self) -> str:
         """Countdown timer with focus/break cycle display."""
-        phase, remaining, _cycle, block = _pomodoro_state(self.elapsed)
+        phase, remaining, _cycle, block = _pomodoro_state(
+            self.elapsed,
+            focus=self.pomo_focus,
+            short_break=self.pomo_short_break,
+            long_break=self.pomo_long_break,
+            cycles=self.pomo_cycles,
+        )
         mins, secs = divmod(remaining, 60)
 
         if phase == "focus":
             colour = "green"
-            label = f"FOCUS {block}/{POMODORO_CYCLE_LENGTH}"
+            label = f"FOCUS {block}/{self.pomo_cycles}"
         elif phase == "short_break":
             colour = "cyan"
             label = "BREAK"
@@ -195,7 +227,9 @@ class TimerWidget(Static):
             colour = "magenta"
             label = "LONG BREAK"
 
-        return f"[bold {colour}]{mins:02d}:{secs:02d}[/] [{colour}]{label}[/]"
+        focus_min = self.pomo_focus // 60
+        time_part = f"[bold {colour}]{mins:02d}:{secs:02d}[/]"
+        return f"{time_part} [{colour}]{label}[/] [dim]({focus_min}m)[/]"
 
 
 class ActivityFeed(Static):
@@ -312,7 +346,10 @@ class SidebarApp(App[None]):
 
     BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
         ("p", "toggle_pause", "Pause/Resume"),
+        ("s", "toggle_pomodoro", "Start/Stop Pomodoro"),
         ("r", "reset_timer", "Reset"),
+        ("plus_sign", "pomo_focus_up", "+5min focus"),
+        ("minus", "pomo_focus_down", "-5min focus"),
         ("Q", "end_session", "End Session"),
         ("q", "quit", "Quit sidebar"),
     ]
@@ -322,7 +359,7 @@ class SidebarApp(App[None]):
         yield BreakBanner(id="break_banner")
         yield ActivityFeed(id="activity")
         yield CounterBar(id="counters")
-        yield Static("[dim]p:pause  r:reset  Q:end session[/]", id="status")
+        yield Static("[dim]p:pause s:pomodoro +/-:adjust r:reset Q:end[/]", id="status")
 
     def on_mount(self) -> None:
         self._poll_ipc_files()
@@ -427,7 +464,14 @@ class SidebarApp(App[None]):
 
         timer_mode = state.get("timer_mode", "elapsed")
         if timer_mode == "pomodoro":
-            phase, remaining, _cycle, block = _pomodoro_state(elapsed)
+            tw = self.query_one("#timer", TimerWidget)
+            phase, remaining, _cycle, block = _pomodoro_state(
+                elapsed,
+                focus=tw.pomo_focus,
+                short_break=tw.pomo_short_break,
+                long_break=tw.pomo_long_break,
+                cycles=tw.pomo_cycles,
+            )
             r_mins, r_secs = divmod(remaining, 60)
             if phase == "focus":
                 timer_str = f"{r_mins:02d}:{r_secs:02d} F{block}"
@@ -490,6 +534,25 @@ class SidebarApp(App[None]):
             }
         )
 
+    def action_toggle_pomodoro(self) -> None:
+        """Toggle between elapsed and pomodoro timer modes."""
+        state = read_session_state()
+        current = state.get("timer_mode", "elapsed")
+        new_mode = "elapsed" if current == "pomodoro" else "pomodoro"
+        write_session_state({"timer_mode": new_mode})
+
+    def action_pomo_focus_up(self) -> None:
+        """Increase pomodoro focus duration by 5 minutes."""
+        timer = self.query_one("#timer", TimerWidget)
+        timer.pomo_focus = min(timer.pomo_focus + 5 * 60, 120 * 60)  # cap at 120min
+        timer.refresh()
+
+    def action_pomo_focus_down(self) -> None:
+        """Decrease pomodoro focus duration by 5 minutes."""
+        timer = self.query_one("#timer", TimerWidget)
+        timer.pomo_focus = max(timer.pomo_focus - 5 * 60, 5 * 60)  # min 5min
+        timer.refresh()
+
     def action_end_session(self) -> None:
         """End the entire study session (agent + sidebar + tmux).
 

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/web/app.py

@@ -84,10 +84,13 @@ def create_app(
     except ImportError:
         pass  # httpx/websockets not installed — proxy unavailable
 
-    # Serve index.html at root
+    # Serve index.html at root (no-cache to prevent stale SW/browser cache)
     @app.get("/")
     async def index() -> FileResponse:
-        return FileResponse(STATIC_DIR / "index.html")
+        return FileResponse(
+            STATIC_DIR / "index.html",
+            headers={"Cache-Control": "no-cache, no-store, must-revalidate"},
+        )
 
     # Redirect /session to hash-routed study-session tab
     @app.get("/session")

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/web/routes/session.py

@@ -57,17 +57,40 @@ def _is_tmux_session_alive(session_name: str) -> bool:
     return result.returncode == 0
 
 
+def _kill_stale_ttyd(state: dict) -> None:
+    """Kill a stale ttyd process if the tmux session it attaches to is gone."""
+    import os
+    import subprocess as _sp
+
+    ttyd_pid = state.get("ttyd_pid")
+    if not ttyd_pid:
+        return
+    try:
+        result = _sp.run(
+            ["ps", "-p", str(ttyd_pid), "-o", "command="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if "ttyd" in result.stdout:
+            os.kill(ttyd_pid, 15)  # SIGTERM
+    except (OSError, _sp.TimeoutExpired):
+        pass
+
+
 def _get_full_state() -> dict:
     """Read all IPC files into a single state dict.
 
     If the state file claims a session is active but the tmux session
-    is gone (zombie), clears the stale state and returns empty.
+    is gone (zombie), kills stale ttyd, clears state, and returns empty.
     """
     state = read_session_state()
 
     # Zombie detection: state says active but tmux session is dead
     tmux_session = state.get("tmux_session")
     if tmux_session and state.get("mode") != "ended" and not _is_tmux_session_alive(tmux_session):
+        # Kill orphaned ttyd before clearing state
+        _kill_stale_ttyd(state)
         # Clear stale IPC files
         for f in (STATE_FILE, TOPICS_FILE, PARKING_FILE):
             if f.exists():
@@ -284,6 +307,26 @@ def get_topics() -> list[dict]:
         return []
 
 
+@router.get("/settings/pomodoro")
+def get_pomodoro_settings() -> dict:
+    """Return pomodoro timer defaults from config.
+
+    The web UI uses these as defaults, overridden by localStorage.
+    """
+    try:
+        from studyctl.settings import load_settings
+
+        pomo = load_settings().pomodoro
+        return {
+            "focus": pomo.focus,
+            "short_break": pomo.short_break,
+            "long_break": pomo.long_break,
+            "cycles": pomo.cycles,
+        }
+    except Exception:
+        return {"focus": 25, "short_break": 5, "long_break": 15, "cycles": 4}
+
+
 # ---------------------------------------------------------------------------
 # Start / End session from web UI
 # ---------------------------------------------------------------------------
@@ -480,8 +523,18 @@ def start_session(body: StartSessionRequest) -> JSONResponse:
         state_update["topic_config_name"] = topic_config.name
     write_session_state(state_update)
 
-    # Start ttyd for terminal access
-    start_ttyd_background(session_name)
+    # Start ttyd for terminal access (with auth from config if available)
+    ttyd_username = ""
+    ttyd_password = ""
+    try:
+        from studyctl.settings import load_settings as _ls_ttyd
+
+        _ttyd_settings = _ls_ttyd()
+        ttyd_username = _ttyd_settings.lan_username or ""
+        ttyd_password = _ttyd_settings.lan_password or ""
+    except Exception:
+        pass
+    start_ttyd_background(session_name, username=ttyd_username, password=ttyd_password)
 
     return JSONResponse(
         {

{studyctl-2.2.0 → studyctl-2.3.0}/src/studyctl/web/routes/terminal_proxy.py

@@ -122,10 +122,14 @@ async def proxy_terminal_ws(ws: WebSocket) -> None:
         qs = "&".join(f"{k}={v}" for k, v in ws.query_params.items())
         upstream_ws_url = f"{upstream_ws_url}?{qs}"
 
-    # Connect to upstream with the same subprotocol
+    # Connect to upstream with the same subprotocol.
+    # Forward the Authorization header so ttyd's -c auth is satisfied.
     upstream_kwargs: dict = {}
     if subprotocol:
         upstream_kwargs["subprotocols"] = [subprotocol]
+    auth_header = ws.headers.get("authorization")
+    if auth_header:
+        upstream_kwargs["additional_headers"] = {"Authorization": auth_header}
 
     try:
         async with websockets.connect(upstream_ws_url, **upstream_kwargs) as upstream: