smart-context-mcp 1.6.0 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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/task-runner.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 import { runTaskRunner } from '../src/task-runner.js';
+import { checkNodeVersion } from '../src/utils/runtime-check.js';
+
+const runtimeCheck = checkNodeVersion();
+if (!runtimeCheck.ok) {
+  console.error(`[smart-context-task] Runtime check failed: ${runtimeCheck.message}`);
+  console.error(`[smart-context-task] Current: ${runtimeCheck.current}, Required: ${runtimeCheck.minimum}+`);
+  process.exit(1);
+}
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];

package/src/server.js

@@ -16,6 +16,7 @@ import { smartMetrics } from './tools/smart-metrics.js';
 import { smartTurn } from './tools/smart-turn.js';
 import { projectRoot, projectRootSource } from './utils/paths.js';
 import { setServerForStreaming } from './streaming.js';
+import { checkNodeVersion } from './utils/runtime-check.js';
 import { 
   getSymbolBlame, 
   getFileAuthorshipStats, 
@@ -44,6 +45,13 @@ export const asTextResult = (result) => ({
 });
 
 export const createDevctxServer = () => {
+  const runtimeCheck = checkNodeVersion();
+  if (!runtimeCheck.ok) {
+    console.error(`[devctx] Runtime check failed: ${runtimeCheck.message}`);
+    console.error(`[devctx] Current: ${runtimeCheck.current}, Required: ${runtimeCheck.minimum}+`);
+    process.exit(1);
+  }
+
   const server = new McpServer({
     name: 'devctx',
     version,

package/src/storage/sqlite.js

@@ -2,12 +2,16 @@ import fs from 'node:fs';
 import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { projectRoot } from '../utils/runtime-config.js';
 
 export const STATE_DB_FILENAME = 'state.sqlite';
 export const SQLITE_SCHEMA_VERSION = 5;
 export const ACTIVE_SESSION_SCOPE = 'project';
 export const STATE_DB_SOFT_MAX_BYTES = 32 * 1024 * 1024;
+const STATE_DB_BUSY_TIMEOUT_MS = 1000;
+const STATE_DB_LOCK_RETRY_ATTEMPTS = 3;
+const STATE_DB_LOCK_RETRY_DELAY_MS = 75;
 export const EXPECTED_TABLES = [
   'active_session',
   'context_access',
@@ -444,7 +448,32 @@ export const getMeta = (db, key) => {
 const getSchemaVersion = (db) => Number(getMeta(db, 'schema_version') ?? 0);
 const VALID_STATUSES = new Set(['planning', 'in_progress', 'blocked', 'completed']);
 
-const applyPragmas = (db) => {
+const isStateDbLockError = (error) =>
+  /database is locked|database table is locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(String(error?.message ?? error ?? ''));
+
+const withStateDbLockRetry = async (operation) => {
+  for (let attempt = 1; attempt <= STATE_DB_LOCK_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isStateDbLockError(error) || attempt === STATE_DB_LOCK_RETRY_ATTEMPTS) {
+        throw error;
+      }
+
+      await delay(STATE_DB_LOCK_RETRY_DELAY_MS * attempt);
+    }
+  }
+
+  throw new Error('SQLite lock retry exhausted unexpectedly.');
+};
+
+const applyPragmas = (db, { readOnly = false } = {}) => {
+  db.exec(`PRAGMA busy_timeout = ${STATE_DB_BUSY_TIMEOUT_MS}`);
+
+  if (readOnly) {
+    return;
+  }
+
   db.exec('PRAGMA foreign_keys = ON');
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');
@@ -505,17 +534,28 @@ export const listStateTables = (db) =>
 
 export const openStateDb = async ({ filePath = getStateDbPath(), readOnly = false } = {}) => {
   try {
-    const { DatabaseSync } = await loadSqliteModule();
-    if (!readOnly) {
-      ensureStateDir(filePath);
-    }
+    return await withStateDbLockRetry(async () => {
+      const { DatabaseSync } = await loadSqliteModule();
+      if (!readOnly) {
+        ensureStateDir(filePath);
+      }
 
-    const db = new DatabaseSync(filePath, readOnly ? { readOnly: true } : {});
-    if (!readOnly) {
-      applyPragmas(db);
-      runStateMigrations(db);
-    }
-    return db;
+      let db = null;
+
+      try {
+        db = new DatabaseSync(filePath, readOnly ? { readOnly: true } : {});
+        applyPragmas(db, { readOnly });
+        if (!readOnly) {
+          runStateMigrations(db);
+        }
+        return db;
+      } catch (error) {
+        try {
+          db?.close();
+        } catch {}
+        throw error;
+      }
+    });
   } catch (error) {
     throw enrichStateDbError(error, { filePath, readOnly });
   }
@@ -1063,6 +1103,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
   const payload = readJsonFile(filePath);
 
   if (!payload || typeof payload !== 'object') {
+    const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
     return {
       type: 'session',
       path: filePath,
@@ -1070,6 +1111,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
       eligible: false,
       reason: 'invalid_json',
       sessionId: null,
+      sizeBytes,
     };
   }
 
@@ -1080,6 +1122,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
     WHERE session_id = ?
   `).get(sessionId);
   if (!sessionRow) {
+    const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
     return {
       type: 'session',
       path: filePath,
@@ -1087,6 +1130,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
       eligible: false,
       reason: 'missing_in_sqlite',
       sessionId,
+      sizeBytes,
     };
   }
 
@@ -1094,6 +1138,8 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
   const sqliteUpdatedAt = toIsoString(sessionRow.updated_at);
   const eligible = getTimestamp(sqliteUpdatedAt) >= getTimestamp(fileUpdatedAt);
 
+  const sizeBytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+
   return {
     type: 'session',
     path: filePath,
@@ -1101,6 +1147,7 @@ const buildSessionCleanupCandidate = (db, sessionsDir, fileName) => {
     eligible,
     reason: eligible ? 'imported_and_not_newer_than_sqlite' : 'legacy_file_newer_than_sqlite',
     sessionId,
+    sizeBytes,
     fileUpdatedAt,
     sqliteUpdatedAt,
   };
@@ -1113,34 +1160,40 @@ const buildActiveCleanupCandidate = (db, activeSessionFile) => {
 
   const payload = readJsonFile(activeSessionFile);
   if (!payload || typeof payload !== 'object') {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: false,
       reason: 'invalid_json',
       sessionId: null,
+      sizeBytes,
     };
   }
 
   const legacySessionId = typeof payload.sessionId === 'string' ? payload.sessionId : null;
   const activeRow = getActiveSessionRow(db);
   if (!legacySessionId) {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: true,
       reason: 'orphaned_legacy_file',
       sessionId: null,
+      sizeBytes,
     };
   }
 
   if (!activeRow) {
+    const sizeBytes = fs.statSync(activeSessionFile).size;
     return {
       type: 'active_session',
       path: activeSessionFile,
       eligible: true,
       reason: 'sqlite_has_no_active_session',
       sessionId: legacySessionId,
+      sizeBytes,
     };
   }
 
@@ -1149,12 +1202,15 @@ const buildActiveCleanupCandidate = (db, activeSessionFile) => {
   const eligible = activeRow.session_id === legacySessionId
     && getTimestamp(sqliteUpdatedAt) >= getTimestamp(fileUpdatedAt);
 
+  const sizeBytes = fs.existsSync(activeSessionFile) ? fs.statSync(activeSessionFile).size : 0;
+
   return {
     type: 'active_session',
     path: activeSessionFile,
     eligible,
     reason: eligible ? 'sqlite_active_session_matches' : 'sqlite_active_session_differs',
     sessionId: legacySessionId,
+    sizeBytes,
     fileUpdatedAt,
     sqliteUpdatedAt,
   };
@@ -1167,12 +1223,14 @@ const buildMetricsCleanupCandidate = (db, metricsFile) => {
 
   const { entries, invalidLines } = readMetricsEntries(metricsFile);
   if (invalidLines.length > 0) {
+    const sizeBytes = fs.statSync(metricsFile).size;
     return {
       type: 'metrics',
       path: metricsFile,
       eligible: false,
       reason: 'invalid_jsonl',
       entryCount: entries.length,
+      sizeBytes,
       invalidLines,
       missingEntries: [],
     };
@@ -1191,12 +1249,15 @@ const buildMetricsCleanupCandidate = (db, metricsFile) => {
     }
   }
 
+  const sizeBytes = fs.existsSync(metricsFile) ? fs.statSync(metricsFile).size : 0;
+
   return {
     type: 'metrics',
     path: metricsFile,
     eligible: missingEntries.length === 0,
     reason: missingEntries.length === 0 ? 'all_entries_imported' : 'sqlite_missing_entries',
     entryCount: entries.length,
+    sizeBytes,
     invalidLines,
     missingEntries,
   };

package/src/task-runner.js

@@ -1,5 +1,7 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { persistMetrics } from './metrics.js';
 import { countTokens } from './tokenCounter.js';
+import { projectRoot } from './utils/paths.js';
 import { TASK_RUNNER_QUALITY_ANALYTICS_KIND } from './analytics/product-quality.js';
 import { runHeadlessWrapper } from './orchestration/headless-wrapper.js';
 import { smartContext } from './tools/smart-context.js';
@@ -22,6 +24,8 @@ import {
 
 const START_MAX_TOKENS = 350;
 const END_MAX_TOKENS = 350;
+const RUNNER_LOCK_RETRY_ATTEMPTS = 3;
+const RUNNER_LOCK_RETRY_DELAY_MS = 100;
 
 const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
 const truncate = (value, maxLength = 160) => {
@@ -39,6 +43,13 @@ const truncate = (value, maxLength = 160) => {
 
 const asArray = (value) => Array.isArray(value) ? value : [];
 const uniqueCompact = (values) => [...new Set(asArray(values).map((value) => normalizeWhitespace(value)).filter(Boolean))];
+const extractContextTopFiles = (topFiles) => uniqueCompact(asArray(topFiles).map((item) => {
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  return item?.file ?? item?.path ?? '';
+})).slice(0, 3);
 
 const extractPreflightTopFiles = (preflightResult) => {
   if (!preflightResult) {
@@ -50,12 +61,7 @@ const extractPreflightTopFiles = (preflightResult) => {
   }
 
   if (preflightResult.tool === 'smart_search') {
-    return uniqueCompact(asArray(preflightResult.result?.topFiles).map((item) => {
-      if (typeof item === 'string') {
-        return item;
-      }
-      return item?.file ?? item?.path ?? '';
-    })).slice(0, 3);
+    return extractContextTopFiles(preflightResult.result?.topFiles);
   }
 
   return [];
@@ -100,7 +106,7 @@ const buildPreflightTask = ({ workflowProfile, prompt, startResult }) => {
   const normalizedPrompt = normalizeWhitespace(prompt);
   const persistedNextStep = normalizeWhitespace(startResult?.summary?.nextStep);
   const currentFocus = normalizeWhitespace(startResult?.summary?.currentFocus);
-  const refreshedTopFiles = uniqueCompact(startResult?.refreshedContext?.topFiles).slice(0, 3);
+  const refreshedTopFiles = extractContextTopFiles(startResult?.refreshedContext?.topFiles);
 
   if (workflowProfile.commandName === 'continue' || workflowProfile.commandName === 'resume') {
     if (persistedNextStep) {
@@ -178,7 +184,7 @@ const buildContinuityGuidance = ({ startResult }) => {
   ];
   const nextStep = normalizeWhitespace(startResult?.summary?.nextStep);
   const currentFocus = normalizeWhitespace(startResult?.summary?.currentFocus);
-  const refreshedTopFiles = uniqueCompact(startResult?.refreshedContext?.topFiles).slice(0, 3);
+  const refreshedTopFiles = extractContextTopFiles(startResult?.refreshedContext?.topFiles);
   const recommendedNextTools = asArray(startResult?.recommendedPath?.nextTools)
     .map((tool) => normalizeWhitespace(tool))
     .filter(Boolean)
@@ -253,6 +259,29 @@ const buildWorkflowPolicyPayload = ({ commandName, workflowProfile, preflightSum
   preflight: preflightSummary,
 });
 
+const isRetriableLockError = (error) => {
+  const issue = error?.storageHealth?.issue ?? error?.cause?.storageHealth?.issue ?? null;
+  const retriable = error?.storageHealth?.retriable ?? error?.cause?.storageHealth?.retriable ?? false;
+  const message = String(error?.message ?? error?.cause?.message ?? error ?? '');
+  return retriable || issue === 'locked' || /database is locked|database table is locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(message);
+};
+
+const withRunnerLockRetry = async (operation) => {
+  for (let attempt = 1; attempt <= RUNNER_LOCK_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isRetriableLockError(error) || attempt === RUNNER_LOCK_RETRY_ATTEMPTS) {
+        throw error;
+      }
+
+      await delay(RUNNER_LOCK_RETRY_DELAY_MS * attempt);
+    }
+  }
+
+  throw new Error('Task runner lock retry exhausted unexpectedly.');
+};
+
 const recordRunnerMetrics = async ({
   commandName,
   client,
@@ -330,13 +359,13 @@ const runWorkflowCommand = async ({
   });
   const workflowProfile = buildWorkflowPolicyProfile({ commandName });
 
-  const start = await smartTurn({
+  const start = await withRunnerLockRetry(() => smartTurn({
     phase: 'start',
     sessionId,
     prompt: requestedPrompt,
     ensureSession: true,
     maxTokens: START_MAX_TOKENS,
-  });
+  }));
 
   const gate = evaluateRunnerGate({ startResult: start });
   let preflightSummary = null;
@@ -363,7 +392,7 @@ const runWorkflowCommand = async ({
   });
 
   if (gate.requiresDoctor && !allowDegraded) {
-    const doctor = await smartDoctor();
+    const doctor = await withRunnerLockRetry(() => smartDoctor());
     const blockedResult = buildRunnerBlockedResult({
       commandName,
       client,
@@ -423,7 +452,7 @@ const runWorkflowCommand = async ({
 };
 
 const runDoctorCommand = async ({ verifyIntegrity = true, client }) => {
-  const result = await smartDoctor({ verifyIntegrity });
+  const result = await withRunnerLockRetry(() => smartDoctor({ verifyIntegrity }));
   await recordRunnerMetrics({
     commandName: 'doctor',
     client,
@@ -436,7 +465,7 @@ const runDoctorCommand = async ({ verifyIntegrity = true, client }) => {
 };
 
 const runStatusCommand = async ({ format = 'compact', maxItems = 10, client }) => {
-  const result = await smartStatus({ format, maxItems });
+  const result = await withRunnerLockRetry(() => smartStatus({ format, maxItems }));
   await recordRunnerMetrics({
     commandName: 'status',
     client,
@@ -451,13 +480,13 @@ const runCheckpointCommand = async ({
   event = 'milestone',
   update = {},
 }) => {
-  const result = await smartTurn({
+  const result = await withRunnerLockRetry(() => smartTurn({
     phase: 'end',
     sessionId,
     event,
     update,
     maxTokens: END_MAX_TOKENS,
-  });
+  }));
   await recordRunnerMetrics({
     commandName: 'checkpoint',
     client,
@@ -485,10 +514,57 @@ const runCleanupCommand = async ({
   });
 
   if (cleanupMode === 'legacy') {
-    const result = await smartSummary({
+    const dryRun = await smartSummary({
       action: 'cleanup_legacy',
-      apply,
+      apply: false,
     });
+
+    if (!apply) {
+      const eligibleFiles = [];
+
+      if (dryRun.sessions?.candidates) {
+        for (const session of dryRun.sessions.candidates) {
+          if (session.deletable) {
+            eligibleFiles.push({
+              relativePath: session.relativePath || session.path,
+              sizeBytes: session.sizeBytes || 0,
+            });
+          }
+        }
+      }
+
+      if (dryRun.metrics?.eligible && dryRun.metrics?.path) {
+        eligibleFiles.push({
+          relativePath: dryRun.metrics.path.replace(projectRoot + '/', ''),
+          sizeBytes: dryRun.metrics.sizeBytes || 0,
+        });
+      }
+
+      if (dryRun.activeSession?.eligible && dryRun.activeSession?.path) {
+        eligibleFiles.push({
+          relativePath: dryRun.activeSession.path.replace(projectRoot + '/', ''),
+          sizeBytes: dryRun.activeSession.sizeBytes || 0,
+        });
+      }
+
+      if (eligibleFiles.length > 0) {
+        console.log('\n📋 Legacy files eligible for cleanup:\n');
+        console.log('File                                      Size');
+        console.log('─'.repeat(60));
+        for (const file of eligibleFiles) {
+          const sizeKB = file.sizeBytes ? `${(file.sizeBytes / 1024).toFixed(1)}KB` : 'N/A';
+          console.log(`${file.relativePath.padEnd(42)} ${sizeKB}`);
+        }
+        const totalKB = eligibleFiles.reduce((sum, f) => sum + (f.sizeBytes || 0), 0) / 1024;
+        console.log('─'.repeat(60));
+        console.log(`Total: ${eligibleFiles.length} files, ${totalKB.toFixed(1)}KB\n`);
+        console.log('💡 To apply cleanup, run: smart-context-task cleanup --cleanup-mode legacy --apply\n');
+      } else {
+        console.log('\n✅ No legacy files eligible for cleanup.\n');
+      }
+    }
+
+    const result = apply ? await smartSummary({ action: 'cleanup_legacy', apply: true }) : dryRun;
     const payload = {
       command: 'cleanup',
       cleanupMode,

package/src/tools/smart-doctor.js

@@ -68,6 +68,76 @@ const readMaintenanceSnapshot = async ({ filePath, storageHealth }) => {
   try {
     return await withStateDbSnapshot((db) => {
       const count = (tableName) => db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get().count;
+      const retentionDays = Number(getMeta(db, 'state_compaction_retention_days') ?? DEFAULT_RETENTION_DAYS);
+      const activeSessionId = db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null;
+      const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+      const hookTurnCutoff = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
+      const staleSessionsQuery = activeSessionId
+        ? db.prepare(`
+          SELECT COUNT(*) AS count
+          FROM sessions
+          WHERE datetime(updated_at) < datetime(?)
+            AND session_id != ?
+        `)
+        : db.prepare(`
+          SELECT COUNT(*) AS count
+          FROM sessions
+          WHERE datetime(updated_at) < datetime(?)
+        `);
+      const staleSessions = activeSessionId
+        ? staleSessionsQuery.get(cutoff, activeSessionId).count
+        : staleSessionsQuery.get(cutoff).count;
+      const staleSessionEventsQuery = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM (
+          SELECT
+            se.event_id,
+            se.created_at,
+            ROW_NUMBER() OVER (
+              PARTITION BY se.session_id
+              ORDER BY datetime(se.created_at) DESC, se.event_id DESC
+            ) AS row_num
+          FROM session_events se
+          JOIN sessions s ON s.session_id = se.session_id
+          WHERE datetime(s.updated_at) >= datetime(@cutoff)
+             OR s.session_id = @activeSessionId
+        )
+        WHERE row_num > @keepLatest
+          AND datetime(created_at) < datetime(@cutoff)
+      `);
+      const staleMetricsQuery = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM (
+          SELECT
+            metric_id,
+            created_at,
+            ROW_NUMBER() OVER (
+              ORDER BY datetime(created_at) DESC, metric_id DESC
+            ) AS row_num
+          FROM metrics_events
+        )
+        WHERE row_num > @keepLatest
+          AND datetime(created_at) < datetime(@cutoff)
+      `);
+      const staleHookTurns = db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM hook_turn_state
+        WHERE datetime(updated_at) < datetime(?)
+      `).get(hookTurnCutoff).count;
+      const compactionEstimate = {
+        sessionsDeleted: staleSessions,
+        sessionEventsDeleted: staleSessionEventsQuery.get({
+          cutoff,
+          activeSessionId,
+          keepLatest: DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION,
+        }).count,
+        metricsEventsDeleted: staleMetricsQuery.get({
+          cutoff,
+          keepLatest: DEFAULT_KEEP_LATEST_METRICS,
+        }).count,
+        hookTurnStateDeleted: staleHookTurns,
+      };
+      compactionEstimate.totalDeletes = Object.values(compactionEstimate).reduce((total, value) => total + value, 0);
 
       return {
         available: true,
@@ -78,14 +148,15 @@ const readMaintenanceSnapshot = async ({ filePath, storageHealth }) => {
           hookTurnState: count('hook_turn_state'),
           workflowMetrics: count('workflow_metrics'),
         },
-        activeSessionId: db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null,
+        activeSessionId,
         schemaVersion: Number(getMeta(db, 'schema_version') ?? 0),
         lastCompactedAt: getMeta(db, 'state_compacted_at'),
-        retentionDays: Number(getMeta(db, 'state_compaction_retention_days') ?? DEFAULT_RETENTION_DAYS),
+        retentionDays,
         legacyImport: {
           sessions: Number(getMeta(db, 'legacy_sessions_import_count') ?? 0),
           metrics: Number(getMeta(db, 'legacy_metrics_import_count') ?? 0),
         },
+        compactionEstimate,
       };
     }, { filePath });
   } catch (error) {
@@ -227,21 +298,30 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
     retentionDays,
     schemaVersion,
     activeSessionId,
+    compactionEstimate = {
+      sessionsDeleted: 0,
+      sessionEventsDeleted: 0,
+      metricsEventsDeleted: 0,
+      hookTurnStateDeleted: 0,
+      totalDeletes: 0,
+    },
   } = maintenance;
   const daysSinceCompaction = daysSince(lastCompactedAt);
   const sessionEventThreshold = Math.max(SESSION_EVENTS_WARNING_FLOOR, counts.sessions * DEFAULT_KEEP_LATEST_EVENTS_PER_SESSION * 5);
   const needsCompaction = [];
+  const canReclaimRows = compactionEstimate.totalDeletes > 0;
 
   if (storageHealth.issue === 'oversized') {
     needsCompaction.push('database_size');
   }
 
-  if (!lastCompactedAt && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
+  if (!lastCompactedAt && canReclaimRows && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
     needsCompaction.push('never_compacted');
   }
 
   if (
     daysSinceCompaction !== null
+    && canReclaimRows
     && daysSinceCompaction > retentionDays
     && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > DEFAULT_KEEP_LATEST_METRICS)
   ) {
@@ -249,12 +329,19 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
   }
 
   if (needsCompaction.length > 0) {
+    const totalRows = compactionEstimate.totalDeletes;
+    const estimatedBytes = Math.round(storageHealth.sizeBytes * (totalRows / (counts.sessions + counts.sessionEvents + counts.metricsEvents + counts.hookTurnState)));
+    const pctReduction = Math.round((estimatedBytes / storageHealth.sizeBytes) * 100);
+    const impactSummary = totalRows > 0
+      ? `Estimated impact: ~${totalRows} rows, ~${(estimatedBytes / 1024 / 1024).toFixed(1)}MB (${pctReduction}% reduction)`
+      : 'Estimated impact: minimal (no rows to delete with current retention policy)';
+
     return buildCheck({
       id: 'compaction',
       status: 'warning',
       message: 'SQLite retention/compaction hygiene should be refreshed before the local state grows further.',
       recommendedActions: [
-        'Run smart_summary with action="compact" to prune old events and metrics.',
+        `Run smart_summary with action="compact" to prune old events and metrics. ${impactSummary}`,
         'Use vacuum=true if you expect large deletions and want to reclaim file size immediately.',
       ],
       details: {
@@ -264,6 +351,33 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
         schemaVersion,
         activeSessionId,
         counts,
+        compactionEstimate,
+        estimatedImpact: {
+          rowsToDelete: totalRows,
+          bytesReclaimed: estimatedBytes,
+          pctReduction,
+        },
+        lastCompactedAt,
+        daysSinceCompaction,
+        retentionDays,
+      },
+    });
+  }
+
+  if (!lastCompactedAt && !canReclaimRows && (counts.sessionEvents > sessionEventThreshold || counts.metricsEvents > METRICS_WARNING_FLOOR)) {
+    return buildCheck({
+      id: 'compaction',
+      status: 'info',
+      message: 'SQLite state has never been compacted, but the current retention policy would not reclaim any rows yet.',
+      recommendedActions: [],
+      details: {
+        available: true,
+        recommended: false,
+        reason: 'baseline_not_initialized',
+        schemaVersion,
+        activeSessionId,
+        counts,
+        compactionEstimate,
         lastCompactedAt,
         daysSinceCompaction,
         retentionDays,
@@ -282,6 +396,7 @@ const buildCompactionCheck = ({ storageHealth, maintenance }) => {
       schemaVersion,
       activeSessionId,
       counts,
+      compactionEstimate,
       lastCompactedAt,
       daysSinceCompaction,
       retentionDays,

package/src/tools/smart-shell.js

@@ -10,7 +10,6 @@ import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
-const blockedPattern = /[|&;<>`\n\r$()]/;
 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']);
@@ -20,8 +19,8 @@ const dangerousPatterns = [
   /sudo/i,
   /curl.*\|/i,
   /wget.*\|/i,
-  /eval/i,
-  /exec/i,
+  /(^|\s)eval(\s|$)/i,
+  /(^|\s)exec(\s|$)/i,
 ];
 const MAX_COMMAND_LENGTH = 500;
 
@@ -79,6 +78,45 @@ const tokenize = (command) => {
   return tokens;
 };
 
+const hasUnquotedShellOperators = (command) => {
+  let inQuote = null;
+  let prevWasEscape = false;
+
+  for (const char of command) {
+    if (prevWasEscape) {
+      prevWasEscape = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      prevWasEscape = true;
+      continue;
+    }
+
+    if (inQuote) {
+      if (char === inQuote) {
+        inQuote = null;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inQuote = char;
+      continue;
+    }
+
+    if (/[|&;<>`\n\r$]/.test(char)) {
+      return true;
+    }
+
+    if (char === '(' || char === ')') {
+      return true;
+    }
+  }
+
+  return false;
+};
+
 const validateCommand = (command, tokens) => {
   if (isShellDisabled()) {
     return 'Shell execution is disabled (DEVCTX_SHELL_DISABLED=true)';
@@ -92,8 +130,8 @@ const validateCommand = (command, tokens) => {
     return `Command too long (max ${MAX_COMMAND_LENGTH} chars)`;
   }
 
-  if (blockedPattern.test(command)) {
-    return 'Shell operators are not allowed (|, &, ;, <, >, `, $, (, ))';
+  if (hasUnquotedShellOperators(command)) {
+    return 'Shell operators are not allowed outside quotes (|, &, ;, <, >, `, $, (, ))';
   }
 
   for (const pattern of dangerousPatterns) {

package/src/utils/runtime-check.js

@@ -0,0 +1,52 @@
+const MINIMUM_NODE_VERSION = 22;
+const MINIMUM_NODE_VERSION_REASON = 'node:sqlite and node:test require Node 22+';
+
+const parseNodeVersion = (versionString) => {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(versionString);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw: versionString,
+  };
+};
+
+export const checkNodeVersion = (versionString = process.version) => {
+  const current = parseNodeVersion(versionString);
+
+  if (!current) {
+    return {
+      ok: false,
+      current: versionString,
+      minimum: MINIMUM_NODE_VERSION,
+      message: `Unable to parse Node version: ${versionString}`,
+      reason: MINIMUM_NODE_VERSION_REASON,
+    };
+  }
+
+  const ok = current.major >= MINIMUM_NODE_VERSION;
+
+  return {
+    ok,
+    current: current.raw,
+    minimum: MINIMUM_NODE_VERSION,
+    message: ok
+      ? `Node ${current.raw} meets minimum requirement (${MINIMUM_NODE_VERSION}+)`
+      : `Node ${current.raw} is below minimum requirement (${MINIMUM_NODE_VERSION}+). ${MINIMUM_NODE_VERSION_REASON}`,
+    reason: ok ? null : MINIMUM_NODE_VERSION_REASON,
+  };
+};
+
+export const assertNodeVersion = (versionString = process.version) => {
+  const check = checkNodeVersion(versionString);
+
+  if (!check.ok) {
+    throw new Error(check.message);
+  }
+
+  return check;
+};

package/src/utils/runtime-config.js

@@ -27,14 +27,14 @@ const readEnvValue = (...names) => {
 };
 
 const defaultDevctxRoot = path.resolve(currentDir, '..', '..');
-const defaultProjectRoot = path.resolve(defaultDevctxRoot, '..', '..');
+const defaultProjectRoot = path.resolve(process.cwd());
 const projectRootArg = readArgValue('--project-root');
 const projectRootEnv = readEnvValue('DEVCTX_PROJECT_ROOT', 'MCP_PROJECT_ROOT');
 const rawProjectRoot = projectRootArg ?? projectRootEnv ?? defaultProjectRoot;
 
 export const devctxRoot = defaultDevctxRoot;
 export let projectRoot = path.resolve(rawProjectRoot);
-export const projectRootSource = projectRootArg ? 'argv' : projectRootEnv ? 'env' : 'default';
+export const projectRootSource = projectRootArg ? 'argv' : projectRootEnv ? 'env' : 'cwd';
 
 export const setProjectRoot = (newRoot) => {
   projectRoot = path.resolve(newRoot);