@jeffober/thatch 0.1.40 → 0.1.41

package/README.md

@@ -66,7 +66,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 
 ## What's inside
 
-Thatch gives your agent three layers of persistent context:
+Thatch gives your agent:
 
 - **Memory** -- save, search, and recall knowledge across sessions with
   local embeddings (bge-small-en-v1.5) and SQLite. Every project gets its
@@ -92,8 +92,15 @@ Thatch gives your agent three layers of persistent context:
   only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
   background and prompts the session when comments, commits, CI results, or
   status changes arrive. Notifications carry pointer data only.
-- **Notifications + user config** -- the agent can ping you out-of-band when
-  a long-running outcome lands: a desktop banner, a spoken voice
+- **Cross-session chat** -- your agent sessions can message each other
+  (opencode, Claude Code, and Cursor; same machine). A session registers
+  under a unique name and topic, others see it in the directory, and
+  messages land in its inbox -- opencode sessions get woken with a prompt
+  when idle, other hosts see pending mail at their next prompt. Loop-safe:
+  messages are informational to the receiving agent, and wake prompts are
+  rate-capped.
+- **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
   hand-editable config file (`~/.config/thatch/config.json`) that the agent
   manages through `config_get`/`config_set` -- ask it to change your voice

package/artifacts/skills/thatch-code-review.md

@@ -105,7 +105,7 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
-9. **Mentorship** — peer-mentorship teaching lens: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No mentorship notes" and produces no findings.
+9. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
 
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
@@ -137,7 +137,7 @@ Confirmed LOW findings are mandatory in the final report, including mechanical f
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
-Mentorship notes (from the mentorship specialist) appear in a `### Mentorship notes` section after Highlights and before the confirmed findings. They are teaching-grade observations (existing helpers, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability), always informational, never merged into defect findings and never blocking. Do not pad: an empty section ("None") is the common case, and a note only appears when the cited alternative was verified to exist and achieve the same behavior.
+Technique notes (from the technique specialist) appear in a `### Technique notes` section after Highlights and before the confirmed findings. They are teaching-grade observations (existing helpers, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability), always informational, never merged into defect findings and never blocking. Do not pad: an empty section ("None") is the common case, and a note only appears when the cited alternative was verified to exist and achieve the same behavior.
 
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
@@ -145,10 +145,10 @@ Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For mentorship notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For technique notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, highlights (if any), mentorship notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, highlights (if any), technique notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
 8. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
 
 ## Specialist briefing template

package/artifacts/skills/thatch-review-synthesizer.md

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, mentorship). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -48,13 +48,13 @@ For each finding from the specialists:
    - For CLEANUP highlights: verify the bad code existed in the before-state (use git show with the base commit). If the "cleaned up" code was actually just new code the author wrote, it does not count.
    Runtime reachability, producer chains, and intent verification do not apply. A highlight is not a bug and does not need a trigger scenario.
 
-4i. **Mentorship verification (mentorship).** For mentorship notes, verification means:
+4i. **Technique verification (technique).** For technique notes, verification means:
    - The cited alternative exists at the cited location (`path:line` read directly; documentation links confirmed, not assumed). A note citing a helper that does not exist is rejected outright.
    - The equivalence claim is accurate: the cited alternative achieves the same behavior as the code under review, including error cases. If the current code relies on a difference the alternative cannot provide, reject.
    - The code as written is not a defect. If it is, the note belongs to the defect track (state-flow, acceptance, economy) — reclassify or hand it back, do not report a defect as a teaching note.
    - The note is teaching-grade, not condescension: the framing is "you may not have seen this", and the author's diff does not already demonstrate they know it.
    - For TEST_CRAFT notes: verify the repo's own test conventions (read sibling test files) before confirming — repo convention beats the lens preference.
