@moretea-labs/forge 1.6.0 → 1.7.1

package/src/cli/controller/context-pack.ts

@@ -1,429 +1,107 @@
-import { existsSync, lstatSync, readdirSync, statSync } from "fs";
-import { gitSnapshot, readRepositoryRange, searchRepositoryMany } from "../repository/inspector";
-import { resolveMcpPath, globMatches } from "../mcp/paths";
+import {
+  gitSnapshot,
+  getRepositoryReadSessionCache,
+  searchRepositoryMany,
+  searchRepositoryManyAsync,
+  searchRepositoryManyCacheIdentity,
+} from "../repository/inspector";
+import { globMatches } from "../mcp/paths";
+import { posix } from "path";
 import type { McpPolicy } from "../mcp/types";
-import { redactMcpText } from "../mcp/redaction";
+import { materializeSource } from "./context/source-materializer";
 import { projectBoard } from "./issue-store";
-import { buildControllerTaskLedgerProjection, type TaskLedgerTaskProjection } from "./task-ledger";
+import { buildControllerTaskLedgerProjection } from "./task-ledger";
 import { legacyIssueAuthorityRetired } from "./legacy-issue-cutover";
 import {
   queryCodeGraphReadProvider,
-  type CodeGraphIndexMetadata,
+  queryCodeGraphReadProviderAsync,
   type CodeGraphNodeSummary,
   type CodeGraphReadProviderResponse,
 } from "../../runtime/context/codegraph-read-provider";
+import {
+  CONTEXT_PACK_SCHEMA_VERSION,
+  CONTROLLER_CONTEXT_IMPACT_DOMAINS,
+  type ControllerContextImpactDomain,
+  type ControllerContextPackDependencies,
+  type ControllerContextPackFile,
+  type ControllerContextPackOptions,
+  type ControllerContextPackProjection,
+  type ControllerContextPackSnippet,
+} from './context/types';
+import {
+  DEFAULT_MAX_CHARS_PER_SNIPPET,
+  DEFAULT_MAX_FILES,
+  DEFAULT_MAX_SNIPPETS,
+  DEFAULT_SEARCH_EXCLUDE_GLOBS,
+  IMPACT_DOMAIN_TERMS,
+  MAX_TOTAL_SEARCHED_FILES,
+  clamp,
+  cleanList,
+  gitStatusChangedPaths,
+  isCodeShapedTerm,
+  pathNoisePenalty,
+  structuralIntentQuery,
+  textTokens,
+} from './context/query-planning';
+import { issueTaskFocus, ledgerTask } from './context/focus';
+import { addReason, coveredByGlob, expandKnownPath, looksLikeGlob, readableFile } from './context/known-paths';
+import { structuralResult } from './context/structural';
+import { buildRepositoryInstructionContext } from './context/instruction-context';
+import { resolveRepositoryGovernance } from './context/rule-resolution';
+import { controllerCheckSelection, listControllerChecks } from './check-runner';
 
