@phuetz/code-buddy 1.2.0 → 1.3.0

package/dist/context/jit-context.d.ts

@@ -1,24 +1,22 @@
 /**
  * JIT (Just-In-Time) Context Discovery
  *
- * Dynamically loads .codebuddy/ context files when tools access
- * subdirectories. Context grows organically as the agent explores,
- * rather than loading everything at startup.
+ * When a tool accesses a path, this loads the instruction files in that
+ * subtree that weren't already injected at startup (delegated to the unified
+ * `project-context` loader, sharing its dedup registry), plus two JIT-only
+ * concerns: auto-discovered doc pages (DOC_DIR_MAP) and path-scoped rules.
  *
- * Inspired by Gemini CLI's jit-context.ts
+ * Inspired by Gemini CLI's jit-context.
  */
 export declare const JIT_CONTEXT_PREFIX = "\n\n--- Discovered Context ---\n";
 export declare const JIT_CONTEXT_SUFFIX = "\n--- End Context ---";
 /**
- * Clear loaded paths cache (for testing).
+ * Clear caches (for testing / `/context reload`). Resets both the doc dedup set
+ * and the active context registry so the next pass re-scans from scratch.
  */
 export declare function clearJitCache(): void;
 /**
- * Discover and load context files for a given accessed path.
- *
- * Walks upward from the accessed file's directory to the project root,
- * checking for context files at each level. Only loads files that
- * haven't been loaded before in this session.
+ * Discover and load JIT context for a given accessed path.
  *
  * @param accessedPath - The file/directory path being accessed by a tool
  * @param projectRoot - The project root directory (stop walking here)

package/dist/context/jit-context.js

@@ -1,28 +1,18 @@
 /**
  * JIT (Just-In-Time) Context Discovery
  *
- * Dynamically loads .codebuddy/ context files when tools access
- * subdirectories. Context grows organically as the agent explores,
- * rather than loading everything at startup.
+ * When a tool accesses a path, this loads the instruction files in that
+ * subtree that weren't already injected at startup (delegated to the unified
+ * `project-context` loader, sharing its dedup registry), plus two JIT-only
+ * concerns: auto-discovered doc pages (DOC_DIR_MAP) and path-scoped rules.
  *
- * Inspired by Gemini CLI's jit-context.ts
+ * Inspired by Gemini CLI's jit-context.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { logger } from '../utils/logger.js';
 import { discoverRulesForPath } from './rules-loader.js';
-import { shouldExcludeInstructionFile } from './instruction-excludes.js';
-import { resolveImportDirectives } from './import-directive-parser.js';
-/** Context file names to discover */
-const CONTEXT_FILES = [
-    'CODEBUDDY.md',
-    'CONTEXT.md',
-    'INSTRUCTIONS.md',
-    'AGENTS.md',
-    'README.md',
-];
-/** Directories that may contain context files */
-const CONTEXT_DIRS = ['.codebuddy', '.claude'];
+import { resolveJitContext, getActiveContextRegistry } from './project-context.js';
 /**
  * Map of source directory prefixes → relevant doc page slugs.
  * When a tool accesses a path under a key, the matching doc is auto-discovered.
@@ -45,26 +35,22 @@ const DOC_DIR_MAP = {
     'src/checkpoints': ['architecture'],
     'tests': ['testing'],
 };
-/** Set of already-loaded paths (avoid re-loading) */
+/** Set of already-loaded doc paths (instruction files dedup via the registry). */
 const loadedPaths = new Set();
 /** Maximum context size per discovery (chars) */
 const MAX_JIT_CONTEXT_CHARS = 4000;
