@jeffober/thatch 0.2.3 → 0.2.5

package/docs/plans/prediction-consolidation.md

@@ -1,11 +1,18 @@
-# Prediction Consolidation and Compound Predictions
+# Fire Tracking and Compound Predictions
 
 ## Synopsis
 
-Post-processing layers for the prediction engine: fire tracking, co-fire-based
-consolidation (dedup), and compound (tier-2) predictions minted from
-co-firing constellations of existing predictions. Uses nudge-driven detection
-and the existing edge model for fire behavior. No cron, no separate backend.
+Post-processing layers for the prediction engine: fire tracking and compound
+(tier-2) predictions minted from co-firing constellations of existing
+predictions. Uses nudge-driven detection and the existing edge model for fire
+behavior. No cron, no separate backend.
+
+The consolidation (dedup) half was implemented separately and has graduated —
+the shipped design is documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). What remains here is the fire-tracking prerequisite
+and the co-fire refinements (behavioral dedup, compound detection) that
+consume the accumulated data.
 
 ## Background
 
@@ -14,10 +21,10 @@ auto-fires at chat.message and updates via agent tool calls. What it lacks
 relative to nak's samskara system:
 
 - **Fire tracking** -- no record of which predictions fire together on the same
-  turn. This is the prerequisite for both co-fire dedup and compound detection.
-- **Consolidation** -- no corpus-level dedup pass. Write-time dedup
-  (findNearestPrediction at 0.85) catches near-identical statements at creation,
-  but behavioral duplicates (same preference, different wording) accumulate.
+  turn. This is the prerequisite for co-fire dedup and compound detection.
+- **Consolidation** -- implemented and graduated: a cosine-only dedup pass
+  over the prediction corpus, no prerequisites
+  ([../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)).
 - **Compound predictions** -- no mechanism to mint a higher-order prediction
   from a constellation of predictions that reliably co-fire. Nak's tier-2
   samskaras fire at 77% genuine-engagement vs tier-1's 21% because compound
@@ -43,10 +50,13 @@ existing edge model.
 The co-fire data is for *deciding what to compound*, not for *making the
 compound fire*. This means:
 
-1. A compound needs no tier column, no special scoring path, no fire-path
-   changes. It is a prediction with multiple matcher edges.
-2. The existing `scorePredictions` already follows all edges and deduplicates by
-   prediction_id. A compound scores through its children's edges.
+1. A compound needs no tier column and no fire-path changes. It is a
+   prediction with multiple matcher edges. The scoring path does get one
+   addition: dynamic child suppression (see the compound-domination risk).
+2. The existing `scoreNudge`/`scoreItems` already follow all edges and
+   deduplicate by prediction_id. A compound scores through its children's
+   edges. Minting records the compound-to-children relation (Phase 4) so
+   suppression can tell parent from child.
 3. The existing `prediction_update` tool already finds existing matchers by
    cosine (0.85 threshold) and creates edges. Calling it multiple times with
    different matcher texts but the same prediction statement creates a
@@ -111,14 +121,18 @@ pass null or derive from the socket connection.
 tables. Same conventions (uuid PK, store column, idempotent CREATE TABLE IF
 NOT EXISTS).
 
-### Phase 2: Consolidation (Co-fire Dedup)
-
-**New DB method: `findPredictionDuplicates(store, threshold)`**
+### Phase 2: Co-fire refinement of dedup
 
-Two-pass, mirroring nak's `samskara_collapse_by_cofiring`:
+The cosine-only dedup pass (`findPredictionDuplicates`, the
+`prediction_dedup_pairs` table, the hygiene line, the merge flow) is
+IMPLEMENTED and graduated — documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). Once
+fire data accumulates, this plan upgrades that same method with behavioral
+evidence, mirroring nak's `samskara_collapse_by_cofiring`:
 
