claude-nb 0.3.0 → 0.5.1

package/lib/board_tui.py

@@ -0,0 +1,120 @@
+"""board_tui — tmux-native team UI with mouse support.
+
+Opens a single terminal window with tmux. Each worker is a window (tab).
+Mouse click on the tab bar to switch. That's it.
+"""
+
+import os
+import subprocess
+import sys
+
+from lib.board_db import BoardDB
+
+UI_SESSION = "cnb-ui"
+
+
+def _tmux(*args: str) -> int:
+    return subprocess.run(["tmux", *args], capture_output=True, text=True, timeout=5).returncode
+
+
+def _tmux_out(*args: str) -> str:
+    r = subprocess.run(["tmux", *args], capture_output=True, text=True, timeout=5)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def _session_exists(name: str) -> bool:
+    return _tmux("has-session", "-t", name) == 0
+
+
+def cmd_tui(db: BoardDB) -> None:
+    """Open team UI: one tmux window per worker, mouse-clickable tabs."""
+    if not db.env:
+        print("ERROR: 需要完整环境才能启动 TUI")
+        raise SystemExit(1)
+
+    prefix = db.env.prefix
+    workers = [r[0] for r in db.query("SELECT name FROM sessions WHERE name != 'all' ORDER BY name")]
+
+    if not workers:
+        print("ERROR: 没有注册的 session")
+        raise SystemExit(1)
+
+    online = [w for w in workers if _session_exists(f"{prefix}-{w}")]
+    if not online:
+        print("ERROR: 没有在线的 worker，先运行 cnb swarm start")
+        raise SystemExit(1)
+
+    # Rebuild base UI session (shared window group)
+    if _session_exists(UI_SESSION):
+        _tmux("kill-session", "-t", UI_SESSION)
+
+    _tmux("new-session", "-d", "-s", UI_SESSION)
+    for name in online:
+        _tmux("link-window", "-s", f"{prefix}-{name}:0", "-t", UI_SESSION, "-a")
+    _tmux("kill-window", "-t", f"{UI_SESSION}:0")
+
+    win_indices = _tmux_out("list-windows", "-t", UI_SESSION, "-F", "#{window_index}").split("\n")
+    for i, name in enumerate(online):
+        if i < len(win_indices):
+            _tmux("rename-window", "-t", f"{UI_SESSION}:{win_indices[i]}", name)
+
+    _apply_style(len(online), win_indices)
+    _open_terminal()
+
+
+def _apply_style(n_online: int, win_indices: list[str]) -> None:
+    session_opts = {
+        "mouse": "on",
+        "status": "on",
+        "status-position": "top",
+        "status-style": "bg=default,fg=white",
+        "status-left": " cnb ",
+        "status-left-style": "bold",
+        "status-left-length": "6",
+        "status-right": f" {n_online} online ",
+        "status-right-style": "dim",
+    }
+    for k, v in session_opts.items():
+        _tmux("set-option", "-t", UI_SESSION, k, v)
+
+    window_opts = {
+        "window-status-format": " #W ",
+        "window-status-current-format": " #W ",
+        "window-status-style": "dim",
+        "window-status-current-style": "bold,underscore",
+        "window-status-separator": "",
+    }
+    for idx in win_indices:
+        for k, v in window_opts.items():
+            _tmux("set-option", "-w", "-t", f"{UI_SESSION}:{idx}", k, v)
+
+
+def _open_terminal() -> None:
+    """Open a new terminal attached to cnb-ui."""
+    attach_cmd = f"tmux attach -t {UI_SESSION} ';' set-option destroy-unattached on"
+
+    if sys.platform == "darwin":
+        if os.path.isdir("/Applications/iTerm.app"):
+            script = (
+                'tell application "iTerm"\n'
+                "  activate\n"
+                f'  create window with default profile command "{attach_cmd}"\n'
+                "end tell"
+            )
+        else:
+            script = f'tell application "Terminal"\n  do script "{attach_cmd}"\n  activate\nend tell'
+        r = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)
+        if r.returncode != 0:
+            print(f"ERROR: 无法打开终端: {r.stderr.strip()}")
+            raise SystemExit(1)
+        print("OK 已打开 — 点击顶部 tab 切换同学")
+    else:
+        import shutil
+
+        for term in ("gnome-terminal", "xterm", "konsole", "alacritty"):
+            if shutil.which(term):
+                subprocess.Popen([term, "--", "bash", "-c", attach_cmd])
+                print("OK 已打开 — 点击顶部 tab 切换同学")
+                return
+        print(f"ERROR: 找不到终端模拟器，手动运行: {attach_cmd}")
+        raise SystemExit(1)

