byterover-cli 1.8.0 → 2.1.0

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

@@ -0,0 +1,50 @@
+/**
+ * File-based implementation of IContextTreeManifestService.
+ *
+ * Builds and reads the context manifest (_manifest.json) which allocates
+ * context tree entries into three lanes (summaries, contexts, stubs)
+ * with token budgets for efficient query context injection.
+ *
+ * Freshness check uses source_fingerprint (hash of sorted path:mtime:size)
+ * to detect additions, modifications, and deletions. Stat-only, no file reads.
+ *
+ * Tradeoff: rare false-fresh cases where content changes but mtime+size
+ * are preserved. Acceptable because writeFile() updates mtime and the next
+ * curate run will rebuild the manifest anyway.
+ */
+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';
+export interface ManifestServiceConfig {
+    baseDirectory?: string;
+}
+export declare class FileContextTreeManifestService implements IContextTreeManifestService {
+    private readonly config;
+    constructor(config?: ManifestServiceConfig);
+    buildManifest(directory?: string, laneBudgets?: LaneTokens): Promise<ContextManifest>;
+    readManifest(directory?: string): Promise<ContextManifest | null>;
+    readManifestIfFresh(directory?: string): Promise<ContextManifest | null>;
+    resolveForInjection(manifest: ContextManifest, _query?: string, directory?: string): Promise<ResolvedEntry[]>;
+    /**
+     * Allocate entries into a lane respecting the token budget.
+     * Entries are already sorted by priority (caller responsibility).
+     */
+    private allocateLane;
+    /**
+     * Compute source fingerprint from stat data (path:mtime:size).
+     * Stat-only — no file reads required.
+     */
+    private computeSourceFingerprint;
+    /**
+     * Recursively scan _archived/ directory for .stub.md files.
+     */
+    private scanArchivedStubs;
+    /**
+     * Recursively scan context tree, collecting entries for manifest building.
+     */
+    private scanForManifest;
+    /**
+     * Recursively collect stat data for all source files (for fingerprint).
+     * Excludes derived artifacts.
+     */
+    private scanSourceStats;
+}

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

