@jeffober/thatch 0.1.41 → 0.1.42

package/src/chat.ts

@@ -77,17 +77,16 @@ export interface ChatInboxItem {
   created_at: string;
 }
 
-export type ChatResult = { ok: true; topic: string | null } | { ok: false; error: string };
-
 /**
  * Derives the synthetic session ID for an MCP-host chat registration: a
- * pure function of the claimed name, so identity survives the ephemeral
- * sessions those hosts run (a later conversation claiming the same name
- * finds the same row). The underscore keeps the ID outside NAME_CHARSET,
- * preserving the name-cannot-shadow-ID invariant that find() relies on.
+ * 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(name: string): string {
-  const hash = Bun.SHA256.hash(name.toLowerCase(), "hex").slice(0, 12);
+export function mcpSessionID(hostSessionID: string): string {
+  const hash = Bun.SHA256.hash(hostSessionID.toLowerCase(), "hex").slice(0, 12);
   return `mcp_${hash}`;
 }
 
@@ -99,20 +98,56 @@ 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_NAME_LEN = 40;
 const MAX_BODY_LEN = 10_000;
 
-// Custom names share the pool's charset: letters, numbers, spaces,
-// apostrophes, hyphens, periods. Parens would truncate the transcript
-// echo's name parse; newlines or tabs would break chat_list's one-line
-// roster format. Exported so the pool conformance test can pin that every
-// baked-in name satisfies it.
+// 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;
@@ -131,96 +166,66 @@ export class ChatStore {
     this.#db = db;
   }
 
-  /** Joins the directory with a pool name: picks uniformly at random from the
-   * names no other session has claimed (case-insensitively). Idempotent for
-   * an already-registered session - it keeps its current name (drawn:
-   * false). Fails when every pool name is taken, or when concurrent
-   * registrations win every draw attempt - see the redraw loop below.
+  /**
+   * 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.
    */
-  assign(
+  register(
     sessionID: string,
     project: string | null,
     topic: string | null,
     kind: ChatHostKind,
-  ): { ok: true; name: string; drawn: boolean; topic: string | null } | { ok: false; error: string } {
+    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);
-      const cleaned = this.#cleanTopic(topic);
-      this.#maybeUpdateTopic(sessionID, existing.topic, cleaned);
-      return { ok: true, name: existing.name, drawn: false, topic: cleaned ?? existing.topic };
-    }
-    // Two processes can snapshot the same free list and draw the same name;
-    // the loser's INSERT hits the constraint. Redrawing from the names
-    // still free (the taken set is re-read each attempt) keeps the pool
-    // path's cannot-collide promise even under concurrent registration.
-    for (let attempt = 0; attempt < 5; attempt++) {
-      const taken = new Set(this.list().map((r) => r.name.toLowerCase()));
-      const free = CHAT_NAME_POOL.filter((n) => !taken.has(n.toLowerCase()));
-      if (free.length === 0) {
-        return { ok: false, error: "Name pool exhausted - pass a custom name." };
-      }
-      const name = free[Math.floor(Math.random() * free.length)];
-      const cleanTopic = this.#cleanTopic(topic);
-      const claimed = this.#insertSession(sessionID, name, project, cleanTopic, kind);
-      if (claimed.ok) return { ok: true, name, drawn: true, topic: cleanTopic };
+      // 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 };
     }
-    return { ok: false, error: "Could not claim a pool name after several attempts - pass a custom name." };
-  }
-
-  /**
-   * Joins the directory, or refreshes an existing registration. Re-registering
-   * with the same session ID renames the session (including changing only
-   * the casing of its own name); the new name must not be claimed by a
-   * different session. Uniqueness is case-insensitive ("Landru" and "landru"
-   * are the same name), so lookups and claims agree no matter what casing the
-   * model or user types. Both paths stamp last_seen.
-   */
-  register(sessionID: string, rawName: string, project: string | null, topic: string | null, kind: ChatHostKind): ChatResult {
-    const name = rawName.trim();
-    const invalid = this.#invalidName(name);
-    if (invalid) return { ok: false, error: invalid };
+    const gate = this.#tombstoneGate(sessionID, kind);
+    if (gate) return gate;
     const cleanTopic = this.#cleanTopic(topic);
-    const existing = this.#find(sessionID);
-    if (existing) {
-      if (existing.name === name) {
-        this.#touch(sessionID);
-        this.#maybeUpdateTopic(sessionID, existing.topic, cleanTopic);
-        // The kept topic: omitted keeps existing, "" clears to null (the
-        // read-side normalization this return path mirrors).
-        return { ok: true, topic: cleanTopic ?? existing.topic };
-      }
-      // A NOCASE hit is only a collision when it belongs to a different
-      // session - otherwise this is the caller recasing its own name.
-      const clash = this.#findByName(name);
-      if (clash && clash.session_id !== sessionID) {
-        return this.#nameTaken(name);
-      }
-      try {
-        // An omitted topic (null) keeps the existing one, same as the
-        // same-name path below - a rename is a re-register, and the tool
-        // treats name and topic updates as independent.
-        const nextTopic = cleanTopic ?? existing.topic;
-        this.#db.run("UPDATE chat_sessions SET name = ?, topic = ?, last_seen = ? WHERE session_id = ?", [
-          name,
-          nextTopic,
-          nowIso(),
-          sessionID,
-        ]);
-        return { ok: true, topic: nextTopic };
-      } catch (err) {
-        if (this.#isConstraintError(err)) {
-          return this.#nameTaken(name);
-        }
-        throw err;
+    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 };
       }
     }