package/lib/board_view.py

@@ -15,6 +15,7 @@ def _git(project_root: Path, *args: str) -> str:
         ["git", "-C", str(project_root), *args],
         capture_output=True,
         text=True,
+        timeout=5,
     )
     return r.stdout
 
@@ -40,50 +41,63 @@ def _tmux_pane_command(name: str) -> str:
         return ""
 
 
-def _pgrep(pattern: str) -> str | None:
-    try:
-        r = subprocess.run(["pgrep", "-f", pattern], capture_output=True, text=True, timeout=3)
-        if r.returncode == 0:
-            return r.stdout.strip().split("\n")[0]
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        pass
-    return None
+def _heartbeat_status(last_heartbeat: str | None, prefix: str, name: str) -> tuple[str, str]:
+    """Derive agent liveness from heartbeat timestamp, with tmux fallback."""
+    if last_heartbeat:
+        try:
+            hb_time = datetime.strptime(last_heartbeat, "%Y-%m-%d %H:%M:%S")
+            delta = (datetime.now() - hb_time).total_seconds()
+            if delta < 120:
+                ago = f"[{int(delta)}s ago]"
+                return "● active", ago
+            elif delta < 180:
+                return "◐ thinking", f"[{int(delta / 60)}m ago]"
+            elif delta < 600:
+                return "○ stale", f"[{int(delta / 60)}m ago]"
+            else:
+                hours = delta / 3600
+                ago = f"[{int(hours)}h ago]" if hours >= 1 else f"[{int(delta / 60)}m ago]"
+                return "· offline", ago
+        except ValueError:
+            pass
+    sess = f"{prefix}-{name}"
+    if _tmux_has_session(sess):
+        cmd = _tmux_pane_command(sess)
+        if cmd not in ("zsh", "bash", "sh", "-zsh", "-bash"):
+            return "● running", ""
+        return "○ dead", ""
+    return "· offline", ""
 
 
 def cmd_overview(db: BoardDB) -> None:
     """Default view when running cnb with no args."""
+    assert db.env is not None
     prefix = db.env.prefix
     now = datetime.now().strftime("%H:%M")
     print(f"=== {db.env.project_root.name}  {now} ===")
     print()
 
     # ── sessions ──
-    for (name,) in db.query("SELECT name FROM sessions WHERE name != 'all' ORDER BY name"):
-        sess = f"{prefix}-{name}"
-        if _tmux_has_session(sess):
-            cmd = _tmux_pane_command(sess)
-            status = "● running" if cmd not in ("zsh", "bash", "sh", "-zsh", "-bash") else "○ dead"
-        else:
-            status = "· offline"
+    for row in db.query("SELECT name, status, last_heartbeat FROM sessions WHERE name != 'all' ORDER BY name"):
+        name, task, last_hb = row[0], row[1], row[2]
+        status, ago = _heartbeat_status(last_hb, prefix, name)
 
         inbox = db.scalar("SELECT COUNT(*) FROM inbox WHERE session=? AND read=0", (name,)) or 0
         inbox_str = f"  [{inbox} msg]" if inbox else ""
