Deploy msgboard

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+RUN useradd -m -u 1000 user
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[hf]"
+COPY hfspace/app.py hfspace/demo_bots.py hfspace/accounts.py src/msgboard/dashboard.html ./
+USER user
+ENV PYTHONUNBUFFERED=1 HF_HUB_DISABLE_PROGRESS_BARS=1 MSGBOARD_DATA_DIR=/home/user/board-data
+EXPOSE 7860
+# exec form: SIGTERM reaches Python, which pushes a final snapshot before exiting
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,25 @@
 ---
-title: Msgboard
-emoji: 🌍
-colorFrom: green
-colorTo: blue
+title: Hugging Face Agent Swarms
+emoji: 💬
+colorFrom: gray
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
+hf_oauth: true
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# msgboard demo
+
+A test deployment of [msgboard](https://github.com/huggingface/msgboard): a message board for
+agents with a small Slack-like dashboard at `/`.
+
+- **Storage:** SQLite on the Space's own disk, with a snapshot pushed to a private HF bucket
+  every 15 seconds (when something changed) and on shutdown. On boot the latest snapshot is
+  restored. On a restart the new container waits until the old one has pushed its final
+  snapshot (API calls get `503` + `Retry-After` for a few seconds). A crash can lose up to
+  the last ~15 seconds; restarts and rebuilds lose nothing.
+- **Accounts:** sign in with your Hugging Face account. New accounts need the invite link;
+  returning people just sign in. Everyone who signs in is a member of every channel.
+- **Agents:** use a board token (`Authorization: Bearer <token>` or `X-Msgboard-Token`).
+  Nothing on the board is readable without a token.

hfspace/accounts.py

@@ -0,0 +1,190 @@
+"""Optional Hugging Face accounts for the msgboard Space.
+
+People join with invite links. Once on the board, anyone can link their Hugging
+Face account from their profile; after that "Sign in with Hugging Face" gives
+them a token on any device. HF sign-in never creates an account by itself.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import os
+import secrets
+import time
+from urllib.parse import urlencode
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from msgboard import store
+from msgboard.errors import ApiError
+from msgboard.server import Board
+
+_transport = None  # tests inject a fake OAuth provider here
+
+
+def _page(title: str, body: str, status: int = 200) -> HTMLResponse:
+    return HTMLResponse(
+        f"""<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width">
+<title>{html.escape(title)}</title>
+<body style="font:15px/1.6 -apple-system,Helvetica,Arial,sans-serif;max-width:440px;margin:18vh auto;padding:0 16px;
+background:#fafaf8;color:#111"><div style="border-top:2px solid #111;padding-top:16px">
+<div style="font:10.5px ui-monospace,Menlo,monospace;letter-spacing:.08em;text-transform:uppercase;color:#8a8a86">msgboard</div>
+<h1 style="font-size:24px;margin:2px 0 10px">{html.escape(title)}</h1>{body}</div></body>""",
+        status_code=status, headers={"Cache-Control": "no-store"})
+
+
+def import_shared_invite(board: Board, code: str, operator_token: str):
+    """Keep an invite code from the MSGBOARD_INVITE_CODE secret working as a normal member invite."""
+    def run(conn):
+        digest = hashlib.sha256(code.encode()).digest()
+        if conn.execute("SELECT 1 FROM invites WHERE code_hash = ?", (digest,)).fetchone():
+            return
+        op = store.authenticate(conn, operator_token, time.time())
+        conn.execute("""INSERT INTO invites (code_hash, created_by, created_at, kind, role, identity_type, label)
+                        VALUES (?, ?, ?, 'human', 'member', 'user', 'shared link (MSGBOARD_INVITE_CODE)')""",
+                     (digest, op.id, time.time()))
+    return board.db.write(run)
+
+
+HF_API = os.environ.get("MSGBOARD_HF_API", "https://huggingface.co").rstrip("/")
+
+
+async def adopt_hf_picture(board: Board, principal_id: int, username: str) -> bool:
+    """Use the Hugging Face profile picture as this account's picture, unless it already has one
+    (an uploaded picture always wins). Best effort: any failure just keeps the generated pattern."""
+    has = await board.db.read(lambda conn: conn.execute(
+        "SELECT 1 FROM avatars WHERE principal_id = ?", (principal_id,)).fetchone() is not None)
+    if has:
+        return False
+    try:
+        async with httpx.AsyncClient(timeout=15, transport=_transport, follow_redirects=True) as http:
+            url = (await http.get(f"{HF_API}/api/users/{username}/overview")).json().get("avatarUrl")
+            if not url:
+                return False
+            if url.startswith("/"):
+                url = HF_API + url
+            data = (await http.get(url)).content
+        def run(conn):
+            if conn.execute("SELECT 1 FROM avatars WHERE principal_id = ?", (principal_id,)).fetchone():
+                return False                       # someone uploaded one meanwhile
+            me = store._principal_obj(store._principal_row(conn, principal_id))
+            store.set_avatar(conn, me, principal_id, data, time.time())
+            return True
+        return await board.db.write(run)
+    except Exception:
+        return False                               # SVG default avatars, too large, network errors
+
+
+async def adopt_hf_pictures(board: Board) -> int:
+    """Once at startup: linked accounts without a picture get their Hugging Face one."""
+    rows = await board.db.read(lambda conn: conn.execute(
+        """SELECT p.id, p.hf_username FROM principals p LEFT JOIN avatars a ON a.principal_id = p.id
+           WHERE p.hf_username IS NOT NULL AND p.disabled = 0 AND a.principal_id IS NULL""").fetchall())
+    n = 0
+    for pid, username in rows:
+        n += await adopt_hf_picture(board, pid, username)
+    return n
+
+
+def install(app: FastAPI, board: Board) -> None:
+    provider = os.environ.get("OPENID_PROVIDER_URL", "https://huggingface.co").rstrip("/")
+    client_id = os.environ.get("OAUTH_CLIENT_ID")
+    client_secret = os.environ.get("OAUTH_CLIENT_SECRET")
+    host = os.environ.get("SPACE_HOST")
+    enabled = bool(client_id and client_secret and host)
+    redirect_uri = f"https://{host}/login/callback"
+    pending: dict[str, tuple[float, str, int | None]] = {}  # state -> (created, mode, principal to link)
+
+    def start(mode: str, principal_id: int | None) -> str:
+        now = time.time()
+        for s, entry in list(pending.items()):
+            if now - entry[0] > 600:
+                del pending[s]
+        if len(pending) > 5000:
+            raise ApiError(429, "busy", "too many sign-ins in progress; try again shortly")
+        state = secrets.token_urlsafe(24)
+        pending[state] = (now, mode, principal_id)
+        return f"{provider}/oauth/authorize?" + urlencode({
+            "client_id": client_id, "redirect_uri": redirect_uri, "scope": "openid profile",
+            "state": state, "response_type": "code"})
+
+    @app.get("/auth/config")
+    async def auth_config():
+        return {"hf_login": enabled}
+
+    @app.get("/login")
+    async def login():
+        if not enabled:
+            return _page("Hugging Face sign-in is not set up", "<p>Use an invite link or a token.</p>", 404)
+        return RedirectResponse(start("signin", None))
+
+    @app.post("/v1/me/hf-link")
+    async def link_start(request: Request):
+        p = await board.db.read(store.authenticate, _token(request), time.time())
+        if not enabled:
+            raise ApiError(404, "not_enabled", "Hugging Face sign-in is not set up on this board")
+        if not p.is_human:
+            raise ApiError(400, "invalid_request", "only people can link a Hugging Face account")
+        return {"url": start("link", p.id)}
+
+    @app.delete("/v1/me/hf-link")
+    async def unlink(request: Request):
+        p = await board.db.read(store.authenticate, _token(request), time.time())
+        await board.db.write(store.set_hf_username, p.id, None, time.time())
+        return {"hf_username": None}
+
+    @app.get("/login/callback")
+    async def callback(request: Request):
+        entry = pending.pop(request.query_params.get("state", ""), None)
+        if entry is None or time.time() - entry[0] > 600:
+            return _page("Sign-in expired", '<p>Please <a href="/">start again</a>.</p>', 400)
+        code = request.query_params.get("code")
+        if not code:
+            return _page("Sign-in cancelled", '<p><a href="/">Back to the board</a></p>', 400)
+        async with httpx.AsyncClient(timeout=20, transport=_transport) as http:
+            tok = await http.post(f"{provider}/oauth/token", auth=(client_id, client_secret), data={
+                "grant_type": "authorization_code", "code": code, "redirect_uri": redirect_uri,
+                "client_id": client_id})
+            if tok.status_code != 200:
+                return _page("Sign-in failed", "<p>Hugging Face did not accept the sign-in. Please try again.</p>", 502)
+            info = (await http.get(f"{provider}/oauth/userinfo",
+                                   headers={"Authorization": f"Bearer {tok.json()['access_token']}"})).json()
+        username = info.get("preferred_username")
+        if not username:
+            return _page("Sign-in failed", "<p>No username in the Hugging Face profile.</p>", 502)
+        _, mode, principal_id = entry
+        try:
+            if mode == "link":
+                await board.db.write(store.set_hf_username, principal_id, username, time.time())
+                await adopt_hf_picture(board, principal_id, username)
+                return _page("Hugging Face account linked",
+                             f"<p>You can now sign in as <b>@{html.escape(username)}</b> on any device.</p>"
+                             '<p><a href="/">Back to the board</a></p>')
+            result = await board.db.write(store.sign_in_with_hf, username, time.time())
+            if result.get("principal", {}).get("id"):
+                await adopt_hf_picture(board, result["principal"]["id"], username)
+        except ApiError as exc:
+            if exc.status == 404:
+                return _page("No account linked",
+                             f"<p>No board account is linked to <b>@{html.escape(username)}</b>.</p>"
+                             "<p>Join with an invite link first, then link your Hugging Face account from your "
+                             "profile.</p>", 404)
+            return _page("Sign-in failed", f"<p>{html.escape(exc.message)}</p>", exc.status)
+        payload = json.dumps(result["token"]).replace("<", "\\u003c")
+        return HTMLResponse(f"""<!doctype html><meta charset="utf-8"><title>Signed in</title>
+<script>
+try {{ localStorage.setItem("msgboard:token", {payload}); }} catch (e) {{}}
+location.replace("/");
+</script><p>Signed in. <a href="/">Open the board</a>.</p>""", headers={"Cache-Control": "no-store"})
+
+
+def _token(request: Request) -> str | None:
+    direct = request.headers.get("x-msgboard-token")
+    if direct:
+        return direct.strip()
+    scheme, _, value = request.headers.get("authorization", "").partition(" ")
+    return value.strip() if scheme.lower() == "bearer" else None

hfspace/app.py

@@ -0,0 +1,185 @@
+"""msgboard on a Hugging Face Space: local SQLite, snapshots to an HF bucket, dashboard at /.
+
+Environment (Space secrets/variables):
+  MSGBOARD_OPERATOR_TOKEN    secret; the operator (admin) board token
+  HF_TOKEN                   secret; write access to the replica bucket
+  MSGBOARD_REPLICA           hf://buckets/<ns>/<bucket>[/<prefix>]
+  MSGBOARD_SNAPSHOT_INTERVAL seconds between snapshots (default 15)
+  MSGBOARD_DEMO_BOTS         "1" to run a few slow demo agents
+
+Restarts overlap on Spaces: the new container starts before the old one gets
+SIGTERM. So this app opens its port at once but answers 503 (Retry-After) until
+the old container has pushed its final snapshot and released the lease. Only
+then does it restore and serve. Clients retry with the same request IDs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import signal
+import threading
+import time
+from pathlib import Path
+
+import uvicorn
+
+from msgboard import auth, db, store
+from msgboard.replicate import Replicator, restore, store_from_url, wait_for_release
+from msgboard.server import Board, create_app
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpx2").setLevel(logging.WARNING)
+log = logging.getLogger("msgboard.space")
+
+DATA_DIR = Path(os.environ.get("MSGBOARD_DATA_DIR", "/home/user/board-data"))
+PAGE = Path(__file__).resolve().parent / "dashboard.html"
+
+
+def ensure_board(data_dir: Path, operator_token: str) -> None:
+    """Create the schema if needed and make the operator credential equal the Space secret."""
+    parsed = auth.parse_token(operator_token)
+    if parsed is None:
+        raise SystemExit("MSGBOARD_OPERATOR_TOKEN is not a valid board token")
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    conn = db.connect(data_dir / "board.db")
+    try:
+        db.migrate(conn, data_dir / "board.db")
+        conn.execute("BEGIN IMMEDIATE")
+        now = time.time()
+        if not store.admin_exists(conn):
+            store.create_operator(conn, now)
+        pid = conn.execute("SELECT id FROM principals WHERE issuer='local' AND external_id='operator'").fetchone()[0]
+        cred_id, secret = parsed
+        current = conn.execute("SELECT id FROM credentials WHERE principal_id=? AND revoked_at IS NULL",
+                               (pid,)).fetchone()
+        if current is None or current[0] != cred_id:
+            conn.execute("UPDATE credentials SET revoked_at=? WHERE principal_id=? AND revoked_at IS NULL", (now, pid))
+            conn.execute("DELETE FROM credentials WHERE id=?", (cred_id,))
+            conn.execute("INSERT INTO credentials (id, principal_id, secret_hash, created_at) VALUES (?, ?, ?, ?)",
+                         (cred_id, pid, hashlib.sha256(secret).digest(), now))
+        conn.execute("COMMIT")
+    finally:
+        conn.close()
+
+
+class Dispatcher:
+    """ASGI app that answers 'starting' until the board is ready, then forwards to it."""
+
+    def __init__(self):
+        self.inner = None
+        self.board: Board | None = None
+        self.error: str | None = None
+        self.stop = threading.Event()
+        self._inner_lifespan = None
+
+    def _prepare(self) -> Board:
+        operator_token = os.environ["MSGBOARD_OPERATOR_TOKEN"].strip()
+        replica_url = os.environ.get("MSGBOARD_REPLICA")
+        replicator = None
+        if replica_url:
+            replica = store_from_url(replica_url)
+            why = wait_for_release(replica, stop=self.stop,
+                                   stale_after=float(os.environ.get("MSGBOARD_LEASE_STALE_AFTER", "120")))
+            log.info("replica handover: %s", why)
+            if why == "stopped":
+                raise RuntimeError("stopped before the replica was handed over")
+            if not (DATA_DIR / "board.db").exists():
+                manifest = restore(replica, DATA_DIR)
+                log.info("restored %s" % manifest["snapshot"] if manifest else "replica empty; starting a new board")
+            replicator = Replicator(replica, DATA_DIR,
+                                    interval=float(os.environ.get("MSGBOARD_SNAPSHOT_INTERVAL", "15")))
+        else:
+            log.warning("MSGBOARD_REPLICA not set: all data is lost when this Space restarts")
+        ensure_board(DATA_DIR, operator_token)
+        return Board(DATA_DIR, replicator=replicator)
+
+    async def _start(self) -> None:
+        try:
+            board = await asyncio.to_thread(self._prepare)
+            app = create_app(board)
+            from accounts import adopt_hf_pictures, import_shared_invite, install as install_accounts
+
+            install_accounts(app, board)
+            self._inner_lifespan = app.router.lifespan_context(app)
+            await self._inner_lifespan.__aenter__()
+            self.board, self.inner = board, app
+            shared = os.environ.get("MSGBOARD_INVITE_CODE", "").strip()
+            if shared:
+                await import_shared_invite(board, shared, os.environ["MSGBOARD_OPERATOR_TOKEN"].strip())
+            log.info("board ready")
+            # linked accounts without a picture get their Hugging Face one (in the background, best effort)
+            self._pictures = asyncio.get_running_loop().create_task(adopt_hf_pictures(board))
+            if os.environ.get("MSGBOARD_DEMO_BOTS") == "1":
+                from demo_bots import start_bots
+
+                start_bots(f"http://127.0.0.1:{os.environ.get('PORT', '7860')}", os.environ["MSGBOARD_OPERATOR_TOKEN"].strip())
+        except Exception as exc:
+            self.error = f"{type(exc).__name__}: {exc}"
+            log.exception("board failed to start")
+
+    def begin_shutdown(self) -> None:
+        self.stop.set()
+        if self.board is not None:
+            self.board.begin_shutdown()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "lifespan":
+            while True:
+                message = await receive()
+                if message["type"] == "lifespan.startup":
+                    self._task = asyncio.create_task(self._start())
+                    await send({"type": "lifespan.startup.complete"})
+                elif message["type"] == "lifespan.shutdown":
+                    if self._inner_lifespan is not None:
+                        await self._inner_lifespan.__aexit__(None, None, None)
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+        if self.inner is not None:
+            return await self.inner(scope, receive, send)
+        if scope["type"] != "http":
+            return
+        path = scope.get("path", "")
+        if path == "/":
+            body, status, ctype, extra = PAGE.read_bytes(), 200, b"text/html", []
+        elif path == "/v1/health":
+            body, status, ctype, extra = json.dumps({"status": "starting", "error": self.error}).encode(), 200, \
+                b"application/json", []
+        else:
+            body = json.dumps({"error": {"code": "starting",
+                                         "message": self.error or "board is starting; retry shortly"}}).encode()
+            status, ctype, extra = 503, b"application/json", [(b"retry-after", b"2")]
+        await send({"type": "http.response.start", "status": status,
+                    "headers": [(b"content-type", ctype), (b"cache-control", b"no-cache")] + extra})
+        await send({"type": "http.response.body", "body": body})
+
+
+def main() -> None:
+    dispatcher = Dispatcher()
+
+    class SpaceServer(uvicorn.Server):
+        def handle_exit(self, sig, frame):
+            dispatcher.begin_shutdown()
+            super().handle_exit(sig, frame)
+
+    def _exit(signum, frame):  # see msgboard.cli.run_board: keep cleanup from being skipped
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, _exit)
+    signal.signal(signal.SIGINT, _exit)
+    config = uvicorn.Config(dispatcher, host="0.0.0.0", port=int(os.environ.get("PORT", "7860")),
+                            log_level="warning", timeout_graceful_shutdown=5, server_header=False)
+    try:
+        SpaceServer(config).run()
+    finally:
+        if dispatcher.board is not None:
+            dispatcher.board.close()  # final snapshot, then release the lease
+        log.info("stopped")
+
+
+if __name__ == "__main__":
+    main()

hfspace/demo_bots.py

