@jeffober/thatch 0.1.42 → 0.1.44

package/README.md

@@ -99,13 +99,22 @@ 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
   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

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/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, mcpSessionID, 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
@@ -324,15 +404,56 @@ 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 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 { 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"));
+  }
+  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"));
+  }
+  return parts.join("\n\n");
 }
 
 async function chatCommand(rest: string[]): Promise<void> {
@@ -345,26 +466,14 @@ async function chatCommand(rest: string[]): Promise<void> {
         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.
+      // fail before any lines print, not mid-follow.
       const matches = flagValues(restArgs, "--match").map((pattern) => {
         try {
           return new RegExp(pattern);
@@ -415,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
@@ -439,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(formatChatTailCard).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", () => {
@@ -458,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));
+              console.log(formatChatTailJsonl(event));
             }
           } catch (err) {
             // The surface's whole job is watching a shared, mutable file;
@@ -597,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 }));
@@ -710,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.");
@@ -749,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");
@@ -769,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;
@@ -813,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;
@@ -844,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.
@@ -916,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
 
@@ -99,6 +100,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,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.
@@ -381,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/README.md

@@ -25,7 +25,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
 | [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) |
+| [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |
 | [watchers.md](watchers.md) | Event-driven notifications (in-memory registry, background poller, PR watching) |
 | [cross-session-chat.md](cross-session-chat.md) | Cross-session chat (shared SQLite directory and inbox, per-process wake-up delivery) |
 | [notifications.md](notifications.md) | Out-of-band notification (banner + voice) and the user config file |