claude-nb 0.3.0

package/lib/build_lock.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""build_lock.py -- Build queue with mkdir-based atomic locking.
+
+Serialize builds to prevent CPU saturation.
+Only one session can build at a time; others wait or skip.
+
+Uses mkdir-based locking for atomicity: mkdir is atomic on all POSIX
+systems, so two concurrent callers cannot both succeed.
+
+Usage:
+    ./lib/build_lock.py acquire <session> <target>
+    ./lib/build_lock.py release <session>
+    ./lib/build_lock.py status
+    ./lib/build_lock.py wrap <session> <command...>
+"""
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# Try to import common; fall back gracefully
+try:
+    from lib.common import ClaudesEnv
+except ImportError:
+    _here = Path(__file__).resolve().parent.parent
+    sys.path.insert(0, str(_here))
+    from lib.common import ClaudesEnv
+
+
+MAX_WAIT = 300  # seconds to wait before giving up
+STALE_THRESHOLD = 600  # 10 minutes
+
+
+class BuildLock:
+    """Mkdir-based atomic build lock."""
+
+    def __init__(self, lock_dir: Path) -> None:
+        self.lock_dir = lock_dir
+        self.info_file = lock_dir / "info"
+
+    def read_info(self) -> tuple[str, int, str]:
+        """Parse the info file. Returns (holder, locked_at, target)."""
+        if self.info_file.exists():
+            try:
+                parts = self.info_file.read_text().strip().split("|", 2)
+                holder = parts[0] if len(parts) > 0 else "unknown"
+                locked_at = int(parts[1]) if len(parts) > 1 else 0
+                target = parts[2] if len(parts) > 2 else "unknown"
+                return holder, locked_at, target
+            except (OSError, ValueError) as e:
+                print(f"WARNING: corrupted lock info file ({e}), resetting", file=sys.stderr)
+                self._remove()
+        return "unknown", 0, "unknown"
+
+    def _try_mkdir(self) -> bool:
+        """Attempt atomic mkdir. Returns True if we got the lock."""
+        try:
+            os.mkdir(self.lock_dir)
+            return True
+        except FileExistsError:
+            return False
+
+    def _force_release_stale(self) -> bool:
+        """Remove a stale lock (>10 min). Returns True if removed."""
+        holder, locked_at, target = self.read_info()
+        now = int(time.time())
+        if locked_at > 0 and (now - locked_at) > STALE_THRESHOLD:
+            print(f"Stale lock from {holder} (>10min), forcing release")
+            self._remove()
+            return True
+        return False
+
+    def _remove(self) -> None:
+        """Remove the lock directory tree."""
+        import shutil
+
+        try:
+            shutil.rmtree(self.lock_dir)
+        except FileNotFoundError:
+            pass
+        except OSError as e:
+            print(f"WARNING: failed to remove lock dir: {e}", file=sys.stderr)
+
+    def _write_info(self, session: str, target: str) -> None:
+        """Write metadata into the lock directory."""
+        self.info_file.write_text(f"{session}|{int(time.time())}|{target}")
+
+    def acquire(self, session: str, target: str = "unknown") -> tuple[bool, str]:
+        """Try to get the build lock.
+
+        Returns (success, message) where message is e.g. "OK|sess|target"
+        or "BUSY|holder|target".
+        """
+        if self._try_mkdir():
+            self._write_info(session, target)
+            return True, f"OK|{session}|{target}"
+
+        # Lock exists -- check for staleness
+        if self._force_release_stale() and self._try_mkdir():
+            self._write_info(session, target)
+            return True, f"OK|{session}|{target}"
+
+        holder, _, lock_target = self.read_info()
+        return False, f"BUSY|{holder}|{lock_target}"
+
+    def release(self, session: str) -> tuple[bool, str]:
+        """Release the build lock held by *session*."""
+        if not self.lock_dir.is_dir():
+            return True, "OK (no lock)"
+        holder, _, _ = self.read_info()
+        if holder == session:
+            self._remove()
+            return True, "OK released"
+        return False, f"ERR: lock held by {holder}, not {session}"
+
+    def status(self) -> str:
+        """Return a human-readable status string."""
+        if not self.lock_dir.is_dir():
+            return "FREE"
+        holder, locked_at, target = self.read_info()
+        elapsed = int(time.time()) - locked_at
+        return f"LOCKED by {holder} ({target}) for {elapsed}s"
+
+    def wrap(self, session: str, command: list) -> int:
+        """Acquire lock, run command, release on exit.
+
+        Returns the command's exit code.
+        """
+        target = command[0] if command else "unknown"
+
+        waited = 0
+        while not self._try_mkdir():
+            if self.lock_dir.is_dir():
+                holder, locked_at, lock_target = self.read_info()
+                now = int(time.time())
+
+                # Stale check
+                if locked_at > 0 and (now - locked_at) > STALE_THRESHOLD:
+                    print(f"[build-queue] Stale lock from {holder}, forcing release")
+                    self._remove()
+                    continue
+
+                if waited >= MAX_WAIT:
+                    print(f"[build-queue] Timeout waiting for lock (held by {holder})")
+                    return 1
+
+                if waited % 30 == 0:
+                    print(f"[build-queue] Waiting for {holder} to finish building... ({waited}s)")
+
+            time.sleep(5)
+            waited += 5
+
+        # We hold the lock
+        self._write_info(session, target)
+        print(f"[build-queue] {session} acquired lock, running: {' '.join(command)}")
+
+        try:
+            result = subprocess.run(command)
+            exit_code = result.returncode
+        except Exception as e:
+            print(f"[build-queue] Command failed: {e}", file=sys.stderr)
+            exit_code = 1
+        finally:
+            self._remove()
+
+        print(f"[build-queue] Build finished (exit {exit_code})")
+        return exit_code
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    env = ClaudesEnv.load()
+    lock = BuildLock(env.claudes_dir / "build.lock.d")
+
+    args = sys.argv[1:]
+    cmd = args[0] if args else "status"
+
+    if cmd == "acquire":
+        if len(args) < 2:
+            print("Usage: build_lock.py acquire <session> <target>", file=sys.stderr)
+            sys.exit(1)
+        session = args[1]
+        target = args[2] if len(args) > 2 else "unknown"
+        ok, msg = lock.acquire(session, target)
+        print(msg)
+        if not ok:
+            sys.exit(1)
+
+    elif cmd == "release":
+        if len(args) < 2:
+            print("Usage: build_lock.py release <session>", file=sys.stderr)
+            sys.exit(1)
+        ok, msg = lock.release(args[1])
+        print(msg)
+        if not ok:
+            sys.exit(1)
+
+    elif cmd == "status":
+        print(lock.status())
+
+    elif cmd == "wrap":
+        if len(args) < 3:
+            print("Usage: build_lock.py wrap <session> <command...>", file=sys.stderr)
+            sys.exit(1)
+        session = args[1]
+        command = args[2:]
+        sys.exit(lock.wrap(session, command))
+
+    else:
+        print("Usage: build_lock.py {acquire|release|status|wrap} [args...]", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/lib/cli.py

@@ -0,0 +1,34 @@
+"""Entry point for `cnb` when installed via pip/uv.
+
+Resolves the bash entry script relative to this file, so it works from
+any working directory after a normal (non-editable) pip install.  For
+editable installs that ship only the lib/ directory, fall back to
+running the bash script through the npm-linked Node.js wrapper.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    claudes_home = Path(__file__).resolve().parent.parent
+    entrypoint = claudes_home / "bin" / "cnb"
+
+    if entrypoint.exists():
+        os.execvp("bash", ["bash", str(entrypoint)] + sys.argv[1:])
+
+    # Fallback for editable installs: try the npm global bin wrapper
+    npm_bin = Path("/opt/homebrew/bin/cnb")
+    if npm_bin.exists():
+        os.execvp(str(npm_bin), [str(npm_bin)] + sys.argv[1:])
+
+    # Last resort: search PATH
+    import shutil
+
+    found = shutil.which("cnb")
+    if found and Path(found).resolve() != Path(__file__).resolve():
+        os.execvp(found, [found] + sys.argv[1:])
+
+    print(f"FATAL: entrypoint not found at {entrypoint}", file=sys.stderr)
+    raise SystemExit(1)

