byterover-cli 2.0.0 → 2.1.0

package/dist/server/infra/executor/curate-executor.js

@@ -2,6 +2,11 @@ import path from 'node:path';
 import { FileValidationError } from '../../core/domain/errors/task-error.js';
 import { createFileContentReader, } from '../../utils/file-content-reader.js';
 import { validateFileForCurate } from '../../utils/file-validator.js';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
+import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
+import { FileContextTreeSummaryService } from '../context-tree/file-context-tree-summary-service.js';
+import { diffStates } from '../context-tree/snapshot-diff.js';
+import { PreCompactionService } from './pre-compaction/pre-compaction-service.js';
 /**
  * CurateExecutor - Executes curate tasks with an injected CipherAgent.
  *
@@ -26,48 +31,72 @@ export class CurateExecutor {
     /** Last curation status — available for future status-check command */
     lastStatus;
     fileContentReader;
+    preCompactionService = new PreCompactionService();
     constructor(fileContentReader) {
         this.fileContentReader = fileContentReader ?? createFileContentReader();
     }
     async executeWithAgent(agent, options) {
         const { clientCwd, content, files, taskId } = options;
-        // Create per-task session for parallel isolation (own sandbox + history + LLM service)
-        const taskSessionId = await agent.createTaskSession(taskId, 'curate');
-        // Process file references - reads file contents directly
+        // --- Phase 1: Preprocessing (no sessions created yet — safe to throw) ---
         const fileReferenceInstructions = await this.processFileReferences(files ?? [], clientCwd);
-        // Build full context (content + optional file references)
         const fullContext = fileReferenceInstructions ? `${content}\n${fileReferenceInstructions}` : content;
-        // Task-scoped variable names for RLM pattern.
-        // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
-        // so the LLM would naturally use underscores when writing code-exec calls — causing a
-        // ReferenceError if the variable was stored under the hyphen version.
-        const taskIdSafe = taskId.replaceAll('-', '_');
-        const ctxVar = `__curate_ctx_${taskIdSafe}`;
-        const histVar = `__curate_hist_${taskIdSafe}`;
-        const metaVar = `__curate_meta_${taskIdSafe}`;
-        // Compute context metadata (RLM pattern — LM sees metadata, not raw content)
-        const contextLines = fullContext.split('\n');
-        const metadata = {
-            charCount: fullContext.length,
-            lineCount: contextLines.length,
-            messageCount: (fullContext.match(/\n\n\[(USER|ASSISTANT)\]:/g) || []).length,
-            preview: fullContext.slice(0, 500),
-            type: 'string',
-        };
-        // Inject context, metadata, and empty history into the TASK session's sandbox
-        agent.setSandboxVariableOnSession(taskSessionId, ctxVar, fullContext);
-        agent.setSandboxVariableOnSession(taskSessionId, histVar, { entries: [], totalProcessed: 0 });
-        agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
-        // Prompt with metadata guidance (RLM pattern: LM sees metadata first, peeks via slicing)
-        const prompt = [
-            `Curate using RLM approach.`,
-            `Context variable: ${ctxVar} (${metadata.charCount} chars, ${metadata.lineCount} lines, ${metadata.messageCount} messages)`,
-            `History variable: ${histVar}`,
-            `Metadata variable: ${metaVar}`,
-            `IMPORTANT: Do NOT print raw context. Use slicing to peek at sections (e.g., ${ctxVar}.slice(0, 3000)).`,
-            `Use silent mode (silent: true) for variable assignments. Use tools.agentQuery() for chunk processing.`,
-        ].join('\n');
+        // --- Phase 2: Pre-compaction (fail-open, manages its own session lifecycle) ---
+        const compactionResult = await this.preCompactionService.compact(agent, fullContext, taskId);
+        const effectiveContext = compactionResult.context;
+        // --- Phase 3: Curation (session created AFTER preprocessing + compaction) ---
+        // Capture pre-curation state for snapshot diff (summary propagation)
+        const baseDir = clientCwd ?? process.cwd();
+        const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: baseDir });
+        let preState;
+        try {
+            preState = await snapshotService.getCurrentState(baseDir);
+        }
+        catch {
+            // Fail-open: if snapshot fails, skip summary propagation
+        }
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
         try {
+            // Task-scoped variable names for RLM pattern.
+            // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
+            // so the LLM would naturally use underscores when writing code-exec calls — causing a
+            // ReferenceError if the variable was stored under the hyphen version.
+            const taskIdSafe = taskId.replaceAll('-', '_');
+            const ctxVar = `__curate_ctx_${taskIdSafe}`;
+            const histVar = `__curate_hist_${taskIdSafe}`;
+            const metaVar = `__curate_meta_${taskIdSafe}`;
+            // Compute context metadata (RLM pattern — LM sees metadata, not raw content)
+            const contextLines = effectiveContext.split('\n');
+            const metadata = {
+                charCount: effectiveContext.length,
+                lineCount: contextLines.length,
+                messageCount: (effectiveContext.match(/\n\n\[(USER|ASSISTANT)\]:/g) || []).length,
+                ...(compactionResult.preCompacted && {
+                    originalCharCount: compactionResult.originalCharCount,
+                    preCompacted: true,
+                    preCompactionTier: compactionResult.preCompactionTier,
+                }),
+                preview: effectiveContext.slice(0, 500),
+                type: 'string',
+            };
+            // Inject context, metadata, empty history, and taskId into the TASK session's sandbox
+            const taskIdVar = `__taskId_${taskIdSafe}`;
+            agent.setSandboxVariableOnSession(taskSessionId, ctxVar, effectiveContext);
+            agent.setSandboxVariableOnSession(taskSessionId, histVar, { entries: [], totalProcessed: 0 });
+            agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
+            agent.setSandboxVariableOnSession(taskSessionId, taskIdVar, taskId);
+            // Prompt with curation helpers guidance (tools.curation.* replaces manual infrastructure code)
+            const prompt = [
+                `Curate using RLM approach.`,
+                `Context variable: ${ctxVar} (${metadata.charCount} chars, ${metadata.lineCount} lines, ${metadata.messageCount} messages)`,
+                `History variable: ${histVar}`,
+                `Metadata variable: ${metaVar}`,
+                `Task ID variable: ${taskIdVar} (pass as bare variable, not a string)`,
+                `IMPORTANT: Do NOT print raw context. Start with tools.curation.recon(${ctxVar}, ${metaVar}, ${histVar}) to assess.`,
+                `For chunked extraction use tools.curation.mapExtract(). Pass taskId: ${taskIdVar} (bare variable).`,
+                `IMPORTANT: Any code_exec call containing mapExtract MUST use timeout: 300000 on the code_exec tool call itself (not inside mapExtract options).`,
+                `Use tools.curation.groupBySubject() and tools.curation.dedup() to organize extractions.`,
+                `Verify via result.applied[].filePath — do NOT call readFile for verification.`,
+            ].join('\n');
             // Execute on the task session (isolated sandbox + history)
             // Task lifecycle is managed by Transport (task:started, task:completed, task:error)
             const response = await agent.executeOnSession(taskSessionId, prompt, {
@@ -76,6 +105,25 @@ export class CurateExecutor {
             });
             // Parse curation status from agent response for status tracking
             this.lastStatus = this.parseCurationStatus(taskId, response);
+            // --- Phase 4: Post-curation summary propagation (fail-open) ---
+            if (preState) {
+                try {
+                    const postState = await snapshotService.getCurrentState(baseDir);
+                    const changedPaths = diffStates(preState, postState);
+                    if (changedPaths.length > 0) {
+                        const summaryService = new FileContextTreeSummaryService();
+                        const results = await summaryService.propagateStaleness(changedPaths, agent, baseDir);
+                        // Opportunistic manifest rebuild (pre-warm for next query)
+                        if (results.some((r) => r.actionTaken)) {
+                            const manifestService = new FileContextTreeManifestService({ baseDirectory: baseDir });
+                            await manifestService.buildManifest(baseDir);
+                        }
+                    }
+                }
+                catch {
+                    // Fail-open: summary/manifest errors never block curation
+                }
+            }
             return response;
         }
         finally {

package/dist/server/infra/executor/folder-pack-executor.js

@@ -773,7 +773,7 @@ await tools.curate([{
             throw new Error(`Failed to write temp file: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Create per-task session for parallel isolation (own sandbox + history + LLM service)
-        const taskSessionId = await agent.createTaskSession(taskId, 'curate');
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
         // Step 3: Store full instructions as sandbox variable (lazy prompt loading).
         // This saves ~12-15K tokens by keeping the massive instruction set out of the prompt.
         // The LLM reads instructions on-demand via code_exec.

package/dist/server/infra/executor/pre-compaction/compaction-escalation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export from shared utilities.
+ * Original implementation moved to src/shared/utils/escalation-utils.ts
+ * to allow cross-layer reuse (both server/ and agent/ can import).
+ */
+export { buildDeterministicFallbackCompaction, type CompactionEscalationTier, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, withAggressiveCompactionDirective, } from '../../../../shared/utils/escalation-utils.js';

package/dist/server/infra/executor/pre-compaction/compaction-escalation.js

@@ -0,0 +1,6 @@
+/**
+ * Re-export from shared utilities.
+ * Original implementation moved to src/shared/utils/escalation-utils.ts
+ * to allow cross-layer reuse (both server/ and agent/ can import).
+ */
+export { buildDeterministicFallbackCompaction, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, withAggressiveCompactionDirective, } from '../../../../shared/utils/escalation-utils.js';

package/dist/server/infra/executor/pre-compaction/index.d.ts

@@ -0,0 +1,3 @@
+export type { CompactionEscalationTier } from './compaction-escalation.js';
+export { PRE_COMPACTION_CHAR_THRESHOLD, PreCompactionService } from './pre-compaction-service.js';
+export type { PreCompactionResult } from './pre-compaction-service.js';

package/dist/server/infra/executor/pre-compaction/index.js

@@ -0,0 +1 @@
+export { PRE_COMPACTION_CHAR_THRESHOLD, PreCompactionService } from './pre-compaction-service.js';

package/dist/server/infra/executor/pre-compaction/pre-compaction-service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pre-Compaction Service — Three-Level Escalation for curation context.
+ *
+ * Compacts large source context BEFORE the curation agent sees it,
+ * saving the agent from wasting iterations on chunking/extraction code.
+ *
+ * Fail-open: any error returns the original context unchanged.
+ */
+import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import { type CompactionEscalationTier } from './compaction-escalation.js';
+/**
+ * Character threshold below which compaction is skipped.
+ * Re-exported from shared constant for backwards compatibility.
+ */
+export declare const PRE_COMPACTION_CHAR_THRESHOLD = 20000;
+/**
+ * Result of a pre-compaction operation.
+ */
+export interface PreCompactionResult {
+    /** The (possibly compacted) context text */
+    context: string;
+    /** Original character count before compaction */
+    originalCharCount: number;
+    /** Whether compaction was actually applied */
+    preCompacted: boolean;
+    /** Which escalation tier succeeded (only set if preCompacted is true) */
+    preCompactionTier?: CompactionEscalationTier;
+}
+/**
+ * Service that pre-compacts curation context using three-level escalation.
+ *
+ * Level 1 (Normal): LLM compaction with standard prompt
+ * Level 2 (Aggressive): LLM compaction with aggressive prompt
+ * Level 3 (Fallback): Deterministic truncation (no LLM, always converges)
+ */
+export declare class PreCompactionService {
+    /**
+     * Compact context if it exceeds the character threshold.
+     *
+     * Fail-open: any error during compaction returns the original context.
+     * Deterministic fallback is only used when the LLM responded but with
+     * unacceptable output — never when the LLM itself errored.
+     * Manages its own session lifecycle (creates + deletes a task session).
+     *
+     * @param agent - The CipherAgent to use for LLM calls
+     * @param context - The source context to compact
+     * @param taskId - Parent task ID (compaction uses `${taskId}__compact`)
+     * @returns PreCompactionResult with the (possibly compacted) context
+     */
+    compact(agent: ICipherAgent, context: string, taskId: string): Promise<PreCompactionResult>;
+    /**
+     * Execute a single compaction pass via the agent.
+     *
+     * Returns a discriminated result so the caller can distinguish
+     * "LLM responded with bad output" from "LLM errored" — the former
+     * should escalate to the next tier, the latter should fail-open.
+     */
+    private executeCompactionPass;
+}

package/dist/server/infra/executor/pre-compaction/pre-compaction-service.js

@@ -0,0 +1,124 @@
+/**
+ * Pre-Compaction Service — Three-Level Escalation for curation context.
+ *
+ * Compacts large source context BEFORE the curation agent sees it,
+ * saving the agent from wasting iterations on chunking/extraction code.
+ *
+ * Fail-open: any error returns the original context unchanged.
+ */
+import { CURATION_CHAR_THRESHOLD } from '../../../../shared/constants/curation.js';
+import { buildDeterministicFallbackCompaction, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, } from './compaction-escalation.js';
+import { buildCompactionSystemPrompt, buildCompactionUserMessage } from './prompts.js';
+/**
+ * Character threshold below which compaction is skipped.
+ * Re-exported from shared constant for backwards compatibility.
+ */
+export const PRE_COMPACTION_CHAR_THRESHOLD = CURATION_CHAR_THRESHOLD;
+/**
+ * Service that pre-compacts curation context using three-level escalation.
+ *
+ * Level 1 (Normal): LLM compaction with standard prompt
+ * Level 2 (Aggressive): LLM compaction with aggressive prompt
+ * Level 3 (Fallback): Deterministic truncation (no LLM, always converges)
+ */
+export class PreCompactionService {
+    /**
+     * Compact context if it exceeds the character threshold.
+     *
+     * Fail-open: any error during compaction returns the original context.
+     * Deterministic fallback is only used when the LLM responded but with
+     * unacceptable output — never when the LLM itself errored.
+     * Manages its own session lifecycle (creates + deletes a task session).
+     *
+     * @param agent - The CipherAgent to use for LLM calls
+     * @param context - The source context to compact
+     * @param taskId - Parent task ID (compaction uses `${taskId}__compact`)
+     * @returns PreCompactionResult with the (possibly compacted) context
+     */
+    async compact(agent, context, taskId) {
+        const originalCharCount = context.length;
+        const failOpen = { context, originalCharCount, preCompacted: false };
+        if (originalCharCount <= PRE_COMPACTION_CHAR_THRESHOLD) {
+            return failOpen;
+        }
+        const inputTokens = estimateTokens(context);
+        const compactionTaskId = `${taskId}__compact`;
+        try {
+            const sessionId = await agent.createTaskSession(compactionTaskId, 'query');
+            try {
+                // --- Pass 1: Normal compaction ---
+                const normalPass = await this.executeCompactionPass({ agent, aggressive: false, context, sessionId, taskId: compactionTaskId });
+                if (normalPass.errored)
+                    return failOpen;
+                if (normalPass.output && shouldAcceptCompactionOutput(normalPass.output, inputTokens) && isCompactionOutputValid(normalPass.output)) {
+                    return {
+                        context: normalPass.output.trim(),
+                        originalCharCount,
+                        preCompacted: true,
+                        preCompactionTier: 'normal',
+                    };
+                }
+                // --- Pass 2: Aggressive compaction ---
+                const aggressivePass = await this.executeCompactionPass({ agent, aggressive: true, context, sessionId, taskId: compactionTaskId });
+                if (aggressivePass.errored)
+                    return failOpen;
+                if (aggressivePass.output && shouldAcceptCompactionOutput(aggressivePass.output, inputTokens) && isCompactionOutputValid(aggressivePass.output)) {
+                    return {
+                        context: aggressivePass.output.trim(),
+                        originalCharCount,
+                        preCompacted: true,
+                        preCompactionTier: 'aggressive',
+                    };
+                }
+                // --- Pass 3: Deterministic fallback ---
+                // Only reached when both passes got LLM responses but output was unacceptable
+                const fallbackResult = buildDeterministicFallbackCompaction({
+                    inputTokens,
+                    sourceText: context,
+                    suffixLabel: 'pre-curation compaction',
+                });
+                return {
+                    context: fallbackResult,
+                    originalCharCount,
+                    preCompacted: true,
+                    preCompactionTier: 'fallback',
+                };
+            }
+            finally {
+                await agent.deleteTaskSession(sessionId);
+            }
+        }
+        catch {
+            // Fail-open: return original context on ANY error
+            return failOpen;
+        }
+    }
+    /**
+     * Execute a single compaction pass via the agent.
+     *
+     * Returns a discriminated result so the caller can distinguish
+     * "LLM responded with bad output" from "LLM errored" — the former
+     * should escalate to the next tier, the latter should fail-open.
+     */
+    async executeCompactionPass(options) {
+        try {
+            const systemPrompt = buildCompactionSystemPrompt();
+            const userMessage = buildCompactionUserMessage(options.context, options.aggressive);
+            const prompt = `${systemPrompt}\n\n${userMessage}`;
+            const response = await options.agent.executeOnSession(options.sessionId, prompt, {
+                executionContext: {
+                    clearHistory: true,
+                    commandType: 'query',
+                    maxIterations: 1,
+                    maxTokens: 4096,
+                    temperature: 0.3,
+                },
+                taskId: options.taskId,
+            });
+            return { errored: false, output: response || undefined };
+        }
+        catch {
+            return { errored: true, output: undefined };
+        }
+    }
+}

package/dist/server/infra/executor/pre-compaction/prompts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compaction prompts for pre-curation context compaction.
+ *
+ * Self-contained prompts that steer the LLM away from query-mode policy
+ * (which would try to search the KB). The real guardrail against
+ * non-compaction responses is isCompactionOutputValid().
+ */
+/**
+ * Build the system prompt for compaction.
+ *
+ * Opens with a clear, self-contained instruction that overrides
+ * query-mode's "answers from KB only" rules. Note: prompt-level override
+ * is best-effort; isCompactionOutputValid() is the actual guardrail.
+ */
+export declare function buildCompactionSystemPrompt(): string;
+/**
+ * Build the user message for a compaction pass.
+ *
+ * Wraps the context in <source_content> tags for clear delimitation.
+ *
+ * @param context - The source text to compact
+ * @param aggressive - Whether this is the aggressive (pass 2) attempt
+ */
+export declare function buildCompactionUserMessage(context: string, aggressive: boolean): string;

package/dist/server/infra/executor/pre-compaction/prompts.js

@@ -0,0 +1,47 @@
+/**
+ * Compaction prompts for pre-curation context compaction.
+ *
+ * Self-contained prompts that steer the LLM away from query-mode policy
+ * (which would try to search the KB). The real guardrail against
+ * non-compaction responses is isCompactionOutputValid().
+ */
+/**
+ * Build the system prompt for compaction.
+ *
+ * Opens with a clear, self-contained instruction that overrides
+ * query-mode's "answers from KB only" rules. Note: prompt-level override
+ * is best-effort; isCompactionOutputValid() is the actual guardrail.
+ */
+export function buildCompactionSystemPrompt() {
+    return `You are a knowledge extraction pre-processor. Your ONLY task is to compact the provided text.
+
+## Rules
+- PRESERVE: facts, decisions, code examples, API signatures, diagrams (verbatim), tables (all rows), procedures, file paths, configurations, error patterns
+- REMOVE: conversational filler, repeated explanations, verbose tool call descriptions, meta-commentary, acknowledgments
+- Output clean structured markdown
+- Do NOT wrap output in code blocks or XML tags
+- Do NOT search any knowledge base
+- Do NOT answer questions about the content
+- Do NOT use any tools
+- Output ONLY the compacted text`;
+}
+/**
+ * Build the user message for a compaction pass.
+ *
+ * Wraps the context in <source_content> tags for clear delimitation.
+ *
+ * @param context - The source text to compact
+ * @param aggressive - Whether this is the aggressive (pass 2) attempt
+ */
+export function buildCompactionUserMessage(context, aggressive) {
+    const instruction = aggressive
+        ? 'Compact the following text MORE AGGRESSIVELY. A previous compaction attempt was not short enough. Remove all non-essential detail while keeping core facts, decisions, and code.'
+        : 'Compact the following text while preserving all knowledge-worthy information — facts, decisions, code, configurations, procedures.';
+    return `${instruction}
+
+<source_content>
+${context}
+</source_content>
+
+Output ONLY the compacted text. Do NOT use any tools.`;
+}

package/dist/server/infra/executor/query-executor.d.ts

@@ -7,6 +7,8 @@ import type { IQueryExecutor, QueryExecuteOptions } from '../../core/interfaces/
  * All fields are optional — without them, the executor falls back to the original behavior.
  */
 export interface QueryExecutorDeps {
+    /** Base directory for manifest service (e.g., project path) */
+    baseDirectory?: string;
     /** Enable query result caching (default: false) */
     enableCache?: boolean;
     /** File system for reading full document content and computing fingerprints */
@@ -35,6 +37,7 @@ export interface QueryExecutorDeps {
  */
 export declare class QueryExecutor implements IQueryExecutor {
     private static readonly FINGERPRINT_CACHE_TTL_MS;
+    private readonly baseDirectory?;
     private readonly cache?;
     private cachedFingerprint?;
     private readonly fileSystem?;

package/dist/server/infra/executor/query-executor.js

@@ -1,5 +1,7 @@
 import { join } from 'node:path';
 import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
+import { isDerivedArtifact } from '../context-tree/derived-artifact.js';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
 import { canRespondDirectly, formatDirectResponse, formatNotFoundResponse, } from './direct-search-responder.js';
 import { QueryResultCache } from './query-result-cache.js';
 /** Attribution footer appended to all query responses */
@@ -29,11 +31,13 @@ const SMART_ROUTING_MAX_DOCS = 5;
  */
 export class QueryExecutor {
     static FINGERPRINT_CACHE_TTL_MS = 30_000;
+    baseDirectory;
     cache;
     cachedFingerprint;
     fileSystem;
     searchService;
     constructor(deps) {
+        this.baseDirectory = deps?.baseDirectory;
         this.fileSystem = deps?.fileSystem;
         this.searchService = deps?.searchService;
         if (deps?.enableCache) {
@@ -97,6 +101,28 @@ export class QueryExecutor {
         if (searchResult && this.fileSystem) {
             prefetchedContext = this.buildPrefetchedContext(searchResult);
         }
+        // Lazy manifest rebuild: provides broad structural awareness for LLM
+        let manifestContext;
+        if (this.baseDirectory) {
+            try {
+                const manifestService = new FileContextTreeManifestService({ baseDirectory: this.baseDirectory });
+                let manifest = await manifestService.readManifestIfFresh(this.baseDirectory);
+                if (!manifest) {
+                    manifest = await manifestService.buildManifest(this.baseDirectory);
+                }
+                if (manifest) {
+                    const resolved = await manifestService.resolveForInjection(manifest, query, this.baseDirectory);
+                    if (resolved.length > 0) {
+                        manifestContext = resolved
+                            .map((e) => `[${e.type} ${e.path}]\n${e.content}`)
+                            .join('\n\n---\n\n');
+                    }
+                }
+            }
+            catch {
+                // Fail-open: proceed without manifest context
+            }
+        }
         // Create per-task session for parallel isolation (own sandbox + history + LLM service)
         const taskSessionId = await agent.createTaskSession(taskId, 'query');
         // Task-scoped variable names for sandbox injection (RLM pattern).
@@ -116,6 +142,7 @@ export class QueryExecutor {
         agent.setSandboxVariableOnSession(taskSessionId, resultsVar, searchResult?.results ?? []);
         agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
         const prompt = this.buildQueryPrompt(query, {
+            manifestContext,
             metadata,
             metaVar,
             prefetchedContext,
@@ -165,7 +192,7 @@ export class QueryExecutor {
      * @param options - Prompt options with variable names and metadata
      */
     buildQueryPrompt(query, options) {
-        const { metadata, metaVar, prefetchedContext, resultsVar } = options;
+        const { manifestContext, metadata, metaVar, prefetchedContext, resultsVar } = options;
         const groundingRules = `### Grounding Rules (CRITICAL)
 - ONLY use information from the curated knowledge base (.brv/context-tree/)
 - If no relevant knowledge is found, respond: "This topic is not covered in the knowledge base."
@@ -177,6 +204,9 @@ export class QueryExecutor {
 - **Details**: Key findings with explanations
 - **Sources**: File paths from .brv/context-tree/
 - **Gaps**: Note any aspects not covered`;
+        const manifestSection = manifestContext
+            ? `\n## Structural Context (from manifest)\nThe following provides broad structural awareness of the knowledge base:\n\n${manifestContext}\n`
+            : '';
         if (prefetchedContext) {
             return `## User Query
 ${query}
@@ -185,7 +215,7 @@ ${query}
 The following relevant knowledge was found in the context tree:
 
 ${prefetchedContext}
-
+${manifestSection}
 ## Search Results Variable
 Additional search results: \`${resultsVar}\` (${metadata.resultCount} results, top score: ${metadata.topScore.toFixed(2)})
 Metadata: \`${metaVar}\`
@@ -202,7 +232,7 @@ ${responseFormat}`;
         }
         return `## User Query
 ${query}
-
+${manifestSection}
 ## Search Results Variable
 Search results: \`${resultsVar}\` (${metadata.resultCount} results, top score: ${metadata.topScore.toFixed(2)})
 Metadata: \`${metaVar}\`
@@ -234,7 +264,12 @@ ${responseFormat}`;
                 maxResults: 10_000,
                 respectGitignore: false,
             });
-            const files = globResult.files.map((f) => ({
+            // Filter out non-searchable derived artifacts (_index.md, _manifest.json, .full.md).
+            // Stubs (.stub.md) are intentionally kept — archive/restore should invalidate cache.
+            // Summary-only churn does NOT invalidate cache (summaries are derivative content).
+            const files = globResult.files
+                .filter((f) => !isDerivedArtifact(f.path))
+                .map((f) => ({
                 mtime: f.modified?.getTime() ?? 0,
                 path: f.path,
             }));

package/dist/server/infra/http/authenticated-http-client.js

@@ -153,6 +153,10 @@ export class AuthenticatedHttpClient {
         if ('message' in responseData && typeof responseData.message === 'string') {
             return responseData.message;
         }
+        // Some endpoints return 'error' instead of 'message'
+        if ('error' in responseData && typeof responseData.error === 'string') {
+            return responseData.error;
+        }
         // Fallback to HTTP status error
         return `HTTP ${error.response.status}: ${error.response.statusText}`;
     }

package/dist/server/infra/http/provider-model-fetcher-registry.js

@@ -6,7 +6,7 @@
  */
 import { PROVIDER_REGISTRY } from '../../core/domain/entities/provider-registry.js';
 import { FileProviderConfigStore } from '../storage/file-provider-config-store.js';
-import { AnthropicModelFetcher, ChatBasedModelFetcher, GoogleModelFetcher, GoogleVertexModelFetcher, OpenAICompatibleModelFetcher, OpenAIModelFetcher, OpenRouterModelFetcher, } from './provider-model-fetchers.js';
+import { AnthropicModelFetcher, ChatBasedModelFetcher, GoogleModelFetcher, OpenAICompatibleModelFetcher, OpenAIModelFetcher, OpenRouterModelFetcher, } from './provider-model-fetchers.js';
 /**
  * Singleton instances of model fetchers, lazily created.
  */
@@ -63,10 +63,6 @@ export async function getModelFetcher(providerId) {
             fetcher = new GoogleModelFetcher();
             break;
         }
-        case 'google-vertex': {
-            fetcher = new GoogleVertexModelFetcher();
-            break;
-        }
         case 'minimax': {
             fetcher = new ChatBasedModelFetcher('https://api.minimax.io/v1', 'MiniMax', ['MiniMax-M2', 'MiniMax-M2-Stable']);
             break;

package/dist/server/infra/http/provider-model-fetchers.d.ts

@@ -50,20 +50,6 @@ export declare class GoogleModelFetcher implements IProviderModelFetcher {
         isValid: boolean;
     }>;
 }
-/**
- * Fetches models from Google Vertex AI using the @google/genai SDK with vertexai mode.
- * Uses Application Default Credentials (ADC) instead of API keys.
- */
-export declare class GoogleVertexModelFetcher implements IProviderModelFetcher {
-    private cache;
-    private readonly cacheTtlMs;
-    constructor(cacheTtlMs?: number);
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
-    validateApiKey(apiKey: string): Promise<{
-        error?: string;
-        isValid: boolean;
-    }>;
-}
 /**
  * Generic model fetcher for OpenAI-compatible APIs.
  * Works with xAI (Grok), Groq, and Mistral.