@@ -0,0 +1,278 @@
+/* eslint-disable camelcase */
+/**
+ * File-based implementation of IContextTreeManifestService.
+ *
+ * Builds and reads the context manifest (_manifest.json) which allocates
+ * context tree entries into three lanes (summaries, contexts, stubs)
+ * with token budgets for efficient query context injection.
+ *
+ * Freshness check uses source_fingerprint (hash of sorted path:mtime:size)
+ * to detect additions, modifications, and deletions. Stat-only, no file reads.
+ *
+ * Tradeoff: rare false-fresh cases where content changes but mtime+size
+ * are preserved. Acceptable because writeFile() updates mtime and the next
+ * curate run will rebuild the manifest anyway.
+ */
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { 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 { 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';
+import { computeContentHash } from './hash-utils.js';
+import { toUnixPath } from './path-utils.js';
+import { parseSummaryFrontmatter } from './summary-frontmatter.js';
+export class FileContextTreeManifestService {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    async buildManifest(directory, laneBudgets) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const budgets = laneBudgets ?? DEFAULT_LANE_BUDGETS;
+        // Scan all entries
+        const summaries = [];
+        const contexts = [];
+        const stubs = [];
+        await this.scanForManifest(contextTreeDir, contextTreeDir, summaries, contexts, stubs);
+        // 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);
+        const activeStubs = this.allocateLane(stubs, budgets.stubs);
+        const activeContext = [...activeSummaries, ...activeContexts, ...activeStubs];
+        const totalTokens = activeContext.reduce((sum, e) => sum + e.tokens, 0);
+        // Compute source fingerprint (stat-only, no file reads)
+        const sourceFingerprint = await this.computeSourceFingerprint(contextTreeDir);
+        const manifest = {
+            active_context: activeContext,
+            generated_at: new Date().toISOString(),
+            lane_tokens: {
+                contexts: activeContexts.reduce((sum, e) => sum + e.tokens, 0),
+                stubs: activeStubs.reduce((sum, e) => sum + e.tokens, 0),
+                summaries: activeSummaries.reduce((sum, e) => sum + e.tokens, 0),
+            },
+            source_fingerprint: sourceFingerprint,
+            total_tokens: totalTokens,
+            version: 1,
+        };
+        // Write _manifest.json
+        const manifestPath = join(contextTreeDir, MANIFEST_FILE);
+        await writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+        return manifest;
+    }
+    async readManifest(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const manifestPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, MANIFEST_FILE);
+        try {
+            const content = await readFile(manifestPath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async readManifestIfFresh(directory) {
+        const manifest = await this.readManifest(directory);
+        if (!manifest)
+            return null;
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        // Compare stored fingerprint against current state
+        const currentFingerprint = await this.computeSourceFingerprint(contextTreeDir);
+        if (currentFingerprint !== manifest.source_fingerprint)
+            return null;
+        return manifest;
+    }
+    async resolveForInjection(manifest, _query, directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const resolved = [];
+        // Order: summaries (broadest first) → contexts → stubs
+        const ordered = [
+            ...manifest.active_context.filter((e) => e.type === 'summary'),
+            ...manifest.active_context.filter((e) => e.type === 'context'),
+            ...manifest.active_context.filter((e) => e.type === 'stub'),
+        ];
+        /* eslint-disable no-await-in-loop */
+        for (const entry of ordered) {
+            try {
+                const fullPath = join(contextTreeDir, entry.path);
+                const content = await readFile(fullPath, 'utf8');
+                resolved.push({
+                    content,
+                    path: entry.path,
+                    tokens: entry.tokens,
+                    type: entry.type,
+                });
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return resolved;
+    }
+    /**
+     * Allocate entries into a lane respecting the token budget.
+     * Entries are already sorted by priority (caller responsibility).
+     */
+    allocateLane(entries, budget) {
+        const allocated = [];
+        let remaining = budget;
+        for (const entry of entries) {
+            if (entry.tokens <= remaining) {
+                allocated.push(entry);
+                remaining -= entry.tokens;
+            }
+        }
+        return allocated;
+    }
+    /**
+     * Compute source fingerprint from stat data (path:mtime:size).
+     * Stat-only — no file reads required.
+     */
+    async computeSourceFingerprint(contextTreeDir) {
+        const entries = [];
+        await this.scanSourceStats(contextTreeDir, contextTreeDir, entries);
+        const input = entries
+            .sort((a, b) => a.path.localeCompare(b.path))
+            .map((e) => `${e.path}:${e.mtime}:${e.size}`)
+            .join('\n');
+        return computeContentHash(input);
+    }
+    /**
+     * Recursively scan _archived/ directory for .stub.md files.
+     */
+    async scanArchivedStubs(currentDir, contextTreeDir, stubs) {
+        let entries;
+        try {
+            entries = await readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        /* eslint-disable no-await-in-loop */
+        for (const entry of entries) {
+            const entryName = entry.name;
+            const fullPath = join(currentDir, entryName);
+            if (entry.isDirectory()) {
+                await this.scanArchivedStubs(fullPath, contextTreeDir, stubs);
+            }
+            else if (entry.isFile() && entryName.endsWith(STUB_EXTENSION)) {
+                const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
+                try {
+                    const content = await readFile(fullPath, 'utf8');
+                    stubs.push({
+                        path: relativePath,
+                        tokens: estimateTokens(content),
+                        type: 'stub',
+                    });
+                }
+                catch {
+                    // Skip unreadable stubs
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+    /**
+     * Recursively scan context tree, collecting entries for manifest building.
+     */
+    async scanForManifest(currentDir, contextTreeDir, summaries, contexts, stubs) {
+        let entries;
+        try {
+            entries = await readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        /* eslint-disable no-await-in-loop */
+        for (const entry of entries) {
+            const entryName = entry.name;
+            const fullPath = join(currentDir, entryName);
+            if (entry.isDirectory()) {
+                // 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));
+            }
+            else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
+                const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
+                if (entryName === SUMMARY_INDEX_FILE) {
+                    // Summary entry — read frontmatter for condensation_order and token_count
+                    try {
+                        const content = await readFile(fullPath, 'utf8');
+                        const fm = parseSummaryFrontmatter(content);
+                        summaries.push({
+                            order: fm?.condensation_order,
+                            path: relativePath,
+                            tokens: fm?.token_count ?? estimateTokens(content),
+                            type: 'summary',
+                        });
+                    }
+                    catch {
+                        // Skip unreadable summaries
+                    }
+                }
+                else if (!isDerivedArtifact(relativePath) && !isArchiveStub(relativePath)) {
+                    // Regular context entry — extract importance from frontmatter
+                    try {
+                        const content = await readFile(fullPath, 'utf8');
+                        const scoring = parseFrontmatterScoring(content);
+                        contexts.push({
+                            importance: scoring?.importance ?? 50,
+                            path: relativePath,
+                            tokens: estimateTokens(content),
+                            type: 'context',
+                        });
+                    }
+                    catch {
+                        // Skip unreadable files
+                    }
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+    /**
+     * Recursively collect stat data for all source files (for fingerprint).
+     * Excludes derived artifacts.
+     */
+    async scanSourceStats(currentDir, contextTreeDir, entries) {
+        let dirEntries;
+        try {
+            dirEntries = await readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        /* eslint-disable no-await-in-loop */
+        for (const entry of dirEntries) {
+            const entryName = entry.name;
+            const fullPath = join(currentDir, entryName);
+            if (entry.isDirectory()) {
+                await this.scanSourceStats(fullPath, contextTreeDir, entries);
+            }
+            else if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
+                const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
+                // Include all non-derived files (contexts + stubs) in fingerprint
+                if (isDerivedArtifact(relativePath))
+                    continue;
+                try {
+                    const fileStat = await stat(fullPath);
+                    entries.push({
+                        mtime: fileStat.mtimeMs,
+                        path: relativePath,
+                        size: fileStat.size,
+                    });
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { IContextTreeMerger, MergeParams, MergeResult } from '../../core/interfaces/context-tree/i-context-tree-merger.js';
+import type { IContextTreeSnapshotService } from '../../core/interfaces/context-tree/i-context-tree-snapshot-service.js';
+export type FileContextTreeMergerDependencies = {
+    snapshotService: IContextTreeSnapshotService;
+};
+/**
+ * File-based implementation of IContextTreeMerger.
+ *
+ * Merge decision per file (remote hash compared against last snapshot hash):
+ *   - Remote unchanged  → skip; local version wins regardless of local state.
+ *   - Remote changed, local clean, preserveLocalFiles=false → overwrite with remote (regular pull).
+ *   - Remote changed, local clean, preserveLocalFiles=true  → conflict (first-time connect; no
+ *     shared history so the local file is not treated as "old").
+ *   - Remote changed, local also changed                    → conflict.
+ *   Conflict handling: local copy saved to .brv/context-tree-conflicts/ and renamed _N.md;
+ *   remote content written to the original path.
+ *
+ * Clean local files absent from remote are deleted (preserveLocalFiles=false) or preserved
+ * (preserveLocalFiles=true). Locally-deleted files are re-created if remote has a newer version.
+ *
+ * A full backup of the context tree is taken before each merge and used for automatic rollback
+ * on failure. The backup is deleted after a successful merge.
+ */
+export declare class FileContextTreeMerger implements IContextTreeMerger {
+    private static readonly MAX_RENAME_ATTEMPTS;
+    private readonly snapshotService;
+    constructor(deps: FileContextTreeMergerDependencies);
+    private static isErrnoException;
+    merge(params: MergeParams): Promise<MergeResult>;
+    /**
+     * Builds a map of remote files with normalized paths and decoded content.
+     */
+    private buildRemoteFilesMap;
+    /**
+     * Recursively copies a directory tree from src to dest.
+     */
+    private copyDir;
+    /**
+     * Finds the first available filename by inserting _N before the extension.
+     * e.g. "path/to/file.md" → "path/to/file_1.md", "path/to/file_2.md", …
+     */
+    private findAvailableName;
+    private runMerge;
+    /**
+     * Handles a true conflict: saves the local content to the conflict dir and as a _N.md
+     * rename, then writes remote content to the original path.
+     *
+     * @returns The _N.md relative path that the local content was saved to.
+     */
+    private writeConflict;
+}

package/dist/server/infra/context-tree/file-context-tree-merger.js

@@ -0,0 +1,265 @@
+import { copyFile, mkdir, opendir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_BACKUP_DIR, CONTEXT_TREE_CONFLICT_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+import { isExcludedFromSync } from './derived-artifact.js';
+import { computeContentHash } from './hash-utils.js';
+import { toUnixPath } from './path-utils.js';
+/**
+ * File-based implementation of IContextTreeMerger.
+ *
+ * Merge decision per file (remote hash compared against last snapshot hash):
+ *   - Remote unchanged  → skip; local version wins regardless of local state.
+ *   - Remote changed, local clean, preserveLocalFiles=false → overwrite with remote (regular pull).
+ *   - Remote changed, local clean, preserveLocalFiles=true  → conflict (first-time connect; no
+ *     shared history so the local file is not treated as "old").
+ *   - Remote changed, local also changed                    → conflict.
+ *   Conflict handling: local copy saved to .brv/context-tree-conflicts/ and renamed _N.md;
+ *   remote content written to the original path.
+ *
+ * Clean local files absent from remote are deleted (preserveLocalFiles=false) or preserved
+ * (preserveLocalFiles=true). Locally-deleted files are re-created if remote has a newer version.
+ *
+ * A full backup of the context tree is taken before each merge and used for automatic rollback
+ * on failure. The backup is deleted after a successful merge.
+ */
+export class FileContextTreeMerger {
+    static MAX_RENAME_ATTEMPTS = 100;
+    snapshotService;
+    constructor(deps) {
+        this.snapshotService = deps.snapshotService;
+    }
+    static isErrnoException(e) {
+        return e instanceof Error && 'code' in e;
+    }
+    async merge(params) {
+        const { directory, files, localChanges, preserveLocalFiles = false } = params;
+        const contextTreeDir = join(directory, BRV_DIR, CONTEXT_TREE_DIR);
+        const backupDir = join(directory, BRV_DIR, CONTEXT_TREE_BACKUP_DIR);
+        const conflictDir = join(directory, BRV_DIR, CONTEXT_TREE_CONFLICT_DIR);
+        // Capture pre-merge disk state and saved snapshot state for comparison
+        const localState = await this.snapshotService.getCurrentState(directory);
+        const snapshotState = await this.snapshotService.getSnapshotState(directory);
+        // Only added/modified files can conflict — deleted files are absent from disk so they
+        // cannot be read during conflict handling. Locally-deleted + remote-changed falls through
+        // to the "file not on disk" branch in runMerge(), where remote wins by re-creating the file.
+        const locallyChangedPaths = new Set([...localChanges.added, ...localChanges.modified]);
+        const remoteFilesMap = this.buildRemoteFilesMap(files);
+        // Clear any leftover backup or conflict folder from a previous merge.
+        await rm(backupDir, { force: true, recursive: true });
+        await rm(conflictDir, { force: true, recursive: true });
+        // Backup local context tree as a safety net for rollback on failure.
+        try {
+            await this.copyDir(contextTreeDir, backupDir);
+        }
+        catch (error) {
+            if (!FileContextTreeMerger.isErrnoException(error) || error.code !== 'ENOENT')
+                throw error;
+            // Context tree dir does not exist — nothing to back up, continue
+        }
+        try {
+            const result = await this.runMerge({
+                conflictDir,
+                contextTreeDir,
+                locallyChangedPaths,
+                localState,
+                preserveLocalFiles,
+                remoteFilesMap,
+                snapshotState,
+            });
+            // Save snapshot atomically before deleting backup.
+            // If this fails, the catch block will restore the context tree from the backup.
+            await this.snapshotService.saveSnapshotFromState(result.remoteFileStates, directory);
+            // Snapshot saved — backup is no longer needed.
+            await rm(backupDir, { force: true, recursive: true });
+            const mergeResult = {
+                added: result.added,
+                conflicted: result.conflicted,
+                deleted: result.deleted,
+                edited: result.edited,
+                restoredFromRemote: result.restoredFromRemote,
+            };
+            return mergeResult;
+        }
+        catch (error) {
+            // Failure: automatically restore context tree from backup.
+            await rm(contextTreeDir, { force: true, recursive: true });
+            try {
+                await rename(backupDir, contextTreeDir);
+            }
+            catch {
+                // Backup does not exist (context tree was empty before merge) — context tree is cleanly absent.
+            }
+            // Remove any partial conflict directory created before the failure.
+            await rm(conflictDir, { force: true, recursive: true }).catch(() => { });
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Merge failed: ${message}. Context tree has been restored to its original state.`);
+        }
+    }
+    /**
+     * Builds a map of remote files with normalized paths and decoded content.
+     */
+    buildRemoteFilesMap(files) {
+        const result = new Map();
+        for (const file of files) {
+            const normalPath = toUnixPath(file.path).replace(/^\/+/, '');
+            result.set(normalPath, { decodedContent: file.decodeContent() });
+        }
+        return result;
+    }
+    /**
+     * Recursively copies a directory tree from src to dest.
+     */
+    async copyDir(src, dest) {
+        await mkdir(dest, { recursive: true });
+        const dir = await opendir(src);
+        for await (const entry of dir) {
+            const srcPath = join(src, entry.name);
+            const destPath = join(dest, entry.name);
+            await (entry.isDirectory() ? this.copyDir(srcPath, destPath) : copyFile(srcPath, destPath));
+        }
+    }
+    /**
+     * Finds the first available filename by inserting _N before the extension.
+     * e.g. "path/to/file.md" → "path/to/file_1.md", "path/to/file_2.md", …
+     */
+    async findAvailableName(contextTreeDir, relativePath) {
+        const ext = extname(relativePath); // '.md'
+        const withoutExt = relativePath.slice(0, -ext.length); // 'path/to/file'
+        for (let n = 1; n <= FileContextTreeMerger.MAX_RENAME_ATTEMPTS; n++) {
+            const candidate = `${withoutExt}_${n}${ext}`;
+            const fullPath = join(contextTreeDir, candidate);
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                await stat(fullPath);
+                // File exists — try next number
+            }
+            catch {
+                return candidate;
+            }
+        }
+        throw new Error(`Cannot find available name for ${relativePath} after ${FileContextTreeMerger.MAX_RENAME_ATTEMPTS} attempts`);
+    }
+    async runMerge(params) {
+        const { conflictDir, contextTreeDir, locallyChangedPaths, localState, preserveLocalFiles, remoteFilesMap, snapshotState, } = params;
+        const added = [];
+        const edited = [];
+        const deleted = [];
+        const conflicted = [];
+        const restoredFromRemote = [];
+        const remoteFileStates = new Map();
+        /* eslint-disable no-await-in-loop */
+        for (const [normalPath, file] of remoteFilesMap) {
+            // Skip derived artifacts (_index.md, _archived/*, _manifest.json)
+            if (isExcludedFromSync(normalPath))
+                continue;
+            const targetPath = join(contextTreeDir, normalPath);
+            const remoteHash = computeContentHash(file.decodedContent);
+            const snapshotHash = snapshotState.get(normalPath)?.hash;
+            remoteFileStates.set(normalPath, {
+                hash: remoteHash,
+                size: Buffer.byteLength(file.decodedContent, 'utf8'),
+            });
+            if (remoteHash === snapshotHash) {
+                // Remote has NOT changed this file — local wins, skip regardless of local state
+                continue;
+            }
+            // Remote has changed this file (or it is new to remote).
+            if (locallyChangedPaths.has(normalPath)) {
+                // Both sides changed — check if content is actually different before treating as conflict.
+                const localContent = await readFile(targetPath, 'utf8');
+                if (localContent === file.decodedContent) {
+                    // Both sides converged on the same content — no real conflict, treat as edited.
+                    edited.push(normalPath);
+                }
+                else {
+                    // True conflict: preserve original local in conflict dir, rename local to _N.md,
+                    // write remote to original path.
+                    const newRelPath = await this.writeConflict({
+                        conflictDir,
+                        contextTreeDir,
+                        localContent,
+                        normalPath,
+                        remoteContent: file.decodedContent,
+                        targetPath,
+                    });
+                    added.push(newRelPath);
+                    conflicted.push(normalPath);
+                }
+            }
+            else if (localState.has(normalPath)) {
+                if (preserveLocalFiles) {
+                    // First-time connect: no shared history — treat tracked+clean file as a conflict.
+                    // Convergence cannot occur here: local is clean (equals snapshot) and remote hash ≠
+                    // snapshot hash, so the contents are guaranteed to differ.
+                    const localContent = await readFile(targetPath, 'utf8');
+                    const newRelPath = await this.writeConflict({
+                        conflictDir,
+                        contextTreeDir,
+                        localContent,
+                        normalPath,
+                        remoteContent: file.decodedContent,
+                        targetPath,
+                    });
+                    added.push(newRelPath);
+                    conflicted.push(normalPath);
+                }
+                else {
+                    // Regular pull: file exists locally and is clean — overwrite with remote
+                    await writeFile(targetPath, file.decodedContent, 'utf8');
+                    edited.push(normalPath);
+                }
+            }
+            else {
+                // File not on disk — either new from remote or locally deleted with remote having newer version.
+                await mkdir(dirname(targetPath), { recursive: true });
+                await writeFile(targetPath, file.decodedContent, 'utf8');
+                if (snapshotState.has(normalPath)) {
+                    // File was in the last snapshot but is absent from disk — user deleted it.
+                    // Remote has a newer version so it is restored. Track this so the caller can notify the user.
+                    restoredFromRemote.push(normalPath);
+                }
+                added.push(normalPath);
+            }
+        }
+        // Apply remote deletions: if a file no longer exists in remote, remote deleted it — sync
+        // that deletion locally. Skip files with local changes so the user's work is not lost.
+        //
+        // Skip entirely when preserveLocalFiles=true (first-time space connect): the local context
+        // tree has no shared history with the target space, so "absent from remote" means
+        // "remote has never seen it", not "remote deleted it".
+        if (!preserveLocalFiles) {
+            for (const localPath of localState.keys()) {
+                const isLocallyChanged = locallyChangedPaths.has(localPath);
+                const isInRemote = remoteFilesMap.has(localPath);
+                if (!isLocallyChanged && !isInRemote) {
+                    await unlink(join(contextTreeDir, localPath));
+                    deleted.push(localPath);
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return { added, conflicted, deleted, edited, remoteFileStates, restoredFromRemote };
+    }
+    /**
+     * Handles a true conflict: saves the local content to the conflict dir and as a _N.md
+     * rename, then writes remote content to the original path.
+     *
+     * @returns The _N.md relative path that the local content was saved to.
+     */
+    async writeConflict(params) {
+        const { conflictDir, contextTreeDir, localContent, normalPath, remoteContent, targetPath } = params;
+        // Copy original to conflict dir for review
+        const conflictTargetPath = join(conflictDir, normalPath);
+        await mkdir(dirname(conflictTargetPath), { recursive: true });
+        await writeFile(conflictTargetPath, localContent, 'utf8');
+        // Save local version at _N.md
+        const newRelPath = await this.findAvailableName(contextTreeDir, normalPath);
+        const newTargetPath = join(contextTreeDir, newRelPath);
+        await mkdir(dirname(newTargetPath), { recursive: true });
+        await writeFile(newTargetPath, localContent, 'utf8');
+        // Write remote to original path
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, remoteContent, 'utf8');
+        return newRelPath;
+    }
+}

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

@@ -9,6 +9,7 @@ export type ContextTreeServiceConfig = {
 export declare class FileContextTreeService implements IContextTreeService {
     private readonly config;
     constructor(config?: ContextTreeServiceConfig);
+    delete(directory?: string): Promise<void>;
     exists(directory?: string): Promise<boolean>;
     initialize(directory?: string): Promise<string>;
 }

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

@@ -1,4 +1,4 @@
-import { access, mkdir } from 'node:fs/promises';
+import { access, mkdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
 /**
@@ -10,6 +10,11 @@ export class FileContextTreeService {
     constructor(config = {}) {
         this.config = config;
     }
+    async delete(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        await rm(contextTreeDir, { force: true, recursive: true });
+    }
     async exists(directory) {
         const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
         const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);