@jeffober/thatch 0.1.43 → 0.1.45

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, sortChatRoster, 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,17 @@ 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 [--stale N|all]  Registered chat sessions, grouped Active/Stale:
+                                    name, age, status, project, topic.
+                                    --stale N (days) hides stale sessions
+                                    older than N; default 1. --stale all
+                                    shows every stale session.
   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 +90,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 +108,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 +157,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 +411,67 @@ 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.
+ * staleCapMs bounds how old a stale row is displayed (null = no bound);
+ * rows past the cap collapse into a muted hidden-count note so the reader
+ * knows rows exist that the window left out.
+ * 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 {
+function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null): 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, staleHidden } = splitChatRoster(sortChatRoster(sessions), Date.now(), staleCapMs);
+  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 || staleHidden > 0) {
+    const lines = [paint("1", "# Stale Sessions")];
+    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.`;
+      lines.push(paint("3;90", explainer), renderTable(stale));
+    }
+    if (staleHidden > 0) {
+      lines.push(
+        paint(
+          "3;90",
+          `${staleHidden} older stale session${staleHidden === 1 ? "" : "s"} hidden; --stale N widens the window to N days, --stale all shows everything.`,
+        ),
+      );
+    }
+    parts.push(lines.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> {
@@ -409,19 +479,33 @@ async function chatCommand(rest: string[]): Promise<void> {
 
   switch (sub) {
     case "list": {
+      // --stale N bounds how old a stale row the roster displays, in days
+      // (fractions allowed); the default of one day keeps long-dead
+      // sessions from burying the fresh signal. --stale all restores the
+      // unbounded view. A bad value dies loudly rather than silently
+      // shrinking the roster.
+      const staleArg = flagValue(restArgs, "--stale");
+      let staleCapMs: number | null = 24 * 60 * 60 * 1000;
+      if (staleArg !== undefined) {
+        if (staleArg === "all") staleCapMs = null;
+        else if (!/^\d+(\.\d+)?$/.test(staleArg) || Number(staleArg) <= 0) {
+          console.error(`error: --stale expects a positive number of days or "all", got "${staleArg}"`);
+          process.exit(1);
+        } else staleCapMs = Number(staleArg) * 24 * 60 * 60 * 1000;
+      }
       const sessions = db.listChatSessions();
       if (sessions.length === 0) {
         console.log("No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register.");
         break;
       }
-      console.log(formatChatRoster(sessions));
+      console.log(formatChatRoster(sessions, staleCapMs));
       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.
+      // fail before any lines print, not mid-follow.
       const matches = flagValues(restArgs, "--match").map((pattern) => {
         try {
           return new RegExp(pattern);
@@ -472,16 +556,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 +579,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 +598,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 +734,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 }));
@@ -765,10 +863,25 @@ switch (command) {
       console.log(`  Instructions:  ${result.claudeMd}`);
       console.log(`  Hooks:         ${result.settings}`);
       printSkills(result);
+      if (result.commands.length > 0) {
+        console.log(`  Commands:      ${result.commands.length} written (${result.commands.map((p) => p.split("/").pop()).join(", ")})`);
+      }
       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 +919,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 +940,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 +985,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 +1018,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 +1100,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

@@ -24,7 +24,8 @@ Shared core
   ├── embeddings.ts   → embedding model via transformers.js
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
-  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, CLAUDE.md instructions
+  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
+  ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
   ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
@@ -83,13 +84,15 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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. 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. |
+| `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. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
+| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
 | `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]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `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 +341,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 +385,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/README.md

@@ -23,6 +23,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
 | [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
+| [commands.md](commands.md) | Slash commands (on-demand actions from shared prompt cores, wrap-ups, host sync) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |