@takara-ai/miru-code 1.1.0 → 1.1.2

package/README.md

@@ -10,7 +10,7 @@ Find code by meaning, not grep. Miru returns the best **chunks** (path, lines, s
 
 Miru sends **file contents** to the [Takara inference API](https://takara.ai) when building an index and when embedding search queries. Chunks from your repo are transmitted over HTTPS to generate embeddings. API usage may incur cost depending on your Takara plan.
 
-If you index proprietary code, make sure that sending snippets to Takara's endpoint fits your security and compliance requirements. Use `MIRU_WORKSPACE_ROOT` to restrict MCP indexing to a single workspace directory.
+If you index proprietary code, make sure that sending snippets to Takara's endpoint fits your security and compliance requirements. `MIRU_WORKSPACE_ROOT` is an opt-in boundary for MCP local `repo` paths only, and restricts indexing to a single workspace directory when set.
 
 ## Install
 
@@ -231,7 +231,7 @@ const results = await index.search({ query: "BM25 tokenize", topK: 10 });
 | `TAKARA_API_KEY` | Required |
 | `MIRU_OPENAI_BASE_URL` | Default `https://infer.takara.ai/v1` |
 | `MIRU_OPENAI_EMBEDDING_MODEL` | Default `ds1-miru-int8` |
-| `MIRU_WORKSPACE_ROOT` | Restrict MCP local `repo` paths to this directory |
+| `MIRU_WORKSPACE_ROOT` | Optional: restrict MCP local `repo` paths to this directory |
 | `MIRU_MAX_INDEX_FILES` | Cap files indexed per operation |
 | `MIRU_ALLOW_HTTP_GIT` | Set `1` to allow plain `http://` git clones |
 | `MIRU_MCP_WATCH` | Set `0` to disable MCP file watch |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/installer/config.ts

@@ -107,13 +107,13 @@ export async function mergeJsonMember(
   if (JSON.stringify(section[memberKey]) === JSON.stringify(value)) {
     return "unchanged";
   }
-
-  section[memberKey] = value;
-  parsed[sectionKey] = section;
-
-  const next = `${JSON.stringify(parsed, null, 2)}\n`;
-
-  await Bun.write(path, next);
+  const next = upsertJsonMemberText(text, sectionKey, memberKey, value);
+  await Bun.write(
+    path,
+    ensureTrailingNewline(
+      next ?? JSON.stringify(withMergedMember(parsed, sectionKey, memberKey, value), null, 2),
+    ),
+  );
   return existed ? "updated" : "created";
 }
 
@@ -136,26 +136,276 @@ export async function removeJsonMember(
   if (section === "error" || !(memberKey in section)) {
     return "not-found";
   }
+  const nextText = removeJsonMemberText(text, sectionKey, memberKey);
+  const nextObject = withRemovedMember(parsed, sectionKey, memberKey);
+  const next = nextText ?? JSON.stringify(nextObject, null, 2);
+  if (ensureTrailingNewline(next) === ensureTrailingNewline(text)) {
+    return "not-found";
+  }
+  const nextParsed = parseJsonObject(next);
+  if (!nextParsed || typeof nextParsed !== "object" || Object.keys(nextParsed).length === 0) {
+    await unlink(path);
+    return "removed";
+  }
+  await Bun.write(path, ensureTrailingNewline(next));
+  return "removed";
+}
+
+function withMergedMember(
+  root: Record<string, unknown>,
+  sectionKey: string,
+  memberKey: string,
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...root };
+  const section =
+    next[sectionKey] && typeof next[sectionKey] === "object" && !Array.isArray(next[sectionKey])
+      ? { ...(next[sectionKey] as Record<string, unknown>) }
+      : {};
+  section[memberKey] = value;
+  next[sectionKey] = section;
+  return next;
+}
 
+function withRemovedMember(
+  root: Record<string, unknown>,
+  sectionKey: string,
+  memberKey: string,
+): Record<string, unknown> {
+  const next = { ...root };
+  const section =
+    next[sectionKey] && typeof next[sectionKey] === "object" && !Array.isArray(next[sectionKey])
+      ? { ...(next[sectionKey] as Record<string, unknown>) }
+      : null;
+  if (!section || !(memberKey in section)) {
+    return next;
+  }
   delete section[memberKey];
   if (Object.keys(section).length === 0) {
-    delete parsed[sectionKey];
+    delete next[sectionKey];
   } else {
-    parsed[sectionKey] = section;
+    next[sectionKey] = section;
   }
+  return next;
+}
 
-  const next = `${JSON.stringify(parsed, null, 2)}\n`;
-  if (next === `${text.endsWith("\n") ? text : `${text}\n`}`) {
-    return "not-found";
+function upsertJsonMemberText(
+  text: string,
+  sectionKey: string,
+  memberKey: string,
+  value: Record<string, unknown>,
+): string | null {
+  if (!hasJsoncSyntax(text)) {
+    return null;
+  }
+  const sectionRange = findSectionRange(text, sectionKey);
+  if (!sectionRange) {
+    return null;
+  }
+  const { openBrace, closeBrace, indent } = sectionRange;
+  const sectionBody = text.slice(openBrace + 1, closeBrace);
+  const memberMatch = new RegExp(`"(${escapeRegExp(memberKey)})"\\s*:`).exec(sectionBody);
+  const valueText = JSON.stringify(value);
+  if (memberMatch) {
+    const memberKeyStart = openBrace + 1 + memberMatch.index;
+    const colonIndex = text.indexOf(":", memberKeyStart);
+    const valueStart = skipWhitespace(text, colonIndex + 1);
+    const valueEnd = parseJsonValueEnd(text, valueStart);
+    if (valueEnd <= valueStart) {
+      return null;
+    }
+    return `${text.slice(0, valueStart)} ${valueText}${text.slice(valueEnd)}`;
   }
 
-  if (Object.keys(parsed).length === 0) {
-    await unlink(path);
-    return "removed";
+  const memberIndent = `${indent}  `;
+  const insertion = `${sectionBody.trim().length === 0 ? "" : ","}\n${memberIndent}"${memberKey}": ${valueText}\n${indent}`;
+  return `${text.slice(0, closeBrace)}${insertion}${text.slice(closeBrace)}`;
+}
+
+function removeJsonMemberText(text: string, sectionKey: string, memberKey: string): string | null {
+  if (!hasJsoncSyntax(text)) {
+    return null;
+  }
+  const sectionRange = findSectionRange(text, sectionKey);
+  if (!sectionRange) {
+    return null;
   }
+  const { openBrace, closeBrace } = sectionRange;
+  const sectionBody = text.slice(openBrace + 1, closeBrace);
+  const memberMatch = new RegExp(`"(${escapeRegExp(memberKey)})"\\s*:`).exec(sectionBody);
+  if (!memberMatch) {
+    return null;
+  }
+  const memberStart = openBrace + 1 + memberMatch.index;
+  const colonIndex = text.indexOf(":", memberStart);
+  const valueStart = skipWhitespace(text, colonIndex + 1);
+  const valueEnd = parseJsonValueEnd(text, valueStart);
+  let removeStart = memberStart;
+  let removeEnd = valueEnd;
+
+  const trailing = skipWhitespace(text, valueEnd);
+  if (text[trailing] === ",") {
+    removeEnd = trailing + 1;
+  } else {
+    const leadingComma = findLeadingComma(text, memberStart, openBrace + 1);
+    if (leadingComma >= 0) {
+      removeStart = leadingComma;
+    }
+  }
+  return `${text.slice(0, removeStart)}${text.slice(removeEnd)}`;
+}
 
-  await Bun.write(path, next);
-  return "removed";
+function hasJsoncSyntax(text: string): boolean {
+  return text.includes("//") || text.includes("/*");
+}
+
+function findSectionRange(
+  text: string,
+  sectionKey: string,
+): { openBrace: number; closeBrace: number; indent: string } | null {
+  const keyMatch = new RegExp(`(^|\\n)([ \\t]*)"${escapeRegExp(sectionKey)}"\\s*:\\s*\\{`).exec(
+    text,
+  );
+  if (!keyMatch) {
+    return null;
+  }
+  const openBrace = text.indexOf("{", keyMatch.index);
+  const closeBrace = findMatchingBrace(text, openBrace);
+  if (openBrace < 0 || closeBrace < 0) {
+    return null;
+  }
+  return { openBrace, closeBrace, indent: keyMatch[2] ?? "" };
+}
+
+function findMatchingBrace(text: string, openIndex: number): number {
+  let depth = 0;
+  let inString = false;
+  let quote = "";
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let i = openIndex; i < text.length; i++) {
+    const ch = text[i] ?? "";
+    const next = text[i + 1] ?? "";
+    if (inLineComment) {
+      if (ch === "\n") inLineComment = false;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === "*" && next === "/") {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === quote) {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      inLineComment = true;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      continue;
+    }
+    if (ch === "{") depth++;
+    if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function parseJsonValueEnd(text: string, start: number): number {
+  const first = text[start];
+  if (!first) return start;
+  if (first === "{") return findMatchingBrace(text, start) + 1;
+  if (first === "[") return findMatchingBracket(text, start) + 1;
+  if (first === '"' || first === "'") return findStringEnd(text, start) + 1;
+  let i = start;
+  while (i < text.length && ![",", "}", "]", "\n"].includes(text[i] ?? "")) {
+    i++;
+  }
+  return i;
+}
+
+function findMatchingBracket(text: string, openIndex: number): number {
+  let depth = 0;
+  let inString = false;
+  let quote = "";
+  for (let i = openIndex; i < text.length; i++) {
+    const ch = text[i] ?? "";
+    if (inString) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === quote) inString = false;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      continue;
+    }
+    if (ch === "[") depth++;
+    if (ch === "]") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function findStringEnd(text: string, start: number): number {
+  const quote = text[start] ?? '"';
+  for (let i = start + 1; i < text.length; i++) {
+    const ch = text[i] ?? "";
+    if (ch === "\\") {
+      i++;
+      continue;
+    }
+    if (ch === quote) return i;
+  }
+  return start;
+}
+
+function skipWhitespace(text: string, index: number): number {
+  let i = index;
+  while (i < text.length && /\s/.test(text[i] ?? "")) i++;
+  return i;
+}
+
+function findLeadingComma(text: string, index: number, min: number): number {
+  for (let i = index - 1; i >= min; i--) {
+    const ch = text[i] ?? "";
+    if (ch === ",") return i;
+    if (!/\s/.test(ch)) break;
+  }
+  return -1;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function ensureTrailingNewline(text: string): string {
+  return text.endsWith("\n") ? text : `${text}\n`;
 }
 
 export async function replaceOrAppendMarked(path: string, content: string): Promise<InstallAction> {

package/src/installer/hooks/install.ts

@@ -5,6 +5,8 @@ import { stripJsonComments } from "../config.ts";
 
 const HOOK_GUARD_MARKER = "hook-guard";
 const MIRU_HOOK_MARKER = "miru-search";
+const VSCODE_OWNERS_KEY = "miruOwners";
+const SHARED_VSCODE_HOOK_OWNERS = ["copilot", "vscode", "visualstudio"] as const;
 
 const MATCHERS = {
   cursor: "Grep|Glob|Shell|SemanticSearch",
@@ -304,37 +306,127 @@ export async function removeGeminiHooks(path: string): Promise<InstallAction> {
   return removeHooksSection(path, ["BeforeTool"], (entry) => hookCommandMatches(entry.command));
 }
 
-export async function mergeVscodeHooks(path: string): Promise<InstallAction> {
+export async function mergeVscodeHooks(path: string, owner?: string): Promise<InstallAction> {
   const command = resolveHookCommand();
-  const content = {
-    hooks: {
-      PreToolUse: [
-        {
-          type: "command",
-          command,
-          matcher: MATCHERS.claude,
-          statusMessage: "Miru search policy",
-        },
-      ],
-    },
-  };
   const existed = await Bun.file(path).exists();
-  if (existed) {
-    const current = await Bun.file(path).text();
-    const next = `${JSON.stringify(content, null, 2)}\n`;
-    if (current === next) {
-      return "unchanged";
-    }
+  const text = existed ? await Bun.file(path).text() : "";
+  const parsed = parseJsonObject(text);
+  if (parsed === "error") {
+    return "error";
   }
-  await Bun.write(path, `${JSON.stringify(content, null, 2)}\n`);
+
+  const hooksRoot =
+    parsed.hooks && typeof parsed.hooks === "object" && !Array.isArray(parsed.hooks)
+      ? (parsed.hooks as Record<string, unknown>)
+      : {};
+
+  const nextEntry = {
+    type: "command",
+    command,
+    matcher: MATCHERS.claude,
+    statusMessage: "Miru search policy",
+  };
+
+  const existingPreToolUse = Array.isArray(hooksRoot.PreToolUse)
+    ? (hooksRoot.PreToolUse as unknown[])
+    : [];
+  const mergedPreToolUse =
+    existingPreToolUse.length > 0 &&
+    existingPreToolUse.some((entry) =>
+      hookCommandMatches((entry as Record<string, unknown>).command),
+    )
+      ? existingPreToolUse.map((entry) => {
+          const hookEntry = entry as Record<string, unknown>;
+          if (!hookCommandMatches(hookEntry.command)) {
+            return hookEntry;
+          }
+          return nextEntry;
+        })
+      : [...existingPreToolUse, nextEntry];
+
+  const currentOwners = Array.isArray(parsed[VSCODE_OWNERS_KEY])
+    ? (parsed[VSCODE_OWNERS_KEY] as unknown[]).filter(
+        (item): item is string =>
+          typeof item === "string" &&
+          SHARED_VSCODE_HOOK_OWNERS.includes(item as (typeof SHARED_VSCODE_HOOK_OWNERS)[number]),
+      )
+    : [];
+  const nextOwners = owner
+    ? Array.from(
+        new Set([
+          ...currentOwners,
+          ...(SHARED_VSCODE_HOOK_OWNERS.includes(
+            owner as (typeof SHARED_VSCODE_HOOK_OWNERS)[number],
+          )
+            ? [owner]
+            : []),
+        ]),
+      )
+    : currentOwners;
+
+  const next = {
+    ...parsed,
+    hooks: { ...hooksRoot, PreToolUse: mergedPreToolUse },
+    ...(nextOwners.length > 0 ? { [VSCODE_OWNERS_KEY]: nextOwners } : {}),
+  };
+  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
+  if (nextJson === `${text.endsWith("\n") ? text : `${text}\n`}`) {
+    return "unchanged";
+  }
+  await Bun.write(path, nextJson);
   return existed ? "updated" : "created";
 }
 
-export async function removeVscodeHooks(path: string): Promise<InstallAction> {
+export async function removeVscodeHooks(path: string, owner?: string): Promise<InstallAction> {
   if (!(await Bun.file(path).exists())) {
     return "not-found";
   }
   const text = await Bun.file(path).text();
+  const parsed = parseJsonObject(text);
+  if (parsed === "error") {
+    return "error";
+  }
+
+  const owners = Array.isArray(parsed[VSCODE_OWNERS_KEY])
+    ? (parsed[VSCODE_OWNERS_KEY] as unknown[]).filter(
+        (item): item is string => typeof item === "string",
+      )
+    : null;
+  if (owners && owner) {
+    const remainingOwners = owners.filter((value) => value !== owner);
+    if (remainingOwners.length > 0) {
+      parsed[VSCODE_OWNERS_KEY] = remainingOwners;
+      await Bun.write(path, `${JSON.stringify(parsed, null, 2)}\n`);
+      return "updated";
+    }
+    delete parsed[VSCODE_OWNERS_KEY];
+    const hooksRoot =
+      parsed.hooks && typeof parsed.hooks === "object" && !Array.isArray(parsed.hooks)
+        ? (parsed.hooks as Record<string, unknown>)
+        : {};
+    const filtered = Array.isArray(hooksRoot.PreToolUse)
+      ? (hooksRoot.PreToolUse as Record<string, unknown>[]).filter(
+          (entry) => !hookCommandMatches(entry.command),
+        )
+      : [];
+    if (filtered.length === 0) {
+      delete hooksRoot.PreToolUse;
+    } else {
+      hooksRoot.PreToolUse = filtered;
+    }
+    if (Object.keys(hooksRoot).length === 0) {
+      delete parsed.hooks;
+    } else {
+      parsed.hooks = hooksRoot;
+    }
+    if (isEmptyHookConfig(parsed)) {
+      await unlink(path);
+      return "removed";
+    }
+    await Bun.write(path, `${JSON.stringify(parsed, null, 2)}\n`);
+    return "removed";
+  }
+
   if (!text.includes(HOOK_GUARD_MARKER) && !text.includes(MIRU_HOOK_MARKER)) {
     return "not-found";
   }
@@ -413,7 +505,11 @@ export async function removeOpenCodePlugin(pluginPath: string): Promise<InstallA
   return "removed";
 }
 
-export async function mergeHooks(format: HooksFormat, path: string): Promise<InstallAction> {
+export async function mergeHooks(
+  format: HooksFormat,
+  path: string,
+  owner?: string,
+): Promise<InstallAction> {
   switch (format) {
     case "cursor":
       return mergeCursorHooks(path);
@@ -422,7 +518,7 @@ export async function mergeHooks(format: HooksFormat, path: string): Promise<Ins
     case "gemini":
       return mergeGeminiHooks(path);
     case "vscode":
-      return mergeVscodeHooks(path);
+      return mergeVscodeHooks(path, owner);
     case "kiro":
       return mergeKiroHooks(path);
     case "windsurf":
@@ -436,7 +532,11 @@ export async function mergeHooks(format: HooksFormat, path: string): Promise<Ins
   }
 }
 
-export async function removeHooks(format: HooksFormat, path: string): Promise<InstallAction> {
+export async function removeHooks(
+  format: HooksFormat,
+  path: string,
+  owner?: string,
+): Promise<InstallAction> {
   switch (format) {
     case "cursor":
       return removeCursorHooks(path);
@@ -445,7 +545,7 @@ export async function removeHooks(format: HooksFormat, path: string): Promise<In
     case "gemini":
       return removeGeminiHooks(path);
     case "vscode":
-      return removeVscodeHooks(path);
+      return removeVscodeHooks(path, owner);
     case "kiro":
       return removeKiroHooks(path);
     case "windsurf":

package/src/installer/installer.ts

@@ -95,7 +95,9 @@ async function applyHooks(agent: AgentTarget, mode: InstallMode): Promise<WriteR
   }
 
   const action =
-    mode === "install" ? await mergeHooks(format, path) : await removeHooks(format, path);
+    mode === "install"
+      ? await mergeHooks(format, path, agent.id)
+      : await removeHooks(format, path, agent.id);
 
   return { path, action };
 }
@@ -181,7 +183,7 @@ const INTEGRATIONS: Integration[] = [
     label: "Search hooks",
     description: "blocks built-in search; routes to Miru MCP",
     experimental: true,
-    defaultChecked: false,
+    defaultChecked: true,
     planPath: (agent) => agent.hooksPath,
     apply: applyHooks,
   },

package/src/installer/prompt.ts

@@ -91,23 +91,52 @@ function readKey(): Promise<Buffer> {
   });
 }
 
-function parseKey(chunk: Buffer): string {
-  const text = chunk.toString("utf8");
-  if (chunk.length >= 3 && chunk[0] === 0x1b && chunk[1] === 0x5b) {
-    const code = chunk[2];
-    if (code === 0x41) {
+function parseArrowKey(chunk: Buffer, text: string): string | null {
+  if (chunk.length >= 2 && (chunk[0] === 0x00 || chunk[0] === 0xe0)) {
+    const scanCode = chunk[1];
+    if (scanCode === 0x48) {
       return "up";
     }
-    if (code === 0x42) {
+    if (scanCode === 0x50) {
       return "down";
     }
-    if (code === 0x43) {
+    if (scanCode === 0x4d) {
       return "right";
     }
-    if (code === 0x44) {
+    if (scanCode === 0x4b) {
       return "left";
     }
   }
+
+  // Support both ANSI CSI (ESC [ A) and SS3 (ESC O A) arrow sequences.
+  if (text.startsWith(ESC) && text.length >= 3) {
+    const introducer = text.charAt(1);
+    if (introducer === "[" || introducer === "O") {
+      const arrow = text.charAt(text.length - 1);
+      if (arrow === "A") {
+        return "up";
+      }
+      if (arrow === "B") {
+        return "down";
+      }
+      if (arrow === "C") {
+        return "right";
+      }
+      if (arrow === "D") {
+        return "left";
+      }
+    }
+  }
+
+  return null;
+}
+
+function parseKey(chunk: Buffer): string {
+  const text = chunk.toString("utf8");
+  const arrowKey = parseArrowKey(chunk, text);
+  if (arrowKey) {
+    return arrowKey;
+  }
   if (text === "\r" || text === "\n") {
     return "enter";
   }
@@ -129,6 +158,11 @@ function parseKey(chunk: Buffer): string {
   return text;
 }
 
+/** Test hook for validating raw key sequence parsing without a TTY. */
+export function parseInstallerKeyForTest(chunk: Buffer): string {
+  return parseKey(chunk);
+}
+
 async function withRawMode<T>(fn: () => Promise<T>): Promise<T> {
   input.setRawMode(true);
   input.resume();

package/src/mcp/index-cache.ts

@@ -1,5 +1,7 @@
 import { watch } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import { walkFiles } from "../index/file-walker.ts";
+import { getExtensions } from "../index/files.ts";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
 import { MiruIndex } from "../miru-index.ts";
 import type { ContentType } from "../types.ts";
@@ -115,26 +117,34 @@ export class IndexCache {
     ref: string | null | undefined,
     cacheKey: string,
   ): Promise<MiruIndex> {
+    const entry = this.ensureEntry(cacheKey, source);
     const task = (async () => {
       const index = await MiruIndex.fromSource(source, this.content, undefined, ref);
       if (!isGitUrl(source)) {
         await index.saveToCache(resolve(source));
       }
+      // Publish before stale reconciliation so flushFileUpdates can use
+      // entry.index instead of awaiting this same task (self-deadlock).
+      entry.index = index;
+      if (index.loadedFromDisk) {
+        // Await reconciliation here (not fire-and-forget) so callers of `get()`
+        // never observe an index that's stale relative to what's on disk.
+        await this.checkAndQueueStaleFiles(source, index, cacheKey);
+      }
       return index;
     })();
 
-    const entry = this.ensureEntry(cacheKey, source);
     entry.task = task;
     void task
       .then((index) => {
         entry.index = index;
         this.maybeStartWatcher(source);
-        void this.flushFileUpdates(cacheKey, source);
         return index;
       })
       .catch(() => {
         if (entry.task === task) {
           entry.task = null;
+          entry.index = null;
         }
       });
 
@@ -162,7 +172,7 @@ export class IndexCache {
     if (!entry.flushQueued) {
       entry.flushQueued = true;
       queueMicrotask(() => {
-        this.flushFileUpdates(cacheKey, source);
+        void this.flushFileUpdates(cacheKey, source);
       });
     }
   }
@@ -219,10 +229,14 @@ export class IndexCache {
     this.scheduleFlush(cacheKey, source, entry);
   }
 
-  private flushFileUpdates(cacheKey: string, source: string): void {
+  private flushFileUpdates(
+    cacheKey: string,
+    source: string,
+    knownIndex?: MiruIndex,
+  ): Promise<void> {
     const entry = this.entries.get(cacheKey);
     if (!entry) {
-      return;
+      return Promise.resolve();
     }
     entry.flushQueued = false;
 
@@ -233,7 +247,9 @@ export class IndexCache {
         return;
       }
 
-      let index = entry.index;
+      // Prefer an index already in hand (or published on the entry). Never await
+      // entry.task while that task is itself waiting on this flush — that deadlocks.
+      let index = knownIndex ?? entry.index;
       if (!index && entry.task) {
         try {
           index = await entry.task;
@@ -264,6 +280,57 @@ export class IndexCache {
     };
 
     entry.updateChain = entry.updateChain.then(run, run);
+    return entry.updateChain;
+  }
+
+  private async checkAndQueueStaleFiles(
+    source: string,
+    index: MiruIndex,
+    cacheKey: string,
+  ): Promise<void> {
+    if (isGitUrl(source)) {
+      return;
+    }
+
+    const root = index.root;
+    if (!root) {
+      return;
+    }
+
+    const storedMtimes = index.getStoredFileMtimes();
+    const entry = this.ensureEntry(cacheKey, source);
+
+    try {
+      await Promise.all(
+        [...storedMtimes].map(async ([filePath, storedMtime]) => {
+          try {
+            const currentStat = await Bun.file(resolve(root, filePath)).stat();
+            const currentMtime = Math.floor(currentStat.mtime?.getTime() ?? 0);
+
+            if (currentMtime !== storedMtime) {
+              entry.pendingPaths.add(normalizeRelativePath(filePath));
+            }
+          } catch {
+            entry.pendingPaths.add(normalizeRelativePath(filePath));
+          }
+        }),
+      );
+
+      // Files created on disk while this index wasn't loaded (or never indexed
+      // before) have no entry in `storedMtimes` and are otherwise invisible to
+      // the mtime comparison above; a directory walk is the only way to find them.
+      const extensions = getExtensions(index.contentTypes);
+      for await (const absolutePath of walkFiles(root, extensions)) {
+        const relativePath = normalizeRelativePath(relative(root, absolutePath));
+        if (!storedMtimes.has(relativePath)) {
+          entry.pendingPaths.add(relativePath);
+        }
+      }
+
+      if (entry.pendingPaths.size > 0) {
+        await this.flushFileUpdates(cacheKey, source, index);
+      }
+    } catch {}
   }
 
   private maybeStartWatcher(source: string): void {

package/src/miru-index.ts

@@ -60,7 +60,7 @@ export class MiruIndex {
    * Absolute path to the indexed tree on disk, or `null` for git-only indexes
    * (clone is deleted after indexing; incremental updates need a local root).
    */
-  private readonly root: string | null;
+  private readonly _root: string | null;
 
   /** Content kinds indexed at build time (e.g. `code`, `markdown`). */
   private readonly content: ContentType[];
@@ -71,6 +71,9 @@ export class MiruIndex {
   /** Language tag → chunk indices, for `filterLanguages` in search. */
   private languageMapping: Map<string, number[]>;
 
+  /** Stored file mtimes (file path → mtime_ms) for cache freshness checking. */
+  private storedFileMtimes: Map<string, number>;
+
   /** Read-only view of indexed chunks. */
   get chunks(): Chunk[] {
     return this.chunksInternal;
@@ -81,6 +84,21 @@ export class MiruIndex {
     return this.loadedFromDiskFlag;
   }
 
+  /** Get stored file mtimes for cache validation. */
+  getStoredFileMtimes(): Map<string, number> {
+    return this.storedFileMtimes;
+  }
+
+  /** Get the root path for local indexes (null for git indexes). */
+  get root(): string | null {
+    return this._root;
+  }
+
+  /** Content kinds indexed at build time, for re-walking the tree during freshness checks. */
+  get contentTypes(): ContentType[] {
+    return this.content;
+  }
+
   /**
    * Prefer static factories (`fromPath`, `fromGit`, `loadFromDisk`) over calling
    * directly; the constructor is public for tests and advanced composition.
@@ -94,15 +112,17 @@ export class MiruIndex {
     root?: string | null;
     content?: ContentType[];
     loadedFromDisk?: boolean;
+    storedFileMtimes?: Record<string, number>;
   }) {
     this.embeddings = options.embeddings;
     this.bm25Index = options.bm25Index;
     this.semanticIndex = options.semanticIndex;
     this.chunksInternal = options.chunks;
     this.embeddingModel = options.embeddingModel;
-    this.root = options.root ?? null;
+    this._root = options.root ?? null;
     this.content = options.content ?? ["code"];
     this.loadedFromDiskFlag = options.loadedFromDisk ?? false;
+    this.storedFileMtimes = new Map(Object.entries(options.storedFileMtimes ?? {}));
     this.fileMapping = new Map();
     this.languageMapping = new Map();
     this.rebuildMappings();
@@ -253,6 +273,7 @@ export class MiruIndex {
     const { bm25, semantic, chunks, metadata } = await loadCachedIndex(path);
     const content = (metadata.content_type as ContentType[]) ?? ["code"];
     const root = metadata.root_path ? String(metadata.root_path) : null;
+    const storedFileMtimes = (metadata.file_mtimes as Record<string, number>) ?? {};
 
     return new MiruIndex({
       embeddings: getEmbeddingBackend(model),
@@ -263,6 +284,7 @@ export class MiruIndex {
       root,
       content,
       loadedFromDisk: true,
+      storedFileMtimes,
     });
   }
 
@@ -275,6 +297,19 @@ export class MiruIndex {
   async save(path: string): Promise<void> {
     const paths = persistencePaths(path);
     await mkdir(paths.root, { recursive: true });
+
+    const fileMtimes: Record<string, number> = {};
+    if (this._root) {
+      for (const filePath of this.fileMapping.keys()) {
+        try {
+          const stat = await Bun.file(resolve(this._root, filePath)).stat();
+          fileMtimes[filePath] = Math.floor(stat.mtime?.getTime() ?? 0);
+        } catch {
+          fileMtimes[filePath] = 0;
+        }
+      }
+    }
+
     await saveIndexBundle({
       paths,
       bm25: this.bm25Index,
@@ -282,7 +317,7 @@ export class MiruIndex {
       chunks: this.chunks.map(chunkToDict),
       metadata: {
         index_epoch: indexCacheEpoch(),
-        root_path: this.root,
+        root_path: this._root,
         time: Date.now() / 1000,
         embedding_model: this.embeddingModel,
         embedding_dimensions:
@@ -290,6 +325,7 @@ export class MiruIndex {
         embedding_provider: "openai",
         content_type: this.content,
         file_paths: [...this.fileMapping.keys()].sort(),
+        file_mtimes: fileMtimes,
       },
     });
   }
@@ -313,7 +349,7 @@ export class MiruIndex {
    * index, and mappings in place; clears `loadedFromDisk` since data changed.
    */
   async applyFileChanges(relativePaths: readonly string[]): Promise<void> {
-    if (!this.root) {
+    if (!this._root) {
       throw new Error("Incremental update requires a local index with root_path set.");
     }
     if (relativePaths.length === 0) {
@@ -321,7 +357,7 @@ export class MiruIndex {
     }
 
     const updated = await applyIncrementalFileChanges({
-      root: this.root,
+      root: this._root,
       content: this.content,
       embeddings: this.embeddings,
       chunks: this.chunksInternal,