@jeffober/thatch 0.1.41 → 0.1.42

package/README.md

@@ -89,16 +89,23 @@ Thatch gives your agent:
   `session_get`, opencode only) and as CLI subcommands (`thatch session
   list/get/transcript/search`, JSONL output designed for piping to `jq`).
 - **Watchers** -- event-driven notifications from external sources (opencode
-  only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
-  background and prompts the session when comments, commits, CI results, or
-  status changes arrive. Notifications carry pointer data only.
+  only). The agent registers a watch on a GitHub PR, a branch (main), or a
+  local shell command; thatch polls it in the
+  background and prompts the session when comments, commits, CI results, status changes, or a
+  watched command's exit-0 condition arrive. Notifications carry pointer
+  data plus machine status (check conclusions, exit codes), never external
+  content.
 - **Cross-session chat** -- your agent sessions can message each other
-  (opencode, Claude Code, and Cursor; same machine). A session registers
-  under a unique name and topic, others see it in the directory, and
-  messages land in its inbox -- opencode sessions get woken with a prompt
+  (opencode, Claude Code, and Cursor; same machine). opencode sessions
+  join the directory automatically under an assigned, never-reused name
+  (a slug of the session title plus a counter); others see the roster, and
+  messages land in inboxes -- opencode sessions get woken with a prompt
   when idle, other hosts see pending mail at their next prompt. Loop-safe:
   messages are informational to the receiving agent, and wake prompts are
-  rate-capped.
+  rate-capped. Delivered messages are framed as untrusted content so a
+  hostile message cannot impersonate your instructions. Disable the whole
+  feature with `chat.enabled: false` in the thatch config (or just the
+  auto-joining with `chat.autoRegister: false`).
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). Preferences live in a
@@ -120,10 +127,13 @@ host.
 Everything is local. The embedding model downloads once from Hugging Face Hub
 and is cached. No data leaves your machine.
 
-One exception: watchers (opencode only) call the GitHub API through the `gh`
-CLI to poll PRs you explicitly asked to watch, using your existing gh
-authentication. Thatch never sees or stores the token, and notifications
-carry pointer data only - GitHub comment text never enters your context
+One exception: PR and branch watchers (opencode only) call the GitHub API
+through the `gh` CLI to poll targets you explicitly asked to watch, using
+your existing gh authentication; command watchers run local shell commands
+in the project directory, reading only their exit codes. Thatch never sees
+or stores the gh token, and notifications
+carry pointer data plus machine status (check conclusions, exit codes),
+never external content - GitHub comment text never enters your context
 unless the agent fetches it.
 
 ## Development

package/bin/release

@@ -90,7 +90,10 @@ echo
 
 echo "▸ pushing..."
 git push
-git push --tags
+# Push only this release's tag. `git push --tags` would also push every
+# other local tag, and a history rewrite (filter-repo) recreates old tags
+# on new SHAs - which the remote correctly refuses to move.
+git push origin "v$next"
 echo "  ✓ pushed"
 echo
 

package/bin/thatch

