@jeffober/thatch 0.2.3 → 0.2.5

package/src/mcp.ts

@@ -70,7 +70,9 @@ export function compileTools(): Map<string, CompiledTool> {
   for (const def of TOOL_DEFS) {
     // opencode-only tools depend on host capabilities MCP servers don't
     // have (e.g. session identity via HostToolContext) - never expose them.
-    if (def.opencodeOnly) continue;
+    // v2-only tools ride v2 plugin surfaces (session move, rpc emit) with
+    // no MCP equivalent - same rule.
+    if (def.opencodeOnly || def.v2Only) continue;
     const schema = z.object(def.args);
     map.set(def.name, {
       def,
@@ -120,7 +122,12 @@ export function compilePrompts(): Map<string, ActionDef> {
  * prompt and search for matches without loading the model themselves.
  */
 export async function runMcpServer(): Promise<void> {
-  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  // Deliberate superset of detectRepo's own chain (src/git.ts): the pinned
+  // THATCH_PROJECT_DIR (written into project-local MCP configs by setup)
+  // beats ambient host vars, which beat the spawn cwd - the server's spawn
+  // cwd is the one input no in-repo test can pin.
+  const projectDir =
+    process.env.THATCH_PROJECT_DIR ?? process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
 
   const home = process.env.HOME ?? "/tmp";
   const configHome = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
@@ -130,7 +137,13 @@ export async function runMcpServer(): Promise<void> {
   // The DB must exist before identity detection: detectRepo consults the
   // repo_paths cache when the project directory is gone (deleted worktree).
   const db = new ThatchDB(dbPath);
-  const repo = await detectRepo(projectDir, repoPathCache(db));
+  const detected = await detectRepo(projectDir, repoPathCache(db));
+  // unknown-to-global, matching the hook's mapping (bin/thatch): chat
+  // registration must follow the same store the tools would read, and
+  // resolveStore degrades both spellings to the global store anyway. The
+  // alignment keeps hook-registered and server-registered rows comparable
+  // by project - which the `as` identity binding depends on.
+  const repo = detected === "unknown" ? "global" : detected;
   const model = new BgeEmbeddingModel(modelName);
 
   await seedDefaultBehaviors(db, model);
@@ -251,6 +264,27 @@ export async function runMcpServer(): Promise<void> {
   // requests. Never blocks tool calls.
   startVersionChecker(dbPath);
 
+  // Idempotent teardown, shared by the stdin-end path (the host closed the
+  // pipe - the normal shutdown) and the signal handlers (SIGINT/SIGTERM/
+  // SIGHUP kill the process mid-loop, and without handlers they skipped
+  // every teardown step). Order matters: the sideband goes first (nothing
+  // may reach the model after disposal), the model's ONNX sessions release
+  // before the db closes, and the db close runs in a finally so a disposal
+  // failure cannot leak the connection.
+  const teardown = createMcpTeardown({
+    sideband,
+    model,
+    db,
+    dbPath,
+    stopVersionChecker,
+    removeVersionFile,
+  });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.on(signal, () => {
+      void teardown(signal).then(() => process.exit(0));
+    });
+  }
+
   // Read stdin line by line. Each line is a complete JSON-RPC message.
   const decoder = new TextDecoder();
   let buf = "";
@@ -303,10 +337,64 @@ export async function runMcpServer(): Promise<void> {
     }
   }
 
-  sideband.stop();
-  stopVersionChecker();
-  removeVersionFile(dbPath);
-  db.close();
+  await teardown("stdin-end");
+}
+
+/**
+ * Builds the idempotent MCP-server teardown. Injected deps so tests can
+ * spy on the close order without spawning anything: sideband first
+ * (nothing may reach the model after disposal), version checker + file
+ * next, the model's native ONNX sessions in a catch (a disposal failure
+ * must not skip the db close), and the db in a finally.
+ */
+export function createMcpTeardown(deps: {
+  sideband: { stop(): void };
+  model: { dispose(): Promise<void> };
+  db: { close(): void };
+  dbPath: string;
+  stopVersionChecker: () => void;
+  removeVersionFile: (dbPath: string) => void;
+}): (reason: string) => Promise<void> {
+  let inFlight: Promise<void> | undefined;
+  return (reason: string): Promise<void> => {
+    // Idempotent ACROSS awaits: a second call while the first teardown is
+    // still running returns the IN-FLIGHT promise, so an early
+    // process.exit(0) waits out the model disposal and the db close
+    // instead of cutting them (a fresh resolve() skipped them). `torn`
+    // tracking is subsumed: inFlight is set synchronously before any await.
+    if (inFlight) return inFlight;
+    void reason;
+    // Every step is isolated: a teardown step's own failure must not
+    // block the remaining ones (the sideband throwing on an
+    // already-unlinked socket used to skip the model disposal and the
+    // db close entirely).
+    try {
+      deps.sideband.stop();
+    } catch (err) {
+      console.error(`[thatch] MCP sideband stop failed: ${err}`);
+    }
+    try {
+      deps.stopVersionChecker();
+    } catch (err) {
+      console.error(`[thatch] MCP version-checker stop failed: ${err}`);
+    }
+    try {
+      deps.removeVersionFile(deps.dbPath);
+    } catch (err) {
+      console.error(`[thatch] MCP version-file removal failed: ${err}`);
+    }
+    inFlight = deps.model
+      .dispose()
+      .catch((err: unknown) => console.error(`[thatch] MCP model disposal failed: ${err}`))
+      .finally(() => {
+        try {
+          deps.db.close();
+        } catch (err) {
+          console.error(`[thatch] MCP db close failed: ${err}`);
+        }
+      });
+    return inFlight;
+  };
 }
 
 /**

package/src/opencode/tui-plugin.ts

@@ -0,0 +1,70 @@
+// The session-tab TUI CLI plugin: the TUI-side half of the session-tab
+// feature (docs/dev/features/session-tabs.md). Loaded by the opencode v2 TUI
+// from the package's ./tui entrypoint; runs once per TUI window, next to the
+// tab primitives it drives.
+//
+// The server-side adapter cannot reach the tab strip - the v2 plugin event
+// domain is subscribe-only and the HTTP surface has no publish route - so
+// the flow crosses processes over an rpc event: the adapter emits
+// rpc.thatch-tabs.tab-opened (sessionID + the coordinator instance's
+// directory), the SSE feed fans it to every window, and THIS plugin acts on
+// it with ui.tabs.open. The guard mirrors the built-in tui.* handlers
+// (packages/tui/src/app.tsx): an event only acts on the window whose
+// directory matches the event's location. ui.tabs.open is idempotent and
+// never steals focus, so no dedupe state is kept - a hot reload re-runs
+// setup from fresh state and double events are no-ops.
+//
+// ISOLATION: this module must only be imported by the TUI process - tests
+// import the pure filter/guard logic from src/session-tab-shared.ts, never
+// this file (the tui entrypoint imports solid-js, an uninstalled optional
+// peer).
+
+import { Plugin } from "@opencode/plugin/tui";
+import { isTabClosedEvent, isTabOpenedEvent, passesDirectoryGuard } from "../session-tab-shared";
+
+export default Plugin.define({
+  id: "jeffober-thatch-tui",
+  setup(context) {
+    const off = context.data.listen(({ details }) => {
+      const windowDirectory = context.location?.directory ?? context.data.location.default().directory;
+      if (!passesDirectoryGuard(details.location?.directory, windowDirectory)) return;
+      if (isTabClosedEvent(details.type)) {
+        // A tool-initiated close request: close the tab if THIS window has
+        // one for the session. Windows that never opened it (and windows at
+        // other directories, filtered above) return false - that is the
+        // correct no-op, not an error. The close is reopenable by the user
+        // (the strip's reopen stack), so this is tab-level, not session
+        // deletion.
+        const closeID = (details.data as { sessionID?: string }).sessionID;
+        if (!closeID) {
+          console.error("[thatch] tab-closed event without a sessionID");
+          return;
+        }
+        if (!context.ui.tabs.close(closeID)) {
+          console.error("[thatch] tab-close requested but no tab matched (or tabs are disabled)");
+        }
+        return;
+      }
+      if (!isTabOpenedEvent(details.type)) return;
+      const sessionID = (details.data as { sessionID?: string }).sessionID;
+      if (!sessionID) {
+        console.error("[thatch] tab-opened event without a sessionID");
+        return;
+      }
+      // Sync the session into the TUI's cache before opening: the strip
+      // renders the session's real title instead of the new-session
+      // fallback.
+      void context.data.session
+        .sync(sessionID)
+        .catch(() => {})
+        .then(() => {
+          if (!context.ui.tabs.open(sessionID)) {
+            console.error("[thatch] tab-open requested but session tabs are disabled in this window");
+          }
+        });
+    });
+    // The unsubscribe IS the cleanup: without it every plugin hot reload
+    // leaks another listener.
+    return off;
+  },
+});

package/src/opencode/v2.ts

@@ -2,11 +2,15 @@ import type { Plugin } from "@opencode/plugin";
 import { z } from "zod";
 import type { Tool } from "@opencode/schema/tool";
 import type { ToolContext as V2ToolContext } from "@opencode/plugin/promise/tool";
+import type { ThatchDB } from "../db";
 import type { HostCapabilities, PromptPart, ToastInput } from "../capabilities";
 import { createRuntime } from "../runtime";
 import { wrapUpCommandContent } from "../commands";
 import { deriveTitle } from "../extraction";
-import { TOOL_DEFS, trimHostContext, type HostToolContext } from "../tool-defs";
+import { detectRepo, detectWorktreeKind } from "../git";
+import { chatEnabled, loadConfig } from "../config";
+import { SESSION_TAB_RPC, TAB_CLOSED_EVENT, TAB_OPENED_EVENT, buildSubordinatePrompt, tabClosedEventType, tabOpenedEventType } from "../session-tab-shared";
+import { TOOL_DEFS, trimHostContext, type HostToolContext, type SessionTabCloseInput, type SessionTabHost, type SessionTabSpawnInput, type SessionTabSpawnResult } from "../tool-defs";
 
 // The opencode v2 adapter (opencode 2.x, plugin API @opencode/plugin 2.x).
 // Loaded only by v2 hosts - the dual entry (src/index.ts) lazy-imports this
@@ -39,6 +43,10 @@ import { TOOL_DEFS, trimHostContext, type HostToolContext } from "../tool-defs";
 //   {type, data, location?}. Filtered client-side the way the v1 host
 //   filters server-side: events resolve to a directory (their own, the
 //   session cache, or session.get) and drop when it is not ours.
+// - TUI reach: the ONLY server-to-TUI channel is the rpc event bridge - the
+//   session-tab rpc definition is registered at setup and its events reach
+//   the TUI CLI plugin (the package's ./tui entrypoint), which drives the
+//   tab strip (ui.tabs). Toast/command/exit pushes still have no surface.
 // - toasts, tui commands, session delete/list endpoints:
 //   no v2 surface reachable from a plugin - degrades as no-op/null.
 //   fetchStatuses returns {} because the wake gate treats an unknown session
@@ -77,7 +85,7 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   let inflightTools = 0;
 
   const capabilities = buildCapabilities(context, worktree, childSessions);
-  const runtime = await createRuntime({ capabilities, directory, worktree });
+  const runtime = await createRuntime({ capabilities, directory, worktree, v2Tools: true });
   // Seed the forwarding set from rehydrated child bookkeeping: after a
   // reload, an in-flight extraction child's maps come back from the journal,
   // but this NEW adapter instance's childSessions set starts empty - without
@@ -85,6 +93,37 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // (the below-root launch case).
   for (const id of runtime.childSessionIds()) childSessions.add(id);
 
+  // Session-tab surface: register the rpc definition once per activation and
+  // wire the host flow into the shared CoreContext (post-construction - the
+  // seam closes over both the runtime's db and the plugin context; see
+  // CoreContext.sessionTabHost in tool-defs.ts). The events are the ONLY
+  // server-to-TUI channel on v2: the TUI CLI plugin (the package's ./tui
+  // entrypoint) consumes them and calls ui.tabs.open. A TUI that is absent
+  // (headless run, still connecting) simply never acts on them.
+  //
+  // SDK-floor guard: the rpc surface is newer than some @opencode/plugin
+  // builds. An absent rpc domain must not crash setup - degrade by leaving
+  // the seam unwired; the session_tab tools refuse cleanly through it
+  // ("did not wire the session-tab surface") like any other unwired host.
+  const tabRegistration = typeof context.rpc?.register === "function"
+    ? await context.rpc.register(SESSION_TAB_RPC, {})
+    : undefined;
+  if (tabRegistration) {
+    const emitTabOpened = (data: { sessionID: string; directory: string }) =>
+      tabRegistration.events.emit(TAB_OPENED_EVENT, data);
+    runtime.coreContext.sessionTabHost = buildSessionTabHost({
+      context,
+      directory,
+      db: runtime.coreContext.db,
+      emitTabOpened,
+      emitTabClosed: (data: { sessionID: string; chatName: string | null }) =>
+        tabRegistration.events.emit(TAB_CLOSED_EVENT, data),
+      debug: runtime.debug,
+    });
+  } else {
+    console.error("[thatch] opencode v2 rpc surface unavailable - session_tab tools will report unwired");
+  }
+
   // Tool registration: the same CoreContext the v1 adapter feeds to
   // createTools, registered through the v2 ToolEditor instead.
   //
@@ -301,11 +340,44 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
             location?: { directory?: string };
           };
           const data = located.data ?? {};
-          if (data.sessionID && located.location?.directory) sessionDirs.set(data.sessionID, located.location.directory);
-          if (data.sessionID && data.location?.directory) sessionDirs.set(data.sessionID, data.location.directory);
+          // rpc events (the session-tab bridge) stamp the PUBLISHING
+          // instance's location, not the session's - caching a tab event's
+          // location would pin the subordinate's sessionID to the
+          // coordinator's directory, and its later location-less execution
+          // events would route to the wrong instance (or be dropped by the
+          // right one). The tab-opened payload's directory IS authoritative
+          // (the subordinate's final, post-move directory) and is cached
+          // explicitly below.
+          const fromRpc = located.type.startsWith("rpc.");
+          if (!fromRpc && data.sessionID && located.location?.directory) sessionDirs.set(data.sessionID, located.location.directory);
+          if (!fromRpc && data.sessionID && data.location?.directory) sessionDirs.set(data.sessionID, data.location.directory);
+          if (located.type === tabOpenedEventType) {
+            const opened = (data ?? {}) as { sessionID?: string; directory?: string };
+            if (opened.sessionID && opened.directory) sessionDirs.set(opened.sessionID, opened.directory);
+          }
           let eventDir = located.location?.directory ?? (data.sessionID ? sessionDirs.get(data.sessionID) : undefined);
           if (!eventDir && data.sessionID) eventDir = await resolveSessionDir(data.sessionID);
           runtime.debug("v2:pump", `event ${located.type} dir=${eventDir} self=${directory}`);
+          if (located.type === tabClosedEventType) {
+            // The session-tab tool's confirmed tab close: translated here
+            // rather than in translateEvent because the payload shape is
+            // tab-domain, and the death path is runtime-domain. Routed by
+            // the CLOSED session's own location, never the event's: the rpc
+            // event carries the publishing (coordinator) instance's
+            // directory, while the watchers and status bookkeeping live in
+            // the instance that owns the session (its post-move location).
+            // A later located event repairs the cache; resolve live when
+            // nothing is cached.
+            const closed = (data ?? {}) as { sessionID?: string; chatName?: string | null };
+            if (closed.sessionID) {
+              let closedDir = sessionDirs.get(closed.sessionID);
+              if (!closedDir) closedDir = await resolveSessionDir(closed.sessionID);
+              if (eventMatchesInstance(closedDir, closed.sessionID, directory, childSessions)) {
+                await runtime.onEvent({ type: "session.tab_closed", properties: { sessionID: closed.sessionID, chatName: closed.chatName ?? null } });
+              }
+            }
+            continue;
+          }
           if (eventMatchesInstance(eventDir, data.sessionID, directory, childSessions)) {
             for (const translated of translateEvent(located)) {
               await runtime.onEvent(translated);
@@ -346,6 +418,7 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
     registerPrompt.dispose();
     registerCompaction.dispose();
     registerCommands.dispose();
+    tabRegistration?.dispose();
     await runtime.dispose();
   };
 }
@@ -506,6 +579,126 @@ export function translateEvent(located: { type: string; data?: any }): { type: s
   }
 }
 
+/**
+ * The session-tab host flow - everything behind the CoreContext.sessionTabHost
+ * seam, host-executed end to end (the model supplies only the args; see the
+ * host-owned-handshake rule: no ids cross a prompt boundary). Order is
+ * load-bearing (docs/dev/features/session-tabs.md, "How it works"):
+ *
+ *   create -> move -> register subordinate -> emit tab-opened -> prompt
+ *
+ * (The calling session's chat name is resolved by the tool definition - it
+ * has the db handle and the session context.)
+ *
+ * The emit runs AFTER the move: the event routes by THIS instance's location
+ * (the coordinator's directory) regardless of the session's directory, so
+ * tab placement is identical either way, and a failed move leaves no
+ * stranded open tab. The move targets an idle session, so its default
+ * "steer" delivery applies immediately - the subordinate's whole first turn
+ * runs in its final directory.
+ *
+ * The subordinate is chat-registered deliberately - participant semantics,
+ * like an explicit chat_register; it is NEVER marked machinery, and its
+ * title cannot collide with the machinery title (validateTitle rejects it).
+ */
+function buildSessionTabHost(input: {
+  context: V2Context;
+  /** This instance's directory - the coordinator session's cwd. */
+  directory: string;
+  db: ThatchDB;
+  emitTabOpened: (data: { sessionID: string; directory: string }) => Promise<unknown>;
+  emitTabClosed: (data: { sessionID: string; chatName: string | null }) => Promise<unknown>;
+  debug(tag: string, message: string): void;
+}): SessionTabHost {
+  return {
+    directory: input.directory,
+    spawnSubordinate: async (spec: SessionTabSpawnInput): Promise<SessionTabSpawnResult> => {
+      const worktreeDir = typeof spec.worktree === "string" ? spec.worktree : undefined;
+      const isWorktreeFlow = worktreeDir !== undefined;
+      const createDirectory = isWorktreeFlow ? input.directory : spec.directory;
+      const finalDirectory = worktreeDir ?? spec.directory;
+      // Failure narration for the error below: a mid-flow throw (move
+      // refused, prompt endpoint down) must leave the calling model the
+      // session id and what already happened, or the created session is
+      // stranded with no way to name it - there is no session delete on
+      // the v2 surface, so rollback is not an option either.
+      const steps: string[] = [];
+      let sessionID: string | undefined;
+      let chatName: string | null = null;
+      try {
+        const created = await input.context.session.create({
+          title: spec.title,
+          metadata: {
+            thatch: {
+              coordinatedBy: spec.coordinatorChatName,
+              coordinatorSessionID: spec.coordinatorSessionID,
+              ...(worktreeDir !== undefined ? { worktree: worktreeDir } : {}),
+            },
+          },
+          location: { directory: createDirectory },
+        });
+        sessionID = created.id;
+        steps.push(`created session ${sessionID ?? "(no id returned)"}`);
+        if (worktreeDir !== undefined) {
+          await input.context.session.move({ sessionID, directory: worktreeDir });
+          steps.push(`moved to ${worktreeDir}`);
+        }
+        // Pre-register the subordinate AFTER the move, so the roster row
+        // records the session's FINAL directory (right repo slug, right
+        // worktree kind) and a failed move leaves no row behind. Deliberate
+        // participant semantics - like an explicit chat_register, never marked
+        // machinery - so the response carries its chat name and the
+        // coordinator's first chat_send resolves; the later auto-register
+        // converges (same id, same name). Gated on the chat-enabled config
+        // like every other registration path: with chat off, the tool
+        // response reports no chat name and advertises no supervision.
+        const repo = await detectRepo(finalDirectory);
+        const registered = chatEnabled(loadConfig().config)
+          ? input.db.registerChatSession(
+              sessionID,
+              repo,
+              null,
+              "opencode",
+              null,
+              detectWorktreeKind(finalDirectory),
+            )
+          : { ok: false as const, error: "chat disabled in config" };
+        if (registered.ok) chatName = registered.name;
+        steps.push(registered.ok ? `registered in chat as ${registered.name}` : "chat registration skipped");
+        input.debug(
+          "session-tab",
+          `created ${sessionID} dir=${finalDirectory} repo=${repo} chat=${registered.ok ? registered.name : registered.error}`,
+        );
+        // The payload's directory is the subordinate's FINAL (post-move)
+        // directory, not this instance's: the TUI guard routes by the event
+        // envelope's location, while the pump caches this field so the
+        // subordinate's later location-less execution events resolve to the
+        // instance that owns it.
+        await input.emitTabOpened({ sessionID, directory: finalDirectory });
+        steps.push("tab-opened emitted");
+        await input.context.session.prompt({
+          sessionID,
+          text: buildSubordinatePrompt(spec.coordinatorChatName, spec.prompt),
+        });
+        steps.push("task prompt delivered");
+        return { sessionID, chatName, directory: finalDirectory };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `session_tab spawn failed: ${reason}. Completed steps: ${steps.length > 0 ? steps.join("; ") : "none"}.` +
+            (sessionID
+              ? ` The session ${sessionID} was created and still exists - name it in your report so it can be recovered (sessions list, or thatch_session_tab_close${chatName ? ` by chat name ${chatName}` : ""}).`
+              : " No session was created."),
+        );
+      }
+    },
+    closeTab: async (spec: SessionTabCloseInput): Promise<void> => {
+      await input.emitTabClosed({ sessionID: spec.sessionID, chatName: spec.chatName });
+      input.debug("session-tab", `tab-close emitted for ${spec.sessionID} (${spec.chatName ?? "unnamed"})`);
+    },
+  };
+}
+
 // The HostCapabilities implementation over the v2 promise context. Every
 // operation the v2 surface lacks degrades as a no-op or null - the shared
 // runtime's callers treat those results as best-effort and log, never crash.

package/src/prediction.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { blobToVector, cosineSimilarity } from "./vector-math";
 import { ScoringEngine, type NudgeItem, PREDICTION_K, PREDICTION_P0, PREDICTION_W_SOFT } from "./scoring-engine";
 
 export { PREDICTION_K, PREDICTION_P0, PREDICTION_W_SOFT };
@@ -27,6 +28,17 @@ export interface PredictionRow {
 
 export interface PredictionNudgeItem extends NudgeItem {}
 
+/** A pair of predictions that are cosine-close enough to be wordings of the
+ *  same preference. Returned by findPredictionDuplicates for agent review. */
+export interface PredictionDedupCandidate {
+  store: string;
+  predictionA: string;
+  statementA: string;
+  predictionB: string;
+  statementB: string;
+  cosine: number;
+}
+
 export interface ScoredPrediction {
   matcher_id: string;
   matcher_description: string;
@@ -55,8 +67,13 @@ const config = {
  */
 export class PredictionEngine {
   #engine: ScoringEngine;
+  // Kept for the dedup pass, whose tables are prediction-only (the shared
+  // ScoringEngine stays unaware of them; the behavior engine has no pair
+  // verdicts yet).
+  #db: Database;
 
   constructor(db: Database) {
+    this.#db = db;
     this.#engine = new ScoringEngine(db, config);
   }
 
@@ -124,4 +141,77 @@ export class PredictionEngine {
   listPredictions(store: string) {
     return this.#engine.listItems(store);
   }
+
+  /**
+   * Corpus-level dedup: pairwise cosine over the store's predictions,
+   * skipping pairs already adjudicated in prediction_dedup_pairs. The
+   * cosine-only counterpart of the memory side's findDuplicates
+   * (src/db.ts) - the co-fire refinement in the compounds plan layers
+   * behavioral evidence on top of this same method later. Threshold 0.70
+   * because [0.85, 1] is already caught at write time
+   * (findNearestPrediction) and below 0.70 short-statement embeddings get
+   * too noisy to call duplicates.
+   */
+  findPredictionDuplicates(store: string, threshold = 0.70): PredictionDedupCandidate[] {
+    const rows = this.#db
+      .query(
+        "SELECT id, statement, embedding FROM predictions WHERE store = ? AND embedding IS NOT NULL ORDER BY id",
+      )
+      .all(store) as any[];
+
+    if (rows.length < 2) return [];
+
+    const preds = rows.map((r: any) => ({
+      id: r.id as string,
+      statement: r.statement as string,
+      embedding: blobToVector(r.embedding),
+    }));
+
+    const checked = this.#checkedPairs(store);
+    const candidates: PredictionDedupCandidate[] = [];
+    for (let i = 0; i < preds.length; i++) {
+      for (let j = i + 1; j < preds.length; j++) {
+        const key = [preds[i].id, preds[j].id].sort().join("|");
+        if (checked.has(key)) continue;
+        if (preds[i].embedding.length !== preds[j].embedding.length) continue;
+
+        const cosine = cosineSimilarity(preds[i].embedding, preds[j].embedding);
+        if (cosine >= threshold) {
+          candidates.push({
+            store,
+            predictionA: preds[i].id,
+            statementA: preds[i].statement,
+            predictionB: preds[j].id,
+            statementB: preds[j].statement,
+            cosine: Math.round(cosine * 1000) / 1000,
+          });
+        }
+      }
+    }
+
+    candidates.sort((a, b) => b.cosine - a.cosine);
+    return candidates;
+  }
+
+  /**
+   * Record a pair verdict (duplicate | distinct) so findPredictionDuplicates
+   * stops surfacing it. The id pair is stored in canonical sorted order -
+   * the same contract as dedup_pairs - so (A,B) and (B,A) are one row.
+   */
+  markPairChecked(store: string, idA: string, idB: string, status: string): void {
+    const [a, b] = [idA, idB].sort();
+    this.#db.run(
+      `INSERT INTO prediction_dedup_pairs (store, id_a, id_b, status, checked_at)
+       VALUES (?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+       ON CONFLICT (store, id_a, id_b) DO UPDATE SET status = excluded.status, checked_at = excluded.checked_at`,
+      [store, a, b, status],
+    );
+  }
+
+  #checkedPairs(store: string): Set<string> {
+    const rows = this.#db
+      .query("SELECT id_a, id_b FROM prediction_dedup_pairs WHERE store = ?")
+      .all(store) as any[];
+    return new Set(rows.map((r: any) => [r.id_a, r.id_b].sort().join("|")));
+  }
 }