@jeffober/thatch 0.2.4 → 0.2.5

package/docs/user/README.md

@@ -138,6 +138,7 @@ Stores are created automatically. No setup required.
 | `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (context description), a prediction (preference statement), and a signal (confirm/disconfirm/soft/create). |
 | `thatch_prediction_list` | List all predictions in a store with matchers, confidence, and provenance. |
 | `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+| `thatch_prediction_mark_checked` | Record a verdict (duplicate/distinct) on a pair the hygiene nudge flagged, so it stops resurfacing. |
 
 ### Behavior tools
 
@@ -183,12 +184,19 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 | `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, thread resolutions, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
 | `thatch_watch_branch_create` | Watch a GitHub branch (typically main) for commit landings, CI check-run completions, and workflow runs, with an optional workflow-name filter. |
 | `thatch_watch_command_create` | Wait on any local condition via a shell command that exits 0 when the wait is over. One-shot: one notification on the first exit 0, then it cancels itself. Accepts a `cd` path to run somewhere other than the project directory. |
-| `thatch_watch_list` | List this session's active watchers. |
+| `thatch_watch_list` | List this session's active watchers, plus events waiting for idle delivery. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
 See [watchers.md](watchers.md) for the full behavior, lifetime, and
 requirements.
 
+### Session tab tools (opencode v2 only)
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_session_tab` | Spawn a detached subordinate LLM session in a new TUI tab: creates the session, pre-assigns its chat name, delivers your task prompt with your coordinator-identity framing, and opens its tab beside yours (unfocused). Takes `prompt` and `title` (required) plus exactly one of `worktree` (a git worktree of the current repository) or `directory` (any existing directory). Requires opencode v2 and the `thatch-coordination` skill describes the supervisor workflow. |
+| `thatch_session_tab_close` | Close a dispatched subordinate's TUI tab when its task is verified and done. Tab-level only: the session survives and the user can reopen the tab; nothing is deleted. Target: the subordinate's chat name or session id. opencode v2 only. |
+
 ### Chat tools
 
 | Tool | What it does |
@@ -247,7 +255,8 @@ Beyond the tools, thatch hooks into opencode itself:
   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,
+  `/thatch/reflect`, `/thatch/whois`) 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
@@ -343,7 +352,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
-| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, chat replies, and code comments. Clarity over compression. |
 
 ### opencode-only skills
 

package/docs/user/cli.md

@@ -163,6 +163,9 @@ thatch setup --claude --skills-only             # refresh just the skill files
 | `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
 | `CLAUDE_PROJECT_DIR` | `process.cwd()` | Claude Code project directory |
 | `CURSOR_PROJECT_DIR` | (falls through) | Cursor project directory |
+| `THATCH_PROJECT_DIR` | (falls through) | Project dir pinned by project-local MCP configs - first in the server's resolution chain |
+| `THATCH_WATCH_DEATH_MINUTES` | `120` | Pending-age threshold before a dead session's watchers are cancelled and announced |
+| `THATCH_PROJECT_DIR` | (falls through) | Project dir pinned by project-local MCP configs - first in the server's resolution chain |
 | `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code config directory |
 | `CURSOR_CONFIG_DIR` | `~/.cursor` | Cursor config directory |
 

package/docs/user/commands.md

@@ -17,6 +17,11 @@ or you invoke it.
   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/whois` — report the current session's chat identity: its handle,
+  topic, project, and whether it runs in the project root or a worktree.
+  Text after the command looks up another session instead (by handle or
+  session id) — this is how you map a handle from the roster to the tab you
+  see: the topic is the session's live title. opencode only.
 - `/thatch/refine` — refine a plan for a code change under the current
   project type's requirements: the agent classifies the project (team,
   personal, shared library, spike, infrastructure, or open source
@@ -38,13 +43,15 @@ or you invoke it.
 | `/thatch/extract` | yes | no | no |
 | `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/whois` | yes | no | no |
 | `/thatch/refine` | 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`).
+Why the gaps: `/thatch/extract` and `/thatch/whois` need 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
 

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

@@ -11,7 +11,9 @@ between tabs all afternoon.
 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
