byterover-cli 3.6.1 → 3.7.1

package/dist/agent/infra/tools/implementations/memory-symbol-tree.js

@@ -46,14 +46,6 @@ function determineKind(segments) {
         }
     }
 }
-function extractMetadataFromScoring(scoring) {
-    return {
-        importance: scoring.importance ?? 50,
-        keywords: [],
-        maturity: scoring.maturity ?? 'draft',
-        tags: [],
-    };
-}
 /**
  * Get or create a folder symbol (Domain/Topic/Subtopic) at the given path.
  * Creates intermediate nodes as needed.
@@ -133,12 +125,8 @@ export function buildSymbolTree(documentMap, summaryMap) {
         const segments = doc.path.split('/');
         const folderPath = segments.slice(0, -1).join('/');
         const folderNode = symbolMap.get(folderPath);
-        if (folderNode) {
-            folderNode.metadata = {
-                ...folderNode.metadata,
-                ...extractMetadataFromScoring(doc.scoring),
-            };
-        }
+        // Post-commit-5: ranking signals (importance, maturity) are read from the
+        // sidecar at query time; the symbol tree only carries structural metadata.
         // Also register the context.md path itself for direct lookups
         symbolMap.set(doc.path, folderNode ?? getOrCreateFolderNode(symbolMap, root, folderPath, segments.slice(0, -1)));
     }
@@ -150,7 +138,7 @@ export function buildSymbolTree(documentMap, summaryMap) {
         const contextNode = {
             children: [],
             kind: MemorySymbolKind.Context,
-            metadata: extractMetadataFromScoring(doc.scoring),
+            metadata: { ...DEFAULT_METADATA },
             name: doc.title || segments.at(-1).replace(/\.md$/, ''),
             parent: parentNode,
             path: doc.path,

package/dist/agent/infra/tools/implementations/search-knowledge-service.d.ts

@@ -1,4 +1,6 @@
+import type { IRuntimeSignalStore } from '../../../../server/core/interfaces/storage/i-runtime-signal-store.js';
 import type { IFileSystem } from '../../../core/interfaces/i-file-system.js';
+import type { ILogger } from '../../../core/interfaces/i-logger.js';
 import type { ISearchKnowledgeService, SearchKnowledgeResult } from '../../sandbox/tools-sdk.js';
 /**
  * Configuration for SearchKnowledgeService.
@@ -8,6 +10,18 @@ export interface SearchKnowledgeServiceConfig {
     baseDirectory?: string;
     /** Cache TTL in milliseconds (defaults to 5000) */
     cacheTtlMs?: number;
+    /**
+     * Optional logger. When provided, sidecar read failures on the ranking
+     * path emit a `warn` so the fail-open degradation is observable rather
+     * than silent.
+     */
+    logger?: ILogger;
+    /**
+     * Sidecar store for runtime ranking signals. When provided, `flushAccessHits`
+     * mirrors its importance/accessCount/maturity bumps to the store alongside
+     * the existing markdown writes. Phase 3 of the runtime-signals migration.
+     */
+    runtimeSignalStore?: IRuntimeSignalStore;
 }
 /**
  * Extended search options supporting symbolic filters.
@@ -36,15 +50,24 @@ export declare class SearchKnowledgeService implements ISearchKnowledgeService {
     private readonly baseDirectory;
     private readonly cacheTtlMs;
     private readonly fileSystem;
+    private readonly logger?;
     private readonly pendingAccessHits;
+    private readonly runtimeSignalStore?;
     private readonly state;
     constructor(fileSystem: IFileSystem, config?: SearchKnowledgeServiceConfig);
     /**
-     * Flush accumulated access hits to disk by updating frontmatter scoring.
-     * Called during index rebuild to batch writes and avoid write amplification.
-     * Best-effort: errors are swallowed per file.
+     * Flush accumulated access hits to the runtime-signal sidecar.
+     *
+     * Post-commit-5 this no longer writes to markdown — ranking signals
+     * live exclusively in the sidecar. The `contextTreePath` parameter is
+     * retained for signature compatibility with the cache-invalidation
+     * callback but is no longer used.
+     *
+     * Returns `true` when hits were processed so the caller knows to
+     * refresh file mtimes (historical contract); with markdown writes
+     * removed the refresh is harmless but kept for symmetry.
      */
