mixdog 0.9.95 → 0.9.97

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs

@@ -4,7 +4,7 @@
 // code-graph.mjs.
 import { resolve as pathResolve, isAbsolute, relative as pathRelative, basename as pathBasename } from 'node:path';
 import { homedir as osHomedir } from 'node:os';
-import { readFileSync, existsSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { normalizeInputPath, toDisplayPath } from '../builtin.mjs';
 import { findFileByBasename } from '../builtin/path-diagnostics.mjs';
 import { markScopedCacheIncomplete } from '../../session/cache/scoped-cache-outcome.mjs';
@@ -40,7 +40,9 @@ import {
   _CALLEES_BRACE_LANGS,
   _formatRelated,
   _formatImpact,
+  _impactSourceNodes,
   _resolveReferenceLanguageNode,
+  _prewarmSourceTextNodes,
   _prewarmReferenceSourceText,
   _cheapReferenceSearch,
   _formatCallerReferences,
@@ -51,7 +53,8 @@ import {
 
 const CODE_GRAPH_BATCHABLE_MODES = new Set(['symbol', 'find_symbol', 'symbol_search', 'callers', 'callees', 'references']);
 const CODE_GRAPH_FILE_BATCHABLE_MODES = new Set(['imports', 'dependents', 'related', 'impact', 'symbols', 'overview']);
-const CODE_GRAPH_SYMBOL_BATCH_CAP = 20;
+const CODE_GRAPH_MAX_BATCH_SYMBOLS = 20;
+const CODE_GRAPH_FILE_BATCH_CAP = 20;
 
 function _collectGraphSymbolList(args) {
   const split = (s) => String(s || '').split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
@@ -60,18 +63,21 @@ function _collectGraphSymbolList(args) {
     ...(typeof args?.symbols === 'string' ? split(args.symbols) : []),
     ...(typeof args?.symbol === 'string' ? split(args.symbol) : []),
   ])];
-  if (list.length <= CODE_GRAPH_SYMBOL_BATCH_CAP) return list;
-  const capped = list.slice(0, CODE_GRAPH_SYMBOL_BATCH_CAP);
-  capped._omitted = list.slice(CODE_GRAPH_SYMBOL_BATCH_CAP);
-  return capped;
+  return list;
 }
 
-const CODE_GRAPH_FILE_BATCH_CAP = 20;
 const _AGGREGATE_FILE_WILDCARD_RE = /[*?[\]{}]/;
 const ROOT_FEDERATED_MODES = new Set([
   'overview', 'symbol', 'find_symbol', 'symbol_search', 'search',
   'references', 'callers', 'callees', 'symbols', 'prewarm',
 ]);
+// Fan-out cap when federation targets are DISCOVERED (immediate child project
+// roots of a sentinel-free cwd) rather than registered. Bounds the cost of
+// answering a query at a multi-repo parent; registered roots are unaffected.
+const CODE_GRAPH_DISCOVERED_FEDERATION_CAP = (() => {
+  const raw = parseInt(process.env.MIXDOG_CODE_GRAPH_FEDERATION_CAP ?? '', 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : 8;
+})();
 
 export async function _runCodeGraphFederation(roots, runOne, projectArgs) {
   return Promise.all((roots || []).map(async (root) => {
@@ -132,6 +138,25 @@ function _hasAggregateFileArgs(args) {
     || (typeof args?.files === 'string' && args.files.trim());
 }
 
+// Aggregate anchors that ALL resolve to the cwd itself ('.', './', the cwd
+// path) add no scope — they mean "search here". Detected so the call can take
+// the plain-cwd route, which adopts a sentinel-free single tree (a vendored
+// reference checkout) as its own root while still refusing an unbounded or
+// multi-project parent. Without this, `files:"."` turned every reference tree
+// into a hard "not inside a project" refusal.
+function _aggregateAnchorsAreCwd(args, baseCwd) {
+  if (!_hasAggregateFileArgs(args)) return false;
+  const files = _collectGraphFileList(args);
+  if (files.length === 0) return false;
+  return files.every((file) => {
+    const trimmed = String(file || '').trim();
+    if (!trimmed || _AGGREGATE_FILE_WILDCARD_RE.test(trimmed)) return false;
+    try {
+      return pathResolve(isAbsolute(trimmed) ? trimmed : pathResolve(baseCwd, trimmed)) === pathResolve(baseCwd);
+    } catch { return false; }
+  });
+}
+
 // An invalid caller cwd may be recovered for an explicit files aggregate only
 // when every supplied anchor points at the same detectable project. Do not use
 // the batch cap here: an omitted anchor could belong to another project.
@@ -156,9 +181,35 @@ function _resolveAggregateFileProjectRoot(args, baseCwd) {
     const root = isDirectory ? _findDirProjectRoot(abs) : _resolveFileProjectRoot(abs);
     if (!root) return null;
     roots.add(pathResolve(root));
-    if (roots.size > 1) return null;
   }
-  return roots.size === 1 ? [...roots][0] : null;
+  if (roots.size === 0) return null;
+  if (roots.size === 1) return [...roots][0];
+  // Monorepo anchors legitimately resolve to DIFFERENT sentinels: a workspace
+  // package (apps/desktop/package.json) is nearer than the repo root, so one
+  // call spanning `apps/desktop/...` and `src/...` yields two roots even though
+  // both live in exactly one project. When one candidate contains every other,
+  // that outermost root IS the single detectable project — adopt it instead of
+  // refusing. Genuinely unrelated trees share no such candidate and still fail.
+  return _outermostContainingRoot([...roots]);
+}
+
+// The candidate that contains (or equals) every other candidate, else null.
+// Only an EXISTING candidate can win: a bare common ancestor that has no
+// sentinel of its own is never adopted as a project root.
+function _outermostContainingRoot(roots) {
+  for (const candidate of roots) {
+    if (roots.every((root) => _isSameOrInside(root, candidate))) return candidate;
+  }
+  return null;
+}
+
+function _isSameOrInside(child, parent) {
+  try {
+    const rel = pathRelative(pathResolve(parent), pathResolve(child));
+    return rel === '' || (!!rel && !rel.startsWith('..') && !isAbsolute(rel));
+  } catch {
+    return false;
+  }
 }
 
 // Aggregate recovery resolves relative anchors against the caller's original
@@ -326,13 +377,19 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     const depsAll = [...(graph.reverse.get(depRel) || [])].sort();
     if (!depsAll.length) return '(no dependents)';
     const deps = depsAll.slice(0, GRAPH_LIST_CAP);
+    await _prewarmSourceTextNodes(
+      graph,
+      deps.map((dep) => graph.nodes.get(dep)).filter(Boolean),
+      { signal },
+    );
     const basename = depRel.split('/').pop();
     const stem = basename.replace(/\.[^/.]+$/, '');
     const enriched = deps.map((dep) => {
       const depNode = graph.nodes.get(dep);
       if (!depNode) return dep;
-      let text;
-      try { text = readFileSync(depNode.abs, 'utf8'); } catch { return dep; }
+      const cached = graph._sourceTextCache?.get(depNode.rel);
+      if (!cached || cached.fingerprint !== (depNode.fingerprint || '')) return dep;
+      const text = cached.text;
       const linesArr = text.split(/\r?\n/);
       for (let i = 0; i < linesArr.length; i++) {
         const ln = linesArr[i];
@@ -358,6 +415,8 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
   if (mode === 'impact') {
     if (!node) return _appendSameBasenameHint(`Error: code_graph impact: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
     const targetSymbol = String(args?.symbol || '').trim();
+    await _prewarmSourceTextNodes(graph, [node], { signal });
+    await _prewarmSourceTextNodes(graph, _impactSourceNodes(node, graph, targetSymbol), { signal });
     return _formatImpact(node, graph, cwd, targetSymbol);
   }
 
@@ -376,6 +435,7 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     if (!_CALLEES_BRACE_LANGS.has(declHit.lang)) {
       return `(callees unsupported for ${declHit.lang})`;
     }
+    await _prewarmSourceTextNodes(graph, [graph.nodes.get(declHit.rel)].filter(Boolean), { signal });
     const rows = _extractCallees(graph, declHit, cwd, {
       cap: 200,
       callerSymbol: symbol,
@@ -389,9 +449,11 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
 
   if (mode === 'symbols') {
     if (!node) return _appendSameBasenameHint(`Error: code_graph symbols: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
-    let text = '';
-    try { text = readFileSync(node.abs, 'utf8'); } catch { return '(no symbols)'; }
-    return _extractSymbolsCheap(text, node.lang);
+    await _prewarmSourceTextNodes(graph, [node], { signal });
+    const cached = graph._sourceTextCache?.get(node.rel);
+    return cached && cached.fingerprint === (node.fingerprint || '')
+      ? _extractSymbolsCheap(cached.text, node.lang)
+      : '(no symbols)';
   }
 
   if (mode === 'find_symbol') {
@@ -400,6 +462,15 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     const language = String(args?.language || '').trim() || null;
     const limit = Math.max(1, Math.min(50, Number(args?.limit || 20)));
     if (rel && !node) return _appendSameBasenameHint(`Error: code_graph find_symbol: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
+    if (args?.body !== false) {
+      const hits = _findSymbolHits(graph, symbol, { language });
+      const primary = hits.find((hit) => hit.declarationLike) || hits[0];
+      await _prewarmSourceTextNodes(
+        graph,
+        [primary?.rel ? graph.nodes.get(primary.rel) : null].filter(Boolean),
+        { signal },
+      );
+    }
     return _findSymbolAcrossGraph(graph, symbol, cwd, { language, limit, fileRel: rel, body: args?.body !== false });
   }
 
@@ -412,6 +483,14 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     const keyword = String(args?.symbol || '').trim();
     const keywords = symbolsList.length ? symbolsList : (keyword ? [keyword] : []);
     if (!keywords.length) throw new Error('code_graph symbol_search: "symbol" (or "symbols[]") is required.');
+    // Native graph symbols answer without source text. Nodes lacking native
+    // symbols fall back to cheap text extraction, so warm exactly that subset
+    // asynchronously before the synchronous formatter scans it.
+    await _prewarmSourceTextNodes(
+      graph,
+      [...graph.nodes.values()].filter((candidate) => !Array.isArray(candidate?.symbols) || candidate.symbols.length === 0),
+      { signal },
+    );
     if (keywords.length === 1) {
       return _searchSymbolsByKeyword(graph, keywords[0], cwd, { language, limit });
     }
@@ -438,6 +517,7 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
       }
     }
     const narrowedByCaller = Boolean(rel || scopeRelPrefix || explicitLanguage);
+    if (node) await _prewarmSourceTextNodes(graph, [node], { signal });
     const resolved = _resolveReferenceLanguageNode(graph, symbol, rel, cwd, explicitLanguage);
     if (rel && resolved.kind === 'file-not-found') {
       return _appendSameBasenameHint(`Error: code_graph references: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
@@ -452,7 +532,7 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     const userLimit = Number.isFinite(rawLimit) && rawLimit > 0
       ? Math.min(500, Math.floor(rawLimit))
       : null;
-    const _refNodes = await _prewarmReferenceSourceText(graph, symbol, lang);
+    const _refNodes = await _prewarmReferenceSourceText(graph, symbol, lang, { signal });
     const refResult = _cheapReferenceSearch(graph, symbol, cwd, { language: lang, limit: userLimit, fileRel: rel, scopeRelPrefix, nodes: _refNodes });
     return narrowedByCaller ? refResult : _augmentNoHitDiagnostic(refResult, '(no references)', graph, cwd, symbol);
   }
@@ -468,6 +548,7 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
       }
     }
     const narrowedByCaller = Boolean(rel || scopeRelPrefix || explicitLanguage);
+    if (node) await _prewarmSourceTextNodes(graph, [node], { signal });
     const resolved = _resolveReferenceLanguageNode(graph, symbol, rel, cwd, explicitLanguage);
     if (rel && resolved.kind === 'file-not-found') {
       return _appendSameBasenameHint(`Error: code_graph callers: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
@@ -482,7 +563,7 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
     const userLimit = Number.isFinite(rawLimit) && rawLimit > 0
       ? Math.min(500, Math.floor(rawLimit))
       : null;
-    const _callerNodes = await _prewarmReferenceSourceText(graph, symbol, lang);
+    const _callerNodes = await _prewarmReferenceSourceText(graph, symbol, lang, { signal });
     const depth = Math.max(1, Math.min(5, Math.floor(Number(args?.depth) || 1)));
     if (depth > 1) {
       return _formatTransitiveCallers(graph, symbol, cwd, { language: lang, depth, page: args?.page });
@@ -527,12 +608,23 @@ async function findSymbolTool(args, cwd, signal = null, options = {}) {
   if (!symbol) {
     if (fileRel) {
       const node = graph.nodes.get(fileRel);
-      let text = '';
-      try { text = readFileSync(node.abs, 'utf8'); } catch { return '(no symbols)'; }
-      return _extractSymbolsCheap(text, node.lang);
+      await _prewarmSourceTextNodes(graph, [node], { signal });
+      const cached = graph._sourceTextCache?.get(node.rel);
+      return cached && cached.fingerprint === (node.fingerprint || '')
+        ? _extractSymbolsCheap(cached.text, node.lang)
+        : '(no symbols)';
     }
     throw new Error('find_symbol: provide "symbol" (to locate) or "file" (to list its symbols).');
   }
+  if (args?.body !== false) {
+    const hits = _findSymbolHits(graph, symbol, { language });
+    const primary = hits.find((hit) => hit.declarationLike) || hits[0];
+    await _prewarmSourceTextNodes(
+      graph,
+      [primary?.rel ? graph.nodes.get(primary.rel) : null].filter(Boolean),
+      { signal },
+    );
+  }
   return _findSymbolAcrossGraph(graph, symbol, cwd, { language, limit, fileRel, body: args?.body !== false });
 }
 
@@ -583,6 +675,7 @@ export async function resolveSymbolReadSpan(cwd, { symbol, path = null, language
   }
   if (!Number.isFinite(endLine) || endLine < startLine) {
     const node = graph.nodes.get(primary.rel);
+    await _prewarmSourceTextNodes(graph, [node].filter(Boolean));
     const srcText = node ? _getSourceTextForNode(graph, node) : null;
     const inferred = srcText ? _inferSpanEndByIndent(srcText.split('\n'), startLine) : null;
     if (inferred) {
@@ -624,6 +717,11 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
     args = { ...args };
     delete args.file;
   }
+  if (symbolMode && _aggregateAnchorsAreCwd(args, baseCwd)) {
+    args = { ...args };
+    delete args.files;
+    delete args.file;
+  }
   const fileArg = (args && typeof args.file === 'string' && args.file.trim()) ? args.file.trim() : '';
   const hasAggregateFileArgs = _hasAggregateFileArgs(args);
   let effectiveCwd = baseCwd;
@@ -647,6 +745,20 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
     ? []
     : collectTrustedCodeGraphRoots(baseCwd)
       .filter((root) => pathResolve(root) !== pathResolve(baseCwd));
+  // Trust registration is a ROUTING PREFERENCE, not an admission gate. A
+  // sentinel-free cwd whose children are obvious project roots (a refs/ folder
+  // of checkouts, a multi-repo parent) is answerable: federate over those
+  // children instead of refusing the call. Cost stays bounded by the existing
+  // per-project graph timeout and the federation fan-out cap — the same way the
+  // reference CLIs bound a wide search (time/output caps, never a scope
+  // refusal). Registered roots keep priority; discovered children only fill in
+  // when registration yields nothing.
+  const federationRootsAtBase = trustedRootsAtBase.length
+    ? trustedRootsAtBase
+    : (baseProjectRoot
+      ? []
+      : _childProjectRoots(baseCwd, { cap: CODE_GRAPH_DISCOVERED_FEDERATION_CAP })
+        .filter((root) => pathResolve(root) !== pathResolve(baseCwd)));
   // A sentinel-free cwd (multi-repo parent, vendored reference tree) is still
   // routable when trusted project roots live under it — federate over those
   // instead of refusing the call outright.
@@ -656,9 +768,12 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
     && !fileArg
     && !hasAggregateFileArgs
     && ROOT_FEDERATED_MODES.has(rawModeAtBase)
-    && trustedRootsAtBase.length > 0;
+    && federationRootsAtBase.length > 0;
   if (filesystemRootCwd || parentDotFederation || sentinelFreeFederation) {
-    const trustedRoots = trustedRootsAtBase;
+    // A filesystem root stays on the REGISTERED set only: fanning out over
+    // every project directory on a whole drive is a different cost class than
+    // fanning out over one folder's children.
+    const trustedRoots = filesystemRootCwd ? trustedRootsAtBase : federationRootsAtBase;
     const files = exactDotFederation ? [] : aggregateFilesAtBase;
     const rawMode = rawModeAtBase;
     const canFederate = files.length > 0 || ROOT_FEDERATED_MODES.has(rawMode);
@@ -818,7 +933,8 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
           ? findSymbolTool(_stripEmptyArgs(a), effectiveCwd, signal, options)
           : codeGraph(a, effectiveCwd, signal, options));
         if (CODE_GRAPH_BATCHABLE_MODES.has(batchMode)) {
-          const symbolList = _collectGraphSymbolList(args);
+          const collectedSymbols = _collectGraphSymbolList(args);
+          const symbolList = collectedSymbols.slice(0, CODE_GRAPH_MAX_BATCH_SYMBOLS);
           if (symbolList.length > 1) {
             return (async () => {
               // Concurrent fan-out: the underlying graph build is single-flight
@@ -831,10 +947,10 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
                 catch (e) { body = `Error: ${e?.message || String(e)}`; }
                 return `# ${batchMode} ${sym}\n${body}`;
               }));
-              if (symbolList._omitted?.length) {
+              if (collectedSymbols.length > symbolList.length) {
                 sections.push(
-                  `Note: symbol list capped at ${CODE_GRAPH_SYMBOL_BATCH_CAP}; `
-                  + `retry symbols=${JSON.stringify(symbolList._omitted)}.`,
+                  `[arg-guard] notice: symbol list capped at ${CODE_GRAPH_MAX_BATCH_SYMBOLS} `
+                    + `(${collectedSymbols.length - symbolList.length} omitted)`,
                 );
               }
               return sections.join('\n\n');
@@ -847,8 +963,8 @@ async function executeCodeGraphToolRaw(name, args, cwd, signal = null, options =
         if (CODE_GRAPH_FILE_BATCHABLE_MODES.has(batchMode)) {
           const fileList = _collectGraphFileList(args);
           if (fileList.length > 1) {
-            const capped = fileList._capped;
             return (async () => {
+              const capped = fileList._capped;
               const sections = await Promise.all(fileList.map(async (f) => {
                 let body;
                 try { body = await dispatchOne({ ...args, file: f, files: undefined }); }

package/src/runtime/agent/orchestrator/tools/code-graph/search-references.mjs

@@ -2,7 +2,6 @@
 // Symbol search / callers / callees / references / impact query layer over a
 // built graph. Pure over {graph,cwd,args}; owns no cache state. Extracted
 // verbatim from code-graph.mjs.
-import { readFileSync } from 'node:fs';
 import { _isJsLike } from './lang-predicates.mjs';
 import { _maskNonCodeText } from './text-mask.mjs';
 import {
@@ -61,6 +60,18 @@ function _collectImpactSymbols(node, graph) {
   return [...names];
 }
 
+export function _impactSourceNodes(node, graph, targetSymbol = '') {
+  const symbols = targetSymbol ? [targetSymbol] : _collectImpactSymbols(node, graph).slice(0, 8);
+  const out = [];
+  const seen = new Set();
+  for (const candidate of [node, ...symbols.flatMap((symbol) => _lookupCandidateNodes(graph, symbol, node?.lang || null))]) {
+    if (!candidate?.rel || seen.has(candidate.rel)) continue;
+    seen.add(candidate.rel);
+    out.push(candidate);
+  }
+  return out;
+}
+
 function _buildImpactSummary(node, graph, cwd, targetSymbol = '') {
   const imports = node.resolvedImports.map((p) => _graphRel(p, cwd));
   const dependents = [...(graph.reverse.get(node.rel) || [])].sort();

package/src/runtime/agent/orchestrator/tools/code-graph/search.mjs

@@ -1,7 +1,8 @@
 // Symbol search / callers / callees / references / impact query layer over a
 // built graph. Pure over {graph,cwd,args}; owns no cache state. Extracted
 // verbatim from code-graph.mjs.
-import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { codeGraphSourceIoAdmission } from '../../../../shared/tool-workload-gates.mjs';
 import { _isJsLike } from './lang-predicates.mjs';
 import { _maskNonCodeText } from './text-mask.mjs';
 import {
@@ -30,7 +31,7 @@ import {
   _keywordMatchesSymbolName,
 } from './keyword-match.mjs';
 
-export { _formatRelated, _formatImpact, _findSymbolAcrossGraph, _resolveReferenceLanguageNode, _formatCallerReferences, _formatTransitiveCallers } from './search-references.mjs';
+export { _formatRelated, _formatImpact, _impactSourceNodes, _findSymbolAcrossGraph, _resolveReferenceLanguageNode, _formatCallerReferences, _formatTransitiveCallers } from './search-references.mjs';
 export function _extractCallees(graph, declHit, _cwd, { cap = 200, callerSymbol = null, language = null } = {}) {
   if (!declHit || !_CALLEES_BRACE_LANGS.has(declHit.lang)) return [];
   const declNode = graph.nodes.get(declHit.rel);
@@ -253,37 +254,64 @@ export function _formatCalleeRow(row) {
   const enclosing = row.enclosing ? `(in ${row.enclosing})` : '(in ?)';
   return `${row.name}\t${callsite}\t${decl}\t${enclosing}`;
 }
-export async function _prewarmReferenceSourceText(graph, symbol, language) {
-  const candidateNodes = _lookupCandidateNodes(graph, symbol, language);
-  // Return the resolved candidate set so the immediately-following
-  // _cheapReferenceSearch (references/callers dispatch) can reuse it instead
-  // of recomputing _lookupCandidateNodes for the same (symbol, language) —
-  // which on a token-index miss is a full-graph scan run twice per symbol.
-  if (!candidateNodes.length) return candidateNodes;
+const CODE_GRAPH_SOURCE_READ_CONCURRENCY = Math.max(
+  1,
+  Math.min(32, Math.floor(Number(process.env.MIXDOG_CODE_GRAPH_SOURCE_READ_CONCURRENCY) || 8)),
+);
+
+export async function _prewarmSourceTextNodes(graph, nodes, {
+  concurrency = CODE_GRAPH_SOURCE_READ_CONCURRENCY,
+  readFileImpl = readFile,
+  signal = null,
+  ownerKey = null,
+} = {}) {
+  const sourceNodes = [];
+  const seen = new Set();
+  for (const node of Array.isArray(nodes) ? nodes : []) {
+    if (!node?.rel || !node?.abs || seen.has(node.rel)) continue;
+    seen.add(node.rel);
+    sourceNodes.push(node);
+  }
   const uncached = [];
-  for (const node of candidateNodes) {
+  for (const node of sourceNodes) {
     const cached = graph._sourceTextCache?.get(node.rel);
     if (!cached || cached.fingerprint !== (node.fingerprint || '')) {
       uncached.push(node);
     }
   }
-  if (uncached.length === 0) return candidateNodes;
-  const { readFile } = await import('fs/promises');
-  const concurrency = 64;
   let next = 0;
-  async function worker() {
-    while (true) {
+  const worker = async () => {
+    while (!signal?.aborted) {
       const index = next++;
       if (index >= uncached.length) return;
       const node = uncached[index];
       try {
-        const text = await readFile(node.abs, 'utf8');
+        const text = await codeGraphSourceIoAdmission.run(
+          ownerKey,
+          () => readFileImpl(node.abs, 'utf8'),
+          { signal },
+        );
         graph._sourceTextCache?.set(node.rel, { fingerprint: node.fingerprint || '', text });
-      } catch { /* skip unreadable file */ }
+      } catch { /* skip unreadable/aborted file */ }
     }
+  };
+  const workerCount = Math.min(
+    Math.max(1, Math.floor(Number(concurrency) || CODE_GRAPH_SOURCE_READ_CONCURRENCY)),
+    Math.max(1, uncached.length),
+  );
+  if (uncached.length > 0) {
+    await Promise.all(Array.from({ length: workerCount }, worker));
   }
-  const workerCount = Math.min(Math.max(1, concurrency), uncached.length);
-  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  return sourceNodes;
+}
+
+export async function _prewarmReferenceSourceText(graph, symbol, language, options = {}) {
+  const candidateNodes = _lookupCandidateNodes(graph, symbol, language);
+  // Return the resolved candidate set so the immediately-following
+  // _cheapReferenceSearch (references/callers dispatch) can reuse it instead
+  // of recomputing _lookupCandidateNodes for the same (symbol, language) —
+  // which on a token-index miss is a full-graph scan run twice per symbol.
+  await _prewarmSourceTextNodes(graph, candidateNodes, options);
   return candidateNodes;
 }
 

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,17 +3,18 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Repo code structure/flow over source files. File modes take files[]; symbol modes take symbols[] — exact identifiers via find_symbol/references/callers/callees, keywords via symbol_search/search. Unsupported target arrays are omitted, never mixed.',
+    description: 'Source-file structure, symbol relations, and flow. File modes take files[]; symbol modes take symbols[] — exact identifiers via find_symbol/references/callers/callees, keywords via symbol_search/search (symbol-index terms). Unsupported target arrays are omitted, never mixed.',
     inputSchema: {
       type: 'object',
       properties: {
         mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'], description: 'File modes={overview,imports,dependents,related,impact}; symbols with files[]=file outline; the rest are symbol modes.' },
         files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Source file path(s); supported targets only.' },
-        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Exact identifiers or keywords; batch multiple in one symbols[].' },
+        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Exact identifiers or keywords; keywords are symbol-index terms; batch multiple in one symbols[].' },
         body: { type: 'boolean', description: 'Include body.' },
         limit: { type: 'number', minimum: 1, description: 'Max results.' },
         depth: { type: 'number', minimum: 1, maximum: 5, description: 'Caller depth.' },
         page: { type: 'number', minimum: 1, description: 'Caller page.' },
+        cwd: { type: 'string', description: 'Explicit root.' },
       },
       required: ['mode'],
       additionalProperties: false,

package/src/runtime/agent/orchestrator/tools/env-scrub.mjs

@@ -120,8 +120,7 @@ export function scrubRuntimeRootVars(env) {
     // Daemon IDENTITY leak: user-facing children must not inherit host/worker
     // ownership or the daemon's terminal-lead PID. Internal daemon/worker
     // spawns set every identity value explicitly after this boundary.
-    delete env.MIXDOG_ENGINE_DAEMON_HOST;
-    delete env.MIXDOG_CHANNEL_DAEMON;
+    delete env.MIXDOG_DAEMON_HOST;
     delete env.MIXDOG_WORKER_MODE;
     delete env.MIXDOG_DAEMON_SPAWNED_FOR;
     delete env.MIXDOG_SUPERVISOR_PID;