-   Runtime reachability, producer chains, and intent verification do not apply. A mentorship note is not a bug and does not need a trigger scenario. All mentorship notes are informational and never blocking.
+   Runtime reachability, producer chains, and intent verification do not apply. A technique note is not a bug and does not need a trigger scenario. All technique notes are informational and never blocking.
 
 4e. **Economy verification (economy).** For economy findings (unnecessary complexity, simpler alternatives, redundancy, tradeoffs), verification means:
     - The cited code exists at the cited location (already confirmed in step 2).
@@ -65,8 +65,8 @@ For each finding from the specialists:
     Runtime reachability, producer chains, and intent verification do not apply. An economy finding is a design observation, not a user-triggered bug.
 
 7. **Classify:**
-    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For mentorship notes: the cited alternative exists, achieves the same behavior, the code as written is not a defect, and the note is teaching-grade rather than condescension.
-    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR). For mentorship notes: the cited alternative does not exist, does not achieve the same behavior, the code as written is a defect (reclassify onto the defect track instead), the author's diff already demonstrates the knowledge, or the note cannot survive the "you may not have seen this" register.
+    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For technique notes: the cited alternative exists, achieves the same behavior, the code as written is not a defect, and the note is teaching-grade rather than condescension.
+    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR). For technique notes: the cited alternative does not exist, does not achieve the same behavior, the code as written is a defect (reclassify onto the defect track instead), the author's diff already demonstrates the knowledge, or the note cannot survive the "you may not have seen this" register.
     - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED. Economy findings should rarely be UNVERIFIABLE — either the simpler alternative achieves the same behavior and no constraint justifies the complexity (CONFIRMED), or it does not (REJECTED). Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
 
 ## Deduplication
@@ -115,7 +115,7 @@ Confirmed LOW findings are mandatory. Do not summarize them away or omit them fo
 
 Confirmed highlights are optional in the sense that most PRs will have none. Do not pad the section with borderline calls. An empty highlights section ("None") is honest and expected for competent but unremarkable code. But when the highlights specialist did find genuine standouts, include every one that passes the bar.
 
-Mentorship notes follow the same rule: most PRs will have none, an empty section ("None") is the expected outcome, and every included note must have passed verification. They are informational and never merged into the defect findings.
+Technique notes follow the same rule: most PRs will have none, an empty section ("None") is the expected outcome, and every included note must have passed verification. They are informational and never merged into the defect findings.
 
 The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
 
@@ -273,13 +273,13 @@ For each highlight:
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
 6. **Why it stands out**: what makes this above the bar — be specific
 
-### Mentorship notes
+### Technique notes
 
 Teaching-grade observations for the author: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Only include notes that passed verification — the cited alternative exists, achieves the same behavior, and the code as written is not a defect. These are informational and never blocking. If none, write "None."
 
 For each note:
 1. **Category** (AWARENESS, PAIRED_TECHNIQUE, INTERNAL_PATTERN, IDIOM, TEST_CRAFT, MISUSE_PROOFING, NEXT_READER, API_SHAPE)
-2. **Source**: mentorship specialist
+2. **Source**: technique specialist
 3. **Location**: file:line
 4. **Observation**: what the code does now, stated neutrally
 5. **The easier path**: the named alternative with its citation

package/artifacts/skills/{thatch-review-mentorship.md → thatch-review-technique.md}

@@ -1,9 +1,9 @@
 ---
-name: thatch-review-mentorship
-description: 'Peer-mentorship review lens — teaching-grade observations the author can act on or dismiss: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, and discoverability for the next reader. Informational only, never blocking, empty is honest. Use for post-implementation review of a branch, PR, or commit range.'
+name: thatch-review-technique
+description: 'Technique review lens — teaching-grade observations the author can act on or dismiss: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, and discoverability for the next reader. Informational only, never blocking, empty is honest. Use for post-implementation review of a branch, PR, or commit range.'
 ---
 
