@jeffober/thatch 0.1.35 → 0.1.36

package/README.md

@@ -83,6 +83,15 @@ Thatch gives your agent three layers of persistent context:
   situations arise. The agent ham/spams each surfaced rule to train the
   classifier. Confidence adjusts the same way as predictions. An anti-laziness
   guard in the prompt prevents the agent from codifying shortcuts.
+- **Conversation search** -- the agent can search its own past opencode
+  conversations by substring or regex and retrieve full messages, including
+  complete tool inputs and outputs. Available as tools (`session_search`,
+  `session_get`, opencode only) and as CLI subcommands (`thatch session
+  list/get/transcript/search`, JSONL output designed for piping to `jq`).
+- **Watchers** -- event-driven notifications from external sources (opencode
+  only). The agent registers a watch on a GitHub PR; thatch polls it in the
+  background and prompts the session when comments, commits, CI results, or
+  status changes arrive. Notifications carry pointer data only.
 
 Plus **26 skills** for memory workflows, structured multi-specialist code
 review, review response, change and feature walkthroughs, memory verification,
@@ -98,6 +107,12 @@ host.
 Everything is local. The embedding model downloads once from Hugging Face Hub
 and is cached. No data leaves your machine.
 
+One exception: watchers (opencode only) call the GitHub API through the `gh`
+CLI to poll PRs you explicitly asked to watch, using your existing gh
+authentication. Thatch never sees or stores the token, and notifications
+carry pointer data only - GitHub comment text never enters your context
+unless the agent fetches it.
+
 ## Development
 
 ```bash

package/bin/thatch

@@ -9,6 +9,7 @@ import { BgeEmbeddingModel } from "../src/embeddings";
 import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor } from "../src/setup";
+import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -34,6 +35,15 @@ function usage(): never {
   thatch flush-predictions [--json] Query predictions for the prompt (hook only)
   thatch setup --claude [--cursor] [--global]
                                    Install config + instructions + hooks + skills
+  thatch session list -s <id> [--after T] [--before T]
+                                   JSONL timeline of a session's parts (one line per part)
+  thatch session get --id <part_id|msg_id>
+                                   Full JSON of one part (tool parts include their output)
+                                   or one message with all its parts
+  thatch session transcript -s <id>
+                                   Full conversation as OpenAI chat-completions JSONL
+  thatch session search <query> [--session <id>] [--regex] [--limit N]
+                                   JSONL of matching parts across sessions (decoded content)
 
 Stores default to the repo detected from git remote. Use "global" for the
 global store. Use "all" with search to search project + global together.`);
@@ -67,6 +77,148 @@ function projectDir(): string {
   return process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
 }
 
