@jeffober/thatch 0.1.43 → 0.1.45

package/docs/plans/thatch-actions.md

@@ -0,0 +1,179 @@
+# Thatch Actions: Prompt Cores Shared by Nudges and /thatch Commands
+
+## Synopsis
+
+Extract the behavior instructions currently embedded in nudge text into
+prompt-core constants in `src/prompts.ts`, then build `/thatch/*` user-facing
+commands on top of the same constants. The nudge and the command become two
+envelopes around one instruction body: the nudge adds escalation tiers and
+stop-and-wait framing, the command adds user-invocation framing. First
+payoff is `/thatch/defrag`, but the structure covers any behavior the nudges
+currently ask the agent to perform on demand.
+
+## Background
+
+Nudges are instruction-carrying messages injected by hooks. Several encode a
+multi-step behavior the agent must execute (dispatch a sub-agent, fetch the
+extraction payload, run a skill, ack). The same behaviors have no user-facing
+invocation path: the user cannot say "drain the extraction queue now" or
+"consolidate duplicate memories now" -- they can only wait for a nudge or
+describe the desired behavior in prose and hope the agent maps it to the right
+skill + tool sequence.
+
+Two existing pieces make this cheap to add:
+
+- `src/commands.ts` already ships `/thatch/compact` and `/thatch/exit` as
+  markdown command files synced into the opencode config dir, and already
+  composes them from shared fragments (`sharedChecklist`,
+  `userMessageSection`).
+- The "Shared prose sync across prompt variants" problem is documented:
+  prompt prose lives in parallel functions with no single source of truth,
+  and drift in unasserted sections passes tests. This plan makes the shared
+  behavior text a true constant.
+
+## Design: prompt cores and envelopes
+
+A **prompt core** is a constant string in `src/prompts.ts` holding the
+host-agnostic instruction body for one behavior: which tools to call, in what
+order, with what arguments, and what "done" looks like.
+
+An **envelope** wraps a core with delivery-specific framing:
+
+- The nudge envelope adds: escalation tier wording, the load-bearing
+  stop-and-wait ending (see "Extraction nudge stop-and-wait wording is
+  load-bearing" -- the stop-and-wait text is nudge-only and must NOT leak
+  into action envelopes, because an action IS user input), and the
+  "system nudge, not user input" disclaimer.
+- The action envelope adds: frontmatter description, the `# User Message`
+  section with `$ARGUMENTS`, and any greenlight-token mechanics (wrap-up
+  commands only).
+
+Cores are plain string constants, not template functions, so both envelopes
+interpolate them identically. Where a core needs host-specific tool names
+(`thatch_memory_remember` vs `mcp__thatch__memory_remember`), the core takes
+the opencode spelling and MCP consumers apply the documented token
+substitution, matching the existing systemPrompt/mcpInstructions convention.
+
+## Actions v1
+
+| Command | Core behavior | Existing machinery |
+|---|---|---|
+| `/thatch/defrag` | Run `thatch_find_duplicates`, classify each pair with the thatch-dedup-classifier skill, consolidate (remember/overwrite or forget), mark pairs checked | find_duplicates + dedup classifier skill |
+| `/thatch/extract` | Fetch the extraction payload, run the fact-extractor skill, call `extraction_done` | get_extraction_payload + fact-extractor skill |
+| `/thatch/hygiene` | Run the hygiene report, act on stale and orphaned branch-scoped memories | `hygieneReport()` + `/thatch hygiene` CLI |
+| `/thatch/reflect` | Run the session-reflection skill over the current session | thatch-session-reflection skill |
+
+The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
+becomes a core reused by both templates (already true via `sharedChecklist`).
+
+`/thatch/extract` interacts with opencode's direct extraction (parent idle
+spawns the extractor child; the nudge is only a fallback). The action must
+reuse the same accept/complete semantics and must not fight the `extracting`
+set: if direct extraction is already running for the session, the action
+should report that and stop rather than double-dispatch.
+
+## Host parity
+
+Commands are markdown or MCP prompts, synced per host. Behavior parity is the
+goal; format differences are documented, not hidden.
+
+- **opencode** (existing): `installOpencodeCommands` syncs markdown to
+  `~/.config/opencode/command/thatch/` on every plugin load.
+- **Claude Code**: native user-level slash commands read markdown from
+  `~/.claude/commands/thatch/` (user scope) or `.claude/commands/thatch/`
+  (project scope), with the same `$ARGUMENTS` substitution. The sync lives in
+  `setup.ts` alongside the existing installers and follows their patterns:
+  idempotent content-compare like `installSkills`, both global and local
+  scopes, reported in the setup output next to the skills report.
+  (Deviation from the draft below: no `checkSetup` entry. That function
+  answers one question - "is thatch set up at all" - and command files
+  self-heal on every setup run, so flagging their absence as a startup
+  warning would be noise.) Differences: no plugin, so no
+  `command.execute.before` arming -- greenlight-token wrap-up commands do not
+  ship to Claude Code; and tool names use the `mcp__thatch__` prefix. MCP
+  hosts do have hooks now (session-start reminders, chat-wake stop hooks), so
+  hook wiring is not the barrier; the missing piece is only the plugin's TUI
+  control routes.
+- **Cursor**: no file-based commands. The stdio MCP server (`mcp.ts`) gains
+  MCP Prompts support (`prompts/list`, `prompts/get`), which Cursor surfaces
+  as slash commands. The dispatch switch currently handles `initialize`,
+  `tools/list`, `tools/call`, and `ping`; prompts get a `compileTools`-style
+  `compilePrompts()` and two new cases. Prompt arguments use MCP's
+  `{{argument}}`-style templating, so each action core gets an MCP-prompt
+  rendering alongside the markdown rendering.
+
+README gains "What works in Claude Code" and "What works in Cursor" sections
+listing per-host support without restating the shared docs. The parity matrix
+in `docs/dev/mcp-parity.md` gets an Actions row next to the existing
+Wrap-up commands row.
+
+## Session ID plumbing
+
+Since the plan was drafted, `HostToolContext` (tool-defs.ts) landed: every
+tool's `execute` receives the invoking session's ID as a third parameter on
+the opencode path, and the watch tools already consume it. `extraction_done`
+also already has the optional `session_id` with the omit-vs-parent rule in
+its description. The remaining work is narrower than first planned:
+
+- `get_extraction_payload`: `session_id` becomes optional. `execute` uses
+  `args.session_id ?? host?.sessionID`. On the opencode path the wrapper
+  supplies the invoking session, so omitted means "this session."
+- MCP path: the host context is omitted (no session concept), so an omitted
+  `session_id` returns a clear error telling the model to pass the parent
+  session's ID from the extraction nudge.
+
+One wrinkle to document: the zod arg shape is shared between hosts, so
+optionality is global -- you cannot make the arg required on MCP and optional
+on opencode at the schema level. Enforcement happens in `execute` per host,
+and the arg description must carry the rule so the model self-corrects.
+
+The rule the LLM must apply, stated everywhere the tools are described:
+
+> Omit `session_id` when acting on the session you are running in. Pass the
+> parent session's `session_id` when running inside a sub-agent that was
+> dispatched to process another session's extraction queue.
+
+This rule appears in: the arg descriptions in `tool-defs.ts`, the extraction
+prompt core (used by both nudge and action envelopes), the fact-extractor
+skill, and the dev docs. Tests cover both paths: omit-resolves-to-current
+and explicit-parent-ID (the existing sub-agent drain bug's regression path).
+
+## Decisions
+
+- Prompt cores live in `src/prompts.ts`, not a new module; `commands.ts`
+  imports them. One prompt module, consistent with the existing module map.
+- Actions are generated, not hand-written: each action has one core and a
+  per-host renderer, so a wording change cannot drift between nudge and
+  command.
+- No `--dry-run` flag for defrag in v1; the dedup classifier skill already
+  asks for pair-by-pair verdicts, which is the interactive safety net.
+- MCP Prompts for Cursor are additive to `mcp.ts` and do not change the
+  tools/list contract.
+
+## Testing
+
+- `tests/commands.test.ts` (or the existing plugin tests): command-file
+  content assertions per host, including that each action's markdown contains
+  its core text verbatim.
+- Claude setup tests: command sync writes, updates only on content change,
+  and `checkSetup` flags a missing or stale command file.
+- MCP tests: `prompts/list` returns every action; `prompts/get` interpolates
+  arguments; an omitted-session-ID `get_extraction_payload` call errors with
+  the pass-the-parent-ID message (no host context on the MCP path).
+- Plugin tests: `get_extraction_payload` without `session_id` resolves via
+  the host context to the invoking session; with an explicit parent ID,
+  drains the parent's queue (the existing sub-agent drain bug's regression
+  path).
+- Parity guard: a test asserts every opencode command def has a
+  corresponding MCP prompt (and vice versa) except the documented exclusions
+  (wrap-up greenlight commands on non-opencode hosts).
+
+## Docs
+
+- `docs/dev/features/commands.md` and `docs/user/commands.md` (two-tier):
+  action list, host parity matrix, session ID rule.
+- `docs/dev/mcp-parity.md`: Actions row in the parity matrix; revisit the
+  Wrap-up commands row if greenlight arming ever lands on MCP hosts.
+- README: "What works in Claude Code" / "What works in Cursor" sections.
+- QA use cases: one auto use case for `/thatch/defrag` end-to-end, one for
+  `/thatch/extract` with omitted session ID.

