byterover-cli 3.1.0 → 3.3.0

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

@@ -1,5 +1,6 @@
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { ABSTRACT_EXTENSION, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
+import { loadSources } from '../../core/domain/source/source-schema.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';
@@ -45,15 +46,16 @@ export class QueryExecutor {
         }
     }
     async executeWithAgent(agent, options) {
-        const { query, taskId } = options;
+        const { query, taskId, worktreeRoot } = options;
+        const workspaceScope = this.deriveWorkspaceScope(worktreeRoot);
         // Start search early — runs in parallel with fingerprint computation (independent operations)
-        const searchPromise = this.searchService?.search(query, { limit: SMART_ROUTING_MAX_DOCS });
+        const searchPromise = this.searchService?.search(query, { limit: SMART_ROUTING_MAX_DOCS, scope: workspaceScope });
         // Prevent unhandled rejection if we return early (cache hit) while search is still pending
         searchPromise?.catch(() => { });
         // === Tier 0: Exact cache hit (0ms) ===
         let fingerprint;
         if (this.cache && this.fileSystem) {
-            fingerprint = await this.computeContextTreeFingerprint();
+            fingerprint = await this.computeContextTreeFingerprint(worktreeRoot);
             const cached = this.cache.get(query, fingerprint);
             if (cached) {
                 return cached + ATTRIBUTION_FOOTER;
@@ -76,7 +78,7 @@ export class QueryExecutor {
         }
         // Supplementary entity-based searches for better multi-session recall
         if (this.searchService && searchResult && searchResult.totalFound < 3) {
-            searchResult = await this.supplementEntitySearches(query, searchResult);
+            searchResult = await this.supplementEntitySearches(query, searchResult, workspaceScope);
         }
         // === OOD short-circuit: no results means topic not covered ===
         if (searchResult && searchResult.results.length === 0) {
@@ -141,12 +143,18 @@ export class QueryExecutor {
         // Inject search results + metadata into the TASK session's sandbox
         agent.setSandboxVariableOnSession(taskSessionId, resultsVar, searchResult?.results ?? []);
         agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
+        // Inject workspace scope so agent follow-up searches are workspace-aware
+        const scopeVar = workspaceScope ? `__query_scope_${taskIdSafe}` : undefined;
+        if (scopeVar && workspaceScope) {
+            agent.setSandboxVariableOnSession(taskSessionId, scopeVar, workspaceScope);
+        }
         const prompt = this.buildQueryPrompt(query, {
             manifestContext,
             metadata,
             metaVar,
             prefetchedContext,
             resultsVar,
+            scopeVar,
         });
         // Query-optimized LLM overrides: tokens and lower temperature
         const queryOverrides = prefetchedContext
@@ -179,7 +187,12 @@ export class QueryExecutor {
         const highConfidenceResults = searchResult.results.filter((r) => r.score >= SMART_ROUTING_SCORE_THRESHOLD);
         if (highConfidenceResults.length === 0)
             return undefined;
-        const sections = highConfidenceResults.map((r) => `### ${r.title}\n**Source**: .brv/context-tree/${r.path}\n\n${r.excerpt}`);
+        const sections = highConfidenceResults.map((r) => {
+            const source = r.origin === 'shared' && r.originAlias
+                ? `[${r.originAlias}]:${r.path}`
+                : `.brv/context-tree/${r.path}`;
+            return `### ${r.title}\n**Source**: ${source}\n\n${r.excerpt}`;
+        });
         return sections.join('\n\n---\n\n');
     }
     /**
@@ -192,9 +205,9 @@ export class QueryExecutor {
      * @param options - Prompt options with variable names and metadata
      */
     buildQueryPrompt(query, options) {
-        const { manifestContext, metadata, metaVar, prefetchedContext, resultsVar } = options;
+        const { manifestContext, metadata, metaVar, prefetchedContext, resultsVar, scopeVar } = options;
         const groundingRules = `### Grounding Rules (CRITICAL)
-- ONLY use information from the curated knowledge base (.brv/context-tree/)
+- ONLY use information from the curated knowledge base (local .brv/context-tree/ plus any read-only shared sources)
 - If no relevant knowledge is found, respond: "This topic is not covered in the knowledge base."
 - Do NOT extrapolate, infer, or generate information beyond what is explicitly stated in sources
 - Every claim MUST be traceable to a specific source file
@@ -202,11 +215,15 @@ export class QueryExecutor {
         const responseFormat = `### Response Format
 - **Summary**: Direct answer (2-3 sentences)
 - **Details**: Key findings with explanations
-- **Sources**: File paths from .brv/context-tree/
+- **Sources**: Use .brv/context-tree/... for local knowledge and [alias]:path for shared sources
 - **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`
             : '';
+        // When workspace scope is active, instruct the agent to pass it to follow-up searches
+        const scopeGuidance = scopeVar
+            ? `\nFor any follow-up \`tools.searchKnowledge()\` calls, pass \`{ scope: ${scopeVar} }\` to scope results to the current workspace.`
+            : '';
         if (prefetchedContext) {
             return `## User Query
 ${query}
@@ -224,7 +241,7 @@ Metadata: \`${metaVar}\`
 
 Answer the user's question using the pre-fetched context above.
 If the pre-fetched context does not directly address the user's query topic, respond that the topic is not covered in the knowledge base. Do not attempt to answer from tangentially related content.
-If the context is insufficient but relevant, use \`code_exec\` with \`silent: true\` to read additional documents from the search results variable. Use \`setFinalResult(answer)\` when done.
+If the context is insufficient but relevant, use \`code_exec\` with \`silent: true\` to read additional documents from the search results variable. Use \`setFinalResult(answer)\` when done.${scopeGuidance}
 
 ${groundingRules}
 
@@ -240,7 +257,7 @@ Metadata: \`${metaVar}\`
 ## Instructions
 
 Use \`code_exec\` to examine the search results in \`${resultsVar}\`, read relevant documents with \`tools.readFile()\`, and synthesize an answer.
-Use \`silent: true\` for data-loading code_exec calls. Use \`setFinalResult(answer)\` to return the final answer immediately.
+Use \`silent: true\` for data-loading code_exec calls. Use \`setFinalResult(answer)\` to return the final answer immediately.${scopeGuidance}
 
 ${groundingRules}
 
@@ -250,10 +267,16 @@ ${responseFormat}`;
      * 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.
      */
-    async computeContextTreeFingerprint() {
+    async computeContextTreeFingerprint(worktreeRoot) {
         // Fast path: return cached fingerprint if still valid (avoids globFiles I/O)
-        if (this.cachedFingerprint && Date.now() < this.cachedFingerprint.expiresAt) {
+        // Invalidate if worktreeRoot changed or knowledge source validity changed
+        if (this.cachedFingerprint && Date.now() < this.cachedFingerprint.expiresAt
+            && this.cachedFingerprint.worktreeRoot === worktreeRoot
+            && this.cachedFingerprint.sourceValidityHash === this.computeSourceValidityHash()) {
             return this.cachedFingerprint.value;
         }
         try {
@@ -271,8 +294,36 @@ ${responseFormat}`;
                 .filter((f) => !isDerivedArtifact(f.path))
                 .map((f) => ({
                 mtime: f.modified?.getTime() ?? 0,
-                path: f.path,
+                path: worktreeRoot ? `${worktreeRoot}:${f.path}` : f.path,
             }));
+            // Include shared source state in fingerprint so edits in shared
+            // projects invalidate cached query answers.
+            const loaded = this.baseDirectory ? loadSources(this.baseDirectory) : null;
+            if (loaded) {
+                // sources-file mtime detects source additions/removals
+                if (loaded.mtime) {
+                    files.push({ mtime: loaded.mtime, path: '__sources.json__' });
+                }
+                // Glob each shared context tree for file-level change detection
+                const sharedResults = await Promise.all(loaded.origins.map(async (origin) => {
+                    try {
+                        const sharedGlob = await this.fileSystem.globFiles(`**/*${CONTEXT_FILE_EXTENSION}`, {
+                            cwd: origin.contextTreeRoot,
+                            includeMetadata: true,
+                            maxResults: 10_000,
+                            respectGitignore: false,
+                        });
+                        return sharedGlob.files
+                            .filter((f) => !isDerivedArtifact(f.path))
+                            .map((f) => ({ mtime: f.modified?.getTime() ?? 0, path: `shared:${origin.originKey}:${f.path}` }));
+                    }
+                    catch {
+                        // Broken source — skip
+                        return [];
+                    }
+                }));
+                files.push(...sharedResults.flat());
+            }
             // Include .abstract.md siblings so newly-written abstracts invalidate the cache.
             // They are excluded by isDerivedArtifact() above, so we append them separately.
             const abstractFiles = globResult.files
@@ -284,7 +335,9 @@ ${responseFormat}`;
             const fingerprint = QueryResultCache.computeFingerprint([...files, ...abstractFiles]);
             this.cachedFingerprint = {
                 expiresAt: Date.now() + QueryExecutor.FINGERPRINT_CACHE_TTL_MS,
+                sourceValidityHash: this.computeSourceValidityHash(),
                 value: fingerprint,
+                worktreeRoot,
             };
             return fingerprint;
         }
@@ -292,6 +345,40 @@ ${responseFormat}`;
             return 'unknown';
         }
     }
+    /**
+     * 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.
+     */
+    computeSourceValidityHash() {
+        if (!this.baseDirectory)
+            return '';
+        const loaded = loadSources(this.baseDirectory);
+        if (!loaded)
+            return 'no-sources';
+        return loaded.origins.map((o) => o.originKey).sort().join(',');
+    }
+    /**
+     * 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.
+     */
+    deriveWorkspaceScope(worktreeRoot) {
+        if (!worktreeRoot || !this.baseDirectory)
+            return undefined;
+        if (worktreeRoot === this.baseDirectory)
+            return undefined;
+        const rel = relative(this.baseDirectory, worktreeRoot);
+        return rel || undefined;
+    }
     /**
      * Extract key entities from a query for supplementary searches.
      * Simple heuristic: split query, filter stopwords, keep significant terms.
@@ -314,20 +401,21 @@ ${responseFormat}`;
      * @param searchResult - Initial search result to supplement
      * @returns Merged search result with additional entity-based matches
      */
-    async supplementEntitySearches(query, searchResult) {
+    async supplementEntitySearches(query, searchResult, scope) {
         const entities = this.extractQueryEntities(query);
         if (entities.length <= 1)
             return searchResult;
         try {
-            const entitySearches = await Promise.allSettled(entities.slice(0, 3).map((entity) => this.searchService.search(entity, { limit: 3 })));
+            const entitySearches = await Promise.allSettled(entities.slice(0, 3).map((entity) => this.searchService.search(entity, { limit: 3, scope })));
             // Collect existing paths to deduplicate
-            const existingPaths = new Set(searchResult.results.map((r) => r.path));
+            const existingPaths = new Set(searchResult.results.map((r) => `${r.originAlias ?? r.origin ?? 'local'}::${r.path}`));
             const supplementary = [];
             for (const settled of entitySearches) {
                 if (settled.status === 'fulfilled' && settled.value.results) {
                     for (const result of settled.value.results) {
-                        if (!existingPaths.has(result.path)) {
-                            existingPaths.add(result.path);
+                        const resultKey = `${result.originAlias ?? result.origin ?? 'local'}::${result.path}`;
+                        if (!existingPaths.has(resultKey)) {
+                            existingPaths.add(resultKey);
                             supplementary.push(result);
                         }
                     }
@@ -363,14 +451,20 @@ ${responseFormat}`;
                 .map(async (result) => {
                 let content = result.excerpt;
                 try {
-                    const ctPath = join(BRV_DIR, CONTEXT_TREE_DIR, result.path);
+                    // Use originContextTreeRoot for shared results, local context tree for local
+                    const ctBase = result.originContextTreeRoot ?? join(BRV_DIR, CONTEXT_TREE_DIR);
+                    const ctPath = join(ctBase, result.path);
                     const { content: fullContent } = await this.fileSystem.readFile(ctPath);
                     content = fullContent;
                 }
                 catch {
                     // Use excerpt if full read fails
                 }
-                return { content, path: result.path, score: result.score, title: result.title };
+                // Include source attribution in path for shared results
+                const displayPath = result.origin === 'shared' && result.originAlias
+                    ? `[${result.originAlias}]:${result.path}`
+                    : result.path;
+                return { content, path: displayPath, score: result.score, title: result.title };
             }));
             if (!canRespondDirectly(fullResults))
                 return undefined;

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

@@ -0,0 +1,17 @@
+/**
+ * SearchExecutor - Executes context tree searches via SearchKnowledgeService.
+ *
+ * Unlike QueryExecutor (Tier 0-4 with LLM synthesis), SearchExecutor is
+ * pure retrieval: BM25 index lookup → scored results. No LLM, no agent
+ * session, no sandbox, no token cost.
+ *
+ * This is the engine behind `brv search`. The CLI command and transport
+ * layer handle I/O; this module handles the search logic.
+ */
+import type { ISearchKnowledgeService, SearchKnowledgeResult } from '../../../agent/infra/sandbox/tools-sdk.js';
+import type { ISearchExecutor, SearchExecuteOptions } from '../../core/interfaces/executor/i-search-executor.js';
+export declare class SearchExecutor implements ISearchExecutor {
+    private readonly searchService;
+    constructor(searchService: ISearchKnowledgeService);
+    execute(options: SearchExecuteOptions): Promise<SearchKnowledgeResult>;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * SearchExecutor - Executes context tree searches via SearchKnowledgeService.
+ *
+ * Unlike QueryExecutor (Tier 0-4 with LLM synthesis), SearchExecutor is
+ * pure retrieval: BM25 index lookup → scored results. No LLM, no agent
+ * session, no sandbox, no token cost.
+ *
+ * This is the engine behind `brv search`. The CLI command and transport
+ * layer handle I/O; this module handles the search logic.
+ */
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+export class SearchExecutor {
+    searchService;
+    constructor(searchService) {
+        this.searchService = searchService;
+    }
+    async execute(options) {
+        const query = options.query.trim();
+        if (!query) {
+            return { message: 'Empty query', results: [], totalFound: 0 };
+        }
+        const scope = options.scope?.trim() || undefined;
+        const limit = Math.min(MAX_LIMIT, Math.max(1, Math.trunc(options.limit ?? DEFAULT_LIMIT)));
+        return this.searchService.search(query, {
+            limit,
+            ...(scope ? { scope } : {}),
+        });
+    }
+}

package/dist/server/infra/mcp/mcp-mode-detector.d.ts

@@ -8,14 +8,16 @@
  */
 export type McpMode = 'global' | 'project';
 export type McpModeResult = {
-    mode: McpMode;
-    projectRoot?: string;
+    mode: 'global';
+} | {
+    mode: 'project';
+    projectRoot: string;
+    worktreeRoot: string;
 };
 /**
  * Detects whether the MCP server is running in project or global mode.
  *
- * Walks up from workingDirectory looking for `.brv/config.json`.
- * If found, returns project mode with the discovered project root.
- * If the filesystem root is reached without finding it, returns global mode.
+ * Uses the canonical project resolver so MCP shares workspace-link semantics
+ * with the rest of the CLI.
  */
 export declare function detectMcpMode(workingDirectory: string): McpModeResult;

package/dist/server/infra/mcp/mcp-mode-detector.js

@@ -1,25 +1,18 @@
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { resolveProject } from '../project/resolve-project.js';
 /**
  * Detects whether the MCP server is running in project or global mode.
  *
- * Walks up from workingDirectory looking for `.brv/config.json`.
- * If found, returns project mode with the discovered project root.
- * If the filesystem root is reached without finding it, returns global mode.
+ * Uses the canonical project resolver so MCP shares workspace-link semantics
+ * with the rest of the CLI.
  */
 export function detectMcpMode(workingDirectory) {
-    let current = workingDirectory;
-    let parent = dirname(current);
-    while (current !== parent) {
-        if (existsSync(join(current, '.brv', 'config.json'))) {
-            return { mode: 'project', projectRoot: current };
-        }
-        current = parent;
-        parent = dirname(current);
+    const resolution = resolveProject({ cwd: workingDirectory });
+    if (!resolution) {
+        return { mode: 'global' };
     }
-    // Check the root directory itself
-    if (existsSync(join(current, '.brv', 'config.json'))) {
-        return { mode: 'project', projectRoot: current };
-    }
-    return { mode: 'global' };
+    return {
+        mode: 'project',
+        projectRoot: resolution.projectRoot,
+        worktreeRoot: resolution.worktreeRoot,
+    };
 }

package/dist/server/infra/mcp/mcp-server.d.ts

@@ -28,6 +28,7 @@ export declare class ByteRoverMcpServer {
     private reconnectorHandle;
     private readonly server;
     private transport;
+    private readonly worktreeRoot;
     constructor(config: McpServerConfig);
     /**
      * Starts the MCP server.

package/dist/server/infra/mcp/mcp-server.js

@@ -29,11 +29,13 @@ export class ByteRoverMcpServer {
     reconnectorHandle;
     server;
     transport;
+    worktreeRoot;
     constructor(config) {
         this.config = config;
-        const { mode, projectRoot } = detectMcpMode(config.workingDirectory);
-        this.mode = mode;
-        this.projectRoot = projectRoot;
+        const modeResult = detectMcpMode(config.workingDirectory);
+        this.mode = modeResult.mode;
+        this.projectRoot = modeResult.mode === 'project' ? modeResult.projectRoot : undefined;
+        this.worktreeRoot = modeResult.mode === 'project' ? modeResult.worktreeRoot : undefined;
         this.server = new McpServer({
             name: 'byterover',
             version: config.version,
@@ -45,10 +47,13 @@ export class ByteRoverMcpServer {
             version: config.version,
             ...(this.mode === 'project' && this.projectRoot ? { projectPath: this.projectRoot } : {}),
         };
+        const getStartupProjectContext = () => this.mode === 'project' && this.projectRoot && this.worktreeRoot
+            ? { projectRoot: this.projectRoot, worktreeRoot: this.worktreeRoot }
+            : undefined;
         // Register tools with lazy client getter
         // Client will be set when start() is called
-        registerBrvQueryTool(this.server, () => this.client, () => this.getWorkingDirectory());
-        registerBrvCurateTool(this.server, () => this.client, () => this.getWorkingDirectory());
+        registerBrvQueryTool(this.server, () => this.client, () => this.getWorkingDirectory(), getStartupProjectContext);
+        registerBrvCurateTool(this.server, () => this.client, () => this.getWorkingDirectory(), getStartupProjectContext);
     }
     /**
      * Starts the MCP server.
@@ -141,7 +146,7 @@ export class ByteRoverMcpServer {
      * In global mode, returns undefined — each tool call must provide cwd.
      */
     getWorkingDirectory() {
-        return this.mode === 'project' ? this.projectRoot : undefined;
+        return this.mode === 'project' ? this.worktreeRoot : undefined;
     }
     /**
      * Log to stderr (stdout is reserved for MCP protocol).

package/dist/server/infra/mcp/tools/brv-curate-tool.d.ts

@@ -1,6 +1,7 @@
 import type { ITransportClient } from '@campfirein/brv-transport-client';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { type McpStartupProjectContext } from './mcp-project-context.js';
 export declare const BrvCurateInputSchema: z.ZodObject<{
     context: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
@@ -26,4 +27,4 @@ export declare const BrvCurateInputSchema: z.ZodObject<{
  * Uses fire-and-forget pattern: returns immediately after queueing the task.
  * The curation is processed asynchronously by the ByteRover agent.
  */
-export declare function registerBrvCurateTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string | undefined): void;
+export declare function registerBrvCurateTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string | undefined, getStartupProjectContext: () => McpStartupProjectContext | undefined): void;

package/dist/server/infra/mcp/tools/brv-curate-tool.js

@@ -1,8 +1,8 @@
 import { waitForConnectedClient } from '@campfirein/brv-transport-client';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { TransportClientEventNames, TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
-import { detectMcpMode } from '../mcp-mode-detector.js';
+import { TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
+import { associateProjectWithRetry, resolveMcpTaskContext, } from './mcp-project-context.js';
 import { resolveClientCwd } from './resolve-client-cwd.js';
 export const BrvCurateInputSchema = z.object({
     context: z
@@ -34,7 +34,7 @@ export const BrvCurateInputSchema = z.object({
  * Uses fire-and-forget pattern: returns immediately after queueing the task.
  * The curation is processed asynchronously by the ByteRover agent.
  */
-export function registerBrvCurateTool(server, getClient, getWorkingDirectory) {
+export function registerBrvCurateTool(server, getClient, getWorkingDirectory, getStartupProjectContext) {
     server.registerTool('brv-curate', {
         description: 'Store context to the ByteRover context tree. Save patterns, decisions, or insights. ' +
             'Curation is processed asynchronously — the tool returns immediately after queueing.',
@@ -69,20 +69,11 @@ export function registerBrvCurateTool(server, getClient, getWorkingDirectory) {
                 isError: true,
             };
         }
-        // In global mode, associate client with the walked-up project root.
-        // Walk up from clientCwd to find .brv/config.json — raw cwd may be a subdirectory.
-        // Fire-and-forget: server handler is idempotent (first association wins).
-        if (!getWorkingDirectory()) {
-            const { projectRoot } = detectMcpMode(cwdResult.clientCwd);
-            if (projectRoot) {
-                client
-                    .requestWithAck(TransportClientEventNames.ASSOCIATE_PROJECT, {
-                    projectPath: projectRoot,
-                })
-                    .catch(() => { });
-            }
-        }
         try {
+            const taskContext = resolveMcpTaskContext(cwdResult.clientCwd, getStartupProjectContext());
+            if (!getWorkingDirectory()) {
+                await associateProjectWithRetry(client, taskContext.projectRoot);
+            }
             const taskId = randomUUID();
             // Create task via transport (same pattern as brv curate command)
             // Use provided context, or empty string for file-only/folder-only mode
@@ -93,8 +84,10 @@ export function registerBrvCurateTool(server, getClient, getWorkingDirectory) {
             const ack = await client.requestWithAck(TransportTaskEventNames.CREATE, {
                 clientCwd: cwdResult.clientCwd,
                 content: resolvedContent,
+                projectPath: taskContext.projectRoot,
                 taskId,
                 type: taskType,
+                worktreeRoot: taskContext.worktreeRoot,
                 ...(hasFolder && folder ? { folderPath: folder } : {}),
                 ...(!hasFolder && files?.length ? { files } : {}),
             });

package/dist/server/infra/mcp/tools/brv-query-tool.d.ts

@@ -1,6 +1,7 @@
 import type { ITransportClient } from '@campfirein/brv-transport-client';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { type McpStartupProjectContext } from './mcp-project-context.js';
 export declare const BrvQueryInputSchema: z.ZodObject<{
     cwd: z.ZodOptional<z.ZodString>;
     query: z.ZodString;
@@ -17,4 +18,4 @@ export declare const BrvQueryInputSchema: z.ZodObject<{
  * This tool allows coding agents to query the ByteRover context tree
  * for patterns, decisions, implementation details, or any stored knowledge.
  */
-export declare function registerBrvQueryTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string | undefined): void;
+export declare function registerBrvQueryTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string | undefined, getStartupProjectContext: () => McpStartupProjectContext | undefined): void;

package/dist/server/infra/mcp/tools/brv-query-tool.js

@@ -1,8 +1,8 @@
 import { waitForConnectedClient } from '@campfirein/brv-transport-client';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { TransportClientEventNames, TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
-import { detectMcpMode } from '../mcp-mode-detector.js';
+import { TransportTaskEventNames } from '../../../core/domain/transport/schemas.js';
+import { associateProjectWithRetry, resolveMcpTaskContext, } from './mcp-project-context.js';
 import { resolveClientCwd } from './resolve-client-cwd.js';
 import { waitForTaskResult } from './task-result-waiter.js';
 export const BrvQueryInputSchema = z.object({
@@ -20,7 +20,7 @@ export const BrvQueryInputSchema = z.object({
  * This tool allows coding agents to query the ByteRover context tree
  * for patterns, decisions, implementation details, or any stored knowledge.
  */
-export function registerBrvQueryTool(server, getClient, getWorkingDirectory) {
+export function registerBrvQueryTool(server, getClient, getWorkingDirectory, getStartupProjectContext) {
     server.registerTool('brv-query', {
         description: 'Query the ByteRover context tree for patterns, decisions, or implementation details.',
         inputSchema: BrvQueryInputSchema,
@@ -47,20 +47,11 @@ export function registerBrvQueryTool(server, getClient, getWorkingDirectory) {
                 isError: true,
             };
         }
-        // In global mode, associate client with the walked-up project root.
-        // Walk up from clientCwd to find .brv/config.json — raw cwd may be a subdirectory.
-        // Fire-and-forget: server handler is idempotent (first association wins).
-        if (!getWorkingDirectory()) {
-            const { projectRoot } = detectMcpMode(cwdResult.clientCwd);
-            if (projectRoot) {
-                client
-                    .requestWithAck(TransportClientEventNames.ASSOCIATE_PROJECT, {
-                    projectPath: projectRoot,
-                })
-                    .catch(() => { });
-            }
-        }
         try {
+            const taskContext = resolveMcpTaskContext(cwdResult.clientCwd, getStartupProjectContext());
+            if (!getWorkingDirectory()) {
+                await associateProjectWithRetry(client, taskContext.projectRoot);
+            }
             const taskId = randomUUID();
             // Register event listeners BEFORE sending task:create to avoid race conditions.
             // If the task completes before listeners are set up, the task:completed event is missed.
@@ -69,8 +60,10 @@ export function registerBrvQueryTool(server, getClient, getWorkingDirectory) {
             await client.requestWithAck(TransportTaskEventNames.CREATE, {
                 clientCwd: cwdResult.clientCwd,
                 content: query,
+                projectPath: taskContext.projectRoot,
                 taskId,
                 type: 'query',
+                worktreeRoot: taskContext.worktreeRoot,
             });
             // Wait for the already-listening result promise
             const result = await resultPromise;

package/dist/server/infra/mcp/tools/mcp-project-context.d.ts

@@ -0,0 +1,11 @@
+import type { ITransportClient } from '@campfirein/brv-transport-client';
+export type McpStartupProjectContext = {
+    projectRoot: string;
+    worktreeRoot: string;
+};
+export type ResolvedMcpTaskContext = {
+    projectRoot: string;
+    worktreeRoot: string;
+};
+export declare function associateProjectWithRetry(client: ITransportClient, projectPath: string): Promise<void>;
+export declare function resolveMcpTaskContext(clientCwd: string, startupProjectContext?: McpStartupProjectContext): ResolvedMcpTaskContext;

package/dist/server/infra/mcp/tools/mcp-project-context.js

@@ -0,0 +1,54 @@
+import { MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS, MCP_ASSOCIATE_PROJECT_TIMEOUT_MS } from '../../../constants.js';
+import { TransportClientEventNames } from '../../../core/domain/transport/schemas.js';
+import { resolveProject } from '../../project/resolve-project.js';
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function withTimeout(promise, timeoutMs, message) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+export async function associateProjectWithRetry(client, projectPath) {
+    let lastError;
+    /* eslint-disable no-await-in-loop -- intentional sequential retry loop */
+    for (let attempt = 1; attempt <= MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS; attempt++) {
+        try {
+            await withTimeout(client.requestWithAck(TransportClientEventNames.ASSOCIATE_PROJECT, { projectPath }), MCP_ASSOCIATE_PROJECT_TIMEOUT_MS, `Timed out waiting for project association ack after ${MCP_ASSOCIATE_PROJECT_TIMEOUT_MS}ms`);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    throw new Error(`Failed to associate MCP client with project "${projectPath}": ${describeError(lastError)}. ` +
+        `Retry the tool call or run 'brv restart' if the daemon is unresponsive.`);
+}
+export function resolveMcpTaskContext(clientCwd, startupProjectContext) {
+    const resolution = resolveProject({ cwd: clientCwd });
+    if (resolution) {
+        return projectResolutionToTaskContext(resolution);
+    }
+    if (startupProjectContext && clientCwd === startupProjectContext.worktreeRoot) {
+        return startupProjectContext;
+    }
+    throw new Error(`No ByteRover project could be resolved from cwd "${clientCwd}".`);
+}
+function projectResolutionToTaskContext(resolution) {
+    return {
+        projectRoot: resolution.projectRoot,
+        worktreeRoot: resolution.worktreeRoot,
+    };
+}