@jeffober/thatch 0.2.4 → 0.2.6

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
@@ -23,29 +25,60 @@ 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, 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
+  into Active and Stale sections: active sessions' harness is alive; stale
+  ones have missed two heartbeats, about a minute (the opencode process
+  hosting them has probably stopped). Each active row also carries a
+  liveness verdict: `open` means the session has an opencode tab open
+  right now, `recent` means the harness is alive but no tab is open. 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, 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.
+  For a recipient with no open tab it says so plainly: the message waits
+  in the inbox, but the wake is not guaranteed to start a turn
+  (daemon-resident sessions like subordinates usually still pick the
+  message up on their next activity).
+  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 that has a tab open, plus every MCP session (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.
+inbox, and decides what to do. If the session's directory has been deleted
+(a merged branch's worktree, for example), the wake is skipped quietly:
+no error appears, the mail stays queued, and it delivers normally once the
+directory exists again. The notification names the senders and the
+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
-on it"). Every live session gets the message and spends a model turn on it,
+on it"). Every OPEN session gets the message and spends a model turn on it,
 so broadcast sparingly - for anything with a known audience, `chat_send` is
-the polite tool. Stale sessions are skipped and reported: a dead session
-never reads a broadcast.
+the polite tool. Sessions without an open tab are skipped and reported by
+name: a stale session will never read the mail, and a fresh-but-tab-less
+session (a closed tab, or a headless subordinate) is not reliably wakeable,
+so messaging it would spend a turn on a delivery that likely never runs.
+With opencode tabs disabled, broadcasts reach only MCP sessions - that is
+the honest reading of "no tab signal", never a false fan-out.
 
 ## Watching the conversation
 
@@ -130,21 +163,34 @@ host the sessions run in.
 
 ## Liveness
 
-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.
+Liveness has three levels, and the roster shows which one a row is in.
+
+The base signal is the heartbeat: 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.
+
+The second signal, read at roster time, is opencode's own tab state: a
+fresh row whose session has a tab open right now shows as `open`, one
+without shows as `recent`. `recent` covers finished-but-recently-active
+conversations, closed tabs, and daemon-resident sessions that never had a
+window (subordinates) - the harness is alive, but presence is unknown.
+With tabs disabled (or no opencode state on the machine) every fresh row
+shows as `recent`: an unknown tab state never reads as open.
+
 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
+never reads them, and `chat_send` says so at send time. Messages to a
+`recent` session are delivered, but `chat_send` warns that the wake is
+not guaranteed without an open tab. 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.
+and a greenlit `/thatch/exit` unregisters the session too: the plugin
+removes the row itself when the exit token passes the greenlight check,
+so other sessions stop
+addressing mail to a session that is closing out.
 
 ## Turning chat off
 
@@ -198,10 +244,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

@@ -46,10 +46,21 @@ like:
   flag tech debt before reviewing the diff
 - [0.61 conf, 2 tests] When choosing test scope: you may prefer
   integration tests over unit tests
+Snapshot: these labels reflect the prediction store as of this message's
+submission. Predictions updated after submission (including during this
+turn) do not refresh it; re-check with thatch_prediction_query before
+relying on them.
 ```
 
 The agent reads this and decides whether to follow the prediction,
-surface it to you, or ignore it. You never see the nudge directly.
+surface it to you, or ignore it. You never see the nudge directly. The
+snapshot line matters when the agent corrects the model mid-conversation
+(you say "no, that's wrong" and it calls `thatch_prediction_delete`):
+the block it saw at the start of the turn is a submission-time snapshot
+and does not update. The agent should re-query with
+`thatch_prediction_query` instead of trusting the block's labels. On
+Claude Code and Cursor the tool name appears with its MCP spelling
+(`mcp__thatch__prediction_query`).
 
 ## Tools
 
@@ -59,6 +70,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 +95,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

@@ -48,11 +48,11 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
 | `thatch-review-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, never blocking. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
-| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work, related PRs) before a review. Prevents false positives about intentionally deferred work and about pieces delivered by sibling PRs in a stack or release train. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
-| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. |
+| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. Also the machinery behind the `/thatch/self-review` and `/thatch/peer-review` mode commands, which couch it with a weighting overlay and run the specialists inline on hosts where the coordinator is not installed. |
 
 ### Walkthrough skills
 
@@ -68,22 +68,22 @@ 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
 
 | Skill | Purpose |
 |-------|---------|
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
-| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
+| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). Plans with UI or session state must include a state-and-transition matrix; a revision self-check runs after each revision; extended runs rotate reviewer lenses and stop on a round with no build-changing findings. |
 
 ### Plan refinement skills
 
 | Skill | Purpose |
 |-------|---------|
-| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. Deep-mode triggers in the core skill are binding; type deltas relax round counts, never mode selection. |
 | `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
-| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. Relaxes round counts, never mode selection. |
 | `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
 | `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
 | `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
@@ -104,7 +104,9 @@ window.
   re-installs from its canonical source). Edit the canonical source
   in the thatch repo instead.
 - The opencode-only coordinator (`thatch-code-review`) requires
-  sub-agent support. It is not available on Claude Code or Cursor.
+  sub-agent support. It is not available on Claude Code or Cursor; the
+  `/thatch/self-review` and `/thatch/peer-review` commands run the
+  same specialists inline there instead.
 - Skill content is markdown read at runtime, not compiled into the
   binary. If the skill file is missing or corrupted, the skill will
   not load (silent failure).

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.6",
   "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

package/src/capabilities.ts

@@ -54,7 +54,13 @@ export interface HostCapabilities {
    * only the title carries over.
    */
   sessionCreate(input: { parentID: string; title: string }): Promise<{ id: string }>;
-  /** Delete a session (child-session cleanup). Degrades to a no-op resolve on v2. */
+  /**
+   * Delete a session (extraction-child cleanup, so the picker stays clean
+   * and `-c` resume does not land in a child). v1: client delete. v2:
+   * session.remove on the promise domain (upstream #52387), runtime-guarded
+   * because the pinned dev types predate the surface - an older host
+   * degrades to a no-op (best-effort by the caller's contract).
+   */
   sessionDelete(id: string): Promise<void>;
   /**
    * Prompt a session with text parts. `sync` mode blocks until the child
@@ -90,15 +96,23 @@ export interface HostCapabilities {
   /**
    * Trigger the host's compaction for a session (the wrap-up compact
    * action). v1 dispatches the TUI's session_compact command (the legacy
-   * alias route; the id is ignored). v2 has no compaction trigger reachable
-   * from the promise context and degrades to a logged no-op.
+   * alias route; the id is ignored). v2 calls session.compact on the
+   * promise domain (upstream #52385), runtime-guarded because the pinned
+   * dev types predate that surface; an older host degrades to a logged
+   * no-op.
    */
   compactSession(sessionID: string): Promise<void>;
   /**
-   * Exit the host application (the wrap-up exit action). v1 publishes the
-   * TUI's app.exit command; v2 has no TUI surface and degrades to a no-op.
+   * End the session's presence on the host (the wrap-up exit action). The
+   * runtime records the session's watcher deaths and unregisters it from
+   * chat BEFORE calling here, so implementations only close out the host
+   * side. v1 publishes the TUI's app.exit command - the id is unused
+   * because the whole app is leaving. v2 emits the session-tab bridge's
+   * exit-tab-closed event, a TUI-only close of the session's OWN tab (the
+   * daemon hosts every tab, so an app-wide exit would take down unrelated
+   * sessions too); a host with no bridge degrades to a logged no-op.
    */
-  exitHost(): Promise<void>;
+  exitHost(sessionID: string): Promise<void>;
 }
 
 /**