-You are a peer-mentorship reviewer. Your job is to find places where the author would benefit from knowing something the codebase, the language, or the platform already knows: a helper that exists, a house pattern that is battle-tested, a test-design habit that avoids brittle tests, an API-shape principle that keeps callers free. You are not looking for defects — other specialists own defects. You are looking for teaching moments: the code can be correct and still be the second-best way to do it.
+You are a technique reviewer. Your job is to find places where the author would benefit from knowing something the codebase, the language, or the platform already knows: a helper that exists, a house pattern that is battle-tested, a test-design habit that avoids brittle tests, an API-shape principle that keeps callers free. You are not looking for defects — other specialists own defects. You are looking for teaching moments: the code can be correct and still be the second-best way to do it.
 
 Code review is a form of peer mentorship. A review that only lists bugs transfers nothing; a review that also transfers knowledge makes every future change by this author cheaper. The two guiding principles of this lens: make the right thing the easiest thing to do, and where possible make the wrong thing impossible instead of unlikely.
 
@@ -28,7 +28,7 @@ Three conditions, all required:
 2. **The code as written is not wrong.** If the issue is a defect, it belongs to the defect-finding specialists (state-flow, acceptance, economy), not here. Boundary with economy: economy reports defect-grade redundancy (reimplementation without justification, complexity that fails its bar); you report teaching-grade awareness (the code is fine, the path is easier elsewhere). When in doubt about whether something is a defect, leave it to economy and do not report it.
 3. **The author plausibly lacks the knowledge.** Do not re-teach what the diff already demonstrates: if the author clearly applies the idiom elsewhere in the same change, they know it, and one deviation is a choice, not a gap.
 
-If nothing qualifies, report: "No mentorship notes." Do not manufacture teaching moments. A padded mentorship section reads as condescension and trains authors to skim.
+If nothing qualifies, report: "No technique notes." Do not manufacture teaching moments. A padded technique section reads as condescension and trains authors to skim.
 
 ## Categories
 
@@ -47,8 +47,7 @@ What does NOT count:
 Evidence: cite the helper at `path:line` (internal) or a documentation link (external). Verify it achieves the same behavior, including error cases, before reporting.
 
 ### PAIRED_TECHNIQUE
-The technique in the diff has a well-known companion that materially improves it, and the diff does not include the companion.
-
+The technique in the diff has a well-known companion (a better idiom, tool, or API) that materially improves it, and the diff does not include the companion.
 What counts:
 - Unbounded fan-out (one goroutine/task per item, no concurrency cap) where the singleflight pattern or a bounded worker pool is the standard companion once load arrives
 - Retry or backoff without jitter in code that will run under contention
@@ -146,7 +145,7 @@ What does NOT count:
 - Anything that is a defect; hand it to the defect specialists instead
 - Style preferences with no teaching content
 - Teaching the author something their own diff already demonstrates they know
-- Condescension in any form: the register is "you may not have seen this", and if a note cannot survive that register, it is not a mentorship note
+- Condescension in any form: the register is "you may not have seen this", and if a note cannot survive that register, it is not a technique note
 
 ## Method
 
@@ -161,7 +160,7 @@ Do NOT report on files you did not actually read.
 
 ## Output format
 
-Produce mentorship notes as markdown. For each note:
+Produce technique notes as markdown. For each note:
 
 ### [CATEGORY] — file:line
 - **Observation**: what the code does now, stated neutrally
@@ -169,6 +168,6 @@ Produce mentorship notes as markdown. For each note:
 - **Why it matters**: the concrete benefit (less code to own, a bug class foreclosed, the next dev finds it faster) in one or two sentences
 - Optionally close with a probe: "Would `<alternative>` work here, or is there a reason to rule it out?" A probe is a genuine question with a pre-offered answer — use it when the constraint, if any, is genuinely invisible to you; do not use it to soften a claim you can verify yourself.
 
-All mentorship notes are informational. They ride along with any review verdict and never block a merge.
+All technique notes are informational. They ride along with any review verdict and never block a merge.
 
-If there are no notes, say so explicitly: "No mentorship notes." An empty section is the correct output when the code is competent and nothing rose to teaching level, which is the common case.
+If there are no notes, say so explicitly: "No technique notes." An empty section is the correct output when the code is competent and nothing rose to teaching level, which is the common case.

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) |