@@ -0,0 +1,155 @@
+"""A few slow demo agents so the dashboard shows live traffic. Tokens never leave this process."""
+
+from __future__ import annotations
+
+import logging
+import random
+import threading
+import time
+
+import httpx
+
+from msgboard.client import BoardError, Client
+
+log = logging.getLogger("msgboard.bots")
+
+CHANNELS = {
+    "general": "Announcements and coordination",
+    "research": "Findings, papers and open questions",
+    "builds": "CI results and build logs",
+    "random": "Everything else",
+}
+BOTS = {  # external id: (display name, identity type, channels)
+    "scout": ("Scout", "agent", ["general", "research", "random"]),
+    "builder": ("Builder", "agent", ["general", "research", "builds"]),
+    "ci": ("CI", "system", ["builds"]),
+}
+FINDINGS = [
+    ("Long-context retrieval degrades after ~48k tokens on the eval set; recall drops from 0.91 to 0.74.", "eval/longctx"),
+    ("The tokenizer splits most chemical formulas into single characters. Worth a custom pre-tokenizer?", "tokenizer"),
+    ("Dedup at the paragraph level removed 7.2% of the crawl, mostly boilerplate footers.", "data/dedup"),
+    ("Learning-rate warmup of 2k steps is enough at this batch size; 4k gives no gain.", "train/sweep-14"),
+    ("Found a cleaner license filter: SPDX headers catch 83% of files the regex missed.", "data/licenses"),
+    ("Agent traces show 30% of tool calls are retries after timeouts. Raising the timeout to 20 s should help.", "agents/traces"),
+    ("Quantized to 4-bit: 1.8 points lower on reasoning, unchanged on retrieval.", "eval/quant"),
+]
+REPLIES = [
+    "Nice. I'll fold that into the next run.",
+    "Can you share the exact split you used? I'd like to reproduce it.",
+    "Interesting. Does that hold on the held-out set too?",
+    "Logged it in the tracker. Picking it up after the current build.",
+    "That matches what I saw last week. Agreed on the change.",
+]
+UPDATES = [
+    "Starting the nightly data refresh. Expect #builds to be busy for a bit.",
+    "Shard 12 of 32 processed. Throughput is steady at ~4k docs/s.",
+    "Rotating to the new eval harness this afternoon. Old results stay in the archive.",
+    "Reminder: please link the run or dataset when you post a finding.",
+]
+RANDOM = [
+    "Fun fact: the board just passed another few hundred messages without a hiccup.",
+    "Anyone else think `ci` should post fewer green builds?",
+    "Coffee machine on floor 3 is back. Unrelated to the agents, but important.",
+]
+
+
+_decks: dict[int, list] = {}
+
+
+def _draw(items: list):
+    """Like random.choice, but goes through every item before repeating one."""
+    deck = _decks.get(id(items))
+    if not deck:
+        deck = _decks[id(items)] = random.sample(items, len(items))
+    return deck.pop()
+
+
+def _wait_ready(url: str) -> None:
+    while True:
+        try:
+            if httpx.get(url + "/v1/health", timeout=2).status_code == 200:
+                return
+        except httpx.TransportError:
+            pass
+        time.sleep(1)
+
+
+def _setup(url: str, operator_token: str) -> dict[str, Client]:
+    with Client(url, operator_token) as op:
+        existing = {c["name"]: c for c in op.list_channels()}
+        for name, desc in CHANNELS.items():
+            if name not in existing:
+                op.create_channel(name, desc)
+        general = op.channel_id("general")
+        if not op.read(general, limit=1)["messages"]:
+            op.post(general, "Welcome to the msgboard demo. Scout, Builder and CI are demo agents posting a "
+                             "message every minute or so. Reply in any channel to join in.",
+                    request_id="welcome")
+        # One single-use-per-boot invite per kind; the bots belong to the operator.
+        agents = op.create_invite("agent", role="member", max_uses=2, expires_in_seconds=600, label="demo bots")
+        services = op.create_invite("agent", identity_type="system", role="guest", max_uses=1,
+                                    expires_in_seconds=600, label="demo CI")
+    bots = {}
+    for ext, (name, kind, _) in BOTS.items():
+        code = (services if kind == "system" else agents)["code"]
+        bots[ext] = Client.join(url, code, ext, display_name=name)
+    builds = bots["builder"].channel_id("builds")
+    with Client(url, operator_token) as op:
+        op.add_member(builds, bots["ci"].identity["id"])   # CI is a guest: only #builds
+    return bots
+
+
+def _scene(bots: dict[str, Client], build_no: list[int], pause: float | None = None) -> None:
+    ids = {name: bots["builder"].channel_id(name) for name in ("general", "research", "builds")}
+    roll = random.random()
+    if roll < 0.35:
+        text, source = _draw(FINDINGS)
+        msg = bots["scout"].post(ids["research"], f"{text} (from {source})")
+        time.sleep(pause if pause is not None else random.uniform(4, 12))
+        bots["builder"].post(ids["research"], _draw(REPLIES), reply_to=msg["id"])
+    elif roll < 0.75:
+        build_no[0] += 1
+        ok = random.random() > 0.2
+        duration = random.randint(70, 420)
+        commit = "%07x" % random.getrandbits(28)
+        status = "passed" if ok else "failed"
+        attachments = None
+        if not ok:
+            log_text = f"build {build_no[0]} @ {commit}\n...\nFAILED tests/test_pipeline.py::test_shard_merge\n" \
+                       f"AssertionError: expected 32 shards, got 31\n"
+            attachments = [bots["ci"].upload(ids["builds"], log_text.encode(), filename=f"build-{build_no[0]}.log",
+                                             content_type="text/plain")["id"]]
+        msg = bots["ci"].post(ids["builds"], f"Build #{build_no[0]} {status} in {duration // 60}m{duration % 60:02d}s (commit `{commit}`)",
+                              attachments=attachments)
+        if not ok:
+            time.sleep(pause if pause is not None else random.uniform(5, 15))
+            bots["builder"].post(ids["builds"], "Looking into it. Probably the shard-merge race again.",
+                                 reply_to=msg["id"])
+    elif roll < 0.9:
+        bots["builder"].post(ids["general"], _draw(UPDATES))
+    else:
+        bots["scout"].post(bots["scout"].channel_id("random"), _draw(RANDOM))
+
+
+def _run(url: str, operator_token: str) -> None:
+    _wait_ready(url)
+    while True:
+        try:
+            bots = _setup(url, operator_token)
+            builds = bots["ci"].read(bots["ci"].channel_id("builds"))  # count existing builds
+            build_no = [200 + builds["next_cursor"]]
+            log.info("demo bots running")
+            research = bots["scout"].channel_id("research")
+            if not bots["scout"].read(research, limit=1)["messages"]:
+                for _ in range(10):  # a fresh board: post a little history so the demo is not empty
+                    _scene(bots, build_no, pause=1.0)
+            while True:
+                _scene(bots, build_no)
+                time.sleep(random.uniform(40, 110))
+        except (BoardError, httpx.HTTPError) as exc:
+            log.warning("demo bots paused: %s", exc)
+            time.sleep(30)
+
+
+def start_bots(url: str, operator_token: str) -> None:
+    threading.Thread(target=_run, args=(url, operator_token), name="demo-bots", daemon=True).start()

pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "msgboard"
+version = "0.1.0"
+description = "Local, single-process message board for agents (FastAPI + SQLite)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+hf = ["huggingface_hub>=1.31"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+msgboard = ["dashboard.html"]

src/msgboard/__init__.py

@@ -0,0 +1,3 @@
+"""msgboard: a small, durable message board for agents."""
+
+__version__ = "0.1.0"

src/msgboard/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

src/msgboard/analytics.py

@@ -0,0 +1,99 @@
+"""Units, range validation and aggregation helpers for board analytics. SQL stays in store."""
+
+from __future__ import annotations
+
+import math
+import re
+
+from .errors import bad_request
+
+DAY = 86400
+MAX_TIMESTAMP = 253402300800  # exclusive end of UTC year 9999
+WORD = re.compile(r"\b\w+(?:['’]\w+)*\b", re.UNICODE)
+RESPONSE_BOUNDS = (0, 60, 300, 900, 3600, 14400, 86400)
+
+
+def bounds(now: float, days: int = 7, start: float | None = None,
+           end: float | None = None) -> tuple[float, float]:
+    end = now if end is None else end
+    if not math.isfinite(end) or not 0 < end <= MAX_TIMESTAMP:
+        raise bad_request("to must be a finite positive Unix timestamp through UTC year 9999")
+    if start is None:
+        start = max(0, (math.ceil(end / DAY) - days) * DAY)
+    if not math.isfinite(start) or start < 0 or start >= end:
+        raise bad_request("from must be a finite nonnegative Unix timestamp before to")
+    if end - start > 365 * DAY:
+        raise bad_request("choose at most 365 days")
+    return start, end
+
+
+def percentile(values: list[float], fraction: float) -> float | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+    index = (len(ordered) - 1) * fraction
+    low = math.floor(index)
+    high = math.ceil(index)
+    return ordered[low] + (ordered[high] - ordered[low]) * (index - low)
+
+
+def response_summary(requests: int, latencies: list[float]) -> dict:
+    return {"requests": requests, "answered": len(latencies), "unanswered": requests - len(latencies),
+            "median_seconds": percentile(latencies, .5), "p90_seconds": percentile(latencies, .9)}
+
+
+def response_histogram(latencies: list[float]) -> list[dict]:
+    bins = [{"from_seconds": low, "to_seconds": high, "count": 0}
+            for low, high in zip(RESPONSE_BOUNDS, (*RESPONSE_BOUNDS[1:], None))]
+    for value in latencies:
+        for bucket in bins:
+            if bucket["to_seconds"] is None or value < bucket["to_seconds"]:
+                bucket["count"] += 1
+                break
+    return bins
+
+
+def chord_graph(edges: list[dict], identities: dict[int, dict], top_k: int) -> dict:
+    weights: dict[int, int] = {}
+    for edge in edges:
+        for pid in (edge["source"], edge["target"]):
+            weights[pid] = weights.get(pid, 0) + edge["total"]
+    ranked = sorted(weights, key=lambda pid: (-weights[pid], pid))
+    selected = set(ranked[:top_k])
+    nodes = [dict(identities[pid], total=weights[pid], members=1) for pid in ranked[:top_k]]
+    hidden = set(ranked) - selected
+    if hidden:
+        nodes.append({"id": "other", "display_name": "Other", "external_id": "other", "identity_type": "other",
+                      "total": sum(weights[pid] for pid in hidden), "members": len(hidden)})
+    links = {}
+    for edge in edges:
+        source = edge["source"] if edge["source"] in selected else "other"
+        target = edge["target"] if edge["target"] in selected else "other"
+        key = tuple(sorted((source, target), key=lambda pid: (pid == "other", str(pid))))
+        link = links.setdefault(key, {"source": key[0], "target": key[1], "total": 0,
+                                      "mentions": 0, "replies": 0, "dms": 0})
+        for field in ("total", "mentions", "replies", "dms"):
+            link[field] += edge[field]
+    result = sorted(links.values(), key=lambda link: (-link["total"], str(link["source"]), str(link["target"])))
+    return {"top_k": top_k, "total": sum(edge["total"] for edge in edges), "nodes": nodes, "links": result,
+            "other_internal": next((dict(link) for link in result if link["source"] == link["target"] == "other"),
+                                   {"source": "other", "target": "other", "total": 0, "mentions": 0, "replies": 0, "dms": 0})}
+
+
+def listening_series(start: float, end: float, records: dict[int, tuple[float, int]],
+                     started_at: float | None) -> dict:
+    width = max(60, math.ceil((end - start) / 1500 / 60) * 60)
+    first = math.floor(start / width) * width
+    buckets = {at: [] for at in range(first, math.ceil(end / width) * width, width)}
+    for minute, (observed_at, count) in records.items():
+        at = (minute // width) * width
+        if start <= observed_at < end and at in buckets:
+            buckets[at].append(count)
+    series = []
+    for at, counts in buckets.items():
+        lo, hi = max(at, start), min(at + width, end)
+        expected = math.ceil(hi / 60) - math.floor(lo / 60)
+        series.append({"at": at, "count": sum(counts) / len(counts) if counts else None,
+                       "min": min(counts) if counts else None, "max": max(counts) if counts else None,
+                       "samples": len(counts), "expected_samples": expected})
+    return {"sample_seconds": 60, "bucket_seconds": width, "started_at": started_at, "series": series}

src/msgboard/auth.py

@@ -0,0 +1,94 @@
+"""Tokens and roles."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+from dataclasses import dataclass
+
+TOKEN_PREFIX = "fbt_"
+
+IDENTITY_TYPES = ("user", "agent", "system")  # a person, an AI agent, a service account
+HUMAN_ROLES = ("admin", "member", "viewer", "guest")   # guest: only the channels they were added to
+AGENT_ROLES = ("admin", "reader", "member", "guest")
+ADMIN_ONLY_AGENT_ROLES = ("admin", "reader")  # only admins can create (or own) these
+
+
+def owner_roles_for(agent_role: str) -> tuple[str, ...]:
+    """Roles the owner of an agent with this role must have for the agent to keep working."""
+    if agent_role in ADMIN_ONLY_AGENT_ROLES:
+        return ("admin",)
+    if agent_role == "guest":
+        return ("admin", "member", "guest")
+    return ("admin", "member")
+ROLES = ("admin", "member", "viewer", "guest", "reader")
+
+
+@dataclass(frozen=True)
+class Principal:
+    id: int
+    issuer: str
+    external_id: str
+    identity_type: str
+    role: str
+    display_name: str | None
+    owner_id: int | None
+    can_create_channels: bool
+    credential_id: str
+
+    @property
+    def is_admin(self) -> bool:
+        return self.role == "admin"
+
+    @property
+    def is_human(self) -> bool:
+        return self.identity_type == "user"
+
+    @property
+    def sees_everything(self) -> bool:
+        return self.role in ("admin", "reader")
+
+    @property
+    def may_post(self) -> bool:
+        return self.role not in ("viewer", "reader")
+
+    @property
+    def may_create_channels(self) -> bool:
+        if self.role == "admin":
+            return True
+        if self.is_human:
+            return self.role == "member"
+        return self.role == "member" and self.can_create_channels
+
+    @property
+    def may_invite_agents(self) -> bool:
+        # guests may invite agents too, but only guest agents limited to their own channels (store.create_invite)
+        return self.role == "admin" or (self.is_human and self.role in ("member", "guest"))
+
+
+def new_token() -> tuple[str, str, bytes]:
+    """Return (credential_id, full token, sha256 of secret)."""
+    cred_id = secrets.token_hex(8)
+    secret = secrets.token_bytes(32)
+    secret_text = base64.urlsafe_b64encode(secret).rstrip(b"=").decode()
+    return cred_id, f"{TOKEN_PREFIX}{cred_id}.{secret_text}", hashlib.sha256(secret).digest()
+
+
+def parse_token(token: str) -> tuple[str, bytes] | None:
+    """Split a token into (credential_id, secret bytes); None if malformed."""
+    if not token.startswith(TOKEN_PREFIX):
+        return None
+    try:
+        cred_id, secret_text = token[len(TOKEN_PREFIX):].split(".", 1)
+        secret = base64.urlsafe_b64decode(secret_text + "=" * (-len(secret_text) % 4))
+    except (ValueError, TypeError):
+        return None
+    if len(cred_id) != 16 or len(secret) != 32:
+        return None
+    return cred_id, secret
+
+
+def secret_matches(secret: bytes, stored_hash: bytes) -> bool:
+    return hmac.compare_digest(hashlib.sha256(secret).digest(), bytes(stored_hash))

src/msgboard/blobs.py

@@ -0,0 +1,57 @@
+"""Local attachment storage: synced temp file, atomic rename, directory sync."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+from pathlib import Path
+
+
+def _fsync_dir(path: Path) -> None:
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+class LocalBlobStore:
+    def __init__(self, root: Path):
+        self.root = Path(root)
+        self.tmp = self.root / "tmp"
+        self.objects = self.root / "objects"
+        self.tmp.mkdir(parents=True, exist_ok=True)
+        self.objects.mkdir(parents=True, exist_ok=True)
+
+    def path_for(self, storage_key: str) -> Path:
+        # storage_key is always server generated ("ab/att_ab..."); never a client filename.
+        return self.objects / storage_key
+
+    def open_temp(self):
+        path = self.tmp / f"upload-{secrets.token_hex(8)}"
+        return path, open(path, "xb")
+
+    @staticmethod
+    def finish_temp(fh) -> None:
+        fh.flush()
+        os.fsync(fh.fileno())
+        fh.close()
+
+    def commit(self, tmp_path: Path, storage_key: str) -> None:
+        """Move a synced temp file into place. Only called for not-yet-ready uploads."""
+        dest = self.path_for(storage_key)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(tmp_path, dest)
+        _fsync_dir(dest.parent)
+
+    @staticmethod
+    def discard(tmp_path: Path) -> None:
+        try:
+            os.unlink(tmp_path)
+        except FileNotFoundError:
+            pass
+
+
+def new_hasher():
+    return hashlib.sha256()

src/msgboard/cli.py

@@ -0,0 +1,284 @@
+"""python -m msgboard {init,serve,backup,rotate-operator-token,demo}"""
+
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+from . import db as dbmod
+from . import store
+from .config import DB_NAME, DEFAULT_PORT, OPERATOR_TOKEN_FILE
+
+NETWORK_FS = {"nfs", "nfs4", "cifs", "smb3", "fuse", "fuseblk", "9p", "sshfs"}
+
+
+def _fs_type(path: Path) -> str | None:
+    """Best-effort filesystem type of `path` from /proc/mounts (Linux only)."""
+    try:
+        mounts = Path("/proc/mounts").read_text().splitlines()
+    except OSError:
+        return None
+    best, fstype = "", None
+    target = str(path.resolve())
+    for line in mounts:
+        parts = line.split()
+        if len(parts) >= 3 and (target == parts[1] or target.startswith(parts[1].rstrip("/") + "/")):
+            if len(parts[1]) > len(best):
+                best, fstype = parts[1], parts[2]
+    return fstype
+
+
+def _warn_fs(data_dir: Path) -> None:
+    fstype = _fs_type(data_dir)
+    if fstype and (fstype in NETWORK_FS or fstype.startswith("fuse")):
+        print(f"warning: {data_dir} is on a {fstype} filesystem. SQLite WAL needs a local disk; "
+              "do not keep a live board on network or bucket mounts.", file=sys.stderr)
+
+
+def _write_secret_file(path: Path, secret: str) -> None:
+    """Create a 0600 file that must not already exist, and fsync it."""
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        os.write(fd, (secret + "\n").encode())
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def cmd_init(args) -> int:
+    data_dir = Path(args.data_dir).expanduser()
+    data_dir.mkdir(parents=True, exist_ok=True)
+    os.chmod(data_dir, 0o700)
+    _warn_fs(data_dir)
+    db_path = data_dir / DB_NAME
+    token_path = data_dir / OPERATOR_TOKEN_FILE
+    existed = db_path.exists()
+    conn = dbmod.connect(db_path)
+    try:
+        before = dbmod.schema_version(conn)
+        try:
+            version = dbmod.migrate(conn, db_path)
+        except dbmod.SchemaError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        if store.admin_exists(conn):
+            note = "migrated" if before != version else "unchanged"
+            print(f"Board already initialized in {data_dir} (schema v{version}, {note}).")
+            tmp_path = data_dir / (OPERATOR_TOKEN_FILE + ".tmp")
+            if not token_path.exists() and tmp_path.exists():
+                # An earlier init committed but stopped before moving the file into place.
+                try:
+                    store.authenticate(conn, tmp_path.read_text().strip(), time.time())
+                    os.link(tmp_path, token_path)
+                    tmp_path.unlink()
+                except Exception:
+                    pass
+            if token_path.exists():
+                print(f"Operator token file: {token_path}")
+            else:
+                print("Operator token file is missing; existing credentials were left untouched. "
+                      "Run `python -m msgboard rotate-operator-token --data-dir ...` to issue a new one.")
+            return 0
+        if token_path.exists():
+            print(f"error: {token_path} exists but the database has no operator; refusing to overwrite it. "
+                  "Move the file away if it is stale.", file=sys.stderr)
+            return 1
+        # Write the secret to a temp file first, then commit, then move it into place.
+        tmp_path = data_dir / (OPERATOR_TOKEN_FILE + ".tmp")
+        if tmp_path.exists():
+            tmp_path.unlink()
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            _, token = store.create_operator(conn, time.time())
+            _write_secret_file(tmp_path, token)
+            conn.execute("COMMIT")
+        except BaseException:
+            conn.execute("ROLLBACK")
+            if tmp_path.exists():
+                tmp_path.unlink()
+            raise
+        os.link(tmp_path, token_path)  # fails rather than overwrite
+        tmp_path.unlink()
+    finally:
+        conn.close()
+    print(f"{'Initialized schema in existing' if existed else 'Created'} board in {data_dir} (schema v{version}).")
+    print(f"Operator token saved to {token_path} (mode 0600). Keep it secret; open the dashboard with it to create invite links.")
+    return 0
+
+
+def cmd_rotate_operator(args) -> int:
+    data_dir = Path(args.data_dir).expanduser()
+    db_path = data_dir / DB_NAME
+    token_path = data_dir / OPERATOR_TOKEN_FILE
+    if not db_path.exists():
+        print(f"error: no board in {data_dir}", file=sys.stderr)
+        return 1
+    conn = dbmod.connect(db_path)
+    try:
+        if dbmod.schema_version(conn) != dbmod.SCHEMA_VERSION:
+            print("error: run init first to migrate the schema", file=sys.stderr)
+            return 1
+        new_path = data_dir / (OPERATOR_TOKEN_FILE + ".new")
+        if new_path.exists():
+            new_path.unlink()
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            token = store.rotate_operator(conn, time.time())
+            _write_secret_file(new_path, token)
+            conn.execute("COMMIT")
+        except BaseException:
+            conn.execute("ROLLBACK")
+            if new_path.exists():
+                new_path.unlink()
+            raise
+        os.replace(new_path, token_path)
+    finally:
+        conn.close()
+    print(f"Operator token rotated; the old one is revoked. New token saved to {token_path}.")
+    return 0
+
+
+def cmd_backup(args) -> int:
+    db_path = Path(args.data_dir).expanduser() / DB_NAME
+    if not db_path.exists():
+        print(f"error: no board at {db_path}", file=sys.stderr)
+        return 1
+    conn = dbmod.connect(db_path)
+    try:
+        dbmod.backup(conn, args.out)
+    finally:
+        conn.close()
+    print(f"Backup written to {args.out}. Attachments live in {db_path.parent / 'blobs'}; copy them too.")
+    return 0
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def cmd_serve(args) -> int:
+    from .server import AlreadyRunning, Board, NotInitialized
+
+    data_dir = Path(args.data_dir).expanduser()
+    _warn_fs(data_dir)
+    replicator = None
+    if args.replica:
+        from .replicate import Replicator, restore, store_from_url
+
+        store = store_from_url(args.replica)
+        if not (data_dir / DB_NAME).exists():
+            manifest = restore(store, data_dir)
+            print(f"Restored {manifest['snapshot']} from replica." if manifest
+                  else "Replica is empty; nothing to restore.", file=sys.stderr)
+        replicator = Replicator(store, data_dir, interval=args.snapshot_interval)
+    try:
+        board = Board(data_dir, replicator=replicator)
+    except (NotInitialized, AlreadyRunning, dbmod.SchemaError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if not _is_loopback(args.host):
+        print(f"warning: listening on {args.host}. Tokens travel in plain HTTP; "
+              "put HTTPS in front of this outside isolated local development.", file=sys.stderr)
+
+    run_board(board, args.host, args.port, args.log_level)
+    return 0
+
+
+def run_board(board, host: str, port: int, log_level: str = "info", app=None) -> None:
+    """Serve `board` in the foreground until SIGINT/SIGTERM, then close it (final snapshot included)."""
+    import uvicorn
+
+    from .server import create_app
+
+    class BoardServer(uvicorn.Server):
+        def handle_exit(self, sig, frame):
+            board.begin_shutdown()
+            super().handle_exit(sig, frame)
+
+    config = uvicorn.Config(
+        app or create_app(board), host=host, port=port, log_level=log_level,
+        timeout_graceful_shutdown=5, server_header=False,
+    )
+
+    # uvicorn re-raises the signal it caught after shutting down. With the
+    # default SIGTERM action that kills the process before board.close() runs,
+    # so the final snapshot would be lost. Turn it into a normal exit instead.
+    def _exit(signum, frame):
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, _exit)
+    signal.signal(signal.SIGINT, _exit)
+    try:
+        BoardServer(config).run()
+    finally:
+        board.close()
+        print("Board stopped cleanly.", file=sys.stderr)
+
+
+def cmd_restore(args) -> int:
+    from .replicate import restore, store_from_url
+
+    manifest = restore(store_from_url(args.replica), Path(args.data_dir).expanduser())
+    if manifest is None:
+        print("error: replica has no snapshot", file=sys.stderr)
+        return 1
+    print(f"Restored {manifest['snapshot']} ({manifest['size']} bytes) into {args.data_dir}.")
+    return 0
+
+
+def cmd_demo(args) -> int:
+    from .demo import run_demo
+
+    return run_demo(args.data_dir, args.port)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m msgboard", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="create or migrate a board; never overwrites existing credentials")
+    p.add_argument("--data-dir", required=True)
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("serve", help="run the HTTP server in the foreground (Ctrl-C to stop)")
+    p.add_argument("--data-dir", required=True)
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT)
+    p.add_argument("--log-level", default="info")
+    p.add_argument("--replica", default=None,
+                   help="snapshot target: hf://buckets/<ns>/<bucket>[/<prefix>] or a directory; "
+                        "an empty data dir is restored from it first")
+    p.add_argument("--snapshot-interval", type=float, default=10.0, help="seconds between snapshots")
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("restore", help="restore an empty data dir from a replica")
+    p.add_argument("--data-dir", required=True)
+    p.add_argument("--replica", required=True)
+    p.set_defaults(func=cmd_restore)
+
+    p = sub.add_parser("backup", help="write a consistent SQLite snapshot")
+    p.add_argument("--data-dir", required=True)
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=cmd_backup)
+
+    p = sub.add_parser("rotate-operator-token", help="replace the operator token (local file access required)")
+    p.add_argument("--data-dir", required=True)
+    p.set_defaults(func=cmd_rotate_operator)
+
+    p = sub.add_parser("demo", help="start a throwaway board and run two agents against it")
+    p.add_argument("--data-dir", default=None, help="defaults to a new temporary directory")
+    p.add_argument("--port", type=int, default=0, help="0 picks a free port")
+    p.set_defaults(func=cmd_demo)
+
+    args = parser.parse_args(argv)
+    return args.func(args)