package/lib/common.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""Shared utilities for cnb Python modules."""
+
+import sqlite3
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Generic, TypeVar
+
+
+def find_claudes_dir() -> Path:
+    """Walk up from cwd to find the .claudes/ directory."""
+    d = Path.cwd()
+    while d != d.parent:
+        if (d / ".claudes").is_dir():
+            return d / ".claudes"
+        d = d.parent
+    raise FileNotFoundError(".claudes/ not found")
+
+
+def _parse_toml(path: Path) -> dict:
+    """Parse a simple TOML config file (handles our flat key=value format)."""
+    import tomllib
+
+    return tomllib.loads(path.read_text())
+
+
+@dataclass
+class ClaudesEnv:
+    claudes_dir: Path
+    project_root: Path
+    install_home: Path
+    board_db: Path
+    sessions_dir: Path
+    cv_dir: Path
+    log_dir: Path
+    prefix: str
+    sessions: list[str]
+    suspended_file: Path
+    attendance_log: Path
+
+    @classmethod
+    def load(cls) -> "ClaudesEnv":
+        cd = find_claudes_dir()
+        pr = cd.parent
+        config: dict = {}
+
+        toml_file = cd / "config.toml"
+        if toml_file.exists():
+            config = _parse_toml(toml_file)
+        else:
+            print("ERROR: config.toml not found in .claudes/. Run: cnb init <session-names>", flush=True)
+            raise SystemExit(1)
+
+        log_dir = cd / "logs"
+        install_home_raw = config.get("claudes_home", str(cd.parent))
+        install_home = Path(install_home_raw) if install_home_raw else cd.parent
+        return cls(
+            claudes_dir=cd,
+            project_root=pr,
+            install_home=install_home,
+            board_db=cd / "board.db",
+            sessions_dir=cd / "sessions",
+            cv_dir=cd / "cv",
+            log_dir=log_dir,
+            prefix=config.get("prefix", "cc"),
+            sessions=config.get("sessions", []),
+            suspended_file=cd / "suspended.list",
+            attendance_log=log_dir / "attendance.log",
+        )
+
+
+PRIVILEGED_ROLES: frozenset[str] = frozenset({"lead", "dispatcher"})
+
+TERMINAL_TASK_STATUSES: frozenset[str] = frozenset({"done"})
+TERMINAL_BUG_STATUSES: frozenset[str] = frozenset({"FIXED"})
+
+
+def is_privileged(name: str) -> bool:
+    """Return True if *name* is a privileged role (lead/dispatcher)."""
+    return name in PRIVILEGED_ROLES
+
+
+def is_terminal_task_status(status: str) -> bool:
+    """Return True if *status* is a terminal state (task will not transition further).
+
+    Guards against operating on dead tasks: inject, assign, nudge, etc.
+    """
+    return status in TERMINAL_TASK_STATUSES
+
+
+def is_terminal_bug_status(status: str) -> bool:
+    """Return True if *status* is a terminal state (bug is resolved).
+
+    Guards against reassigning or updating resolved bugs.
+    """
+    return status in TERMINAL_BUG_STATUSES
+
+
+def sanitize_session_name(name: str) -> str:
+    """Strip path traversal and other filesystem-dangerous characters.
+
+    Session names become .md filenames in sessions/. This prevents names like
+    '../evil' from escaping the sessions directory.
+    """
+    return name.replace("/", "_").replace("\\", "_").replace("\0", "")
+
+
+def ts() -> str:
+    """Current timestamp as 'YYYY-MM-DD HH:MM:SS'."""
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def is_suspended(name: str, sf: Path) -> bool:
+    """Check if a session name appears in the suspended.list file."""
+    return sf.exists() and name in sf.read_text().splitlines()
+
+
+def date_to_epoch(s: str) -> int:
+    """Parse a date string into a Unix epoch, trying multiple formats."""
+    for f in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M"):
+        try:
+            return int(datetime.strptime(s, f).timestamp())
+        except ValueError:
+            pass
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Database wrappers (shared abstract base)
+# ---------------------------------------------------------------------------
+
+
+class BaseDB(ABC):
+    """Abstract base for SQLite wrappers for the cnb board database.
+
+    Guarantees: new connection per call, WAL mode, parameterized queries.
+    Both DB (lightweight) and BoardDB (full-featured) implement this interface.
+    """
+
+    @abstractmethod
+    def query(self, sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
+        """Execute a SELECT and return all rows."""
+
+    @abstractmethod
+    def scalar(self, sql: str, params: tuple[Any, ...] = ()) -> Any:
+        """Execute a SELECT and return the first column of the first row, or None."""
+
+    @abstractmethod
+    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> int:
+        """Execute a non-SELECT statement and return lastrowid."""
+
+
+class DB(BaseDB):
+    """Lightweight SQLite wrapper — new connection per call, no pooling.
+
+    Used by: bin/dispatcher, lib/monitor.py, standalone scripts.
+    For board_* modules, use BoardDB (which adds .md file sync helpers).
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.db_path = path
+
+    @contextmanager
+    def conn(self) -> Generator[sqlite3.Connection, None, None]:
+        """New connection per call. Commits on success, rolls back on exception."""
+        c = sqlite3.connect(str(self.db_path))
+        c.execute("PRAGMA journal_mode=WAL")
+        c.execute("PRAGMA foreign_keys=ON")
+        c.row_factory = sqlite3.Row
+        try:
+            yield c
+            c.commit()
+        except Exception:
+            c.rollback()
+            raise
+        finally:
+            c.close()
+
+    def query(self, sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
+        with self.conn() as c:
+            return c.execute(sql, params).fetchall()
+
+    def scalar(self, sql: str, params: tuple[Any, ...] = ()) -> Any:
+        rows = self.query(sql, params)
+        return rows[0][0] if rows else None
+
+    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> int:
+        with self.conn() as c:
+            return c.execute(sql, params).lastrowid
+
+
+# ---------------------------------------------------------------------------
+# Signal — inspired by Claude Code's createSignal() (utils/signal.ts)
+# ---------------------------------------------------------------------------
+
+T = TypeVar("T")
+
+
+class Signal(Generic[T]):
+    """Lightweight pub/sub for pure event notification (no stored state).
+
+    Distinct from a state store — there is no snapshot, no get_state().
+    Subscribers are notified that "something happened", optionally with args.
+
+    Usage:
+        changed = Signal[str]()
+        unsub = changed.subscribe(lambda src: print(f"changed: {src}"))
+        changed.emit("file_watcher")   # prints "changed: file_watcher"
+        unsub()                          # unsubscribed
+    """
+
+    def __init__(self) -> None:
+        self._listeners: set[Callable[[T], None]] = set()
+
+    def subscribe(self, listener: Callable[[T], None]) -> Callable[[], None]:
+        """Register a listener. Returns an unsubscribe function."""
+        self._listeners.add(listener)
+
+        def unsubscribe() -> None:
+            self._listeners.discard(listener)
+
+        return unsubscribe
+
+    def emit(self, arg: T) -> None:
+        """Notify all listeners with *arg*."""
+        for listener in list(self._listeners):
+            try:
+                listener(arg)
+            except Exception:
+                pass  # keep firing remaining listeners
+
+    def clear(self) -> None:
+        """Remove all listeners. Use in dispose/reset paths."""
+        self._listeners.clear()
+
+
+# ---------------------------------------------------------------------------
+# CLI flag parser
+# ---------------------------------------------------------------------------
+
+
+def parse_flags(
+    args: list[str],
+    value_flags: dict[str, list[str]] | None = None,
+    bool_flags: dict[str, list[str]] | None = None,
+) -> tuple[dict[str, str | bool], list[str]]:
+    """Parse CLI flags from an argument list, returning (flags_dict, positional_args).
+
+    value_flags: canonical_name -> [aliases...] — flags that consume the next arg as value.
+    bool_flags:  canonical_name -> [aliases...] — flags that set True when present.
+    """
+    value_flags = value_flags or {}
+    bool_flags = bool_flags or {}
+
+    val_lookup: dict[str, str] = {}
+    for canonical, aliases in value_flags.items():
+        for a in aliases:
+            val_lookup[a] = canonical
+
+    bool_lookup: dict[str, str] = {}
+    for canonical, aliases in bool_flags.items():
+        for a in aliases:
+            bool_lookup[a] = canonical
+
+    result: dict[str, str | bool] = {}
+    positional: list[str] = []
+    i = 0
+    while i < len(args):
+        if args[i] in val_lookup:
+            canonical = val_lookup[args[i]]
+            if i + 1 >= len(args):
+                return result, positional
+            result[canonical] = args[i + 1]
+            i += 2
+        elif args[i] in bool_lookup:
+            result[bool_lookup[args[i]]] = True
+            i += 1
+        else:
+            positional.append(args[i])
+            i += 1
+    return result, positional

package/lib/concerns/__init__.py

@@ -0,0 +1,42 @@
+"""Dispatcher concerns package.
+
+Each concern is a self-contained module with its own check interval.
+"""
+
+from .adaptive_throttle import AdaptiveThrottle
+from .base import Concern
+from .bug_sla_checker import BugSLAChecker
+from .config import DispatcherConfig
+from .coral_manager import CoralManager
+from .coral_poker import CoralPoker
+from .file_watcher import FileWatcher
+from .health_checker import HealthChecker
+from .helpers import log, tmux_ok, warn
+from .idle_detector import IdleDetector
+from .idle_killer import IdleKiller
+from .idle_nudger import IdleNudger
+from .inbox_nudger import InboxNudger
+from .resource_monitor import ResourceMonitor
+from .session_keepalive import SessionKeepAlive
+from .time_announcer import TimeAnnouncer
+
+__all__ = [
+    "AdaptiveThrottle",
+    "BugSLAChecker",
+    "Concern",
+    "CoralManager",
+    "CoralPoker",
+    "DispatcherConfig",
+    "FileWatcher",
+    "HealthChecker",
+    "IdleDetector",
+    "IdleKiller",
+    "IdleNudger",
+    "InboxNudger",
+    "ResourceMonitor",
+    "SessionKeepAlive",
+    "TimeAnnouncer",
+    "log",
+    "tmux_ok",
+    "warn",
+]

package/lib/concerns/adaptive_throttle.py

@@ -0,0 +1,26 @@
+"""AdaptiveThrottle — slow down main loop when CPU is high."""
+
+from lib.resources import check_cpu
+
+from .base import Concern
+from .helpers import log
+
+
+class AdaptiveThrottle(Concern):
+    interval = 10
+    HIGH = 80
+    LOW = 60
+    MAX_MULT = 4
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.multiplier: int = 1
+
+    def tick(self, now: int) -> None:
+        cpu = check_cpu()
+        if cpu.usage > self.HIGH and self.multiplier < self.MAX_MULT:
+            self.multiplier = min(self.multiplier * 2, self.MAX_MULT)
+            log(f"THROTTLE: CPU={cpu.usage}% > {self.HIGH}%, interval x{self.multiplier}")
+        elif cpu.usage < self.LOW and self.multiplier > 1:
+            self.multiplier = 1
+            log(f"THROTTLE: CPU={cpu.usage}% < {self.LOW}%, restored normal interval")

package/lib/concerns/base.py

@@ -0,0 +1,25 @@
+"""Base Concern class for dispatcher concerns."""
+
+
+class Concern:
+    """Base class for all dispatcher concerns.
+
+    Each concern has an independent check interval and a tick() method
+    that performs the actual work.
+    """
+
+    interval: int = 5
+
+    def __init__(self) -> None:
+        self.last_tick: int = 0
+
+    def should_tick(self, now: int) -> bool:
+        return (now - self.last_tick) >= self.interval
+
+    def tick(self, now: int) -> None:
+        raise NotImplementedError
+
+    def maybe_tick(self, now: int) -> None:
+        if self.should_tick(now):
+            self.tick(now)
+            self.last_tick = now

package/lib/concerns/bug_sla_checker.py

@@ -0,0 +1,32 @@
+"""BugSLAChecker — check overdue bugs."""
+
+import subprocess
+
+from .base import Concern
+from .config import DispatcherConfig
+from .coral_poker import CoralPoker
+from .helpers import log
+
+
+class BugSLAChecker(Concern):
+    interval = 600
+
+    def __init__(self, cfg: DispatcherConfig, poker: CoralPoker) -> None:
+        super().__init__()
+        self.cfg = cfg
+        self.poker = poker
+
+    def tick(self, now: int) -> None:
+        try:
+            r = subprocess.run(
+                [self.cfg.board_sh, "bug", "overdue"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            overdue = r.stdout.strip()
+        except Exception:
+            return
+        if overdue and "No overdue" not in overdue:
+            log(f"Bug SLA alert: {overdue}")
+            self.poker.poke(f"[Dispatcher] Bug SLA 超时: {overdue}")

package/lib/concerns/config.py

@@ -0,0 +1,22 @@
+"""Configuration object passed to all concerns as dependency injection."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class DispatcherConfig:
+    """Holds all paths and settings that concerns need."""
+
+    prefix: str
+    project_root: Path
+    claudes_dir: Path
+    sessions_dir: Path
+    board_db: Path
+    suspended_file: Path
+    board_sh: str
+    coral_sess: str
+    dispatcher_session: str
+    log_dir: Path
+    okr_dir: Path
+    dev_sessions: list[str] = field(default_factory=list)