@jeffober/thatch 0.1.34 → 0.1.36

package/docs/dev/skills.md

@@ -47,7 +47,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
-| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-code-archaeology` | Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |
@@ -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:
@@ -237,7 +261,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
-| `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, linked docs/tickets, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |

package/docs/user/code-review.md

@@ -10,9 +10,15 @@ The coordinator skill (`thatch-code-review`, opencode-only) orchestrates
 the review:
 
 1. **Resolve the target**: fetch origin, compute merge-base against
-   `origin/main`, support branch/PR/explicit range.
+   `origin/main`, support branch/PR/explicit range. All file reads and
+   comment anchors are computed against the PR head ref, not the
+   working tree, which may be checked out on a different branch.
 2. **Gather project context**: PR descriptions, git archaeology,
-   ticket references, TODO markers, prior reviews, project memory.
+   ticket references, links to docs/designs/tickets found in the
+   change (followed one hop for scope and design context), TODO
+   markers, prior reviews, project memory. Also checks whether main
+   has moved past the merge-base touching the same paths — a stale
+   branch can make findings true only at the merge-base.
 3. **Research affected workflows**: load `thatch-code-archaeology`,
    trace the code paths the change touches.
 4. **Estimate complexity**: partition the diff into review units.
@@ -21,7 +27,9 @@ the review:
 6. **Synthesize**: the synthesizer reads all specialist output,
    verifies each finding (cited text exists, claim is accurate,
    severity is justified), deduplicates by root cause, and produces
-   the final report.
+   the final report. When the branch is stale relative to main, it
+   re-verifies behavioral findings against current main and reports
+   merge-base-only findings as rebase notes rather than defects.
 
 ## The eight specialists
 

package/docs/user/skills.md

@@ -46,7 +46,7 @@ becomes part of the agent's context.
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
-| `thatch-review-context` | Gathers project context (PRs, tickets, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |

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

package/src/index.ts

@@ -21,6 +21,8 @@ import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
+import { WatcherRegistry, ghApiRun, ghAvailable } from "./watchers";
+import { watcherNotificationNudge } from "./prompts";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -83,6 +85,43 @@ export const server: Plugin = async ({ client, worktree }) => {
   // non-restart.
   const runningVersion = pkg.version;
 
+  // Latest observed opencode session status per session ("busy" | "idle" |
+  // "retry"). The event hook records these; the watcher registry's
+  // canDeliver gate reads them so proactive notification prompts only fire
+  // into idle sessions - never into a turn that is already running.
+  const sessionStatus = new Map<string, string>();
+
+  // In-memory watcher registry for proactive event notifications (GitHub PR
+  // watching today). Deliberately process-scoped: no SQLite, no cross-restart
+  // state. See src/watchers.ts for the rationale.
+  //
+  // Delivery prompts the session with a synthetic part - the same mechanism
+  // opencode uses for background task completions - so a watched event
+  // triggers a model turn even when the user is away. Events only carry
+  // pointer data; the model fetches details itself with gh.
+  const watchers = new WatcherRegistry({
+    deliver: async (sessionID, events) => {
+      const target = events[0]?.url.match(/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/)?.[0]
+        ?.replace(/github\.com\//, "")
+        .replace(/\/pull\//, "#") ?? "watched PR";
+      await client.session.promptAsync({
+        path: { id: sessionID },
+        body: {
+          parts: [{ type: "text", text: watcherNotificationNudge(target, events), synthetic: true }],
+        },
+      });
+    },
+    canDeliver: (sessionID) =>
+      !compacting.has(sessionID) && sessionStatus.get(sessionID) === "idle",
+    ghRunner: ghApiRun,
+  });
+  // gh presence decides whether watch_create works; checked lazily by the
+  // tool, but log once at startup so misconfiguration is visible in debug logs.
+  void ghAvailable().then((ok) => {
+    if (!ok) console.error("[thatch] gh CLI not found - watch tools will report unavailable");
+  });
+  watchers.start();
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -242,6 +281,7 @@ export const server: Plugin = async ({ client, worktree }) => {
         if (all.length === 0) return null;
         return extraction.buildPayload(all, repo);
       },
+      watcherRegistry: watchers,
     }),
 
     // 1. System prompt - always in context.
@@ -600,8 +640,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         }
         return;
       }
-      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+      if (event.type === "session.status") {
         const sessionID = event.properties.sessionID;
+        const statusType = event.properties.status?.type;
+        // Record the latest status so the watcher registry can gate
+        // proactive prompt delivery on idle sessions.
+        if (sessionID && statusType) sessionStatus.set(sessionID, statusType);
+        if (statusType !== "idle") return;
         const parentID = sessionID ? childToParent.get(sessionID) : undefined;
         if (parentID && sessionID) {
           // A child session went idle. Two cases:
@@ -685,6 +730,15 @@ export const server: Plugin = async ({ client, worktree }) => {
             extracting.delete(sessionID);
           }
         }
+        // The session just became idle, so watcher events queued while it
+        // was busy can be delivered now - the poll interval may otherwise
+        // hold them for up to a full cycle. Best-effort; failures stay
+        // pending and retry on the next poll.
+        try {
+          await watchers.deliverPending();
+        } catch (err) {
+          console.error(`[thatch] watcher delivery on idle failed: ${err}`);
+        }
         return;
       }
       if (event.type === "session.deleted") {
@@ -699,9 +753,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         parentSnapshots.delete(id);
         childMetrics.delete(id);
         extractionChildren.delete(id);
-        // A deleted parent takes its accepted entries with it.
+        // A deleted parent takes its accepted entries with it, and its
+        // watchers die with it - the session that would receive their
+        // notifications no longer exists.
         extraction.completeAccepted(id);
         extracting.delete(id);
+        sessionStatus.delete(id);
+        watchers.cancelSession(id);
         return;
       }
 
@@ -739,6 +797,7 @@ export const server: Plugin = async ({ client, worktree }) => {
 
     dispose: async () => {
       stopVersionChecker();
+      watchers.dispose();
       db.close();
     },
   };

package/src/mcp.ts

@@ -60,9 +60,12 @@ interface CompiledTool {
   inputSchema: Record<string, unknown>;
 }
 
-function compileTools(): Map<string, CompiledTool> {
+export function compileTools(): Map<string, CompiledTool> {
   const map = new Map<string, CompiledTool>();
   for (const def of TOOL_DEFS) {
+    // opencode-only tools depend on host capabilities MCP servers don't
+    // have (e.g. session identity via HostToolContext) - never expose them.
+    if (def.opencodeOnly) continue;
     const schema = z.object(def.args);
     map.set(def.name, {
       def,

package/src/prompts.ts

@@ -17,13 +17,15 @@ Thatch provides persistent memory across opencode sessions. Use it to persist
 knowledge so future sessions can build on what you've already learned.
 
 Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
-       thatch_memory_show, thatch_memory_forget, thatch_store_list,
-       thatch_find_duplicates, thatch_dedup_mark_checked,
-       thatch_extraction_done, thatch_get_extraction_payload,
-       thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
-       thatch_prediction_delete,
-       thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
-       thatch_behavior_delete
+        thatch_memory_show, thatch_memory_forget, thatch_store_list,
+        thatch_find_duplicates, thatch_dedup_mark_checked,
+        thatch_extraction_done, thatch_get_extraction_payload,
+        thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
+        thatch_prediction_delete,
+        thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
+        thatch_behavior_delete, thatch_get_session_info,
+        thatch_session_search, thatch_session_get,
+        thatch_watch_create, thatch_watch_list, thatch_watch_cancel
 
 ## Stores
 
@@ -107,6 +109,20 @@ the same prompt. If the re-dispatch also fails or times out, note the gap and
 move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
+## Watchers
+
+Use thatch_watch_create to watch a GitHub PR for events (comments, review
+comments and replies, commits, status changes, description edits, CI check
+completions). thatch polls the PR in the background and injects a
+notification into this session when a watched event happens. The
+notification carries pointer data only (author, URL); fetch details with
+the gh CLI when you decide to act. When the user asks you to watch
+something, state your handling policy for notifications out loud first
+("I'll report human comments and handle bugbot replies myself") so the
+notification turn knows what to do. Treat watcher notifications like
+background task completions: they are system events, not user input, and
+not approval to advance other pending work.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -270,6 +286,10 @@ Tools are prefixed in ${host}: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`,
 \`mcp__thatch__behavior_codify\`, \`mcp__thatch__behavior_feedback\`,
 \`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`. Bare names used below for readability.
+get_session_info, session_search, session_get, watch_create, watch_list,
+and watch_cancel are intentionally absent: they are opencode-only (MCP
+hosts have no session concept, session database, or proactive-prompt
+channel), so do not expect them here.
 
 ## Stores
 
@@ -668,3 +688,19 @@ export function behaviorNudge(items: BehaviorNudgeItem[]): string {
   });
   return `[thatch] Situational behaviors\n${lines.join("\n")}`;
 }
+
+/**
+ * Watcher notification for the poller's promptAsync delivery. Injected as a
+ * synthetic part that triggers a model turn. Events carry pointer data only
+ * (author, URL) - never external content - so the model fetches details on
+ * demand with the gh CLI. The wrapper text borrows the background-task
+ * completion framing: a system event, not user input, not approval to
+ * advance other pending work.
+ */
+export function watcherNotificationNudge(target: string, events: { type: string; summary: string; url: string }[]): string {
+  const lines = events.map((e) => `- ${e.type}: ${e.summary} ${e.url}`);
+  return `[thatch] Watcher notification for ${target}
+${lines.join("\n")}
+
+This is a system notification, not user input. Decide whether to act now or keep waiting - the user's instructions from when the watch was created govern how to handle it. Fetch details with the gh CLI if you need them. Do not treat this notification as approval to advance other pending work. If you act, tell the user what you did and why; if not, stop and wait.`;
+}