smart-context-mcp 1.10.0 → 1.13.0

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.10.0 (or later)
+# Should show: smart-context-mcp@1.13.0 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.10.0",
+  "version": "1.13.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/scripts/init-clients.js

@@ -461,11 +461,9 @@ const updateCursorRule = (targetDir, dryRun) => {
   const rulesDir = path.join(targetDir, '.cursor', 'rules');
   const profilesDir = path.join(rulesDir, 'profiles-compact');
   
-  // Write base rule (always active)
   const baseFilePath = path.join(rulesDir, 'devctx.mdc');
   writeFile(baseFilePath, cursorRuleContent, dryRun);
-  
-  // Write profiles README
+
   const profilesReadmePath = path.join(profilesDir, 'README.md');
   writeFile(profilesReadmePath, cursorProfilesNote, dryRun);
   

package/scripts/report-adoption-metrics.js

@@ -73,7 +73,6 @@ const calculateAdoptionMetrics = (days = 30) => {
   return withStateDb((db) => {
     const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
 
-    // Get all sessions since cutoff
     const sessions = db
       .prepare(
         `
@@ -94,7 +93,6 @@ const calculateAdoptionMetrics = (days = 30) => {
       toolUsage: {},
     };
 
-    // Initialize workflow stats
     Object.keys(WORKFLOW_DEFINITIONS).forEach((type) => {
       results.byWorkflow[type] = {
         total: 0,
@@ -103,12 +101,10 @@ const calculateAdoptionMetrics = (days = 30) => {
       };
     });
 
-    // Analyze each session
     sessions.forEach((session) => {
       const snapshot = JSON.parse(session.snapshot_json || '{}');
       const sessionId = session.session_id;
 
-      // Get events for this session
       const sessionEvents = db
         .prepare('SELECT * FROM session_events WHERE session_id = ?')
         .all(sessionId);
@@ -117,25 +113,21 @@ const calculateAdoptionMetrics = (days = 30) => {
         .prepare('SELECT * FROM metrics_events WHERE session_id = ?')
         .all(sessionId);
 
-      // Check if non-trivial
       if (!isNonTrivialTask(sessionEvents, metricsEvents)) {
         return;
       }
 
       results.nonTrivialTasks++;
 
-      // Check if used devctx
       const hasDevctx = usedDevctx(metricsEvents);
       if (hasDevctx) {
         results.tasksWithDevctx++;
       }
 
-      // Track tool usage
       metricsEvents.forEach((m) => {
         results.toolUsage[m.tool] = (results.toolUsage[m.tool] || 0) + 1;
       });
 
-      // Classify by workflow if possible
       const goal = snapshot.goal || '';
       let workflowType = null;
 
@@ -154,7 +146,6 @@ const calculateAdoptionMetrics = (days = 30) => {
       }
     });
 
-    // Calculate rates
     if (results.nonTrivialTasks > 0) {
       results.adoptionRate = (results.tasksWithDevctx / results.nonTrivialTasks) * 100;
     }

package/scripts/report-workflow-metrics.js

@@ -171,7 +171,6 @@ const printSummary = (summary) => {
   console.log('─'.repeat(120));
   console.log('');
 
-  // Show detailed breakdown for each workflow type
   console.log('Detailed Breakdown:');
   console.log('');
 

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.10.0",
+  "version": "1.13.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.10.0",
+      "version": "1.13.0",
       "transport": {
         "type": "stdio"
       },

package/src/index-manager.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { execFile as execFileCallback } from 'node:child_process';
 import { promisify } from 'node:util';
 import { projectRoot } from './utils/paths.js';
-import { loadIndex, buildIndex as buildIndexCore } from './index.js';
+import { loadIndex, buildIndexIncremental, persistIndex } from './index.js';
 
 const execFile = promisify(execFileCallback);
 
@@ -83,23 +83,28 @@ export const ensureIndexReady = async (options = {}) => {
   }
   
   log('Building search index...');
-  
+
   try {
-    const buildPromise = buildIndexCore({ root, incremental: true });
+    const buildPromise = (async () => {
+      const { index, stats } = buildIndexIncremental(root);
+      await persistIndex(index, root);
+      return { stats, fileCount: Object.keys(index.files).length, version: index.version };
+    })();
+
     const result = await Promise.race([
       buildPromise,
-      timeout(timeoutMs, 'Index build timeout')
+      timeout(timeoutMs, 'Index build timeout'),
     ]);
-    
+
     saveIndexMetadata({
       builtAt: Date.now(),
       gitHead: getGitHead(root),
-      fileCount: result?.files?.length || 0,
-      version: result?.version
+      fileCount: result.fileCount,
+      version: result.version,
     }, root);
-    
+
     log('Index ready');
-    return { status: 'built', cached: false, fileCount: result?.files?.length || 0 };
+    return { status: 'built', cached: false, fileCount: result.fileCount };
   } catch (error) {
     log(`Index build failed: ${error.message}`);
     return { status: 'fallback', error: error.message };

package/src/index.js

@@ -726,9 +726,7 @@ export const buildIndex = (root, progress = null) => {
         if (sym.snippet) entry.snippet = sym.snippet;
         invertedIndex[key].push(entry);
       }
-    } catch {
-      // skip unreadable files
-    }
+    } catch { /* unreadable */ }
 
     processed++;
     

package/src/missed-opportunities.js

@@ -141,7 +141,6 @@ export const formatMissedOpportunities = () => {
   lines.push('⚠️ **Missed devctx opportunities detected:**');
   lines.push('');
   
-  // Show session stats
   lines.push(`**Session stats:**`);
   lines.push(`- Duration: ${analysis.sessionDuration}s`);
   lines.push(`- devctx operations: ${analysis.devctxOperations}`);

package/src/server.js

@@ -39,7 +39,7 @@ export const asTextResult = (result) => ({
   content: [
     {
       type: 'text',
-      text: JSON.stringify(result, null, 2),
+      text: JSON.stringify(result),
     },
   ],
 });
@@ -57,13 +57,11 @@ export const createDevctxServer = () => {
     version,
   });
 
-  // Enable streaming progress notifications
   setServerForStreaming(server);
 
-  // Register prompts
   server.prompt(
     'use-devctx',
-    'Force the agent to use devctx tools for the current task. Use this prompt at the start of your message to ensure devctx is used instead of native tools.',
+    'Force the agent to use devctx tools for the current task.',
     {},
     async () => ({
       messages: [
@@ -71,7 +69,7 @@ export const createDevctxServer = () => {
           role: 'user',
           content: {
             type: 'text',
-            text: 'Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)',
+            text: 'Use devctx MCP tools for this task. Start with smart_context(task) for multi-file context. Use smart_read(outline) → smart_read(symbol) cascade for individual files. Never use native Read on large files.',
           },
         },
       ],
@@ -80,7 +78,7 @@ export const createDevctxServer = () => {
 
   server.prompt(
     'devctx-workflow',
-    'Complete devctx workflow template with all recommended steps. Includes session start, context building, file reading, and session end.',
+    'Complete devctx workflow for complex tasks with session continuity.',
     {},
     async () => ({
       messages: [
@@ -88,15 +86,7 @@ export const createDevctxServer = () => {
           role: 'user',
           content: {
             type: 'text',
-            text: `Follow this devctx workflow:
-
-1. smart_turn(start) - Start session and recover previous context
-2. smart_context(task) - Build complete context for the task
-3. smart_search(query) - Search for specific patterns if needed
-4. smart_read(file) - Read files with appropriate mode (outline/signatures/symbol)
-5. smart_turn(end) - Save checkpoint for next session
-
-Use devctx tools instead of native Read/Grep/Shell when possible.`,
+            text: 'Follow devctx workflow: 1) smart_turn(start) to recover session 2) smart_context(task) for curated context (replaces search+read cycle) 3) smart_read(symbol) only for specific functions not covered by smart_context 4) smart_turn(end) to checkpoint. Never skip to smart_read(full) — use the cascade: outline → signatures → symbol → full.',
           },
         },
       ],
@@ -105,7 +95,7 @@ Use devctx tools instead of native Read/Grep/Shell when possible.`,
 
   server.prompt(
     'devctx-preflight',
-    'Preflight checklist before starting work. Ensures index is built and session is initialized.',
+    'Preflight: build index and initialize session before work.',
     {},
     async () => ({
       messages: [
@@ -113,13 +103,7 @@ Use devctx tools instead of native Read/Grep/Shell when possible.`,
           role: 'user',
           content: {
             type: 'text',
-            text: `Preflight checklist:
-
-1. build_index(incremental=true) - Build/update symbol index
-2. smart_turn(start) - Initialize session and recover context
-3. Proceed with your task using devctx tools
-
-This ensures optimal performance and context recovery.`,
+            text: 'Preflight: 1) build_index(incremental=true) 2) smart_turn(start) 3) Proceed with devctx tools.',
           },
         },
       ],
@@ -128,7 +112,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_read',
-    'Read a file with token-efficient modes. outline/signatures: compact structure (~90% savings). range: specific line range with line numbers. symbol: extract function/class/method by name (string or array for batch). full: file content capped at 12k chars. maxTokens: token budget — auto-selects the most detailed mode that fits (full -> outline -> signatures -> truncated). context=true (symbol mode only): includes callers, tests, and referenced types from the dependency graph; returns graphCoverage (imports/tests: full|partial|none) so the agent knows how reliable the cross-file context is. Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
+    'Read a file with token-efficient modes. ALWAYS prefer outline/signatures/symbol over full. Reading cascade: outline → signatures → symbol → range → full (last resort). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use first for orientation. signatures (~85% savings): function signatures with parameters and return types — use when you need the API surface. symbol: extract specific functions/classes by name (string or array) — use when you know what to read; add context=true for callers, tests, and dependencies. range: specific line range — use only when you need exact lines. full: raw content, no savings — only for config/lock files. maxTokens: token budget — auto-cascades to fit (outline → signatures → truncated). Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
     {
       filePath: z.string(),
       mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol']).optional(),
@@ -144,7 +128,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_read_batch',
-    'Read multiple files in one call. Each item accepts path, mode, symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
+    'Read multiple files in one call. Each item accepts path, mode (prefer outline/signatures/symbol — full saves 0 tokens), symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
     {
       files: z.array(z.object({
         path: z.string(),
@@ -162,7 +146,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_search',
-    'Search code across the project using ripgrep (with filesystem fallback). Returns grouped, ranked results. Optional intent (implementation/debug/tests/config/docs/explore) adjusts ranking: tests boosts test files, config boosts config files, docs reduces penalty on READMEs. Includes a unified confidence block: { level, indexFreshness } plus retrievalConfidence and provenance metadata.',
+    'Search code across the project using ripgrep (with filesystem fallback). Returns grouped, ranked results. Optional intent (implementation/debug/tests/config/docs/explore) adjusts ranking. Use instead of native Grep for ranked, deduplicated results with index boosting.',
     {
       query: z.string(),
       cwd: z.string().optional(),
@@ -173,7 +157,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_context',
-    'Get curated context for a task in one call. Combines smart_search + smart_read + graph expansion. Returns relevant files, evidence for why each file was included, related tests, dependencies, symbol previews from the index, and symbol details — optimized for tokens. Includes a unified confidence block: { indexFreshness, graphCoverage } indicating index state and how complete the relational context is. Replaces the manual search → read → read cycle. Optional intent override, token budget, diff mode (pass diff=true for HEAD or diff="main" to scope context to changed files only), detail mode (minimal=index+signatures+snippets, balanced=default, deep=full content), include array to control which fields are returned (["content","graph","hints","symbolDetail"]), and prefetch=true to enable intelligent context prediction based on historical patterns (reduces round-trips by 40-60%).',
+    'PREFERRED for multi-file tasks. Gets curated context in one call — replaces the manual search → read → read cycle. Combines search + graph expansion + selective reading. Returns relevant files with symbols and content, optimized for tokens. Options: intent, maxTokens (budget), diff (true for HEAD or branch name), detail (minimal/balanced/deep), include (content/graph/hints/symbolDetail), prefetch (true for predictive loading). Call this FIRST before individual smart_read/smart_search calls.',
     {
       task: z.string(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
@@ -190,7 +174,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_shell',
-    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. Includes a unified confidence block: { blocked, timedOut }.',
+    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. For large diffs: output is split by file (up to 8 files, 60 lines each); prefer git diff --stat first, then git show -- <file> per file.',
     {
       command: z.string(),
     },
@@ -487,7 +471,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_turn',
-    'Orchestrate start/end of a meaningful agent turn so context usage becomes almost mandatory with low token overhead. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, returns `recommendedPath` guidance for the next safe devctx actions, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary, returns follow-up `recommendedPath` guidance, and can optionally include compact metrics. Both phases expose `mutationSafety` when repo-safety blocks persisted writes and now surface `storageHealth` when SQLite state is missing, oversized, locked, or corrupted. Use this instead of manually chaining `smart_summary(get)` and `smart_summary(checkpoint)` when you want a single context-first turn workflow.',
+    'Orchestrate start/end of a meaningful agent turn for multi-session tasks where context continuity matters. SKIP for single-session point-in-time tasks (reviewing a specific commit, answering a quick question, one-off lookup) — the setup overhead exceeds the benefit if the session will never be resumed. USE when: the task spans multiple chat sessions, you may return to it the next day, or the codebase context is large enough that re-reading is expensive. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, returns `recommendedPath` guidance for the next safe devctx actions, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary, returns follow-up `recommendedPath` guidance, and can optionally include compact metrics. Both phases expose `mutationSafety` when repo-safety blocks persisted writes and surface `storageHealth` when SQLite state is missing, oversized, locked, or corrupted.',
     {
       phase: z.enum(['start', 'end']),
       sessionId: z.string().optional(),

package/src/tokenCounter.js

@@ -1,12 +1,35 @@
 import { encodingForModel } from 'js-tiktoken';
 
-const fallbackModel = 'gpt-4o-mini';
-const encoder = encodingForModel(fallbackModel);
+const CLAUDE_ALIASES = new Set(['claude', 'anthropic']);
 
-export const countTokens = (text = '') => {
-  if (!text) {
-    return 0;
+// js-tiktoken does not ship Claude's tokenizer; gpt-4o (o200k_base) is the
+// closest available encoding. Accuracy for Claude models: ±15-20%.
+const CLAUDE_FALLBACK = 'gpt-4o';
+const DEFAULT_MODEL = 'gpt-4o-mini';
+
+const resolveModel = () => {
+  const requested = (process.env.DEVCTX_TOKEN_MODEL || '').toLowerCase().trim();
+  if (!requested) return DEFAULT_MODEL;
+  if (CLAUDE_ALIASES.has(requested) || requested.startsWith('claude')) {
+    return CLAUDE_FALLBACK;
+  }
+  return requested;
+};
+
+const buildEncoder = () => {
+  const model = resolveModel();
+  try {
+    return encodingForModel(model);
+  } catch {
+    return encodingForModel(DEFAULT_MODEL);
   }
+};
 
+// Encoder is initialised once; if the env var changes at runtime the process
+// must be restarted (acceptable for a CLI/MCP server).
+const encoder = buildEncoder();
+
+export const countTokens = (text = '') => {
+  if (!text) return 0;
   return encoder.encode(String(text)).length;
 };

package/src/tools/smart-context.js

@@ -15,7 +15,6 @@ import { predictContextFiles, recordContextAccess } from '../context-patterns.js
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 import { 
   getDetailedDiff, 
@@ -35,7 +34,6 @@ import {
 } from '../utils/query-extraction.js';
 import {
   dedupeEvidence,
-  formatReasonIncluded,
   buildSymbolPreviews,
   attachSymbolEvidence,
   computeStaticUtility,
@@ -226,29 +224,6 @@ const getSymbolSignatureLimit = (item, detailMode, readMode) => {
 const getSymbolSignatures = (entries, maxItems = 10) =>
   entries.filter((entry) => entry.signature).slice(0, maxItems).map((entry) => entry.signature);
 
-const serializeEvidencePayload = (item) => {
-  const evidence = dedupeEvidence(item.evidence ?? []);
-  if (evidence.length === 0) return [];
-
-  const limit = item.role === 'primary' ? 2 : 1;
-  const preferred = item.role === 'primary'
-    ? evidence
-    : [
-      evidence.find((entry) => ['testOf', 'dependencyOf', 'dependentOf'].includes(entry.type)),
-      evidence[0],
-    ].filter(Boolean);
-
-  return uniqueList(preferred)
-    .slice(0, limit)
-    .map((entry) => ({
-      type: entry.type,
-      ...(entry.via ? { via: entry.via } : {}),
-      ...(entry.query && item.role === 'primary' ? { query: entry.query } : {}),
-      ...(entry.ref && item.role === 'primary' ? { ref: entry.ref } : {}),
-      ...(Array.isArray(entry.symbols) && entry.symbols.length > 0 ? { symbols: entry.symbols.slice(0, 2) } : {}),
-    }));
-};
-
 const shouldIncludeSymbolNames = (item, symbolPreviews, readMode) => {
   if (item.role === 'primary') return true;
   if (readMode === 'full') return true;
@@ -273,14 +248,10 @@ const buildContextItemPayload = (item, index, detailMode, readMode = 'index-only
   const symbolSignatures = shouldIncludeSymbolSignatures(item, symbolPreviews)
     ? getSymbolSignatures(fileSymbolEntries, getSymbolSignatureLimit(item, detailMode, readMode))
     : [];
-  const evidence = serializeEvidencePayload(item);
 
   return {
     file: item.rel,
     role: item.role,
-    readMode,
-    reasonIncluded: formatReasonIncluded(item.evidence),
-    evidence,
     ...(fileSymbols.length > 0 ? { symbols: fileSymbols } : {}),
     ...(symbolSignatures.length > 0 ? { symbolSignatures } : {}),
     ...(symbolPreviews.length > 0 ? { symbolPreviews } : {}),
@@ -412,17 +383,11 @@ export const smartContext = async ({
     
     await ensureIndexReady({ root });
     
-    // Get detailed diff stats
     const detailedChanges = await getDetailedDiff(changed.ref, root);
     const index = loadIndex(root);
-    
-    // Analyze impact and prioritize
     const prioritized = analyzeChangeImpact(detailedChanges, index);
-    
-    // Expand to include related files (importers, dependencies, tests)
     const expandedFiles = expandChangedContext(changed.files, index, 10);
-    
-    // Build primary seeds with priority and impact data
+
     primarySeeds = Array.from(expandedFiles).map(rel => {
       const changeInfo = prioritized.find(c => c.file === rel);
       const evidence = [{ 
@@ -432,7 +397,6 @@ export const smartContext = async ({
         impact: changeInfo?.impactScore || 0,
       }];
       
-      // Mark files that were expanded (not directly changed)
       if (!changed.files.includes(rel)) {
         evidence[0].expanded = true;
       }
@@ -444,7 +408,6 @@ export const smartContext = async ({
       };
     });
     
-    // Sort by impact (critical changes first)
     primarySeeds.sort((a, b) => {
       const impactA = a.evidence[0].impact || 0;
       const impactB = b.evidence[0].impact || 0;
@@ -677,16 +640,9 @@ export const smartContext = async ({
 
         const filtered = filterFoundSymbols(symbolResult.content, symbolCandidates);
         if (filtered) {
-          const symbolEvidence = dedupeEvidence([{
-            type: 'symbolDetail',
-            symbols: symbolCandidates.slice(0, 3),
-          }]);
           const symbolPayload = {
             file: topPrimary.rel,
             role: 'symbolDetail',
-            readMode: 'symbol',
-            reasonIncluded: formatReasonIncluded(symbolEvidence),
-            evidence: symbolEvidence,
             content: filtered,
           };
           const symbolTokens = countTokens(JSON.stringify(symbolPayload));
@@ -700,7 +656,6 @@ export const smartContext = async ({
                 const existing = context[existingIdx];
                 const signaturesOnly = {
                   ...existing,
-                  readMode: 'signatures-only',
                   content: '(omitted — see symbolDetail)',
                 };
                 const oldTokens = countTokens(JSON.stringify(existing));
@@ -755,7 +710,6 @@ export const smartContext = async ({
 
   const contentTokens = countTokens(context.map((c) => c.content).join('\n'));
   const previewTokens = context.reduce((sum, item) => sum + countTokens(JSON.stringify(item.symbolPreviews ?? [])), 0);
-  const indexOnlyItems = context.filter((item) => item.readMode === 'index-only').length;
   const contentItems = context.filter((item) => typeof item.content === 'string' && item.content.length > 0).length;
   const primaryItem = context.find((item) => item.role === 'primary');
 
@@ -771,17 +725,13 @@ export const smartContext = async ({
     timestamp: new Date().toISOString(),
   });
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_context',
     savedTokens,
     target: task,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
+
   let reason = DECISION_REASONS.TASK_CONTEXT;
   if (diff) {
     reason = DECISION_REASONS.DIFF_ANALYSIS;
@@ -828,17 +778,6 @@ export const smartContext = async ({
   };
 
   const filesIncluded = new Set(context.map((c) => c.file)).size;
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_context',
-    target: task,
-    metrics: {
-      rawTokens: totalRawTokens,
-      compressedTokens: totalCompressedTokens,
-      savedTokens,
-    },
-    startTime: enableProgress ? startTime : null,
-    filesCount: filesIncluded,
-  });
 
   if (progress) {
     progress.complete({
@@ -857,28 +796,20 @@ export const smartContext = async ({
     confidence: { indexFreshness, graphCoverage: graphCov },
     context,
     ...(includeSet.has('graph') ? { graph: graphSummary, graphCoverage: graphCov } : {}),
-    metrics: {
-      contentTokens,
-      totalTokens: 0,
+    stats: {
       filesIncluded,
       filesEvaluated: expanded.size,
-      savingsPct,
       detailMode,
-      include: [...includeSet],
-      previewTokens,
-      indexOnlyItems,
-      contentItems,
-      primaryReadMode: primaryItem?.readMode ?? null,
+      totalTokens: countTokens(context.map((c) => c.content || '').join('')),
       ...(prefetchResult ? {
         prefetch: {
           enabled: true,
           confidence: prefetchResult.confidence || 0,
           predictedFiles: prefetchResult.predicted?.length || 0,
-          matchedPattern: prefetchResult.matchedPattern || null
-        }
-      } : {})
+          matchedPattern: prefetchResult.matchedPattern || null,
+        },
+      } : {}),
     },
-    metricsDisplay,
     ...(includeSet.has('hints') ? { hints } : {}),
   };
 
@@ -887,7 +818,5 @@ export const smartContext = async ({
     result.diffSummary = diffSummary;
   }
 
-  result.metrics.totalTokens = countTokens(JSON.stringify(result));
-
   return result;
 };

package/src/tools/smart-read/code.js

@@ -105,15 +105,25 @@ const formatDeclarationName = (name) => {
 
 const collectVariableNames = (declarationList) => declarationList.declarations.map((declaration) => formatDeclarationName(declaration.name));
 
-const formatTopLevelStatement = (statement, sourceFile) => {
+const getFunctionSignature = (statement, sourceFile) => {
+  const body = statement.body;
+  if (!body) return statement.getText(sourceFile).split('\n')[0];
+  const fullText = statement.getText(sourceFile);
+  const bodyOffset = body.getStart(sourceFile) - statement.getStart(sourceFile);
+  const sig = fullText.slice(0, bodyOffset).replace(/\s+$/, '');
+  return sig.length > 120 ? `${sig.slice(0, 120)}...` : sig;
+};
+
+const formatTopLevelStatement = (statement, sourceFile, mode = 'outline') => {
   const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
   const prefix = exported ? 'export ' : '';
 
   if (ts.isImportDeclaration(statement)) {
-    return formatImport(statement);
+    return null;
   }
 
   if (ts.isFunctionDeclaration(statement)) {
+    if (mode === 'signatures') return getFunctionSignature(statement, sourceFile);
     return `${prefix}function ${getNodeName(statement)}()`;
   }
 
@@ -143,7 +153,8 @@ const formatTopLevelStatement = (statement, sourceFile) => {
   }
 
   if (ts.isExportAssignment(statement)) {
-    return `export default ${statement.expression.getText(sourceFile)}`;
+    const text = statement.expression.getText(sourceFile);
+    return `export default ${text.length > 60 ? `${text.slice(0, 60)}...` : text}`;
   }
 
   return statement.getText(sourceFile).split('\n')[0];
@@ -248,7 +259,8 @@ export const summarizeCode = (fullPath, content, mode) => {
   const sourceFile = parseSource(fullPath, content);
   const topLevel = sourceFile.statements.flatMap((statement) => {
     if (isIIFE(statement)) return extractIIFEMembers(statement, sourceFile);
-    return [formatTopLevelStatement(statement, sourceFile)];
+    const formatted = formatTopLevelStatement(statement, sourceFile, mode);
+    return formatted !== null ? [formatted] : [];
   });
   const hooks = collectHooks(sourceFile);
 

package/src/tools/smart-read-batch.js

@@ -4,7 +4,6 @@ import { countTokens } from '../tokenCounter.js';
 export const smartReadBatch = async ({ files, maxTokens }) => {
   const results = [];
   let totalTokens = 0;
-  let totalRawTokens = 0;
   let filesSkipped = 0;
 
   for (const item of files) {
@@ -40,13 +39,11 @@ export const smartReadBatch = async ({ files, maxTokens }) => {
         parser: readResult.parser,
         truncated: readResult.truncated,
         content: readResult.content,
-        ...(readResult.confidence ? { confidence: readResult.confidence } : {}),
         ...(readResult.indexHint !== undefined ? { indexHint: readResult.indexHint } : {}),
         ...(readResult.chosenMode ? { chosenMode: readResult.chosenMode, budgetApplied: true } : {}),
       });
 
       totalTokens += itemTokens;
-      totalRawTokens += readResult.metrics?.rawTokens ?? 0;
     } catch (err) {
       results.push({
         filePath: item.path,
@@ -56,17 +53,12 @@ export const smartReadBatch = async ({ files, maxTokens }) => {
     }
   }
 
-  const totalSavingsPct = totalRawTokens > 0
-    ? Math.max(0, Math.round(((totalRawTokens - totalTokens) / totalRawTokens) * 100))
-    : 0;
-
   return {
     results,
     metrics: {
       totalTokens,
       filesRead: results.length,
       filesSkipped,
-      totalSavingsPct,
     },
   };
 };

package/src/tools/smart-read.js

@@ -12,7 +12,6 @@ import { countTokens } from '../tokenCounter.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 
 const execFile = promisify(execFileCb);
@@ -536,17 +535,12 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_read',
     savedTokens: metrics.savedTokens,
     target: path.relative(effectiveRoot, fullPath),
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
   const lineCount = content.split('\n').length;
   let reason = DECISION_REASONS.LARGE_FILE;
   let expectedBenefit = EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens);
@@ -568,16 +562,6 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     context: `${lineCount} lines, ${metrics.rawTokens} tokens → ${metrics.compressedTokens} tokens`,
   });
 
-  const confidence = { parser, truncated, cached: cacheHit && !contextResult };
-  if (contextResult) confidence.graphCoverage = contextResult.graphCoverage;
-
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_read',
-    target: path.relative(effectiveRoot, fullPath),
-    metrics,
-    startTime: enableProgress ? startTime : null,
-  });
-
   if (progress) {
     progress.complete({
       file: path.relative(effectiveRoot, fullPath),
@@ -593,12 +577,7 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     parser,
     truncated,
     content: compressedText,
-    confidence,
-    metrics,
-    metricsDisplay,
   };
-
-  if (cacheHit && !contextResult) result.cached = true;
   if (mode === 'symbol') result.indexHint = indexHintUsed;
   if (validBudget && effectiveMode !== mode) {
     result.chosenMode = effectiveMode;

package/src/tools/smart-search.js

@@ -12,7 +12,6 @@ import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
 import { IGNORED_DIRS, IGNORED_FILE_NAMES, IGNORED_FILE_PATTERNS } from '../config/ignored-paths.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
 import { createProgressReporter } from '../streaming.js';
 import { ensureIndexReady } from '../index-manager.js';
 
@@ -475,17 +474,13 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_search',
     savedTokens: metrics.savedTokens,
     target: query,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
+
   let reason = DECISION_REASONS.MULTIPLE_FILES;
   if (validIntent) {
     reason = DECISION_REASONS.INTENT_AWARE;
@@ -510,16 +505,6 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
   else if (usedFallback) retrievalConfidence = provenance?.skippedItemsTotal > 0 ? 'low' : 'medium';
   else if (provenance?.skippedItemsTotal > 0) retrievalConfidence = 'low';
 
-  const confidence = { level: retrievalConfidence, indexFreshness };
-
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_search',
-    target: query,
-    metrics,
-    startTime: enableProgress ? startTime : null,
-    filesCount: groups.length,
-  });
-
   if (progress) {
     progress.complete({
       query,
@@ -532,23 +517,17 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
 
   const result = {
     query,
-    root,
-    engine,
-    retrievalConfidence,
     indexFreshness,
-    sourceBreakdown: breakdown,
-    confidence,
     ...(validIntent ? { intent: validIntent } : {}),
     ...(indexHits ? { indexBoosted: indexHits.size } : {}),
     totalMatches: dedupedMatches.length,
     matchedFiles: groups.length,
     topFiles: groups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
     matches: compressedText,
-    metrics,
-    metricsDisplay,
   };
 
-  if (provenance) result.provenance = provenance;
+  if (provenance?.fallbackReason) result.searchMode = provenance.fallbackReason;
+  if (retrievalConfidence !== 'high') result.retrievalConfidence = retrievalConfidence;
 
   return result;
 };

package/src/tools/smart-shell.js

@@ -7,10 +7,13 @@ import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
-import { buildMetricsDisplay } from '../utils/metrics-display.js';
-
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
+const DEFAULT_TIMEOUT_MS = 15000;
+const getTimeoutMs = () => {
+  const env = parseInt(process.env.DEVCTX_SHELL_TIMEOUT_MS, 10);
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_TIMEOUT_MS;
+};
 const allowedCommands = new Set(['pwd', 'ls', 'find', 'rg', 'git', 'npm', 'pnpm', 'yarn', 'bun']);
 const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse', 'blame']);
 const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
@@ -176,6 +179,52 @@ const validateCommand = (command, tokens) => {
   return null;
 };
 
+const DIFF_FILE_HEADER = /^diff --git a\/.+ b\/.+/;
+const DIFF_HUNK_HEADER = /^@@ /;
+const MAX_DIFF_FILES = 8;
+const MAX_LINES_PER_FILE = 60;
+const DIFF_TOTAL_LIMIT = 4000;
+
+const splitDiffByFile = (text) => {
+  const files = [];
+  let current = null;
+
+  for (const line of text.split('\n')) {
+    if (DIFF_FILE_HEADER.test(line)) {
+      if (current) files.push(current);
+      current = { header: line, lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) files.push(current);
+  return files;
+};
+
+const compressDiff = (text) => {
+  if (!DIFF_FILE_HEADER.test(text)) return text;
+
+  const files = splitDiffByFile(text);
+  if (files.length === 0) return text;
+
+  const shown = files.slice(0, MAX_DIFF_FILES);
+  const skipped = files.length - shown.length;
+
+  const parts = shown.map(({ header, lines }) => {
+    const truncatedLines = lines.slice(0, MAX_LINES_PER_FILE);
+    const skippedLines = lines.length - truncatedLines.length;
+    const hunkCount = lines.filter((l) => DIFF_HUNK_HEADER.test(l)).length;
+    const suffix = skippedLines > 0 ? [`... (${skippedLines} more lines — use smart_read(symbol) for full body)`] : [];
+    return [header, `# ${hunkCount} hunk(s)`, ...truncatedLines, ...suffix].join('\n');
+  });
+
+  const footer = skipped > 0
+    ? `\n# ${skipped} more file(s) not shown — run git show -- <file> for each`
+    : '';
+
+  return truncate(parts.join('\n\n'), DIFF_TOTAL_LIMIT) + footer;
+};
+
 const buildBlockedResult = async (command, message) => {
   const metrics = buildMetrics({
     tool: 'smart_shell',
@@ -191,8 +240,6 @@ const buildBlockedResult = async (command, message) => {
     exitCode: 126,
     blocked: true,
     output: message,
-    confidence: { blocked: true, timedOut: false },
-    metrics,
   };
 };
 
@@ -227,16 +274,17 @@ export const smartShell = async ({ command }) => {
   }
 
   const resolvedFile = file === 'rg' ? rgPath : file;
+  const timeoutMs = getTimeoutMs();
   const execution = await execFile(resolvedFile, args, {
     cwd: projectRoot,
     maxBuffer: 1024 * 1024 * 10,
-    timeout: 15000,
+    timeout: timeoutMs,
   }).then(
     ({ stdout, stderr }) => ({ stdout, stderr, code: 0 }),
     (error) => ({
       stdout: error.stdout ?? '',
       stderr: error.killed
-        ? `Command timed out after 15s: ${command}`
+        ? `Command timed out after ${timeoutMs / 1000}s: ${command}`
         : (error.stderr ?? error.message ?? ''),
       code: Number.isInteger(error.code) ? error.code : 1,
       timedOut: !!error.killed,
@@ -254,7 +302,7 @@ export const smartShell = async ({ command }) => {
   ]);
   const shouldPrioritizeRelevant = execution.code !== 0 || execution.timedOut;
   const compressedSource = shouldPrioritizeRelevant && relevant ? relevant : rawText;
-  const compressedText = truncate(uniqueLines(compressedSource), 5000);
+  const compressedText = truncate(compressDiff(uniqueLines(compressedSource)), 5000);
   const metrics = buildMetrics({
     tool: 'smart_shell',
     target: command,
@@ -264,17 +312,12 @@ export const smartShell = async ({ command }) => {
 
   await persistMetrics(metrics);
   
-  // Record usage for feedback
   recordToolUsage({
     tool: 'smart_shell',
     savedTokens: metrics.savedTokens,
     target: command,
   });
-  
-  // Record devctx operation for missed opportunity detection
   recordDevctxOperation();
-  
-  // Record decision explanation
   const outputLines = rawText.split('\n').length;
   let reason = DECISION_REASONS.COMMAND_OUTPUT;
   if (shouldPrioritizeRelevant && relevant) {
@@ -290,24 +333,13 @@ export const smartShell = async ({ command }) => {
     context: `${outputLines} lines → ${compressedText.split('\n').length} lines (relevant only)`,
   });
 
-  const metricsDisplay = buildMetricsDisplay({
-    tool: 'smart_shell',
-    target: command,
-    metrics,
-    startTime: null,
-  });
-
   const result = {
     command,
     exitCode: execution.code,
     blocked: false,
     output: compressedText,
-    confidence: { blocked: false, timedOut: !!execution.timedOut },
-    metrics,
-    metricsDisplay,
+    ...(execution.timedOut ? { timedOut: true } : {}),
   };
 
-  if (execution.timedOut) result.timedOut = true;
-
   return result;
 };

package/src/tools/smart-turn.js

@@ -13,6 +13,9 @@ import { smartContext } from './smart-context.js';
 import { smartMetrics } from './smart-metrics.js';
 import { smartSummary } from './smart-summary.js';
 
+const isStorageUnhealthy = (health) =>
+  health && health.status !== 'ok' && health.status !== null && health.status !== undefined;
+
 const DEFAULT_START_MAX_TOKENS = 400;
 const DEFAULT_END_MAX_TOKENS = 500;
 const DEFAULT_END_EVENT = 'milestone';
@@ -129,10 +132,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'resume',
       shouldReuseContext: true,
       reason: 'A persisted session was found and no prompt terms were available for comparison.',
-      sharedTerms: [],
-      promptTermCount: 0,
-      summaryTermCount: 0,
-      matchScore: 1,
     };
   }
 
@@ -147,10 +146,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'aligned',
       shouldReuseContext: true,
       reason: 'Prompt terms align with persisted task context.',
-      sharedTerms: sharedTerms.slice(0, 8),
-      promptTermCount: promptTerms.length,
-      summaryTermCount: summaryTerms.length,
-      matchScore,
     };
   }
 
@@ -159,10 +154,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
       state: 'possible_shift',
       shouldReuseContext: true,
       reason: 'Prompt partially overlaps the persisted context; review before continuing.',
-      sharedTerms: sharedTerms.slice(0, 8),
-      promptTermCount: promptTerms.length,
-      summaryTermCount: summaryTerms.length,
-      matchScore,
     };
   }
 
@@ -170,10 +161,6 @@ const classifyContinuity = ({ prompt, summaryResult }) => {
     state: 'context_mismatch',
     shouldReuseContext: false,
     reason: 'Prompt terms do not align with the persisted session summary.',
-    sharedTerms: [],
-    promptTermCount: promptTerms.length,
-    summaryTermCount: summaryTerms.length,
-    matchScore,
   };
 };
 
@@ -342,7 +329,7 @@ const buildStartRecommendedPath = ({
     autoCreated,
     isolatedSession,
     nextTools: [...new Set(nextTools)],
-    steps,
+    instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
 
@@ -389,7 +376,7 @@ const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow }
         : 'checkpointed',
     checkpointEvent: event,
     nextTools: [...new Set(nextTools)],
-    steps,
+    instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
 
@@ -579,7 +566,7 @@ const startTurn = async ({
     ...(summaryResult.candidates ? { candidates: summaryResult.candidates } : {}),
     ...(summaryResult.recommendedSessionId ? { recommendedSessionId: summaryResult.recommendedSessionId } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth ?? null,
+    ...(isStorageUnhealthy(summaryResult.storageHealth ?? metrics?.storageHealth) ? { storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
     message: mutationSafety?.blocked
       ? mutationSafety.message
@@ -694,7 +681,7 @@ const endTurn = async ({
     checkpoint,
     ...(workflow ? { workflow } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
-    storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth ?? null,
+    ...(isStorageUnhealthy(checkpoint.storageHealth ?? metrics?.storageHealth) ? { storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
     message: mutationSafety?.blocked ? mutationSafety.message : checkpoint.message,
   }, {

package/src/usage-feedback.js

@@ -60,7 +60,6 @@ export const formatUsageFeedback = () => {
   lines.push('');
   lines.push('📊 **devctx usage this session:**');
   
-  // Sort by count descending
   const sorted = usage.tools.sort((a, b) => b.count - a.count);
   
   for (const { tool, count, savedTokens, targets } of sorted) {

package/src/utils/mutation-safety.js

@@ -77,9 +77,9 @@ export const attachSafetyMetadata = (
 
   return {
     ...result,
-    ...(mutationSafety ? { mutationSafety } : {}),
-    repoSafety,
-    sideEffectsSuppressed: Boolean(sideEffectsSuppressed),
+    ...(mutationSafety?.blocked ? { mutationSafety } : {}),
+    ...(repoSafety && (mutationSafety?.blocked || sideEffectsSuppressed) ? { repoSafety } : {}),
+    ...(sideEffectsSuppressed ? { sideEffectsSuppressed: true } : {}),
     ...(degraded ? { degradedMode: degraded } : {}),
   };
 };

package/src/utils/text.js

@@ -8,6 +8,7 @@ export const truncate = (text = '', maxChars = 4000) => {
 
 export const uniqueLines = (text = '') => {
   const seen = new Set();
+  let prevEmpty = false;
 
   return text
     .split('\n')
@@ -15,9 +16,13 @@ export const uniqueLines = (text = '') => {
       const key = line.trim();
 
       if (!key) {
+        if (prevEmpty) return false;
+        prevEmpty = true;
         return true;
       }
 
+      prevEmpty = false;
+
       if (seen.has(key)) {
         return false;
       }

package/src/workflow-tracker.js

@@ -183,7 +183,6 @@ export const endWorkflow = (workflowId) => {
         return null;
       }
 
-    // Get workflow start time and session
     const workflow = db
       .prepare(
         `
@@ -203,7 +202,6 @@ export const endWorkflow = (workflowId) => {
     const endTime = new Date(now);
     const durationMs = endTime - startTime;
 
-    // Get all metrics for this session since workflow start
     const metrics = db
       .prepare(
         `
@@ -215,7 +213,6 @@ export const endWorkflow = (workflowId) => {
       )
       .all(workflow.session_id, workflow.start_time);
 
-    // Calculate totals
     const rawTokens = metrics.reduce((sum, m) => sum + (m.raw_tokens || 0), 0);
     const compressedTokens = metrics.reduce((sum, m) => sum + (m.compressed_tokens || 0), 0);
     const savedTokens = metrics.reduce((sum, m) => sum + (m.saved_tokens || 0), 0);
@@ -231,7 +228,6 @@ export const endWorkflow = (workflowId) => {
     const savingsPct = rawTokens > 0 ? ((savedTokens / rawTokens) * 100).toFixed(2) : 0;
     const netSavingsPct = rawTokens > 0 ? ((netSavedTokens / rawTokens) * 100).toFixed(2) : 0;
 
-    // Calculate vs baseline
     const baselineTokens = workflow.baseline_tokens || 0;
     const vsBaselinePct = baselineTokens > 0 ? (((baselineTokens - compressedTokens) / baselineTokens) * 100).toFixed(2) : 0;
     const vsBaselineNetPct = baselineTokens > 0 ? (((baselineTokens - (compressedTokens + overheadTokens)) / baselineTokens) * 100).toFixed(2) : 0;
@@ -247,10 +243,7 @@ export const endWorkflow = (workflowId) => {
       },
     };
 
-    // Get unique tools used
     const toolsUsed = [...new Set(metrics.map((m) => m.tool))];
-
-    // Update workflow
     const stmt = db.prepare(`
       UPDATE workflow_metrics
       SET end_time = ?,
@@ -584,7 +577,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
         return null;
       }
 
-    // Check if workflow already tracked for this session
     const existing = db
       .prepare(
         `
@@ -601,7 +593,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
       return existing.workflow_id;
     }
 
-    // Get tools used so far in this session
     const metrics = db
       .prepare(
         `
@@ -621,7 +612,6 @@ export const autoTrackWorkflow = (sessionId, sessionGoal) => {
       return null;
     }
 
-      // Start tracking
       return startWorkflow(workflowType, sessionId, { autoDetected: true, goal: sessionGoal });
     });
   } catch {