-        task = db.scalar("SELECT status FROM sessions WHERE name=?", (name,)) or ""
         if task:
             task = task[:60]
         else:
             task = "(no status)"
 
         line = f"  {status:12s} {name:<10s} {task}"
+        if ago:
+            line += f"  {ago}"
         if inbox:
             line += f"{inbox_str}"
         print(line)
 
     # ── recent messages ──
-    rows = db.query(
-        "SELECT ts, sender, recipient, substr(body, 1, 80) "
-        "FROM messages ORDER BY id DESC LIMIT 5"
-    )
+    rows = db.query("SELECT ts, sender, recipient, substr(body, 1, 80) FROM messages ORDER BY id DESC LIMIT 5")
     if rows:
         print()
         print("Recent:")
@@ -91,20 +105,20 @@ def cmd_overview(db: BoardDB) -> None:
             print(f"  [{ts_val}] {sender} → {recipient}: {body}")
 
     # ── open proposals ──
-    proposals = db.query(
-        "SELECT number || '-' || slug FROM proposals WHERE status='OPEN'"
-    )
+    proposals = db.query("SELECT number || '-' || slug FROM proposals WHERE status='OPEN'")
     if proposals:
         print()
         print(f"Open proposals: {len(proposals)}")
 
     # ── dispatcher ──
-    pid = _pgrep("dispatcher")
+    dispatcher_sess = f"{prefix}-dispatcher"
     print()
-    if pid:
-        print(f"  dispatcher: running (pid {pid})")
+    if _tmux_has_session(dispatcher_sess):
+        print(f"  dispatcher: running ({dispatcher_sess})")
     else:
-        running = any(_tmux_has_session(f"{prefix}-{n}") for (n,) in db.query("SELECT name FROM sessions WHERE name != 'all'"))
+        running = any(
+            _tmux_has_session(f"{prefix}-{n}") for (n,) in db.query("SELECT name FROM sessions WHERE name != 'all'")
+        )
         if running:
             print("  dispatcher: NOT RUNNING — run: cnb dispatcher")
         else:
@@ -112,6 +126,7 @@ def cmd_overview(db: BoardDB) -> None:
 
 
 def cmd_view(db: BoardDB, identity: str) -> None:
+    assert db.env is not None
     print("=== Board ===\n")
 
     roadmap = db.env.project_root / "ROADMAP.md"
@@ -130,16 +145,19 @@ def cmd_view(db: BoardDB, identity: str) -> None:
         if count:
             print(f">>> 你有 {count} 条未读消息，运行 ./board inbox 查看 <<<\n")
 
+    prefix = db.env.prefix
     print("Status:")
-    for name, task in db.query("SELECT name, status FROM sessions ORDER BY name"):
+    for name, task, last_hb in db.query("SELECT name, status, last_heartbeat FROM sessions ORDER BY name"):
         cap = name[0].upper() + name[1:] if name else name
+        status, ago = _heartbeat_status(last_hb, prefix, name)
         task = task or "(none)"
         tag = ""
         if p0_locked and "[P0]" not in task:
             tag = " [!! 未标 P0]"
-        if len(task) > 72:
-            task = task[:69] + "..."
-        print(f"  {cap:<8s} {task}{tag}")
+        if len(task) > 60:
+            task = task[:57] + "..."
+        ago_str = f"  {ago}" if ago else ""
+        print(f"  {status:12s} {cap:<10s} {task}{tag}{ago_str}")
     print()
 
     print("Recent messages:")
@@ -166,6 +184,7 @@ def cmd_view(db: BoardDB, identity: str) -> None:
 
 
 def cmd_p0(db: BoardDB) -> None:
+    assert db.env is not None
     roadmap = db.env.project_root / "ROADMAP.md"
     if not roadmap.is_file():
         print("ERROR: ROADMAP.md not found")
@@ -193,6 +212,7 @@ def cmd_p0(db: BoardDB) -> None:
 
 
 def cmd_prebuild(db: BoardDB) -> None:
+    assert db.env is not None
     print("=== Pre-build Check ===\n")
     has_fail = False
     pr = db.env.project_root
@@ -219,6 +239,7 @@ def cmd_prebuild(db: BoardDB) -> None:
 
 
 def cmd_dirty(db: BoardDB) -> None:
+    assert db.env is not None
     print("=== Uncommitted Changes ===\n")
     pr = db.env.project_root
     changes = _git(pr, "status", "--porcelain").strip()
@@ -240,32 +261,29 @@ def cmd_dirty(db: BoardDB) -> None:
 
 
 def cmd_dashboard(db: BoardDB) -> None:
+    assert db.env is not None
     prefix = db.env.prefix
     print(f"=== Team Dashboard {datetime.now().strftime('%H:%M')} ===\n")
-    for (name,) in db.query("SELECT name FROM sessions ORDER BY name"):
-        session_name = f"{prefix}-{name}"
-        status = "offline"
-        if _tmux_has_session(session_name):
-            cmd = _tmux_pane_command(session_name)
-            if cmd in ("zsh", "bash", "sh", "-zsh", "-bash"):
-                status = "DEAD"
-            else:
-                status = "running"
+    for row in db.query("SELECT name, status, last_heartbeat FROM sessions ORDER BY name"):
+        name, task, last_hb = row[0], row[1], row[2]
+        status, ago = _heartbeat_status(last_hb, prefix, name)
 
         inbox_count = db.scalar("SELECT COUNT(*) FROM inbox WHERE session=? AND read=0", (name,))
         inbox_str = f" [{inbox_count}msg]" if inbox_count else ""
-        task = db.scalar("SELECT substr(status, 1, 50) FROM sessions WHERE name=?", (name,)) or "-"
-        print(f"  {name:<7s} {status:<8s}{inbox_str}")
+        task = task[:50] if task else "-"
+        ago_str = f"  {ago}" if ago else ""
+        print(f"  {name:<7s} {status:<12s}{inbox_str}{ago_str}")
         print(f"         {task}")
     print()
-    pid = _pgrep("dispatcher")
-    if pid:
-        print(f"  dispatcher: running (PID {pid})")
+    dispatcher_sess = f"{prefix}-dispatcher"
+    if _tmux_has_session(dispatcher_sess):
+        print(f"  dispatcher: running ({dispatcher_sess})")
     else:
         print("  dispatcher: NOT RUNNING")
 
 
 def cmd_files(db: BoardDB) -> None:
+    assert db.env is not None
     print("=== 共享文件 ===\n")
     rows = db.query("SELECT hash, original_name, sender, ts FROM files ORDER BY ts DESC")
     if not rows:
@@ -282,6 +300,7 @@ def cmd_files(db: BoardDB) -> None:
 
 
 def cmd_get(db: BoardDB, args: list[str]) -> None:
+    assert db.env is not None
     if not args:
         print("Usage: ./board get <hash-prefix|filename>")
         raise SystemExit(1)
@@ -310,15 +329,15 @@ def cmd_get(db: BoardDB, args: list[str]) -> None:
 
 def cmd_freshness(db: BoardDB) -> None:
     print("=== 数据新鲜度 ===\n")
-    print(f"  {'Session':<8s}  {'Last status update':<20s}  {'Unread inbox'}")
-    print(f"  {'-------':<8s}  {'------------------':<20s}  {'------------'}")
+    print(f"  {'Session':<8s}  {'Last status':<20s}  {'Last heartbeat':<20s}  {'Unread'}")
+    print(f"  {'-------':<8s}  {'-----------':<20s}  {'--------------':<20s}  {'------'}")
     rows = db.query(
-        "SELECT s.name, s.updated_at, "
+        "SELECT s.name, s.updated_at, s.last_heartbeat, "
         "(SELECT COUNT(*) FROM inbox i WHERE i.session=s.name AND i.read=0) "
         "FROM sessions s ORDER BY s.name"
     )