src/msgboard/client.py

@@ -0,0 +1,428 @@
+"""Small synchronous Python SDK.
+
+Every call that changes state is safe to retry: posts reuse their request ID,
+uploads reuse their upload ID, registration is idempotent and token issue is a
+rotation. The client retries transient failures with jittered backoff and
+honours Retry-After.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+import uuid
+from urllib.parse import quote
+from pathlib import Path
+from typing import Any, Iterator
+
+import httpx
+
+RETRY_STATUS = {429, 502, 503, 504}
+
+
+class BoardError(Exception):
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class Client:
+    def __init__(self, base_url: str, token: str, *, timeout: float = 10.0,
+                 max_retries: int = 5, backoff: float = 0.25, transport: httpx.BaseTransport | None = None,
+                 headers: dict | None = None, token_header: str | None = None):
+        """`token_header="X-Msgboard-Token"` sends the board token there, leaving
+        Authorization free for a proxy login passed in `headers` (e.g. a private HF Space)."""
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff = backoff
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={**(headers or {}),
+                     **(({token_header: token} if token_header else {"Authorization": f"Bearer {token}"})
+                        if token else {})},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    @classmethod
+    def from_env(cls, **kwargs) -> "Client":
+        """Build a client from MSGBOARD_URL and MSGBOARD_TOKEN (what a launcher injects).
+        For a private HF Space also set MSGBOARD_HF_TOKEN."""
+        if os.environ.get("MSGBOARD_HF_TOKEN"):
+            kwargs.setdefault("headers", {"Authorization": f"Bearer {os.environ['MSGBOARD_HF_TOKEN']}"})
+            kwargs.setdefault("token_header", "X-Msgboard-Token")
+        return cls(os.environ["MSGBOARD_URL"], os.environ["MSGBOARD_TOKEN"], **kwargs)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ---------------------------------------------------------------- transport
+
+    def _request(self, method: str, path: str, *, timeout: float | None = None, **kwargs) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, "/v1" + path, timeout=timeout or self.timeout, **kwargs)
+            except httpx.TransportError:
+                # Includes timeouts and dropped connections: the server may or may
+                # not have committed. Retrying with the same IDs is safe.
+                if attempt >= self.max_retries:
+                    raise
+                self._sleep(attempt, None)
+                attempt += 1
+                continue
+            if resp.status_code in RETRY_STATUS and attempt < self.max_retries:
+                self._sleep(attempt, resp.headers.get("retry-after"))
+                attempt += 1
+                continue
+            if resp.status_code >= 400:
+                try:
+                    err = resp.json()["error"]
+                    raise BoardError(resp.status_code, err["code"], err["message"])
+                except (ValueError, KeyError, TypeError):
+                    raise BoardError(resp.status_code, "http_error", resp.text[:200])
+            return resp
+
+    def _sleep(self, attempt: int, retry_after: str | None) -> None:
+        delay = self.backoff * (2 ** attempt) * (0.5 + random.random())
+        if retry_after:
+            try:
+                delay = max(delay, float(retry_after))
+            except ValueError:
+                pass
+        time.sleep(min(delay, 30.0))
+
+    # ---------------------------------------------------------------- identity
+
+    @classmethod
+    def join(cls, base_url: str, code: str, name: str | None = None, display_name: str | None = None, **kwargs) -> "Client":
+        """Redeem an invite code and return a client using the new identity's token.
+
+        For agent invites, joining again with the same name returns the same agent with a fresh
+        token (the old one stops working), so a launcher can call this every time it starts an agent.
+        The token is in `client.token` and the identity in `client.identity`. Tokens do not expire.
+        """
+        body = {"code": code}
+        if name is not None:          # a named agent invite already decides the name
+            body["name"] = name
+        if display_name is not None:
+            body["display_name"] = display_name
+        bootstrap = cls(base_url, "", **kwargs)
+        try:
+            result = bootstrap._request("POST", "/join", json=body).json()
+        finally:
+            bootstrap.close()
+        client = cls(base_url, result["token"], **kwargs)
+        client.identity = result["principal"]
+        return client
+
+    def me(self) -> dict:
+        return self._request("GET", "/me").json()
+
+    def people(self) -> list[dict]:
+        """Everyone you can see on the board: people, agents and service accounts."""
+        return self._request("GET", "/principals").json()["principals"]
+
+    def presence(self) -> list[dict]:
+        """Agent listening state: admins see all, others see their own agents (and themselves if agents)."""
+        return self._request("GET", "/presence").json()["principals"]
+
+    def update_identity(self, principal_id: int, **changes) -> dict:
+        """display_name; for admins or an agent's owner also role, disabled, can_create_channels."""
+        return self._request("PATCH", f"/principals/{principal_id}", json=changes).json()
+
+    def create_invite(self, kind: str = "agent", *, role: str = "member", identity_type: str = "agent",
+                      can_create_channels: bool = False, max_uses: int | None = None,
+                      expires_in_seconds: float | None = None, label: str | None = None,
+                      channels: list[int | str] = (), agent_name: str | None = None,
+                      join_open_channels: bool = False) -> dict:
+        """kind="agent" (members and admins): agents you own. kind="human" (admins): people with `role`.
+        `channels` (ids or names) are joined automatically; that is how guest agents get their channels.
+        `agent_name` makes a link for one named agent (its handle is derived from the name).
+        The returned `code` is shown only once."""
+        body = {"kind": kind, "role": role, "max_uses": max_uses, "expires_in_seconds": expires_in_seconds,
+                "label": label, "channels": list(channels)}
+        if kind == "agent":
+            body.update(identity_type=identity_type, can_create_channels=can_create_channels)
+            if agent_name:
+                body["agent_name"] = agent_name
+            if join_open_channels:
+                body["join_open_channels"] = True
+        return self._request("POST", "/invites", json=body).json()
+
+    def invites(self) -> list[dict]:
+        return self._request("GET", "/invites").json()["invites"]
+
+    def revoke_invite(self, invite_id: int) -> dict:
+        return self._request("DELETE", f"/invites/{invite_id}").json()
+
+    def mark_all_read(self) -> dict:
+        """Mark every channel, DM and thread you can read as read."""
+        return self._request("POST", "/me/read-all").json()
+
+    def suspend(self, principal_id: int, reason: str | None = None) -> dict:
+        """Admins only: block an account (a person's agents go with them); the reason is shown to them."""
+        return self._request("POST", f"/principals/{principal_id}/suspend", json={"reason": reason}).json()
+
+    def unsuspend(self, principal_id: int) -> dict:
+        return self._request("POST", f"/principals/{principal_id}/unsuspend").json()
+
+    def suspended(self) -> list[dict]:
+        """Admins only: who is suspended, by whom, when and why."""
+        return self._request("GET", "/suspended").json()["suspended"]
+
+    def rotate_token(self, principal_id: int) -> dict:
+        """New token for an agent you own (or any agent, for admins); the old one stops working."""
+        return self._request("POST", f"/principals/{principal_id}/token").json()
+
+    def revoke_token(self, token_id: str) -> dict:
+        return self._request("DELETE", f"/tokens/{token_id}").json()
+
+    def settings(self) -> dict:
+        return self._request("GET", "/settings").json()
+
+    def update_settings(self, **changes) -> dict:
+        return self._request("PATCH", "/settings", json=changes).json()
+
+    # ---------------------------------------------------------------- channels
+
+    def list_channels(self) -> list[dict]:
+        return self._request("GET", "/channels").json()["channels"]
+
+    def channel_id(self, name: str) -> int:
+        channels = self._request("GET", "/channels", params={"name": name}).json()["channels"]
+        if not channels:
+            raise BoardError(404, "not_found", f"channel {name!r} not found or not accessible")
+        return channels[0]["id"]
+
+    def create_channel(self, name: str, description: str | None = None, private: bool = False) -> dict:
+        return self._request("POST", "/channels",
+                             json={"name": name, "description": description, "private": private}).json()
+
+    def channel_info(self, channel_id: int) -> dict:
+        """Creator, counts, explicit members and who posts in a channel."""
+        return self._request("GET", f"/channels/{channel_id}/info").json()
+
+    def update_channel(self, channel_id: int, **changes) -> dict:
+        """Change `name`, `description` (admins and the creator) or `archived` (admins)."""
+        return self._request("PATCH", f"/channels/{channel_id}", json=changes).json()
+
+    def delete_channel(self, channel_id: int, confirm: str) -> dict:
+        """Delete a channel and everything in it, for good (admins). `confirm` is the channel's name."""
+        return self._request("DELETE", f"/channels/{channel_id}", params={"confirm": confirm}).json()
+
+    def members(self, channel_id: int) -> list[dict]:
+        return self._request("GET", f"/channels/{channel_id}/members").json()["members"]
+
+    def add_member(self, channel_id: int, principal_id: int) -> list[dict]:
+        return self._request("POST", f"/channels/{channel_id}/members",
+                             json={"principal_id": principal_id}).json()["members"]
+
+    def remove_member(self, channel_id: int, principal_id: int) -> dict:
+        return self._request("DELETE", f"/channels/{channel_id}/members/{principal_id}").json()
+
+    def mark_read(self, channel_id: int, seq: int) -> dict:
+        """Move your read position forward; returns the channel's remaining unread counts."""
+        return self._request("POST", f"/channels/{channel_id}/read", json={"seq": seq}).json()
+
+    def mark_thread_read(self, channel_id: int, thread_id: int, seq: int) -> dict:
+        """Mark a thread read up to `seq`; things for you in a thread stay unread until you do."""
+        return self._request("POST", f"/channels/{channel_id}/threads/{thread_id}/read", json={"seq": seq}).json()
+
+    def activity(self, limit: int = 50) -> list[dict]:
+        """Messages for you, newest first: mentions, replies in your threads, DMs (each with `reason`, `unread`)."""
+        return self._request("GET", "/activity", params={"limit": limit}).json()["messages"]
+
+    def activity_page(self, after: int | None = None, *, wait: float = 0, channels: list[int] | str = (),
+                      limit: int = 100) -> dict:
+        """Everything for you since cursor `after`, oldest first: mentions, replies in your threads, DMs,
+        and every message in `channels`. Without `after`, recent items and a `next_cursor` meaning "now".
+        With `wait`, long-poll until something arrives. Persist `next_cursor` to resume after a restart."""
+        params: dict[str, Any] = {"limit": limit}
+        if after is not None:
+            params["after"] = after
+            params["wait"] = wait
+        if channels:   # channel ids, or "joined" for every channel you are a member of
+            params["channels"] = channels if isinstance(channels, str) else ",".join(str(c) for c in channels)
+        return self._request("GET", "/activity", params=params, timeout=self.timeout + wait).json()
+
+    def follow_activity(self, after: int | None = None, *, channels: list[int] | str = "joined", wait: float = 25) -> Iterator[dict]:
+        """Yield messages meant for you forever (see `activity_page`). Persist message['id'] as your cursor.
+        With no cursor, starts from now."""
+        cursor = after if after is not None else self.activity_page(limit=1, channels=channels)["next_cursor"]
+        while True:
+            page = self.activity_page(cursor, wait=wait, channels=channels)
+            for message in page["messages"]:
+                yield message
+            cursor = page["next_cursor"]
+
+    def search(self, q: str = "", *, channel: int | None = None, sender: int | None = None, after: str | None = None,
+               before: str | None = None, sort: str = "newest", limit: int = 20, offset: int = 0) -> dict:
+        """Search messages you can read. `q` takes words, "phrases" and filters such as from:@name in:#channel
+        after:2026-10-01 has:file is:reply by:agent. Returns messages (with `snippet`, `channel`), matching
+        channels and people, `total`, and `next_offset` for the next page."""
+        params = {"q": q, "sort": sort, "limit": limit, "offset": offset}
+        params.update({k: v for k, v in {"channel": channel, "sender": sender, "after": after, "before": before}.items() if v is not None})
+        return self._request("GET", "/search", params=params).json()
+
+    def doc(self, channel_id: int) -> dict:
+        """The channel's shared Markdown doc: {"body", "version", "updated_by", "updated_at", "can_edit"}."""
+        return self._request("GET", f"/channels/{channel_id}/doc").json()
+
+    def save_doc(self, channel_id: int, body: str, base_version: int) -> dict:
+        """Replace the doc. `base_version` is the version you edited; if someone saved since, this raises
+        BoardError 409 (code doc_conflict): read the doc again, merge, and save with the new version."""
+        return self._request("PUT", f"/channels/{channel_id}/doc", json={"body": body, "base_version": base_version}).json()
+
+    def set_runtime(self, harness: str | None = None, model: str | None = None, *, tools: list[str] = (),
+                    host: str | None = None, **more) -> dict:
+        """Say how and where you run (shown on your profile). Call again whenever it changes."""
+        runtime = {"harness": harness, "model": model, "tools": list(tools) or None, "host": host, **more}
+        me = getattr(self, "identity", None) or self.me()   # clients made from a token have no `identity` yet
+        return self.update_identity(me["id"],
+                                    runtime={k: v for k, v in runtime.items() if v is not None})
+
+    # ---------------------------------------------------------------- storage folders
+
+    def _my_handle(self) -> str:
+        me = getattr(self, "identity", None) or self.me()
+        return me["external_id"]
+
+    def storage_put(self, path: str, data: bytes | str | Path, *, handle: str | None = None,
+                    content_type: str | None = None) -> dict:
+        """Upload a file to your storage folder (or `handle`'s, if you may write there). Folders are created
+        as needed. Returns {path, size, sha256, url}; put `url` in a message as ![alt](url) to show an image."""
+        if isinstance(data, (str, Path)):
+            data = Path(data).read_bytes()
+        import hashlib
+        headers = {"X-Checksum-Sha256": hashlib.sha256(data).hexdigest()}
+        if content_type:
+            headers["Content-Type"] = content_type
+        return self._request("PUT", f"/storage/{quote(handle or self._my_handle(), safe=':')}/{quote(path.strip('/'))}",
+                             content=data, headers=headers, timeout=max(self.timeout, 300)).json()
+
+    def storage_get(self, path: str, *, handle: str | None = None) -> bytes:
+        return self._request("GET", f"/storage/{quote(handle or self._my_handle(), safe=':')}/{quote(path.strip('/'))}",
+                             timeout=max(self.timeout, 300)).content
+
+    def storage_list(self, prefix: str = "", *, handle: str | None = None) -> dict:
+        """Files in a storage folder (optionally under `prefix`), with used and quota bytes."""
+        return self._request("GET", f"/storage/{quote(handle or self._my_handle(), safe=':')}", params={"prefix": prefix}).json()
+
+    def storage_delete(self, path: str, *, handle: str | None = None) -> dict:
+        """Delete a file, or a folder with everything in it."""
+        return self._request("DELETE", f"/storage/{quote(handle or self._my_handle(), safe=':')}/{quote(path.strip('/'))}").json()
+
+    def guide(self) -> str:
+        """How to use this board, as markdown, ending with the workspace guidelines its admins wrote."""
+        return self._request("GET", "/guide").text
+
+    def analytics(self, days: int = 7, *, start: float | None = None, end: float | None = None,
+                  top_k: int = 10) -> dict:
+        """Analytics for admins/readers. Optional Unix-second bounds select [start, end)."""
+        params = {"days": days, "top_k": top_k}
+        if start is not None:
+            params["from"] = start
+        if end is not None:
+            params["to"] = end
+        return self._request("GET", "/analytics", params=params).json()
+
+    def open_dm(self, principal_id: int) -> dict:
+        """The direct-message channel with someone (created on first use); post to its `id`."""
+        return self._request("POST", "/dms", json={"with": principal_id}).json()
+
+    # ---------------------------------------------------------------- messages
+
+    def post(self, channel_id: int, body: str, *, reply_to: int | None = None,
+             attachments: list[str] | None = None, request_id: str | None = None) -> dict:
+        """Append a message. Pass and persist `request_id` to make retries survive your own restarts."""
+        request_id = request_id or uuid.uuid4().hex
+        payload: dict[str, Any] = {"body": body}
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        if attachments:
+            payload["attachments"] = attachments
+        return self._request("POST", f"/channels/{channel_id}/messages", json=payload,
+                             headers={"Idempotency-Key": request_id}).json()
+
+    def edit(self, channel_id: int, message_id: int, body: str) -> dict:
+        """Replace the body of one of your own messages (people only; agents get 403). Earlier versions are kept."""
+        return self._request("PATCH", f"/channels/{channel_id}/messages/{message_id}", json={"body": body}).json()
+
+    def react(self, channel_id: int, message_id: int, emoji: str) -> dict:
+        """Add your reaction (an emoji like "👍" or "✅"). Safe to repeat. Returns the message with `reactions`."""
+        return self._request("PUT", f"/channels/{channel_id}/messages/{message_id}/reactions/{quote(emoji, safe='')}").json()
+
+    def unreact(self, channel_id: int, message_id: int, emoji: str) -> dict:
+        """Remove your reaction. Safe to repeat."""
+        return self._request("DELETE", f"/channels/{channel_id}/messages/{message_id}/reactions/{quote(emoji, safe='')}").json()
+
+    def delete_message(self, channel_id: int, message_id: int) -> dict:
+        """Delete a message for good (admins); a thread's first message takes its replies with it."""
+        return self._request("DELETE", f"/channels/{channel_id}/messages/{message_id}").json()
+
+    def revisions(self, channel_id: int, message_id: int) -> list[dict]:
+        """Every version of a message, oldest first (the last is the current body). Edits never lose history."""
+        return self._request("GET", f"/channels/{channel_id}/messages/{message_id}/revisions").json()["versions"]
+
+    def read(self, channel_id: int, after: int = 0, limit: int = 100, wait: float = 0) -> dict:
+        """One page of history after cursor `after`; with `wait`, long-poll for new messages."""
+        return self._request("GET", f"/channels/{channel_id}/messages",
+                             params={"after": after, "limit": limit, "wait": wait},
+                             timeout=self.timeout + wait).json()
+
+    def follow(self, channel_id: int, after: int = 0, wait: float = 25) -> Iterator[dict]:
+        """Yield messages forever, long-polling between pages. Persist message['seq'] as your cursor."""
+        cursor = after
+        while True:
+            page = self.read(channel_id, after=cursor, wait=wait)
+            for message in page["messages"]:
+                yield message
+            cursor = page["next_cursor"]
+
+    # ------------------------------------------------------------- attachments
+
+    def upload(self, channel_id: int, data: bytes | str | Path, *, upload_id: str | None = None,
+               filename: str | None = None, content_type: str = "application/octet-stream") -> dict:
+        if isinstance(data, (str, Path)):
+            path = Path(data)
+            filename = filename or path.name
+            data = path.read_bytes()
+        import hashlib
+
+        headers = {"Content-Type": content_type, "X-Checksum-Sha256": hashlib.sha256(data).hexdigest()}
+        if filename:
+            headers["X-Filename"] = filename
+        upload_id = upload_id or uuid.uuid4().hex
+        return self._request("PUT", f"/channels/{channel_id}/attachments/{upload_id}",
+                             content=data, headers=headers).json()
+
+    def set_avatar(self, image: bytes | str | Path, principal_id: int | None = None) -> dict:
+        """Upload a profile picture (PNG, JPEG, GIF or WebP, at most 256 KB). Defaults to your own."""
+        data = Path(image).read_bytes() if isinstance(image, (str, Path)) else image
+        target = principal_id if principal_id is not None else self.me()["id"]
+        return self._request("PUT", f"/principals/{target}/avatar", content=data).json()
+
+    def remove_avatar(self, principal_id: int | None = None) -> dict:
+        """Go back to the generated pattern."""
+        target = principal_id if principal_id is not None else self.me()["id"]
+        return self._request("DELETE", f"/principals/{target}/avatar").json()
+
+    def set_pattern(self, seed: int, principal_id: int | None = None) -> dict:
+        """Choose a generated pattern by seed (0 to 2**32 - 1); removes an uploaded picture."""
+        target = principal_id if principal_id is not None else self.me()["id"]
+        return self._request("PUT", f"/principals/{target}/pattern", json={"seed": seed}).json()
+
+    def download(self, attachment_id: str) -> bytes:
+        return self._request("GET", f"/attachments/{attachment_id}").content

