@moretea-labs/forge 1.5.1 → 1.7.0

package/src/cli/repository/inspector.ts

@@ -1,12 +1,15 @@
 import { createHash } from 'crypto';
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'fs';
-import { join } from 'path';
+import { execFile } from 'child_process';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'fs';
+import { lstat as lstatAsync, readFile as readFileAsync, readdir as readdirAsync, stat as statAsync } from 'fs/promises';
+import { join, resolve } from 'path';
 import { runProcess } from '../../effects/process-runner';
 import { globMatches, resolveMcpPath } from '../mcp/paths';
 import type { McpPolicy } from '../mcp/types';
 import {
   collectSessionIdentity,
   getOrCreateSessionCache,
+  invalidateSessionCachesForRepository,
   type RepositorySessionCache,
   type SessionIdentity,
 } from './session-cache';
@@ -36,6 +39,8 @@ export interface CachedGitIdentity {
   sampledAt: number;
   head: string | null;
   branch: string | null;
+  /** Dirty state comes from the same porcelain-v2 sample as branch/HEAD. */
+  dirty: boolean;
   workingTreeFingerprint?: string;
 }
 
@@ -76,7 +81,7 @@ function sampleGitIdentity(repoRoot: string): Omit<CachedGitIdentity, 'sampledAt
       timeoutMs: 10_000,
       maxOutputBytes: 4 * 1024 * 1024,
     });
-    if (!result.ok) return { head: null, branch: null };
+    if (!result.ok) return { head: null, branch: null, dirty: false };
 
     let head: string | null = null;
     let branch: string | null = null;
@@ -93,13 +98,43 @@ function sampleGitIdentity(repoRoot: string): Omit<CachedGitIdentity, 'sampledAt
       }
     }
     const status = statusLines.join('\n');
+    let dirtyBytes = 0;
+    const dirtyContentIdentity = statusLines.slice(0, 500).map((line) => {
+      const path = line.startsWith('? ') || line.startsWith('! ')
+        ? line.slice(2)
+        : line.startsWith('1 ')
+          ? line.split(' ').slice(8).join(' ')
+          : line.startsWith('2 ')
+            ? line.split(' ').slice(9).join(' ').split('\t')[0]
+            : line.startsWith('u ')
+              ? line.split(' ').slice(10).join(' ')
+              : '';
+      if (!path) return line;
+      try {
+        const absolute = join(repoRoot, path);
+        const stat = lstatSync(absolute);
+        if (!stat.isFile()) return `${path}:${stat.mode}:${stat.size}:${stat.mtimeMs}`;
+        if (stat.size <= 256 * 1024 && dirtyBytes + stat.size <= 4 * 1024 * 1024) {
+          dirtyBytes += stat.size;
+          return `${path}:${createHash('sha256').update(readFileSync(absolute)).digest('hex')}`;
+        }
+        return `${path}:${stat.size}:${stat.mtimeMs}`;
+      } catch {
+        return `${path}:missing`;
+      }
+    }).join('\n');
     const workingTreeFingerprint = createHash('sha256')
-      .update(`${head ?? ''}\n${branch ?? ''}\n${status}`)
+      .update(`${head ?? ''}\n${branch ?? ''}\n${status}\n${dirtyContentIdentity}`)
       .digest('hex')
       .slice(0, 24);
-    return { head, branch, workingTreeFingerprint: head || status ? workingTreeFingerprint : undefined };
+    return {
+      head,
+      branch,
+      dirty: statusLines.length > 0,
+      workingTreeFingerprint: head || status ? workingTreeFingerprint : undefined,
+    };
   } catch {
-    return { head: null, branch: null };
+    return { head: null, branch: null, dirty: false };
   }
 }
 
@@ -110,18 +145,46 @@ function sampleGitIdentity(repoRoot: string): Omit<CachedGitIdentity, 'sampledAt
  * fingerprint is content-based (stable across reads) and the short TTL window
  * keeps checkout routing safe while real mutations invalidate through markers.
  */
