@jeffober/thatch 0.1.48 → 0.2.0

package/src/seed-behaviors.ts

@@ -30,7 +30,7 @@ interface DefaultBehavior {
  * (2) a user-codified behavior that happens to match a seed situation
  * would be found and silently deleted.
  *
- * Called by both the opencode plugin (src/index.ts) and the MCP server
+ * Called by both the opencode plugin (src/runtime.ts) and the MCP server
  * (src/mcp.ts) at startup, after DB and model initialization.
  */
 const DEFAULT_BEHAVIORS: DefaultBehavior[] = [

package/src/session-db.ts

@@ -54,6 +54,38 @@ export function resolveOpencodeDbPath(): string | null {
   return existsSync(path) ? path : null;
 }
 
+/**
+ * Resolves the session `opencode -c` continues: the most recently updated
+ * top-level session in the directory, read straight from the session
+ * database - the same pick the TUI makes from client.session.list(), which
+ * the v2 plugin context cannot call (its session domain has no list) and
+ * which would arrive too late for the runtime's synchronous rehydration
+ * partition regardless. Null when the db is unavailable or no top-level
+ * session exists in the directory.
+ */
+export function mostRecentTopLevelSessionId(directory: string): string | null {
+  const dbPath = resolveOpencodeDbPath();
+  if (!dbPath) return null;
+  let db: Database;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch {
+    return null;
+  }
+  try {
+    const row = db
+      .query(
+        "SELECT id FROM session WHERE directory = ? AND (parent_id IS NULL OR parent_id = '') ORDER BY time_updated DESC LIMIT 1",
+      )
+      .get(directory) as { id: string } | undefined;
+    return row?.id ?? null;
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
 export interface SessionRow {
   id: string;
   title: string;

package/src/tool-defs.ts

@@ -2,15 +2,20 @@ 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,
@@ -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;
@@ -579,7 +615,11 @@ const predictionUpdateDef: ToolDef = {
     "and confidence adjustment automatically.",
   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.",
@@ -740,11 +780,18 @@ 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.",
   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 +849,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 +881,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 +942,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 +954,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 +1005,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 +1027,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 +1045,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 +1094,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 +1140,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) : "")
     );
   },
 };
@@ -2006,3 +2125,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;
+}

package/src/tools.ts

@@ -1,48 +1,29 @@
 import { tool } from "@opencode-ai/plugin";
-import type { ThatchDB } from "./db";
-import type { EmbeddingModel } from "./embeddings";
-import { TOOL_DEFS, type CoreContext, type HostToolContext } from "./tool-defs";
-import type { WatcherRegistry } from "./watchers";
+import { TOOL_DEFS, trimHostContext, type CoreContext } from "./tool-defs";
+
+// V1-ONLY module: this file imports the opencode v1 SDK at runtime, so
+// nothing shared may import from it. The host-agnostic pieces
+// (buildCoreContext, trimHostContext, CoreContext, TOOL_DEFS) live in
+// tool-defs.ts precisely so the v2 adapter and the MCP server can use them
+// without evaluating the v1 SDK - the v2 plugin install skips optional
+// peers, and a missing SDK import here would kill the whole plugin load.
 
 /**
- * Builds the opencode tool map from shared tool definitions. Each definition
- * in TOOL_DEFS is wrapped in opencode's `tool()` with a `thatch_` prefix
- * on the name - opencode uses the object key as the tool name, so the prefix
- * lives here, not in the shared definitions.
+ * Builds the v1 opencode tool map from shared tool definitions. Each
+ * definition in TOOL_DEFS is wrapped in opencode's `tool()` with a
+ * `thatch_` prefix on the name - opencode uses the object key as the tool
+ * name, so the prefix lives here, not in the shared definitions. Takes the
+ * shared CoreContext (buildCoreContext) rather than raw deps, so both host
+ * adapters feed the same context construction.
  */
