@jeffober/thatch 0.1.43 → 0.1.44

package/README.md

@@ -99,8 +99,10 @@ Thatch gives your agent:
   (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 land in inboxes -- idle opencode sessions get woken with a
+  prompt, and Cursor and Claude Code wake when a turn ends with unread
+  mail (Cursor also at prompt time; Claude Code also at startup and
+  resume). Loop-safe:
   messages are informational to the receiving agent, and wake prompts are
   rate-capped. Delivered messages are framed as untrusted content so a
   hostile message cannot impersonate your instructions. Disable the whole

package/bin/thatch

@@ -8,10 +8,12 @@ import { detectRepo } from "../src/git";
 import { BgeEmbeddingModel } from "../src/embeddings";
 import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
-import { setupClaudeCode, setupCursor } from "../src/setup";
+import { setupClaudeCode, setupCursor, registerClaudeMcpServer } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
-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 { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
 import { chatEnabled, loadConfig } from "../src/config";
+import { chatNotificationNudge } from "../src/prompts";
+import { createDebugLog } from "../src/debug";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -34,6 +36,7 @@ function usage(): never {
   thatch buffer-batch              Append a PostToolBatch payload to the queue (Claude Code hook only)
   thatch buffer-tool               Append a single postToolUse interaction to the queue (Cursor hook only)
   thatch flush-tools [--json]      Peek the queue + print an extraction nudge (hook only)
+  thatch chat-notify               Print a chat follow-up message when mail is unread (Cursor stop hook)
   thatch flush-predictions [--json] Query predictions for the prompt (hook only)
   thatch setup --claude [--cursor] [--local|--global]
                                    Install config + instructions + hooks + skills
@@ -46,11 +49,14 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   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 list                 Registered chat sessions, grouped Active/Stale:
+                                   name, age, status, project, topic
   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
+                                   Follow cross-session chat as a JSONL
+                                   event log: one line per event, "sent"
+                                   and "read" as separate events linked by
+                                   message id. The backlog shows the last
                                    ${CHAT_TAIL_DEFAULT_LIMIT} messages
                                    (--limit N or --limit all to override).
                                    --match filters message bodies
@@ -81,7 +87,7 @@ async function defaultStore(): Promise<string> {
  * 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(hookSessionID?: string): Promise<string> {
+async function chatHookLine(hookSessionID?: string, transcriptPath?: 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).
@@ -99,6 +105,25 @@ async function chatHookLine(hookSessionID?: string): Promise<string> {
     // the MCP identity anchor - the session ID is stable per conversation,
     // so re-registering finds the same row and name.
     const sessionID = mcpSessionID(hookSessionID);
+    // Continuation adoption: Claude Code forks the session id on resume
+    // (and has been observed to fork spontaneously), stranding the old
+    // identity and mailbox. When this session is unknown, look for a
+    // predecessor transcript handing off to it; adopting keeps the name
+    // and mail following the human-level conversation. Runs before the
+    // ensure so the migrated row is the one re-registered.
+    if (!db.findChatSession(sessionID) && transcriptPath) {
+      try {
+        const pred = resolveRegisteredPredecessor(transcriptPath, hookSessionID, (raw) =>
+          db.findChatSession(mcpSessionID(raw))?.session_id ?? null,
+        );
+        if (pred) {
+          db.continueChatSession(pred, sessionID);
+          hookDebug("hook:adoption", `continued chat identity: ${pred} -> ${sessionID}`);
+        }
+      } catch (err) {
+        console.error(`[thatch] chat continuation adoption failed: ${err}`);
+      }
+    }
     // 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
@@ -129,6 +154,61 @@ async function chatHookLine(hookSessionID?: string): Promise<string> {
   return `[thatch] chat: unread message(s) for ${parts.join(", ")} - the addressee should call chat_read`;
 }
 
+/**
+ * Reads the hook session ID from stdin without hanging when no payload is
+ * coming. Interactive runs skip the read outright (isTTY); a piped or
+ * inherited stdin that never closes (bare spawns) gives up after a short
+ * grace period. Hook hosts write the payload immediately at spawn, so the
+ * grace window costs nothing on the hot path. Malformed payloads resolve to
+ * undefined rather than failing the reminder.
+ */
+/**
+ * Reads the hook's stdin JSON without hanging when no payload is coming.
+ * Interactive runs skip the read outright (isTTY); a piped or inherited
+ * stdin that never closes (bare spawns) gives up after a short grace
+ * period and destroys the stream, because a pending stdin read keeps
+ * the process alive after main finishes. Hook hosts write the payload
+ * immediately at spawn, so the grace window costs nothing on the hot path.
+ * Malformed payloads resolve to undefined rather than failing the command.
+ * Uses the Node stream API instead of Bun.stdin.text(): a pending
+ * Bun.stdin read cannot be cancelled and pins the process forever.
+ */
+function readHookInput(tag: string): Promise<Record<string, unknown> | undefined> {
+  if (process.stdin.isTTY) return Promise.resolve(undefined);
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    const timer = setTimeout(() => done(undefined), 500);
+    const done = (value: string | undefined) => {
+      clearTimeout(timer);
+      process.stdin.destroy();
+      try {
+        if (!value) return resolve(undefined);
+        logHookPayload(tag, value);
+        resolve(JSON.parse(value) as Record<string, unknown>);
+      } catch {
+        resolve(undefined);
+      }
+    };
+    process.stdin.on("data", (chunk: Buffer) => chunks.push(chunk));
+    process.stdin.on("end", () => done(Buffer.concat(chunks).toString()));
+    process.stdin.on("error", () => done(undefined));
+  });
+}
+
+const hookDebug = createDebugLog(dbPath);
+
+/**
+ * Debug-logs one hook invocation's raw stdin payload (tag hook:<command>,
+ * payload truncated). Answers "did the host fire the hook at all, and what
+ * did it send?" - the chat DB cannot distinguish a hook that never fired
+ * from one whose payload carried no session id, and host hook contracts
+ * are sometimes documented wrong.
+ */
+function logHookPayload(command: string, raw: string): void {
+  const clipped = raw.length > 2000 ? `${raw.slice(0, 2000)}...` : raw;
+  hookDebug(`hook:${command}`, `stdin: ${JSON.stringify(clipped)}`);
+}
+
 /**
  * Emits the nudge output, prepending a version warning if present. The
  * warning goes first so the LLM sees it before the nudge text. Used by
@@ -328,80 +408,52 @@ async function sessionCommand(rest: string[]): Promise<void> {
 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.
+ * Renders the `chat list` roster as two sections - Active and Stale - each
+ * an aligned-column table under a header row. Section headers are bold,
+ * the stale explainer is muted italic; rows use green names, dim age,
+ * green/red status, and a muted italic topic.
+ * 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.
  */
 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 { active, stale } = splitChatRoster(sessions);
+  const renderTable = (rows: ChatSessionRow[]) => {
+    const cells = (r: ChatSessionRow) => [
+      r.name,
+      humanAge(r.last_seen),
+      chatLiveness(r),
+      r.project ?? "unknown",
+      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(status === "stale" ? "31" : "32", status),
+        project,
+        topic ? paint("3;90", topic) : "",
+      ].join("  ").trimEnd();
+    });
+    return [header, ...body].join("\n");
+  };
+  const parts: string[] = [];
+  if (active.length > 0) {
+    parts.push([paint("1", "# Active Sessions"), renderTable(active)].join("\n"));
   }
-  const argv = selectChatBodyRenderer(Bun.which("glow"), Bun.which("gum"));
-  if (!argv) {
-    renderChatBody = (body) => body;
-    return renderChatBody;
+  if (stale.length > 0) {
+    const explainer = `These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume.`;
+    parts.push([paint("1", "# Stale Sessions"), paint("3;90", explainer), renderTable(stale)].join("\n"));
   }
-  // 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;
+  return parts.join("\n\n");
 }
 
 async function chatCommand(rest: string[]): Promise<void> {
@@ -421,7 +473,7 @@ 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.
+      // fail before any lines print, not mid-follow.
       const matches = flagValues(restArgs, "--match").map((pattern) => {
         try {
           return new RegExp(pattern);
@@ -472,16 +524,15 @@ async function chatCommand(rest: string[]): Promise<void> {
       // each poll emits only new messages and newly-read rows. The diff
       // 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.
+      // from every feed row, so the limit hides lines, 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: render the backlog as cards, then follow unless
+        // First pass: print the backlog, 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
@@ -496,13 +547,13 @@ async function chatCommand(rest: string[]): Promise<void> {
         }
         state = backlog.state;
         if (backlog.elided > 0) {
-          // The elision note goes to stderr so stdout stays a clean card
-          // stream for pipes.
+          // The elision note goes to stderr so stdout stays pure JSONL
+          // for pipes.
           console.error(
-            `[thatch chat tail] showing last ${backlog.events.length} of ${backlog.elided + backlog.events.length} messages (--limit N, --limit all)`,
+            `[thatch chat tail] showing last ${backlog.shown} of ${backlog.elided + backlog.shown} messages (--limit N, --limit all)`,
           );
         }
-        console.log(backlog.events.map((e) => formatChatTailCard(e, markdownBodyRenderer())).join(`\n\n${CHAT_TAIL_SEPARATOR}\n\n`));
+        for (const event of backlog.events) console.log(formatChatTailJsonl(event));
         if (onceOnly || (filter.untilMs !== null && filter.untilMs <= Date.now())) break;
 
         process.on("SIGINT", () => {
@@ -515,10 +566,7 @@ async function chatCommand(rest: string[]): Promise<void> {
             // 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()));
+              console.log(formatChatTailJsonl(event));
             }
           } catch (err) {
             // The surface's whole job is watching a shared, mutable file;
@@ -654,10 +702,28 @@ switch (command) {
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
-    // 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();
+    // Chat mail check. SessionStart DOES pass a session id in the hook's
+    // stdin JSON (session_id for Claude Code, conversation_id for Cursor),
+    // so a hooked session learns its identity at session start, not only at
+    // its first prompt. When no payload is coming (manual runs, bare
+    // spawns) the read is skipped and the line keeps the old shape: a line
+    // only when pending mail exists for registered sessions in this project.
+    const hookInput = await readHookInput("reminder");
+    const hookSessionID = (hookInput?.session_id as string | undefined) ?? (hookInput?.conversation_id as string | undefined);
+    const chatLine = await chatHookLine(hookSessionID, hookInput?.transcript_path as string | undefined);
+    // Claude Code identity anchor: hooks and the MCP server are children of
+    // the same claude process, so recording (parent pid -> session) lets the
+    // server resolve the caller without trusting the model's `as`. Recorded
+    // only for payloads with session_id (Claude Code) - Cursor's hooks come
+    // from a shared extension host where ppid is ambiguous. CLAUDE_CODE_
+    // SESSION_ID env in the server process is the spawn-time fallback.
+    if (hookInput?.session_id && chatLine) {
+      try {
+        db.recordChatHostPid(process.ppid, mcpSessionID(String(hookInput.session_id)));
+      } catch (err) {
+        console.error(`[thatch] chat host-pid anchor failed: ${err}`);
+      }
+    }
     const reminder = claudeSessionStartReminder(repo, hygiene) + (chatLine ? `\n\n${chatLine}` : "");
     if (isJson) {
       console.log(JSON.stringify({ additional_context: reminder }));
@@ -767,8 +833,20 @@ switch (command) {
       printSkills(result);
       console.log();
       if (result.mcpAddCommand) {
-        console.log("To register the MCP server globally, run:");
-        console.log(`  ${result.mcpAddCommand}`);
+        // Global setup cannot write ~/.claude.json directly, so run the
+        // registration on the user's behalf. Idempotent: an existing
+        // registration is left alone; a missing or failing claude CLI
+        // falls back to printing the manual command.
+        const reg = await registerClaudeMcpServer(thatchBin);
+        if (reg.status === "registered") {
+          console.log(`  MCP server:    ${reg.detail}`);
+        } else if (reg.status === "already-registered") {
+          console.log(`  MCP server:    already registered (claude mcp get thatch to inspect)`);
+        } else {
+          console.log("To register the MCP server globally, run:");
+          console.log(`  ${result.mcpAddCommand}`);
+          console.log(`  (${reg.detail})`);
+        }
         console.log();
       }
       console.log("Restart Claude Code for the changes to take effect.");
@@ -806,6 +884,7 @@ switch (command) {
     // is not delayed waiting for an exit code-driven message.
     try {
       const raw = await Bun.stdin.text();
+      logHookPayload("buffer-batch", raw);
       const data = JSON.parse(raw) as { session_id?: string; tool_calls?: unknown[] };
       if (data.session_id && Array.isArray(data.tool_calls)) {
         const { appendBatch } = await import("../src/extract-queue");
@@ -826,6 +905,7 @@ switch (command) {
     // so we try the most likely candidates.
     try {
       const raw = await Bun.stdin.text();
+      logHookPayload("buffer-tool", raw);
       const data = JSON.parse(raw) as {
         conversation_id?: string;
         session_id?: string;
@@ -870,9 +950,11 @@ switch (command) {
     const isJson = args.includes("--json");
     try {
       const raw = await Bun.stdin.text();
+      logHookPayload("flush-tools", raw);
       const data = JSON.parse(raw) as {
         session_id?: string;
         conversation_id?: string;
+        transcript_path?: string;
         prompt?: string;
         message?: string;
         text?: string;
@@ -901,7 +983,17 @@ switch (command) {
       // 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);
+      const chatLine = await chatHookLine(sessionID, data.transcript_path);
+      // Claude Code identity anchor (see reminder case): record the
+      // parent-process mapping for session_id-bearing (Claude Code)
+      // payloads; Cursor's conversation_id stays on the `as` path.
+      if (data.session_id && chatLine && sessionID) {
+        try {
+          db.recordChatHostPid(process.ppid, mcpSessionID(sessionID));
+        } catch (err) {
+          console.error(`[thatch] chat host-pid anchor failed: ${err}`);
+        }
+      }
 
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
@@ -973,6 +1065,91 @@ switch (command) {
     break;
   }
 
+  case "chat-notify": {
+    // Stop hook for BOTH MCP hosts; the payload shape tells them apart:
+    // Claude Code sends session_id (+ stop_hook_active, background_tasks),
+    // Cursor sends conversation_id (+ status, loop_count).
+    //
+    // Output shapes: Cursor consumes { followup_message } (auto-submitted
+    // as the next user message); Claude Code consumes hookSpecificOutput.
+    // additionalContext on Stop - a reminder that continues the turn,
+    // rendered as hook feedback rather than a hook error. Pointer-only:
+    // sender names and a count, never bodies (bodies flow only through
+    // the framed chat_read). The nudge text carries the system-
+    // notification framing because a follow-up arrives as user input.
+    try {
+      const hookInput = await readHookInput("chat-notify");
+      if (!chatEnabled(loadConfig(dbPath).config)) {
+        console.log("{}");
+        break;
+      }
+      const claudeID = typeof hookInput?.session_id === "string" && hookInput.session_id ? String(hookInput.session_id) : null;
+      const cursorID = typeof hookInput?.conversation_id === "string" && hookInput.conversation_id ? String(hookInput.conversation_id) : null;
+
+      // Host-specific loop guards.
+      if (claudeID) {
+        // Never fight the host's loop protections: a stop-hook continuation
+        // already in flight ends the turn, and a session paused on
+        // background work gets its wake when that work's turn ends -
+        // injecting now would interject mid-flight (the mid-turn injection
+        // incident class).
+        if (hookInput?.stop_hook_active === true) {
+          console.log("{}");
+          break;
+        }
+        if (Array.isArray(hookInput?.background_tasks) && hookInput.background_tasks.length > 0) {
+          console.log("{}");
+          break;
+        }
+      } else if (cursorID) {
+        // Cursor: never auto-continue an aborted or errored turn (the
+        // user's stop key wins).
+        if (hookInput?.status !== "completed") {
+          console.log("{}");
+          break;
+        }
+      } else {
+        console.log("{}");
+        break;
+      }
+
+      // Lookup, not ensure-register: registration exists by the time stop
+      // fires (the prompt hooks anchored the conversation), and minting
+      // rows from contexts we do not understand is how the throwaway
+      // sessionStart identities happened.
+      const anchor = mcpSessionID(claudeID ?? cursorID!);
+      if (!db.findChatSession(anchor)) {
+        console.log("{}");
+        break;
+      }
+      const pending = db
+        .pendingChatNotifications([anchor], isoMinutesAgo(CHAT_RENUDGE_MINUTES))
+        .filter((m) => m.to_session === anchor);
+      if (pending.length === 0) {
+        console.log("{}");
+        break;
+      }
+      const senders = [
+        ...new Set(pending.map((m) => renderChatParticipant(m.from_name, m.from_session))),
+      ];
+      // Stamp before emitting: the re-nudge window (not the model's
+      // obedience) bounds repeats when the mail goes ignored.
+      db.markChatDelivered(pending.map((m) => m.id));
+      const nudge = chatNotificationNudge(senders, pending.length);
+      console.log(
+        JSON.stringify(
+          claudeID
+            ? { hookSpecificOutput: { hookEventName: "Stop", additionalContext: nudge } }
+            : { followup_message: nudge },
+        ),
+      );
+    } catch (err) {
+      console.error(`[thatch chat-notify] failed: ${err}`);
+      console.log("{}");
+    }
+    break;
+  }
+
   case "flush-predictions": {
     // UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor) hook.
     // Standalone prediction fire: queries the sideband for scored

package/docs/dev/README.md

@@ -90,6 +90,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |
 | `seed-behaviors.ts` | Default behavior seeding on first run. Populates starter self-discipline rules. |
 | `vector-math.ts` | `blobToVector` and `cosineSimilarity` helpers used across the codebase. |
+| `debug.ts` | Opt-in diagnostic logging (`THATCH_DEBUG`) to `debug.log` beside the database, never to the host's stdout/stderr (invisible inside the TUI; would leak into the quality gate from tests). Lines are `<iso> [feature:aspect] msg`; the env var is `1`/`all`/`*` for everything or a comma-separated list of tag filters matching a whole tag or its feature part. Add a tagged line wherever a live harness might need to answer "what did the plugin actually see here?" - the first consumer is `chat:startup`, which records the resolved `-s` session and every registration guard. |
 
 ## Plugin hooks
 
@@ -338,7 +339,7 @@ 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, topic, project, host_kind, registered_at, last_seen, auto)`,
+  `chat_sessions(session_id PK, name UNIQUE COLLATE NOCASE, topic, project, host_kind, registered_at, last_seen, auto, worktree)`,
   `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.
@@ -382,6 +383,12 @@ alone to check docs without the test suite. Run `mise run typecheck` for
 `tsc` alone (uses `tsconfig.check.json`, which includes the test files that
 the build's `tsconfig.json` excludes).
 
+To watch what a live harness's plugin actually sees at init, launch opencode
+with `THATCH_DEBUG=chat` (or `=1` for every tag) and tail
+`~/.config/thatch/debug.log`. The env var must be set on the `opencode`
+process itself: the plugin runs in a worker thread that inherits the
+process environment but not its argv.
+
 ## Release
 
 ```bash

package/docs/dev/features/cli.md

@@ -49,24 +49,22 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 - `chat list` renders the roster as aligned columns under a header row
   (NAME/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout is a TTY
   (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
-  text). Status reuses the `isStale()` staleness convention.
-- `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. On a TTY, sent bodies render as markdown via
-  an external renderer (`glow`, then `gum format`; plain fallback):
-  selection (`selectChatBodyRenderer()`) and body cleanup
-  (`cleanRenderedBody()`) live in `src/chat.ts`, unit-tested there;
-  `bin/thatch` owns the TTY/NO_COLOR gate, the once-per-process cache,
-  and the spawn. The card renderer is
-  `formatChatTailCard()` (optional `renderBody` hook; the read-event
-  clip is never rendered) 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;
+  text). Rows are split into Active and Stale sections by
+  `splitChatRoster()`; the status column is `chatLiveness()`'s verdict
+  (`fresh`/`stale` for opencode rows, `active`/`idle` for MCP rows).
+- `chat tail` follows the message stream as JSONL: one `ChatTailEvent`
+  per line via `formatChatTailJsonl()` (a bare `JSON.stringify`; no ANSI,
+  no markdown rendering, no local-time conversion - the tail is a log for
+  `jq` and `grep`). `sent` and `read` are separate events linked by the
+  message `id`; broadcast fan-out is one `sent` per recipient with
+  `broadcast: true` and the real `to`. Event shaping is `chatTailDiff()`
+  in `src/chat.ts`, unit-tested there. `--once` prints one snapshot and
+  exits; the snapshot includes a `read` event for every shown message
+  whose `read_at` is set, sorted by time, so it is the same log a follow
+  would have accumulated.
+- The backlog prints 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
+  state from every feed row (so the limit hides lines, 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