+at harness start with its old name. Sessions thatch itself creates in the
+background - like the fact-extraction runs - are machinery, not chat
+participants, and never appear in the roster. 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
@@ -29,16 +31,33 @@ explicitly with `thatch_chat_register` (no arguments) - useful after
   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, and states the recipient's liveness at send time
-- `thatch_chat_read` drains the session's inbox
+  name or session id, and states the recipient's liveness at send time.
+  An identical resend within a few seconds is treated as a client retry:
+  while the first copy is still unread it succeeds but delivers nothing
+  new (the tool output says so); once the recipient has read it, the same
+  body delivers again - a deliberate repeat, not a retry. A body over
+  2,000 characters is not refused: it is auto-split into several messages,
+  and the tool output reports the split ("SENT AS N PARTS"). The whole
+  message is capped at 20,000 characters; longer is refused with the
+  attempted count
+- `thatch_chat_read` drains the session's inbox. A message longer than
+  one page (2,000 characters) is shown clipped, with a marker naming the
+  characters ("[clipped: showing 2000 of 2047 characters]"); page through
+  the rest with the `message` and `offset` arguments (each drain line
+  carries the message id). Paging never marks anything read
 - `thatch_chat_broadcast` delivers one message to every other live
-  registered session at once
+  registered session at once (a long body is split per recipient, exactly
+  like a split `chat_send`)
 - `thatch_chat_unregister` leaves the directory
 
 When mail arrives for an idle session, thatch wakes it with a notification -
 the agent gets a model turn even with nobody at the keyboard, reads its
 inbox, and decides what to do. The notification names the senders and the
