byterover-cli 3.1.0 → 3.3.0

package/dist/server/core/domain/transport/task-info.d.ts

@@ -18,4 +18,6 @@ export type TaskInfo = {
     projectPath?: string;
     taskId: string;
     type: TaskType;
+    /** Workspace root (linked subdir or projectRoot if unlinked) */
+    worktreeRoot?: string;
 };

package/dist/server/core/interfaces/client/i-client-manager.d.ts

@@ -114,4 +114,17 @@ export interface IClientManager {
      * @param clientId - The client's Socket.IO ID
      */
     unregister(clientId: string): void;
+    /**
+     * Update a client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     * Moves the client from the old project index to the new one,
+     * and fires onProjectEmpty if the old project has no remaining external clients.
+     *
+     * No-op if client is unknown.
+     *
+     * @param clientId - The client's Socket.IO ID
+     * @param newProjectPath - The new project path to associate
+     * @returns The previous project path (undefined if client not found or not previously associated)
+     */
+    updateProjectPath(clientId: string, newProjectPath: string): string | undefined;
 }

package/dist/server/core/interfaces/executor/i-curate-executor.d.ts

@@ -10,8 +10,12 @@ export interface CurateExecuteOptions {
     content: string;
     /** Optional file paths for --files flag */
     files?: string[];
+    /** Canonical project root where .brv/ lives (for post-processing: snapshot, summary, manifest) */
+    projectRoot?: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Workspace root — linked subdir or same as projectRoot for direct projects */
+    worktreeRoot?: string;
 }
 /**
  * ICurateExecutor - Executes curate tasks with an injected CipherAgent.

package/dist/server/core/interfaces/executor/i-folder-pack-executor.d.ts

@@ -4,14 +4,18 @@ import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-ag
  * Agent uses its default session (Single-Session pattern).
  */
 export interface FolderPackExecuteOptions {
-    /** Client's working directory for resolving relative paths */
+    /** Client's working directory for resolving relative paths (shell semantics) */
     clientCwd?: string;
     /** Optional context to guide the analysis */
     content?: string;
-    /** Folder path to pack (relative to clientCwd or absolute) */
-    folderPath: string;
+    /** Folder path to pack (relative to clientCwd or absolute). When absent, defaults to worktreeRoot. */
+    folderPath?: string;
+    /** Canonical project root where .brv/ lives (for temp file location) */
+    projectRoot?: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Workspace root — linked subdir or same as projectRoot. Used as default folderPath when none supplied. */
+    worktreeRoot?: string;
 }
 /**
  * IFolderPackExecutor - Executes folder pack + curate tasks with an injected CipherAgent.

package/dist/server/core/interfaces/executor/i-query-executor.d.ts

@@ -8,6 +8,8 @@ export interface QueryExecuteOptions {
     query: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Stable workspace root for scoping search and cache isolation */
+    worktreeRoot?: string;
 }
 /**
  * IQueryExecutor - Executes query tasks with an injected CipherAgent.

package/dist/server/core/interfaces/executor/i-search-executor.d.ts

@@ -0,0 +1,34 @@
+import type { SearchKnowledgeResult } from '../../../../agent/infra/sandbox/tools-sdk.js';
+/**
+ * Options for executing a context tree search.
+ * Search is stateless — no agent session, no LLM, no task isolation needed.
+ */
+export interface SearchExecuteOptions {
+    /** Maximum number of results to return (default: 10) */
+    limit?: number;
+    /** Search query */
+    query: string;
+    /** Path prefix to scope results (e.g. "auth/" for auth domain only) */
+    scope?: string;
+}
+/**
+ * ISearchExecutor - Executes search against the context tree's BM25 index.
+ *
+ * Unlike QueryExecutor (which requires a CipherAgent for LLM synthesis),
+ * SearchExecutor is stateless and returns raw search results directly.
+ * No agent session, no sandbox, no LLM call.
+ *
+ * Architecture:
+ * - SearchKnowledgeService provides BM25-indexed search
+ * - Executor wraps it with option validation
+ * - Results are SearchKnowledgeResult (paths, scores, excerpts)
+ */
+export interface ISearchExecutor {
+    /**
+     * Execute a context tree search.
+     *
+     * @param options - Search options (query, limit, scope)
+     * @returns Raw search results with paths, scores, and excerpts
+     */
+    execute(options: SearchExecuteOptions): Promise<SearchKnowledgeResult>;
+}

package/dist/server/core/interfaces/executor/i-search-executor.js

@@ -0,0 +1 @@
+export {};

package/dist/server/core/interfaces/executor/index.d.ts

@@ -1,3 +1,4 @@
 export * from './i-curate-executor.js';
 export * from './i-folder-pack-executor.js';
 export * from './i-query-executor.js';
+export * from './i-search-executor.js';

package/dist/server/core/interfaces/executor/index.js

@@ -1,3 +1,4 @@
 export * from './i-curate-executor.js';
 export * from './i-folder-pack-executor.js';
 export * from './i-query-executor.js';
+export * from './i-search-executor.js';

package/dist/server/infra/client/client-manager.d.ts

