smart-context-mcp 1.16.4 → 1.17.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.16.4 (or later)
+# Should show: smart-context-mcp@1.17.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.16.4",
+  "version": "1.17.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/server.json

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

package/src/client-contract.js

@@ -52,8 +52,11 @@ export const buildRecommendedPathLines = (
     lines.push(`${nextToolsLabel}: ${recommendedPath.nextTools.slice(0, 3).join(' -> ')}`);
   }
 
-  if (includePath && recommendedPath.steps?.[0]?.instruction) {
-    lines.push(`${pathLabel}: ${truncate(recommendedPath.steps[0].instruction, maxLength)}`);
+  if (includePath) {
+    const pathInstruction = recommendedPath.steps?.[0]?.instruction ?? recommendedPath.next ?? null;
+    if (pathInstruction) {
+      lines.push(`${pathLabel}: ${truncate(pathInstruction, maxLength)}`);
+    }
   }
 
   return lines;

package/src/index-manager.js

@@ -128,3 +128,24 @@ export const getIndexStatus = (root = projectRoot) => {
     age: meta?.builtAt ? Date.now() - meta.builtAt : null
   };
 };
+
+let backgroundBuildPromise = null;
+
+export const triggerBackgroundIndexBuild = ({ root = projectRoot, timeoutMs = INDEX_BUILD_TIMEOUT_MS } = {}) => {
+  if (backgroundBuildPromise) {
+    return backgroundBuildPromise;
+  }
+
+  const status = getIndexStatus(root);
+  if (status.available && status.fresh) {
+    return Promise.resolve({ status: 'fresh', cached: true });
+  }
+
+  backgroundBuildPromise = ensureIndexReady({ root, timeoutMs })
+    .catch((error) => ({ status: 'error', error: error?.message ?? String(error) }))
+    .finally(() => {
+      backgroundBuildPromise = null;
+    });
+
+  return backgroundBuildPromise;
+};

package/src/index.js

@@ -5,7 +5,7 @@ import ts from 'typescript';
 import { isBinaryBuffer } from './utils/fs.js';
 import { IGNORED_DIRS } from './config/ignored-paths.js';
 
-const INDEX_VERSION = 4;
+const INDEX_VERSION = 5;
 
 const MAX_SIGNATURE_LEN = 200;
 const MAX_SNIPPET_LEN = 280;
@@ -722,8 +722,6 @@ export const buildIndex = (root, progress = null) => {
         if (!invertedIndex[key]) invertedIndex[key] = [];
         const entry = { path: relPath, line: sym.line, kind: sym.kind };
         if (sym.parent) entry.parent = sym.parent;
-        if (sym.signature) entry.signature = sym.signature;
-        if (sym.snippet) entry.snippet = sym.snippet;
         invertedIndex[key].push(entry);
       }
     } catch { /* unreadable */ }
