byterover-cli 3.6.1 → 3.7.1

package/dist/server/core/domain/knowledge/runtime-signals-schema.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime signals — per-machine ranking fields that live in a sidecar store
+ * rather than in shared context-tree markdown frontmatter.
+ *
+ * These fields change on every query (access hit flush) and would otherwise
+ * dirty version control state and cause merge conflicts across teammates.
+ *
+ * Related: `features/runtime-signals/plan.md`
+ */
+import { z } from 'zod';
+export declare const DEFAULT_IMPORTANCE = 50;
+export declare const DEFAULT_RECENCY = 1;
+export declare const DEFAULT_MATURITY: "draft";
+export declare const DEFAULT_ACCESS_COUNT = 0;
+export declare const DEFAULT_UPDATE_COUNT = 0;
+export declare const MaturityTierSchema: z.ZodEnum<["core", "draft", "validated"]>;
+export declare const RuntimeSignalsSchema: z.ZodObject<{
+    accessCount: z.ZodDefault<z.ZodNumber>;
+    importance: z.ZodDefault<z.ZodNumber>;
+    maturity: z.ZodDefault<z.ZodEnum<["core", "draft", "validated"]>>;
+    recency: z.ZodDefault<z.ZodNumber>;
+    updateCount: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    accessCount: number;
+    importance: number;
+    maturity: "draft" | "core" | "validated";
+    recency: number;
+    updateCount: number;
+}, {
+    accessCount?: number | undefined;
+    importance?: number | undefined;
+    maturity?: "draft" | "core" | "validated" | undefined;
+    recency?: number | undefined;
+    updateCount?: number | undefined;
+}>;
+export type MaturityTier = z.infer<typeof MaturityTierSchema>;
+export type RuntimeSignals = z.infer<typeof RuntimeSignalsSchema>;
+/**
+ * Frontmatter fields that remain in context-tree markdown after runtime
+ * signals are moved to the sidecar.
+ *
+ * `createdAt` is immutable. `updatedAt` reflects real content modifications
+ * (set by curate ADD/UPDATE and by MERGE); ranking updates never touch it.
+ */
+export interface SemanticFrontmatter {
+    createdAt?: string;
+    keywords: string[];
+    related: string[];
+    summary?: string;
+    tags: string[];
+    title?: string;
+    updatedAt?: string;
+}
+/**
+ * Return a fresh RuntimeSignals with default values.
+ * Used by the sidecar store when a path has no entry yet, and by curate ADD
+ * when seeding a new knowledge file.
+ */
+export declare function createDefaultRuntimeSignals(): RuntimeSignals;

package/dist/server/core/domain/knowledge/runtime-signals-schema.js

@@ -0,0 +1,46 @@
+/**
+ * Runtime signals — per-machine ranking fields that live in a sidecar store
+ * rather than in shared context-tree markdown frontmatter.
+ *
+ * These fields change on every query (access hit flush) and would otherwise
+ * dirty version control state and cause merge conflicts across teammates.
+ *
+ * Related: `features/runtime-signals/plan.md`
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Defaults (used when a path has no sidecar entry yet)
+// ---------------------------------------------------------------------------
+export const DEFAULT_IMPORTANCE = 50;
+export const DEFAULT_RECENCY = 1;
+export const DEFAULT_MATURITY = 'draft';
+export const DEFAULT_ACCESS_COUNT = 0;
+export const DEFAULT_UPDATE_COUNT = 0;
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const MaturityTierSchema = z.enum(['core', 'draft', 'validated']);
+export const RuntimeSignalsSchema = z.object({
+    accessCount: z.number().int().nonnegative().default(DEFAULT_ACCESS_COUNT),
+    importance: z.number().min(0).max(100).default(DEFAULT_IMPORTANCE),
+    maturity: MaturityTierSchema.default(DEFAULT_MATURITY),
+    recency: z.number().min(0).max(1).default(DEFAULT_RECENCY),
+    updateCount: z.number().int().nonnegative().default(DEFAULT_UPDATE_COUNT),
+});
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Return a fresh RuntimeSignals with default values.
+ * Used by the sidecar store when a path has no entry yet, and by curate ADD
+ * when seeding a new knowledge file.
+ */
+export function createDefaultRuntimeSignals() {
+    return {
+        accessCount: DEFAULT_ACCESS_COUNT,
+        importance: DEFAULT_IMPORTANCE,
+        maturity: DEFAULT_MATURITY,
+        recency: DEFAULT_RECENCY,
+        updateCount: DEFAULT_UPDATE_COUNT,
+    };
+}