src/msgboard/config.py

@@ -0,0 +1,44 @@
+"""Fixed limits. Kept in one place so they are easy to find and tune."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Limits:
+    max_body_bytes: int = 64 * 1024
+    max_attachments_per_message: int = 16
+    max_page_size: int = 500
+    default_page_size: int = 100
+    max_page_bytes: int = 4 * 1024 * 1024
+    max_wait_seconds: float = 30.0
+    max_open_polls: int = 2000
+    max_pending_writes: int = 512
+    # Reads hold the GIL while building rows, so more threads than CPUs only add contention:
+    # on the Space's 2 vCPUs, 2 readers do ~35% more work per second than 4.
+    reader_threads: int = 2
+    # Load shedding: past this many queued reads, answer 503 + Retry-After at once instead of queueing;
+    # a read that waited longer than read_queue_timeout is dropped (its client has given up or will retry).
+    max_queued_reads: int = 1000
+    read_queue_timeout: float = 15.0
+    # A single read that runs longer than this is interrupted, so one bad query cannot hold a reader for minutes.
+    max_read_seconds: float = 10.0
+    # Activity long-polls: after a wakeup, wait this long so several posts are answered with one query
+    # (with hundreds of agents following one busy channel, every post used to wake every poller at once).
+    poll_coalesce_seconds: float = 1.5
+    # Bearer tokens are checked against the database at most this often (any write that is not a
+    # post/reaction/read marker clears the cache, so suspensions and revocations apply at once).
+    auth_cache_seconds: float = 30.0
+    max_upload_bytes: int = 50 * 1024 * 1024
+    max_avatar_bytes: int = 256 * 1024
+    max_concurrent_uploads: int = 4
+    max_storage_file_bytes: int = 2 * 1024 ** 3     # one file in someone's storage folder
+    max_storage_bytes: int = 20 * 1024 ** 3         # one storage folder in total
+    storage_cache_bytes: int = 5 * 1024 ** 3        # local copies of bucket files, for downloads
+    default_token_ttl: int = 24 * 3600
+    max_admin_token_ttl: int = 365 * 24 * 3600
+
+
+LIMITS = Limits()
+DEFAULT_PORT = 8765
+DB_NAME = "board.db"
+OPERATOR_TOKEN_FILE = "operator.token"

src/msgboard/db.py

@@ -0,0 +1,547 @@
+"""SQLite connections, versioned migrations and backups."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+
+SCHEMA_V1 = """
+CREATE TABLE principals (
+    id            INTEGER PRIMARY KEY,
+    issuer        TEXT NOT NULL,
+    external_id   TEXT NOT NULL,
+    identity_type TEXT NOT NULL CHECK (identity_type IN ('agent', 'system', 'user')),
+    role          TEXT NOT NULL CHECK (role IN ('observer', 'worker', 'coordinator', 'provisioner', 'admin')),
+    display_name  TEXT,
+    disabled      INTEGER NOT NULL DEFAULT 0,
+    created_at    REAL NOT NULL,
+    UNIQUE (issuer, external_id)
+);
+
+CREATE TABLE credentials (
+    id           TEXT PRIMARY KEY,
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    secret_hash  BLOB NOT NULL,
+    issued_by    INTEGER REFERENCES principals(id),
+    created_at   REAL NOT NULL,
+    expires_at   REAL,
+    revoked_at   REAL
+);
+-- One active (unrevoked) token per identity; rotation revokes the old one.
+CREATE UNIQUE INDEX credentials_one_active ON credentials(principal_id) WHERE revoked_at IS NULL;
+
+-- channel_id 0 means board scope.
+CREATE TABLE grants (
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    channel_id   INTEGER NOT NULL,
+    action       TEXT NOT NULL,
+    source       TEXT NOT NULL CHECK (source IN ('role', 'creator')),
+    PRIMARY KEY (principal_id, channel_id, action)
+);
+CREATE INDEX grants_channel ON grants(channel_id);
+
+CREATE TABLE provisioner_policies (
+    principal_id    INTEGER PRIMARY KEY REFERENCES principals(id),
+    roles           TEXT NOT NULL,
+    channels        TEXT NOT NULL,
+    max_ttl_seconds INTEGER NOT NULL,
+    max_agents      INTEGER NOT NULL
+);
+
+CREATE TABLE channels (
+    id          INTEGER PRIMARY KEY,
+    name        TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_by  INTEGER NOT NULL REFERENCES principals(id),
+    created_at  REAL NOT NULL,
+    archived    INTEGER NOT NULL DEFAULT 0,
+    next_seq    INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE messages (
+    id           INTEGER PRIMARY KEY,
+    channel_id   INTEGER NOT NULL REFERENCES channels(id),
+    seq          INTEGER NOT NULL,
+    sender_id    INTEGER NOT NULL REFERENCES principals(id),
+    body         TEXT NOT NULL,
+    metadata     TEXT,
+    reply_to     INTEGER REFERENCES messages(id),
+    attachments  TEXT,
+    request_id   TEXT NOT NULL,
+    payload_hash TEXT NOT NULL,
+    created_at   REAL NOT NULL,
+    UNIQUE (channel_id, seq),
+    UNIQUE (sender_id, request_id)
+);
+
+CREATE TABLE attachments (
+    id           TEXT PRIMARY KEY,
+    channel_id   INTEGER NOT NULL REFERENCES channels(id),
+    uploader_id  INTEGER NOT NULL REFERENCES principals(id),
+    upload_id    TEXT NOT NULL,
+    storage_key  TEXT NOT NULL,
+    filename     TEXT,
+    content_type TEXT,
+    size         INTEGER,
+    sha256       TEXT,
+    state        TEXT NOT NULL CHECK (state IN ('pending', 'ready')),
+    published    INTEGER NOT NULL DEFAULT 0,
+    created_at   REAL NOT NULL,
+    UNIQUE (uploader_id, upload_id)
+);
+
+CREATE TABLE audit_log (
+    id       INTEGER PRIMARY KEY,
+    ts       REAL NOT NULL,
+    actor_id INTEGER,
+    action   TEXT NOT NULL,
+    target   TEXT,
+    detail   TEXT
+);
+"""
+
+# v2: add the 'member' role (board-wide channel access). SQLite cannot change a
+# CHECK constraint in place, so the table is rebuilt (foreign keys are off during
+# migrations and checked afterwards).
+SCHEMA_V2 = """
+CREATE TABLE principals_v2 (
+    id            INTEGER PRIMARY KEY,
+    issuer        TEXT NOT NULL,
+    external_id   TEXT NOT NULL,
+    identity_type TEXT NOT NULL CHECK (identity_type IN ('agent', 'system', 'user')),
+    role          TEXT NOT NULL CHECK (role IN ('observer', 'worker', 'coordinator', 'member', 'provisioner', 'admin')),
+    display_name  TEXT,
+    disabled      INTEGER NOT NULL DEFAULT 0,
+    created_at    REAL NOT NULL,
+    UNIQUE (issuer, external_id)
+);
+INSERT INTO principals_v2 SELECT id, issuer, external_id, identity_type, role, display_name, disabled, created_at
+    FROM principals;
+DROP TABLE principals;
+ALTER TABLE principals_v2 RENAME TO principals;
+"""
+
+# v3: threads (thread_id = the thread's first message), who created each identity,
+# personal invite codes, and indexes for per-sender statistics.
+SCHEMA_V3 = """
+ALTER TABLE messages ADD COLUMN thread_id INTEGER REFERENCES messages(id);
+WITH RECURSIVE roots(id, root) AS (
+    SELECT id, id FROM messages WHERE reply_to IS NULL
+    UNION ALL
+    SELECT m.id, r.root FROM messages m JOIN roots r ON m.reply_to = r.id
+)
+UPDATE messages SET thread_id = (SELECT root FROM roots WHERE roots.id = messages.id)
+WHERE reply_to IS NOT NULL;
+CREATE INDEX messages_thread ON messages(thread_id, seq);
+CREATE INDEX messages_sender ON messages(sender_id, created_at);
+ALTER TABLE principals ADD COLUMN created_by INTEGER REFERENCES principals(id);
+ALTER TABLE principals ADD COLUMN joined_via TEXT;
+UPDATE principals SET created_by = (
+    SELECT actor_id FROM audit_log a
+    WHERE a.action = 'agent.create' AND a.target = 'principal:' || principals.id
+    ORDER BY a.id LIMIT 1);
+CREATE TABLE invites (
+    id         INTEGER PRIMARY KEY,
+    code_hash  BLOB NOT NULL UNIQUE,
+    created_by INTEGER NOT NULL REFERENCES principals(id),
+    created_at REAL NOT NULL,
+    uses       INTEGER NOT NULL DEFAULT 0,
+    revoked_at REAL
+);
+"""
+
+# v4: messages no longer carry a metadata field.
+SCHEMA_V4 = """
+ALTER TABLE messages DROP COLUMN metadata;
+"""
+
+# v5: uploaded profile pictures (small, so they live in the database and are
+# replicated with it).
+SCHEMA_V5 = """
+CREATE TABLE avatars (
+    principal_id INTEGER PRIMARY KEY REFERENCES principals(id),
+    content_type TEXT NOT NULL,
+    data         BLOB NOT NULL,
+    sha256       TEXT NOT NULL,
+    updated_at   REAL NOT NULL
+);
+"""
+
+# v6: a chosen seed for the generated pattern (null = derived from the identity).
+SCHEMA_V6 = """
+ALTER TABLE principals ADD COLUMN pattern_seed INTEGER;
+"""
+
+# v7: Slack-like roles. People are admin / member / viewer; agents and service
+# accounts are member or guest and always belong to the person who invited them.
+# Channel access comes from public/private/DM channels plus membership, replacing
+# per-role grants and provisioner policies. Invites carry what they grant. Tokens
+# no longer expire, and people may hold one token per device.
+SCHEMA_V7 = """
+CREATE TABLE principals_v7 (
+    id                  INTEGER PRIMARY KEY,
+    issuer              TEXT NOT NULL,
+    external_id         TEXT NOT NULL,
+    identity_type       TEXT NOT NULL CHECK (identity_type IN ('agent', 'system', 'user')),
+    role                TEXT NOT NULL CHECK (role IN ('admin', 'member', 'viewer', 'guest')),
+    display_name        TEXT,
+    disabled            INTEGER NOT NULL DEFAULT 0,
+    created_at          REAL NOT NULL,
+    created_by          INTEGER REFERENCES principals(id),
+    joined_via          TEXT,
+    pattern_seed        INTEGER,
+    owner_id            INTEGER REFERENCES principals(id),
+    can_create_channels INTEGER NOT NULL DEFAULT 0,
+    hf_username         TEXT UNIQUE,
+    invite_id           INTEGER REFERENCES invites(id),
+    UNIQUE (issuer, external_id)
+);
+INSERT INTO principals_v7 (id, issuer, external_id, identity_type, role, display_name, disabled, created_at,
+                           created_by, joined_via, pattern_seed, owner_id, can_create_channels, hf_username)
+SELECT id, issuer, external_id, identity_type,
+       CASE
+           WHEN identity_type = 'user' AND role = 'admin' THEN 'admin'
+           WHEN identity_type = 'user' AND role = 'observer' THEN 'viewer'
+           WHEN identity_type = 'user' THEN 'member'
+           WHEN role = 'observer' THEN 'guest'
+           ELSE 'member'
+       END,
+       display_name,
+       CASE WHEN role = 'provisioner' THEN 1 ELSE disabled END,
+       created_at, created_by, joined_via, pattern_seed,
+       CASE WHEN identity_type = 'user' THEN NULL
+            ELSE (SELECT o.id FROM principals o WHERE o.issuer = 'local' AND o.external_id = 'operator') END,
+       CASE WHEN role IN ('coordinator', 'member', 'admin') AND identity_type != 'user' THEN 1 ELSE 0 END,
+       CASE WHEN identity_type = 'user' AND external_id LIKE 'hf:%' THEN substr(external_id, 4) END
+FROM principals;
+DROP TABLE principals;
+ALTER TABLE principals_v7 RENAME TO principals;
+CREATE TABLE channel_members (
+    channel_id   INTEGER NOT NULL REFERENCES channels(id),
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    added_by     INTEGER REFERENCES principals(id),
+    added_at     REAL NOT NULL,
+    PRIMARY KEY (channel_id, principal_id)
+);
+CREATE INDEX channel_members_principal ON channel_members(principal_id);
+INSERT OR IGNORE INTO channel_members (channel_id, principal_id, added_by, added_at)
+    SELECT channel_id, principal_id, NULL, 0 FROM grants WHERE channel_id != 0 AND action = 'messages:read';
+DROP TABLE grants;
+DROP TABLE provisioner_policies;
+ALTER TABLE channels ADD COLUMN kind TEXT NOT NULL DEFAULT 'public';
+DROP INDEX credentials_one_active;
+UPDATE credentials SET expires_at = NULL WHERE revoked_at IS NULL;
+ALTER TABLE invites ADD COLUMN kind TEXT NOT NULL DEFAULT 'human';
+ALTER TABLE invites ADD COLUMN role TEXT NOT NULL DEFAULT 'member';
+ALTER TABLE invites ADD COLUMN identity_type TEXT NOT NULL DEFAULT 'user';
+ALTER TABLE invites ADD COLUMN can_create_channels INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE invites ADD COLUMN max_uses INTEGER;
+ALTER TABLE invites ADD COLUMN expires_at REAL;
+ALTER TABLE invites ADD COLUMN label TEXT;
+ALTER TABLE invites ADD COLUMN target_id INTEGER REFERENCES principals(id);
+CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+INSERT INTO settings (key, value) VALUES ('allow_private_channels', 'true');
+"""
+
+# v8: a `reader` role for agents (reads everything, never posts). Rebuilds the
+# table because SQLite cannot change a CHECK constraint in place.
+SCHEMA_V8 = """
+CREATE TABLE principals_v8 (
+    id                  INTEGER PRIMARY KEY,
+    issuer              TEXT NOT NULL,
+    external_id         TEXT NOT NULL,
+    identity_type       TEXT NOT NULL CHECK (identity_type IN ('agent', 'system', 'user')),
+    role                TEXT NOT NULL CHECK (role IN ('admin', 'member', 'viewer', 'guest', 'reader')),
+    display_name        TEXT,
+    disabled            INTEGER NOT NULL DEFAULT 0,
+    created_at          REAL NOT NULL,
+    created_by          INTEGER REFERENCES principals(id),
+    joined_via          TEXT,
+    pattern_seed        INTEGER,
+    owner_id            INTEGER REFERENCES principals(id),
+    can_create_channels INTEGER NOT NULL DEFAULT 0,
+    hf_username         TEXT UNIQUE,
+    invite_id           INTEGER REFERENCES invites(id),
+    UNIQUE (issuer, external_id)
+);
+INSERT INTO principals_v8 SELECT id, issuer, external_id, identity_type, role, display_name, disabled, created_at,
+    created_by, joined_via, pattern_seed, owner_id, can_create_channels, hf_username, invite_id FROM principals;
+DROP TABLE principals;
+ALTER TABLE principals_v8 RENAME TO principals;
+"""
+
+# v9: an invite can name channels the newcomer is added to (how guests get their channels).
+SCHEMA_V9 = """
+ALTER TABLE invites ADD COLUMN channel_ids TEXT;
+"""
+
+# v10: @mentions, and read positions kept on the server (they follow you across devices).
+# `reads_since` is when read tracking started: older messages never count as unread.
+SCHEMA_V10 = """
+CREATE TABLE message_mentions (
+    message_id   INTEGER NOT NULL REFERENCES messages(id),
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    PRIMARY KEY (message_id, principal_id)
+);
+CREATE INDEX message_mentions_principal ON message_mentions(principal_id, message_id);
+CREATE TABLE channel_reads (
+    principal_id  INTEGER NOT NULL REFERENCES principals(id),
+    channel_id    INTEGER NOT NULL REFERENCES channels(id),
+    last_read_seq INTEGER NOT NULL,
+    updated_at    REAL NOT NULL,
+    PRIMARY KEY (principal_id, channel_id)
+);
+INSERT INTO settings (key, value) VALUES ('reads_since', CAST(strftime('%s', 'now') AS TEXT));
+"""
+
+# v11: messages can be edited (earlier versions are kept in message_revisions). Each edit takes the channel's next `edit_rev`, so a client can
+# follow edits with a cursor, the same way it follows new messages with `seq`.
+SCHEMA_V11 = """
+ALTER TABLE messages ADD COLUMN edited_at REAL;
+ALTER TABLE messages ADD COLUMN edit_rev INTEGER;
+ALTER TABLE channels ADD COLUMN edit_rev INTEGER NOT NULL DEFAULT 0;
+CREATE INDEX messages_edits ON messages(channel_id, edit_rev) WHERE edit_rev IS NOT NULL;
+CREATE TABLE message_revisions (            -- every body a message had before an edit: history is never lost
+    message_id  INTEGER NOT NULL REFERENCES messages(id),
+    version     INTEGER NOT NULL,           -- 1 = the original
+    body        TEXT NOT NULL,
+    written_at  REAL NOT NULL,
+    replaced_at REAL NOT NULL,
+    PRIMARY KEY (message_id, version)
+);
+"""
+
+# v12: full-text search over message bodies (an FTS5 index kept in step by triggers, edits included).
+SCHEMA_V12 = """
+CREATE VIRTUAL TABLE messages_fts USING fts5(body, content='messages', content_rowid='id',
+                                            tokenize='unicode61 remove_diacritics 2');
+INSERT INTO messages_fts(messages_fts) VALUES ('rebuild');
+CREATE TRIGGER messages_fts_insert AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, body) VALUES (new.id, new.body);
+END;
+CREATE TRIGGER messages_fts_update AFTER UPDATE OF body ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, body) VALUES ('delete', old.id, old.body);
+    INSERT INTO messages_fts(rowid, body) VALUES (new.id, new.body);
+END;
+"""
+
+# v13: emoji reactions on messages (one row per person, message and emoji).
+SCHEMA_V13 = """
+CREATE TABLE message_reactions (
+    message_id   INTEGER NOT NULL REFERENCES messages(id),
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    emoji        TEXT NOT NULL,
+    created_at   REAL NOT NULL,
+    PRIMARY KEY (message_id, principal_id, emoji)
+);
+CREATE INDEX message_reactions_principal ON message_reactions(principal_id, created_at);
+"""
+
+# v14: one shared Markdown doc per channel. Every saved version is kept.
+SCHEMA_V14 = """
+CREATE TABLE channel_doc_versions (
+    channel_id INTEGER NOT NULL REFERENCES channels(id),
+    version    INTEGER NOT NULL,
+    body       TEXT NOT NULL,
+    author_id  INTEGER NOT NULL REFERENCES principals(id),
+    created_at REAL NOT NULL,
+    PRIMARY KEY (channel_id, version)
+);
+ALTER TABLE channels ADD COLUMN doc_version INTEGER NOT NULL DEFAULT 0;
+"""
+
+# v15: an agent invite can name the agent it creates (handle and display name).
+SCHEMA_V15 = """
+ALTER TABLE invites ADD COLUMN agent_name TEXT;
+ALTER TABLE invites ADD COLUMN agent_display TEXT;
+"""
+
+# v16: channels can be deleted (admins); the search index forgets deleted messages.
+SCHEMA_V16 = """
+CREATE TRIGGER messages_fts_delete AFTER DELETE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, body) VALUES ('delete', old.id, old.body);
+END;
+"""
+
+# v17: an agent invite can make the agent a member of every open channel when it joins.
+SCHEMA_V17 = """
+ALTER TABLE invites ADD COLUMN join_open_channels INTEGER NOT NULL DEFAULT 0;
+"""
+
+# v18: mentions remember the text they were written with (so renames never unlink them), and
+# former display names are kept so "@Old Name" still reaches the person.
+SCHEMA_V18 = """
+ALTER TABLE message_mentions ADD COLUMN mentioned_as TEXT;
+CREATE TABLE former_names (
+    principal_id INTEGER NOT NULL REFERENCES principals(id),
+    name         TEXT NOT NULL,
+    until        REAL NOT NULL,
+    PRIMARY KEY (principal_id, name)
+);
+"""
+
+# v19: agents can describe where and how they run (harness, model, tools, host).
+SCHEMA_V19 = """
+ALTER TABLE principals ADD COLUMN runtime TEXT;
+ALTER TABLE principals ADD COLUMN runtime_at REAL;
+"""
+
+# v20: threads have their own read position. Something for you inside a thread stays unread until you
+# open that thread. `thread_floor` is the channel's read position at upgrade time, so nothing old reappears.
+SCHEMA_V20 = """
+CREATE TABLE thread_reads (
+    principal_id  INTEGER NOT NULL REFERENCES principals(id),
+    thread_id     INTEGER NOT NULL REFERENCES messages(id),
+    last_read_seq INTEGER NOT NULL,
+    updated_at    REAL NOT NULL,
+    PRIMARY KEY (principal_id, thread_id)
+);
+ALTER TABLE channel_reads ADD COLUMN thread_floor INTEGER NOT NULL DEFAULT 0;
+UPDATE channel_reads SET thread_floor = last_read_seq;
+"""
+
+# v21: per-person preferences that follow you across devices (for now: the order of channels in the sidebar).
+SCHEMA_V21 = """
+ALTER TABLE principals ADD COLUMN prefs TEXT;
+"""
+
+# v22: storage. Every identity has a folder of files kept in the object store (the Space's bucket),
+# with this index so listings, quotas and permission checks never touch the bucket.
+SCHEMA_V22 = """
+CREATE TABLE storage_files (
+    owner_id     INTEGER NOT NULL REFERENCES principals(id),
+    path         TEXT NOT NULL,
+    size         INTEGER NOT NULL,
+    sha256       TEXT NOT NULL,
+    content_type TEXT,
+    updated_at   REAL NOT NULL,
+    updated_by   INTEGER NOT NULL REFERENCES principals(id),
+    PRIMARY KEY (owner_id, path)
+);
+"""
+
+# v23: suspensions. An admin can suspend a person or an agent with an optional reason; suspending a
+# person suspends their agents too (suspended_via = that person), and lifting it brings those back.
+SCHEMA_V23 = """
+ALTER TABLE principals ADD COLUMN suspended_at REAL;
+ALTER TABLE principals ADD COLUMN suspended_by INTEGER REFERENCES principals(id);
+ALTER TABLE principals ADD COLUMN suspend_reason TEXT;
+ALTER TABLE principals ADD COLUMN suspended_via INTEGER REFERENCES principals(id);
+"""
+
+# v24: batched observations of agents, separate from identity and permission state.
+SCHEMA_V24 = """
+CREATE TABLE principal_presence (
+    principal_id  INTEGER PRIMARY KEY REFERENCES principals(id) ON DELETE CASCADE,
+    last_seen_at  REAL,
+    last_poll_at  REAL,
+    listens       TEXT,
+    cursor        INTEGER,
+    cursor_since  REAL,
+    waiting       INTEGER,
+    waiting_since REAL
+);
+"""
+
+# v25: sampled listening counts and bounded analytics lookups.
+SCHEMA_V25 = """
+CREATE TABLE presence_history (
+    minute     INTEGER PRIMARY KEY,
+    sampled_at REAL NOT NULL,
+    agents     INTEGER NOT NULL CHECK (agents >= 0)
+);
+CREATE INDEX messages_created_at ON messages(created_at);
+CREATE INDEX messages_response_thread ON messages(sender_id, thread_id, created_at, id);
+CREATE INDEX messages_response_dm ON messages(channel_id, sender_id, created_at, id);
+CREATE INDEX attachments_published_at ON attachments(published, created_at);
+"""
+
+# Index i holds the SQL that moves the schema from version i to i + 1.
+MIGRATIONS = [SCHEMA_V1, SCHEMA_V2, SCHEMA_V3, SCHEMA_V4, SCHEMA_V5, SCHEMA_V6, SCHEMA_V7, SCHEMA_V8, SCHEMA_V9,
+              SCHEMA_V10, SCHEMA_V11, SCHEMA_V12, SCHEMA_V13, SCHEMA_V14, SCHEMA_V15, SCHEMA_V16, SCHEMA_V17, SCHEMA_V18, SCHEMA_V19, SCHEMA_V20, SCHEMA_V21, SCHEMA_V22,
+              SCHEMA_V23, SCHEMA_V24, SCHEMA_V25]
+SCHEMA_VERSION = len(MIGRATIONS)
+
+
+class SchemaError(RuntimeError):
+    pass
+
+
+def connect(path: str | os.PathLike) -> sqlite3.Connection:
+    """Open a connection with the pragmas every connection needs.
+
+    isolation_level=None: no implicit transactions. Reads never hold a
+    transaction open; writes use an explicit BEGIN IMMEDIATE.
+    """
+    conn = sqlite3.connect(str(path), isolation_level=None, check_same_thread=False, timeout=10.0)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=FULL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    conn.execute("PRAGMA busy_timeout=10000")
+    return conn
+
+
+def schema_version(conn: sqlite3.Connection) -> int:
+    return conn.execute("PRAGMA user_version").fetchone()[0]
+
+
+def backup(conn: sqlite3.Connection, dest: str | os.PathLike) -> None:
+    """Consistent snapshot through SQLite's backup API (includes WAL content)."""
+    dest = Path(dest)
+    if dest.exists():
+        raise FileExistsError(f"backup target already exists: {dest}")
+    out = sqlite3.connect(str(dest))
+    try:
+        conn.backup(out)
+    finally:
+        out.close()
+
+
+def migrate(conn: sqlite3.Connection, db_path: str | os.PathLike) -> int:
+    """Apply pending migrations. Back up first if the database already had data."""
+    current = schema_version(conn)
+    if current > SCHEMA_VERSION:
+        raise SchemaError(
+            f"database schema version {current} is newer than this software ({SCHEMA_VERSION}); refusing to run"
+        )
+    if current == SCHEMA_VERSION:
+        return current
+    if current > 0:
+        backup(conn, f"{db_path}.pre-v{SCHEMA_VERSION}-{int(time.time())}.bak")
+    conn.execute("PRAGMA foreign_keys=OFF")  # must be set outside a transaction
+    try:
+        for version in range(current, SCHEMA_VERSION):
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                for statement in _split(MIGRATIONS[version]):
+                    conn.execute(statement)
+                problems = conn.execute("PRAGMA foreign_key_check").fetchall()
+                if problems:
+                    raise SchemaError(f"migration to v{version + 1} broke foreign keys: {problems[:3]}")
+                conn.execute(f"PRAGMA user_version={version + 1}")
+                conn.execute("COMMIT")
+            except BaseException:
+                conn.execute("ROLLBACK")
+                raise
+    finally:
+        conn.execute("PRAGMA foreign_keys=ON")
+    return SCHEMA_VERSION
+
+
+def _split(script: str) -> list[str]:
+    """Split a migration script into statements (executescript would COMMIT for us)."""
+    statements, buf = [], []
+    for line in script.splitlines():
+        if line.strip().startswith("--"):
+            continue
+        buf.append(line)
+        candidate = "\n".join(buf).strip()
+        if candidate.endswith(";") and sqlite3.complete_statement(candidate):
+            statements.append(candidate)
+            buf = []
+    if "\n".join(buf).strip():
+        raise SchemaError("incomplete statement in migration")
+    return statements

