@jeffober/thatch 0.1.40 → 0.1.42

package/src/chat.ts

@@ -0,0 +1,1210 @@
+import type { Database } from "bun:sqlite";
+import { CHAT_NAME_POOL } from "./chat-names";
+
+/**
+ * Cross-session chat: opt-in messaging between live opencode sessions on one
+ * machine, routed through the shared thatch.db.
+ *
+ * The design splits cleanly into two halves. ChatStore is the shared state:
+ * the session directory and the message inbox live in SQLite so any opencode
+ * process on the machine can read and write them. ChatPoller is the local
+ * delivery: each process polls the inbox for messages addressed to sessions
+ * it hosts and wake-prompts them through its own SDK client. A sender never
+ * prompts a session in another process - only the recipient's host delivers.
+ * This crosses process boundaries while preserving the watcher rationale's core
+ * property: no process ever prompts a session it does not host, so there is
+ * exactly one possible deliverer per message and no cross-process double
+ * delivery. Within a host process, delivery is at-least-once: a crash between
+ * the wake prompt and its delivered_at stamp re-nudges the same mail after
+ * restart, which is the safe direction for prompts that only point at the
+ * inbox.
+ *
+ * Liveness is heartbeat-based. A crashed process fires no session.deleted
+ * event, so the only reliable offline signal is a stale last_seen value: each
+ * host process refreshes last_seen for its registered sessions on every poll
+ * cycle, and chat_list marks anything older than the staleness threshold as
+ * stale instead of hiding it.
+ *
+ * Loop control has a soft and a hard brake. The prompt guidance tells agents
+ * not to auto-reply reflexively (two polite agents acknowledging each other
+ * forever is an infinite wake cycle); the poller's per-recipient nudge cap
+ * stops it mechanically regardless of what the models decide to do.
+ */
+
+/** ISO-8601 UTC timestamp with second resolution, matching the house
+ *  strftime('%Y-%m-%dT%H:%M:%SZ','now') default so string comparison between
+ *  SQLite-generated and JS-generated timestamps stays consistent. */
+export function nowIso(): string {
+  return isoMinutesAgo(0);
+}
+
+/** An ISO timestamp `minutes` in the past, in the same second-resolution
+ *  format. The poller passes this shape as the re-nudge cutoff; tests use
+ *  it for the same purpose, so the format expression lives in exactly one
+ *  place. */
+export function isoMinutesAgo(minutes: number): string {
+  return new Date(Date.now() - minutes * 60_000).toISOString().slice(0, 19) + "Z";
+}
+
+export interface ChatSessionRow {
+  session_id: string;
+  name: string;
+  topic: string | null;
+  project: string | null;
+  /** Which harness hosts this session: "opencode" (poller-driven) or "mcp"
+   *  (turn-driven). Determines how staleness is interpreted and whether
+   *  wake delivery is possible. */
+  host_kind: ChatHostKind;
+  registered_at: string;
+  last_seen: string;
+}
+
+/** One message selected for wake-up delivery, with the sender's display name
+ *  resolved for the nudge text. */
+export interface ChatNotificationRow {
+  id: number;
+  to_session: string;
+  from_session: string;
+  from_name: string | null;
+}
+
+/** A message as returned to the reading agent. */
+export interface ChatInboxItem {
+  id: number;
+  from_session: string;
+  from_name: string | null;
+  body: string;
+  created_at: string;
+}
+
+/**
+ * Derives the synthetic session ID for an MCP-host chat registration: a
+ * pure function of the host's own stable session identifier (Claude Code
+ * and Cursor pass one in their hook payloads), so identity survives the
+ * ephemeral conversations those hosts run. The underscore keeps the ID
+ * outside NAME_CHARSET, preserving the name-cannot-shadow-ID invariant
+ * that find() relies on.
+ */
+export function mcpSessionID(hostSessionID: string): string {
+  const hash = Bun.SHA256.hash(hostSessionID.toLowerCase(), "hex").slice(0, 12);
+  return `mcp_${hash}`;
+}
+
+/** Which kind of harness hosts a chat session: opencode rows are
+ *  poller-driven (liveness = process alive), mcp rows are turn-driven
+ *  (liveness = a turn ran recently; mail is read at the next prompt). */
+export type ChatHostKind = "opencode" | "mcp";
+
+// Display names appear inside wake prompts and chat_list output, so they are
+// capped tight. Bodies are capped so a runaway sender cannot turn a nudge
+// into a context bomb; the reader fetches full content via chat_read anyway.
+const MAX_BODY_LEN = 10_000;
+
+// Assigned names are lowercase slugs with a numeric counter suffix
+// ("fix-auth-bug-00001"), which satisfies NAME_CHARSET. The charset stays
+// exported for the pool conformance test. Slugs never contain underscores,
+// so the name-cannot-shadow-an-ID invariant in find() still holds.
+export const NAME_CHARSET = /^[\p{L}\p{N} '.\-]+$/u;
+
+// Topics are free text (unlike names) but must stay one line for the
+// chat_list roster, so whitespace runs collapse and the value is capped.
+const MAX_TOPIC_LEN = 80;
+
+// Auto-registered sessions whose host has not heartbeat-ed them for this
+// many days are pruned from the directory. Counters never decrement, so a
+// pruned session's name is never reissued - pruning cannot create identity
+// confusion, only roster silence.
+export const CHAT_AUTO_TTL_DAYS = 7;
+
+/**
+ * Slugifies a session title into a name base: lowercase, letter/number runs
+ * joined by single hyphens, capped at 32 characters (leaving room for the
+ * 6-character counter suffix). Returns null for titles with no usable
+ * characters.
+ *
+ * Deliberately NOT the same as ThatchDB.slugify (src/db.ts): chat names
+ * must never contain underscores (find() resolves name-first, and opencode
+ * session IDs contain underscores - a legal display name could shadow an
+ * ID), so non-alphanumeric runs all become hyphens and empty input returns
+ * null rather than a hash fallback.
+ */
+export function slugifyTitle(title: string): string | null {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32)
+    .replace(/-+$/g, "");
+  return slug || null;
+}
+
+/**
+ * Whether a session title is opencode's pre-autotitle placeholder
+ * ("New session - <timestamp>" / "Child session - <timestamp>"). These must
+ * not become names or topics: they carry no information about the work, and
+ * the auto-titler usually replaces them within the first turn or two.
+ */
+export function isDefaultSessionTitle(title: string): boolean {
+  return /^New session - /.test(title) || /^Child session - /.test(title);
+}
+
+// Timing defaults, shared by the poller and the chat_list staleness display
+// so both agree on what "stale" means.
+export const CHAT_POLL_INTERVAL_MS = 30_000;
+export const CHAT_STALE_MINUTES = 10;
+export const CHAT_RENUDGE_MINUTES = 15;
+export const CHAT_MAX_NUDGES_PER_HOUR = 6;
+
+/**
+ * SQLite CRUD for the chat tables. Constructed by ThatchDB with the shared
+ * Database handle; the tables are created by ThatchDB's schema init.
+ */
+export class ChatStore {
+  #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  /**
+   * Joins the directory, or refreshes an existing registration. Names are
+   * assigned by the system, never claimed: a new session gets
+   * "<slug>-<counter>" (e.g. "fix-auth-bug-00001"), where the slug comes
+   * from the session title (or a pool-draw slug when there is none) and the
+   * per-base counter only ever increments - so a name is minted exactly
+   * once, machine-wide, and pruning an old session can never reissue its
+   * name to someone else. Idempotent for an already-registered session: it
+   * keeps its name and just refreshes liveness.
+   *
+   * `nameBase` is the slugified title for a new registration (null draws a
+   * pool slug instead). `topic` is the live title for auto-registrations;
+   * null leaves the topic unset. Every row minted here is marked auto=1 -
+   * rows with auto=0 exist only as legacy data from the claimed-names era.
+   */
+  register(
+    sessionID: string,
+    project: string | null,
+    topic: string | null,
+    kind: ChatHostKind,
+    nameBase: string | null = null,
+  ): { ok: true; name: string; topic: string | null } | { ok: false; error: string } {
+    const existing = this.#find(sessionID);
+    if (existing) {
+      this.#touch(sessionID);
+      // An explicit registration clears the leave tombstone for its own
+      // session ID: "I want back in" is the opposite of "I left". This is
+      // also what closes the in-flight race - an auto-register IIFE whose
+      // session was deleted mid-await finds the tombstone here and stops.
+      // The caller distinction is by ID: the idle path re-checks with the
+      // session's own ID, so a tombstone set by chat_unregister or
+      // session.deleted suppresses exactly that session.
+      const gate = this.#tombstoneGate(sessionID, kind);
+      if (gate) return gate;
+      return { ok: true, name: existing.name, topic: existing.topic };
+    }
+    const gate = this.#tombstoneGate(sessionID, kind);
+    if (gate) return gate;
+    const cleanTopic = this.#cleanTopic(topic);
+    const base =
+      nameBase ??
+      slugifyTitle(CHAT_NAME_POOL[Math.floor(Math.random() * CHAT_NAME_POOL.length)]) ??
+      "session";
+    // The counter draw is atomic, but the name INSERT can still lose to a
+    // legacy row that already holds that exact name (custom claims from
+    // before names were assigned). Each retry bumps the counter, so the
+    // loop always makes forward progress and terminates.
+    for (let attempt = 0; attempt < 10; attempt++) {
+      const next = this.#bumpCounter(base);
+      const name = `${base}-${String(next).padStart(5, "0")}`;
+      const claimed = this.#insertSession(sessionID, name, project, cleanTopic, kind);
+      if (claimed.ok) return { ok: true, name, topic: cleanTopic };
+      if (claimed.reason === "already-registered") {
+        // A concurrent registration of the same session ID won the race;
+        // report its row rather than erroring.
+        const winner = this.#find(sessionID);
+        if (winner) return { ok: true, name: winner.name, topic: winner.topic };
+      }
+    }
+    return { ok: false, error: "Could not assign a unique name after several attempts." };
+  }
+
+  /** Leaves the directory. Messages already sent to or from the session are
+   *  kept as history; departed senders show as unknown names to readers. */
+  unregister(sessionID: string): boolean {
+    const existing = this.#find(sessionID);
+    if (!existing) return false;
+    this.#db.transaction(() => {
+      // Tombstone before delete: auto-registration keys on the row being
+      // absent, so without a marker the next idle event would silently
+      // re-register the session under a brand-new name and the user's
+      // "leave the directory" would last until the turn ended. The
+      // tombstone survives the delete and suppresses auto-registration
+      // until the session explicitly rejoins via chat_register (which
+      // clears it). Both leave paths come through here - chat_unregister
+      // AND session.deleted (a deleted TUI session is an exit too; without
+      // the tombstone an in-flight auto-register could resurrect it).
+      this.#db.run("INSERT OR REPLACE INTO chat_leave_tombstones (session_id, left_at) VALUES (?, ?)", [
+        sessionID,
+        nowIso(),
+      ]);
+      this.#db.run("DELETE FROM chat_sessions WHERE session_id = ?", [sessionID]);
+    })();
+    return true;
+  }
+
+  /** Whether the session explicitly left the directory and has not
+   *  rejoined. Auto-registration consults this before inserting; manual
+   *  registration (chat_register) clears the tombstone on join. */
+  hasLeaveTombstone(sessionID: string): boolean {
+    const row = this.#db
+      .query("SELECT 1 FROM chat_leave_tombstones WHERE session_id = ?")
+      .get(sessionID);
+    return row !== null && row !== undefined;
+  }
+
+  /** Clears the leave tombstone (chat_register rejoin path). */
+  clearLeaveTombstone(sessionID: string): void {
+    this.#db.run("DELETE FROM chat_leave_tombstones WHERE session_id = ?", [sessionID]);
+  }
+
+  /**
+   * Whether the leave tombstone for `sessionID` has been superseded: a
+   * newer registration exists in the same project (registered after the
+   * leave). The hook uses this to stop announcing a stale leave once the
+   * model has rejoined under a fresh identity - the tombstoned identity
+   * and the fresh one cannot be linked, but a newer join in the same
+   * project is evidence the conversation moved on.
+   */
+  leaveSuperseded(sessionID: string, project: string | null): boolean {
+    if (!project) return false;
+    const row = this.#db
+      .query(
+        `SELECT 1 FROM chat_leave_tombstones t
+         JOIN chat_sessions cs ON cs.project = ? AND cs.registered_at > t.left_at
+         WHERE t.session_id = ?
+         LIMIT 1`,
+      )
+      .get(project, sessionID);
+    return row !== null && row !== undefined;
+  }
+
+  /**
+   * Refreshes an auto-registered session's topic from its current title.
+   * opencode's auto-titler usually lands a real title within the first turn
+   * or two, so this converges the roster annotation to the actual work.
+   * Manual (legacy) rows are never touched - the topic column on those is
+   * user/model-set, not title-derived.
+   */
+  refreshAutoTopic(sessionID: string, title: string): void {
+    const clean = this.#cleanTopic(title);
+    if (!clean) return;
+    this.#db.run("UPDATE chat_sessions SET topic = ? WHERE session_id = ? AND auto = 1 AND topic IS NOT ?", [
+      clean,
+      sessionID,
+      clean,
+    ]);
+  }
+
+  /**
+   * Removes auto-registered directory rows whose host has not heartbeat-ed
+   * them since `cutoff` (ISO), plus unread mail addressed to sessions no
+   * longer in the directory. The mail delete is bounded by the same
+   * cutoff: unread mail newer than the cutoff survives this sweep and is
+   * removed by a later one once it ages past the moving cutoff - the
+   * cutoff is a conservative bound, not an exact age match. Delivered/read
+   * history and mail from pruned senders to live recipients are kept -
+   * departed senders already render as unknown names. Counters are NOT
+   * touched: never decrementing is what makes reissued names impossible.
+   * Returns the number of directory rows pruned.
+   */
+  pruneStaleAuto(cutoff: string): number {
+    const result = this.#db.run("DELETE FROM chat_sessions WHERE auto = 1 AND last_seen < ?", [cutoff]);
+    this.#db.run(
+      "DELETE FROM chat_messages WHERE read_at IS NULL AND to_session NOT IN (SELECT session_id FROM chat_sessions) AND created_at < ?",
+      [cutoff],
+    );
+    // Tombstones age out too: they are leave markers, not identity records.
+    // A resumed opencode session whose tombstone expired simply
+    // auto-registers under a fresh name - the expiry window is the
+    // grace period for that. Growth is bounded (one row per distinct
+    // session), but the sweep keeps the table from growing monotonically
+    // forever.
+    this.#db.run("DELETE FROM chat_leave_tombstones WHERE left_at < ?", [cutoff]);
+    return result.changes;
+  }
+
+  list(): ChatSessionRow[] {
+    return (this.#db
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions ORDER BY name")
+      .all() as any[]).map(rowFromSession);
+  }
+
+  /** Resolves a recipient by display name (case-insensitive) or session ID.
+   *  Name-first is safe only because opencode session IDs contain
+   *  underscores and NAME_CHARSET excludes them, so no legal display name
+   *  can shadow an ID; if either format ever changes, resolve IDs first. */
+  find(nameOrID: string): ChatSessionRow | null {
+    return this.#findByName(nameOrID) ?? this.#find(nameOrID);
+  }
+
+  /**
+   * Posts a message. Both endpoints must be registered; a session cannot
+   * message itself (nothing is coordinated: the message would sit unread
+   * until the sender drains its own inbox, and the wake prompt would be the
+   * sender nudging itself). Returns the resolved recipient so callers never
+   * need a second lookup - a re-lookup could race a concurrent unregister
+   * and fail after the message already landed.
+   */
+  send(
+    fromSession: string,
+    toNameOrID: string,
+    body: string,
+  ): { ok: true; recipient: { session_id: string; name: string } } | { ok: false; error: string } {
+    const trimmed = body.trim();
+    if (!trimmed) return { ok: false, error: "Message body cannot be empty." };
+    if (trimmed.length > MAX_BODY_LEN) {
+      return { ok: false, error: `Message too long (max ${MAX_BODY_LEN} characters).` };
+    }
+    const sender = this.#find(fromSession);
+    if (!sender) return { ok: false, error: "You are not registered - call chat_register first." };
+    const recipient = this.find(toNameOrID);
+    if (!recipient) {
+      return { ok: false, error: `No registered session named "${toNameOrID}". Use chat_list to see who is available.` };
+    }
+    if (recipient.session_id === fromSession) {
+      return { ok: false, error: "You cannot message yourself." };
+    }
+    this.#db.run(
+      "INSERT INTO chat_messages (from_session, to_session, body, created_at, via_broadcast) VALUES (?, ?, ?, ?, 0)",
+      [fromSession, recipient.session_id, trimmed, nowIso()],
+    );
+    return { ok: true, recipient: { session_id: recipient.session_id, name: recipient.name } };
+  }
+
+  /**
+   * Posts a message to every other registered session at once. Stale
+   * sessions are skipped, not messaged - a host process that has stopped
+   * heartbeat-ing will never read the mail, and a broadcast is for reaching
+   * live agents. Each recipient gets its own inbox row, so the existing
+   * wake machinery (grouping, gating, rate cap) treats the broadcast as
+   * ordinary per-recipient mail.
+   */
+  broadcast(
+    fromSession: string,
+    body: string,
+  ): { ok: true; recipients: string[]; skipped: string[] } | { ok: false; error: string } {
+    const trimmed = body.trim();
+    if (!trimmed) return { ok: false, error: "Message body cannot be empty." };
+    if (trimmed.length > MAX_BODY_LEN) {
+      return { ok: false, error: `Message too long (max ${MAX_BODY_LEN} characters).` };
+    }
+    const sender = this.#find(fromSession);
+    if (!sender) return { ok: false, error: "You are not registered - call chat_register first." };
+    const recipients: string[] = [];
+    const skipped: string[] = [];
+    // One transaction: a crash mid-loop rolls the whole fan-out back
+    // instead of leaving a partial broadcast where some recipients got the
+    // message and others silently did not.
+    this.#db.transaction(() => {
+      for (const row of this.list()) {
+        if (row.session_id === fromSession) continue;
+        // Staleness means "host process gone" only for opencode rows; an
+        // mcp row between turns reads its mail at the next prompt, so it
+        // always receives.
+        if (row.host_kind === "opencode" && isStale(row, CHAT_STALE_MINUTES)) {
+          skipped.push(row.name);
+          continue;
+        }
+        this.#db.run(
+          "INSERT INTO chat_messages (from_session, to_session, body, created_at, via_broadcast) VALUES (?, ?, ?, ?, 1)",
+          [fromSession, row.session_id, trimmed, nowIso()],
+        );
+        recipients.push(row.name);
+      }
+    })();
+    return { ok: true, recipients, skipped };
+  }
+
+  /**
+   * Drains the calling session's inbox: returns unread messages oldest-first
+   * and stamps exactly those rows read. The stamp is scoped to the selected
+   * ids, not re-derived - a message arriving from another process between
+   * the SELECT and the UPDATE must stay unread so the poller re-nudges it;
+   * an unscoped stamp would swallow it silently.
+   */
+  read(sessionID: string): ChatInboxItem[] {
+    const rows = this.#db
+      .query(
+        `SELECT m.id, m.from_session, s.name AS from_name, m.body, m.created_at
+         FROM chat_messages m
+         LEFT JOIN chat_sessions s ON s.session_id = m.from_session
+         WHERE m.to_session = ? AND m.read_at IS NULL
+         ORDER BY m.id`,
+      )
+      .all(sessionID) as any[];
+    if (rows.length === 0) return [];
+    const marks = rows.map(() => "?").join(",");
+    this.#db.run(`UPDATE chat_messages SET read_at = ? WHERE id IN (${marks})`, [
+      nowIso(),
+      ...rows.map((r) => r.id),
+    ]);
+    return rows.map((r) => ({
+      id: r.id,
+      from_session: r.from_session,
+      from_name: r.from_name ?? null,
+      body: r.body,
+      created_at: r.created_at,
+    }));
+  }
+
+  /** Unread message count for a session, for chat_list's self row. */
+  unreadCount(sessionID: string): number {
+    const row = this.#db
+      .query("SELECT COUNT(*) AS n FROM chat_messages WHERE to_session = ? AND read_at IS NULL")
+      .get(sessionID) as any;
+    return row.n;
+  }
+
+  /**
+   * The caller's mailbox summary for chat_status: whether a directory row
+   * exists, and pending/total counts. Touches last_seen on use, which is
+   * what keeps an active MCP session's roster row fresh between prompt-time
+   * checks. An unregistered caller gets registered: false - the explicit,
+   * quiet answer that replaces any nudge.
+   */
+  status(sessionID: string): { registered: true; name: string; pending: number; total: number } | { registered: false } {
+    const row = this.#find(sessionID);
+    if (!row) return { registered: false };
+    this.#touch(sessionID);
+    const counts = this.#db
+      .query(
+        `SELECT COUNT(*) AS total, SUM(CASE WHEN read_at IS NULL THEN 1 ELSE 0 END) AS pending
+         FROM chat_messages WHERE to_session = ?`,
+      )
+      .get(sessionID) as any;
+    return {
+      registered: true,
+      name: row.name,
+      pending: counts.pending ?? 0,
+      total: counts.total ?? 0,
+    };
+  }
+
+  /**
+   * Pending-mail summary for the hook channel (flush-tools / reminder):
+   * every registered session in the project with unread mail, with its
+   * display name and unread count. The hook prints this only when
+   * non-empty, and names the addressee - a session that never registered
+   * never sees a chat line at all.
+   */
+  pendingByProject(project: string): Array<{ name: string; pending: number }> {
+    return (
+      this.#db
+        .query(
+          `SELECT cs.name AS name, COUNT(*) AS pending
+           FROM chat_messages m
+           JOIN chat_sessions cs ON cs.session_id = m.to_session
+           WHERE m.read_at IS NULL AND cs.project = ?
+           GROUP BY cs.name
+           ORDER BY cs.name`,
+        )
+        .all(project) as any[]
+    ).map((r) => ({ name: r.name, pending: r.pending }));
+  }
+
+  /** Refreshes last_seen for the given sessions. Sessions that never
+   *  registered are absent from chat_sessions, so the UPDATE is a no-op for
+   *  them - no filtering needed on the caller's side. */
+  heartbeat(sessionIDs: string[]): void {
+    if (sessionIDs.length === 0) return;
+    const marks = sessionIDs.map(() => "?").join(",");
+    this.#db.run(`UPDATE chat_sessions SET last_seen = ? WHERE session_id IN (${marks})`, [
+      nowIso(),
+      ...sessionIDs,
+    ]);
+  }
+
+  /**
+   * The full message feed for `thatch chat tail`: every row with sender and
+   * recipient display names resolved (departed senders degrade to unknown),
+   * oldest first. The CLI diffs consecutive snapshots to emit sent and
+   * read events; the table is machine-scale, so a full scan per poll is
+   * cheap.
+   */
+  messageFeed(): Array<{
+    id: number;
+    from: string | null;
+    to: string | null;
+    fromTopic: string | null;
+    toTopic: string | null;
+    viaBroadcast: boolean;
+    body: string;
+    created_at: string;
+    read_at: string | null;
+  }> {
+    return (
+      this.#db
+        .query(
+          `SELECT m.id, m.from_session, m.to_session, fs.name AS from_name, ts.name AS to_name, fs.topic AS from_topic, ts.topic AS to_topic, m.via_broadcast, m.body, m.created_at, m.read_at
+           FROM chat_messages m
+           LEFT JOIN chat_sessions fs ON fs.session_id = m.from_session
+           LEFT JOIN chat_sessions ts ON ts.session_id = m.to_session
+           ORDER BY m.id`,
+        )
+        .all() as any[]
+    ).map((r) => ({
+      id: r.id,
+      from: renderChatParticipant(r.from_name, r.from_session),
+      to: renderChatParticipant(r.to_name, r.to_session),
+      fromTopic: r.from_topic ?? null,
+      toTopic: r.to_topic ?? null,
+      viaBroadcast: r.via_broadcast === 1,
+      body: r.body,
+      created_at: r.created_at,
+      read_at: r.read_at ?? null,
+    }));
+  }
+
+  /**
+   * Messages that need a wake prompt for the given sessions: unread and
+   * either never delivered, or delivered so long ago that a re-nudge is due.
+   * Only registered recipients are selected - unregistering must stop wake
+   * prompts for kept-but-unread mail, which is exactly what the
+   * chat_unregister tool promises. The cutoff is passed by the poller (its
+   * renudge window, as an ISO timestamp); delivered_at comparison is string
+   * comparison, which works because every timestamp in these tables uses
+   * the same second-resolution format.
+   */
+  pendingNotifications(sessionIDs: string[], renudgeCutoff: string): ChatNotificationRow[] {
+    if (sessionIDs.length === 0) return [];
+    const marks = sessionIDs.map(() => "?").join(",");
+    return (
+      this.#db
+        .query(
+          `SELECT m.id, m.to_session, m.from_session, s.name AS from_name
+           FROM chat_messages m
+           LEFT JOIN chat_sessions s ON s.session_id = m.from_session
+           WHERE m.read_at IS NULL
+             AND m.to_session IN (${marks})
+             AND (m.delivered_at IS NULL OR m.delivered_at <= ?)
+             AND EXISTS (SELECT 1 FROM chat_sessions cs WHERE cs.session_id = m.to_session)
+           ORDER BY m.id`,
+        )
+        .all(...sessionIDs, renudgeCutoff) as any[]
+    ).map((r) => ({
+      id: r.id,
+      to_session: r.to_session,
+      from_session: r.from_session,
+      from_name: r.from_name ?? null,
+    }));
+  }
+
+  /** Stamps delivered_at on the given messages. Called after a wake prompt
+   *  was accepted; re-stamping on later nudges resets the re-nudge timer. */
+  markDelivered(ids: number[]): void {
+    if (ids.length === 0) return;
+    const marks = ids.map(() => "?").join(",");
+    this.#db.run(`UPDATE chat_messages SET delivered_at = ? WHERE id IN (${marks})`, [nowIso(), ...ids]);
+  }
+
+  #find(sessionID: string): ChatSessionRow | null {
+    const row = this.#db
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions WHERE session_id = ?")
+      .get(sessionID) as any;
+    return row ? rowFromSession(row) : null;
+  }
+
+  #findByName(name: string): ChatSessionRow | null {
+    const row = this.#db
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions WHERE name = ? COLLATE NOCASE")
+      .get(name) as any;
+    return row ? rowFromSession(row) : null;
+  }
+
+  #touch(sessionID: string): void {
+    this.#db.run("UPDATE chat_sessions SET last_seen = ? WHERE session_id = ?", [nowIso(), sessionID]);
+  }
+
+  /** Collapses whitespace runs (topics must stay one roster line) and caps
+   *  the length. The null/empty distinction is load-bearing: null means
+   *  "omit on re-register, keep the existing topic", while empty or
+   *  whitespace-only means "clear it" - so this never turns one into the
+   *  other. Oversized topics are capped, never an error: a topic is
+   *  advisory. */
+  #cleanTopic(topic: string | null): string | null {
+    if (topic === null) return null;
+    return topic.replace(/\s+/g, " ").trim().slice(0, MAX_TOPIC_LEN);
+  }
+
+  /**
+   * The leave-tombstone gate, applied on both register() paths (existing
+   * row and fresh mint). Policy: an opencode registration is the plugin's
+   * auto-registration, so a tombstone suppresses it outright - the in-
+   * flight IIFE whose session was deleted mid-await lands here and stops
+   * instead of resurrecting a dead session as a roster corpse. An MCP
+   * registration over the hook-anchored ID is a genuine rejoin (the
+   * derived session ID matches the tombstone), so the gate clears it and
+   * lets the registration proceed. Defense in depth: no current
+   * production caller reaches the MCP branch with a tombstoned ID (the
+   * tool's rejoin clears at its own layer first); UC-101 pins the DB
+   * contract. Returns the failure result when the gate refuses, or null
+   * to proceed.
+   */
+  #tombstoneGate(sessionID: string, kind: ChatHostKind): { ok: false; error: string } | null {
+    if (!this.hasLeaveTombstone(sessionID)) return null;
+    if (kind === "opencode") {
+      return { ok: false, error: "leave tombstone active" };
+    }
+    this.clearLeaveTombstone(sessionID);
+    return null;
+  }
+
+  /**
+   * Atomically draws the next counter value for a name base: the INSERT
+   * ... ON CONFLICT upsert seeds the counter at 2 on first draw and
+   * increments it on every later draw, returning the drawn value in one
+   * statement - two processes racing the same base can never draw the same
+   * number. Counters only ever increment (prune included), which is what
+   * makes assigned names immortal.
+   */
+  #bumpCounter(base: string): number {
+    // The insert seeds the counter at 2 (1 is being handed out now) so the
+    // stored value always reads as the next unassigned number; the RETURNING
+    // hands out the drawn value. One statement, race-safe.
+    const row = this.#db
+      .query(
+        "INSERT INTO chat_name_counters (base, next) VALUES (?, 2) ON CONFLICT(base) DO UPDATE SET next = next + 1 RETURNING next - 1 AS drawn",
+      )
+      .get(base) as { drawn: number };
+    return row.drawn;
+  }
+
+  /**
+   * INSERTs a directory row as auto=1 (the only rows this class mints;
+   * auto=0 rows are legacy data). Constraint violations are translated
+   * into structured outcomes rather than raw SQLite errors: a UNIQUE hit
+   * on name means the counter draw collided with a legacy row holding that
+   * exact name (the caller bumps and retries), and a PK hit on session_id
+   * means the session row already exists (a concurrent registration won
+   * the race).
+   */
+  #insertSession(
+    sessionID: string,
+    name: string,
+    project: string | null,
+    topic: string | null,
+    kind: ChatHostKind,
+  ): { ok: true; topic: string | null } | { ok: false; reason: "name-taken" | "already-registered" } {
+    try {
+      this.#db.run(
+        "INSERT INTO chat_sessions (session_id, name, topic, project, host_kind, registered_at, last_seen, auto) VALUES (?, ?, ?, ?, ?, ?, ?, 1)",
+        [sessionID, name, topic, project, kind, nowIso(), nowIso()],
+      );
+      return { ok: true, topic };
+    } catch (err) {
+      if (!this.#isConstraintError(err)) throw err;
+      const msg = String((err as any)?.message ?? err);
+      return msg.includes("chat_sessions.name")
+        ? { ok: false, reason: "name-taken" }
+        : { ok: false, reason: "already-registered" };
+    }
+  }
+
+  #isConstraintError(err: unknown): boolean {
+    return String((err as any)?.code ?? err).includes("CONSTRAINT");
+  }
+}
+
+function rowFromSession(r: any): ChatSessionRow {
+  return {
+    session_id: r.session_id,
+    name: r.name,
+    // An empty-string topic (explicit clear) reads back as no topic, so the
+    // API never leaks the sentinel.
+    topic: r.topic || null,
+    host_kind: r.host_kind === "mcp" ? "mcp" : "opencode",
+    project: r.project,
+    registered_at: r.registered_at,
+    last_seen: r.last_seen,
+  };
+}
+
+/**
+ * Renders a chat participant for user-visible surfaces (wake prompts, the
+ * tail feed, chat_read): the display name when the directory row still
+ * exists, otherwise the shared unknown-departed convention. One helper
+ * because the exact string is a cross-surface convention - a reword here
+ * must reach every surface or the reader sees two names for the same
+ * condition.
+ */
+export function renderChatParticipant(name: string | null, sessionID: string | null | undefined): string {
+  if (name) return name;
+  return `unknown (${String(sessionID ?? "").slice(0, 12)}, departed)`;
+}
+
+// ---------------------------------------------------------------------------
+// Tail events (pure logic behind `thatch chat tail`)
+// ---------------------------------------------------------------------------
+
+export type ChatTailEvent =
+  | { kind: "sent"; timestamp: string; from: string; to: string; fromTopic: string | null; toTopic: string | null; body: string }
+  | { kind: "read"; timestamp: string; reader: string; from: string; fromTopic: string | null; toTopic: string | null; body: string };
+
+/** One message row as the tail diff consumes it. */
+export interface ChatTailRow {
+  id: number;
+  from: string | null;
+  to: string | null;
+  fromTopic: string | null;
+  toTopic: string | null;
+  viaBroadcast: boolean;
+  body: string;
+  created_at: string;
+  read_at: string | null;
+}
+
+/**
+ * Diffs one feed snapshot against the previous one, emitting sent events
+ * for rows the poller has not seen and read events for rows whose read_at
+ * appeared since the last poll. Pure: the caller owns the state map (start
+ * empty for a fresh tail) and updates it from the returned state. A message
+ * inserted and read between two polls emits only its sent line - the sent
+ * event is the primary record, and the read of a message nobody saw as sent
+ * adds nothing.
+ */
+export function chatTailDiff(
+  prev: Map<number, string | null>,
+  rows: Array<ChatTailRow>,
+): { events: ChatTailEvent[]; state: Map<number, string | null> } {
+  const events: ChatTailEvent[] = [];
+  for (const r of rows) {
+    const isNew = !prev.has(r.id);
+    if (isNew) {
+      events.push({
+        kind: "sent",
+        timestamp: r.created_at,
+        from: r.from ?? "unknown",
+        to: r.viaBroadcast ? "broadcast" : r.to ?? "unknown",
+        fromTopic: r.fromTopic,
+        toTopic: r.viaBroadcast ? null : r.toTopic,
+        body: r.body,
+      });
+    } else {
+      const prevRead = prev.get(r.id) ?? null;
+      if (r.read_at !== null && prevRead === null) {
+        events.push({
+          kind: "read",
+          timestamp: r.read_at,
+          reader: r.to ?? "unknown",
+          from: r.from ?? "unknown",
+          fromTopic: r.fromTopic,
+          toTopic: r.toTopic,
+          body: r.body,
+        });
+      }
+    }
+    prev.set(r.id, r.read_at);
+  }
+  return { events, state: prev };
+}
+
+/**
+ * The default number of backlog cards `thatch chat tail` renders before
+ * follow mode takes over. The message table is machine-scale but the
+ * history still grows forever, so an unbounded default would dump the
+ * entire database on every run.
+ */
+export const CHAT_TAIL_DEFAULT_LIMIT = 20;
+
+/**
+ * Parses a tail time-bound value into epoch milliseconds, interpreted in
+ * the terminal's local timezone (the same clock the When headers print).
+ * Accepted: "YYYY-MM-DD" (midnight) or "YYYY-MM-DD HH:MM", with either a
+ * space or a T between the date and the time. The component round-trip
+ * rejects impossible calendar values like 2026-09-31 and 25:99, which
+ * JavaScript's Date would otherwise silently normalize.
+ */
+export function parseChatTimeBound(value: string, flag: string): number {
+  const m = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?$/.exec(value.trim());
+  if (!m) {
+    throw new Error(`${flag} expects "YYYY-MM-DD" or "YYYY-MM-DD HH:MM", got "${value}"`);
+  }
+  const y = Number(m[1]);
+  const mo = Number(m[2]);
+  const d = Number(m[3]);
+  const h = Number(m[4] ?? 0);
+  const mi = Number(m[5] ?? 0);
+  const date = new Date(y, mo - 1, d, h, mi);
+  // Date normalizes out-of-range components (month 13, hour 25); the
+  // round-trip is the check that the value was real.
+  if (!roundTrip(date, y, mo, d, h, mi)) {
+    throw new Error(`${flag} is not a real date or time: "${value}"`);
+  }
+  return date.getTime();
+}
+
+function roundTrip(date: Date, y: number, mo: number, d: number, h: number, mi: number): boolean {
+  return (
+    date.getFullYear() === y &&
+    date.getMonth() === mo - 1 &&
+    date.getDate() === d &&
+    date.getHours() === h &&
+    date.getMinutes() === mi
+  );
+}
+
+/**
+ * Everything the tail can narrow a feed by, all ANDed together. `matches`
+ * test the message body; `fromSubstr`/`toSubstr` are case-insensitive
+ * substrings of the rendered participant names (so a departed sender can
+ * only match as "unknown (...)", the string the reader actually sees).
+ * One deliberate asymmetry: broadcast rows keep the real recipient in
+ * `to`, so `--to <realname>` matches fan-out rows even though their cards
+ * say "broadcast", and `--to broadcast` matches nothing. `sinceMs`/
+ * `untilMs` bound created_at in a since-inclusive, until-exclusive
+ * window. An empty field is no constraint.
+ *
+ * Name inputs are not stable across polls: they are re-resolved from the
+ * live directory on every feed snapshot, so an unregister or rename
+ * flips which rows match. chatTailBacklog's full-feed state seeding is
+ * what keeps such flips from resurfacing old rows as sent events; reads
+ * of rows whose name stopped matching simply go quiet.
+ */
+export interface ChatTailFilter {
+  matches: RegExp[];
+  fromSubstr: string[];
+  toSubstr: string[];
+  sinceMs: number | null;
+  untilMs: number | null;
+}
+
+/** Filters a feed snapshot down to the rows the tail should consider. */
+export function filterChatTailRows(rows: Array<ChatTailRow>, filter: ChatTailFilter): Array<ChatTailRow> {
+  const froms = filter.fromSubstr.map((s) => s.toLowerCase());
+  const tos = filter.toSubstr.map((s) => s.toLowerCase());
+  return rows.filter((r) => {
+    const t = Date.parse(r.created_at);
+    if (filter.sinceMs !== null && t < filter.sinceMs) return false;
+    if (filter.untilMs !== null && t >= filter.untilMs) return false;
+    if (!filter.matches.every((re) => re.test(r.body))) return false;
+    if (froms.some((s) => !(r.from ?? "").toLowerCase().includes(s))) return false;
+    if (tos.some((s) => !(r.to ?? "").toLowerCase().includes(s))) return false;
+    return true;
+  });
+}
+
+/**
+ * Prepares the tail's first render. The diff state seeds from EVERY row in
+ * the feed - filtered or not, rendered or not - for two reasons. First,
+ * the limit hides cards, not history: a state seeded only from the
+ * rendered slice would re-emit the elided history as new sent events on
+ * the first follow poll. Second, the name filters test JOIN-resolved
+ * participant names that can flip mid-follow (a peer unregisters and its
+ * history starts rendering as "unknown (... departed)", or it re-registers
+ * under a new name); seeding everything means an old row can never resurface
+ * as a sent event no matter how its rendered name changes. The last
+ * `limit` filtered rows (null = all) shape into sent events via
+ * chatTailDiff, so card rendering keeps a single source. `elided` counts
+ * matching rows the limit hid, for the CLI's summary line.
+ *
+ * The caller must re-apply the same filter to every follow poll's feed
+ * BEFORE the diff (filterChatTailRows, then chatTailDiff with the state
+ * returned here). Skipping the poll filter resurrects non-matching
+ * history; mutating the state between polls corrupts the read diff.
+ */
+export function chatTailBacklog(
+  rows: Array<ChatTailRow>,
+  filter: ChatTailFilter,
+  limit: number | null,
+): { events: ChatTailEvent[]; state: Map<number, string | null>; elided: number } {
+  const state = new Map(rows.map((r) => [r.id, r.read_at]));
+  const filtered = filterChatTailRows(rows, filter);
+  const shown = limit === null ? filtered : filtered.slice(-limit);
+  const events = chatTailDiff(new Map(), shown).events;
+  return { events, state, elided: filtered.length - shown.length };
+}
+
+/** Renders one tail event in the CLI's line format. */
+export function formatChatTailEvent(event: ChatTailEvent): string {
+  if (event.kind === "sent") {
+    return `[${event.timestamp}] ${event.from} -> ${event.to}: ${event.body}`;
+  }
+  const clipped = event.body.length > 60 ? event.body.slice(0, 60) + "..." : event.body;
+  return `[${event.timestamp}] ${event.reader} read a message from ${event.from}: ${clipped}`;
+}
+
+/** "2026-09-12 19:46 MT" - the UTC timestamp converted to the terminal's
+ *  local timezone (abbreviation from the locale, fallback "UTC"), one line
+ *  for the card header. */
+function localWhen(timestamp: string): string {
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.getTime())) return timestamp;
+  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())} ${tz}`
+  );
+}
+
+/**
+ * Renders one tail event as a chat card: header block (From / To / When),
+ * blank line, full body, then a separator line. This is the human format
+ * for `thatch chat tail` - the single-line formatChatTailEvent remains for
+ * tests and compact contexts. Read events use the same card shape with the
+ * reader in the From slot; broadcast events show "broadcast" as the
+ * recipient. The separator is between cards, so the caller joins cards
+ * with it and never gets a trailing rule.
+ */
+// ANSI styling for the tail cards: black-on-green field-label chips, green
+// values, dim for the timestamps and the "read" marker, and a drawn rule
+// for the separator. Bare ESC sequences rather than a color library - the
+// tail is a terminal surface, and the codes are trivial.
+const ANSI = {
+  // Label chips are padded to a fixed width (5 + padding = 7 columns) so
+  // every line's content starts at the same column - To's 2-char label
+  // misaligned against 4-char labels without this.
+  labelBg: (s: string) => `\x1b[30;42m ${s.padEnd(5)} \x1b[0m`,
+  valueFg: (s: string) => `\x1b[32m${s}\x1b[0m`, // green (field values)
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`, // dim ("read" marker)
+  rule: (s: string) => `\x1b[2m${s}\x1b[0m`, // dim (the drawn separator)
+  // Session-of-origin annotation: italic + bright-black (muted gray).
+  originLabel: (s: string) => `\x1b[3;90m<${s}>\x1b[0m`,
+};
+
+const CARD_INDENT = ""; // cards sit flush with the separator (no extra indent)
+
+export function formatChatTailCard(event: ChatTailEvent): string {
+  const lines: string[] = [];
+  const when = ANSI.dim(localWhen(event.timestamp));
+  // The session-of-origin annotation: the participant's registered topic,
+  // italic + muted bright-black, after the name. Omitted for participants
+  // without a topic (and for the broadcast pseudo-recipient, whose topic
+  // is null by construction).
+  const origin = (topic: string | null) => (topic ? ` ${ANSI.originLabel(topic)}` : "");
+  const chip = (label: string, value: string, topic: string | null) =>
+    `${CARD_INDENT}${ANSI.labelBg(label)} ${ANSI.valueFg(value)}${origin(topic)}`;
+  if (event.kind === "sent") {
+    lines.push(chip("From", event.from, event.fromTopic));
+    lines.push(chip("To", event.to, event.toTopic));
+    lines.push(chip("When", when, null));
+    lines.push("");
+    lines.push(event.body);
+  } else {
+    const clipped = event.body.length > 60 ? event.body.slice(0, 60) + "..." : event.body;
+    lines.push(chip("From", event.reader, event.toTopic));
+    lines.push(`${CARD_INDENT}${ANSI.dim("read")} ${ANSI.valueFg(event.from)}${origin(event.fromTopic)}`);
+    lines.push(chip("When", when, null));
+    lines.push("");
+    lines.push(clipped);
+  }
+  return lines.join("\n");
+}
+
+export const CHAT_TAIL_SEPARATOR = "_".repeat(60);
+
+// ---------------------------------------------------------------------------
+// Poller
+// ---------------------------------------------------------------------------
+
+/** The poller's narrow view of the store: the three chat methods it needs.
+ *  ThatchDB satisfies this structurally through its delegated chat methods.
+ *  The interface pins the poller to exactly these dependencies and removes
+ *  chat.ts's need to import db.ts at all - db.ts already value-imports
+ *  ChatStore, so a reverse import would form a runtime module cycle. A
+ *  test that wants a fake store can pass a plain object, though the suite
+ *  currently uses real temp-dir databases. */
+export interface ChatPollerStore {
+  heartbeatChatSessions(sessionIDs: string[]): void;
+  pendingChatNotifications(sessionIDs: string[], renudgeCutoff: string): ChatNotificationRow[];
+  markChatDelivered(ids: number[]): void;
+  /** Hourly TTL prune of auto-registered directory rows (and the mail that
+   *  can no longer reach a reader). Optional so test fakes stay minimal. */
+  pruneStaleChatAuto?(cutoff: string): number;
+}
+
+export interface ChatPollerOptions {
+  store: ChatPollerStore;
+  /** Session IDs this process has seen events for. Only sessions hosted by
+   *  this process can be delivered to - the recipient's host is the single
+   *  deliverer, by design. */
+  hostedSessions: () => string[];
+  /** Delivers a wake prompt for a recipient. Injected so tests never spawn. */
+  deliver: (sessionID: string, senders: string[], count: number) => Promise<void>;
+  /** Gate for delivery: true only when the session can accept a proactive
+   *  prompt right now (idle, not compacting). May be async - the plugin's
+   *  gate verifies against the server's live status, because the event-fed
+   *  map can be stale and a wake injected into a running turn is mid-turn
+   *  context injection. Undeliverable messages stay pending and retry on
+   *  later cycles. */
+  canDeliver: (sessionID: string) => boolean | Promise<boolean>;
+  /** Poll interval. Default 30s - frequent enough that wake prompts feel
+   *  prompt, cheap enough that the shared DB sees only a couple of light
+   *  statements per cycle per process. */
+  pollIntervalMs?: number;
+  /** A delivered-but-unread message re-queues a nudge after this long.
+   *  Default 15 minutes. */
+  renudgeMinutes?: number;
+  /** Hard brake on wake cycles: maximum wake prompts per recipient per hour.
+   *  Default 6. In-memory on purpose - it is a loop guard, not accounting. */
+  maxNudgesPerHour?: number;
+}
+
+/**
+ * Background poller: heartbeats hosted sessions, delivers wake prompts for
+ * pending chat messages. Mirrors the watcher registry's shape (start/stop/
+ * dispose, re-entrant guards, pending-retry semantics) but its pending state
+ * lives in SQLite rather than memory, because the sender may be a different
+ * process than the deliverer.
+ */
+export class ChatPoller {
+  #opts: Required<ChatPollerOptions>;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #polling = false;
+  #delivering = false;
+  /** Per-recipient wake-prompt timestamps inside the last hour. */
+  #nudges = new Map<string, number[]>();
+  /** Last TTL prune epoch ms. Auto-registered rows are pruned hourly, not
+   *  every cycle - the prune is a maintenance sweep, not delivery. */
+  #lastPrune = 0;
+
+  constructor(opts: ChatPollerOptions) {
+    this.#opts = {
+      pollIntervalMs: CHAT_POLL_INTERVAL_MS,
+      renudgeMinutes: CHAT_RENUDGE_MINUTES,
+      maxNudgesPerHour: CHAT_MAX_NUDGES_PER_HOUR,
+      ...opts,
+    };
+  }
+
+  /** True while the poller timer is armed. */
+  get running(): boolean {
+    return this.#timer !== null;
+  }
+
+  start(): void {
+    if (this.#timer !== null) return;
+    this.#timer = setInterval(() => void this.poll(), this.#opts.pollIntervalMs);
+    // Never keep the host process alive just for the poller - matches the
+    // watcher registry's timer.
+    this.#timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.#timer === null) return;
+    clearInterval(this.#timer);
+    this.#timer = null;
+  }
+
+  /** Stops polling and drops the nudge counters. The inbox itself is shared
+   *  SQLite state and outlives this process by design. */
+  dispose(): void {
+    this.stop();
+    this.#nudges.clear();
+  }
+
+  /**
+   * One poll cycle: heartbeat hosted sessions, then deliver whatever is
+   * pending for sessions that can accept a prompt. Re-entrant calls are
+   * dropped, matching the watcher registry - a slow cycle overlapping the
+   * next would double-deliver the same messages. Store failures are caught
+   * here, not just deliver failures: the timer discards the returned
+   * promise, so an escaping SQLite error would surface as an unhandled
+   * rejection in the plugin host process. A failed cycle logs and retries
+   * on the next tick.
+   */
+  async poll(): Promise<void> {
+    if (this.#polling) return;
+    this.#polling = true;
+    try {
+      const hosted = this.#opts.hostedSessions();
+      this.#opts.store.heartbeatChatSessions(hosted);
+      await this.deliverPending();
+      // Hourly sweep: drop auto-registered rows whose host died more than
+      // CHAT_AUTO_TTL_DAYS ago, plus the unread mail addressed to sessions
+      // no longer in the directory. Automatic registration makes one-shots
+      // and crashed sessions routine, so without this the roster fills
+      // with corpses; counters never decrement, so pruning cannot reissue
+      // a name. The stamp lands before the call, so a throwing prune
+      // retries on the next hourly sweep, not the next cycle.
+      const now = Date.now();
+      if (now - this.#lastPrune > 3_600_000 && this.#opts.store.pruneStaleChatAuto) {
+        this.#lastPrune = now;
+        this.#opts.store.pruneStaleChatAuto(isoMinutesAgo(CHAT_AUTO_TTL_DAYS * 24 * 60));
+      }
+    } catch (err) {
+      console.error(`[thatch] chat poll failed: ${err}`);
+    } finally {
+      this.#polling = false;
+    }
+  }
+
+  /**
+   * Delivers pending messages for every hosted session that can accept a
+   * prompt. Sessions that are busy keep their messages pending; the idle
+   * event handler calls this directly so mail lands promptly instead of
+   * waiting for the next cycle. Failures stay pending and retry. Delivery
+   * is at-least-once: a crash after the wake prompt but before
+   * markChatDelivered re-nudges the same batch on the next cycle.
+   */
+  async deliverPending(): Promise<void> {
+    if (this.#delivering) return;
+    this.#delivering = true;
+    try {
+      const hosted = this.#opts.hostedSessions();
+      const cutoff = isoMinutesAgo(this.#opts.renudgeMinutes);
+      const pending = this.#opts.store.pendingChatNotifications(hosted, cutoff);
+      if (pending.length === 0) return;
+
+      const byRecipient = new Map<string, ChatNotificationRow[]>();
+      for (const msg of pending) {
+        const queue = byRecipient.get(msg.to_session) ?? [];
+        queue.push(msg);
+        byRecipient.set(msg.to_session, queue);
+      }
+
+      for (const [recipient, messages] of byRecipient) {
+        if (!(await this.#opts.canDeliver(recipient))) continue;
+        if (this.#nudgeBudget(recipient) <= 0) continue;
+        try {
+          // "unknown (id, departed)" matches chat_read's rendering of a
+          // sender whose directory row is gone, so both surfaces use one
+          // convention for the same condition.
+          const senders = [...new Set(messages.map((m) => renderChatParticipant(m.from_name, m.from_session)))];
+          await this.#opts.deliver(recipient, senders, messages.length);
+          // Count the nudge before the stamp: the cap must bind on prompts
+          // actually sent, not on the DB write succeeding. A failing stamp
+          // leaves the mail pending, and an uncounted re-delivery every
+          // cycle would be the ping-pong the cap exists to stop.
+          this.#recordNudge(recipient);
+          this.#opts.store.markChatDelivered(messages.map((m) => m.id));
+        } catch (err) {
+          console.error(`[thatch] chat delivery to ${recipient} failed: ${err}`);
+        }
+      }
+    } finally {
+      this.#delivering = false;
+    }
+  }
+
+  /** Remaining wake prompts for this recipient in the current hour. */
+  #nudgeBudget(recipient: string): number {
+    const now = Date.now();
+    const window = this.#nudges.get(recipient) ?? [];
+    const fresh = window.filter((t) => now - t < 3_600_000);
+    this.#nudges.set(recipient, fresh);
+    return this.#opts.maxNudgesPerHour - fresh.length;
+  }
+
+  #recordNudge(recipient: string): void {
+    const window = this.#nudges.get(recipient) ?? [];
+    window.push(Date.now());
+    this.#nudges.set(recipient, window);
+  }
+}
+
+/** True when a session row's last_seen is older than the staleness
+ *  threshold. Used by chat_list to mark ghosts. */
+export function isStale(row: ChatSessionRow, staleMinutes: number, now = Date.now()): boolean {
+  return now - Date.parse(row.last_seen) > staleMinutes * 60_000;
+}