package/dist/server/core/domain/knowledge/sidecar-logging.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared helper for observing swallowed sidecar failures.
+ *
+ * Runtime-signals dual-write is best-effort: failures never break the
+ * caller's primary operation (markdown write, ranking read, etc.). After
+ * commit 5 the sidecar is the canonical source for ranking signals, so
+ * silent swallows hide real outages from operators. Every site that
+ * swallows a sidecar error should call this helper from inside the catch.
+ *
+ * The log message shape is stable across call sites so operators can
+ * grep for `sidecar <verb> failed` to surface every occurrence.
+ */
+import type { ILogger } from '../../../../agent/core/interfaces/i-logger.js';
+export declare function warnSidecarFailure(logger: ILogger | undefined, site: string, verb: string, target: string, error: unknown): void;

package/dist/server/core/domain/knowledge/sidecar-logging.js

@@ -0,0 +1,18 @@
+/**
+ * Shared helper for observing swallowed sidecar failures.
+ *
+ * Runtime-signals dual-write is best-effort: failures never break the
+ * caller's primary operation (markdown write, ranking read, etc.). After
+ * commit 5 the sidecar is the canonical source for ranking signals, so
+ * silent swallows hide real outages from operators. Every site that
+ * swallows a sidecar error should call this helper from inside the catch.
+ *
+ * The log message shape is stable across call sites so operators can
+ * grep for `sidecar <verb> failed` to surface every occurrence.
+ */
+export function warnSidecarFailure(logger, site, verb, target, error) {
+    if (!logger)
+        return;
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`${site}: sidecar ${verb} failed for ${target}: ${message}`);
+}

package/dist/server/core/interfaces/storage/i-runtime-signal-store.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Sidecar store for per-machine ranking signals.
+ *
+ * Keeps `importance`, `recency`, `maturity`, `accessCount`, `updateCount`
+ * out of context-tree markdown frontmatter so that query-time bumps don't
+ * dirty version-controlled files or create merge conflicts across teammates.
+ *
+ * Backed by `IKeyStorage` with composite keys of the form
+ * `["signals", ...pathSegments]`. The relative path is split on `/` so each
+ * segment satisfies the key-storage validation rules.
+ *
+ * All paths are relative to the context tree root (e.g. `auth/jwt-refresh.md`)
+ * using forward slashes, matching how paths flow through the rest of the
+ * knowledge pipeline.
+ *
+ * ## Concurrency guarantees
+ *
+ * Atomicity applies **within a single process**. Two `update` calls on the
+ * same path in the same process serialize via the per-key RWLock inside
+ * `FileKeyStorage` — no lost updates.
+ *
+ * Across processes (daemon + CLI), the per-process locks do not coordinate,
+ * so there is a narrow lost-update window when both processes race a read-
+ * modify-write on the same entry. For ranking signals this is acceptable:
+ * losing one access-hit bump has no correctness impact, only a tiny
+ * ranking drift that the next session self-heals. Do **not** rely on
+ * this interface for data where consistency is required (e.g. identifiers,
+ * counters that must never skip).
+ *
+ * ## Invariants NOT enforced here
+ *
+ * The store accepts any `RuntimeSignals` record that satisfies the schema —
+ * it does not enforce semantic invariants such as the importance ↔ maturity
+ * hysteresis defined by `determineTier`. Callers bumping `importance` must
+ * recompute `maturity` themselves (typically via `determineTier`) as part
+ * of the same updater callback.
+ */
+import type { RuntimeSignals } from '../../domain/knowledge/runtime-signals-schema.js';
+/**
+ * Pure function that derives the next signals from the current signals.
+ * Called inside an atomic read-modify-write critical section.
+ */
+export type RuntimeSignalsUpdater = (current: RuntimeSignals) => RuntimeSignals;
+export interface IRuntimeSignalStore {
+    /**
+     * Apply an updater to many entries in parallel.
+     *
+     * Each entry is updated atomically via {@link update}; different paths run
+     * concurrently. Used by the access-hit flush path which accumulates bumps
+     * across many files between index rebuilds.
+     */
+    batchUpdate(updates: Map<string, RuntimeSignalsUpdater>): Promise<void>;
+    /**
+     * Remove an entry. No-op if the entry does not exist.
+     *
+     * Called when a file is archived or deleted so the sidecar does not retain
+     * orphan records.
+     */
+    delete(relPath: string): Promise<void>;
+    /**
+     * Read the signals for a path, returning defaults when no entry exists
+     * or when the stored record fails schema validation.
+     *
+     * Never throws and never returns null — callers can treat every path as
+     * having a signal record.
+     */
+    get(relPath: string): Promise<RuntimeSignals>;
+    /**
+     * Bulk-read signals for a known set of paths.
+     *
+     * Preferred over {@link list} for ranking passes that operate on the
+     * top-N search results: O(k) where k is the number of requested paths,
+     * instead of O(all stored entries).
+     *
+     * The returned map contains entries **only for paths that have a stored
+     * record**. Missing or corrupt records are omitted so callers can
+     * distinguish "no entry yet" from "entry with default values" via
+     * `.has(path)`. Use `map.get(path) ?? createDefaultRuntimeSignals()` when
+     * the caller wants defaults on miss.
+     */
+    getMany(relPaths: readonly string[]): Promise<Map<string, RuntimeSignals>>;
+    /**
+     * Snapshot every stored entry as a Map keyed by relative path.
+     *
+     * Intended for administrative passes (diagnostics, orphan pruning) rather
+     * than per-query ranking — use {@link getMany} for that.
+     */
+    list(): Promise<Map<string, RuntimeSignals>>;
+    /**
+     * Replace the signals for a path with the provided record.
+     *
+     * Used for seeding (curate ADD with defaults) and for operations that
+     * compute a full new record without needing the current value (merge,
+     * restore).
+     */
+    set(relPath: string, signals: RuntimeSignals): Promise<void>;
+    /**
+     * Atomically read, transform, and write the signals for a path.
+     *
+     * The updater receives the current signals (defaults if none are stored)
+     * and must return the complete replacement record. Runs inside the
+     * per-key lock provided by {@link IKeyStorage.update}, so concurrent
+     * callers on the same path within one process serialize cleanly — no
+     * lost updates. See the interface-level note about cross-process
+     * behaviour.
+     *
+     * Use this for any bump semantics that depend on the current value, e.g.
+     * `accessCount += hits` or `importance = min(100, current + bonus)`.
+     */
+    update(relPath: string, updater: RuntimeSignalsUpdater): Promise<RuntimeSignals>;
+}

