claude-nb 0.4.0 → 0.5.1

package/lib/board_bbs.py

@@ -3,31 +3,43 @@
 import hashlib
 
 from lib.board_db import BoardDB, ts
+from lib.common import validate_identity
 
 
 def cmd_post(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     if len(args) < 2:
         print("Usage: ./board --as <name> post <标题> <内容>")
         raise SystemExit(1)
     title = args[0]
+    body = " ".join(args[1:])
     now = ts()
     tid = hashlib.sha256(f"{title}{now}{identity}".encode()).hexdigest()[:6]
 
-    db.execute(
-        "INSERT INTO threads(id, title, author) VALUES (?, ?, ?)",
-        (tid, title, name),
-    )
-    db.execute(
-        "INSERT INTO messages(ts, sender, recipient, body) VALUES (?, ?, 'all', ?)",
-        (now, name, f"[BBS] 新帖「{title}」({tid})"),
-    )
+    with db.conn() as c:
+        db.execute(
+            "INSERT INTO threads(id, title, author) VALUES (?, ?, ?)",
+            (tid, title, name),
+            c=c,
+        )
+        db.execute(
+            "INSERT INTO thread_replies(thread_id, author, body) VALUES (?, ?, ?)",
+            (tid, name, body),
+            c=c,
+        )
+        db.execute(
+            "INSERT INTO messages(ts, sender, recipient, body) VALUES (?, ?, 'all', ?)",
+            (now, name, f"[BBS] 新帖「{title}」({tid})"),
+            c=c,
+        )
     print(f"OK 帖子已创建: {tid}")
     print(f"  标题: {title}")
     print(f"  查看: ./board --as <name> thread {tid}")
 
 
 def cmd_reply(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     if len(args) < 2:
         print("Usage: ./board --as <name> reply <帖子ID> <内容>")
@@ -70,6 +82,9 @@ def cmd_thread(db: BoardDB, args: list[str]) -> None:
         raise SystemExit(1)
 
     row = db.query_one("SELECT title, author, created_at FROM threads WHERE id=?", (full_tid,))
+    if not row:
+        print(f"ERROR: 帖子 {full_tid} 数据异常")
+        raise SystemExit(1)
     title, author, created = row
     print(f"# {title}")
     print(f"> @{author} — {created}\n")

package/lib/board_bug.py

@@ -4,10 +4,11 @@ import time
 from datetime import datetime
 
 from lib.board_db import BoardDB, ts
-from lib.common import is_terminal_bug_status
+from lib.common import is_terminal_bug_status, validate_identity
 
 
 def cmd_bug(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     subcmd = args[0] if args else "list"
     rest = args[1:] if len(args) > 1 else []
     dispatch = {

package/lib/board_db.py

@@ -41,6 +41,10 @@ class BoardDB(BaseDB):
             self.env = None
             self.db_path = Path(env_or_path)
 
+    def require_env(self) -> ClaudesEnv:
+        assert self.env is not None, "BoardDB created without ClaudesEnv — this command requires a full environment"
+        return self.env
+
     def _auto_migrate(self) -> None:
         """Apply pending schema migrations on first load (idempotent).
 
@@ -92,24 +96,32 @@ class BoardDB(BaseDB):
 
     def execute(self, sql: str, params: tuple[Any, ...] = (), *, c: sqlite3.Connection | None = None) -> int:
         if c is not None:
-            return c.execute(sql, params).lastrowid
+            return c.execute(sql, params).lastrowid or 0
         with self.conn() as conn:
             cur = conn.execute(sql, params)
-            return cur.lastrowid
+            return cur.lastrowid or 0
 
     def execute_changes(self, sql: str, params: tuple[Any, ...] = (), *, c: sqlite3.Connection | None = None) -> int:
         if c is not None:
             c.execute(sql, params)
-            return c.execute("SELECT changes()").fetchone()[0]
+            return int(c.execute("SELECT changes()").fetchone()[0])
         with self.conn() as conn:
             conn.execute(sql, params)
-            return conn.execute("SELECT changes()").fetchone()[0]
+            return int(conn.execute("SELECT changes()").fetchone()[0])
 
     def ensure_session(self, name: str, *, c: sqlite3.Connection | None = None) -> None:
         n = name.lower()
         existing = self.scalar("SELECT COUNT(*) FROM sessions WHERE name=?", (n,), c=c)
-        if existing == 0:
-            self.execute("INSERT INTO sessions(name) VALUES (?)", (n,), c=c)
+        if existing:
+            return
+        if self.env is not None:
+            from lib.common import PRIVILEGED_ROLES
+
+            allowed = {s.lower() for s in self.env.sessions} | {"all"} | PRIVILEGED_ROLES
+            if n not in allowed:
+                print(f"ERROR: '{n}' is not a registered session")
+                raise SystemExit(1)
+        self.execute("INSERT INTO sessions(name) VALUES (?)", (n,), c=c)
 
     def deliver_to_inbox(
         self, sender: str, recipient: str, msg_id: int, *, c: sqlite3.Connection | None = None

package/lib/board_lock.py

@@ -4,6 +4,7 @@ import subprocess
 import time
 
 from lib.board_db import BoardDB, ts
+from lib.common import validate_identity
 
 GIT_LOCK_TTL = 60
 
@@ -14,6 +15,7 @@ def _cleanup_stale(db: BoardDB) -> None:
 
 
 def cmd_git_lock(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     reason = " ".join(args) if args else "git operation"
 
@@ -50,6 +52,8 @@ def cmd_git_lock(db: BoardDB, identity: str, args: list[str]) -> None:
 
 
 def cmd_git_unlock(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
+    assert db.env is not None
     name = identity.lower()
     force = "--force" in args
 
@@ -90,6 +94,7 @@ def cmd_git_unlock(db: BoardDB, identity: str, args: list[str]) -> None:
 
 
 def cmd_git_lock_status(db: BoardDB) -> None:
+    assert db.env is not None
     _cleanup_stale(db)
 
     row = db.query_one("SELECT session, reason, acquired_at, expires_at FROM git_locks WHERE id=1")

package/lib/board_mailbox.py

@@ -1,6 +1,6 @@
 """board_mailbox — encrypted async messaging between registered agents."""
 
-import base64
+import binascii
 import json
 from pathlib import Path
 
@@ -22,12 +22,14 @@ PUBKEYS_FILE = REGISTRY_DIR / "pubkeys.json"
 
 
 def _keys_dir(db: BoardDB) -> Path:
+    assert db.env is not None
     return db.env.claudes_dir / "keys"
 
 
 def _load_pubkeys() -> dict[str, str]:
     if PUBKEYS_FILE.exists():
-        return json.loads(PUBKEYS_FILE.read_text())
+        data: dict[str, str] = json.loads(PUBKEYS_FILE.read_text())
+        return data
     return {}
 
 
@@ -117,7 +119,7 @@ def cmd_unseal(db: BoardDB, identity: str) -> None:
             plaintext = unseal_b64(encrypted_body, private)
             print(f"  [{msg_ts}] **{sender}**: {plaintext}")
             decrypted_ids.append(msg_id)
-        except (InvalidTag, ValueError, base64.binascii.Error, UnicodeDecodeError) as e:
+        except (InvalidTag, ValueError, binascii.Error, UnicodeDecodeError) as e:
             print(f"  [{msg_ts}] **{sender}**: [解密失败 — {type(e).__name__}: {e}]")
 
     if decrypted_ids:
@@ -149,5 +151,5 @@ def cmd_mailbox_log(db: BoardDB, identity: str) -> None:
         try:
             plaintext = unseal_b64(encrypted_body, private)
             print(f"  [{msg_ts}] {sender}: {plaintext}")
-        except (InvalidTag, ValueError, base64.binascii.Error, UnicodeDecodeError) as e:
+        except (InvalidTag, ValueError, binascii.Error, UnicodeDecodeError) as e:
             print(f"  [{msg_ts}] {sender}: [无法解密 — {type(e).__name__}: {e}]")

package/lib/board_msg.py

@@ -1,19 +1,86 @@
 """board_msg — send / inbox / ack / status / log commands."""
 
 import hashlib
+import re
 import shutil
+import subprocess
 from pathlib import Path
 
 from lib.board_db import BoardDB, ts
-from lib.common import parse_flags
+from lib.common import parse_flags, validate_identity
 
 
 def _ack_marker_path(db: BoardDB, name: str) -> Path:
     """Path to file recording max message_id seen by last inbox call."""
+    assert db.env is not None
     return db.env.sessions_dir / f".{name}.ack_max_id"
 
 
+def _is_idle(sess: str) -> bool:
+    """Check if a Claude Code session is idle at its prompt (not mid-response).
+
+    Claude Code's prompt layout puts the prompt marker a few lines above the bottom
+    (status bar, project name, permissions line are below it), so we
+    check the last ~8 lines rather than just the final line.
+    """
+    r = subprocess.run(
+        ["tmux", "capture-pane", "-t", sess, "-p", "-S", "-10"],
+        capture_output=True,
+        text=True,
+        timeout=3,
+    )
+    if r.returncode != 0:
+        return False
+    text = r.stdout.rstrip()
+    if not text:
+        return False
+    busy_indicators = ("Choreographing", "Seasoning", "Churned", "Gitifying", "Running", "ctrl+b", "thinking")
+    for line in reversed(text.splitlines()):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if any(ind in stripped for ind in busy_indicators):
+            return False
+        if "❯" in stripped or "Press up to edit" in stripped:
+            return True
+        break
+    return "❯" in text or "Press up to edit" in text
+
+
+def _nudge_session(db: BoardDB, recipient: str) -> None:
+    """Inject a fixed prompt into the recipient's tmux session to check inbox.
+
+    Only nudges idle agents — busy agents will pick up messages via the
+    PostToolBatch hook. This avoids commands piling up in Claude Code's
+    message queue when injected mid-response.
+    """
+    assert db.env is not None
+    if recipient == "all":
+        sessions = [r[0] for r in db.query("SELECT name FROM sessions WHERE name != 'all'")]
+    else:
+        sessions = [recipient]
+    prefix = db.env.prefix
+    board = db.env.install_home / "bin" / "board"
+    for name in sessions:
+        if not re.match(r"^[a-z0-9][a-z0-9_-]*$", name):
+            continue
+        sess = f"{prefix}-{name}"
+        try:
+            r = subprocess.run(["tmux", "has-session", "-t", sess], capture_output=True, timeout=5)
+            if r.returncode != 0:
+                continue
+            if not _is_idle(sess):
+                continue
+            cmd = f"{board} --as {name} inbox"
+            subprocess.run(["tmux", "send-keys", "-t", sess, "-l", cmd], capture_output=True, timeout=5)
+            subprocess.run(["tmux", "send-keys", "-t", sess, "Enter"], capture_output=True, timeout=5)
+        except (subprocess.TimeoutExpired, OSError):
+            continue
+
+
 def cmd_send(db: BoardDB, identity: str, args: list[str]) -> None:
+    assert db.env is not None
+    validate_identity(db, identity)
     name = identity.lower()
     flags, send_args = parse_flags(args, value_flags={"attach": ["--attach", "-a"]})
     attach_file = flags.get("attach")
@@ -24,9 +91,8 @@ def cmd_send(db: BoardDB, identity: str, args: list[str]) -> None:
 
     to = send_args[0].lower()
 
-    if to != "all" and not db.scalar("SELECT COUNT(*) FROM sessions WHERE name=?", (to,)):
-        print(f"ERROR: 收件人 '{to}' 不存在")
-        raise SystemExit(1)
+    if to != "all":
+        db.ensure_session(to)
 
     msg = " ".join(send_args[1:]) if len(send_args) > 1 else ""
 
@@ -38,7 +104,7 @@ def cmd_send(db: BoardDB, identity: str, args: list[str]) -> None:
     stored_path = ""
     h = ""
     if attach_file:
-        path = Path(attach_file)
+        path = Path(str(attach_file))
         if not path.is_file():
             print(f"ERROR: file not found: {attach_file}")
             raise SystemExit(1)
@@ -76,9 +142,14 @@ def cmd_send(db: BoardDB, identity: str, args: list[str]) -> None:
         db.deliver_to_inbox(name, to, msg_id, c=c)
 
     print("OK sent")
+    if attach_ref:
+        print(f"  附件已存储: {stored_path}")
+
+    _nudge_session(db, to)
 
 
 def cmd_status(db: BoardDB, identity: str, args: list[str]) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     if not args:
         print("Usage: ./board --as <name> status <description>")
@@ -90,34 +161,51 @@ def cmd_status(db: BoardDB, identity: str, args: list[str]) -> None:
         "UPDATE sessions SET status=?, updated_at=? WHERE name=?",
         (full_status, now, name),
     )
-    print("OK")
+    print("OK status updated")
 
 
 def cmd_inbox(db: BoardDB, identity: str) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
-    if not db.scalar("SELECT COUNT(*) FROM sessions WHERE name=?", (name,)):
-        print(f"ERROR: 会话 '{name}' 未注册")
-        raise SystemExit(1)
     count = db.scalar("SELECT COUNT(*) FROM inbox WHERE session=? AND read=0", (name,))
     if not count:
-        print("(empty)")
-        return
+        print("收件箱为空")
+    else:
+        rows = db.query(
+            "SELECT i.message_id, m.ts, m.sender, m.body "
+            "FROM inbox i JOIN messages m ON i.message_id=m.id "
+            "WHERE i.session=? AND i.read=0 ORDER BY m.ts",
+            (name,),
+        )
+        max_id = 0
+        for msg_id, msg_ts, sender, body in rows:
+            print(f'<message from="{sender}" ts="{msg_ts}">\n{body}\n</message>')
+            if msg_id > max_id:
+                max_id = msg_id
+        if max_id > 0:
+            _ack_marker_path(db, name).write_text(str(max_id))
+
+    _task_print_queue_short(db, name)
+
+
+def _task_print_queue_short(db: BoardDB, target: str) -> None:
     rows = db.query(
-        "SELECT i.message_id, m.ts, m.sender, m.body "
-        "FROM inbox i JOIN messages m ON i.message_id=m.id "
-        "WHERE i.session=? AND i.read=0 ORDER BY m.ts",
-        (name,),
+        "SELECT id, status, priority, description FROM tasks "
+        "WHERE session=? AND status != 'done' "
+        "ORDER BY CASE status WHEN 'active' THEN 0 ELSE 1 END, priority DESC, id ASC",
+        (target,),
     )
-    max_id = 0
-    for msg_id, msg_ts, sender, body in rows:
-        print(f'<message from="{sender}" ts="{msg_ts}">\n{body}\n</message>')
-        if msg_id > max_id:
-            max_id = msg_id
-    if max_id > 0:
-        _ack_marker_path(db, name).write_text(str(max_id))
+    print("\n任务队列:")
+    if not rows:
+        print("  (无待办任务)")
+        return
+    for tid, status, priority, desc in rows:
+        marker = "*" if status == "active" else " "
+        print(f"  {marker} #{tid} [{status} p{priority}] {desc}")
 
 
 def cmd_ack(db: BoardDB, identity: str) -> None:
+    validate_identity(db, identity)
     name = identity.lower()
     marker = _ack_marker_path(db, name)
     max_id = None
@@ -136,7 +224,7 @@ def cmd_ack(db: BoardDB, identity: str) -> None:
         count = db.scalar("SELECT COUNT(*) FROM inbox WHERE session=? AND read=0", (name,))
 
     if count == 0:
-        print("OK")
+        print("收件箱已经是空的")
         marker.unlink(missing_ok=True)
         return
 
@@ -148,7 +236,7 @@ def cmd_ack(db: BoardDB, identity: str) -> None:
     else:
         db.execute("UPDATE inbox SET read=1 WHERE session=? AND read=0", (name,))
 
-    print(f"OK {count}")
+    print(f"OK {count} 条已清空（完整记录在 messages.log）")
     marker.unlink(missing_ok=True)
 
 

package/lib/board_pending.py

@@ -0,0 +1,233 @@
+"""board_pending — pending actions queue: add / list / verify / retry / resolve."""
+
+import subprocess
+
+from lib.board_db import BoardDB, ts
+from lib.common import parse_flags
+
+
+VALID_TYPES = ("auth", "approve", "confirm")
+PENDING_STATUSES = ("pending", "reminded")
+
+
+def cmd_pending(db: BoardDB, identity: str, args: list[str]) -> None:
+    subcmd = args[0] if args else "list"
+    rest = args[1:] if len(args) > 1 else []
+
+    if subcmd == "add":
+        _pending_add(db, identity, rest)
+    elif subcmd == "list":
+        _pending_list(db, identity, rest)
+    elif subcmd == "verify":
+        _pending_verify(db, identity, rest)
+    elif subcmd == "retry":
+        _pending_retry(db, identity, rest)
+    elif subcmd == "resolve":
+        _pending_resolve(db, identity, rest)
+    else:
+        print("Usage: ./board --as <name> pending {add|list|verify|retry|resolve}")
+        raise SystemExit(1)
+
+
+def _pending_add(db: BoardDB, identity: str, args: list[str]) -> None:
+    name = identity.lower()
+    flags, positional = parse_flags(
+        args,
+        value_flags={
+            "type": ["--type", "-t"],
+            "command": ["--command", "-c"],
+            "reason": ["--reason", "-r"],
+            "verify": ["--verify", "-v"],
+            "retry": ["--retry"],
+        },
+    )
+
+    action_type = str(flags.get("type", "")).lower()
+    command = str(flags.get("command", ""))
+    reason = str(flags.get("reason", ""))
+    verify_cmd = str(flags.get("verify", "")) or None
+    retry_cmd = str(flags.get("retry", "")) or None
+
+    if not action_type or not command or not reason:
+        print("Usage: ./board --as <name> pending add --type <auth|approve|confirm> --command <cmd> --reason <why> [--verify <cmd>] [--retry <cmd>]")
+        raise SystemExit(1)
+
+    if action_type not in VALID_TYPES:
+        print(f"ERROR: 类型必须是 {', '.join(VALID_TYPES)} 之一")
+        raise SystemExit(1)
+
+    now = ts()
+    action_id = db.execute(
+        "INSERT INTO pending_actions(type, command, reason, verify_command, retry_command, created_by, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (action_type, command, reason, verify_cmd, retry_cmd, name, now),
+    )
+    print(f"OK pending #{action_id} added ({action_type})")
+    print(f"  用户需执行: {command}")
+    print(f"  原因: {reason}")
+
+
+def _pending_list(db: BoardDB, identity: str, args: list[str]) -> None:
+    flags, _ = parse_flags(args, bool_flags={"all": ["--all", "-a"]})
+    show_all = bool(flags.get("all"))
+
+    if show_all:
+        rows = db.query(
+            "SELECT id, type, command, reason, verify_command, retry_command, status, created_by, created_at, resolved_at "
+            "FROM pending_actions ORDER BY id"
+        )
+    else:
+        rows = db.query(
+            "SELECT id, type, command, reason, verify_command, retry_command, status, created_by, created_at, resolved_at "
+            "FROM pending_actions WHERE status IN ('pending', 'reminded') ORDER BY id"
+        )
+
+    if not rows:
+        print("无待处理操作" if not show_all else "无操作记录")
+        return
+
+    print("=== 待处理操作 ===" if not show_all else "=== 所有操作 ===")
+    print()
+    for row in rows:
+        aid, atype, cmd, reason, verify, retry, status, creator, created, resolved = row
+        status_icon = {"pending": "⏳", "reminded": "🔔", "done": "✓", "retried": "✓✓", "failed": "✗"}.get(status, "?")
+        print(f"  #{aid} [{status_icon} {status}] ({atype}) by {creator}")
+        print(f"    用户需执行: ! {cmd}")
+        print(f"    原因: {reason}")
+        if verify:
+            print(f"    验证命令: {verify}")
+        if retry:
+            print(f"    重试命令: {retry}")
+        if resolved:
+            print(f"    完成于: {resolved}")
+        print()
+
+
+def _pending_verify(db: BoardDB, identity: str, args: list[str]) -> None:
+    specific_id = None
+    if args:
+        try:
+            specific_id = int(args[0].lstrip("#"))
+        except ValueError:
+            print("Usage: ./board --as <name> pending verify [#id]")
+            raise SystemExit(1)
+
+    if specific_id:
+        rows = db.query(
+            "SELECT id, verify_command, command FROM pending_actions WHERE id=? AND status IN ('pending', 'reminded')",
+            (specific_id,),
+        )
+    else:
+        rows = db.query(
+            "SELECT id, verify_command, command FROM pending_actions WHERE status IN ('pending', 'reminded') AND verify_command IS NOT NULL ORDER BY id"
+        )
+
+    if not rows:
+        print("无可验证的操作")
+        return
+
+    verified = 0
+    failed = 0
+    for aid, verify_cmd, cmd in rows:
+        if not verify_cmd:
+            continue
+        try:
+            r = subprocess.run(verify_cmd, shell=True, capture_output=True, text=True, timeout=30)
+            if r.returncode == 0:
+                now = ts()
+                db.execute(
+                    "UPDATE pending_actions SET status='done', resolved_at=? WHERE id=?",
+                    (now, aid),
+                )
+                print(f"  #{aid}: 验证通过 ✓")
+                verified += 1
+            else:
+                db.execute("UPDATE pending_actions SET status='reminded' WHERE id=?", (aid,))
+                print(f"  #{aid}: 验证失败 — 用户仍需执行: ! {cmd}")
+                failed += 1
+        except subprocess.TimeoutExpired:
+            print(f"  #{aid}: 验证超时")
+            failed += 1
+        except OSError as e:
+            print(f"  #{aid}: 验证出错: {e}")
+            failed += 1
+
+    print(f"\n验证结果: {verified} 通过, {failed} 未通过")
+
+
+def _pending_retry(db: BoardDB, identity: str, args: list[str]) -> None:
+    specific_id = None
+    if args:
+        try:
+            specific_id = int(args[0].lstrip("#"))
+        except ValueError:
+            print("Usage: ./board --as <name> pending retry [#id]")
+            raise SystemExit(1)
+
+    if specific_id:
+        rows = db.query(
+            "SELECT id, retry_command FROM pending_actions WHERE id=? AND status='done'",
+            (specific_id,),
+        )
+    else:
+        rows = db.query(
+            "SELECT id, retry_command FROM pending_actions WHERE status='done' AND retry_command IS NOT NULL ORDER BY id"
+        )
+
+    if not rows:
+        print("无可重试的操作（需先通过验证）")
+        return
+
+    retried = 0
+    failed = 0
+    for aid, retry_cmd in rows:
+        if not retry_cmd:
+            continue
+        try:
+            r = subprocess.run(retry_cmd, shell=True, capture_output=True, text=True, timeout=60)
+            if r.returncode == 0:
+                db.execute("UPDATE pending_actions SET status='retried' WHERE id=?", (aid,))
+                print(f"  #{aid}: 重试成功 ✓")
+                retried += 1
+            else:
+                db.execute("UPDATE pending_actions SET status='failed' WHERE id=?", (aid,))
+                print(f"  #{aid}: 重试失败 — {r.stderr.strip() or r.stdout.strip() or 'exit ' + str(r.returncode)}")
+                failed += 1
+        except subprocess.TimeoutExpired:
+            db.execute("UPDATE pending_actions SET status='failed' WHERE id=?", (aid,))
+            print(f"  #{aid}: 重试超时")
+            failed += 1
+        except OSError as e:
+            db.execute("UPDATE pending_actions SET status='failed' WHERE id=?", (aid,))
+            print(f"  #{aid}: 重试出错: {e}")
+            failed += 1
+
+    print(f"\n重试结果: {retried} 成功, {failed} 失败")
+
+
+def _pending_resolve(db: BoardDB, identity: str, args: list[str]) -> None:
+    if not args:
+        print("Usage: ./board --as <name> pending resolve <#id>")
+        raise SystemExit(1)
+
+    try:
+        action_id = int(args[0].lstrip("#"))
+    except ValueError:
+        print("Usage: ./board --as <name> pending resolve <#id>")
+        raise SystemExit(1)
+
+    row = db.query_one("SELECT status FROM pending_actions WHERE id=?", (action_id,))
+    if not row:
+        print(f"ERROR: pending #{action_id} 不存在")
+        raise SystemExit(1)
+
+    if row[0] not in PENDING_STATUSES:
+        print(f"pending #{action_id} 已是 {row[0]} 状态")
+        return
+
+    now = ts()
+    db.execute(
+        "UPDATE pending_actions SET status='done', resolved_at=? WHERE id=?",
+        (now, action_id),
+    )
+    print(f"OK pending #{action_id} 已手动标记为完成")

package/lib/board_pulse.py

@@ -0,0 +1,14 @@
+"""board_pulse — lightweight heartbeat + unread count for PostToolBatch hook."""
+
+from lib.board_db import BoardDB, ts
+from lib.common import validate_identity
+
+
+def cmd_pulse(db: BoardDB, identity: str) -> None:
+    name = identity.lower()
+    validate_identity(db, identity)
+    now = ts()
+    db.execute("UPDATE sessions SET last_heartbeat=? WHERE name=?", (now, name))
+    count = db.scalar("SELECT COUNT(*) FROM inbox WHERE session=? AND read=0", (name,))
+    if count:
+        print(f"{count} 条未读")