package/docs/user/README.md

@@ -19,6 +19,7 @@ This README is the overview. Each feature has its own guide:
 - [default-behaviors.md](default-behaviors.md): what ships automatically
 - [hygiene.md](hygiene.md): store maintenance signals
 - [deduplication.md](deduplication.md): duplicate detection and resolution
+- [commands.md](commands.md): `/thatch/*` slash commands (on-demand actions and wrap-ups)
 - [skills.md](skills.md): structured workflow skills
 - [code-review.md](code-review.md): multi-agent code review pipeline
 - [setup.md](setup.md): installation and configuration
@@ -190,8 +191,8 @@ requirements.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a slug plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
-| `thatch_chat_list` | List registered sessions with a liveness marker (fresh = its process is alive, stale = likely gone), how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
+| `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a pool name plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
+| `thatch_chat_list` | List registered sessions grouped into Active and Stale sections (stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
 | `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
 | `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
 | `thatch_chat_unregister` | Leave the chat directory. |
@@ -240,8 +241,12 @@ Beyond the tools, thatch hooks into opencode itself:
   watches for the token and then runs the compaction or exits opencode.
   Without the token nothing fires -- a toast points you at the items the
   agent listed, and you re-run the command once they're handled. Text typed
-  after the command is passed to the agent ahead of the checklist (say
-  goodbye or hand off context: `/thatch/exit Good work - see you tomorrow`).
+  after the command reaches the agent first, labeled as a `User Message`
+  section ahead of the checklist (say goodbye or hand off context:
+  `/thatch/exit Good work - see you tomorrow`). Alongside the wrap-ups,
+  on-demand actions (`/thatch/defrag`, `/thatch/extract`, `/thatch/hygiene`,
+  `/thatch/reflect`) run the memory-maintenance behaviors whenever you want,
+  not just when a nudge fires -- see [commands.md](commands.md).
   A greenlit `/thatch/exit` also unregisters the session from the chat
   directory, so other sessions stop sending it mail. The commands
   self-install into `~/.config/opencode/command/thatch/` at plugin startup;
@@ -445,6 +450,7 @@ Most configuration needs none. Two layers exist:
 | `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location (the config file follows it) |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Override embedding model |
 | `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_DEBUG` | unset (off) | Diagnostic logging to `debug.log` beside the database. `1` logs everything; or a comma-separated list of tags, e.g. `chat` or `chat:startup` |
 
 Unchanged defaults: the database is created automatically, the embedding
 model downloads once and is cached, the store name is auto-detected from

