@jeffober/thatch 0.1.38 → 0.1.40

package/src/embeddings.ts

@@ -16,6 +16,7 @@ export interface EmbeddingModel {
   load(): Promise<void>;
   queryEmbed(text: string): Promise<Float32Array>;
   passageEmbed(text: string): Promise<Float32Array>;
+  dispose(): Promise<void>;
 }
 
 /**
@@ -24,11 +25,99 @@ export interface EmbeddingModel {
  */
 export type PipelineFactory = (modelName: string) => Promise<any>;
 
+/**
+ * Embedding backend mode. "wasm" runs the ONNX model on onnxruntime-web's
+ * pure-JS/wasm runtime; "native" runs it on onnxruntime-node's NAPI addon.
+ */
+export type EmbeddingBackendMode = "wasm" | "native";
+
+/**
+ * Reads the backend override. Only "native" opts out; any other value,
+ * including unset, selects the wasm default. Exported for tests.
+ */
+export function backendMode(): EmbeddingBackendMode {
+  return process.env.THATCH_EMBEDDING_BACKEND === "native" ? "native" : "wasm";
+}
+
+const ORT_SYMBOL = Symbol.for("onnxruntime");
+
+let backendConfigured: Promise<EmbeddingBackendMode> | null = null;
+
+/**
+ * Chooses the ONNX backend before transformers initializes. Memoized: the
+ * choice is made once at transformers' module init and cannot be changed
+ * afterwards. Exported for tests.
+ *
+ * "wasm" mode pins globalThis[Symbol.for("onnxruntime")] to onnxruntime-web
+ * so transformers' node build creates sessions on its pure-JS/wasm runtime
+ * instead of the onnxruntime-node NAPI addon. The NAPI addon leaves wrap
+ * finalizers that panic Bun at process teardown (oven-sh/bun#34664); the wasm
+ * runtime creates none. A backend already chosen by the host (symbol present)
+ * is respected, never clobbered. A failed onnxruntime-web import falls back
+ * to native rather than blocking embedding.
+ */
+export async function configureBackend(): Promise<EmbeddingBackendMode> {
+  backendConfigured ??= (async () => {
+    const mode = backendMode();
+    if (mode === "native" || ORT_SYMBOL in globalThis) return mode;
+    try {
+      const ort = await import("onnxruntime-web");
+      (globalThis as Record<symbol, unknown>)[ORT_SYMBOL] = ort;
+      // Single-threaded wasm: deterministic, and avoids worker_threads,
+      // where Bun has known shutdown crashes. Latency at one thread is fine
+      // for background embedding.
+      ort.env.wasm.numThreads = 1;
+    } catch {
+      // onnxruntime-web unavailable - native sessions still work.
+    }
+    return mode;
+  })();
+  return backendConfigured;
+}
+
+/**
+ * Test hook: clears the configureBackend memo and unpins the onnxruntime
+ * global, so a test can exercise the pinning path itself. Needed because the
+ * test process is shared across files: initializing the plugin server seeds
+ * behaviors, which embeds, which runs configureBackend and pins the symbol
+ * as a side effect. Whether that happened before a given test file runs
+ * depends on bun's file order, which differs between machines.
+ */
+export function resetBackendForTests(): void {
+  backendConfigured = null;
+  delete (globalThis as Record<symbol, unknown>)[ORT_SYMBOL];
+}
+
 const defaultPipelineFactory: PipelineFactory = async (modelName) => {
+  const mode = await configureBackend();
   const { pipeline } = await import("@huggingface/transformers");
-  return pipeline("feature-extraction", modelName);
+  if (mode === "native") {
+    return pipeline("feature-extraction", modelName);
+  }
+  // The ORT_SYMBOL override branch leaves transformers' device allowlist
+  // empty, so any named device throws; "auto" bypasses the check and the
+  // explicit execution provider does the real work.
+  return pipeline("feature-extraction", modelName, {
+    device: "auto",
+    session_options: { executionProviders: ["wasm"] },
+  });
 };
 
