@jeffober/thatch 0.1.41 → 0.1.43

package/README.md

@@ -89,16 +89,30 @@ 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`).
+- **Wrap-up commands** (opencode only) -- `/thatch/compact` and `/thatch/exit`
+  run a pre-flight checklist before a compaction or an exit: the agent flushes
+  pending fact extraction, finishes promised memory writes, and surfaces
+  todos or follow-ups it never addressed. It ends its response with a
+  greenlight token only when the checklist is clean; thatch then triggers the
+  compaction or quits opencode. With items outstanding, the agent lists them
+  and nothing fires -- you decide when to retry.
 - **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 +134,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/artifacts/skills/thatch-clear-writing.md

@@ -0,0 +1,77 @@
+---
+name: thatch-clear-writing
+description: Prose rules for every piece of text a human reads that no dedicated skill already covers - PR and ticket comments posted on the user's behalf, documentation, feature plans, reports, write-ups, status updates, and chat replies to the user. Load it before drafting any of those. When a dedicated writing skill is loaded (thatch-pr-description, thatch-ticket-description, thatch-review-response), that skill's rules win.
+---
+
+# Clear writing
+
+## Core principle
+
+Write for humans. Not for LLMs. Not to impress. Not to pad.
+
+Every sentence earns its place or gets cut. Plain English over jargon. Concrete over abstract. If a phrase sounds smart but you cannot say it in simpler words, it is a buzzword. Cut or replace it.
+
+Target a 7th-grade reading level. Short sentences, common words, one idea each. The concepts stay technical; the language stays simple.
+
+## Where these rules apply
+
+Every text a human reads:
+
+- **Comments you post for the user** - PR comments, ticket comments (Linear, Jira), replies to reviewers, replies to bot findings.
+- **Written artifacts** - documentation, feature plans, reports, write-ups, design notes, status updates.
+- **Replies to the user in chat** - explanations, summaries, answers.
+
+Same prose rules everywhere. Only the structure differs:
+
+- **Artifacts** may use sections, headings, and bullets as the content needs.
+- **Chat replies** use no scaffold. Lead with the answer, then the context, then the caveats. Short, but never compressed into shorthand to make it short.
+
+A dedicated writing skill overrides this one when loaded: `thatch-pr-description` for PR bodies, `thatch-ticket-description` for ticket descriptions, `thatch-review-response` for replies on the user's own PR, the review skills for review reports. Use those where they fit. This skill covers everything they do not.
+
+## The reader
+
+A busy engineer with zero context on this task. They know the stack and general engineering vocabulary. They have never touched this area. They read once, top to bottom, and every sentence must parse on the first read.
+
+## Ordering
+
+Lead with the answer. Then the evidence. Then the caveats.
+
+The reader decides when to stop reading. Give them the point first so stopping early is safe. Never build to a reveal.
+
+- First sentence or two: the conclusion, the answer, or the request.
+- Then: why. The mechanism, the evidence, the reasoning.
+- Last: caveats, open questions, alternatives considered.
+
+## Prose rules
+
+Hard rules. Not suggestions.
+
+1. **One idea per sentence.** Split clause-chains. One topic per paragraph.
+2. **Literal phrasing beats compressed idiom.** Write for an unfamiliar reader. Do not use method names as verbs. Prefer plain English nouns over code-domain nouns: "reading the row from the database" not "the row read"; "a request waiting for a worker" not "a waiter". If a word sounds like it belongs in a source file rather than a sentence, replace it.
+3. **Define subsystem-specific terms on first use.** General engineering vocabulary needs no definition. "the DEK (the symmetric key that encrypts secrets at rest)" - yes. After the first definition, use the term freely.
+4. **Translate project-private labels.** Roadmap names, subsystem nicknames, ticket shorthand, and branch-local labels are not explanations. Say what the code does first: what reads, writes, blocks, retries, or changes. The label can follow if it helps the reader connect prose to code.
+5. **Prefer concrete over ambiguous.** If a word can mean more than one thing here, qualify it or replace it with the specific behavior. Ordinary words can be ambiguous when the code gives them a special role: claim, owner, active, current, publish, resolve, sync, scope. "Persist the value in the database so the UI can display it" beats "publish the value".
+6. **Explain operations before naming them.** Refresh, repair, coalesce, reconcile, normalize, hydrate, fan out - these are not explanations. Name the object, the action, and the effect: "The worker waits up to 5 seconds, then reloads each stale cache key once."
+7. **Name both sides of a contrast.** If timing, ownership, or behavior changed, state the old behavior and the new close together.
+8. **Show causal links.** If a sentence uses "so", "because", or "prevents", make the middle step visible. Cause and effect that do not obviously touch need the missing step spelled out.
+9. **Clarity wins over compression.** Brevity means fewer claims, not denser claims. Shorten by deleting whole claims. Never rewrite surviving sentences into tighter ones. Keep the connective tissue that makes a sentence parse on first read.
+10. **No invented shorthand.** Do not coin abbreviations, portmanteaus, or labels mid-text. Use the real name, or spell out the behavior. A term the reader cannot find anywhere else is a term they cannot look up.
+11. **No buzzwordy abstractions.** "leverage" -> "use". "utilize" -> "use". If you cannot say what a phrase means in plain English, it does not belong.
+12. **Plain ASCII.** No smart quotes, em dashes, or ellipsis glyphs.
+13. **No process narration.** Never describe the order you assembled things in or narrate your own actions inside the text. State the thing itself.
+
+## Length
+
+Match length to complexity: how much new mental model the reader must build.
+
+- A one-line answer gets one line.
+- A real explanation gets as many sentences as the idea needs, and not one more.
+- When over length, cut the lowest-value claim. Do not compress the survivors.
+
+For chat replies: terse is fine, illegible is not. If a two-line answer only fits by inventing shorthand, spend five lines.
+
+## Clarity pass
+
+Before you post, save, or send: reread the draft as a reader with zero context. Fix what they would stumble on. Do not announce the pass; just return clean prose.
+
+Check: Does every sentence parse on first read? Does every term carry its plain-English meaning before or with the label? Would a reader who has never seen this codebase, ticket, or conversation understand it? If the draft runs long, cut a claim; never tighten the grammar.

package/artifacts/skills/thatch-coding-workflow.md

@@ -48,6 +48,7 @@ After all changes are complete, verify in this order:
    - Simple fixes: fix immediately.
    - Complex fixes: plan as a separate milestone.
 4. **Run tests, linters, and formatters.** Address any issues they surface. If the project has a quality gate (make check, npm run check, mise run check), run it.
+5. **Repo finish gate.** If the current repo defines its own definition-of-done skill (in the thatch repo: `thatch-dev-done`), load it and work its checklist before claiming the task complete. The generic verification above does not cover repo-specific duties: QA use cases, doc tiers, count touch points, commit conventions.
 
 ## Blockers vs intermediate states
 

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, humanAge, mcpSessionID, selectChatBodyRenderer, cleanRenderedBody, type ChatSessionRow, 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) {
@@ -253,15 +324,84 @@ async function sessionCommand(rest: string[]): Promise<void> {
 // chat subcommand group - read-only window on the cross-session chat
 // ---------------------------------------------------------------------------
 
-/** "2m ago", "3h ago", "5d ago" - human-readable age for the chat roster. */
-function humanAge(iso: string, now = Date.now()): string {
-  const seconds = Math.max(0, Math.floor((now - Date.parse(iso)) / 1000));
-  if (Number.isNaN(seconds)) return "unknown age";
-  if (seconds < 60) return `${seconds}s ago`;
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-  if (minutes < 24 * 60) return `${Math.floor(minutes / 60)}h ago`;
-  return `${Math.floor(minutes / (24 * 60))}d ago`;
+/** Column headers for the `chat list` roster, in display order. */
+const CHAT_ROSTER_HEADER = ["NAME", "AGE", "STATUS", "PROJECT", "TOPIC"];
+
+/**
+ * Renders the `chat list` roster as aligned columns under a header row.
+ * Columns size to the widest cell so names, ages, and projects line up
+ * across sessions. Color is applied only when stdout is an interactive
+ * terminal (and NO_COLOR is unset), so piped output - grep, redirect,
+ * QA runners - stays clean plain text. Palette matches the chat tail
+ * cards: green values, dim age, red STALE, muted italic topic.
+ */
+function formatChatRoster(sessions: ChatSessionRow[]): string {
+  const colored = process.stdout.isTTY === true && !process.env.NO_COLOR;
+  const paint = (code: string, s: string) => (colored ? `\x1b[${code}m${s}\x1b[0m` : s);
+  const rows = sessions.map((s) => ({
+    name: s.name,
+    age: humanAge(s.last_seen),
+    stale: isStale(s, CHAT_STALE_MINUTES),
+    project: s.project ?? "unknown",
+    topic: s.topic ?? "",
+  }));
+  const cells = (r: (typeof rows)[number]) => [r.name, r.age, r.stale ? "STALE" : "fresh", r.project, r.topic];
+  // Widths come from the PLAIN cell text; color is applied after padding so
+  // zero-width escape codes never skew the alignment.
+  const widths = CHAT_ROSTER_HEADER.map((h, i) => Math.max(h.length, ...rows.map((r) => cells(r)[i].length)));
+  const align = (line: string[]) => line.map((c, i) => (i < line.length - 1 ? c.padEnd(widths[i]) : c));
+  const header = align(CHAT_ROSTER_HEADER).map((h) => paint("1", h)).join("  ");
+  const body = rows.map((r) => {
+    const [name, age, status, project, topic] = align(cells(r));
+    return [
+      paint("32", name),
+      paint("2", age),
+      paint(r.stale ? "31" : "32", status),
+      project,
+      topic ? paint("3;90", topic) : "",
+    ].join("  ").trimEnd();
+  });
+  return [header, ...body].join("\n");
+}
+
+/**
+ * Markdown-to-ANSI renderer for chat tail bodies: prefers glow, then
+ * `gum format`, and degrades to the plain body when neither is installed.
+ * Detection runs once and only for interactive terminals - pipes (grep,
+ * QA runners) always get the raw body, and NO_COLOR opts out entirely.
+ * The renderer never fails open: a crashed or missing binary returns the
+ * body unchanged.
+ */
+let renderChatBody: (body: string) => string | null | undefined;
+
+/**
+ * Markdown-to-ANSI renderer for chat tail bodies: renderer selection
+ * (glow, then gum format) and body cleanup live in src/chat.ts
+ * (selectChatBodyRenderer, cleanRenderedBody, unit-tested there); this
+ * wrapper owns the TTY gate, the once-per-process cache, and the spawn.
+ * Detection runs only for interactive terminals - pipes (grep, QA
+ * runners) always get the raw body, and NO_COLOR opts out entirely.
+ * The renderer never fails open: a crashed or missing binary returns the
+ * body unchanged.
+ */
+function markdownBodyRenderer(): (body: string) => string {
+  if (renderChatBody !== undefined) return renderChatBody;
+  if (process.stdout.isTTY !== true || process.env.NO_COLOR) {
+    renderChatBody = (body) => body;
+    return renderChatBody;
+  }
+  const argv = selectChatBodyRenderer(Bun.which("glow"), Bun.which("gum"));
+  if (!argv) {
+    renderChatBody = (body) => body;
+    return renderChatBody;
+  }
+  // spawnSync stdin needs a Response (the `input` option is a no-op in
+  // Bun 1.3.14).
+  renderChatBody = (body) => {
+    const run = Bun.spawnSync(argv, { stdin: new Response(body), stdout: "pipe", stderr: "pipe" });
+    return run.exitCode === 0 ? cleanRenderedBody(run.stdout.toString()) : body;
+  };
+  return renderChatBody;
 }
 
 async function chatCommand(rest: string[]): Promise<void> {
@@ -271,48 +411,114 @@ 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) {
-        // Same staleness convention as the chat_list tool: an age past the
-        // threshold means the session's host process is probably gone.
-        const liveness = isStale(s, CHAT_STALE_MINUTES) ? "STALE" : "fresh";
-        const parts = [
-          s.name,
-          `(${humanAge(s.last_seen)})`,
-          liveness,
-          `project:${s.project ?? "unknown"}`,
-        ];
-        if (s.topic) parts.push(s.topic);
-        console.log(parts.join("  "));
-      }
+      console.log(formatChatRoster(sessions));
       break;
     }
 
     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;
         }
-        if (onceOnly) break;
+        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)`,
+          );
+        }
+        console.log(backlog.events.map((e) => formatChatTailCard(e, markdownBodyRenderer())).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, markdownBodyRenderer()));
             }
           } catch (err) {
             // The surface's whole job is watching a shared, mutable file;
@@ -321,6 +527,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 +654,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 +898,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]`. |
@@ -99,6 +99,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
+| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
 | `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
@@ -337,8 +338,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 =