stagent 0.9.6 → 0.11.0

package/src/lib/chat/dismissals.ts

@@ -0,0 +1,73 @@
+export const DISMISSAL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface DismissalStore {
+  read(): string | null;
+  write(value: string): void;
+}
+
+export type DismissalMap = Record<string, Record<string, number>>;
+
+export function loadDismissals(store: DismissalStore): DismissalMap {
+  const raw = store.read();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as DismissalMap;
+  } catch {
+    // corrupt — fall through
+  }
+  return {};
+}
+
+export function saveDismissal(
+  store: DismissalStore,
+  conversationId: string,
+  skillId: string,
+  nowMs: number = Date.now()
+): void {
+  const current = loadDismissals(store);
+  current[conversationId] = current[conversationId] ?? {};
+  current[conversationId][skillId] = nowMs;
+  try {
+    store.write(JSON.stringify(current));
+  } catch {
+    // silent — in-memory state won't persist
+  }
+}
+
+export function activeDismissedIds(
+  store: DismissalStore,
+  conversationId: string,
+  nowMs: number = Date.now()
+): Set<string> {
+  const all = loadDismissals(store);
+  const conv = all[conversationId];
+  if (!conv) return new Set();
+  const out = new Set<string>();
+  for (const [skillId, ts] of Object.entries(conv)) {
+    if (nowMs - ts < DISMISSAL_TTL_MS) out.add(skillId);
+  }
+  return out;
+}
+
+/** Browser store adapter around localStorage for a given key. */
+export function browserLocalStore(key: string): DismissalStore {
+  return {
+    read() {
+      if (typeof window === "undefined") return null;
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    write(value) {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(key, value);
+      } catch {
+        // quota / disabled — silent
+      }
+    },
+  };
+}

package/src/lib/chat/engine.ts

@@ -3,7 +3,12 @@ import { db } from "@/lib/db";
 import { projects, chatMessages } from "@/lib/db/schema";
 import { eq } from "drizzle-orm";
 import { getAuthEnv } from "@/lib/settings/auth";
