byterover-cli 3.5.1 → 3.6.0

package/dist/server/infra/dream/parse-dream-response.js

@@ -0,0 +1,35 @@
+/**
+ * Extract and validate a JSON response from LLM output.
+ *
+ * Tries two strategies in order:
+ * 1. JSON inside a ```json code fence (first match, non-greedy)
+ * 2. Raw JSON (first { to last })
+ *
+ * Returns null if no valid JSON matching the schema is found.
+ */
+export function parseDreamResponse(response, schema) {
+    // Strategy 1: JSON in code fence (labeled ```json or plain ```)
+    const fenceMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenceMatch) {
+        const result = tryParse(fenceMatch[1], schema);
+        if (result !== null)
+            return result;
+    }
+    // Strategy 2: Raw JSON (first { to last })
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        const result = tryParse(jsonMatch[0], schema);
+        if (result !== null)
+            return result;
+    }
+    return null;
+}
+function tryParse(raw, schema) {
+    try {
+        const parsed = JSON.parse(raw);
+        return schema.parse(parsed);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { BRV_DIR } from '../../constants.js';
 import { FileValidationError } from '../../core/domain/errors/task-error.js';
 import { createFileContentReader, } from '../../utils/file-content-reader.js';
 import { validateFileForCurate } from '../../utils/file-validator.js';
@@ -6,6 +7,7 @@ import { FileContextTreeManifestService } from '../context-tree/file-context-tre
 import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
 import { FileContextTreeSummaryService } from '../context-tree/file-context-tree-summary-service.js';
 import { diffStates } from '../context-tree/snapshot-diff.js';
+import { DreamStateService } from '../dream/dream-state-service.js';
 import { PreCompactionService } from './pre-compaction/pre-compaction-service.js';
 /**
  * CurateExecutor - Executes curate tasks with an injected CipherAgent.
@@ -126,6 +128,14 @@ export class CurateExecutor {
                     // Fail-open: summary/manifest errors never block curation
                 }
             }
+            // Increment dream curation counter (fail-open: non-critical for curation)
+            try {
+                const dreamStateService = new DreamStateService({ baseDir: path.join(baseDir, BRV_DIR) });
+                await dreamStateService.incrementCurationCount();
+            }
+            catch {
+                // Dream state tracking is non-critical — don't block curation
+            }
             await agent.drainBackgroundWork?.();
             return response;
         }

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

@@ -0,0 +1,97 @@
+/**
+ * DreamExecutor - Orchestrates background memory consolidation ("dreaming").
+ *
+ * 8-step flow:
+ * 1. Capture pre-state snapshot
+ * 2. Load dream state
+ * 3. Find changed files since last dream (via curate log scanning)
+ * 4. Run operations (consolidate, synthesize, prune)
+ * 5. Post-dream propagation (staleness + manifest rebuild)
+ * 6. Write dream log
+ * 7. Update dream state
+ * 8. Release lock (in finally block)
+ *
+ * Lock lifecycle: caller acquires lock via DreamTrigger; this executor releases on
+ * success or rolls back on error so the time gate isn't fooled.
+ */
+import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { CurateLogEntry } from '../../core/domain/entities/curate-log-entry.js';
+import type { CurateLogStatus } from '../../core/interfaces/storage/i-curate-log-store.js';
+import type { DreamLogEntry, DreamOperation } from '../dream/dream-log-schema.js';
+import { type ConsolidateDeps } from '../dream/operations/consolidate.js';
+export type DreamExecutorDeps = {
+    archiveService: {
+        archiveEntry(relativePath: string, agent: ICipherAgent, directory?: string): Promise<{
+            fullPath: string;
+            originalPath: string;
+            stubPath: string;
+        }>;
+        findArchiveCandidates(directory?: string): Promise<string[]>;
+    };
+    curateLogStore: {
+        getNextId(): Promise<string>;
+        list(filters?: {
+            after?: number;
+            before?: number;
+            limit?: number;
+            status?: CurateLogStatus[];
+        }): Promise<CurateLogEntry[]>;
+        save(entry: CurateLogEntry): Promise<void>;
+    };
+    dreamLockService: {
+        release(): Promise<void>;
+        rollback(priorMtime: number): Promise<void>;
+    };
+    dreamLogStore: {
+        getNextId(): Promise<string>;
+        save(entry: DreamLogEntry): Promise<void>;
+    };
+    dreamStateService: {
+        read(): Promise<import('../dream/dream-state-schema.js').DreamState>;
+        update(updater: (state: import('../dream/dream-state-schema.js').DreamState) => import('../dream/dream-state-schema.js').DreamState): Promise<import('../dream/dream-state-schema.js').DreamState>;
+        write(state: import('../dream/dream-state-schema.js').DreamState): Promise<void>;
+    };
+    reviewBackupStore?: {
+        save(relativePath: string, content: string): Promise<void>;
+    };
+    searchService: ConsolidateDeps['searchService'];
+};
+type DreamExecuteOptions = {
+    priorMtime: number;
+    projectRoot: string;
+    taskId: string;
+    trigger: 'agent-idle' | 'cli' | 'manual';
+};
+export declare class DreamExecutor {
+    private readonly deps;
+    constructor(deps: DreamExecutorDeps);
+    executeWithAgent(agent: ICipherAgent, options: DreamExecuteOptions): Promise<{
+        logId: string;
+        result: string;
+    }>;
+    /**
+     * Runs the three dream operations sequentially, pushing results into `out` after
+     * each step. Extracted so the executor can preserve partial work when a later step
+     * throws — and so tests can inject controlled ops without a full LLM round-trip.
+     */
+    protected runOperations(args: {
+        agent: ICipherAgent;
+        changedFiles: Set<string>;
+        contextTreeDir: string;
+        logId: string;
+        out: DreamOperation[];
+        projectRoot: string;
+        signal: AbortSignal;
+        taskId: string;
+    }): Promise<void>;
+    /** Errors are tracked at the log level (status='error'), not per-operation — always 0 here. */
+    private computeSummary;
+    /**
+     * Dual-write: create curate log entries for dream operations that need human review.
+     * This surfaces them in `brv review pending` without modifying the review system.
+     */
+    private createReviewEntries;
+    private findChangedFilesSinceLastDream;
+    private formatResult;
+}
+export {};

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

@@ -0,0 +1,431 @@
+/**
+ * DreamExecutor - Orchestrates background memory consolidation ("dreaming").
+ *
+ * 8-step flow:
+ * 1. Capture pre-state snapshot
+ * 2. Load dream state
+ * 3. Find changed files since last dream (via curate log scanning)
+ * 4. Run operations (consolidate, synthesize, prune)
+ * 5. Post-dream propagation (staleness + manifest rebuild)
+ * 6. Write dream log
+ * 7. Update dream state
+ * 8. Release lock (in finally block)
+ *
+ * Lock lifecycle: caller acquires lock via DreamTrigger; this executor releases on
+ * success or rolls back on error so the time gate isn't fooled.
+ */
+import { access } from 'node:fs/promises';
+import { isAbsolute, join, sep } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
+import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
+import { FileContextTreeSummaryService } from '../context-tree/file-context-tree-summary-service.js';
+import { diffStates } from '../context-tree/snapshot-diff.js';
+import { consolidate } from '../dream/operations/consolidate.js';
+import { prune } from '../dream/operations/prune.js';
+import { synthesize } from '../dream/operations/synthesize.js';
+const DREAM_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+export class DreamExecutor {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async executeWithAgent(agent, options) {
+        const { priorMtime, projectRoot, trigger } = options;
+        const contextTreeDir = join(projectRoot, BRV_DIR, CONTEXT_TREE_DIR);
+        // Timeout budget
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), DREAM_TIMEOUT_MS);
+        const logId = await this.deps.dreamLogStore.getNextId();
+        const startedAt = Date.now();
+        const zeroes = { consolidated: 0, errors: 0, flaggedForReview: 0, pruned: 0, synthesized: 0 };
+        // Save initial processing entry
+        const processingEntry = {
+            id: logId,
+            operations: [],
+            startedAt,
+            status: 'processing',
+            summary: zeroes,
+            taskId: options.taskId,
+            trigger,
+        };
+        await this.deps.dreamLogStore.save(processingEntry);
+        // Hoisted so the catch block can surface any work that completed before a
+        // timeout or error — keeps the dream log audit trail and `brv dream --undo`
+        // history accurate for partial runs.
+        const allOperations = [];
+        let succeeded = false;
+        // Tracks whether the success-path createReviewEntries already ran. The
+        // catch path also calls createReviewEntries for partial runs; without this
+        // flag, a failure that occurs after step 6b succeeds (e.g. step 7
+        // dreamStateService.update throws) would re-write the same review entries.
+        let reviewEntriesWritten = false;
+        try {
+            // Step 1: Capture pre-state
+            const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: projectRoot });
+            let preState;
+            try {
+                preState = await snapshotService.getCurrentState(projectRoot);
+            }
+            catch {
+                // Fail-open: if snapshot fails, skip propagation
+            }
+            // Step 2: Load dream state
+            const dreamState = await this.deps.dreamStateService.read();
+            // Step 3: Find changed files since last dream
+            const changedFiles = await this.findChangedFilesSinceLastDream(dreamState.lastDreamAt, contextTreeDir);
+            // Step 4: Run operations, pushing results incrementally so partial work
+            // is preserved if a later step throws or the budget aborts.
+            await this.runOperations({
+                agent,
+                changedFiles,
+                contextTreeDir,
+                logId,
+                out: allOperations,
+                projectRoot,
+                signal: controller.signal,
+                taskId: options.taskId,
+            });
+            // Step 5: Post-dream propagation (fail-open)
+            if (preState) {
+                try {
+                    const postState = await snapshotService.getCurrentState(projectRoot);
+                    const changedPaths = diffStates(preState, postState);
+                    if (changedPaths.length > 0) {
+                        const summaryService = new FileContextTreeSummaryService();
+                        await summaryService.propagateStaleness(changedPaths, agent, projectRoot);
+                        const manifestService = new FileContextTreeManifestService({ baseDirectory: projectRoot });
+                        await manifestService.buildManifest(projectRoot);
+                    }
+                }
+                catch {
+                    // Fail-open: propagation errors never block dream
+                }
+            }
+            // Step 6: Write dream log
+            const summary = this.computeSummary(allOperations);
+            const completedEntry = {
+                completedAt: Date.now(),
+                id: logId,
+                operations: allOperations,
+                startedAt,
+                status: 'completed',
+                summary,
+                taskId: options.taskId,
+                trigger,
+            };
+            await this.deps.dreamLogStore.save(completedEntry);
+            // Step 6b: Create curate log entries for needsReview operations (dual-write for review system).
+            // Runs after the completed dream log is durably written so review tasks never outlive their dream log.
+            await this.createReviewEntries(allOperations, contextTreeDir, options.taskId);
+            reviewEntriesWritten = true;
+            // Step 7: Update dream state — atomic RMW under the per-file mutex so a
+            // concurrent curate's incrementCurationCount can't be overwritten by the
+            // reset, and so pendingMerges written by prune are preserved by the spread.
+            await this.deps.dreamStateService.update((state) => ({
+                ...state,
+                curationsSinceDream: 0,
+                lastDreamAt: new Date().toISOString(),
+                lastDreamLogId: logId,
+                totalDreams: state.totalDreams + 1,
+            }));
+            succeeded = true;
+            return { logId, result: this.formatResult(logId, summary) };
+        }
+        catch (error) {
+            // Save error/partial log entry (best-effort). Use allOperations so any work
+            // that completed before the failure is captured — keeps the audit trail and
+            // undo history accurate even for partial runs.
+            const summary = this.computeSummary(allOperations);
+            if (controller.signal.aborted) {
+                const partialEntry = {
+                    abortReason: 'Budget exceeded (5 min)',
+                    completedAt: Date.now(),
+                    id: logId,
+                    operations: allOperations,
+                    startedAt,
+                    status: 'partial',
+                    summary,
+                    taskId: options.taskId,
+                    trigger,
+                };
+                await this.deps.dreamLogStore.save(partialEntry).catch(() => { });
+            }
+            else {
+                const errorEntry = {
+                    completedAt: Date.now(),
+                    error: error instanceof Error ? error.message : String(error),
+                    id: logId,
+                    operations: allOperations,
+                    startedAt,
+                    status: 'error',
+                    summary,
+                    taskId: options.taskId,
+                    trigger,
+                };
+                await this.deps.dreamLogStore.save(errorEntry).catch(() => { });
+            }
+            // Surface review-flagged ops that did complete into `brv review pending` even
+            // when the dream failed overall. Skipped when no work accumulated so the
+            // "no dream log, no review entries" invariant holds for errors that fire
+            // before any operation ran. Also skipped when the success-path call
+            // already wrote the entries (i.e. step 7 threw after step 6b succeeded)
+            // to prevent duplicate review items.
+            if (allOperations.length > 0 && !reviewEntriesWritten) {
+                await this.createReviewEntries(allOperations, contextTreeDir, options.taskId);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            // Step 8: Lock management — release on success, rollback on error
+            // eslint-disable-next-line unicorn/prefer-ternary
+            if (succeeded) {
+                await this.deps.dreamLockService.release().catch(() => { });
+            }
+            else {
+                await this.deps.dreamLockService.rollback(priorMtime).catch(() => { });
+            }
+        }
+    }
+    /**
+     * Runs the three dream operations sequentially, pushing results into `out` after
+     * each step. Extracted so the executor can preserve partial work when a later step
+     * throws — and so tests can inject controlled ops without a full LLM round-trip.
+     */
+    async runOperations(args) {
+        const { agent, changedFiles, contextTreeDir, logId, out, projectRoot, signal, taskId } = args;
+        out.push(...(await consolidate([...changedFiles], {
+            agent,
+            contextTreeDir,
+            dreamStateService: this.deps.dreamStateService,
+            reviewBackupStore: this.deps.reviewBackupStore,
+            searchService: this.deps.searchService,
+            signal,
+            taskId,
+        })));
+        if (changedFiles.size > 0) {
+            out.push(...(await synthesize({
+                agent,
+                contextTreeDir,
+                searchService: this.deps.searchService,
+                signal,
+                taskId,
+            })));
+        }
+        out.push(...(await prune({
+            agent,
+            archiveService: this.deps.archiveService,
+            contextTreeDir,
+            dreamLogId: logId,
+            dreamStateService: this.deps.dreamStateService,
+            projectRoot,
+            reviewBackupStore: this.deps.reviewBackupStore,
+            signal,
+            taskId,
+        })));
+    }
+    /** Errors are tracked at the log level (status='error'), not per-operation — always 0 here. */
+    computeSummary(operations) {
+        const summary = { consolidated: 0, errors: 0, flaggedForReview: 0, pruned: 0, synthesized: 0 };
+        for (const op of operations) {
+            if (op.type === 'CONSOLIDATE')
+                summary.consolidated++;
+            if (op.type === 'SYNTHESIZE')
+                summary.synthesized++;
+            if (op.type === 'PRUNE')
+                summary.pruned++;
+            if (op.needsReview)
+                summary.flaggedForReview++;
+        }
+        return summary;
+    }
+    /**
+     * Dual-write: create curate log entries for dream operations that need human review.
+     * This surfaces them in `brv review pending` without modifying the review system.
+     */
+    async createReviewEntries(operations, contextTreeDir, taskId) {
+        const reviewOps = operations.filter((op) => op.needsReview);
+        if (reviewOps.length === 0)
+            return;
+        const curateOps = reviewOps.map((op) => mapDreamOpToCurateOp(op, contextTreeDir));
+        try {
+            const logId = await this.deps.curateLogStore.getNextId();
+            const entry = {
+                completedAt: Date.now(),
+                id: logId,
+                input: { context: 'dream' },
+                operations: curateOps,
+                startedAt: Date.now(),
+                status: 'completed',
+                summary: {
+                    added: curateOps.filter((op) => op.type === 'ADD').length,
+                    deleted: curateOps.filter((op) => op.type === 'DELETE').length,
+                    failed: 0,
+                    merged: curateOps.filter((op) => op.type === 'MERGE').length,
+                    updated: curateOps.filter((op) => op.type === 'UPDATE' || op.type === 'UPSERT').length,
+                },
+                taskId,
+            };
+            await this.deps.curateLogStore.save(entry);
+        }
+        catch {
+            // Fail-open: review entry creation must not block dream
+        }
+    }
+    async findChangedFilesSinceLastDream(lastDreamAt, contextTreeDir) {
+        // First dream (lastDreamAt=null): scan ALL curate logs — every curation happened "since never"
+        const afterTimestamp = lastDreamAt ? new Date(lastDreamAt).getTime() : 0;
+        const recentLogs = await this.deps.curateLogStore.list({
+            after: afterTimestamp,
+            status: ['completed'],
+        });
+        const changedFiles = new Set();
+        for (const log of recentLogs) {
+            if (log.input.context === 'dream')
+                continue;
+            for (const op of log.operations ?? []) {
+                // op.filePath is absolute; convert to relative for context tree operations
+                if (op.filePath) {
+                    const relative = toContextTreeRelative(op.filePath, contextTreeDir);
+                    if (relative)
+                        changedFiles.add(relative);
+                }
+                if (op.additionalFilePaths) {
+                    for (const p of op.additionalFilePaths) {
+                        const relative = toContextTreeRelative(p, contextTreeDir);
+                        if (relative)
+                            changedFiles.add(relative);
+                    }
+                }
+            }
+        }
+        // Filter to files that still exist (concurrent with Promise.all to avoid no-await-in-loop)
+        const checks = [...changedFiles].map(async (file) => {
+            try {
+                await access(join(contextTreeDir, file));
+                return file;
+            }
+            catch {
+                return null;
+            }
+        });
+        const results = await Promise.all(checks);
+        return new Set(results.filter((f) => f !== null));
+    }
+    formatResult(logId, summary) {
+        const parts = [`Dream completed (${logId})`];
+        const counts = [
+            summary.consolidated > 0 ? `${summary.consolidated} consolidated` : '',
+            summary.synthesized > 0 ? `${summary.synthesized} synthesized` : '',
+            summary.pruned > 0 ? `${summary.pruned} pruned` : '',
+        ].filter(Boolean);
+        if (counts.length > 0) {
+            parts.push(counts.join(' | '));
+        }
+        else if (summary.errors === 0 && summary.flaggedForReview === 0) {
+            parts.push('No changes needed — context tree is up to date');
+        }
+        if (summary.errors > 0) {
+            parts.push(`${summary.errors} operations failed`);
+        }
+        if (summary.flaggedForReview > 0) {
+            parts.push(`${summary.flaggedForReview} operations flagged for review`);
+        }
+        return parts.join('\n');
+    }
+}
+/** Map a dream operation to a curate log operation for the review system. */
+function mapDreamOpToCurateOp(op, contextTreeDir) {
+    if (op.type === 'PRUNE' && op.action === 'ARCHIVE') {
+        return {
+            filePath: join(contextTreeDir, op.file),
+            needsReview: true,
+            path: op.file,
+            reason: `[dream/prune] ${op.reason}`,
+            reviewStatus: 'pending',
+            status: 'success',
+            type: 'DELETE',
+        };
+    }
+    if (op.type === 'CONSOLIDATE' && op.action === 'MERGE') {
+        return {
+            additionalFilePaths: op.inputFiles.filter((f) => f !== op.outputFile).map((f) => join(contextTreeDir, f)),
+            filePath: op.outputFile ? join(contextTreeDir, op.outputFile) : undefined,
+            needsReview: true,
+            path: op.outputFile ?? op.inputFiles[0],
+            reason: `[dream/consolidate] ${op.reason}`,
+            reviewStatus: 'pending',
+            status: 'success',
+            type: 'MERGE',
+        };
+    }
+    if (op.type === 'CONSOLIDATE' && op.action === 'TEMPORAL_UPDATE') {
+        const targetFile = op.inputFiles[0];
+        return {
+            filePath: join(contextTreeDir, targetFile),
+            needsReview: true,
+            path: targetFile,
+            reason: `[dream/consolidate] ${op.reason}`,
+            reviewStatus: 'pending',
+            status: 'success',
+            type: 'UPDATE',
+        };
+    }
+    if (op.type === 'CONSOLIDATE' && op.action === 'CROSS_REFERENCE') {
+        const [targetFile, ...relatedFiles] = op.inputFiles;
+        return {
+            additionalFilePaths: relatedFiles.map((file) => join(contextTreeDir, file)),
+            filePath: join(contextTreeDir, targetFile),
+            needsReview: true,
+            path: targetFile,
+            reason: `[dream/consolidate] ${op.reason}`,
+            reviewStatus: 'pending',
+            status: 'success',
+            type: 'UPDATE',
+        };
+    }
+    if (op.type === 'SYNTHESIZE' && op.action === 'CREATE') {
+        return {
+            filePath: join(contextTreeDir, op.outputFile),
+            needsReview: true,
+            path: op.outputFile,
+            reason: '[dream/synthesize] Generated synthesis draft',
+            reviewStatus: 'pending',
+            status: 'success',
+            type: 'ADD',
+        };
+    }
+    const filePath = 'file' in op
+        ? op.file
+        : 'inputFiles' in op
+            ? op.outputFile ?? op.inputFiles[0]
+            : op.outputFile;
+    return {
+        filePath: join(contextTreeDir, filePath),
+        needsReview: true,
+        path: filePath,
+        reason: `[dream/${op.type.toLowerCase()}] ${'reason' in op ? op.reason : ''}`,
+        reviewStatus: 'pending',
+        status: 'success',
+        type: 'UPDATE',
+    };
+}
+/** Convert an absolute file path to a context-tree-relative path, or undefined if not inside the tree. */
+function toContextTreeRelative(absolutePath, contextTreeDir) {
+    // Normalize separators for cross-platform (Windows uses backslash)
+    const normalized = absolutePath.replaceAll('\\', '/');
+    const normalizedDir = contextTreeDir.replaceAll('\\', '/');
+    if (normalized.startsWith(normalizedDir + '/')) {
+        return normalized.slice(normalizedDir.length + 1);
+    }
+    // Already relative? Validate it doesn't traverse outside the context tree
+    if (!isAbsolute(normalized)) {
+        const resolved = join(contextTreeDir, normalized);
+        if (resolved.startsWith(contextTreeDir + sep) || resolved.startsWith(contextTreeDir + '/')) {
+            return normalized;
+        }
+        return undefined; // Path traversal attempt (e.g., ../../secret.md)
+    }
+    return undefined;
+}

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

@@ -1,7 +1,7 @@
 import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
 import type { IFileSystem } from '../../../agent/core/interfaces/i-file-system.js';
 import type { ISearchKnowledgeService } from '../../../agent/infra/sandbox/tools-sdk.js';
-import type { IQueryExecutor, QueryExecuteOptions } from '../../core/interfaces/executor/i-query-executor.js';
+import type { IQueryExecutor, QueryExecuteOptions, QueryExecutorResult } from '../../core/interfaces/executor/i-query-executor.js';
 /**
  * Optional dependencies for QueryExecutor.
  * All fields are optional — without them, the executor falls back to the original behavior.
@@ -43,7 +43,7 @@ export declare class QueryExecutor implements IQueryExecutor {
     private readonly fileSystem?;
     private readonly searchService?;
     constructor(deps?: QueryExecutorDeps);
-    executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<string>;
+    executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<QueryExecutorResult>;
     /**
      * Build pre-fetched context string from search results for LLM prompt injection.
      * Synchronous — uses already-fetched search results (no additional I/O for excerpts).