@jeffober/thatch 0.1.30 → 0.1.32

package/bin/thatch

@@ -48,6 +48,20 @@ async function defaultStore(): Promise<string> {
   }
 }
 
+/**
+ * Emits the nudge output, prepending a version warning if present. The
+ * warning goes first so the LLM sees it before the nudge text. Used by
+ * flush-tools to surface version skew and update-available notices on
+ * every UserPromptSubmit, regardless of which tier fired.
+ */
+function emit(output: string, versionWarning: string | null, isJson: boolean): void {
+  if (versionWarning) {
+    output = `[thatch] ${versionWarning}\n\n${output}`;
+  }
+  if (isJson) console.log(JSON.stringify({ additional_context: output }));
+  else console.log(output);
+}
+
 /** Resolve the project directory from host-specific env vars or cwd. */
 function projectDir(): string {
   return process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
@@ -359,10 +373,22 @@ switch (command) {
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
       const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge, behaviorNudge } = await import("../src/prompts");
+      const { detectSkew, readNpmCacheForUpdate } = await import("../src/version-check");
 
       let repo = "unknown";
       try { repo = await detectRepo(); } catch {}
 
+      // Version checks (best-effort, no network, instant):
+      //   - Skew: the running MCP server's version file differs from this
+      //     binary's version. Means the user upgraded but didn't restart.
+      //   - Update: the npm cache file (written by the MCP server's
+      //     background poll) says a newer version is published.
+      // The warning is prepended to whatever nudge the tiers below produce.
+      // This is the primary delivery channel for version warnings because
+      // flush-tools fires on every prompt, including conversational turns
+      // with no tool calls.
+      const versionWarning = detectSkew(dbPath) ?? readNpmCacheForUpdate(dbPath);
+
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
       // If the agent ignores the nudge, the payload grows on the next flush.
@@ -373,8 +399,7 @@ switch (command) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
         const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
-        if (isJson) console.log(JSON.stringify({ additional_context: output }));
-        else console.log(output);
+        emit(output, versionWarning, isJson);
         break;
       }
 
@@ -408,16 +433,14 @@ switch (command) {
 
         if (parts.length > 0) {
           const output = parts.join("\n\n");
-          if (isJson) console.log(JSON.stringify({ additional_context: output }));
-          else console.log(output);
+          emit(output, versionWarning, isJson);
           break;
         }
       }
 
       // Tier 3: static write nudge.
       const output = claudeWriteNudge();