-count only; the agent reads the actual messages itself.
+count only; the agent reads the actual messages itself. A split message
+arrives as one grouped notification ("N unread messages from X"), and the
+parts carry their own markers so the reader assembles the whole before
+acting: the first part is prefixed "(message 1 of N)" and every part but
+the last is suffixed "(continued in next message)".
 
 Broadcasts are for announcements and open questions ("which of you is
 working on the payments code?", "main just moved, rebase if you are based
@@ -198,10 +217,14 @@ construction. Three mitigations:
   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
+  tools 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.
+  but the claim is directory-bound: a session may only claim an identity
+  registered to its own project, and a cross-project claim is refused.
+  The refusal teaches the fix - register a fresh identity for the project
+  once, then reuse it; do not re-register every turn. opencode is immune
+  (the host supplies identity). The threat model is one user's machine;
+  same-project spoofing on Cursor remains possible and accepted.
 - **No external content via wake.** The wake notification names senders
   and counts only - bodies flow exclusively through the framed
   `chat_read` surface.

package/docs/user/prediction-engine.md

@@ -59,6 +59,7 @@ surface it to you, or ignore it. You never see the nudge directly.
 | `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (situation), prediction (preference), signal (confirm/disconfirm/soft/create), and rationale. |
 | `thatch_prediction_list` | List all predictions with matchers, confidence, evidence count, and provenance history. |
 | `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+| `thatch_prediction_mark_checked` | Record a verdict (duplicate/distinct) on a pair the hygiene nudge flagged, so it stops resurfacing. |
 
 ## Configuration
 
@@ -83,5 +84,15 @@ surface it to you, or ignore it. You never see the nudge directly.
   store does not automatically apply to other projects. The global
   store is shared across projects.
 
+## Keeping the model tidy
+
+If the same preference gets recorded twice in different words, the hygiene
+nudge reports `prediction duplicate pairs pending review`. The agent reads
+both, then either merges them (moves the loser's matchers onto the winner
+with `thatch_prediction_update`, deletes the loser with
+`thatch_prediction_delete`) or judges them distinct — and records the
+verdict with `thatch_prediction_mark_checked` either way, so an adjudicated
+pair never nags again.
+
 See [memory.md](memory.md) for the base memory system and
 [behavior-engine.md](behavior-engine.md) for the self-discipline rules.

package/docs/user/setup.md

@@ -44,6 +44,22 @@ The same file loads on both opencode lines: opencode 1.x reads its `server`
 export, opencode 2.x reads its default export (the merged plugin
 definition). No path change when you switch opencode versions.
 
+For opencode 2.x session-tab support, the plugin must be a DIRECTORY shim
+so the TUI can load the `./tui` entrypoint:
+
+```text
+~/.config/opencode/plugins/thatch/
+  index.ts   export { server } from "<thatch-checkout>/src/index";
+             export { default } from "<thatch-checkout>/src/index";
+  tui.ts     export { default } from "<thatch-checkout>/src/opencode/tui-plugin";
+```
+
+Delete the old `thatch.ts` file shim in the same step - a file and a
+directory shim coexisting stops plugin loading entirely (duplicate plugin
+id, detected before any plugin code runs). The TUI plugin is what makes
+spawned subordinate sessions appear as tabs; without it the tool still
+works but no tab opens.
+
 Or place the thatch repo in `.opencode/plugins/` for auto-loading.
 
 ## Claude Code

package/docs/user/skills.md

@@ -68,7 +68,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
-| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, chat replies, and code comments. Clarity over compression. |
 
 ### Workflow skills
 

package/docs/user/watchers.md

@@ -112,7 +112,8 @@ Other tools:
   commits, CI check runs, and workflow runs
 - `thatch_watch_command_create` - wait on any local condition via a
   shell command that exits 0 when the wait is over
-- `thatch_watch_list` - shows the session's active watchers
+- `thatch_watch_list` - shows the session's active watchers, plus any
+  detected events waiting for the session to go idle before delivery
 - `thatch_watch_cancel` - cancels one by id
 
 ## Lifetime
@@ -129,17 +130,31 @@ restarts:
   watch is still there.
 - Watch definitions whose 8-hour TTL expired while the session was
   away are not re-armed; the re-arm notice reports how many expired.
-- If a watched session is never resumed, a live session in the same
-  project hears a one-line notice that the watch died with its
-  session, so a watch that will never fire is at least explained.
-- A watcher expires after 8 hours by default.
+- If a watched session's tab is closed (or the watcher's deliveries fail
+  past the death threshold), its watchers are cancelled, and a live
+  session in the same project hears a one-line notice that the watch
+  died with its session - the notice says the watches were cancelled,
+  not re-armed, so a watch that will never fire is at least explained.
+- A watcher expires after 8 hours by default, and reports its own
+  expiry: the session gets a final notification naming the watched
+  target and how long the watch lived (for example, "watch on
+  acme/widgets#7 expired after 480 min"). The notification states
+  that the watched condition never occurred - it is not a signal
+  that whatever the watch was gating finished. Re-register the watch
+  if notifications are still wanted.
+- A watch also dies with its session: on opencode v2, a closed tab's
+  watchers are cancelled automatically once its undelivered events
+  have aged past 2 hours (THATCH_WATCH_DEATH_MINUTES) while delivery
+  keeps failing, and live sessions in the same project hear a death
+  notice naming the dead session and its watch targets. A coordinator
+  can use that notice to mark a subordinate's task failed and respawn.
 - Each session can hold up to 5 active watchers (all sources share
   the budget).
 - A one-shot watch cancels itself after its first event - a single
   "tell me when this run finishes" request leaves nothing polling
   afterwards. Standing watches (the default) keep going until they
-  are cancelled, expire, or the process ends. Command watches are
-  always one-shot.
+  are cancelled, expire (and say so), or the process ends. Command
+  watches are always one-shot.
 
 ## Requirements and limitations
 

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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",
   "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/opencode/tui-plugin.ts"
+  },
   "bin": {
     "thatch": "./bin/thatch"
   },
@@ -38,11 +42,15 @@
     "yaml": "^2.7.0"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.17.0"
+    "@opencode-ai/plugin": "^1.17.0",
+    "@opencode/plugin": "^2.0.15"
   },
   "peerDependenciesMeta": {
     "@opencode-ai/plugin": {
       "optional": true
+    },
+    "@opencode/plugin": {
+      "optional": true
     }
   },
   "keywords": [

package/src/alerts.ts

@@ -10,7 +10,7 @@
 // deduplication is exact by construction - delivering from the TUI side
 // instead would fire once per attached TUI. State is rebuilt empty on
 // plugin setup: a v2 reload mid-turn loses that turn's transition and the
-// alert stays silent (accepted; see docs/plans/llm-alerts.md).
+// alert stays silent (accepted; see docs/dev/features/notifications.md).
 //
 // What makes a round "real work" is split across two sources, on purpose:
 // - the TOOL side comes from live bookkeeping: the runtime marks real work