byterover-cli 3.1.0 → 3.2.0

package/dist/server/core/domain/source/source-schema.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { BRV_DIR, CONTEXT_TREE_DIR, PROJECT_CONFIG_FILE, SOURCES_FILE } from '../../../constants.js';
+// ============================================================================
+// Schema
+// ============================================================================
+export const SourceSchema = z.object({
+    addedAt: z.string(),
+    alias: z.string().min(1),
+    projectRoot: z.string().min(1),
+    readOnly: z.literal(true),
+});
+export const SourcesFileSchema = z.object({
+    sources: z.array(SourceSchema),
+    version: z.literal(1),
+});
+/**
+ * Derives a stable, short origin key from a canonical path.
+ * Uses first 12 hex chars of SHA-256 to avoid alias-based collisions.
+ */
+export function deriveOriginKey(canonicalPath) {
+    return createHash('sha256').update(canonicalPath).digest('hex').slice(0, 12);
+}
+/**
+ * Loads and validates `.brv/sources.json` from a project root.
+ *
+ * Returns null if the file does not exist.
+ * Broken sources (target `.brv/` missing) are included in `sources` but excluded
+ * from `origins` — callers decide how to surface them (status vs search).
+ */
+export function loadSources(projectRoot) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    const mtime = statSync(filePath).mtimeMs;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return { mtime, origins: [], sources: [] };
+    }
+    const result = SourcesFileSchema.safeParse(raw);
+    if (!result.success) {
+        return { mtime, origins: [], sources: [] };
+    }
+    const origins = [];
+    for (const source of result.data.sources) {
+        const targetConfigPath = join(source.projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+        if (!existsSync(targetConfigPath)) {
+            // Broken source — skip from origins but keep in sources for status display
+            continue;
+        }
+        let canonicalRoot;
+        try {
+            canonicalRoot = realpathSync(source.projectRoot);
+        }
+        catch {
+            continue;
+        }
+        const contextTreeRoot = join(canonicalRoot, BRV_DIR, CONTEXT_TREE_DIR);
+        if (!existsSync(contextTreeRoot)) {
+            continue;
+        }
+        origins.push({
+            alias: source.alias,
+            contextTreeRoot,
+            origin: 'shared',
+            originKey: deriveOriginKey(canonicalRoot),
+        });
+    }
+    return { mtime, origins, sources: result.data.sources };
+}
+/**
+ * Validates each source and returns status for display.
+ *
+ * A source is valid only when both `.brv/config.json` AND `.brv/context-tree/`
+ * exist — matching what loadSources() requires before including a source in
+ * search origins. When valid, `contextTreeSize` counts `.md` files.
+ */
+export function getSourceStatuses(sources) {
+    return sources.map((source) => {
+        const targetConfigPath = join(source.projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+        const targetContextTree = join(source.projectRoot, BRV_DIR, CONTEXT_TREE_DIR);
+        const valid = existsSync(targetConfigPath) && existsSync(targetContextTree);
+        let contextTreeSize;
+        if (valid) {
+            contextTreeSize = countMarkdownFiles(targetContextTree);
+        }
+        return {
+            alias: source.alias,
+            contextTreeSize,
+            projectRoot: source.projectRoot,
+            valid,
+        };
+    });
+}
+/**
+ * Recursively counts .md files in a directory.
+ */
+function countMarkdownFiles(dir) {
+    let count = 0;
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += countMarkdownFiles(join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                count++;
+            }
+        }
+    }
+    catch {
+        // Directory unreadable — return 0
+    }
+    return count;
+}

package/dist/server/core/domain/transport/schemas.d.ts

@@ -515,6 +515,8 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     taskId: z.ZodString;
     /** Task type */
     type: z.ZodEnum<["curate", "curate-folder", "query"]>;
+    /** Workspace root for scoped query/curate */
+    worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "curate" | "query" | "curate-folder";
     content: string;
@@ -524,6 +526,7 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
@@ -533,6 +536,7 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }>;
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -960,6 +964,8 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     taskId: z.ZodString;
     /** Task type */
     type: z.ZodEnum<["curate", "curate-folder", "query"]>;
+    /** Workspace root for scoped query/curate (stable linked root or projectRoot if unlinked) */
+    worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "curate" | "query" | "curate-folder";
     content: string;
@@ -968,6 +974,7 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
@@ -976,6 +983,7 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     clientCwd?: string | undefined;
     folderPath?: string | undefined;
     projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }>;
 /**
  * Response after task creation

package/dist/server/core/domain/transport/schemas.js

@@ -315,6 +315,8 @@ export const TaskExecuteSchema = z.object({
     taskId: z.string(),
     /** Task type */
     type: z.enum(['curate', 'curate-folder', 'query']),
+    /** Workspace root for scoped query/curate */
+    worktreeRoot: z.string().optional(),
 });
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -492,6 +494,8 @@ export const TaskCreateRequestSchema = z.object({
     taskId: z.string().uuid('Invalid taskId format - must be UUID'),
     /** Task type */
     type: TaskTypeSchema,
+    /** Workspace root for scoped query/curate (stable linked root or projectRoot if unlinked) */
+    worktreeRoot: z.string().optional(),
 });
 /**
  * Response after task creation

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/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

@@ -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 {

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.