-    if (this.#findByName(name)) {
-      return this.#nameTaken(name);
-    }
-    const inserted = this.#insertSession(sessionID, name, project, cleanTopic, kind);
-    if (inserted.ok) return { ok: true, topic: cleanTopic };
-    return inserted;
+    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
@@ -228,10 +233,106 @@ export class ChatStore {
   unregister(sessionID: string): boolean {
     const existing = this.#find(sessionID);
     if (!existing) return false;
-    this.#db.run("DELETE FROM chat_sessions WHERE session_id = ?", [sessionID]);
+    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")
@@ -434,6 +535,8 @@ export class ChatStore {
     id: number;
     from: string | null;
     to: string | null;
+    fromTopic: string | null;
+    toTopic: string | null;
     viaBroadcast: boolean;
     body: string;
     created_at: string;
@@ -442,7 +545,7 @@ export class ChatStore {
     return (
       this.#db
         .query(
-          `SELECT m.id, m.from_session, m.to_session, fs.name AS from_name, ts.name AS to_name, m.via_broadcast, m.body, m.created_at, m.read_at
+          `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
@@ -453,6 +556,8 @@ export class ChatStore {
       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,
@@ -520,15 +625,6 @@ export class ChatStore {
     this.#db.run("UPDATE chat_sessions SET last_seen = ? WHERE session_id = ?", [nowIso(), sessionID]);
   }
 
-  #invalidName(name: string): string | null {
-    if (!name) return "Name cannot be empty.";
-    if (name.length > MAX_NAME_LEN) return `Name too long (max ${MAX_NAME_LEN} characters).`;
-    if (!NAME_CHARSET.test(name)) {
-      return "Names may contain letters, numbers, spaces, apostrophes, hyphens, and periods.";
-    }
-    return null;
-  }
-
   /** 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
@@ -540,61 +636,83 @@ export class ChatStore {
     return topic.replace(/\s+/g, " ").trim().slice(0, MAX_TOPIC_LEN);
   }
 
-  /** Refreshes the topic on re-registration when it changed. Omitting the
-   *  topic (null) keeps the existing one; passing an empty topic clears it. */
-  #maybeUpdateTopic(sessionID: string, current: string | null, next: string | null): void {
-    if (next === null || next === current) return;
-    this.#db.run("UPDATE chat_sessions SET topic = ? WHERE session_id = ?", [next, sessionID]);
+  /**
+   * 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, translating a UNIQUE-constraint violation into
-   * the friendly taken message. The pre-checks are advisory only against
-   * other processes: two sessions claiming one free name in the same
-   * instant both pass the check, and the loser's INSERT must not escape the
-   * { ok, error } contract as a raw SQLite error. Same pattern as
-   * remember()'s slug-collision handling in db.ts.
+   * 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): ChatResult {
+  #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) VALUES (?, ?, ?, ?, ?, ?, ?)",
+        "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) {
-      // The two constraints fail differently: a UNIQUE hit on name means
-      // someone else claimed it; a PK hit on session_id means this session
-      // is somehow registered twice, which is an identity event, not a
-      // naming one.
-      if (this.#isConstraintError(err)) {
-        return this.#alreadyRegistered();
-      }
-      throw 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");
   }
-
-  /** The one taken-message every claim path returns, so a rewording cannot
-   *  drift between the pre-checks and the race catches. Points at the
-   *  guaranteed-success recovery (a pool draw) like every other failure
-   *  path in this feature. */
-  #nameTaken(name: string): ChatResult {
-    return {
-      ok: false,
-      error: `Name "${name}" is taken by another session - pick another name, or omit the name to draw one from the pool.`,
-    };
-  }
-
-  /** The one already-registered message for a session-ID PRIMARY KEY hit -
-   *  a constraint collision that is not a taken name (the caller's own
-   *  session row already exists under a different identity path). */
-  #alreadyRegistered(): ChatResult {
-    return { ok: false, error: "You are already registered - call chat_list to see your current name." };
-  }
 }
 
 function rowFromSession(r: any): ChatSessionRow {
@@ -629,14 +747,16 @@ export function renderChatParticipant(name: string | null, sessionID: string | n
 // ---------------------------------------------------------------------------
 
 export type ChatTailEvent =
-  | { kind: "sent"; timestamp: string; from: string; to: string; body: string }
-  | { kind: "read"; timestamp: string; reader: string; from: string; body: string };
+  | { 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;
@@ -665,6 +785,8 @@ export function chatTailDiff(
         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 {
@@ -675,6 +797,8 @@ export function chatTailDiff(
           timestamp: r.read_at,
           reader: r.to ?? "unknown",
           from: r.from ?? "unknown",
+          fromTopic: r.fromTopic,
+          toTopic: r.toTopic,
           body: r.body,
         });
       }
@@ -684,6 +808,122 @@ export function chatTailDiff(
   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") {
@@ -693,6 +933,76 @@ export function formatChatTailEvent(event: ChatTailEvent): string {
   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
 // ---------------------------------------------------------------------------
@@ -708,6 +1018,9 @@ 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 {
@@ -719,9 +1032,12 @@ export interface ChatPollerOptions {
   /** 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). Undeliverable messages stay
-   *  pending and retry on later cycles. */
-  canDeliver: (sessionID: string) => boolean;
+   *  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. */
@@ -748,6 +1064,9 @@ export class ChatPoller {
   #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 = {
@@ -801,6 +1120,18 @@ export class ChatPoller {
       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 {
@@ -833,7 +1164,7 @@ export class ChatPoller {
       }
 
       for (const [recipient, messages] of byRecipient) {
-        if (!this.#opts.canDeliver(recipient)) continue;
+        if (!(await this.#opts.canDeliver(recipient))) continue;
         if (this.#nudgeBudget(recipient) <= 0) continue;
         try {
           // "unknown (id, departed)" matches chat_read's rendering of a