+/**
+ * How long a loaded pipeline may sit unused before its native ONNX sessions
+ * are released while the runtime is still healthy. Long enough to span the
+ * gap between extraction bursts, short enough to matter before process exit.
+ */
+const DEFAULT_IDLE_TTL_MS = 10 * 60 * 1000;
+
+export interface BgeEmbeddingModelOptions {
+  /**
+   * Idle milliseconds before the pipeline's native sessions are released.
+   * A later embed lazily re-loads. 0 disables idle release.
+   */
+  idleTtlMs?: number;
+}
+
 /**
  * Lazy-loads an embedding model via @huggingface/transformers.
  * Model files (~34 MB for the default) are downloaded once and cached by HF Hub.
@@ -36,12 +125,19 @@ const defaultPipelineFactory: PipelineFactory = async (modelName) => {
 export class BgeEmbeddingModel implements EmbeddingModel {
   #modelName: string;
   #pipelineFactory: PipelineFactory;
+  #idleTtlMs: number;
   #pipe: any = null;
   #loading: Promise<void> | null = null;
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor(modelName = "Xenova/bge-small-en-v1.5", pipelineFactory?: PipelineFactory) {
+  constructor(
+    modelName = "Xenova/bge-small-en-v1.5",
+    pipelineFactory?: PipelineFactory,
+    options: BgeEmbeddingModelOptions = {},
+  ) {
     this.#modelName = modelName;
     this.#pipelineFactory = pipelineFactory ?? defaultPipelineFactory;
+    this.#idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
   }
 
   get loaded(): boolean {
@@ -74,11 +170,90 @@ export class BgeEmbeddingModel implements EmbeddingModel {
   }
 
   async #embed(text: string): Promise<Float32Array> {
-    await this.load();
-    const output = await this.#pipe(text, {
-      pooling: "mean",
-      normalize: true,
-    });
-    return output.data as Float32Array;
+    // Clear any pending idle timer before touching the pipeline. The timer
+    // must never fire while an embed is in flight - its callback releases
+    // the pipeline this call is about to use.
+    this.#clearIdleTimer();
+    try {
+      await this.load();
+      const pipe = this.#pipe;
+      const output = await pipe(text, {
+        pooling: "mean",
+        normalize: true,
+      });
+      // Copy the vector before releasing the tensor: the real Tensor's data
+      // getter exposes memory the disposer frees.
+      const data = new Float32Array(output.data);
+      if (typeof output?.dispose === "function") {
+        try {
+          await output.dispose();
+        } catch {
+          // Tensor release is best-effort; the copied data is already valid.
+        }
+      }
+      return data;
+    } finally {
+      this.#armIdleTimer();
+    }
+  }
+
+  /**
+   * Releases the pipeline's native ONNX sessions. The host calls this during
+   * graceful shutdown so onnxruntime's NAPI wrap finalizers are freed while
+   * the runtime is still alive. If instead they survive to Bun's worker
+   * teardown, Bun panics creating their errors (oven-sh/bun#34664).
+   *
+   * The idle timer releases on the same principle during normal operation:
+   * the plugin's dispose hook is best-effort because opencode can exit
+   * without running it, so sessions are also freed after a quiet period.
+   *
+   * Best-effort by design: dispose never throws, and a failed release is
+   * indistinguishable from never loading. An embed call after dispose just
+   * lazily re-loads the model.
+   */
+  async dispose(): Promise<void> {
+    this.#clearIdleTimer();
+    // An in-flight load memoizes a rejecting promise on failure. Await it
+    // defensively so its error neither escapes dispose nor kills the teardown.
+    if (this.#loading) {
+      try {
+        await this.#loading;
+      } catch {
+        // Load failed - nothing was loaded, so nothing to release.
+      }
+    }
+    await this.#release();
+  }
+
+  async #release(): Promise<void> {
+    const pipe = this.#pipe;
+    this.#pipe = null;
+    this.#loading = null;
+    if (!pipe) return;
+    try {
+      await pipe.dispose();
+    } catch {
+      // Best-effort - see dispose's doc comment.
+    }
+  }
+
+  #armIdleTimer(): void {
+    if (this.#idleTtlMs <= 0) return;
+    this.#clearIdleTimer();
+    this.#idleTimer = setTimeout(() => {
+      this.#idleTimer = null;
+      this.#release().catch(() => {
+        // Idle release is best-effort; a failed release retries on dispose.
+      });
+    }, this.#idleTtlMs);
+    // Never hold the host process open for an idle timer.
+    this.#idleTimer.unref?.();
+  }
+
+  #clearIdleTimer(): void {
+    if (this.#idleTimer) {
+      clearTimeout(this.#idleTimer);
+      this.#idleTimer = null;
+    }
   }
 }

