@jeffober/thatch 0.1.36 → 0.1.38

package/README.md

@@ -89,7 +89,7 @@ Thatch gives your agent three layers of persistent context:
   `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
+  only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
   background and prompts the session when comments, commits, CI results, or
   status changes arrive. Notifications carry pointer data only.
 

package/docs/dev/README.md

@@ -73,7 +73,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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. |
+| `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches GitHub PRs and branches 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]`. |

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

@@ -17,9 +17,9 @@ Thatch supports three host agents from a single codebase:
   `mcp__thatch__` tool prefix, system prompt in AGENTS.md
 
 All three paths share the tool definitions from `src/tool-defs.ts`: 18
-host-agnostic tools plus opencode-only tools (currently six:
+host-agnostic tools plus opencode-only tools (currently seven:
 `get_session_info`, `session_search`/`session_get`, and the
-`watch_create`/`watch_list`/`watch_cancel` watcher tools), which the MCP server
+`watch_create`/`watch_branch_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.

package/docs/dev/features/qa-system.md

@@ -1,6 +1,6 @@
 # QA System
 
-Thatch ships 93 QA use cases that verify end-to-end behavior. Each use case is
+Thatch ships 95 QA use cases that verify end-to-end behavior. Each use case is
 a `bun:test` file that runs in an isolated environment — a temp-directory copy
 of the repo, not the working tree itself. Use cases are split into
 **automatable** (no LLM, fast) and **live** (spawns opencode, costs model
@@ -8,7 +8,7 @@ tokens).
 
 ## What it does
 
-- 93 use cases: 73 automatable + 20 live
+- 95 use cases: 75 automatable + 20 live
 - Automatable use cases run without an LLM — they test CLI behavior, hooks, DB
   operations, and tool execution directly via bun assertions
 - Live use cases spawn real opencode sessions — they test the full
@@ -182,7 +182,7 @@ includes all of `tests/`), just not executed during `check`. See
 | `tests/qa/runner.ts` | `registerUseCase`, `UseCase` type, `ensureMaster`, `createFixture`, `runViaOpencode`, execution logic |
 | `tests/qa/auto/index.test.ts` | Automatable use case barrel — imports all auto use case modules |
 | `tests/qa/live/index.test.ts` | Live use case barrel — imports all live use case modules |
-| `tests/qa/auto/uc-NNN-*.ts` | 73 automatable use case files |
+| `tests/qa/auto/uc-NNN-*.ts` | 75 automatable use case files |
 | `tests/qa/live/uc-NNN-*.ts` | 20 live use case files |
 
 No separate QA docs directory exists. QA use cases live in `tests/qa/` as executable tests, not docs.

package/docs/dev/features/watchers.md

@@ -3,15 +3,18 @@
 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.
