@jeffober/thatch 0.1.34 → 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/artifacts/skills/thatch-code-review.md

@@ -26,6 +26,8 @@ Also detect whether the current branch has a **connected PR/MR** even when none
 
 Also fetch any refs not locally reachable so branches and PRs that were never checked out can be reviewed (e.g. `git fetch origin <branch>` for a PR head).
 
+**Anchor discipline**: the working tree may be checked out on any branch — main, another feature, a detached HEAD — and is not guaranteed to match the change under review. Resolve the head SHA of the review range (`git rev-parse <head-ref>`), and compute every file:line citation and review-comment anchor against that ref with `git show <head-sha>:<path>` — never from the working tree, and never from the base. When the working tree happens to be the PR branch this is equivalent, so apply the rule unconditionally rather than branching on it. Pass the head SHA to sub-agents (see the briefing template).
+
 Run git diff --stat on the resolved range and git log --oneline to understand the change.
 
 ## Step 2: Gather project context
@@ -38,7 +40,9 @@ Load the thatch-review-context skill and follow its methodology to build a conte
 - thatch_memory_recall for feature/project status, design decisions, ticket dependencies
 - Project docs, READMEs, design docs
 - Issue tracker (gh issue/view) if ticket IDs are found
-- **Prior review comments** — if Step 1 detected a connected PR/MR, fetch ALL prior review comments on it (see source #8 in the review-context skill) and build the prior-comments register with a preliminary addressed-check status per comment. This is what distinguishes a **follow-up round** (register non-empty) from the **first round** (register empty or PR has no prior reviews). If Step 1 found no connected PR/MR, the brief explicitly states `Local-branch review — no prior-comment fetch`.
+- **Links in the change** — docs, designs, tickets, and related PRs linked from the PR description, commit messages, or the changed files themselves; follow them for scope and design context (see source #8 in the review-context skill)
+- **Staleness check** — whether main has moved past the merge-base touching the same paths (see source #3 in the review-context skill); when it has, record the commits in the brief
+- **Prior review comments** — if Step 1 detected a connected PR/MR, fetch ALL prior review comments on it (see source #9 in the review-context skill) and build the prior-comments register with a preliminary addressed-check status per comment. This is what distinguishes a **follow-up round** (register non-empty) from the **first round** (register empty or PR has no prior reviews). If Step 1 found no connected PR/MR, the brief explicitly states `Local-branch review — no prior-comment fetch`.
 
 Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints, and the prior review comments section when present).
 
@@ -123,6 +127,7 @@ Pass the synthesizer:
 - The workflow guide from Step 3.
 - The specialist findings.
 - The prior-comments register when present.
+- The staleness signal from the brief (commits on main after the merge-base touching this change's paths), when present.
 
 The final user-facing report MUST begin with a concise explanation of the workflow(s) this PR changes before listing findings. Use one `### Workflow changes` section, with one subheading per affected workflow when there are multiple. Use the before/now walkthrough shape from the thatch-pr-description skill: numbered step = existing behavior; `NOW` sub-bullet = what the PR changes; `N/A` for new stages. This gives the user a map of the change before the findings. Keep it short: 3-6 steps per workflow.
 
@@ -136,7 +141,7 @@ Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
 7. Produce a final report with a workflow-change preface, highlights (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
@@ -145,6 +150,7 @@ Alternatively, perform the synthesis yourself:
 
 When dispatching each sub-agent, include in the prompt:
 - The git range to review
+- **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
 - The specialist focus (from the eight specialists above)
 - The diff stat for this unit's files

package/artifacts/skills/thatch-review-context.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-review-context
-description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, docs, and memory to build a context brief that prevents false positives about intentionally deferred work. Use before dispatching review specialists or running a solo review.
+description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, linked docs/tickets, docs, and memory to build a context brief that prevents false positives about intentionally deferred work. Use before dispatching review specialists or running a solo review.
 ---
 
 You are a review context builder. Your job is to gather project context that gives reviewers the background they need to avoid false positives about intentionally deferred work, incomplete features, and multi-ticket dependencies.
@@ -28,6 +28,7 @@ Branch names often contain ticket identifiers. Look for patterns:
 - `git log --all --oneline --grep="TICKET-ID"` — find related commits on other branches
 - `git log -S "TODO (TICKET"` — find TODO markers that reference this or related tickets
 - `git branch -a` — other branches may show planned or in-progress related work
+- **Staleness check**: `git log --oneline <merge-base>..origin/main -- <changed paths>` — commits that landed on main AFTER this branch's merge-base, touching the same files. If any exist, the branch is stale relative to main and findings true at the merge-base may already be moot. List these commits in the brief under Dependencies so the synthesizer re-verifies findings against current main.
 
 ### 4. TODO ($ticket) markers in the diff
 Scan the diff for TODO markers that reference ticket identifiers:
@@ -56,7 +57,17 @@ If ticket IDs were found:
 - Look for milestone assignments, dependencies, and blocking relationships
 - Check for epic or parent issues that describe the overall feature
 
-### 8. Prior review comments (follow-up round detection)
+### 8. Links in the change (follow the references)
+
+Collect links to material outside the diff that a reviewer would need for context, then follow them:
+- PR description links: docs, design docs, RFCs, tickets, related PRs
+- Commit message links and ticket references
+- Links inside the changed files themselves: READMEs, doc comments, config comments referencing designs or runbooks
+- Ticket bodies from source 7, which often link parent epics, blocking issues, or design docs
+
+Follow each link one hop and read it for review-relevant context: scope, design decisions, constraints, deferred work, sibling changes. If a linked document references another artifact that is directly about this change (a parent epic, a design doc for the same feature), follow that too. Stop at depth 2, and stop following a path once the linked material stops changing what a reviewer would flag. Record anything that changes review context in the brief. A link that 404s or requires access you do not have is not a finding — note it as `link unreachable` and move on.
+
+### 9. Prior review comments (follow-up round detection)
 
 If the change under review has a connected PR/MR on the upstream remote, fetch all prior review comments so this review does not duplicate already-identified issues. Any prior review activity on the PR/MR means **this is a follow-up round**, not the first review. If no PR/MR is connected, this is a **local-branch review** — skip this source entirely; the existing review procedure applies.
 
@@ -113,7 +124,7 @@ For each comment, attempt to determine whether it has been addressed in the **cu
 
 The register produced here is a **preliminary** classification. The synthesizer produces the final cross-reference, including any prelim-status overrides when new findings from the specialist round reproduce or refute a prior comment.
 
-### 9. Repo structure conventions (implicit)
+### 10. Repo structure conventions (implicit)
 Directory structure conventions are often undocumented. They live in the repo's layout itself, not in a CONTRIBUTING.md. Look at the directory tree to identify how the repo organizes code:
 - `git ls-files | head -50` or `ls` at the top level to see the organizational pattern
 - For multi-app repos, identify whether shared packages live inside app directories or at the repo root
@@ -143,6 +154,7 @@ List each deferred piece:
 - What other tickets or PRs this depends on (must merge first)
 - What tickets or PRs depend on this (are blocked by it)
 - Whether base branches have landed (for stacked PRs)
+- **Staleness**: whether main has moved past the merge-base since the branch point. When the staleness check (source 3) found commits touching this change's paths, list them here — the synthesizer re-verifies behavioral findings against current main before classifying them
 
 ### Relevant constraints
 - Design decisions or architectural constraints from memories or docs

package/artifacts/skills/thatch-review-synthesizer.md

@@ -31,11 +31,9 @@ For each finding from the specialists:
 
 5a. **Verify governing constraints for data-shape findings.** For findings claiming a field can be NULL/missing/orphaned/malformed, locate and read the field's definition (schema migration, model, type declaration). If a NOT NULL, FK, enum, or type constraint forecloses the claimed state, REJECT and cite the constraint. Do not classify such a finding CONFIRMED without having read the governing definition.
 
+5b. **Re-verify against post-branch-point main (behavioral findings, only when the context brief flags staleness).** If the brief reports commits on main after this branch's merge-base touching this change's paths, the branch may be stale and a finding can be true at the merge-base but already moot on main. For each behavioral finding, read the equivalent code on current main (`git show origin/main:<path>`). A finding that main has already fixed or mooted is a **rebase note**, not a defect in this PR: keep it out of the confirmed findings and list it in the report's rebase-notes appendix instead.
+
 6. **Verify intent (behavioral findings only).** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
-   - Read the callers of the cited code to see if the pattern makes sense in context.
-   - Check git log or git blame on the cited file for commit messages explaining the decision.
-   - Use thatch_memory_recall to search for documented rationale.
-   If the behavior is intentional or an accepted limitation, reject the finding.
 
 4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments, structural conventions).** For mechanical findings, verification means:
     - The cited text exists at the cited location (already confirmed in step 2). For PLACEMENT findings, the cited evidence is the file path and the existing directory structure, not quoted code. Verify the file exists at the claimed path and that the existing structure shows the convention the specialist cited.
@@ -71,7 +69,7 @@ Multiple findings may stem from the same underlying issue (e.g., a contract mism
 
 ## Cross-reference against prior review comments
 
-If your input includes a **prior-comments register** (built by the coordinator via `thatch-review-context` source #8 — prior review comments retrieved from the PR/MR's review history), cross-reference every confirmed and rejected finding against it so the final report does not present already-identified issues as fresh discoveries.
+If your input includes a **prior-comments register** (built by the coordinator via `thatch-review-context` source #9 — prior review comments retrieved from the PR/MR's review history), cross-reference every confirmed and rejected finding against it so the final report does not present already-identified issues as fresh discoveries.
 
 For each new finding:
 1. **Search for a matching prior comment** by location and semantic claim. Match if both hold:
@@ -255,6 +253,10 @@ Findings you rejected and a one-line reason why. Include the specialist and loca
 
 Findings you verified as real but pre-existing, with a one-line note on the issue and its potential impact.
 
+### Rebase notes (appendix, brief — only when the context brief flags staleness)
+
+Findings that were true at the merge-base but are already fixed or mooted by later commits on main. One line each: the finding, and the main commit that moots it. Omit this section entirely when the brief reports no staleness.
+
 ### Previously identified findings (appendix — only when a prior-comments register was provided)
 
 List every entry from the prior-comments register here. For each entry, produce a one-block record:

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 |