@jeffober/thatch 0.1.48 → 0.2.1

package/src/tool-defs.ts

@@ -2,24 +2,29 @@ import { z } from "zod";
 import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
 import {
+  ALERT_EVENT_KINDS,
   CONFIG_SECTIONS,
+  alertEventPrefsSchema,
+  alertsPrefsSchema,
   chatEnabled,
   chatPrefsSchema,
   loadConfig,
+  mergeAlertsPrefs,
   mergeChatPrefs,
   mergeNotificationPrefs,
   notificationDefaults,
   notificationPrefsSchema,
   saveConfig,
+  type AlertsPrefs,
   type ChatPrefs,
   type Config,
   type ConfigSection,
   type NotificationPrefs,
 } from "./config";
 import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
-import { predictionVerb, chatInboxFrame } from "./prompts";
+import { predictionVerb, formatWhenLine, chatInboxFrame } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
-import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
+import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type Watcher, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
 import { CHAT_STALE_MS, chatLiveness, humanAge, renderChatParticipant, sortChatRoster, splitChatRoster, type ChatHostKind } from "./chat";
 import { detectWorktreeKind } from "./git";
 
@@ -49,8 +54,39 @@ function dedupScanStores(store: string): string[] {
   return store === "global" ? ["global"] : [store, "global"];
 }
 
+/**
+ * Resolve a behavior from feedback/delete text. The behavior nudge renders
+ * "When <matcher description>: <verb> <statement>" - and models copy back
+ * EITHER half (observed live three times: the situation half was fed back
+ * and statement search failed, even though the text was verbatim from the
+ * nudge). Try the statement first, then the matcher description resolved
+ * through its edge to the linked behavior. Returns the behavior row, an
+ * ambiguity list (the situation is shared by multiple behaviors), or null.
+ */
+async function resolveBehaviorForFeedback(
+  ctx: CoreContext,
+  store: string,
+  text: string,
+): Promise<{ behavior: { id: string; statement: string }; via: string } | { ambiguous: string[] } | null> {
+  const embed = await ctx.model.passageEmbed(text);
+  const direct = ctx.db.findNearestBehavior(dedupScanStores(store), embed, BEHAVIOR_DEDUP_COSINE);
+  if (direct) return { behavior: direct, via: "statement" };
+  for (const s of dedupScanStores(store)) {
+    const matcher = ctx.db.findNearestBehaviorMatcher(s, embed, BEHAVIOR_DEDUP_COSINE);
+    if (!matcher) continue;
+    const linked = ctx.db.scoreBehaviors([{ id: matcher.id, description: matcher.description, score: 1 }]);
+    if (linked.length === 1) {
+      const row = ctx.db.getBehavior(linked[0].behavior_id);
+      if (row) return { behavior: row, via: "matcher description" };
+      return null;
+    }
+    if (linked.length > 1) return { ambiguous: linked.map((l) => l.statement) };
+  }
+  return null;
+}
+
 // Minimum matcher cosine to consider a prediction relevant. Matches the
-// auto-fire threshold in index.ts (PREDICTION_THRESHOLD). The query tool
+// auto-fire threshold in runtime.ts (PREDICTION_THRESHOLD). The query tool
 // should not return predictions from near-zero-similarity matchers that
 // would never fire in the auto-fire.
 const PREDICTION_QUERY_THRESHOLD = 0.60;