-    flushAccessHits(contextTreePath: string): Promise<boolean>;
+    flushAccessHits(_contextTreePath: string): Promise<boolean>;
     /**
      * Search the knowledge base for relevant topics.
      * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode.
@@ -64,6 +87,28 @@ export declare class SearchKnowledgeService implements ISearchKnowledgeService {
      * For archive stubs, extracts points_to path into archiveFullPath.
      */
     private enrichResult;
+    /**
+     * Load the runtime-signal map for this search via `getMany`, limiting the
+     * request to paths that this search could possibly rank: every indexed
+     * document plus every summary sibling (parent-propagation can touch any
+     * summary). The returned map contains entries only for paths with stored
+     * signals; callers use `.has()` / `.get()` to distinguish missing from
+     * default. Returns an empty map on sidecar failure so ranking degrades to
+     * BM25 alone rather than erroring out mid-query.
+     */
+    private loadSignalsByPath;
+    /**
+     * Mirror a batch of access-hit bumps into the runtime-signal sidecar.
+     *
+     * Matches the markdown flush semantics above:
+     *   - `recordAccessHits` bumps `importance` by `ACCESS_IMPORTANCE_BONUS * count`
+     *     and `accessCount` by `count`.
+     *   - `determineTier` recomputes `maturity` from the new importance.
+     * Both steps run inside `update`'s atomic read-modify-write callback so
+     * same-path contention within the process does not lose bumps.
+     * `updatedAt` is never mirrored — it is a content timestamp, not a signal.
+     */
+    private mirrorHitsToSignalStore;
     /**
      * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
      */

package/dist/agent/infra/tools/implementations/search-knowledge-service.js

@@ -3,8 +3,9 @@ import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { removeStopwords } from 'stopword';
 import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, OVERVIEW_EXTENSION, SHARED_SOURCE_LOCAL_SCORE_BOOST, SUMMARY_INDEX_FILE, } from '../../../../server/constants.js';
