byterover-cli 3.0.1 → 3.2.0

package/dist/server/infra/context-tree/file-context-tree-manifest-service.js

@@ -15,7 +15,7 @@
  */
 import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE, } from '../../constants.js';
+import { ABSTRACT_EXTENSION, ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE, } from '../../constants.js';
 import { parseFrontmatterScoring } from '../../core/domain/knowledge/markdown-writer.js';
 import { DEFAULT_LANE_BUDGETS } from '../../core/domain/knowledge/summary-types.js';
 import { estimateTokens } from '../executor/pre-compaction/compaction-escalation.js';
@@ -98,8 +98,23 @@ export class FileContextTreeManifestService {
         /* eslint-disable no-await-in-loop */
         for (const entry of ordered) {
             try {
-                const fullPath = join(contextTreeDir, entry.path);
-                const content = await readFile(fullPath, 'utf8');
+                let content;
+                // For context entries, prefer .abstract.md sibling if it exists on disk
+                // (dynamic read avoids stale-manifest issues since .abstract.md is a derived artifact)
+                if (entry.type === 'context') {
+                    const abstractRelPath = entry.path.replace(/\.md$/, ABSTRACT_EXTENSION);
+                    const abstractFullPath = join(contextTreeDir, abstractRelPath);
+                    try {
+                        content = await readFile(abstractFullPath, 'utf8');
+                    }
+                    catch {
+                        // Abstract not ready yet — fall back to full content
+                        content = await readFile(join(contextTreeDir, entry.path), 'utf8');
+                    }
+                }
+                else {
+                    content = await readFile(join(contextTreeDir, entry.path), 'utf8');
+                }
                 resolved.push({
                     content,
                     path: entry.path,
@@ -188,6 +203,12 @@ export class FileContextTreeManifestService {
         catch {
             return;
         }
+        // Build a set of abstract sibling paths present in this directory so we can
+        // check existence without throwing ENOENT for every context file that has
+        // no abstract yet (the common case early in a project's lifetime).
+        const abstractsInDir = new Set(entries
+            .filter((e) => e.isFile() && e.name.endsWith(ABSTRACT_EXTENSION))
+            .map((e) => join(currentDir, e.name)));
         /* eslint-disable no-await-in-loop */
         for (const entry of entries) {
             const entryName = entry.name;
@@ -221,10 +242,24 @@ export class FileContextTreeManifestService {
                     try {
                         const content = await readFile(fullPath, 'utf8');
                         const scoring = parseFrontmatterScoring(content);
+                        // Use abstract sibling for token budgeting only if it is known to exist
+                        // (checked via abstractsInDir set, avoiding ENOENT as control flow).
+                        const abstractRelPath = relativePath.replace(/\.md$/, ABSTRACT_EXTENSION);
+                        const abstractFullPath = join(contextTreeDir, abstractRelPath);
+                        let abstractTokens;
+                        if (abstractsInDir.has(abstractFullPath)) {
+                            try {
+                                const abstractContent = await readFile(abstractFullPath, 'utf8');
+                                abstractTokens = estimateTokens(abstractContent);
+                            }
+                            catch { /* unreadable — treat as absent */ }
+                        }
                         contexts.push({
+                            abstractPath: abstractTokens === undefined ? undefined : abstractRelPath,
+                            abstractTokens,
                             importance: scoring?.importance ?? 50,
                             path: relativePath,
-                            tokens: estimateTokens(content),
+                            tokens: abstractTokens ?? estimateTokens(content),
                             type: 'context',
                         });
                     }
@@ -238,7 +273,8 @@ export class FileContextTreeManifestService {
     }
     /**
      * Recursively collect stat data for all source files (for fingerprint).
-     * Excludes derived artifacts.
+     * Excludes derived artifacts except .abstract.md siblings, which are included
+     * so abstract generation invalidates the manifest without a second tree walk.
      */
     async scanSourceStats(currentDir, contextTreeDir, entries) {
         let dirEntries;
@@ -257,8 +293,8 @@ export class FileContextTreeManifestService {
             }
             else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
                 const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
-                // Include all non-derived files (contexts + stubs) in fingerprint
-                if (isDerivedArtifact(relativePath))
+                const isAbstractSibling = entryName.endsWith(ABSTRACT_EXTENSION);
+                if (!isAbstractSibling && isDerivedArtifact(relativePath))
                     continue;
                 try {
                     const fileStat = await stat(fullPath);

package/dist/server/infra/context-tree/file-context-tree-summary-service.js

@@ -74,7 +74,18 @@ export class FileContextTreeSummaryService {
             // Step 5: Three-tier escalation via CipherAgent
             const taskId = `summary_${directoryPath.replaceAll('/', '_') || 'root'}`;
             const childEntries = children.map((c) => ({ content: c.content, name: c.name }));
-            const summaryText = await this.generateWithEscalation(agent, taskId, childEntries, level, totalInputTokens);
+            let summaryText;
+            try {
+                summaryText = await this.generateWithEscalation(agent, taskId, childEntries, level, totalInputTokens);
+            }
+            catch {
+                const combinedInput = childEntries.map((entry) => `## ${entry.name}\n${entry.content}`).join('\n\n');
+                summaryText = buildDeterministicFallbackCompaction({
+                    inputTokens: totalInputTokens,
+                    sourceText: combinedInput,
+                    suffixLabel: 'summary compaction',
+                });
+            }
             // Step 6: Write _index.md
             const summaryTokens = estimateTokens(summaryText);
             const frontmatter = {
@@ -289,7 +300,14 @@ export class FileContextTreeSummaryService {
             });
         }
         finally {
-            await agent.deleteTaskSession(sessionId);
+            try {
+                // Cleanup is best-effort. A generated summary should still be written even
+                // if the backing task session cannot be torn down cleanly.
+                await agent.deleteTaskSession(sessionId);
+            }
+            catch {
+                // Ignore cleanup failures
+            }
         }
     }
     /**

package/dist/server/infra/daemon/agent-process.js

@@ -31,6 +31,7 @@ import { AuthEvents } from '../../../shared/transport/events/auth-events.js';
 import { getCurrentConfig } from '../../config/environment.js';
 import { DEFAULT_LLM_MODEL, PROJECT } from '../../constants.js';
 import { serializeTaskError, TaskError, TaskErrorCode } from '../../core/domain/errors/task-error.js';
+import { loadSources } from '../../core/domain/source/source-schema.js';
 import { TransportAgentEventNames, TransportDaemonEventNames, TransportStateEventNames, TransportTaskEventNames, } from '../../core/domain/transport/schemas.js';
 import { CurateExecutor } from '../executor/curate-executor.js';
 import { FolderPackExecutor } from '../executor/folder-pack-executor.js';
@@ -189,10 +190,14 @@ async function start() {
     cachedProviderHeaders = providerResult.providerHeaders ? JSON.stringify(providerResult.providerHeaders) : undefined;
     agentLog(`Provider: ${activeProvider}, Model: ${activeModel ?? 'default'}`);
     // 5. Create CipherAgent with lazy providers + transport client
+    // Load knowledge sources early so shared context tree roots can be shared with both
+    // the agent's FileSystemService (via config) and the executor's FileSystemService
+    const sourcesData = loadSources(projectPath);
+    const sharedAllowedPaths = (sourcesData?.origins ?? []).map((o) => o.contextTreeRoot);
     const envConfig = getCurrentConfig();
     const agentConfig = {
         apiBaseUrl: envConfig.llmApiBaseUrl,
-        fileSystem: { workingDirectory: projectPath },
+        fileSystem: { allowedPaths: ['.', ...sharedAllowedPaths], workingDirectory: projectPath },
         llm: {
             maxIterations: 10,
             maxTokens: 4096,
@@ -279,7 +284,10 @@ async function start() {
         }
     });
     // 6. Create FileSystemService + SearchKnowledgeService for smart query routing
-    const fileSystemService = new FileSystemService({ workingDirectory: projectPath });
+    const fileSystemService = new FileSystemService({
+        allowedPaths: ['.', ...sharedAllowedPaths],
+        workingDirectory: projectPath,
+    });
     await fileSystemService.initialize();
     const searchService = createSearchKnowledgeService(fileSystemService, { baseDirectory: projectPath });
     // 7. Create executors and listen for task:execute from pool
@@ -305,7 +313,7 @@ async function start() {
     agentLog('Ready — listening for tasks');
 }
 async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor) {
-    const { clientCwd, clientId, content, files, folderPath, taskId, type } = task;
+    const { clientCwd, clientId, content, files, folderPath, taskId, type, worktreeRoot } = task;
     if (!transport || !agent)
         return;
     const freshProviderConfig = await transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
@@ -372,7 +380,7 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
             let result;
             switch (type) {
                 case 'curate': {
-                    result = await curateExecutor.executeWithAgent(agent, { clientCwd, content, files, taskId });
+                    result = await curateExecutor.executeWithAgent(agent, { clientCwd, content, files, projectRoot: projectPath, taskId, worktreeRoot });
                     break;
                 }
                 case 'curate-folder': {
@@ -380,12 +388,14 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                         clientCwd,
                         content,
                         folderPath: folderPath,
+                        projectRoot: projectPath,
                         taskId,
+                        worktreeRoot,
                     });
                     break;
                 }
                 case 'query': {
-                    result = await queryExecutor.executeWithAgent(agent, { query: content, taskId });
+                    result = await queryExecutor.executeWithAgent(agent, { query: content, taskId, worktreeRoot });
                     break;
                 }
             }

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

@@ -36,7 +36,7 @@ export class CurateExecutor {
         this.fileContentReader = fileContentReader ?? createFileContentReader();
     }
     async executeWithAgent(agent, options) {
-        const { clientCwd, content, files, taskId } = options;
+        const { clientCwd, content, files, projectRoot, taskId } = options;
         // --- Phase 1: Preprocessing (no sessions created yet — safe to throw) ---
         const fileReferenceInstructions = await this.processFileReferences(files ?? [], clientCwd);
         const fullContext = fileReferenceInstructions ? `${content}\n${fileReferenceInstructions}` : content;
@@ -45,7 +45,9 @@ export class CurateExecutor {
         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();
+        // Post-processing (snapshot, summary, manifest) operates on projectRoot where .brv/ lives.
+        // worktreeRoot is a linked subdir — .brv/ does not exist there in linked setups.
+        const baseDir = projectRoot ?? clientCwd ?? process.cwd();
         const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: baseDir });
         let preState;
         try {
@@ -54,7 +56,7 @@ export class CurateExecutor {
         catch {
             // Fail-open: if snapshot fails, skip summary propagation
         }
-        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true, userFacing: true });
         try {
             // Task-scoped variable names for RLM pattern.
             // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
@@ -124,6 +126,7 @@ export class CurateExecutor {
                     // Fail-open: summary/manifest errors never block curation
                 }
             }
+            await agent.drainBackgroundWork?.();
             return response;
         }
         finally {

package/dist/server/infra/executor/direct-search-responder.js

@@ -58,7 +58,11 @@ export function formatDirectResponse(query, results) {
         return `### ${r.title}\n\n${truncatedContent}`;
     })
         .join('\n\n---\n\n');
-    const sources = topResults.map((r) => `- \`.brv/context-tree/${r.path}\``).join('\n');
+    const sources = topResults.map((r) => {
+        // Paths starting with [ are already namespaced (linked results)
+        const displayPath = r.path.startsWith('[') ? r.path : `.brv/context-tree/${r.path}`;
+        return `- \`${displayPath}\``;
+    }).join('\n');
     return `**Summary**: ${summary}
 
 **Details**:

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

@@ -1,6 +1,10 @@
 import { appendFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+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';
 const LOG_PATH = process.env.BRV_SESSION_LOG;
 function folderPackLog(message) {
     if (!LOG_PATH)
@@ -34,13 +38,32 @@ export class FolderPackExecutor {
         this.folderPackService = folderPackService;
     }
     async executeWithAgent(agent, options) {
-        const { clientCwd, content, folderPath, taskId } = options;
+        const { clientCwd, content, folderPath, projectRoot, taskId, worktreeRoot } = options;
+        // Resolve folder path:
+        // - Absent folderPath → default to worktreeRoot (implicit workspace default)
+        // - Relative folderPath → resolve from clientCwd (shell semantics)
+        // - Absolute folderPath → use as-is
+        let absoluteFolderPath;
         if (!folderPath) {
-            throw new Error('folderPath is required for curate-folder tasks');
+            absoluteFolderPath = worktreeRoot ?? clientCwd ?? process.cwd();
+        }
+        else if (path.isAbsolute(folderPath)) {
+            absoluteFolderPath = folderPath;
+        }
+        else {
+            const shellCwd = clientCwd ?? process.cwd();
+            absoluteFolderPath = path.resolve(shellCwd, folderPath);
+        }
+        // Temp file location: use projectRoot where .brv/ lives (accessible to sandbox)
+        const tempFileDir = projectRoot ?? clientCwd ?? process.cwd();
+        const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: tempFileDir });
+        let preState;
+        try {
+            preState = await snapshotService.getCurrentState(tempFileDir);
+        }
+        catch {
+            // Fail-open: if snapshot fails, skip summary propagation
         }
-        // Resolve folder path
-        const basePath = clientCwd ?? process.cwd();
-        const absoluteFolderPath = path.isAbsolute(folderPath) ? folderPath : path.resolve(basePath, folderPath);
         // Pack the folder
         const packResult = await this.folderPackService.pack(absoluteFolderPath, {
             extractDocuments: true,
@@ -50,7 +73,26 @@ export class FolderPackExecutor {
         // Use iterative extraction strategy (inspired by rlm)
         // Stores packed folder in sandbox environment and lets agent iteratively query/extract
         // This avoids token limits entirely - works for folders of any size
-        return this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId, basePath);
+        const response = await this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId, tempFileDir);
+        if (preState) {
+            try {
+                const postState = await snapshotService.getCurrentState(tempFileDir);
+                const changedPaths = diffStates(preState, postState);
+                if (changedPaths.length > 0) {
+                    const summaryService = new FileContextTreeSummaryService();
+                    const results = await summaryService.propagateStaleness(changedPaths, agent, tempFileDir);
+                    if (results.some((result) => result.actionTaken)) {
+                        const manifestService = new FileContextTreeManifestService({ baseDirectory: tempFileDir });
+                        await manifestService.buildManifest(tempFileDir);
+                    }
+                }
+            }
+            catch {
+                // Fail-open: summary/manifest errors never block curation
+            }
+        }
+        await agent.drainBackgroundWork?.();
+        return response;
     }
     /**
      * Build iterative extraction prompt with file-based access.
@@ -133,6 +175,15 @@ Use **code_exec with tools.readFile/tools.grep** to extract knowledge:
 
 **Important**: All tools.* methods are async - always use \`await\`!
 
+## Curate Shape Constraints
+
+- Prefer one concrete knowledge entry per relevant source file when curating a small leaf folder.
+- For folders with 3 or fewer relevant source files, keep the number of curated leaf entries at or below the number of curated source files by default.
+- Do **NOT** create an extra module/folder "overview" leaf at the bare topic path just because the folder has multiple files.
+- Treat bare topic paths as scopes for \`topicContext\`, not as default destinations for standalone knowledge files.
+- If you need topic-level framing, provide \`topicContext\` on the operation that creates the topic. The system will create/update \`context.md\` and higher-level summaries separately.
+- Only add a standalone overview leaf when the user explicitly asks for it or when there is a distinct cross-file concept that cannot be represented by the per-file entries.
+
 ## Common Mistakes to Avoid
 
 **❌ WRONG - Using require() inside code_exec:**
@@ -773,7 +824,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', { mapRootEligible: true });
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true, userFacing: 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.
@@ -783,15 +834,45 @@ await tools.curate([{
         const taskIdSafe = taskId.replaceAll('-', '_');
         const instructionsVar = `__curate_instructions_${taskIdSafe}`;
         agent.setSandboxVariableOnSession(taskSessionId, instructionsVar, fullInstructions);
+        const smallFolderFilesVar = `__curate_files_${taskIdSafe}`;
+        const shouldExposePackedFiles = packResult.files.length > 0 && packResult.files.length <= 10 && packResult.totalCharacters <= 80_000;
+        if (shouldExposePackedFiles) {
+            agent.setSandboxVariableOnSession(taskSessionId, smallFolderFilesVar, packResult.files.map((file) => ({
+                content: file.content,
+                fileType: file.fileType,
+                lineCount: file.lineCount,
+                path: file.path,
+                size: file.size,
+                truncated: file.truncated,
+            })));
+        }
         // Compact prompt with variable reference and essential metadata
         const contextSection = userContext?.trim() ? `\nUser context: ${userContext}\n` : '';
+        const sourceFilePaths = packResult.files.map((file) => file.path);
+        const sourceFilesSection = sourceFilePaths.length > 0
+            ? `Relevant source files: ${sourceFilePaths.join(', ')} (these paths are relative to the packed folder root; do not prefix them with parent directories like src/auth/)`
+            : undefined;
+        const smallFolderLeafQuota = sourceFilePaths.length > 0 && sourceFilePaths.length <= 3
+            ? `Leaf quota: create no more than ${sourceFilePaths.length} curated leaf knowledge files for this folder unless the user explicitly asks for more.`
+            : undefined;
+        const smallFolderQuotaWarning = sourceFilePaths.length > 0 && sourceFilePaths.length <= 3
+            ? `A topic-level overview leaf counts toward that quota and is usually incorrect here; keep folder-level framing in topicContext instead.`
+            : undefined;
         const compactPrompt = [
             `# Folder Curation Task`,
             ``,
             `Folder: ${folderPath} (${packResult.fileCount} files, ${packResult.totalLines} lines)`,
             `Data file: \`${tmpFilePath}\` (repomix-style XML format)`,
             `Full instructions: variable \`${instructionsVar}\``,
+            shouldExposePackedFiles
+                ? `Relevant files variable: \`${smallFolderFilesVar}\` (array of packed files; for this small folder, prefer using it directly instead of parsing XML with brittle regexes).`
+                : undefined,
             contextSection,
+            sourceFilesSection,
+            `Small-folder rule: for folders with 3 or fewer relevant source files, create at most one leaf knowledge entry per file by default.`,
+            smallFolderLeafQuota,
+            smallFolderQuotaWarning,
+            `Do not create an extra overview leaf at the bare topic path; use topicContext for topic-level framing instead.`,
             `**Start by reading instructions**: Use code_exec to read \`${instructionsVar}.slice(0, 5000)\` for the strategy section, then \`${instructionsVar}.slice(5000, 10000)\` for content rules.`,
             `Use \`tools.readFile()\` and \`tools.grep()\` inside code_exec to process the XML data file.`,
             `Use \`tools.curate()\` to create knowledge topics. Use \`setFinalResult()\` when done.`,

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

@@ -64,8 +64,31 @@ export declare class QueryExecutor implements IQueryExecutor {
      * Compute a context tree fingerprint cheaply using file mtimes.
      * Used for cache invalidation — if any file in the context tree changes,
      * the fingerprint changes and cached results are invalidated.
+     *
+     * Includes worktreeRoot in the hash so different workspaces produce
+     * different fingerprints, preventing cross-workspace cache bleed.
      */
     private computeContextTreeFingerprint;
+    /**
+     * Lightweight hash of currently valid shared source keys.
+     * Used by the fingerprint cache fast path to detect when a source target
+     * becomes broken (directory deleted) within the TTL window.
+     * Cost: one readFileSync + existsSync per source — sub-millisecond for typical setups.
+     */
+    private computeSourceValidityHash;
+    /**
+     * Derive a workspace scope for search from the worktreeRoot.
+     * Returns the relative path from projectRoot to worktreeRoot,
+     * or undefined if they are the same (no scoping needed).
+     *
+     * KNOWN LIMITATION: Workspace scoping only works if the curated context
+     * tree has a subtree matching the workspace relative path (e.g., 'packages/api').
+     * Since the context tree is organized semantically by the LLM (topic-based),
+     * not by directory structure, scope filtering typically has 0 matches and
+     * falls through to unscoped search. A proper fix requires tagging curated
+     * files with source workspace metadata during curation.
+     */
+    private deriveWorkspaceScope;
     /**
      * Extract key entities from a query for supplementary searches.
      * Simple heuristic: split query, filter stopwords, keep significant terms.