+session when a watched event happens. Two sources ship: GitHub pull
+requests (source `pr`) and GitHub branches (source `branch`, for
+watching CI and workflow runs on main). The registry, poller, and
+delivery are source-agnostic - a new source adds a fetch-and-diff
+function pair 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)
+- `thatch_watch_create` (PRs) / `thatch_watch_branch_create` (branches) /
+  `thatch_watch_list` / `thatch_watch_cancel` tools (all 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
@@ -51,12 +54,13 @@ process exit is the real lifetime boundary in both TUI and serve mode
 ### 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.
+`fetchPrState()` - five gh calls (the pull, issue comments, review
+comments, check runs on the head SHA, and one GraphQL query for
+review-thread resolution state), four 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
 
@@ -76,6 +80,11 @@ Event detection:
 - description by SHA-256 of the body text (the body itself is never
   stored)
 - CI by check-run transitions into a completed status
+- review-thread resolution by symmetric difference of the sorted
+  resolved-thread-id lists (thread `isResolved` state exists only in
+  the GraphQL API, so the fetch is a `gh api graphql -f query=...`
+  call; the `GhRunner` interface carries an args array to fit both
+  transports)
 
 A diff emits at most 10 events per watcher per cycle, so comment
 floods collapse into one batch.
@@ -102,9 +111,10 @@ cycle or when the session next goes idle (the event hook calls
 
 ### 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.
+`pr_comment`, `pr_review_comment`, `pr_review_reply`,
+`pr_review_resolved`, `pr_commit`, `pr_status`, `pr_description`,
+`pr_ci`. The tool's `events` argument selects a subset; the default is
+all eight.
 
 ## Interactions with other features
 
@@ -141,10 +151,11 @@ selects a subset; the default is all seven.
 
 ## 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.
+The registry is a discriminated union over sources: `PrWatcher` and
+`BranchWatcher` implement the same lifecycle (id, session, repo,
+events, expiry, snapshot), and `poll()` dispatches to the source's
+fetch/diff pair. Adding a third source means: new event types, a
+`fetchXState`/`diffXState` pair, a new arm of the `Watcher` union, a
+`#pollOne` branch, 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 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 |
+| **Tools** (18 shared + 7 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

@@ -99,7 +99,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 25 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 26 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 

package/docs/user/README.md

@@ -11,7 +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)
+- [watchers.md](watchers.md): event-driven notifications (PR and branch 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

package/docs/user/watchers.md

@@ -1,29 +1,39 @@
 # 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?"
+Watchers monitor external sources - today, GitHub pull requests and
+branches - and inject a notification into the conversation when
+something happens. You ask the agent to watch a PR or a branch; 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.
+The agent calls `thatch_watch_create` to register a watcher on a PR,
+or `thatch_watch_branch_create` to register a watcher on a branch
+(typically main). thatch captures the target's current state as a
+baseline, then polls the GitHub API through the `gh` CLI once a
+minute. When the target changes in a way the watcher cares about, the
+plugin prompts the agent with a notification.
 
-Watched events:
+PR 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_review_resolved` - a review thread resolved or reopened
 - `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
 
+Branch watched events:
+
+- `branch_commit` - new commits land on the branch (e.g. a PR merged)
+- `branch_ci` - a check run on the branch head completed
+- `branch_workflow` - a GitHub Actions workflow run starts or finishes
+  on the branch, optionally filtered by workflow name (substring,
+  case-insensitive)
+
 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.
@@ -51,6 +61,8 @@ do about it.
 
 Other tools:
 
+- `thatch_watch_branch_create` - watch a branch (typically main) for
+  commits, CI check runs, and workflow runs
 - `thatch_watch_list` - shows the session's active watchers
 - `thatch_watch_cancel` - cancels one by id
 

package/package.json

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

@@ -101,15 +101,33 @@ export const server: Plugin = async ({ client, worktree }) => {
   // 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";
+      // Events carry their watch's target label from the registry, so the
+      // notification header is correct for every source (PRs, branches,
+      // CI events whose URLs would not parse).
       await client.session.promptAsync({
         path: { id: sessionID },
         body: {
-          parts: [{ type: "text", text: watcherNotificationNudge(target, events), synthetic: true }],
+          parts: [{ type: "text", text: watcherNotificationNudge(events[0]?.target ?? "watched target", events), synthetic: true }],
         },
       });
+      // Toast: the notification part is TUI-hidden, so without this the
+      // user watching the session sees the model wake up with no visible
+      // cause. Announce what fired. Failed checks/workflows surface as a
+      // warning variant; routine events as info. Best-effort - the TUI may
+      // not be connected (headless mode).
+      const failed = events.some((e) => e.summary.includes("failure"));
+      const more = events.length > 1 ? ` +${events.length - 1} more` : "";
+      try {
+        await client.tui.showToast({
+          body: {
+            message: `\u23F0 ${events[0]?.target ?? "watched target"}: ${events[0]?.summary ?? ""}${more}`,
+            variant: failed ? "warning" : "info",
+            duration: 5000,
+          },
+        });
+      } catch {
+        // TUI may not be connected. Best-effort.
+      }
     },
     canDeliver: (sessionID) =>
       !compacting.has(sessionID) && sessionStatus.get(sessionID) === "idle",

package/src/prompts.ts

@@ -25,7 +25,8 @@ Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
         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
+        thatch_watch_create, thatch_watch_branch_create,
+        thatch_watch_list, thatch_watch_cancel
 
 ## Stores
 
@@ -67,7 +68,6 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 - \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
-
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
@@ -112,12 +112,15 @@ 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
+comments and replies, review thread resolutions, commits, status changes,
+description edits, CI check completions), or thatch_watch_branch_create to
+watch a branch (typically main) for commit landings, check-run completions,
+and workflow runs on the branch. thatch polls 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
@@ -286,7 +289,8 @@ 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,
+get_session_info, session_search, session_get, watch_create,
+watch_branch_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.
@@ -331,7 +335,6 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 - \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
-
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.

package/src/tool-defs.ts

@@ -3,7 +3,7 @@ import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
 import { predictionVerb } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
-import { WATCHER_EVENT_TYPES, type WatcherRegistry, type WatcherEventType } from "./watchers";
+import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
 
 // Near-duplicate thresholds for matcher/prediction/behavior dedup at
 // creation time. Matches the thatch_find_duplicates threshold (0.85).
@@ -960,12 +960,13 @@ const watchCreateDef: ToolDef = {
   description:
     "Watch a GitHub PR for events and get notified in this session when they " +
     "happen. Events: new top-level comments, new inline review comments, " +
-    "replies to review comments, new commits (head SHA change), PR status " +
-    "changes, title/description edits, and completed CI check runs. The " +
-    "watcher polls in the background and injects a notification prompt; " +
-    "notifications carry pointers only (author, URL) - fetch details yourself " +
-    "with the gh CLI when you decide to act. Watches live until cancelled, " +
-    "the session ends, or opencode restarts. Requires the gh CLI.",
+    "replies to review comments, review thread resolutions, new commits " +
+    "(head SHA change), PR status changes, title/description edits, and " +
+    "completed CI check runs. The watcher polls in the background and " +
+    "injects a notification prompt; notifications carry pointers only " +
+    "(author, URL) - fetch details yourself with the gh CLI when you decide " +
+    "to act. Watches live until cancelled, the session ends, or opencode " +
+    "restarts. Requires the gh CLI.",
   args: {
     pr: z.number().int().positive().describe(
       "The PR number to watch.",
@@ -973,8 +974,8 @@ const watchCreateDef: ToolDef = {
     repo: z.string().optional().describe(
       "GitHub repo as owner/repo. Defaults to this project's repo from the git remote.",
     ),
-    events: z.array(z.enum(WATCHER_EVENT_TYPES as [WatcherEventType, ...WatcherEventType[]])).optional().describe(
-      "Which event types to watch. Omit for all event types.",
+    events: z.array(z.enum(PR_EVENT_TYPES as [PrWatcherEventType, ...PrWatcherEventType[]])).optional().describe(
+      "Which event types to watch. Omit for all PR event types.",
     ),
   },
   opencodeOnly: true,
@@ -986,8 +987,8 @@ const watchCreateDef: ToolDef = {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
     const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
-    const events = (args.events as WatcherEventType[] | undefined) ?? [...WATCHER_EVENT_TYPES];
-    const result = await ctx.watchers.create(host.sessionID, repo, args.pr as number, events);
+    const events = (args.events as PrWatcherEventType[] | undefined) ?? [...PR_EVENT_TYPES];
+    const result = await ctx.watchers.createPr(host.sessionID, repo, args.pr as number, events);
     if (!result.ok) return `Watcher not created: ${result.error}`;
     const w = result.watcher;
     return (
@@ -1025,11 +1026,79 @@ const watchListDef: ToolDef = {
     if (watchers.length === 0) return "No active watchers.";
     const minutesLeft = (w: { expiresAt: number }) => Math.max(0, Math.round((w.expiresAt - Date.now()) / 60_000));
     return watchers
-      .map((w) => `${w.id}: ${w.repo}#${w.pr} events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`)
+      .map((w) => {
+        const target = w.source === "pr" ? `${w.repo}#${w.pr}` : `${w.repo}@${w.branch}`;
+        return `${w.id}: ${target} [${w.source}] events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`;
+      })
       .join("\n");
   },
 };
 
+/**
+ * Registers a background watcher on a GitHub branch (typically main): commit
+ * landings, check-run completions on the head, and workflow runs. This is
+ * how the model watches "CI against main" or waits for a post-merge build.
+ * opencode-only, like the PR watch tools.
+ */
+const watchBranchCreateDef: ToolDef = {
+  name: "watch_branch_create",
+  description:
+    "Watch a GitHub branch (typically main) and get notified in this session " +
+    "when things happen on it: branch_commit when new commits land (e.g. a " +
+    "PR merged), branch_ci when a check run on the head completes, and " +
+    "branch_workflow when a GitHub Actions workflow run starts or finishes " +
+    "on the branch. Optionally filter to workflow names (substring match). " +
+    "The watcher polls in the background and injects a notification prompt; " +
+    "notifications carry pointers only - fetch details with the gh CLI when " +
+    "you decide to act. Watches live until cancelled, the session ends, or " +
+    "opencode restarts. Requires the gh CLI.",
+  args: {
+    branch: z.string().describe(
+      "The branch name to watch, e.g. main.",
+    ),
+    repo: z.string().optional().describe(
+      "GitHub repo as owner/repo. Defaults to this project's repo from the git remote.",
+    ),
+    events: z.array(z.enum(BRANCH_EVENT_TYPES as [BranchWatcherEventType, ...BranchWatcherEventType[]])).optional().describe(
+      "Which event types to watch. Omit for all branch event types.",
+    ),
+    workflows: z.array(z.string()).optional().describe(
+      "Only notify for workflow runs whose name contains one of these substrings (case-insensitive). Omit for all workflows.",
+    ),
+  },
+  opencodeOnly: true,
+  async execute(args, ctx, host) {
+    if (!host) {
+      return "Watching is unavailable: this host did not provide a session context.";
+    }
+    if (!ctx.watchers) {
+      return "Watching is unavailable: no watcher registry was wired by this host.";
+    }
+    const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
+    const events = (args.events as BranchWatcherEventType[] | undefined) ?? [...BRANCH_EVENT_TYPES];
+    const result = await ctx.watchers.createBranch(
+      host.sessionID,
+      repo,
+      args.branch as string,
+      events,
+      (args.workflows as string[] | undefined) ?? [],
+    );
+    if (!result.ok) return `Watcher not created: ${result.error}`;
+    const w = result.watcher;
+    return (
+      `[watching] ${w.repo}@${w.branch}\n` +
+      `id: ${w.id}\n` +
+      `events: ${w.events.join(", ")}\n` +
+      (w.workflows.length > 0 ? `workflow filter: ${w.workflows.join(", ")}\n` : "") +
+      `head: ${w.state.headSha.slice(0, 7)}\n\n` +
+      `The baseline is captured now - only changes from this point notify. ` +
+      `You will receive a system notification in this session when a watched event happens. ` +
+      `State any handling policy for those notifications now (e.g. what to act on, what just to report), ` +
+      `since the notification itself carries only pointers.`
+    );
+  },
+};
+
 /**
  * Cancels one watcher. opencode-only, session-scoped: cancelling by id only
  * works for the session that created it.
@@ -1038,7 +1107,7 @@ const watchCancelDef: ToolDef = {
   name: "watch_cancel",
   description: "Cancel one of this session's watchers by id. opencode-only.",
   args: {
-    id: z.string().describe("The watcher id from watch_create or watch_list."),
+    id: z.string().describe("The watcher id from watch_create, watch_branch_create, or watch_list."),
   },
   opencodeOnly: true,
   async execute(args, ctx, host) {
@@ -1083,6 +1152,7 @@ export const TOOL_DEFS: ToolDef[] = [
   sessionSearchDef,
   sessionGetDef,
   watchCreateDef,
+  watchBranchCreateDef,
   watchListDef,
   watchCancelDef,
 ];

package/src/watchers.ts

@@ -2,11 +2,13 @@
  * Watchers: event-driven notifications from external sources, delivered into
  * a live opencode session as injected prompts.
  *
- * The motivating case: the model registers a watcher on a GitHub PR, and
- * thatch polls the PR in the background. When something the watcher cares
- * about happens (new comments, commits, CI results), the plugin prompts the
- * session with a synthetic notification part - the same delivery mechanism
- * opencode itself uses for background task completions.
+ * The registry supports multiple source types behind one mechanism. The
+ * first source was GitHub pull requests (source "pr"); GitHub branches
+ * (source "branch") arrived second, for watching CI and workflow runs
+ * against main. A source contributes: event types, a fetch function that
+ * produces a snapshot of the watched state, and a pure diff between two
+ * snapshots. Everything else - registry, pending queue, delivery gating -
+ * is source-agnostic.
  *
  * Lifetime is deliberately process-scoped. The registry lives in plugin
  * memory, never in SQLite: opencode loads thatch in-process, so the plugin
@@ -21,38 +23,50 @@
  */
 
 // ---------------------------------------------------------------------------
-// Types
+// Event types
 // ---------------------------------------------------------------------------
 
-/**
- * The event vocabulary for the github-pr source. Each type maps to one diff
- * against the watcher's last-seen PR state. Notifications carry pointer data
- * (author, URL, counts) rather than content, so text authored by strangers
- * on GitHub never enters the model's context directly - the model fetches
- * details on demand with the gh CLI.
- */
-export type WatcherEventType =
+/** Event types for source "pr". */
+export type PrWatcherEventType =
   | "pr_comment"
   | "pr_review_comment"
   | "pr_review_reply"
+  | "pr_review_resolved"
   | "pr_commit"
   | "pr_status"
   | "pr_description"
   | "pr_ci";
 
-export const WATCHER_EVENT_TYPES: WatcherEventType[] = [
+/** Event types for source "branch" (typically main): commits land, CI and workflow runs execute. */
+export type BranchWatcherEventType = "branch_commit" | "branch_ci" | "branch_workflow";
+
+export type WatcherEventType = PrWatcherEventType | BranchWatcherEventType;
+
+export const PR_EVENT_TYPES: PrWatcherEventType[] = [
   "pr_comment",
   "pr_review_comment",
   "pr_review_reply",
+  "pr_review_resolved",
   "pr_commit",
   "pr_status",
   "pr_description",
   "pr_ci",
 ];
 
+export const BRANCH_EVENT_TYPES: BranchWatcherEventType[] = [
+  "branch_commit",
+  "branch_ci",
+  "branch_workflow",
+];
+
+/** Every event type across all sources - for diagnostics and tests. */
+export const WATCHER_EVENT_TYPES: WatcherEventType[] = [...PR_EVENT_TYPES, ...BRANCH_EVENT_TYPES];
+
 /** A single detected change, ready for delivery. Pointer data only. */
 export interface WatcherEvent {
   type: WatcherEventType;
+  /** Which watch produced this event, e.g. "acme/widgets#7" or "acme/widgets@main". */
+  target: string;
   /** Human-readable, content-free summary: who/what/where, never body text. */
   summary: string;
   url: string;
@@ -67,6 +81,31 @@ export interface CommentRef {
   isReply: boolean;
 }
 
+/** One CI check run, keyed by id in state snapshots. */
+export interface CheckRunRef {
+  name: string;
+  status: string;
+  conclusion: string | null;
+  url: string | null;
+}
+
+/** One GitHub Actions workflow run, keyed by run id. */
+export interface WorkflowRunRef {
+  name: string;
+  status: string;
+  conclusion: string | null;
+  url: string;
+  /** What triggered the run: push, pull_request, schedule, workflow_run, ... */
+  event: string;
+  /** The branch the run's head commit is on (a tag-triggered run puts the TAG name here). */
+  headBranch: string;
+  headSha: string;
+}
+
+// ---------------------------------------------------------------------------
+// Watchers: a discriminated union over sources
+// ---------------------------------------------------------------------------
+
 /**
  * The last-seen state of a PR, captured at watch creation and updated each
  * poll. Comment arrays are kept whole so each diff can name individual new
@@ -83,25 +122,56 @@ export interface PrState {
   lastReviewCommentId: number;
   issueComments: CommentRef[];
   reviewComments: CommentRef[];
-  /** Check runs on the head SHA, keyed by check run id. */
-  checkRuns: Record<string, { name: string; status: string; conclusion: string | null; url: string | null }>;
+  /** Sorted ids of review threads currently in the resolved state. */
+  resolvedThreads: string[];
+  checkRuns: Record<string, CheckRunRef>;
 }
 
-export interface Watcher {
+/** The last-seen state of a branch. */
+export interface BranchState {
+  headSha: string;
+  checkRuns: Record<string, CheckRunRef>;
+  /** Workflow runs on the branch, keyed by run id (last 20). */
+  workflowRuns: Record<string, WorkflowRunRef>;
+}
+
+export interface PrWatcher {
   id: string;
+  source: "pr";
   sessionID: string;
   /** owner/repo */
   repo: string;
   pr: number;
-  events: WatcherEventType[];
+  events: PrWatcherEventType[];
   /** Epoch ms. When now > expiresAt the watcher is silently dropped. */
   expiresAt: number;
   createdAt: number;
   state: PrState;
 }
 
-/** Runs one GitHub REST API path via the gh CLI and parses the JSON response. */
-export type GhRunner = (apiPath: string) => Promise<unknown>;
+export interface BranchWatcher {
+  id: string;
+  source: "branch";
+  sessionID: string;
+  /** owner/repo */
+  repo: string;
+  branch: string;
+  events: BranchWatcherEventType[];
+  /** Substring filters on workflow run names; empty means all workflows. */
+  workflows: string[];
+  expiresAt: number;
+  createdAt: number;
+  state: BranchState;
+}
+
+export type Watcher = PrWatcher | BranchWatcher;
+
+/** Runs one GitHub API call via the gh CLI and parses the JSON response.
+ *  The array is the argument list after `gh api`: a REST path like
+ *  ["/repos/o/r/pulls/7"] or a GraphQL invocation like
+ *  ["graphql", "-f", "query={...}"]. Array-shaped so both transports fit
+ *  without the callers string-concatenating shell quotes. */
+export type GhRunner = (apiArgs: string[]) => Promise<unknown>;
 
 export interface WatcherRegistryOptions {
   /** Delivers a batch of events for a session. Injected so tests never spawn. */
@@ -128,8 +198,8 @@ export interface WatcherRegistryOptions {
  * existing gh session - thatch never sees or stores a token. Throws on
  * non-zero exit or unparseable output.
  */
-export async function ghApiRun(apiPath: string): Promise<unknown> {
-  const proc = Bun.spawn(["gh", "api", apiPath], {
+export async function ghApiRun(apiArgs: string[]): Promise<unknown> {
+  const proc = Bun.spawn(["gh", "api", ...apiArgs], {
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -141,7 +211,7 @@ export async function ghApiRun(apiPath: string): Promise<unknown> {
     ]);
     if (exitCode !== 0) {
       const stderr = await new Response(proc.stderr).text();
-      throw new Error(`gh api ${apiPath} failed (exit ${exitCode}): ${stderr.trim().slice(0, 200)}`);
+      throw new Error(`gh api ${apiArgs.join(" ")} failed (exit ${exitCode}): ${stderr.trim().slice(0, 200)}`);
     }
     return JSON.parse(stdout);
   } finally {
@@ -176,7 +246,7 @@ export function _resetGhAvailability(): void {
 }
 
 // ---------------------------------------------------------------------------
-// PR state construction and diffing
+// Snapshot construction
 // ---------------------------------------------------------------------------
 
 function sha256(text: string): string {
@@ -206,32 +276,9 @@ function maxCommentId(refs: CommentRef[]): number {
   return refs.reduce((max, c) => Math.max(max, c.id), 0);
 }
 
-/**
- * Fetches the current state of a PR plus everything the diff functions need.
- * Four gh calls per poll per watcher: the PR itself, issue comments
- * (top-level PR conversation), review comments (inline diff comments), and
- * check runs on the head SHA. Comment and check-run fetches run in parallel.
- */
-export async function fetchPrState(gh: GhRunner, repo: string, pr: number): Promise<PrState> {
-  const pull = (await gh(`/repos/${repo}/pulls/${pr}`)) as {
-    head?: { sha?: string };
-    state?: string;
-    merged?: boolean;
-    title?: string;
-    body?: string | null;
-  };
-  const headSha = pull.head?.sha ?? "";
-  const [issueComments, reviewComments, checkRuns] = await Promise.all([
-    gh(`/repos/${repo}/issues/${pr}/comments?per_page=100&sort=created&direction=desc`),
-    gh(`/repos/${repo}/pulls/${pr}/comments?per_page=100&sort=created&direction=desc`),
-    gh(`/repos/${repo}/commits/${headSha}/check-runs?per_page=100`),
-  ]);
-
-  const issueRefs = toCommentRefs(issueComments);
-  const reviewRefs = toCommentRefs(reviewComments);
-
-  const runs: PrState["checkRuns"] = {};
-  const rawRuns = (checkRuns as { check_runs?: Array<{
+function parseCheckRuns(raw: unknown): Record<string, CheckRunRef> {
+  const runs: Record<string, CheckRunRef> = {};
+  const rawRuns = (raw as { check_runs?: Array<{
     id?: number;
     name?: string;
     status?: string;
@@ -247,6 +294,76 @@ export async function fetchPrState(gh: GhRunner, repo: string, pr: number): Prom
       url: run.html_url ?? null,
     };
   }
+  return runs;
+}
+
+function parseWorkflowRuns(raw: unknown): Record<string, WorkflowRunRef> {
+  const runs: Record<string, WorkflowRunRef> = {};
+  const rawRuns = (raw as { workflow_runs?: Array<{
+    id?: number;
+    name?: string;
+    status?: string;
+    conclusion?: string | null;
+    html_url?: string;
+    event?: string;
+    head_branch?: string;
+    head_sha?: string;
+  }> }).workflow_runs ?? [];
+  for (const run of rawRuns) {
+    if (run.id === undefined) continue;
+    runs[String(run.id)] = {
+      name: run.name ?? "workflow",
+      status: run.status ?? "unknown",
+      conclusion: run.conclusion ?? null,
+      url: run.html_url ?? "",
+      event: run.event ?? "unknown",
+      headBranch: run.head_branch ?? "",
+      headSha: run.head_sha ?? "",
+    };
+  }
+  return runs;
+}
+
+function parseResolvedThreads(raw: unknown): string[] {
+  const nodes = (raw as {
+    data?: { repository?: { pullRequest?: { reviewThreads?: { nodes?: Array<{ id?: string; isResolved?: boolean }> } } } };
+  }).data?.repository?.pullRequest?.reviewThreads?.nodes ?? [];
+  return nodes
+    .filter((n) => n.id && n.isResolved)
+    .map((n) => n.id!)
+    .sort();
+}
+
+/**
+ * Fetches the current state of a PR plus everything the diff functions need.
+ * Five gh calls per poll per watcher: the PR itself, issue comments
+ * (top-level PR conversation), review comments (inline diff comments), check
+ * runs on the head SHA, and one GraphQL query for review-thread resolution
+ * state (isResolved exists only in GraphQL, not the REST API). All
+ * non-pull fetches run in parallel.
+ */
+export async function fetchPrState(gh: GhRunner, repo: string, pr: number): Promise<PrState> {
+  const pull = (await gh([`/repos/${repo}/pulls/${pr}`])) as {
+    head?: { sha?: string };
+    state?: string;
+    merged?: boolean;
+    title?: string;
+    body?: string | null;
+  };
+  const headSha = pull.head?.sha ?? "";
+  const [owner, repoName] = repo.split("/");
+  const graphqlQuery =
+    `query { repository(owner: "${owner}", name: "${repoName}") { ` +
+    `pullRequest(number: ${pr}) { reviewThreads(first: 100) { nodes { id isResolved } } } } }`;
+  const [issueComments, reviewComments, checkRuns, threads] = await Promise.all([
+    gh([`/repos/${repo}/issues/${pr}/comments?per_page=100&sort=created&direction=desc`]),
+    gh([`/repos/${repo}/pulls/${pr}/comments?per_page=100&sort=created&direction=desc`]),
+    gh([`/repos/${repo}/commits/${headSha}/check-runs?per_page=100`]),
+    gh(["graphql", "-f", `query=${graphqlQuery}`]),
+  ]);
+
+  const issueRefs = toCommentRefs(issueComments);
+  const reviewRefs = toCommentRefs(reviewComments);
 
   return {
     headSha,
@@ -258,59 +375,168 @@ export async function fetchPrState(gh: GhRunner, repo: string, pr: number): Prom
     lastReviewCommentId: maxCommentId(reviewRefs),
     issueComments: issueRefs,
     reviewComments: reviewRefs,
-    checkRuns: runs,
+    resolvedThreads: parseResolvedThreads(threads),
+    checkRuns: parseCheckRuns(checkRuns),
   };
 }
 
+/**
+ * Fetches the current state of a branch: the head commit, check runs on that
+ * head, and recent workflow runs relevant to the branch. The branch and
+ * workflow-run calls run in parallel; check runs need the head SHA first.
+ *
+ * Workflow runs are fetched WITHOUT the API's branch filter and filtered
+ * client-side: keep runs whose head_branch matches the branch (push runs)
+ * or whose head_sha is the branch's current head (tag-triggered runs like a
+ * release Publish run - their head_branch is the tag name, so the API's
+ * branch filter would hide exactly the runs a release watch exists for).
+ */
+export async function fetchBranchState(gh: GhRunner, repo: string, branch: string): Promise<BranchState> {
+  const [branchInfo, runs] = await Promise.all([
+    gh([`/repos/${repo}/branches/${branch}`]),
+    gh([`/repos/${repo}/actions/runs?per_page=30`]),
+  ]);
+  const headSha = (branchInfo as { commit?: { sha?: string } }).commit?.sha ?? "";
+  const allRuns = parseWorkflowRuns(runs);
+  const relevant = Object.fromEntries(
+    Object.entries(allRuns).filter(([, run]) => run.headBranch === branch || run.headSha === headSha),
+  );
+  const checkRuns = await gh([`/repos/${repo}/commits/${headSha}/check-runs?per_page=100`]);
+  return {
+    headSha,
+    checkRuns: parseCheckRuns(checkRuns),
+    workflowRuns: relevant,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Diffing
+// ---------------------------------------------------------------------------
+
 /** At most this many events per watcher per cycle; comment floods collapse. */
 const MAX_EVENTS_PER_DIFF = 10;
 
+/**
+ * Shared check-run diff: emits one event per run that reaches a completed
+ * status. A run that was already completed before produces nothing; a run
+ * that appears between polls already completed produces one.
+ */
+function diffCheckRuns(
+  before: Record<string, CheckRunRef>,
+  after: Record<string, CheckRunRef>,
+  eventType: "pr_ci" | "branch_ci",
+  fallbackUrl: string,
+  out: WatcherEvent[],
+): void {
+  for (const [runId, run] of Object.entries(after)) {
+    const previous = before[runId];
+    if (run.status !== "completed") continue;
+    if (previous && previous.status === "completed") continue;
+    const conclusion = run.conclusion ? ` (${run.conclusion})` : "";
+    out.push({
+      type: eventType,
+      target: "",
+      summary: `check "${run.name}" completed${conclusion}`,
+      url: run.url ?? fallbackUrl,
+    });
+  }
+}
+
 /**
  * Pure diff between the last-seen and current PR state. Detects comments by
  * id monotonicity, commits by head SHA, description by body hash, CI by
- * check-run transitions to a completed status.
+ * check-run transitions, thread resolution by symmetric difference of the
+ * sorted resolved-id lists.
  */
-export function diffPrState(before: PrState, after: PrState, url: string): WatcherEvent[] {
+export function diffPrState(before: PrState, after: PrState, target: string, baseUrl: string): WatcherEvent[] {
   const events: WatcherEvent[] = [];
 
   if (after.headSha !== before.headSha && after.headSha) {
-    events.push({
-      type: "pr_commit",
-      summary: `head moved to ${after.headSha.slice(0, 7)}`,
-      url,
-    });
+    events.push({ type: "pr_commit", target, summary: `head moved to ${after.headSha.slice(0, 7)}`, url: baseUrl });
   }
 
   if (after.state !== before.state || after.merged !== before.merged) {
     const status = after.merged ? "merged" : after.state;
-    events.push({ type: "pr_status", summary: `PR is now ${status}`, url });
+    events.push({ type: "pr_status", target, summary: `PR is now ${status}`, url: baseUrl });
   }
 
   if (after.bodySha !== before.bodySha || after.title !== before.title) {
-    events.push({ type: "pr_description", summary: "PR title or description changed", url });
+    events.push({ type: "pr_description", target, summary: "PR title or description changed", url: baseUrl });
   }
 
   const fresh = (refs: CommentRef[], lastSeenId: number) =>
     refs.filter((c) => c.id > lastSeenId);
 
   for (const c of fresh(after.issueComments, before.lastIssueCommentId)) {
-    events.push({ type: "pr_comment", summary: `comment by ${c.author}`, url: c.url || url });
+    events.push({ type: "pr_comment", target, summary: `comment by ${c.author}`, url: c.url || baseUrl });
   }
   for (const c of fresh(after.reviewComments, before.lastReviewCommentId)) {
     events.push({
       type: c.isReply ? "pr_review_reply" : "pr_review_comment",
+      target,
       summary: `comment by ${c.author}`,
-      url: c.url || url,
+      url: c.url || baseUrl,
     });
   }
 
-  for (const [runId, run] of Object.entries(after.checkRuns)) {
-    const previous = before.checkRuns[runId];
-    const completed = run.status === "completed";
-    if (!completed) continue;
-    if (previous && previous.status === "completed") continue;
-    const conclusion = run.conclusion ? ` (${run.conclusion})` : "";
-    events.push({ type: "pr_ci", summary: `check "${run.name}" completed${conclusion}`, url: run.url ?? url });
+  const afterResolved = new Set(after.resolvedThreads);
+  const beforeResolved = new Set(before.resolvedThreads);
+  for (const id of after.resolvedThreads) {
+    if (!beforeResolved.has(id)) {
+      events.push({ type: "pr_review_resolved", target, summary: "review thread resolved", url: baseUrl });
+    }
+  }
+  for (const id of before.resolvedThreads) {
+    if (!afterResolved.has(id)) {
+      events.push({ type: "pr_review_resolved", target, summary: "review thread reopened", url: baseUrl });
+    }
+  }
+
+  diffCheckRuns(before.checkRuns, after.checkRuns, "pr_ci", baseUrl, events);
+
+  return events.slice(0, MAX_EVENTS_PER_DIFF);
+}
+
+/**
+ * Pure diff between the last-seen and current branch state: head movement,
+ * check-run completions on the head, and workflow runs appearing or
+ * transitioning on the branch.
+ */
+export function diffBranchState(
+  before: BranchState,
+  after: BranchState,
+  target: string,
+  repo: string,
+): WatcherEvent[] {
+  const events: WatcherEvent[] = [];
+
+  if (after.headSha !== before.headSha && after.headSha) {
+    events.push({
+      type: "branch_commit",
+      target,
+      summary: `head moved to ${after.headSha.slice(0, 7)}`,
+      url: `https://github.com/${repo}/commit/${after.headSha}`,
+    });
+  }
+
+  diffCheckRuns(before.checkRuns, after.checkRuns, "branch_ci", `https://github.com/${repo}/actions`, events);
+
+  for (const [runId, run] of Object.entries(after.workflowRuns)) {
+    const previous = before.workflowRuns[runId];
+    const transition = !previous
+      ? `started (${run.status})`
+      : previous.status !== run.status
+        ? run.status === "completed"
+          ? `completed (${run.conclusion ?? "no conclusion"})`
+          : `${previous.status} -> ${run.status}`
+        : null;
+    if (!transition) continue;
+    events.push({
+      type: "branch_workflow",
+      target,
+      summary: `workflow "${run.name}" ${transition} [${run.event}]`,
+      url: run.url,
+    });
   }
 
   return events.slice(0, MAX_EVENTS_PER_DIFF);
@@ -371,24 +597,20 @@ export class WatcherRegistry {
   // -- CRUD ----------------------------------------------------------------
 
   /**
-   * Registers a watcher and captures the baseline state immediately. The
+   * Registers a PR watcher and captures the baseline state immediately. The
    * baseline fetch doubles as validation: a bad repo, missing PR, or broken
    * gh setup fails here with a real error instead of a watcher that never
    * fires.
    */
-  async create(
+  async createPr(
     sessionID: string,
     repo: string,
     pr: number,
-    events: WatcherEventType[],
-  ): Promise<{ ok: true; watcher: Watcher } | { ok: false; error: string }> {
-    const existing = this.listForSession(sessionID);
-    if (existing.length >= this.#opts.maxPerSession) {
-      return {
-        ok: false,
-        error: `Watcher limit reached: ${this.#opts.maxPerSession} active watchers per session. Cancel one with watch_cancel first.`,
-      };
-    }
+    events: PrWatcherEventType[],
+  ): Promise<{ ok: true; watcher: PrWatcher } | { ok: false; error: string }> {
+    const limit = this.#checkLimit(sessionID);
+    if (limit) return { ok: false, error: limit };
+    if (events.length === 0) return { ok: false, error: "No events to watch - pass at least one event type." };
 
     let state: PrState;
     try {
@@ -400,8 +622,9 @@ export class WatcherRegistry {
       return { ok: false, error: `Could not resolve a head SHA for ${repo}#${pr}. Is it an open PR?` };
     }
 
-    const watcher: Watcher = {
+    const watcher: PrWatcher = {
       id: `watch_${Math.random().toString(36).slice(2, 10)}`,
+      source: "pr",
       sessionID,
       repo,
       pr,
@@ -414,6 +637,56 @@ export class WatcherRegistry {
     return { ok: true, watcher };
   }
 
+  /**
+   * Registers a branch watcher (typically main): commit landings, check-run
+   * completions on the head, and workflow runs on the branch. Same baseline
+   * validation as createPr.
+   */
+  async createBranch(
+    sessionID: string,
+    repo: string,
+    branch: string,
+    events: BranchWatcherEventType[],
+    workflows: string[] = [],
+  ): Promise<{ ok: true; watcher: BranchWatcher } | { ok: false; error: string }> {
+    const limit = this.#checkLimit(sessionID);
+    if (limit) return { ok: false, error: limit };
+    if (events.length === 0) return { ok: false, error: "No events to watch - pass at least one event type." };
+
+    let state: BranchState;
+    try {
+      state = await fetchBranchState(this.#opts.ghRunner, repo, branch);
+    } catch (err) {
+      return { ok: false, error: `Failed to read ${repo}@${branch}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!state.headSha) {
+      return { ok: false, error: `Could not resolve a head SHA for ${repo}@${branch}. Does the branch exist and have commits?` };
+    }
+
+    const watcher: BranchWatcher = {
+      id: `watch_${Math.random().toString(36).slice(2, 10)}`,
+      source: "branch",
+      sessionID,
+      repo,
+      branch,
+      events,
+      workflows,
+      expiresAt: Date.now() + this.#opts.ttlMinutes * 60_000,
+      createdAt: Date.now(),
+      state,
+    };
+    this.#watchers.set(watcher.id, watcher);
+    return { ok: true, watcher };
+  }
+
+  #checkLimit(sessionID: string): string | null {
+    const existing = this.listForSession(sessionID);
+    if (existing.length >= this.#opts.maxPerSession) {
+      return `Watcher limit reached: ${this.#opts.maxPerSession} active watchers per session. Cancel one with watch_cancel first.`;
+    }
+    return null;
+  }
+
   /** Summaries of one session's watchers, newest first. */
   listForSession(sessionID: string): Watcher[] {
     return [...this.#watchers.values()]
@@ -442,9 +715,9 @@ export class WatcherRegistry {
   /**
    * One poll cycle: diff every watcher, queue events, then deliver whatever
    * is pending for sessions that can accept a prompt. Errors are per-watcher:
-   * one bad PR never blocks the others. Reentrant calls (a cycle slower than
-   * the interval) are dropped - overlapping diffs against the same baseline
-   * would queue duplicate events.
+   * one bad target never blocks the others. Reentrant calls (a cycle slower
+   * than the interval) are dropped - overlapping diffs against the same
+   * baseline would queue duplicate events.
    */
   async poll(): Promise<void> {
     if (this.#polling) return;
@@ -457,15 +730,12 @@ export class WatcherRegistry {
           continue;
         }
         try {
-          const after = await fetchPrState(this.#opts.ghRunner, watcher.repo, watcher.pr);
-          const events = diffPrState(watcher.state, after, this.pullUrl(watcher))
-            .filter((e) => watcher.events.includes(e.type));
+          const events = await this.#pollOne(watcher);
           if (events.length > 0) {
             const queue = this.#pending.get(watcher.sessionID) ?? [];
             queue.push(...events);
             this.#pending.set(watcher.sessionID, queue);
           }
-          watcher.state = after;
         } catch (err) {
           console.error(`[thatch] watcher ${id} poll failed: ${err}`);
         }
@@ -476,6 +746,29 @@ export class WatcherRegistry {
     }
   }
 
+  /** Fetches and diffs one watcher, filtered to its watched event types. */
+  async #pollOne(watcher: Watcher): Promise<WatcherEvent[]> {
+    if (watcher.source === "pr") {
+      const after = await fetchPrState(this.#opts.ghRunner, watcher.repo, watcher.pr);
+      const events = diffPrState(watcher.state, after, `${watcher.repo}#${watcher.pr}`, this.#prUrl(watcher))
+        .filter((e) => watcher.events.includes(e.type as PrWatcherEventType));
+      watcher.state = after;
+      return events;
+    }
+    const after = await fetchBranchState(this.#opts.ghRunner, watcher.repo, watcher.branch);
+    const all = diffBranchState(watcher.state, after, `${watcher.repo}@${watcher.branch}`, watcher.repo);
+    watcher.state = after;
+    // The workflow-name filter narrows branch_workflow events only -
+    // commits and check runs pass through unfiltered, or a watch filtered
+    // to "Publish" would silently drop its commit and CI notifications.
+    const matchesFilter = (e: WatcherEvent) =>
+      e.type !== "branch_workflow" ||
+      watcher.workflows.length === 0 ||
+      watcher.workflows.some((wf) => e.summary.toLowerCase().includes(wf.toLowerCase()));
+    return all
+      .filter((e) => watcher.events.includes(e.type as BranchWatcherEventType) && matchesFilter(e));
+  }
+
   /**
    * Delivers pending events for every session that can accept a prompt.
    * Failed deliveries stay pending and retry on the next cycle or the next
@@ -505,7 +798,7 @@ export class WatcherRegistry {
     return (this.#pending.get(sessionID) ?? []).length;
   }
 
-  private pullUrl(watcher: Watcher): string {
+  #prUrl(watcher: PrWatcher): string {
     return `https://github.com/${watcher.repo}/pull/${watcher.pr}`;
   }
 }