-      if (isJson) console.log(JSON.stringify({ additional_context: output }));
-      else console.log(output);
+      emit(output, versionWarning, isJson);
     } catch (err) {
       console.error(`[thatch flush-tools] failed: ${err}`);
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -13,12 +13,15 @@ import {
   extractionDirectPrompt,
   predictionNudge,
   behaviorNudge,
+  versionWarningNudge,
   type NudgeMatch,
 } from "./prompts";
 import { ExtractionPipeline, type ToolInteraction } from "./extraction";
 import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
+import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
+import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
 // V1 server export - tools, prompt injection, session hooks
@@ -65,6 +68,21 @@ export const server: Plugin = async ({ client, worktree }) => {
   // for the full mechanism.
   await seedDefaultBehaviors(db, model);
 
+  // Start background npm update polling. The checker caches the latest
+  // version in memory and to a file. Never blocks the plugin or tool calls.
+  // The opencode plugin path has no hook/server split, so version skew
+  // between hooks and server is not a concern here. But two opencode
+  // sessions on different versions sharing one DB can cause schema/data
+  // corruption. The npm update nudge covers the "please update" case.
+  // The on-disk version check (readOnDiskVersion) catches the case where
+  // the user ran `npm update` but hasn't restarted opencode yet.
+  startVersionChecker(dbPath);
+
+  // The running version, frozen at module load time. Compared against the
+  // on-disk package.json version on each chat.message to detect post-upgrade
+  // non-restart.
+  const runningVersion = pkg.version;
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -370,6 +388,34 @@ export const server: Plugin = async ({ client, worktree }) => {
         if (isCompactionMsg) return;
         compacting.delete(input.sessionID);
       }
+
+      // Version warning: check if the on-disk package.json version differs
+      // from the running version (user upgraded but didn't restart opencode),
+      // or if the npm poller found a newer version. Best-effort: any failure
+      // silently skips. Injected as a synthetic part so the LLM sees it and
+      // can tell the user to restart.
+      try {
+        const onDisk = readOnDiskVersion();
+        const checker = getVersionChecker();
+        const npmUpdate = checker?.getUpdateWarning() ?? null;
+        const skewWarning = onDisk && compareSemver(runningVersion, onDisk) < 0
+          ? `thatch was upgraded to v${onDisk} but this session is running v${runningVersion}. Restart opencode to apply the update.`
+          : null;
+        const warning = skewWarning ?? npmUpdate;
+        if (warning) {
+          output.parts.push({
+            id: `prt_thatch_ver_${Math.random().toString(36).slice(2)}`,
+            sessionID: input.sessionID,
+            messageID: input.messageID ?? output.message.id,
+            type: "text",
+            text: versionWarningNudge(warning),
+            synthetic: true,
+          });
+        }
+      } catch {
+        // Best-effort. Version check failure must not block nudges.
+      }
+
       // Extraction nudge (fallback path). Skipped when the extracting set
       // is active - that means a direct-extraction child session is running
       // and the plugin is handling extraction via the SDK. The nudge fires
@@ -678,6 +724,7 @@ export const server: Plugin = async ({ client, worktree }) => {
     },
 
     dispose: async () => {
+      stopVersionChecker();
       db.close();
     },
   };

package/src/mcp.ts

@@ -9,6 +9,7 @@ import { SidebandServer, sidebandSocketPath } from "./sideband";
 import { peekQueue, consumeQueue, resetMissedCount } from "./extract-queue";
 import { buildExtractionPayload } from "./extraction";
 import { seedDefaultBehaviors } from "./seed-behaviors";
+import { writeVersionFile, removeVersionFile, startVersionChecker, stopVersionChecker, getVersionChecker } from "./version-check";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -144,6 +145,19 @@ export async function runMcpServer(): Promise<void> {
     console.error(`[thatch] ${setupWarning}`);
   }
 
+  // Version warning: surfaced once on the first tools/call response. The
+  // primary delivery channel is flush-tools (fires on every prompt), so this
+  // is a backup. Combines npm update-available and version-skew warnings.
+  let versionWarning: string | null = null;
+  const checker = getVersionChecker();
+  if (checker) {
+    const updateMsg = checker.getUpdateWarning();
+    if (updateMsg) {
+      versionWarning = updateMsg;
+      console.error(`[thatch] ${updateMsg}`);
+    }
+  }
+
   // Auto-refresh: if setup was previously run (markers exist), re-run the
   // install functions to update skills, instructions, and hooks that may have
   // drifted since the last `thatch setup`. All operations are idempotent --
@@ -182,6 +196,16 @@ export async function runMcpServer(): Promise<void> {
     console.error(`[thatch] sideband socket failed: ${err}`);
   }
 
+  // Stamp the running version so hook processes (flush-tools) can detect
+  // version skew after an upgrade. The hook reads this file on every
+  // UserPromptSubmit and compares it to its own package.json version.
+  writeVersionFile(dbPath);
+
+  // Start background npm update polling. The checker caches the latest
+  // version to a file so hook processes can read it without making network
+  // requests. Never blocks tool calls.
+  startVersionChecker(dbPath);
+
   // Read stdin line by line. Each line is a complete JSON-RPC message.
   const decoder = new TextDecoder();
   let buf = "";
@@ -218,11 +242,25 @@ export async function runMcpServer(): Promise<void> {
         setupWarning = null;
       }
 
+      // Surface the version warning once per session on the first tools/call.
+      // The primary delivery channel is flush-tools (fires on every prompt),
+      // so this is a backup for when hooks are missing or fail. Cleared after
+      // one surfacing.
+      if (versionWarning && req.method === "tools/call" && !res.error) {
+        const content = res.result?.content;
+        if (Array.isArray(content) && content[0]?.text != null) {
+          content[0].text = `[thatch] ${versionWarning}\n\n${content[0].text}`;
+        }
+        versionWarning = null;
+      }
+
       send(res);
     }
   }
 
   sideband.stop();