-export function createTools(
-  db: ThatchDB,
-  model: EmbeddingModel,
-  defaultStore: string,
-  extensions?: {
-    extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
-    drainExtractionQueue?: CoreContext["drainExtractionQueue"];
-    watcherRegistry?: WatcherRegistry;
-    projectDir?: string;
-  },
-): Record<string, ReturnType<typeof tool>> {
-  const ctx: CoreContext = {
-    db,
-    model,
-    defaultStore,
-    extractionPayloadProvider: extensions?.extractionPayloadProvider,
-    drainExtractionQueue: extensions?.drainExtractionQueue,
-    watchers: extensions?.watcherRegistry,
-    projectDir: extensions?.projectDir,
-  };
-
+export function createTools(coreContext: CoreContext): Record<string, ReturnType<typeof tool>> {
   const tools: Record<string, ReturnType<typeof tool>> = {};
   for (const def of TOOL_DEFS) {
     tools[`thatch_${def.name}`] = tool({
       description: def.description,
       args: def.args,
       async execute(args, hostContext) {
-        // Trim opencode's ToolContext to the host-agnostic fields the shared
-        // definitions know about. Tests and MCP paths pass no host context.
-        const host: HostToolContext | undefined = hostContext
-          ? { sessionID: hostContext.sessionID, agent: hostContext.agent }
-          : undefined;
-        return def.execute(args as Record<string, unknown>, ctx, host);
+        return def.execute(args as Record<string, unknown>, coreContext, trimHostContext(hostContext));
       },
     });
   }

package/src/watchers.ts

@@ -16,16 +16,14 @@
  * never its output (injection hygiene: command output can be external
  * content, so it never rides a notification).
  *
- * Lifetime is deliberately process-scoped. The registry lives in plugin
- * memory, never in SQLite: opencode loads thatch in-process, so the plugin
- * process is the natural owner of its watchers. This makes multi-instance
- * ownership structurally impossible (each process polls only what it
- * registered), leaves no orphan data behind, and matches the extraction
- * pipeline's opencode path, which is also in-memory. A crashed or restarted
- * opencode loses its watchers - acceptable, because the session that created
- * them lost its conversational context too, and a delivered notification
- * into a session that no longer knows why it is being watched is worse than
- * a lost watch.
+ * Lifetime is deliberately process-scoped for the LIVE registry: the
+ * poller and delivery state live in plugin memory, never in SQLite -
+ * opencode loads thatch in-process, so the plugin process is the natural
+ * owner of its watchers, and no cross-process "who polls this?" claim
+ * logic is needed. The DEFINITIONS, however, are journaled to
+ * runtime_state (the optional journal hook) so they survive v2 plugin
+ * reloads and, as dormant rows, full restarts - see the rearm() and the
+ * runtime's dormant-watcher scan.
  */
 
 // ---------------------------------------------------------------------------
@@ -280,6 +278,8 @@ export interface WatcherRegistryOptions {
   pollIntervalMs?: number;
   ttlMinutes?: number;
   maxPerSession?: number;
+  /** Persistence hook: called after membership changes with the session's watcher list. */
+  journal?: (sessionID: string, watchers: Watcher[]) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -391,6 +391,17 @@ export async function ghApiRunWithTimeout(apiArgs: string[], timeoutMs: number):
   }
 }
 
+/**
+ * The stable target label a watcher reports in events, lists, and recovery
+ * notices: "owner/repo#N" for PRs, "owner/repo@branch" for branches, and a
+ * one-line clip of the command for command watches.
+ */
+export function watcherTarget(watcher: Watcher): string {
+  if (watcher.source === "pr") return `${watcher.repo}#${watcher.pr}`;
+  if (watcher.source === "branch") return `${watcher.repo}@${watcher.branch}`;
+  return commandTargetLabel(watcher.command);
+}
+
 let ghAvailability: boolean | null = null;
 
 /**
@@ -829,6 +840,13 @@ export class WatcherRegistry {
   #timer: ReturnType<typeof setInterval> | null = null;
   #delivering = false;
   #polling = false;
+  /**
+   * Persistence hook (optional): called after every membership change with
+   * the session's current watcher list, so the runtime can journal the
+   * definitions and re-arm them after a v2 plugin reload. Passing no hook
+   * (tests, MCP) keeps the registry in-memory only.
+   */
+  #journal?: (sessionID: string, watchers: Watcher[]) => void;
   readonly #opts: WatcherRegistryOptions & {
     pollIntervalMs: number;
     ttlMinutes: number;
@@ -846,6 +864,7 @@ export class WatcherRegistry {
       commandTimeoutMs: defaultCommandTimeoutMs(),
       ...options,
     };
+    this.#journal = options.journal;
   }
 
   // -- Lifecycle -----------------------------------------------------------
