@coreyuan/vector-mind 1.0.30 → 1.0.35

package/dist/index.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import * as readline from "node:readline";
 import crypto from "node:crypto";
 import os from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 import Database from "better-sqlite3";
@@ -13,9 +14,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
-import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.30";
+const SERVER_VERSION = "1.0.35";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -64,6 +65,11 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+const RIPGREP_RESOLVE_TIMEOUT_MS = 5_000;
+const RIPGREP_SEARCH_TIMEOUT_MS = 30_000;
+const RIPGREP_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+let cachedRipgrepCommand;
+let cachedRipgrepResolveError = null;
 function getCodexHomeDir() {
     const raw = process.env.CODEX_HOME?.trim();
     if (raw)
@@ -253,7 +259,7 @@ function summarizeActivityEvent(e) {
         case "semantic_search":
             return `semantic_search mode=${String(d.mode ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
         case "grep":
-            return `grep q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
+            return `grep backend=${String(d.backend ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "query_codebase":
             return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
         case "read_file_lines":
@@ -505,6 +511,22 @@ const IGNORED_PATH_SEGMENTS = new Set([
     "x64",
     "x86",
 ].map((s) => s.toLowerCase()));
+const NOISE_FILE_SUFFIXES = [
+    ".min.js",
+    ".min.css",
+    ".bundle.js",
+    ".bundle.css",
+    ".chunk.js",
+    ".chunk.css",
+];
+const NOISE_FILE_BASENAMES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+];
 const IGNORED_LIKE_PATTERNS = (() => {
     const patterns = [];
     for (const seg of IGNORED_PATH_SEGMENTS) {
@@ -608,27 +630,11 @@ function pruneIgnoredIndexesByPathPatterns() {
 function pruneFilenameNoiseIndexes() {
     if (!db)
         return { chunks_deleted: 0, symbols_deleted: 0 };
-    const suffixes = [
-        ".min.js",
-        ".min.css",
-        ".bundle.js",
-        ".bundle.css",
-        ".chunk.js",
-        ".chunk.css",
-    ];
-    const baseNames = [
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ];
     try {
-        const suffixWhere = suffixes.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const baseWhere = baseNames.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const suffixArgs = suffixes.map((s) => `%${s}`);
-        const baseArgs = baseNames.map((n) => `%/${n}`);
+        const suffixWhere = NOISE_FILE_SUFFIXES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const baseWhere = NOISE_FILE_BASENAMES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const suffixArgs = NOISE_FILE_SUFFIXES.map((s) => `%${s}`);
+        const baseArgs = NOISE_FILE_BASENAMES.map((n) => `%/${n}`);
         const whereParts = [];
         const args = [];
         if (suffixWhere) {
@@ -710,21 +716,9 @@ function isSymbolIndexableFile(filePath) {
 }
 function shouldIgnoreContentFile(filePath) {
     const base = path.basename(filePath).toLowerCase();
-    const ignoreNames = new Set([
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ]);
-    if (ignoreNames.has(base))
-        return true;
-    if (base.endsWith(".min.js") || base.endsWith(".min.css"))
-        return true;
-    if (base.endsWith(".bundle.js") || base.endsWith(".bundle.css"))
+    if (NOISE_FILE_BASENAMES.includes(base))
         return true;
-    if (base.endsWith(".chunk.js") || base.endsWith(".chunk.css"))
+    if (NOISE_FILE_SUFFIXES.some((suffix) => base.endsWith(suffix)))
         return true;
     return false;
 }
@@ -1175,13 +1169,14 @@ const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
     // If case_sensitive is omitted and smart_case=true, uppercase => case-sensitive, otherwise case-insensitive.
     smart_case: z.boolean().optional().default(true),
     case_sensitive: z.boolean().optional(),
-    // Optional hint used to narrow candidates quickly when mode=regex and the pattern has few literals.
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     literal_hint: z.string().optional().default(""),
-    // Defaults to code/doc chunks; can be widened if needed.
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     kinds: z.array(z.string().min(1)).optional(),
     include_paths: z.array(z.string().min(1)).optional(),
     exclude_paths: z.array(z.string().min(1)).optional(),
     max_results: z.number().int().min(1).max(5000).optional().default(200),
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     max_candidates: z.number().int().min(1).max(50_000).optional(),
 }));
 const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
@@ -1922,6 +1917,385 @@ function compileGrepRegex(opts) {
     const source = opts.mode === "literal" ? escapeRegExp(opts.query) : opts.query;
     return new RegExp(source, flags);
 }
+function trimGrepText(input, maxChars) {
+    if (input.length <= maxChars)
+        return input;
+    return `${input.slice(0, maxChars)}…`;
+}
+function buildGrepPreviewSnippet(lineText, col, maxChars = 500) {
+    const clean = lineText.replace(/\r$/, "");
+    if (clean.length <= maxChars)
+        return clean;
+    const matchIndex = Math.max(0, col - 1);
+    let start = Math.max(0, matchIndex - Math.floor(maxChars * 0.35));
+    if (start + maxChars > clean.length)
+        start = Math.max(0, clean.length - maxChars);
+    const end = Math.min(clean.length, start + maxChars);
+    let snippet = clean.slice(start, end);
+    if (start > 0)
+        snippet = `…${snippet}`;
+    if (end < clean.length)
+        snippet = `${snippet}…`;
+    return snippet;
+}
+function extractGrepMatchText(opts) {
+    const clean = opts.lineText.replace(/\r$/, "");
+    const startIndex = Math.max(0, opts.col - 1);
+    if (opts.mode === "literal") {
+        const slice = clean.slice(startIndex, startIndex + opts.query.length) || opts.query;
+        return trimGrepText(slice, 200);
+    }
+    try {
+        const flags = opts.caseSensitive ? "m" : "im";
+        const anchored = new RegExp(opts.query, flags);
+        const tail = clean.slice(startIndex);
+        const found = anchored.exec(tail);
+        if (found?.index === 0 && found[0])
+            return trimGrepText(found[0], 200);
+    }
+    catch { }
+    const fallback = clean.slice(startIndex, Math.min(clean.length, startIndex + 200));
+    return trimGrepText(fallback || opts.query, 200);
+}
+function toProcessText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    return value.toString("utf8");
+}
+function formatProcessFailure(result) {
+    if (result.error)
+        return `${result.error.name}: ${result.error.message}`;
+    const stderr = toProcessText(result.stderr).trim();
+    if (stderr)
+        return stderr;
+    const stdout = toProcessText(result.stdout).trim();
+    if (stdout)
+        return stdout;
+    if (typeof result.status === "number")
+        return `exit ${result.status}`;
+    if (result.signal)
+        return `signal ${result.signal}`;
+    return "unknown failure";
+}
+function buildRipgrepEnv() {
+    const env = { ...process.env };
+    delete env.RIPGREP_CONFIG_PATH;
+    return env;
+}
+function pushUniqueCandidate(candidates, seen, raw) {
+    const value = raw?.trim();
+    if (!value || seen.has(value))
+        return;
+    seen.add(value);
+    candidates.push(value);
+}
+function listChildDirsSafe(dirPath) {
+    try {
+        return fs
+            .readdirSync(dirPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(dirPath, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+function collectRipgrepCandidates() {
+    const candidates = [];
+    const seen = new Set();
+    const override = process.env.VECTORMIND_RG_PATH?.trim();
+    if (override)
+        pushUniqueCandidate(candidates, seen, path.resolve(override));
+    if (process.platform === "win32") {
+        pushUniqueCandidate(candidates, seen, "rg.exe");
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    else {
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    for (const rawDir of (process.env.PATH ?? "").split(path.delimiter)) {
+        const dir = rawDir.trim().replace(/^"+|"+$/g, "");
+        if (!dir)
+            continue;
+        if (process.platform === "win32") {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg.exe"));
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+        else {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        const programsDir = localAppData ? path.join(localAppData, "Programs") : "";
+        if (programsDir && fs.existsSync(programsDir)) {
+            for (const appDir of listChildDirsSafe(programsDir)) {
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "extensions", "kiro.kiro-agent", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                for (const childDir of listChildDirsSafe(appDir)) {
+                    pushUniqueCandidate(candidates, seen, path.join(childDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                }
+            }
+        }
+    }
+    return candidates;
+}
+function resolveRipgrepCommand() {
+    if (typeof cachedRipgrepCommand !== "undefined") {
+        if (cachedRipgrepCommand)
+            return { ok: true, command: cachedRipgrepCommand };
+        return { ok: false, error: cachedRipgrepResolveError ?? "ripgrep unavailable", attempts: [] };
+    }
+    const env = buildRipgrepEnv();
+    const attempts = [];
+    for (const candidate of collectRipgrepCandidates()) {
+        const probe = spawnSync(candidate, ["--version"], {
+            cwd: projectRoot || undefined,
+            env,
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: RIPGREP_RESOLVE_TIMEOUT_MS,
+            maxBuffer: 256 * 1024,
+        });
+        if (probe.status === 0) {
+            cachedRipgrepCommand = candidate;
+            cachedRipgrepResolveError = null;
+            return { ok: true, command: candidate };
+        }
+        attempts.push(`${candidate}: ${formatProcessFailure(probe)}`);
+    }
+    cachedRipgrepCommand = null;
+    cachedRipgrepResolveError = attempts.slice(0, 8).join(" | ") || "ripgrep unavailable";
+    return { ok: false, error: cachedRipgrepResolveError, attempts };
+}
+function appendBuiltInRipgrepExcludes(args) {
+    for (const segment of IGNORED_PATH_SEGMENTS) {
+        args.push("-g", `!${segment}/**`);
+        args.push("-g", `!**/${segment}/**`);
+    }
+    for (const baseName of NOISE_FILE_BASENAMES) {
+        args.push("-g", `!**/${baseName}`);
+    }
+    for (const suffix of NOISE_FILE_SUFFIXES) {
+        args.push("-g", `!**/*${suffix}`);
+    }
+}
+function runRipgrepSearch(opts) {
+    const resolved = resolveRipgrepCommand();
+    if (!resolved.ok) {
+        return { ok: false, unavailable: true, error: resolved.error, attempts: resolved.attempts };
+    }
+    const args = ["--vimgrep", "--no-heading", "--color", "never", "-m", String(opts.maxResults)];
+    args.push(opts.caseSensitive ? "-s" : "-i");
+    if (opts.mode === "literal")
+        args.push("-F");
+    appendBuiltInRipgrepExcludes(args);
+    args.push("--", opts.query, ".");
+    const result = spawnSync(resolved.command, args, {
+        cwd: projectRoot,
+        env: buildRipgrepEnv(),
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: RIPGREP_SEARCH_TIMEOUT_MS,
+        maxBuffer: RIPGREP_MAX_BUFFER_BYTES,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: result.status,
+        };
+    }
+    const status = result.status ?? 0;
+    if (status !== 0 && status !== 1) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: status,
+        };
+    }
+    const matches = [];
+    let totalMatches = 0;
+    let truncated = false;
+    for (const rawLine of toProcessText(result.stdout).split(/\r?\n/)) {
+        if (!rawLine)
+            continue;
+        const parsed = /^(.*?):(\d+):(\d+):(.*)$/.exec(rawLine);
+        if (!parsed)
+            continue;
+        const filePath = path.posix
+            .normalize(parsed[1].replace(/\\/g, "/"))
+            .replace(/^\.\/+/, "");
+        const lineNumber = Number.parseInt(parsed[2] ?? "0", 10);
+        const colNumber = Number.parseInt(parsed[3] ?? "0", 10);
+        const lineText = (parsed[4] ?? "").replace(/\r$/, "");
+        if (!filePath || !Number.isFinite(lineNumber) || !Number.isFinite(colNumber))
+            continue;
+        if (shouldIgnoreDbFilePath(filePath))
+            continue;
+        if (shouldIgnoreContentFile(filePath))
+            continue;
+        if (!passesPathFilters(filePath, opts.includePaths, opts.excludePaths))
+            continue;
+        totalMatches += 1;
+        if (matches.length >= opts.maxResults) {
+            truncated = true;
+            continue;
+        }
+        matches.push({
+            file_path: filePath,
+            kind: "file_match",
+            line: lineNumber,
+            col: colNumber,
+            preview: buildGrepPreviewSnippet(lineText, colNumber),
+            match: extractGrepMatchText({
+                lineText,
+                query: opts.query,
+                mode: opts.mode,
+                caseSensitive: opts.caseSensitive,
+                col: colNumber,
+            }),
+        });
+    }
+    return {
+        ok: true,
+        backend: "ripgrep",
+        rg_command: resolved.command,
+        matches,
+        truncated,
+        total_matches: totalMatches,
+    };
+}
+function runIndexedGrepSearch(opts) {
+    const hint = (() => {
+        if (opts.mode === "literal")
+            return opts.query;
+        const explicit = opts.literalHint.trim();
+        if (explicit)
+            return explicit;
+        return extractLongestLiteralFromRegex(opts.query);
+    })();
+    if (opts.mode === "regex" && hint.trim().length < 3) {
+        throw new Error("Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.");
+    }
+    let re;
+    try {
+        re = compileGrepRegex({
+            query: opts.query,
+            mode: opts.mode,
+            caseSensitive: opts.caseSensitive,
+        });
+    }
+    catch (err) {
+        throw new Error(`Invalid pattern: ${String(err)}`);
+    }
+    const maxCandidates = opts.maxCandidates ?? Math.min(50_000, Math.max(1000, opts.maxResults * 200));
+    const candidates = (() => {
+        if (ftsAvailable) {
+            const matchQuery = buildFtsMatchQuery(hint);
+            const placeholders = opts.kinds.map(() => "?").join(", ");
+            const stmt = db.prepare(`
+        SELECT
+          m.id as id,
+          m.kind as kind,
+          m.content as content,
+          m.file_path as file_path,
+          m.start_line as start_line,
+          m.end_line as end_line
+        FROM ${FTS_TABLE_NAME}
+        JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
+        WHERE ${FTS_TABLE_NAME} MATCH ?
+          AND m.kind IN (${placeholders})
+        ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
+        LIMIT ?
+      `);
+            return stmt.all(matchQuery, ...opts.kinds, maxCandidates);
+        }
+        const needle = opts.mode === "literal" ? opts.query : hint;
+        const escaped = escapeLike(needle);
+        const like = `%${escaped}%`;
+        const placeholders = opts.kinds.map(() => "?").join(", ");
+        const stmt = db.prepare(`
+      SELECT
+        id,
+        kind,
+        content,
+        file_path,
+        start_line,
+        end_line
+      FROM memory_items
+      WHERE content LIKE ? ESCAPE '\\'
+        AND kind IN (${placeholders})
+      ORDER BY file_path ASC, start_line ASC, id ASC
+      LIMIT ?
+    `);
+        return stmt.all(like, ...opts.kinds, maxCandidates);
+    })();
+    const matches = [];
+    let candidatesScanned = 0;
+    let truncated = false;
+    for (const c of candidates) {
+        candidatesScanned += 1;
+        if (!c.file_path || c.start_line == null)
+            continue;
+        if (shouldIgnoreDbFilePath(c.file_path))
+            continue;
+        if (!passesPathFilters(c.file_path, opts.includePaths, opts.excludePaths))
+            continue;
+        const content = c.content ?? "";
+        const lineStarts = buildLineStarts(content);
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const idx = m.index ?? 0;
+            const matched = m[0] ?? "";
+            if (!matched) {
+                if (re.lastIndex >= content.length)
+                    break;
+                re.lastIndex += 1;
+                continue;
+            }
+            const lineIdx = lineIndexForOffset(lineStarts, idx);
+            const lineStart = lineStarts[lineIdx] ?? 0;
+            const lineEnd = lineIdx + 1 < lineStarts.length
+                ? (lineStarts[lineIdx + 1] ?? content.length) - 1
+                : content.length;
+            const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
+            matches.push({
+                file_path: c.file_path,
+                kind: c.kind,
+                line: c.start_line + lineIdx,
+                col: idx - lineStart + 1,
+                preview: trimGrepText(previewRaw, 500),
+                match: trimGrepText(matched, 200),
+            });
+            if (matches.length >= opts.maxResults) {
+                truncated = true;
+                break;
+            }
+        }
+        if (truncated)
+            break;
+    }
+    return {
+        backend: "indexed_fallback",
+        hint,
+        kinds: opts.kinds,
+        include_paths: opts.includePaths ?? [],
+        exclude_paths: opts.excludePaths ?? [],
+        candidates: { total: candidates.length, scanned: candidatesScanned },
+        matches,
+        truncated,
+    };
+}
 function resolveProjectPathUnderRoot(inputPath, opts = {}) {
     const normalizedInput = inputPath.trim() || ".";
     const abs = path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput);
@@ -2150,16 +2524,31 @@ function buildServerInstructions() {
         "Built-in architecture and code-organization policy:",
         BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
         "",
+        "Built-in low-overhead execution and heavy-thread policy:",
+        BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS,
+        "",
+        "Built-in payload / oversized-thread guard policy:",
+        BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS,
+        "",
+        "Built-in thread handoff / switch-gate policy:",
+        BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS,
+        "",
         "Required workflow:",
-        "- On every new conversation/session: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
+        "- On every new conversation/session for analysis/design/development work: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
         "  - Output is compact by default. Use include_content=true only when you truly need full text (it increases tokens).",
         "  - Tune output size with: requirements_limit/changes_limit/notes_limit, preview_chars, pending_limit/pending_offset.",
         "  - Prefer read_memory_item(id, offset, limit) to fetch full text on demand instead of returning large content in other tool outputs.",
+        "- For pure execution-first tasks with explicit targets (for example compile/build/run/launch/package/publish/test rerun), you may skip retrieval and go straight to the minimum necessary shell or host tools unless code/context lookup is actually needed to unblock execution.",
         "- To read local Codex skill/prompt/rule files (for example SKILL.md under CODEX_HOME or AGENTS_HOME), prefer read_codex_text_file({ path }) instead of assuming a filesystem MCP resource server exists.",
         "- For project file/directory browsing, prefer list_project_files({ path, recursive?, max_depth? }) over shelling out to Get-ChildItem/ls. It respects ignore rules and keeps output bounded.",
         "- For small/medium raw file reads, prefer read_file_text({ path, offset?, max_chars? }) over Get-Content -Raw. Use read_file_lines(...) when you need deterministic line ranges or the file may be large.",
-        "- For an rg/Select-String-style search with exact file+line+col matches, prefer grep({ query: <pattern> }) over shelling out (uses the indexed code/doc chunks).",
+        "- For raw repo text search with exact file+line+col matches, prefer grep({ query: <pattern> }). It uses ripgrep against real project files when available, applies built-in noise filters, and only falls back to indexed search if ripgrep is unavailable.",
         "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
+        "- If the current thread is heavy, recently compacted, has become slow, or has already hit a 413 / Payload Too Large style error, switch to payload guard mode: avoid unbounded shell dumps, prefer bounded MCP tools, and summarize outputs instead of pasting large raw blocks.",
+        "- In payload guard mode, do not use full-repo recursive listings, whole-file dumps, or broad raw match echo unless the user explicitly requests that raw output and accepts the size risk.",
+        "- Thread-switch judgment must not rely on a fixed token threshold; use observable signals plus the weight of the upcoming work. If the current thread is heavy, repeatedly compacting, slow, or has already hit a 413 / Payload Too Large style error and the next work still needs broad analysis, cross-module investigation, release validation, or other substantial continuation, pause once and ask whether to switch to a fresh thread before continuing.",
+        "- If the user declines that switch, continue in the current thread and do not raise the thread-switch reminder again in the same session.",
+        "- If the user accepts and the host cannot create a new top-level thread automatically, output the fixed THREAD_HANDOFF_PACK template plus the fixed copy-ready first message for the new thread instead of dumping raw history or the last N chat turns.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
@@ -2167,6 +2556,7 @@ function buildServerInstructions() {
         "- When you need full text for a specific note/summary/match: call read_memory_item(id, offset, limit) and page through it.",
         "- When asked to locate code (class/function/type): call query_codebase(query) instead of guessing.",
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
+        "- If the current thread is already heavy or the user reports it has become slow, switch to a lighter workflow: avoid redundant retrieval, keep outputs compact, and if the user refuses thread switching, continue in light mode without repeating the switch reminder in that same session.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
     ].join("\n");
@@ -2732,7 +3122,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "grep",
-                description: "Fast indexed grep across code/doc chunks with precise file/line/col matches. Prefer this over shelling out to rg/Select-String when possible.",
+                description: "Repo text search with precise file/line/col matches, powered by ripgrep against real project files plus built-in noise filters. Falls back to indexed search only when ripgrep is unavailable.",
                 inputSchema: toJsonSchemaCompat(GrepArgsSchema),
             },
             {
@@ -3434,15 +3824,53 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const includePaths = args.include_paths?.length ? args.include_paths : null;
             const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
             const maxResults = args.max_results;
-            const hint = (() => {
-                if (mode === "literal")
-                    return q;
-                const explicit = args.literal_hint.trim();
-                if (explicit)
-                    return explicit;
-                return extractLongestLiteralFromRegex(q);
-            })();
-            if (mode === "regex" && hint.trim().length < 3) {
+            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
+            const ripgrepResult = runRipgrepSearch({
+                query: q,
+                mode,
+                smartCase,
+                caseSensitive,
+                includePaths,
+                excludePaths,
+                maxResults,
+            });
+            if (ripgrepResult.ok) {
+                logActivity("grep", {
+                    backend: ripgrepResult.backend,
+                    rg_command: ripgrepResult.rg_command,
+                    query: q,
+                    mode,
+                    case_sensitive: caseSensitive,
+                    smart_case: smartCase,
+                    include_paths: includePaths ?? [],
+                    exclude_paths: excludePaths ?? [],
+                    matches: ripgrepResult.matches.length,
+                    total_matches: ripgrepResult.total_matches,
+                    truncated: ripgrepResult.truncated,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: true,
+                                backend: ripgrepResult.backend,
+                                rg_command: ripgrepResult.rg_command,
+                                query: q,
+                                mode,
+                                case_sensitive: caseSensitive,
+                                smart_case: smartCase,
+                                include_paths: includePaths ?? [],
+                                exclude_paths: excludePaths ?? [],
+                                matches: ripgrepResult.matches,
+                                total_matches: ripgrepResult.total_matches,
+                                truncated: ripgrepResult.truncated,
+                            }),
+                        },
+                    ],
+                };
+            }
+            if (!ripgrepResult.unavailable) {
                 return {
                     isError: true,
                     content: [
@@ -3450,19 +3878,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             type: "text",
                             text: toolJson({
                                 ok: false,
-                                error: "Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.",
+                                backend: "ripgrep",
+                                error: ripgrepResult.error,
+                                rg_command: ripgrepResult.rg_command,
+                                exit_status: ripgrepResult.exit_status,
                                 query: q,
                                 mode,
-                                literal_hint: args.literal_hint,
                             }),
                         },
                     ],
                 };
             }
-            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
-            let re;
+            let indexedResult;
             try {
-                re = compileGrepRegex({ query: q, mode, caseSensitive });
+                indexedResult = runIndexedGrepSearch({
+                    query: q,
+                    mode,
+                    smartCase,
+                    caseSensitive,
+                    literalHint: args.literal_hint,
+                    kinds,
+                    includePaths,
+                    excludePaths,
+                    maxResults,
+                    maxCandidates: args.max_candidates,
+                });
             }
             catch (err) {
                 return {
@@ -3470,114 +3910,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: toolJson({ ok: false, error: `Invalid pattern: ${String(err)}`, query: q, mode }),
+                            text: toolJson({
+                                ok: false,
+                                backend: "indexed_fallback",
+                                fallback_reason: "ripgrep_unavailable",
+                                ripgrep_error: ripgrepResult.error,
+                                ripgrep_attempts: ripgrepResult.attempts,
+                                error: String(err),
+                                query: q,
+                                mode,
+                                literal_hint: args.literal_hint,
+                            }),
                         },
                     ],
                 };
             }
-            const maxCandidates = args.max_candidates ?? Math.min(50_000, Math.max(1000, maxResults * 200));
-            const candidates = (() => {
-                if (ftsAvailable) {
-                    const matchQuery = buildFtsMatchQuery(hint);
-                    const placeholders = kinds.map(() => "?").join(", ");
-                    const stmt = db.prepare(`
-            SELECT
-              m.id as id,
-              m.kind as kind,
-              m.content as content,
-              m.file_path as file_path,
-              m.start_line as start_line,
-              m.end_line as end_line
-            FROM ${FTS_TABLE_NAME}
-            JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
-            WHERE ${FTS_TABLE_NAME} MATCH ?
-              AND m.kind IN (${placeholders})
-            ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
-            LIMIT ?
-          `);
-                    return stmt.all(matchQuery, ...kinds, maxCandidates);
-                }
-                const needle = mode === "literal" ? q : hint;
-                const escaped = escapeLike(needle);
-                const like = `%${escaped}%`;
-                const placeholders = kinds.map(() => "?").join(", ");
-                const stmt = db.prepare(`
-          SELECT
-            id,
-            kind,
-            content,
-            file_path,
-            start_line,
-            end_line
-          FROM memory_items
-          WHERE content LIKE ? ESCAPE '\\'
-            AND kind IN (${placeholders})
-          ORDER BY file_path ASC, start_line ASC, id ASC
-          LIMIT ?
-        `);
-                return stmt.all(like, ...kinds, maxCandidates);
-            })();
-            const matches = [];
-            let candidatesScanned = 0;
-            let truncated = false;
-            for (const c of candidates) {
-                candidatesScanned += 1;
-                if (!c.file_path || c.start_line == null)
-                    continue;
-                if (shouldIgnoreDbFilePath(c.file_path))
-                    continue;
-                if (!passesPathFilters(c.file_path, includePaths, excludePaths))
-                    continue;
-                const content = c.content ?? "";
-                const lineStarts = buildLineStarts(content);
-                re.lastIndex = 0;
-                let m;
-                while ((m = re.exec(content)) !== null) {
-                    const idx = m.index ?? 0;
-                    const matched = m[0] ?? "";
-                    if (!matched) {
-                        if (re.lastIndex >= content.length)
-                            break;
-                        re.lastIndex += 1;
-                        continue;
-                    }
-                    const lineIdx = lineIndexForOffset(lineStarts, idx);
-                    const lineStart = lineStarts[lineIdx] ?? 0;
-                    const lineEnd = lineIdx + 1 < lineStarts.length
-                        ? (lineStarts[lineIdx + 1] ?? content.length) - 1
-                        : content.length;
-                    const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
-                    const preview = previewRaw.length > 500 ? `${previewRaw.slice(0, 500)}…` : previewRaw;
-                    const matchText = matched.length > 200 ? `${matched.slice(0, 200)}…` : matched;
-                    matches.push({
-                        file_path: c.file_path,
-                        kind: c.kind,
-                        line: c.start_line + lineIdx,
-                        col: idx - lineStart + 1,
-                        preview,
-                        match: matchText,
-                    });
-                    if (matches.length >= maxResults) {
-                        truncated = true;
-                        break;
-                    }
-                }
-                if (truncated)
-                    break;
-            }
             logActivity("grep", {
+                backend: indexedResult.backend,
+                fallback_reason: "ripgrep_unavailable",
+                ripgrep_error: ripgrepResult.error,
                 query: q,
                 mode,
                 case_sensitive: caseSensitive,
                 smart_case: smartCase,
-                hint,
+                hint: indexedResult.hint,
                 kinds,
                 include_paths: includePaths ?? [],
                 exclude_paths: excludePaths ?? [],
-                candidates: candidates.length,
-                candidates_scanned: candidatesScanned,
-                matches: matches.length,
-                truncated,
+                candidates: indexedResult.candidates.total,
+                candidates_scanned: indexedResult.candidates.scanned,
+                matches: indexedResult.matches.length,
+                truncated: indexedResult.truncated,
             });
             return {
                 content: [
@@ -3585,17 +3948,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         type: "text",
                         text: toolJson({
                             ok: true,
+                            backend: indexedResult.backend,
+                            fallback_reason: "ripgrep_unavailable",
+                            ripgrep_error: ripgrepResult.error,
+                            ripgrep_attempts: ripgrepResult.attempts,
                             query: q,
                             mode,
                             case_sensitive: caseSensitive,
                             smart_case: smartCase,
-                            hint,
+                            hint: indexedResult.hint,
                             kinds,
                             include_paths: includePaths ?? [],
                             exclude_paths: excludePaths ?? [],
-                            candidates: { total: candidates.length, scanned: candidatesScanned },
-                            matches,
-                            truncated,
+                            candidates: indexedResult.candidates,
+                            matches: indexedResult.matches,
+                            truncated: indexedResult.truncated,
                         }),
                     },
                 ],