@jeffober/thatch 0.1.43 → 0.1.44

package/docs/user/cli.md

@@ -46,7 +46,7 @@ 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 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 +54,41 @@ 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?" A
+stale session has missed two heartbeats, about a minute: the opencode
+process hosting it has probably stopped. 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 +102,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 +111,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
 

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

@@ -1,6 +1,7 @@
 # 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.
@@ -8,9 +9,9 @@ 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
+moment. 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 +20,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 +59,12 @@ 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 it first goes idle, and a session continued with
+`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. 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 +79,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 +190,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "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.