+export function freshGitIdentity(repoRoot: string): CachedGitIdentity {
+  const root = resolve(repoRoot);
+  const sampled = sampleGitIdentity(root);
+  const entry: CachedGitIdentity = { ...sampled, sampledAt: Date.now() };
+  gitIdentityCache.set(root, entry);
+  pruneGitIdentityCache();
+  return entry;
+}
+
 export function cachedGitIdentity(repoRoot: string): CachedGitIdentity {
+  const root = resolve(repoRoot);
   const now = Date.now();
-  const existing = gitIdentityCache.get(repoRoot);
+  const existing = gitIdentityCache.get(root);
   if (existing && now - existing.sampledAt < GIT_IDENTITY_SAMPLE_TTL_MS) {
     gitIdentityPerformance.cacheHits += 1;
     return existing;
   }
-  const sampled = sampleGitIdentity(repoRoot);
-  const entry: CachedGitIdentity = { ...sampled, sampledAt: now };
-  gitIdentityCache.set(repoRoot, entry);
-  pruneGitIdentityCache();
-  return entry;
+  return freshGitIdentity(root);
+}
+
+/**
+ * Successful Forge-owned mutations invalidate observations derived from the
+ * previous source state. This is intentionally lazy: no graph rebuild, check,
+ * or language server is started here; the next read re-samples Git/current bytes.
+ */
+export function invalidateRepositoryReadCaches(repoRoot: string): void {
+  const root = resolve(repoRoot);
+  gitIdentityCache.delete(root);
+  gitSnapshotCache.delete(root);
+  for (const key of [...searchFileInventoryCache.keys()]) {
+    try {
+      const identity = JSON.parse(key) as { repoRoot?: unknown };
+      if (typeof identity.repoRoot === 'string' && resolve(identity.repoRoot) === root) {
+        searchFileInventoryCache.delete(key);
+      }
+    } catch {
+      // Cache keys are internal JSON identities. Ignore legacy/unparseable entries.
+    }
+  }
+  invalidateSessionCachesForRepository(root);
 }
 
 export function clearGitIdentityCacheForTest(): void {
@@ -159,14 +222,26 @@ export interface RepositoryReadSession {
 
 function bindSessionCache(repoRoot: string, session?: RepositoryReadSession): RepositorySessionCache | null {
   if (!session?.sessionId || !session.repoId || !session.checkoutId) return null;
-  const identity = collectSessionIdentity({
-    repoRoot,
+  const sampled = cachedGitIdentity(repoRoot);
+  const identity: SessionIdentity = {
     repoId: session.repoId,
     checkoutId: session.checkoutId,
-  });
+    branch: sampled.branch,
+    head: sampled.head,
+    workingTreeFingerprint: sampled.workingTreeFingerprint
+      ?? createHash('sha256').update(`${sampled.head ?? ''}\n${sampled.branch ?? ''}`).digest('hex').slice(0, 24),
+  };
   return getOrCreateSessionCache(session.sessionId, repoRoot, identity);
 }
 
+/** Shared non-durable cache binding for progressive Context Plane providers. */
+export function getRepositoryReadSessionCache(
+  repoRoot: string,
+  session?: RepositoryReadSession,
+): RepositorySessionCache | null {
+  return bindSessionCache(repoRoot, session);
+}
+
 export function resolveSessionIdentity(
   repoRoot: string,
   repoId: string,
@@ -208,6 +283,15 @@ const SEARCH_GIT_INVENTORY_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
  * output is truncated so non-Git/ephemeral workspaces retain the filesystem
  * fallback below.
  */
+function parseGitSearchFileInventory(stdout: string): string[] {
+  return stdout
+    .split('\0')
+    // NUL framing already gives exact Git paths; do not trim because leading
+    // or trailing whitespace is legal in a repository filename.
+    .filter((path) => path.length > 0)
+    .sort((left, right) => left.localeCompare(right));
+}
+
 function gitSearchFileInventory(repoRoot: string): string[] | null {
   try {
     const result = runProcess('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
@@ -216,17 +300,34 @@ function gitSearchFileInventory(repoRoot: string): string[] | null {
       maxOutputBytes: SEARCH_GIT_INVENTORY_MAX_OUTPUT_BYTES,
     });
     if (!result.ok || result.stdout.includes('[output truncated after')) return null;
-    return result.stdout
-      .split('\0')
-      // NUL framing already gives exact Git paths; do not trim because leading
-      // or trailing whitespace is legal in a repository filename.
-      .filter((path) => path.length > 0)
-      .sort((left, right) => left.localeCompare(right));
+    return parseGitSearchFileInventory(result.stdout);
   } catch {
     return null;
   }
 }
 
+function gitSearchFileInventoryAsync(repoRoot: string): Promise<string[] | null> {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      ['ls-files', '-z', '--cached', '--others', '--exclude-standard'],
+      {
+        cwd: repoRoot,
+        timeout: 10_000,
+        maxBuffer: SEARCH_GIT_INVENTORY_MAX_OUTPUT_BYTES,
+        encoding: 'utf8',
+      },
+      (error, stdout) => {
+        if (error || typeof stdout !== 'string') {
+          resolve(null);
+          return;
+        }
+        resolve(parseGitSearchFileInventory(stdout));
+      },
+    );
+  });
+}
+
 function binary(bytes: Buffer): boolean {
   return bytes.subarray(0, Math.min(bytes.length, 8000)).includes(0);
 }