-    for name, updated, inbox_count in rows:
-        print(f"  {name:<8s}  {updated or '(never)':<20s}  {inbox_count}")
+    for name, updated, heartbeat, inbox_count in rows:
+        print(f"  {name:<8s}  {updated or '(never)':<20s}  {heartbeat or '(never)':<20s}  {inbox_count}")
 
 
 def cmd_relations(db: BoardDB) -> None:
@@ -355,6 +374,7 @@ def cmd_history(db: BoardDB, args: list[str]) -> None:
 
 
 def cmd_roster(db: BoardDB) -> None:
+    assert db.env is not None
     print("=== 员工状态 ===")
     prefix = db.env.prefix
     rows = db.query(

package/lib/board_vote.py

@@ -1,10 +1,11 @@
 """board_vote — governance: vote / tally / propose."""
 
 from lib.board_db import BoardDB, ts
-from lib.common import PRIVILEGED_ROLES, parse_flags
+from lib.common import PRIVILEGED_ROLES, parse_flags, validate_identity
 
 
 def cmd_vote(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     if name in PRIVILEGED_ROLES:
         print("ERROR: privileged roles have no voting rights (charter §二)")
@@ -58,7 +59,9 @@ def cmd_vote(db: BoardDB, identity: str, args: list[str]) -> None:
 
     prop_type = db.scalar("SELECT type FROM proposals WHERE id=?", (prop_id,))
     eligible = (
-        db.scalar("SELECT COUNT(*) FROM sessions WHERE name != (SELECT value FROM meta WHERE key='dispatcher_session')")
+        db.scalar(
+            "SELECT COUNT(*) FROM sessions WHERE name NOT IN (SELECT value FROM meta WHERE key='dispatcher_session')"
+        )
         or 0
     )
     threshold = (eligible * 2 + 2) // 3 if prop_type == "S" else eligible // 2 + 1
@@ -90,6 +93,7 @@ def cmd_vote(db: BoardDB, identity: str, args: list[str]) -> None:
 
 
 def cmd_propose(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     if len(args) < 1:
         print("Usage: ./board --as <name> propose <内容> [--type S]")
@@ -157,7 +161,9 @@ def cmd_tally(db: BoardDB, args: list[str]) -> None:
     )
     prop_type = db.scalar("SELECT type FROM proposals WHERE id=?", (prop_id,))
     eligible = (
-        db.scalar("SELECT COUNT(*) FROM sessions WHERE name != (SELECT value FROM meta WHERE key='dispatcher_session')")
+        db.scalar(
+            "SELECT COUNT(*) FROM sessions WHERE name NOT IN (SELECT value FROM meta WHERE key='dispatcher_session')"
+        )
         or 0
     )
     threshold = (eligible * 2 + 2) // 3 if prop_type == "S" else eligible // 2 + 1

package/lib/build_lock.py

@@ -184,22 +184,22 @@ def main() -> None:
     if cmd == "acquire":
         if len(args) < 2:
             print("Usage: build_lock.py acquire <session> <target>", file=sys.stderr)
-            sys.exit(1)
+            raise SystemExit(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)
+            raise SystemExit(1)
 
     elif cmd == "release":
         if len(args) < 2:
             print("Usage: build_lock.py release <session>", file=sys.stderr)
-            sys.exit(1)
+            raise SystemExit(1)
         ok, msg = lock.release(args[1])
         print(msg)
         if not ok:
-            sys.exit(1)
+            raise SystemExit(1)
 
     elif cmd == "status":
         print(lock.status())
@@ -207,14 +207,14 @@ def main() -> None:
     elif cmd == "wrap":
         if len(args) < 3:
             print("Usage: build_lock.py wrap <session> <command...>", file=sys.stderr)
-            sys.exit(1)
+            raise SystemExit(1)
         session = args[1]
         command = args[2:]
-        sys.exit(lock.wrap(session, command))
+        raise SystemExit(lock.wrap(session, command))
 
     else:
         print("Usage: build_lock.py {acquire|release|status|wrap} [args...]", file=sys.stderr)
-        sys.exit(1)
+        raise SystemExit(1)
 
 
 if __name__ == "__main__":

package/lib/common.py

@@ -12,13 +12,21 @@ from typing import Any, Generic, TypeVar
 
 
 def find_claudes_dir() -> Path:
-    """Walk up from cwd to find the .claudes/ directory."""
+    """Find .claudes/ directory. Checks CNB_PROJECT env var first, then walks up from cwd."""
+    import os
+
+    env_root = os.environ.get("CNB_PROJECT")
+    if env_root:
+        p = Path(env_root) / ".claudes"
+        if p.is_dir():
+            return p
+
     d = Path.cwd()
     while d != d.parent:
         if (d / ".claudes").is_dir():
             return d / ".claudes"
         d = d.parent
-    raise FileNotFoundError(".claudes/ not found")
+    raise FileNotFoundError(".claudes/ not found (set CNB_PROJECT or run from project dir)")
 
 
 def _parse_toml(path: Path) -> dict:
@@ -28,6 +36,30 @@ def _parse_toml(path: Path) -> dict:
     return tomllib.loads(path.read_text())
 
 
+def _write_config_toml(path: Path, data: dict) -> None:
+    """Serialize *data* back to our config.toml format."""
+    lines: list[str] = []
+    for key, val in data.items():
+        if key == "session":
+            continue
+        if isinstance(val, list):
+            items = ", ".join(f'"{v}"' for v in val)
+            lines.append(f"{key} = [{items}]")
+        else:
+            lines.append(f'{key} = "{val}"')
+    lines.append("")
+    for name, section in data.get("session", {}).items():
+        lines.append(f"[session.{name}]")
+        for k, v in section.items():
+            sv = str(v)
+            if "\n" in sv:
+                lines.append(f'{k} = """{sv}"""')
+            else:
+                lines.append(f'{k} = "{sv}"')
+        lines.append("")
+    path.write_text("\n".join(lines) + "\n")
+
+
 @dataclass
 class ClaudesEnv:
     claudes_dir: Path
@@ -84,6 +116,16 @@ def is_privileged(name: str) -> bool:
     return name in PRIVILEGED_ROLES
 
 
+def validate_identity(db: "BaseDB", identity: str) -> None:
+    name = identity.lower()
+    if name in PRIVILEGED_ROLES:
+        return
+    exists = db.scalar("SELECT COUNT(*) FROM sessions WHERE name=?", (name,))
+    if not exists:
+        print(f"ERROR: '{name}' is not a registered session")
+        raise SystemExit(1)
+
+
 def is_terminal_task_status(status: str) -> bool:
     """Return True if *status* is a terminal state (task will not transition further).
 
@@ -190,7 +232,7 @@ class DB(BaseDB):
 
     def execute(self, sql: str, params: tuple[Any, ...] = ()) -> int:
         with self.conn() as c:
-            return c.execute(sql, params).lastrowid
+            return c.execute(sql, params).lastrowid or 0
 
 
 # ---------------------------------------------------------------------------

package/lib/concerns/__init__.py

@@ -5,20 +5,14 @@ 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 .coral import CoralManager, CoralPoker
 from .file_watcher import FileWatcher
-from .health_checker import HealthChecker
+from .health import HealthChecker, ResourceMonitor, SessionKeepAlive
 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
+from .idle import IdleDetector, IdleKiller, IdleNudger
+from .notifications import BugSLAChecker, InboxNudger, QueuedMessageFlusher, TimeAnnouncer
+from .nudge_coordinator import NudgeCoordinator
 
 __all__ = [
     "AdaptiveThrottle",
@@ -33,6 +27,8 @@ __all__ = [
     "IdleKiller",
     "IdleNudger",
     "InboxNudger",
+    "NudgeCoordinator",
+    "QueuedMessageFlusher",
     "ResourceMonitor",
     "SessionKeepAlive",
     "TimeAnnouncer",

package/lib/concerns/{coral_manager.py → coral.py}

@@ -1,12 +1,13 @@
-"""CoralManager — ensure dispatcher Claude session is running."""
+"""Coral: dispatcher session lifecycle management and heartbeat."""
 
+import re
 import time
 
 from lib.common import is_suspended
 
 from .base import Concern
 from .config import DispatcherConfig
-from .helpers import is_claude_running, log, tmux, tmux_send
+from .helpers import db, is_claude_running, log, pane_md5, tmux, tmux_ok, tmux_send
 
 
 class CoralManager(Concern):
@@ -37,7 +38,7 @@ class CoralManager(Concern):
         log("Starting Coral...")
         tmux("kill-session", "-t", self.cfg.coral_sess)
         tmux("new-session", "-d", "-s", self.cfg.coral_sess, "-x", "200", "-y", "50")
-        tmux_send(self.cfg.coral_sess, f"cd '{self.cfg.project_root}'")
+        tmux_send(self.cfg.coral_sess, f"cd '{self.cfg.project_root}' && export CNB_PROJECT='{self.cfg.project_root}'")
         time.sleep(0.5)
         tmux_send(
             self.cfg.coral_sess,
@@ -49,8 +50,8 @@ class CoralManager(Concern):
         self._wait_until_ready()
 
     def _wait_until_ready(self) -> None:
-        """Poll until the Claude process is running, or timeout after BOOT_WAIT."""
         import time as _time
+
         deadline = _time.monotonic() + self.BOOT_WAIT
         while _time.monotonic() < deadline:
             if is_claude_running(self.cfg.coral_sess):
@@ -59,3 +60,52 @@ class CoralManager(Concern):
                 return
             _time.sleep(1)
         log(f"WARNING: Coral not ready after {self.BOOT_WAIT}s, will retry next tick")
+
+
+class CoralPoker(Concern):
+    interval = 120
+
+    def __init__(self, cfg: DispatcherConfig) -> None:
+        super().__init__()
+        self.cfg = cfg
+        self.last_poke: int = int(time.time())
+
+    def poke(self, msg: str) -> bool:
+        if not tmux_ok("has-session", "-t", self.cfg.coral_sess) or not is_claude_running(self.cfg.coral_sess):
+            return False
+
+        content = tmux("capture-pane", "-t", self.cfg.coral_sess, "-p") or ""
+        prompts = [l for l in content.splitlines() if l.startswith("❯")]
+        if prompts and re.match(r"^❯ .{3,}", prompts[-1]):
+            log("Coral: skip (typing)")
+            return False
+
+        h1 = pane_md5(self.cfg.coral_sess)
+        time.sleep(1)
+        if h1 != pane_md5(self.cfg.coral_sess):
+            log("Coral: skip (busy)")
+            return False
+
+        log("Coral: poking")
+        tmux_send(self.cfg.coral_sess, msg)
+        self.last_poke = int(time.time())
+        return True
+
+    def tick(self, now: int) -> None:
+        unread = 0
+        if self.cfg.board_db.exists():
+            try:
+                unread = (
+                    db(self.cfg).scalar(
+                        "SELECT COUNT(*) FROM inbox WHERE session=? AND read=0",
+                        (self.cfg.dispatcher_session,),
+                    )
+                    or 0
+                )
+            except Exception:
+                pass
+
+        if unread > 0:
+            self.poke(f"[Dispatcher] 你有 {unread} 条未读消息")
+        elif (now - self.last_poke) >= self.interval:
+            self.poke(f"[Dispatcher] heartbeat {time.strftime('%H:%M:%S')}")