@velvetmonkey/flywheel-memory 2.0.28 → 2.0.30

package/dist/index.js

@@ -476,7 +476,10 @@ async function readVaultFile(vaultPath2, notePath) {
     throw new Error("Invalid path: path traversal not allowed");
   }
   const fullPath = path18.join(vaultPath2, notePath);
-  const rawContent = await fs18.readFile(fullPath, "utf-8");
+  const [rawContent, stat3] = await Promise.all([
+    fs18.readFile(fullPath, "utf-8"),
+    fs18.stat(fullPath)
+  ]);
   const lineEnding = detectLineEnding(rawContent);
   const normalizedContent = normalizeLineEndings(rawContent);
   const parsed = matter5(normalizedContent);
@@ -485,7 +488,8 @@ async function readVaultFile(vaultPath2, notePath) {
     content: parsed.content,
     frontmatter,
     rawContent,
-    lineEnding
+    lineEnding,
+    mtimeMs: stat3.mtimeMs
   };
 }
 function deepCloneFrontmatter(obj) {
@@ -2481,7 +2485,8 @@ import {
 } from "@velvetmonkey/vault-core";
 var DEFAULT_CONFIG = {
   exclude_task_tags: [],
-  exclude_analysis_tags: []
+  exclude_analysis_tags: [],
+  exclude_entities: []
 };
 function loadConfig(stateDb2) {
   if (stateDb2) {
@@ -5894,36 +5899,38 @@ async function buildFTS5Index(vaultPath2) {
     if (!db2) {
       throw new Error("FTS5 database not initialized. Call setFTS5Database() first.");
     }
-    db2.exec("DELETE FROM notes_fts");
     const files = await scanVault(vaultPath2);
     const indexableFiles = files.filter((f) => shouldIndexFile2(f.path));
+    const rows = [];
+    for (const file of indexableFiles) {
+      try {
+        const stats = fs7.statSync(file.absolutePath);
+        if (stats.size > MAX_INDEX_FILE_SIZE) {
+          continue;
+        }
+        const raw = fs7.readFileSync(file.absolutePath, "utf-8");
+        const { frontmatter, body } = splitFrontmatter(raw);
+        const title = file.path.replace(/\.md$/, "").split("/").pop() || file.path;
+        rows.push([file.path, title, frontmatter, body]);
+      } catch (err) {
+        console.error(`[FTS5] Skipping ${file.path}:`, err);
+      }
+    }
     const insert = db2.prepare(
       "INSERT INTO notes_fts (path, title, frontmatter, content) VALUES (?, ?, ?, ?)"
     );
-    const insertMany = db2.transaction((filesToIndex) => {
-      let indexed2 = 0;
-      for (const file of filesToIndex) {
-        try {
-          const stats = fs7.statSync(file.absolutePath);
-          if (stats.size > MAX_INDEX_FILE_SIZE) {
-            continue;
-          }
-          const raw = fs7.readFileSync(file.absolutePath, "utf-8");
-          const { frontmatter, body } = splitFrontmatter(raw);
-          const title = file.path.replace(/\.md$/, "").split("/").pop() || file.path;
-          insert.run(file.path, title, frontmatter, body);
-          indexed2++;
-        } catch (err) {
-          console.error(`[FTS5] Skipping ${file.path}:`, err);
-        }
-      }
-      return indexed2;
-    });
-    const indexed = insertMany(indexableFiles);
     const now = /* @__PURE__ */ new Date();
-    db2.prepare(
-      "INSERT OR REPLACE INTO fts_metadata (key, value) VALUES (?, ?)"
-    ).run("last_built", now.toISOString());
+    const swapAll = db2.transaction(() => {
+      db2.exec("DELETE FROM notes_fts");
+      for (const row of rows) {
+        insert.run(...row);
+      }
+      db2.prepare(
+        "INSERT OR REPLACE INTO fts_metadata (key, value) VALUES (?, ?)"
+      ).run("last_built", now.toISOString());
+    });
+    swapAll();
+    const indexed = rows.length;
     state = {
       ready: true,
       building: false,
@@ -6183,6 +6190,9 @@ function setTaskCacheDatabase(database) {
 function isTaskCacheReady() {
   return cacheReady && db3 !== null;
 }
+function isTaskCacheBuilding() {
+  return rebuildInProgress;
+}
 async function buildTaskCache(vaultPath2, index, excludeTags) {
   if (!db3) {
     throw new Error("Task cache database not initialized. Call setTaskCacheDatabase() first.");
@@ -6191,53 +6201,47 @@ async function buildTaskCache(vaultPath2, index, excludeTags) {
   rebuildInProgress = true;
   const start = Date.now();
   try {
+    const notePaths = [];
+    for (const note of index.notes.values()) {
+      notePaths.push(note.path);
+    }
+    const allRows = [];
+    for (const notePath of notePaths) {
+      const absolutePath = path10.join(vaultPath2, notePath);
+      const tasks = await extractTasksFromNote(notePath, absolutePath);
+      for (const task of tasks) {
+        if (excludeTags?.length && excludeTags.some((t) => task.tags.includes(t))) {
+          continue;
+        }
+        allRows.push([
+          task.path,
+          task.line,
+          task.text,
+          task.status,
+          task.raw,
+          task.context ?? null,
+          task.tags.length > 0 ? JSON.stringify(task.tags) : null,
+          task.due_date ?? null
+        ]);
+      }
+    }
     const insertStmt = db3.prepare(`
       INSERT OR REPLACE INTO tasks (path, line, text, status, raw, context, tags_json, due_date)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `);
-    const insertAll = db3.transaction(() => {
+    const swapAll = db3.transaction(() => {
       db3.prepare("DELETE FROM tasks").run();
-      let count = 0;
-      const promises7 = [];
-      const notePaths2 = [];
-      for (const note of index.notes.values()) {
-        notePaths2.push(note.path);
+      for (const row of allRows) {
+        insertStmt.run(...row);
       }
-      return { notePaths: notePaths2, insertStmt };
+      db3.prepare(
+        "INSERT OR REPLACE INTO fts_metadata (key, value) VALUES (?, ?)"
+      ).run("task_cache_built", (/* @__PURE__ */ new Date()).toISOString());
     });
-    const { notePaths, insertStmt: stmt } = insertAll();
-    let totalTasks = 0;
-    for (const notePath of notePaths) {
-      const absolutePath = path10.join(vaultPath2, notePath);
-      const tasks = await extractTasksFromNote(notePath, absolutePath);
-      if (tasks.length > 0) {
-        const insertBatch = db3.transaction(() => {
-          for (const task of tasks) {
-            if (excludeTags?.length && excludeTags.some((t) => task.tags.includes(t))) {
-              continue;
-            }
-            stmt.run(
-              task.path,
-              task.line,
-              task.text,
-              task.status,
-              task.raw,
-              task.context ?? null,
-              task.tags.length > 0 ? JSON.stringify(task.tags) : null,
-              task.due_date ?? null
-            );
-            totalTasks++;
-          }
-        });
-        insertBatch();
-      }
-    }
-    db3.prepare(
-      "INSERT OR REPLACE INTO fts_metadata (key, value) VALUES (?, ?)"
-    ).run("task_cache_built", (/* @__PURE__ */ new Date()).toISOString());
+    swapAll();
     cacheReady = true;
     const duration = Date.now() - start;
-    serverLog("tasks", `Task cache built: ${totalTasks} tasks from ${notePaths.length} notes in ${duration}ms`);
+    serverLog("tasks", `Task cache built: ${allRows.length} tasks from ${notePaths.length} notes in ${duration}ms`);
   } finally {
     rebuildInProgress = false;
   }
@@ -6671,10 +6675,20 @@ async function getContext(vaultPath2, sourcePath, line, contextLines = 1) {
   try {
     const fullPath = path11.join(vaultPath2, sourcePath);
     const content = await fs9.promises.readFile(fullPath, "utf-8");
-    const lines = content.split("\n");
-    const startLine = Math.max(0, line - 1 - contextLines);
-    const endLine = Math.min(lines.length, line + contextLines);
-    return lines.slice(startLine, endLine).join("\n").trim();
+    const allLines = content.split("\n");
+    let fmLines = 0;
+    if (allLines[0]?.trimEnd() === "---") {
+      for (let i = 1; i < allLines.length; i++) {
+        if (allLines[i].trimEnd() === "---") {
+          fmLines = i + 1;
+          break;
+        }
+      }
+    }
+    const absLine = line + fmLines;
+    const startLine = Math.max(0, absLine - 1 - contextLines);
+    const endLine = Math.min(allLines.length, absLine + contextLines);
+    return allLines.slice(startLine, endLine).join("\n").trim();
   } catch {
     return "";
   }
@@ -7299,10 +7313,28 @@ function getActivitySummary(index, days) {
 import { SCHEMA_VERSION } from "@velvetmonkey/vault-core";
 
 // src/core/shared/indexActivity.ts
+function createStepTracker() {
+  const steps = [];
+  let current = null;
+  return {
+    steps,
+    start(name, input) {
+      current = { name, input, startTime: Date.now() };
+    },
+    end(output) {
+      if (!current) return;
+      steps.push({ name: current.name, duration_ms: Date.now() - current.startTime, input: current.input, output });
+      current = null;
+    },
+    skip(name, reason) {
+      steps.push({ name, duration_ms: 0, input: {}, output: {}, skipped: true, skip_reason: reason });
+    }
+  };
+}
 function recordIndexEvent(stateDb2, event) {
   stateDb2.db.prepare(
-    `INSERT INTO index_events (timestamp, trigger, duration_ms, success, note_count, files_changed, changed_paths, error)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+    `INSERT INTO index_events (timestamp, trigger, duration_ms, success, note_count, files_changed, changed_paths, error, steps)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
   ).run(
     Date.now(),
     event.trigger,
@@ -7311,7 +7343,8 @@ function recordIndexEvent(stateDb2, event) {
     event.note_count ?? null,
     event.files_changed ?? null,
     event.changed_paths ? JSON.stringify(event.changed_paths) : null,
-    event.error ?? null
+    event.error ?? null,
+    event.steps ? JSON.stringify(event.steps) : null
   );
 }
 function rowToEvent(row) {
@@ -7324,7 +7357,8 @@ function rowToEvent(row) {
     note_count: row.note_count,
     files_changed: row.files_changed,
     changed_paths: row.changed_paths ? JSON.parse(row.changed_paths) : null,
-    error: row.error
+    error: row.error,
+    steps: row.steps ? JSON.parse(row.steps) : null
   };
 }
 function getRecentIndexEvents(stateDb2, limit = 20) {
@@ -7402,6 +7436,7 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
     note_count: z3.coerce.number().describe("Number of notes in the index"),
     entity_count: z3.coerce.number().describe("Number of linkable entities (titles + aliases)"),
     tag_count: z3.coerce.number().describe("Number of unique tags"),
+    link_count: z3.coerce.number().describe("Total number of outgoing wikilinks"),
     periodic_notes: z3.array(PeriodicNoteInfoSchema).optional().describe("Detected periodic note conventions"),
     config: z3.record(z3.unknown()).optional().describe("Current flywheel config (paths, templates, etc.)"),
     last_rebuild: z3.object({
@@ -7410,11 +7445,27 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
       duration_ms: z3.number(),
       ago_seconds: z3.number()
     }).optional().describe("Most recent index rebuild event"),
+    last_pipeline: z3.object({
+      timestamp: z3.number(),
+      trigger: z3.string(),
+      duration_ms: z3.number(),
+      files_changed: z3.number().nullable(),
+      steps: z3.array(z3.object({
+        name: z3.string(),
+        duration_ms: z3.number(),
+        input: z3.record(z3.unknown()),
+        output: z3.record(z3.unknown()),
+        skipped: z3.boolean().optional(),
+        skip_reason: z3.string().optional()
+      }))
+    }).optional().describe("Most recent watcher pipeline run with per-step timing"),
     fts5_ready: z3.boolean().describe("Whether the FTS5 keyword search index is ready"),
     fts5_building: z3.boolean().describe("Whether the FTS5 keyword search index is currently building"),
     embeddings_building: z3.boolean().describe("Whether semantic embeddings are currently building"),
     embeddings_ready: z3.boolean().describe("Whether semantic embeddings have been built (enables hybrid keyword+semantic search)"),
     embeddings_count: z3.coerce.number().describe("Number of notes with semantic embeddings"),
+    tasks_ready: z3.boolean().describe("Whether the task cache is ready to serve queries"),
+    tasks_building: z3.boolean().describe("Whether the task cache is currently rebuilding"),
     recommendations: z3.array(z3.string()).describe("Suggested actions if any issues detected")
   };
   server2.registerTool(
@@ -7455,6 +7506,10 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
       const noteCount = indexBuilt ? index.notes.size : 0;
       const entityCount = indexBuilt ? index.entities.size : 0;
       const tagCount = indexBuilt ? index.tags.size : 0;
+      let linkCount = 0;
+      if (indexBuilt) {
+        for (const note of index.notes.values()) linkCount += note.outlinks.length;
+      }
       if (indexBuilt && noteCount === 0 && vaultAccessible) {
         recommendations.push("No notes found in vault. Is PROJECT_PATH pointing to a markdown vault?");
       }
@@ -7500,6 +7555,23 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         } catch {
         }
       }
+      let lastPipeline;
+      if (stateDb2) {
+        try {
+          const events = getRecentIndexEvents(stateDb2, 1);
+          if (events.length > 0 && events[0].steps && events[0].steps.length > 0) {
+            const evt = events[0];
+            lastPipeline = {
+              timestamp: evt.timestamp,
+              trigger: evt.trigger,
+              duration_ms: evt.duration_ms,
+              files_changed: evt.files_changed,
+              steps: evt.steps
+            };
+          }
+        } catch {
+        }
+      }
       const ftsState = getFTS5State();
       const output = {
         status,
@@ -7515,14 +7587,18 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         note_count: noteCount,
         entity_count: entityCount,
         tag_count: tagCount,
+        link_count: linkCount,
         periodic_notes: periodicNotes && periodicNotes.length > 0 ? periodicNotes : void 0,
         config: configInfo,
         last_rebuild: lastRebuild,
+        last_pipeline: lastPipeline,
         fts5_ready: ftsState.ready,
         fts5_building: ftsState.building,
         embeddings_building: isEmbeddingsBuilding(),
         embeddings_ready: hasEmbeddingsIndex(),
         embeddings_count: getEmbeddingsCount(),
+        tasks_ready: isTaskCacheReady(),
+        tasks_building: isTaskCacheBuilding(),
         recommendations
       };
       return {
@@ -7999,6 +8075,64 @@ import * as fs11 from "fs";
 import * as path12 from "path";
 import { z as z5 } from "zod";
 import { scanVaultEntities as scanVaultEntities2, getEntityIndexFromDb as getEntityIndexFromDb2 } from "@velvetmonkey/vault-core";
+
+// src/core/read/aliasSuggestions.ts
+function generateAliasCandidates(entityName, existingAliases) {
+  const existing = new Set(existingAliases.map((a) => a.toLowerCase()));
+  const candidates = [];
+  const words = entityName.split(/[\s-]+/).filter((w) => w.length > 0);
+  if (words.length >= 2) {
+    const acronym = words.map((w) => w[0]).join("").toUpperCase();
+    if (acronym.length >= 2 && acronym.length <= 6 && !existing.has(acronym.toLowerCase())) {
+      candidates.push({ candidate: acronym, type: "acronym" });
+    }
+    if (words.length >= 3) {
+      const short = words[0];
+      if (short.length >= 3 && !existing.has(short.toLowerCase())) {
+        candidates.push({ candidate: short, type: "short_form" });
+      }
+    }
+  }
+  return candidates;
+}
+function suggestEntityAliases(stateDb2, folder) {
+  const db4 = stateDb2.db;
+  const entities = folder ? db4.prepare(
+    "SELECT name, path, aliases_json FROM entities WHERE path LIKE ? || '/%'"
+  ).all(folder) : db4.prepare("SELECT name, path, aliases_json FROM entities").all();
+  const allEntityNames = new Set(
+    db4.prepare("SELECT name_lower FROM entities").all().map((r) => r.name_lower)
+  );
+  const suggestions = [];
+  const countStmt = db4.prepare(
+    "SELECT COUNT(*) as cnt FROM notes_fts WHERE content MATCH ?"
+  );
+  for (const row of entities) {
+    const aliases = row.aliases_json ? JSON.parse(row.aliases_json) : [];
+    const candidates = generateAliasCandidates(row.name, aliases);
+    for (const { candidate, type } of candidates) {
+      if (allEntityNames.has(candidate.toLowerCase())) continue;
+      let mentions = 0;
+      try {
+        const result = countStmt.get(`"${candidate}"`);
+        mentions = result?.cnt ?? 0;
+      } catch {
+      }
+      suggestions.push({
+        entity: row.name,
+        entity_path: row.path,
+        current_aliases: aliases,
+        candidate,
+        type,
+        mentions
+      });
+    }
+  }
+  suggestions.sort((a, b) => b.mentions - a.mentions || a.entity.localeCompare(b.entity));
+  return suggestions;
+}
+
+// src/tools/read/system.ts
 function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfig, getStateDb) {
   const RefreshIndexOutputSchema = {
     success: z5.boolean().describe("Whether the refresh succeeded"),
@@ -8485,6 +8619,35 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
       };
     }
   );
+  server2.registerTool(
+    "suggest_entity_aliases",
+    {
+      title: "Suggest Entity Aliases",
+      description: "Generate alias suggestions for entities in a folder based on acronyms and short forms, validated against vault content.",
+      inputSchema: {
+        folder: z5.string().optional().describe("Folder path to scope suggestions to"),
+        limit: z5.number().default(20).describe("Max suggestions to return")
+      }
+    },
+    async ({
+      folder,
+      limit: requestedLimit
+    }) => {
+      const stateDb2 = getStateDb?.();
+      if (!stateDb2) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available" }) }]
+        };
+      }
+      const suggestions = suggestEntityAliases(stateDb2, folder || void 0);
+      const limit = Math.min(requestedLimit ?? 20, 50);
+      const limited = suggestions.slice(0, limit);
+      const output = { suggestion_count: limited.length, suggestions: limited };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
 }
 
 // src/tools/read/primitives.ts
@@ -8799,6 +8962,8 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
           content: [{ type: "text", text: JSON.stringify({
             total_count: result2.total,
             open_count: result2.open_count,
+            completed_count: result2.completed_count,
+            cancelled_count: result2.cancelled_count,
             returned_count: result2.tasks.length,
             tasks: result2.tasks
           }, null, 2) }]
@@ -8831,6 +8996,8 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
         content: [{ type: "text", text: JSON.stringify({
           total_count: result.total,
           open_count: result.open_count,
+          completed_count: result.completed_count,
+          cancelled_count: result.cancelled_count,
           returned_count: paged.length,
           tasks: paged
         }, null, 2) }]
@@ -9686,6 +9853,35 @@ function isPeriodicNote(notePath) {
   const folder = notePath.split("/")[0]?.toLowerCase() || "";
   return patterns.some((p) => p.test(nameWithoutExt)) || periodicFolders.includes(folder);
 }
+function getExcludedPaths(index, config) {
+  const excluded = /* @__PURE__ */ new Set();
+  const excludeTags = new Set((config.exclude_analysis_tags ?? []).map((t) => t.toLowerCase()));
+  const excludeEntities = new Set((config.exclude_entities ?? []).map((e) => e.toLowerCase()));
+  if (excludeTags.size === 0 && excludeEntities.size === 0) return excluded;
+  for (const note of index.notes.values()) {
+    if (excludeTags.size > 0) {
+      const tags = note.frontmatter?.tags;
+      const tagList = Array.isArray(tags) ? tags : typeof tags === "string" ? [tags] : [];
+      if (tagList.some((t) => excludeTags.has(String(t).toLowerCase()))) {
+        excluded.add(note.path);
+        continue;
+      }
+    }
+    if (excludeEntities.size > 0) {
+      if (excludeEntities.has(note.title.toLowerCase())) {
+        excluded.add(note.path);
+        continue;
+      }
+      for (const alias of note.aliases) {
+        if (excludeEntities.has(alias.toLowerCase())) {
+          excluded.add(note.path);
+          break;
+        }
+      }
+    }
+  }
+  return excluded;
+}
 function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb, getConfig) {
   server2.registerTool(
     "graph_analysis",
@@ -9707,9 +9903,11 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
       requireIndex();
       const limit = Math.min(requestedLimit ?? 50, MAX_LIMIT);
       const index = getIndex();
+      const config = getConfig?.() ?? {};
+      const excludedPaths = getExcludedPaths(index, config);
       switch (analysis) {
         case "orphans": {
-          const allOrphans = findOrphanNotes(index, folder).filter((o) => !isPeriodicNote(o.path));
+          const allOrphans = findOrphanNotes(index, folder).filter((o) => !isPeriodicNote(o.path) && !excludedPaths.has(o.path));
           const orphans = allOrphans.slice(offset, offset + limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
@@ -9726,7 +9924,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
           };
         }
         case "dead_ends": {
-          const allResults = findDeadEnds(index, folder, min_backlinks);
+          const allResults = findDeadEnds(index, folder, min_backlinks).filter((n) => !excludedPaths.has(n.path));
           const result = allResults.slice(offset, offset + limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
@@ -9739,7 +9937,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
           };
         }
         case "sources": {
-          const allResults = findSources(index, folder, min_outlinks);
+          const allResults = findSources(index, folder, min_outlinks).filter((n) => !excludedPaths.has(n.path));
           const result = allResults.slice(offset, offset + limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
@@ -9752,17 +9950,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
           };
         }
         case "hubs": {
-          const excludeTags = new Set(
-            (getConfig?.()?.exclude_analysis_tags ?? []).map((t) => t.toLowerCase())
-          );
-          const allHubs = findHubNotes(index, min_links).filter((h) => {
-            if (excludeTags.size === 0) return true;
-            const note = index.notes.get(h.path);
-            if (!note) return true;
-            const tags = note.frontmatter?.tags;
-            const tagList = Array.isArray(tags) ? tags : typeof tags === "string" ? [tags] : [];
-            return !tagList.some((t) => excludeTags.has(String(t).toLowerCase()));
-          });
+          const allHubs = findHubNotes(index, min_links).filter((h) => !excludedPaths.has(h.path));
           const hubs = allHubs.slice(offset, offset + limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
@@ -9788,7 +9976,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
               }, null, 2) }]
             };
           }
-          const result = getStaleNotes(index, days, min_backlinks).slice(0, limit);
+          const result = getStaleNotes(index, days, min_backlinks).filter((n) => !excludedPaths.has(n.path)).slice(0, limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
               analysis: "stale",
@@ -9804,7 +9992,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
         case "immature": {
           const vaultPath2 = getVaultPath();
           const allNotes = Array.from(index.notes.values()).filter(
-            (note) => (!folder || note.path.startsWith(folder + "/") || note.path.substring(0, note.path.lastIndexOf("/")) === folder) && !isPeriodicNote(note.path)
+            (note) => (!folder || note.path.startsWith(folder + "/") || note.path.substring(0, note.path.lastIndexOf("/")) === folder) && !isPeriodicNote(note.path) && !excludedPaths.has(note.path)
           );
           const conventions = inferFolderConventions(index, folder, 0.5);
           const expectedFields = conventions.inferred_fields.map((f) => f.name);
@@ -9889,22 +10077,20 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb,
           }
           const daysBack = days ?? 30;
           let hubs = getEmergingHubs(db4, daysBack);
-          const excludeTags = new Set(
-            (getConfig?.()?.exclude_analysis_tags ?? []).map((t) => t.toLowerCase())
-          );
-          if (excludeTags.size > 0) {
+          if (excludedPaths.size > 0) {
             const notesByTitle = /* @__PURE__ */ new Map();
             for (const note of index.notes.values()) {
               notesByTitle.set(note.title.toLowerCase(), note);
             }
             hubs = hubs.filter((hub) => {
               const note = notesByTitle.get(hub.entity.toLowerCase());
-              if (!note) return true;
-              const tags = note.frontmatter?.tags;
-              const tagList = Array.isArray(tags) ? tags : typeof tags === "string" ? [tags] : [];
-              return !tagList.some((t) => excludeTags.has(String(t).toLowerCase()));
+              return !note || !excludedPaths.has(note.path);
             });
           }
+          const excludeEntities = new Set((config.exclude_entities ?? []).map((e) => e.toLowerCase()));
+          if (excludeEntities.size > 0) {
+            hubs = hubs.filter((hub) => !excludeEntities.has(hub.entity.toLowerCase()));
+          }
           return {
             content: [{ type: "text", text: JSON.stringify({
               analysis: "emerging_hubs",
@@ -11141,41 +11327,58 @@ async function withVaultFile(options, operation) {
     if (existsError) {
       return formatMcpResult(existsError);
     }
-    const { content, frontmatter, lineEnding } = await readVaultFile(vaultPath2, notePath);
-    const writeStateDb = getWriteStateDb();
-    if (writeStateDb) {
-      processImplicitFeedback(writeStateDb, notePath, content);
+    const runMutation = async () => {
+      const { content, frontmatter: frontmatter2, lineEnding: lineEnding2, mtimeMs } = await readVaultFile(vaultPath2, notePath);
+      const writeStateDb = getWriteStateDb();
+      if (writeStateDb) {
+        processImplicitFeedback(writeStateDb, notePath, content);
+      }
+      let sectionBoundary;
+      if (section) {
+        const sectionResult = ensureSectionExists(content, section, notePath);
+        if ("error" in sectionResult) {
+          return { error: sectionResult.error };
+        }
+        sectionBoundary = sectionResult.boundary;
+      }
+      const ctx = {
+        content,
+        frontmatter: frontmatter2,
+        lineEnding: lineEnding2,
+        sectionBoundary,
+        vaultPath: vaultPath2,
+        notePath
+      };
+      const opResult2 = await operation(ctx);
+      return { opResult: opResult2, frontmatter: frontmatter2, lineEnding: lineEnding2, mtimeMs };
+    };
+    let result = await runMutation();
+    if ("error" in result) {
+      return formatMcpResult(result.error);
     }
-    let sectionBoundary;
-    if (section) {
-      const sectionResult = ensureSectionExists(content, section, notePath);
-      if ("error" in sectionResult) {
-        return formatMcpResult(sectionResult.error);
+    const fullPath = path19.join(vaultPath2, notePath);
+    const statBefore = await fs19.stat(fullPath);
+    if (statBefore.mtimeMs !== result.mtimeMs) {
+      console.warn(`[withVaultFile] External modification detected on ${notePath}, re-reading and retrying`);
+      result = await runMutation();
+      if ("error" in result) {
+        return formatMcpResult(result.error);
       }
-      sectionBoundary = sectionResult.boundary;
     }
-    const ctx = {
-      content,
-      frontmatter,
-      lineEnding,
-      sectionBoundary,
-      vaultPath: vaultPath2,
-      notePath
-    };
-    const opResult = await operation(ctx);
+    const { opResult, frontmatter, lineEnding } = result;
     let finalFrontmatter = opResult.updatedFrontmatter ?? frontmatter;
     if (scoping && (scoping.agent_id || scoping.session_id)) {
       finalFrontmatter = injectMutationMetadata(finalFrontmatter, scoping);
     }
     await writeVaultFile(vaultPath2, notePath, opResult.updatedContent, finalFrontmatter, lineEnding);
     const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, commitPrefix);
-    const result = successResult(notePath, opResult.message, gitInfo, {
+    const successRes = successResult(notePath, opResult.message, gitInfo, {
       preview: opResult.preview,
       warnings: opResult.warnings,
       outputIssues: opResult.outputIssues,
       normalizationChanges: opResult.normalizationChanges
     });
-    return formatMcpResult(result);
+    return formatMcpResult(successRes);
   } catch (error) {
     const extras = {};
     if (error instanceof DiagnosticError) {
@@ -15664,6 +15867,7 @@ async function main() {
     setFTS5Database(stateDb.db);
     setEmbeddingsDatabase(stateDb.db);
     setTaskCacheDatabase(stateDb.db);
+    serverLog("statedb", "Injected FTS5, embeddings, task cache handles");
     loadEntityEmbeddingsToMemory();
     setWriteStateDb(stateDb);
   } catch (err) {
@@ -15712,7 +15916,8 @@ async function main() {
     vaultIndex = cachedIndex;
     setIndexState("ready");
     const duration = Date.now() - startTime;
-    serverLog("index", `Loaded from cache in ${duration}ms \u2014 ${cachedIndex.notes.size} notes`);
+    const cacheAge = cachedIndex.builtAt ? Math.round((Date.now() - cachedIndex.builtAt.getTime()) / 1e3) : 0;
+    serverLog("index", `Cache hit: ${cachedIndex.notes.size} notes, ${cacheAge}s old \u2014 loaded in ${duration}ms`);
     if (stateDb) {
       recordIndexEvent(stateDb, {
         trigger: "startup_cache",
@@ -15722,7 +15927,7 @@ async function main() {
     }
     runPostIndexWork(vaultIndex);
   } else {
-    serverLog("index", "Building vault index...");
+    serverLog("index", "Cache miss: building from scratch");
     try {
       vaultIndex = await buildVaultIndex(vaultPath);
       setIndexState("ready");
@@ -15793,9 +15998,13 @@ async function updateEntitiesInStateDb() {
   }
 }
 async function runPostIndexWork(index) {
+  const postStart = Date.now();
+  serverLog("index", "Scanning entities...");
   await updateEntitiesInStateDb();
   await initializeEntityIndex(vaultPath);
+  serverLog("index", "Entity index initialized");
   await exportHubScores(index, stateDb);
+  serverLog("index", "Hub scores exported");
   if (stateDb) {
     try {
       const metrics = computeMetrics(index, stateDb);
@@ -15820,6 +16029,7 @@ async function runPostIndexWork(index) {
   if (stateDb) {
     try {
       updateSuppressionList(stateDb);
+      serverLog("index", "Suppression list updated");
     } catch (err) {
       serverLog("server", `Failed to update suppression list: ${err instanceof Error ? err.message : err}`, "error");
     }
@@ -15830,9 +16040,15 @@ async function runPostIndexWork(index) {
     saveConfig(stateDb, inferred, existing);
   }
   flywheelConfig = loadConfig(stateDb);
+  const configKeys = Object.keys(flywheelConfig).filter((k) => flywheelConfig[k] != null);
+  serverLog("config", `Config inferred: ${configKeys.join(", ")}`);
   if (stateDb) {
-    refreshIfStale(vaultPath, index, flywheelConfig.exclude_task_tags);
-    serverLog("tasks", "Task cache ready");
+    if (isTaskCacheStale()) {
+      serverLog("tasks", "Task cache stale, rebuilding...");
+      refreshIfStale(vaultPath, index, flywheelConfig.exclude_task_tags);
+    } else {
+      serverLog("tasks", "Task cache fresh, skipping rebuild");
+    }
   }
   if (flywheelConfig.vault_name) {
     serverLog("config", `Vault: ${flywheelConfig.vault_name}`);
@@ -15878,36 +16094,47 @@ async function runPostIndexWork(index) {
         serverLog("watcher", `Processing ${batch.events.length} file changes`);
         const batchStart = Date.now();
         const changedPaths = batch.events.map((e) => e.path);
+        const tracker = createStepTracker();
         try {
+          tracker.start("index_rebuild", { files_changed: batch.events.length, changed_paths: changedPaths });
           vaultIndex = await buildVaultIndex(vaultPath);
           setIndexState("ready");
-          const duration = Date.now() - batchStart;
-          serverLog("watcher", `Index rebuilt in ${duration}ms`);
-          if (stateDb) {
-            recordIndexEvent(stateDb, {
-              trigger: "watcher",
-              duration_ms: duration,
-              note_count: vaultIndex.notes.size,
-              files_changed: batch.events.length,
-              changed_paths: changedPaths
-            });
-          }
+          tracker.end({ note_count: vaultIndex.notes.size, entity_count: vaultIndex.entities.size, tag_count: vaultIndex.tags.size });
+          serverLog("watcher", `Index rebuilt: ${vaultIndex.notes.size} notes, ${vaultIndex.entities.size} entities`);
+          tracker.start("entity_scan", { note_count: vaultIndex.notes.size });
           await updateEntitiesInStateDb();
-          await exportHubScores(vaultIndex, stateDb);
+          const entityCount = stateDb ? getAllEntitiesFromDb3(stateDb).length : 0;
+          tracker.end({ entity_count: entityCount });
+          serverLog("watcher", `Entity scan: ${entityCount} entities`);
+          tracker.start("hub_scores", { entity_count: entityCount });
+          const hubUpdated = await exportHubScores(vaultIndex, stateDb);
+          tracker.end({ updated: hubUpdated ?? 0 });
+          serverLog("watcher", `Hub scores: ${hubUpdated ?? 0} updated`);
           if (hasEmbeddingsIndex()) {
+            tracker.start("note_embeddings", { files: batch.events.length });
+            let embUpdated = 0;
+            let embRemoved = 0;
             for (const event of batch.events) {
               try {
                 if (event.type === "delete") {
                   removeEmbedding(event.path);
+                  embRemoved++;
                 } else if (event.path.endsWith(".md")) {
                   const absPath = path29.join(vaultPath, event.path);
                   await updateEmbedding(event.path, absPath);
+                  embUpdated++;
                 }
               } catch {
               }
             }
+            tracker.end({ updated: embUpdated, removed: embRemoved });
+            serverLog("watcher", `Note embeddings: ${embUpdated} updated, ${embRemoved} removed`);
+          } else {
+            tracker.skip("note_embeddings", "not built");
           }
           if (hasEntityEmbeddingsIndex() && stateDb) {
+            tracker.start("entity_embeddings", { files: batch.events.length });
+            let entEmbUpdated = 0;
             try {
               const allEntities = getAllEntitiesFromDb3(stateDb);
               for (const event of batch.events) {
@@ -15920,28 +16147,58 @@ async function runPostIndexWork(index) {
                     category: entity.category,
                     aliases: entity.aliases
                   }, vaultPath);
+                  entEmbUpdated++;
                 }
               }
             } catch {
             }
+            tracker.end({ updated: entEmbUpdated });
+            serverLog("watcher", `Entity embeddings: ${entEmbUpdated} updated`);
+          } else {
+            tracker.skip("entity_embeddings", !stateDb ? "no stateDb" : "not built");
           }
           if (stateDb) {
+            tracker.start("index_cache", { note_count: vaultIndex.notes.size });
             try {
               saveVaultIndexToCache(stateDb, vaultIndex);
+              tracker.end({ saved: true });
+              serverLog("watcher", "Index cache saved");
             } catch (err) {
+              tracker.end({ saved: false, error: err instanceof Error ? err.message : String(err) });
               serverLog("index", `Failed to update index cache: ${err instanceof Error ? err.message : err}`, "error");
             }
+          } else {
+            tracker.skip("index_cache", "no stateDb");
           }
+          tracker.start("task_cache", { files: batch.events.length });
+          let taskUpdated = 0;
+          let taskRemoved = 0;
           for (const event of batch.events) {
             try {
               if (event.type === "delete") {
                 removeTaskCacheForFile(event.path);
+                taskRemoved++;
               } else if (event.path.endsWith(".md")) {
                 await updateTaskCacheForFile(vaultPath, event.path);
+                taskUpdated++;
               }
             } catch {
             }
           }
+          tracker.end({ updated: taskUpdated, removed: taskRemoved });
+          serverLog("watcher", `Task cache: ${taskUpdated} updated, ${taskRemoved} removed`);
+          const duration = Date.now() - batchStart;
+          if (stateDb) {
+            recordIndexEvent(stateDb, {
+              trigger: "watcher",
+              duration_ms: duration,
+              note_count: vaultIndex.notes.size,
+              files_changed: batch.events.length,
+              changed_paths: changedPaths,
+              steps: tracker.steps
+            });
+          }
+          serverLog("watcher", `Batch complete: ${batch.events.length} files, ${duration}ms, ${tracker.steps.length} steps`);
         } catch (err) {
           setIndexState("error");
           setIndexError(err instanceof Error ? err : new Error(String(err)));
@@ -15953,7 +16210,8 @@ async function runPostIndexWork(index) {
               success: false,
               files_changed: batch.events.length,
               changed_paths: changedPaths,
-              error: err instanceof Error ? err.message : String(err)
+              error: err instanceof Error ? err.message : String(err),
+              steps: tracker.steps
             });
           }
           serverLog("watcher", `Failed to rebuild index: ${err instanceof Error ? err.message : err}`, "error");
@@ -15969,7 +16227,10 @@ async function runPostIndexWork(index) {
       }
     });
     watcher.start();
+    serverLog("watcher", "File watcher started");
   }
+  const postDuration = Date.now() - postStart;
+  serverLog("server", `Post-index work complete in ${postDuration}ms`);
 }
 if (process.argv.includes("--init-semantic")) {
   (async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.28",
+  "version": "2.0.30",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. 42 tools for search, backlinks, graph queries, mutations, and hybrid semantic search.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.28",
+    "@velvetmonkey/vault-core": "^2.0.30",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",