salmon-loop 0.4.1 → 0.5.0

package/dist/core/context/ast/skeleton-extractor.js

@@ -0,0 +1,225 @@
+import { AstParser } from '../../ast/parser.js';
+import { createLanguageSupportOrchestrator } from '../../language-support/orchestrator.js';
+import { getLogger } from '../../observability/logger.js';
+import { tryGetPluginRegistry } from '../../plugin/registry.js';
+const MAX_SKELETON_LINES = 200;
+/**
+ * Top-level declaration node types that should be included in the skeleton
+ * even if not captured by the definitions query. This handles imports, exports,
+ * and other top-level statements.
+ */
+const TOP_LEVEL_INCLUDE_TYPES = new Set([
+    // JS/TS
+    'import_statement',
+    'export_statement',
+    'import_declaration',
+    'export_declaration',
+    // Python
+    'import_from_statement',
+    // Rust
+    'use_declaration',
+    'extern_crate_declaration',
+    // Go
+    'import_declaration',
+    'package_clause',
+]);
+/**
+ * Extract a cross-language code skeleton using tree-sitter AST.
+ *
+ * For each definition (function, class, method, type, etc.), the skeleton
+ * includes only the signature line — not the body. Imports and top-level
+ * declarations are preserved in full.
+ *
+ * Falls back to undefined if tree-sitter parsing fails (e.g., no grammar
+ * installed for the language). The caller should fall back to regex-based
+ * outlineSource in that case.
+ */
+export async function extractSkeleton(sourceCode, lang) {
+    const plugin = tryGetPluginRegistry()?.getByExtension(`.${lang}`) ?? tryGetPluginRegistry()?.getById(lang);
+    if (!plugin)
+        return undefined;
+    try {
+        const tree = await AstParser.parse(sourceCode, lang);
+        if (!tree?.rootNode)
+            return undefined;
+        const lines = sourceCode.split('\n');
+        const includeLines = new Set();
+        const signatureLines = new Map(); // startRow -> signatureEndRow
+        // 1. Collect definition nodes via the plugin's definitions query
+        const orchestrator = createLanguageSupportOrchestrator();
+        const queryStr = await orchestrator.getASTQuery(lang, 'definitions');
+        if (queryStr) {
+            const captures = await AstParser.queryCapturesFromQuery(tree, lang, queryStr);
+            for (const capture of captures) {
+                if (capture.name === 'def') {
+                    const sigEnd = findSignatureEnd(lines, capture.line - 1);
+                    signatureLines.set(capture.line - 1, sigEnd);
+                }
+            }
+        }
+        // 2. Walk top-level nodes for imports and declarations not caught by the query
+        for (const child of tree.rootNode.children ?? []) {
+            const nodeType = child.type;
+            const startRow = child.startPosition.row;
+            if (TOP_LEVEL_INCLUDE_TYPES.has(nodeType)) {
+                // Include import/export lines in full
+                for (let r = child.startPosition.row; r <= child.endPosition.row; r++) {
+                    includeLines.add(r);
+                }
+            }
+            else if (signatureLines.has(startRow)) {
+                // Already captured by definitions query — include signature only
+                // (handled below)
+            }
+            else if (isLikelyDeclaration(nodeType)) {
+                // Top-level declaration not caught by definitions query
+                const sigEnd = findSignatureEnd(lines, startRow);
+                signatureLines.set(startRow, sigEnd);
+            }
+        }
+        // 3. Also handle nested definitions (class methods, etc.)
+        collectNestedDefinitions(tree.rootNode, lines, signatureLines, 0);
+        // 4. Build the skeleton
+        const out = [];
+        const includedRows = new Set();
+        // First pass: include full import/export lines
+        for (const row of includeLines) {
+            if (out.length >= MAX_SKELETON_LINES)
+                break;
+            if (!includedRows.has(row)) {
+                out.push(lines[row]);
+                includedRows.add(row);
+            }
+        }
+        // Second pass: include signature lines from definitions
+        const sortedSigs = [...signatureLines.entries()].sort((a, b) => a[0] - b[0]);
+        for (const [startRow, sigEndRow] of sortedSigs) {
+            if (out.length >= MAX_SKELETON_LINES)
+                break;
+            for (let r = startRow; r <= sigEndRow; r++) {
+                if (out.length >= MAX_SKELETON_LINES)
+                    break;
+                if (!includedRows.has(r)) {
+                    out.push(lines[r]);
+                    includedRows.add(r);
+                }
+            }
+        }
+        const result = out.join('\n').trim();
+        return result.length > 0 ? result : undefined;
+    }
+    catch (error) {
+        // Tree-sitter parsing failed (no grammar, parse error, etc.)
+        getLogger().debug(`[SkeletonExtractor] parse failed: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Recursively collect nested definitions (e.g., class methods) that may not
+ * be captured by the top-level definitions query.
+ */
+function collectNestedDefinitions(node, lines, signatureLines, depth) {
+    if (depth > 3)
+        return; // Prevent deep recursion
+    for (const child of node.children ?? []) {
+        const startRow = child.startPosition.row;
+        if (isDefinitionNode(child.type) && !signatureLines.has(startRow)) {
+            const sigEnd = findSignatureEnd(lines, startRow);
+            signatureLines.set(startRow, sigEnd);
+        }
+        // Recurse into class/struct/impl bodies to find methods
+        if (isContainerNode(child.type)) {
+            collectNestedDefinitions(child, lines, signatureLines, depth + 1);
+        }
+    }
+}
+/**
+ * Find the last line of a definition's signature (before the body starts).
+ * For single-line definitions, returns startRow.
+ * For multi-line definitions, returns the line containing the body-starting token.
+ */
+function findSignatureEnd(lines, startRow) {
+    // Look up to 10 lines ahead for the body start
+    const maxLook = Math.min(startRow + 10, lines.length - 1);
+    for (let r = startRow; r <= maxLook; r++) {
+        const line = lines[r];
+        // C-family: body starts with '{'
+        if (line.includes('{'))
+            return r;
+        // Python: body starts with ':'
+        // Heuristic: the colon is at the end of a def/class/if/for/while line
+        if (/:\s*$/.test(line) && r > startRow)
+            return r;
+        // Single-line Python def: def foo(): pass
+        if (/:\s+\S/.test(line) && r === startRow)
+            return r;
+        // Rust: body starts with '{' or 'where' clause
+        if (line.includes('{'))
+            return r;
+    }
+    // Fallback: just the first line
+    return startRow;
+}
+/**
+ * Check if a node type is a definition-like node that should appear in skeleton.
+ */
+function isDefinitionNode(type) {
+    return (type.includes('function') ||
+        type.includes('method') ||
+        type.includes('class') ||
+        type.includes('interface') ||
+        type.includes('type_alias') ||
+        type.includes('type_definition') ||
+        type.includes('enum') ||
+        type.includes('struct') ||
+        type.includes('impl') ||
+        type.includes('trait') ||
+        type.includes('module') ||
+        type.includes('namespace') ||
+        type === 'decorated_definition' ||
+        type === 'function_definition' ||
+        type === 'async_function_definition' ||
+        type === 'class_definition');
+}
+/**
+ * Check if a node type is a container that may hold nested definitions.
+ */
+function isContainerNode(type) {
+    return (type.includes('class_body') ||
+        type.includes('interface_body') ||
+        type.includes('struct_body') ||
+        type.includes('impl_body') ||
+        type.includes('declaration_list') ||
+        type === 'block' ||
+        type === 'statement_block' ||
+        type === 'class_definition' ||
+        type === 'impl_item');
+}
+/**
+ * Check if a top-level node type looks like a declaration worth including.
+ */
+function isLikelyDeclaration(type) {
+    return (type.includes('declaration') ||
+        type.includes('definition') ||
+        type.includes('variable') ||
+        type.includes('const') ||
+        type.includes('let') ||
+        type.includes('type_alias') ||
+        type.includes('struct') ||
+        type.includes('enum') ||
+        type.includes('trait') ||
+        type.includes('impl'));
+}
+/**
+ * Detect the tree-sitter language ID from a file path.
+ * Returns undefined if no matching plugin is found.
+ */
+export function detectLang(filePath) {
+    const dotIndex = filePath.lastIndexOf('.');
+    if (dotIndex < 0)
+        return undefined;
+    const ext = filePath.slice(dotIndex).toLowerCase();
+    const plugin = tryGetPluginRegistry()?.getByExtension(ext);
+    return plugin?.meta.id;
+}
+//# sourceMappingURL=skeleton-extractor.js.map

package/dist/core/context/ast/source-outline.js

@@ -1,4 +1,25 @@
+import { extractSkeleton } from './skeleton-extractor.js';
 const MAX_OUTLINE_LINES = 200;
+/**
+ * Generate an outline/skeleton of source code.
+ *
+ * When a language plugin with tree-sitter support is available, uses AST-based
+ * skeleton extraction (signature-only for definitions, full lines for imports).
+ * Falls back to regex-based line filtering for unsupported languages.
+ */
+export async function outlineSourceAsync(sourceCode, lang) {
+    if (lang) {
+        const skeleton = await extractSkeleton(sourceCode, lang);
+        if (skeleton)
+            return skeleton;
+    }
+    return outlineSource(sourceCode);
+}
+/**
+ * Regex-based outline generator (fallback for unsupported languages).
+ * Recognizes JS/TS-style keywords: function, class, interface, type, enum,
+ * const/let/var declarations, import/export statements.
+ */
 export function outlineSource(sourceCode) {
     const lines = sourceCode.split('\n');
     const out = [];
@@ -16,7 +37,9 @@ export function outlineSource(sourceCode) {
             continue;
         }
         if (/^\s*(?:export\s+)?(?:declare\s+)?(interface|type|class|enum|function)\b/.test(line) ||
-            /^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z0-9_$]+\s*[:=]/.test(line)) {
+            /^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z0-9_$]+\s*[:=]/.test(line) ||
+            /^\s*(?:async\s+)?(?:def|class)\s+\w+/.test(line) ||
+            /^\s*(?:from|import)\s+\w+/.test(line)) {
             include(line);
         }
     }

package/dist/core/context/budget/dynamic-adjuster.js

@@ -1,8 +1,5 @@
-/**
- * Dynamic Budget Adjuster
- *
- * Collects runtime metrics and adjusts budget based on actual usage patterns.
- */
+import { getLogger } from '../../observability/logger.js';
+import { getEffectivenessTracker } from '../effectiveness/tracker.js';
 /**
  * Budget adjustment strategy based on runtime feedback.
  */
@@ -76,6 +73,24 @@ export class DynamicBudgetAdjuster {
         if (successRate > 0.7 && truncationRate < 0.3) {
             return null; // Current budget is working well
         }
+        // Strategy 5: Effectiveness-based adjustment
+        // If context effectiveness is low, increase budget to allow more targeted context
+        try {
+            const effectivenessTracker = getEffectivenessTracker();
+            const metrics = effectivenessTracker.getMetrics();
+            if (metrics.totalSessions > 3 && metrics.tokenEfficiency < 0.3) {
+                const newBudget = Math.min(currentBudget * (1 + this.adjustmentStep * 0.5), this.maxBudget);
+                return {
+                    newBudget: Math.round(newBudget),
+                    reason: `Low context token efficiency (${metrics.tokenEfficiency.toFixed(2)})`,
+                    confidence: 0.5,
+                };
+            }
+        }
+        catch (error) {
+            // Effectiveness tracker not available, skip
+            getLogger().debug(`[DynamicBudgetAdjuster] effectiveness tracker unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
         return null;
     }
     /**

package/dist/core/context/builder.js

@@ -3,6 +3,7 @@ import { defaultPathAdapter } from '../adapters/path/path-adapter.js';
 import { ConfigError } from '../config/errors.js';
 import { LIMITS } from '../config/limits.js';
 import { resolveConfig } from '../config/resolve.js';
+import { getLogger } from '../observability/logger.js';
 import { createDefaultPermissionGate } from '../permission-gate/default-gate.js';
 import { ensureInSandbox, normalizePath } from '../utils/path.js';
 /**
@@ -30,7 +31,8 @@ function getExtensionsPatternForPlugins(plugins) {
     return Array.from(extensions).join('|');
 }
 const fileAdapter = new FileAdapter();
-import { outlineSource } from './ast/source-outline.js';
+import { detectLang } from './ast/skeleton-extractor.js';
+import { outlineSourceAsync } from './ast/source-outline.js';
 import { createContextCacheStore } from './cache/store-factory.js';
 import { applySmartCompression } from './compression/smart-compress.js';
 import { findFileDependencies } from './dependencies.js';
@@ -85,7 +87,8 @@ async function readRepoFileText(repoPath, relativePath) {
         const fullPath = ensureInSandbox(repoPath, defaultPathAdapter.join(repoPath, normalized));
         return await fileAdapter.readFile(fullPath, 'utf-8');
     }
-    catch {
+    catch (error) {
+        getLogger().debug(`[ContextBuilder] readRepoFileText failed for ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
 }
@@ -134,6 +137,7 @@ export class ContextBuilder {
             snapshotHash: options.snapshotHash,
             checkpointManager: options.checkpointManager,
             signal: options.signal,
+            contextFiles: options.contextFiles,
         });
         return result;
     }
@@ -239,7 +243,7 @@ export class ContextBuilder {
                 if (content === null)
                     continue;
                 const isLarge = content.length > LIMITS.largeFileThresholdBytes;
-                const outline = outlineSource(content);
+                const outline = await outlineSourceAsync(content, detectLang(p));
                 newRelatedFiles.push({
                     path: p,
                     kind: normalizedFailed.includes(p) ? 'failed' : 'dependency',

package/dist/core/context/cache/store-factory.js

@@ -1,5 +1,6 @@
 import { FileAdapter } from '../../adapters/fs/file-adapter.js';
 import { recordAuditEvent } from '../../observability/audit-trail.js';
+import { getLogger } from '../../observability/logger.js';
 import { resolveContextCachePath } from './path-resolver.js';
 import { MemoryContextCacheStore, PersistentContextCacheStore, } from './store.js';
 export async function createContextCacheStore(repoPath, rawConfig, options) {
@@ -24,8 +25,9 @@ export async function createContextCacheStore(repoPath, rawConfig, options) {
         try {
             await cleanupAdapter.deleteFile(details.filePath);
         }
-        catch {
+        catch (error) {
             // best-effort cleanup only
+            getLogger().debug(`[ContextCache] cleanup failed for ${details.filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     };
     if (pathResolution.mode === 'persistent' && pathResolution.filePath) {

package/dist/core/context/dependencies.js

@@ -75,7 +75,8 @@ async function findDirectDependencies(filePath, repoPath, fsAdapter) {
         }
         return dependencies;
     }
-    catch {
+    catch (error) {
+        getLogger().debug(`[Dependencies] failed to find direct dependencies for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         return [];
     }
 }

package/dist/core/context/effectiveness/persistence.js

@@ -0,0 +1,50 @@
+/**
+ * Effectiveness data persistence.
+ *
+ * Saves and restores tracker state across sessions.
+ * Data is stored in `.salmonloop/runtime/effectiveness.json`.
+ */
+import { mkdir, readFile, writeFile } from '../../adapters/fs/node-fs.js';
+import { defaultPathAdapter } from '../../adapters/path/path-adapter.js';
+import { logIgnoredError } from '../../observability/ignored-error.js';
+import { getLogger } from '../../observability/logger.js';
+import { getEffectivenessTracker } from './tracker.js';
+const EFFECTIVENESS_FILE = 'effectiveness.json';
+function getEffectivenessPath(repoRoot) {
+    return defaultPathAdapter.join(repoRoot, '.salmonloop', 'runtime', EFFECTIVENESS_FILE);
+}
+/**
+ * Persist current tracker state to disk.
+ */
+export async function persistEffectiveness(repoRoot) {
+    try {
+        const tracker = getEffectivenessTracker();
+        const data = tracker.serialize();
+        const filePath = getEffectivenessPath(repoRoot);
+        await mkdir(defaultPathAdapter.join(repoRoot, '.salmonloop', 'runtime'), { recursive: true });
+        await writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (error) {
+        logIgnoredError('[Effectiveness] Failed to persist', error);
+    }
+}
+/**
+ * Restore tracker state from disk.
+ * Silently returns if no saved data exists.
+ */
+export async function restoreEffectiveness(repoRoot) {
+    try {
+        const filePath = getEffectivenessPath(repoRoot);
+        const raw = await readFile(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object') {
+            const tracker = getEffectivenessTracker();
+            tracker.deserialize(data);
+        }
+    }
+    catch (error) {
+        // File missing or corrupted — start fresh
+        getLogger().debug(`[Effectiveness] restore failed, starting fresh: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/dist/core/context/effectiveness/tracker.js

@@ -176,6 +176,30 @@ export class ContextEffectivenessTracker {
         this.totalExecutions = 0;
         this.sessionCount = 0;
     }
+    /**
+     * Serialize tracker state for persistence.
+     */
+    serialize() {
+        return {
+            usageRecords: this.usageRecords,
+            failureRecords: this.failureRecords,
+            totalTokensUsed: this.totalTokensUsed,
+            successfulExecutions: this.successfulExecutions,
+            totalExecutions: this.totalExecutions,
+            sessionCount: this.sessionCount,
+        };
+    }
+    /**
+     * Restore tracker state from serialized data.
+     */
+    deserialize(data) {
+        this.usageRecords = data.usageRecords ?? [];
+        this.failureRecords = data.failureRecords ?? [];
+        this.totalTokensUsed = data.totalTokensUsed ?? 0;
+        this.successfulExecutions = data.successfulExecutions ?? 0;
+        this.totalExecutions = data.totalExecutions ?? 0;
+        this.sessionCount = data.sessionCount ?? 0;
+    }
     /**
      * Aggregate file statistics.
      */

package/dist/core/context/gatherers/architecture-gatherer.js

@@ -18,8 +18,9 @@ export class ArchitectureGatherer {
                 return parsed;
             }
         }
-        catch {
+        catch (error) {
             // Cache miss or corrupted, proceed to scan
+            getLogger().debug(`[ArchitectureGatherer] cache read failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         const topology = {
             modules: [],

package/dist/core/context/gatherers/artifact-gatherer.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { getLogger } from '../../observability/logger.js';
 import { safeJoin } from '../../utils/path.js';
 export class ArtifactGatherer {
     static COMMON_BUILD_DIRS = ['dist', 'build', 'out', 'target', 'bin'];
@@ -25,8 +26,9 @@ export class ArtifactGatherer {
             const rootEntries = await this.fileAdapter.readdir(repoPath);
             artifacts.buildDirs = rootEntries.filter((e) => ArtifactGatherer.COMMON_BUILD_DIRS.includes(e));
         }
-        catch {
-            /* Ignore */
+        catch (error) {
+            /* Ignore - best-effort build dir detection */
+            getLogger().debug(`[ArtifactGatherer] build dir scan failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         // 2. Lock Files & Hashes
         for (const lock of ArtifactGatherer.CRITICAL_LOCK_FILES) {
@@ -40,8 +42,9 @@ export class ArtifactGatherer {
                     artifacts.lockFiles?.push({ path: lock, hash });
                 }
             }
-            catch {
-                /* Ignore */
+            catch (error) {
+                /* Ignore - best-effort lock file detection */
+                getLogger().debug(`[ArtifactGatherer] lock file scan failed for ${lock}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         // 3. Selective Env Vars (Names only, no values for security)

package/dist/core/context/gatherers/ast-gatherer.js

@@ -8,7 +8,8 @@ import { getPluginRegistry } from '../../plugin/registry.js';
 import { normalizePath, safeJoin } from '../../utils/path.js';
 import { extractImportSpecifiers } from '../ast/import-extractor.js';
 import { resolveImportCandidates } from '../ast/module-resolver.js';
-import { outlineSource } from '../ast/source-outline.js';
+import { detectLang } from '../ast/skeleton-extractor.js';
+import { outlineSourceAsync } from '../ast/source-outline.js';
 const AST_DEEP_TRIGGER_PATTERN = /\b(refactor|rename|migrate|cross[- ]?file|across|dependency|dependencies|module|architecture|global)\b/i;
 function getImportScanDepth(req) {
     const instruction = req.instruction || '';
@@ -23,7 +24,7 @@ async function buildSymbolMap(symbols, primaryFile, callNames, relatedFiles) {
     const nodes = [];
     const edges = [];
     const definitionNodeByName = new Map();
-    // Process primary file symbols
+    // Phase 1: Collect all definitions (primary file first, then imported files)
     for (const def of definitions) {
         const id = `def:${def.name}:${def.location.start.line}:${def.location.start.column}`;
         definitionNodeByName.set(def.name, id);
@@ -35,27 +36,6 @@ async function buildSymbolMap(symbols, primaryFile, callNames, relatedFiles) {
             location: def.location,
         });
     }
-    for (const ref of references) {
-        const refId = `ref:${ref.name}:${ref.location.start.line}:${ref.location.start.column}`;
-        nodes.push({
-            id: refId,
-            name: ref.name,
-            kind: 'reference',
-            path: primaryFile,
-            location: ref.location,
-        });
-        const targetDefId = definitionNodeByName.get(ref.name);
-        if (!targetDefId)
-            continue;
-        const edgeType = callNames.includes(ref.name) ? 'call' : 'reference';
-        edges.push({
-            from: refId,
-            to: targetDefId,
-            type: edgeType,
-            confidence: 'high',
-        });
-    }
-    // Process imported files
     for (const related of relatedFiles) {
         if (related.kind !== 'import' || related.mode !== 'full')
             continue;
@@ -74,7 +54,6 @@ async function buildSymbolMap(symbols, primaryFile, callNames, relatedFiles) {
                     path: related.path,
                     location: def.location,
                 });
-                // Allow cross-file references to find these definitions
                 if (!definitionNodeByName.has(def.name)) {
                     definitionNodeByName.set(def.name, id);
                 }
@@ -84,6 +63,27 @@ async function buildSymbolMap(symbols, primaryFile, callNames, relatedFiles) {
             getLogger().debug(`  [CONTEXT] Failed to extract symbols from ${related.path}: ${e}`);
         }
     }
+    // Phase 2: Create reference nodes and edges (now all definitions are available)
+    for (const ref of references) {
+        const refId = `ref:${ref.name}:${ref.location.start.line}:${ref.location.start.column}`;
+        nodes.push({
+            id: refId,
+            name: ref.name,
+            kind: 'reference',
+            path: primaryFile,
+            location: ref.location,
+        });
+        const targetDefId = definitionNodeByName.get(ref.name);
+        if (!targetDefId)
+            continue;
+        const edgeType = callNames.includes(ref.name) ? 'call' : 'reference';
+        edges.push({
+            from: refId,
+            to: targetDefId,
+            type: edgeType,
+            confidence: 'high',
+        });
+    }
     return { symbolMap: { nodes, edges } };
 }
 function summarizeControlFlow(primaryText) {
@@ -298,7 +298,7 @@ export class AstGatherer {
                     continue;
                 if (!relatedSeen.has(normalized)) {
                     relatedSeen.add(normalized);
-                    const outline = outlineSource(content);
+                    const outline = await outlineSourceAsync(content, detectLang(normalized));
                     const isLarge = content.length > LIMITS.largeFileThresholdBytes;
                     related.push({
                         path: normalized,
@@ -339,8 +339,9 @@ export class AstGatherer {
                 await this.fileAdapter.readFile(safeJoin(req.repoPath, c), 'utf-8');
                 return c;
             }
-            catch {
-                // continue
+            catch (error) {
+                // continue - file not found, try next candidate
+                getLogger().debug(`[AstGatherer] candidate file not found: ${c}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         return null;
@@ -354,7 +355,8 @@ export class AstGatherer {
         try {
             return await this.fileAdapter.readFile(safeJoin(req.repoPath, filePath), 'utf-8');
         }
-        catch {
+        catch (error) {
+            getLogger().debug(`[AstGatherer] readRepoFile failed for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
     }

package/dist/core/context/gatherers/git-history-gatherer.js

@@ -1,4 +1,5 @@
 import { GitAdapter } from '../../adapters/git/git-adapter.js';
+import { getLogger } from '../../observability/logger.js';
 import { normalizePath } from '../../utils/path.js';
 function buildChurnIndex(logOutput) {
     const churn = {};
@@ -48,8 +49,9 @@ export class GitHistoryGatherer {
                 churnByFile: Object.keys(churnByNumstat).length > 0 ? churnByNumstat : buildChurnIndex(churnLog),
             };
         }
-        catch {
+        catch (error) {
             // Not a git repo or git not found
+            getLogger().debug(`[GitHistoryGatherer] git history gather failed: ${error instanceof Error ? error.message : String(error)}`);
             return {};
         }
     }