@@ -64,12 +100,16 @@ export interface CoreContext {
   db: ThatchDB;
   model: EmbeddingModel;
   defaultStore: string;
-  /** Peeks the extraction buffer for a session and returns the serialized
-   *  JSON payload (same shape as buildExtractionPayload). Returns null when
-   *  no interactions are queued. Used by the get_extraction_payload tool so
-   *  the sub-agent fetches the payload as a tool response instead of
-   *  receiving it inline in the nudge text. */
-  extractionPayloadProvider?: (sessionID: string) => string | null;
+  /** Fetches a session's extraction payload for a fetcher. Returns the
+   *  serialized JSON payload (same shape as buildExtractionPayload), or
+   *  null when no interactions are queued. With a fetcherID, the fetch is
+   *  a CLAIM: the fetched entries stay accepted and that fetcher's
+   *  completion signal consumes only this delivery (sibling sub-agents
+   *  going idle cannot drop it). Without a fetcherID, the fetch is a pure
+   *  peek. Used by the get_extraction_payload tool so the sub-agent
+   *  fetches the payload as a tool response instead of receiving it
+   *  inline in the nudge text. */
+  extractionPayloadProvider?: (sessionID: string, fetcherID?: string) => string | null;
   /** Drains a session's extraction queue. On the MCP path this deletes the
    *  file-backed queue and resets the missed-nudge counter. On the opencode
    *  path this is unused (the tool.execute.after hook handles drain via
@@ -129,6 +169,73 @@ export interface ToolDef {
 // Formatting helpers - shared by all tools that render entries
 // ---------------------------------------------------------------------------
 
+/**
+ * Human-readable age of a memory, rendered at output time so the reading
+ * model can weigh staleness semantically (an ISO timestamp does not get
+ * weighed; "47 days ago" does). Keyed on updated_at - the last CONTENT
+ * change - and deliberately NOT on last_recalled_at: hygiene's staleness
+ * sweep treats a recall as refreshing the clock, but for content accuracy
+ * the opposite holds. A memory recalled yesterday but written eight months
+ * ago is exactly the case where the world may have moved on since the
+ * claim was recorded. Freshness-of-use is not freshness-of-claim.
+ *
+ * Bucket boundaries are a formatting choice, independent of hygiene's
+ * 90-day staleness window (db.ts STALE_DAYS) - the two 90s are a
+ * coincidence, do not couple them. Compact sibling: humanAge() in
+ * chat.ts renders roster-style "5m ago" for chat surfaces; keep the two
+ * apart when changing either.
+ */
+export function formatAge(iso: string, now: Date = new Date()): string {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) return "unknown age";
+  const seconds = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 90) return `${days} day${days === 1 ? "" : "s"} ago`;
+  if (days < 365) return `${Math.floor(days / 30)} month${Math.floor(days / 30) === 1 ? "" : "s"} ago`;
+  const years = Math.floor(days / 365);
+  return `${years} year${years === 1 ? "" : "s"} ago`;
+}
+
+/**
+ * The age sentence inserted between the meta line and a memory's content,
+ * so the model weighs staleness BEFORE reading the claim it qualifies.
+ */
+function ageLine(iso: string): string {
+  return `This memory was last updated ${formatAge(iso)}.`;
+}
+
+/**
+ * Caveat attached to memory_recall and memory_show tool output at render
+ * time - the persisted rows are untouched. The sibling of chatInboxFrame's
+ * untrusted-content framing in prompts.ts: a content-classification line
+ * that rides with the claims it qualifies, at the moment they enter the
+ * model's context, instead of a general rule it has to recall from the
+ * system prompt (or a nudge it learns to tune out). memory_list is
+ * excluded: a labels-only listing carries no artifact claims to qualify.
+ *
+ * Tool names use the BARE form (memory_remember, memory_forget) on
+ * purpose: tool-defs.ts is host-shared and has no host context. On MCP
+ * hosts the bare-name convention is established by the instructions in
+ * prompts.ts ("Bare names used below for readability"); on opencode the
+ * system prompt uses thatch_ spellings, but the model sees its own tool
+ * list and maps the bare name without a stated convention. If either
+ * convention changes, update this string with it.
+ */
+const memoryCaveat =
+  `[thatch] Memories are a point-in-time record - a guide to where to look, ` +
+  `not a source of truth. Verify artifact claims (code, docs, tickets, git) ` +
+  `against current sources before relying on them; if a memory has drifted, ` +
+  `correct it with memory_remember (overwrite: true) or memory_forget.`;
+
+function withMemoryCaveat(body: string): string {
+  return `${memoryCaveat}\n\n${body}`;
+}
+
 function formatEntry(
   entry: Awaited<ReturnType<ThatchDB["showEntry"]>>,
 ): string | null {
@@ -139,8 +246,8 @@ function formatEntry(
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
-  meta += ` created:${entry.created_at} updated:${entry.updated_at}`;
-  parts.push(meta, "", entry.content);
+  meta += ` created:${entry.created_at}`;
+  parts.push(meta, "", ageLine(entry.updated_at), entry.content);
   return parts.join("\n");
 }
 
@@ -149,9 +256,8 @@ function formatRecallResult(entry: MemoryRow & { _score: number }): string {
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
-  meta += ` updated:${entry.updated_at}`;
   const score = entry._score.toFixed(3);
-  return `[${meta}] [score:${score}]\n${entry.content}`;
+  return `[${meta}] [score:${score}]\n${ageLine(entry.updated_at)}\n${entry.content}`;
 }
 
 /**
@@ -159,8 +265,26 @@ function formatRecallResult(entry: MemoryRow & { _score: number }): string {
  * so a topic fragmented across N entries reads as one cluster instead of
  * O(N²) pairs. Verdicts stay pairwise (markChecked) - this is presentation only.
  */
-function renderClusters(candidates: DedupCandidate[]): string {
-  const parent = new Map<string, string>();
+/**
+ * Self-heal the watcher registry from the journal before a watch tool reads
+ * it. The runtime (and its registry) is rebuilt on session directory changes
+ * and plugin reloads, leaving journaled watchers absent from the live set
+ * while the old instance's poller keeps delivering: watch_list reported "No
+ * active watchers" and watch_cancel "No watcher in this session" for
+ * watchers that were alive and firing (observed + reproduced September
+ * 2026). Hydrating the CURRENT process's journal row for the session makes
+ * every watch-tool call converge. Cross-process (dormant) rows stay owned
+ * by the runtime's scanDormantWatchers and its revalidation.
+ */
+function reconcileSessionWatchers(ctx: CoreContext, sessionID: string): void {
+  if (!ctx.watchers) return;
+  const row = ctx.db
+    .runtimeStateAll()
+    .find((r) => r.kind === "watchers" && r.sessionID === sessionID && r.pid === process.pid);
+  if (row && Array.isArray(row.value)) ctx.watchers.hydrate(row.value as Watcher[]);
+}
+
+function renderClusters(candidates: DedupCandidate[]): string {  const parent = new Map<string, string>();
   const find = (x: string): string => {
     let root = parent.get(x) ?? x;
     while (root !== (parent.get(root) ?? root)) root = parent.get(root) ?? root;
@@ -202,8 +326,9 @@ const rememberDef: ToolDef = {
     "Each memory should be focused on a single topic. Write memories as " +
     "reference material for a future instance of yourself with zero context.",
   args: {
-    label: z.string().describe(
-      "Short descriptive title. Used for deduplication - same label in the same store is the same entry.",
+    label: z.string().optional().describe(
+      "Short descriptive title. Used for deduplication - same label in the same store is the same entry. " +
+      "Omit to derive it from the content's first heading or line (capped at 80 characters).",
     ),
     content: z.string().describe(
       "The information to remember. Self-contained, understandable without session context.",
@@ -228,8 +353,32 @@ const rememberDef: ToolDef = {
   },
   async execute(args, ctx) {
     const store = resolveStore(args, ctx);
-    const label = args.label as string;
-    const content = `# ${label}\n\n${args.content as string}`;
+    const rawContent = (args.content as string | undefined)?.trim();
+    if (!rawContent) {
+      return "No content provided - pass the information to remember in the content parameter.";
+    }
+    let label = (args.label as string | undefined)?.trim();
+    let content = rawContent;
+    if (!label) {
+      // Label omitted (or arrived under a misnamed key that schema
+      // validation stripped): derive it from the content so the write
+      // still lands instead of erroring. A leading markdown heading
+      // becomes the label and is stripped from the stored content
+      // (heading-only content keeps the heading text as the body so the
+      // entry is never empty). The 80-char cap keeps a derived label -
+      // which can be a whole first line - from bloating list output and
+      // slug keys; matches deriveTitle's cap in extraction.ts.
+      const firstLine = rawContent.split("\n")[0]?.trim() ?? "";
+      const heading = /^#{1,6}\s+(.+)$/.exec(firstLine);
+      if (heading) {
+        label = heading[1].trim().slice(0, 80);
+        const rest = rawContent.split("\n").slice(1).join("\n").trim();
+        content = rest.length > 0 ? rest : heading[1].trim();
+      } else {
+        label = firstLine.slice(0, 80);
+      }
+    }
+    content = `# ${label}\n\n${content}`;
     const embedding = await ctx.model.passageEmbed(content);
 
     const similar = ctx.db.findSimilar(store, embedding, {
@@ -296,7 +445,7 @@ const recallDef: ToolDef = {
 
     if (results.length === 0) return "No matching memories found.";
 
-    return results.map(formatRecallResult).join("\n\n-----\n\n");
+    return withMemoryCaveat(results.map(formatRecallResult).join("\n\n-----\n\n"));
   },
 };
 
@@ -346,7 +495,7 @@ const showDef: ToolDef = {
 
     if (!entry) return `No memory labeled "${args.label as string}" found in store "${store}".`;
 
-    return formatEntry(entry) || "Error formatting entry.";
+    return withMemoryCaveat(formatEntry(entry) || "Error formatting entry.");
   },
 };
 
@@ -474,7 +623,7 @@ const getExtractionPayloadDef: ToolDef = {
     if (!sessionID) {
       return 'session_id is required on this host (it has no session context). Pass the parent session\'s session_id from the extraction nudge.';
     }
-    const payload = ctx.extractionPayloadProvider(sessionID);
+    const payload = ctx.extractionPayloadProvider(sessionID, host?.sessionID);
     if (!payload) {
       return "No queued tool interactions found for this session.";
     }
@@ -488,8 +637,10 @@ const getExtractionPayloadDef: ToolDef = {
  * Called in a PARENT session after dispatching the fact-extractor, it accepts
  * the buffer: entries move to a holding area and the nudge quiets, but they
  * are not dropped until the extractor completes. Called in a CHILD extractor
- * at the end of its run, it completes the parent's accepted entries -
- * including no-save runs that write no memory. If the child errors or is
+ * at the end of its run, it completes the entries THAT child claimed via its
+ * payload fetch - never the whole accepted set, so a sibling sub-agent's
+ * completion cannot drop another extractor's in-flight payload. Completion
+ * includes no-save runs that write no memory. If the child errors or is
  * deleted before either signal, the host requeues the entries so the facts
  * are not lost.
  *
@@ -563,8 +714,7 @@ const predictionQueryDef: ToolDef = {
     if (scored.length === 0) return "No matching predictions found.";
     return scored.map((s) => {
       const verb = predictionVerb(s.evidence_count);
-      return `[${s.confidence.toFixed(2)} conf, ${s.evidence_count} tests] ` +
-        `When ${s.matcher_description}: ${verb} ${s.statement}`;
+      return formatWhenLine(s.confidence, s.evidence_count, s.matcher_description, s.statement, verb);
     }).join("\n");
   },
 };
@@ -576,13 +726,25 @@ const predictionUpdateDef: ToolDef = {
     "model. Use when the user corrects you, answers a question, or " +
     "provides a clear signal about their preferences or decision-making " +
     "strategy. The tool handles matcher and prediction lookup, dedup, " +
-    "and confidence adjustment automatically.",
+    "and confidence adjustment automatically. " +
+    "ALL FOUR of matcher, prediction, signal, and rationale are required " +
+    "in the SAME call - calls omitting any of them fail validation. " +
+    "signal must be exactly one of: create, confirm, disconfirm, soft " +
+    "(use \"create\" for a new observation - never a prose description).",
   args: {
     matcher: z.string().describe(
-      "Description of the situation. What decision was being made?",
+      "Description of the situation. What decision was being made? Word it " +
+      "for semantic matching: after writing it, re-read it against " +
+      "everything that ought to trigger it and widen the wording to the " +
+      "broadest surface of the class - a matcher that only names this " +
+      "incident never fires for the next one.",
     ),
     prediction: z.string().describe(
-      "The user's preference or tendency in this situation.",
+      "The user's preference or tendency in this situation. Phrase it as a " +
+      "tendency starting with a base-form verb (e.g. \"prefer X over Y\", " +
+      "\"push back on Z\") rather than " +
+      "a full sentence - the nudge and query renderers prefix the evidence " +
+      "verb (\"you tend to ...\") onto it.",
     ),
     signal: z.enum(["confirm", "disconfirm", "soft", "create"]).describe(
       "What happened: confirm (user confirmed the prediction), " +
@@ -740,11 +902,19 @@ const behaviorCodifyDef: ToolDef = {
     "discipline, not what the user wants. Examples: check the whole " +
     "codebase for a library before importing it; investigate disabled " +
     "tests before touching the area; read a large function fully before " +
-    "editing it.",
+    "editing it. When a review, bug, or incident reveals a CLASS of " +
+    "mistake you are prone to (not a one-off), codify a guard against the " +
+    "class. ALL THREE of situation, behavior, and rationale are required " +
+    "in the SAME call - calls omitting any of them fail validation.",
   args: {
     situation: z.string().describe(
       "Description of the situation that triggers this behavior. What context " +
-      "or task type makes this rule apply?",
+      "or task type makes this rule apply? Word it for semantic matching: " +
+      "describe the context a future session will be in when this class of " +
+      "trouble starts, then re-read your wording against everything that " +
+      "ought to trigger it and widen it to the broadest surface of the " +
+      "class - a matcher that only names this incident never fires for the " +
+      "next one.",
     ),
     behavior: z.string().describe(
       "The behavioral rule. What should you do when this situation arises?",
@@ -802,11 +972,19 @@ const behaviorFeedbackDef: ToolDef = {
     "or relevant: false (spam) if it does not. This trains the classifier " +
     "so future nudges are more accurate. Also use when the user corrects " +
     "your behavior and you realize a codified rule led you astray or " +
-    "should have been followed.",
+    "should have been followed. The nudge line carries two texts - the " +
+    "situation (\"When ...\") and the behavior statement (after \"do\") - " +
+    "and EITHER is accepted: the tool resolves the situation back to its " +
+    "linked behavior. If it reports no match, the behavior may live in a " +
+    "different store than your default (seeded behaviors live in the " +
+    "global store): list with behavior_list and retry, passing the store " +
+    "the behavior was listed from.",
   args: {
     behavior: z.string().describe(
-      "The behavior statement to provide feedback on. Use behavior_list " +
-      "to find the exact text; matching is semantic (cosine >= 0.85).",
+      "The behavior statement to provide feedback on. The situation line " +
+      "from the nudge (\"When ...\") is also accepted and resolves to its " +
+      "linked behavior. Use behavior_list to find the exact text; " +
+      "matching is semantic (cosine >= 0.85).",
     ),
     relevant: z.boolean().describe(
       "true (ham) if the behavior is relevant to the current situation. " +
@@ -826,9 +1004,20 @@ const behaviorFeedbackDef: ToolDef = {
     const relevant = args.relevant as boolean;
     const contextText = args.context as string;
 
-    const behaviorEmbed = await ctx.model.passageEmbed(behaviorText);
-    const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
-    if (!behavior) return `No behavior matching "${behaviorText}" found in "${store}".`;
+    const resolved = await resolveBehaviorForFeedback(ctx, store, behaviorText);
+    if (!resolved) {
+      return (
+        `No behavior matching "${behaviorText}" found in any of ${dedupScanStores(store).join(", ")} ` +
+        `(tried both statements and matcher descriptions). Use behavior_list to see the exact statements.`
+      );
+    }
+    if ("ambiguous" in resolved) {
+      return (
+        `That text matches a situation shared by multiple behaviors - re-run with the exact statement: ` +
+        resolved.ambiguous.map((s) => `"${s}"`).join("; ")
+      );
+    }
+    const behavior = resolved.behavior;
 
     const signal = relevant ? "confirm" : "disconfirm";
     ctx.db.transaction(() => {
@@ -876,7 +1065,9 @@ const behaviorDeleteDef: ToolDef = {
     "automatically (cascade).",
   args: {
     statement: z.string().describe(
-      "The behavior statement to delete. Use behavior_list to find the " +
+      "The behavior statement to delete. The situation line from the " +
+      "nudge (\"When ...\") is also accepted and resolves to its linked " +
+      "behavior. Use behavior_list to find the " +
       "exact text; matching is semantic (cosine >= 0.85).",
     ),
     store: z.string().optional().describe(
@@ -886,12 +1077,24 @@ const behaviorDeleteDef: ToolDef = {
   async execute(args, ctx) {
     const store = resolveStore(args, ctx);
     const statementText = args.statement as string;
-    const behaviorEmbed = await ctx.model.passageEmbed(statementText);
-    const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
-    if (!behavior) return `No behavior matching "${statementText}" found in "${store}".`;
+    const resolved = await resolveBehaviorForFeedback(ctx, store, statementText);
+    if (!resolved) {
+      return (
+        `No behavior matching "${statementText}" found in any of ${dedupScanStores(store).join(", ")} ` +
+        `(tried both statements and matcher descriptions). Use behavior_list to see the exact statements.`
+      );
+    }
+    if ("ambiguous" in resolved) {
+      return (
+        `That text matches a situation shared by multiple behaviors - re-run with the exact statement: ` +
+        resolved.ambiguous.map((s) => `"${s}"`).join("; ")
+      );
+    }
+    const behavior = resolved.behavior;
+    const rowBefore = ctx.db.getBehavior(behavior.id);
     const deleted = ctx.db.deleteBehavior(behavior.id);
     if (!deleted) return `Failed to delete behavior "${behavior.statement}".`;
-    return `[deleted] "${behavior.statement}" from "${store}"`;
+    return `[deleted] "${behavior.statement}" from "${rowBefore?.store ?? store}"`;
   },
 };
 
@@ -925,6 +1128,15 @@ function renderChatSection(prefs: ChatPrefs | undefined): string {
   ].join("\n");
 }
 
+/** Renders the alerts section. Every event defaults to banner. */
+function renderAlertsSection(prefs: AlertsPrefs | undefined): string {
+  const lines = ["alerts:"];
+  for (const kind of ALERT_EVENT_KINDS) {
+    lines.push(`  ${kind}.mode: ${prefs?.[kind]?.mode ?? "<unset>"} (default: banner)`);
+  }
+  return lines.join("\n");
+}
+
 /** Drops keys explicitly set to undefined so a merge never overwrites. */
 function stripUndefined(obj: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -938,7 +1150,7 @@ const configGetDef: ToolDef = {
     "The config file (~/.config/thatch/config.json, beside thatch.db) is " +
     "also hand-editable. Call this before config_set.",
   args: {
-    section: z.enum(["notifications", "chat"]).optional().describe(
+    section: z.enum(["notifications", "chat", "alerts"]).optional().describe(
       "Restrict output to one section. Omit to read all sections.",
     ),
   },
@@ -956,6 +1168,9 @@ const configGetDef: ToolDef = {
       if (name === "chat") {
         lines.push(renderChatSection(loaded.config.chat));
       }
+      if (name === "alerts") {
+        lines.push(renderAlertsSection(loaded.config.alerts));
+      }
     }
     lines.push("", `file: ${loaded.path}`);
     return lines.join("\n");
@@ -1002,19 +1217,40 @@ const configSetDef: ToolDef = {
       "Chat preferences to update. Fields you omit keep their current " +
       "values.",
     ),
+    alerts: z.strictObject({
+      pause: alertEventPrefsSchema.optional().describe(
+        "Alert when the LLM blocks on a question or permission prompt.",
+      ),
+      done: alertEventPrefsSchema.optional().describe(
+        "Alert when a round of real work finishes. Rounds triggered by " +
+        "synthetic input (thatch nudges, task completions, watcher " +
+        "wake-ups) and rounds of only bookkeeping tools stay silent.",
+      ),
+      error: alertEventPrefsSchema.optional().describe(
+        "Alert when a session fails with nothing to recover it (user " +
+        "aborts stay silent; retried failures stay silent).",
+      ),
+    }).optional().describe(
+      "Automatic alert preferences (desktop notification when the LLM " +
+      "pauses or finishes). Each event takes a mode: both, banner only, " +
+      "voice only, or none. Default: banner.",
+    ),
   },
   async execute(args) {
     const loaded = loadConfig();
     const config: Config = { ...loaded.config };
     const notifPatch = args.notifications as Record<string, unknown> | undefined;
     const chatPatch = args.chat as Record<string, unknown> | undefined;
+    const alertsPatch = args.alerts as Record<string, unknown> | undefined;
     const notifClean = notifPatch ? stripUndefined(notifPatch) : {};
     const chatClean = chatPatch ? stripUndefined(chatPatch) : {};
-    if (Object.keys(notifClean).length === 0 && Object.keys(chatClean).length === 0) {
+    const alertsClean = alertsPatch ? stripUndefined(alertsPatch) : {};
+    if (Object.keys(notifClean).length === 0 && Object.keys(chatClean).length === 0 && Object.keys(alertsClean).length === 0) {
       return (
         "Nothing to update: pass a section with fields to change.\n" +
         renderNotificationSection(config.notifications) + "\n" +
-        renderChatSection(config.chat)
+        renderChatSection(config.chat) + "\n" +
+        renderAlertsSection(config.alerts)
       );
     }
     if (Object.keys(notifClean).length > 0) {
@@ -1027,11 +1263,17 @@ const configSetDef: ToolDef = {
         mergeChatPrefs(config.chat, chatClean),
       );
     }
+    if (Object.keys(alertsClean).length > 0) {
+      config.alerts = alertsPrefsSchema.parse(
+        mergeAlertsPrefs(config.alerts, alertsClean),
+      );
+    }
     const path = saveConfig(config);
     return (
       `[saved] ${path}\n` +
       (Object.keys(notifClean).length > 0 ? renderNotificationSection(config.notifications) + "\n" : "") +
-      (Object.keys(chatClean).length > 0 ? renderChatSection(config.chat) : "")
+      (Object.keys(chatClean).length > 0 ? renderChatSection(config.chat) + "\n" : "") +
+      (Object.keys(alertsClean).length > 0 ? renderAlertsSection(config.alerts) : "")
     );
   },
 };
@@ -1275,6 +1517,7 @@ const watchCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
     const events = (args.events as PrWatcherEventType[] | undefined) ?? [...PR_EVENT_TYPES];
     const result = await ctx.watchers.createPr(host.sessionID, repo, args.pr as number, events, { once: args.once === true });
@@ -1314,6 +1557,7 @@ const watchListDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const watchers = ctx.watchers.listForSession(host.sessionID);
     if (watchers.length === 0) return "No active watchers.";
     const minutesLeft = (w: { expiresAt: number }) => Math.max(0, Math.round((w.expiresAt - Date.now()) / 60_000));
@@ -1379,6 +1623,7 @@ const watchBranchCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     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(
@@ -1463,6 +1708,7 @@ const watchCommandCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const dir = (args.cd as string | undefined) ?? ctx.projectDir;
     if (!dir) {
       return "Watching is unavailable: no project directory was wired by this host.";
@@ -1503,6 +1749,7 @@ const watchCancelDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const cancelled = ctx.watchers.cancel(host.sessionID, args.id as string);
     if (!cancelled) return `No watcher "${args.id}" in this session.`;
     return `[cancelled] ${args.id}`;
@@ -2006,3 +2253,50 @@ export const TOOL_DEFS: ToolDef[] = [
   chatBroadcastDef,
   chatStatusDef,
 ];
+
+/** Extensions a host adapter passes into the shared CoreContext. */
+export interface CoreContextExtensions {
+  extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
+  drainExtractionQueue?: CoreContext["drainExtractionQueue"];
+  watcherRegistry?: WatcherRegistry;
+  projectDir?: string;
+}
+
+/**
+ * Builds the host-agnostic CoreContext both adapters share: the opencode
+ * plugin path and the MCP server each construct a CoreContext once per
+ * init and reuse it for every tool call. This helper is the plugin-side
+ * constructor; the MCP server builds its own inline (src/mcp.ts).
+ *
+ * Lives in this module - NOT in tools.ts - because tools.ts imports the v1
+ * SDK at runtime, and the v2 adapter's entry graph must stay SDK-free (the
+ * v2 plugin install skips optional peers, so evaluating the v1 SDK there
+ * crashes the load).
+ */
+export function buildCoreContext(
+  db: ThatchDB,
+  model: EmbeddingModel,
+  defaultStore: string,
+  extensions?: CoreContextExtensions,
+): CoreContext {
+  return {
+    db,
+    model,
+    defaultStore,
+    extractionPayloadProvider: extensions?.extractionPayloadProvider,
+    drainExtractionQueue: extensions?.drainExtractionQueue,
+    watchers: extensions?.watcherRegistry,
+    projectDir: extensions?.projectDir,
+  };
+}
+
+/**
+ * Trim opencode's per-call ToolContext to the host-agnostic fields the
+ * shared definitions know about. Both adapters do this same two-field trim;
+ * tests and MCP paths pass no host context.
+ */
+export function trimHostContext(
+  hostContext: { sessionID: string; agent: string } | undefined,
+): HostToolContext | undefined {
+  return hostContext ? { sessionID: hostContext.sessionID, agent: hostContext.agent } : undefined;
+}