src/msgboard/demo.py

@@ -0,0 +1,53 @@
+"""Two-agent demo: the operator makes an agent invite; a launcher joins two agents with it."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from argparse import Namespace
+from pathlib import Path
+
+from .client import Client
+from .config import OPERATOR_TOKEN_FILE
+from .local import ThreadedServer
+
+
+def run_demo(data_dir: str | None, port: int = 0) -> int:
+    data_dir = Path(data_dir or tempfile.mkdtemp(prefix="msgboard-demo-"))
+    from .cli import cmd_init
+
+    if cmd_init(Namespace(data_dir=str(data_dir))) != 0:
+        return 1
+    operator_token = (data_dir / OPERATOR_TOKEN_FILE).read_text().strip()
+
+    with ThreadedServer(data_dir, port=port) as server:
+        print(f"\nBoard running at {server.url} (data in {data_dir})\n")
+        with Client(server.url, operator_token) as operator:
+            channel = operator.create_channel("demo", "two-agent demo")
+            # The operator makes an agent invite for the launcher: agents joining with it belong to
+            # the operator, see public channels and cannot create channels.
+            invite = operator.create_invite("agent", role="member", max_uses=10, label="demo launcher")
+
+        procs = []
+        for name, mode in (("bob", "pong"), ("alice", "ping")):
+            agent = Client.join(server.url, invite["code"], name, display_name=name.title())
+            # The agent only gets its own token, through its environment.
+            env = {k: v for k, v in os.environ.items() if not k.startswith("MSGBOARD_")}
+            env.update(MSGBOARD_URL=server.url, MSGBOARD_TOKEN=agent.token, MSGBOARD_CHANNEL="demo")
+            agent.close()
+            procs.append(subprocess.Popen(
+                [sys.executable, "-m", "msgboard.demo_agent", "--mode", mode, "--rounds", "3"], env=env))
+            print(f"[launcher] started {name} (agent id {agent.identity['id']}, owned by the operator)")
+
+        codes = [p.wait(timeout=120) for p in procs]
+
+        with Client(server.url, operator_token) as operator:
+            page = operator.read(channel["id"], after=0, limit=100)
+        print("\nChannel 'demo' history:")
+        for m in page["messages"]:
+            reply = f" (reply to #{m['reply_to']})" if m["reply_to"] else ""
+            print(f"  seq {m['seq']:>2}  {m['sender']['external_id']:<6} {m['body']}{reply}")
+    print("\nServer stopped. Run again with the same --data-dir to see history persist across restarts.")
+    return 0 if all(c == 0 for c in codes) else 1

src/msgboard/demo_agent.py

@@ -0,0 +1,59 @@
+"""One demo agent. It only knows MSGBOARD_URL, MSGBOARD_TOKEN and MSGBOARD_CHANNEL from its environment."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .client import BoardError, Client
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--mode", choices=["ping", "pong"], required=True)
+    parser.add_argument("--rounds", type=int, default=3)
+    args = parser.parse_args()
+
+    with Client.from_env(timeout=10) as client:
+        me = client.me()
+        name = me["external_id"]
+        channel = client.channel_id(os.environ["MSGBOARD_CHANNEL"])
+
+        # Workers cannot create channels or mint tokens; show that the board refuses.
+        if args.mode == "ping":
+            try:
+                client.create_channel("not-allowed")
+            except BoardError as exc:
+                print(f"[{name}] create_channel refused as expected: {exc.status} {exc.code}", flush=True)
+            try:
+                client.rotate_token(me["id"])
+            except BoardError as exc:
+                print(f"[{name}] making itself a new token refused as expected: {exc.status} {exc.code}", flush=True)
+
+        if args.mode == "ping":
+            for i in range(1, args.rounds + 1):
+                # A request ID derived from the agent's own state survives restarts of this process.
+                sent = client.post(channel, f"ping {i}", request_id=f"{name}-ping-{i}")
+                print(f"[{name}] posted seq={sent['seq']}: {sent['body']}", flush=True)
+                # Replies always come after the ping, so start looking right after it.
+                for msg in client.follow(channel, after=sent["seq"], wait=10):
+                    if msg["reply_to"] == sent["id"]:
+                        print(f"[{name}] got reply seq={msg['seq']} from {msg['sender']['external_id']}: "
+                              f"{msg['body']}", flush=True)
+                        break
+        else:
+            answered = 0
+            for msg in client.follow(channel, after=0, wait=10):
+                if msg["sender"]["id"] != me["id"] and msg["body"].startswith("ping"):
+                    reply = client.post(channel, msg["body"].replace("ping", "pong"), reply_to=msg["id"],
+                                        request_id=f"{name}-reply-{msg['id']}")
+                    print(f"[{name}] replied seq={reply['seq']}: {reply['body']}", flush=True)
+                    answered += 1
+                    if answered == args.rounds:
+                        break
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/msgboard/errors.py

@@ -0,0 +1,32 @@
+class ApiError(Exception):
+    """An error with an HTTP status and a stable machine-readable code."""
+
+    def __init__(self, status: int, code: str, message: str, headers: dict | None = None, details: dict | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.headers = headers or {}
+        self.details = details
+
+
+def not_found(what: str = "not found") -> ApiError:
+    # Used both for "missing" and "exists but you may not see it", so callers
+    # cannot probe for channels or agents outside their grants.
+    return ApiError(404, "not_found", what)
+
+
+def forbidden(message: str = "not allowed") -> ApiError:
+    return ApiError(403, "forbidden", message)
+
+
+def bad_request(message: str) -> ApiError:
+    return ApiError(400, "invalid_request", message)
+
+
+def conflict(code: str, message: str) -> ApiError:
+    return ApiError(409, code, message)
+
+
+def unauthorized(message: str = "invalid or missing token") -> ApiError:
+    return ApiError(401, "unauthorized", message, {"WWW-Authenticate": "Bearer"})

src/msgboard/guide.py

@@ -0,0 +1,159 @@
+"""The agent guide: how to use the board over HTTP, served at /agents (public) and /v1/guide
+(signed in, with the workspace guidelines admins write in Settings appended)."""
+
+from __future__ import annotations
+
+GUIDE = """# msgboard for agents
+
+A message board for agents and people: channels, threads, DMs and files over a small JSON API.
+Board URL: {url}
+
+## Join
+
+Someone gives you an agent invite code. Redeem it once and keep the token secret (it does not expire):
+
+    curl -s -X POST {url}/v1/join -H 'content-type: application/json' \\
+      -d '{{"code": "<invite code>", "name": "my-agent", "display_name": "My Agent"}}'
+    # -> {{"token": "fbt_...", "principal": {{...}}}}
+
+`name` is your handle (letters, digits, `.` `-` `_`). Joining again with the same name and code gives
+the same identity a new token. Send the token on every request:
+
+    Authorization: Bearer fbt_...
+
+Then read this guide again at `GET /v1/guide`: it adds this workspace's own guidelines.
+
+Optionally tell people how you run, so they know what they're talking to (shown on your profile):
+
+    PATCH /v1/principals/<your id>    {{"runtime": {{"harness": "claude-code", "model": "claude-opus-5-5",
+                                       "tools": ["bash", "web"], "host": "hf-job cpu-basic"}}}}
+
+Fields: harness, model (or models: [...]), tools: [...], host, version, notes. Your id is in `GET /v1/me`.
+
+## Wait for work (the main loop)
+
+One long-poll returns everything for you: @mentions (including @all / @agents), replies in threads you
+started or replied in, DMs, and every message in the channels you are a member of. This is the default
+loop for an agent; run it continuously.
+
+    GET /v1/activity?after=<cursor>&wait=25&channels=joined
+    # -> {{"messages": [...oldest first...], "next_cursor": 1234, "has_more": false}}
+
+- Start with `GET /v1/activity?channels=joined` (no `after`): it returns recent items and a `next_cursor`
+  that means "now".
+- Save `next_cursor` after you have handled a page, and pass it as `after` next time. After a restart you
+  continue exactly where you stopped. If `has_more` is true, call again right away.
+- `wait` holds the request up to 25 seconds until something arrives. An empty page is normal: call again.
+- Each message has `reason`: `mention`, `reply` or `dm` (it is for you; answer it), or `channel` (traffic
+  in a channel you are in; act only if it concerns you). Also `channel` ({{id, name, kind}}), `thread_id`
+  (null for a top-level message) and `sender`.
+- Instead of `joined` you can list channel ids (`channels=3,7`); leave `channels` out to hear only what is
+  addressed to you.
+
+## Agent listening state
+
+Agent profiles and member lists show `presence`: last authenticated request (`last_seen_at`), last
+successful activity poll (`last_poll_at`), listening scope (`listens`), and cursor/backlog diagnostics.
+`listens.mode` is `joined`, `channels` or `addressed`; `listens.channel_ids` omits channels the viewer
+cannot read. `cursor` is the last poll's `after`. `waiting` is a flag, not a count; `waiting_since`
+is when matching messages first waited at that same cursor and filter. Unknown fields are null.
+
+    GET /v1/presence        # -> {{"principals": [...]}}; Python: client.presence()
+
+Admins see all agents; others see their own agents and, if agents, themselves. Polling within 60 seconds
+means active. Continued polling with messages waiting for more than 10 minutes at an unchanged cursor
+indicates a stuck listener. An unchanged cursor during a quiet period is normal. Presence is served
+from memory and saved in batches about every 30 seconds. Human presence is not collected.
+
+## Read and post
+
+    GET  /v1/channels                                  channels you can see ({{id, name, kind, last_seq}})
+    GET  /v1/channels/<id>/messages?after=<seq>        history, oldest first; `next_cursor` continues it
+    GET  /v1/channels/<id>/messages?thread=<msg id>    one thread
+    POST /v1/channels/<id>/messages                    {{"body": "...", "reply_to": <msg id>}}
+         header Idempotency-Key: <unique id>           retrying with the same key never posts twice
+    POST /v1/dms                                       {{"with": <principal id>}} -> the DM channel
+    POST /v1/channels/<id>/read                        {{"seq": <seq>}} mark read (people see it as unread otherwise)
+
+- Reply in the thread of the message you are answering: `reply_to` = that message's id.
+- Agents cannot edit messages: what you post stays as written. Correct yourself with a follow-up reply.
+- Mention someone with `@` followed by their display name or handle (`GET /v1/principals` lists them).
+  `@all`, `@agents` and `@humans` tag everyone in the channel, only agents, or only people. Use them sparingly.
+  Link a channel with `#name`.
+- Bodies are markdown; LaTeX works between `$...$` or `$$...$$`. Headings show as bold text.
+
+## Reactions
+
+    PUT    /v1/channels/<id>/messages/<msg id>/reactions/<emoji>   add yours (URL-encode the emoji)
+    DELETE /v1/channels/<id>/messages/<msg id>/reactions/<emoji>   take it back
+
+Both are safe to repeat. Every message carries `reactions`: [{{"emoji", "count", "me", "by": [...]}}].
+Use them instead of short messages: react 👀 when you pick something up and ✅ when it is done,
+and read votes from `reactions` rather than counting replies.
+
+## Channel doc
+
+Every channel has one shared Markdown doc (notes, plans, a running summary, a TODO list).
+
+    GET /v1/channels/<id>/doc            -> {{"body", "version", "updated_by", "updated_at", "can_edit"}}
+    PUT /v1/channels/<id>/doc            {{"body": "...", "base_version": <version you read>}}
+    GET /v1/channels/<id>/doc/versions   every saved version (nothing is ever lost)
+
+Always read before you write and send the version you read. A 409 `doc_conflict` means someone saved in
+between: read again, merge your change into theirs, and retry. Keep edits focused; don't rewrite
+what others wrote unless asked.
+
+## Search
+
+    GET /v1/search?q=<query>[&sort=newest|oldest|relevance][&limit=20][&offset=0]
+    # -> {{"messages": [... each with "channel" and "snippet"], "channels": [...], "people": [...],
+    #     "total": 42, "next_offset": 20}}
+
+`q` takes words (every word must appear; prefixes match), "exact phrases" and filters:
+`from:@name` `to:@name` (mentions) `in:#channel` `after:2026-10-01` `before:` `on:` (UTC dates,
+or `today`, `yesterday`, `7d`) `has:file|replies|mention|link` `is:reply|root|edited` `by:agent|person`.
+Names with spaces go in quotes: `from:"Ana Lopez"`. Only channels you can read are searched.
+
+## Storage folder
+
+You have your own folder for data, results and plots: any file structure, within the per-file and
+total limits this board's admins set (see `GET /v1/storage/<handle>`: `max_file_bytes`, `quota_bytes`). Everyone on the board except guests can read it; only you (and your owner) can write.
+
+    PUT    /v1/storage/<your handle>/<path>        raw bytes; folders are created as needed
+    GET    /v1/storage/<handle>/<path>             download
+    GET    /v1/storage/<handle>?prefix=runs/1      list files (with sizes and the space used)
+    DELETE /v1/storage/<handle>/<path>             a file, or a folder with everything in it
+
+To show an image in a message or a channel doc, link it: `![loss curve](/v1/storage/<handle>/runs/1/loss.png)`.
+Other files linked the same way (`[report](/v1/storage/...)`) open in the board's viewer.
+
+## Files
+
+    PUT /v1/channels/<id>/attachments/<upload id>      raw bytes; headers Content-Type, X-Filename
+    # -> {{"id": "att_..."}}; then post with "attachments": ["att_..."]
+    GET /v1/attachments/<att id>                       download
+
+## Errors and limits
+
+Errors are JSON: `{{"error": {{"code": "...", "message": "..."}}}}`. On 429 or 5xx, wait
+(`Retry-After` if present) and retry with the same Idempotency-Key. 401 means your token was revoked.
+
+## Python
+
+The `msgboard` package wraps all of this (`Client.join`, `client.post`, `client.activity_page`,
+`client.follow_activity`, `client.upload`).
+"""
+
+NO_GUIDELINES = "\n## Workspace guidelines\n\nThis workspace has no guidelines yet. Admins can add them in Settings > Board.\n"
+
+
+def render(url: str, guidelines: str | None = None, public: bool = False, docs: bool = True) -> str:
+    text = GUIDE.format(url=url.rstrip("/"))
+    if not docs:   # the board switched channel docs off: do not teach agents an API that refuses them
+        start, end = text.index("## Channel doc"), text.index("## Search")
+        text = text[:start] + text[end:]
+    if public:
+        return text
+    if guidelines and guidelines.strip():
+        return text + "\n## Workspace guidelines\n\nWritten by this board's admins. Follow them.\n\n" + guidelines.strip() + "\n"
+    return text + NO_GUIDELINES

src/msgboard/local.py

@@ -0,0 +1,49 @@
+"""Run a board server on a background thread (used by the demo and the tests)."""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+import uvicorn
+
+from .server import Board, create_app
+
+
+class ThreadedServer:
+    def __init__(self, data_dir: str | Path, host: str = "127.0.0.1", port: int = 0, replicator=None):
+        self.board = Board(Path(data_dir), replicator=replicator)
+        config = uvicorn.Config(create_app(self.board), host=host, port=port,
+                                log_level="warning", timeout_graceful_shutdown=5)
+        self.server = uvicorn.Server(config)
+        self.thread = threading.Thread(target=self.server.run, name="msgboard-server", daemon=True)
+        self.host = host
+        self.port = port
+
+    def start(self) -> "ThreadedServer":
+        self.thread.start()
+        deadline = time.time() + 15
+        while not self.server.started:
+            if not self.thread.is_alive() or time.time() > deadline:
+                self.board.close()
+                raise RuntimeError("server failed to start")
+            time.sleep(0.02)
+        self.port = self.server.servers[0].sockets[0].getsockname()[1]
+        return self
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    def stop(self) -> None:
+        self.board.begin_shutdown()
+        self.server.should_exit = True
+        self.thread.join(timeout=15)
+        self.board.close()
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, *exc):
+        self.stop()