package/docs/user/cli.md

@@ -46,7 +46,8 @@ Read-only access to the chat directory your opencode sessions share
 
 ```bash
 thatch chat list               # who is registered: name, age, project, topic
-thatch chat tail               # follow sent and read events, live
+thatch chat list --stale all   # also show stale sessions older than a day
+thatch chat tail               # follow sent and read events, live (JSONL)
 thatch chat tail --once        # print the last 20 messages and exit
 thatch chat tail --once --limit 50   # a longer backlog (or --limit all)
 thatch chat tail --match "rebase" --match "payments"   # body must match both
@@ -54,47 +55,47 @@ thatch chat tail --from al --to bob        # substring match on names
 thatch chat tail --since 2026-09-12 --until "2026-09-13 09:00"   # a window
 ```
 
-`chat list` shows every registered session as aligned columns under a
-header row: how long since its last heartbeat (a large age means the
-session's process is probably gone), its status (`fresh` or `STALE`),
-its project, and the topic it registered with - the fastest way to
-answer "which session should I talk to about X?" Color is added only
-when the output is a terminal; a pipe prints plain aligned text.
-
-`chat tail` prints the conversation as styled chat cards (labels on a
-colored background, names in color, timestamps dimmed; a drawn rule
-separates cards, with blank lines on either side). After each name, the
-session's registered topic appears in muted italics - so the tail tells
-you not just who is talking but what they are working on. In a
-terminal, message bodies render as markdown: if `glow` (or `gum`) is
-installed, bodies with headings, lists, code blocks, and emphasis are
-styled; plain-text bodies print exactly as sent. Piped output - and a
-system without either tool - always gets the raw body.
+`chat list` shows every registered session in two sections, Active and
+Stale, each as aligned columns under a header row: how long since its
+last heartbeat, its status (`fresh` or `stale` for opencode sessions;
+`active` or `idle` for Claude Code and Cursor sessions, which only beat
+when a prompt runs), its project, and its topic (the session's title) -
+the fastest way to answer "which session should I talk to about X?"
+Rows are grouped by project (alphabetical; sessions with no project
+last), most recently seen first within each project. A
+stale session has missed two heartbeats, about a minute: the opencode
+process hosting it has probably stopped. The stale section shows rows
+up to one day old by default; older ones collapse into a hidden-count
+note so long-dead sessions cannot bury the fresh signal. Pass
+`--stale N` (days) to widen the window or `--stale all` to see every
+stale row. Color is added only when the
+output is a terminal; a pipe prints plain aligned text.
+
+`chat tail` prints the conversation as a JSONL event log: one JSON
+object per line, one event per line. Sending a message and reading it
+are separate events, linked by the message `id`. Every field is plain
+data: names as registered, each participant's topic, the message body
+exactly as sent, and ISO-8601 UTC timestamps. No color, no markdown
+rendering, no local time; pipe through `jq` for either.
 
 ```text
- From   Al Go Rithm <cross-session messaging between opencode sessions>
- To     Brute the Dream Farrier <diagnosing watcher underuse>
- When   2026-09-12 14:02 America/Denver
-
-CI is green on main
-____________________________________________________________
-
- To     broadcast
- When   2026-09-12 21:07 America/Denver
-
-rebasing payments, hold off
-____________________________________________________________
+{"event":"sent","at":"2026-09-12T20:02:11Z","id":41,"from":"al-go-rithm-00001","from_topic":"cross-session messaging","to":"brute-the-dream-farrier-00001","to_topic":"diagnosing watcher underuse","broadcast":false,"body":"CI is green on main"}
+{"event":"read","at":"2026-09-12T20:02:40Z","id":41,"reader":"brute-the-dream-farrier-00001","reader_topic":"diagnosing watcher underuse","from":"al-go-rithm-00001","from_topic":"cross-session messaging"}
+{"event":"sent","at":"2026-09-13T03:07:02Z","id":42,"from":"al-go-rithm-00001","from_topic":"cross-session messaging","to":"kurn-the-typechecker-00001","to_topic":"release QA","broadcast":true,"body":"rebasing payments, hold off"}
+```
 
- From   Kurn the Typechecker <release QA>
- read Marlowe the Cherry Picker <payments refactor>
- When   2026-09-12 21:08 America/Denver
+A broadcast is one `sent` event per recipient, each with `broadcast:
+true` and its real `to`, so every copy tracks its own read. Handy
+one-liners:
 
-direct ping
+```bash
+thatch chat tail | jq -r '"\(.at) \(.event) \(.from) -> \(.to // .reader): \(.body // "")"'
+thatch chat tail --once --limit all | jq -c 'select(.event == "read")'
 ```
 
-Follow mode runs until Ctrl-C. Read events appear only in follow mode
-(they fire when an inbox is drained after the tail started). When
-timestamps are in your local timezone. The chat itself flows through the
+Follow mode runs until Ctrl-C. The backlog includes the `read` event of
+every message already read; in follow mode, reads appear as inboxes
+drain. The chat itself flows through the
 agents (the CLI never sends, reads, or registers on a session's behalf;
 that happens from opencode sessions via the `thatch_chat_*` tools).
 
@@ -108,10 +109,8 @@ too, so a filtered tail keeps watching the same way:
   together: every one must match the message body.
 - `--from NAME` and `--to NAME` match participant names (case doesn't
   matter). A departed sender can only be found as the `unknown`
-  rendering the tail shows. Broadcast cards say `broadcast` in the To
-  slot, but the row underneath keeps the real recipient: `--to <name>`
-  finds the fan-out rows that reached them, while `--to broadcast`
-  matches nothing.
+  rendering the tail shows. Broadcast events carry their real recipient,
+  so `--to <name>` finds the fan-out copies that reached them.
 - `--since DT` and `--until DT` bound the window; a message counts if
   it was sent at or after `--since` and before `--until`. The date
   format is `YYYY-MM-DD` with an optional `HH:MM` in your local
@@ -119,9 +118,9 @@ too, so a filtered tail keeps watching the same way:
 
 A `--until` already in the past exits after the backlog (a closed
 window has nothing left to follow); one in the future follows until
-the window closes. Note that the limit hides sent cards, not their
-reads: a hidden message that gets read during follow mode still emits
-its read card.
+the window closes. In the backlog, a hidden message's read is hidden
+with it; in follow mode, a hidden message that gets read still emits
+its read event.
 
 ## Priming a new project
 
@@ -168,7 +167,9 @@ thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
 
 ## Limitations
 
-- Requires `bun` on PATH. Thatch does not bundle its own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - `search` is limited to 10 results. There is no pagination.
 - `prime` requires an external CLI (`opencode`, `agent`, or `claude`)
   on PATH. If none is found, it exits with an error.

package/docs/user/commands.md

@@ -0,0 +1,50 @@
+# Slash commands
+
+Thatch ships `/thatch/*` commands you run yourself, on top of the nudges the
+plugin fires on its own schedule. Nudges and commands share the same
+instruction text, so a behavior works the same whether it fires automatically
+or you invoke it.
+
+## Commands
+
+- `/thatch/defrag` — find duplicate-candidate memory pairs and clusters,
+  classify each one, consolidate duplicates, and mark the rest checked.
+  Text after the command narrows the scope (for example, a store name).
+- `/thatch/extract` — drain the extraction queue now, instead of waiting
+  for the next nudge or idle-time extraction. opencode only.
+- `/thatch/hygiene` — run the hygiene report and act on it: stale
+  memories, memories scoped to deleted branches, and pending dedup pairs.
+  The agent asks before forgetting anything that may still matter.
+- `/thatch/reflect` — run the session-reflection skill to persist what the
+  current session learned.
+- `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
+  pre-flight checklist (flush extraction, finish promised memory writes,
+  surface loose ends) before a compaction or an exit, gated by a greenlight
+  token. opencode only; the greenlight mechanics are described in the
+  [user guide overview](README.md).
+
+## Host support
+
+| Command | opencode | Claude Code | Cursor |
+|---|---|---|---|
+| `/thatch/defrag` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/extract` | yes | no | no |
+| `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/compact`, `/thatch/exit` | yes | no | no |
+
+Why the gaps: `/thatch/extract` needs the invoking session's ID, which only
+the opencode plugin can supply. The wrap-up commands trigger TUI actions
+through the plugin. Cursor has no file-based commands; its prompts come from
+the MCP server (`prompts/list` and `prompts/get`).
+
+## Installation
+
+- **opencode**: installed by the plugin on every load.
+- **Claude Code**: installed by `thatch setup --claude` into the same scope
+  as the skills (`.claude/commands/thatch/` project-local, or the Claude
+  config dir for `--global`). Re-run setup to refresh after an upgrade.
+
+Tool names inside the command text follow each host's spelling
+(`thatch_memory_remember` on opencode, `mcp__thatch__memory_remember` on
+Claude Code and Cursor).

package/docs/user/cross-session-chat.md

@@ -1,16 +1,19 @@
 # Cross-Session Chat
 
-Cross-session chat lets your opencode sessions talk to each other. If one
+Cross-session chat lets your agent sessions talk to each other, in
+opencode, Claude Code, and Cursor. If one
 session is QAing a release and another is planning a feature, the second can
 ask the first "is the release green yet?" instead of you relaying messages
 between tabs all afternoon.
 
 ## What it does
 
-opencode sessions join the directory automatically, on their first idle
-moment. Names are assigned by thatch, never chosen: a lowercase slug of the
-session's title plus a counter (a session titled "Fix auth bug" becomes
-`fix-auth-bug-00001`). The counter only ever increments, so a name is
+opencode sessions join the directory automatically, the moment their
+first user message arrives (before the assistant responds), and a session
+resumed with `opencode -c` or `opencode -s <id>` is back in the directory
+at harness start with its old name. Names are assigned by thatch, never chosen: a name drawn from a
+built-in pool plus a counter (`al-go-rithm-00001`). The counter only ever
+increments, so a name is
 minted exactly once per machine - pruning an old session never reissues its
 name to someone else, and the same name always refers to the same session.
 The live title rides along as the session's topic (refreshed as the
@@ -19,12 +22,14 @@ board without anyone filling in forms. A session can also join or rejoin
 explicitly with `thatch_chat_register` (no arguments) - useful after
 `chat_unregister`, or just to check your assigned name. Once registered:
 
-- `thatch_chat_list` shows every registered session on the machine, with a
-  liveness marker (fresh or stale), how long ago it last checked in, its
-  project, whether it runs in the project root or a linked git worktree,
-  its topic, and your unread count
+- `thatch_chat_list` shows every registered session on the machine, grouped
+  into Active and Stale sections: active sessions can be woken; stale ones
+  have missed two heartbeats, about a minute (the opencode process hosting
+  them has probably stopped). Each row carries how long ago the session last
+  checked in, its project, whether it runs in the project root or a linked
+  git worktree, its topic, and your unread count
 - `thatch_chat_send` delivers a message to another registered session, by
-  name or session id
+  name or session id, and states the recipient's liveness at send time
 - `thatch_chat_read` drains the session's inbox
 - `thatch_chat_broadcast` delivers one message to every other live
   registered session at once
@@ -56,8 +61,14 @@ toggle reveals those output blocks if you want them.)
 
 ## How to use it
 