-**Primary pass (behavioral):** For each pair of predictions (A, B) in the store
-where both have fire_count > 0:
+**Behavioral pass (added to `findPredictionDuplicates`):** For each pair of
+predictions (A, B) in the store where both have fire_count > 0:
 
 ```
 cofires(A, B) >= 3
@@ -131,26 +145,11 @@ when either fires are duplicates. Two that co-fire but also fire independently
 are adjacent-but-distinct. Cosine is a sanity floor against spurious co-fires.
 
 **Safety cap (cosine-only):** If the prediction count exceeds a target (e.g.,
-100), fall through to pure embedding-cosine greedy merge (cosine >= 0.60)
-regardless of co-fire data. This catches accumulation when the behavioral pass
-finds nothing but the pool is still growing.
-
-**Output:** A list of candidate merge pairs with {predictionA, predictionB,
-cofires, ratio, cosine, firesA, firesB}. Surfaced via the hygiene nudge, not
-auto-merged. The agent reviews and merges via prediction_delete + (optionally)
-prediction_update to fold the loser's matchers into the winner.
-
-The merge itself is agent-driven: the agent sees the candidate pair, reads both
-predictions, deletes the weaker one (or uses a future `prediction_merge` tool
-if one is added). This matches the memory dedup pattern
-(`find_duplicates` + `dedup_mark_checked`).
-
-**Integration point:** `hygiene.ts` -- add a line to `hygieneReport`:
-`N prediction duplicate pairs pending review` when candidates exist.
+100), the implemented pure cosine pass already covers the pool;
+no behavioral evidence is required to keep dedup moving.
 
-**Nudge throttling:** Runs at session start only, same as the existing hygiene
-report. The analysis is O(n^2) over the predictions table but n is small
-(tens, not hundreds) so the cost is negligible.
+**Output:** the dedup plan's candidate shape extended with {cofires, ratio,
+firesA, firesB} per pair.
 
 ### Phase 3: Compound Prediction Detection
 
@@ -216,7 +215,14 @@ first child's matcher. Subsequent calls find the existing compound by
 `findNearestPrediction` (0.85 store-wide dedup) and add edges from the other
 children's matchers.
 
-This works with the existing tool surface. No new tools needed for minting.
+This works with the existing tool surface. One addition: minting must also
+record WHICH predictions the compound supersedes, because child suppression
+(see the compound-domination risk) needs the parent-to-children relation at
+scoring time -- shared matcher edges are implicit and cannot distinguish a
+compound from a busy multi-matcher prediction. `prediction_update` gains an
+optional `supersedes` arg (array of prediction ids), carried on the first
+mint call, writing one `prediction_compounds(compound_id, child_id)` row per
+child. No tier column; the compound is still an ordinary prediction.
 
 **Prompt instructions addition** (in prompts.ts, all three host variants):
 
@@ -225,8 +231,9 @@ After the existing prediction instructions, add guidance for compounds:
 - When the hygiene nudge reports co-fire constellations, consider whether the
   members share a generalizable behavior.
 - If so, synthesize a compound statement and call `prediction_update` once per
-  child matcher with the compound statement. The tool handles matcher dedup and
-  edge creation.
+  child matcher with the compound statement, passing the child prediction ids
+  as `supersedes` on the first call. The tool handles matcher dedup and edge
+  creation.
 - A compound should be strictly more general than any single child. If you
   cannot generalize, do not compound.
 - The compound inherits the fire coverage of its children's matchers. It will
@@ -258,7 +265,7 @@ chat.message (user text)
 session.created (top-level)
   → hygieneReport
     → findDuplicates (memories, existing)
-    → findPredictionDuplicates (NEW: co-fire dedup candidates)
+    → findPredictionDuplicates (implemented; co-fire-refined here)
     → findCoFireConstellations (NEW: compound candidates)
     → inject hygiene nudge with all signals
 
@@ -276,44 +283,48 @@ computation, same as existing prediction methods.
 db.ts.
 
 **Code changes by file:**
-- `src/db.ts` -- new table, 4-5 new methods (recordFires, fireCount,
-  cofireCount, totalCohorts, findPredictionDuplicates, findCoFireConstellations)
+- `src/db.ts` -- one new table (`prediction_fires`) + 4 new methods
+  (recordFires, fireCount, cofireCount, totalCohorts, findCoFireConstellations);
+  the co-fire refinement extends the implemented `findPredictionDuplicates`
+  method
 - `src/runtime.ts` -- generate cohort_id, pass to recordFires in auto-fire path
 - `src/sideband.ts` -- same for MCP path
-- `src/hygiene.ts` -- add prediction dedup + constellation counts to report
+- `src/hygiene.ts` -- add constellation count to report (the dedup count is
+  already implemented there)
 - `src/prompts.ts` -- compound minting guidance in all three prompt variants
 - `tests/prediction.test.ts` -- tests for new DB methods
 - `tests/plugin.test.ts` -- test that fire tracking records cohorts
 
 ## Implementation Order
 
+0. **Cosine dedup** -- IMPLEMENTED and graduated (Oct 2026):
+   `findPredictionDuplicates` + `prediction_mark_checked`; nothing left to do.
 1. **Fire tracking** (table + recordFires + caller wiring). Foundation for
-   everything else. Ship and let fire data accumulate.
-2. **Cosine dedup** (findPredictionDuplicates + hygiene integration). Does not
-   need fire tracking. Can ship in parallel with phase 1. Immediate value:
-   catches behavioral duplicates the write-time 0.85 dedup misses.
-3. **Co-fire dedup** (add co-fire ratio + cosine filter to
-  findPredictionDuplicates). Needs fire data to accumulate first. Wait a few
-   weeks after phase 1 ships.
-4. **Compound detection** (findCoFireConstellations + hygiene integration).
+   everything else here. Ship and let fire data accumulate.
+2. **Co-fire dedup** (add the behavioral pass to findPredictionDuplicates).
+   Needs fire data only -- the method and pair table already exist. Wait a
+   few weeks after fire tracking ships.
+3. **Compound detection** (findCoFireConstellations + hygiene integration).
    Needs more fire data than dedup (p_min_cofires = 10). Wait longer.
-5. **Compound minting** (prompt instructions + agent-driven via existing
-  tools). Ships with phase 4 -- the nudge surfaces candidates, the agent
-   compounds.
+4. **Compound minting** (prompt instructions + agent-driven via existing
+  tools). Ships with compound detection -- the nudge surfaces candidates,
+   the agent compounds.
 
-Phases 1-2 can ship together. Phases 3-5 follow once fire data accumulates.
+Fire tracking ships immediately; the rest follow once fire data accumulates.
 
 ## Test Plan
 
 - `prediction.test.ts`: test recordFires, fireCount, cofireCount,
-  totalCohorts with synthetic cohorts. Test findPredictionDuplicates with
-  known co-firing pairs. Test findCoFireConstellations with lift thresholds.
+  totalCohorts with synthetic cohorts, the co-fire refinement of
+  findPredictionDuplicates with known co-firing pairs, and
+  findCoFireConstellations with lift thresholds.
   Use the existing `makeEmbed(seed, dim=384)` helper.
 - `plugin.test.ts`: test that chat.message auto-fire records a cohort.
   Follow the recall-nudge test pattern (mock.module transformers + server
   hooks).
 - `hygiene.test.ts` (if exists) or `plugin.test.ts`: test that hygiene report
-  includes prediction dedup/constellation counts when candidates exist.
+  includes the constellation count when candidates exist (the dedup count
+  tests are implemented, riding UC-113).
 
 ## Risks and Mitigations
 
@@ -324,11 +335,18 @@ precondition gate (minimum prediction count, minimum fire count) before running
 the analysis.
 
 **Risk: Compound predictions fire too much, dominating the nudge.**
-Mitigation: The existing `scorePredictionNudge` deduplicates by prediction_id
-and slices to limit=5. A compound competes on equal footing with its children.
-If a compound and a child both fire, the higher-scoring one wins the slot. The
-compound's score is `cosine(matcher) * edge.weight * confidence` -- same
-formula. No special treatment.
+Mitigation (nak-proven): dynamic child suppression, not equal-footing
+competition. When a compound and its child both score in the same round and
+the compound's score is higher, the child is skipped. The rule resolves
+during the scoring pass, per query -- not as a stored flag -- so the
+surviving set adjusts as it searches and freed slots refill from the
+remaining scored list. If the child outscores the compound (it matched a
+matcher the compound did not inherit), both surface. Implementation: the
+per-round dedup filter in `scoreItems` (src/scoring-engine.ts:153-178)
+gains the suppression check, using the compound-to-children relation
+recorded at mint time. Plain prediction_id dedup and the limit=5 slice are
+unchanged. Fire rows record post-suppression survivors only, so co-fire
+data means co-surfaced.
 
 **Risk: Agent creates poor compounds (too generic, not useful).**
 Mitigation: The prompt instructions include the "strictly more general" guard
@@ -351,9 +369,11 @@ this becomes a concern. Low priority.
   a separate improvement, not part of this plan, but worth doing alongside
   phase 1.
 - The existing write-time dedup (`findNearestPrediction` at 0.85) catches
-  near-identical statements at creation. The co-fire dedup in phase 3 catches
-  behavioral duplicates that differ in wording. The two are complementary:
-  write-time catches semantic twins, co-fire catches behavioral twins.
+  near-identical statements at creation. The implemented dedup pass
+  (cosine, with its co-fire refinement here) catches
+  behavioral duplicates that differ in wording. The layers are
+  complementary: write-time catches semantic twins, the dedup passes catch
+  behavioral twins.
 - Nak's tier-2 decline ledger (`samskara_tier2_declines`, TTL'd 7 days) prevents
   re-offering a declined constellation every sweep. Thatch's equivalent: a
   `prediction_constellation_declines` table or a `dedup_pairs`-style

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

@@ -148,7 +148,8 @@ thatch buffer-batch             # append tool batch to queue (Claude Code hook)
 thatch buffer-tool              # append single tool to queue (Cursor hook)
 thatch flush-tools [--json]     # peek queue + print nudges (hook)
 thatch flush-predictions [--json]  # prediction-only nudge (hook)
-thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
+thatch setup --claude [--cursor] [--global]     # install config + hooks + skills
+thatch setup --claude --skills-only             # refresh just the skill files
 ```
 
 ## Environment variables
@@ -162,6 +163,9 @@ thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
 | `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
@@ -60,6 +76,16 @@ Skills follow the install scope: project-local installs them to the
 repo's `.claude/skills/` so they version with the project; `--global`
 installs them to `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`).
 
+To refresh just the skill files without rewriting anything else, add
+`--skills-only`:
+
+```bash
+thatch setup --claude --skills-only
+```
+
+This skips the MCP config, instructions, hooks, and commands, and
+reports the same skills directory and install counts as a full run.
+
 `bun` must be on PATH (the thatch binary runs under bun). Setup is
 idempotent. Re-running it updates drifted content without clobbering
 unrelated config, and reports what it did: the skills directory plus
@@ -84,6 +110,9 @@ thatch setup --cursor --global   # user-scoped (~/.cursor/)
 Skills follow the install scope: project-local installs them to the
 repo's `.cursor/skills/`; `--global` installs them to `~/.cursor/skills/`.
 
+As with Claude Code, `--skills-only` refreshes just the skill files and
+skips the MCP config, instructions, and hooks.
+
 Cursor uses a flat hooks format (`{version, hooks:{event:[{command}]}}`)
 and `--json` output for hook commands.
 

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.3",
+  "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