@@ -41,6 +41,7 @@ export declare class ClientManager implements IClientManager {
     register(clientId: string, type: ClientType, projectPath?: string): void;
     setAgentName(clientId: string, agentName: string): void;
     unregister(clientId: string): void;
+    updateProjectPath(clientId: string, newProjectPath: string): string | undefined;
     private addToProjectIndex;
     /**
      * Check if a project has no remaining external clients.

package/dist/server/infra/client/client-manager.js

@@ -111,6 +111,22 @@ export class ClientManager {
         // Notify idle timeout policy
         this.clientDisconnectedCallback?.();
     }
+    updateProjectPath(clientId, newProjectPath) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return undefined;
+        const oldPath = client.updateProjectPath(newProjectPath);
+        // Move between project indexes
+        if (oldPath) {
+            this.removeFromProjectIndex(clientId, oldPath);
+        }
+        this.addToProjectIndex(clientId, newProjectPath);
+        // Check if old project is now empty
+        if (oldPath && oldPath !== newProjectPath && client.isExternalClient) {
+            this.checkProjectEmpty(oldPath);
+        }
+        return oldPath;
+    }
     addToProjectIndex(clientId, projectPath) {
         let members = this.projectClients.get(projectPath);
         if (!members) {

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

@@ -28,13 +28,16 @@ import { FolderPackService } from '../../../agent/infra/folder-pack/folder-pack-
 import { SessionMetadataStore } from '../../../agent/infra/session/session-metadata-store.js';
 import { createSearchKnowledgeService } from '../../../agent/infra/tools/implementations/search-knowledge-service.js';
 import { AuthEvents } from '../../../shared/transport/events/auth-events.js';
+import { decodeSearchContent } from '../../../shared/transport/search-content.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';
 import { QueryExecutor } from '../executor/query-executor.js';
+import { SearchExecutor } from '../executor/search-executor.js';
 import { AgentInstanceDiscovery } from '../transport/agent-instance-discovery.js';
 import { createAgentLogger } from './agent-logger.js';
 import { resolveSessionId } from './session-resolver.js';
@@ -189,10 +192,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 +286,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
@@ -293,10 +303,11 @@ async function start() {
         fileSystem: fileSystemService,
         searchService,
     });
+    const searchExecutor = new SearchExecutor(searchService);
     transport.on(TransportTaskEventNames.EXECUTE, (task) => {
         agentLog(`task:execute received taskId=${task.taskId} type=${task.type} activeTaskCount=${activeTaskCount + 1}`);
         // eslint-disable-next-line no-void
-        void executeTask(task, curateExecutor, folderPackExecutor, queryExecutor);
+        void executeTask(task, curateExecutor, folderPackExecutor, queryExecutor, searchExecutor);
     });
     // 8. Register with transport server (for TransportHandlers tracking)
     await transport.requestWithAck('agent:register', { projectPath });
@@ -304,15 +315,19 @@ async function start() {
     process.send?.({ clientId, type: 'ready' });
     agentLog('Ready — listening for tasks');
 }
-async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor) {
-    const { clientCwd, clientId, content, files, folderPath, taskId, type } = task;
+async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor, searchExecutor) {
+    const { clientCwd, clientId, content, files, folderPath, taskId, type, worktreeRoot } = task;
     if (!transport || !agent)
         return;
-    const freshProviderConfig = await transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
-    const validationError = validateProviderForTask(freshProviderConfig);
-    if (validationError) {
-        transport.request(TransportTaskEventNames.ERROR, { clientId, error: validationError, taskId });
-        return;
+    // Search tasks are pure BM25 retrieval — no LLM, no provider needed.
+    // Skip provider validation so search works even without a configured provider.
+    if (type !== 'search') {
+        const freshProviderConfig = await transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
+        const validationError = validateProviderForTask(freshProviderConfig);
+        if (validationError) {
+            transport.request(TransportTaskEventNames.ERROR, { clientId, error: validationError, taskId });
+            return;
+        }
     }
     activeTaskCount++;
     try {
@@ -372,7 +387,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 +395,20 @@ 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;
+                }
+                case 'search': {
+                    const searchOptions = decodeSearchContent(content);
+                    const searchResult = await searchExecutor.execute(searchOptions);
+                    result = JSON.stringify(searchResult);
                     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 {

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

@@ -38,17 +38,28 @@ 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();
         }
-        // Resolve folder path
-        const basePath = clientCwd ?? process.cwd();
-        const absoluteFolderPath = path.isAbsolute(folderPath) ? folderPath : path.resolve(basePath, folderPath);
-        const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: basePath });
+        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(basePath);
+            preState = await snapshotService.getCurrentState(tempFileDir);
         }
         catch {
             // Fail-open: if snapshot fails, skip summary propagation
@@ -62,17 +73,17 @@ 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
-        const response = await 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(basePath);
+                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, basePath);
+                    const results = await summaryService.propagateStaleness(changedPaths, agent, tempFileDir);
                     if (results.some((result) => result.actionTaken)) {
-                        const manifestService = new FileContextTreeManifestService({ baseDirectory: basePath });
-                        await manifestService.buildManifest(basePath);
+                        const manifestService = new FileContextTreeManifestService({ baseDirectory: tempFileDir });
+                        await manifestService.buildManifest(tempFileDir);
                     }
                 }
             }

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.