@@ -10,7 +10,8 @@ import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
-import { chatTailDiff, formatChatTailEvent, isStale, CHAT_STALE_MINUTES } from "../src/chat";
+import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailCard, CHAT_TAIL_SEPARATOR, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, isStale, CHAT_STALE_MINUTES, mcpSessionID, type ChatTailFilter } from "../src/chat";
+import { chatEnabled, loadConfig } from "../src/config";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -46,8 +47,17 @@ function usage(): never {
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
   thatch chat list                 Registered chat sessions: name, age, project, topic
-  thatch chat tail [--once]        Follow cross-session chat: sent and read events
-                                   (--once prints current state and exits)
+  thatch chat tail [--once] [--limit N|all] [--match RE]
+                   [--from NAME] [--to NAME] [--since DT] [--until DT]
+                                   Follow cross-session chat: sent and read
+                                   events. The backlog shows the last
+                                   ${CHAT_TAIL_DEFAULT_LIMIT} messages
+                                   (--limit N or --limit all to override).
+                                   --match filters message bodies
+                                   (repeatable, ANDed); --from/--to filter
+                                   participant names; --since/--until bound
+                                   the window ("YYYY-MM-DD [HH:MM]" local
+                                   time). Filters apply to follow mode too.
 
 Stores default to the repo detected from git remote. Use "global" for the
 global store. Use "all" with search to search project + global together.`);
@@ -63,20 +73,56 @@ async function defaultStore(): Promise<string> {
 }
 
 /**
- * Builds the chat-mail hook line for the given project: one line when
- * unread mail is waiting for registered sessions, naming the addressee
- * sessions. Empty string when the project has no chat state or no pending
- * mail - a session that never registered never sees a chat line at all,
- * and the line is about the addressee, not about the reader, so there is
- * nothing for an unregistered model to hallucinate.
+ * Builds the chat-mail hook line for the given project. With a hook
+ * session ID (Claude Code/Cursor pass one in the hook's stdin JSON), it
+ * first ensures the caller is registered - the host's assigned identity -
+ * and prints that identity plus the caller's own unread count, so the
+ * model learns who it is on every prompt without a tool call. Without a
+ * session ID it keeps the old shape: a line only when pending mail exists
+ * for registered sessions in the project, naming the addressees.
  */
-async function chatHookLine(): Promise<string> {
+async function chatHookLine(hookSessionID?: string): Promise<string> {
+  // Disabled chat prints nothing: the hook line must not advertise a
+  // feature the user turned off (the tools refuse, the poller never
+  // starts, the prompt section omits chat).
+  if (!chatEnabled(loadConfig(dbPath).config)) return "";
   let repo: string | null = null;
   try {
     repo = await detectRepo();
   } catch {
     return "";
   }
+
+  if (hookSessionID) {
+    // Ensure-register: idempotent, so every prompt re-touches liveness and
+    // the first prompt of a conversation mints the assigned name. This is
+    // the MCP identity anchor - the session ID is stable per conversation,
+    // so re-registering finds the same row and name.
+    const sessionID = mcpSessionID(hookSessionID);
+    // The leave tombstone blocks this ensure: chat_unregister must outlive
+    // the turn that issued it, on MCP hosts as on opencode. The line is
+    // the standing signal - it repeats every prompt until the model
+    // rejoins, and it says plainly that rejoining mints a fresh identity,
+    // because the old one is closed for good (assigned names are never
+    // reused, so a tombstoned identity cannot be resurrected by a later
+    // register).
+    if (db.hasChatLeaveTombstone(sessionID) && !db.chatLeaveSuperseded(sessionID, repo)) {
+      return `[thatch] chat: this conversation left the chat directory (chat_unregister) and will not receive mail. If the user asks to rejoin, call thatch_chat_register with no arguments - that mints a fresh identity; the old one stays closed.`;
+    }
+    db.registerChatSession(sessionID, repo, null, "mcp");
+    const me = db.findChatSession(sessionID);
+    if (!me) return "";
+    const mine = db.unreadChatCount(sessionID);
+    const pendingOthers = db
+      .chatPendingByProject(repo)
+      .filter((p) => p.name !== me.name);
+    const others = pendingOthers.length > 0
+      ? ` Others in this project with unread mail: ${pendingOthers.map((p) => `${p.name} (${p.pending})`).join(", ")}.`
+      : "";
+    const mailbox = mine > 0 ? `${mine} unread message(s) for you` : "no unread mail for you";
+    return `[thatch] chat: you are ${me.name} (${mailbox}).${others}`;
+  }
+
   const pending = db.chatPendingByProject(repo);
   if (pending.length === 0) return "";
   const parts = pending.map((p) => `${p.name} (${p.pending})`);
@@ -88,8 +134,8 @@ async function chatHookLine(): Promise<string> {
  * warning goes first so the LLM sees it before the nudge text. Used by
  * flush-tools to surface version skew and update-available notices on
  * every UserPromptSubmit, regardless of which tier fired. The chat hook
- * line, when present, is appended last (the mail check is the last thing
- * the model reads before the nudge body).
+ * line, when present, is appended last (the identity/mail check is the
+ * last thing the model reads before the nudge body).
  */
 function emit(output: string, versionWarning: string | null, isJson: boolean, chatLine = ""): void {
   if (chatLine) {
@@ -123,17 +169,42 @@ function parseTimeBound(value: string, flag: string): number {
   return parsed;
 }
 
-/** Reads a flag's value (-flag value or --flag=value forms). */
+/** Reads a flag's value (-flag value or --flag=value forms). A flag given
+ *  with no value is a typo, not a default - it dies loudly so `--until`
+ *  at the end of a command line cannot silently disable the bound. */
 function flagValue(flags: string[], ...names: string[]): string | undefined {
   for (let i = 0; i < flags.length; i++) {
     for (const name of names) {
-      if (flags[i] === name) return flags[i + 1];
+      if (flags[i] === name) {
+        if (flags[i + 1] === undefined) {
+          console.error(`error: ${name} expects a value`);
+          process.exit(1);
+        }
+        return flags[i + 1];
+      }
       if (flags[i]?.startsWith(`${name}=`)) return flags[i]!.slice(name.length + 1);
     }
   }
   return undefined;
 }
 
+/** Collects every occurrence of a repeatable flag, dying on a dangling one. */
+function flagValues(flags: string[], ...names: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < flags.length; i++) {
+    for (const name of names) {
+      if (flags[i] === name) {
+        if (flags[i + 1] === undefined) {
+          console.error(`error: ${name} expects a value`);
+          process.exit(1);
+        }
+        out.push(flags[i + 1]);
+      } else if (flags[i]?.startsWith(`${name}=`)) out.push(flags[i]!.slice(name.length + 1));
+    }
+  }
+  return out;
+}
+
 function openSessionDb(): SessionDB {
   const path = resolveOpencodeDbPath();
   if (!path) {
@@ -271,7 +342,7 @@ async function chatCommand(rest: string[]): Promise<void> {
     case "list": {
       const sessions = db.listChatSessions();
       if (sessions.length === 0) {
-        console.log("No sessions registered. Sessions join with thatch_chat_register from opencode.");
+        console.log("No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register.");
         break;
       }
       for (const s of sessions) {
@@ -292,27 +363,105 @@ async function chatCommand(rest: string[]): Promise<void> {
 
     case "tail": {
       const onceOnly = restArgs.includes("--once");
+      // Parse and validate everything up front: a bad regex or date must
+      // fail before any cards print, not mid-follow.
+      const matches = flagValues(restArgs, "--match").map((pattern) => {
+        try {
+          return new RegExp(pattern);
+        } catch {
+          console.error(`error: --match is not a valid regular expression: "${pattern}"`);
+          process.exit(1);
+        }
+      });
+      const limitArg = flagValue(restArgs, "--limit");
+      let limit: number | null = CHAT_TAIL_DEFAULT_LIMIT;
+      if (limitArg !== undefined) {
+        if (limitArg === "all") limit = null;
+        else if (!/^\d+$/.test(limitArg)) {
+          console.error(`error: --limit expects a positive integer or "all", got "${limitArg}"`);
+          process.exit(1);
+        } else limit = Number(limitArg);
+        if (limit !== null && limit < 1) {
+          console.error(`error: --limit expects a positive integer or "all", got "${limitArg}"`);
+          process.exit(1);
+        }
+      }
+      let sinceMs: number | null = null;
+      let untilMs: number | null = null;
+      try {
+        const since = flagValue(restArgs, "--since");
+        const until = flagValue(restArgs, "--until");
+        if (since !== undefined) sinceMs = parseChatTimeBound(since, "--since");
+        if (until !== undefined) untilMs = parseChatTimeBound(until, "--until");
+      } catch (err) {
+        console.error(`error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      if (sinceMs !== null && untilMs !== null && sinceMs >= untilMs) {
+        console.error("error: --since is not before --until; the window is empty");
+        process.exit(1);
+      }
+      const fromName = flagValue(restArgs, "--from");
+      const toName = flagValue(restArgs, "--to");
+      const filter: ChatTailFilter = {
+        matches,
+        fromSubstr: fromName !== undefined ? [fromName] : [],
+        toSubstr: toName !== undefined ? [toName] : [],
+        sinceMs,
+        untilMs,
+      };
+
       // Diff state: one entry per seen message id holding its read_at, so
       // each poll emits only new messages and newly-read rows. The diff
-      // logic lives in src/chat.ts (chatTailDiff), unit-tested there.
-      const state = new Map<number, string | null>();
-
-      // Follow mode holds the handle open until Ctrl-C; the finally below
-      // closes it on every exit path, including the SIGINT handler's.
+      // and backlog logic lives in src/chat.ts (chatTailDiff,
+      // chatTailBacklog), unit-tested there. The backlog seeds the state
+      // from every feed row, so the limit hides cards, not history.
+      let state: Map<number, string | null>;
+      let firstFollowEvent = true;
+
+      // Follow mode holds the handle open until Ctrl-C. The finally below
+      // closes it on every exit path except the SIGINT handler's, which
+      // is why the handler closes it itself: process.exit does not unwind
+      // finally blocks (closing twice is harmless).
       try {
-        // First pass: print the backlog (every existing row as its sent
-        // line), then follow unless --once.
-        for (const event of chatTailDiff(state, db.chatMessageFeed()).events) {
-          if (event.kind === "sent") console.log(formatChatTailEvent(event));
+        // First pass: render the backlog as cards, then follow unless
+        // --once or the --until window has already closed (a closed
+        // window has no future events to follow). The backlog fetch gets
+        // the same friendly failure treatment as follow polls: a locked
+        // or missing database should say so, not die with a stack trace.
+        let backlog;
+        try {
+          backlog = chatTailBacklog(db.chatMessageFeed(), filter, limit);
+        } catch (err) {
+          console.error(`[thatch chat tail] feed query failed: ${err}`);
+          console.error("The database may be locked or missing; exiting.");
+          return;
+        }
+        state = backlog.state;
+        if (backlog.elided > 0) {
+          // The elision note goes to stderr so stdout stays a clean card
+          // stream for pipes.
+          console.error(
+            `[thatch chat tail] showing last ${backlog.events.length} of ${backlog.elided + backlog.events.length} messages (--limit N, --limit all)`,
+          );
         }
-        if (onceOnly) break;
+        console.log(backlog.events.map(formatChatTailCard).join(`\n\n${CHAT_TAIL_SEPARATOR}\n\n`));
+        if (onceOnly || (filter.untilMs !== null && filter.untilMs <= Date.now())) break;
 
-        process.on("SIGINT", () => process.exit(0));
+        process.on("SIGINT", () => {
+          db.close();
+          process.exit(0);
+        });
         for (;;) {
           await Bun.sleep(2000);
           try {
-            for (const event of chatTailDiff(state, db.chatMessageFeed()).events) {
-              console.log(formatChatTailEvent(event));
+            // Follow polls re-filter the live feed: matching messages
+            // surface as they arrive, non-matching ones stay invisible.
+            for (const event of chatTailDiff(state, filterChatTailRows(db.chatMessageFeed(), filter)).events) {
+              // Separate follow-mode cards from whatever came before.
+              if (firstFollowEvent && backlog.events.length > 0) console.log(`\n${CHAT_TAIL_SEPARATOR}\n`);
+              firstFollowEvent = false;
+              console.log(formatChatTailCard(event));
             }
           } catch (err) {
             // The surface's whole job is watching a shared, mutable file;
@@ -321,6 +470,11 @@ async function chatCommand(rest: string[]): Promise<void> {
             console.error("The database may be locked or missing; exiting.");
             return;
           }
+          // The window check runs after the poll, so a message created
+          // inside the window but landed during the final sleep is still
+          // displayed; anything inserted after this poll has a created_at
+          // past the bound and is filtered by the window anyway.
+          if (filter.untilMs !== null && Date.now() >= filter.untilMs) break;
         }
       } finally {
         db.close();
@@ -443,8 +597,9 @@ switch (command) {
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
-    // Chat mail check: same gating as flush-tools - a line only when
-    // pending mail exists for registered sessions in this project.
+    // Chat mail check. Without a hook session ID (SessionStart does not
+    // read stdin) the line keeps the old shape: a line only when pending
+    // mail exists for registered sessions in this project.
     const chatLine = await chatHookLine();
     const reminder = claudeSessionStartReminder(repo, hygiene) + (chatLine ? `\n\n${chatLine}` : "");
     if (isJson) {
@@ -686,9 +841,10 @@ switch (command) {
       // flush-tools fires on every prompt, including conversational turns
       // with no tool calls.
       const versionWarning = detectSkew(dbPath) ?? readNpmCacheForUpdate(dbPath);
-      // Chat mail check: one line when pending mail exists for registered
-      // sessions in this project, empty string otherwise (see chatHookLine).
-      const chatLine = await chatHookLine();
+      // Chat check: with a hook session ID this always prints the caller's
+      // assigned identity (and its unread count), so the model knows who it
+      // is before any chat tool call; with no mail the line says so.
+      const chatLine = await chatHookLine(sessionID);
 
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.

package/docs/dev/README.md

@@ -79,9 +79,9 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `config.ts` | User config file (`~/.config/thatch/config.json`, beside the DB): Zod section schemas (strict — unknown keys fail validation), load with missing/invalid fallback to defaults, field-level merge, atomic save (temp + rename). Backs the `config_get`/`config_set` tools. |
 | `notify.ts` | Out-of-band notification dispatch: darwin (`osascript` banner + `/usr/bin/say` voice), linux (`notify-send` + `spd-say`/`espeak`), other platforms report unsupported. Injectable spawner (`CoreContext.spawner`) so tests never fire real commands. Backs the `notify_user` tool. |
 | `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
-| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches GitHub PRs and branches via `gh api` (injected `GhRunner`), diffs against last-seen state, queues pointer-only events per session, and delivers them through a plugin-supplied callback when the session is idle. Process-lifetime state by design - no SQLite. |
+| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Three sources: GitHub PRs and branches via `gh api` (injected `GhRunner`), and local shell commands via `bash -c` (injected `CommandRunner`) run as condition variables - only the exit code is read, never the command's output. Diffs against last-seen state, queues events (pointer data plus machine status like check conclusions and exit codes, never external content) per session, and delivers them through a plugin-supplied callback when the session is idle. The `pollSeconds` getter surfaces the poll cadence to tool output and notifications. Process-lifetime state by design - no SQLite. |
 | `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
-| `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. `chat_register` without a name draws from it. |
+| `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. The pool is the fallback base for registrations with no usable session title. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
@@ -337,8 +337,10 @@ behavior cycle (agent-driven, self-graded)
   `behaviors(id PK, store, statement, rationale, embedding BLOB, model, confidence REAL, confirm_count REAL, disconfirm_count REAL, created_at, updated_at)`,
   `behavior_edges(matcher_id, behavior_id, weight REAL, PK(matcher_id, behavior_id), FK CASCADE)`,
   `behavior_provenance(id PK, behavior_id, signal, detail, created_at, FK CASCADE)`,
-  `chat_sessions(session_id PK, name UNIQUE COLLATE NOCASE, project, registered_at, last_seen)`,
-  `chat_messages(id PK AUTOINCREMENT, from_session, to_session, body, created_at, delivered_at, read_at)`.
+  `chat_sessions(session_id PK, name UNIQUE COLLATE NOCASE, topic, project, host_kind, registered_at, last_seen, auto)`,
+  `chat_messages(id PK AUTOINCREMENT, from_session, to_session, body, created_at, delivered_at, read_at, via_broadcast)`,
+  `chat_name_counters(base PK, next)` - per-base counters for assigned chat names; only ever increments.
+  `chat_leave_tombstones(session_id PK, left_at)` - explicit leaves; suppresses auto-registration until chat_register rejoins.
 - `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing
   databases by an idempotent column migration at init (`PRAGMA table_info` +
   `ALTER TABLE`). The `archived` column is `INTEGER NOT NULL DEFAULT 0` (0 =

package/docs/dev/features/cli.md

@@ -22,7 +22,7 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 | `setup --claude [--cursor] [--global]` | none | `--claude`, `--cursor`, `--global` | none | Install config + instructions + hooks + skills |
 | `session list/get/transcript/search` | per subcommand | `-s/--session`, `--id`, `--after`, `--before`, `--regex`, `--limit` | none | Read-only archaeology on the opencode session database (JSONL output) |
 | `chat list` | none | none | none | Registered chat sessions: name, human-readable age, project, topic |
-| `chat tail [--once]` | none | `--once` | none | Follow cross-session chat: sent and read events (`--once` prints the backlog and exits) |
+| `chat tail` | none | `--once`, `--limit N\|all`, `--match RE` (repeatable), `--from NAME`, `--to NAME`, `--since DT`, `--until DT` | none | Follow cross-session chat: sent and read events. Backlog defaults to the last 20 messages; filters apply to follow mode too. |
 | (unknown) | none | none | none | Print usage, exit 1 |
 
 ## Global behavior
@@ -48,14 +48,25 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 
 - `chat list` renders the roster: display name, human-readable age since the
   last heartbeat, project, and topic when set.
-- `chat tail [--once]` follows the message stream. Sent lines have the shape
-  `[timestamp] from -> to: body` (broadcast rows render `broadcast` via the
-  `via_broadcast` marker); in follow mode, an inbox drain emits a read line
-  (`[timestamp] ${reader} read a message from ${sender}: preview` — the
-  reader is the recipient draining its inbox). The diff logic is
-  `chatTailDiff()`/`formatChatTailEvent()` in `src/chat.ts`, unit-tested
-  there; `--once` prints one snapshot and exits, because a snapshot has no
-  previous state to diff read events against.
+- `chat tail` follows the message stream as styled cards: label chips,
+  colored names, dimmed timestamps, topic annotations after names, and a
+  drawn rule between cards. The card renderer is `formatChatTailCard()`
+  and the event shaping is `chatTailDiff()` in `src/chat.ts`, unit-tested
+  there; the single-line `formatChatTailEvent()` remains for tests and
+  compact contexts. `--once` prints one snapshot and exits, because a
+  snapshot has no previous state to diff read events against.
+- The backlog renders only the last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages;
+  `chatTailBacklog()` in `src/chat.ts` filters the feed, seeds the diff
+  state from every feed row (so the limit hides cards, not history, and a
+  mid-follow rename or unregister cannot resurface old rows as sent
+  events), and reports the elided count for
+  the CLI's stderr note. `filterChatTailRows()` ANDs body regexes
+  (`--match`, repeatable), rendered-name substrings (`--from`/`--to`,
+  case-insensitive), and a half-open `--since`/`--until` window on
+  `created_at`; the same filter applies to follow polls, so non-matching
+  messages stay invisible (their read events too). A `--until` in the past
+  exits after the backlog; one in the future follows until the window
+  closes. `parseChatTimeBound()` accepts `YYYY-MM-DD [HH:MM]` local time.
 
 ## Environment variables