@devflow-tools/context-engine 0.16.26 → 0.16.28

package/dist/context-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-engine.d.ts","sourceRoot":"","sources":["../src/context-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,WAAW,EACX,aAAa,EAOd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAOzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,OAAO,KAAK,EAKV,kBAAkB,EAClB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAsSpB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAwBD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,IAAI,EAAE,iBAAiB;IAYnC,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,UAAU,CAAkD;IAE9D,gCAAgC,CAAC,KAAK,EAAE;QAC5C,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC;IAIX,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,OAAO,CAAC,yBAAyB;YAuBnB,yBAAyB;IAiCvC,OAAO,CAAC,eAAe;IAKjB,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwQtD,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,+BAA+B,CAAC;YAqe/F,sBAAsB;IAkSpC,OAAO,CAAC,yBAAyB;YAgBnB,2BAA2B;YA4B3B,6BAA6B;IAkB3C,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,2BAA2B;IAOnC,SAAS,IAAI,WAAW;CASzB"}
+{"version":3,"file":"context-engine.d.ts","sourceRoot":"","sources":["../src/context-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,WAAW,EACX,aAAa,EAOd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAQzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,OAAO,KAAK,EAKV,kBAAkB,EAClB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAsSpB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAoCD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,IAAI,EAAE,iBAAiB;IAYnC,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,UAAU,CAAkD;IAE9D,gCAAgC,CAAC,KAAK,EAAE;QAC5C,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC;IAIX,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,OAAO,CAAC,yBAAyB;YA4BnB,yBAAyB;IAiCvC,OAAO,CAAC,eAAe;IAKjB,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAmRtD,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,+BAA+B,CAAC;YAwiB/F,sBAAsB;IAmWpC,OAAO,CAAC,yBAAyB;YAgBnB,2BAA2B;YA4B3B,6BAA6B;IAkB3C,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,2BAA2B;IAOnC,SAAS,IAAI,WAAW;CASzB"}

package/dist/context-engine.js

@@ -1,9 +1,10 @@
 import CGModule from "@colbymchenry/codegraph";
 import { parseIntent, expandQuery } from "./intent-parser.js";
+import { buildRetrievalTaskPlan } from './retrieval-task-plan.js';
 import { fuzzySearch, shouldFallback } from "./fuzzy-fallback.js";
 import { compressToTokenLimit } from "./compressor.js";
 import { claudeRerank } from "./claude-rerank.js";
-import { QueryCache } from "./query-cache.js";
+import { invalidateContextPrefetchCache, QueryCache } from "./query-cache.js";
 import { rankOptionalContextFiles, } from "./ranker.js";
 import { describeLayerEvidence, detectLanguageFromPath, } from "./layer-rules.js";
 import { reachableCodeGraphNodeIds, sanitizeCodeGraphEdges, } from './graph-edge-quality.js';
@@ -241,8 +242,21 @@ function extractTargetAnchors(query) {
         if (match[1])
             pathAnchors.add(match[1].replace(/^\.\//, '').replace(/\/+$/, '').toLowerCase());
     }
-    if (pathAnchors.size > 0)
+    if (pathAnchors.size > 0) {
+        const directories = [...pathAnchors]
+            .filter(anchor => /\.[a-z0-9]+$/iu.test(anchor))
+            .map(anchor => anchor.split('/').slice(0, -1).join('/'))
+            .filter(Boolean);
+        const existingNames = new Set([...pathAnchors].map(anchor => anchor.split('/').at(-1)));
+        for (const match of query.matchAll(/\b([A-Za-z0-9_.-]+\.(?:[cm]?[jt]sx?|vue|svelte|json|ya?ml|md))\b/gu)) {
+            const fileName = match[1]?.toLowerCase();
+            if (!fileName || existingNames.has(fileName))
+                continue;
+            if (directories.length === 1)
+                pathAnchors.add(`${directories[0]}/${fileName}`);
+        }
         return [...pathAnchors];
+    }
     const anchors = new Set();
     for (const match of query.matchAll(/([a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)+)\s+(?:component|module|file|组件|模块|文件)/gi)) {
         if (match[1])
@@ -289,7 +303,7 @@ export class ContextEngine {
     async index(_projectRoot) {
         await this.indexer.reconcile();
     }
-    getKnowledgeSearchOptions(query, limit, options = {}) {
+    getKnowledgeSearchOptions(query, limit, options = {}, taskPlan, totalBudget = 8_000) {
         const stats = this.cg.getStats();
         const frameworks = typeof this.cg.getDetectedFrameworks === "function"
             ? this.cg.getDetectedFrameworks()
@@ -297,8 +311,11 @@ export class ContextEngine {
         const languages = Object.keys(stats.filesByLanguage ?? {});
         return {
             limit,
+            budgetTokens: Math.max(0, Math.floor(totalBudget * 0.25)),
             activeSkill: options.activeSkill,
             relevantFiles: options.relevantFiles,
+            action: taskPlan?.action,
+            knowledgeNeeds: taskPlan?.knowledgeNeeds,
             projectSignals: {
                 frameworks,
                 languages,
@@ -329,6 +346,12 @@ export class ContextEngine {
         const warnings = this.scheduleSymbolVectorBuild();
         const maxTokens = request.maxTokens ?? 8000;
         const intent = parseIntent(request.query);
+        const retrievalTaskPlan = buildRetrievalTaskPlan({
+            query: request.query,
+            parsedIntent: intent,
+            targetAnchors: request.relevantFiles,
+            activeSkill: request.activeSkill,
+        });
         const stats = this.cg.getStats();
         const adaptive = getAdaptiveParams(stats.fileCount ?? 500);
         const depth = request.mode === "deep" ? 3 : adaptive.depth;
@@ -418,10 +441,13 @@ export class ContextEngine {
         }
         // 2. Knowledge + Memory in parallel
         const [kResultsRaw, memResultsRaw] = await Promise.all([
-            this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 10, { activeSkill: request.activeSkill, relevantFiles: request.relevantFiles })).catch(() => ({ entries: [], warnings: [] })),
+            this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 10, { activeSkill: request.activeSkill, relevantFiles: request.relevantFiles }, retrievalTaskPlan, maxTokens)).catch(() => ({ entries: [], warnings: [] })),
             this.memory.search(request.query, {
                 limit: 5,
                 purpose: intent.intent,
+                scope: this.cg.getProjectRoot?.() ?? process.cwd(),
+                action: retrievalTaskPlan.action,
+                requiredPolicyFacets: retrievalTaskPlan.requiredPolicyFacets,
             }).catch(() => []),
         ]);
         if (kResultsRaw.warnings.length > 0)
@@ -564,10 +590,29 @@ export class ContextEngine {
         const warnings = this.scheduleSymbolVectorBuild();
         const maxTokens = options?.maxTokens ?? 8000;
         const mode = options?.mode ?? "fast";
-        const cacheKey = `ctx:${query}:${mode}:${options?.activeSkill ?? ""}:${(options?.relevantFiles ?? []).join(",")}`;
-        const cached = warnings.length === 0 && !options?.requestId
+        const memoryRevision = this.memory.getRetrievalRevision?.() ?? 0;
+        const cacheKey = `ctx:${query}:${mode}:${options?.activeSkill ?? ""}:${(options?.relevantFiles ?? []).join(",")}:memory:${memoryRevision}`;
+        let cached = warnings.length === 0 && !options?.requestId
             ? this.queryCache.get(cacheKey)
             : undefined;
+        if (cached) {
+            const changed = typeof this.cg.getChangedFiles === 'function'
+                ? this.cg.getChangedFiles()
+                : {};
+            const changedPaths = [...(changed.added ?? []), ...(changed.modified ?? []), ...(changed.removed ?? [])];
+            const cachedPaths = [
+                ...getGroupFilePaths(cached.requiredFiles),
+                ...getGroupFilePaths(cached.optionalFiles),
+            ];
+            const freshness = this.indexer?.ensureFilesCurrent
+                ? await this.indexer.ensureFilesCurrent(cachedPaths, { refresh: false })
+                : null;
+            if (changedPaths.length > 0 || freshness?.files.some(file => !file.current)) {
+                this.queryCache.invalidatePaths(new Set([...changedPaths, ...(freshness?.stale ?? []), ...(freshness?.missing ?? [])]));
+                invalidateContextPrefetchCache(this.cg.getProjectRoot?.() ?? process.cwd());
+                cached = undefined;
+            }
+        }
         if (cached) {
             return {
                 ...cached,
@@ -578,6 +623,13 @@ export class ContextEngine {
         const taskType = intent.intent;
         const combinedQuery = mergeQueries(query, expandQuery(query), options?.expandedTerms);
         const targetAnchors = extractTargetAnchors(query);
+        const retrievalTaskPlan = buildRetrievalTaskPlan({
+            query,
+            parsedIntent: intent,
+            targetAnchors,
+            activeSkill: options?.activeSkill,
+            command: options?.command,
+        });
         const timing = {};
         const t0 = Date.now();
         const [cgResult, knowledgeResult, memoryHits] = await Promise.all([
@@ -597,7 +649,7 @@ export class ContextEngine {
                 })
                 : Promise.resolve(null),
             Promise.race([
-                this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options)),
+                this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options, retrievalTaskPlan, maxTokens)),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("knowledge timeout")), 5000)),
             ]).catch((err) => {
                 console.error("[devflow] knowledge.search timeout:", err.message);
@@ -609,6 +661,9 @@ export class ContextEngine {
                         limit: 5,
                         purpose: taskType,
                         recordAccess: false,
+                        scope: this.cg.getProjectRoot?.() ?? process.cwd(),
+                        action: retrievalTaskPlan.action,
+                        requiredPolicyFacets: retrievalTaskPlan.requiredPolicyFacets,
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error("memory timeout")), 5000)),
                 ]).catch((err) => {
@@ -678,6 +733,31 @@ export class ContextEngine {
         }
         console.error("[devflow:timing] Fallback searchNodes loop:", Date.now() - tFallback, "ms");
         timing["2_fallback_loop"] = Date.now() - tFallback;
+        const fileFreshnessByPath = new Map();
+        if (this.indexer?.ensureFilesCurrent) {
+            const candidatePaths = [...new Set([
+                    ...ctx.nodes.map((node) => String(node.filePath ?? '')).filter(Boolean),
+                    ...ctx.entryPoints.map((entry) => String(entry.filePath ?? '')).filter(Boolean),
+                ])];
+            const freshness = await this.indexer.ensureFilesCurrent(candidatePaths, { refresh: true, timeoutMs: 5_000 });
+            for (const file of freshness.files)
+                fileFreshnessByPath.set(file.path, file);
+            const rejectedPaths = new Set([...freshness.missing, ...freshness.stale]);
+            if (rejectedPaths.size > 0 || freshness.refreshed.length > 0) {
+                this.queryCache.invalidatePaths(new Set([...rejectedPaths, ...freshness.refreshed]));
+                invalidateContextPrefetchCache(this.cg.getProjectRoot?.() ?? process.cwd());
+            }
+            if (freshness.missing.length > 0)
+                warnings.push(`codegraph-missing-files:${freshness.missing.length}`);
+            if (freshness.stale.length > 0)
+                warnings.push(`codegraph-stale-degraded:${freshness.stale.length}`);
+            ctx.nodes = ctx.nodes.filter((node) => !rejectedPaths.has(node.filePath));
+            ctx.entryPoints = ctx.entryPoints.filter((entry) => !rejectedPaths.has(entry.filePath));
+            if (Array.isArray(ctx.edges) && rejectedPaths.size > 0) {
+                const retainedIds = new Set(ctx.nodes.map((node) => node.id));
+                ctx.edges = ctx.edges.filter((edge) => retainedIds.has(edge.source) && retainedIds.has(edge.target));
+            }
+        }
         const edgeQuality = sanitizeCodeGraphEdges(this.cg, Array.isArray(ctx.edges) ? ctx.edges : []);
         ctx.edges = edgeQuality.accepted;
         if (edgeQuality.rejected.length > 0) {
@@ -774,6 +854,9 @@ export class ContextEngine {
             })
             : [];
         for (const candidate of roleCandidates) {
+            if (this.indexer?.getFileFreshness) {
+                fileFreshnessByPath.set(candidate.path, this.indexer.getFileFreshness(candidate.path));
+            }
             fileRoleByPath.set(candidate.path, candidate);
             if (candidate.role === 'target') {
                 requiredFileSet.add(candidate.path);
@@ -791,10 +874,21 @@ export class ContextEngine {
                 });
             }
         }
-        const rankedOptionalFiles = rankOptionalContextFiles([...optionalCandidates.values()], taskType);
-        const rankedOptionalPaths = new Set(rankedOptionalFiles.map(candidate => candidate.path));
+        let rankedOptionalFiles = rankOptionalContextFiles([...optionalCandidates.values()], taskType);
         for (const candidate of rankedOptionalFiles)
             optionalFileSet.add(candidate.path);
+        if (this.indexer?.getFileFreshness) {
+            for (const path of [...requiredFileSet, ...optionalFileSet]) {
+                const freshness = fileFreshnessByPath.get(path) ?? this.indexer.getFileFreshness(path);
+                fileFreshnessByPath.set(path, freshness);
+                if (freshness.current)
+                    continue;
+                requiredFileSet.delete(path);
+                optionalFileSet.delete(path);
+                fileRoleByPath.delete(path);
+            }
+            rankedOptionalFiles = rankedOptionalFiles.filter(candidate => optionalFileSet.has(candidate.path));
+        }
         const optionalCandidateByPath = new Map(rankedOptionalFiles.map(candidate => [candidate.path, candidate]));
         const retainedFiles = new Set([...requiredFileSet, ...optionalFileSet]);
         for (let index = keySymbols.length - 1; index >= 0; index--) {
@@ -845,7 +939,7 @@ export class ContextEngine {
                 score: 0.5,
             });
         }
-        const compressed = compressToTokenLimit(allFileSnippets, maxTokens);
+        const compressed = compressToTokenLimit(allFileSnippets, Math.floor(maxTokens * 0.45));
         if (compressed.overBudget)
             warnings.push("context-compressor-budget-exceeded");
         console.error("[devflow:timing] Snippet building + compress:", Date.now() - tSnippet, "ms");
@@ -979,7 +1073,9 @@ export class ContextEngine {
             command: options?.command,
             tokenBudget: maxTokens,
             targetAnchors,
+            taskPlan: retrievalTaskPlan,
             fileRoles: fileRoleByPath,
+            fileFreshness: fileFreshnessByPath,
             memoryHits,
             knowledgeHits,
             rejectedCodeRelations: edgeQuality.rejected.length,
@@ -1029,6 +1125,27 @@ export class ContextEngine {
         });
         await this.applyLegacySymbolVectorRecall(cgResult, query, warnings);
         this.clearRecoveredSymbolWarning(warnings);
+        const fileFreshnessByPath = new Map();
+        if (this.indexer?.ensureFilesCurrent) {
+            const candidatePaths = [...new Set(Array.from(cgResult.nodes.values()).map(node => node.filePath))];
+            const freshness = await this.indexer.ensureFilesCurrent(candidatePaths, { refresh: true, timeoutMs: 5_000 });
+            for (const file of freshness.files)
+                fileFreshnessByPath.set(file.path, file);
+            const rejectedPaths = new Set([...freshness.missing, ...freshness.stale]);
+            for (const [id, node] of cgResult.nodes) {
+                if (rejectedPaths.has(node.filePath))
+                    cgResult.nodes.delete(id);
+            }
+            cgResult.roots = cgResult.roots.filter(id => cgResult.nodes.has(id));
+            if (freshness.missing.length > 0)
+                warnings.push(`codegraph-missing-files:${freshness.missing.length}`);
+            if (freshness.stale.length > 0)
+                warnings.push(`codegraph-stale-degraded:${freshness.stale.length}`);
+            if (rejectedPaths.size > 0 || freshness.refreshed.length > 0) {
+                this.queryCache.invalidatePaths(new Set([...rejectedPaths, ...freshness.refreshed]));
+                invalidateContextPrefetchCache(this.cg.getProjectRoot?.() ?? process.cwd());
+            }
+        }
         const edgeQuality = sanitizeCodeGraphEdges(this.cg, cgResult.edges ?? []);
         if (edgeQuality.rejected.length > 0) {
             warnings.push(`codegraph-relations-rejected:${edgeQuality.rejected.length}`);
@@ -1082,6 +1199,13 @@ export class ContextEngine {
             }
         }
         const targetAnchors = extractTargetAnchors(query);
+        const retrievalTaskPlan = buildRetrievalTaskPlan({
+            query,
+            parsedIntent: intent,
+            targetAnchors,
+            activeSkill: options?.activeSkill,
+            command: options?.command,
+        });
         const roleTargets = targetAnchors.length > 0
             ? [...requiredFileSet].filter(file => fileMatchesTargetAnchor(file, targetAnchors))
             : allNodes.filter(node => rootIds.has(node.id)).map(node => node.filePath);
@@ -1095,6 +1219,9 @@ export class ContextEngine {
             })
             : [];
         for (const candidate of roleCandidates) {
+            if (this.indexer?.getFileFreshness) {
+                fileFreshnessByPath.set(candidate.path, this.indexer.getFileFreshness(candidate.path));
+            }
             fileRoleByPath.set(candidate.path, candidate);
             if (candidate.role === 'target') {
                 requiredFileSet.add(candidate.path);
@@ -1112,9 +1239,21 @@ export class ContextEngine {
                 });
             }
         }
-        const rankedOptionalFiles = rankOptionalContextFiles([...optionalCandidates.values()], taskType);
+        let rankedOptionalFiles = rankOptionalContextFiles([...optionalCandidates.values()], taskType);
         for (const candidate of rankedOptionalFiles)
             optionalFileSet.add(candidate.path);
+        if (this.indexer?.getFileFreshness) {
+            for (const path of [...requiredFileSet, ...optionalFileSet]) {
+                const freshness = fileFreshnessByPath.get(path) ?? this.indexer.getFileFreshness(path);
+                fileFreshnessByPath.set(path, freshness);
+                if (freshness.current)
+                    continue;
+                requiredFileSet.delete(path);
+                optionalFileSet.delete(path);
+                fileRoleByPath.delete(path);
+            }
+            rankedOptionalFiles = rankedOptionalFiles.filter(candidate => optionalFileSet.has(candidate.path));
+        }
         for (const node of allNodes) {
             if (optionalFileSet.has(node.filePath))
                 optionalSymbols.push(node.name);
@@ -1172,10 +1311,12 @@ export class ContextEngine {
         const nextActions = generateNextActions(taskType, keySymbols.slice(0, 5));
         // Knowledge hits
         let knowledgeReasoning = [];
+        let knowledgeHits = [];
         try {
-            const kResults = await this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options));
+            const kResults = await this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options, retrievalTaskPlan, maxTokens));
             if (kResults.warnings.length > 0)
                 warnings.push(...kResults.warnings);
