threadnote 0.3.1 → 0.3.2

package/README.md

@@ -68,6 +68,27 @@ threadnote start
 threadnote doctor --dry-run
 ```
 
+### Update
+
+Threadnote occasionally checks npm for a newer published version when you run human-facing commands such as `doctor`,
+`start`, `install`, or `repair`. The check is cached under `THREADNOTE_HOME` and never runs in CI or when
+`THREADNOTE_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` is set.
+
+Update the package and refresh local shims, user instructions, and MCP config with one command:
+
+```bash
+threadnote update
+```
+
+Check without changing anything:
+
+```bash
+threadnote update --check
+threadnote update --dry-run
+```
+
+After updating, restart Cursor, Codex, Claude, or open a fresh agent session so MCP tools reload.
+
 ### MCP
 
 Make the agents you use aware of Threadnote. Use only the MCP install lines for agents you actually use. Open a fresh
@@ -152,6 +173,8 @@ This is it! Start working with your agents as usual. The agent will automaticall
 - `doctor`: checks prerequisites, the generated command shim, manifest shape, templates, and local OpenViking health.
 - `install`: installs `openviking[local-embed]==0.3.12` if missing, creates `~/.openviking` config files if absent,
   writes the command shim, and upserts user-level agent instructions.
+- `update`: updates the published Threadnote package, then runs `repair` so shims and MCP config point at the new
+  version.
 - `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude/Cursor MCP configs from the
   current checkout.
 - `start`: starts `openviking-server` on `127.0.0.1:1933`.
@@ -215,6 +238,8 @@ Environment variables:
 - `THREADNOTE_USER`: OpenViking user value, default local username.
 - `THREADNOTE_AGENT_ID`: shared agent identity, default `threadnote`.
 - `THREADNOTE_OPENVIKING_VERSION`: package version to install, default `0.3.12`.
+- `THREADNOTE_NPM_REGISTRY`: npm registry used by the installer and updater, default `https://registry.npmjs.org/`.
+- `THREADNOTE_NO_UPDATE_CHECK`: disables opportunistic update notifications.
 - `THREADNOTE_BIN_DIR`: directory for the `threadnote` shim, default `~/.local/bin`.
 - `THREADNOTE_HOST`: local bind host, default `127.0.0.1`.
 - `THREADNOTE_PORT`: local bind port, default `1933`.

package/dist/mcp_server.cjs

@@ -30961,6 +30961,7 @@ var DEFAULT_AGENT_ID = "threadnote";
 
 // src/utils.ts
 var import_node_child_process = require("node:child_process");
+var import_node_crypto = require("node:crypto");
 function redactText(content) {
   return content.replace(
     /([A-Za-z0-9_.-]*(?:token|secret|password|api[_-]?key|authorization)[A-Za-z0-9_.-]*\s*[:=]\s*)("[^"]+"|'[^']+'|Bearer\s+[^'"\s]+|\S+)/gi,
@@ -31008,6 +31009,66 @@ async function runCommand(executable, args, options = {}) {
     });
   });
 }