@@ -889,6 +908,59 @@ export class WatcherRegistry {
 
   // -- CRUD ----------------------------------------------------------------
 
+  /** Journal the session's current watcher list (no-op without a hook). */
+  #emit(sessionID: string): void {
+    this.#journal?.(sessionID, this.listForSession(sessionID));
+  }
+
+  /** Restore persisted watchers (same-process reload rehydration). */
+  hydrate(watchers: Watcher[]): void {
+    for (const w of watchers) {
+      // Do not clobber a watcher created after the journal was written.
+      if (!this.#watchers.has(w.id)) this.#watchers.set(w.id, w);
+    }
+  }
+
+  /**
+   * Re-arms persisted watcher definitions recovered on session resume after
+   * a restart (the dormant journal rows the runtime keeps instead of
+   * pruning). Definitions whose TTL expired while the session was away are
+   * dropped - a watch that outlived its own expiry must not fire on a stale
+   * baseline. PR and branch definitions are REVALIDATED by re-fetching
+   * their baseline: a deleted branch or closed PR would otherwise re-arm
+   * into silent poll failure, and a stale baseline would flood the session
+   * with every event that happened while it was away; fetch failures drop
+   * the definition and count as failed. The rest join the live registry
+   * newest-first up to the per-session limit (the session may have created
+   * watchers since the restart), and the journal is rewritten either way:
+   * with the current process's pid when anything re-arms, deleted when
+   * nothing does.
+   */
+  async rearm(sessionID: string, defs: Watcher[]): Promise<{ rearmed: Watcher[]; expired: number; failed: number }> {
+    const now = Date.now();
+    const fresh = defs.filter((w) => now <= w.expiresAt).sort((a, b) => b.createdAt - a.createdAt);
+    const budget = Math.max(0, this.#opts.maxPerSession - this.listForSession(sessionID).length);
+    const rearmed: Watcher[] = [];
+    let failed = 0;
+    for (const def of fresh.slice(0, budget)) {
+      if (def.source !== "command") {
+        try {
+          def.state = def.source === "pr"
+            ? await fetchPrState(this.#opts.ghRunner, def.repo, def.pr)
+            : await fetchBranchState(this.#opts.ghRunner, def.repo, def.branch);
+        } catch {
+          failed++;
+          continue;
+        }
+      }
+      // Do not clobber a watcher created after the journal was written.
+      if (!this.#watchers.has(def.id)) this.#watchers.set(def.id, def);
+      rearmed.push(def);
+    }
+    this.#emit(sessionID);
+    return { rearmed, expired: defs.length - fresh.length, failed };
+  }
+
   /**
    * Registers a PR watcher and captures the baseline state immediately. The
    * baseline fetch doubles as validation: a bad repo, missing PR, or broken
@@ -929,6 +1001,7 @@ export class WatcherRegistry {
       state,
     };
     this.#watchers.set(watcher.id, watcher);
+    this.#emit(sessionID);
     return { ok: true, watcher };
   }
 
@@ -973,6 +1046,7 @@ export class WatcherRegistry {
       state,
     };
     this.#watchers.set(watcher.id, watcher);
+    this.#emit(sessionID);
     return { ok: true, watcher };
   }
 
@@ -1028,6 +1102,7 @@ export class WatcherRegistry {
       state: { lastExit: baseline.timedOut ? 124 : baseline.exitCode },
     };
     this.#watchers.set(watcher.id, watcher);
+    this.#emit(sessionID);
     return { ok: true, watcher };
   }
 
@@ -1051,6 +1126,7 @@ export class WatcherRegistry {
     const watcher = this.#watchers.get(id);
     if (!watcher || watcher.sessionID !== sessionID) return false;
     this.#watchers.delete(id);
+    this.#emit(sessionID);
     return true;
   }
 
@@ -1060,6 +1136,7 @@ export class WatcherRegistry {
       if (w.sessionID === sessionID) this.#watchers.delete(id);
     }
     this.#pending.delete(sessionID);
+    this.#emit(sessionID);
   }
 
   // -- Polling and delivery ------------------------------------------------
@@ -1079,6 +1156,7 @@ export class WatcherRegistry {
       for (const [id, watcher] of this.#watchers) {
         if (now > watcher.expiresAt) {
           this.#watchers.delete(id);
+          this.#emit(watcher.sessionID);
           continue;
         }
         try {
@@ -1092,7 +1170,10 @@ export class WatcherRegistry {
             // if the session is busy. Cancellation at detection time keeps
             // "wait for this run to finish" from leaving a standing watch
             // polling a target nobody is waiting on anymore.
-            if (watcher.once) this.#watchers.delete(id);
+            if (watcher.once) {
+              this.#watchers.delete(id);
+              this.#emit(watcher.sessionID);
+            }
           }
         } catch (err) {
           console.error(`[thatch] watcher ${id} poll failed: ${err}`);
@@ -1108,7 +1189,7 @@ export class WatcherRegistry {
   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))
+      const events = diffPrState(watcher.state, after, watcherTarget(watcher), this.#prUrl(watcher))
         .filter((e) => watcher.events.includes(e.type as PrWatcherEventType));
       watcher.state = after;
       return events;
@@ -1124,13 +1205,13 @@ export class WatcherRegistry {
       if (result.timedOut || result.exitCode !== 0) return [];
       return [{
         type: "command_success",
-        target: commandTargetLabel(watcher.command),
+        target: watcherTarget(watcher),
         summary: `command exited 0 (took ${(result.durationMs / 1000).toFixed(1)}s)`,
         url: "",
       }];
     }
     const after = await fetchBranchState(this.#opts.ghRunner, watcher.repo, watcher.branch);
-    const all = diffBranchState(watcher.state, after, `${watcher.repo}@${watcher.branch}`, watcher.repo);
+    const all = diffBranchState(watcher.state, after, watcherTarget(watcher), 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