+            knowledgeHits = kResults.entries;
             knowledgeReasoning = kResults.entries.map(k => ({
                 source: "knowledge",
                 fileGroup: k.source ?? "knowledge",
@@ -1187,16 +1328,21 @@ export class ContextEngine {
         }
         // Memory context
         let memoryReasoning = [];
+        let memoryHits = [];
         try {
-            const mem = await this.memory.getAll();
-            const conventions = mem.project?.conventions ?? [];
-            if (Array.isArray(conventions) && conventions.length > 0) {
-                memoryReasoning = [{
-                        source: "memory",
-                        fileGroup: "project memory",
-                        explanation: `${conventions.length} conventions available for context`,
-                    }];
-            }
+            memoryHits = await this.memory.search(query, {
+                limit: 5,
+                purpose: taskType,
+                scope: this.cg.getProjectRoot?.() ?? process.cwd(),
+                action: retrievalTaskPlan.action,
+                requiredPolicyFacets: retrievalTaskPlan.requiredPolicyFacets,
+                recordAccess: false,
+            });
+            memoryReasoning = memoryHits.map((hit) => ({
+                source: 'memory',
+                fileGroup: hit.entry?.title ?? 'project memory',
+                explanation: `Selected applicable memory ${hit.entry?.id ?? 'unknown'} with score ${hit.score ?? 0}`,
+            }));
         }
         catch {
             // memory may be empty
@@ -1221,12 +1367,12 @@ export class ContextEngine {
                 score: 0.5,
             });
         }
-        const compressed = compressToTokenLimit(allFileSnippets, maxTokens);
+        const compressed = compressToTokenLimit(allFileSnippets, Math.floor(maxTokens * 0.45));
         if (compressed.overBudget)
             warnings.push("context-compressor-budget-exceeded");
         const requiredPaths = new Set(compressed.files.filter(f => requiredFileSet.has(f.path)).map(f => f.path));
         const optionalPaths = new Set(compressed.files.filter(f => optionalFileSet.has(f.path)).map(f => f.path));
-        return {
+        const result = {
             taskType,
             requiredFiles: {
                 files: [...requiredPaths],
@@ -1282,6 +1428,25 @@ export class ContextEngine {
                 ],
             },
         };
+        result.taskEnvelope = buildTaskContextEnvelope({
+            query,
+            result,
+            projectRoot: this.cg.getProjectRoot?.() ?? process.cwd(),
+            sessionId: options?.sessionId,
+            executionId: options?.executionId,
+            requestId: options?.requestId,
+            host: options?.host,
+            command: options?.command,
+            tokenBudget: maxTokens,
+            targetAnchors,
+            fileRoles: fileRoleByPath,
+            fileFreshness: fileFreshnessByPath,
+            memoryHits,
+            knowledgeHits,
+            rejectedCodeRelations: edgeQuality.rejected.length,
+            taskPlan: retrievalTaskPlan,
+        });
+        return result;
     }
     scheduleSymbolVectorBuild() {
         const warnings = [];
@@ -1366,4 +1531,9 @@ export class ContextEngine {
         };
     }
 }
+function getGroupFilePaths(group) {
+    if (Array.isArray(group))
+        return group;
+    return group?.files ?? [];
+}
 //# sourceMappingURL=context-engine.js.map