-With auto-registration you usually do nothing: both sessions are already
-in the directory. To introduce them, just tell each session who to talk to:
+With auto-registration you usually do nothing: a session joins the
+directory when its first user message arrives, and a session continued
+with `opencode -c` or `opencode -s <id>` is registered again the moment
+its harness starts - same session id, same name, reclaimed. The agent
+gets a quiet toast with
+its assigned name when it first registers, and a resumed session
+announces its reclaimed name on its first prompt. To introduce two
+sessions, just tell each one who to talk to:
 
 > Ask the other session whether the release has shipped; answer its
 > questions directly.
@@ -72,14 +83,65 @@ doing. When in doubt it summarizes the mail for you and waits. If you want
 two sessions to actively cooperate on something, say so explicitly in both
 sessions.
 
+## Claude Code and Cursor
+
+Chat works from Claude Code and Cursor through the same MCP server and the
+same shared directory. The seven tools are identical on every host; two
+things differ.
+
+**Identity comes from the hook.** Claude Code and Cursor pass no session
+context to MCP tool calls, so the thatch hook anchors identity instead. It
+registers the conversation under a stable id derived from the host's
+session id, and prints `you are NAME (unread count)` at session start and
+on every prompt. The model passes that name as the `as` argument on the
+chat tools. Without the hook (MCP registered by hand, hooks removed), the
+model can still join: `chat_register` with no arguments mints a fresh
+identity for the conversation, and the model uses the returned name from
+there. That identity does not survive a compacted context - re-register
+then, or prefer the hooked path.
+
+**Delivery model.** Only opencode can start a turn when mail arrives
+while you are away. The other hosts surface mail at their hook points,
+and both wake the agent when a turn ends:
+
+- **Cursor** checks the mailbox when a turn ends (the `stop` hook): unread
+  mail is auto-submitted as a follow-up message, so the agent reads it
+  without you typing anything. The notification is a pointer (sender
+  names + count, never message bodies); bodies flow only through the
+  framed `chat_read`. A loop cap bounds consecutive follow-ups, and an
+  aborted or errored turn is never auto-continued.
+- **Claude Code** also checks at turn end (the `Stop` hook): unread mail
+  arrives as a Stop-hook reminder and the turn continues so the agent
+  reads it. The host's own loop protections plus the delivered stamp
+  bound repeats, and a session paused on background work is not
+  interrupted - the wake lands when that work's turn ends. Mail is also
+  announced at startup and resume (the `SessionStart` hook line) and at
+  every prompt; if an answer is urgent, say so to the agent directly.
+
+Two limits worth knowing:
+
+- Cursor cloud agents run no client-side hooks: no identity anchor, no
+  mail lines. The MCP tools still work, with a self-registered identity.
+- A conversation idle past the prune window (a week) re-registers under a
+  fresh name; mail addressed to the old name is swept.
+
+The terminal view ([cli.md](cli.md)) works the same regardless of which
+host the sessions run in.
+
 ## Liveness
 