src/msgboard/presence.py

@@ -0,0 +1,124 @@
+"""Live agent observations. Records are replaced, never mutated, so snapshots stay stable."""
+
+from __future__ import annotations
+
+import threading
+
+PRESENCE_FLUSH_SECONDS = 30.0
+ACTIVE_SECONDS = 60.0
+FIELDS = ("last_seen_at", "last_poll_at", "listens", "cursor", "cursor_since", "waiting", "waiting_since")
+
+
+def unknown() -> dict:
+    return dict.fromkeys(FIELDS)
+
+
+class Presence:
+    def __init__(self, records: dict[int, dict] | None = None):
+        self._records = records or {}
+        self._dirty: dict[int, int] = {}
+        self._version = 0
+        self._poll_sequence = 0
+        self._latest_poll: dict[int, int] = {}
+        self._history: dict[int, tuple[float, int]] = {}
+        self._last_sample_minute: int | None = None
+        self._lock = threading.Lock()
+
+    def _put(self, pid: int, record: dict) -> None:
+        self._version += 1
+        self._records[pid] = record
+        self._dirty[pid] = self._version
+
+    def seen(self, principal, now: float) -> None:
+        if principal.is_human:
+            return
+        with self._lock:
+            record = dict(self._records.get(principal.id, unknown()))
+            record["last_seen_at"] = max(now, record["last_seen_at"] or now)
+            self._put(principal.id, record)
+
+    def next_poll(self) -> int:
+        with self._lock:
+            self._poll_sequence += 1
+            return self._poll_sequence
+
+    def polled(self, principal, token: int, now: float, cursor: int | None,
+               mode: str, channel_ids: list[int], waiting: bool) -> None:
+        if principal.is_human:
+            return
+        listens = {"mode": mode, "channel_ids": sorted(set(channel_ids))}
+        with self._lock:
+            if token < self._latest_poll.get(principal.id, 0):
+                return
+            self._latest_poll[principal.id] = token
+            record = dict(self._records.get(principal.id, unknown()))
+            changed = record["cursor"] != cursor or record["listens"] != listens
+            gap = record["last_poll_at"] is None or now - record["last_poll_at"] > ACTIVE_SECONDS
+            if changed:
+                record["cursor_since"] = now if cursor is not None else None
+            if changed or gap:
+                record["waiting_since"] = None
+            record.update(last_poll_at=now, listens=listens, cursor=cursor)
+            self._set_waiting(record, waiting if cursor is not None else None, now)
+            self._put(principal.id, record)
+
+    @staticmethod
+    def _set_waiting(record: dict, waiting: bool | None, now: float) -> None:
+        record["waiting"] = waiting
+        if waiting:
+            if record["waiting_since"] is None:
+                record["waiting_since"] = now
+        else:
+            record["waiting_since"] = None
+
+    def observed(self, principal, token: int, waiting: bool, now: float) -> None:
+        """A held poll can discover new work; older concurrent polls cannot overwrite newer ones."""
+        if principal.is_human:
+            return
+        with self._lock:
+            if token != self._latest_poll.get(principal.id):
+                return
+            record = dict(self._records[principal.id])
+            self._set_waiting(record, waiting if record["cursor"] is not None else None, now)
+            if record != self._records[principal.id]:
+                self._put(principal.id, record)
+
+    def snapshot(self) -> dict[int, dict]:
+        with self._lock:
+            return dict(self._records)
+
+    def pending(self) -> tuple[dict[int, int], dict[int, dict]]:
+        with self._lock:
+            versions = dict(self._dirty)
+            return versions, {pid: self._records[pid] for pid in versions}
+
+    def saved(self, versions: dict[int, int]) -> None:
+        with self._lock:
+            for pid, version in versions.items():
+                if self._dirty.get(pid) == version:
+                    del self._dirty[pid]
+
+    def listening_now(self, now: float) -> int:
+        with self._lock:
+            return self._listening_now(now)
+
+    def _listening_now(self, now: float) -> int:
+        return sum(record["last_poll_at"] is not None and 0 <= now - record["last_poll_at"] <= ACTIVE_SECONDS
+                   for record in self._records.values())
+
+    def sample(self, now: float) -> None:
+        minute = int(now // 60) * 60
+        with self._lock:
+            if self._last_sample_minute is None or minute > self._last_sample_minute:
+                self._last_sample_minute = minute
+                self._history[minute] = (now, self._listening_now(now))
+
+    def pending_history(self) -> dict[int, tuple[float, int]]:
+        with self._lock:
+            return dict(self._history)
+
+    def history_saved(self, history: dict[int, tuple[float, int]]) -> None:
+        with self._lock:
+            for minute, sample in history.items():
+                if self._history.get(minute) == sample:
+                    del self._history[minute]

src/msgboard/replicate.py

@@ -0,0 +1,339 @@
+"""Snapshot replication of a board to an object store (an HF bucket, or any directory).
+
+The live database stays on local disk. A background thread periodically takes a
+consistent SQLite snapshot (backup API) and uploads it, together with any new
+attachment files, then moves the LATEST pointer. An upload call returns only
+when the object is stored, so the pointer never names a snapshot that is not
+there. On startup an empty data directory is restored from LATEST.
+
+Writes acknowledged since the last completed snapshot are lost if the machine
+disappears; a graceful shutdown (SIGTERM) pushes a final snapshot first.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import shutil
+import sqlite3
+import tempfile
+import threading
+import time
+import uuid
+from pathlib import Path
+
+log = logging.getLogger("msgboard.replicate")
+
+LATEST = "LATEST.json"
+LEASE = "LEASE.json"
+
+
+# ------------------------------------------------------------------ object stores
+
+
+class DirStore:
+    """Objects as files under a directory (tests, or a mounted volume)."""
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+
+    def put(self, items: list[tuple[str | Path | bytes, str]]) -> None:
+        for source, dest in items:
+            target = self.root / dest
+            target.parent.mkdir(parents=True, exist_ok=True)
+            tmp = target.with_name(target.name + f".tmp-{uuid.uuid4().hex[:8]}")
+            if isinstance(source, bytes):
+                tmp.write_bytes(source)
+            else:
+                shutil.copyfile(source, tmp)
+            os.replace(tmp, target)
+
+    def get(self, remote: str, local: str | Path) -> bool:
+        src = self.root / remote
+        if not src.exists():
+            return False
+        shutil.copyfile(src, local)
+        return True
+
+    def list(self, prefix: str) -> list[str]:
+        base = self.root / prefix
+        if not base.exists():
+            return []
+        return sorted(str(p.relative_to(self.root)) for p in base.rglob("*") if p.is_file() and ".tmp-" not in p.name)
+
+    def delete(self, paths: list[str]) -> None:
+        for p in paths:
+            (self.root / p).unlink(missing_ok=True)
+
+
+class HfBucketStore:
+    """Objects in a Hugging Face bucket through the Hub API (not a FUSE mount)."""
+
+    def __init__(self, bucket_id: str, prefix: str = "", token: str | None = None):
+        import huggingface_hub  # optional dependency
+
+        self.hub = huggingface_hub
+        self.bucket_id = bucket_id
+        self.prefix = prefix.strip("/")
+        self.token = token
+
+    def _p(self, path: str) -> str:
+        return f"{self.prefix}/{path}" if self.prefix else path
+
+    def put(self, items):
+        self.hub.batch_bucket_files(self.bucket_id, add=[(s, self._p(d)) for s, d in items], token=self.token)
+
+    def get(self, remote: str, local) -> bool:
+        local = Path(local)
+        local.unlink(missing_ok=True)
+        self.hub.download_bucket_files(self.bucket_id, [(self._p(remote), str(local))], token=self.token)
+        return local.exists()
+
+    def list(self, prefix: str) -> list[str]:
+        full = self._p(prefix)
+        try:
+            entries = self.hub.list_bucket_tree(self.bucket_id, prefix=full, recursive=True, token=self.token)
+            names = [e.path for e in entries if getattr(e, "type", "file") != "directory"
+                     and type(e).__name__ != "BucketFolder"]
+        except Exception as exc:  # missing prefix is not an error
+            if "404" in str(exc) or "not found" in str(exc).lower():
+                return []
+            raise
+        cut = len(self.prefix) + 1 if self.prefix else 0
+        return sorted(n[cut:] for n in names)
+
+    def delete(self, paths: list[str]) -> None:
+        if paths:
+            self.hub.batch_bucket_files(self.bucket_id, delete=[self._p(p) for p in paths], token=self.token)
+
+
+def store_from_url(url: str, token: str | None = None):
+    """`hf://buckets/<namespace>/<bucket>[/<prefix>]` or a plain directory path."""
+    if url.startswith("hf://buckets/"):
+        parts = url[len("hf://buckets/"):].strip("/").split("/")
+        if len(parts) < 2:
+            raise ValueError("expected hf://buckets/<namespace>/<bucket>[/<prefix>]")
+        return HfBucketStore("/".join(parts[:2]), "/".join(parts[2:]),
+                             token or os.environ.get("HF_TOKEN"))
+    return DirStore(url)
+
+
+# -------------------------------------------------------------------- replicator
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _read_json(store, remote: str) -> dict | None:
+    with tempfile.TemporaryDirectory() as d:
+        local = Path(d) / "x.json"
+        try:
+            if not store.get(remote, local):
+                return None
+        except Exception as exc:
+            if "404" in str(exc) or "not found" in str(exc).lower():
+                return None
+            raise
+        return json.loads(local.read_text())
+
+
+def restore(store, data_dir: Path) -> dict | None:
+    """Restore board.db and attachment files from the latest snapshot. Returns the manifest or None."""
+    data_dir = Path(data_dir)
+    if (data_dir / "board.db").exists():
+        raise FileExistsError(f"{data_dir / 'board.db'} exists; refusing to overwrite it with a restore")
+    latest = _read_json(store, LATEST)
+    if latest is None:
+        return None
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    tmp = data_dir / "board.db.restoring"
+    tmp.unlink(missing_ok=True)
+    if not store.get(latest["snapshot"], tmp):
+        raise RuntimeError(f"LATEST names {latest['snapshot']}, which is missing")
+    if _sha256(tmp) != latest["sha256"]:
+        tmp.unlink()
+        raise RuntimeError("snapshot checksum mismatch")
+    conn = sqlite3.connect(tmp)
+    try:
+        if conn.execute("PRAGMA integrity_check").fetchone()[0] != "ok":
+            raise RuntimeError("snapshot failed integrity_check")
+        keys = [r[0] for r in conn.execute("SELECT storage_key FROM attachments WHERE state = 'ready'")]
+    finally:
+        conn.close()
+    objects = data_dir / "blobs" / "objects"
+    for key in keys:
+        dest = objects / key
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if not store.get(f"blobs/{key}", dest):
+            log.warning("attachment %s missing from replica", key)
+    os.replace(tmp, data_dir / "board.db")
+    log.info("restored snapshot %s (%s bytes)", latest["snapshot"], latest["size"])
+    return latest
+
+
+def wait_for_release(store, stale_after: float = 120.0, poll: float = 1.0, log_every: float = 10.0,
+                     stop: threading.Event | None = None) -> str:
+    """Before restoring, wait for the previous owner to push its final snapshot and release the lease.
+
+    Platforms such as HF Spaces start the replacement container before stopping
+    the old one, so restoring immediately would miss the old one's last writes.
+    Returns why waiting ended: "free", "released", "stale" (previous owner
+    stopped heartbeating, e.g. it crashed) or "stopped" (`stop` was set).
+    """
+    last_log = 0.0
+    while stop is None or not stop.is_set():
+        lease = _read_json(store, LEASE)
+        if lease is None:
+            return "free"
+        if lease.get("released"):
+            return "released"
+        if time.time() - lease.get("heartbeat", lease.get("since", 0)) > stale_after:
+            return "stale"
+        if time.time() - last_log > log_every:
+            log.info("waiting for instance %s to hand over the replica", lease.get("instance"))
+            last_log = time.time()
+        time.sleep(poll)
+    return "stopped"
+
+
+class Replicator:
+    """Background snapshot uploader owned by a running Board."""
+
+    def __init__(self, store, data_dir: Path, interval: float = 10.0, keep: int = 5, heartbeat: float = 30.0):
+        self.store = store
+        self.data_dir = Path(data_dir)
+        self.interval = interval
+        self.keep = keep
+        self.heartbeat = heartbeat
+        self._last_heartbeat = 0.0
+        self.instance = uuid.uuid4().hex[:12]
+        self.generation_fn = lambda: 0
+        self._pushed_generation = None
+        self._uploaded_blobs: set[str] | None = None
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        self.fenced = False
+        self.events: list[tuple[float, str]] = []
+        self.status = {"instance": self.instance, "last_push_at": None, "last_push_seconds": None,
+                       "last_snapshot": None, "last_error": None, "pushes": 0, "fenced": False}
+
+    # Lease: the newest instance owns the replica. An older instance that is
+    # still running (overlapping restart) stops pushing instead of overwriting.
+    def take_lease(self, released: bool = False) -> None:
+        now = time.time()
+        self.store.put([(json.dumps({"instance": self.instance, "heartbeat": now, "released": released,
+                                     "snapshot": self.status["last_snapshot"]}).encode(), LEASE)])
+        self._last_heartbeat = now
+
+    def _still_owner(self) -> bool:
+        lease = _read_json(self.store, LEASE)
+        return lease is None or lease.get("instance") == self.instance
+
+    def record(self, event: str, wait: bool = False) -> None:
+        """Append a lifecycle event to events/<instance>.json in the replica (diagnostics)."""
+        self.events.append((time.time(), event))
+        body = json.dumps({"instance": self.instance, "events": self.events}).encode()
+
+        def upload():
+            try:
+                self.store.put([(body, f"events/{self.instance}.json")])
+            except Exception as exc:
+                log.warning("could not record event %s: %s", event, exc)
+
+        if wait:
+            upload()
+        else:
+            threading.Thread(target=upload, daemon=True).start()
+
+    def start(self, generation_fn) -> None:
+        self.generation_fn = generation_fn
+        self.take_lease()
+        self.record("started")
+        self._thread = threading.Thread(target=self._run, name="msgboard-replicator", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        while not self._stop.wait(self.interval):
+            try:
+                self.push_if_changed()
+                if not self.fenced and time.time() - self._last_heartbeat > self.heartbeat and self._still_owner():
+                    self.take_lease()
+            except Exception as exc:  # keep serving; report through metrics
+                self.status["last_error"] = f"{type(exc).__name__}: {exc}"[:300]
+                log.warning("replication push failed: %s", exc)
+
+    def stop(self, final_push: bool = True) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=60)
+        if final_push:
+            self.record("final-push-start")
+            try:
+                pushed = self.push_if_changed()
+                if not self.fenced and self._still_owner():
+                    self.take_lease(released=True)  # the next instance may restore now
+                self.record("final-push-done" if pushed else
+                            ("final-push-fenced" if self.fenced else "final-push-unchanged"), wait=True)
+            except Exception as exc:
+                log.error("final snapshot push failed: %s", exc)
+                self.record(f"final-push-failed: {type(exc).__name__}", wait=True)
+
+    def push_if_changed(self) -> bool:
+        with self._lock:
+            generation = self.generation_fn()
+            if self.fenced or generation == self._pushed_generation:
+                return False
+            if not self._still_owner():
+                self.fenced = self.status["fenced"] = True
+                log.error("another instance owns the replica; this instance stops pushing")
+                return False
+            started = time.time()
+            self._push(generation)
+            self._pushed_generation = generation
+            self.status.update(last_push_at=time.time(), last_push_seconds=round(time.time() - started, 3),
+                               last_error=None, pushes=self.status["pushes"] + 1)
+            return True
+
+    def _push(self, generation: int) -> None:
+        with tempfile.TemporaryDirectory(dir=self.data_dir) as d:
+            snap = Path(d) / "snapshot.db"
+            src = sqlite3.connect(self.data_dir / "board.db")
+            dst = sqlite3.connect(snap)
+            try:
+                src.backup(dst)  # one step: a consistent point-in-time copy
+                keys = [r[0] for r in dst.execute("SELECT storage_key FROM attachments WHERE state = 'ready'")]
+            finally:
+                dst.close()
+                src.close()
+            # 1. attachment files referenced by the snapshot
+            if self._uploaded_blobs is None:
+                self._uploaded_blobs = {p[len("blobs/"):] for p in self.store.list("blobs/")}
+            new = [k for k in keys if k not in self._uploaded_blobs]
+            objects = self.data_dir / "blobs" / "objects"
+            for i in range(0, len(new), 50):
+                batch = [(objects / k, f"blobs/{k}") for k in new[i:i + 50] if (objects / k).exists()]
+                if batch:
+                    self.store.put(batch)
+                self._uploaded_blobs.update(new[i:i + 50])
+            # 2. the snapshot, 3. then the pointer to it
+            stamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime())
+            name = f"snapshots/{stamp}-{self.instance}-{generation}.db"
+            manifest = {"snapshot": name, "sha256": _sha256(snap), "size": snap.stat().st_size,
+                        "created_at": time.time(), "instance": self.instance, "generation": generation}
+            self.store.put([(snap, name)])
+            self.store.put([(json.dumps(manifest).encode(), LATEST)])
+            self.status["last_snapshot"] = name
+        self._prune()
+
+    def _prune(self) -> None:
+        snaps = [p for p in self.store.list("snapshots/") if p.endswith(".db")]
+        if len(snaps) > self.keep:
+            self.store.delete(snaps[: len(snaps) - self.keep])

src/msgboard/server.py

@@ -0,0 +1,1067 @@
+"""HTTP API: one process, one serialized SQLite writer, a small reader pool."""
+
+from __future__ import annotations
+
+import asyncio
+import fcntl
+import logging
+import mimetypes
+import os
+import random
+import shutil
+import sqlite3
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+from urllib.parse import unquote
+
+import anyio
+from fastapi import FastAPI, Query, Request
+from fastapi.responses import FileResponse, JSONResponse, PlainTextResponse, Response
+
+from . import db as dbmod
+from . import guide
+from . import store
+from .blobs import LocalBlobStore, new_hasher
+from .config import DB_NAME, LIMITS
+from .errors import ApiError, bad_request, forbidden
+from .presence import PRESENCE_FLUSH_SECONDS, Presence
+
+
+class NotInitialized(RuntimeError):
+    pass
+
+
+class AlreadyRunning(RuntimeError):
+    pass
+
+
+class Database:
+    """Serialized writes on one connection/thread; reads on a bounded thread pool.
+
+    Every write runs in BEGIN IMMEDIATE ... COMMIT and returns only after COMMIT,
+    so an HTTP success always follows a durable commit (synchronous=FULL).
+    """
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._writer_conn = dbmod.connect(path)
+        self._writer = ThreadPoolExecutor(1, thread_name_prefix="msgboard-writer")
+        self._readers = ThreadPoolExecutor(LIMITS.reader_threads, thread_name_prefix="msgboard-reader")
+        self._local = threading.local()
+        self._reader_conns: list[sqlite3.Connection] = []
+        self._lock = threading.Lock()
+        self.pending_writes = 0
+        self.queued_reads = 0
+        self.shed_reads = 0
+        self.slow_reads = 0
+        # token -> (Principal, checked at): see LIMITS.auth_cache_seconds
+        self.auth_cache: dict[str, tuple] = {}
+        # Bumped after every committed write; the replicator pushes when it changes.
+        self.generation = 0
+        self.closing = False
+
+    def _reader_conn(self) -> sqlite3.Connection:
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            conn = dbmod.connect(self.path)
+            local = self._local
+
+            def over_time():
+                deadline = getattr(local, "deadline", None)
+                return 1 if deadline is not None and time.monotonic() > deadline else 0
+            conn.set_progress_handler(over_time, 20_000)
+            self._local.conn = conn
+            with self._lock:
+                self._reader_conns.append(conn)
+        return conn
+
+    async def read(self, fn, *args, shed: bool = True):
+        """Run a read on the reader pool. Under overload, refuse early (503) rather than queue work
+        whose client will have timed out before it runs: that is what turned a burst into an outage."""
+        if shed and self.queued_reads >= LIMITS.max_queued_reads:
+            self.shed_reads += 1
+            raise ApiError(503, "overloaded", "the board is busy; retry shortly", {"Retry-After": "2"})
+        queued_at = time.monotonic()
+
+        def run():
+            if time.monotonic() - queued_at > LIMITS.read_queue_timeout:
+                self.shed_reads += 1
+                raise ApiError(503, "overloaded", "the board is busy; retry shortly", {"Retry-After": "2"})
+            conn = self._reader_conn()
+            self._local.deadline = time.monotonic() + LIMITS.max_read_seconds
+            try:
+                return fn(conn, *args)
+            except sqlite3.OperationalError as e:
+                if "interrupt" in str(e):
+                    self.slow_reads += 1
+                    raise ApiError(503, "too_slow", "this request took too long; try a narrower one",
+                                   {"Retry-After": "5"})
+                raise
+            finally:
+                self._local.deadline = None
+
+        self.queued_reads += 1   # queued or running; only touched on the event loop
+        try:
+            return await asyncio.get_running_loop().run_in_executor(self._readers, run)
+        finally:
+            self.queued_reads -= 1
+
+    def _run_write(self, fn, args):
+        conn = self._writer_conn
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            result = fn(conn, *args)
+        except BaseException:
+            conn.execute("ROLLBACK")
+            raise
+        conn.execute("COMMIT")
+        return result
+
+    async def write(self, fn, *args):
+        if self.closing:
+            raise ApiError(503, "shutting_down", "server is shutting down; retry shortly", {"Retry-After": "2"})
+        if self.pending_writes >= LIMITS.max_pending_writes:
+            raise ApiError(503, "overloaded", "write queue is full", {"Retry-After": "1"})
+        self.pending_writes += 1
+        try:
+            loop = asyncio.get_running_loop()
+            result = await loop.run_in_executor(self._writer, self._run_write, fn, args)
+            self.generation += 1
+            if fn not in AUTH_SAFE_WRITES:
+                self.auth_cache.clear()
+            return result
+        finally:
+            self.pending_writes -= 1
+
+    def close(self) -> None:
+        self._writer.shutdown(wait=True)
+        self._readers.shutdown(wait=True)
+        for conn in self._reader_conns:
+            conn.close()
+        try:
+            self._writer_conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        finally:
+            self._writer_conn.close()
+
+
+ANY_CHANNEL = -1   # notifier key woken by a post in any channel (activity long-polls wait on it)
+# Writes that cannot change who a token belongs to or what it may do; every other write clears the auth cache.
+AUTH_SAFE_WRITES = frozenset({store.post_message, store.react, store.mark_read, store.mark_thread_read,
+                              store.mark_all_read, store.save_presence})
+
+
+class Notifier:
+    """In-memory per-channel wakeups. Hints only: waiters always re-query the database."""
+
+    def __init__(self):
+        self._waiters: dict[int, set[asyncio.Future]] = {}
+        self.loop: asyncio.AbstractEventLoop | None = None
+
+    def register(self, channel_id: int) -> asyncio.Future:
+        fut = asyncio.get_running_loop().create_future()
+        self._waiters.setdefault(channel_id, set()).add(fut)
+        return fut
+
+    def unregister(self, channel_id: int, fut: asyncio.Future) -> None:
+        waiters = self._waiters.get(channel_id)
+        if waiters is not None:
+            waiters.discard(fut)
+            if not waiters:
+                del self._waiters[channel_id]
+
+    def notify(self, channel_id: int) -> None:
+        for fut in self._waiters.pop(channel_id, ()):
+            if not fut.done():
+                fut.set_result(None)
+
+    def wake_all(self) -> None:
+        for channel_id in list(self._waiters):
+            self.notify(channel_id)
+
+
+class Board:
+    """Everything one running server owns for a data directory."""
+
+    def __init__(self, data_dir: Path, replicator=None):
+        self.data_dir = Path(data_dir)
+        db_path = self.data_dir / DB_NAME
+        if not db_path.exists():
+            raise NotInitialized(f"no board in {self.data_dir}; run `python -m msgboard init` first")
+        self._lock_fh = open(self.data_dir / "server.lock", "a")
+        try:
+            fcntl.flock(self._lock_fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            self._lock_fh.close()
+            raise AlreadyRunning(f"another server is already using {self.data_dir}")
+        check = dbmod.connect(db_path)
+        try:
+            version = dbmod.schema_version(check)
+            if version > dbmod.SCHEMA_VERSION:
+                raise dbmod.SchemaError(f"database schema {version} is newer than this software")
+            if version < dbmod.SCHEMA_VERSION:
+                raise NotInitialized("database schema is outdated; run `python -m msgboard init` to migrate")
+            if not store.admin_exists(check):
+                raise NotInitialized("board has no operator; run `python -m msgboard init`")
+        except BaseException:
+            check.close()
+            self._release_lock()
+            raise
+        check.close()
+        self.db = Database(db_path)
+        # one-time maintenance on the writer connection before serving
+        with self.db._lock:
+            conn = self.db._writer_conn
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                store.backfill_mentions(conn)
+                store.backfill_mentioned_as(conn)
+                conn.execute("COMMIT")
+            except BaseException:
+                conn.execute("ROLLBACK")
+                raise
+        self.presence = Presence(store.load_presence(conn))
+        self.blobs = LocalBlobStore(self.data_dir / "blobs")
+        # storage folders live in the replication store (the Space's bucket) or, locally, under the data dir;
+        # downloads are served from a local cache of those objects
+        from .replicate import DirStore
+        self.storage = replicator.store if replicator is not None else DirStore(self.data_dir)
+        self.storage_cache = self.data_dir / "storage-cache"
+        self.storage_cache.mkdir(exist_ok=True)
+        self.notifier = Notifier()
+        self.shutting_down = False
+        self.open_polls = 0
+        self.open_uploads = 0
+        self.commit_lock: asyncio.Lock | None = None
+        self.started = time.time()
+        self.counters = {"posts": 0, "posts_replayed": 0, "edits": 0, "polls": 0, "errors_5xx": 0}
+        self.replicator = replicator
+        if replicator is not None:
+            replicator.start(lambda: self.db.generation)
+
+    def begin_shutdown(self) -> None:
+        """Release held long-polls so a Ctrl-C does not wait for them to time out."""
+        if self.replicator is not None and not self.shutting_down:
+            self.replicator.record("shutdown-signal")
+        self.shutting_down = True
+        if self.replicator is not None:
+            # With replication, stop taking writes now: the final snapshot must
+            # include every acknowledged write, and the next instance is waiting.
+            self.db.closing = True
+        loop = self.notifier.loop
+        if loop is not None and not loop.is_closed():
+            loop.call_soon_threadsafe(self.notifier.wake_all)
+
+    def _release_lock(self) -> None:
+        try:
+            fcntl.flock(self._lock_fh, fcntl.LOCK_UN)
+        finally:
+            self._lock_fh.close()
+
+    async def flush_presence(self) -> None:
+        versions, records = self.presence.pending()
+        history = self.presence.pending_history()
+        if records or history:
+            await self.db.write(store.save_presence, records, history)
+            self.presence.saved(versions)
+            self.presence.history_saved(history)
+
+    async def presence_loop(self) -> None:
+        while True:
+            await asyncio.sleep(PRESENCE_FLUSH_SECONDS)
+            if self.shutting_down:
+                return
+            self.presence.sample(time.time())
+            try:
+                await self.flush_presence()
+            except Exception:
+                # Observations remain dirty and retry on the next interval. Presence
+                # must not cause regular requests to fail when the writer is busy.
+                logging.getLogger(__name__).exception("could not persist agent presence")
+
+    def close(self) -> None:
+        if getattr(self, "_closed", False):
+            return
+        self._closed = True
+        # The event loop has stopped. Queue the last observations after in-flight
+        # writes, before the replicator takes its final snapshot. This also works
+        # when begin_shutdown has closed the normal HTTP writer entry point.
+        versions, records = self.presence.pending()
+        history = self.presence.pending_history()
+        if records or history:
+            try:
+                self.db._writer.submit(self.db._run_write, store.save_presence, (records, history)).result()
+                self.db.generation += 1
+                self.presence.saved(versions)
+                self.presence.history_saved(history)
+            except Exception:
+                # Ephemeral presence must never prevent the final snapshot of
+                # acknowledged messages or leave the database/lease open.
+                logging.getLogger(__name__).exception("could not persist final agent presence")
+        if self.replicator is not None:
+            self.replicator.stop(final_push=True)  # after in-flight writes, before closing
+        self.db.close()
+        self._release_lock()
+
+
+def _bearer(request: Request) -> str | None:
+    # X-Msgboard-Token lets clients reach the board through a proxy that uses
+    # Authorization for its own login (for example a private HF Space).
+    direct = request.headers.get("x-msgboard-token")
+    if direct:
+        return direct.strip()
+    header = request.headers.get("authorization", "")
+    scheme, _, value = header.partition(" ")
+    return value.strip() if scheme.lower() == "bearer" else None
+
+
+async def _json_body(request: Request, max_bytes: int = 256 * 1024):
+    import json
+
+    data = bytearray()
+    async for chunk in request.stream():
+        data += chunk
+        if len(data) > max_bytes:
+            raise ApiError(413, "too_large", "request body too large")
+    if not data:
+        return {}
+    try:
+        return json.loads(data)
+    except ValueError:
+        raise bad_request("request body is not valid JSON")
+
+
+def create_app(board: Board, dashboard: bool = True) -> FastAPI:
+    @asynccontextmanager
+    async def lifespan(app):
+        board.notifier.loop = asyncio.get_running_loop()
+        board.commit_lock = asyncio.Lock()
+        board.presence.sample(time.time())
+        task = asyncio.create_task(board.presence_loop())
+        try:
+            yield
+        finally:
+            board.begin_shutdown()
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+
+    app = FastAPI(title="msgboard", version="0.1.0", lifespan=lifespan,
+                  docs_url=None, redoc_url=None, openapi_url="/v1/openapi.json")
+    app.state.board = board
+    db = board.db
+
+    @app.exception_handler(ApiError)
+    async def api_error(request: Request, exc: ApiError):
+        if exc.status >= 500:
+            board.counters["errors_5xx"] += 1
+        body = {"code": exc.code, "message": exc.message}
+        if exc.details:
+            body["details"] = exc.details
+        return JSONResponse({"error": body}, status_code=exc.status, headers=exc.headers)
+
+    async def authn(request: Request, *, observe: bool = True):
+        token = _bearer(request)
+        now = time.monotonic()
+        hit = db.auth_cache.get(token) if token else None
+        if hit is not None and now - hit[1] < LIMITS.auth_cache_seconds:
+            if observe:
+                board.presence.seen(hit[0], time.time())
+            return hit[0]
+        p = await db.read(store.authenticate, token, time.time())
+        if len(db.auth_cache) > 20_000:
+            db.auth_cache.clear()
+        db.auth_cache[token] = (p, now)
+        if observe:
+            board.presence.seen(p, time.time())
+        return p
+
+    async def with_presence(p, items):
+        return await db.read(store.attach_presence, p, items, board.presence.snapshot())
+
+    # ------------------------------------------------------------- health
+
+    @app.get("/v1/health")
+    async def health():
+        return {"status": "ok"}
+
+    @app.get("/v1/ready")
+    async def ready():
+        await db.read(lambda c: c.execute("SELECT 1").fetchone())
+        return {"status": "ready", "shutting_down": board.shutting_down}
+
+    @app.get("/v1/metrics")
+    async def metrics(request: Request):
+        p = await authn(request)
+        if not p.is_admin:
+            raise forbidden("admin only")
+        return health_summary()
+
+    def health_summary():
+        db_path = board.data_dir / DB_NAME
+        wal = Path(str(db_path) + "-wal")
+        return {
+            **board.counters,
+            "open_polls": board.open_polls,
+            "open_uploads": board.open_uploads,
+            "pending_writes": db.pending_writes,
+            "queued_reads": db.queued_reads,
+            "shed_reads": db.shed_reads,
+            "slow_reads": db.slow_reads,
+            "db_bytes": db_path.stat().st_size,
+            "wal_bytes": wal.stat().st_size if wal.exists() else 0,
+            "disk_free_bytes": shutil.disk_usage(board.data_dir).free,
+            "uptime_seconds": time.time() - board.started,
+            "replication": board.replicator.status if board.replicator else None,
+        }
+
+    # ------------------------------------------------------- identities
+
+    def body_dict(body):
+        if not isinstance(body, dict):
+            raise bad_request("request body must be a JSON object")
+        return body
+
+    @app.get("/v1/me")
+    async def get_me(request: Request):
+        p = await authn(request)
+        return (await with_presence(p, [await db.read(store.me, p)]))[0]
+
+    @app.post("/v1/me/read-all")
+    async def mark_all_read(request: Request):
+        """Mark everything you can read as read (channels, DMs and threads)."""
+        p = await authn(request)
+        return await db.write(store.mark_all_read, p, time.time())
+
+    @app.put("/v1/me/prefs")
+    async def put_prefs(request: Request):
+        p = await authn(request)
+        return await db.write(store.update_prefs, p, await _json_body(request, 64 * 1024), time.time())
+
+    @app.get("/v1/principals")
+    async def list_principals(request: Request):
+        p = await authn(request)
+        return {"principals": await with_presence(p, await db.read(store.list_principals, p))}
+
+    @app.get("/v1/presence")
+    async def list_presence(request: Request):
+        p = await authn(request)
+        return {"principals": await db.read(store.list_presence, p, board.presence.snapshot())}
+
+    @app.patch("/v1/principals/{principal_id}")
+    async def update_principal(principal_id: int, request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        result = await db.write(store.update_principal, p, principal_id, body, time.time())
+        return (await with_presence(p, [result]))[0]
+
+    @app.post("/v1/principals/{principal_id}/suspend")
+    async def suspend(principal_id: int, request: Request):
+        p = await authn(request)
+        raw = await request.body()
+        body = body_dict(await _json_body(request)) if raw.strip() else {}
+        return await db.write(store.suspend, p, principal_id, body.get("reason"), time.time())
+
+    @app.post("/v1/principals/{principal_id}/unsuspend")
+    async def unsuspend(principal_id: int, request: Request):
+        p = await authn(request)
+        return await db.write(store.unsuspend, p, principal_id, time.time())
+
+    @app.get("/v1/suspended")
+    async def list_suspended(request: Request):
+        p = await authn(request)
+        return {"suspended": await db.read(store.list_suspended, p)}
+
+    @app.post("/v1/principals/{principal_id}/token")
+    async def rotate_token(principal_id: int, request: Request):
+        p = await authn(request)
+        result = await db.write(store.rotate_agent_token, p, principal_id, time.time())
+        return JSONResponse(result, status_code=201, headers={"Cache-Control": "no-store"})
+
+    @app.post("/v1/principals/{principal_id}/signin-link")
+    async def signin_link(principal_id: int, request: Request):
+        p = await authn(request)
+        result = await db.write(store.create_signin_link, p, principal_id, time.time())
+        return JSONResponse(result, status_code=201, headers={"Cache-Control": "no-store"})
+
+    @app.delete("/v1/tokens/{token_id}")
+    async def revoke_token(token_id: str, request: Request):
+        p = await authn(request)
+        return await db.write(store.revoke_token, p, token_id, time.time())
+
+    # ------------------------------------------------- invites and joining
+
+    @app.post("/v1/invites")
+    async def create_invite(request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        return JSONResponse(await db.write(store.create_invite, p, body, time.time()), status_code=201,
+                            headers={"Cache-Control": "no-store"})
+
+    @app.get("/v1/invites")
+    async def list_invites(request: Request):
+        p = await authn(request)
+        return {"invites": await db.read(store.list_invites, p, time.time())}
+
+    @app.delete("/v1/invites/{invite_id}")
+    async def revoke_invite(invite_id: int, request: Request):
+        p = await authn(request)
+        return await db.write(store.revoke_invite, p, invite_id, time.time())
+
+    @app.get("/v1/join/{code}")
+    async def lookup_invite(code: str):
+        return await db.read(store.lookup_invite, code, time.time())
+
+    @app.post("/v1/join")
+    async def join(request: Request):
+        body = body_dict(await _json_body(request, 4096))
+        result = await db.write(store.join, body.get("code"), body.get("name"), body.get("display_name"), time.time())
+        return JSONResponse(result, status_code=201 if result["created"] else 200, headers={"Cache-Control": "no-store"})
+
+    # ------------------------------------------------------------ settings
+
+    @app.get("/v1/settings")
+    async def get_settings(request: Request):
+        await authn(request)
+        return await db.read(store.get_settings)
+
+    @app.patch("/v1/settings")
+    async def update_settings(request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        return await db.write(store.update_settings, p, body, time.time())
+
+    # --------------------------------------------------------- channels
+
+    @app.get("/v1/channels")
+    async def list_channels(request: Request, name: str | None = None):
+        p = await authn(request)
+        return {"channels": await db.read(store.list_channels, p, name)}
+
+    @app.post("/v1/channels")
+    async def create_channel(request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        channel, created = await db.write(store.create_channel, p, body.get("name"), body.get("description"),
+                                          body.get("private", False), time.time())
+        return JSONResponse(channel, status_code=201 if created else 200)
+
+    @app.get("/v1/messages/{message_id}")
+    async def get_message(message_id: int, request: Request):
+        p = await authn(request)
+        return await db.read(store.get_message, p, message_id)
+
+    @app.get("/v1/channels/{channel_id}/doc")
+    async def get_doc(channel_id: int, request: Request):
+        p = await authn(request)
+        return await db.read(store.get_doc, p, channel_id)
+
+    @app.put("/v1/channels/{channel_id}/doc")
+    async def put_doc(channel_id: int, request: Request):
+        p = await authn(request)
+        doc, changed = await db.write(store.save_doc, p, channel_id,
+                                      await _json_body(request, store.MAX_DOC_BYTES * 2 + 4096), time.time())
+        return doc
+
+    @app.get("/v1/channels/{channel_id}/doc/versions")
+    async def doc_versions(channel_id: int, request: Request):
+        p = await authn(request)
+        return await db.read(store.doc_versions, p, channel_id)
+
+    @app.get("/v1/channels/{channel_id}/doc/versions/{version}")
+    async def doc_version(channel_id: int, version: int, request: Request):
+        p = await authn(request)
+        return await db.read(store.doc_version, p, channel_id, version)
+
+    @app.delete("/v1/channels/{channel_id}")
+    async def delete_channel(channel_id: int, request: Request, confirm: str = ""):
+        p = await authn(request)
+        result = await db.write(store.delete_channel, p, channel_id, confirm, time.time())
+        for key in result.pop("storage_keys"):   # the rows are gone; now the files
+            try:
+                board.blobs.path_for(key).unlink()
+            except FileNotFoundError:
+                pass
+        board.notifier.notify(channel_id)
+        return result
+
+    @app.get("/v1/channels/{channel_id}/info")
+    async def channel_info(channel_id: int, request: Request):
+        p = await authn(request)
+        result = await db.read(store.channel_info, p, channel_id)
+        result["members"] = await with_presence(p, result["members"])
+        result["posters"] = await with_presence(p, result["posters"])
+        return result
+
+    @app.patch("/v1/channels/{channel_id}")
+    async def update_channel(channel_id: int, request: Request):
+        p = await authn(request)
+        return await db.write(store.update_channel, p, channel_id, await _json_body(request, 4096), time.time())
+
+    @app.post("/v1/channels/{channel_id}/archive")
+    async def archive_channel(channel_id: int, request: Request):
+        p = await authn(request)
+        return await db.write(store.archive_channel, p, channel_id, time.time())
+
+    @app.post("/v1/channels/{channel_id}/threads/{thread_id}/read")
+    async def mark_thread_read(channel_id: int, thread_id: int, request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request, 1024))
+        return await db.write(store.mark_thread_read, p, channel_id, thread_id, body.get("seq"), time.time())
+
+    @app.post("/v1/channels/{channel_id}/read")
+    async def mark_read(channel_id: int, request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request, 1024))
+        return await db.write(store.mark_read, p, channel_id, body.get("seq"), time.time())
+
+    @app.get("/v1/activity")
+    async def get_activity(request: Request, limit: int = Query(50, ge=1, le=200), after: int | None = Query(None, ge=0),
+                           wait: float = Query(0, ge=0, le=LIMITS.max_wait_seconds), channels: str | None = None,
+                           reactions: bool = False):
+        """Everything for you (mentions, replies, DMs, plus `channels` you follow). With `after`, a
+        cursor read, oldest first; add `wait` to long-poll it."""
+        p = await authn(request)
+        parts = [x.strip() for x in channels.split(",") if x.strip()] if channels else []
+        joined = "joined" in parts           # every channel you are a member of
+        try:
+            follow = [int(x) for x in parts if x != "joined"]
+        except ValueError:
+            raise bad_request("channels must be comma-separated channel ids, or `joined`")
+        if joined:
+            follow += await db.read(store.joined_channel_ids, p)
+        if len(follow) > 100:
+            raise bad_request("follow at most 100 channels")
+        if wait > 0 and after is None:
+            raise bad_request("wait needs a cursor: pass `after` (start from the next_cursor of a plain read)")
+        token = board.presence.next_poll()
+        polled_at = time.time()
+        mode = "joined" if joined else ("channels" if follow else "addressed")
+
+        def observe(result):
+            board.presence.polled(p, token, polled_at, after, mode, follow, bool(result["messages"]))
+
+        if wait <= 0:
+            result = await db.read(store.activity, p, limit, after, follow, reactions)
+            observe(result)
+            return result
+        if board.open_polls >= LIMITS.max_open_polls:
+            raise ApiError(429, "too_many_polls", "too many open long-polls", {"Retry-After": "1"})
+        board.open_polls += 1
+        board.counters["polls"] += 1
+        fut = board.notifier.register(ANY_CHANNEL)
+        try:
+            result = await db.read(store.activity, p, limit, after, follow)
+            observe(result)
+            if result["messages"] or board.shutting_down:
+                return result
+            deadline = time.monotonic() + wait
+            while True:   # any post wakes us; keep waiting until one is actually for this caller
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    break
+                done, _ = await asyncio.wait({fut}, timeout=left)
+                if done and not board.shutting_down:
+                    # let a burst of posts land, then answer them with one query instead of one per post
+                    await asyncio.sleep(min(LIMITS.poll_coalesce_seconds * (0.75 + random.random() / 2),
+                                            max(0.0, deadline - time.monotonic())))
+                if await request.is_disconnected():
+                    return result
+                board.notifier.unregister(ANY_CHANNEL, fut)
+                fut = board.notifier.register(ANY_CHANNEL)
+                p = await authn(request, observe=False)
+                result = await db.read(store.activity, p, limit, after, follow, shed=False)
+                board.presence.observed(p, token, bool(result["messages"]), time.time())
+                if result["messages"] or board.shutting_down:
+                    return result
+            return result
+        finally:
+            board.notifier.unregister(ANY_CHANNEL, fut)
+            board.open_polls -= 1
+
+    @app.get("/v1/search")
+    async def search(request: Request, q: str = "", channel: int | None = None, sender: int | None = None,
+                     after: str | None = None, before: str | None = None, sort: str = "newest",
+                     limit: int = Query(20, ge=1, le=100), offset: int = Query(0, ge=0, le=10_000)):
+        """Full-text search over messages you can read, plus matching channel and people names.
+        `q` takes words, "phrases" and filters: from:@name in:#channel after:/before:/on:DATE has:file ..."""
+        p = await authn(request)
+        if len(q) > 500:
+            raise bad_request("q is at most 500 characters")
+        return await db.read(lambda conn: store.search(conn, p, q, channel_id=channel, sender_id=sender, after=after,
+                                                       before=before, sort=sort, limit=limit, offset=offset,
+                                                       now=time.time()))
+
+    @app.get("/v1/analytics")
+    async def get_analytics(request: Request, days: int = Query(7, ge=1, le=365),
+                            start: float | None = Query(None, alias="from"),
+                            end: float | None = Query(None, alias="to"),
+                            top_k: int = Query(10, ge=1, le=100)):
+        p = await authn(request)
+        result = await db.read(store.analytics, p, time.time(), days, start, end, top_k,
+                               board.presence.pending_history())
+        result["listening"]["now"] = board.presence.listening_now(time.time())
+        result["health"] = health_summary()
+        return result
+
+    def _origin(request: Request) -> str:
+        proto = request.headers.get("x-forwarded-proto") or request.url.scheme
+        host = request.headers.get("x-forwarded-host") or request.headers.get("host") or request.url.netloc
+        return f"{proto}://{host}{request.scope.get('root_path', '')}"
+
+    @app.get("/agents", include_in_schema=False)
+    async def agents_guide(request: Request):
+        return PlainTextResponse(guide.render(_origin(request), public=True), media_type="text/markdown; charset=utf-8")
+
+    @app.get("/v1/guide")
+    async def get_guide(request: Request):
+        await authn(request)
+        settings = await db.read(store.get_settings)
+        return PlainTextResponse(guide.render(_origin(request), settings["guidelines"], docs=settings["channel_docs"]),
+                                 media_type="text/markdown; charset=utf-8")
+
+    @app.get("/v1/channels/{channel_id}/members")
+    async def list_members(channel_id: int, request: Request):
+        p = await authn(request)
+        return {"members": await with_presence(p, await db.read(store.list_members, p, channel_id))}
+
+    @app.post("/v1/channels/{channel_id}/members")
+    async def add_member(channel_id: int, request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        members = await db.write(store.add_member, p, channel_id, body.get("principal_id"), time.time())
+        return {"members": await with_presence(p, members)}
+
+    @app.delete("/v1/channels/{channel_id}/members/{principal_id}")
+    async def remove_member(channel_id: int, principal_id: int, request: Request):
+        p = await authn(request)
+        result = await db.write(store.remove_member, p, channel_id, principal_id, time.time())
+        return result if isinstance(result, dict) else {"members": await with_presence(p, result)}
+
+    @app.post("/v1/dms")
+    async def open_dm(request: Request):
+        p = await authn(request)
+        body = body_dict(await _json_body(request))
+        channel, created = await db.write(store.open_dm, p, body.get("with"), time.time())
+        return JSONResponse(channel, status_code=201 if created else 200)
+
+    # --------------------------------------------------------- messages
+
+    @app.post("/v1/channels/{channel_id}/messages")
+    async def post_message(channel_id: int, request: Request):
+        p = await authn(request)
+        request_id = request.headers.get("idempotency-key")
+        if not request_id or not store.CLIENT_ID.match(request_id):
+            raise bad_request("Idempotency-Key header is required and must match " + store.CLIENT_ID.pattern)
+        payload = await _json_body(request, LIMITS.max_body_bytes * 2 + 64 * 1024)
+        normalized, digest = store.normalize_payload(channel_id, payload)
+        message, created = await db.write(
+            store.post_message, p, channel_id, request_id, normalized, digest, time.time())
+        if created:
+            board.counters["posts"] += 1
+            board.notifier.notify(channel_id)
+            board.notifier.notify(ANY_CHANNEL)
+            return JSONResponse(message, status_code=201)
+        board.counters["posts_replayed"] += 1
+        return JSONResponse(message, status_code=200, headers={"Idempotent-Replayed": "true"})
+
+    @app.patch("/v1/channels/{channel_id}/messages/{message_id}")
+    async def edit_message(channel_id: int, message_id: int, request: Request):
+        p = await authn(request)
+        payload = await _json_body(request, LIMITS.max_body_bytes * 2 + 1024)
+        message, changed = await db.write(store.edit_message, p, channel_id, message_id, payload, time.time())
+        if changed:
+            board.counters["edits"] += 1
+            board.notifier.notify(channel_id)
+        return message
+
+    @app.put("/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}")
+    async def add_reaction(channel_id: int, message_id: int, emoji: str, request: Request):
+        p = await authn(request)
+        message, changed = await db.write(store.react, p, channel_id, message_id, unquote(emoji), True, time.time())
+        if changed:
+            board.notifier.notify(channel_id)
+        return message
+
+    @app.delete("/v1/channels/{channel_id}/messages/{message_id}/reactions/{emoji}")
+    async def remove_reaction(channel_id: int, message_id: int, emoji: str, request: Request):
+        p = await authn(request)
+        message, changed = await db.write(store.react, p, channel_id, message_id, unquote(emoji), False, time.time())
+        if changed:
+            board.notifier.notify(channel_id)
+        return message
+
+    @app.delete("/v1/channels/{channel_id}/messages/{message_id}")
+    async def delete_message(channel_id: int, message_id: int, request: Request):
+        p = await authn(request)
+        result = await db.write(store.delete_message, p, channel_id, message_id, time.time())
+        for key in result.pop("storage_keys"):
+            try:
+                board.blobs.path_for(key).unlink()
+            except FileNotFoundError:
+                pass
+        board.notifier.notify(channel_id)
+        return result
+
+    @app.get("/v1/channels/{channel_id}/messages/{message_id}/revisions")
+    async def message_revisions(channel_id: int, message_id: int, request: Request):
+        p = await authn(request)
+        return await db.read(store.message_revisions, p, channel_id, message_id)
+
+    @app.get("/v1/channels/{channel_id}/messages")
+    async def read_messages(
+        channel_id: int,
+        request: Request,
+        after: int = Query(0, ge=0),
+        limit: int = Query(LIMITS.default_page_size, ge=1, le=LIMITS.max_page_size),
+        wait: float = Query(0, ge=0, le=LIMITS.max_wait_seconds),
+        before: int | None = Query(None, ge=1),
+        top_level: bool = False,
+        thread: int | None = Query(None, ge=1),
+        edits_after: int | None = Query(None, ge=0),
+    ):
+        p = await authn(request)
+        if before is not None or top_level or thread is not None:
+            if wait > 0 or edits_after is not None:
+                raise bad_request("wait and edits_after only work with plain `after` reads")
+            return await db.read(store.read_messages, p, channel_id, after, limit, before, top_level, thread)
+
+        async def page(p):
+            result = await db.read(store.read_messages, p, channel_id, after, limit)
+            if edits_after is not None:   # also hand back messages edited since this edit cursor
+                result.update(await db.read(store.read_edits, p, channel_id, edits_after, limit))
+            return result
+
+        if wait <= 0:
+            return await page(p)
+        if board.open_polls >= LIMITS.max_open_polls:
+            raise ApiError(429, "too_many_polls", "too many open long-polls", {"Retry-After": "1"})
+        board.open_polls += 1
+        board.counters["polls"] += 1
+        # Register before checking history so a commit between the query and
+        # the wait cannot be missed.
+        fut = board.notifier.register(channel_id)
+        try:
+            result = await page(p)
+            if result["messages"] or result.get("edits") or board.shutting_down:
+                return result
+            await asyncio.wait({fut}, timeout=wait)
+            # Re-authenticate and re-authorize: the token may have been revoked
+            # or the grant removed while this request was held.
+            p = await authn(request)
+            return await page(p)
+        finally:
+            board.notifier.unregister(channel_id, fut)
+            board.open_polls -= 1
+
+    # ------------------------------------------------- profiles, invites
+
+    @app.get("/v1/principals/{principal_id}/profile")
+    async def get_profile(principal_id: int, request: Request):
+        p = await authn(request)
+        result = await db.read(store.profile, p, principal_id, time.time())
+        result = (await with_presence(p, [result]))[0]
+        result["agents"] = await with_presence(p, result["agents"])
+        return result
+
+    @app.put("/v1/principals/{principal_id}/avatar")
+    async def put_avatar(principal_id: int, request: Request):
+        p = await authn(request)
+        data = bytearray()
+        async for chunk in request.stream():
+            data += chunk
+            if len(data) > LIMITS.max_avatar_bytes:
+                raise ApiError(413, "too_large", f"pictures are limited to {LIMITS.max_avatar_bytes // 1024} KB")
+        return await db.write(store.set_avatar, p, principal_id, bytes(data), time.time())
+
+    @app.delete("/v1/principals/{principal_id}/avatar")
+    async def delete_avatar(principal_id: int, request: Request):
+        p = await authn(request)
+        return await db.write(store.delete_avatar, p, principal_id, time.time())
+
+    @app.put("/v1/principals/{principal_id}/pattern")
+    async def put_pattern(principal_id: int, request: Request):
+        p = await authn(request)
+        body = await _json_body(request, 1024)
+        seed = body.get("seed") if isinstance(body, dict) else None
+        return await db.write(store.set_pattern, p, principal_id, seed, time.time())
+
+    @app.get("/v1/principals/{principal_id}/avatar")
+    async def get_avatar(principal_id: int, request: Request):
+        await authn(request)  # any member of the board may see pictures
+        ctype, data, digest = await db.read(store.get_avatar, principal_id)
+        return Response(data, media_type=ctype, headers={
+            "ETag": f'"{digest[:16]}"', "Cache-Control": "private, max-age=86400",
+            "X-Content-Type-Options": "nosniff", "Content-Security-Policy": "default-src 'none'"})
+
+    # ------------------------------------------------------ attachments
+
+    @app.put("/v1/channels/{channel_id}/attachments/{upload_id}")
+    async def upload(channel_id: int, upload_id: str, request: Request):
+        p = await authn(request)
+        declared = request.headers.get("content-length")
+        if declared and declared.isdigit() and int(declared) > LIMITS.max_upload_bytes:
+            raise ApiError(413, "too_large", f"uploads are limited to {LIMITS.max_upload_bytes} bytes")
+        if board.open_uploads >= LIMITS.max_concurrent_uploads:
+            raise ApiError(429, "too_many_uploads", "too many concurrent uploads", {"Retry-After": "1"})
+        # Browsers can only send ASCII headers, so the filename may be percent-encoded.
+        filename = os.path.basename(unquote(request.headers.get("x-filename", "")))[:255] or None
+        if filename and any(ord(ch) < 32 for ch in filename):
+            raise bad_request("invalid filename")
+        content_type = request.headers.get("content-type", "application/octet-stream")[:128]
+        board.open_uploads += 1
+        tmp_path = None
+        try:
+            row = await db.write(store.begin_upload, p, channel_id, upload_id, filename, content_type, time.time())
+            tmp_path, fh = await anyio.to_thread.run_sync(board.blobs.open_temp)
+            hasher, size = new_hasher(), 0
+            try:
+                async for chunk in request.stream():
+                    size += len(chunk)
+                    if size > LIMITS.max_upload_bytes:
+                        raise ApiError(413, "too_large", f"uploads are limited to {LIMITS.max_upload_bytes} bytes")
+                    hasher.update(chunk)
+                    await anyio.to_thread.run_sync(fh.write, chunk)
+                await anyio.to_thread.run_sync(board.blobs.finish_temp, fh)
+            finally:
+                if not fh.closed:
+                    fh.close()
+            digest = hasher.hexdigest()
+            expected = request.headers.get("x-checksum-sha256")
+            if expected and expected.lower() != digest:
+                raise bad_request("X-Checksum-Sha256 does not match the uploaded content")
+            async with board.commit_lock:
+                current = await db.read(store.attachment_state, row["id"])
+                if current["state"] == "ready":
+                    result = await db.write(store.finish_upload, row["id"], size, digest)
+                    return JSONResponse(result, status_code=200)
+                await anyio.to_thread.run_sync(board.blobs.commit, tmp_path, row["storage_key"])
+                tmp_path = None
+                result = await db.write(store.finish_upload, row["id"], size, digest)
+                return JSONResponse(result, status_code=201)
+        finally:
+            board.open_uploads -= 1
+            if tmp_path is not None:
+                board.blobs.discard(tmp_path)
+
+    @app.get("/v1/attachments/{att_id}/info")
+    async def attachment_info(att_id: str, request: Request):
+        p = await authn(request)
+        info = await db.read(store.get_attachment, p, att_id)
+        info.pop("storage_key")
+        return info
+
+    @app.get("/v1/attachments/{att_id}")
+    async def download(att_id: str, request: Request):
+        p = await authn(request)
+        info = await db.read(store.get_attachment, p, att_id)
+        return FileResponse(
+            board.blobs.path_for(info["storage_key"]),
+            media_type="application/octet-stream",
+            filename=info["filename"] or att_id,
+            headers={
+                "X-Checksum-Sha256": info["sha256"],
+                "X-Content-Type-Options": "nosniff",
+                "X-Upload-Content-Type": info["content_type"] or "application/octet-stream",
+            },
+        )
+
+    # ------------------------------------------------------------------ storage folders
+
+    def _cache_put(src: Path, sha: str) -> Path:
+        dest = board.storage_cache / sha
+        os.replace(src, dest)
+        files = sorted(board.storage_cache.iterdir(), key=lambda f: f.stat().st_atime)
+        total = sum(f.stat().st_size for f in files)
+        for f in files:                                   # keep the cache under its size, oldest first
+            if total <= LIMITS.storage_cache_bytes or f == dest:
+                continue
+            total -= f.stat().st_size
+            f.unlink(missing_ok=True)
+        return dest
+
+    @app.put("/v1/storage/{handle}/{path:path}")
+    async def storage_put(handle: str, path: str, request: Request):
+        p = await authn(request)
+        owner = await db.read(store.storage_owner, p, handle, True)
+        path = store.storage_path(path)
+        declared = request.headers.get("content-length")
+        if declared and declared.isdigit():
+            await db.read(store.storage_check_quota, owner["id"], path, int(declared))
+        content_type = (request.headers.get("content-type") or mimetypes.guess_type(path)[0]
+                        or "application/octet-stream")[:128]
+        tmp_path, fh = await anyio.to_thread.run_sync(board.blobs.open_temp)
+        try:
+            hasher, size = new_hasher(), 0
+            try:
+                max_file = (await db.read(store.storage_limits))[0]
+                async for chunk in request.stream():
+                    size += len(chunk)
+                    if size > max_file:
+                        raise ApiError(413, "too_large", f"files are limited to {store._mb(max_file)} on this board")
+                    hasher.update(chunk)
+                    await anyio.to_thread.run_sync(fh.write, chunk)
+                await anyio.to_thread.run_sync(board.blobs.finish_temp, fh)
+            finally:
+                if not fh.closed:
+                    fh.close()
+            digest = hasher.hexdigest()
+            expected = request.headers.get("x-checksum-sha256")
+            if expected and expected.lower() != digest:
+                raise bad_request("X-Checksum-Sha256 does not match the uploaded content")
+            await db.read(store.storage_check_quota, owner["id"], path, size)
+            key = store.storage_key(owner["id"], path)
+            await anyio.to_thread.run_sync(lambda: board.storage.put([(tmp_path, key)]))   # in the bucket before it is listed
+            await anyio.to_thread.run_sync(_cache_put, tmp_path, digest)
+            tmp_path = None
+            result = await db.write(store.storage_record, p, owner["id"], path, size, digest, content_type, time.time())
+            return JSONResponse(result, status_code=201)
+        finally:
+            if tmp_path is not None:
+                board.blobs.discard(tmp_path)
+
+    @app.get("/v1/storage/{handle}")
+    async def storage_root(handle: str, request: Request, prefix: str = ""):
+        p = await authn(request)
+        return await db.read(store.storage_list, p, handle, prefix)
+
+    @app.get("/v1/storage/{handle}/{path:path}")
+    async def storage_get(handle: str, path: str, request: Request, info: bool = False):
+        p = await authn(request)
+        if path.endswith("/"):                            # a folder: list it
+            return await db.read(store.storage_list, p, handle, path)
+        meta, key = await db.read(store.storage_lookup, p, handle, path)
+        if info:
+            return meta
+        cached = board.storage_cache / meta["sha256"]
+        if not cached.exists():
+            tmp = board.storage_cache / f".{meta['sha256']}.{os.getpid()}.part"
+            ok = await anyio.to_thread.run_sync(board.storage.get, key, tmp)
+            if not ok:
+                raise ApiError(503, "storage_unavailable", "the file is listed but could not be fetched from storage; try again")
+            os.replace(tmp, cached)
+        # always a download: never let stored HTML or SVG run on the board's own origin
+        return FileResponse(cached, media_type="application/octet-stream", filename=os.path.basename(meta["path"]),
+                            headers={"X-Checksum-Sha256": meta["sha256"], "X-Content-Type-Options": "nosniff",
+                                     "X-Upload-Content-Type": meta["content_type"] or "application/octet-stream",
+                                     "Content-Security-Policy": "sandbox", "Cache-Control": "private, no-cache"})
+
+    @app.delete("/v1/storage/{handle}/{path:path}")
+    async def storage_delete(handle: str, path: str, request: Request):
+        p = await authn(request)
+        out = await db.write(store.storage_remove, p, handle, path, time.time())
+        keys = out.pop("keys")
+        await anyio.to_thread.run_sync(lambda: board.storage.delete(keys))
+        return out
+
+    if dashboard:
+        page = Path(__file__).with_name("dashboard.html")
+
+        @app.get("/", include_in_schema=False)
+        async def dashboard_page():
+            return FileResponse(page, media_type="text/html",
+                                headers={"Cache-Control": "no-cache", "X-Content-Type-Options": "nosniff"})
+
+    return app