byterover-cli 1.8.0 → 2.1.0

package/dist/server/infra/connectors/skill/skill-connector.js

@@ -1,11 +1,11 @@
 import os from 'node:os';
 import path from 'node:path';
 import { AGENT_CONNECTOR_CONFIG } from '../../../core/domain/entities/agent.js';
-import { SKILL_CONNECTOR_CONFIGS, SKILL_FILE_NAMES } from './skill-connector-config.js';
+import { BRV_SKILL_NAME, MAIN_SKILL_FILE_NAME, SKILL_CONNECTOR_CONFIGS, SKILL_FILE_NAMES, } from './skill-connector-config.js';
 import { SkillContentLoader } from './skill-content-loader.js';
 /**
  * Connector that integrates BRV with coding agents via skill files.
- * Writes static markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md)
+ * Writes static markdown files (SKILL.md)
  * into an agent-specific subdirectory.
  */
 export class SkillConnector {
@@ -26,7 +26,12 @@ export class SkillConnector {
         if (!this.isSupported(agent)) {
             throw new Error(`Skill connector does not support agent: ${agent}`);
         }
-        return SKILL_CONNECTOR_CONFIGS[agent].basePath;
+        const config = this.getConfig(agent);
+        const basePath = config.projectPath || config.globalPath;
+        if (!basePath) {
+            throw new Error(`Skill connector has no configured path for agent: ${agent}`);
+        }
+        return path.join(basePath, BRV_SKILL_NAME);
     }
     getSupportedAgents() {
         return this.supportedAgents;
@@ -40,20 +45,29 @@ export class SkillConnector {
                 success: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
+        // Install the skill connector in the project directory by default
+        if (!config.projectPath && !config.globalPath) {
+            return {
+                alreadyInstalled: false,
+                configPath: '',
+                message: `Skill connector has no configured path for agent: ${agent}`,
+                success: false,
+            };
+        }
+        // Install to project directory by default, fall back to global for global-only agents
+        const scope = config.projectPath ? 'project' : 'global';
+        const fullDir = this.resolveFullPath(config, scope, BRV_SKILL_NAME);
         try {
-            // Check if already installed
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
+            const skillFilePath = path.join(fullDir, MAIN_SKILL_FILE_NAME);
             if (await this.fileService.exists(skillFilePath)) {
                 return {
                     alreadyInstalled: true,
-                    configPath: config.basePath,
+                    configPath: fullDir,
                     message: `Skill connector is already installed for ${agent}`,
                     success: true,
                 };
             }
-            // Write all skill files
             await Promise.all(SKILL_FILE_NAMES.map(async (fileName) => {
                 const content = await this.contentLoader.loadSkillFile(fileName);
                 const filePath = path.join(fullDir, fileName);
@@ -69,7 +83,7 @@ export class SkillConnector {
         catch (error) {
             return {
                 alreadyInstalled: false,
-                configPath: config.basePath,
+                configPath: fullDir,
                 message: `Failed to install skill connector for ${agent}: ${error instanceof Error ? error.message : String(error)}`,
                 success: false,
             };
@@ -94,21 +108,42 @@ export class SkillConnector {
                 installed: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
         try {
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
-            const exists = await this.fileService.exists(skillFilePath);
+            // Check project scope first
+            if (config.projectPath) {
+                const projectDir = this.resolveFullPath(config, 'project', BRV_SKILL_NAME);
+                const projectSkillFile = path.join(projectDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(projectSkillFile)) {
+                    return {
+                        configExists: true,
+                        configPath: path.join(config.projectPath, BRV_SKILL_NAME),
+                        installed: true,
+                    };
+                }
+            }
+            // Check global scope
+            if (config.globalPath) {
+                const globalDir = this.resolveFullPath(config, 'global', BRV_SKILL_NAME);
+                const globalSkillFile = path.join(globalDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(globalSkillFile)) {
+                    return {
+                        configExists: true,
+                        configPath: path.join(config.globalPath, BRV_SKILL_NAME),
+                        installed: true,
+                    };
+                }
+            }
             return {
-                configExists: exists,
-                configPath: config.basePath,
-                installed: exists,
+                configExists: false,
+                configPath: '',
+                installed: false,
             };
         }
         catch (error) {
             return {
                 configExists: false,
-                configPath: config.basePath,
+                configPath: '',
                 error: error instanceof Error ? error.message : String(error),
                 installed: false,
             };
@@ -131,45 +166,111 @@ export class SkillConnector {
                 wasInstalled: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
         try {
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
-            const exists = await this.fileService.exists(skillFilePath);
-            if (!exists) {
-                return {
-                    configPath: config.basePath,
-                    message: `Skill connector is not installed for ${agent}`,
-                    success: true,
-                    wasInstalled: false,
-                };
+            // Try to uninstall from project scope
+            if (config.projectPath) {
+                const projectDir = this.resolveFullPath(config, 'project', BRV_SKILL_NAME);
+                const projectSkillFile = path.join(projectDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(projectSkillFile)) {
+                    await this.fileService.deleteDirectory(projectDir);
+                    return {
+                        configPath: path.join(config.projectPath, BRV_SKILL_NAME),
+                        message: `Skill connector uninstalled for ${agent}`,
+                        success: true,
+                        wasInstalled: true,
+                    };
+                }
+            }
+            // Try to uninstall from global scope
+            if (config.globalPath) {
+                const globalDir = this.resolveFullPath(config, 'global', BRV_SKILL_NAME);
+                const globalSkillFile = path.join(globalDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(globalSkillFile)) {
+                    await this.fileService.deleteDirectory(globalDir);
+                    return {
+                        configPath: path.join(config.globalPath, BRV_SKILL_NAME),
+                        message: `Skill connector uninstalled for ${agent}`,
+                        success: true,
+                        wasInstalled: true,
+                    };
+                }
             }
-            await this.fileService.deleteDirectory(fullDir);
             return {
-                configPath: config.basePath,
-                message: `Skill connector uninstalled for ${agent}`,
+                configPath: '',
+                message: `Skill connector is not installed for ${agent}`,
                 success: true,
-                wasInstalled: true,
+                wasInstalled: false,
             };
         }
         catch (error) {
             return {
-                configPath: config.basePath,
+                configPath: '',
                 message: `Failed to uninstall skill connector for ${agent}: ${error instanceof Error ? error.message : String(error)}`,
                 success: false,
                 wasInstalled: true,
             };
         }
     }
+    /**
+     * Write files to a named skill subdirectory for the given agent.
+     * Used by hub install to write downloaded skill files to e.g. `.claude/skills/{skillName}/`.
+     *
+     * @param agent - Agent connector target
+     * @param skillName - Skill folder name to create under the connector path
+     * @param files - Skill files to write
+     * @param options - Optional install scope
+     * @param options.scope - 'global' writes to home dir, 'project' (default) writes to project root
+     */
+    async writeSkillFiles(agent, skillName, files, options) {
+        if (!this.isSupported(agent)) {
+            throw new Error(`Skill connector does not support agent: ${agent}`);
+        }
+        const scope = options?.scope ?? 'project';
+        const config = this.getConfig(agent);
+        const basePath = scope === 'global' ? config.globalPath : config.projectPath;
+        if (!basePath) {
+            throw new Error(`Skill connector does not support ${scope} scope for agent: ${agent}`);
+        }
+        const fullDir = this.resolveFullPath(config, scope, skillName);
+        if (files.length > 0) {
+            const firstFilePath = path.join(fullDir, files[0].name);
+            if (await this.fileService.exists(firstFilePath)) {
+                return { alreadyInstalled: true, installedFiles: [], installedPath: fullDir };
+            }
+        }
+        const installedFiles = [];
+        await Promise.all(files.map(async (file) => {
+            const filePath = path.join(fullDir, file.name);
+            await this.fileService.write(file.content, filePath, 'overwrite');
+            installedFiles.push(filePath);
+        }));
+        return { alreadyInstalled: false, installedFiles, installedPath: fullDir };
+    }
+    /**
+     * Get the skill connector config for an agent, typed as SkillConnectorConfig
+     * to allow safe optional property access on union types from `as const`.
+     */
+    getConfig(agent) {
+        return SKILL_CONNECTOR_CONFIGS[agent];
+    }
     /**
      * Get the full (absolute) path for skill file operations.
-     * - Project scope: relative to project root
-     * - Global scope: relative to os.homedir()
+     * Combines the config base path with the skill name, rooted at either
+     * the project root (project scope) or the user's home directory (global scope).
+     *
+     * @throws Error if the requested scope is not configured for the agent.
      */
-    getFullPath(basePath, scope) {
+    resolveFullPath(config, scope, skillName) {
         if (scope === 'global') {
-            return path.join(os.homedir(), basePath);
+            if (!config.globalPath) {
+                throw new Error('Global path is not configured for this agent');
+            }
+            return path.join(os.homedir(), config.globalPath, skillName);
+        }
+        if (!config.projectPath) {
+            throw new Error('Project path is not configured for this agent');
         }
-        return path.join(this.projectRoot, basePath);
+        return path.join(this.projectRoot, config.projectPath, skillName);
     }
 }

package/dist/server/infra/context-tree/children-hash.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Children hash utility for summary staleness detection.
+ *
+ * Computes a deterministic hash from child paths and their content hashes.
+ * Including paths (not just content hashes) ensures that renames and moves
+ * are detected as structural changes.
+ */
+/**
+ * Compute a deterministic hash of children for staleness detection.
+ *
+ * The hash includes both the relative path and content hash of each child,
+ * sorted by path for determinism. This detects:
+ * - Content changes (different contentHash)
+ * - Renames/moves (different path, same contentHash)
+ * - Additions/deletions (different set of paths)
+ */
+export declare function computeChildrenHash(children: Array<{
+    contentHash: string;
+    path: string;
+}>): string;

package/dist/server/infra/context-tree/children-hash.js

@@ -0,0 +1,22 @@
+/**
+ * Children hash utility for summary staleness detection.
+ *
+ * Computes a deterministic hash from child paths and their content hashes.
+ * Including paths (not just content hashes) ensures that renames and moves
+ * are detected as structural changes.
+ */
+import { computeContentHash } from './hash-utils.js';
+/**
+ * Compute a deterministic hash of children for staleness detection.
+ *
+ * The hash includes both the relative path and content hash of each child,
+ * sorted by path for determinism. This detects:
+ * - Content changes (different contentHash)
+ * - Renames/moves (different path, same contentHash)
+ * - Additions/deletions (different set of paths)
+ */
+export function computeChildrenHash(children) {
+    const sorted = [...children].sort((a, b) => a.path.localeCompare(b.path));
+    const input = sorted.map((c) => `${c.path}:${c.contentHash}`).join('\n');
+    return computeContentHash(input);
+}

package/dist/server/infra/context-tree/derived-artifact.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Derived-artifact predicates for the Hierarchical DAG architecture.
+ *
+ * Three predicates with clear separation of concerns:
+ * - isDerivedArtifact()  — non-searchable derived content (excluded from query fingerprint)
+ * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
+ * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
+ */
+/**
+ * Returns true if the given relative path is a derived artifact
+ * that should be excluded from snapshot tracking, CoGit sync,
+ * and query cache fingerprinting.
+ *
+ * Derived artifacts: _index.md, _manifest.json, _archived/*.full.md
+ * NOTE: _archived/*.stub.md are NOT derived — they are searchable.
+ */
+export declare function isDerivedArtifact(relativePath: string): boolean;
+/**
+ * Returns true if the path is an archive stub (.stub.md inside _archived/).
+ * Stubs are searchable but excluded from snapshot/sync.
+ */
+export declare function isArchiveStub(relativePath: string): boolean;
+/**
+ * Returns true if the path should be excluded from snapshot tracking,
+ * CoGit sync (push/pull/merge), and writer operations.
+ * This includes ALL derived artifacts plus searchable stubs.
+ */
+export declare function isExcludedFromSync(relativePath: string): boolean;

package/dist/server/infra/context-tree/derived-artifact.js

@@ -0,0 +1,48 @@
+/**
+ * Derived-artifact predicates for the Hierarchical DAG architecture.
+ *
+ * Three predicates with clear separation of concerns:
+ * - isDerivedArtifact()  — non-searchable derived content (excluded from query fingerprint)
+ * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
+ * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
+ */
+import { ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
+import { toUnixPath } from './path-utils.js';
+/**
+ * Returns true if the given relative path is a derived artifact
+ * that should be excluded from snapshot tracking, CoGit sync,
+ * and query cache fingerprinting.
+ *
+ * Derived artifacts: _index.md, _manifest.json, _archived/*.full.md
+ * NOTE: _archived/*.stub.md are NOT derived — they are searchable.
+ */
+export function isDerivedArtifact(relativePath) {
+    const normalized = toUnixPath(relativePath);
+    const segments = normalized.split('/');
+    const fileName = segments.at(-1) ?? '';
+    if (fileName === SUMMARY_INDEX_FILE)
+        return true;
+    if (fileName === MANIFEST_FILE)
+        return true;
+    if (segments.includes(ARCHIVE_DIR) && fileName.endsWith(FULL_ARCHIVE_EXTENSION))
+        return true;
+    return false;
+}
+/**
+ * Returns true if the path is an archive stub (.stub.md inside _archived/).
+ * Stubs are searchable but excluded from snapshot/sync.
+ */
+export function isArchiveStub(relativePath) {
+    const normalized = toUnixPath(relativePath);
+    const segments = normalized.split('/');
+    const fileName = segments.at(-1) ?? '';
+    return segments.includes(ARCHIVE_DIR) && fileName.endsWith(STUB_EXTENSION);
+}
+/**
+ * Returns true if the path should be excluded from snapshot tracking,
+ * CoGit sync (push/pull/merge), and writer operations.
+ * This includes ALL derived artifacts plus searchable stubs.
+ */
+export function isExcludedFromSync(relativePath) {
+    return isDerivedArtifact(relativePath) || isArchiveStub(relativePath);
+}

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

@@ -27,13 +27,17 @@ export class FileContextFileReader {
         const fullPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, relativePath);
         try {
             const content = await readFile(fullPath, 'utf8');
-            const title = extractTitle(content, relativePath);
-            const parsedContent = MarkdownWriter.parseContent(content, title);
+            const fallbackTitle = extractTitle(content, relativePath);
+            const parsedContent = MarkdownWriter.parseContent(content, fallbackTitle);
+            // Frontmatter title takes precedence, then H1 heading, then path fallback
+            const title = parsedContent.name || fallbackTitle;
             return {
                 content,
+                keywords: parsedContent.keywords,
                 narrative: parsedContent.narrative,
                 path: relativePath,
                 rawConcept: parsedContent.rawConcept,
+                tags: parsedContent.tags,
                 title,
             };
         }

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

@@ -0,0 +1,37 @@
+/**
+ * File-based implementation of IContextTreeArchiveService.
+ *
+ * Archives low-importance context entries into _archived/ with:
+ * - .full.md: lossless preserved original content
+ * - .stub.md: searchable ghost cue (~220 tokens) with lineage pointers
+ *
+ * Archive naming preserves relative paths to avoid collisions:
+ *   auth/jwt-tokens/refresh-flow.md → _archived/auth/jwt-tokens/refresh-flow.stub.md
+ *
+ * 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 { ArchiveResult, DrillDownResult } from '../../core/domain/knowledge/summary-types.js';
+import type { IContextTreeArchiveService } from '../../core/interfaces/context-tree/i-context-tree-archive-service.js';
+export declare class FileContextTreeArchiveService implements IContextTreeArchiveService {
+    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.
+     */
+    private parseScoring;
+    /**
+     * Recursively scan context tree for archive candidates.
+     */
+    private scanForCandidates;
+}

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

@@ -0,0 +1,219 @@
+/* eslint-disable camelcase */
+/**
+ * File-based implementation of IContextTreeArchiveService.
+ *
+ * Archives low-importance context entries into _archived/ with:
+ * - .full.md: lossless preserved original content
+ * - .stub.md: searchable ghost cue (~220 tokens) with lineage pointers
+ *
+ * Archive naming preserves relative paths to avoid collisions:
+ *   auth/jwt-tokens/refresh-flow.md → _archived/auth/jwt-tokens/refresh-flow.stub.md
+ *
+ * Fail-open: any error during ghost cue generation falls back to deterministic truncation.
+ */
+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 { 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 {
+    async archiveEntry(relativePath, agent, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const originalFullPath = join(contextTreeDir, relativePath);
+        // Read original content
+        const content = await readFile(originalFullPath, 'utf8');
+        const originalTokenCount = estimateTokens(content);
+        // Compute archive paths: replace extension with .stub.md / .full.md
+        const pathWithoutExt = relativePath.slice(0, -extname(relativePath).length);
+        const stubRelPath = join(ARCHIVE_DIR, `${pathWithoutExt}${STUB_EXTENSION}`);
+        const fullRelPath = join(ARCHIVE_DIR, `${pathWithoutExt}${FULL_ARCHIVE_EXTENSION}`);
+        const stubFullPath = join(contextTreeDir, stubRelPath);
+        const fullFullPath = join(contextTreeDir, fullRelPath);
+        // Create parent directories under _archived/
+        await mkdir(dirname(stubFullPath), { recursive: true });
+        // Write .full.md — verbatim original content (lossless)
+        await writeFile(fullFullPath, content, 'utf8');
+        // 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);
+        // Write .stub.md with archive stub frontmatter
+        const stubContent = generateArchiveStubContent({
+            evicted_at: new Date().toISOString(),
+            evicted_importance: importance,
+            original_path: relativePath,
+            original_token_count: originalTokenCount,
+            points_to: toUnixPath(fullRelPath),
+            type: 'archive_stub',
+        }, ghostCue);
+        await writeFile(stubFullPath, stubContent, 'utf8');
+        // Delete original file
+        await unlink(originalFullPath);
+        return {
+            fullPath: toUnixPath(fullRelPath),
+            ghostCueTokenCount,
+            originalPath: relativePath,
+            stubPath: toUnixPath(stubRelPath),
+        };
+    }
+    async drillDown(stubPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const stubFullPath = join(contextTreeDir, stubPath);
+        // Parse stub to get points_to
+        const stubContent = await readFile(stubFullPath, 'utf8');
+        const fm = parseArchiveStubFrontmatter(stubContent);
+        if (!fm) {
+            throw new Error(`Invalid archive stub: ${stubPath}`);
+        }
+        // Read full content
+        const fullPath = join(contextTreeDir, fm.points_to);
+        const fullContent = await readFile(fullPath, 'utf8');
+        return {
+            fullContent,
+            originalPath: fm.original_path,
+            tokenCount: estimateTokens(fullContent),
+        };
+    }
+    async findArchiveCandidates(directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const candidates = [];
+        await this.scanForCandidates(contextTreeDir, contextTreeDir, candidates);
+        return candidates;
+    }
+    async restoreEntry(stubPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const stubFullPath = join(contextTreeDir, stubPath);
+        // Parse stub to get original_path and points_to
+        const stubContent = await readFile(stubFullPath, 'utf8');
+        const fm = parseArchiveStubFrontmatter(stubContent);
+        if (!fm) {
+            throw new Error(`Invalid archive stub: ${stubPath}`);
+        }
+        // Read full content
+        const fullPath = join(contextTreeDir, fm.points_to);
+        const fullContent = await readFile(fullPath, 'utf8');
+        // Write to original path (restore)
+        const restoredPath = join(contextTreeDir, fm.original_path);
+        await mkdir(dirname(restoredPath), { recursive: true });
+        await writeFile(restoredPath, fullContent, 'utf8');
+        // Delete stub and full archive files
+        await unlink(stubFullPath);
+        await unlink(fullPath);
+        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.
+     */
+    async generateGhostCue(agent, content) {
+        try {
+            const taskId = `ghost_cue_${Date.now()}`;
+            const sessionId = await agent.createTaskSession(taskId, 'query');
+            try {
+                const prompt = `Summarize the following knowledge entry in ~${DEFAULT_GHOST_CUE_MAX_TOKENS} tokens or less. Output ONLY the summary. Preserve key entity names and relationships.
+
+<content>
+${content.slice(0, 8000)}
+</content>`;
+                const response = await agent.executeOnSession(sessionId, prompt, {
+                    executionContext: {
+                        clearHistory: true,
+                        commandType: 'query',
+                        maxIterations: 1,
+                        maxTokens: DEFAULT_GHOST_CUE_MAX_TOKENS * 4, // chars ≈ tokens * 4
+                        temperature: 0.3,
+                    },
+                    taskId,
+                });
+                if (response && response.trim().length > 20) {
+                    return response.trim();
+                }
+            }
+            finally {
+                await agent.deleteTaskSession(sessionId);
+            }
+        }
+        catch {
+            // Fall through to deterministic fallback
+        }
+        // Deterministic fallback: truncate content
+        return `${content.replaceAll(/\s+/g, ' ').trim().slice(0, 320)}...`;
+    }
+    /**
+     * Parse FrontmatterScoring fields from content frontmatter.
+     */
+    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;
+    }
+    /**
+     * Recursively scan context tree for archive candidates.
+     */
+    async scanForCandidates(currentDir, contextTreeDir, candidates) {
+        const { readdir: readdirFs } = await import('node:fs/promises');
+        let entries;
+        try {
+            entries = await readdirFs(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        /* eslint-disable no-await-in-loop */
+        for (const entry of entries) {
+            const entryName = entry.name;
+            const fullPath = join(currentDir, entryName);
+            if (entry.isDirectory()) {
+                if (entryName === ARCHIVE_DIR)
+                    continue;
+                await this.scanForCandidates(fullPath, contextTreeDir, candidates);
+            }
+            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);
+                    // Only archive draft entries below importance threshold
+                    if (scoring.maturity !== 'draft')
+                        continue;
+                    const daysSinceUpdate = scoring.updatedAt
+                        ? (now - new Date(scoring.updatedAt).getTime()) / (1000 * 60 * 60 * 24)
+                        : 0;
+                    const decayed = applyDecay(scoring, daysSinceUpdate);
+                    if ((decayed.importance ?? 50) < ARCHIVE_IMPORTANCE_THRESHOLD) {
+                        candidates.push(relativePath);
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+}