+  stopVersionChecker();
+  removeVersionFile(dbPath);
   db.close();
 }
 

package/src/prompts.ts

@@ -458,6 +458,14 @@ export function claudeWriteNudge(): string {
   return `[thatch] After responding, check: did you learn new project knowledge, user preferences, or corrections worth persisting? If so, save to thatch.`;
 }
 
+/**
+ * Version warning for the opencode plugin's chat.message hook. Injected as a
+ * synthetic part so the LLM sees it and can tell the user to restart.
+ */
+export function versionWarningNudge(message: string): string {
+  return `[thatch] ${message} This is a system nudge, not user input. After informing the user, continue with their request.`;
+}
+
 /**
  * Extraction nudge with escalation. Both the opencode plugin (src/index.ts)
  * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with

package/src/version-check.ts

@@ -0,0 +1,340 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import pkg from "../package.json";
+
+/**
+ * Compares two semver strings (e.g. "0.1.30", "0.1.31"). Returns a negative
+ * number if a < b, positive if a > b, 0 if equal. Pre-release tags are not
+ * supported because @jeffober/thatch does not use them.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Version skew detection and npm update checking.
+ *
+ * Two complementary checks:
+ *
+ * Check A (npm): A long-running process (MCP server or opencode plugin) polls
+ * the npm registry hourly to see if a newer version of @jeffober/thatch is
+ * published. The result is cached in memory and written to a file so that
+ * one-shot hook processes (flush-tools) can read it without making network
+ * requests. The poll is async and never blocks tool calls. If npm is
+ * unreachable, the cache stays stale and the check is silently skipped.
+ *
+ * Check B (skew): The MCP server writes its running version to a file at
+ * startup. Hook processes (flush-tools) read that file and compare it to
+ * their own version from package.json. If they differ, the hooks were
+ * spawned from a newer binary than the long-running server process. This is
+ * the exact scenario from issue #6: the user upgraded thatch but did not
+ * restart the host, so the MCP server is frozen at the old version while
+ * hooks run the new code.
+ *
+ * Both checks share a file-based cache directory derived from the DB path
+ * (same hashing as the sideband socket) so all processes independently
+ * arrive at the same location without out-of-band coordination.
+ */
+
+const NPM_PACKAGE = "@jeffober/thatch";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE}/latest`;
+const POLL_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const REQUEST_TIMEOUT_MS = 5000;
+
+// ---------------------------------------------------------------------------
+// Cache directory (shared with sideband socket path derivation)
+// ---------------------------------------------------------------------------
+
+function cacheDir(dbPath: string): string {
+  const hash = createHash("sha256").update(dbPath).digest("hex").slice(0, 16);
+  return join(tmpdir(), `thatch-${hash}`);
+}
+
+/** Path to the file where the running MCP server stamps its version. */
+export function versionFilePath(dbPath: string): string {
+  return join(cacheDir(dbPath), "version");
+}
+
+/** Path to the file where the latest npm version is cached. */
+export function npmCachePath(dbPath: string): string {
+  return join(cacheDir(dbPath), "npm-latest");
+}
+
+// ---------------------------------------------------------------------------
+// Check B: version skew (local, instant, no network)
+// ---------------------------------------------------------------------------
+
+/**
+ * Writes the running process's version to the version file. Called once at
+ * MCP server or opencode plugin startup. The file is read by hook processes
+ * (flush-tools) to detect version skew.
+ */
+export function writeVersionFile(dbPath: string): void {
+  const path = versionFilePath(dbPath);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, pkg.version, "utf-8");
+  } catch {
+    // Best-effort. If the file can't be written, skew detection silently
+    // degrades: flush-tools will see no version file and skip the skew check.
+  }
+}
+
+/**
+ * Reads the running server's version from the version file. Returns null if
+ * the file doesn't exist (server never wrote it, or it was cleaned up).
+ */
+export function readVersionFile(dbPath: string): string | null {
+  try {
+    const path = versionFilePath(dbPath);
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf-8").trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Removes the version file. Called on MCP server shutdown so stale version
+ * files don't trigger false skew warnings for a different server instance.
+ */
+export function removeVersionFile(dbPath: string): void {
+  try {
+    unlinkSync(versionFilePath(dbPath));
+  } catch {
+    // Already gone, or never written. Fine either way.
+  }
+}
+
+/**
+ * Reads package.json from disk and returns the version string. Used by the
+ * opencode plugin to detect that the installed package was updated while the
+ * process is still running the old cached module. Returns null if the file
+ * can't be read.
+ */
+export function readOnDiskVersion(): string | null {
+  try {
+    // Resolve package.json relative to this source file: src/version-check.ts
+    // -> ../package.json (the repo root or the npm install directory).
+    const path = join(dirname(new URL(import.meta.url).pathname), "..", "package.json");
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    return parsed.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compares the on-disk version (what the running server stamped at startup)
+ * against the current binary's version (from package.json). Returns a human-
+ * readable skew warning if they differ, or null if they match or the file
+ * is absent.
+ */
+export function detectSkew(dbPath: string): string | null {
+  const serverVersion = readVersionFile(dbPath);
+  if (serverVersion === null) return null;
+  if (serverVersion === pkg.version) return null;
+  return `thatch was upgraded to v${pkg.version} but this session is running v${serverVersion}. ` +
+    `Restart your editor (Claude Code or Cursor) to apply the update.`;
+}
+
+// ---------------------------------------------------------------------------
+// Check A: npm update polling (network, cached, async)
+// ---------------------------------------------------------------------------
+
+interface NpmCacheEntry {
+  version: string;
+  checkedAt: number;
+}
+
+class NpmVersionChecker {
+  #dbPath: string;
+  #latestVersion: string | null = null;
+  #lastCheck: number = 0;
+  #polling: boolean = false;
+  #timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(dbPath: string) {
+    this.#dbPath = dbPath;
+    // Load cached result from file so a fresh MCP server startup benefits
+    // from the last poll a previous process did.
+    const cached = this.#readCacheFile();
+    if (cached) {
+      this.#latestVersion = cached.version;
+      this.#lastCheck = cached.checkedAt;
+    }
+  }
+
+  /**
+   * Starts background polling. The first poll fires after the poll interval
+   * has elapsed since the last check (or immediately if no cached result
+   * exists). Never blocks the caller.
+   */
+  start(): void {
+    if (this.#timer) return;
+    // Fire the first poll after a short delay so server startup is not
+    // impacted, and subsequent polls at the configured interval.
+    const initialDelay = this.#latestVersion ? POLL_INTERVAL_MS : 10_000;
+    this.#timer = setInterval(() => { void this.#poll(); }, POLL_INTERVAL_MS);
+    // Fire the first check after initialDelay. If we have a recent cache,
+    // we wait for the full interval before re-checking.
+    setTimeout(() => { void this.#poll(); }, initialDelay);
+  }
+
+  /** Stops background polling. */
+  stop(): void {
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+  }
+
+  /**
+   * Returns the latest version from npm if known, or null if the cache is
+   * empty. This is the fast path: no network, no I/O. The background poll
+   * keeps this value fresh.
+   */
+  getLatestVersion(): string | null {
+    return this.#latestVersion;
+  }
+
+  /**
+   * Returns true if the running version is older than the latest npm
+   * version. Returns false if the cache is empty (no data to compare).
+   */
+  isOutdated(): boolean {
+    if (!this.#latestVersion) return false;
+    return compareSemver(pkg.version, this.#latestVersion) < 0;
+  }
+
+  /**
+   * Returns a human-readable update-available warning, or null if no update
+   * is known or the running version is current.
+   */
+  getUpdateWarning(): string | null {
+    if (!this.isOutdated()) return null;
+    return `thatch v${this.#latestVersion} is available. ` +
+      `Run \`npm update ${NPM_PACKAGE}\` to update, then restart your editor.`;
+  }
+
+  /**
+   * Fetches the latest version from the npm registry. Best-effort: any
+   * network error, timeout, or parse failure is silently ignored. The
+   * cache is only updated on success.
+   */
+  async #poll(): Promise<void> {
+    if (this.#polling) return;
+    this.#polling = true;
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      const res = await fetch(NPM_REGISTRY_URL, { signal: controller.signal });
+      clearTimeout(timeout);
+      if (!res.ok) return;
+      const data = await res.json() as { version?: string };
+      if (!data.version) return;
+      this.#latestVersion = data.version;
+      this.#lastCheck = Date.now();
+      this.#writeCacheFile({ version: data.version, checkedAt: this.#lastCheck });
+    } catch {
+      // Network error, timeout, or parse failure. Leave the cache as-is.
+      // The next poll will retry.
+    } finally {
+      this.#polling = false;
+    }
+  }
+
+  #readCacheFile(): NpmCacheEntry | null {
+    try {
+      const path = npmCachePath(this.#dbPath);
+      if (!existsSync(path)) return null;
+      const raw = readFileSync(path, "utf-8");
+      const parsed = JSON.parse(raw) as NpmCacheEntry;
+      if (!parsed.version || !parsed.checkedAt) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  #writeCacheFile(entry: NpmCacheEntry): void {
+    try {
+      const path = npmCachePath(this.#dbPath);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(entry), "utf-8");
+    } catch {
+      // Best-effort. If the file can't be written, only in-memory cache
+      // is used. A different process won't benefit, but functionality
+      // is unaffected.
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory and standalone helpers for hook processes
+// ---------------------------------------------------------------------------
+
+let activeChecker: NpmVersionChecker | null = null;
+
+/**
+ * Creates and starts an NpmVersionChecker for the long-running process
+ * (MCP server or opencode plugin). Stores it in a module-level variable so
+ * the caller can retrieve update warnings without holding a reference.
+ * Call stopVersionChecker() on shutdown.
+ */
+export function startVersionChecker(dbPath: string): NpmVersionChecker {
+  if (activeChecker) return activeChecker;
+  activeChecker = new NpmVersionChecker(dbPath);
+  activeChecker.start();
+  return activeChecker;
+}
+
+/** Stops the active version checker and clears the module-level reference. */
+export function stopVersionChecker(): void {
+  if (activeChecker) {
+    activeChecker.stop();
+    activeChecker = null;
+  }
+}
+
+/** Returns the active version checker, or null if none was started. */
+export function getVersionChecker(): NpmVersionChecker | null {
+  return activeChecker;
+}
+
+/**
+ * Reads the npm cache file and returns an update warning if the cached
+ * latest version is newer than the running version. Used by one-shot hook
+ * processes (flush-tools) that don't have a long-running checker. Returns
+ * null if no cache file exists or the running version is current.
+ */
+export function readNpmCacheForUpdate(dbPath: string): string | null {
+  try {
+    const path = npmCachePath(dbPath);
+    if (!existsSync(path)) return null;
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as NpmCacheEntry;
+    if (!parsed.version) return null;
+    if (compareSemver(pkg.version, parsed.version) >= 0) return null;
+    return `thatch v${parsed.version} is available. ` +
+      `Run \`npm update ${NPM_PACKAGE}\` to update, then restart your editor.`;
+  } catch {
+    return null;
+  }
+}
+
+// For testing: reset module-level state.
+export function _resetForTesting(): void {
+  stopVersionChecker();
+}