package/dist/server/core/interfaces/storage/i-runtime-signal-store.js

@@ -0,0 +1,38 @@
+/**
+ * Sidecar store for per-machine ranking signals.
+ *
+ * Keeps `importance`, `recency`, `maturity`, `accessCount`, `updateCount`
+ * out of context-tree markdown frontmatter so that query-time bumps don't
+ * dirty version-controlled files or create merge conflicts across teammates.
+ *
+ * Backed by `IKeyStorage` with composite keys of the form
+ * `["signals", ...pathSegments]`. The relative path is split on `/` so each
+ * segment satisfies the key-storage validation rules.
+ *
+ * All paths are relative to the context tree root (e.g. `auth/jwt-refresh.md`)
+ * using forward slashes, matching how paths flow through the rest of the
+ * knowledge pipeline.
+ *
+ * ## Concurrency guarantees
+ *
+ * Atomicity applies **within a single process**. Two `update` calls on the
+ * same path in the same process serialize via the per-key RWLock inside
+ * `FileKeyStorage` — no lost updates.
+ *
+ * Across processes (daemon + CLI), the per-process locks do not coordinate,
+ * so there is a narrow lost-update window when both processes race a read-
+ * modify-write on the same entry. For ranking signals this is acceptable:
+ * losing one access-hit bump has no correctness impact, only a tiny
+ * ranking drift that the next session self-heals. Do **not** rely on
+ * this interface for data where consistency is required (e.g. identifiers,
+ * counters that must never skip).
+ *
+ * ## Invariants NOT enforced here
+ *
+ * The store accepts any `RuntimeSignals` record that satisfies the schema —
+ * it does not enforce semantic invariants such as the importance ↔ maturity
+ * hysteresis defined by `determineTier`. Callers bumping `importance` must
+ * recompute `maturity` themselves (typically via `determineTier`) as part
+ * of the same updater callback.
+ */
+export {};

package/dist/server/infra/context-tree/file-context-tree-archive-service.d.ts