+// ---------------------------------------------------------------------------
+// session subcommand group - read-only archaeology on the opencode db
+// ---------------------------------------------------------------------------
+
+/** Parses an ISO timestamp or epoch-milliseconds value into epoch ms. */
+function parseTimeBound(value: string, flag: string): number {
+  const asNum = Number(value);
+  if (Number.isFinite(asNum) && value !== "") return asNum;
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) {
+    console.error(`error: ${flag} expects an ISO timestamp or epoch ms, got "${value}"`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+/** Reads a flag's value (-flag value or --flag=value forms). */
+function flagValue(flags: string[], ...names: string[]): string | undefined {
+  for (let i = 0; i < flags.length; i++) {
+    for (const name of names) {
+      if (flags[i] === name) return flags[i + 1];
+      if (flags[i]?.startsWith(`${name}=`)) return flags[i]!.slice(name.length + 1);
+    }
+  }
+  return undefined;
+}
+
+function openSessionDb(): SessionDB {
+  const path = resolveOpencodeDbPath();
+  if (!path) {
+    console.error(
+      "error: no opencode database found. The session commands inspect the\n" +
+        "session history of the opencode host; other hosts (Claude Code, Cursor)\n" +
+        "have no such database. Set OPENCODE_DB to point at an opencode.db file.",
+    );
+    process.exit(1);
+  }
+  return new SessionDB(path);
+}
+
+async function sessionCommand(rest: string[]): Promise<void> {
+  const [sub, ...restArgs] = rest;
+  const sessionID = flagValue(restArgs, "-s", "--session");
+  const after = flagValue(restArgs, "--after");
+  const before = flagValue(restArgs, "--before");
+
+  const db = openSessionDb();
+  try {
+    switch (sub) {
+      case "list": {
+        if (!sessionID) {
+          console.error("error: session list requires -s/--session <session id>");
+          process.exit(1);
+        }
+        const parts = db.listParts(
+          sessionID,
+          after ? parseTimeBound(after, "--after") : undefined,
+          before ? parseTimeBound(before, "--before") : undefined,
+        );
+        for (const part of parts) console.log(JSON.stringify(partToTimelineEntry(part)));
+        break;
+      }
+
+      case "get": {
+        const id = flagValue(restArgs, "--id");
+        if (!id) {
+          console.error("error: session get requires --id <part_id|msg_id>");
+          process.exit(1);
+        }
+        if (id.startsWith("msg_")) {
+          const message = db.getMessage(id);
+          if (!message) {
+            console.error(`error: no message "${id}" in ${db.path}`);
+            process.exit(1);
+          }
+          console.log(JSON.stringify(messageToFullJson(message), null, 2));
+        } else {
+          const part = db.getPart(id);
+          if (!part) {
+            console.error(`error: no part "${id}" in ${db.path}`);
+            process.exit(1);
+          }
+          console.log(JSON.stringify(partToFullJson(part), null, 2));
+        }
+        break;
+      }
+
+      case "transcript": {
+        if (!sessionID) {
+          console.error("error: session transcript requires -s/--session <session id>");
+          process.exit(1);
+        }
+        for (const message of db.listMessages(sessionID)) {
+          for (const entry of partToTranscriptEntries(message.role, message.parts)) {
+            console.log(JSON.stringify(entry));
+          }
+        }
+        break;
+      }
+
+      case "search": {
+        // Positional = args not preceded by a value-taking flag. Values like
+        // "50" or a session id don't start with "-", so predecessor checks
+        // are the only reliable discriminator.
+        const valueFlags = new Set(["-s", "--session", "--limit"]);
+        const positional = restArgs.filter((a, i) => !a.startsWith("-") && !valueFlags.has(restArgs[i - 1] ?? ""));
+        const query = positional[0];
+        if (!query) {
+          console.error("error: session search requires a query (substring, or regex with --regex)");
+          process.exit(1);
+        }
+        const limit = flagValue(restArgs, "--limit");
+        const matches = db.search(query, {
+          regex: restArgs.includes("--regex"),
+          sessionID,
+          limit: limit ? parseInt(limit, 10) : undefined,
+        });
+        // Titles let a cross-session result list be triaged without a
+        // second lookup per hit. Sessions are cached - matches cluster.
+        const titles = new Map<string, string | null>();
+        for (const part of matches) {
+          if (!titles.has(part.sessionId)) {
+            titles.set(part.sessionId, db.getSession(part.sessionId)?.title ?? null);
+          }
+          const entry: Record<string, unknown> = {
+            session_id: part.sessionId,
+            session_title: titles.get(part.sessionId),
+            ...partToTimelineEntry(part),
+          };
+          console.log(JSON.stringify(entry));
+        }
+        break;
+      }
+
+      default:
+        usage();
+    }
+  } finally {
+    db.close();
+  }
+}
+
 switch (command) {
   case "--version":
   case "-v":
@@ -290,6 +442,11 @@ switch (command) {
     break;
   }
 
+  case "session": {
+    await sessionCommand(args);
+    break;
+  }
+
   case "buffer-batch": {
     // PostToolBatch hook: append the batch's tool_calls to the session's
     // JSONL queue. Silent on success - no stdout - so the next model call

package/docs/dev/README.md

@@ -31,12 +31,17 @@ Shared core
   ├── prediction.ts   → prediction engine wrapper (thin layer over ScoringEngine)
   ├── behavior.ts     → behavior engine wrapper (thin layer over ScoringEngine)
   ├── seed-behaviors.ts → default behavior seeding on first run
+  ├── session-db.ts   → read-only opencode.db access: session timeline, full parts,
+  │                     decoded-content search, OpenAI transcript builder (backs the
+  │                     `thatch session` CLI and the opencode-only session tools)
   └── vector-math.ts  → blobToVector + cosineSimilarity helpers
 
 OpenCode plugin path
   ├── index.ts        → plugin entry: wires DB/model/extraction, registers tools + hooks
   ├── tools.ts        → thin opencode tool() wrappers over tool-defs
-  └── extraction.ts   → in-memory ring buffer + shared payload builders
+  ├── extraction.ts   → in-memory ring buffer + shared payload builders
+  └── watchers.ts     → in-memory watcher registry + poller (opencode-only,
+                        event-driven PR notifications delivered as prompts)
 
 MCP server path
   ├── mcp.ts          → stdio JSON-RPC server: z.toJSONSchema() for tools/list,
@@ -67,6 +72,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
+| `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
+| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches a GitHub PR via `gh api` (injected `GhRunner`), diffs against last-seen state, queues pointer-only events per session, and delivers them through a plugin-supplied callback when the session is idle. Process-lifetime state by design - no SQLite. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (25 skills: fact-extractor, dedup-classifier, project-primer, 8 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
@@ -87,8 +94,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
 | `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
-| `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status` (idle): if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child. `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
-| `dispose` | Closes the DB. |
+| `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher delivery gate; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, and cancels the session's watchers. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
+| `dispose` | Stops the version checker and the watcher poller, closes the DB. |
 
 Hook failures are logged with a `[thatch]` prefix — never swallowed silently.
 Two of these hooks were dead for weeks because failures were invisible.

package/docs/dev/features/README.md

@@ -26,6 +26,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
+| [watchers.md](watchers.md) | Event-driven notifications (in-memory registry, background poller, PR watching) |
 | [setup.md](setup.md) | Setup system (markers, checkSetup, auto-refresh, binary resolution) |
 | [cli.md](cli.md) | CLI (subcommands, environment variables) |
 | [database.md](database.md) | Database (schema, migrations, WAL, 11 tables) |

package/docs/dev/features/multi-host.md

@@ -16,9 +16,12 @@ Thatch supports three host agents from a single codebase:
 - **Cursor MCP**---same stdio MCP server, `--json` hook output format,
   `mcp__thatch__` tool prefix, system prompt in AGENTS.md
 
-All three paths expose the same 18 tool definitions from `src/tool-defs.ts`.
-The tools are host-agnostic: each takes args and a `CoreContext`
-(`{ db, model, defaultStore }`) and returns a string. The host-specific
+All three paths share the tool definitions from `src/tool-defs.ts`: 18
+host-agnostic tools plus opencode-only tools (currently six:
+`get_session_info`, `session_search`/`session_get`, and the
+`watch_create`/`watch_list`/`watch_cancel` watcher tools), which the MCP server
+filters out. The shared tools take args and a `CoreContext`
+(`{ db, model, defaultStore }`) and return a string. The host-specific
 wrapping---prefixing, transport, session hooks---lives outside the core.
 
 ## The three paths
@@ -147,7 +150,7 @@ an asymmetry a reviewer can catch by diffing the tool lines.
 
 ## Tool name prefixing
 
-The 18 tool definitions in `src/tool-defs.ts` use bare names:
+The tool definitions in `src/tool-defs.ts` use bare names:
 `memory_remember`, `memory_recall`, `memory_list`, etc. Each host applies its
 own prefix.
 
@@ -177,13 +180,16 @@ behavior, with some features having no MCP counterpart.
 | code-review coordinator skill | Yes | No | No |
 | Background sub-agents | Yes (experimental) | No | No |
 | Tool batching | N/A (in-process) | PostToolBatch (batch) | postToolUse (per-tool) |
+| `get_session_info` (session identity) | Yes | No | No |
+| `session_search` / `session_get` (conversation archaeology) | Yes (tools) | CLI only (`thatch session ...`) | CLI only (`thatch session ...`) |
 
 For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
 
 ## Interactions with other features
 
-All 18 tools are shared across all hosts via the single source of truth in
-`src/tool-defs.ts`. Individual tool behavior is documented in
+The 18 shared tools are available on all hosts via the single source of truth
+in `src/tool-defs.ts`; opencode-only tools (e.g. `get_session_info`) are
+filtered out by the MCP server. Individual tool behavior is documented in
 [memory-store.md](memory-store.md), [extraction.md](extraction.md),
 [prediction-engine.md](prediction-engine.md),
 [behavior-engine.md](behavior-engine.md), and
@@ -216,13 +222,13 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 | `src/setup.ts` | Setup installer for Claude Code and Cursor---markers, hooks, skills |
 | `src/prompts.ts` | All three system prompt variants---`systemPrompt()`, `claudeInstructions()`, `cursorInstructions()` |
 | `src/tools.ts` | Thin opencode tool wrappers---imports tool-defs, adds `thatch_` prefix via `tool()` |
-| `src/tool-defs.ts` | Single source of truth for all 18 tool definitions---name, description, zod schema, execute |
+| `src/tool-defs.ts` | Single source of truth for all tool definitions---name, description, zod schema, execute, `opencodeOnly` flag |
 | `bin/thatch` | CLI hook commands for MCP hosts---`reminder`, `buffer-tool`, `flush-tools`, `setup` |
 
 ## Key invariants
 
-- All three hosts share the same 18 tool definitions from `src/tool-defs.ts`. Adding a tool requires updating `TOOL_DEFS` and all three prompt functions.
+- All hosts share the tool definitions from `src/tool-defs.ts` (18 shared + opencode-only tools marked `opencodeOnly: true`, which the MCP server filters out). Adding a tool requires updating `TOOL_DEFS` and all three prompt functions; opencode-only tools go in the opencode prompt only.
 - The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
 - The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
-- The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts`. The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.
-- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts) have no MCP counterpart.
+- The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts` (opencode's list includes opencode-only tools; the MCP lists exclude them). The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.
+- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts, `get_session_info`, `session_search`/`session_get`, PR watchers) have no MCP counterpart. The `thatch session` CLI subcommands work anywhere - they only need an opencode.db file to read.

package/docs/dev/features/watchers.md

@@ -0,0 +1,150 @@
+# Watchers
+
+Watchers are the general mechanism for event-driven notifications from
+external sources: the model registers a watch on something outside the
+session, thatch polls it in the background, and the plugin prompts the
+session when a watched event happens. The first source is GitHub pull
+requests. The registry, poller, and delivery are source-agnostic - a
+future source only adds a fetch-and-diff function and event types.
+
+User-facing behavior is documented in [docs/user/watchers.md](../../user/watchers.md).
+
+## What it does
+
+- `thatch_watch_create` / `thatch_watch_list` / `thatch_watch_cancel` tools (opencode-only)
+- A background poller in the plugin process diffs each watcher's target
+  against its last-seen state
+- Delivery prompts the session with a synthetic part - the same
+  mechanism opencode uses for background task completions
+- Notifications carry pointer data only (author, URL, counts); the
+  model fetches content on demand with `gh`
+
+## The process-lifetime decision
+
+The registry lives in plugin memory, never in SQLite. Three reasons:
+
+1. **Ownership is structural.** opencode loads thatch in-process, so
+   the plugin process that registered a watcher is the only process
+   that can poll and deliver it. A shared registry would need
+   claiming logic to answer "which process polls this?" - and
+   version-skewed opencode instances sharing a DB have already caused
+   corruption once.
+2. **No orphans.** When the process exits, watcher state evaporates
+   with it. There is no cleanup path to get wrong.
+3. **Precedent.** The extraction pipeline's opencode path is also
+   in-memory; the file-backed queue exists only for the MCP path's
+   separate short-lived hook processes.
+
+The cost: a restart loses watches. Accepted because the session that
+created them loses its conversational context too - a notification
+into a session that no longer knows why it is being watched is worse
+than a lost watch.
+
+`session.deleted` also cancels the session's watchers and pending
+events, and `dispose` stops the poller. These are cheap insurance;
+process exit is the real lifetime boundary in both TUI and serve mode
+(plugins load per-instance in the server process under
+`opencode serve`, so watchers work there too).
+
+## How it works
+
+### Registration (`watch_create`)
+
+`create()` immediately fetches the PR's state as a baseline via
+`fetchPrState()` - four `gh api` calls (the pull, issue comments,
+review comments, check runs on the head SHA), three of them in
+parallel. The baseline doubles as validation: a missing PR, wrong
+repo, or broken gh setup fails registration with a real error instead
+of producing a watcher that never fires. Watch creation is also gated
+on a cached `gh --version` availability check.
+
+### Polling
+
+A `setInterval` loop (unref'd - it never keeps the process alive)
+runs `poll()` every 60 seconds (configurable). Each cycle:
+fetch the current state, run `diffPrState()` against the watcher's
+last-seen state, filter events to the watched types, queue them, and
+attempt delivery. Poll errors are per-watcher; one bad PR never
+blocks the others. The diff is a pure function, so it is unit-tested
+without any network access.
+
+Event detection:
+
+- comments by id monotonicity (fetch is sorted descending)
+- commits by head SHA change
+- status/merged by field change
+- description by SHA-256 of the body text (the body itself is never
+  stored)
+- CI by check-run transitions into a completed status
+
+A diff emits at most 10 events per watcher per cycle, so comment
+floods collapse into one batch.
+
+### Delivery
+
+Events queue in an in-memory pending map keyed by session. Delivery
+is gated by a `canDeliver` predicate the plugin supplies: the session
+must be idle (tracked from `session.status` events) and not
+compacting. Proactive prompts are never injected into a running turn.
+
+When the gate is open, the plugin calls `client.session.promptAsync`
+on the session with a synthetic text part built by
+`watcherNotificationNudge()`. This triggers a full model turn - the
+model reads the notification and decides whether to act. The
+notification text borrows the background-task-completion framing
+(system event, not user input, not approval to advance other work),
+following the same load-bearing wording discipline as the extraction
+nudge.
+
+Failed or gated deliveries stay pending and retry on the next poll
+cycle or when the session next goes idle (the event hook calls
+`deliverPending()` there).
+
+### Event vocabulary
+
+`pr_comment`, `pr_review_comment`, `pr_review_reply`, `pr_commit`,
+`pr_status`, `pr_description`, `pr_ci`. The tool's `events` argument
+selects a subset; the default is all seven.
+
+## Interactions with other features
+
+- Extraction pipeline ([extraction.md](extraction.md)): the
+  notification turn's tool calls are buffered and extracted like any
+  other turn. Watch tools themselves are `thatch_*`-prefixed and
+  excluded from buffering.
+- Session lifecycle ([session-lifecycle.md](session-lifecycle.md)):
+  `session.status` feeds the delivery gate; `session.deleted`
+  cancels watchers.
+- Multi-host ([multi-host.md](multi-host.md)): opencode-only. MCP
+  hosts have no poller, no event bus, and no channel to start a turn
+  proactively. A future CLI daemon could close this gap.
+
+## Configuration
+
+- `THATCH_WATCH_POLL_SECONDS` - poll interval (default 60)
+- `THATCH_WATCH_TTL_MINUTES` - watcher time-to-live (default 480)
+- `THATCH_WATCH_MAX_PER_SESSION` - active watchers per session
+  (default 5)
+
+## Source files
+
+- `src/watchers.ts` - registry, poller, gh CLI runner, diff functions
+- `src/tool-defs.ts` - the three watch tool definitions
+- `src/index.ts` - registry construction, delivery closure,
+  session.status tracking, session.deleted cleanup, dispose
+- `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
+  Watchers section
+- `tests/watchers.test.ts` - registry, poll, and diff unit tests
+  (mocked gh, no network)
+- `tests/qa/auto/uc-095-watchers.ts` - end-to-end lifecycle against a
+  mocked gh runner
+
+## Adding a new source type
+
+The registry is source-agnostic in shape but currently hardcoded to
+the github-pr fetch/diff pair. A new source type means: new event
+types in `WATCHER_EVENT_TYPES`, a fetch/diff function pair, a
+`source_type` discriminator on `Watcher` (add it when the second
+source arrives - do not parameterize early), and the tool surface for
+registering it. Keep the pointer-only notification rule: external
+content enters the context on explicit fetch, never via notification.

package/docs/dev/mcp-parity.md

@@ -18,7 +18,7 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (18, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
+| **Tools** (18 shared + 6 opencode-only, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the 18 shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |

package/docs/dev/skills.md

@@ -119,10 +119,12 @@ and `--cursor` pass only the shared set.
   versions without users manually deleting files.
 - **Stale cleanup**: before installing, `installSkills` removes stale skill
   directories. Any `thatch-*` directory not in the current install set is
-  deleted (the `thatch-` prefix is our namespace). Three skills renamed from
-  non-prefixed to `thatch-`-prefixed in v0.1.27 (pr-description, ticket-description,
-  split-overlarge-pr) are also cleaned up through v0.1.35; after that, those
-  names are fair game for third parties and the cleanup stops.
+  deleted (the `thatch-` prefix is our namespace). Non-prefixed directories
+  are never touched: the v0.1.27 rename migration (pr-description,
+  ticket-description, split-overlarge-pr) cleaned up old installs only
+  through a version window that closed with v0.1.35, after which those names
+  are fair game for third parties and the cleanup no longer runs. Users
+  upgrading from before v0.1.27 delete the old directories manually.
 - **Idempotent**: re-running init or setup overwrites drifted content but leaves
   unrelated (non-`thatch-*`) skill files alone.
 

package/docs/user/README.md

@@ -11,6 +11,7 @@ This README is the overview. Each feature has its own guide:
 
 - [memory.md](memory.md): persistent memory store
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
+- [watchers.md](watchers.md): event-driven notifications (PR watching)
 - [prediction-engine.md](prediction-engine.md): user decision model
 - [behavior-engine.md](behavior-engine.md): agent self-discipline rules
 - [default-behaviors.md](default-behaviors.md): what ships automatically
@@ -142,6 +143,29 @@ Stores are created automatically. No setup required.
 | `thatch_behavior_list` | List all codified behaviors with matchers, confidence, and provenance. |
 | `thatch_behavior_delete` | Delete a behavior by semantic match. Edges and provenance are cascade-deleted. |
 
+### Session tools (opencode only)
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_get_session_info` | Report the current session's ID and the agent name running this turn. opencode doesn't surface its session ID to the model; the agent needs it to fetch extraction payloads or look up past sessions. MCP hosts have no session concept, so this tool doesn't exist there. |
+| `thatch_session_search` | Search past opencode conversations by substring or regex. Matches decoded message text, tool outputs, and reasoning across all sessions. Returns JSONL hits with ids for follow-up. |
+| `thatch_session_get` | Retrieve the full content of one part or message found via `thatch_session_search`, including complete tool inputs and outputs. |
+
+The same functionality is available on the command line as `thatch session
+list`, `thatch session get`, `thatch session transcript`, and `thatch session
+search` - JSONL output designed for piping to `jq` or `grep`.
+
+### Watcher tools (opencode only)
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
+| `thatch_watch_list` | List this session's active watchers. |
+| `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
+
+See [watchers.md](watchers.md) for the full behavior, lifetime, and
+requirements.
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:

package/docs/user/watchers.md

@@ -0,0 +1,79 @@
+# Watchers
+
+Watchers monitor external sources - today, GitHub pull requests - and
+inject a notification into the conversation when something happens. You
+ask the agent to watch a PR; thatch polls it in the background; the
+agent gets woken up when a watched event occurs. No one has to keep
+asking "any updates yet?"
+
+## What it does
+
+The agent calls `thatch_watch_create` to register a watcher on a PR.
+thatch captures the PR's current state as a baseline, then polls the
+GitHub API through the `gh` CLI once a minute. When the PR changes in a
+way the watcher cares about, the plugin prompts the agent with a
+notification.
+
+Watched events:
+
+- `pr_comment` - new top-level comments on the PR
+- `pr_review_comment` - new inline comments on the diff
+- `pr_review_reply` - replies to an existing review comment
+- `pr_commit` - new commits (the head SHA moved)
+- `pr_status` - the PR opened, closed, or merged
+- `pr_description` - title or description edited
+- `pr_ci` - a CI check run on the head SHA completed
+
+Notifications are delivered as synthetic parts: the model sees them,
+the transcript does not. A notification triggers a model turn, so the
+agent can act on the event even while you are away.
+
+## Privacy model
+
+Notifications carry pointer data only: who commented, what happened,
+and a URL. Comment bodies, diff contents, and CI logs never enter the
+context from the notification itself. This is deliberate - GitHub
+comments are written by strangers, and untrusted text flowing into a
+model's context is a prompt-injection vector. The agent fetches details
+on demand with `gh` when it decides to act.
+
+## How to use it
+
+Ask for it in conversation:
+
+> Watch PR 1234 for review comments. If bugbot comments, handle it
+> yourself. If a human comments, just tell me.
+
+The handling policy lives in your instruction. State it when you ask -
+the notification turn reads your policy from the conversation and
+follows it. The notification says what happened and where, not what to
+do about it.
+
+Other tools:
+
+- `thatch_watch_list` - shows the session's active watchers
+- `thatch_watch_cancel` - cancels one by id
+
+## Lifetime
+
+Watchers are in-memory and process-scoped:
+
+- Ending the opencode process (or restarting it) drops all watchers.
+- A watcher expires after 8 hours by default.
+- Each session can hold up to 5 active watchers.
+
+If opencode restarts while a watch is active, re-register it - the
+session's conversation survives, so the policy you stated is still
+there.
+
+## Requirements and limitations
+
+- **opencode only.** MCP hosts (Claude Code, Cursor) have no way for a
+  plugin to start a conversation turn, so the watch tools are not
+  available there.
+- **Requires the `gh` CLI** to be installed and authenticated. Watch
+  creation reports a clear error if it is not.
+- **Polling, not webhooks.** Events appear on the next poll cycle
+  (60 seconds by default), not instantly.
+- **No delivery during an active turn.** If the agent is mid-turn when
+  an event fires, the notification waits until the turn ends.

package/package.json

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