@@ -783,10 +781,24 @@ export const buildIndex = (root, progress = null) => {
 // Query helpers
 // ---------------------------------------------------------------------------
 
+const findSymbolForHit = (index, key, hit) => {
+  const symbols = index.files?.[hit.path]?.symbols;
+  if (!Array.isArray(symbols)) return null;
+  return symbols.find((sym) => sym.name?.toLowerCase() === key && sym.line === hit.line) ?? null;
+};
+
 export const queryIndex = (index, symbolName) => {
   if (!index?.invertedIndex) return [];
   const key = symbolName.toLowerCase();
-  return index.invertedIndex[key] ?? [];
+  const hits = index.invertedIndex[key] ?? [];
+  return hits.map((hit) => {
+    const sym = findSymbolForHit(index, key, hit);
+    if (!sym) return hit;
+    const enriched = { ...hit };
+    if (sym.signature && !enriched.signature) enriched.signature = sym.signature;
+    if (sym.snippet && !enriched.snippet) enriched.snippet = sym.snippet;
+    return enriched;
+  });
 };
 
 export const queryRelated = (index, relPath) => {
@@ -873,8 +885,6 @@ export const reindexFile = (index, root, relPath) => {
       if (!index.invertedIndex[key]) index.invertedIndex[key] = [];
       const invEntry = { path: relPath, line: sym.line, kind: sym.kind };
       if (sym.parent) invEntry.parent = sym.parent;
-      if (sym.signature) invEntry.signature = sym.signature;
-      if (sym.snippet) invEntry.snippet = sym.snippet;
       index.invertedIndex[key].push(invEntry);
     }
 

package/src/orchestration/adapters/claude-adapter.js

@@ -12,7 +12,15 @@ import {
   upsertAgentRun,
 } from '../../storage/sqlite.js';
 import { DEFAULT_START_MAX_TOKENS, resolveManagedStart } from '../base-orchestrator.js';
-import { extractNextStep, normalizeWhitespace, truncate } from '../policy/event-policy.js';
+import {
+  MAX_READ_FILES,
+  READ_CHECKPOINT_THRESHOLD,
+  READ_CHECKPOINT_THROTTLE_MS,
+  extractNextStep,
+  extractReadPathsFromToolUse,
+  normalizeWhitespace,
+  truncate,
+} from '../policy/event-policy.js';
 
 export const HOOK_CLIENT = 'claude';
 export const STOP_MAX_TOKENS = 300;
@@ -204,6 +212,11 @@ export const createClaudeAdapter = ({
     const autoStartTriggered = action === 'SessionStart' || action === 'UserPromptSubmit';
     const autoCheckpointTriggered = action === 'Stop' && autoAppended;
 
+    const shouldPersist = autoStartTriggered || autoCheckpointTriggered || blocked || overheadTokens > 0;
+    if (!shouldPersist) {
+      return;
+    }
+
     await persistMetric({
       tool: 'claude_hook',
       action,
@@ -266,10 +279,88 @@ export const createClaudeAdapter = ({
         checkpointEvent: null,
         touchedFiles: [],
         meaningfulWriteCount: 0,
+        readFiles: [],
+        meaningfulReadCount: 0,
+        lastReadCheckpointAt: 0,
       },
     });
   };
 
+  const maybeAutoCheckpointFromState = async (state, { trigger = 'post_tool_use', mode = 'milestone' } = {}) => {
+    if (!state?.projectSessionId || getMutationSafety().shouldBlock) {
+      return false;
+    }
+
+    if (mode === 'read_progress') {
+      const filesForUpdate = state.readFiles.slice(-MAX_READ_FILES);
+      if (filesForUpdate.length === 0) {
+        return false;
+      }
+
+      await summaryTool({
+        action: 'auto_append',
+        sessionId: state.projectSessionId,
+        update: {
+          ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+          touchedFiles: filesForUpdate,
+        },
+        maxTokens: STOP_MAX_TOKENS,
+      });
+
+      if (state.taskId) {
+        await writeTaskHandoff({
+          taskId: state.taskId,
+          sessionId: state.projectSessionId,
+          fromAgentId: state.agentId ?? null,
+          toAgentId: null,
+          trigger: 'read_progress',
+          summary: {
+            currentFocus: state.promptPreview,
+            touchedFiles: filesForUpdate,
+            pending: [],
+            nextStep: null,
+            evidence: [`Exploration: ${filesForUpdate.length} file(s) read`],
+          },
+        });
+      }
+
+      return true;
+    }
+
+    const update = {
+      ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+      ...(state.touchedFiles.length > 0 ? { touchedFiles: state.touchedFiles } : {}),
+    };
+
+    await summaryTool({
+      action: 'checkpoint',
+      sessionId: state.projectSessionId,
+      event: 'milestone',
+      update,
+      maxTokens: STOP_MAX_TOKENS,
+      force: true,
+    });
+
+    if (state.taskId) {
+      await writeTaskHandoff({
+        taskId: state.taskId,
+        sessionId: state.projectSessionId,
+        fromAgentId: state.agentId ?? null,
+        toAgentId: null,
+        trigger,
+        summary: {
+          currentFocus: state.promptPreview,
+          touchedFiles: state.touchedFiles,
+          pending: [],
+          nextStep: null,
+          evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+        },
+      });
+    }
+
+    return true;
+  };
+
   const handleSessionStart = async () => {
     const result = await startTurn({
       phase: 'start',
@@ -349,18 +440,60 @@ export const createClaudeAdapter = ({
       toolInput: input.tool_input,
       toolResponse: input.tool_response,
     });
-
-    const nextState = {
+    const readPaths = touchedFiles.length === 0 && !checkpoint.matched
+      ? extractReadPathsFromToolUse({ toolName: input.tool_name, toolInput: input.tool_input })
+      : [];
+
+    const previousReadFiles = Array.isArray(existing.readFiles) ? existing.readFiles : [];
+    const previousReadCount = Number.isFinite(existing.meaningfulReadCount) ? existing.meaningfulReadCount : 0;
+    const readFiles = readPaths.length > 0
+      ? uniq([...previousReadFiles, ...readPaths]).slice(-MAX_READ_FILES)
+      : previousReadFiles;
+    const meaningfulReadCount = readPaths.length > 0 ? previousReadCount + 1 : previousReadCount;
+
+    let nextState = {
       ...existing,
       checkpointed: checkpoint.matched ? true : existing.checkpointed,
       checkpointEvent: checkpoint.matched ? checkpoint.event : existing.checkpointEvent,
       touchedFiles: uniq([...existing.touchedFiles, ...touchedFiles]).slice(0, MAX_TOUCHED_FILES),
       meaningfulWriteCount: existing.meaningfulWriteCount + touchedFiles.length,
+      readFiles,
+      meaningfulReadCount,
+      lastReadCheckpointAt: existing.lastReadCheckpointAt ?? 0,
       updatedAt: new Date().toISOString(),
     };
 
+    if (!checkpoint.matched && touchedFiles.length > 0) {
+      const autoCheckpointed = await maybeAutoCheckpointFromState(nextState, { trigger: 'post_tool_use' });
+      if (autoCheckpointed) {
+        nextState = {
+          ...nextState,
+          checkpointed: true,
+          checkpointEvent: 'milestone',
+        };
+      }
+    } else if (
+      !checkpoint.matched
+      && touchedFiles.length === 0
+      && meaningfulReadCount >= READ_CHECKPOINT_THRESHOLD
+      && Date.now() - (nextState.lastReadCheckpointAt ?? 0) >= READ_CHECKPOINT_THROTTLE_MS
+    ) {
+      const autoAppended = await maybeAutoCheckpointFromState(nextState, {
+        trigger: 'read_progress',
+        mode: 'read_progress',
+      });
+      if (autoAppended) {
+        nextState = {
+          ...nextState,
+          readFiles: [],
+          meaningfulReadCount: 0,
+          lastReadCheckpointAt: Date.now(),
+        };
+      }
+    }
+
     await maybeSetTrackedTurnState({ hookKey, state: nextState });
-    if (checkpoint.matched || touchedFiles.length > 0) {
+    if (checkpoint.matched || touchedFiles.length > 0 || readPaths.length > 0) {
       await recordHookMetrics({
         action: 'PostToolUse',
         sessionId: existing.projectSessionId,

package/src/orchestration/adapters/cursor-adapter.js

@@ -12,7 +12,15 @@ import {
   upsertAgentRun,
 } from '../../storage/sqlite.js';
 import { DEFAULT_START_MAX_TOKENS, resolveManagedStart } from '../base-orchestrator.js';
-import { extractNextStep, normalizeWhitespace, truncate } from '../policy/event-policy.js';
+import {
+  MAX_READ_FILES,
+  READ_CHECKPOINT_THRESHOLD,
+  READ_CHECKPOINT_THROTTLE_MS,
+  extractNextStep,
+  extractReadPathsFromToolUse,
+  normalizeWhitespace,
+  truncate,
+} from '../policy/event-policy.js';
 
 export const HOOK_CLIENT = 'cursor';
 export const STOP_MAX_TOKENS = 300;
@@ -207,6 +215,11 @@ export const createCursorAdapter = ({
     const autoStartTriggered = action === 'ConversationStart' || action === 'UserMessageSubmit';
     const autoCheckpointTriggered = action === 'ConversationEnd' && autoAppended;
 
+    const shouldPersist = autoStartTriggered || autoCheckpointTriggered || blocked || overheadTokens > 0;
+    if (!shouldPersist) {
+      return;
+    }
+
     await persistMetric({
       tool: 'cursor_hook',
       action,
@@ -269,10 +282,88 @@ export const createCursorAdapter = ({
         checkpointEvent: null,
         touchedFiles: [],
         meaningfulWriteCount: 0,
+        readFiles: [],
+        meaningfulReadCount: 0,
+        lastReadCheckpointAt: 0,
       },
     });
   };
 
+  const maybeAutoCheckpointFromState = async (state, { trigger = 'post_tool_use', mode = 'milestone' } = {}) => {
+    if (!state?.projectSessionId || getMutationSafety().shouldBlock) {
+      return false;
+    }
+
+    if (mode === 'read_progress') {
+      const filesForUpdate = state.readFiles.slice(-MAX_READ_FILES);
+      if (filesForUpdate.length === 0) {
+        return false;
+      }
+
+      await summaryTool({
+        action: 'auto_append',
+        sessionId: state.projectSessionId,
+        update: {
+          ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+          touchedFiles: filesForUpdate,
+        },
+        maxTokens: STOP_MAX_TOKENS,
+      });
+
+      if (state.taskId) {
+        await writeTaskHandoff({
+          taskId: state.taskId,
+          sessionId: state.projectSessionId,
+          fromAgentId: state.agentId ?? null,
+          toAgentId: null,
+          trigger: 'read_progress',
+          summary: {
+            currentFocus: state.promptPreview,
+            touchedFiles: filesForUpdate,
+            pending: [],
+            nextStep: null,
+            evidence: [`Exploration: ${filesForUpdate.length} file(s) read`],
+          },
+        });
+      }
+
+      return true;
+    }
+
+    const update = {
+      ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+      ...(state.touchedFiles.length > 0 ? { touchedFiles: state.touchedFiles } : {}),
+    };
+
+    await summaryTool({
+      action: 'checkpoint',
+      sessionId: state.projectSessionId,
+      event: 'milestone',
+      update,
+      maxTokens: STOP_MAX_TOKENS,
+      force: true,
+    });
+
+    if (state.taskId) {
+      await writeTaskHandoff({
+        taskId: state.taskId,
+        sessionId: state.projectSessionId,
+        fromAgentId: state.agentId ?? null,
+        toAgentId: null,
+        trigger,
+        summary: {
+          currentFocus: state.promptPreview,
+          touchedFiles: state.touchedFiles,
+          pending: [],
+          nextStep: null,
+          evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+        },
+      });
+    }
+
+    return true;
+  };
+
   const handleConversationStart = async () => {
     const result = await startTurn({
       phase: 'start',
@@ -352,18 +443,60 @@ export const createCursorAdapter = ({
       toolInput: input.tool_input,
       toolResponse: input.tool_response,
     });
-
-    const nextState = {
+    const readPaths = touchedFiles.length === 0 && !checkpoint.matched
+      ? extractReadPathsFromToolUse({ toolName: input.tool_name, toolInput: input.tool_input })
+      : [];
+
+    const previousReadFiles = Array.isArray(existing.readFiles) ? existing.readFiles : [];
+    const previousReadCount = Number.isFinite(existing.meaningfulReadCount) ? existing.meaningfulReadCount : 0;
+    const readFiles = readPaths.length > 0
+      ? uniq([...previousReadFiles, ...readPaths]).slice(-MAX_READ_FILES)
+      : previousReadFiles;
+    const meaningfulReadCount = readPaths.length > 0 ? previousReadCount + 1 : previousReadCount;
+
+    let nextState = {
       ...existing,
       checkpointed: checkpoint.matched ? true : existing.checkpointed,
       checkpointEvent: checkpoint.matched ? checkpoint.event : existing.checkpointEvent,
       touchedFiles: uniq([...existing.touchedFiles, ...touchedFiles]).slice(0, MAX_TOUCHED_FILES),
       meaningfulWriteCount: existing.meaningfulWriteCount + touchedFiles.length,
+      readFiles,
+      meaningfulReadCount,
+      lastReadCheckpointAt: existing.lastReadCheckpointAt ?? 0,
       updatedAt: new Date().toISOString(),
     };
 
+    if (!checkpoint.matched && touchedFiles.length > 0) {
+      const autoCheckpointed = await maybeAutoCheckpointFromState(nextState, { trigger: 'post_tool_use' });
+      if (autoCheckpointed) {
+        nextState = {
+          ...nextState,
+          checkpointed: true,
+          checkpointEvent: 'milestone',
+        };
+      }
+    } else if (
+      !checkpoint.matched
+      && touchedFiles.length === 0
+      && meaningfulReadCount >= READ_CHECKPOINT_THRESHOLD
+      && Date.now() - (nextState.lastReadCheckpointAt ?? 0) >= READ_CHECKPOINT_THROTTLE_MS
+    ) {
+      const autoAppended = await maybeAutoCheckpointFromState(nextState, {
+        trigger: 'read_progress',
+        mode: 'read_progress',
+      });
+      if (autoAppended) {
+        nextState = {
+          ...nextState,
+          readFiles: [],
+          meaningfulReadCount: 0,
+          lastReadCheckpointAt: Date.now(),
+        };
+      }
+    }
+
     await maybeSetTrackedTurnState({ hookKey, state: nextState });
-    if (checkpoint.matched || touchedFiles.length > 0) {
+    if (checkpoint.matched || touchedFiles.length > 0 || readPaths.length > 0) {
       await recordHookMetrics({
         action: 'PostToolUse',
         sessionId: existing.projectSessionId,

package/src/orchestration/policy/event-policy.js

@@ -3,6 +3,11 @@ import { smartSearch } from '../../tools/smart-search.js';
 
 export const SAFE_CONTINUITY_STATES = new Set(['aligned', 'resume']);
 
+export const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'SemanticSearch']);
+export const READ_CHECKPOINT_THRESHOLD = 8;
+export const READ_CHECKPOINT_THROTTLE_MS = 60_000;
+export const MAX_READ_FILES = 12;
+
 export const MAX_TOP_FILES = 3;
 export const MAX_PREFLIGHT_HINTS = 2;
 export const MAX_FOCUS_LENGTH = 140;
@@ -63,6 +68,29 @@ export const truncate = (value, maxLength = DEFAULT_TRUNCATE_LENGTH) => {
 
 const asArray = (value) => Array.isArray(value) ? value : [];
 
+const isMeaningfulPath = (value) => typeof value === 'string' && value.trim().length > 1;
+
+export const extractReadPathsFromToolUse = ({ toolName, toolInput } = {}) => {
+  if (!toolName || !READ_TOOLS.has(toolName) || !toolInput || typeof toolInput !== 'object') {
+    return [];
+  }
+
+  const candidates = [];
+
+  if (toolName === 'Read') {
+    candidates.push(toolInput.path, toolInput.file_path, toolInput.filePath);
+  } else if (toolName === 'Grep' || toolName === 'SemanticSearch') {
+    candidates.push(toolInput.path);
+    if (Array.isArray(toolInput.target_directories)) {
+      candidates.push(...toolInput.target_directories);
+    }
+  } else if (toolName === 'Glob') {
+    candidates.push(toolInput.target_directory);
+  }
+
+  return [...new Set(candidates.filter(isMeaningfulPath))];
+};
+
 export const uniqueCompact = (values) => [...new Set(
   asArray(values)
     .map((value) => normalizeWhitespace(value))

package/src/server.js

@@ -41,6 +41,7 @@ smart_turn (session continuity — read this before calling):
 - START: phase "start". Pass userPrompt (current goal). ensureSession true recommended when you want persistence. Use at the beginning of substantial work or when resuming after a break — not for one-line fixes or single-shot questions.
 - END: phase "end". Pass event: milestone | blocker | task_complete. Pass sessionId if you have it; include update (nextStep, completed, etc.) when checkpointing progress. Call after a meaningful slice of work (close a phase), not after every trivial edit.
 - SKIP smart_turn entirely for trivial or same-session point tasks (the tool schema also warns about this).
+- smart_resume is the cheap shortcut for the first prompt of a substantial task — equivalent to smart_turn(start, ensureSession=true, verbosity=minimal).
 
 Source of truth: devctx does not replace git history, PRs, or repo docs (e.g. MIGRATION.md). If end was not called or work was not committed, those remain authoritative.
 
@@ -508,8 +509,9 @@ export const createDevctxServer = () => {
       includeMetrics: z.boolean().optional(),
       metricsWindow: z.enum(['24h', '7d', '30d', 'all']).optional(),
       latestMetrics: z.number().int().min(1).max(20).optional(),
+      verbosity: z.enum(['minimal', 'standard', 'full']).optional().describe('Default "minimal" — returns compact recommendedPath/continuity/task. Use "standard" or "full" only when you need long instructions, candidates, or full checkpoint diagnostics.'),
     },
-    async ({ phase, sessionId, prompt, update, event, force, maxTokens, ensureSession, includeMetrics, metricsWindow, latestMetrics }) =>
+    async ({ phase, sessionId, prompt, update, event, force, maxTokens, ensureSession, includeMetrics, metricsWindow, latestMetrics, verbosity }) =>
       asTextResult(await smartTurn({
         phase,
         sessionId,
@@ -522,6 +524,29 @@ export const createDevctxServer = () => {
         includeMetrics,
         metricsWindow,
         latestMetrics,
+        verbosity,
+      })),
+  );
+
+  server.tool(
+    'smart_resume',
+    'Lightweight entry point for the first prompt of a substantial task. Equivalent to smart_turn(phase=start, ensureSession=true, verbosity=minimal): rehydrates the most recent persisted session for this project, classifies prompt continuity, and returns a compact recommendedPath. Prefer this over smart_turn(start) when you just want to recover context cheaply at the beginning of a session. SKIP for one-off lookups, single-line fixes, or trivial questions where re-reading is faster than rehydration.',
+    {
+      prompt: z.string().optional(),
+      sessionId: z.string().optional(),
+      taskId: z.string().optional(),
+      maxTokens: z.number().int().min(100).max(2000).optional(),
+      verbosity: z.enum(['minimal', 'standard', 'full']).optional(),
+    },
+    async ({ prompt, sessionId, taskId, maxTokens, verbosity }) =>
+      asTextResult(await smartTurn({
+        phase: 'start',
+        prompt,
+        sessionId,
+        taskId,
+        maxTokens,
+        ensureSession: true,
+        verbosity: verbosity ?? 'minimal',
       })),
   );
 

package/src/storage/sqlite.js

@@ -511,6 +511,16 @@ export const getMeta = (db, key) => {
   return row?.value ?? null;
 };
 
+const DEFAULT_GC_RETENTION_DAYS = 30;
+const DEFAULT_GC_THROTTLE_MS = 24 * 60 * 60 * 1000;
+const STORAGE_GC_META_KEY = 'last_storage_gc_at';
+
+const sanitizeRetentionDays = (value) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_GC_RETENTION_DAYS;
+  return Math.min(365, Math.max(1, Math.floor(parsed)));
+};
+
 const getSchemaVersion = (db) => Number(getMeta(db, 'schema_version') ?? 0);
 const VALID_STATUSES = new Set(['planning', 'in_progress', 'blocked', 'completed']);
 
@@ -1456,6 +1466,42 @@ export const upsertAgentRun = async ({ filePath = getStateDbPath(), runId, taskI
     };
   }, { filePath });
 
+export const runStorageMaintenance = async ({
+  filePath = getStateDbPath(),
+  retentionDays = DEFAULT_GC_RETENTION_DAYS,
+  throttleMs = DEFAULT_GC_THROTTLE_MS,
+  force = false,
+} = {}) => withStateDb((db) => {
+  const now = Date.now();
+  const lastRun = Number(getMeta(db, STORAGE_GC_META_KEY) ?? 0);
+  if (!force && now - lastRun < throttleMs) {
+    return { skipped: true, reason: 'throttled', lastRunAt: lastRun || null };
+  }
+
+  const days = sanitizeRetentionDays(retentionDays);
+  const cutoffIso = new Date(now - days * 24 * 60 * 60 * 1000).toISOString();
+
+  const removeOlder = (sql) => db.prepare(sql).run(cutoffIso).changes;
+
+  const removed = {
+    metricsEvents: removeOlder('DELETE FROM metrics_events WHERE created_at < ?'),
+    sessionEvents: removeOlder('DELETE FROM session_events WHERE created_at < ?'),
+    taskHandoffs: removeOlder('DELETE FROM task_handoffs WHERE created_at < ?'),
+    agentRuns: removeOlder('DELETE FROM agent_runs WHERE updated_at < ?'),
+    workflowMetrics: removeOlder('DELETE FROM workflow_metrics WHERE created_at < ?'),
+    contextAccess: removeOlder('DELETE FROM context_access WHERE timestamp < ?'),
+  };
+
+  setMeta(db, STORAGE_GC_META_KEY, String(now));
+
+  return {
+    skipped: false,
+    runAt: now,
+    retentionDays: days,
+    removed,
+  };
+}, { filePath });
+
 const listLegacySessionFiles = (sessionsDir) => {
   if (!fs.existsSync(sessionsDir)) {
     return [];

package/src/tools/smart-search.js

@@ -332,30 +332,21 @@ const buildCompactResult = (groups, totalMatches, query, root, searchMode, prove
   }
 
   const modeLabel = searchMode === 'exact' ? '' : searchMode === 'regex' ? ' [regex fallback]' : ` [term expansion: ${(provenance?.expandedTerms ?? []).join(', ')}]`;
-
   const topGroups = groups.slice(0, MAX_RESULT_FILES);
 
   if (totalMatches <= 20) {
-    const header = modeLabel ? `# Search mode:${modeLabel}\n\n` : '';
+    const header = modeLabel ? `# Search mode:${modeLabel}\n` : '';
     return header + topGroups
       .flatMap((group) => group.matches)
       .map(formatMatch)
       .join('\n');
   }
 
-  const lines = [
-    `query: ${query}${modeLabel}`,
-    `total: ${totalMatches} matches in ${totalFiles ?? groups.length} files${totalFiles && totalFiles > groups.length ? ` (showing top ${groups.length})` : ''}`,
-    '',
-    '# Top files',
-  ];
-
-  for (const group of topGroups.slice(0, 10)) {
-    lines.push(`${group.count} match(es), score ${group.score} :: ${group.file}`);
+  const lines = [];
+  if (modeLabel) {
+    lines.push(`# Search mode:${modeLabel}`);
   }
 
-  lines.push('', '# Sample matches');
-
   const topScore = topGroups[0]?.score ?? 0;
   for (const group of topGroups.slice(0, 5)) {
     const linesPerFile = group.score >= topScore * 0.7 ? 5 : 2;
@@ -366,7 +357,7 @@ const buildCompactResult = (groups, totalMatches, query, root, searchMode, prove
 
   const fileCount = totalFiles ?? groups.length;
   if (fileCount > 30) {
-    lines.push('', `# Note: ${fileCount} files matched — query may be too broad. Use Grep for exact pattern matching.`);
+    lines.push(`# Note: ${fileCount} files matched — query may be too broad. Use Grep for exact pattern matching.`);
   }
 
   return lines.join('\n');
@@ -535,7 +526,7 @@ export const smartSearch = async ({ query, cwd = '.', intent, maxFiles, _testFor
     totalMatches: dedupedMatches.length,
     matchedFiles: cappedGroups.length,
     ...(groups.length > cappedGroups.length ? { totalFiles: groups.length } : {}),
-    topFiles: cappedGroups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
+    topFiles: cappedGroups.slice(0, 5).map((group) => ({ file: group.file, count: group.count, score: group.score })),
     matches: compressedText,
   };
 

package/src/tools/smart-shell.js

@@ -185,6 +185,19 @@ const MAX_DIFF_FILES = 8;
 const MAX_LINES_PER_FILE = 60;
 const DIFF_TOTAL_LIMIT = 4000;
 
+const TAP_HEADER = /^TAP version/;
+const TAP_OK_LINE = /^\s*ok\s+\d+/;
+const TAP_NOT_OK_LINE = /^\s*not ok\s+\d+/;
+const TAP_SUBTEST_LINE = /^\s*#\s+Subtest:/;
+const TAP_YAML_FENCE = /^\s*(---|\.\.\.)\s*$/;
+const TAP_SUMMARY_LINE = /^\s*#\s+(tests|pass|fail|skipped|todo|duration_ms|cancelled|suites)\b/;
+const TAP_DETECT = /(^|\n)(TAP version |# tests \d+)/;
+const TAP_FAIL_CONTEXT = 4;
+
+const GIT_LOG_COMMIT_HEADER = /^commit [0-9a-f]{40}/;
+const GIT_LOG_DETECT = /^commit [0-9a-f]{40}\nAuthor:/m;
+const MAX_GIT_LOG_COMMITS = 40;
+
 const splitDiffByFile = (text) => {
   const files = [];
   let current = null;
@@ -201,6 +214,95 @@ const splitDiffByFile = (text) => {
   return files;
 };
 
+export const compressTapOutput = (text) => {
+  const lines = text.split('\n');
+  const summary = [];
+  const failures = [];
+  const headerLines = [];
+  let inYaml = false;
+  let yamlFailureBuffer = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (TAP_HEADER.test(line) && headerLines.length === 0) {
+      headerLines.push(line);
+      continue;
+    }
+
+    if (TAP_SUMMARY_LINE.test(line)) {
+      summary.push(line);
+      continue;
+    }
+
+    if (TAP_NOT_OK_LINE.test(line)) {
+      failures.push(line);
+      yamlFailureBuffer = failures;
+      inYaml = false;
+      continue;
+    }
+
+    if (TAP_YAML_FENCE.test(line)) {
+      if (yamlFailureBuffer) yamlFailureBuffer.push(line);
+      inYaml = !inYaml;
+      if (!inYaml) yamlFailureBuffer = null;
+      continue;
+    }
+
+    if (inYaml && yamlFailureBuffer) {
+      if (yamlFailureBuffer.length - failures.indexOf(yamlFailureBuffer[0]) <= TAP_FAIL_CONTEXT + 6) {
+        yamlFailureBuffer.push(line);
+      }
+      continue;
+    }
+
+    if (TAP_OK_LINE.test(line) || TAP_SUBTEST_LINE.test(line)) {
+      continue;
+    }
+
+    if (line.trim().startsWith('#') && failures.length > 0 && failures.length < 200) {
+      failures.push(line);
+    }
+  }
+
+  const parts = [];
+  if (headerLines.length > 0) parts.push(headerLines.join('\n'));
+  if (failures.length > 0) {
+    parts.push(`# ${failures.filter((l) => TAP_NOT_OK_LINE.test(l)).length} failure(s):`);
+    parts.push(failures.join('\n'));
+  } else {
+    parts.push('# all tests passed (ok lines collapsed)');
+  }
+  if (summary.length > 0) parts.push(summary.join('\n'));
+
+  return parts.join('\n');
+};
+
+export const compressGitLog = (text) => {
+  const lines = text.split('\n');
+  const commits = [];
+  let current = null;
+
+  for (const line of lines) {
+    if (GIT_LOG_COMMIT_HEADER.test(line)) {
+      if (current) commits.push(current);
+      current = { sha: line.split(' ')[1], subject: '' };
+    } else if (current && !current.subject && line.trim() && !/^(Author|Date|Merge|commit):/i.test(line)) {
+      current.subject = line.trim();
+    }
+  }
+  if (current) commits.push(current);
+
+  if (commits.length === 0) return text;
+
+  const shown = commits.slice(0, MAX_GIT_LOG_COMMITS);
+  const skipped = commits.length - shown.length;
+  const body = shown.map(({ sha, subject }) => `${sha.slice(0, 7)} ${subject}`).join('\n');
+  return skipped > 0
+    ? `${body}\n# ${skipped} more commit(s) not shown — narrow with --since/--until or git log -n <N>`
+    : body;
+};
+
 const compressDiff = (text) => {
   if (!DIFF_FILE_HEADER.test(text)) return text;
 
@@ -301,8 +403,20 @@ export const smartShell = async ({ command }) => {
     'entity not found',
   ]);
   const shouldPrioritizeRelevant = execution.code !== 0 || execution.timedOut;
-  const compressedSource = shouldPrioritizeRelevant && relevant ? relevant : rawText;
-  const compressedText = truncate(compressDiff(uniqueLines(compressedSource)), 5000);
+  const isTap = TAP_DETECT.test(rawText);
+  const isGitLog = !isTap && GIT_LOG_DETECT.test(rawText);
+  let stagedCompression;
+
+  if (isTap) {
+    stagedCompression = compressTapOutput(rawText);
+  } else if (isGitLog) {
+    stagedCompression = compressGitLog(rawText);
+  } else {
+    const compressedSource = shouldPrioritizeRelevant && relevant ? relevant : rawText;
+    stagedCompression = compressDiff(uniqueLines(compressedSource));
+  }
+
+  const compressedText = truncate(stagedCompression, 5000);
   const metrics = buildMetrics({
     tool: 'smart_shell',
     target: command,

package/src/tools/smart-summary.js

@@ -19,6 +19,16 @@ import {
 
 const MAX_SESSION_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_MAX_TOKENS = 500;
+const ROLLING_LIMIT = 30;
+const ROLLING_KEEP = 20;
+
+const applyRollingWindow = (items) => {
+  if (!Array.isArray(items) || items.length <= ROLLING_LIMIT) {
+    return { items: Array.isArray(items) ? items : [], archived: 0 };
+  }
+  const archived = items.length - ROLLING_KEEP;
+  return { items: items.slice(-ROLLING_KEEP), archived };
+};
 const VALID_STATUSES = new Set(['planning', 'in_progress', 'blocked', 'completed']);
 const ACTIVE_STATUSES = new Set(['planning', 'in_progress', 'blocked']);
 const DEFAULT_STATUS = 'in_progress';
@@ -735,6 +745,65 @@ const getLatestTaskHandoffRow = (db, taskId) => db.prepare(`
   LIMIT 1
 `).get(taskId);
 
+const HANDOFF_FALLBACK_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+const getMostRecentTaskHandoffRow = (db) => db.prepare(`
+  SELECT
+    handoff_id,
+    task_id,
+    session_id,
+    from_agent_id,
+    to_agent_id,
+    trigger,
+    summary_json,
+    created_at
+  FROM task_handoffs
+  ORDER BY datetime(created_at) DESC, handoff_id DESC
+  LIMIT 1
+`).get();
+
+const buildSummaryFromHandoff = (handoff, taskRecord = null) => {
+  const summary = handoff?.summary ?? {};
+  const touchedFiles = mergeUniqueStrings(summary.touchedFiles);
+  const pending = mergeUniqueStrings(summary.pending);
+
+  return pruneEmptyFields({
+    status: normalizeStatus(taskRecord?.status, 'in_progress'),
+    nextStep: isMeaningfulString(summary.nextStep) ? summary.nextStep : undefined,
+    currentFocus: isMeaningfulString(summary.currentFocus) ? summary.currentFocus : undefined,
+    goal: isMeaningfulString(taskRecord?.canonicalGoal) ? taskRecord.canonicalGoal : undefined,
+    pinnedContext: pending.slice(0, 3),
+    hotFiles: uniqueTail(touchedFiles.map(compactFilePath), 5),
+    touchedFilesCount: touchedFiles.length,
+    completedCount: 0,
+    decisionsCount: 0,
+  });
+};
+
+const buildHandoffFallback = (db) => {
+  const handoffRow = getMostRecentTaskHandoffRow(db);
+  if (!handoffRow) {
+    return null;
+  }
+
+  const ageMs = Date.now() - getTimestamp(handoffRow.created_at, 0);
+  if (!Number.isFinite(ageMs) || ageMs > HANDOFF_FALLBACK_MAX_AGE_MS) {
+    return null;
+  }
+
+  const handoff = normalizeTaskHandoff(handoffRow);
+  const taskRecord = handoff?.taskId ? normalizeTaskRow(getTaskRow(db, handoff.taskId)) : null;
+  const summary = buildSummaryFromHandoff(handoff, taskRecord);
+  const tokens = countTokens(JSON.stringify(summary));
+
+  return {
+    summary,
+    tokens,
+    handoff,
+    task: taskRecord,
+  };
+};
+
 const normalizeTaskHandoff = (row) => {
   if (!row) {
     return null;
@@ -761,6 +830,13 @@ const hydrateSession = (row) => {
   const completed = mergeUniqueStrings(snapshot.completed);
   const decisions = mergeUniqueStrings(snapshot.decisions);
   const touchedFiles = mergeUniqueStrings(snapshot.touchedFiles);
+  const archivedCounts = snapshot.archivedCounts && typeof snapshot.archivedCounts === 'object'
+    ? {
+        completed: Number(snapshot.archivedCounts.completed ?? 0) || 0,
+        decisions: Number(snapshot.archivedCounts.decisions ?? 0) || 0,
+        touchedFiles: Number(snapshot.archivedCounts.touchedFiles ?? 0) || 0,
+      }
+    : { completed: 0, decisions: 0, touchedFiles: 0 };
   const pinnedContext = mergeUniqueStrings(parseJsonText(row.pinned_context_json, []), snapshot.pinnedContext);
   const unresolvedQuestions = mergeUniqueStrings(parseJsonText(row.unresolved_questions_json, []), snapshot.unresolvedQuestions);
   const blockers = mergeUniqueStrings(parseJsonText(row.blockers_json, []), snapshot.blockers);
@@ -784,9 +860,10 @@ const hydrateSession = (row) => {
     completed,
     decisions,
     touchedFiles,
-    completedCount: Number.isInteger(row.completed_count) ? row.completed_count : completed.length,
-    decisionsCount: Number.isInteger(row.decisions_count) ? row.decisions_count : decisions.length,
-    touchedFilesCount: Number.isInteger(row.touched_files_count) ? row.touched_files_count : touchedFiles.length,
+    archivedCounts,
+    completedCount: Number.isInteger(row.completed_count) ? row.completed_count : completed.length + archivedCounts.completed,
+    decisionsCount: Number.isInteger(row.decisions_count) ? row.decisions_count : decisions.length + archivedCounts.decisions,
+    touchedFilesCount: Number.isInteger(row.touched_files_count) ? row.touched_files_count : touchedFiles.length + archivedCounts.touchedFiles,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -821,7 +898,7 @@ const buildSessionSummary = (session) => {
 const compressSummary = (data, maxTokens) => {
   const baseSummary = buildSessionSummary(data);
   let compressed = baseSummary;
-  let summary = JSON.stringify(compressed, null, 2);
+  let summary = JSON.stringify(compressed);
   let tokens = countTokens(summary);
 
   if (tokens <= maxTokens) {
@@ -830,7 +907,7 @@ const compressSummary = (data, maxTokens) => {
 
   const recomputeTokens = () => {
     compressed = pruneEmptyFields(compressed);
-    summary = JSON.stringify(compressed, null, 2);
+    summary = JSON.stringify(compressed);
     tokens = countTokens(summary);
   };
 
@@ -1005,13 +1082,23 @@ const saveSession = (db, sessionId, data, { action, eventPayload } = {}) => {
     branchName: data.branchName ?? existing?.branchName ?? null,
     worktreePath: data.worktreePath ?? existing?.worktreePath ?? null,
   });
-  const completed = mergeUniqueStrings(data.completed);
-  const decisions = mergeUniqueStrings(data.decisions);
-  const touchedFiles = mergeUniqueStrings(data.touchedFiles);
+  const completedRoll = applyRollingWindow(mergeUniqueStrings(data.completed));
+  const decisionsRoll = applyRollingWindow(mergeUniqueStrings(data.decisions));
+  const touchedRoll = applyRollingWindow(mergeUniqueStrings(data.touchedFiles));
+  const completed = completedRoll.items;
+  const decisions = decisionsRoll.items;
+  const touchedFiles = touchedRoll.items;
   const pinnedContext = mergeUniqueStrings(data.pinnedContext);
   const unresolvedQuestions = mergeUniqueStrings(data.unresolvedQuestions);
   const blockers = mergeUniqueStrings(data.blockers);
 
+  const previousArchived = existing?.archivedCounts ?? {};
+  const archivedCounts = {
+    completed: (previousArchived.completed ?? 0) + completedRoll.archived,
+    decisions: (previousArchived.decisions ?? 0) + decisionsRoll.archived,
+    touchedFiles: (previousArchived.touchedFiles ?? 0) + touchedRoll.archived,
+  };
+
   const snapshot = {
     taskId: task.taskId,
     agentId: data.agentId ?? existing?.agentId ?? null,
@@ -1028,9 +1115,10 @@ const saveSession = (db, sessionId, data, { action, eventPayload } = {}) => {
     blockers,
     nextStep: data.nextStep ?? '',
     touchedFiles,
-    completedCount: completed.length,
-    decisionsCount: decisions.length,
-    touchedFilesCount: touchedFiles.length,
+    archivedCounts,
+    completedCount: completed.length + archivedCounts.completed,
+    decisionsCount: decisions.length + archivedCounts.decisions,
+    touchedFilesCount: touchedFiles.length + archivedCounts.touchedFiles,
     schemaVersion: SQLITE_SCHEMA_VERSION,
     sessionId,
     createdAt,
@@ -1446,6 +1534,23 @@ export const smartSummary = async ({
           cleanup: allowReadSideEffects,
         });
         if (!resolution.found) {
+          const handoffFallback = buildHandoffFallback(db);
+          if (handoffFallback) {
+            return addRepoSafety({
+              action: 'get',
+              sessionId: null,
+              found: true,
+              recoveredFromHandoff: true,
+              autoResumed: false,
+              ambiguous: false,
+              summary: handoffFallback.summary,
+              tokens: handoffFallback.tokens,
+              compressionLevel: 'handoff',
+              ...(handoffFallback.task ? { task: handoffFallback.task } : {}),
+              handoff: handoffFallback.handoff,
+              message: 'Recovered from latest task handoff (no live session).',
+            }, mutationSafety.repoSafety, suppressReadSideEffects);
+          }
           return addRepoSafety({
             action: 'get',
             sessionId: null,
@@ -1463,6 +1568,21 @@ export const smartSummary = async ({
       }
 
       if (!targetSessionId) {
+        const handoffFallback = buildHandoffFallback(db);
+        if (handoffFallback) {
+          return addRepoSafety({
+            action: 'get',
+            sessionId: null,
+            found: true,
+            recoveredFromHandoff: true,
+            summary: handoffFallback.summary,
+            tokens: handoffFallback.tokens,
+            compressionLevel: 'handoff',
+            ...(handoffFallback.task ? { task: handoffFallback.task } : {}),
+            handoff: handoffFallback.handoff,
+            message: 'Recovered from latest task handoff (no live session).',
+          }, mutationSafety.repoSafety, suppressReadSideEffects);
+        }
         return addRepoSafety({
           action: 'get',
           sessionId: null,
@@ -1473,6 +1593,21 @@ export const smartSummary = async ({
 
       const session = hydrateSession(getSessionRow(db, targetSessionId));
       if (!session) {
+        const handoffFallback = buildHandoffFallback(db);
+        if (handoffFallback) {
+          return addRepoSafety({
+            action: 'get',
+            sessionId: targetSessionId,
+            found: true,
+            recoveredFromHandoff: true,
+            summary: handoffFallback.summary,
+            tokens: handoffFallback.tokens,
+            compressionLevel: 'handoff',
+            ...(handoffFallback.task ? { task: handoffFallback.task } : {}),
+            handoff: handoffFallback.handoff,
+            message: 'Session not found; recovered context from latest task handoff.',
+          }, mutationSafety.repoSafety, suppressReadSideEffects);
+        }
         return addRepoSafety({
           action: 'get',
           sessionId: targetSessionId,

package/src/tools/smart-turn.js

@@ -1,4 +1,5 @@
 import { buildIndexIncremental, persistIndex } from '../index.js';
+import { triggerBackgroundIndexBuild } from '../index-manager.js';
 import { projectRoot } from '../utils/runtime-config.js';
 import {
   autoTrackWorkflow,
@@ -7,6 +8,7 @@ import {
   isWorkflowTrackingEnabled,
 } from '../workflow-tracker.js';
 import { persistMetrics } from '../metrics.js';
+import { runStorageMaintenance } from '../storage/sqlite.js';
 import { PRODUCT_QUALITY_ANALYTICS_KIND } from '../analytics/product-quality.js';
 import { attachSafetyMetadata, buildMutationSafety } from '../utils/mutation-safety.js';
 import { smartContext } from './smart-context.js';
@@ -16,6 +18,12 @@ import { smartSummary } from './smart-summary.js';
 const isStorageUnhealthy = (health) =>
   health && health.status !== 'ok' && health.status !== null && health.status !== undefined;
 
+const VALID_VERBOSITIES = new Set(['minimal', 'standard', 'full']);
+const DEFAULT_VERBOSITY = 'minimal';
+
+const normalizeVerbosity = (value) =>
+  typeof value === 'string' && VALID_VERBOSITIES.has(value) ? value : DEFAULT_VERBOSITY;
+
 const DEFAULT_START_MAX_TOKENS = 400;
 const DEFAULT_END_MAX_TOKENS = 500;
 const DEFAULT_END_EVENT = 'milestone';
@@ -253,6 +261,7 @@ const buildStartRecommendedPath = ({
   mutationSafety,
   autoCreated,
   isolatedSession,
+  verbosity = DEFAULT_VERBOSITY,
 }) => {
   const nextTools = [];
   const steps = [];
@@ -310,15 +319,23 @@ const buildStartRecommendedPath = ({
     ));
   }
 
+  const mode = mutationSafety?.blocked
+    ? 'blocked_guided'
+    : refreshedContext
+      ? 'guided_refresh'
+      : hasMeaningfulPrompt(prompt)
+        ? 'guided_context'
+        : 'lightweight';
+  const dedupedTools = [...new Set(nextTools)];
+  const next = steps[0] ? `${steps[0].tool}: ${steps[0].instruction}` : (dedupedTools[0] ?? '');
+
+  if (verbosity === 'minimal') {
+    return { phase: 'start', mode, nextTools: dedupedTools, next };
+  }
+
   return {
     phase: 'start',
-    mode: mutationSafety?.blocked
-      ? 'blocked_guided'
-      : refreshedContext
-        ? 'guided_refresh'
-        : hasMeaningfulPrompt(prompt)
-          ? 'guided_context'
-          : 'lightweight',
+    mode,
     contextSource: refreshedContext
       ? 'refreshed_context'
       : continuity?.shouldReuseContext
@@ -328,12 +345,13 @@ const buildStartRecommendedPath = ({
     ensureSessionRecommended: Boolean(hasMeaningfulPrompt(prompt) && (ensureSession || !summaryResult?.found)),
     autoCreated,
     isolatedSession,
-    nextTools: [...new Set(nextTools)],
+    nextTools: dedupedTools,
+    next,
     instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
 
-const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow }) => {
+const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow, verbosity = DEFAULT_VERBOSITY }) => {
   const nextTools = [];
   const steps = [];
 
@@ -367,15 +385,24 @@ const buildEndRecommendedPath = ({ event, checkpoint, mutationSafety, workflow }
     ));
   }
 
+  const mode = mutationSafety?.blocked
+    ? 'blocked_guided'
+    : checkpoint?.skipped
+      ? 'continue_until_milestone'
+      : 'checkpointed';
+  const dedupedTools = [...new Set(nextTools)];
+  const next = steps[0] ? `${steps[0].tool}: ${steps[0].instruction}` : (dedupedTools[0] ?? '');
+
+  if (verbosity === 'minimal') {
+    return { phase: 'end', mode, nextTools: dedupedTools, next };
+  }
+
   return {
     phase: 'end',
-    mode: mutationSafety?.blocked
-      ? 'blocked_guided'
-      : checkpoint?.skipped
-        ? 'continue_until_milestone'
-        : 'checkpointed',
+    mode,
     checkpointEvent: event,
-    nextTools: [...new Set(nextTools)],
+    nextTools: dedupedTools,
+    next,
     instructions: steps.map((s) => `${s.tool}: ${s.instruction}`).join(' | '),
   };
 };
@@ -416,8 +443,15 @@ const startTurn = async ({
   includeMetrics = false,
   metricsWindow = '7d',
   latestMetrics = 5,
+  verbosity = DEFAULT_VERBOSITY,
 } = {}) => {
   const startTime = Date.now();
+
+  if (process.env.DEVCTX_DISABLE_BACKGROUND_TASKS !== 'true') {
+    triggerBackgroundIndexBuild({ root: projectRoot }).catch(() => {});
+    runStorageMaintenance().catch(() => {});
+  }
+
   let summaryResult = await smartSummary({
     action: 'get',
     sessionId,
@@ -526,6 +560,7 @@ const startTurn = async ({
     mutationSafety,
     autoCreated,
     isolatedSession,
+    verbosity,
   });
 
   await persistSmartTurnQualityMetrics({
@@ -555,32 +590,43 @@ const startTurn = async ({
     },
   });
 
+  const minimal = verbosity === 'minimal';
+  const compactContinuity = minimal
+    ? { state: continuity.state, shouldReuseContext: continuity.shouldReuseContext }
+    : continuity;
+  const compactTask = summaryResult.task && minimal
+    ? { taskId: summaryResult.task.taskId, status: summaryResult.task.status }
+    : summaryResult.task ?? null;
+  const includeMessage = !minimal || mutationSafety?.blocked;
+
   return attachSafetyMetadata({
     phase: 'start',
-    promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),
     sessionId: effectiveSessionId,
     found: summaryResult.found ?? false,
     autoCreated,
     isolatedSession,
+    ...(minimal ? {} : { promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW) }),
     ...(previousSessionId ? { previousSessionId } : {}),
-    continuity,
-    summary: summaryResult.summary ?? null,
+    continuity: compactContinuity,
+    ...(summaryResult.summary ? { summary: summaryResult.summary } : {}),
     ...(refreshedContext ? { refreshedContext } : {}),
     ...(workflow ? { workflow } : {}),
-    ...(summaryResult.candidates ? { candidates: summaryResult.candidates } : {}),
-    ...(summaryResult.recommendedSessionId ? { recommendedSessionId: summaryResult.recommendedSessionId } : {}),
-    ...(summaryResult.task ? { task: summaryResult.task } : {}),
+    ...(!minimal && summaryResult.candidates ? { candidates: summaryResult.candidates } : {}),
+    ...(summaryResult.ambiguous && summaryResult.recommendedSessionId ? { recommendedSessionId: summaryResult.recommendedSessionId } : {}),
+    ...(compactTask ? { task: compactTask } : {}),
     ...(summaryResult.handoff ? { handoff: summaryResult.handoff } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
     ...(isStorageUnhealthy(summaryResult.storageHealth ?? metrics?.storageHealth) ? { storageHealth: summaryResult.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
-    message: mutationSafety?.blocked
-      ? mutationSafety.message
-      : summaryResult.found
-        ? continuity.reason
-        : autoCreated
-          ? 'Created a new persisted session for this task prompt.'
-          : continuity.reason,
+    ...(includeMessage ? {
+      message: mutationSafety?.blocked
+        ? mutationSafety.message
+        : summaryResult.found
+          ? continuity.reason
+          : autoCreated
+            ? 'Created a new persisted session for this task prompt.'
+            : continuity.reason,
+    } : {}),
   }, {
     repoSafety: summaryResult.repoSafety ?? metrics?.repoSafety ?? null,
     sideEffectsSuppressed: Boolean(summaryResult.sideEffectsSuppressed ?? metrics?.sideEffectsSuppressed),
@@ -601,6 +647,7 @@ const endTurn = async ({
   includeMetrics = false,
   metricsWindow = '7d',
   latestMetrics = 5,
+  verbosity = DEFAULT_VERBOSITY,
 } = {}) => {
   const startTime = Date.now();
   const checkpoint = await smartSummary({
@@ -660,6 +707,7 @@ const endTurn = async ({
     checkpoint,
     mutationSafety,
     workflow,
+    verbosity,
   });
 
   await persistSmartTurnQualityMetrics({
@@ -683,15 +731,34 @@ const endTurn = async ({
     },
   });
 
+  const minimal = verbosity === 'minimal';
+  const compactCheckpoint = minimal
+    ? {
+        skipped: Boolean(checkpoint.skipped),
+        ...(checkpoint.blocked !== undefined ? { blocked: checkpoint.blocked } : {}),
+        ...(checkpoint.summary ? { summary: checkpoint.summary } : {}),
+        ...(checkpoint.tokens !== undefined ? { tokens: checkpoint.tokens } : {}),
+        ...(checkpoint.checkpoint ? {
+          checkpoint: {
+            event: checkpoint.checkpoint.event,
+            shouldPersist: checkpoint.checkpoint.shouldPersist,
+            score: checkpoint.checkpoint.score,
+            threshold: checkpoint.checkpoint.threshold,
+          },
+        } : {}),
+      }
+    : checkpoint;
+  const includeMessage = !minimal || mutationSafety?.blocked;
+
   return attachSafetyMetadata({
     phase: 'end',
     sessionId: checkpoint.sessionId ?? sessionId ?? null,
-    checkpoint,
+    checkpoint: compactCheckpoint,
     ...(workflow ? { workflow } : {}),
     ...(metrics ? { metrics: summarizeMetrics(metrics) } : {}),
     ...(isStorageUnhealthy(checkpoint.storageHealth ?? metrics?.storageHealth) ? { storageHealth: checkpoint.storageHealth ?? metrics?.storageHealth } : {}),
     recommendedPath,
-    message: mutationSafety?.blocked ? mutationSafety.message : checkpoint.message,
+    ...(includeMessage ? { message: mutationSafety?.blocked ? mutationSafety.message : checkpoint.message } : {}),
   }, {
     repoSafety: checkpoint.repoSafety ?? metrics?.repoSafety ?? null,
     sideEffectsSuppressed: Boolean(checkpoint.sideEffectsSuppressed ?? metrics?.sideEffectsSuppressed),
@@ -715,7 +782,10 @@ export const smartTurn = async ({
   includeMetrics = false,
   metricsWindow = '7d',
   latestMetrics = 5,
+  verbosity,
 } = {}) => {
+  const resolvedVerbosity = normalizeVerbosity(verbosity);
+
   if (phase === 'start') {
     return startTurn({
       sessionId,
@@ -726,6 +796,7 @@ export const smartTurn = async ({
       includeMetrics,
       metricsWindow,
       latestMetrics,
+      verbosity: resolvedVerbosity,
     });
   }
 
@@ -740,6 +811,7 @@ export const smartTurn = async ({
       includeMetrics,
       metricsWindow,
       latestMetrics,
+      verbosity: resolvedVerbosity,
     });
   }