-A session shows as fresh while its opencode process is running. A crashed
-or closed process stops heartbeat-ing, and the session shows as stale in
-`thatch_chat_list` after ten minutes. Messages to a stale session wait in
-its inbox unread - a dead session never reads them. Explicitly closing a
-session (deleting it in the TUI) unregisters it immediately, and a
-greenlit `/thatch/exit` unregisters the session too: the wrap-up
+A session shows as fresh while the opencode process hosting it is
+running: hosted sessions keep beating (idle ones included), so the
+freshness is real. When that process dies, its sessions stop beating and
+show as stale about a minute later (two missed heartbeats), grouped into
+a separate Stale section. A laptop that slept reads the same way until
+its processes catch up.
+Messages to a stale session wait in its inbox unread - a dead session
+never reads them, and `chat_send` says so at send time. Continuing a
+session with `opencode -s <id>` reclaims its name and row, and any mail
+that queued while it was down is delivered at startup. Explicitly
+closing a session (deleting it in the TUI) unregisters it immediately,
+and a greenlit `/thatch/exit` unregisters the session too: the wrap-up
 checklist calls `chat_unregister`, and the plugin removes the row itself
 when the exit token passes the greenlight check, so other sessions stop
 addressing mail to a process that is about to vanish.
@@ -132,16 +194,26 @@ construction. Three mitigations:
 - **Names are assigned, not claimed.** Display names are minted by thatch
   with a never-reused counter, so a name cannot be grabbed by an unrelated
   session and an old name cannot be resurrected by an impersonator.
