@jeffober/thatch 0.1.39 → 0.1.41

package/bin/thatch

@@ -10,6 +10,7 @@ import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
+import { chatTailDiff, formatChatTailEvent, isStale, CHAT_STALE_MINUTES } from "../src/chat";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -33,7 +34,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 +45,9 @@ 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]        Follow cross-session chat: sent and read events
+                                   (--once prints current state and exits)
 
 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 +62,39 @@ async function defaultStore(): Promise<string> {
   }
 }
 
+/**
+ * Builds the chat-mail hook line for the given project: one line when
+ * unread mail is waiting for registered sessions, naming the addressee
+ * sessions. Empty string when the project has no chat state or no pending
+ * mail - a session that never registered never sees a chat line at all,
+ * and the line is about the addressee, not about the reader, so there is
+ * nothing for an unregistered model to hallucinate.
+ */
+async function chatHookLine(): Promise<string> {
+  let repo: string | null = null;
+  try {
+    repo = await detectRepo();
+  } catch {
+    return "";
+  }
+  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 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}`;
   }
@@ -219,6 +249,92 @@ 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 with thatch_chat_register from opencode.");
+        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");
+      // Diff state: one entry per seen message id holding its read_at, so
+      // each poll emits only new messages and newly-read rows. The diff
+      // logic lives in src/chat.ts (chatTailDiff), unit-tested there.
+      const state = new Map<number, string | null>();
+
+      // Follow mode holds the handle open until Ctrl-C; the finally below
+      // closes it on every exit path, including the SIGINT handler's.
+      try {
+        // First pass: print the backlog (every existing row as its sent
+        // line), then follow unless --once.
+        for (const event of chatTailDiff(state, db.chatMessageFeed()).events) {
+          if (event.kind === "sent") console.log(formatChatTailEvent(event));
+        }
+        if (onceOnly) break;
+
+        process.on("SIGINT", () => process.exit(0));
+        for (;;) {
+          await Bun.sleep(2000);
+          try {
+            for (const event of chatTailDiff(state, db.chatMessageFeed()).events) {
+              console.log(formatChatTailEvent(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;
+          }
+        }
+      } 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 +443,10 @@ switch (command) {
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
-    const reminder = claudeSessionStartReminder(repo, hygiene);
+    // Chat mail check: same gating as flush-tools - 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 +502,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 +526,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 +552,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 +571,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 +583,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 +686,9 @@ switch (command) {
       // flush-tools fires on every prompt, including conversational turns
       // with no tool calls.
       const versionWarning = detectSkew(dbPath) ?? readNpmCacheForUpdate(dbPath);
+      // Chat mail check: one line when pending mail exists for registered
+      // sessions in this project, empty string otherwise (see chatHookLine).
+      const chatLine = await chatHookLine();
 
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
@@ -556,7 +700,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 +734,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
@@ -76,8 +80,10 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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. |
+| `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
+| `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. `chat_register` without a name draws from it. |
 | `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,16 @@ 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, project, registered_at, last_seen)`,
+  `chat_messages(id PK AUTOINCREMENT, from_session, to_session, body, created_at, delivered_at, read_at)`.
 - `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/behavior-engine.md

@@ -78,9 +78,11 @@ Runs in a single DB transaction:
 
 1. **Matcher dedup** — finds an existing behavior matcher above cosine 0.85,
    else creates one.
-2. **Behavior dedup** — store-wide search for a near-identical behavior
-   (cosine >= 0.85). If found, links this matcher to it via an edge rather
-   than creating a duplicate row.
+2. **Behavior dedup** — search across the target store AND global for a
+   near-identical behavior (cosine >= 0.85). If found, links this matcher to
+   it via an edge rather than creating a duplicate row. The auto-fire nudge
+   scans both stores, so the write reinforces the existing row in its home
+   store and the result echoes where it landed.
 3. **New behavior** — creates behavior + edge + provenance entry tagged
    `codify`.
 4. Returns `[codified]` for a new behavior or `[linked]` for an existing one

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 [--once]` | none | `--once` | none | Follow cross-session chat: sent and read events (`--once` prints the backlog and exits) |
 | (unknown) | none | none | none | Print usage, exit 1 |
 
 ## Global behavior
@@ -41,6 +42,21 @@ 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 [--once]` follows the message stream. Sent lines have the shape
+  `[timestamp] from -> to: body` (broadcast rows render `broadcast` via the
+  `via_broadcast` marker); in follow mode, an inbox drain emits a read line
+  (`[timestamp] ${reader} read a message from ${sender}: preview` — the
+  reader is the recipient draining its inbox). The diff logic is
+  `chatTailDiff()`/`formatChatTailEvent()` in `src/chat.ts`, unit-tested
+  there; `--once` prints one snapshot and exits, because a snapshot has no
+  previous state to diff read events against.
+
 ## Environment variables
 
 | Variable | Purpose | Default |
@@ -59,7 +75,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 +86,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