-const CONTEXT_PACK_SCHEMA_VERSION = 6;
-const DEFAULT_MAX_FILES = 8;
-const DEFAULT_MAX_SNIPPETS = 20;
-const DEFAULT_SNIPPET_CONTEXT_BEFORE = 12;
-const DEFAULT_SNIPPET_CONTEXT_AFTER = 28;
-const DEFAULT_MAX_CHARS_PER_SNIPPET = 8000;
-const DEFAULT_SEARCH_EXCLUDE_GLOBS = [
-  ".git/**",
-  "_ops/**",
-  ".forge/**",
-  ".ai/harness/**",
-  "node_modules/**",
-  "dist/**",
-  "coverage/**",
-  "**/*.bak",
-] as const;
-const MAX_TOTAL_SEARCHED_FILES = 800;
-
-const STOPWORDS = new Set([
-  "about", "after", "again", "also", "and", "around", "because", "before", "between", "change", "code", "config",
-  "context", "current", "does", "file", "from", "have", "into", "issue", "make", "need", "needs", "only", "path",
-  "repo", "repository", "runtime", "should", "task", "that", "this", "through", "todo", "update", "when", "with",
-]);
-
-export type StructuralContextMode = "off" | "auto" | "required";
-export type ControllerContextRetrievalMode = "implementation" | "plan" | "debug" | "review";
-export const CONTROLLER_CONTEXT_IMPACT_DOMAINS = [
-  "persistence", "scheduler", "notification", "timeline", "events", "cache", "api", "concurrency",
-] as const;
-export type ControllerContextImpactDomain = (typeof CONTROLLER_CONTEXT_IMPACT_DOMAINS)[number];
-
-const IMPACT_DOMAIN_TERMS: Record<ControllerContextImpactDomain, readonly string[]> = {
-  persistence: ["persist", "database", "repository"],
-  scheduler: ["scheduler", "schedule", "reminder"],
-  notification: ["notification", "notify", "push"],
-  timeline: ["timeline", "history", "activity"],
-  events: ["event", "publish", "subscribe"],
-  cache: ["cache", "invalidate", "memo"],
-  api: ["api", "dto", "controller"],
-  concurrency: ["transaction", "lock", "atomic"],
-};
-
-export interface ControllerContextPackOptions {
-  description?: string;
-  issueId?: string;
-  taskId?: string;
-  knownPaths?: string[];
-  includeGlobs?: string[];
-  excludeGlobs?: string[];
-  searchTerms?: string[];
-  maxFiles?: number;
-  maxSnippets?: number;
-  maxCharsPerSnippet?: number;
-  structuralContext?: StructuralContextMode;
-  /** Optional repository-level CodeGraph root used as structural baseline when the selected checkout has no local index. */
-  structuralIndexRoot?: string;
-  retrievalMode?: ControllerContextRetrievalMode;
-  /** GPT-selected cross-cutting evidence dimensions. Forge expands mechanically and never treats them as semantic completeness proof. */
-  impactDomains?: ControllerContextImpactDomain[];
-}
-
-export interface ControllerContextPackDependencies {
-  queryCodeGraph?: typeof queryCodeGraphReadProvider;
-}
-
-export interface ControllerContextPackSnippet {
-  path: string;
-  startLine: number;
-  endLine: number;
-  totalLines: number;
-  sha256: string;
-  content: string;
-  truncated: boolean;
-  redactions: Array<{ type: string; count: number }>;
-  reason: string;
-}
-
-export interface ControllerContextPackFile {
-  path: string;
-  reasons: string[];
-  hitLines: number[];
-  snippetCount: number;
-  snippets: ControllerContextPackSnippet[];
-}
-
-export interface ControllerContextPackProjection {
-  schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;
-  generatedAt: string;
-  source: "controller-context-pack";
-  focus: {
-    issueId?: string;
-    issueTitle?: string;
-    taskId?: string;
-    taskTitle?: string;
-    taskStatus?: string;
-  };
-  goal: string;
-  git: {
-    branch: string | null;
-    status: string;
-    diffStat: string;
-    dirty: boolean;
-  };
-  search: {
-    terms: string[];
-    impactDomains: ControllerContextImpactDomain[];
-    impactCoverage: Array<{
-      domain: ControllerContextImpactDomain;
-      queries: string[];
-      matchedFiles: string[];
-      selectedFiles: string[];
-      omittedFileCount: number;
-      status: "selected" | "matched_not_selected" | "no_evidence";
-    }>;
-    includeGlobs: string[];
-    excludeGlobs: string[];
-    scannedFiles: number;
-    policyDeniedFiles: number;
-    skippedLargeFiles: number;
-    skippedBinaryFiles: number;
-    truncated: boolean;
-  };
-  structuralContext: {
-    provider: "codegraph";
-    requestedMode: StructuralContextMode;
-    status: "disabled" | "ready" | "stale" | "unavailable" | "degraded";
-    requiredSatisfied: boolean;
-    indexSource: "current_checkout" | "repository_baseline";
-    overlayChangedFiles: string[];
-    baselineRevisionMatches: boolean;
-    query?: string;
-    entryPoints: Array<Pick<CodeGraphNodeSummary, "id" | "kind" | "name" | "filePath" | "startLine" | "endLine">>;
-    relatedFiles: string[];
-    metadata?: Pick<CodeGraphIndexMetadata, "initialized" | "lastIndexedAt" | "buildVersion" | "extractionVersion" | "staleEngine" | "changedFiles" | "ignoredChangedFileCount">;
-    fallbackReason?: string;
-    timingsMs?: CodeGraphReadProviderResponse["timingsMs"];
-    truncated: boolean;
-  };
-  impactContext: {
-    status: "not_requested" | "ready" | "degraded";
-    confidence: "low" | "medium" | "high";
-    primaryTargets: string[];
-    mustInspect: string[];
-    likelyAffected: string[];
-    relevantTests: string[];
-    relevantChecks: string[];
-    architectureContracts: string[];
-    coverageGaps: string[];
-    relationSources: Array<"codegraph" | "lexical" | "forge_checks">;
-    freshness: {
-      structuralStatus: "disabled" | "ready" | "stale" | "unavailable" | "degraded";
-      lastIndexedAt?: number | null;
-      changedFileCount: number;
-      indexSource: "current_checkout" | "repository_baseline";
-      overlayChangedFileCount: number;
-      baselineRevisionMatches: boolean;
-    };
-  };
-  files: ControllerContextPackFile[];
-  deniedPaths: Array<{ path: string; reason: string }>;
-  omitted: Array<{ path: string; reason: string }>;
-  limits: {
-    maxFiles: number;
-    maxSnippets: number;
-    maxCharsPerSnippet: number;
-  };
-  validation: {
-    policy: "task-targeted" | "minimal";
-    checks: string[];
-  };
-  contextContract: {
-    strategy: string;
-    retrievalMode: ControllerContextRetrievalMode;
-    semanticSufficiencyAuthority: "chatgpt";
-    rawCodeRequiredForImplementation: boolean;
-    expansionSignals: string[];
-    notes: string[];
-  };
-  next: string[];
-}
-
-function cleanList(value: string[] | undefined): string[] {
-  return Array.from(new Set((value ?? []).map((entry) => entry.trim()).filter(Boolean)));
-}
-
-function clamp(value: number | undefined, fallback: number, min: number, max: number): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
-  return Math.min(Math.max(Math.trunc(value), min), max);
-}
-
-function textTokens(value: string): string[] {
-  const split = value
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .split(/[^\p{L}\p{N}_./:-]+/u)
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-  const tokens = split
-    .map((entry) => entry.replace(/^['"`]+|['"`]+$/g, ""))
-    .filter((entry) => entry.length >= 3)
-    .filter((entry) => !STOPWORDS.has(entry.toLowerCase()))
-    .filter((entry) => !/^\d+$/.test(entry));
-  return Array.from(new Set(tokens)).slice(0, 12);
-}
-
-interface ContextPackIssueFocus {
-  id?: string;
-  title?: string;
-  summary?: string;
-  tasks: ContextPackTaskFocus[];
-}
-
-interface ContextPackTaskFocus {
-  id?: string;
-  title?: string;
-  objective?: string;
-  status?: string;
-}
-
-function unknownRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
-function unknownString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
-function unknownRecordArray(value: unknown): Array<Record<string, unknown>> {
-  if (!Array.isArray(value)) return [];
-  return value.map(unknownRecord).filter((entry) => Object.keys(entry).length > 0);
-}
-
-function contextPackTaskFocus(value: unknown): ContextPackTaskFocus {
-  const record = unknownRecord(value);
-  return {
-    id: unknownString(record.id),
-    title: unknownString(record.title),
-    objective: unknownString(record.objective),
-    status: unknownString(record.status),
-  };
-}
-
-function contextPackIssueFocus(value: unknown): ContextPackIssueFocus {
-  const record = unknownRecord(value);
-  return {
-    id: unknownString(record.id),
-    title: unknownString(record.title),
-    summary: unknownString(record.summary),
-    tasks: unknownRecordArray(record.tasks).map(contextPackTaskFocus),
-  };
-}
-
-function issueTaskFocus(board: ReturnType<typeof projectBoard>, issueId?: string, taskId?: string): { issue?: ContextPackIssueFocus; task?: ContextPackTaskFocus } {
-  const issues = board.issues.map(contextPackIssueFocus);
-  const resolvedIssue = issueId
-    ? issues.find((issue) => issue.id === issueId)
-    : board.currentIssueId
-      ? issues.find((issue) => issue.id === board.currentIssueId)
-      : undefined;
-  const resolvedTask = resolvedIssue?.tasks.find((task) => task.id === taskId) ?? resolvedIssue?.tasks[0];
-  return { issue: resolvedIssue, task: resolvedTask };
-}
-
-function ledgerTask(ledger: ReturnType<typeof buildControllerTaskLedgerProjection>, issueId?: string, taskId?: string): TaskLedgerTaskProjection | undefined {
-  const tasks = ledger.issues.flatMap((issue) => issue.tasks);
-  const findTask = (candidateIssueId?: string, candidateTaskId?: string) => tasks
-    .find((task) => (!candidateIssueId || task.issueId === candidateIssueId) && (!candidateTaskId || task.taskId === candidateTaskId));
-
-  if (!issueId && !taskId) {
-    const readyTask = ledger.readyTasks[0];
-    return ledger.attention[0]
-      ?? findTask(readyTask?.issueId, readyTask?.taskId)
-      ?? tasks.find((task) => task.dispatchable || task.queueable);
-  }
-
-  return findTask(issueId, taskId);
-}
-
-function looksLikeGlob(path: string): boolean {
-  return /[*?{[]/.test(path);
-}
-
-function coveredByGlob(path: string, globs: string[]): boolean {
-  return globs.length === 0 || globs.some((glob) => globMatches(glob, path));
-}
-
-function gitStatusChangedPaths(status: string): string[] {
-  const paths: string[] = [];
-  for (const line of status.split(/\r?\n/)) {
-    if (!line.trim() || line.startsWith("##") || line.length < 4) continue;
-    let path = line.slice(3).trim();
-    if (path.includes(" -> ")) path = path.slice(path.lastIndexOf(" -> ") + 4).trim();
-    if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
-    if (path && !paths.includes(path)) paths.push(path);
-  }
-  return paths;
-}
-
-function addReason(map: Map<string, { reasons: Set<string>; lines: Set<number> }>, path: string, reason: string, line?: number): void {
-  const entry = map.get(path) ?? { reasons: new Set<string>(), lines: new Set<number>() };
-  entry.reasons.add(reason);
-  if (typeof line === "number" && Number.isFinite(line)) entry.lines.add(Math.max(1, Math.trunc(line)));
-  map.set(path, entry);
-}
-
-function readableFile(repoRoot: string, policy: McpPolicy, path: string): { ok: true; path: string } | { ok: false; path: string; reason: string } {
-  const decision = resolveMcpPath(repoRoot, path, policy, "read");
-  if (!decision.ok || !decision.relativePath || !decision.absolutePath) {
-    return { ok: false, path: decision.relativePath ?? path, reason: decision.reason ?? "path denied" };
-  }
-  if (!existsSync(decision.absolutePath)) return { ok: false, path: decision.relativePath, reason: "path does not exist" };
-  if (!statSync(decision.absolutePath).isFile()) return { ok: false, path: decision.relativePath, reason: "path is not a file" };
-  return { ok: true, path: decision.relativePath };
-}
-
-interface ExpandedKnownPath {
-  files: string[];
-  denied: Array<{ path: string; reason: string }>;
-  directory?: string;
-  truncated: boolean;
-}
+export { CONTROLLER_CONTEXT_IMPACT_DOMAINS } from './context/types';
+export type {
+  ControllerContextImpactDomain,
+  ControllerContextPackDependencies,
+  ControllerContextPackFile,
+  ControllerContextPackOptions,
+  ControllerContextPackProjection,
+  ControllerContextPackSnippet,
+  ControllerContextRetrievalMode,
+  ControllerEvidenceReadiness,
+  ControllerContextExpansionState,
+  StructuralContextMode,
+} from './context/types';
 
-/**
- * Expand an explicit file or directory without following symlinks. Every file
- * is re-checked through resolveMcpPath so directory support never broadens the
- * policy boundary. Enumeration is deterministic and bounded.
- */
-function expandKnownPath(
-  repoRoot: string,
-  policy: McpPolicy,
-  path: string,
-  maxFiles: number,
-): ExpandedKnownPath {
-  const decision = resolveMcpPath(repoRoot, path, policy, "read");
-  if (!decision.ok || !decision.relativePath || !decision.absolutePath) {
-    return { files: [], denied: [{ path: decision.relativePath ?? path, reason: decision.reason ?? "path denied" }], truncated: false };
-  }
-  if (!existsSync(decision.absolutePath)) {
-    return { files: [], denied: [{ path: decision.relativePath, reason: "path does not exist" }], truncated: false };
-  }
-  const rootStat = lstatSync(decision.absolutePath);
-  if (rootStat.isSymbolicLink()) {
-    return { files: [], denied: [{ path: decision.relativePath, reason: "symbolic links are not followed" }], truncated: false };
-  }
-  if (rootStat.isFile()) return { files: [decision.relativePath], denied: [], truncated: false };
-  if (!rootStat.isDirectory()) {
-    return { files: [], denied: [{ path: decision.relativePath, reason: "path is neither a regular file nor directory" }], truncated: false };
-  }
+const MAX_CONTEXT_EVIDENCE_WAVES = 3;
+const SOURCE_REFERENCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'] as const;
 
-  const files: string[] = [];
-  const denied: Array<{ path: string; reason: string }> = [];
-  let truncated = false;
-  const walk = (relativeDirectory: string, depth: number): void => {
-    if (files.length >= maxFiles) { truncated = true; return; }
-    if (depth > 8) { denied.push({ path: relativeDirectory, reason: "directory recursion depth exceeded" }); return; }
-    const directoryDecision = resolveMcpPath(repoRoot, relativeDirectory, policy, "read");
-    if (!directoryDecision.ok || !directoryDecision.absolutePath || !directoryDecision.relativePath) {
-      denied.push({ path: directoryDecision.relativePath ?? relativeDirectory, reason: directoryDecision.reason ?? "path denied" });
-      return;
-    }
-    let entries;
-    try {
-      entries = readdirSync(directoryDecision.absolutePath, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
-    } catch (error) {
-      denied.push({ path: directoryDecision.relativePath, reason: error instanceof Error ? error.message : String(error) });
-      return;
-    }
-    for (const entry of entries) {
-      if (files.length >= maxFiles) { truncated = true; break; }
-      const child = `${directoryDecision.relativePath}/${entry.name}`.replace(/^\.\//, "");
-      if (entry.isSymbolicLink()) {
-        denied.push({ path: child, reason: "symbolic links are not followed" });
-      } else if (entry.isDirectory()) {
-        walk(child, depth + 1);
-      } else if (entry.isFile()) {
-        const readable = readableFile(repoRoot, policy, child);
-        if (readable.ok) files.push(readable.path);
-        else denied.push(readable);
-      }
+function sourceReferenceSpecifiers(contents: string): string[] {
+  const specifiers = new Set<string>();
+  const patterns = [
+    /\b(?:import|export)\s+(?:type\s+)?(?:[^'\"]*?\s+from\s+)?['\"]([^'\"]+)['\"]/g,
+    /\brequire\s*\(\s*['\"]([^'\"]+)['\"]\s*\)/g,
+    /\bimport\s*\(\s*['\"]([^'\"]+)['\"]\s*\)/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of contents.matchAll(pattern)) {
+      const value = match[1]?.trim();
+      if (value?.startsWith('.')) specifiers.add(value);
     }
-  };
-  walk(decision.relativePath, 0);
-  return { files, denied, directory: decision.relativePath, truncated };
-}
-
-function boundedSnippet(content: string, maxChars: number): { content: string; truncated: boolean } {
-  if (content.length <= maxChars) return { content, truncated: false };
-  return { content: `${content.slice(0, maxChars)}\n... <snippet truncated>`, truncated: true };
+  }
+  return Array.from(specifiers).slice(0, 24);
 }
 
-function mergeHitLines(lines: number[]): number[] {
-  const sorted = Array.from(new Set(lines.filter((line) => line > 0))).sort((a, b) => a - b);
-  const merged: number[] = [];
-  for (const line of sorted) {
-    const previous = merged[merged.length - 1];
-    if (previous !== undefined && line - previous <= DEFAULT_SNIPPET_CONTEXT_BEFORE + DEFAULT_SNIPPET_CONTEXT_AFTER) continue;
-    merged.push(line);
+function resolveSourceReference(repoRoot: string, policy: McpPolicy, sourcePath: string, specifier: string): string | undefined {
+  const base = posix.normalize(posix.join(posix.dirname(sourcePath), specifier));
+  if (!base || base === '..' || base.startsWith('../') || posix.isAbsolute(base)) return undefined;
+  const hasExtension = /\.[A-Za-z0-9]+$/.test(posix.basename(base));
+  const candidates = hasExtension
+    ? [base]
+    : [base, ...SOURCE_REFERENCE_EXTENSIONS.map((extension) => `${base}${extension}`), ...SOURCE_REFERENCE_EXTENSIONS.map((extension) => `${base}/index${extension}`)];
+  for (const candidate of candidates) {
+    const readable = readableFile(repoRoot, policy, candidate);
+    if (readable.ok) return readable.path;
   }
-  return merged;
+  return undefined;
 }
 
-function structuralResult(response: CodeGraphReadProviderResponse): {
-  nodes: CodeGraphNodeSummary[];
-  entryPoints: CodeGraphNodeSummary[];
-  relatedFiles: string[];
-  truncated: boolean;
-} {
-  const result = response.result ?? {};
-  const nodes = Array.isArray(result.nodes) ? result.nodes as CodeGraphNodeSummary[] : [];
-  const entryPoints = Array.isArray(result.entryPoints) ? result.entryPoints as CodeGraphNodeSummary[] : [];
-  const relatedFiles = Array.isArray(result.relatedFiles) ? result.relatedFiles.filter((value): value is string => typeof value === "string") : [];
-  return { nodes, entryPoints, relatedFiles, truncated: result.truncated === true };
+function contextPathPriority(path: string, reasons: string[]): number {
+  const testBonus = /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(path) ? 6 : 0;
+  const sourceBonus = reasons.some((reason) => reason.startsWith('source-reference:')) ? 5 : 0;
+  const structuralBonus = reasons.some((reason) => reason.startsWith('codegraph:')) ? 3 : 0;
+  return testBonus + sourceBonus + structuralBonus;
 }
 
 export function buildControllerContextPack(
@@ -432,9 +110,13 @@ export function buildControllerContextPack(
   options: ControllerContextPackOptions = {},
   dependencies: ControllerContextPackDependencies = {},
 ): ControllerContextPackProjection {
+  const contextStartedAt = performance.now();
+  const timingsMs = { gitAndFocus: 0, structural: 0, lexical: 0, materialization: 0, governance: 0, total: 0, waveCount: 1, expansionBudgetUsed: 0, expansionBudgetMax: 2 };
   const retrievalMode = options.retrievalMode ?? "implementation";
-  const maxFiles = clamp(options.maxFiles, DEFAULT_MAX_FILES, 1, 30);
-  const maxSnippets = clamp(options.maxSnippets, DEFAULT_MAX_SNIPPETS, 1, 80);
+  const requestedMaxFiles = clamp(options.maxFiles, DEFAULT_MAX_FILES, 1, 30);
+  const requestedMaxSnippets = clamp(options.maxSnippets, DEFAULT_MAX_SNIPPETS, 1, 80);
+  let maxFiles = requestedMaxFiles;
+  let maxSnippets = requestedMaxSnippets;
   const maxCharsPerSnippet = clamp(options.maxCharsPerSnippet, DEFAULT_MAX_CHARS_PER_SNIPPET, 500, 50_000);
   const knownPaths = cleanList(options.knownPaths);
   const knownGlobs = knownPaths.filter(looksLikeGlob);
@@ -447,13 +129,16 @@ export function buildControllerContextPack(
   // Independent investigations must not inherit an unrelated repository focus.
   // Only bind Issue/Task context when the caller explicitly requests it.
   const hasExplicitFocus = Boolean(options.issueId || options.taskId);
-  const git = gitSnapshot(repoRoot);
+  const git = gitSnapshot(repoRoot, options.session);
   const board = hasExplicitFocus && !legacyIssueAuthorityRetired(repoRoot) ? projectBoard(repoRoot) : undefined;
   const focus = board ? issueTaskFocus(board, options.issueId, options.taskId) : {};
   const ledger = board ? buildControllerTaskLedgerProjection(repoRoot, board) : undefined;
   const compactTask = ledger ? ledgerTask(ledger, focus.issue?.id, focus.task?.id) : undefined;
-  const allowedPathGlobs = cleanList(compactTask?.allowedPaths);
-  const searchIncludeGlobs = includeGlobs.length > 0 ? includeGlobs : allowedPathGlobs;
+  timingsMs.gitAndFocus = Math.round((performance.now() - contextStartedAt) * 100) / 100;
+  // Work allowed paths are an authorization boundary, not a claim that early
+  // investigation already discovered the complete semantic scope. Only an
+  // explicit retrieval include narrows discovery.
+  const searchIncludeGlobs = includeGlobs;
   const taskChecks = cleanList(compactTask?.checks);
   const goalParts = [
     options.description,
@@ -467,6 +152,7 @@ export function buildControllerContextPack(
   const impactDomains = cleanList(options.impactDomains)
     .filter((domain): domain is ControllerContextImpactDomain => CONTROLLER_CONTEXT_IMPACT_DOMAINS.includes(domain as ControllerContextImpactDomain))
     .slice(0, 6);
+  const retrievalIntent = [goal, ...terms].filter(Boolean).join(" ");
   const impactTermDomains = new Map<string, ControllerContextImpactDomain[]>();
   for (const domain of impactDomains) {
     for (const term of IMPACT_DOMAIN_TERMS[domain]) {
@@ -480,6 +166,11 @@ export function buildControllerContextPack(
     ...impactDomains.flatMap((domain) => IMPACT_DOMAIN_TERMS[domain]),
     ...terms.slice(1),
   ]).slice(0, 32);
+  // Preserve the guarantee for explicit code symbols while broad natural-
+  // language terms remain eligible for early discovery completion.
+  const requiredSearchQueries = cleanList(options.searchTerms)
+    .filter(isCodeShapedTerm)
+    .slice(0, 2);
   const impactCandidatePaths = new Map<ControllerContextImpactDomain, Set<string>>(impactDomains.map((domain) => [domain, new Set<string>()]));
   const candidates = new Map<string, { reasons: Set<string>; lines: Set<number> }>();
   const deniedPaths: Array<{ path: string; reason: string }> = [];
@@ -489,10 +180,15 @@ export function buildControllerContextPack(
   let skippedLargeFiles = 0;
   let skippedBinaryFiles = 0;
   let searchTruncated = false;
+  let lexicalCacheHit = false;
+  let structuralCacheHits = 0;
+  let structuralCacheMisses = 0;
+  let rangeCacheHits = 0;
+  let rangeCacheMisses = 0;
   const structuralMode = options.structuralContext ?? "off";
   const structuralIndexRoot = options.structuralIndexRoot?.trim() || repoRoot;
   const indexSource = structuralIndexRoot === repoRoot ? "current_checkout" : "repository_baseline";
-  const overlayChangedFiles = indexSource === "repository_baseline" ? gitStatusChangedPaths(git.status) : [];
+  let overlayChangedFiles = indexSource === "repository_baseline" ? gitStatusChangedPaths(git.status) : [];
   const baselineRevisionMatches = indexSource === "current_checkout" || gitSnapshot(structuralIndexRoot).head === git.head;
   const graphImpactFiles = new Set<string>();
   let structuralContext: ControllerContextPackProjection["structuralContext"] = {
@@ -507,9 +203,26 @@ export function buildControllerContextPack(
     relatedFiles: [],
     truncated: false,
   };
+  const repositorySessionCache = getRepositoryReadSessionCache(repoRoot, options.session);
+  const queryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
+  const queryStructural = (queryRoot: string, request: Parameters<typeof queryCodeGraphReadProvider>[1]): CodeGraphReadProviderResponse => {
+    const key = JSON.stringify({ queryRoot, request });
+    const cached = repositorySessionCache?.getStructural(key);
+    if (cached && typeof cached === "object") {
+      structuralCacheHits += 1;
+      return cached as CodeGraphReadProviderResponse;
+    }
+    structuralCacheMisses += 1;
+    const response = queryCodeGraph(queryRoot, request);
+    if (response.error?.code !== CODEGRAPH_PREFETCH_DEFERRED_CODE) {
+      repositorySessionCache?.putStructural(key, response);
+    }
+    return response;
+  };
 
+  const structuralStartedAt = performance.now();
   if (structuralMode !== "off") {
-    const structuralQuery = [goal || terms.join(" "), ...impactDomains].filter(Boolean).join(" ");
+    const structuralQuery = structuralIntentQuery(goal, terms, impactDomains);
     if (!structuralQuery) {
       structuralContext = {
         ...structuralContext,
@@ -518,8 +231,7 @@ export function buildControllerContextPack(
         fallbackReason: "No task description or search term was available for structural context.",
       };
     } else {
-      const queryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
-      const structural = queryCodeGraph(structuralIndexRoot, {
+      const structural = queryStructural(structuralIndexRoot, {
         operation: "context",
         query: structuralQuery,
         limit: Math.min(Math.max(maxFiles, 4), 12),
@@ -538,16 +250,28 @@ export function buildControllerContextPack(
             ignoredChangedFileCount: structural.metadata.ignoredChangedFileCount,
           }
         : undefined;
+      const providerChangedFiles = metadata
+        ? [...metadata.changedFiles.added, ...metadata.changedFiles.modified]
+        : [];
+      overlayChangedFiles = Array.from(new Set([...overlayChangedFiles, ...providerChangedFiles]));
+      const structuralEvidenceCurrent = structural.status === "ready"
+        && baselineRevisionMatches
+        && overlayChangedFiles.length === 0;
+      const structuralStatus = structural.status === "ready" && !structuralEvidenceCurrent
+        ? "stale"
+        : structural.status;
       structuralContext = {
         provider: "codegraph",
         requestedMode: structuralMode,
-        status: indexSource === "repository_baseline" && (!baselineRevisionMatches || overlayChangedFiles.length > 0) && structural.status === "ready" ? "stale" : structural.status,
-        requiredSatisfied: structuralMode !== "required" || (structural.status === "ready" && baselineRevisionMatches && overlayChangedFiles.length === 0),
+        status: structuralStatus,
+        requiredSatisfied: structuralMode !== "required" || structuralEvidenceCurrent,
         indexSource,
         overlayChangedFiles,
         baselineRevisionMatches,
         query: structuralQuery,
-        entryPoints: graph.entryPoints.slice(0, 12).map((node) => ({
+        entryPoints: graph.entryPoints
+          .filter((node) => pathNoisePenalty(node.filePath, retrievalIntent, retrievalMode) < 15)
+          .slice(0, 12).map((node) => ({
           id: node.id,
           kind: node.kind,
           name: node.name,
@@ -555,7 +279,9 @@ export function buildControllerContextPack(
           startLine: node.startLine,
           endLine: node.endLine,
         })),
-        relatedFiles: Array.from(new Set(graph.relatedFiles)).slice(0, 80),
+        relatedFiles: Array.from(new Set(graph.relatedFiles))
+          .filter((path) => pathNoisePenalty(path, retrievalIntent, retrievalMode) < 50)
+          .slice(0, 80),
         metadata,
         ...(structural.error ? { fallbackReason: `${structural.error.code}: ${structural.error.message}` } : {}),
         timingsMs: structural.timingsMs,
@@ -565,27 +291,31 @@ export function buildControllerContextPack(
       const addStructuralPath = (path: string, reason: string, line?: number): void => {
         if (!path || !coveredByGlob(path, searchIncludeGlobs) || excludeGlobs.some((glob) => globMatches(glob, path))) return;
         const readable = readableFile(repoRoot, policy, path);
-        if (!readable.ok) {
+        if (readable.ok === false) {
           deniedPaths.push({ path: readable.path, reason: readable.reason });
           return;
         }
         addReason(candidates, readable.path, reason, line);
       };
-      for (const node of graph.nodes.slice(0, maxFiles * 6)) {
-        addStructuralPath(node.filePath, `codegraph:context:${node.kind}:${node.name}`, node.startLine);
-      }
-      for (const node of graph.entryPoints) {
-        addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
-      }
-      for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
-      // Context search identifies the structural entry points. For a bounded
-      // number of those files, enrich the same Context Plane call with direct
-      // file dependencies/dependents. This is impact evidence, not a second
-      // routing/tool surface, and remains completely off for ordinary Direct.
-      if (structural.status === "ready") {
+      // Structural relationships may only influence discovery/materialization
+      // when the graph is current for this exact source identity. Stale graph
+      // nodes remain visible through structuralContext/impactContext hints, but
+      // must never steer which raw source GPT sees first.
+      if (structuralEvidenceCurrent) {
+        for (const node of graph.nodes.slice(0, maxFiles * 6)) {
+          addStructuralPath(node.filePath, `codegraph:context:${node.kind}:${node.name}`, node.startLine);
+        }
+        for (const node of graph.entryPoints) {
+          addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
+        }
+        for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
+        // Context search identifies the structural entry points. For a bounded
+        // number of those files, enrich the same Context Plane call with direct
+        // file dependencies/dependents. This is impact evidence, not a second
+        // routing/tool surface, and remains completely off for ordinary Direct.
         const primaryFiles = Array.from(new Set(graph.entryPoints.map((node) => node.filePath).filter(Boolean))).slice(0, 4);
         for (const filePath of primaryFiles) {
-          const adjacency = queryCodeGraph(structuralIndexRoot, { operation: "file_dependencies", filePath, limit: 40 });
+          const adjacency = queryStructural(structuralIndexRoot, { operation: "file_dependencies", filePath, limit: 40 });
           if (!adjacency.ok || adjacency.status !== "ready") continue;
           const dependencies = Array.isArray(adjacency.result?.dependencies)
             ? adjacency.result.dependencies.filter((value): value is string => typeof value === "string")
@@ -603,19 +333,23 @@ export function buildControllerContextPack(
           }
         }
       }
-      for (const path of metadata?.changedFiles.added ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
-      for (const path of metadata?.changedFiles.modified ?? []) addStructuralPath(path, "codegraph:changed-file", 1);
       for (const path of metadata?.changedFiles.removed ?? []) omitted.push({ path, reason: "codegraph reports file removed since index" });
-      for (const path of overlayChangedFiles) addStructuralPath(path, "worktree:changed-file", 1);
+      // A repository-baseline graph deliberately runs against another checkout.
+      // Current worktree changes are still authoritative raw-source evidence,
+      // but they come from Git rather than stale CodeGraph metadata.
+      if (indexSource === "repository_baseline") {
+        for (const path of gitStatusChangedPaths(git.status)) addStructuralPath(path, "worktree:changed-file", 1);
+      }
     }
   }
 
+  timingsMs.structural = Math.round((performance.now() - structuralStartedAt) * 100) / 100;
   const exactKnownFiles: string[] = [];
   let exactKnownFileScope = explicitKnownPaths.length > 0;
   for (const path of explicitKnownPaths) {
     const expanded = expandKnownPath(repoRoot, policy, path, Math.max(maxFiles * 4, 40));
     for (const file of expanded.files) {
-      addReason(candidates, file, expanded.directory ? `explicit-known-directory:${expanded.directory}` : "explicit-known-path", 1);
+      addReason(candidates, file, expanded.directory ? `explicit-known-directory:${expanded.directory}` : "explicit-known-path");
     }
     if (!expanded.directory && expanded.files.length === 1 && expanded.denied.length === 0 && !expanded.truncated) {
       exactKnownFiles.push(expanded.files[0]!);
@@ -626,10 +360,10 @@ export function buildControllerContextPack(
     scannedFiles += expanded.files.length;
     searchTruncated = searchTruncated || expanded.truncated;
   }
-
-  for (const glob of allowedPathGlobs) {
-    if (!includeGlobs.includes(glob)) includeGlobs.push(glob);
-  }
+  // Exact caller-selected files own a reserved file slot. The inferred-file
+  // budget may be smaller, but another ranked candidate must never displace an
+  // exact known file. The overall response remains bounded by the hard cap.
+  maxFiles = Math.min(30, Math.max(requestedMaxFiles, exactKnownFiles.length));
 
   // Exact known files are already a caller-selected implementation scope. When
   // no broader impact/structural/include scope was requested, search those files
@@ -644,7 +378,9 @@ export function buildControllerContextPack(
   // Lexical retrieval is one bounded pass across candidate files for all terms.
   // The old per-term loop reread the same source files up to 14 times even
   // though inventory itself was cached.
-  if (searchQueries.length > 0 && candidates.size < maxFiles * 3) {
+  const lexicalStartedAt = performance.now();
+  const requiredStructuralFallbackNeedsLexical = structuralMode === "required" && !structuralContext.requiredSatisfied;
+  if (searchQueries.length > 0 && (requiredStructuralFallbackNeedsLexical || candidates.size < maxFiles * 3)) {
     const search = searchRepositoryMany(repoRoot, policy, {
       queries: searchQueries,
       files: scopedExactKnownFileSearch ? exactKnownFiles : undefined,
@@ -654,7 +390,15 @@ export function buildControllerContextPack(
       maxFiles: scopedExactKnownFileSearch ? exactKnownFiles.length : MAX_TOTAL_SEARCHED_FILES,
       caseSensitive: false,
       cacheKey: JSON.stringify({ head: git.head, status: git.status, diffStat: git.diffStat }),
+      ...(!scopedExactKnownFileSearch ? {
+        completionMode: 'discovery' as const,
+        discoveryTargetFiles: Math.max(maxFiles * 2, 12),
+        discoveryMinQueryCoverage: Math.min(3, searchQueries.length),
+        requiredQueries: requiredSearchQueries,
+      } : {}),
+      session: options.session,
     });
+    lexicalCacheHit = search.cacheHit === true;
     scannedFiles += search.scannedFiles;
     policyDeniedFiles += search.policyDeniedFiles;
     skippedLargeFiles += search.skippedLargeFiles;
@@ -676,21 +420,50 @@ export function buildControllerContextPack(
     }
   }
 
+  timingsMs.lexical = Math.round((performance.now() - lexicalStartedAt) * 100) / 100;
   const primarySearchReason = terms.length > 0 ? `search:${terms[0]}` : undefined;
   const rankedCandidates = Array.from(candidates.entries())
     .map(([path, entry]) => ({ path, reasons: Array.from(entry.reasons), lines: Array.from(entry.lines) }))
     .sort((left, right) => {
-      const leftExplicit = left.reasons.some((reason) => reason === "explicit-known-path" || reason.startsWith("explicit-known-directory:")) ? 1 : 0;
-      const rightExplicit = right.reasons.some((reason) => reason === "explicit-known-path" || reason.startsWith("explicit-known-directory:")) ? 1 : 0;
+      const leftExplicit = left.reasons.includes("explicit-known-path")
+        ? 2
+        : left.reasons.some((reason) => reason.startsWith("explicit-known-directory:")) ? 1 : 0;
+      const rightExplicit = right.reasons.includes("explicit-known-path")
+        ? 2
+        : right.reasons.some((reason) => reason.startsWith("explicit-known-directory:")) ? 1 : 0;
       if (leftExplicit !== rightExplicit) return rightExplicit - leftExplicit;
       const leftPrimary = primarySearchReason && left.reasons.includes(primarySearchReason) ? 1 : 0;
       const rightPrimary = primarySearchReason && right.reasons.includes(primarySearchReason) ? 1 : 0;
       if (leftPrimary !== rightPrimary) return rightPrimary - leftPrimary;
+      const noise = pathNoisePenalty(left.path, retrievalIntent, retrievalMode)
+        - pathNoisePenalty(right.path, retrievalIntent, retrievalMode);
+      if (noise !== 0) return noise;
       if (left.reasons.length !== right.reasons.length) return right.reasons.length - left.reasons.length;
       if (left.lines.length !== right.lines.length) return right.lines.length - left.lines.length;
       return left.path.localeCompare(right.path);
     });
-  const selected = rankedCandidates.slice(0, maxFiles);
+  const isExactKnownCandidate = (entry: { reasons: string[] }): boolean => entry.reasons.includes("explicit-known-path");
+  // Adaptive closure is enabled whenever the caller asks for investigation/review
+  // evidence or leaves structural discovery enabled. A deliberately narrow
+  // implementation read with structural discovery disabled stays single-wave.
+  // This keeps the common exact-file edit path cheap without making the default
+  // implementation mode a permanent evidence-closure blind spot.
+  const multiWaveEligible = retrievalMode !== "implementation"
+    || structuralMode !== "off"
+    || impactDomains.length > 0
+    || explicitKnownPaths.length > 1;
+  timingsMs.expansionBudgetMax = multiWaveEligible ? Math.min(6, Math.max(2, Math.ceil(maxFiles / 2))) : 0;
+  const rankedExactKnownCount = rankedCandidates.filter(isExactKnownCandidate).length;
+  const initialCandidateLimit = multiWaveEligible
+    ? Math.min(maxFiles, Math.max(rankedExactKnownCount, Math.max(1, maxFiles - timingsMs.expansionBudgetMax)))
+    : maxFiles;
+  const selected = rankedCandidates.slice(0, initialCandidateLimit);
+  const deferredSelected = rankedCandidates.slice(initialCandidateLimit, maxFiles);
+  const selectedExactKnownCount = selected.filter(isExactKnownCandidate).length;
+  // Reserve at least one materialization for every selected exact known file.
+  // This may raise a caller's inferred snippet budget, but never beyond the
+  // existing hard response cap.
+  maxSnippets = Math.min(80, Math.max(requestedMaxSnippets, selectedExactKnownCount));
   const selectedPaths = new Set(selected.map((entry) => entry.path));
   const impactCoverage = impactDomains.map((domain) => {
     const matchedFiles = [...(impactCandidatePaths.get(domain) ?? new Set<string>())].sort();
@@ -708,40 +481,45 @@ export function buildControllerContextPack(
 
   let remainingSnippets = maxSnippets;
   const files: ControllerContextPackFile[] = [];
-  for (const entry of selected) {
+  const expansionDiscoveredPaths: string[] = [];
+  const expansionMaterializedPaths: string[] = [];
+  const materializationStartedAt = performance.now();
+  for (let selectedIndex = 0; selectedIndex < selected.length; selectedIndex += 1) {
+    const entry = selected[selectedIndex]!;
     if (remainingSnippets <= 0) {
       omitted.push({ path: entry.path, reason: "max_snippets" });
       continue;
     }
-    const hitLines = mergeHitLines(entry.lines.length > 0 ? entry.lines : [1]).slice(0, remainingSnippets);
-    const snippets: ControllerContextPackSnippet[] = [];
-    for (const line of hitLines) {
-      if (remainingSnippets <= 0) break;
-      try {
-        const raw = readRepositoryRange(
-          repoRoot,
-          policy,
-          entry.path,
-          Math.max(1, line - DEFAULT_SNIPPET_CONTEXT_BEFORE),
-          line + DEFAULT_SNIPPET_CONTEXT_AFTER,
-        );
-        const redacted = redactMcpText(raw.content);
-        const bounded = boundedSnippet(redacted.text, maxCharsPerSnippet);
-        snippets.push({
-          path: raw.path,
-          startLine: raw.startLine,
-          endLine: raw.endLine,
-          totalLines: raw.totalLines,
-          sha256: raw.sha256,
-          content: bounded.content,
-          truncated: bounded.truncated,
-          redactions: redacted.redactions,
-          reason: entry.reasons.join(", "),
-        });
-        remainingSnippets -= 1;
-      } catch (error) {
-        deniedPaths.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+    const exactKnown = isExactKnownCandidate(entry);
+    const exactKnownAfter = selected
+      .slice(selectedIndex + 1)
+      .filter(isExactKnownCandidate)
+      .length;
+    const waveOnePerFileCap = multiWaveEligible
+      ? Math.max(1, Math.ceil(maxSnippets / Math.max(1, initialCandidateLimit + timingsMs.expansionBudgetMax)))
+      : remainingSnippets;
+    const fileSnippetBudget = exactKnown
+      ? Math.max(1, remainingSnippets - exactKnownAfter)
+      : Math.min(remainingSnippets, waveOnePerFileCap);
+    let snippets: ControllerContextPackSnippet[] = [];
+    try {
+      snippets = materializeSource({
+        repoRoot,
+        policy,
+        path: entry.path,
+        hitLines: entry.lines.length > 0 ? entry.lines : [1],
+        reasons: entry.reasons,
+        maxSnippets: Math.min(fileSnippetBudget, remainingSnippets),
+        maxCharsPerSnippet,
+        session: options.session,
+      });
+      for (const snippet of snippets) {
+        if (snippet.cacheHit) rangeCacheHits += 1;
+        else rangeCacheMisses += 1;
       }
+      remainingSnippets -= snippets.length;
+    } catch (error) {
+      deniedPaths.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
     }
     if (snippets.length > 0) {
       files.push({
@@ -754,11 +532,152 @@ export function buildControllerContextPack(
     }
   }
 
+  // Evidence-closure eligible requests perform bounded internal waves after
+  // Wave 1 raw source materialization. Each later wave derives concrete paths
+  // from the source that was just read plus current CodeGraph adjacency, then
+  // materializes those paths in the same context request.
+  const materializedPathSet = new Set(files.map((file) => file.path));
+  let frontier = files.slice();
+  if (multiWaveEligible && frontier.length > 0 && timingsMs.expansionBudgetMax > 0) {
+    for (let wave = 2; wave <= MAX_CONTEXT_EVIDENCE_WAVES; wave += 1) {
+      if (frontier.length === 0 || timingsMs.expansionBudgetUsed >= timingsMs.expansionBudgetMax || files.length >= maxFiles || remainingSnippets <= 0) break;
+      const expansionReasons = new Map<string, { reasons: Set<string>; lines: Set<number> }>();
+      const addExpansionCandidate = (path: string, reason: string, line = 1): void => {
+        if (!path || materializedPathSet.has(path) || !coveredByGlob(path, searchIncludeGlobs) || excludeGlobs.some((glob) => globMatches(glob, path))) return;
+        const readable = readableFile(repoRoot, policy, path);
+        if (!readable.ok) {
+          if (/denied|policy/i.test(readable.reason)) deniedPaths.push({ path: readable.path, reason: readable.reason });
+          return;
+        }
+        const current = expansionReasons.get(readable.path) ?? { reasons: new Set<string>(), lines: new Set<number>() };
+        current.reasons.add(reason);
+        current.lines.add(line);
+        expansionReasons.set(readable.path, current);
+      };
+
+      for (const file of frontier.slice(0, 6)) {
+        const contents = file.snippets.map((snippet) => snippet.content).join('\n');
+        for (const specifier of sourceReferenceSpecifiers(contents)) {
+          const resolved = resolveSourceReference(repoRoot, policy, file.path, specifier);
+          if (resolved) addExpansionCandidate(resolved, `source-reference:${file.path}`);
+        }
+        if (structuralContext.status !== 'ready') continue;
+        const adjacency = queryStructural(structuralIndexRoot, { operation: 'file_dependencies', filePath: file.path, limit: 40 });
+        if (!adjacency.ok || adjacency.status !== 'ready') continue;
+        const dependencies = Array.isArray(adjacency.result?.dependencies)
+          ? adjacency.result.dependencies.filter((value): value is string => typeof value === 'string')
+          : [];
+        const dependents = Array.isArray(adjacency.result?.dependents)
+          ? adjacency.result.dependents.filter((value): value is string => typeof value === 'string')
+          : [];
+        for (const path of dependencies.slice(0, 40)) {
+          graphImpactFiles.add(path);
+          addExpansionCandidate(path, `codegraph:dependency:${file.path}`);
+        }
+        for (const path of dependents.slice(0, 40)) {
+          graphImpactFiles.add(path);
+          addExpansionCandidate(path, `codegraph:dependent:${file.path}`);
+        }
+      }
+
+      const expansionCandidates = Array.from(expansionReasons.entries())
+        .map(([path, entry]) => ({ path, reasons: Array.from(entry.reasons), lines: Array.from(entry.lines) }))
+        .sort((left, right) => {
+          const priority = contextPathPriority(right.path, right.reasons) - contextPathPriority(left.path, left.reasons);
+          if (priority !== 0) return priority;
+          if (left.reasons.length !== right.reasons.length) return right.reasons.length - left.reasons.length;
+          return left.path.localeCompare(right.path);
+        });
+      expansionDiscoveredPaths.push(...expansionCandidates.map((entry) => entry.path));
+      if (expansionCandidates.length === 0) break;
+
+      const nextFrontier: ControllerContextPackFile[] = [];
+      for (const entry of expansionCandidates) {
+        if (timingsMs.expansionBudgetUsed >= timingsMs.expansionBudgetMax || files.length >= maxFiles || remainingSnippets <= 0) break;
+        try {
+          const snippets = materializeSource({
+            repoRoot,
+            policy,
+            path: entry.path,
+            hitLines: entry.lines.length > 0 ? entry.lines : [1],
+            reasons: entry.reasons,
+            maxSnippets: Math.min(3, remainingSnippets),
+            maxCharsPerSnippet,
+            session: options.session,
+          });
+          for (const snippet of snippets) {
+            if (snippet.cacheHit) rangeCacheHits += 1;
+            else rangeCacheMisses += 1;
+          }
+          remainingSnippets -= snippets.length;
+          if (snippets.length === 0) continue;
+          const materialized: ControllerContextPackFile = {
+            path: entry.path,
+            reasons: entry.reasons,
+            hitLines: Array.from(new Set(entry.lines)).sort((a, b) => a - b).slice(0, 30),
+            snippetCount: snippets.length,
+            snippets,
+          };
+          files.push(materialized);
+          materializedPathSet.add(entry.path);
+          expansionMaterializedPaths.push(entry.path);
+          nextFrontier.push(materialized);
+          timingsMs.expansionBudgetUsed += 1;
+        } catch (error) {
+          deniedPaths.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      if (nextFrontier.length === 0) break;
+      timingsMs.waveCount = wave;
+      frontier = nextFrontier;
+    }
+  }
+
+  // Fill any reserved first-pass candidates only after expansion has had a
+  // chance to use its bounded slots; this preserves ordinary discovery evidence
+  // when no higher-value relationship is found.
+  for (const entry of deferredSelected) {
+    if (files.length >= maxFiles || remainingSnippets <= 0 || materializedPathSet.has(entry.path)) continue;
+    try {
+      const snippets = materializeSource({
+        repoRoot,
+        policy,
+        path: entry.path,
+        hitLines: entry.lines.length > 0 ? entry.lines : [1],
+        reasons: entry.reasons,
+        maxSnippets: remainingSnippets,
+        maxCharsPerSnippet,
+        session: options.session,
+      });
+      for (const snippet of snippets) {
+        if (snippet.cacheHit) rangeCacheHits += 1;
+        else rangeCacheMisses += 1;
+      }
+      remainingSnippets -= snippets.length;
+      if (snippets.length > 0) {
+        files.push({
+          path: entry.path,
+          reasons: entry.reasons,
+          hitLines: Array.from(new Set(entry.lines)).sort((a, b) => a - b).slice(0, 30),
+          snippetCount: snippets.length,
+          snippets,
+        });
+        materializedPathSet.add(entry.path);
+      }
+    } catch (error) {
+      deniedPaths.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  timingsMs.materialization = Math.round((performance.now() - materializationStartedAt) * 100) / 100;
   if (files.length === 0 && terms.length === 0 && explicitKnownPaths.length === 0) {
     omitted.push({ path: "<none>", reason: "No description, search_terms, issue/task focus, or known_paths produced search terms." });
   }
 
   const rawSnippetTruncated = files.some((file) => file.snippets.some((snippet) => snippet.truncated));
+  const unresolvedExpansionPaths = Array.from(new Set(expansionDiscoveredPaths)).filter((path) => !files.some((file) => file.path === path));
+  const expansionBudgetExhausted = unresolvedExpansionPaths.length > 0
+    && (timingsMs.expansionBudgetUsed >= timingsMs.expansionBudgetMax || files.length >= maxFiles || remainingSnippets <= 0);
   const expansionSignals = [
     ...(files.length === 0 ? ["no_current_raw_source"] : []),
     ...(rawSnippetTruncated ? ["raw_snippet_truncated"] : []),
@@ -768,6 +687,7 @@ export function buildControllerContextPack(
     ...(structuralMode === "required" && !structuralContext.requiredSatisfied ? ["required_structural_context_unavailable"] : []),
     ...(policyDeniedFiles > 0 || deniedPaths.length > 0 ? ["policy_denied_candidates"] : []),
     ...(skippedLargeFiles > 0 ? ["large_candidates_skipped"] : []),
+    ...(expansionBudgetExhausted ? ["evidence_expansion_budget_exhausted"] : []),
     ...impactCoverage.flatMap((coverage) => coverage.status === "no_evidence"
       ? [`impact_domain_without_evidence:${coverage.domain}`]
       : coverage.status === "matched_not_selected"
@@ -777,12 +697,18 @@ export function buildControllerContextPack(
   const rawCodeRequiredForImplementation = retrievalMode !== "implementation"
     || files.length === 0
     || rawSnippetTruncated;
-  const primaryTargets = Array.from(new Set(structuralContext.entryPoints.map((entry) => entry.filePath).filter(Boolean))).slice(0, 20);
+  const graphEntryPaths = Array.from(new Set(structuralContext.entryPoints.map((entry) => entry.filePath).filter(Boolean))).slice(0, 20);
+  const structuralEvidenceCurrent = structuralContext.status === "ready";
+  const primaryTargets = structuralEvidenceCurrent ? graphEntryPaths : [];
+  const structuralHints = structuralEvidenceCurrent
+    ? []
+    : Array.from(new Set([...graphEntryPaths, ...graphImpactFiles, ...structuralContext.relatedFiles])).slice(0, 80);
   const structuralUniverse = Array.from(new Set([
-    ...primaryTargets,
+    ...graphEntryPaths,
     ...graphImpactFiles,
     ...structuralContext.relatedFiles,
     ...selected.map((entry) => entry.path),
+    ...files.map((file) => file.path),
   ])).slice(0, 160);
   const relevantTests = structuralUniverse.filter((path) => /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(path)).slice(0, 40);
   const architectureContracts = structuralUniverse.filter((path) =>
@@ -791,7 +717,9 @@ export function buildControllerContextPack(
     || path.startsWith("docs/architecture/")
     || path.startsWith(".ai/context/"),
   ).slice(0, 40);
-  const mustInspect = Array.from(new Set([...primaryTargets, ...graphImpactFiles, ...relevantTests, ...architectureContracts])).slice(0, 80);
+  const mustInspect = structuralEvidenceCurrent
+    ? Array.from(new Set([...primaryTargets, ...graphImpactFiles, ...relevantTests, ...architectureContracts])).slice(0, 80)
+    : [];
   const mustInspectSet = new Set(mustInspect);
   const likelyAffected = structuralUniverse.filter((path) => !mustInspectSet.has(path)).slice(0, 80);
   const changedFileCount = structuralContext.metadata
@@ -816,6 +744,7 @@ export function buildControllerContextPack(
         ? "medium"
         : "low",
     primaryTargets,
+    structuralHints,
     mustInspect,
     likelyAffected,
     relevantTests,
@@ -836,6 +765,111 @@ export function buildControllerContextPack(
       baselineRevisionMatches: structuralContext.baselineRevisionMatches,
     },
   };
+  const inspectedFiles = files.map((file) => file.path);
+  const instructionContext = buildRepositoryInstructionContext(
+    repoRoot,
+    policy,
+    [...exactKnownFiles, ...inspectedFiles],
+    { maxCharsPerContract: Math.min(maxCharsPerSnippet, 12_000) },
+  );
+  const governanceStartedAt = performance.now();
+  const governanceResolution = resolveRepositoryGovernance(repoRoot, policy, {
+    goal,
+    targetPaths: [...exactKnownFiles, ...inspectedFiles],
+    changedPaths: gitStatusChangedPaths(git.status),
+  });
+  const availableChecks = governanceResolution.recommendedCheckIds.length > 0
+    ? new Map(listControllerChecks(repoRoot).map((check) => [check.id, check]))
+    : new Map();
+  const governanceContext: ControllerContextPackProjection['governanceContext'] = {
+    ...governanceResolution,
+    recommendedChecks: governanceResolution.recommendedCheckIds.map((checkId) => {
+      const check = availableChecks.get(checkId);
+      const ruleIds = governanceResolution.activeRules.filter((rule) => rule.checkIds.includes(checkId)).map((rule) => rule.id).sort();
+      if (!check) return { checkId, ruleIds, available: false };
+      const selection = controllerCheckSelection(check);
+      return { checkId, ruleIds, available: true, ...selection };
+    }),
+    coverageGaps: [
+      ...governanceResolution.coverageGaps,
+      ...governanceResolution.recommendedCheckIds
+        .filter((checkId) => !availableChecks.has(checkId))
+        .map((checkId) => `governance_check_unregistered:${checkId}`),
+    ].filter((value, index, values) => values.indexOf(value) === index).slice(0, 80),
+  };
+  if (governanceContext.coverageGaps.length > 0 && governanceContext.status === 'ready') governanceContext.status = 'degraded';
+  timingsMs.governance = Math.round((performance.now() - governanceStartedAt) * 100) / 100;
+  const inspectedSet = new Set(inspectedFiles);
+  const likelyRelatedNotInspected = Array.from(new Set([
+    ...rankedCandidates.map((entry) => entry.path),
+    ...structuralContext.relatedFiles,
+    ...graphImpactFiles,
+    ...expansionDiscoveredPaths,
+  ])).filter((path) => !inspectedSet.has(path)).slice(0, 80);
+  const materializedExactKnownPaths = files
+    .filter((file) => file.reasons.includes("explicit-known-path"))
+    .map((file) => file.path);
+  const materializedExactKnownSet = new Set(materializedExactKnownPaths);
+  const unresolvedRelationships = Array.from(new Set([
+    ...coverageGaps,
+    ...expansionSignals,
+    ...(likelyRelatedNotInspected.length > 0 ? ["likely_related_files_not_inspected"] : []),
+  ])).slice(0, 80);
+  const materialRelationshipUnresolved = unresolvedExpansionPaths.length > 0;
+  const readinessReasonCodes = Array.from(new Set([
+    ...(files.length === 0 ? ["raw_source_unavailable"] : []),
+    ...(rawSnippetTruncated ? ["raw_source_truncated"] : []),
+    ...(searchTruncated ? ["retrieval_truncated"] : []),
+    ...(structuralMode === "required" && !structuralContext.requiredSatisfied ? ["required_structural_context_unsatisfied"] : []),
+    ...(structuralContext.status === "stale" ? ["structural_context_stale"] : []),
+    ...(structuralContext.status === "unavailable" || structuralContext.status === "degraded" ? ["structural_provider_degraded"] : []),
+    ...(policyDeniedFiles > 0 || deniedPaths.length > 0 ? ["policy_denied_evidence"] : []),
+    ...(skippedLargeFiles > 0 ? ["large_evidence_skipped"] : []),
+    ...(expansionBudgetExhausted ? ["expansion_budget_exhausted"] : []),
+    ...(materialRelationshipUnresolved ? ["material_relationship_unresolved"] : []),
+    ...(likelyRelatedNotInspected.length > 0 ? ["related_evidence_not_materialized"] : []),
+  ])).slice(0, 40);
+  const readinessStatus = files.length === 0
+    || (structuralMode === "required" && !structuralContext.requiredSatisfied)
+    || materialRelationshipUnresolved
+    ? "insufficient" as const
+    : readinessReasonCodes.length > 0
+      ? "degraded" as const
+      : "ready" as const;
+  const readiness: ControllerContextPackProjection["readiness"] = {
+    status: readinessStatus,
+    sourceRevision: git.head,
+    rawSource: {
+      status: files.length === 0 ? "unavailable" : rawSnippetTruncated ? "partial" : "current",
+      materializedFileCount: files.length,
+      snippetTruncated: rawSnippetTruncated,
+    },
+    structural: {
+      requested: structuralMode,
+      status: structuralContext.status,
+      requiredSatisfied: structuralContext.requiredSatisfied,
+      baselineRevisionMatches: structuralContext.baselineRevisionMatches,
+      overlayChangedFileCount: structuralContext.overlayChangedFiles.length,
+    },
+    semantic: { status: "not_requested", reasonCodes: ["semantic_navigation_not_requested"] },
+    retrieval: {
+      searchTruncated,
+      omittedCandidateCount: rankedCandidates.filter((entry) => !inspectedSet.has(entry.path)).length,
+      policyDeniedCandidateCount: policyDeniedFiles + deniedPaths.length,
+      likelyRelatedNotInspectedCount: likelyRelatedNotInspected.length,
+    },
+    unresolvedReasonCodes: readinessReasonCodes,
+    readyForHighConfidenceMutation: readinessStatus === "ready",
+  };
+  const expansion: ControllerContextPackProjection["expansion"] = {
+    waveCount: timingsMs.waveCount,
+    expansionPerformed: timingsMs.waveCount > 1,
+    expansionBudgetUsed: timingsMs.expansionBudgetUsed,
+    expansionBudgetMax: timingsMs.expansionBudgetMax,
+    discoveredPaths: Array.from(new Set(expansionDiscoveredPaths)).slice(0, 30),
+    materializedPaths: Array.from(new Set(expansionMaterializedPaths)).slice(0, 30),
+  };
+  timingsMs.total = Math.round((performance.now() - contextStartedAt) * 100) / 100;
 
   return {
     schemaVersion: CONTEXT_PACK_SCHEMA_VERSION,
@@ -861,31 +895,83 @@ export function buildControllerContextPack(
       skippedLargeFiles,
       skippedBinaryFiles,
       truncated: searchTruncated,
+      cacheHit: lexicalCacheHit,
     },
+    instructionContext,
+    governanceContext,
     structuralContext,
     impactContext,
+    readiness,
+    expansion,
     files,
+    coverage: {
+      inspectedFiles,
+      likelyRelatedNotInspected,
+      unresolvedRelationships,
+      relevantTests,
+      exactKnownPaths: {
+        requested: exactKnownFiles,
+        materialized: materializedExactKnownPaths,
+        missing: exactKnownFiles.filter((path) => !materializedExactKnownSet.has(path)),
+      },
+      skippedCandidates: {
+        omittedFiles: Math.max(0, rankedCandidates.length - selected.length),
+        policyDeniedFiles: policyDeniedFiles + deniedPaths.length,
+        largeFiles: skippedLargeFiles,
+        binaryFiles: skippedBinaryFiles,
+        searchTruncated,
+        structuralTruncated: structuralContext.truncated,
+      },
+      materialization: {
+        completeFiles: files.flatMap((file) => file.snippets).filter((snippet) => snippet.materialization === "complete_file").length,
+        symbols: files.flatMap((file) => file.snippets).filter((snippet) => snippet.materialization === "symbol").length,
+        fallbackWindows: files.flatMap((file) => file.snippets).filter((snippet) => snippet.materialization === "line_window").length,
+      },
+    },
+    cache: {
+      sessionBound: Boolean(options.session),
+      lexicalHit: lexicalCacheHit,
+      structuralHits: structuralCacheHits,
+      structuralMisses: structuralCacheMisses,
+      rangeHits: rangeCacheHits,
+      rangeMisses: rangeCacheMisses,
+      reused: lexicalCacheHit || structuralCacheHits > 0 || rangeCacheHits > 0,
+    },
+    timingsMs,
     deniedPaths: deniedPaths.slice(0, 20),
     omitted: omitted.slice(0, 30),
-    limits: { maxFiles, maxSnippets, maxCharsPerSnippet },
+    limits: {
+      maxFiles,
+      maxSnippets,
+      maxCharsPerSnippet,
+      requestedMaxFiles,
+      requestedMaxSnippets,
+      reservedExactKnownFiles: selectedExactKnownCount,
+    },
     validation: {
       policy: taskChecks.length > 0 ? "task-targeted" : "minimal",
       checks: taskChecks,
     },
     contextContract: {
       strategy: retrievalMode === "implementation"
-        ? "Use the returned current raw snippets plus bounded impact evidence as the implementation decision input. ChatGPT owns semantic sufficiency; do not re-read source solely because it arrived through search."
-        : "Use this pack as investigation evidence and deliberately expand the evidence surface when the selected mode requires planning, debugging, or review.",
+        ? "Use one broad current-source pack to discover credible entry points, then progressively expand from returned paths and symbols. Lexical terms are heuristic hints rather than completeness requirements. ChatGPT owns semantic sufficiency and should prefer targeted known_paths, compiler semantic navigation for concrete TypeScript symbols, or structural relationships before repeating broad lexical discovery."
+        : "Use the bounded evidence-closure waves already performed inside this rh_context call. Repeat rh_context only when unresolved material relationships remain after the internal expansion budget, or when the Controller intentionally changes evidence scope.",
       retrievalMode,
       semanticSufficiencyAuthority: "chatgpt",
       rawCodeRequiredForImplementation,
       expansionSignals,
       notes: [
         retrievalMode === "implementation"
-          ? "The pack already contains policy-approved current raw source snippets with file SHA identities. Request wider/exact ranges only when ChatGPT judges the impact surface ambiguous or an expansion signal makes the raw evidence mechanically incomplete."
-          : "Investigation modes may intentionally expand exact ranges, structural relationships, tests, and neighboring modules before any implementation decision.",
-        "Search/CodeGraph ranking is discovery evidence, not a business-semantics authority. impactContext makes the bounded evidence surface and coverage gaps explicit; ChatGPT still decides semantic sufficiency.",
+          ? "The pack contains policy-approved current raw source with file SHA identities, but returned snippets are bounded evidence rather than proof of semantic completeness. After reading this evidence, derive new exact paths, symbols, tests, or relationships from the source itself. A guessed lexical term with no result is not by itself a reason to keep scanning or repeat the same broad query."
+          : `Investigation mode performed ${timingsMs.waveCount} bounded evidence wave(s) inside this request; expansion budget ${timingsMs.expansionBudgetUsed}/${timingsMs.expansionBudgetMax}.`,
+        "Search/CodeGraph ranking is discovery evidence, not a business-semantics authority. readiness and impactContext make the bounded evidence surface and unresolved gaps explicit; ChatGPT still decides semantic sufficiency.",
+        instructionContext.contracts.length > 0
+          ? `Applicable repository guidance was resolved hierarchically for selected source paths: ${instructionContext.contracts.map((entry) => entry.path).join(", ")}. These AGENTS.md/CLAUDE.md files are guidance-only evidence and do not define semantic scope.`
+          : "No applicable AGENTS.md/CLAUDE.md guidance file was found for the selected source paths.",
         impactDomains.length > 0 ? `Impact domains were selected by ChatGPT and expanded mechanically in this same retrieval call: ${impactDomains.join(", ")}. Missing or omitted domain evidence is an ambiguity signal, not proof that the domain is irrelevant.` : "No explicit cross-cutting impact domains were requested; ChatGPT may add them when state, scheduling, notifications, events, caching, API, or concurrency could materially change the implementation.",
+        governanceContext.status === 'none'
+          ? "No repository governance rule registry is present; existing guidance and explicit Task checks behave as before."
+          : `Repository governance resolved ${governanceContext.activeRules.length} active rule(s), ${governanceContext.suppressedRules.length} suppressed rule(s), and ${governanceContext.recommendedCheckIds.length} recommended check(s) through bounded local matching. Recommendations are evidence only and never execute checks or create Work by themselves.`,
         "CodeGraph structural evidence is discovery evidence. Raw source access still passes through Forge repository policy and current-file reads.",
         structuralContext.status === "stale" ? "CodeGraph reports stale structural evidence. Treat graph relationships as hints and prefer the returned current raw source for changed files." : structuralContext.status === "unavailable" || structuralContext.status === "degraded" ? "Structural context was unavailable or degraded; bounded text search remains the fallback." : structuralContext.status === "ready" ? "CodeGraph structural context was queried read-only with index sync disabled." : "Structural context was not requested.",
         "Run focused validation after a coherent edit batch; expensive full-suite checks belong at candidate/release boundaries unless debugging specifically needs them earlier.",
@@ -898,7 +984,7 @@ export function buildControllerContextPack(
         : []),
       files.length > 0
         ? retrievalMode === "implementation"
-          ? "ChatGPT should decide whether the impact coverage is sufficient; if yes, edit directly from the returned current raw snippets and SHA identities instead of issuing a mandatory second read."
+          ? "ChatGPT should decide whether impact coverage is sufficient. Edit when it is; otherwise derive the next exact paths/symbols/tests from this source and repeat rh_context narrowly. For concrete TypeScript symbols prefer semantic navigation; use another broad lexical pass only when no credible entry point exists or a dynamic/string/config edge still needs discovery."
           : "Expand exact ranges or neighboring evidence when that investigation can materially change the plan, diagnosis, or review conclusion."
         : "Provide known_paths or narrower search_terms before attempting implementation.",
       "After editing, review the bounded diff/evidence for the coherent edit batch.",
@@ -906,3 +992,258 @@ export function buildControllerContextPack(
     ],
   };
 }
+
+/**
+ * Broad first-call fan-in for the canonical rh_context path. Lexical retrieval
+ * remains required evidence. Auto CodeGraph is opportunistic enrichment: it may
+ * finish inside the first-call latency budget, otherwise the request returns
+ * bounded lexical/raw evidence while the same source-bound structural request
+ * continues warming the session cache. Required structural mode still waits.
+ */
+export const AUTO_STRUCTURAL_PREFETCH_BUDGET_MS = 100;
+export const AUTO_STRUCTURAL_PREFETCH_TIMEOUT_MS = 1_000;
+const CODEGRAPH_PREFETCH_DEFERRED_CODE = 'CODEGRAPH_PREFETCH_DEFERRED';
+const structuralPrefetchInflight = new Map<string, Promise<CodeGraphReadProviderResponse>>();
+
+function codeGraphPrefetchDeferredResponse(elapsedMs: number): CodeGraphReadProviderResponse {
+  return {
+    schemaVersion: 1,
+    provider: 'codegraph',
+    operation: 'context',
+    ok: false,
+    status: 'degraded',
+    error: {
+      code: CODEGRAPH_PREFETCH_DEFERRED_CODE,
+      message: `Optional CodeGraph enrichment exceeded the ${AUTO_STRUCTURAL_PREFETCH_BUDGET_MS}ms first-call budget and continues warming the source-bound session cache.`,
+    },
+    timingsMs: { total: Math.round(elapsedMs * 100) / 100 },
+  };
+}
+
+async function settleWithinBudget<T>(promise: Promise<T>, budgetMs: number): Promise<{ settled: true; value: T } | { settled: false }> {
+  if (budgetMs <= 0) return { settled: false };
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      promise.then((value) => ({ settled: true as const, value })),
+      new Promise<{ settled: false }>((resolveBudget) => {
+        timer = setTimeout(() => resolveBudget({ settled: false }), budgetMs);
+        timer.unref();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function cacheDeferredStructuralResult(
+  sessionCache: ReturnType<typeof getRepositoryReadSessionCache>,
+  structuralCacheKey: string,
+  sourceIdentity: string | undefined,
+  response: CodeGraphReadProviderResponse,
+): void {
+  if (!sessionCache || !sourceIdentity) return;
+  if (response.error?.code === 'CODEGRAPH_TIMEOUT' || response.error?.code === CODEGRAPH_PREFETCH_DEFERRED_CODE) return;
+  if (JSON.stringify(sessionCache.currentIdentity()) !== sourceIdentity) return;
+  sessionCache.putStructural(structuralCacheKey, response);
+}
+
+export async function buildControllerContextPackAsync(
+  repoRoot: string,
+  policy: McpPolicy,
+  options: ControllerContextPackOptions = {},
+  dependencies: ControllerContextPackDependencies = {},
+): Promise<ControllerContextPackProjection> {
+  const structuralMode = options.structuralContext ?? 'off';
+  if ((dependencies.queryCodeGraph && !dependencies.queryCodeGraphAsync) || !options.session || options.issueId || options.taskId) {
+    return buildControllerContextPack(repoRoot, policy, options, dependencies);
+  }
+  const prefetchStartedAt = performance.now();
+  const retrievalMode = options.retrievalMode ?? 'implementation';
+  const requestedMaxFiles = clamp(options.maxFiles, DEFAULT_MAX_FILES, 1, 30);
+  const knownPaths = cleanList(options.knownPaths);
+  const knownGlobs = knownPaths.filter(looksLikeGlob);
+  const explicitKnownPaths = knownPaths.filter((path) => !looksLikeGlob(path));
+  const includeGlobs = cleanList([...(options.includeGlobs ?? []), ...knownGlobs]);
+  const excludeGlobs = cleanList([...DEFAULT_SEARCH_EXCLUDE_GLOBS, ...(options.excludeGlobs ?? [])]);
+  const terms = cleanList([...(options.searchTerms ?? []), ...textTokens(options.description ?? '')]).slice(0, 14);
+  const impactDomains = cleanList(options.impactDomains)
+    .filter((domain): domain is ControllerContextImpactDomain => CONTROLLER_CONTEXT_IMPACT_DOMAINS.includes(domain as ControllerContextImpactDomain))
+    .slice(0, 6);
+  const exactKnownFiles: string[] = [];
+  let exactKnownFileScope = explicitKnownPaths.length > 0;
+  for (const path of explicitKnownPaths) {
+    const expanded = expandKnownPath(repoRoot, policy, path, Math.max(requestedMaxFiles * 4, 40));
+    if (!expanded.directory && expanded.files.length === 1 && expanded.denied.length === 0 && !expanded.truncated) {
+      exactKnownFiles.push(expanded.files[0]!);
+    } else {
+      exactKnownFileScope = false;
+    }
+  }
+  const maxFiles = Math.min(30, Math.max(requestedMaxFiles, exactKnownFiles.length));
+  const scopedExactKnownFileSearch = exactKnownFileScope
+    && retrievalMode === 'implementation'
+    && structuralMode === 'off'
+    && impactDomains.length === 0
+    && includeGlobs.length === 0;
+  const searchQueries = cleanList([
+    ...(terms[0] ? [terms[0]] : []),
+    ...impactDomains.flatMap((domain) => IMPACT_DOMAIN_TERMS[domain]),
+    ...terms.slice(1),
+  ]).slice(0, 32);
+  const requiredSearchQueries = cleanList(options.searchTerms)
+    .filter(isCodeShapedTerm)
+    .slice(0, 2);
+  const structuralQuery = structuralMode === 'off'
+    ? ''
+    : structuralIntentQuery(options.description ?? '', terms, impactDomains);
+  const structuralIndexRoot = options.structuralIndexRoot?.trim() || repoRoot;
+  const structuralRequest = {
+    operation: 'context' as const,
+    query: structuralQuery,
+    limit: Math.min(Math.max(maxFiles, 4), 12),
+    maxNodes: Math.min(Math.max(maxFiles * 5, 20), 60),
+    maxDepth: 2,
+  };
+  const structuralCacheKey = JSON.stringify({ queryRoot: structuralIndexRoot, request: structuralRequest });
+  const sessionCache = getRepositoryReadSessionCache(repoRoot, options.session);
+  const structuralSourceIdentity = sessionCache ? JSON.stringify(sessionCache.currentIdentity()) : undefined;
+  const cachedStructural = structuralQuery
+    ? sessionCache?.peekStructural(structuralCacheKey) as CodeGraphReadProviderResponse | undefined
+    : undefined;
+  const lexicalOptions = searchQueries.length > 0
+    ? (() => {
+        const git = gitSnapshot(repoRoot, options.session);
+        return {
+          queries: searchQueries,
+          files: scopedExactKnownFileSearch ? exactKnownFiles : undefined,
+          includeGlobs: scopedExactKnownFileSearch ? undefined : includeGlobs,
+          excludeGlobs,
+          maxResultsPerQuery: Math.max(maxFiles * 4, 12),
+          maxFiles: scopedExactKnownFileSearch ? exactKnownFiles.length : MAX_TOTAL_SEARCHED_FILES,
+          caseSensitive: false,
+          cacheKey: JSON.stringify({ head: git.head, status: git.status, diffStat: git.diffStat }),
+          ...(!scopedExactKnownFileSearch ? {
+            completionMode: 'discovery' as const,
+            discoveryTargetFiles: Math.max(maxFiles * 2, 12),
+            discoveryMinQueryCoverage: Math.min(3, searchQueries.length),
+            requiredQueries: requiredSearchQueries,
+          } : {}),
+        };
+      })()
+    : undefined;
+  const lexicalIdentity = lexicalOptions ? searchRepositoryManyCacheIdentity(lexicalOptions) : undefined;
+  const cachedLexical = lexicalIdentity && sessionCache
+    ? sessionCache.getSearch(lexicalIdentity.batchQueryKey, lexicalIdentity.includeKey)
+    : undefined;
+  if ((!structuralQuery || cachedStructural) && (!lexicalIdentity || cachedLexical?.result)) {
+    const pack = buildControllerContextPack(repoRoot, policy, options, dependencies);
+    pack.timingsMs.parallelFirstPass = false;
+    pack.timingsMs.parallelPrefetch = 0;
+    pack.timingsMs.structuralPrefetchBudgetMs = structuralMode === 'auto' && structuralQuery ? AUTO_STRUCTURAL_PREFETCH_BUDGET_MS : 0;
+    pack.timingsMs.structuralPrefetchDeferred = false;
+    pack.timingsMs.structuralPrefetchReusedInFlight = false;
+    return pack;
+  }
+
+  const noStructuralResponse: CodeGraphReadProviderResponse = {
+    schemaVersion: 1,
+    provider: 'codegraph',
+    operation: 'context',
+    ok: false,
+    status: 'degraded',
+    error: { code: 'CODEGRAPH_QUERY_REQUIRED', message: 'No context query was provided.' },
+    timingsMs: { total: 0 },
+  };
+  let structuralSettled = Boolean(cachedStructural) || !structuralQuery;
+  let structuralSettledValue: CodeGraphReadProviderResponse | undefined = cachedStructural || (!structuralQuery ? noStructuralResponse : undefined);
+  const queryCodeGraphAsync = dependencies.queryCodeGraphAsync ?? queryCodeGraphReadProviderAsync;
+  const structuralInflightKey = structuralQuery && structuralSourceIdentity
+    ? JSON.stringify({ structuralCacheKey, sourceIdentity: structuralSourceIdentity, structuralMode })
+    : undefined;
+  const existingStructuralInflight = structuralInflightKey ? structuralPrefetchInflight.get(structuralInflightKey) : undefined;
+  const structuralPrefetchReusedInFlight = Boolean(existingStructuralInflight);
+  const launchedStructuralPromise = cachedStructural
+    ? Promise.resolve(cachedStructural)
+    : structuralQuery
+      ? existingStructuralInflight ?? queryCodeGraphAsync(
+          structuralIndexRoot,
+          structuralRequest,
+          structuralMode === 'auto' ? { timeoutMs: AUTO_STRUCTURAL_PREFETCH_TIMEOUT_MS } : {},
+        )
+      : Promise.resolve(noStructuralResponse);
+  if (structuralInflightKey && structuralQuery && !cachedStructural && !existingStructuralInflight) {
+    structuralPrefetchInflight.set(structuralInflightKey, launchedStructuralPromise);
+    void launchedStructuralPromise.then(
+      () => { if (structuralPrefetchInflight.get(structuralInflightKey) === launchedStructuralPromise) structuralPrefetchInflight.delete(structuralInflightKey); },
+      () => { if (structuralPrefetchInflight.get(structuralInflightKey) === launchedStructuralPromise) structuralPrefetchInflight.delete(structuralInflightKey); },
+    );
+  }
+  const structuralPromise = launchedStructuralPromise.then((response) => {
+    structuralSettled = true;
+    structuralSettledValue = response;
+    return response;
+  });
+  const lexicalPromise = lexicalOptions && lexicalIdentity && !cachedLexical?.result
+    ? searchRepositoryManyAsync(repoRoot, policy, lexicalOptions).then((result) => {
+        sessionCache?.putSearch({
+          query: lexicalIdentity.batchQueryKey,
+          includeKey: lexicalIdentity.includeKey,
+          result,
+          scannedFiles: result.scannedFiles,
+        });
+        return result;
+      })
+    : Promise.resolve(cachedLexical?.result);
+
+  // Lexical/raw discovery is required first-call evidence. Auto structural work is
+  // allowed to consume only the remainder of its budget measured from the start
+  // of the parallel prefetch, so a slow lexical pass never gains an extra 100ms
+  // structural tax after it completes.
+  await lexicalPromise;
+  let prefetched = structuralSettledValue ?? noStructuralResponse;
+  let structuralPrefetchDeferred = false;
+  if (structuralQuery && !cachedStructural) {
+    if (structuralMode === 'required') {
+      prefetched = await structuralPromise;
+    } else if (structuralSettled && structuralSettledValue) {
+      prefetched = structuralSettledValue;
+    } else {
+      const elapsedMs = performance.now() - prefetchStartedAt;
+      // Reusing an already-deferred in-flight request should be effectively free:
+      // do not make a progressive follow-up repay the first call's latency budget.
+      const remainingBudgetMs = structuralPrefetchReusedInFlight
+        ? 0
+        : Math.max(0, AUTO_STRUCTURAL_PREFETCH_BUDGET_MS - elapsedMs);
+      const outcome = await settleWithinBudget(structuralPromise, remainingBudgetMs);
+      if (outcome.settled) {
+        prefetched = outcome.value;
+      } else {
+        structuralPrefetchDeferred = true;
+        prefetched = codeGraphPrefetchDeferredResponse(performance.now() - prefetchStartedAt);
+      }
+    }
+  }
+
+  const fallbackQueryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
+  const pack = buildControllerContextPack(repoRoot, policy, options, {
+    queryCodeGraph: (queryRoot, request) => request.operation === 'context' && queryRoot === structuralIndexRoot
+      ? prefetched
+      : fallbackQueryCodeGraph(queryRoot, request),
+  });
+  pack.timingsMs.parallelFirstPass = true;
+  pack.timingsMs.parallelPrefetch = Math.round((performance.now() - prefetchStartedAt) * 100) / 100;
+  pack.timingsMs.structuralPrefetchBudgetMs = structuralMode === 'auto' && structuralQuery ? AUTO_STRUCTURAL_PREFETCH_BUDGET_MS : 0;
+  pack.timingsMs.structuralPrefetchDeferred = structuralPrefetchDeferred;
+  pack.timingsMs.structuralPrefetchReusedInFlight = structuralPrefetchReusedInFlight;
+
+  if (structuralPrefetchDeferred) {
+    // The provider request is intentionally not cancelled. Cache only if the
+    // repository source identity still matches the request that launched it;
+    // a mutation must never let late structural evidence attach to newer source.
+    void structuralPromise
+      .then((response) => cacheDeferredStructuralResult(sessionCache, structuralCacheKey, structuralSourceIdentity, response))
+      .catch(() => undefined);
+  }
+  return pack;
+}