+async function sleep(ms) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
+function sha256(content) {
+  return (0, import_node_crypto.createHash)("sha256").update(content).digest("hex");
+}
+function exactRecallTerms(query) {
+  const stopWords = /* @__PURE__ */ new Set([
+    "about",
+    "after",
+    "agent",
+    "anything",
+    "branch",
+    "case",
+    "current",
+    "find",
+    "handoff",
+    "issue",
+    "issues",
+    "latest",
+    "memory",
+    "memories",
+    "recall",
+    "related",
+    "search",
+    "the",
+    "this",
+    "with"
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const terms = [];
+  for (const match of query.matchAll(/[A-Za-z0-9_.-]{4,}/g)) {
+    const term = match[0];
+    const normalized = term.toLowerCase();
+    if (stopWords.has(normalized) || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    terms.push(term);
+  }
+  return terms.sort((left, right) => exactRecallTermScore(right) - exactRecallTermScore(left)).slice(0, 4);
+}
+function grepOutputHasMatches(output) {
+  return !output.includes("matches        []") && !output.includes('"matches":[]') && !output.includes("match_count    0");
+}
+function exactRecallTermScore(term) {
+  let score = term.length;
+  if (/[A-Z]/.test(term)) {
+    score += 8;
+  }
+  if (/[0-9_.-]/.test(term)) {
+    score += 6;
+  }
+  return score;
+}
+function safeTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
 function formatShellCommand(executable, args) {
   return redactText([executable, ...args].map(shellQuote).join(" "));
 }
@@ -31210,7 +31271,7 @@ function registerSearchTool(server, config2, name, description) {
       if (!checkedUri.ok) {
         return checkedUri.error;
       }
-      return runOpenVikingTool(config2, [
+      return runRecallTool(config2, [
         "search",
         checkedQuery.value,
         ...checkedUri.value ? ["--uri", checkedUri.value] : [],
@@ -31219,6 +31280,52 @@ function registerSearchTool(server, config2, name, description) {
     }
   );
 }
+async function runRecallTool(config2, args) {
+  const semanticResult = await runOpenVikingTool(config2, args);
+  if (semanticResult.isError === true) {
+    return semanticResult;
+  }
+  const query = args[1];
+  const exactMatches = typeof query === "string" ? await exactMemoryMatchesText(config2, query) : void 0;
+  if (!exactMatches) {
+    return semanticResult;
+  }
+  const [firstContent] = semanticResult.content;
+  if (firstContent?.type !== "text") {
+    return semanticResult;
+  }
+  return {
+    ...semanticResult,
+    content: [{ type: "text", text: `${firstContent.text}
+
+Exact durable memory matches:
+${exactMatches}` }]
+  };
+}
+async function exactMemoryMatchesText(config2, query) {
+  const terms = exactRecallTerms(query);
+  if (terms.length === 0) {
+    return void 0;
+  }
+  const ov = await requiredOpenVikingCli();
+  const scopes = [
+    `viking://user/${uriSegment(config2.user)}/memories`,
+    `viking://agent/${uriSegment(config2.agentId)}/memories`
+  ];
+  const outputs = [];
+  for (const term of terms) {
+    for (const scope of scopes) {
+      const result = await runCommand(ov, withIdentity(config2, ["grep", term, "--uri", scope, "--node-limit", "5"]), {
+        allowFailure: true
+      });
+      const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+      if (result.exitCode === 0 && grepOutputHasMatches(output)) {
+        outputs.push(output);
+      }
+    }
+  }
+  return outputs.length > 0 ? outputs.join("\n\n") : void 0;
+}
 function registerReadTool(server, config2, name, description) {
   server.registerTool(
     name,
@@ -31284,8 +31391,8 @@ function registerStoreTool(server, config2, name, description) {
       if (!checkedText.ok) {
         return checkedText.error;
       }
-      return runOpenVikingTool(config2, [
-        "add-memory",
+      return writeDurableMemory(
+        config2,
         [
           "MEMORY",
           `source_agent_client: ${sourceAgentClient ?? "mcp"}`,
@@ -31293,10 +31400,74 @@ function registerStoreTool(server, config2, name, description) {
           "",
           checkedText.value
         ].join("\n")
-      ]);
+      );
     }
   );
 }
+async function writeDurableMemory(config2, memory) {
+  try {
+    const ov = await requiredOpenVikingCli();
+    const directoryUri = durableMemoryDirectoryUri(config2);
+    const stat = await runCommand(ov, withIdentity(config2, ["stat", directoryUri]), { allowFailure: true });
+    if (stat.exitCode !== 0) {
+      await runCommand(
+        ov,
+        withIdentity(config2, [
+          "mkdir",
+          directoryUri,
+          "--description",
+          "Threadnote durable handoffs, memories, and cross-agent notes."
+        ])
+      );
+    }
+    const memoryUri = durableMemoryUri(config2, memory);
+    const result = await runOpenVikingWriteWithRetry(
+      ov,
+      config2,
+      memoryUri,
+      withIdentity(config2, ["write", memoryUri, "--content", memory, "--mode", "create", "--wait", "--timeout", "120"])
+    );
+    const text = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+    return { content: [{ type: "text", text: [`Stored durable memory: ${memoryUri}`, text].filter(Boolean).join("\n") }] };
+  } catch (err) {
+    return { content: [{ type: "text", text: errorMessage(err) }], isError: true };
+  }
+}
+async function runOpenVikingWriteWithRetry(ov, config2, memoryUri, args) {
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const result = await runCommand(ov, args, { allowFailure: true });
+    if (result.exitCode === 0) {
+      return result;
+    }
+    if (await vikingResourceExists(ov, config2, memoryUri)) {
+      await runCommand(ov, withIdentity(config2, ["wait", "--timeout", "120"]), { allowFailure: true });
+      return { exitCode: 0, stdout: "OpenViking accepted the memory and indexing wait completed.", stderr: "" };
+    }
+    if (!isResourceBusy(result.stderr, result.stdout) || attempt === 3) {
+      throw new Error(`${ov} ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
+    }
+    await sleep(1e3 * (attempt + 1));
+  }
+  throw new Error(`${ov} ${args.join(" ")} failed.`);
+}
+async function vikingResourceExists(ov, config2, uri) {
+  const stat = await runCommand(ov, withIdentity(config2, ["stat", uri]), { allowFailure: true });
+  return stat.exitCode === 0;
+}
+function isResourceBusy(stderr, stdout) {
+  return `${stderr}
+${stdout}`.includes("resource is busy");
+}
+function durableMemoryUri(config2, memory) {
+  return `${durableMemoryDirectoryUri(config2)}/threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+}
+function durableMemoryDirectoryUri(config2) {
+  return `viking://user/${uriSegment(config2.user)}/memories/events`;
+}
+function uriSegment(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized.length > 0 ? normalized : "unknown";
+}
 function requiredText(value, toolName, fieldName, example) {
   const normalized = value?.trim();
   if (normalized) {

package/dist/threadnote.cjs

@@ -3897,6 +3897,55 @@ function parentVikingUri(uri) {
 function sha256(content) {
   return (0, import_node_crypto.createHash)("sha256").update(content).digest("hex");
 }
+function exactRecallTerms(query) {
+  const stopWords = /* @__PURE__ */ new Set([
+    "about",
+    "after",
+    "agent",
+    "anything",
+    "branch",
+    "case",
+    "current",
+    "find",
+    "handoff",
+    "issue",
+    "issues",
+    "latest",
+    "memory",
+    "memories",
+    "recall",
+    "related",
+    "search",
+    "the",
+    "this",
+    "with"
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const terms = [];
+  for (const match of query.matchAll(/[A-Za-z0-9_.-]{4,}/g)) {
+    const term = match[0];
+    const normalized = term.toLowerCase();
+    if (stopWords.has(normalized) || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    terms.push(term);
+  }
+  return terms.sort((left, right) => exactRecallTermScore(right) - exactRecallTermScore(left)).slice(0, 4);
+}
+function grepOutputHasMatches(output) {
+  return !output.includes("matches        []") && !output.includes('"matches":[]') && !output.includes("match_count    0");
+}
+function exactRecallTermScore(term) {
+  let score = term.length;
+  if (/[A-Z]/.test(term)) {
+    score += 8;
+  }
+  if (/[0-9_.-]/.test(term)) {
+    score += 6;
+  }
+  return score;
+}
 function safeTimestamp() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
@@ -7010,6 +7059,7 @@ async function runRecall(config, options) {
     args.push("--node-limit", String(parsePositiveInteger(options.nodeLimit, "node limit")));
   }
   await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
+  await printExactMemoryMatches(config, ov, options.query, options.dryRun === true);
 }
 async function runRead(config, uri, options) {
   assertVikingUri(uri);
@@ -7082,18 +7132,141 @@ async function inferProjectFromQuery(config, normalizedQuery) {
     return void 0;
   }
 }
+async function printExactMemoryMatches(config, ov, query, dryRun) {
+  const terms = exactRecallTerms(query);
+  if (terms.length === 0) {
+    return;
+  }
+  const scopes = [
+    `viking://user/${uriSegment(config.user)}/memories`,
+    `viking://agent/${uriSegment(config.agentId)}/memories`
+  ];
+  const outputs = [];
+  for (const term of terms) {
+    for (const scope of scopes) {
+      const args = withIdentity(config, ["grep", term, "--uri", scope, "--node-limit", "5"]);
+      if (dryRun) {
+        outputs.push(formatShellCommand(ov, args));
+        continue;
+      }
+      const result = await runCommand(ov, args, { allowFailure: true });
+      const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+      if (result.exitCode === 0 && grepOutputHasMatches(output)) {
+        outputs.push(output);
+      }
+    }
+  }
+  if (outputs.length === 0) {
+    return;
+  }
+  console.log("\nExact durable memory matches:");
+  console.log(outputs.join("\n\n"));
+}
 async function storeMemory(config, memory, dryRun) {
   const ov = await openVikingCliForMode(dryRun);
   const memoryPath = (0, import_node_path4.join)(config.agentContextHome, "last-memory.txt");
+  const memoryUri = durableMemoryUri(config, memory);
   if (dryRun) {
     console.log(memory);
     console.log("\nWould run:");
-    console.log(formatShellCommand(ov, withIdentity(config, ["add-memory", memory])));
+    console.log(
+      formatShellCommand(
+        ov,
+        withIdentity(config, [
+          "write",
+          memoryUri,
+          "--from-file",
+          memoryPath,
+          "--mode",
+          "create",
+          "--wait",
+          "--timeout",
+          "120"
+        ])
+      )
+    );
     return;
   }
   await (0, import_promises4.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
   await (0, import_promises4.chmod)(memoryPath, 384);
-  await maybeRun(false, ov, withIdentity(config, ["add-memory", memory]));
+  await ensureDurableMemoryDirectory(ov, config);
+  await writeDurableMemoryFile(ov, config, memoryUri, memoryPath);
+  console.log(`Stored durable memory: ${memoryUri}`);
+}
+async function writeDurableMemoryFile(ov, config, memoryUri, memoryPath) {
+  const args = withIdentity(config, [
+    "write",
+    memoryUri,
+    "--from-file",
+    memoryPath,
+    "--mode",
+    "create",
+    "--wait",
+    "--timeout",
+    "120"
+  ]);
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    console.log(`${attempt === 0 ? "Running" : "Retrying"}: ${formatShellCommand(ov, args)}`);
+    const result = await runCommand(ov, args, { allowFailure: true });
+    if (result.exitCode === 0) {
+      if (result.stdout.trim()) {
+        console.log(result.stdout.trim());
+      }
+      if (result.stderr.trim()) {
+        console.error(result.stderr.trim());
+      }
+      return;
+    }
+    if (await vikingResourceExists(ov, config, memoryUri)) {
+      console.log("OpenViking accepted the memory but returned before the wait completed; waiting for indexing.");
+      await waitForOpenVikingQueue(ov, config);
+      return;
+    }
+    if (!isResourceBusy(result.stderr, result.stdout) || attempt === 3) {
+      throw new Error(`${formatShellCommand(ov, args)} failed: ${result.stderr || result.stdout}`);
+    }
+    await sleep(1e3 * (attempt + 1));
+  }
+}
+async function waitForOpenVikingQueue(ov, config) {
+  const result = await runCommand(ov, withIdentity(config, ["wait", "--timeout", "120"]), { allowFailure: true });
+  if (result.stdout.trim()) {
+    console.log(result.stdout.trim());
+  }
+  if (result.stderr.trim()) {
+    console.error(result.stderr.trim());
+  }
+}
+async function vikingResourceExists(ov, config, uri) {
+  const stat2 = await runCommand(ov, withIdentity(config, ["stat", uri]), { allowFailure: true });
+  return stat2.exitCode === 0;
+}
+async function ensureDurableMemoryDirectory(ov, config) {
+  const directoryUri = durableMemoryDirectoryUri(config);
+  const stat2 = await runCommand(ov, withIdentity(config, ["stat", directoryUri]), { allowFailure: true });
+  if (stat2.exitCode === 0) {
+    return;
+  }
+  await maybeRun(
+    false,
+    ov,
+    withIdentity(config, [
+      "mkdir",
+      directoryUri,
+      "--description",
+      "Threadnote durable handoffs, memories, and cross-agent notes."
+    ])
+  );
+}
+function durableMemoryUri(config, memory) {
+  return `${durableMemoryDirectoryUri(config)}/threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+}
+function durableMemoryDirectoryUri(config) {
+  return `viking://user/${uriSegment(config.user)}/memories/events`;
+}
+function isResourceBusy(stderr, stdout) {
+  return `${stderr}
+${stdout}`.includes("resource is busy");
 }
 async function buildHandoff(options) {
   const repoRoot = await gitValue(["rev-parse", "--show-toplevel"]) ?? getInvocationCwd();
@@ -8284,25 +8457,289 @@ function parsePackageManager(value) {
   throw new Error(`Invalid package manager: ${value}`);
 }
 
+// src/update.ts
+var import_node_fs4 = require("node:fs");
+var import_promises7 = require("node:fs/promises");
+var import_node_os5 = require("node:os");
+var import_node_path7 = require("node:path");
+var NPM_PACKAGE_NAME = "threadnote";
+var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+var UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
+function parseUpdateRuntime(value) {
+  if (value === "auto" || value === "npm" || value === "bun" || value === "deno") {
+    return value;
+  }
+  throw new Error(`Invalid update runtime: ${value}. Expected auto, npm, bun, or deno.`);
+}
+async function maybeNotifyUpdate(config, options = {}) {
+  if (isUpdateNotificationDisabled()) {
+    return;
+  }
+  try {
+    const info = await getUpdateInfo(config, {
+      allowCacheWrite: options.dryRun !== true,
+      preferFresh: false,
+      registry: updateRegistry()
+    });
+    if (!info.isUpdateAvailable) {
+      return;
+    }
+    console.log("");
+    console.log(`Update available: threadnote ${info.currentVersion} -> ${info.latestVersion}`);
+    console.log("Run: threadnote update");
+  } catch (_err) {
+    return;
+  }
+}
+async function runUpdate(config, options) {
+  const registry = normalizeRegistry(options.registry ?? updateRegistry());
+  const info = await getUpdateInfo(config, {
+    allowCacheWrite: options.dryRun !== true,
+    preferFresh: true,
+    registry
+  });
+  console.log(`Current version: ${info.currentVersion}`);
+  console.log(`Latest version:  ${info.latestVersion}`);
+  console.log(`Registry:        ${info.registry}`);
+  if (options.check === true) {
+    if (info.isUpdateAvailable) {
+      console.log(`Update available. Run: threadnote update`);
+    } else {
+      console.log(
+        compareVersions(info.currentVersion, info.latestVersion) > 0 ? "Current version is newer than npm latest." : "Threadnote is up to date."
+      );
+    }
+    return;
+  }
+  if (!info.isUpdateAvailable && options.force !== true) {
+    console.log("Threadnote is up to date.");
+    return;
+  }
+  const runtime = await resolveUpdateRuntime(options.runtime ?? "auto");
+  const updateCommand = updatePackageCommand(runtime, registry);
+  await maybeRun(options.dryRun === true, updateCommand.executable, updateCommand.args);
+  if (options.repair === false) {
+    console.log("Skipping repair because --no-repair was provided.");
+    return;
+  }
+  const threadnoteCommand = await installedThreadnoteCommand(runtime);
+  await maybeRun(options.dryRun === true, threadnoteCommand, ["repair"]);
+  console.log("Update complete. Restart Cursor, Codex, Claude, or open a fresh agent session so MCP tools reload.");
+}
+async function getUpdateInfo(config, options) {
+  const currentVersion = await currentPackageVersion();
+  const cached = options.preferFresh ? void 0 : await readFreshCache(config, options.registry);
+  const latestVersion = cached?.latestVersion ?? await fetchLatestVersion(options.registry);
+  if (!cached && options.allowCacheWrite) {
+    await writeUpdateCache(config, { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latestVersion, registry: options.registry });
+  }
+  return {
+    currentVersion,
+    isUpdateAvailable: compareVersions(currentVersion, latestVersion) < 0,
+    latestVersion,
+    registry: options.registry
+  };
+}
+async function currentPackageVersion() {
+  const rawPackage = await (0, import_promises7.readFile)((0, import_node_path7.join)(toolRoot(), "package.json"), "utf8");
+  const parsed = JSON.parse(rawPackage);
+  if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
+    throw new Error("Could not read current threadnote package version.");
+  }
+  return parsed.version;
+}
+async function fetchLatestVersion(registry) {
+  const url = new URL(`${NPM_PACKAGE_NAME}/latest`, normalizeRegistry(registry));
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, 2500);
+  try {
+    const response = await fetch(url, { headers: { accept: "application/json" }, signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`npm registry returned HTTP ${response.status}`);
+    }
+    const parsed = await response.json();
+    if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
+      throw new Error("npm registry response did not include a version.");
+    }
+    return parsed.version;
+  } catch (err) {
+    throw new Error(`Could not check npm for updates: ${errorMessage(err)}`, { cause: err });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function readFreshCache(config, registry) {
+  const rawCache = await readFileIfExists(updateCachePath(config));
+  if (!rawCache) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(rawCache);
+    if (!isJsonObject(parsed) || typeof parsed.checkedAt !== "string" || typeof parsed.latestVersion !== "string" || parsed.registry !== registry) {
+      return void 0;
+    }
+    const checkedAt = Date.parse(parsed.checkedAt);
+    if (!Number.isFinite(checkedAt) || Date.now() - checkedAt > UPDATE_CHECK_TTL_MS) {
+      return void 0;
+    }
+    return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion, registry };
+  } catch (_err) {
+    return void 0;
+  }
+}
+async function writeUpdateCache(config, cache) {
+  await ensureDirectory(config.agentContextHome, false);
+  await (0, import_promises7.writeFile)(updateCachePath(config), `${JSON.stringify(cache, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+}
+function updateCachePath(config) {
+  return (0, import_node_path7.join)(config.agentContextHome, "update-check.json");
+}
+async function resolveUpdateRuntime(runtime) {
+  if (runtime !== "auto") {
+    await requireRuntime(runtime);
+    return runtime;
+  }
+  for (const candidate of ["npm", "bun", "deno"]) {
+    if (await findExecutable([candidate])) {
+      return candidate;
+    }
+  }
+  throw new Error("Install Node/npm, Bun, or Deno to update threadnote.");
+}
+async function requireRuntime(runtime) {
+  if (!await findExecutable([runtime])) {
+    throw new Error(`${runtime} was requested but was not found on PATH.`);
+  }
+}
+async function installedThreadnoteCommand(runtime) {
+  const runtimeBin = await runtimeThreadnoteBin(runtime);
+  if (runtimeBin && await isExecutable(runtimeBin)) {
+    return runtimeBin;
+  }
+  return await findExecutable([NPM_PACKAGE_NAME]) ?? NPM_PACKAGE_NAME;
+}
+async function runtimeThreadnoteBin(runtime) {
+  if (runtime === "npm") {
+    const result = await runCommand("npm", ["prefix", "--global"], { allowFailure: true });
+    const prefix = result.stdout.trim();
+    return prefix ? (0, import_node_path7.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
+  }
+  if (runtime === "bun") {
+    const result = await runCommand("bun", ["pm", "bin", "-g"], { allowFailure: true });
+    const binDir = result.stdout.trim();
+    return binDir ? (0, import_node_path7.join)(binDir, NPM_PACKAGE_NAME) : void 0;
+  }
+  return (0, import_node_path7.join)(process.env.DENO_INSTALL ?? (0, import_node_path7.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
+}
+async function isExecutable(path) {
+  try {
+    await (0, import_promises7.access)(path, import_node_fs4.constants.X_OK);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+function updatePackageCommand(runtime, registry) {
+  if (runtime === "npm") {
+    return { executable: "npm", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
+  }
+  if (runtime === "bun") {
+    return { executable: "bun", args: ["install", "--global", `${NPM_PACKAGE_NAME}@latest`, `--registry=${registry}`] };
+  }
+  return {
+    executable: "env",
+    args: [
+      `NPM_CONFIG_REGISTRY=${registry}`,
+      "deno",
+      "install",
+      "--global",
+      "--force",
+      "--name",
+      NPM_PACKAGE_NAME,
+      "--allow-read",
+      "--allow-write",
+      "--allow-run",
+      "--allow-env",
+      "--allow-net",
+      `npm:${NPM_PACKAGE_NAME}@latest`
+    ]
+  };
+}
+function normalizeRegistry(registry) {
+  return registry.endsWith("/") ? registry : `${registry}/`;
+}
+function updateRegistry() {
+  return normalizeRegistry(process.env.THREADNOTE_NPM_REGISTRY ?? DEFAULT_NPM_REGISTRY);
+}
+function isUpdateNotificationDisabled() {
+  return process.env.CI !== void 0 || process.env.NO_UPDATE_NOTIFIER !== void 0 || process.env.THREADNOTE_NO_UPDATE_CHECK !== void 0;
+}
+function compareVersions(currentVersion, latestVersion) {
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = current.numbers[index] - latest.numbers[index];
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  if (current.prerelease === latest.prerelease) {
+    return 0;
+  }
+  if (current.prerelease === void 0) {
+    return 1;
+  }
+  if (latest.prerelease === void 0) {
+    return -1;
+  }
+  return current.prerelease.localeCompare(latest.prerelease);
+}
+function parseVersion(version) {
+  const normalized = version.trim().replace(/^v/, "");
+  const [core2, prerelease] = normalized.split("-", 2);
+  const parts = core2.split(".").map((part) => Number(part));
+  return {
+    numbers: [safeVersionNumber(parts[0]), safeVersionNumber(parts[1]), safeVersionNumber(parts[2])],
+    prerelease
+  };
+}
+function safeVersionNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
 // src/threadnote.ts
 async function main() {
   const program2 = new Command();
   program2.name("threadnote").description("Threadnote shared context workflow for development agents").showHelpAfterError().option("--home <path>", "Override THREADNOTE_HOME for this invocation").option("--manifest <path>", "Override THREADNOTE_MANIFEST for this invocation").option("--host <host>", "OpenViking host", DEFAULT_HOST).option("--port <port>", "OpenViking port", parsePort, DEFAULT_PORT);
   program2.command("doctor").description("Check local prerequisites, config files, manifest shape, and server health").option("--dry-run", "Show checks without writing anything").option("--strict", "Exit non-zero if any check fails").action(async (options) => {
-    await runDoctor(getRuntimeConfig(program2), options);
+    const config = getRuntimeConfig(program2);
+    await runDoctor(config, options);
+    await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
   program2.command("install").description("Install OpenViking, local config files, command shim, and user-level agent instructions").option("--dry-run", "Print the actions without making changes").option("--package-manager <manager>", "pipx, uv, or pip", parsePackageManager).action(async (options) => {
-    await runInstall(getRuntimeConfig(program2), options);
+    const config = getRuntimeConfig(program2);
+    await runInstall(config, options);
+    await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
+  });
+  program2.command("update").description("Update the published Threadnote package, then repair local shims and MCP config").option("--check", "Only check whether a newer version is available").option("--dry-run", "Print update and repair commands without running them").option("--force", "Run package-manager update even if this version is already current").option("--registry <url>", "npm registry URL", process.env.THREADNOTE_NPM_REGISTRY).option("--runtime <runtime>", "auto, npm, bun, or deno", parseUpdateRuntime, "auto").option("--no-repair", "Skip threadnote repair after updating the package").action(async (options) => {
+    await runUpdate(getRuntimeConfig(program2), options);
   });
   program2.command("repair").description("Repair local OpenViking install, config files, server health, shim, manifest, and MCP config").option("--dry-run", "Print the repair actions without making changes").option(
     "--mcp <clients>",
     "MCP clients to repair: available, all, none, codex, claude, cursor, or comma-separated list",
     "available"
   ).option("--no-start", "Do not start OpenViking if health is failing").option("--package-manager <manager>", "pipx, uv, or pip", parsePackageManager).action(async (options) => {
-    await runRepair(getRuntimeConfig(program2), options);
+    const config = getRuntimeConfig(program2);
+    await runRepair(config, options);
+    await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
   program2.command("start").description("Start the local OpenViking server").option("--dry-run", "Print the start command without running it").option("--foreground", "Run in the foreground instead of detaching").option("--launchd", "Install and start a macOS LaunchAgent").action(async (options) => {
-    await runStart(getRuntimeConfig(program2), options);
+    const config = getRuntimeConfig(program2);
+    await runStart(config, options);
+    await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
   program2.command("stop").description("Stop the local OpenViking server or LaunchAgent").option("--dry-run", "Print the stop actions without running them").action(async (options) => {
     await runStop(getRuntimeConfig(program2), options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",