-import { buildClaudeSdkEnv } from "@/lib/agents/runtime/claude-sdk";
+import {
+  buildClaudeSdkEnv,
+  CLAUDE_SDK_SETTING_SOURCES,
+  CLAUDE_SDK_ALLOWED_TOOLS,
+  CLAUDE_SDK_READ_ONLY_FS_TOOLS,
+} from "@/lib/agents/runtime/claude-sdk";
 import {
   extractUsageSnapshot,
   mergeUsageSnapshot,
@@ -21,6 +26,9 @@ import {
   updateConversation,
 } from "@/lib/data/chat";
 import { buildChatContext, type MentionReference } from "./context-builder";
+import { finalizeStreamingMessage } from "./reconcile";
+import { recordTermination } from "./stream-telemetry";
+import { registerChatStream, unregisterChatStream } from "./active-streams";
 import {
   detectEntities,
   extractToolResultEntities,
@@ -39,7 +47,7 @@ import {
 } from "./permission-bridge";
 import { isToolAllowed } from "@/lib/settings/permissions";
 import { getLaunchCwd, getWorkspaceContext } from "@/lib/environment/workspace-context";
-import { createStagentMcpServer } from "./stagent-tools";
+import { createToolServer } from "./stagent-tools";
 import {
   getBrowserMcpServers,
   getBrowserAllowedToolPatterns,
@@ -50,6 +58,36 @@ import {
   isExaTool,
   isExaReadOnly,
 } from "@/lib/agents/browser-mcp";
+import { resolveChatExecutionTarget } from "@/lib/agents/runtime/execution-target";
+
+// Re-exported from runtime/claude-sdk.ts so chat/engine.ts remains a stable
+// import surface for the Phase 1a test suite. The canonical definitions
+// live in the runtime module since task execution needs them too — see
+// features/task-runtime-skill-parity.md Task 1.
+export {
+  CLAUDE_SDK_SETTING_SOURCES,
+  CLAUDE_SDK_ALLOWED_TOOLS,
+  CLAUDE_SDK_READ_ONLY_FS_TOOLS,
+} from "@/lib/agents/runtime/claude-sdk";
+
+/**
+ * Pure auto-allow policy for SDK filesystem + Skill tools. Exposed for tests.
+ * Returns `{ behavior: "allow" }` for auto-allowed tools, or
+ * `{ behavior: "pending" }` to signal "route through permission flow".
+ * The real canUseTool in query() options uses the full side-channel bridge.
+ */
+export async function canUseToolForTest(
+  toolName: string,
+  _input: Record<string, unknown>
+): Promise<ToolPermissionResponse | { behavior: "pending" }> {
+  if (CLAUDE_SDK_READ_ONLY_FS_TOOLS.has(toolName)) {
+    return { behavior: "allow" };
+  }
+  if (toolName === "Skill") {
+    return { behavior: "allow" };
+  }
+  return { behavior: "pending" };
+}
 
 // ── Streaming input wrapper (required for MCP tools) ─────────────────
 
@@ -148,21 +186,43 @@ export async function* sendMessage(
     return;
   }
 
+  let target;
+  try {
+    target = await resolveChatExecutionTarget({
+      requestedRuntimeId: conversation.runtimeId,
+      requestedModelId: conversation.modelId,
+    });
+  } catch (error) {
+    yield {
+      type: "error",
+      message: error instanceof Error ? error.message : "No chat runtime is available",
+    };
+    return;
+  }
+
+  if (target.fallbackApplied && target.fallbackReason) {
+    yield {
+      type: "status",
+      phase: "runtime_fallback",
+      message: target.fallbackReason,
+    };
+  }
+
   // Route to Codex App Server for OpenAI models
-  if (conversation.runtimeId === "openai-codex-app-server") {
+  if (target.effectiveRuntimeId === "openai-codex-app-server") {
     const { sendCodexMessage } = await import("./codex-engine");
-    yield* sendCodexMessage(conversationId, userContent, signal);
+    yield* sendCodexMessage(conversationId, userContent, signal, target);
     return;
   }
 
   // Route to Ollama for local models
-  if (conversation.runtimeId === "ollama") {
+  if (target.effectiveRuntimeId === "ollama") {
     const { sendOllamaMessage } = await import("./ollama-engine");
     yield* sendOllamaMessage(conversationId, userContent, signal);
     return;
   }
 
-  const runtimeId = conversation.runtimeId;
+  const runtimeId = target.effectiveRuntimeId;
   const providerId = getProviderForRuntime(runtimeId);
 
   // Enforce budget before the turn
@@ -250,6 +310,8 @@ export async function* sendMessage(
     status: "streaming",
   });
 
+  registerChatStream(conversationId);
+
   // Create side channel for canUseTool → SSE bridge communication
   const sideChannel = createSideChannel(conversationId);
 
@@ -272,10 +334,11 @@ export async function* sendMessage(
 
     // Create in-process MCP server for Stagent CRUD tools
     const toolResults: ToolResultCapture[] = [];
-    const stagentServer = createStagentMcpServer(
+    const stagentServer = createToolServer(
       conversation.projectId,
-      (toolName, result) => { toolResults.push({ toolName, result }); }
-    );
+      (toolName, result) => { toolResults.push({ toolName, result }); },
+      projectCwd,
+    ).asMcpServer();
 
     yield { type: "status", phase: "connecting", message: "Connecting to model..." };
 
@@ -295,7 +358,7 @@ export async function* sendMessage(
     const response = query({
       prompt: generatePrompt(fullPrompt),
       options: {
-        model: conversation.modelId || undefined,
+        model: target.effectiveModelId || conversation.modelId || undefined,
         maxTurns,
         abortController,
         includePartialMessages: true,
@@ -307,7 +370,13 @@ export async function* sendMessage(
           if (stderrChunks.length > 50) stderrChunks.shift();
         },
         mcpServers: { stagent: stagentServer, ...browserServers, ...externalServers },
-        allowedTools: ["mcp__stagent__*", ...browserToolPatterns, ...externalToolPatterns],
+        allowedTools: [
+          "mcp__stagent__*",
+          ...browserToolPatterns,
+          ...externalToolPatterns,
+          ...CLAUDE_SDK_ALLOWED_TOOLS,
+        ],
+        settingSources: [...CLAUDE_SDK_SETTING_SOURCES],
         // @ts-expect-error Agent SDK canUseTool types are incomplete — our async handler is compatible at runtime
         canUseTool: async (
           toolName: string,
@@ -364,6 +433,32 @@ export async function* sendMessage(
             // Mutation browser tools fall through to permission check below
           }
 
+          // SDK filesystem read-only tools: auto-allow (mirror browser/exa pattern)
+          if (CLAUDE_SDK_READ_ONLY_FS_TOOLS.has(toolName)) {
+            emitSideChannelEvent(conversationId, {
+              type: "status",
+              phase: "tool_use",
+              message: `Filesystem: ${toolName.toLowerCase()}...`,
+            });
+            return { behavior: "allow", updatedInput: input };
+          }
+
+          // Skill tool: auto-allow. Rationale: the Skill tool loads skills from
+          // ~/.claude/skills/ and .claude/skills/ — the same sources the Claude Code
+          // CLI trusts unconditionally. Any tool the skill subsequently invokes
+          // (Bash, Edit, etc.) goes through this same canUseTool check. The trust
+          // assumption here is identical to using `claude` directly; no new attack
+          // surface is introduced. See: features/chat-claude-sdk-skills.md, Error
+          // & Rescue Registry row "settingSources loads hostile skill".
+          if (toolName === "Skill") {
+            emitSideChannelEvent(conversationId, {
+              type: "status",
+              phase: "tool_use",
+              message: `Skill: ${(input as { skill?: string }).skill ?? "unknown"}...`,
+            });
+            return { behavior: "allow", updatedInput: input };
+          }
+
           const isQuestion = toolName === "AskUserQuestion";
 
           // Layer 1: Check saved user permissions (skip for questions)
@@ -610,7 +705,11 @@ export async function* sendMessage(
 
     // Save usage metadata + quick access links + screenshot attachments
     const metadata = JSON.stringify({
-      modelId: usage.modelId ?? conversation.modelId,
+      modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId,
+      runtimeId,
+      requestedRuntimeId: target.requestedRuntimeId ?? conversation.runtimeId,
+      requestedModelId: target.requestedModelId ?? conversation.modelId,
+      ...(target.fallbackReason ? { fallbackReason: target.fallbackReason } : {}),
       inputTokens: usage.inputTokens,
       outputTokens: usage.outputTokens,
       ...(quickAccess.length > 0 ? { quickAccess } : {}),
@@ -627,7 +726,7 @@ export async function* sendMessage(
       activityType: "chat_turn",
       runtimeId,
       providerId,
-      modelId: usage.modelId ?? conversation.modelId ?? null,
+      modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
       inputTokens: usage.inputTokens ?? null,
       outputTokens: usage.outputTokens ?? null,
       totalTokens: usage.totalTokens ?? null,
@@ -636,6 +735,13 @@ export async function* sendMessage(
       finishedAt: new Date(),
     });
 
+    recordTermination({
+      reason: "stream.completed",
+      conversationId,
+      messageId: assistantMsg.id,
+      durationMs: Date.now() - startedAt.getTime(),
+    });
+
     yield {
       type: "done",
       messageId: assistantMsg.id,
@@ -647,7 +753,27 @@ export async function* sendMessage(
 
     // Enrich the error with stderr diagnostics when available
     const stderrTail = stderrChunks.join("").trim();
-    const errorMessage = diagnoseProcessError(rawMessage, stderrTail);
+    const rawErrorMessage = diagnoseProcessError(rawMessage, stderrTail);
+    // Truncate at 4KB to prevent multi-MB stderr dumps bloating chat_messages
+    const errorMessage =
+      rawErrorMessage.length > 4096
+        ? rawErrorMessage.slice(0, 4096) + "... (truncated)"
+        : rawErrorMessage;
+
+    // Telemetry: record BEFORE the yield below. If this code is reached
+    // via iterator abandonment (consumer broke the for-await and the
+    // generator's own yield throws GeneratorReturn), control would skip
+    // past any post-yield statement. Recording up front guarantees the
+    // event lands in the ring buffer regardless of whether the yield
+    // completes or aborts. Matches the same invariant we rely on for
+    // the success-path recordTermination before the done yield.
+    recordTermination({
+      reason: signal?.aborted ? "stream.aborted.signal" : "stream.finalized.error",
+      conversationId,
+      messageId: assistantMsg.id,
+      durationMs: Date.now() - startedAt.getTime(),
+      error: errorMessage.slice(0, 500),
+    });
 
     if (fullText && fullText.length > 50) {
       // Substantial content was already streamed — complete gracefully with warning
@@ -663,7 +789,7 @@ export async function* sendMessage(
         activityType: "chat_turn",
         runtimeId,
         providerId,
-        modelId: usage.modelId ?? conversation.modelId ?? null,
+        modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
         inputTokens: usage.inputTokens ?? null,
         outputTokens: usage.outputTokens ?? null,
         totalTokens: usage.totalTokens ?? null,
@@ -674,10 +800,14 @@ export async function* sendMessage(
 
       yield { type: "done", messageId: assistantMsg.id, quickAccess: [] };
     } else {
-      // No meaningful content — show as error
+      // No meaningful content — show as error. Fallback chain ensures we
+      // never write an empty string even if both fullText and errorMessage
+      // happen to be blank.
       await updateMessageContent(
         assistantMsg.id,
-        fullText || errorMessage
+        fullText ||
+          errorMessage ||
+          "(Response failed — no error detail available.)"
       );
       await updateMessageStatus(assistantMsg.id, "error");
 
@@ -686,7 +816,7 @@ export async function* sendMessage(
         activityType: "chat_turn",
         runtimeId,
         providerId,
-        modelId: usage.modelId ?? conversation.modelId ?? null,
+        modelId: usage.modelId ?? target.effectiveModelId ?? conversation.modelId ?? null,
         inputTokens: usage.inputTokens ?? null,
         outputTokens: usage.outputTokens ?? null,
         totalTokens: usage.totalTokens ?? null,
@@ -698,6 +828,17 @@ export async function* sendMessage(
       yield { type: "error", message: errorMessage };
     }
   } finally {
+    // Safety net: guarantee the placeholder row never remains in
+    // status='streaming' after the generator exits. Catches code paths that
+    // bypass the catch block — most notably async iterator abandonment, where
+    // a consumer `break`ing out of a `for await` loop triggers the generator's
+    // return() method and jumps straight here, skipping catch entirely.
+    try {
+      await finalizeStreamingMessage(assistantMsg.id, fullText);
+    } catch (finalizeErr) {
+      console.error("[chat] finalize safety net failed:", finalizeErr);
+    }
+    unregisterChatStream(conversationId);
     cleanupConversation(conversationId);
   }
 }

package/src/lib/chat/files/__tests__/search.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Hoist mutable state so the mock factories can read it.
+const { mockState } = vi.hoisted(() => ({
+  mockState: {
+    stdout: "" as string,
+    execFileThrows: false as boolean | Error,
+    files: new Map<string, { size: number; mtimeMs: number }>(),
+    realpathMap: new Map<string, string>(),
+  },
+}));
+
+vi.mock("node:child_process", () => {
+  const execFileSync = vi.fn(() => {
+    if (mockState.execFileThrows) {
+      throw mockState.execFileThrows instanceof Error
+        ? mockState.execFileThrows
+        : new Error("git not available");
+    }
+    return mockState.stdout;
+  });
+  return {
+    default: { execFileSync },
+    execFileSync,
+  };
+});
+
+vi.mock("node:fs", () => {
+  const realpathSync = (p: string) => mockState.realpathMap.get(p) ?? p;
+  const statSync = (absPath: string) => {
+    const f = mockState.files.get(absPath);
+    if (!f) throw new Error(`ENOENT: ${absPath}`);
+    return { size: f.size, mtimeMs: f.mtimeMs };
+  };
+  return {
+    default: { realpathSync, statSync },
+    realpathSync,
+    statSync,
+  };
+});
+
+import { searchFiles } from "../search";
+
+// Helper: all test files live under this fake cwd
+const CWD = "/repo";
+
+function file(relPath: string, size: number, mtimeMs: number) {
+  mockState.files.set(`${CWD}/${relPath}`, { size, mtimeMs });
+}
+
+beforeEach(() => {
+  mockState.stdout = "";
+  mockState.execFileThrows = false;
+  mockState.files.clear();
+  mockState.realpathMap.clear();
+  mockState.realpathMap.set(CWD, CWD);
+  vi.clearAllMocks();
+});
+
+describe("searchFiles", () => {
+  it("returns all files when query is empty, mtime-sorted newest first", () => {
+    mockState.stdout = ["src/a.ts", "src/b.ts", "src/c.ts", ""].join("\n");
+    file("src/a.ts", 100, 1_000);
+    file("src/b.ts", 200, 3_000);
+    file("src/c.ts", 300, 2_000);
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/b.ts", "src/c.ts", "src/a.ts"]);
+    expect(hits[0].sizeBytes).toBe(200);
+  });
+
+  it("ranks filename matches above directory-path matches", () => {
+    mockState.stdout = [
+      "src/schema/other.ts", // directory match for "schema"
+      "src/lib/db/schema.ts", // filename match for "schema"
+      ""
+    ].join("\n");
+    file("src/schema/other.ts", 100, 1_000);
+    file("src/lib/db/schema.ts", 100, 500); // older but should still rank first
+
+    const hits = searchFiles(CWD, "schema", 10);
+    expect(hits[0].path).toBe("src/lib/db/schema.ts");
+    expect(hits[1].path).toBe("src/schema/other.ts");
+  });
+
+  it("performs case-insensitive substring match", () => {
+    mockState.stdout = ["src/Foo.TSX", "src/bar.ts", ""].join("\n");
+    file("src/Foo.TSX", 100, 1_000);
+    file("src/bar.ts", 100, 1_000);
+
+    const hits = searchFiles(CWD, "foo", 10);
+    expect(hits).toHaveLength(1);
+    expect(hits[0].path).toBe("src/Foo.TSX");
+  });
+
+  it("respects limit cap", () => {
+    const lines: string[] = [];
+    for (let i = 0; i < 50; i++) {
+      const p = `src/file${i}.ts`;
+      lines.push(p);
+      file(p, 100, i * 10);
+    }
+    mockState.stdout = lines.join("\n");
+
+    const hits = searchFiles(CWD, "", 5);
+    expect(hits).toHaveLength(5);
+  });
+
+  it("returns [] when execFileSync throws (not a git repo)", () => {
+    mockState.execFileThrows = new Error("not a git repository");
+    const hits = searchFiles(CWD, "anything", 10);
+    expect(hits).toEqual([]);
+  });
+
+  it("skips files that disappeared between ls-files and stat", () => {
+    mockState.stdout = ["src/exists.ts", "src/ghost.ts", ""].join("\n");
+    file("src/exists.ts", 100, 1_000);
+    // src/ghost.ts intentionally absent from the files map — statSync throws
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/exists.ts"]);
+  });
+
+  it("excludes files that would resolve outside cwd (defense-in-depth)", () => {
+    // git ls-files should never emit such a path, but if it did we must reject.
+    mockState.stdout = ["../escape.ts", "src/ok.ts", ""].join("\n");
+    // Do NOT register the escape path in files — resolve() would point outside
+    // /repo, and the startsWith check in search.ts will discard it before
+    // statSync is even called.
+    file("src/ok.ts", 100, 1_000);
+
+    const hits = searchFiles(CWD, "", 10);
+    expect(hits.map((h) => h.path)).toEqual(["src/ok.ts"]);
+  });
+});

package/src/lib/chat/files/expand-mention.ts

@@ -0,0 +1,76 @@
+import { realpathSync, statSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Format a single `entityType: "file"` mention for Tier 3.
+ *
+ * Security:
+ *  - `cwd` is resolved by the caller from a trusted source (active project's
+ *    workingDirectory, else `getLaunchCwd()`) — NEVER from the mention itself.
+ *  - The mention's `relPath` is treated as a relative path; any path that
+ *    resolves outside `cwd` is rejected without opening the file.
+ *
+ * Size semantics (matches spec §3 "tiered expansion"):
+ *  - < 8 KB: inline content inside a fenced code block with path header.
+ *  - >= 8 KB and < MAX_SIZE: emit a short reference line so agents with a
+ *    `Read` tool can fetch the file on demand; agents without one degrade
+ *    gracefully ("I can't read large files on this runtime").
+ *  - >= MAX_SIZE (50 MB): skip silently — pathological.
+ *
+ * Non-crashing by design: any read/stat failure becomes a short note in
+ * the output, not a thrown error that would break the whole prompt build.
+ */
+export function expandFileMention(relPath: string, cwd: string): string[] {
+  const lines: string[] = [];
+
+  let cwdReal: string;
+  try {
+    cwdReal = realpathSync(cwd);
+  } catch {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(cwd does not exist)");
+    return lines;
+  }
+
+  const abs = resolve(cwdReal, relPath);
+  if (!abs.startsWith(cwdReal)) {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(invalid path — escapes working directory)");
+    return lines;
+  }
+
+  let stat: { size: number };
+  try {
+    stat = statSync(abs);
+  } catch {
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("(file not found at context-build time)");
+    return lines;
+  }
+
+  const INLINE_LIMIT = 8 * 1024;
+  const MAX_SIZE = 50 * 1024 * 1024;
+  if (stat.size > MAX_SIZE) return []; // skip silently
+
+  if (stat.size < INLINE_LIMIT) {
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf8");
+    } catch {
+      lines.push(`\n### File: ${relPath}`);
+      lines.push("(file could not be read as UTF-8)");
+      return lines;
+    }
+    const ext = relPath.split(".").pop() ?? "";
+    lines.push(`\n### File: ${relPath}`);
+    lines.push("```" + ext);
+    lines.push(content);
+    lines.push("```");
+  } else {
+    lines.push(
+      `\n### File (by reference): ${relPath} (${Math.round(stat.size / 1024)} KB)`
+    );
+    lines.push("Use the Read tool to load this file if you need its content.");
+  }
+  return lines;
+}

package/src/lib/chat/files/search.ts

@@ -0,0 +1,99 @@
+import { execFileSync } from "node:child_process";
+import { statSync, realpathSync } from "node:fs";
+import { resolve, basename } from "node:path";
+
+export interface FileSearchHit {
+  /** Path relative to the resolved cwd. */
+  path: string;
+  sizeBytes: number;
+  /** mtime in epoch ms. */
+  mtime: number;
+}
+
+/**
+ * Return up to `limit` files under `cwd` (respecting .gitignore) whose
+ * path or basename contains `query` (case-insensitive). Filename matches
+ * rank above directory-path matches; secondary sort by mtime desc.
+ *
+ * Uses `git ls-files --cached --others --exclude-standard` to honor
+ * .gitignore natively — matches the subprocess pattern already in use
+ * in `src/lib/environment/workspace-context.ts`. No npm dep required.
+ * Returns [] if `cwd` is not inside a git repo or git is unavailable.
+ *
+ * Security: the caller is responsible for server-resolving `cwd` from
+ * a trusted source (e.g., the active project's workingDirectory or
+ * `getLaunchCwd()`). Never pass a client-controlled path directly.
+ */
+export function searchFiles(
+  cwd: string,
+  query: string,
+  limit = 20
+): FileSearchHit[] {
+  const cwdReal = realpathSync(cwd);
+
+  let stdout: string;
+  try {
+    stdout = execFileSync(
+      "git",
+      ["ls-files", "--cached", "--others", "--exclude-standard"],
+      {
+        cwd: cwdReal,
+        encoding: "utf-8",
+        maxBuffer: 10 * 1024 * 1024,
+        timeout: 3000,
+      }
+    );
+  } catch {
+    // Not a git repo, or git missing, or timeout — degrade to empty list.
+    return [];
+  }
+
+  const q = query.trim().toLowerCase();
+  const hits: Array<FileSearchHit & { score: number }> = [];
+
+  for (const rel of stdout.split("\n")) {
+    if (!rel) continue;
+    // Defensive: ensure the resolved path stays within cwd. `git ls-files`
+    // should never emit such a path, but stat-ing anything outside cwd
+    // would bypass the .gitignore guarantee anyway.
+    const abs = resolve(cwdReal, rel);
+    if (!abs.startsWith(cwdReal)) continue;
+
+    const relLower = rel.toLowerCase();
+    const baseLower = basename(rel).toLowerCase();
+    let score: number;
+    if (q === "") {
+      score = 1;
+    } else if (baseLower.includes(q)) {
+      score = 3;
+    } else if (relLower.includes(q)) {
+      score = 2;
+    } else {
+      continue;
+    }
+
+    let sizeBytes = 0;
+    let mtime = 0;
+    try {
+      const s = statSync(abs);
+      sizeBytes = s.size;
+      mtime = s.mtimeMs;
+    } catch {
+      // File disappeared between ls-files and stat — skip.
+      continue;
+    }
+
+    hits.push({ path: rel, sizeBytes, mtime, score });
+  }
+
+  hits.sort((a, b) => {
+    if (a.score !== b.score) return b.score - a.score;
+    return b.mtime - a.mtime;
+  });
+
+  return hits.slice(0, limit).map(({ path, sizeBytes, mtime }) => ({
+    path,
+    sizeBytes,
+    mtime,
+  }));
+}