@jeffober/thatch 0.1.40 → 0.1.42

package/bin/thatch

@@ -10,6 +10,8 @@ import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
+import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailCard, CHAT_TAIL_SEPARATOR, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, isStale, CHAT_STALE_MINUTES, mcpSessionID, type ChatTailFilter } from "../src/chat";
+import { chatEnabled, loadConfig } from "../src/config";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -33,7 +35,7 @@ function usage(): never {
   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 flush-predictions [--json] Query predictions for the prompt (hook only)
-  thatch setup --claude [--cursor] [--global]
+  thatch setup --claude [--cursor] [--local|--global]
                                    Install config + instructions + hooks + skills
   thatch session list -s <id> [--after T] [--before T]
                                    JSONL timeline of a session's parts (one line per part)
@@ -44,6 +46,18 @@ 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 tail [--once] [--limit N|all] [--match RE]
+                   [--from NAME] [--to NAME] [--since DT] [--until DT]
+                                   Follow cross-session chat: sent and read
+                                   events. The backlog shows the last
+                                   ${CHAT_TAIL_DEFAULT_LIMIT} messages
+                                   (--limit N or --limit all to override).
+                                   --match filters message bodies
+                                   (repeatable, ANDed); --from/--to filter
+                                   participant names; --since/--until bound
+                                   the window ("YYYY-MM-DD [HH:MM]" local
+                                   time). Filters apply to follow mode too.
 
 Stores default to the repo detected from git remote. Use "global" for the
 global store. Use "all" with search to search project + global together.`);
@@ -58,13 +72,75 @@ async function defaultStore(): Promise<string> {
   }
 }
 
+/**
+ * Builds the chat-mail hook line for the given project. With a hook
+ * session ID (Claude Code/Cursor pass one in the hook's stdin JSON), it
+ * first ensures the caller is registered - the host's assigned identity -
+ * and prints that identity plus the caller's own unread count, so the
+ * model learns who it is on every prompt without a tool call. Without a
+ * session ID it keeps the old shape: a line only when pending mail exists
+ * for registered sessions in the project, naming the addressees.
+ */
+async function chatHookLine(hookSessionID?: string): Promise<string> {
+  // Disabled chat prints nothing: the hook line must not advertise a
+  // feature the user turned off (the tools refuse, the poller never
+  // starts, the prompt section omits chat).
+  if (!chatEnabled(loadConfig(dbPath).config)) return "";
+  let repo: string | null = null;
+  try {
+    repo = await detectRepo();
+  } catch {
+    return "";
+  }
+
+  if (hookSessionID) {
+    // Ensure-register: idempotent, so every prompt re-touches liveness and
+    // the first prompt of a conversation mints the assigned name. This is
+    // the MCP identity anchor - the session ID is stable per conversation,
+    // so re-registering finds the same row and name.
+    const sessionID = mcpSessionID(hookSessionID);
+    // The leave tombstone blocks this ensure: chat_unregister must outlive
+    // the turn that issued it, on MCP hosts as on opencode. The line is
+    // the standing signal - it repeats every prompt until the model
+    // rejoins, and it says plainly that rejoining mints a fresh identity,
+    // because the old one is closed for good (assigned names are never
+    // reused, so a tombstoned identity cannot be resurrected by a later
+    // register).
+    if (db.hasChatLeaveTombstone(sessionID) && !db.chatLeaveSuperseded(sessionID, repo)) {
+      return `[thatch] chat: this conversation left the chat directory (chat_unregister) and will not receive mail. If the user asks to rejoin, call thatch_chat_register with no arguments - that mints a fresh identity; the old one stays closed.`;
+    }
+    db.registerChatSession(sessionID, repo, null, "mcp");
+    const me = db.findChatSession(sessionID);
+    if (!me) return "";
+    const mine = db.unreadChatCount(sessionID);
+    const pendingOthers = db
+      .chatPendingByProject(repo)
+      .filter((p) => p.name !== me.name);
+    const others = pendingOthers.length > 0
+      ? ` Others in this project with unread mail: ${pendingOthers.map((p) => `${p.name} (${p.pending})`).join(", ")}.`
+      : "";
+    const mailbox = mine > 0 ? `${mine} unread message(s) for you` : "no unread mail for you";
+    return `[thatch] chat: you are ${me.name} (${mailbox}).${others}`;
+  }
+
+  const pending = db.chatPendingByProject(repo);
+  if (pending.length === 0) return "";
+  const parts = pending.map((p) => `${p.name} (${p.pending})`);
+  return `[thatch] chat: unread message(s) for ${parts.join(", ")} - the addressee should call chat_read`;
+}
+
 /**
  * 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
  * flush-tools to surface version skew and update-available notices on
- * every UserPromptSubmit, regardless of which tier fired.
+ * every UserPromptSubmit, regardless of which tier fired. The chat hook
+ * line, when present, is appended last (the identity/mail check is the
+ * last thing the model reads before the nudge body).
  */
-function emit(output: string, versionWarning: string | null, isJson: boolean): void {
+function emit(output: string, versionWarning: string | null, isJson: boolean, chatLine = ""): void {
+  if (chatLine) {
+    output = `${output}\n\n${chatLine}`;
+  }
   if (versionWarning) {
     output = `[thatch] ${versionWarning}\n\n${output}`;
   }
@@ -93,17 +169,42 @@ function parseTimeBound(value: string, flag: string): number {
   return parsed;
 }
 
-/** Reads a flag's value (-flag value or --flag=value forms). */
+/** Reads a flag's value (-flag value or --flag=value forms). A flag given
+ *  with no value is a typo, not a default - it dies loudly so `--until`
+ *  at the end of a command line cannot silently disable the bound. */
 function flagValue(flags: string[], ...names: string[]): string | undefined {
   for (let i = 0; i < flags.length; i++) {
     for (const name of names) {
-      if (flags[i] === name) return flags[i + 1];
+      if (flags[i] === name) {
+        if (flags[i + 1] === undefined) {
+          console.error(`error: ${name} expects a value`);
+          process.exit(1);
+        }
+        return flags[i + 1];
+      }
       if (flags[i]?.startsWith(`${name}=`)) return flags[i]!.slice(name.length + 1);
     }
   }
   return undefined;
 }
 
+/** Collects every occurrence of a repeatable flag, dying on a dangling one. */
+function flagValues(flags: string[], ...names: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < flags.length; i++) {
+    for (const name of names) {
+      if (flags[i] === name) {
+        if (flags[i + 1] === undefined) {
+          console.error(`error: ${name} expects a value`);
+          process.exit(1);
+        }
+        out.push(flags[i + 1]);
+      } else if (flags[i]?.startsWith(`${name}=`)) out.push(flags[i]!.slice(name.length + 1));
+    }
+  }
+  return out;
+}
+
 function openSessionDb(): SessionDB {
   const path = resolveOpencodeDbPath();
   if (!path) {
@@ -219,6 +320,175 @@ 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`;
+}
+
+async function chatCommand(rest: string[]): Promise<void> {
+  const [sub, ...restArgs] = rest;
+
+  switch (sub) {
+    case "list": {
+      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;
+      }
+      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("  "));
+      }
+      break;
+    }
+
+    case "tail": {
+      const onceOnly = restArgs.includes("--once");
+      // Parse and validate everything up front: a bad regex or date must
+      // fail before any cards print, not mid-follow.
+      const matches = flagValues(restArgs, "--match").map((pattern) => {
+        try {
+          return new RegExp(pattern);
+        } catch {
+          console.error(`error: --match is not a valid regular expression: "${pattern}"`);
+          process.exit(1);
+        }
+      });
+      const limitArg = flagValue(restArgs, "--limit");
+      let limit: number | null = CHAT_TAIL_DEFAULT_LIMIT;
+      if (limitArg !== undefined) {
+        if (limitArg === "all") limit = null;
+        else if (!/^\d+$/.test(limitArg)) {
+          console.error(`error: --limit expects a positive integer or "all", got "${limitArg}"`);
+          process.exit(1);
+        } else limit = Number(limitArg);
+        if (limit !== null && limit < 1) {
+          console.error(`error: --limit expects a positive integer or "all", got "${limitArg}"`);
+          process.exit(1);
+        }
+      }
+      let sinceMs: number | null = null;
+      let untilMs: number | null = null;
+      try {
+        const since = flagValue(restArgs, "--since");
+        const until = flagValue(restArgs, "--until");
+        if (since !== undefined) sinceMs = parseChatTimeBound(since, "--since");
+        if (until !== undefined) untilMs = parseChatTimeBound(until, "--until");
+      } catch (err) {
+        console.error(`error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      if (sinceMs !== null && untilMs !== null && sinceMs >= untilMs) {
+        console.error("error: --since is not before --until; the window is empty");
+        process.exit(1);
+      }
+      const fromName = flagValue(restArgs, "--from");
+      const toName = flagValue(restArgs, "--to");
+      const filter: ChatTailFilter = {
+        matches,
+        fromSubstr: fromName !== undefined ? [fromName] : [],
+        toSubstr: toName !== undefined ? [toName] : [],
+        sinceMs,
+        untilMs,
+      };
+
+      // Diff state: one entry per seen message id holding its read_at, so
+      // each poll emits only new messages and newly-read rows. The diff
+      // and backlog logic lives in src/chat.ts (chatTailDiff,
+      // chatTailBacklog), unit-tested there. The backlog seeds the state
+      // from every feed row, so the limit hides cards, not history.
+      let state: Map<number, string | null>;
+      let firstFollowEvent = true;
+
+      // Follow mode holds the handle open until Ctrl-C. The finally below
+      // closes it on every exit path except the SIGINT handler's, which
+      // is why the handler closes it itself: process.exit does not unwind
+      // finally blocks (closing twice is harmless).
+      try {
+        // First pass: render the backlog as cards, then follow unless
+        // --once or the --until window has already closed (a closed
+        // window has no future events to follow). The backlog fetch gets
+        // the same friendly failure treatment as follow polls: a locked
+        // or missing database should say so, not die with a stack trace.
+        let backlog;
+        try {
+          backlog = chatTailBacklog(db.chatMessageFeed(), filter, limit);
+        } catch (err) {
+          console.error(`[thatch chat tail] feed query failed: ${err}`);
+          console.error("The database may be locked or missing; exiting.");
+          return;
+        }
+        state = backlog.state;
+        if (backlog.elided > 0) {
+          // The elision note goes to stderr so stdout stays a clean card
+          // stream for pipes.
+          console.error(
+            `[thatch chat tail] showing last ${backlog.events.length} of ${backlog.elided + backlog.events.length} messages (--limit N, --limit all)`,
+          );
+        }
+        console.log(backlog.events.map(formatChatTailCard).join(`\n\n${CHAT_TAIL_SEPARATOR}\n\n`));
+        if (onceOnly || (filter.untilMs !== null && filter.untilMs <= Date.now())) break;
+
+        process.on("SIGINT", () => {
+          db.close();
+          process.exit(0);
+        });
+        for (;;) {
+          await Bun.sleep(2000);
+          try {
+            // Follow polls re-filter the live feed: matching messages
+            // surface as they arrive, non-matching ones stay invisible.
+            for (const event of chatTailDiff(state, filterChatTailRows(db.chatMessageFeed(), filter)).events) {
+              // Separate follow-mode cards from whatever came before.
+              if (firstFollowEvent && backlog.events.length > 0) console.log(`\n${CHAT_TAIL_SEPARATOR}\n`);
+              firstFollowEvent = false;
+              console.log(formatChatTailCard(event));
+            }
+          } catch (err) {
+            // The surface's whole job is watching a shared, mutable file;
+            // a feed failure should say so, not die with a stack trace.
+            console.error(`[thatch chat tail] feed query failed: ${err}`);
+            console.error("The database may be locked or missing; exiting.");
+            return;
+          }
+          // The window check runs after the poll, so a message created
+          // inside the window but landed during the final sleep is still
+          // displayed; anything inserted after this poll has a created_at
+          // past the bound and is filtered by the window anyway.
+          if (filter.untilMs !== null && Date.now() >= filter.untilMs) break;
+        }
+      } finally {
+        db.close();
+        // The script tail also closes; closing twice is harmless and the
+        // early-return paths need this one.
+      }
+      break;
+    }
+
+    default:
+      usage();
+  }
+}
+
 switch (command) {
   case "--version":
   case "-v":
@@ -327,7 +597,11 @@ switch (command) {
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
-    const reminder = claudeSessionStartReminder(repo, hygiene);
+    // Chat mail check. Without a hook session ID (SessionStart does not
+    // read stdin) the line keeps the old shape: a line only when pending
+    // mail exists for registered sessions in this project.
+    const chatLine = await chatHookLine();
+    const reminder = claudeSessionStartReminder(repo, hygiene) + (chatLine ? `\n\n${chatLine}` : "");
     if (isJson) {
       console.log(JSON.stringify({ additional_context: reminder }));
     } else {
@@ -383,12 +657,19 @@ switch (command) {
 
   case "setup": {
     const isGlobal = args.includes("--global");
+    // --local is the default scope; accepted explicitly so the flag the
+    // user types always matches what the command does.
+    const isLocal = args.includes("--local");
     const isClaude = args.includes("--claude");
     const isCursor = args.includes("--cursor");
 
+    if (isGlobal && isLocal) {
+      console.error("Choose one scope: --local or --global.");
+      process.exit(1);
+    }
     if (!isClaude && !isCursor) {
       console.error("Specify at least one host: --claude and/or --cursor.");
-      console.error("Usage: thatch setup --claude [--cursor] [--global]");
+      console.error("Usage: thatch setup --claude [--cursor] [--local|--global]");
       process.exit(1);
     }
 
@@ -400,6 +681,22 @@ switch (command) {
     const thatchBin = thatchOnPath ?? resolve(process.argv[1] ?? process.execPath);
     const dir = projectDir();
 
+    // Shared reporting: where skills went and what the pass did, so an
+    // idempotent re-run still tells the user something true.
+    const printSkills = (result: { skills: { dir: string; added: unknown[]; updated: unknown[]; removed: string[]; unchanged: string[] }; otherScopeSkills: { dir: string; count: number } | null; global: boolean }) => {
+      const { added, updated, removed, unchanged } = result.skills;
+      console.log(`  Skills:        ${result.skills.dir}`);
+      console.log(`                 ${added.length} added, ${updated.length} updated, ${removed.length} removed, ${unchanged.length} unchanged`);
+      if (result.otherScopeSkills) {
+        const { dir: otherDir, count } = result.otherScopeSkills;
+        if (result.global) {
+          console.log(`  Note: ${count} thatch skills exist in ${otherDir} (project scope); --global does not update them.`);
+        } else {
+          console.log(`  Note: ${count} thatch skills remain in ${otherDir} (user scope; not updated by this run). Run setup with --global to refresh them, or remove them if this repo now owns its skills.`);
+        }
+      }
+    };
+
     if (isClaude) {
       const result = setupClaudeCode(thatchBin, isGlobal, dir);
 
@@ -410,10 +707,7 @@ switch (command) {
       }
       console.log(`  Instructions:  ${result.claudeMd}`);
       console.log(`  Hooks:         ${result.settings}`);
-      const skillsDir = result.skills[0]?.path
-        ? result.skills[0].path.split("/").slice(0, -1).join("/")
-        : "(no skills installed)";
-      console.log(`  Skills:        ${skillsDir} (${result.skills.length} files)`);
+      printSkills(result);
       console.log();
       if (result.mcpAddCommand) {
         console.log("To register the MCP server globally, run:");
@@ -432,10 +726,7 @@ switch (command) {
       console.log(`  MCP config:    ${result.mcpConfig}`);
       console.log(`  Instructions:  ${result.agentsMd}`);
       console.log(`  Hooks:         ${result.hooks}`);
-      const skillsDir = result.skills[0]?.path
-        ? result.skills[0].path.split("/").slice(0, -1).join("/")
-        : "(no skills installed)";
-      console.log(`  Skills:        ${skillsDir} (${result.skills.length} files)`);
+      printSkills(result);
       console.log();
       console.log("Restart Cursor for the changes to take effect.");
     }
@@ -447,6 +738,11 @@ switch (command) {
     break;
   }
 
+  case "chat": {
+    await chatCommand(args);
+    break;
+  }
+
   case "buffer-batch": {
     // PostToolBatch hook: append the batch's tool_calls to the session's
     // JSONL queue. Silent on success - no stdout - so the next model call
@@ -545,6 +841,10 @@ switch (command) {
       // flush-tools fires on every prompt, including conversational turns
       // with no tool calls.
       const versionWarning = detectSkew(dbPath) ?? readNpmCacheForUpdate(dbPath);
+      // Chat check: with a hook session ID this always prints the caller's
+      // assigned identity (and its unread count), so the model knows who it
+      // is before any chat tool call; with no mail the line says so.
+      const chatLine = await chatHookLine(sessionID);
 
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
@@ -556,7 +856,7 @@ switch (command) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
         const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
-        emit(output, versionWarning, isJson);
+        emit(output, versionWarning, isJson, chatLine);
         break;
       }
 
@@ -590,14 +890,14 @@ switch (command) {
 
         if (parts.length > 0) {
           const output = parts.join("\n\n");
-          emit(output, versionWarning, isJson);
+          emit(output, versionWarning, isJson, chatLine);
           break;
         }
       }
 
       // Tier 3: static write nudge.
       const output = claudeWriteNudge();
-      emit(output, versionWarning, isJson);
+      emit(output, versionWarning, isJson, chatLine);
     } catch (err) {
       console.error(`[thatch flush-tools] failed: ${err}`);
       try {

package/docs/dev/README.md

@@ -40,8 +40,11 @@ OpenCode plugin path
   ├── index.ts        → plugin entry: wires DB/model/extraction, registers tools + hooks
   ├── tools.ts        → thin opencode tool() wrappers over tool-defs
   ├── extraction.ts   → in-memory ring buffer + shared payload builders
-  └── watchers.ts     → in-memory watcher registry + poller (opencode-only,
-                        event-driven PR notifications delivered as prompts)
+  ├── watchers.ts     → in-memory watcher registry + poller (opencode-only,
+  │                     event-driven PR notifications delivered as prompts)
+  └── chat.ts         → cross-session chat: shared SQLite directory + inbox
+                        (ChatStore) and the per-process wake-up poller
+                        (ChatPoller, opencode-only)
 
 MCP server path
   ├── mcp.ts          → stdio JSON-RPC server: z.toJSONSchema() for tools/list,
@@ -54,7 +57,8 @@ MCP server path
                         CLAUDE.md / AGENTS.md, settings/hooks JSON, installs skills
 
 bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygiene|
-                        prime|buffer-batch|buffer-tool|flush-tools|flush-predictions|setup
+                        prime|buffer-batch|buffer-tool|flush-tools|flush-predictions|setup|
+                        session (archaeology)|chat (list|tail)
 ```
 
 ## Module responsibilities
@@ -75,9 +79,11 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `config.ts` | User config file (`~/.config/thatch/config.json`, beside the DB): Zod section schemas (strict — unknown keys fail validation), load with missing/invalid fallback to defaults, field-level merge, atomic save (temp + rename). Backs the `config_get`/`config_set` tools. |
 | `notify.ts` | Out-of-band notification dispatch: darwin (`osascript` banner + `/usr/bin/say` voice), linux (`notify-send` + `spd-say`/`espeak`), other platforms report unsupported. Injectable spawner (`CoreContext.spawner`) so tests never fire real commands. Backs the `notify_user` tool. |
 | `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
-| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches GitHub PRs and branches via `gh api` (injected `GhRunner`), diffs against last-seen state, queues pointer-only events per session, and delivers them through a plugin-supplied callback when the session is idle. Process-lifetime state by design - no SQLite. |
+| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Three sources: GitHub PRs and branches via `gh api` (injected `GhRunner`), and local shell commands via `bash -c` (injected `CommandRunner`) run as condition variables - only the exit code is read, never the command's output. Diffs against last-seen state, queues events (pointer data plus machine status like check conclusions and exit codes, never external content) per session, and delivers them through a plugin-supplied callback when the session is idle. The `pollSeconds` getter surfaces the poll cadence to tool output and notifications. Process-lifetime state by design - no SQLite. |
+| `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
+| `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. 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`), 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. |
 | `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. |
@@ -94,10 +100,10 @@ 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. |
 | `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++. 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. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
-| `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher delivery gate; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, and cancels the session's watchers. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
-| `dispose` | Stops the version checker and the watcher poller, closes the DB. |
+| `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). |
+| `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher and chat delivery gates; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events and pending chat mail (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, cancels the session's watchers, and unregisters it from the chat directory (the crash path — a dead process fires no event — is covered by heartbeat staleness). `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
+| `dispose` | Stops the version checker, the watcher poller, and the chat poller, closes the DB. |
 
 Hook failures are logged with a `[thatch]` prefix — never swallowed silently.
 Two of these hooks were dead for weeks because failures were invisible.
@@ -119,10 +125,12 @@ Two of these hooks were dead for weeks because failures were invisible.
 5. **Store creation is implicit.** First `remember` to a new store creates it.
 6. **Default recall scope is repo + global.** The tool layer hardcodes this.
 7. **Skills are plugin-owned files.** Installed to
-   `$XDG_CONFIG_HOME/opencode/skills` (opencode), `~/.claude/skills/`
-   (Claude Code), or `~/.cursor/skills/` (Cursor) — never into the
-   worktree; drifted content is overwritten on plugin init or re-running
-   `thatch setup`. Skills are split into `SHARED_SKILLS` (work on all
+   `$XDG_CONFIG_HOME/opencode/skills` (opencode); for MCP hosts,
+   scope-dependent — the repo's `.claude/skills/` or `.cursor/skills/`
+   for project-local `thatch setup`, `~/.claude/skills/` or
+   `~/.cursor/skills/` for `--global`. Drifted content is overwritten
+   on plugin init or re-running `thatch setup`. Skills are split into
+   `SHARED_SKILLS` (work on all
    three hosts) and `OPENCODE_ONLY_SKILLS` (require sub-agent support,
    not installed for Claude Code or Cursor). The opencode plugin
    installs both arrays; `thatch setup --claude` and `--cursor` install
@@ -328,12 +336,18 @@ behavior cycle (agent-driven, self-graded)
   `behavior_matchers(id PK, store, description, embedding BLOB, model, created_at, updated_at)`,
   `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)`.
+  `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_messages(id PK AUTOINCREMENT, from_session, to_session, body, created_at, delivered_at, read_at, via_broadcast)`,
+  `chat_name_counters(base PK, next)` - per-base counters for assigned chat names; only ever increments.
+  `chat_leave_tombstones(session_id PK, left_at)` - explicit leaves; suppresses auto-registration until chat_register rejoins.
 - `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing
   databases by an idempotent column migration at init (`PRAGMA table_info` +
   `ALTER TABLE`). The `archived` column is `INTEGER NOT NULL DEFAULT 0` (0 =
   live, 1 = archived); search, dedup, and staleness queries all exclude
-  archived entries by default.
+  archived entries by default. A second init migration rebuilds a
+  pre-NOCASE `chat_sessions` table to enforce case-insensitive name
+  uniqueness (see [features/database.md](features/database.md)).
 - Embeddings are raw Float32Array bytes. Serialization honors
   `byteOffset`/`byteLength` — transformers.js can return views into larger
   tensor buffers, and serializing the whole backing buffer corrupts vectors.

package/docs/dev/features/README.md

@@ -27,6 +27,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
 | [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 |
 | [setup.md](setup.md) | Setup system (markers, checkSetup, auto-refresh, binary resolution) |
 | [cli.md](cli.md) | CLI (subcommands, environment variables) |

package/docs/dev/features/cli.md

@@ -1,11 +1,9 @@
 # CLI (bin/thatch)
 
-The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, MCP server startup, hook commands for MCP hosts, and the setup installer.
+The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, MCP server startup, hook commands for MCP hosts, the setup installer, session archaeology over the opencode database, and a read-only window on the cross-session chat directory.
 
 ## Subcommands
 
-15 subcommands:
-
 | Command | Args | Flags | Stdin | Purpose |
 |---------|------|-------|-------|---------|
 | `stores` | none | none | none | List all store names |
@@ -22,6 +20,9 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 | `flush-tools [--json]` | none | `--json` | JSON | Peek queue + extraction/recall/prediction/behavior/write nudge |
 | `flush-predictions [--json]` | none | `--json` | JSON | Standalone prediction-only nudge |
 | `setup --claude [--cursor] [--global]` | none | `--claude`, `--cursor`, `--global` | none | Install config + instructions + hooks + skills |
+| `session list/get/transcript/search` | per subcommand | `-s/--session`, `--id`, `--after`, `--before`, `--regex`, `--limit` | none | Read-only archaeology on the opencode session database (JSONL output) |
+| `chat list` | none | none | none | Registered chat sessions: name, human-readable age, project, topic |
+| `chat tail` | none | `--once`, `--limit N\|all`, `--match RE` (repeatable), `--from NAME`, `--to NAME`, `--since DT`, `--until DT` | none | Follow cross-session chat: sent and read events. Backlog defaults to the last 20 messages; filters apply to follow mode too. |
 | (unknown) | none | none | none | Print usage, exit 1 |
 
 ## Global behavior
@@ -41,6 +42,32 @@ Runs the thatch-project-primer skill via an external CLI. Searches `PATH` in ord
 
 Inherits stdio, exits with the child's exit code. Errors and exits 1 if none found.
 
+## chat
+
+Read-only window on the cross-session chat directory ([cross-session-chat.md](cross-session-chat.md)):
+
+- `chat list` renders the roster: display name, human-readable age since the
+  last heartbeat, project, and topic when set.
+- `chat tail` follows the message stream as styled cards: label chips,
+  colored names, dimmed timestamps, topic annotations after names, and a
+  drawn rule between cards. The card renderer is `formatChatTailCard()`
+  and the event shaping is `chatTailDiff()` in `src/chat.ts`, unit-tested
+  there; the single-line `formatChatTailEvent()` remains for tests and
+  compact contexts. `--once` prints one snapshot and exits, because a
+  snapshot has no previous state to diff read events against.
+- The backlog renders only the last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages;
+  `chatTailBacklog()` in `src/chat.ts` filters the feed, seeds the diff
+  state from every feed row (so the limit hides cards, not history, and a
+  mid-follow rename or unregister cannot resurface old rows as sent
+  events), and reports the elided count for
+  the CLI's stderr note. `filterChatTailRows()` ANDs body regexes
+  (`--match`, repeatable), rendered-name substrings (`--from`/`--to`,
+  case-insensitive), and a half-open `--since`/`--until` window on
+  `created_at`; the same filter applies to follow polls, so non-matching
+  messages stay invisible (their read events too). A `--until` in the past
+  exits after the backlog; one in the future follows until the window
+  closes. `parseChatTimeBound()` accepts `YYYY-MM-DD [HH:MM]` local time.
+
 ## Environment variables
 
 | Variable | Purpose | Default |
@@ -59,7 +86,7 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 
 ## Source files
 
-- `bin/thatch` — the CLI (Bun script, 486 lines)
+- `bin/thatch` — the CLI (Bun script)
 - `bin/release` — release helper (bash, separate from the main CLI)
 
 ## Interactions with other features
@@ -70,6 +97,8 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 - Extraction ([extraction.md](extraction.md)): `buffer-batch`, `buffer-tool`, `flush-tools` subcommands
 - Hygiene ([hygiene.md](hygiene.md)): `hygiene`, `reminder` subcommands
 - Multi-host ([multi-host.md](multi-host.md)): `mcp` subcommand starts the MCP server for Claude Code and Cursor
+- Session archaeology: the `session` subcommand group (see the table above) reads the opencode session database via `src/session-db.ts`
+- Cross-session chat ([cross-session-chat.md](cross-session-chat.md)): the `chat` subcommand group reads the shared chat directory and inbox
 
 ## Key invariants