+- **Claude Code identity is anchored by the host process.** Hooks learn
+  the true session id from the host and record which process spawned them;
+  the MCP server resolves its own parent process against that record, so
+  the model cannot claim another session's identity there. On Cursor, chat
+  tools still trust the `as` argument the caller supplies (hooks and MCP
+  servers share one workspace process, so process identity is ambiguous) -
+  a local session that knows a name can act as it. opencode is immune (the
+  host supplies identity). The threat model is one user's machine.
 - **No external content via wake.** The wake notification names senders
   and counts only - bodies flow exclusively through the framed
   `chat_read` surface.
 
 ## Requirements and limitations
 
-- **Wake-up delivery is opencode only.** The chat tools work everywhere
-  (other hosts declare their identity with `as`), but only opencode can
-  start a turn when a message arrives; Claude Code and Cursor see pending
-  mail at their next prompt (the flush-tools hook line, or `chat_status`).
+- **Idle wake (starting a turn with nobody at the keyboard) is opencode
+  only.** The chat tools work everywhere (other hosts declare their
+  identity with `as`). Cursor and Claude Code additionally wake the agent
+  when a turn ends with mail unread (the `stop`/`Stop` hooks); Claude
+  Code also announces mail at startup and resume, and both see pending
+  mail at prompt time (the flush-tools hook line, or `chat_status`).
 - **Same machine only.** The directory and inbox live in thatch's local
   database. There is no network relay.
 - **Opt-in.** Unregistered sessions cannot be messaged and cannot send.

