@aria-cli/tools 1.0.2 → 1.0.3

package/src/executors/search-freshness.ts

@@ -0,0 +1,249 @@
+/**
+ * Freshness tracker for aria-search (code_search tool).
+ *
+ * Mirrors frg-freshness.ts patterns to close the freshness gaps:
+ * 1. Tracks file mutations from ARIA tool writes (session overlay)
+ * 2. Reconciles git-dirty files on each search
+ * 3. Generates session overlay for the napi search() call
+ *
+ * The session overlay gives 0ms visibility for pending mutations —
+ * files written by agents/users appear in search results immediately
+ * without waiting for an index rebuild or hot.log sync.
+ */
+
+import * as fsSync from "node:fs";
+import * as nodePath from "node:path";
+import { execFileSync } from "node:child_process";
+
+export type SearchMutationOperation = "write" | "delete";
+
+export interface SearchMutationRecord {
+  path: string;
+  operation: SearchMutationOperation;
+  content?: string;
+  sequence: number;
+}
+
+export interface SearchSessionOverlay {
+  sessionWrites: Array<{ path: string; content: string }>;
+  sessionDeletes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// In-memory state (per repo root)
+// ---------------------------------------------------------------------------
+
+interface RepoState {
+  sequence: number;
+  pending: Map<string, SearchMutationRecord>;
+  lastGitReconcileMs: number;
+}
+
+const repoStates = new Map<string, RepoState>();
+
+/** Minimum interval between git-dirty reconciliations (avoid hammering git). */
+const GIT_RECONCILE_INTERVAL_MS = 2_000;
+
+/** Max content size to cache in memory per file. */
+const MAX_CACHED_CONTENT_BYTES = 256 * 1024;
+
+function norm(p: string): string {
+  return nodePath.resolve(p);
+}
+
+function getState(root: string): RepoState {
+  const key = norm(root);
+  let state = repoStates.get(key);
+  if (!state) {
+    state = { sequence: 0, pending: new Map(), lastGitReconcileMs: 0 };
+    repoStates.set(key, state);
+  }
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Public API — called from filesystem/patch executors
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a file mutation from an ARIA tool write/edit/delete.
+ * Called alongside recordFrgMutation in filesystem.ts and apply-patch.ts.
+ */
+export function recordSearchMutation(
+  filePath: string,
+  operation: SearchMutationOperation,
+  content?: string,
+): void {
+  // Find the git repo root to scope mutations correctly
+  const repoRoot = findGitRepoRoot(filePath);
+  if (!repoRoot) return;
+
+  const state = getState(repoRoot);
+  state.sequence += 1;
+  const normalizedPath = norm(filePath);
+
+  state.pending.set(normalizedPath, {
+    path: normalizedPath,
+    operation,
+    content:
+      typeof content === "string" && Buffer.byteLength(content, "utf8") <= MAX_CACHED_CONTENT_BYTES
+        ? content
+        : undefined,
+    sequence: state.sequence,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API — called from search executor
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile git-dirty files into the pending mutations map.
+ * Runs `git diff --name-status -z HEAD` and `git ls-files -o --exclude-standard -z`
+ * to detect files modified/created/deleted by external agents or the user.
+ *
+ * Throttled to at most once per GIT_RECONCILE_INTERVAL_MS to avoid
+ * hammering git on rapid sequential searches.
+ */
+export function reconcileSearchGitDirty(root: string): void {
+  const state = getState(root);
+  const now = Date.now();
+  if (now - state.lastGitReconcileMs < GIT_RECONCILE_INTERVAL_MS) {
+    return; // Throttled — recent reconciliation is still fresh enough
+  }
+  state.lastGitReconcileMs = now;
+
+  const normalizedRoot = norm(root);
+
+  // Tracked modified/deleted files
+  const trackedOutput = runGit(normalizedRoot, ["diff", "--name-status", "-z", "HEAD", "--"]);
+  if (trackedOutput) {
+    const tokens = trackedOutput.split("\0").filter(Boolean);
+    for (let i = 0; i < tokens.length; i++) {
+      const status = tokens[i] ?? "";
+      if (status.startsWith("R")) {
+        // Rename: old path deleted, new path written
+        const oldPath = tokens[++i];
+        const newPath = tokens[++i];
+        if (oldPath) addGitDirtyMutation(state, normalizedRoot, oldPath, "delete");
+        if (newPath) addGitDirtyMutation(state, normalizedRoot, newPath, "write");
+        continue;
+      }
+      const filePath = tokens[++i];
+      if (!filePath) continue;
+      addGitDirtyMutation(
+        state,
+        normalizedRoot,
+        filePath,
+        status.startsWith("D") ? "delete" : "write",
+      );
+    }
+  }
+
+  // Untracked new files
+  const untrackedOutput = runGit(normalizedRoot, ["ls-files", "-o", "--exclude-standard", "-z"]);
+  if (untrackedOutput) {
+    for (const token of untrackedOutput.split("\0").filter(Boolean)) {
+      addGitDirtyMutation(state, normalizedRoot, token, "write");
+    }
+  }
+}
+
+function addGitDirtyMutation(
+  state: RepoState,
+  root: string,
+  relativePath: string,
+  operation: SearchMutationOperation,
+): void {
+  const absPath = norm(nodePath.join(root, relativePath));
+  const existing = state.pending.get(absPath);
+  // Don't overwrite ARIA-sourced mutations (which have cached content)
+  if (existing?.content) return;
+  if (existing?.operation === operation) return;
+
+  state.sequence += 1;
+  state.pending.set(absPath, {
+    path: absPath,
+    operation,
+    content: undefined, // Will be read from disk in getSearchSessionOverlay
+    sequence: state.sequence,
+  });
+}
+
+/**
+ * Generate the session overlay for the napi search() call.
+ * Reads content from disk for mutations without cached content.
+ */
+export function getSearchSessionOverlay(root: string): SearchSessionOverlay {
+  const state = getState(root);
+  const sessionWrites: Array<{ path: string; content: string }> = [];
+  const sessionDeletes: string[] = [];
+
+  for (const mutation of state.pending.values()) {
+    if (mutation.operation === "delete") {
+      sessionDeletes.push(mutation.path);
+      continue;
+    }
+
+    let content = mutation.content;
+    if (typeof content !== "string") {
+      // Read from disk — closes the gap where git-dirty files have no cached content
+      try {
+        const buf = fsSync.readFileSync(mutation.path);
+        if (!buf.subarray(0, Math.min(buf.length, 8192)).includes(0)) {
+          content = buf.toString("utf8");
+        }
+      } catch {
+        continue; // Unreadable — skip
+      }
+    }
+
+    if (typeof content === "string") {
+      sessionWrites.push({ path: mutation.path, content });
+    }
+  }
+
+  return { sessionWrites, sessionDeletes };
+}
+
+/**
+ * Clear all pending mutations for a repo root.
+ * Called after a full index rebuild (all mutations are now in the base index).
+ */
+export function clearSearchMutations(root: string): void {
+  const key = norm(root);
+  repoStates.delete(key);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findGitRepoRoot(startPath: string): string | null {
+  let current = norm(startPath);
+  try {
+    if (!fsSync.statSync(current).isDirectory()) {
+      current = nodePath.dirname(current);
+    }
+  } catch {
+    current = nodePath.dirname(current);
+  }
+  while (true) {
+    if (fsSync.existsSync(nodePath.join(current, ".git"))) return current;
+    const parent = nodePath.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function runGit(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}

package/src/executors/search.ts

@@ -0,0 +1,89 @@
+/**
+ * Executor for the native indexed regex search tool.
+ *
+ * Freshness architecture (frg parity):
+ * 1. ARIA tool writes → recordSearchMutation → session overlay (0ms visibility)
+ * 2. External edits → reconcileSearchGitDirty → session overlay (0ms visibility)
+ * 3. Commit/version change → syncIndex or buildIndex (incremental/full)
+ * 4. Session overlay passed to napi search() — no index rebuild needed
+ */
+
+import * as nodePath from "node:path";
+import { buildIndex, syncIndex, indexStatus, search } from "@aria-cli/search";
+import { success, fail } from "./utils.js";
+import type { ToolContext, ToolResult } from "../types.js";
+import {
+  reconcileSearchGitDirty,
+  getSearchSessionOverlay,
+  clearSearchMutations,
+} from "./search-freshness.js";
+
+interface SearchInput {
+  pattern: string;
+  directory?: string;
+  fileGlob?: string;
+  fileType?: string;
+  caseSensitive?: boolean;
+  literal?: boolean;
+  maxResults?: number;
+  context?: number;
+}
+
+export async function executeSearch(input: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const opts = input as SearchInput;
+  const dir = nodePath.resolve(ctx.workingDir, opts.directory || ".");
+
+  try {
+    // Step 1: Index management — build or sync base index if needed.
+    const status = indexStatus(dir);
+    if (status.state === "none") {
+      buildIndex(dir);
+      clearSearchMutations(dir); // fresh index includes everything
+    } else if (status.state === "stale") {
+      // Commit or binary version changed — incremental sync is sufficient
+      // (syncIndex rebuilds hot.log from git diff, much cheaper than full build).
+      // Only fall back to full build if sync fails.
+      try {
+        syncIndex(dir);
+      } catch {
+        buildIndex(dir);
+      }
+      clearSearchMutations(dir);
+    }
+    // "ready" — base index is fresh, session overlay handles uncommitted changes
+
+    // Step 2: Reconcile git-dirty files into pending mutations.
+    // Detects files modified/created/deleted by external agents or the user.
+    // Throttled to avoid hammering git on rapid sequential searches.
+    reconcileSearchGitDirty(dir);
+
+    // Step 3: Generate session overlay from pending mutations.
+    // This gives 0ms visibility for ARIA tool writes and external edits —
+    // no index rebuild needed. The overlay is applied in-memory by the
+    // Rust search engine on top of the base index + hot.log.
+    const overlay = getSearchSessionOverlay(dir);
+
+    // Step 4: Search with overlay.
+    const results = search({
+      pattern: opts.pattern,
+      directory: dir,
+      maxResults: opts.maxResults ?? 1000,
+      fileGlob: opts.fileGlob,
+      fileType: opts.fileType,
+      caseSensitive: opts.caseSensitive ?? true,
+      literal: opts.literal ?? false,
+      context: opts.context ?? 0,
+      sessionWrites: overlay.sessionWrites,
+      sessionDeletes: overlay.sessionDeletes,
+    });
+
+    const truncated = results.length >= (opts.maxResults ?? 1000);
+    return success(
+      `Found ${results.length} matches for "${opts.pattern}"${truncated ? " (truncated)" : ""}`,
+      { matches: results, truncated },
+    );
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return fail(`Search failed: ${reason}`);
+  }
+}

package/src/index.ts

@@ -515,6 +515,25 @@ export {
   executeGlob,
   executeGrep,
   executeApplyPatch,
+  executeFrg,
+  recordFrgMutation,
+  getPendingFrgMutations,
+  getPendingFrgMutationBytes,
+  clearPendingFrgMutations,
+  flushPendingFrgMutations,
+  maybeBuildFrgIndexForRepo,
+  ensureFrgRepoStateLoaded,
+  reconcileGitDirtyMutations,
+  getGitDirtyStatus,
+  getFrgFlushStatus,
+  getFrgFreshnessSnapshot,
+  scheduleBackgroundFrgFlush,
+  shouldForceSynchronousFrgFlush,
+  DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS,
+  BACKGROUND_FRG_MAX_FLUSH_DELAY_MS,
+  MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH,
+  MAX_PENDING_MUTATION_BYTES_BEFORE_SYNC_FLUSH,
+  MAX_CACHED_MUTATION_CONTENT_BYTES,
 } from "./executors/index.js";
 
 // Filesystem types
@@ -528,6 +547,12 @@ export type {
   GrepInput,
   GrepMatch,
   ApplyPatchInput,
+  FrgInput,
+  FrgMutationOperation,
+  FrgMutationRecord,
+  FrgGitDirtyStatus,
+  FrgFlushStatus,
+  FrgFreshnessSnapshot,
 } from "./executors/index.js";
 
 // Shell executors

package/src/network-runtime/local-control-contract.ts

@@ -45,6 +45,7 @@ export const RunRequestSchema = z
     arion: NonEmptyStringSchema.optional(),
     cwd: NonEmptyStringSchema.optional(),
     history: MessageHistorySchema,
+    requestedModel: NonEmptyStringSchema.optional(),
     preferredTier: z.enum(["fast", "balanced", "powerful", "ensemble"]).optional(),
     budget: z.number().positive().optional(),
     maxTurns: z.number().int().positive().optional(),
@@ -144,6 +145,7 @@ export const ResumeRunRequestSchema = z
     state: z.unknown(),
     arion: NonEmptyStringSchema.optional(),
     cwd: NonEmptyStringSchema.optional(),
+    requestedModel: NonEmptyStringSchema.optional(),
     preferredTier: z.enum(["fast", "balanced", "powerful", "ensemble"]).optional(),
     budget: z.number().positive().optional(),
     maxTurns: z.number().int().positive().optional(),

package/tests/definitions/tool-inventory.test.ts

@@ -15,12 +15,13 @@ import {
   ARION_TOOL_DEFINITIONS,
   DELEGATION_TOOL_DEFINITIONS,
   META_TOOL_DEFINITIONS,
+  FRG_TOOL_DEFINITIONS,
 } from "../../src/definitions/core.js";
 
 describe("Tool Inventory", () => {
   describe("total tool count", () => {
-    it("should have exactly 64 core tools", () => {
-      expect(CORE_TOOL_DEFINITIONS).toHaveLength(64);
+    it("should have exactly 74 core tools", () => {
+      expect(CORE_TOOL_DEFINITIONS).toHaveLength(74);
     });
   });
 
@@ -35,6 +36,7 @@ describe("Tool Inventory", () => {
       expect(names).toContain("apply_patch");
       expect(names).toContain("write_stdin");
       expect(names).toContain("ls");
+      expect(names).toContain("frg");
     });
 
     it("should include OpenClaw-forked tools", () => {
@@ -107,7 +109,7 @@ describe("Tool Inventory", () => {
     });
 
     it("all core tools have loadingTier 'always' or 'deferred'", () => {
-      const ALLOWED_DEFERRED = new Set(["session_history", "self_diagnose"]);
+      const ALLOWED_DEFERRED = new Set(["session_history", "frg"]);
       for (const tool of CORE_TOOL_DEFINITIONS) {
         if (ALLOWED_DEFERRED.has(tool.name)) {
           expect(tool.loadingTier, `Tool "${tool.name}" should have loadingTier "deferred"`).toBe(
@@ -126,8 +128,8 @@ describe("Tool Inventory", () => {
     const countByCategory = (category: string) =>
       CORE_TOOL_DEFINITIONS.filter((t) => t.category === category).length;
 
-    it("filesystem: 7 tools", () => {
-      expect(countByCategory("filesystem")).toBe(7);
+    it("filesystem: 8 tools", () => {
+      expect(countByCategory("filesystem")).toBe(8);
     });
 
     it("shell: 8 tools", () => {
@@ -154,6 +156,10 @@ describe("Tool Inventory", () => {
       expect(countByCategory("messaging")).toBe(14);
     });
 
+    it("code: 9 tools (rg, ug, probe, sg, cbm, lsp, serena, fff, frg)", () => {
+      expect(countByCategory("code")).toBe(9);
+    });
+
     it("category counts sum to total", () => {
       const total =
         countByCategory("filesystem") +
@@ -162,7 +168,8 @@ describe("Tool Inventory", () => {
         countByCategory("memory") +
         countByCategory("arion") +
         countByCategory("meta") +
-        countByCategory("messaging");
+        countByCategory("messaging") +
+        countByCategory("code");
       expect(total).toBe(CORE_TOOL_DEFINITIONS.length);
     });
   });
@@ -195,6 +202,10 @@ describe("Tool Inventory", () => {
     it("META_TOOL_DEFINITIONS has 12 tools", () => {
       expect(META_TOOL_DEFINITIONS).toHaveLength(12);
     });
+
+    it("FRG_TOOL_DEFINITIONS has 1 tool", () => {
+      expect(FRG_TOOL_DEFINITIONS).toHaveLength(1);
+    });
   });
 
   describe("every tool has an execute function", () => {

package/tests/executors/frg-freshness.test.ts

@@ -0,0 +1,136 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import {
+  DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS,
+  MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH,
+  clearPendingFrgMutations,
+  ensureFrgRepoStateLoaded,
+  getFrgFreshnessSnapshot,
+  getGitDirtyStatus,
+  getPendingFrgMutations,
+  recordFrgMutation,
+  scheduleBackgroundFrgFlush,
+  searchPendingFrgMutations,
+  shouldForceSynchronousFrgFlush,
+} from "../../src/executors/frg-freshness.js";
+
+describe("frg freshness manager", () => {
+  let repoDir: string;
+  let filePath: string;
+
+  beforeEach(async () => {
+    repoDir = await fs.mkdtemp(path.join(os.tmpdir(), "aria-frg-freshness-"));
+    await fs.mkdir(path.join(repoDir, ".git"));
+    await fs.writeFile(path.join(repoDir, "a.ts"), "export const a = 1;\n", "utf8");
+    filePath = path.join(repoDir, "a.ts");
+    clearPendingFrgMutations(repoDir);
+  });
+
+  it("records write mutations in sequence order", () => {
+    recordFrgMutation(filePath, "write");
+    recordFrgMutation(filePath, "write");
+
+    const pending = getPendingFrgMutations(repoDir);
+    expect(pending).toHaveLength(1);
+    expect(pending[0]?.operation).toBe("write");
+    expect(pending[0]?.path).toBe(path.resolve(filePath));
+  });
+
+  it("tracks delete operations", () => {
+    recordFrgMutation(filePath, "delete");
+    const pending = getPendingFrgMutations(repoDir);
+    expect(pending).toHaveLength(1);
+    expect(pending[0]?.operation).toBe("delete");
+  });
+
+  it("searches pending session mutations directly", async () => {
+    const updatedContent = 'export const token = "abc123";\nexport const Beta = 2;\n';
+    await fs.writeFile(filePath, updatedContent, "utf8");
+    recordFrgMutation(filePath, "write", updatedContent);
+
+    const result = await searchPendingFrgMutations(repoDir, {
+      pattern: "abc123",
+      literal: true,
+    });
+    expect(result?.mode).toBe("matches");
+    expect(result && result.mode === "matches" ? result.matches?.length : 0).toBeGreaterThan(0);
+
+    const filesOnly = await searchPendingFrgMutations(repoDir, {
+      pattern: "token",
+      filesOnly: true,
+    });
+    expect(filesOnly?.mode).toBe("files");
+    expect(filesOnly && filesOnly.mode === "files" ? filesOnly.files : []).toContain("a.ts");
+
+    const count = await searchPendingFrgMutations(repoDir, {
+      pattern: "export",
+      count: true,
+    });
+    expect(count?.mode).toBe("counts");
+    expect(count && count.mode === "counts" ? count.counts?.[0]?.count : 0).toBeGreaterThan(0);
+
+    const quiet = await searchPendingFrgMutations(repoDir, {
+      pattern: "BETA",
+      caseInsensitive: true,
+      quiet: true,
+    });
+    expect(quiet?.mode).toBe("quiet");
+    expect(quiet?.matched).toBe(true);
+  });
+
+  it("schedules background flushes without forcing sync below threshold", async () => {
+    const updatedContent = 'export const token = "abc123";\n';
+    await fs.writeFile(filePath, updatedContent, "utf8");
+    recordFrgMutation(filePath, "write", updatedContent);
+
+    expect(DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS).toBeGreaterThan(0);
+    expect(shouldForceSynchronousFrgFlush(repoDir)).toBe(false);
+
+    scheduleBackgroundFrgFlush(repoDir, 5);
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  });
+
+  it("forces sync only when pending mutations cross threshold", () => {
+    for (let i = 0; i < MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH - 1; i++) {
+      recordFrgMutation(path.join(repoDir, `f-${i}.ts`), "write");
+    }
+    expect(shouldForceSynchronousFrgFlush(repoDir)).toBe(false);
+
+    recordFrgMutation(
+      path.join(repoDir, `f-${MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH}.ts`),
+      "write",
+    );
+    expect(shouldForceSynchronousFrgFlush(repoDir)).toBe(true);
+  });
+
+  it("reports freshness snapshot and can clear/reload state boundaries", async () => {
+    const updatedContent = 'export const wal = "persisted";\n';
+    await fs.writeFile(filePath, updatedContent, "utf8");
+    recordFrgMutation(filePath, "write", updatedContent);
+
+    const pendingBefore = getPendingFrgMutations(repoDir);
+    expect(pendingBefore).toHaveLength(1);
+
+    clearPendingFrgMutations(repoDir);
+    ensureFrgRepoStateLoaded(repoDir);
+    const pendingAfter = getPendingFrgMutations(repoDir);
+    expect(pendingAfter).toHaveLength(0);
+  });
+
+  it("reads git dirty status and freshness metadata", async () => {
+    const dirtyPath = path.join(repoDir, "dirty.ts");
+    await fs.writeFile(dirtyPath, "export const dirty = true;\n", "utf8");
+
+    const dirty = getGitDirtyStatus(repoDir);
+    expect(Array.isArray(dirty.untracked)).toBe(true);
+
+    const snapshot = getFrgFreshnessSnapshot(repoDir, {
+      commit_hash: "abc",
+      tree_hash: "def",
+      age_seconds: 10,
+    });
+    expect(snapshot.freshnessState).toBeDefined();
+  });
+});

package/tests/executors/frg-merge.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { ToolContext } from "../../src/types.js";
+import { clearPendingFrgMutations, recordFrgMutation } from "../../src/executors/frg-freshness.js";
+import { executeFrg } from "../../src/executors/frg.js";
+
+describe("frg search merge precedence", () => {
+  let repoDir: string;
+  let filePath: string;
+  let ctx: ToolContext;
+
+  beforeEach(async () => {
+    repoDir = await fs.mkdtemp(path.join(os.tmpdir(), "aria-frg-merge-"));
+    await fs.mkdir(path.join(repoDir, ".git"));
+    filePath = path.join(repoDir, "a.ts");
+    await fs.writeFile(filePath, 'export const version = "old";\n', "utf8");
+    clearPendingFrgMutations(repoDir);
+    ctx = {
+      workingDir: repoDir,
+      env: {},
+      confirm: async () => true,
+    };
+    await executeFrg({ command: "init", path: repoDir }, ctx);
+    await executeFrg({ command: "index", path: repoDir }, ctx);
+  });
+
+  afterEach(() => {
+    clearPendingFrgMutations(repoDir);
+  });
+
+  it("shadows indexed matches for mutated files with session delta matches", async () => {
+    const updatedContent = 'export const version = "new";\n';
+    await fs.writeFile(filePath, updatedContent, "utf8");
+    recordFrgMutation(filePath, "write", updatedContent);
+
+    const result = await executeFrg({ command: "search", path: repoDir, pattern: "version" }, ctx);
+    expect(result.success).toBe(true);
+    const data = result.data as { matches?: Array<{ file: string; content: string }> };
+    const matches = data.matches ?? [];
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches.every((match) => match.file === "a.ts")).toBe(true);
+    expect(matches.some((match) => match.content.includes("new"))).toBe(true);
+    expect(matches.some((match) => match.content.includes("old"))).toBe(false);
+  });
+
+  it("shadows indexed files/counts for mutated files", async () => {
+    const updatedContent = 'export const changed = "yes";\nexport const changedAgain = "yes";\n';
+    await fs.writeFile(filePath, updatedContent, "utf8");
+    recordFrgMutation(filePath, "write", updatedContent);
+
+    const filesOnly = await executeFrg(
+      { command: "search", path: repoDir, pattern: "changed", filesOnly: true },
+      ctx,
+    );
+    expect(filesOnly.success).toBe(true);
+    const files = (filesOnly.data as { files?: string[] }).files ?? [];
+    expect(files).toEqual(["a.ts"]);
+
+    const counts = await executeFrg(
+      { command: "search", path: repoDir, pattern: "changed", count: true },
+      ctx,
+    );
+    expect(counts.success).toBe(true);
+    const countRows =
+      (counts.data as { counts?: Array<{ file: string; count: number }> }).counts ?? [];
+    expect(countRows).toEqual([{ file: "a.ts", count: 2 }]);
+  });
+});