-import { parseFrontmatterScoring, updateScoringInContent, } from '../../../../server/core/domain/knowledge/markdown-writer.js';
-import { applyDecay, applyDefaultScoring, compoundScore, determineTier, recordAccessHits, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
+import { applyDecay, compoundScore, determineTier, recordAccessHits, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
+import { createDefaultRuntimeSignals, } from '../../../../server/core/domain/knowledge/runtime-signals-schema.js';
+import { warnSidecarFailure } from '../../../../server/core/domain/knowledge/sidecar-logging.js';
 import { loadSources } from '../../../../server/core/domain/source/source-schema.js';
 import { isArchiveStub, isDerivedArtifact } from '../../../../server/infra/context-tree/derived-artifact.js';
 import { parseArchiveStubFrontmatter, parseSummaryFrontmatter, } from '../../../../server/infra/context-tree/summary-frontmatter.js';
@@ -55,7 +56,7 @@ function getSymbolPath(origin, relativePath) {
  * @param propagationFactor - Score multiplier per level up (default 0.55)
  * @returns New parent entries only — caller merges and re-sorts
  */
-function propagateScoresToParents(results, symbolTree, summaryMap, symbolPathDocMap, propagationFactor = 0.55) {
+function propagateScoresToParents(results, symbolTree, summaryMap, symbolPathDocMap, signalsByPath, propagationFactor = 0.55) {
     const boosts = new Map();
     for (const r of results) {
         const symbol = symbolTree.symbolMap.get(r.path);
@@ -76,11 +77,15 @@ function propagateScoresToParents(results, symbolTree, summaryMap, symbolPathDoc
         const doc = getSummarySource(parentPath, summaryMap, symbolPathDocMap);
         if (!doc)
             continue;
-        // Propagate the strongest child BM25 signal upward, then apply the parent
-        // summary's own scoring exactly once. This avoids double-counting lifecycle
-        // weights that are already baked into child compound scores.
-        const finalScore = doc.scoring
-            ? compoundScore(score, doc.scoring.importance ?? 50, doc.scoring.recency ?? 0.5, doc.scoring.maturity ?? 'draft')
+        // Propagate the strongest child BM25 signal upward. Apply the parent
+        // summary's own scoring boost only when the sidecar has a concrete entry
+        // for this path — matches the pre-migration behaviour where summaries
+        // without scoring in their frontmatter were not boosted. Lookup uses the
+        // summary doc's file path (e.g. `auth/jwt/_index.md`) which matches the
+        // sidecar's relPath key scheme.
+        const sidecarSignals = signalsByPath.get(doc.path);
+        const finalScore = sidecarSignals
+            ? compoundScore(score, sidecarSignals)
             : score;
         boosted.push({
             backlinkCount: 0,
@@ -114,7 +119,6 @@ function getSummarySource(path, summaryMap, symbolPathDocMap) {
         return {
             excerpt: summaryDoc.excerpt ?? '',
             path: summaryDoc.path,
-            scoring: summaryDoc.scoring,
         };
     }
     // Look up context.md via symbolPath-keyed map since documentMap keys are
@@ -124,7 +128,6 @@ function getSummarySource(path, summaryMap, symbolPathDocMap) {
         return {
             excerpt: extractExcerpt(contextDoc.content, contextDoc.title),
             path: contextDoc.path,
-            scoring: contextDoc.scoring,
         };
     }
     return undefined;
@@ -318,7 +321,6 @@ async function indexOriginDocuments(fileSystem, origin, filesWithMtime) {
             const fullPath = join(origin.contextTreeRoot, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
-            const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
             const qualifiedId = `${origin.originKey}::${filePath}`;
             const symbolPath = getSymbolPath(origin, filePath);
             // Check if a .overview.md sibling exists (written by abstract generation queue)
@@ -333,7 +335,6 @@ async function indexOriginDocuments(fileSystem, origin, filesWithMtime) {
                 originKey: origin.originKey,
                 ...(overviewPath !== undefined && { overviewPath }),
                 path: filePath,
-                scoring,
                 symbolPath,
                 title,
             };
@@ -352,16 +353,10 @@ async function indexOriginDocuments(fileSystem, origin, filesWithMtime) {
             const fm = parseSummaryFrontmatter(content);
             if (!fm)
                 return null;
-            // Persist frontmatter scoring so propagateScoresToParents can apply hotness/tier boosts
-            const frontmatter = parseFrontmatterScoring(content);
-            const scoring = frontmatter
-                ? { importance: frontmatter.importance, maturity: frontmatter.maturity, recency: frontmatter.recency }
-                : undefined;
             return {
                 condensationOrder: fm.condensation_order,
                 excerpt: stripMarkdownFrontmatter(content).slice(0, 400),
                 path: getSymbolPath(origin, filePath),
-                scoring,
                 tokenCount: fm.token_count,
             };
         }
@@ -600,7 +595,9 @@ export class SearchKnowledgeService {
     baseDirectory;
     cacheTtlMs;
     fileSystem;
+    logger;
     pendingAccessHits = new Map();
+    runtimeSignalStore;
     state = {
         buildingPromise: undefined,
         cachedIndex: undefined,
@@ -609,34 +606,28 @@ export class SearchKnowledgeService {
         this.fileSystem = fileSystem;
         this.baseDirectory = config.baseDirectory ?? process.cwd();
         this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.logger = config.logger;
+        this.runtimeSignalStore = config.runtimeSignalStore;
     }
     /**
-     * Flush accumulated access hits to disk by updating frontmatter scoring.
-     * Called during index rebuild to batch writes and avoid write amplification.
-     * Best-effort: errors are swallowed per file.
+     * Flush accumulated access hits to the runtime-signal sidecar.
+     *
+     * Post-commit-5 this no longer writes to markdown — ranking signals
+     * live exclusively in the sidecar. The `contextTreePath` parameter is
+     * retained for signature compatibility with the cache-invalidation
+     * callback but is no longer used.
+     *
+     * Returns `true` when hits were processed so the caller knows to
+     * refresh file mtimes (historical contract); with markdown writes
+     * removed the refresh is harmless but kept for symmetry.
      */
-    async flushAccessHits(contextTreePath) {
+    async flushAccessHits(_contextTreePath) {
         if (this.pendingAccessHits.size === 0) {
             return false;
         }
         const hits = new Map(this.pendingAccessHits);
         this.pendingAccessHits.clear();
-        const tasks = [...hits.entries()].map(async ([relPath, count]) => {
-            try {
-                const fullPath = join(contextTreePath, relPath);
-                const { content } = await this.fileSystem.readFile(fullPath);
-                const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
-                const updated = recordAccessHits(scoring, count);
-                const newTier = determineTier(updated.importance ?? 50, (updated.maturity ?? 'draft'));
-                const finalScoring = { ...updated, maturity: newTier };
-                const newContent = updateScoringInContent(content, finalScoring);
-                await this.fileSystem.writeFile(fullPath, newContent);
-            }
-            catch {
-                // Best-effort — swallow per-file errors
-            }
-        });
-        await Promise.allSettled(tasks);
+        await this.mirrorHitsToSignalStore(hits);
         return true;
     }
     /**
@@ -674,9 +665,16 @@ export class SearchKnowledgeService {
         if (options?.overview) {
             return this.buildOverviewResult(symbolTree, referenceIndex, normalizedScope, options.overviewDepth);
         }
+        // Load the runtime-signal sidecar map for the specific paths this query
+        // touches: all document paths in the index plus their summary siblings.
+        // This is O(k) per search instead of O(all entries). Entries are present
+        // only for paths with stored signals — callers use `.has()` to distinguish
+        // missing from default, and `.get(path) ?? defaults` for ergonomic
+        // default-on-miss. On sidecar failure, degrade to BM25-only ranking.
+        const signalsByPath = await this.loadSignalsByPath(documentMap, summaryMap);
         // Symbolic path resolution: try path-based query first
         if (isPathLikeQuery(query, symbolTree)) {
-            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, options);
+            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, signalsByPath, options);
             if (symbolicResult) {
                 return symbolicResult;
             }
@@ -691,10 +689,10 @@ export class SearchKnowledgeService {
         const effectiveScope = (rawScope !== undefined && rawScope !== '' ? rawScope : undefined) ?? parsed.scopePath;
         const effectiveQuery = parsed.scopePath ? parsed.textQuery : query;
         // Run text-based MiniSearch (existing pipeline), optionally scoped to a subtree
-        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
+        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, signalsByPath, options);
         // If scoped search returned nothing and we had a scope, fall back to global search
         if (textResult.results.length === 0 && effectiveScope && effectiveQuery) {
-            return this.runTextSearch(query, documentMap, index, limit, undefined, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
+            return this.runTextSearch(query, documentMap, index, limit, undefined, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, signalsByPath, options);
         }
         return textResult;
     }
@@ -772,10 +770,72 @@ export class SearchKnowledgeService {
             symbolPath: isContextSummary ? summaryPath : symbol?.path,
         };
     }
+    /**
+     * Load the runtime-signal map for this search via `getMany`, limiting the
+     * request to paths that this search could possibly rank: every indexed
+     * document plus every summary sibling (parent-propagation can touch any
+     * summary). The returned map contains entries only for paths with stored
+     * signals; callers use `.has()` / `.get()` to distinguish missing from
+     * default. Returns an empty map on sidecar failure so ranking degrades to
+     * BM25 alone rather than erroring out mid-query.
+     */
+    async loadSignalsByPath(documentMap, summaryMap) {
+        if (!this.runtimeSignalStore)
+            return new Map();
+        const paths = new Set();
+        for (const doc of documentMap.values())
+            paths.add(doc.path);
+        for (const summary of summaryMap.values())
+            paths.add(summary.path);
+        try {
+            return await this.runtimeSignalStore.getMany([...paths]);
+        }
+        catch (error) {
+            this.logger?.warn(`SearchKnowledgeService: sidecar getMany failed, falling back to BM25-only ranking: ${error instanceof Error ? error.message : String(error)}`);
+            return new Map();
+        }
+    }
+    /**
+     * Mirror a batch of access-hit bumps into the runtime-signal sidecar.
+     *
+     * Matches the markdown flush semantics above:
+     *   - `recordAccessHits` bumps `importance` by `ACCESS_IMPORTANCE_BONUS * count`
+     *     and `accessCount` by `count`.
+     *   - `determineTier` recomputes `maturity` from the new importance.
+     * Both steps run inside `update`'s atomic read-modify-write callback so
+     * same-path contention within the process does not lose bumps.
+     * `updatedAt` is never mirrored — it is a content timestamp, not a signal.
+     */
+    async mirrorHitsToSignalStore(hits) {
+        const store = this.runtimeSignalStore;
+        if (!store)
+            return;
+        const updates = new Map([...hits.entries()].map(([relPath, count]) => [
+            relPath,
+            (current) => {
+                const bumped = recordAccessHits(current, count);
+                return {
+                    ...current,
+                    accessCount: bumped.accessCount,
+                    importance: bumped.importance,
+                    maturity: determineTier(bumped.importance, current.maturity),
+                };
+            },
+        ]));
+        try {
+            await store.batchUpdate(updates);
+        }
+        catch (error) {
+            // Best-effort — sidecar failure must not break the flush. The sidecar
+            // will re-sync on the next bump for these paths; the warn makes the
+            // fail-open visible to operators.
+            warnSidecarFailure(this.logger, 'search-knowledge-flush', 'batchUpdate', `${updates.size} path(s)`, error);
+        }
+    }
     /**
      * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
      */
-    runTextSearch(query, documentMap, index, limit, scopePath, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options) {
+    runTextSearch(query, documentMap, index, limit, scopePath, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, signalsByPath, options) {
         const filteredQuery = filterStopWords(query);
         const filteredWords = filteredQuery.split(/\s+/).filter((w) => w.length >= 2);
         // Build scope filter if a subtree is specified
@@ -811,14 +871,19 @@ export class SearchKnowledgeService {
         // Normalize BM25 scores to [0, 1) then blend with importance + recency via compound scoring.
         // Decay is computed lazily from file mtime — no disk writes during search.
         // Local results get a configurable score boost to prefer local knowledge over shared.
+        //
+        // Runtime signals (importance / recency / maturity) come from the sidecar
+        // `signalsByPath` map. Paths with no sidecar entry fall back to defaults —
+        // matches the pre-migration behaviour where missing-frontmatter files used
+        // applyDefaultScoring().
         const now = Date.now();
         const searchResults = rawResults.map((r) => {
             const doc = documentMap.get(r.id);
-            const scoring = doc?.scoring ?? applyDefaultScoring();
+            const signals = (doc && signalsByPath.get(doc.path)) ?? createDefaultRuntimeSignals();
             const daysSince = doc ? Math.max(0, (now - doc.mtime) / 86_400_000) : 0;
-            const decayed = applyDecay(scoring, daysSince);
+            const decayed = applyDecay(signals, daysSince);
             const bm25 = normalizeScore(r.score);
-            let finalScore = compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft');
+            let finalScore = compoundScore(bm25, decayed);
             // Local score boost: prefer local results over shared when scores are close
             if (doc?.origin === 'local') {
                 finalScore = Math.min(finalScore + SHARED_SOURCE_LOCAL_SCORE_BOOST, 1);
@@ -883,10 +948,15 @@ export class SearchKnowledgeService {
                     }
                     if (options?.minMaturity && enriched.symbolKind) {
                         const docMaturity = enriched.symbolKind === 'summary'
-                            ? (getSummarySource(enriched.path, summaryMap, symbolPathDocMap)?.scoring?.maturity ??
-                                symbolTree.symbolMap.get(enriched.path)?.metadata.maturity ??
-                                'draft')
-                            : (symbolTree.symbolMap.get(document.symbolPath)?.metadata.maturity ?? 'draft');
+                            ? (() => {
+                                const summaryDoc = getSummarySource(enriched.path, summaryMap, symbolPathDocMap);
+                                return ((summaryDoc && signalsByPath.get(summaryDoc.path)?.maturity) ??
+                                    symbolTree.symbolMap.get(enriched.path)?.metadata.maturity ??
+                                    'draft');
+                            })()
+                            : (signalsByPath.get(document.path)?.maturity ??
+                                symbolTree.symbolMap.get(document.symbolPath)?.metadata.maturity ??
+                                'draft');
                         if ((MATURITY_TIER_RANK[docMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1)) {
                             continue;
                         }
@@ -900,7 +970,7 @@ export class SearchKnowledgeService {
             }
         }
         // Propagate scores upward to parent domain/topic nodes (hierarchical retrieval)
-        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, symbolPathDocMap);
+        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, symbolPathDocMap, signalsByPath);
         for (const p of propagated) {
             // Apply local score boost to propagated summaries so they stay competitive
             // with boosted direct BM25 hits (the boost was already applied to direct hits above)
@@ -913,7 +983,7 @@ export class SearchKnowledgeService {
                 continue;
             if (options?.minMaturity && p.symbolKind === 'summary') {
                 const summaryDoc = getSummarySource(p.path, summaryMap, symbolPathDocMap);
-                const summaryMaturity = summaryDoc?.scoring?.maturity ?? 'draft';
+                const summaryMaturity = (summaryDoc && signalsByPath.get(summaryDoc.path)?.maturity) ?? 'draft';
                 if ((MATURITY_TIER_RANK[summaryMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1))
                     continue;
             }
@@ -942,7 +1012,7 @@ export class SearchKnowledgeService {
     /**
      * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, options) {
+    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, signalsByPath, options) {
         const pathMatches = matchMemoryPath(symbolTree, query.split(/\s+/)[0].includes('/') ? query.split(/\s+/)[0] : query);
         if (pathMatches.length === 0) {
             return null;
@@ -971,7 +1041,7 @@ export class SearchKnowledgeService {
         const textPart = query.slice(query.indexOf(pathPart) + pathPart.length).trim();
         if (textPart) {
             // Scoped search: search text within the matched subtree
-            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
+            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, signalsByPath, options);
         }
         // No text part — return all children of the matched node
         const subtreeIds = getSubtreeDocumentIds(symbolTree, topMatch.path);

package/dist/agent/infra/tools/implementations/search-knowledge-tool.d.ts

@@ -1,3 +1,4 @@
+import type { IRuntimeSignalStore } from '../../../../server/core/interfaces/storage/i-runtime-signal-store.js';
 import type { Tool } from '../../../core/domain/tools/types.js';
 import type { IFileSystem } from '../../../core/interfaces/i-file-system.js';
 /**
@@ -6,6 +7,7 @@ import type { IFileSystem } from '../../../core/interfaces/i-file-system.js';
 export interface SearchKnowledgeToolConfig {
     baseDirectory?: string;
     cacheTtlMs?: number;
+    runtimeSignalStore?: IRuntimeSignalStore;
 }
 /**
  * Creates the search knowledge tool.

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

@@ -28,6 +28,7 @@ export class ToolProvider {
         maxContextTokens: 0,
         memoryManager: 0,
         processService: 0,
+        runtimeSignalStore: 0,
         sandboxService: 0,
         swarmCoordinator: 0,
         todoStorage: 0,

package/dist/agent/infra/tools/tool-registry.d.ts

@@ -1,3 +1,4 @@
+import type { IRuntimeSignalStore } from '../../../server/core/interfaces/storage/i-runtime-signal-store.js';
 import type { EnvironmentContext } from '../../core/domain/environment/types.js';
 import type { KnownTool } from '../../core/domain/tools/constants.js';
 import type { Tool } from '../../core/domain/tools/types.js';
@@ -42,6 +43,12 @@ export interface ToolServices {
     memoryManager?: MemoryManager;
     /** Process service for command execution */
     processService?: IProcessService;
+    /**
+     * Sidecar store for per-machine ranking signals. When provided, curate and
+     * search tools mirror their scoring writes here alongside the markdown
+     * writes. Phase 3 of the runtime-signals migration.
+     */
+    runtimeSignalStore?: IRuntimeSignalStore;
     /** Sandbox service for code execution */
     sandboxService?: ISandboxService;
     /** Swarm coordinator for cross-provider memory queries */

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

@@ -57,7 +57,7 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.CODE_EXEC]: {
         descriptionFile: 'code_exec',
-        factory({ abstractQueue, environmentContext, fileSystemService, sandboxService, swarmCoordinator }) {
+        factory({ abstractQueue, environmentContext, fileSystemService, runtimeSignalStore, sandboxService, swarmCoordinator }) {
             const sandbox = getRequiredService(sandboxService, 'sandboxService');
             // Inject file system service into sandbox for Tools SDK
             if (fileSystemService && sandbox.setFileSystem) {
@@ -65,12 +65,14 @@ export const TOOL_REGISTRY = {
             }
             // Inject search knowledge service into sandbox for Tools SDK
             if (fileSystemService && sandbox.setSearchKnowledgeService) {
-                const searchKnowledgeService = createSearchKnowledgeService(fileSystemService);
+                const searchKnowledgeService = createSearchKnowledgeService(fileSystemService, {
+                    runtimeSignalStore,
+                });
                 sandbox.setSearchKnowledgeService(searchKnowledgeService);
             }
             // Inject curate service into sandbox for Tools SDK
             if (sandbox.setCurateService) {
-                const curateService = createCurateService(environmentContext?.workingDirectory, abstractQueue);
+                const curateService = createCurateService(environmentContext?.workingDirectory, abstractQueue, runtimeSignalStore);
                 sandbox.setCurateService(curateService);
             }
             // Inject environment context into sandbox for env.* access
@@ -88,14 +90,17 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.CURATE]: {
         descriptionFile: 'curate',
-        factory: ({ abstractQueue, environmentContext }) => createCurateTool(environmentContext?.workingDirectory, abstractQueue),
+        factory: ({ abstractQueue, environmentContext, logger, runtimeSignalStore }) => createCurateTool(environmentContext?.workingDirectory, abstractQueue, runtimeSignalStore, logger),
         markers: [ToolMarker.ContextBuilding, ToolMarker.Modification],
         outputGuidance: 'curate',
         requiredServices: [],
     },
     [ToolName.EXPAND_KNOWLEDGE]: {
         descriptionFile: 'expand_knowledge',
-        factory: ({ environmentContext }) => createExpandKnowledgeTool({ baseDirectory: environmentContext?.workingDirectory }),
+        factory: ({ environmentContext, runtimeSignalStore }) => createExpandKnowledgeTool({
+            baseDirectory: environmentContext?.workingDirectory,
+            runtimeSignalStore,
+        }),
         markers: [ToolMarker.Discovery],
         requiredServices: [],
     },
@@ -144,7 +149,9 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.SEARCH_KNOWLEDGE]: {
         descriptionFile: 'search_knowledge',
-        factory: (services) => createSearchKnowledgeTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        factory: (services) => createSearchKnowledgeTool(getRequiredService(services.fileSystemService, 'fileSystemService'), {
+            runtimeSignalStore: services.runtimeSignalStore,
+        }),
         markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },

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

@@ -1,5 +1,9 @@
 import { Command } from '@oclif/core';
+import type { ILogger } from '../../agent/core/interfaces/i-logger.js';
+import { undoLastDream } from '../../server/infra/dream/dream-undo.js';
 import { type DaemonClientOptions } from '../lib/daemon-client.js';
+/** Build the dep bundle for `undoLastDream` on the CLI-direct path; exported for wiring tests. */
+export declare function buildUndoDeps(projectRoot: string, logger?: ILogger): Promise<Parameters<typeof undoLastDream>[0]>;
 export default class Dream extends Command {
     static description: string;
     static examples: string[];

package/dist/oclif/commands/dream.js

@@ -1,10 +1,14 @@
 import { Command, Flags } from '@oclif/core';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
+import { NoOpLogger } from '../../agent/core/interfaces/i-logger.js';
+import { ConsoleLogger } from '../../agent/infra/logger/console-logger.js';
+import { FileKeyStorage } from '../../agent/infra/storage/file-key-storage.js';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../server/constants.js';
 import { TransportStateEventNames } from '../../server/core/domain/transport/schemas.js';
 import { FileContextTreeArchiveService } from '../../server/infra/context-tree/file-context-tree-archive-service.js';
 import { FileContextTreeManifestService } from '../../server/infra/context-tree/file-context-tree-manifest-service.js';
+import { RuntimeSignalStore } from '../../server/infra/context-tree/runtime-signal-store.js';
 import { DreamLogStore } from '../../server/infra/dream/dream-log-store.js';
 import { DreamStateService } from '../../server/infra/dream/dream-state-service.js';
 import { undoLastDream } from '../../server/infra/dream/dream-undo.js';
@@ -16,6 +20,28 @@ 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 { DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, waitForTaskCompletion } from '../lib/task-client.js';
+/** Build the dep bundle for `undoLastDream` on the CLI-direct path; exported for wiring tests. */
+export async function buildUndoDeps(projectRoot, logger = new ConsoleLogger()) {
+    const brvDir = join(projectRoot, BRV_DIR);
+    const contextTreeDir = join(brvDir, CONTEXT_TREE_DIR);
+    const projectDataDir = getProjectDataDir(projectRoot);
+    // Runtime-signal sidecar — keeps archive/restore from leaking orphan
+    // signal entries on the CLI-direct `brv dream --undo` path. Mirrors the
+    // daemon wiring in agent-process.ts.
+    const keyStorage = new FileKeyStorage({ storageDir: projectDataDir });
+    await keyStorage.initialize();
+    const runtimeSignalStore = new RuntimeSignalStore(keyStorage, logger);
+    return {
+        archiveService: new FileContextTreeArchiveService(runtimeSignalStore),
+        contextTreeDir,
+        curateLogStore: new FileCurateLogStore({ baseDir: projectDataDir }),
+        dreamLogStore: new DreamLogStore({ baseDir: brvDir }),
+        dreamStateService: new DreamStateService({ baseDir: brvDir }),
+        manifestService: new FileContextTreeManifestService({ baseDirectory: projectRoot, runtimeSignalStore }),
+        projectRoot,
+        reviewBackupStore: new FileReviewBackupStore(brvDir),
+    };
+}
 export default class Dream extends Command {
     static description = 'Run background memory consolidation on the context tree';
     static examples = [
@@ -119,20 +145,12 @@ export default class Dream extends Command {
     }
     async runUndo(format) {
         const projectRoot = resolveProject()?.projectRoot ?? process.cwd();
-        const brvDir = join(projectRoot, BRV_DIR);
-        const contextTreeDir = join(brvDir, CONTEXT_TREE_DIR);
-        const projectDataDir = getProjectDataDir(projectRoot);
+        // JSON mode: route sidecar warnings to a no-op so structured stdout
+        // is never paired with stderr noise that breaks downstream parsers.
+        const logger = format === 'json' ? new NoOpLogger() : new ConsoleLogger();
+        const deps = await buildUndoDeps(projectRoot, logger);
         try {
-            const result = await undoLastDream({
-                archiveService: new FileContextTreeArchiveService(),
-                contextTreeDir,
-                curateLogStore: new FileCurateLogStore({ baseDir: projectDataDir }),
-                dreamLogStore: new DreamLogStore({ baseDir: brvDir }),
-                dreamStateService: new DreamStateService({ baseDir: brvDir }),
-                manifestService: new FileContextTreeManifestService({ baseDirectory: projectRoot }),
-                projectRoot,
-                reviewBackupStore: new FileReviewBackupStore(brvDir),
-            });
+            const result = await undoLastDream(deps);
             if (format === 'json') {
                 writeJsonResponse({ command: 'dream', data: { ...result, status: 'undone' }, success: true });
             }

package/dist/server/constants.d.ts

@@ -71,6 +71,6 @@ export declare const OVERVIEW_EXTENSION = ".overview.md";
 export declare const MANIFEST_FILE = "_manifest.json";
 export declare const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export declare const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;
-/** Patterns the context-tree .gitignore must contain (derived artifacts only). */
+/** Patterns the context-tree .gitignore must contain. */
 export declare const CONTEXT_TREE_GITIGNORE_PATTERNS: string[];
 export declare const CONTEXT_TREE_GITIGNORE_HEADER = "# Derived artifacts \u2014 do not track";