@@ -251,6 +352,36 @@ function walk(repoRoot: string, root: string, maxFiles: number, excludes: string
   }
 }
 
+async function walkAsync(repoRoot: string, root: string, maxFiles: number, excludes: string[], output: string[]): Promise<void> {
+  if (output.length >= maxFiles) return;
+  const absolute = join(repoRoot, root);
+  let info;
+  try {
+    info = await lstatAsync(absolute);
+  } catch {
+    return;
+  }
+  if (info.isSymbolicLink()) return;
+  if (info.isFile()) {
+    output.push(root);
+    return;
+  }
+  if (!info.isDirectory()) return;
+  let entries;
+  try {
+    entries = await readdirAsync(absolute, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (output.length >= maxFiles) break;
+    const child = root ? `${root}/${entry.name}` : entry.name;
+    if (isExcluded(child, excludes) || isExcluded(`${child}/`, excludes)) continue;
+    if (entry.isDirectory()) await walkAsync(repoRoot, child, maxFiles, excludes, output);
+    else if (entry.isFile()) output.push(child);
+  }
+}
+
 export interface SearchRepositoryOptions {
   query: string;
   includeGlobs?: string[];
@@ -264,12 +395,26 @@ export interface SearchRepositoryOptions {
 
 export interface SearchRepositoryManyOptions {
   queries: string[];
+  /** Pre-resolved exact candidate files. Skips repository inventory discovery. */
+  files?: string[];
   includeGlobs?: string[];
   excludeGlobs?: string[];
   maxResultsPerQuery?: number;
   maxFiles?: number;
   caseSensitive?: boolean;
   cacheKey?: string;
+  /**
+   * Strict search remains the default. Broad Context discovery may stop once it
+   * has enough distinct candidate files across several query hints; guessed
+   * natural-language terms are evidence hints, not completeness obligations.
+   */
+  completionMode?: 'per_query' | 'discovery';
+  discoveryTargetFiles?: number;
+  discoveryMinQueryCoverage?: number;
+  /** Exact caller-supplied needles that discovery must not skip. */
+  requiredQueries?: string[];
+  /** MCP/controller session identity used for progressive follow-up reuse. */
+  session?: RepositoryReadSession;
 }
 
 export interface SearchRepositoryManyResult {
@@ -280,10 +425,76 @@ export interface SearchRepositoryManyResult {
   skippedLargeFiles: number;
   skippedBinaryFiles: number;
   truncated: boolean;
-  truncationReason?: 'max_results' | 'max_files';
+  truncationReason?: 'max_results' | 'max_files' | 'discovery_budget';
   cacheHit?: boolean;
 }
 
+export interface SearchRepositoryManyCacheIdentity {
+  queries: string[];
+  maxResultsPerQuery: number;
+  maxFiles: number;
+  includes: string[];
+  excludes: string[];
+  directCandidates?: string[];
+  completionMode: 'per_query' | 'discovery';
+  discoveryTargetFiles: number;
+  discoveryMinQueryCoverage: number;
+  requiredQueries: string[];
+  includeKey: string;
+  batchQueryKey: string;
+}
+
+/** Shared normalization/cache identity for sync search and worker-prefetched search. */
+export function searchRepositoryManyCacheIdentity(opts: SearchRepositoryManyOptions): SearchRepositoryManyCacheIdentity {
+  const queries = Array.from(new Set(opts.queries.map((query) => query.trim()).filter(Boolean)));
+  if (queries.length === 0) throw new Error('at least one search query is required');
+  const maxResultsPerQuery = Math.min(Math.max(opts.maxResultsPerQuery ?? 100, 1), 500);
+  const maxFiles = Math.min(Math.max(opts.maxFiles ?? 5000, 1), 20_000);
+  const includes = opts.includeGlobs ?? [];
+  const excludes = [...(includes.length === 0 ? DEFAULT_EXCLUDES : []), ...(opts.excludeGlobs ?? [])];
+  const directFiles = opts.files?.map((path) => path.trim()).filter(Boolean);
+  const directCandidates = directFiles
+    ? Array.from(new Set(directFiles)).filter((path) => !isExcluded(path, excludes))
+    : undefined;
+  const completionMode = opts.completionMode === 'discovery' ? 'discovery' : 'per_query';
+  const discoveryTargetFiles = completionMode === 'discovery'
+    ? Math.min(Math.max(opts.discoveryTargetFiles ?? Math.max(12, Math.ceil(maxResultsPerQuery / 2)), 1), maxFiles)
+    : maxFiles;
+  const discoveryMinQueryCoverage = completionMode === 'discovery'
+    ? Math.min(Math.max(opts.discoveryMinQueryCoverage ?? Math.min(3, queries.length), 1), queries.length)
+    : queries.length;
+  const requiredQueries = completionMode === 'discovery'
+    ? Array.from(new Set((opts.requiredQueries ?? []).map((query) => query.trim()).filter((query) => queries.includes(query))))
+    : [];
+  const includeKey = JSON.stringify({
+    files: directCandidates,
+    includes,
+    excludes,
+    maxResultsPerQuery,
+    maxFiles,
+    caseSensitive: opts.caseSensitive === true,
+    cacheKey: opts.cacheKey,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+  });
+  return {
+    queries,
+    maxResultsPerQuery,
+    maxFiles,
+    includes,
+    excludes,
+    directCandidates,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    includeKey,
+    batchQueryKey: queries.join('\u0000'),
+  };
+}
+
 function searchInventory(
   repoRoot: string,
   includes: string[],
@@ -311,6 +522,157 @@ function searchInventory(
   return { files: candidates.slice(0, maxFiles), candidateCount: candidates.length, cacheHit };
 }
 
+async function searchInventoryAsync(
+  repoRoot: string,
+  includes: string[],
+  excludes: string[],
+  maxFiles: number,
+  cacheKey?: string,
+): Promise<{ files: string[]; candidateCount: number; cacheHit: boolean }> {
+  const inventoryKey = JSON.stringify({ repoRoot, excludes, cacheKey });
+  const now = Date.now();
+  const cachedInventory = searchFileInventoryCache.get(inventoryKey);
+  const cacheHit = Boolean(cachedInventory && now - cachedInventory.createdAt < SEARCH_FILE_INVENTORY_CACHE_TTL_MS);
+  let inventory: string[];
+  if (cacheHit) {
+    inventory = cachedInventory!.files;
+  } else {
+    const gitFiles = await gitSearchFileInventoryAsync(repoRoot);
+    if (gitFiles) {
+      inventory = gitFiles;
+    } else {
+      const walked: string[] = [];
+      await walkAsync(repoRoot, '', 20_000, excludes, walked);
+      inventory = walked;
+    }
+    searchFileInventoryCache.set(inventoryKey, { createdAt: now, files: inventory });
+  }
+  const candidates = inventory.filter((path) => isIncluded(path, includes) && !isExcluded(path, excludes));
+  return { files: candidates.slice(0, maxFiles), candidateCount: candidates.length, cacheHit };
+}
+
+interface SearchManyMatchState {
+  queries: string[];
+  needles: Array<{ query: string; needle: string }>;
+  counts: Map<string, number>;
+  results: SearchRepositoryManyResult['results'];
+  matchedPaths: Set<string>;
+  maxResultsPerQuery: number;
+  completionMode: 'per_query' | 'discovery';
+  discoveryTargetFiles: number;
+  discoveryMinQueryCoverage: number;
+  requiredQueries: string[];
+  caseSensitive: boolean;
+}
+
+function createSearchManyMatchState(
+  queries: string[],
+  maxResultsPerQuery: number,
+  completionMode: 'per_query' | 'discovery',
+  discoveryTargetFiles: number,
+  discoveryMinQueryCoverage: number,
+  requiredQueries: string[],
+  caseSensitive: boolean,
+): SearchManyMatchState {
+  return {
+    queries,
+    needles: queries.map((query) => ({ query, needle: caseSensitive ? query : query.toLowerCase() })),
+    counts: new Map(queries.map((query) => [query, 0])),
+    results: [],
+    matchedPaths: new Set<string>(),
+    maxResultsPerQuery,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    caseSensitive,
+  };
+}
+
+function searchManyComplete(state: SearchManyMatchState): boolean {
+  if (state.completionMode === 'per_query') {
+    return state.needles.every(({ query }) => (state.counts.get(query) ?? 0) >= state.maxResultsPerQuery);
+  }
+  if (state.requiredQueries.some((query) => (state.counts.get(query) ?? 0) === 0)) return false;
+  const coveredQueries = state.needles.reduce(
+    (count, { query }) => count + ((state.counts.get(query) ?? 0) > 0 ? 1 : 0),
+    0,
+  );
+  return state.matchedPaths.size >= state.discoveryTargetFiles
+    && coveredQueries >= state.discoveryMinQueryCoverage;
+}
+
+function exactCodeNeedleMatches(haystack: string, needle: string): boolean {
+  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?:^|[^\\p{L}\\p{N}_$])${escaped}(?=$|[^\\p{L}\\p{N}_$])`, 'u').test(haystack);
+}
+
+function matchSearchManySource(state: SearchManyMatchState, path: string, bytes: Buffer): void {
+  const raw = bytes.toString('utf-8');
+  const searchable = state.caseSensitive ? raw : raw.toLowerCase();
+  const activeNeedles = state.needles.filter(({ query, needle }) =>
+    (state.counts.get(query) ?? 0) < state.maxResultsPerQuery
+      && (state.requiredQueries.includes(query)
+        ? exactCodeNeedleMatches(searchable, needle)
+        : searchable.includes(needle)));
+  if (activeNeedles.length === 0) return;
+
+  const lines = raw.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const text = lines[index]!;
+    const haystack = state.caseSensitive ? text : text.toLowerCase();
+    for (const { query, needle } of activeNeedles) {
+      const matches = state.requiredQueries.includes(query)
+        ? exactCodeNeedleMatches(haystack, needle)
+        : haystack.includes(needle);
+      if ((state.counts.get(query) ?? 0) >= state.maxResultsPerQuery || !matches) continue;
+      state.results.push({ query, path, line: index + 1, text: text.slice(0, 500) });
+      state.matchedPaths.add(path);
+      state.counts.set(query, (state.counts.get(query) ?? 0) + 1);
+    }
+  }
+}
+
+function finalizeSearchManyResult(input: {
+  state: SearchManyMatchState;
+  scannedFiles: number;
+  policyDeniedFiles: number;
+  skippedLargeFiles: number;
+  skippedBinaryFiles: number;
+  candidateCount: number;
+  inventoryFileCount: number;
+  inventoryCacheHit: boolean;
+}): SearchRepositoryManyResult {
+  const { state } = input;
+  const queryPriority = new Map(state.queries.map((query, index) => [query, index]));
+  state.results.sort((left, right) => {
+    const priority = (queryPriority.get(left.query) ?? state.queries.length) - (queryPriority.get(right.query) ?? state.queries.length);
+    if (priority !== 0) return priority;
+    const pathOrder = left.path.localeCompare(right.path);
+    return pathOrder !== 0 ? pathOrder : left.line - right.line;
+  });
+  const discoveryBudgetReached = state.completionMode === 'discovery' && searchManyComplete(state);
+  const hitResultLimit = state.needles.some(({ query }) => (state.counts.get(query) ?? 0) >= state.maxResultsPerQuery);
+  const truncationReason = discoveryBudgetReached
+    ? 'discovery_budget' as const
+    : hitResultLimit
+      ? 'max_results' as const
+      : input.candidateCount > input.inventoryFileCount
+        ? 'max_files' as const
+        : undefined;
+  return {
+    queries: state.queries,
+    results: state.results,
+    scannedFiles: input.scannedFiles,
+    policyDeniedFiles: input.policyDeniedFiles,
+    skippedLargeFiles: input.skippedLargeFiles,
+    skippedBinaryFiles: input.skippedBinaryFiles,
+    truncated: Boolean(truncationReason),
+    truncationReason,
+    cacheHit: input.inventoryCacheHit,
+  };
+}
+
 /**
  * Internal Context Plane batch search. Every candidate file is policy-checked
  * and read at most once while all lexical terms are matched in the same pass.
@@ -321,24 +683,52 @@ export function searchRepositoryMany(
   policy: McpPolicy,
   opts: SearchRepositoryManyOptions,
 ): SearchRepositoryManyResult {
-  const queries = Array.from(new Set(opts.queries.map((query) => query.trim()).filter(Boolean)));
-  if (queries.length === 0) throw new Error('at least one search query is required');
-  const maxResultsPerQuery = Math.min(Math.max(opts.maxResultsPerQuery ?? 100, 1), 500);
-  const maxFiles = Math.min(Math.max(opts.maxFiles ?? 5000, 1), 20_000);
-  const includes = opts.includeGlobs ?? [];
-  const excludes = [...(includes.length === 0 ? DEFAULT_EXCLUDES : []), ...(opts.excludeGlobs ?? [])];
-  const inventory = searchInventory(repoRoot, includes, excludes, maxFiles, opts.cacheKey);
-  const needles = queries.map((query) => ({ query, needle: opts.caseSensitive ? query : query.toLowerCase() }));
-  const counts = new Map(queries.map((query) => [query, 0]));
-  const results: SearchRepositoryManyResult['results'] = [];
+  const {
+    queries,
+    maxResultsPerQuery,
+    maxFiles,
+    includes,
+    excludes,
+    directCandidates,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    includeKey,
+    batchQueryKey,
+  } = searchRepositoryManyCacheIdentity(opts);
+  const sessionCache = bindSessionCache(repoRoot, opts.session);
+  if (sessionCache) {
+    const cached = sessionCache.getSearch(batchQueryKey, includeKey);
+    if (cached?.result && typeof cached.result === 'object') {
+      return { ...(cached.result as SearchRepositoryManyResult), cacheHit: true };
+    }
+  }
+  const inventory = directCandidates && directCandidates.length > 0
+    ? {
+        files: directCandidates.slice(0, maxFiles),
+        candidateCount: directCandidates.length,
+        cacheHit: false,
+      }
+    : searchInventory(repoRoot, includes, excludes, maxFiles, opts.cacheKey);
+  const matchState = createSearchManyMatchState(
+    queries,
+    maxResultsPerQuery,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    opts.caseSensitive === true,
+  );
   let scannedFiles = 0;
   let policyDeniedFiles = 0;
   let skippedLargeFiles = 0;
   let skippedBinaryFiles = 0;
+  const canonicalRepoRoot = realpathSync(repoRoot);
 
   for (const path of inventory.files) {
-    if (needles.every(({ query }) => (counts.get(query) ?? 0) >= maxResultsPerQuery)) break;
-    const decision = resolveMcpPath(repoRoot, path, policy, 'read');
+    if (searchManyComplete(matchState)) break;
+    const decision = resolveMcpPath(repoRoot, path, policy, 'read', canonicalRepoRoot);
     if (!decision.ok || !decision.absolutePath) {
       policyDeniedFiles += 1;
       continue;
@@ -354,46 +744,159 @@ export function searchRepositoryMany(
       continue;
     }
     scannedFiles += 1;
-    const lines = bytes.toString('utf-8').split(/\r?\n/);
-    for (let index = 0; index < lines.length; index += 1) {
-      const text = lines[index]!;
-      const haystack = opts.caseSensitive ? text : text.toLowerCase();
-      for (const { query, needle } of needles) {
-        if ((counts.get(query) ?? 0) >= maxResultsPerQuery || !haystack.includes(needle)) continue;
-        results.push({ query, path, line: index + 1, text: text.slice(0, 500) });
-        counts.set(query, (counts.get(query) ?? 0) + 1);
-      }
-    }
+    matchSearchManySource(matchState, path, bytes);
   }
 
   // Consumers may bound distinct candidate files after this call. Preserve the
   // caller's query priority so an exact symbol/phrase cannot be displaced by
   // earlier alphabetic files that only matched broad recall tokens.
-  const queryPriority = new Map(queries.map((query, index) => [query, index]));
-  results.sort((left, right) => {
-    const priority = (queryPriority.get(left.query) ?? queries.length) - (queryPriority.get(right.query) ?? queries.length);
-    if (priority !== 0) return priority;
-    const pathOrder = left.path.localeCompare(right.path);
-    return pathOrder !== 0 ? pathOrder : left.line - right.line;
+  const payload = finalizeSearchManyResult({
+    state: matchState,
+    scannedFiles,
+    policyDeniedFiles,
+    skippedLargeFiles,
+    skippedBinaryFiles,
+    candidateCount: inventory.candidateCount,
+    inventoryFileCount: inventory.files.length,
+    inventoryCacheHit: inventory.cacheHit,
   });
+  if (sessionCache) {
+    sessionCache.putSearch({
+      query: batchQueryKey,
+      includeKey,
+      result: payload,
+      scannedFiles,
+    });
+  }
+  return payload;
+}
 
-  const hitResultLimit = needles.some(({ query }) => (counts.get(query) ?? 0) >= maxResultsPerQuery);
-  const truncationReason = hitResultLimit
-    ? 'max_results' as const
-    : inventory.candidateCount > inventory.files.length
-      ? 'max_files' as const
-      : undefined;
-  return {
+// File reads are already bounded by policy/maxFiles. A wider batch keeps broad
+// Context scans from serializing dozens of filesystem waves while still
+// preserving original-order matching and early-stop semantics below.
+const ASYNC_SEARCH_READ_BATCH_SIZE = 64;
+
+type AsyncSearchCandidate =
+  | { path: string; kind: 'denied' }
+  | { path: string; kind: 'large' }
+  | { path: string; kind: 'binary' }
+  | { path: string; kind: 'source'; bytes: Buffer }
+  | { path: string; kind: 'error'; error: unknown };
+
+async function readSearchCandidateAsync(
+  repoRoot: string,
+  policy: McpPolicy,
+  canonicalRepoRoot: string,
+  path: string,
+): Promise<AsyncSearchCandidate> {
+  try {
+    const decision = resolveMcpPath(repoRoot, path, policy, 'read', canonicalRepoRoot);
+    if (!decision.ok || !decision.absolutePath) return { path, kind: 'denied' };
+    const size = (await statAsync(decision.absolutePath)).size;
+    if (size > policy.maxFileBytes) return { path, kind: 'large' };
+    const bytes = await readFileAsync(decision.absolutePath);
+    if (binary(bytes)) return { path, kind: 'binary' };
+    return { path, kind: 'source', bytes };
+  } catch (error) {
+    return { path, kind: 'error', error };
+  }
+}
+
+/**
+ * Async Context Plane batch search with result semantics matching
+ * searchRepositoryMany. Candidate reads happen in bounded batches, while policy
+ * accounting, early-stop behavior, matching, and result ordering are consumed in
+ * original repository order on the caller thread.
+ */
+export async function searchRepositoryManyAsync(
+  repoRoot: string,
+  policy: McpPolicy,
+  opts: SearchRepositoryManyOptions,
+): Promise<SearchRepositoryManyResult> {
+  const {
     queries,
-    results,
+    maxResultsPerQuery,
+    maxFiles,
+    includes,
+    excludes,
+    directCandidates,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    includeKey,
+    batchQueryKey,
+  } = searchRepositoryManyCacheIdentity(opts);
+  const sessionCache = bindSessionCache(repoRoot, opts.session);
+  if (sessionCache) {
+    const cached = sessionCache.getSearch(batchQueryKey, includeKey);
+    if (cached?.result && typeof cached.result === 'object') {
+      return { ...(cached.result as SearchRepositoryManyResult), cacheHit: true };
+    }
+  }
+  const inventory = directCandidates && directCandidates.length > 0
+    ? {
+        files: directCandidates.slice(0, maxFiles),
+        candidateCount: directCandidates.length,
+        cacheHit: false,
+      }
+    : await searchInventoryAsync(repoRoot, includes, excludes, maxFiles, opts.cacheKey);
+  const matchState = createSearchManyMatchState(
+    queries,
+    maxResultsPerQuery,
+    completionMode,
+    discoveryTargetFiles,
+    discoveryMinQueryCoverage,
+    requiredQueries,
+    opts.caseSensitive === true,
+  );
+  let scannedFiles = 0;
+  let policyDeniedFiles = 0;
+  let skippedLargeFiles = 0;
+  let skippedBinaryFiles = 0;
+  const canonicalRepoRoot = realpathSync(repoRoot);
+  for (let offset = 0; offset < inventory.files.length && !searchManyComplete(matchState); offset += ASYNC_SEARCH_READ_BATCH_SIZE) {
+    const batchPaths = inventory.files.slice(offset, offset + ASYNC_SEARCH_READ_BATCH_SIZE);
+    const batch = await Promise.all(batchPaths.map((path) => readSearchCandidateAsync(repoRoot, policy, canonicalRepoRoot, path)));
+    for (const candidate of batch) {
+      if (searchManyComplete(matchState)) break;
+      if (candidate.kind === 'denied') {
+        policyDeniedFiles += 1;
+        continue;
+      }
+      if (candidate.kind === 'large') {
+        skippedLargeFiles += 1;
+        continue;
+      }
+      if (candidate.kind === 'binary') {
+        skippedBinaryFiles += 1;
+        continue;
+      }
+      if (candidate.kind === 'error') throw candidate.error;
+      scannedFiles += 1;
+      matchSearchManySource(matchState, candidate.path, candidate.bytes);
+    }
+  }
+
+  const payload = finalizeSearchManyResult({
+    state: matchState,
     scannedFiles,
     policyDeniedFiles,
     skippedLargeFiles,
     skippedBinaryFiles,
-    truncated: Boolean(truncationReason),
-    truncationReason,
-    cacheHit: inventory.cacheHit,
-  };
+    candidateCount: inventory.candidateCount,
+    inventoryFileCount: inventory.files.length,
+    inventoryCacheHit: inventory.cacheHit,
+  });
+  if (sessionCache) {
+    sessionCache.putSearch({
+      query: batchQueryKey,
+      includeKey,
+      result: payload,
+      scannedFiles,
+    });
+  }
+  return payload;
 }
 
 export function searchRepository(repoRoot: string, policy: McpPolicy, opts: SearchRepositoryOptions & {