@moretea-labs/forge 1.8.1 → 1.8.2

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

@@ -5,19 +5,13 @@ import {
   searchRepositoryManyAsync,
   searchRepositoryManyCacheIdentity,
 } from "../repository/inspector";
-import { globMatches } from "../mcp/paths";
+import { globMatches } from "../../../adapters/mcp/paths";
 import { posix } from "path";
-import type { McpPolicy } from "../mcp/types";
+import type { McpPolicy } from "../../../adapters/mcp/types";
 import { materializeSource } from "./context/source-materializer";
 import { projectBoard } from "./issue-store";
 import { buildControllerTaskLedgerProjection } from "./task-ledger";
 import { legacyIssueAuthorityRetired } from "./legacy-issue-cutover";
-import {
-  queryCodeGraphReadProvider,
-  queryCodeGraphReadProviderAsync,
-  type CodeGraphNodeSummary,
-  type CodeGraphReadProviderResponse,
-} from "../../runtime/context/codegraph-read-provider";
 import {
   CONTEXT_PACK_SCHEMA_VERSION,
   CONTROLLER_CONTEXT_IMPACT_DOMAINS,
@@ -38,7 +32,7 @@ import {
   clamp,
   cleanList,
   gitStatusChangedPaths,
-  isCodeShapedTerm,
+  explicitCodeQueries,
   pathNoisePenalty,
   structuralIntentQuery,
   textTokens,
@@ -46,6 +40,11 @@ import {
 import { issueTaskFocus, ledgerTask } from './context/focus';
 import { addReason, coveredByGlob, expandKnownPath, looksLikeGlob, readableFile } from './context/known-paths';
 import { structuralResult } from './context/structural';
+import {
+  unavailableStructuralProvider,
+  unavailableStructuralProviderAsync,
+  type StructuralReadProviderResponse,
+} from './context/structural-provider';
 import { buildRepositoryInstructionContext } from './context/instruction-context';
 import { resolveRepositoryGovernance } from './context/rule-resolution';
 import { controllerCheckSelection, listControllerChecks } from './check-runner';
@@ -100,7 +99,7 @@ function resolveSourceReference(repoRoot: string, policy: McpPolicy, sourcePath:
 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;
+  const structuralBonus = reasons.some((reason) => reason.startsWith('structural:')) ? 3 : 0;
   return testBonus + sourceBonus + structuralBonus;
 }
 
@@ -148,7 +147,8 @@ export function buildControllerContextPack(
     focus.task?.objective,
   ].filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
   const goal = goalParts.join("\n").trim();
-  const terms = cleanList([...(options.searchTerms ?? []), ...textTokens(goal)]).slice(0, 14);
+  const requiredSearchQueries = explicitCodeQueries(options.searchTerms);
+  const terms = cleanList([...requiredSearchQueries, ...(options.searchTerms ?? []), ...(options.searchTerms ?? []).flatMap(textTokens), ...textTokens(goal)]).slice(0, 14);
   const impactDomains = cleanList(options.impactDomains)
     .filter((domain): domain is ControllerContextImpactDomain => CONTROLLER_CONTEXT_IMPACT_DOMAINS.includes(domain as ControllerContextImpactDomain))
     .slice(0, 6);
@@ -168,9 +168,6 @@ export function buildControllerContextPack(
   ]).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 }> = [];
@@ -192,7 +189,7 @@ export function buildControllerContextPack(
   const baselineRevisionMatches = indexSource === "current_checkout" || gitSnapshot(structuralIndexRoot).head === git.head;
   const graphImpactFiles = new Set<string>();
   let structuralContext: ControllerContextPackProjection["structuralContext"] = {
-    provider: "codegraph",
+    provider: "none",
     requestedMode: structuralMode,
     status: "disabled",
     requiredSatisfied: structuralMode !== "required",
@@ -204,17 +201,17 @@ export function buildControllerContextPack(
     truncated: false,
   };
   const repositorySessionCache = getRepositoryReadSessionCache(repoRoot, options.session);
-  const queryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
-  const queryStructural = (queryRoot: string, request: Parameters<typeof queryCodeGraphReadProvider>[1]): CodeGraphReadProviderResponse => {
+  const structuralProvider = dependencies.queryStructural ?? unavailableStructuralProvider;
+  const queryStructural = (queryRoot: string, request: Parameters<typeof unavailableStructuralProvider>[1]): StructuralReadProviderResponse => {
     const key = JSON.stringify({ queryRoot, request });
     const cached = repositorySessionCache?.getStructural(key);
     if (cached && typeof cached === "object") {
       structuralCacheHits += 1;
-      return cached as CodeGraphReadProviderResponse;
+      return cached as StructuralReadProviderResponse;
     }
     structuralCacheMisses += 1;
-    const response = queryCodeGraph(queryRoot, request);
-    if (response.error?.code !== CODEGRAPH_PREFETCH_DEFERRED_CODE) {
+    const response = structuralProvider(queryRoot, request);
+    if (response.error?.code !== STRUCTURAL_PREFETCH_DEFERRED_CODE) {
       repositorySessionCache?.putStructural(key, response);
     }
     return response;
@@ -262,7 +259,7 @@ export function buildControllerContextPack(
         ? "stale"
         : structural.status;
       structuralContext = {
-        provider: "codegraph",
+        provider: "none",
         requestedMode: structuralMode,
         status: structuralStatus,
         requiredSatisfied: structuralMode !== "required" || structuralEvidenceCurrent,
@@ -304,12 +301,12 @@ export function buildControllerContextPack(
       // 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);
+          addStructuralPath(node.filePath, `structural:context:${node.kind}:${node.name}`, node.startLine);
         }
         for (const node of graph.entryPoints) {
-          addStructuralPath(node.filePath, `codegraph:entry:${node.name}`, node.startLine);
+          addStructuralPath(node.filePath, `structural:entry:${node.name}`, node.startLine);
         }
-        for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "codegraph:related");
+        for (const path of graph.relatedFiles.slice(0, maxFiles * 6)) addStructuralPath(path, "structural: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
@@ -326,18 +323,18 @@ export function buildControllerContextPack(
             : [];
           for (const path of dependencies.slice(0, 40)) {
             graphImpactFiles.add(path);
-            addStructuralPath(path, `codegraph:dependency:${filePath}`);
+            addStructuralPath(path, `structural:dependency:${filePath}`);
           }
           for (const path of dependents.slice(0, 40)) {
             graphImpactFiles.add(path);
-            addStructuralPath(path, `codegraph:dependent:${filePath}`);
+            addStructuralPath(path, `structural:dependent:${filePath}`);
           }
         }
       }
-      for (const path of metadata?.changedFiles.removed ?? []) omitted.push({ path, reason: "codegraph reports file removed since index" });
+      for (const path of metadata?.changedFiles.removed ?? []) omitted.push({ path, reason: "structural provider reports file removed since index" });
       // 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.
+      // but they come from Git rather than stale structural metadata.
       if (indexSource === "repository_baseline") {
         for (const path of gitStatusChangedPaths(git.status)) addStructuralPath(path, "worktree:changed-file", 1);
       }
@@ -349,16 +346,17 @@ export function buildControllerContextPack(
   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) {
+    const allowedFiles = expanded.files.filter((file) => !excludeGlobs.some((glob) => globMatches(glob, file)));
+    for (const file of allowedFiles) {
       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]!);
+    if (!expanded.directory && allowedFiles.length === 1 && expanded.denied.length === 0 && !expanded.truncated) {
+      exactKnownFiles.push(allowedFiles[0]!);
     } else {
       exactKnownFileScope = false;
     }
     deniedPaths.push(...expanded.denied);
-    scannedFiles += expanded.files.length;
+    scannedFiles += allowedFiles.length;
     searchTruncated = searchTruncated || expanded.truncated;
   }
   // Exact caller-selected files own a reserved file slot. The inferred-file
@@ -407,6 +405,14 @@ export function buildControllerContextPack(
     searchTruncated = searchTruncated || search.truncated;
     for (const hit of search.results) {
       if (!coveredByGlob(hit.path, searchIncludeGlobs) || excludeGlobs.some((glob) => globMatches(glob, hit.path))) continue;
+      if (candidates.size >= maxFiles * 3 && !candidates.has(hit.path) && !requiredSearchQueries.includes(hit.query)) continue;
+      if (requiredSearchQueries.includes(hit.query)) {
+        const source = hit.text.trimStart();
+        const declared = /^(?:(?:export|declare|default|async)\s+)*(?:function|class|interface|type|const|let|enum)\s+([\w$]+)/.exec(source)?.[1];
+        if (declared?.toLowerCase() === hit.query.toLowerCase()) {
+          addReason(candidates, hit.path, `${source.startsWith('export ') ? 'exported' : 'local'}-definition:${hit.query}`, hit.line);
+        }
+      }
       if (terms.includes(hit.query)) {
         addReason(candidates, hit.path, `search:${hit.query}`, hit.line);
       } else {
@@ -417,12 +423,14 @@ export function buildControllerContextPack(
           addReason(candidates, hit.path, `impact:${domain}:${hit.query}`, hit.line);
         }
       }
-      if (candidates.size >= maxFiles * 3) break;
     }
   }
 
   timingsMs.lexical = Math.round((performance.now() - lexicalStartedAt) * 100) / 100;
   const primarySearchReason = terms.length > 0 ? `search:${terms[0]}` : undefined;
+  const definitionPriority = (reasons: readonly string[]): number =>
+    reasons.some((reason) => reason.startsWith('exported-definition:')) ? 2
+      : reasons.some((reason) => reason.startsWith('local-definition:')) ? 1 : 0;
   const rankedCandidates = Array.from(candidates.entries())
     .map(([path, entry]) => ({ path, reasons: Array.from(entry.reasons), lines: Array.from(entry.lines) }))
     .sort((left, right) => {
@@ -433,6 +441,8 @@ export function buildControllerContextPack(
         ? 2
         : right.reasons.some((reason) => reason.startsWith("explicit-known-directory:")) ? 1 : 0;
       if (leftExplicit !== rightExplicit) return rightExplicit - leftExplicit;
+      const definitionDelta = definitionPriority(right.reasons) - definitionPriority(left.reasons);
+      if (definitionDelta !== 0) return definitionDelta;
       const leftPrimary = primarySearchReason && left.reasons.includes(primarySearchReason) ? 1 : 0;
       const rightPrimary = primarySearchReason && right.reasons.includes(primarySearchReason) ? 1 : 0;
       if (leftPrimary !== rightPrimary) return rightPrimary - leftPrimary;
@@ -453,12 +463,19 @@ export function buildControllerContextPack(
     || structuralMode !== "off"
     || impactDomains.length > 0;
   timingsMs.expansionBudgetMax = multiWaveEligible ? Math.min(6, Math.max(2, Math.ceil(maxFiles / 2))) : 0;
-  const rankedExactKnownCount = rankedCandidates.filter(isExactKnownCandidate).length;
+  // Reserve one best file per explicit symbol before broad hits can consume
+  // the result window. Caller-selected exact paths retain first priority.
+  const prioritizedCandidates = Array.from(new Map([
+    ...rankedCandidates.filter(isExactKnownCandidate),
+    ...requiredSearchQueries.flatMap((query) => rankedCandidates.filter((entry) => entry.reasons.includes(`search:${query}`)).slice(0, 1)),
+    ...rankedCandidates,
+  ].map((entry) => [entry.path, entry] as const)).values());
+  const rankedExactKnownCount = prioritizedCandidates.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 selected = prioritizedCandidates.slice(0, initialCandidateLimit);
+  const deferredSelected = prioritizedCandidates.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
@@ -477,7 +494,7 @@ export function buildControllerContextPack(
       status: selectedFiles.length > 0 ? "selected" as const : matchedFiles.length > 0 ? "matched_not_selected" as const : "no_evidence" as const,
     };
   });
-  for (const entry of rankedCandidates.slice(maxFiles)) omitted.push({ path: entry.path, reason: "max_files" });
+  for (const entry of prioritizedCandidates.slice(maxFiles)) omitted.push({ path: entry.path, reason: "max_files" });
 
   let remainingSnippets = maxSnippets;
   const files: ControllerContextPackFile[] = [];
@@ -498,9 +515,12 @@ export function buildControllerContextPack(
     const waveOnePerFileCap = multiWaveEligible
       ? Math.max(1, Math.ceil(maxSnippets / Math.max(1, initialCandidateLimit + timingsMs.expansionBudgetMax)))
       : remainingSnippets;
+    // A caller-increased max_snippets budget must not let the first broad
+    // candidate consume every snippet and erase other selected source files.
+    const inferredFairShare = Math.max(1, Math.ceil(remainingSnippets / (selected.length - selectedIndex)));
     const fileSnippetBudget = exactKnown
       ? Math.max(1, remainingSnippets - exactKnownAfter)
-      : Math.min(remainingSnippets, waveOnePerFileCap);
+      : Math.min(remainingSnippets, waveOnePerFileCap, inferredFairShare);
     let snippets: ControllerContextPackSnippet[] = [];
     try {
       snippets = materializeSource({
@@ -509,8 +529,11 @@ export function buildControllerContextPack(
         path: entry.path,
         hitLines: entry.lines.length > 0 ? entry.lines : [1],
         reasons: entry.reasons,
-        maxSnippets: Math.min(fileSnippetBudget, remainingSnippets),
-        maxCharsPerSnippet,
+        // Discovery should cover multiple entry points rather than dump one huge file.
+        // Explicit known files retain their full evidence budget; only inferred
+        // candidates receive the cheap two-snippet discovery default.
+        maxSnippets: Math.min(options.maxSnippets === undefined && !exactKnown ? 2 : fileSnippetBudget, remainingSnippets),
+        maxCharsPerSnippet: exactKnown && options.maxCharsPerSnippet === undefined ? 8000 : maxCharsPerSnippet,
         session: options.session,
       });
       for (const snippet of snippets) {
@@ -534,7 +557,7 @@ 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
+  // from the source that was just read plus current structural adjacency, then
   // materializes those paths in the same context request.
   const materializedPathSet = new Set(files.map((file) => file.path));
   let frontier = files.slice();
@@ -572,11 +595,11 @@ export function buildControllerContextPack(
           : [];
         for (const path of dependencies.slice(0, 40)) {
           graphImpactFiles.add(path);
-          addExpansionCandidate(path, `codegraph:dependency:${file.path}`);
+          addExpansionCandidate(path, `structural:dependency:${file.path}`);
         }
         for (const path of dependents.slice(0, 40)) {
           graphImpactFiles.add(path);
-          addExpansionCandidate(path, `codegraph:dependent:${file.path}`);
+          addExpansionCandidate(path, `structural:dependent:${file.path}`);
         }
       }
 
@@ -752,7 +775,7 @@ export function buildControllerContextPack(
     architectureContracts,
     coverageGaps: Array.from(new Set(coverageGaps)).slice(0, 40),
     relationSources: [
-      ...(structuralMode !== "off" ? ["codegraph" as const] : []),
+      ...(structuralMode !== "off" ? ["structural" as const] : []),
       ...(files.length > 0 ? ["lexical" as const] : []),
       ...(taskChecks.length > 0 ? ["forge_checks" as const] : []),
     ],
@@ -985,7 +1008,7 @@ export function buildControllerContextPack(
         retrievalMode === "implementation"
           ? "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.",
+        "Search/structural 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.",
@@ -993,15 +1016,15 @@ export function buildControllerContextPack(
         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.",
+        "Structural evidence is discovery evidence. Raw source access still passes through Forge repository policy and current-file reads.",
+        structuralContext.status === "stale" ? "Structural provider reports stale evidence. Treat 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" ? "Structural context was queried read-only." : "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.",
         taskChecks.length > 0 ? `Task checks advertised by the board: ${taskChecks.join(", ")}.` : "No task-specific checks were found in the compact ledger.",
       ],
     },
     next: [
       ...(structuralMode === "required" && !structuralContext.requiredSatisfied
-        ? ["Structural context was required but is not current/ready. Refresh CodeGraph explicitly or continue only with the degraded-plan warning visible."]
+        ? ["Structural context was required but is not current/ready. Continue only with the degraded-plan warning visible or use current raw source / semantic navigation instead."]
         : []),
       files.length > 0
         ? retrievalMode === "implementation"
@@ -1016,26 +1039,26 @@ 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
+ * remains required evidence. Auto structural retrieval 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>>();
+const STRUCTURAL_PREFETCH_DEFERRED_CODE = 'STRUCTURAL_PREFETCH_DEFERRED';
+const structuralPrefetchInflight = new Map<string, Promise<StructuralReadProviderResponse>>();
 
-function codeGraphPrefetchDeferredResponse(elapsedMs: number): CodeGraphReadProviderResponse {
+function structuralPrefetchDeferredResponse(elapsedMs: number): StructuralReadProviderResponse {
   return {
     schemaVersion: 1,
-    provider: 'codegraph',
+    provider: 'none',
     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.`,
+      code: STRUCTURAL_PREFETCH_DEFERRED_CODE,
+      message: `Optional structural 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 },
   };
@@ -1061,10 +1084,10 @@ function cacheDeferredStructuralResult(
   sessionCache: ReturnType<typeof getRepositoryReadSessionCache>,
   structuralCacheKey: string,
   sourceIdentity: string | undefined,
-  response: CodeGraphReadProviderResponse,
+  response: StructuralReadProviderResponse,
 ): void {
   if (!sessionCache || !sourceIdentity) return;
-  if (response.error?.code === 'CODEGRAPH_TIMEOUT' || response.error?.code === CODEGRAPH_PREFETCH_DEFERRED_CODE) return;
+  if (response.error?.code === 'STRUCTURAL_TIMEOUT' || response.error?.code === STRUCTURAL_PREFETCH_DEFERRED_CODE) return;
   if (JSON.stringify(sessionCache.currentIdentity()) !== sourceIdentity) return;
   sessionCache.putStructural(structuralCacheKey, response);
 }
@@ -1076,7 +1099,7 @@ export async function buildControllerContextPackAsync(
   dependencies: ControllerContextPackDependencies = {},
 ): Promise<ControllerContextPackProjection> {
   const structuralMode = options.structuralContext ?? 'off';
-  if ((dependencies.queryCodeGraph && !dependencies.queryCodeGraphAsync) || !options.session || options.issueId || options.taskId) {
+  if ((dependencies.queryStructural && !dependencies.queryStructuralAsync) || !options.session || options.issueId || options.taskId) {
     return buildControllerContextPack(repoRoot, policy, options, dependencies);
   }
   const prefetchStartedAt = performance.now();
@@ -1087,7 +1110,8 @@ export async function buildControllerContextPackAsync(
   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 requiredSearchQueries = explicitCodeQueries(options.searchTerms);
+  const terms = cleanList([...requiredSearchQueries, ...(options.searchTerms ?? []), ...(options.searchTerms ?? []).flatMap(textTokens), ...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);
@@ -1095,8 +1119,9 @@ export async function buildControllerContextPackAsync(
   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]!);
+    const allowedFiles = expanded.files.filter((file) => !excludeGlobs.some((glob) => globMatches(glob, file)));
+    if (!expanded.directory && allowedFiles.length === 1 && expanded.denied.length === 0 && !expanded.truncated) {
+      exactKnownFiles.push(allowedFiles[0]!);
     } else {
       exactKnownFileScope = false;
     }
@@ -1112,9 +1137,6 @@ export async function buildControllerContextPackAsync(
     ...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);
@@ -1131,7 +1153,7 @@ export async function buildControllerContextPackAsync(
   const sessionCache = getRepositoryReadSessionCache(repoRoot, options.session);
   const structuralSourceIdentity = sessionCache ? JSON.stringify(sessionCache.currentIdentity()) : undefined;
   const cachedStructural = structuralQuery
-    ? sessionCache?.peekStructural(structuralCacheKey) as CodeGraphReadProviderResponse | undefined
+    ? sessionCache?.peekStructural(structuralCacheKey) as StructuralReadProviderResponse | undefined
     : undefined;
   const lexicalOptions = searchQueries.length > 0
     ? (() => {
@@ -1168,18 +1190,18 @@ export async function buildControllerContextPackAsync(
     return pack;
   }
 
-  const noStructuralResponse: CodeGraphReadProviderResponse = {
+  const noStructuralResponse: StructuralReadProviderResponse = {
     schemaVersion: 1,
-    provider: 'codegraph',
+    provider: 'none',
     operation: 'context',
     ok: false,
     status: 'degraded',
-    error: { code: 'CODEGRAPH_QUERY_REQUIRED', message: 'No context query was provided.' },
+    error: { code: 'STRUCTURAL_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;
+  let structuralSettledValue: StructuralReadProviderResponse | undefined = cachedStructural || (!structuralQuery ? noStructuralResponse : undefined);
+  const queryStructuralAsync = dependencies.queryStructuralAsync ?? unavailableStructuralProviderAsync;
   const structuralInflightKey = structuralQuery && structuralSourceIdentity
     ? JSON.stringify({ structuralCacheKey, sourceIdentity: structuralSourceIdentity, structuralMode })
     : undefined;
@@ -1188,10 +1210,9 @@ export async function buildControllerContextPackAsync(
   const launchedStructuralPromise = cachedStructural
     ? Promise.resolve(cachedStructural)
     : structuralQuery
-      ? existingStructuralInflight ?? queryCodeGraphAsync(
+      ? existingStructuralInflight ?? queryStructuralAsync(
           structuralIndexRoot,
           structuralRequest,
-          structuralMode === 'auto' ? { timeoutMs: AUTO_STRUCTURAL_PREFETCH_TIMEOUT_MS } : {},
         )
       : Promise.resolve(noStructuralResponse);
   if (structuralInflightKey && structuralQuery && !cachedStructural && !existingStructuralInflight) {
@@ -1242,16 +1263,16 @@ export async function buildControllerContextPackAsync(
         prefetched = outcome.value;
       } else {
         structuralPrefetchDeferred = true;
-        prefetched = codeGraphPrefetchDeferredResponse(performance.now() - prefetchStartedAt);
+        prefetched = structuralPrefetchDeferredResponse(performance.now() - prefetchStartedAt);
       }
     }
   }
 
-  const fallbackQueryCodeGraph = dependencies.queryCodeGraph ?? queryCodeGraphReadProvider;
+  const fallbackQueryStructural = dependencies.queryStructural ?? unavailableStructuralProvider;
   const pack = buildControllerContextPack(repoRoot, policy, options, {
-    queryCodeGraph: (queryRoot, request) => request.operation === 'context' && queryRoot === structuralIndexRoot
+    queryStructural: (queryRoot, request) => request.operation === 'context' && queryRoot === structuralIndexRoot
       ? prefetched
-      : fallbackQueryCodeGraph(queryRoot, request),
+      : fallbackQueryStructural(queryRoot, request),
   });
   pack.timingsMs.parallelFirstPass = true;
   pack.timingsMs.parallelPrefetch = Math.round((performance.now() - prefetchStartedAt) * 100) / 100;

package/src/cli/controller/operational-plan.ts

@@ -169,7 +169,7 @@ export function buildControllerOperationalPlan(repoRoot: string, ledger: TaskLed
     mcpToolSchemaConvergence: {
       source: "mcp-tool-schema-convergence",
       readModels: ["controller_context", "rh_context", "work_status_digest", "prepare_transfer_artifacts"],
-      commandModels: ["rh_work", "run_check", "repository_command_execute", "plugin_action_execute", "repository_safe_patch_apply"],
+      commandModels: ["rh_work", "run_check", "execute_command", "plugin_action_execute", "repository_safe_patch_apply"],
       compatibilityRules: [
         "compact reads are default",
         "raw code and raw logs require explicit opt-in tools",

package/src/cli/controller/systemd-user.ts

@@ -1,7 +1,8 @@
+import { writeAtomicTextFile } from '../../runtime/shared/atomic-text-file';
 import { spawnSync, type SpawnSyncReturns } from 'child_process';
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, rmSync } from 'fs';
 import { homedir } from 'os';
-import { dirname, join } from 'path';
+import { join } from 'path';
 
 export interface SystemdUserUnitInput {
   description?: string;
@@ -12,13 +13,6 @@ export interface SystemdUserUnitInput {
   restartSec?: number;
 }
 
-function atomicWrite(path: string, content: string, mode = 0o644): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, content, { encoding: 'utf8', mode });
-  renameSync(temporary, path);
-}
-
 export function systemdEscape(value: string): string {
   return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
@@ -79,7 +73,7 @@ export function writeSystemdUserUnit(
   env: NodeJS.ProcessEnv = process.env,
 ): string {
   const unitPath = systemdUserUnitPath(unitName, env);
-  atomicWrite(unitPath, renderSystemdUserUnit(input), 0o644);
+  writeAtomicTextFile(unitPath, renderSystemdUserUnit(input), 0o644);
   return unitPath;
 }
 

package/src/cli/editing/edit-session.ts

@@ -9,8 +9,8 @@ import {
   type ControllerCheckResult,
 } from '../controller/check-runner';
 import { tryAppendControllerWorklogEvent } from '../controller/worklog';
-import { globMatches, resolveMcpPath } from '../mcp/paths';
-import type { McpPolicy } from '../mcp/types';
+import { globMatches, resolveMcpPath } from '../../../adapters/mcp/paths';
+import type { McpPolicy } from '../../../adapters/mcp/types';
 import type { ProcessCheckCompletionReceipt, ProcessCheckReceiptStatus } from '../../runtime/execution/process-runtime/check-receipt';
 import { invalidateRepositoryReadCaches } from '../repository/inspector';
 import type { EditOperation } from './edit-operation-contract';
@@ -312,6 +312,10 @@ function bindSessionControllerInstance(repoRoot: string, session: EditSession, b
   assertEditSessionDurableBinding(session, binding);
   const nextInstanceId = binding?.controllerInstanceId?.trim();
   if (!nextInstanceId || session.controllerInstanceId === nextInstanceId) return session;
+  // A non-Work Safe Patch session has no Controller instance owner to rebind.
+  // Its persisted repository identity is still checked above; never promote
+  // a caller-supplied transient Runtime identity into durable session authority.
+  if (!session.workId && !session.controllerInstanceId) return session;
   const durableIdentity = [
     [session.workId, binding?.workId],
     [session.repoId, binding?.repoId],
@@ -1144,7 +1148,7 @@ function sessionSummary(session: EditSession): EditSessionSummary {
   };
 }
 
-function findOccurrence(value: string, anchor: string, occurrence: number): number {
+export function findOccurrence(value: string, anchor: string, occurrence: number): number {
   let from = 0;
   for (let current = 1; current <= occurrence; current += 1) {
     const index = value.indexOf(anchor, from);
@@ -1913,9 +1917,17 @@ export function finalizeEditSession(repoRoot: string, sessionId: string, input:
 } = {}): EditSession {
   let session = getEditSession(repoRoot, sessionId);
   session = bindSessionControllerInstance(repoRoot, session, input.binding);
-  if (session.baseRevision && gitRevision(repoRoot) !== session.baseRevision) throw new Error('EDIT_SESSION_BASE_REVISION_CHANGED');
-  if (session.workspaceFingerprint && workspaceFingerprint(repoRoot) !== session.workspaceFingerprint) throw new Error('EDIT_SESSION_WORKSPACE_FINGERPRINT_CHANGED');
+  const baseRevisionChanged = Boolean(session.baseRevision && gitRevision(repoRoot) !== session.baseRevision);
+  const workspaceFingerprintChanged = Boolean(session.workspaceFingerprint && workspaceFingerprint(repoRoot) !== session.workspaceFingerprint);
   if (session.assurance?.approvalRequired && input.approvalConfirmed !== true) throw new Error('EDIT_SESSION_APPROVAL_REQUIRED');
+  if (baseRevisionChanged || workspaceFingerprintChanged) {
+    // A commit changes HEAD and Git's workspace fingerprint even when the exact edit-session after-images are now integrated.
+    // Reconcile through the canonical after-image + clean-tracked-path checks before rejecting the stale snapshot.
+    const reconciled = reconcileEditSession(repoRoot, session.sessionId, input);
+    if (reconciled.status === 'finalized' || reconciled.status === 'superseded') return reconciled;
+    if (baseRevisionChanged) throw new Error('EDIT_SESSION_BASE_REVISION_CHANGED');
+    throw new Error('EDIT_SESSION_WORKSPACE_FINGERPRINT_CHANGED');
+  }
   const emptyOpenSession = session.status === 'open' && session.operations.length === 0;
   if (!emptyOpenSession && !['dirty', 'checked', 'check_failed'].includes(session.status)) {
     throw new Error(`edit session cannot be finalized from ${session.status}`);

package/src/cli/github/github.ts

@@ -121,7 +121,7 @@ export function buildGitHubWorkflowDispatchArgs(repository: string, input: GitHu
   return args;
 }
 
-function gh(repoRoot: string, args: string[], input?: string, maxOutputBytes = 512 * 1024) {
+export function gh(repoRoot: string, args: string[], input?: string, maxOutputBytes = 512 * 1024) {
   return runProcess('gh', args, {
     cwd: repoRoot,
     timeoutMs: 120_000,
@@ -284,7 +284,7 @@ function parseIssueUrl(output: string): { url: string; number: number } {
   return { url, number };
 }
 
-function addProjectItem(repoRoot: string, link: GitHubIssueLink, projectOwner?: string, projectNumber?: number): GitHubIssueLink {
+export function addProjectItem(repoRoot: string, link: GitHubIssueLink, projectOwner?: string, projectNumber?: number): GitHubIssueLink {
   if (!projectOwner || !projectNumber) return link;
   const result = gh(repoRoot, ['project', 'item-add', String(projectNumber), '--owner', projectOwner, '--url', link.url, '--format', 'json']);
   if (!result.ok) throw new Error(`failed to add ${link.url} to GitHub Project: ${result.error || result.stderr}`);
@@ -302,7 +302,7 @@ function withoutPairedOption(args: string[], option: string): string[] {
   return args.filter((entry, index, all) => entry !== option && all[index - 1] !== option);
 }
 
-function createGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, title: string, bodyPath: string, labels: string[], parentNumber?: number): GitHubIssueLink {
+export function createGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, title: string, bodyPath: string, labels: string[], parentNumber?: number): GitHubIssueLink {
   const args = ['issue', 'create', '--repo', repo.nameWithOwner, '--title', title, '--body-file', bodyPath];
   for (const label of labels) args.push('--label', label);
   if (parentNumber) args.push('--parent', String(parentNumber));
@@ -323,7 +323,7 @@ function createGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, title:
   return { owner: repo.owner, repo: repo.repo, number: parsed.number, url: parsed.url, syncedAt: new Date().toISOString() };
 }
 
-function updateGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, link: GitHubIssueLink, title: string, bodyPath: string): GitHubIssueLink {
+export function updateGitHubIssue(repoRoot: string, repo: GitHubRepositoryInfo, link: GitHubIssueLink, title: string, bodyPath: string): GitHubIssueLink {
   const result = gh(repoRoot, ['issue', 'edit', String(link.number), '--repo', repo.nameWithOwner, '--title', title, '--body-file', bodyPath]);
   if (!result.ok) throw new Error(`failed to update GitHub issue #${link.number}: ${result.error || result.stderr}`);
   return { ...link, owner: repo.owner, repo: repo.repo, syncedAt: new Date().toISOString() };