package/src/index.ts

@@ -816,6 +816,10 @@ export const server: Plugin = async ({ client, worktree }) => {
     dispose: async () => {
       stopVersionChecker();
       watchers.dispose();
+      // Release native ONNX sessions while the worker is still healthy. Left
+      // to Bun's teardown, their NAPI finalizers panic the process (see
+      // BgeEmbeddingModel.dispose).
+      await model.dispose();
       db.close();
     },
   };

package/src/notify.ts

@@ -0,0 +1,123 @@
+// Out-of-band user notification: desktop banner plus spoken voice. Both are
+// plain child processes - no vendored binaries, no npm notifier dependency -
+// because the per-platform commands are one-liners and the alternatives
+// (node-notifier's bundled terminal-notifier) trip Gatekeeper on modern macOS.
+// Dispatch is darwin and linux only by design: win32 support is not a goal,
+// and the tool reports the gap honestly rather than half-working.
+
+export type NotifyChannel = "both" | "banner" | "voice";
+
+export interface NotifyRequest {
+  message: string;
+  title?: string;
+  source?: string;
+  channel: NotifyChannel;
+  /** Voice name override; falls back to the platform default. */
+  voice?: string;
+  /** Banner alert sound (macOS); falls back to Submarine. */
+  sound?: string;
+  platform?: string;
+}
+
+export interface SpawnResult {
+  exitCode: number | null;
+  stderr: string;
+}
+
+export type Spawner = (cmd: string[]) => Promise<SpawnResult>;
+
+/** The real runner. Tests inject a mock so nothing actually speaks. */
+export const defaultSpawner: Spawner = async (cmd) => {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+  return { exitCode: proc.exitCode, stderr };
+};
+
+/**
+ * The spoken line. The source label (ticket number, feature name) goes first
+ * so the listener immediately knows which session is talking.
+ */
+export function spokenText(request: Pick<NotifyRequest, "message" | "source">): string {
+  return request.source ? `${request.source}: ${request.message}` : request.message;
+}
+
+/** AppleScript string literal - backslash and double-quote are the escapes. */
+function appleScriptString(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+interface StepOutcome {
+  label: string;
+  ok: boolean;
+  detail: string;
+}
+
+async function runStep(label: string, cmd: string[], spawner: Spawner): Promise<StepOutcome> {
+  try {
+    const result = await spawner(cmd);
+    if (result.exitCode === 0) {
+      return { label, ok: true, detail: label };
+    }
+    return { label, ok: false, detail: `${label} failed: exited ${result.exitCode}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ""}` };
+  } catch (err) {
+    // Missing binary surfaces here (ENOENT) rather than as an exit code.
+    return { label, ok: false, detail: `${label} failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * Sends the notification and returns a result line for the tool response.
+ * A zero exit proves only that the command ran - macOS focus modes can still
+ * suppress the banner silently - so the result never claims the user saw it.
+ * Never throws: every failure becomes text the calling model can read.
+ */
+export async function sendNotification(
+  request: NotifyRequest,
+  spawner: Spawner = defaultSpawner,
+): Promise<string> {
+  const platform = request.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux") {
+    return `[unsupported] notifications are not implemented on ${platform} (macOS and Linux only); nothing was sent.`;
+  }
+
+  const outcomes: StepOutcome[] = [];
+
+  if (request.channel !== "voice") {
+    const title = request.title ?? request.source ?? "thatch";
+    if (platform === "darwin") {
+      const sound = request.sound ?? "Submarine";
+      const script =
+        `display notification ${appleScriptString(request.message)} ` +
+        `with title ${appleScriptString(title)} sound name ${appleScriptString(sound)}`;
+      outcomes.push(await runStep("banner (osascript)", ["/usr/bin/osascript", "-e", script], spawner));
+    } else {
+      outcomes.push(await runStep("banner (notify-send)", ["notify-send", title, request.message], spawner));
+    }
+  }
+
+  if (request.channel !== "banner") {
+    const spoken = spokenText(request);
+    if (platform === "darwin") {
+      const voice = request.voice ?? "Zarvox";
+      outcomes.push(await runStep(`voice (${voice})`, ["/usr/bin/say", "-v", voice, spoken], spawner));
+    } else {
+      // spd-say has no voice flag, so a voice override goes straight to
+      // espeak (-v). Without an override, speech-dispatcher is the friendlier
+      // default; raw espeak is the fallback when it is absent.
+      if (request.voice) {
+        outcomes.push(await runStep(`voice (espeak -v ${request.voice})`, ["espeak", "-v", request.voice, spoken], spawner));
+      } else {
+        const spd = await runStep("voice (spd-say)", ["spd-say", "-w", spoken], spawner);
+        outcomes.push(spd.ok ? spd : await runStep("voice (espeak)", ["espeak", spoken], spawner));
+      }
+    }
+  }
+
+  const failed = outcomes.filter((o) => !o.ok);
+  if (outcomes.every((o) => !o.ok)) {
+    return `[failed] ${failed.map((o) => o.detail).join("; ")}`;
+  }
+  const parts = outcomes.map((o) => (o.ok ? `${o.detail} ok` : o.detail));
+  return `[notified] ${parts.join("; ")}`;
+}

package/src/prediction.ts

@@ -89,7 +89,7 @@ export class PredictionEngine {
     return this.#engine.createMatcher(store, description, embedding, model);
   }
 
-  findNearestPrediction(store: string, embedding: Float32Array, threshold: number): PredictionRow | null {
+  findNearestPrediction(store: string | string[], embedding: Float32Array, threshold: number): PredictionRow | null {
     return this.#engine.findNearestItem(store, embedding, threshold) as PredictionRow | null;
   }
 

package/src/prompts.ts

@@ -23,7 +23,8 @@ Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
         thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
         thatch_prediction_delete,
         thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
-        thatch_behavior_delete, thatch_get_session_info,
+        thatch_behavior_delete, thatch_config_get, thatch_config_set,
+        thatch_notify_user, thatch_get_session_info,
         thatch_session_search, thatch_session_get,
         thatch_watch_create, thatch_watch_branch_create,
         thatch_watch_list, thatch_watch_cancel
@@ -178,6 +179,17 @@ way that is about your own operational discipline (not a user preference):
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
+## Notifications
+
+Use thatch_notify_user for terminal-event outcomes the user should hear about
+even when looking away: CI results, merge or deploy completion, watcher
+events. Always include a source label (ticket number or feature name) so the
+user knows which session spoke. Manage notification preferences with
+thatch_config_get and thatch_config_set - call config_get first; config_set
+merges fields and echoes the result. The config file
+(~/.config/thatch/config.json) is also hand-editable; do not store thatch
+config in memory.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -288,7 +300,9 @@ Tools are prefixed in ${host}: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`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.
+\`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`,
+\`mcp__thatch__config_get\`, \`mcp__thatch__config_set\`,
+\`mcp__thatch__notify_user\`. Bare names used below for readability.
 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
@@ -324,7 +338,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-economy\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` - eight specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-economy\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` / \`-mentorship\` - nine specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
 - \`thatch-project-primer\` - investigate a new project and write foundational memories.
 - \`thatch-session-reflection\` - record what you learned at end of session.
 - \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
@@ -412,6 +426,16 @@ way that is about your own operational discipline (not a user preference):
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
+## Notifications
+
+Use notify_user for terminal-event outcomes the user should hear about even
+when looking away: CI results, merge or deploy completion, watcher events.
+Always include a source label (ticket number or feature name) so the user
+knows which session spoke. Manage notification preferences with config_get
+and config_set - call config_get first; config_set merges fields and echoes
+the result. The config file (~/.config/thatch/config.json) is also
+hand-editable; do not store thatch config in memory.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment

package/src/scoring-engine.ts

@@ -118,7 +118,7 @@ export class ScoringEngine {
     const rows = this.#db
       .query(
         `SELECT p.id, p.statement, p.rationale, p.confidence, p.confirm_count, p.disconfirm_count,
-                e.matcher_id, e.weight
+                p.embedding, e.matcher_id, e.weight
          FROM ${edgesTable} e
          JOIN ${itemsTable} p ON e.${itemForeignKey} = p.id
          WHERE e.matcher_id IN (${placeholders})
@@ -128,6 +128,7 @@ export class ScoringEngine {
 
     const matcherMap = new Map(matchers.map((m) => [m.id, m]));
     const scored: ScoredItem[] = [];
+    const embeddings = new Map<string, Float32Array>();
     for (const r of rows) {
       const matcher = matcherMap.get(r.matcher_id);
       if (!matcher) continue;
@@ -135,6 +136,7 @@ export class ScoringEngine {
       const confidence = r.confidence as number;
       const evidence = Math.round(r.confirm_count + r.disconfirm_count);
       const score = matcher.score * (r.weight as number) * confidence;
+      if (r.embedding) embeddings.set(r.id as string, blobToVector(r.embedding));
       scored.push({
         matcher_id: r.matcher_id,
         matcher_description: matcher.description,
@@ -153,9 +155,25 @@ export class ScoringEngine {
     // so the nudge does not repeat the same item with different matcher
     // contexts.
     const seen = new Set<string>();
+    // Semantic dedup across stores: the same preference saved to both the
+    // project and global stores has different row ids but near-identical
+    // embeddings. Without this, the multi-store nudge scan surfaces it
+    // twice every turn. Sorted by score descending, so the first occurrence
+    // (highest-scoring copy) wins.
+    const SEMANTIC_DEDUP_COSINE = 0.85;
+    const seenEmbeddings: Float32Array[] = [];
     return scored.filter((s) => {
       if (seen.has(s.item_id)) return false;
       seen.add(s.item_id);
+      const emb = embeddings.get(s.item_id);
+      if (emb) {
+        for (const other of seenEmbeddings) {
+          if (other.length === emb.length && cosineSimilarity(other, emb) >= SEMANTIC_DEDUP_COSINE) {
+            return false;
+          }
+        }
+        seenEmbeddings.push(emb);
+      }
       return true;
     });
   }
@@ -219,18 +237,21 @@ export class ScoringEngine {
   }
 
   findNearestItem(
-    store: string,
+    store: string | string[],
     embedding: Float32Array,
     threshold: number,
   ): ItemRow | null {
     const { itemsTable } = this.#cfg;
+    const stores = Array.isArray(store) ? store : [store];
+    if (stores.length === 0) return null;
+    const placeholders = stores.map(() => "?").join(", ");
     const rows = this.#db
       .query(
         `SELECT id, store, statement, rationale, confidence, confirm_count, disconfirm_count, created_at, updated_at, embedding
          FROM ${itemsTable}
-         WHERE store = ? AND embedding IS NOT NULL`,
+         WHERE store IN (${placeholders}) AND embedding IS NOT NULL`,
       )
-      .all(store) as any[];
+      .all(...(stores as [string, ...string[]])) as any[];
 
     let best: { row: any; score: number } | null = null;
     for (const r of rows) {

package/src/skills.ts

@@ -41,6 +41,7 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-review-breadcrumbs",
     "thatch-review-mark-and-sweep",
     "thatch-review-highlights",
+    "thatch-review-mentorship",
     "thatch-review-synthesizer",
     "thatch-review-context",
     "thatch-code-archaeology",