package/docs/user/setup.md

@@ -90,6 +90,7 @@ and `--json` output for hook commands.
 | `THATCH_DB_PATH` | `~/.config/thatch/thatch.db` | SQLite database path |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Hugging Face model name for embeddings |
 | `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_MODEL_CACHE` | platform per-user cache dir | Where downloaded model files are stored |
 | `THATCH_RECALL_THRESHOLD` | `0.55` | Cosine threshold for recall nudge |
 | `THATCH_PREDICTION_THRESHOLD` | `0.60` | Cosine threshold for prediction auto-fire |
 | `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
@@ -110,10 +111,15 @@ instructions are deployed without requiring you to manually re-run
 
 ## Limitations
 
-- `bun` must be installed and on PATH. Thatch does not bundle its
-  own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - The embedding model (~34 MB) is downloaded once on first use and
-  cached in `node_modules/@huggingface/transformers/.cache/`.
+  cached in the platform's per-user cache dir
+  (`~/Library/Caches/thatch/models` on macOS (or
+  `$XDG_CACHE_HOME/thatch/models` when `XDG_CACHE_HOME` is set),
+  `$XDG_CACHE_HOME/thatch/models` elsewhere). Override with
+  `THATCH_MODEL_CACHE`.
 - There is no web UI or dashboard. All interaction is through the
   agent's tool calls and the `thatch` CLI.
 - The MCP server is a long-lived process that keeps the embedding model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat-names.ts

@@ -9,8 +9,8 @@
  * unnamed-cast extras). fnord generates its names with an LLM at runtime;
  * thatch bakes the pool in - static contents, no model call.
  *
- * The pool is the fallback base for registrations with no usable session
- * title (ChatStore.register slugifies a random pool name). Pool names are
+ * The pool is the base for every registration (ChatStore.register
+ * slugifies a random pool name and appends a counter). Pool names are
  * case-insensitively distinct from each other; slugify is lossy, but a
  * shared base is harmless - the per-base counter still yields unique
  * names.