@@ -11,25 +11,35 @@
  * Fail-open: any error during ghost cue generation falls back to deterministic truncation.
  */
 import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { ILogger } from '../../../agent/core/interfaces/i-logger.js';
 import type { ArchiveResult, DrillDownResult } from '../../core/domain/knowledge/summary-types.js';
 import type { IContextTreeArchiveService } from '../../core/interfaces/context-tree/i-context-tree-archive-service.js';
+import type { IRuntimeSignalStore } from '../../core/interfaces/storage/i-runtime-signal-store.js';
 export declare class FileContextTreeArchiveService implements IContextTreeArchiveService {
+    private readonly runtimeSignalStore?;
+    private readonly logger?;
+    constructor(runtimeSignalStore?: IRuntimeSignalStore | undefined, logger?: ILogger | undefined);
     archiveEntry(relativePath: string, agent: ICipherAgent, directory?: string): Promise<ArchiveResult>;
     drillDown(stubPath: string, directory?: string): Promise<DrillDownResult>;
     findArchiveCandidates(directory?: string): Promise<string[]>;
     restoreEntry(stubPath: string, directory?: string): Promise<string>;
-    /**
-     * Extract importance score from frontmatter. Returns 50 if not found.
-     */
-    private extractImportance;
     /**
      * Generate a ghost cue using LLM with deterministic fallback.
      */
     private generateGhostCue;
     /**
-     * Parse FrontmatterScoring fields from content frontmatter.
+     * Extract the `updatedAt` timestamp from markdown frontmatter. This is
+     * the one scoring-adjacent field that stays in markdown (it tracks real
+     * content modification, not a runtime signal).
+     */
+    private parseUpdatedAt;
+    /**
+     * Read the importance value to embed in an archive stub's eviction metadata.
+     * Pulls from the runtime-signal sidecar (source of truth post-commit-4),
+     * falling back to the default when no entry exists or the store is
+     * unavailable.
      */
-    private parseScoring;
+    private readImportanceForArchiveMetadata;
     /**
      * Recursively scan context tree for archive candidates.
      */

package/dist/server/infra/context-tree/file-context-tree-archive-service.js

@@ -15,11 +15,19 @@ import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { dirname, extname, join } from 'node:path';
 import { ARCHIVE_DIR, ARCHIVE_IMPORTANCE_THRESHOLD, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, DEFAULT_GHOST_CUE_MAX_TOKENS, FULL_ARCHIVE_EXTENSION, STUB_EXTENSION, } from '../../constants.js';
 import { applyDecay } from '../../core/domain/knowledge/memory-scoring.js';
+import { createDefaultRuntimeSignals } from '../../core/domain/knowledge/runtime-signals-schema.js';
+import { warnSidecarFailure } from '../../core/domain/knowledge/sidecar-logging.js';
 import { estimateTokens } from '../executor/pre-compaction/compaction-escalation.js';
 import { isArchiveStub, isDerivedArtifact } from './derived-artifact.js';
 import { toUnixPath } from './path-utils.js';
 import { generateArchiveStubContent, parseArchiveStubFrontmatter } from './summary-frontmatter.js';
 export class FileContextTreeArchiveService {
+    runtimeSignalStore;
+    logger;
+    constructor(runtimeSignalStore, logger) {
+        this.runtimeSignalStore = runtimeSignalStore;
+        this.logger = logger;
+    }
     async archiveEntry(relativePath, agent, directory) {
         const baseDir = directory ?? process.cwd();
         const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
@@ -40,8 +48,11 @@ export class FileContextTreeArchiveService {
         // Generate ghost cue via LLM (fail-open to deterministic truncation)
         const ghostCue = await this.generateGhostCue(agent, content);
         const ghostCueTokenCount = estimateTokens(ghostCue);
-        // Parse frontmatter to get importance for eviction metadata
-        const importance = this.extractImportance(content);
+        // Capture current importance from the sidecar for the archive stub's
+        // eviction metadata. Falls back to the default when no sidecar entry
+        // exists (pre-migration files, or a sidecar that hasn't been written to
+        // for this path). Fail-open on sidecar errors.
+        const importance = await this.readImportanceForArchiveMetadata(toUnixPath(relativePath));
         // Write .stub.md with archive stub frontmatter
         const stubContent = generateArchiveStubContent({
             evicted_at: new Date().toISOString(),
@@ -54,6 +65,17 @@ export class FileContextTreeArchiveService {
         await writeFile(stubFullPath, stubContent, 'utf8');
         // Delete original file
         await unlink(originalFullPath);
+        // Dual-write: drop the archived file's runtime-signal entry so the
+        // sidecar does not retain an orphan. Fail-open — markdown is canonical.
+        if (this.runtimeSignalStore) {
+            try {
+                await this.runtimeSignalStore.delete(toUnixPath(relativePath));
+            }
+            catch (error) {
+                // Best-effort — archive already succeeded.
+                warnSidecarFailure(this.logger, 'archive-service', 'delete', relativePath, error);
+            }
+        }
         return {
             fullPath: toUnixPath(fullRelPath),
             ghostCueTokenCount,
@@ -83,8 +105,22 @@ export class FileContextTreeArchiveService {
     async findArchiveCandidates(directory) {
         const baseDir = directory ?? process.cwd();
         const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        // Preload the runtime-signal map once per scan. `list()` returns only
+        // paths with stored entries; paths without one fall back to defaults at
+        // the comparison site. On sidecar failure, scan with an empty map —
+        // archive candidacy then depends on defaults only (importance 50), which
+        // keeps all draft entries above the threshold and archives nothing. That
+        // is the safest fallback when scoring data is unavailable.
+        let signalsByPath;
+        try {
+            signalsByPath = this.runtimeSignalStore ? await this.runtimeSignalStore.list() : new Map();
+        }
+        catch (error) {
+            warnSidecarFailure(this.logger, 'archive-service', 'list', 'candidate scan', error);
+            signalsByPath = new Map();
+        }
         const candidates = [];
-        await this.scanForCandidates(contextTreeDir, contextTreeDir, candidates);
+        await this.scanForCandidates(contextTreeDir, contextTreeDir, candidates, signalsByPath);
         return candidates;
     }
     async restoreEntry(stubPath, directory) {
@@ -107,15 +143,20 @@ export class FileContextTreeArchiveService {
         // Delete stub and full archive files
         await unlink(stubFullPath);
         await unlink(fullPath);
+        // Dual-write: seed the restored file with default signals. Signal
+        // history from before archiving was already dropped on archive — restore
+        // is a user-initiated action, so resetting to defaults is acceptable.
+        if (this.runtimeSignalStore) {
+            try {
+                await this.runtimeSignalStore.set(toUnixPath(fm.original_path), createDefaultRuntimeSignals());
+            }
+            catch (error) {
+                // Best-effort — markdown restore already succeeded.
+                warnSidecarFailure(this.logger, 'archive-service', 'seed', fm.original_path, error);
+            }
+        }
         return fm.original_path;
     }
-    /**
-     * Extract importance score from frontmatter. Returns 50 if not found.
-     */
-    extractImportance(content) {
-        const match = /^importance:\s*(\d+(?:\.\d+)?)/m.exec(content);
-        return match ? Number.parseFloat(match[1]) : 50;
-    }
     /**
      * Generate a ghost cue using LLM with deterministic fallback.
      */
@@ -154,25 +195,36 @@ ${content.slice(0, 8000)}
         return `${content.replaceAll(/\s+/g, ' ').trim().slice(0, 320)}...`;
     }
     /**
-     * Parse FrontmatterScoring fields from content frontmatter.
+     * Extract the `updatedAt` timestamp from markdown frontmatter. This is
+     * the one scoring-adjacent field that stays in markdown (it tracks real
+     * content modification, not a runtime signal).
      */
-    parseScoring(content) {
-        const scoring = {};
-        const importanceMatch = /^importance:\s*(\d+(?:\.\d+)?)/m.exec(content);
-        if (importanceMatch)
-            scoring.importance = Number.parseFloat(importanceMatch[1]);
-        const maturityMatch = /^maturity:\s*['"]?(core|draft|validated)['"]?/m.exec(content);
-        if (maturityMatch)
-            scoring.maturity = maturityMatch[1];
-        const updatedMatch = /^updatedAt:\s*['"]?(.+?)['"]?\s*$/m.exec(content);
-        if (updatedMatch)
-            scoring.updatedAt = updatedMatch[1];
-        return scoring;
+    parseUpdatedAt(content) {
+        const match = /^updatedAt:\s*['"]?(.+?)['"]?\s*$/m.exec(content);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Read the importance value to embed in an archive stub's eviction metadata.
+     * Pulls from the runtime-signal sidecar (source of truth post-commit-4),
+     * falling back to the default when no entry exists or the store is
+     * unavailable.
+     */
+    async readImportanceForArchiveMetadata(relativePath) {
+        if (!this.runtimeSignalStore)
+            return createDefaultRuntimeSignals().importance;
+        try {
+            const signals = await this.runtimeSignalStore.get(relativePath);
+            return signals.importance;
+        }
+        catch (error) {
+            warnSidecarFailure(this.logger, 'archive-service', 'get', `${relativePath} (archive metadata read)`, error);
+            return createDefaultRuntimeSignals().importance;
+        }
     }
     /**
      * Recursively scan context tree for archive candidates.
      */
-    async scanForCandidates(currentDir, contextTreeDir, candidates) {
+    async scanForCandidates(currentDir, contextTreeDir, candidates, signalsByPath) {
         const { readdir: readdirFs } = await import('node:fs/promises');
         let entries;
         try {
@@ -189,23 +241,30 @@ ${content.slice(0, 8000)}
             if (entry.isDirectory()) {
                 if (entryName === ARCHIVE_DIR)
                     continue;
-                await this.scanForCandidates(fullPath, contextTreeDir, candidates);
+                await this.scanForCandidates(fullPath, contextTreeDir, candidates, signalsByPath);
             }
             else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
                 const relativePath = toUnixPath(fullPath.slice(contextTreeDir.length + 1));
                 if (isDerivedArtifact(relativePath) || isArchiveStub(relativePath))
                     continue;
                 try {
-                    const content = await readFile(fullPath, 'utf8');
-                    const scoring = this.parseScoring(content);
+                    // Runtime signals come from the sidecar; `updatedAt` stays in
+                    // markdown because it reflects content modification time, not a
+                    // ranking signal. Paths without a sidecar entry use defaults —
+                    // maturity 'draft' passes the gate, importance 50 stays above
+                    // ARCHIVE_IMPORTANCE_THRESHOLD (which is < 50), so files without
+                    // recorded signals are correctly excluded from archival.
+                    const signals = signalsByPath.get(relativePath) ?? createDefaultRuntimeSignals();
                     // Only archive draft entries below importance threshold
-                    if (scoring.maturity !== 'draft')
+                    if (signals.maturity !== 'draft')
                         continue;
-                    const daysSinceUpdate = scoring.updatedAt
-                        ? (now - new Date(scoring.updatedAt).getTime()) / (1000 * 60 * 60 * 24)
+                    const content = await readFile(fullPath, 'utf8');
+                    const updatedAt = this.parseUpdatedAt(content);
+                    const daysSinceUpdate = updatedAt
+                        ? (now - new Date(updatedAt).getTime()) / (1000 * 60 * 60 * 24)
                         : 0;
-                    const decayed = applyDecay(scoring, daysSinceUpdate);
-                    if ((decayed.importance ?? 50) < ARCHIVE_IMPORTANCE_THRESHOLD) {
+                    const decayed = applyDecay(signals, daysSinceUpdate);
+                    if (decayed.importance < ARCHIVE_IMPORTANCE_THRESHOLD) {
                         candidates.push(relativePath);
                     }
                 }

package/dist/server/infra/context-tree/file-context-tree-manifest-service.d.ts

@@ -12,10 +12,24 @@
  * are preserved. Acceptable because writeFile() updates mtime and the next
  * curate run will rebuild the manifest anyway.
  */
+import type { ILogger } from '../../../agent/core/interfaces/i-logger.js';
 import type { ContextManifest, LaneTokens, ResolvedEntry } from '../../core/domain/knowledge/summary-types.js';
 import type { IContextTreeManifestService } from '../../core/interfaces/context-tree/i-context-tree-manifest-service.js';
+import type { IRuntimeSignalStore } from '../../core/interfaces/storage/i-runtime-signal-store.js';
 export interface ManifestServiceConfig {
     baseDirectory?: string;
+    /**
+     * Optional logger. When provided, sidecar list failures during manifest
+     * build emit a warn so the fail-open degradation is visible.
+     */
+    logger?: ILogger;
+    /**
+     * Optional. Source of truth for per-context `importance` used in lane
+     * allocation. When absent or when a path has no entry, the default
+     * importance (50) is used — same effective sort as the pre-migration
+     * fallback of `scoring?.importance ?? 50`.
+     */
+    runtimeSignalStore?: IRuntimeSignalStore;
 }
 export declare class FileContextTreeManifestService implements IContextTreeManifestService {
     private readonly config;

package/dist/server/infra/context-tree/file-context-tree-manifest-service.js

@@ -16,7 +16,7 @@
 import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { ABSTRACT_EXTENSION, ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE, } from '../../constants.js';
-import { parseFrontmatterScoring } from '../../core/domain/knowledge/markdown-writer.js';
+import { warnSidecarFailure } from '../../core/domain/knowledge/sidecar-logging.js';
 import { DEFAULT_LANE_BUDGETS } from '../../core/domain/knowledge/summary-types.js';
 import { estimateTokens } from '../executor/pre-compaction/compaction-escalation.js';
 import { isArchiveStub, isDerivedArtifact } from './derived-artifact.js';
@@ -32,11 +32,22 @@ export class FileContextTreeManifestService {
         const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
         const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
         const budgets = laneBudgets ?? DEFAULT_LANE_BUDGETS;
+        // Preload sidecar signals once — used to read `importance` per context.
+        // Fail-open: on sidecar error we treat every path as having no entry,
+        // which falls back to default importance (50) at the read site.
+        let signalsByPath;
+        try {
+            signalsByPath = this.config.runtimeSignalStore ? await this.config.runtimeSignalStore.list() : new Map();
+        }
+        catch (error) {
+            warnSidecarFailure(this.config.logger, 'manifest-service', 'list', 'buildManifest', error);
+            signalsByPath = new Map();
+        }
         // Scan all entries
         const summaries = [];
         const contexts = [];
         const stubs = [];
-        await this.scanForManifest(contextTreeDir, contextTreeDir, summaries, contexts, stubs);
+        await this.scanForManifest(contextTreeDir, contextTreeDir, summaries, contexts, stubs, signalsByPath);
         // Lane allocation with prioritized fill
         const activeSummaries = this.allocateLane(summaries.sort((a, b) => (b.order ?? 0) - (a.order ?? 0)), budgets.summaries);
         const activeContexts = this.allocateLane(contexts.sort((a, b) => (b.importance ?? 50) - (a.importance ?? 50)), budgets.contexts);
@@ -195,7 +206,7 @@ export class FileContextTreeManifestService {
     /**
      * Recursively scan context tree, collecting entries for manifest building.
      */
-    async scanForManifest(currentDir, contextTreeDir, summaries, contexts, stubs) {
+    async scanForManifest(currentDir, contextTreeDir, summaries, contexts, stubs, signalsByPath) {
         let entries;
         try {
             entries = await readdir(currentDir, { withFileTypes: true });
@@ -217,7 +228,7 @@ export class FileContextTreeManifestService {
                 // Scan _archived/ for .stub.md files only; recurse otherwise
                 await (entryName === ARCHIVE_DIR
                     ? this.scanArchivedStubs(fullPath, contextTreeDir, stubs)
-                    : this.scanForManifest(fullPath, contextTreeDir, summaries, contexts, stubs));
+                    : this.scanForManifest(fullPath, contextTreeDir, summaries, contexts, stubs, signalsByPath));
             }
             else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
                 const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
@@ -238,10 +249,12 @@ export class FileContextTreeManifestService {
                     }
                 }
                 else if (!isDerivedArtifact(relativePath) && !isArchiveStub(relativePath)) {
-                    // Regular context entry — extract importance from frontmatter
+                    // Regular context entry — importance comes from the sidecar, not
+                    // markdown frontmatter. Paths without a sidecar entry fall back to
+                    // default importance (50), matching the prior `?? 50` behaviour.
                     try {
                         const content = await readFile(fullPath, 'utf8');
-                        const scoring = parseFrontmatterScoring(content);
+                        const importance = signalsByPath.get(relativePath)?.importance ?? 50;
                         // Use abstract sibling for token budgeting only if it is known to exist
                         // (checked via abstractsInDir set, avoiding ENOENT as control flow).
                         const abstractRelPath = relativePath.replace(/\.md$/, ABSTRACT_EXTENSION);
@@ -257,7 +270,7 @@ export class FileContextTreeManifestService {
                         contexts.push({
                             abstractPath: abstractTokens === undefined ? undefined : abstractRelPath,
                             abstractTokens,
-                            importance: scoring?.importance ?? 50,
+                            importance,
                             path: relativePath,
                             tokens: abstractTokens ?? estimateTokens(content),
                             type: 'context',