byterover-cli 3.1.0 → 3.3.0

package/dist/agent/infra/tools/implementations/write-file-tool.d.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentContext } from '../../../core/domain/environment/types.js';
 import type { Tool } from '../../../core/domain/tools/types.js';
 import type { IFileSystem } from '../../../core/interfaces/i-file-system.js';
 /**
@@ -9,4 +10,4 @@ import type { IFileSystem } from '../../../core/interfaces/i-file-system.js';
  * @param fileSystemService - File system service dependency
  * @returns Configured write file tool
  */
-export declare function createWriteFileTool(fileSystemService: IFileSystem): Tool;
+export declare function createWriteFileTool(fileSystemService: IFileSystem, environmentContext?: EnvironmentContext): Tool;

package/dist/agent/infra/tools/implementations/write-file-tool.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { sanitizeFolderName } from '../../../../server/utils/file-helpers.js';
 import { ToolName } from '../../../core/domain/tools/constants.js';
+import { validateWriteTarget } from '../write-guard.js';
 /**
  * Input schema for write file tool.
  */
@@ -29,13 +30,26 @@ const WriteFileInputSchema = z
  * @param fileSystemService - File system service dependency
  * @returns Configured write file tool
  */
-export function createWriteFileTool(fileSystemService) {
+export function createWriteFileTool(fileSystemService, environmentContext) {
     return {
         description: 'Write content to a file. Overwrites existing files. Can optionally create parent directories.',
         async execute(input, _context) {
             const { content, createDirs, encoding, filePath } = input;
+            const sanitizedPath = sanitizeFolderName(filePath);
+            // Write guard: block writes to shared source context trees
+            if (environmentContext?.workingDirectory) {
+                const writeError = validateWriteTarget(sanitizedPath, environmentContext.workingDirectory);
+                if (writeError) {
+                    return {
+                        bytesWritten: 0,
+                        error: writeError,
+                        path: sanitizedPath,
+                        success: false,
+                    };
+                }
+            }
             // Call file system service
-            const result = await fileSystemService.writeFile(sanitizeFolderName(filePath), content, {
+            const result = await fileSystemService.writeFile(sanitizedPath, content, {
                 createDirs,
                 encoding: encoding,
             });

package/dist/agent/infra/tools/tool-registry.js

@@ -144,7 +144,7 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.WRITE_FILE]: {
         descriptionFile: 'write_file',
-        factory: (services) => createWriteFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        factory: (services) => createWriteFileTool(getRequiredService(services.fileSystemService, 'fileSystemService'), services.environmentContext),
         markers: [ToolMarker.Modification],
         requiredServices: ['fileSystemService'],
     },

package/dist/agent/infra/tools/write-guard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates that a write target path is within the local project's context tree,
+ * not inside any shared knowledge source's context tree.
+ *
+ * Shared sources are read-only — agents must never write to them.
+ *
+ * @param targetPath - Absolute path being written to
+ * @param projectRoot - The local project root (owns .brv/)
+ * @returns null if write is allowed, or an error message string if blocked
+ */
+export declare function validateWriteTarget(targetPath: string, projectRoot: string): null | string;

package/dist/agent/infra/tools/write-guard.js

@@ -0,0 +1,48 @@
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_DIR } from '../../../server/constants.js';
+import { loadSources } from '../../../server/core/domain/source/source-schema.js';
+import { isDescendantOf } from '../../../server/utils/path-utils.js';
+const canonicalize = (path) => {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        // For non-existent files, try canonicalizing the parent
+        try {
+            const parent = dirname(resolve(path));
+            return join(realpathSync(parent), basename(path));
+        }
+        catch {
+            return resolve(path);
+        }
+    }
+};
+/**
+ * Validates that a write target path is within the local project's context tree,
+ * not inside any shared knowledge source's context tree.
+ *
+ * Shared sources are read-only — agents must never write to them.
+ *
+ * @param targetPath - Absolute path being written to
+ * @param projectRoot - The local project root (owns .brv/)
+ * @returns null if write is allowed, or an error message string if blocked
+ */
+export function validateWriteTarget(targetPath, projectRoot) {
+    const localContextTree = resolve(projectRoot, BRV_DIR, CONTEXT_TREE_DIR);
+    const canonicalLocalContextTree = canonicalize(localContextTree);
+    const canonicalTarget = canonicalize(targetPath);
+    if (isDescendantOf(canonicalTarget, canonicalLocalContextTree)) {
+        return null;
+    }
+    // Load sources to get shared context tree roots
+    const loaded = loadSources(projectRoot);
+    for (const origin of loaded?.origins ?? []) {
+        const canonicalSharedRoot = canonicalize(origin.contextTreeRoot);
+        if (isDescendantOf(canonicalTarget, canonicalSharedRoot)) {
+            const alias = origin.alias ?? origin.originKey;
+            return `Cannot write to shared source "${alias}" — sources are read-only. Only the local context tree (${localContextTree}) is writable.`;
+        }
+    }
+    return `Cannot write outside the local context tree. Only the local context tree (${localContextTree}) is writable.`;
+}

package/dist/agent/resources/prompts/system-prompt.yml

@@ -38,6 +38,15 @@ prompt: |
   - Maximum depth: 2 levels (domain → topic → subtopic)
   </DIRECTORIES>
 
+  <KNOWLEDGE_SOURCES>
+  This project may have knowledge sources pointing to other projects' context trees (read-only).
+  - Search results may include `origin: "shared"` results from shared sources
+  - Shared results include `originContextTreeRoot` — use `join(originContextTreeRoot, path)` for `readFile`
+  - Local results get a slight relevance boost over shared results
+  - You CANNOT curate, write, or modify shared source context trees — they are read-only
+  - Only the local `.brv/context-tree/` is writable
+  </KNOWLEDGE_SOURCES>
+
   <TOOL_QUICK_REFERENCE>
   **Queries:** `code_exec` with `tools.*` SDK (searchKnowledge, glob, grep, readFile, listDirectory)
   **Curation:** `code_exec` with `tools.curate()` using UPSERT (preferred), ADD, UPDATE, MERGE, DELETE

package/dist/agent/resources/tools/expand_knowledge.txt

@@ -14,6 +14,10 @@ When searching the knowledge base, you may encounter results with `symbolKind: "
 - `fullContent`: Complete original content of the archived entry
 - `tokenCount`: Estimated token count of the full content
 
+**Shared-source results:**
+- For shared results (`origin: "shared"`), the `stubPath` is relative to the shared context tree
+- Use `originContextTreeRoot` from the search result to resolve the full path
+
 **Example:**
 - Search returns: `{ path: "_archived/auth/jwt-tokens/refresh-flow.stub.md", symbolKind: "archive_stub" }`
 - Call: `expand_knowledge({ stubPath: "_archived/auth/jwt-tokens/refresh-flow.stub.md" })`

package/dist/agent/resources/tools/search_knowledge.txt

@@ -17,14 +17,24 @@ This tool enables semantic/fuzzy search across all curated knowledge without nee
   - `title`: Topic title
   - `excerpt`: Relevant content snippet
   - `score`: Relevance score (higher is better)
+  - `origin`: `"local"` or `"shared"` (shared = from a knowledge source pointing at another project)
+  - `originAlias`: Alias of the shared source (only for shared results)
+  - `originContextTreeRoot`: Absolute path to the shared context tree (only for shared results). Use `join(originContextTreeRoot, path)` to read full content.
 - `totalFound`: Total number of matches
 - `message`: Status message
 
+**Knowledge sources:**
+- Results may include entries from shared knowledge sources (read-only)
+- Shared results have `origin: "shared"` and `originContextTreeRoot` for reading
+- Local results are boosted slightly in relevance scoring
+- You cannot curate or write to shared source context trees
+
 **Usage tips:**
 - Use descriptive queries: "authentication flow" works better than "auth"
 - Search is fuzzy: minor typos are tolerated
 - Results are ranked by relevance to your query
-- Use `read_file` on returned paths to view full content
+- For local results, use `read_file` on returned paths to view full content
+- For shared results, use `read_file` on `join(originContextTreeRoot, path)`
 
 **Examples:**
 - Query: "API authentication" - finds topics about auth design

package/dist/oclif/commands/curate/index.d.ts

@@ -11,6 +11,7 @@ export default class Curate extends Command {
         files: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         folder: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected getDaemonClientOptions(): DaemonClientOptions;
     run(): Promise<void>;

package/dist/oclif/commands/curate/index.js

@@ -6,7 +6,7 @@ import { extractCurateOperations } from '../../../server/utils/curate-result-par
 import { TaskEvents } from '../../../shared/transport/events/index.js';
 import { formatConnectionError, hasLeakedHandles, providerMissingMessage, withDaemonRetry, } from '../../lib/daemon-client.js';
 import { writeJsonResponse } from '../../lib/json-response.js';
-import { waitForTaskCompletion } from '../../lib/task-client.js';
+import { DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, waitForTaskCompletion } from '../../lib/task-client.js';
 export default class Curate extends Command {
     static args = {
         context: Args.string({
@@ -38,6 +38,9 @@ Bad examples:
         '# Folder pack with context',
         '<%= config.bin %> <%= command.id %> "Analyze authentication module" -d src/auth/',
         '',
+        '# Increase timeout for slow models (in seconds)',
+        '<%= config.bin %> <%= command.id %> "context here" --timeout 600',
+        '',
         '# View curate history',
         '<%= config.bin %> curate view',
         '<%= config.bin %> curate view --status completed --since 1h',
@@ -62,6 +65,12 @@ Bad examples:
             description: 'Output format (text or json)',
             options: ['text', 'json'],
         }),
+        timeout: Flags.integer({
+            default: DEFAULT_TIMEOUT_SECONDS,
+            description: 'Maximum seconds to wait for task completion',
+            max: MAX_TIMEOUT_SECONDS,
+            min: MIN_TIMEOUT_SECONDS,
+        }),
     };
     getDaemonClientOptions() {
         return {};
@@ -73,6 +82,7 @@ Bad examples:
             files: rawFlags.files,
             folder: rawFlags.folder,
             format: rawFlags.format === 'json' ? 'json' : rawFlags.format === 'text' ? 'text' : undefined,
+            timeout: rawFlags.timeout,
         };
         const format = flags.format ?? 'text';
         if (!this.validateInput(args, flags, format))
@@ -85,7 +95,7 @@ Bad examples:
         const taskType = flags.folder?.length ? 'curate-folder' : 'curate';
         let providerContext;
         try {
-            await withDaemonRetry(async (client, projectRoot) => {
+            await withDaemonRetry(async (client, projectRoot, worktreeRoot) => {
                 const active = await client.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
                 providerContext = { activeModel: active.activeModel, activeProvider: active.activeProvider };
                 if (!active.activeProvider) {
@@ -94,7 +104,7 @@ Bad examples:
                 if (active.providerKeyMissing) {
                     throw new Error(providerMissingMessage(active.activeProvider, active.authMethod));
                 }
-                await this.submitTask({ client, content: resolvedContent, flags, format, projectRoot, taskType });
+                await this.submitTask({ client, content: resolvedContent, flags, format, projectRoot, taskType, worktreeRoot });
             }, {
                 ...this.getDaemonClientOptions(),
                 onRetry: format === 'text'
@@ -221,7 +231,7 @@ Bad examples:
         }
     }
     async submitTask(props) {
-        const { client, content, flags, format, projectRoot, taskType } = props;
+        const { client, content, flags, format, projectRoot, taskType, worktreeRoot } = props;
         const hasFolders = Boolean(flags.folder?.length);
         const taskId = randomUUID();
         const taskPayload = {
@@ -232,8 +242,12 @@ Bad examples:
             ...(projectRoot ? { projectPath: projectRoot } : {}),
             taskId,
             type: taskType,
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         };
         if (flags.detach) {
+            if (flags.timeout !== DEFAULT_TIMEOUT_SECONDS && format !== 'json') {
+                this.log('Note: --timeout has no effect with --detach');
+            }
             const ack = await client.requestWithAck(TaskEvents.CREATE, taskPayload);
             const { logId } = ack;
             if (format === 'json') {
@@ -298,6 +312,7 @@ Bad examples:
                     }
                 },
                 taskId,
+                timeoutMs: (flags.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
             }, (msg) => this.log(msg));
             await client.requestWithAck(TaskEvents.CREATE, taskPayload);
             await completionPromise;

package/dist/oclif/commands/curate/view.js

@@ -1,5 +1,5 @@
-import { findProjectRoot } from '@campfirein/brv-transport-client';
 import { Args, Command, Flags } from '@oclif/core';
+import { resolveProject } from '../../../server/infra/project/resolve-project.js';
 import { FileCurateLogStore } from '../../../server/infra/storage/file-curate-log-store.js';
 import { CurateLogUseCase } from '../../../server/infra/usecase/curate-log-use-case.js';
 import { getProjectDataDir } from '../../../server/utils/path-utils.js';
@@ -77,7 +77,7 @@ export default class CurateView extends Command {
         const after = flags.since ? this.parseTime(flags.since, '--since') : undefined;
         const before = flags.before ? this.parseTime(flags.before, '--before') : undefined;
         const format = flags.format === 'json' ? 'json' : 'text';
-        const projectRoot = (await findProjectRoot(process.cwd())) ?? process.cwd();
+        const projectRoot = resolveProject()?.projectRoot ?? process.cwd();
         const baseDir = getProjectDataDir(projectRoot);
         const store = new FileCurateLogStore({ baseDir });
         const useCase = new CurateLogUseCase({

package/dist/oclif/commands/main.js

@@ -1,5 +1,6 @@
 import { ensureDaemonRunning } from '@campfirein/brv-transport-client';
 import { Command } from '@oclif/core';
+import { resolveProject } from '../../server/infra/project/resolve-project.js';
 import { resolveLocalServerMainPath } from '../../server/utils/server-main-resolver.js';
 import { startRepl } from '../../tui/repl-startup.js';
 /**
@@ -31,9 +32,21 @@ export default class Main extends Command {
             const detail = daemonResult.spawnError ? `: ${daemonResult.spawnError}` : '';
             this.error(`Failed to start daemon: timed out waiting for daemon to become ready${detail}\n\nRun 'brv restart' to force a clean restart.`);
         }
+        // Resolve project (workspace-link-aware) before starting TUI.
+        // Gracefully handle broken/malformed workspace links so TUI still starts
+        // (user can fix via /worktree remove from within the REPL).
+        let resolution = null;
+        try {
+            resolution = resolveProject();
+        }
+        catch {
+            // Broken workspace link — start TUI without resolved project (falls back to cwd)
+        }
         // Start the interactive REPL (TUI connects via connectToDaemon internally)
         await startRepl({
+            projectPath: resolution?.projectRoot,
             version: this.config.version,
+            worktreeRoot: resolution?.worktreeRoot,
         });
         this.exit(0);
     }

package/dist/oclif/commands/query.d.ts

@@ -8,6 +8,7 @@ export default class Query extends Command {
     static examples: string[];
     static flags: {
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     static strict: boolean;
     protected getDaemonClientOptions(): DaemonClientOptions;

package/dist/oclif/commands/query.js

@@ -4,7 +4,7 @@ import { TransportStateEventNames } from '../../server/core/domain/transport/sch
 import { TaskEvents } from '../../shared/transport/events/index.js';
 import { formatConnectionError, hasLeakedHandles, providerMissingMessage, withDaemonRetry, } from '../lib/daemon-client.js';
 import { writeJsonResponse } from '../lib/json-response.js';
-import { waitForTaskCompletion } from '../lib/task-client.js';
+import { DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, waitForTaskCompletion } from '../lib/task-client.js';
 export default class Query extends Command {
     static args = {
         query: Args.string({
@@ -34,6 +34,12 @@ Bad:
             description: 'Output format (text or json)',
             options: ['text', 'json'],
         }),
+        timeout: Flags.integer({
+            default: DEFAULT_TIMEOUT_SECONDS,
+            description: 'Maximum seconds to wait for task completion',
+            max: MAX_TIMEOUT_SECONDS,
+            min: MIN_TIMEOUT_SECONDS,
+        }),
     };
     static strict = false;
     getDaemonClientOptions() {
@@ -47,7 +53,7 @@ Bad:
             return;
         let providerContext;
         try {
-            await withDaemonRetry(async (client, projectRoot) => {
+            await withDaemonRetry(async (client, projectRoot, worktreeRoot) => {
                 const active = await client.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
                 providerContext = { activeModel: active.activeModel, activeProvider: active.activeProvider };
                 if (!active.activeProvider) {
@@ -56,7 +62,14 @@ Bad:
                 if (active.providerKeyMissing) {
                     throw new Error(providerMissingMessage(active.activeProvider, active.authMethod));
                 }
-                await this.submitTask({ client, format, projectRoot, query: args.query });
+                await this.submitTask({
+                    client,
+                    format,
+                    projectRoot,
+                    query: args.query,
+                    timeoutMs: (flags.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+                    worktreeRoot,
+                });
             }, {
                 ...this.getDaemonClientOptions(),
                 onRetry: format === 'text'
@@ -82,7 +95,7 @@ Bad:
         }
     }
     async submitTask(props) {
-        const { client, format, projectRoot, query } = props;
+        const { client, format, projectRoot, query, timeoutMs, worktreeRoot } = props;
         const taskId = randomUUID();
         const taskPayload = {
             clientCwd: process.cwd(),
@@ -90,6 +103,7 @@ Bad:
             ...(projectRoot ? { projectPath: projectRoot } : {}),
             taskId,
             type: 'query',
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         };
         let finalResult;
         const completionPromise = waitForTaskCompletion({
@@ -155,6 +169,7 @@ Bad:
                 }
             },
             taskId,
+            timeoutMs,
         }, (msg) => this.log(msg));
         await client.requestWithAck(TaskEvents.CREATE, taskPayload);
         await completionPromise;

package/dist/oclif/commands/search.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import { type DaemonClientOptions } from '../lib/daemon-client.js';
+export default class Search extends Command {
+    static args: {
+        query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        scope: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static strict: boolean;
+    protected getDaemonClientOptions(): DaemonClientOptions;
+    run(): Promise<void>;
+    private reportError;
+    private submitTask;
+    private validateInput;
+}

package/dist/oclif/commands/search.js

@@ -0,0 +1,186 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { randomUUID } from 'node:crypto';
+import { TaskEvents } from '../../shared/transport/events/index.js';
+import { encodeSearchContent } from '../../shared/transport/search-content.js';
+import { formatConnectionError, hasLeakedHandles, withDaemonRetry, } from '../lib/daemon-client.js';
+import { writeJsonResponse } from '../lib/json-response.js';
+import { formatSearchTextOutput } from '../lib/search-format.js';
+import { waitForTaskCompletion } from '../lib/task-client.js';
+export default class Search extends Command {
+    static args = {
+        query: Args.string({
+            description: 'Search query to find relevant knowledge in the context tree',
+            required: true,
+        }),
+    };
+    static description = `Search the context tree for relevant knowledge
+
+Returns ranked results with paths, scores, and excerpts.
+Pure BM25 retrieval — no LLM, no token cost.
+
+Use this for structured results with file paths.
+Use "brv query" when you need a synthesized answer.`;
+    static examples = [
+        '# Search for knowledge about authentication',
+        '<%= config.bin %> <%= command.id %> "authentication"',
+        '',
+        '# Limit results and scope to a domain',
+        '<%= config.bin %> <%= command.id %> "JWT tokens" --limit 5 --scope auth/',
+        '',
+        '# JSON output (for automation)',
+        '<%= config.bin %> <%= command.id %> "auth" --format json',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'text',
+            description: 'Output format (text or json)',
+            options: ['text', 'json'],
+        }),
+        limit: Flags.integer({
+            default: 10,
+            description: 'Maximum number of results (1-50)',
+            max: 50,
+            min: 1,
+        }),
+        scope: Flags.string({
+            description: 'Path prefix to scope results (e.g. "auth/" for auth domain only)',
+        }),
+    };
+    static strict = false;
+    getDaemonClientOptions() {
+        return {};
+    }
+    async run() {
+        const { args, flags } = await this.parse(Search);
+        const format = flags.format === 'json' ? 'json' : 'text';
+        if (!this.validateInput(args.query, format))
+            return;
+        try {
+            await withDaemonRetry(async (client, projectRoot, worktreeRoot) => {
+                // No provider validation — search is pure BM25, no LLM needed.
+                await this.submitTask({
+                    client,
+                    format,
+                    limit: flags.limit,
+                    projectRoot,
+                    query: args.query,
+                    scope: flags.scope,
+                    worktreeRoot,
+                });
+            }, {
+                ...this.getDaemonClientOptions(),
+                onRetry: format === 'text'
+                    ? (attempt, maxRetries) => this.log(`\nConnection lost. Restarting daemon... (attempt ${attempt}/${maxRetries})`)
+                    : undefined,
+            });
+        }
+        catch (error) {
+            this.reportError(error, format);
+        }
+    }
+    reportError(error, format) {
+        const errorMessage = error instanceof Error ? error.message : 'Search failed';
+        if (format === 'json') {
+            writeJsonResponse({ command: 'search', data: { error: errorMessage, status: 'error' }, success: false });
+        }
+        else {
+            this.log(formatConnectionError(error));
+        }
+        if (hasLeakedHandles(error)) {
+            // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+            process.exit(1);
+        }
+    }
+    async submitTask(props) {
+        const { client, format, projectRoot, query, worktreeRoot } = props;
+        const taskId = randomUUID();
+        const contentPayload = encodeSearchContent({ limit: props.limit, query, scope: props.scope });
+        const taskPayload = {
+            clientCwd: process.cwd(),
+            content: contentPayload,
+            ...(projectRoot ? { projectPath: projectRoot } : {}),
+            taskId,
+            type: 'search',
+            ...(worktreeRoot ? { worktreeRoot } : {}),
+        };
+        const completionPromise = waitForTaskCompletion({
+            client,
+            command: 'search',
+            format,
+            onCompleted: ({ result }) => {
+                if (!result) {
+                    if (format === 'json') {
+                        writeJsonResponse({
+                            command: 'search',
+                            data: { results: [], status: 'completed', totalFound: 0 },
+                            success: true,
+                        });
+                    }
+                    else {
+                        this.log('\nNo results.\n');
+                    }
+                    return;
+                }
+                try {
+                    const searchResult = JSON.parse(result);
+                    if (format === 'json') {
+                        writeJsonResponse({
+                            command: 'search',
+                            data: {
+                                ...searchResult,
+                                status: 'completed',
+                            },
+                            success: true,
+                        });
+                    }
+                    else {
+                        for (const line of formatSearchTextOutput(searchResult)) {
+                            this.log(line);
+                        }
+                    }
+                }
+                catch {
+                    // Fallback: result isn't valid JSON — display as-is
+                    if (format === 'json') {
+                        writeJsonResponse({
+                            command: 'search',
+                            data: { error: 'Invalid search result format', raw: result, status: 'error' },
+                            success: false,
+                        });
+                    }
+                    else {
+                        this.log(`\n${result}\n`);
+                    }
+                }
+            },
+            onError({ error }) {
+                if (format === 'json') {
+                    writeJsonResponse({
+                        command: 'search',
+                        data: { event: 'error', message: error.message, status: 'error' },
+                        success: false,
+                    });
+                }
+            },
+            taskId,
+        }, (msg) => this.log(msg));
+        await client.requestWithAck(TaskEvents.CREATE, taskPayload);
+        await completionPromise;
+    }
+    validateInput(query, format) {
+        if (query.trim())
+            return true;
+        if (format === 'json') {
+            writeJsonResponse({
+                command: 'search',
+                data: { message: 'Search query is required.', status: 'error' },
+                success: false,
+            });
+        }
+        else {
+            this.log('Search query is required.');
+            this.log('Usage: brv search "your query here"');
+        }
+        return false;
+    }
+}

package/dist/oclif/commands/source/add.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class SourceAdd extends Command {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        alias: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/oclif/commands/source/add.js

@@ -0,0 +1,42 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { resolve } from 'node:path';
+import { SourceEvents } from '../../../shared/transport/events/source-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class SourceAdd extends Command {
+    static args = {
+        path: Args.string({
+            description: 'Path to the target project containing .brv/',
+            required: true,
+        }),
+    };
+    static description = "Add a read-only knowledge source from another project's context tree";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> /path/to/shared-lib',
+        '<%= config.bin %> <%= command.id %> /path/to/shared-lib --alias shared',
+    ];
+    static flags = {
+        alias: Flags.string({
+            description: 'Custom alias for the source (defaults to directory name)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SourceAdd);
+        const targetPath = resolve(args.path);
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(SourceEvents.ADD, {
+                alias: flags.alias,
+                targetPath,
+            }), { projectPath: process.cwd() });
+            if (result.success) {
+                this.log(result.message);
+            }
+            else {
+                this.error(result.message, { exit: 1 });
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}