-/** Maximum directory depth to traverse upward */
-const MAX_UPWARD_DEPTH = 10;
 export const JIT_CONTEXT_PREFIX = '\n\n--- Discovered Context ---\n';
 export const JIT_CONTEXT_SUFFIX = '\n--- End Context ---';
 /**
- * Clear loaded paths cache (for testing).
+ * Clear caches (for testing / `/context reload`). Resets both the doc dedup set
+ * and the active context registry so the next pass re-scans from scratch.
  */
 export function clearJitCache() {
     loadedPaths.clear();
+    getActiveContextRegistry().clear();
 }
 /**
- * Discover and load context files for a given accessed path.
- *
- * Walks upward from the accessed file's directory to the project root,
- * checking for context files at each level. Only loads files that
- * haven't been loaded before in this session.
+ * Discover and load JIT context for a given accessed path.
  *
  * @param accessedPath - The file/directory path being accessed by a tool
  * @param projectRoot - The project root directory (stop walking here)
@@ -74,84 +60,18 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
     try {
         const normalizedRoot = path.resolve(projectRoot);
         const normalizedPath = path.resolve(accessedPath);
-        // Start from the accessed file's directory
-        let currentDir = fs.existsSync(normalizedPath) && fs.statSync(normalizedPath).isDirectory()
-            ? normalizedPath
-            : path.dirname(normalizedPath);
         const discoveredContent = [];
-        let depth = 0;
-        while (depth < MAX_UPWARD_DEPTH) {
-            // Check if we've gone above the project root
-            if (!currentDir.startsWith(normalizedRoot) && currentDir !== normalizedRoot) {
-                break;
-            }
-            // Look for context files in this directory
-            for (const contextFile of CONTEXT_FILES) {
-                const filePath = path.join(currentDir, contextFile);
-                if (!loadedPaths.has(filePath) && fs.existsSync(filePath)) {
-                    // CC10: Check instruction excludes
-                    if (shouldExcludeInstructionFile(filePath, normalizedRoot)) {
-                        logger.debug(`JIT context: excluded ${path.relative(normalizedRoot, filePath)}`);
-                        loadedPaths.add(filePath); // Mark as "seen" to avoid re-checking
-                        continue;
-                    }
-                    try {
-                        let content = fs.readFileSync(filePath, 'utf-8');
-                        if (content.trim()) {
-                            // CC9: Resolve @import directives
-                            content = resolveImportDirectives(content, {
-                                baseDir: path.dirname(filePath),
-                                projectRoot: normalizedRoot,
-                            });
-                            const relativePath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
-                            discoveredContent.push(`[${relativePath}]\n${content.trim()}`);
-                            loadedPaths.add(filePath);
-                            logger.debug(`JIT context: loaded ${relativePath}`);
-                        }
-                    }
-                    catch { /* read error — skip */ }
-                }
-            }
-            // Also check .codebuddy/ and .claude/ subdirectories
-            for (const contextDir of CONTEXT_DIRS) {
-                const dirPath = path.join(currentDir, contextDir);
-                if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
-                    for (const contextFile of CONTEXT_FILES) {
-                        const filePath = path.join(dirPath, contextFile);
-                        if (!loadedPaths.has(filePath) && fs.existsSync(filePath)) {
-                            // CC10: Check instruction excludes
-                            if (shouldExcludeInstructionFile(filePath, normalizedRoot)) {
-                                logger.debug(`JIT context: excluded ${path.relative(normalizedRoot, filePath)}`);
-                                loadedPaths.add(filePath);
-                                continue;
-                            }
-                            try {
-                                let content = fs.readFileSync(filePath, 'utf-8');
-                                if (content.trim()) {
-                                    // CC9: Resolve @import directives
-                                    content = resolveImportDirectives(content, {
-                                        baseDir: path.dirname(filePath),
-                                        projectRoot: normalizedRoot,
-                                    });
-                                    const relativePath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
-                                    discoveredContent.push(`[${relativePath}]\n${content.trim()}`);
-                                    loadedPaths.add(filePath);
-                                    logger.debug(`JIT context: loaded ${relativePath}`);
-                                }
-                            }
-                            catch { /* read error — skip */ }
-                        }
-                    }
-                }
-            }
-            // Move up
-            const parent = path.dirname(currentDir);
-            if (parent === currentDir)
-                break; // reached filesystem root
-            currentDir = parent;
-            depth++;
+        // 1. Instruction files in the accessed subtree, via the unified loader.
+        //    The shared active registry skips anything already injected at startup,
+        //    so the same AGENTS.md/CODEBUDDY.md is never duplicated.
+        const ctx = resolveJitContext(accessedPath, {
+            projectRoot: normalizedRoot,
+            registry: getActiveContextRegistry(),
+        });
+        if (ctx.text) {
+            discoveredContent.push(ctx.text);
         }
-        // Auto-discover relevant doc pages based on accessed path
+        // 2. Auto-discover relevant doc pages based on the accessed path.
         const relativePath = path.relative(normalizedRoot, normalizedPath).replace(/\\/g, '/');
         for (const [prefix, slugPatterns] of Object.entries(DOC_DIR_MAP)) {
             if (!relativePath.startsWith(prefix))
@@ -160,16 +80,16 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
             if (!fs.existsSync(docsDir))
                 break;
             try {
-                const docFiles = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+                const docFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith('.md'));
                 for (const pattern of slugPatterns) {
-                    const match = docFiles.find(f => f.includes(pattern));
+                    const match = docFiles.find((f) => f.includes(pattern));
                     if (!match)
                         continue;
                     const docPath = path.join(docsDir, match);
                     if (loadedPaths.has(docPath))
                         continue;
                     const content = fs.readFileSync(docPath, 'utf-8');
-                    // Only inject the first 2 sections (title + first H2) to stay compact
+                    // Only inject the first 2 sections (title + first H2) to stay compact.
                     const sections = content.split(/(?=^## )/m);
                     const compact = sections.slice(0, 2).join('').trim();
                     if (compact) {
@@ -181,10 +101,12 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
                     break; // One doc per prefix
                 }
             }
-            catch { /* docs dir not readable */ }
+            catch {
+                /* docs dir not readable */
+            }
             break; // One prefix match
         }
-        // Discover path-scoped rules matching this access
+        // 3. Path-scoped rules matching this access.
         const rulesContext = discoverRulesForPath(accessedPath, projectRoot);
         if (rulesContext) {
             discoveredContent.push(rulesContext);

package/dist/context/project-context.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Project Context — the canonical hierarchical loader for project-instruction
+ * files (the AGENTS.md / CLAUDE.md / GEMINI.md / CODEBUDDY.md hierarchy).
+ *
+ * Single source of truth that replaces the previously fragmented readers
+ * (jit-context, bootstrap-loader's hierarchical walk, context-files). It owns:
+ *   - the config-driven accepted-filename list (`loadContextConfig`),
+ *   - the per-directory probe (incl. `.codebuddy/` + `.claude/` descent),
+ *   - variant precedence (`<name>.local.md` > `<name>.override.md` > `<name>`),
+ *   - `@import` resolution (code-fence-safe), token/byte budgeting,
+ *   - realpath dedup shared across the startup pass and JIT (the `ContextRegistry`).
+ *
+ * Precedence (documented once, here):
+ *   - Tiers: global (`~/.codebuddy/`) is appended FIRST (lowest precedence),
+ *     then the project hierarchy from project-root DOWN to cwd. Files closer to
+ *     cwd appear later in the text → win on conflict (Codex AGENTS.md model).
+ *   - Within a directory, every accepted filename present is COMPOSED (so
+ *     `CODEBUDDY.md` extends `AGENTS.md`), in the configured order.
+ *   - Within a (directory, name), the first existing variant wins and REPLACES
+ *     the base: `<name>.local.md` (gitignored) > `<name>.override.md` > `<name>`.
+ *   - Dedup key is `fs.realpathSync` so a `CLAUDE.md`/`GEMINI.md` symlinked to
+ *     `AGENTS.md` collapses to one injection.
+ *
+ * Determinism: iteration is over the fixed `dirs × probeDirs × names` product
+ * with relative origin headers and no mtimes — the rendered text is byte-stable
+ * across runs, which keeps prompt caching intact.
+ */
+export type ContextTier = 'global' | 'hierarchy' | 'jit';
+export type ContextVariant = 'base' | 'override' | 'local';
+export interface ContextSource {
+    /** Absolute path of the loaded file. */
+    path: string;
+    /** `fs.realpathSync` of `path` — the dedup key. */
+    realpath: string;
+    /** Display path (relative to project root; `~/.codebuddy/...` for global). */
+    relPath: string;
+    tier: ContextTier;
+    variant: ContextVariant;
+    /** Size of this source's rendered body (chars). */
+    bytes: number;
+    /** Whether this source was truncated to fit the budget. */
+    truncated: boolean;
+}
+export interface ResolvedContext {
+    /** Merged, header-decorated text, ready to inject. */
+    text: string;
+    sources: ContextSource[];
+    bytes: number;
+    truncated: boolean;
+}
+export interface ResolveOptions {
+    cwd?: string;
+    /** Project root; resolved via ROOT_MARKERS when omitted. */
+    projectRoot?: string;
+    /** Shared dedup registry (startup ↔ JIT). A private one is used if omitted. */
+    registry?: ContextRegistry;
+    /** Byte budget override (defaults to config `maxBytes` / `jitMaxBytes`). */
+    budgetBytes?: number;
+    /** Accepted filenames override (defaults to config). */
+    fileNames?: string[];
+    /** Home-dir override (for testing). */
+    homeDir?: string;
+}
+/** Tracks realpaths already injected so a file is never loaded twice. */
+export declare class ContextRegistry {
+    private readonly seen;
+    has(realpath: string): boolean;
+    add(realpath: string): void;
+    clear(): void;
+    get size(): number;
+}
+export declare function createContextRegistry(): ContextRegistry;
+export declare function setActiveContextRegistry(registry: ContextRegistry): void;
+export declare function getActiveContextRegistry(): ContextRegistry;
+/** Project root via ROOT_MARKERS, walking up from `cwd` (null if none found). */
+export declare function findProjectRoot(cwd: string, markers?: string[]): string | null;
+/** Accepted instruction filenames for a project (config-driven). */
+export declare function getAcceptedFileNames(projectRoot?: string): string[];
+/**
+ * Startup pass: global tier + the project hierarchy from root DOWN to cwd.
+ * Call once per prompt build. Populates `registry` (if given) so the later JIT
+ * pass skips files already in the system prompt.
+ */
+export declare function resolveProjectContext(opts?: ResolveOptions): ResolvedContext;
+/**
+ * JIT pass: when a tool touches `accessedPath`, load any context files along its
+ * directory chain (root → accessed dir) that weren't already injected at
+ * startup (skipped via the shared `registry`). Smaller per-touch budget.
+ */
+export declare function resolveJitContext(accessedPath: string, opts?: ResolveOptions): ResolvedContext;

package/dist/context/project-context.js

@@ -0,0 +1,295 @@
+/**
+ * Project Context — the canonical hierarchical loader for project-instruction
+ * files (the AGENTS.md / CLAUDE.md / GEMINI.md / CODEBUDDY.md hierarchy).
+ *
+ * Single source of truth that replaces the previously fragmented readers
+ * (jit-context, bootstrap-loader's hierarchical walk, context-files). It owns:
+ *   - the config-driven accepted-filename list (`loadContextConfig`),
+ *   - the per-directory probe (incl. `.codebuddy/` + `.claude/` descent),
+ *   - variant precedence (`<name>.local.md` > `<name>.override.md` > `<name>`),
+ *   - `@import` resolution (code-fence-safe), token/byte budgeting,
+ *   - realpath dedup shared across the startup pass and JIT (the `ContextRegistry`).
+ *
+ * Precedence (documented once, here):
+ *   - Tiers: global (`~/.codebuddy/`) is appended FIRST (lowest precedence),
+ *     then the project hierarchy from project-root DOWN to cwd. Files closer to
+ *     cwd appear later in the text → win on conflict (Codex AGENTS.md model).
+ *   - Within a directory, every accepted filename present is COMPOSED (so
+ *     `CODEBUDDY.md` extends `AGENTS.md`), in the configured order.
+ *   - Within a (directory, name), the first existing variant wins and REPLACES
+ *     the base: `<name>.local.md` (gitignored) > `<name>.override.md` > `<name>`.
+ *   - Dedup key is `fs.realpathSync` so a `CLAUDE.md`/`GEMINI.md` symlinked to
+ *     `AGENTS.md` collapses to one injection.
+ *
+ * Determinism: iteration is over the fixed `dirs × probeDirs × names` product
+ * with relative origin headers and no mtimes — the rendered text is byte-stable
+ * across runs, which keeps prompt caching intact.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { logger } from '../utils/logger.js';
+import { resolveImportDirectives } from './import-directive-parser.js';
+import { loadContextConfig, shouldExcludeInstructionFile, } from './instruction-excludes.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Project-root markers, walked upward from cwd. */
+const ROOT_MARKERS = ['.git', 'package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.hg'];
+const MAX_HIERARCHY_DEPTH = 10;
+/** Subdirectories probed inside every level of the hierarchy. */
+const SUBDIR_PROBES = ['.codebuddy', '.claude'];
+const TRUNCATION_MARKER = '\n\n... (truncated)';
+// ============================================================================
+// Dedup registry (shared between the startup pass and JIT)
+// ============================================================================
+/** Tracks realpaths already injected so a file is never loaded twice. */
+export class ContextRegistry {
+    seen = new Set();
+    has(realpath) {
+        return this.seen.has(realpath);
+    }
+    add(realpath) {
+        this.seen.add(realpath);
+    }
+    clear() {
+        this.seen.clear();
+    }
+    get size() {
+        return this.seen.size;
+    }
+}
+export function createContextRegistry() {
+    return new ContextRegistry();
+}
+// Module-level "active" registry. The prompt builder publishes its per-build
+// registry here (`setActiveContextRegistry`) so the standalone JIT pass — which
+// has no handle to the PromptBuilder — can dedup against files already injected
+// at startup. Defaults to a persistent registry until the first build.
+let activeRegistry = new ContextRegistry();
+export function setActiveContextRegistry(registry) {
+    activeRegistry = registry;
+}
+export function getActiveContextRegistry() {
+    return activeRegistry;
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/** Project root via ROOT_MARKERS, walking up from `cwd` (null if none found). */
+export function findProjectRoot(cwd, markers = ROOT_MARKERS) {
+    let dir = path.resolve(cwd);
+    let depth = 0;
+    while (depth < MAX_HIERARCHY_DEPTH) {
+        for (const marker of markers) {
+            try {
+                if (fs.existsSync(path.join(dir, marker)))
+                    return dir;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        depth++;
+    }
+    return null;
+}
+/** Accepted instruction filenames for a project (config-driven). */
+export function getAcceptedFileNames(projectRoot = process.cwd()) {
+    return loadContextConfig(projectRoot).fileNames;
+}
+/**
+ * Startup pass: global tier + the project hierarchy from root DOWN to cwd.
+ * Call once per prompt build. Populates `registry` (if given) so the later JIT
+ * pass skips files already in the system prompt.
+ */
+export function resolveProjectContext(opts = {}) {
+    const cwd = path.resolve(opts.cwd ?? process.cwd());
+    const root = path.resolve(opts.projectRoot ?? findProjectRoot(cwd) ?? cwd);
+    const cfg = loadContextConfig(root);
+    const names = opts.fileNames ?? cfg.fileNames;
+    const homeDir = opts.homeDir ?? os.homedir();
+    const registry = opts.registry ?? new ContextRegistry();
+    const loaded = [];
+    // Tier 1 — global (~/.codebuddy/), lowest precedence (appended first).
+    const globalDir = path.join(homeDir, '.codebuddy');
+    loaded.push(...collectDir(globalDir, 'global', names, root, registry, homeDir, cfg));
+    // Tier 2 — hierarchy, project root → cwd inclusive (closest appended last).
+    for (const dir of getDirectoryChain(root, cwd)) {
+        for (const probe of [dir, ...SUBDIR_PROBES.map((s) => path.join(dir, s))]) {
+            loaded.push(...collectDir(probe, 'hierarchy', names, root, registry, homeDir, cfg));
+        }
+    }
+    return budgetMerge(loaded, opts.budgetBytes ?? cfg.maxBytes);
+}
+/**
+ * JIT pass: when a tool touches `accessedPath`, load any context files along its
+ * directory chain (root → accessed dir) that weren't already injected at
+ * startup (skipped via the shared `registry`). Smaller per-touch budget.
+ */
+export function resolveJitContext(accessedPath, opts = {}) {
+    const accessedDir = path.dirname(path.resolve(accessedPath));
+    const root = path.resolve(opts.projectRoot ?? findProjectRoot(accessedDir) ?? accessedDir);
+    const cfg = loadContextConfig(root);
+    const names = opts.fileNames ?? cfg.fileNames;
+    const homeDir = opts.homeDir ?? os.homedir();
+    const registry = opts.registry ?? new ContextRegistry();
+    const loaded = [];
+    for (const dir of getDirectoryChain(root, accessedDir)) {
+        for (const probe of [dir, ...SUBDIR_PROBES.map((s) => path.join(dir, s))]) {
+            loaded.push(...collectDir(probe, 'jit', names, root, registry, homeDir, cfg));
+        }
+    }
+    return budgetMerge(loaded, opts.budgetBytes ?? cfg.jitMaxBytes);
+}
+/** Directory chain from `root` to `target` (inclusive). */
+function getDirectoryChain(root, target) {
+    const resolved = path.resolve(target);
+    const resolvedRoot = path.resolve(root);
+    const chain = [resolvedRoot];
+    const rel = path.relative(resolvedRoot, resolved);
+    if (!rel || rel.startsWith('..'))
+        return chain;
+    let current = resolvedRoot;
+    for (const seg of rel.split(path.sep).filter(Boolean)) {
+        current = path.join(current, seg);
+        chain.push(current);
+    }
+    return chain;
+}
+/** Variant filenames for a base name, most-specific first. */
+function variantNames(base) {
+    const ext = path.extname(base); // '.md'
+    const stem = ext ? base.slice(0, base.length - ext.length) : base;
+    return [
+        { name: `${stem}.local${ext}`, variant: 'local' },
+        { name: `${stem}.override${ext}`, variant: 'override' },
+        { name: base, variant: 'base' },
+    ];
+}
+/**
+ * Collect every accepted instruction file present in one directory (composed),
+ * applying variant precedence, excludes, realpath dedup and @import resolution.
+ */
+function collectDir(probeDir, tier, names, root, registry, homeDir, cfg) {
+    const out = [];
+    const isGlobal = tier === 'global';
+    for (const base of names) {
+        // First existing variant wins (local > override > base) and replaces it.
+        let chosen = null;
+        for (const v of variantNames(base)) {
+            const filePath = path.join(probeDir, v.name);
+            try {
+                if (fs.statSync(filePath).isFile()) {
+                    chosen = { filePath, variant: v.variant };
+                    break;
+                }
+            }
+            catch {
+                /* not present */
+            }
+        }
+        if (!chosen)
+            continue;
+        // Project files honor codebuddyMdExcludes; global files are never excluded.
+        if (!isGlobal && shouldExcludeInstructionFile(chosen.filePath, root))
+            continue;
+        let realpath;
+        try {
+            realpath = fs.realpathSync(chosen.filePath);
+        }
+        catch {
+            realpath = chosen.filePath;
+        }
+        if (registry.has(realpath))
+            continue;
+        let body;
+        try {
+            body = fs.readFileSync(chosen.filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (!body.trim())
+            continue;
+        // User-authored, trusted files: warn (don't drop) on shell-exec-like
+        // patterns — dropping would break legitimate AGENTS.md that documents them.
+        if (containsDangerousPatterns(body)) {
+            logger.warn(`Context file ${chosen.filePath} contains shell-exec-like patterns; loading anyway (user-authored).`);
+        }
+        body = resolveImportDirectives(body, {
+            baseDir: probeDir,
+            projectRoot: root,
+            homeDir,
+            maxDepth: cfg.importMaxDepth,
+            maxBytes: cfg.importMaxBytes,
+        });
+        registry.add(realpath);
+        out.push({
+            path: chosen.filePath,
+            realpath,
+            relPath: displayPath(chosen.filePath, root, homeDir, isGlobal),
+            tier,
+            variant: chosen.variant,
+            body,
+        });
+    }
+    return out;
+}
+/** Deterministic, abs-path-free display path for the origin header. */
+function displayPath(filePath, root, homeDir, isGlobal) {
+    if (isGlobal) {
+        const rel = path.relative(path.join(homeDir, '.codebuddy'), filePath).replace(/\\/g, '/');
+        return `~/.codebuddy/${rel}`;
+    }
+    return path.relative(root, filePath).replace(/\\/g, '/') || path.basename(filePath);
+}
+/** Merge loaded sources under a budget, truncating the overflowing source. */
+function budgetMerge(sources, budget) {
+    let total = 0;
+    let truncated = false;
+    const parts = [];
+    const outSources = [];
+    for (const s of sources) {
+        if (total >= budget) {
+            truncated = true;
+            break;
+        }
+        let body = s.body;
+        let sourceTruncated = false;
+        const remaining = budget - total;
+        if (body.length > remaining) {
+            body = body.slice(0, remaining) + TRUNCATION_MARKER;
+            sourceTruncated = true;
+            truncated = true;
+        }
+        parts.push(`<!-- context: ${s.relPath} (${s.tier}) -->\n${body}`);
+        total += body.length;
+        outSources.push({
+            path: s.path,
+            realpath: s.realpath,
+            relPath: s.relPath,
+            tier: s.tier,
+            variant: s.variant,
+            bytes: body.length,
+            truncated: sourceTruncated,
+        });
+    }
+    return { text: parts.join('\n\n'), sources: outSources, bytes: total, truncated };
+}
+/** Shell-exec-like patterns — used to WARN (not drop) on user-authored files. */
+function containsDangerousPatterns(content) {
+    return [
+        /\beval\s*\(/,
+        /\bnew\s+Function\s*\(/,
+        /\brequire\s*\(\s*['"]child_process['"]\s*\)/,
+        /\bexec(?:Sync)?\s*\(/,
+        /\bspawn(?:Sync)?\s*\(/,
+        /<script\b/i,
+    ].some((p) => p.test(content));
+}
+//# sourceMappingURL=project-context.js.map

package/dist/daemon/autonomous-loop.d.ts

@@ -37,6 +37,15 @@ export interface TaskExecutionResult {
     output?: string;
 }
 export type TaskExecutor = (task: ColabTask, model: AutonomousModelChoice) => Promise<TaskExecutionResult>;
+/**
+ * Idle-time self-improvement hook. Runs ONE bounded improvement cycle and reports
+ * whether it kept anything. Injected so the loop stays testable and the heavy
+ * engine is swappable; the default (lazy) hook runs the tool-improvement engine.
+ */
+export type SelfImproveHook = () => Promise<{
+    applied: boolean;
+    detail: string;
+}>;
 export interface AutonomousLoopConfig {
     store: FleetColabStore;
     tierConfig: ModelTierConfig;
@@ -49,9 +58,19 @@ export interface AutonomousLoopConfig {
      * goal-mode tasks complete like plain tasks (no judge gate).
      */
     goalJudge?: ColabGoalJudge;
+    /**
+     * Idle-time self-improvement. When the queue is empty AND
+     * `CODEBUDDY_SELF_IMPROVE=true`, run one bounded improvement cycle (cooldown-
+     * gated). Injected for tests; defaults to the tool-improvement engine.
+     */
+    selfImprove?: SelfImproveHook;
+    /** Minimum ms between idle self-improvement cycles (default 15 min). */
+    selfImproveCooldownMs?: number;
+    /** Clock for the cooldown (tests). Default Date.now. */
+    now?: () => number;
 }
 export interface TickResult {
-    outcome: 'disabled' | 'idle' | 'completed' | 'failed' | 'saturated' | 'goal_continue' | 'goal_blocked';
+    outcome: 'disabled' | 'idle' | 'completed' | 'failed' | 'saturated' | 'goal_continue' | 'goal_blocked' | 'self_improved';
     taskId?: string;
     taskTitle?: string;
     model?: AutonomousModelChoice;
@@ -71,7 +90,18 @@ export declare class FleetAutonomousLoop {
      */
     private readonly failures;
     private readonly goalJudge;
+    private readonly selfImprove;
+    private readonly selfImproveCooldownMs;
+    private readonly now;
+    private lastSelfImproveAt;
     constructor(config: AutonomousLoopConfig);
+    /**
+     * Idle hook: when the queue is empty and self-improvement is opted in, run one
+     * bounded, cooldown-gated improvement cycle instead of sitting fully idle.
+     * Double-gated (idle + CODEBUDDY_SELF_IMPROVE) and bounded (cooldown + the
+     * engine no-ops once seed scenarios are covered). Never throws.
+     */
+    private maybeSelfImprove;
     /** Run a single autonomous tick. Never throws — failures are logged + reported. */
     tick(): Promise<TickResult>;
     /**