context-mode 0.9.21 → 1.0.0

package/build/server.js

@@ -2,12 +2,24 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { existsSync, unlinkSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
 import { z } from "zod";
 import { PolyglotExecutor } from "./executor.js";
 import { ContentStore, cleanupStaleDBs } from "./store.js";
 import { readBashPolicies, evaluateCommandDenyOnly, extractShellCommands, readToolDenyPatterns, evaluateFilePath, } from "./security.js";
 import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime, } from "./runtime.js";
-const VERSION = "0.9.21";
+const VERSION = "1.0.0";
+// Prevent silent server death from unhandled async errors
+process.on("unhandledRejection", (err) => {
+    process.stderr.write(`[context-mode] unhandledRejection: ${err}\n`);
+});
+process.on("uncaughtException", (err) => {
+    process.stderr.write(`[context-mode] uncaughtException: ${err?.message ?? err}\n`);
+});
 const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({
@@ -20,9 +32,35 @@ const executor = new PolyglotExecutor({
 });
 // Lazy singleton — no DB overhead unless index/search is used
 let _store = null;
+/**
+ * Auto-index session events files written by SessionStart hook.
+ * Scans ~/.claude/context-mode/sessions/ for *-events.md files.
+ * CLAUDE_PROJECT_DIR is NOT available to MCP servers — only to hooks —
+ * so we glob-scan instead of computing a specific hash.
+ * Files are consumed (deleted) after indexing to prevent double-indexing.
+ * Called on every getStore() — readdirSync is sub-millisecond when no files match.
+ */
+function maybeIndexSessionEvents(store) {
+    try {
+        const sessionsDir = join(homedir(), ".claude", "context-mode", "sessions");
+        if (!existsSync(sessionsDir))
+            return;
+        const files = readdirSync(sessionsDir).filter(f => f.endsWith("-events.md"));
+        for (const file of files) {
+            const filePath = join(sessionsDir, file);
+            try {
+                store.index({ path: filePath, source: "session-events" });
+                unlinkSync(filePath);
+            }
+            catch { /* best-effort per file */ }
+        }
+    }
+    catch { /* best-effort — session continuity never blocks tools */ }
+}
 function getStore() {
     if (!_store)
         _store = new ContentStore();
+    maybeIndexSessionEvents(_store);
     return _store;
 }
 // ─────────────────────────────────────────────────────────
@@ -232,7 +270,7 @@ export function extractSnippet(content, query, maxLen = 1500, highlighted) {
 // ─────────────────────────────────────────────────────────
 // Tool: execute
 // ─────────────────────────────────────────────────────────
-server.registerTool("execute", {
+server.registerTool("ctx_execute", {
     title: "Execute Code",
     description: `MANDATORY: Use for any command where output exceeds 20 lines. Execute code in a sandboxed subprocess. Only stdout enters context — raw data stays in the subprocess.${bunNote} Available: ${langList}.\n\nPREFER THIS OVER BASH for: API calls (gh, curl, aws), test runners (npm test, pytest), git queries (git log, git diff), data processing, and ANY CLI command that may produce large output. Bash should only be used for file mutations, git writes, and navigation.`,
     inputSchema: z.object({
@@ -259,6 +297,11 @@ server.registerTool("execute", {
             .optional()
             .default(30000)
             .describe("Max execution time in ms"),
+        background: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Keep process running after timeout (for servers/daemons). Returns partial output without killing the process. IMPORTANT: Do NOT add setTimeout/self-close timers in background scripts — the process must stay alive until the timeout detaches it. For server+fetch patterns, prefer putting both server and fetch in ONE ctx_execute call instead of using background."),
         intent: z
             .string()
             .optional()
@@ -267,7 +310,7 @@ server.registerTool("execute", {
             "Use search(queries: [...]) to retrieve specific sections. Example: 'failing tests', 'HTTP 500 errors'." +
             "\n\nTIP: Use specific technical terms, not just concepts. Check 'Searchable terms' in the response for available vocabulary."),
     }),
-}, async ({ language, code, timeout, intent }) => {
+}, async ({ language, code, timeout, background, intent }) => {
     // Security: deny-only firewall
     if (language === "shell") {
         const denied = checkDenyPolicy(code, "execute");
@@ -280,22 +323,61 @@ server.registerTool("execute", {
             return denied;
     }
     try {
-        // For JS/TS: wrap in async IIFE with fetch interceptor to track network bytes
+        // For JS/TS: wrap in async IIFE with fetch + http/https interceptors to track network bytes
         let instrumentedCode = code;
         if (language === "javascript" || language === "typescript") {
+            // Wrap user code in a closure that shadows CJS require with http/https interceptor.
+            // globalThis.require does NOT work because CJS require is module-scoped, not global.
+            // The closure approach (function(__cm_req){ var require=...; })(require) correctly
+            // shadows the CJS require for all code inside, including __cm_main().
             instrumentedCode = `
-let __cm_net=0;const __cm_f=globalThis.fetch;
+let __cm_net=0;
+// Report network bytes on process exit — works with both promise and callback patterns.
+// process.on('exit') fires after all I/O completes, unlike .finally() which fires
+// when __cm_main() resolves (immediately for callback-based http.get without await).
+process.on('exit',()=>{if(__cm_net>0)try{process.stderr.write('__CM_NET__:'+__cm_net+'\\n')}catch{}});
+;(function(__cm_req){
+// Intercept globalThis.fetch
+const __cm_f=globalThis.fetch;
 globalThis.fetch=async(...a)=>{const r=await __cm_f(...a);
 try{const cl=r.clone();const b=await cl.arrayBuffer();__cm_net+=b.byteLength}catch{}
 return r};
+// Shadow CJS require with http/https network tracking.
+const __cm_hc=new Map();
+const __cm_hm=new Set(['http','https','node:http','node:https']);
+function __cm_wf(m,origFn){return function(...a){
+  const li=a.length-1;
+  if(li>=0&&typeof a[li]==='function'){const oc=a[li];a[li]=function(res){
+    res.on('data',function(c){__cm_net+=c.length});oc(res);};}
+  const req=origFn.apply(m,a);
+  const oOn=req.on.bind(req);
+  req.on=function(ev,cb,...r){
+    if(ev==='response'){return oOn(ev,function(res){
+      res.on('data',function(c){__cm_net+=c.length});cb(res);
+    },...r);}
+    return oOn(ev,cb,...r);
+  };
+  return req;
+}}
+var require=__cm_req?function(id){
+  const m=__cm_req(id);
+  if(!__cm_hm.has(id))return m;
+  const k=id.replace('node:','');
+  if(__cm_hc.has(k))return __cm_hc.get(k);
+  const w=Object.create(m);
+  if(typeof m.get==='function')w.get=__cm_wf(m,m.get);
+  if(typeof m.request==='function')w.request=__cm_wf(m,m.request);
+  __cm_hc.set(k,w);return w;
+}:__cm_req;
+if(__cm_req){if(__cm_req.resolve)require.resolve=__cm_req.resolve;
+if(__cm_req.cache)require.cache=__cm_req.cache;}
 async function __cm_main(){
 ${code}
 }
-__cm_main().catch(e=>{console.error(e);process.exitCode=1}).finally(()=>{
-if(__cm_net>0)process.stderr.write('__CM_NET__:'+__cm_net+'\\n');
-});`;
+__cm_main().catch(e=>{console.error(e);process.exitCode=1});${background ? '\nsetInterval(()=>{},2147483647);' : ''}
+})(typeof require!=='undefined'?require:null);`;
         }
-        const result = await executor.execute({ language, code: instrumentedCode, timeout });
+        const result = await executor.execute({ language, code: instrumentedCode, timeout, background });
         // Parse sandbox network metrics from stderr
         const netMatch = result.stderr?.match(/__CM_NET__:(\d+)/);
         if (netMatch) {
@@ -304,11 +386,34 @@ if(__cm_net>0)process.stderr.write('__CM_NET__:'+__cm_net+'\\n');
             result.stderr = result.stderr.replace(/\n?__CM_NET__:\d+\n?/g, "");
         }
         if (result.timedOut) {
-            return trackResponse("execute", {
+            const partialOutput = result.stdout?.trim();
+            if (result.backgrounded && partialOutput) {
+                // Background mode: process is still running, return partial output as success
+                return trackResponse("ctx_execute", {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${partialOutput}\n\n_(process backgrounded after ${timeout}ms — still running)_`,
+                        },
+                    ],
+                });
+            }
+            if (partialOutput) {
+                // Timeout with partial output — return as success with note
+                return trackResponse("ctx_execute", {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${partialOutput}\n\n_(timed out after ${timeout}ms — partial output shown above)_`,
+                        },
+                    ],
+                });
+            }
+            return trackResponse("ctx_execute", {
                 content: [
                     {
                         type: "text",
-                        text: `Execution timed out after ${timeout}ms\n\nPartial stdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`,
+                        text: `Execution timed out after ${timeout}ms\n\nstderr:\n${result.stderr}`,
                     },
                 ],
                 isError: true,
@@ -318,14 +423,14 @@ if(__cm_net>0)process.stderr.write('__CM_NET__:'+__cm_net+'\\n');
             const output = `Exit code: ${result.exitCode}\n\nstdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`;
             if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
                 trackIndexed(Buffer.byteLength(output));
-                return trackResponse("execute", {
+                return trackResponse("ctx_execute", {
                     content: [
                         { type: "text", text: intentSearch(output, intent, `execute:${language}:error`) },
                     ],
                     isError: true,
                 });
             }
-            return trackResponse("execute", {
+            return trackResponse("ctx_execute", {
                 content: [
                     { type: "text", text: output },
                 ],
@@ -336,13 +441,13 @@ if(__cm_net>0)process.stderr.write('__CM_NET__:'+__cm_net+'\\n');
         // Intent-driven search: if intent provided and output is large enough
         if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
             trackIndexed(Buffer.byteLength(stdout));
-            return trackResponse("execute", {
+            return trackResponse("ctx_execute", {
                 content: [
                     { type: "text", text: intentSearch(stdout, intent, `execute:${language}`) },
                 ],
             });
         }
-        return trackResponse("execute", {
+        return trackResponse("ctx_execute", {
             content: [
                 { type: "text", text: stdout },
             ],
@@ -350,7 +455,7 @@ if(__cm_net>0)process.stderr.write('__CM_NET__:'+__cm_net+'\\n');
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("execute", {
+        return trackResponse("ctx_execute", {
             content: [
                 { type: "text", text: `Runtime error: ${message}` },
             ],
@@ -422,7 +527,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
 // ─────────────────────────────────────────────────────────
 // Tool: execute_file
 // ─────────────────────────────────────────────────────────
-server.registerTool("execute_file", {
+server.registerTool("ctx_execute_file", {
     title: "Execute File Processing",
     description: "Read a file and process it without loading contents into context. The file is read into a FILE_CONTENT variable inside the sandbox. Only your printed summary enters context.\n\nPREFER THIS OVER Read/cat for: log files, data files (CSV, JSON, XML), large source files for analysis, and any file where you need to extract specific information rather than read the entire content.",
     inputSchema: z.object({
@@ -482,7 +587,7 @@ server.registerTool("execute_file", {
             timeout,
         });
         if (result.timedOut) {
-            return trackResponse("execute_file", {
+            return trackResponse("ctx_execute_file", {
                 content: [
                     {
                         type: "text",
@@ -496,14 +601,14 @@ server.registerTool("execute_file", {
             const output = `Error processing ${path} (exit ${result.exitCode}):\n${result.stderr || result.stdout}`;
             if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
                 trackIndexed(Buffer.byteLength(output));
-                return trackResponse("execute_file", {
+                return trackResponse("ctx_execute_file", {
                     content: [
                         { type: "text", text: intentSearch(output, intent, `file:${path}:error`) },
                     ],
                     isError: true,
                 });
             }
-            return trackResponse("execute_file", {
+            return trackResponse("ctx_execute_file", {
                 content: [
                     { type: "text", text: output },
                 ],
@@ -513,13 +618,13 @@ server.registerTool("execute_file", {
         const stdout = result.stdout || "(no output)";
         if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
             trackIndexed(Buffer.byteLength(stdout));
-            return trackResponse("execute_file", {
+            return trackResponse("ctx_execute_file", {
                 content: [
                     { type: "text", text: intentSearch(stdout, intent, `file:${path}`) },
                 ],
             });
         }
-        return trackResponse("execute_file", {
+        return trackResponse("ctx_execute_file", {
             content: [
                 { type: "text", text: stdout },
             ],
@@ -527,7 +632,7 @@ server.registerTool("execute_file", {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("execute_file", {
+        return trackResponse("ctx_execute_file", {
             content: [
                 { type: "text", text: `Runtime error: ${message}` },
             ],
@@ -538,7 +643,7 @@ server.registerTool("execute_file", {
 // ─────────────────────────────────────────────────────────
 // Tool: index
 // ─────────────────────────────────────────────────────────
-server.registerTool("index", {
+server.registerTool("ctx_index", {
     title: "Index Content",
     description: "Index documentation or knowledge content into a searchable BM25 knowledge base. " +
         "Chunks markdown by headings (keeping code blocks intact) and stores in ephemeral FTS5 database. " +
@@ -568,7 +673,7 @@ server.registerTool("index", {
     }),
 }, async ({ content, path, source }) => {
     if (!content && !path) {
-        return trackResponse("index", {
+        return trackResponse("ctx_index", {
             content: [
                 {
                     type: "text",
@@ -591,7 +696,7 @@ server.registerTool("index", {
         }
         const store = getStore();
         const result = store.index({ content, path, source });
-        return trackResponse("index", {
+        return trackResponse("ctx_index", {
             content: [
                 {
                     type: "text",
@@ -602,7 +707,7 @@ server.registerTool("index", {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("index", {
+        return trackResponse("ctx_index", {
             content: [
                 { type: "text", text: `Index error: ${message}` },
             ],
@@ -619,7 +724,7 @@ let searchWindowStart = Date.now();
 const SEARCH_WINDOW_MS = 60_000;
 const SEARCH_MAX_RESULTS_AFTER = 3; // after 3 calls: 1 result per query
 const SEARCH_BLOCK_AFTER = 8; // after 8 calls: refuse, demand batching
-server.registerTool("search", {
+server.registerTool("ctx_search", {
     title: "Search Indexed Content",
     description: "Search indexed content. Pass ALL search questions as queries array in ONE call.\n\n" +
         "TIPS: 2-4 specific terms per query. Use 'source' to scope results.",
@@ -651,7 +756,7 @@ server.registerTool("search", {
             queryList.push(raw.query);
         }
         if (queryList.length === 0) {
-            return trackResponse("search", {
+            return trackResponse("ctx_search", {
                 content: [{ type: "text", text: "Error: provide query or queries." }],
                 isError: true,
             });
@@ -666,7 +771,7 @@ server.registerTool("search", {
         searchCallCount++;
         // After SEARCH_BLOCK_AFTER calls: refuse
         if (searchCallCount > SEARCH_BLOCK_AFTER) {
-            return trackResponse("search", {
+            return trackResponse("ctx_search", {
                 content: [{
                         type: "text",
                         text: `BLOCKED: ${searchCallCount} search calls in ${Math.round((now - searchWindowStart) / 1000)}s. ` +
@@ -716,17 +821,17 @@ server.registerTool("search", {
             const sourceList = sources.length > 0
                 ? `\nIndexed sources: ${sources.map((s) => `"${s.label}" (${s.chunkCount} sections)`).join(", ")}`
                 : "";
-            return trackResponse("search", {
+            return trackResponse("ctx_search", {
                 content: [{ type: "text", text: `No results found.${sourceList}` }],
             });
         }
-        return trackResponse("search", {
+        return trackResponse("ctx_search", {
             content: [{ type: "text", text: output }],
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("search", {
+        return trackResponse("ctx_search", {
             content: [{ type: "text", text: `Search error: ${message}` }],
             isError: true,
         });
@@ -757,13 +862,23 @@ function resolveGfmPluginPath() {
 // Subprocess code that fetches a URL, detects Content-Type, and outputs a
 // __CM_CT__:<type> marker on the first line so the handler can route to the
 // appropriate indexing strategy.  HTML is converted to markdown via Turndown.
-function buildFetchCode(url) {
+function buildFetchCode(url, outputPath) {
     const turndownPath = JSON.stringify(resolveTurndownPath());
     const gfmPath = JSON.stringify(resolveGfmPluginPath());
+    const escapedOutputPath = JSON.stringify(outputPath);
     return `
 const TurndownService = require(${turndownPath});
 const { gfm } = require(${gfmPath});
+const fs = require('fs');
 const url = ${JSON.stringify(url)};
+const outputPath = ${escapedOutputPath};
+
+function emit(ct, content) {
+  // Write content to file to bypass executor stdout truncation (100KB limit).
+  // Only the content-type marker goes to stdout.
+  fs.writeFileSync(outputPath, content);
+  console.log('__CM_CT__:' + ct);
+}
 
 async function main() {
   const resp = await fetch(url);
@@ -775,12 +890,9 @@ async function main() {
     const text = await resp.text();
     try {
       const pretty = JSON.stringify(JSON.parse(text), null, 2);
-      console.log('__CM_CT__:json');
-      console.log(pretty);
+      emit('json', pretty);
     } catch {
-      // Unparseable "JSON" — fall back to plain text
-      console.log('__CM_CT__:text');
-      console.log(text);
+      emit('text', text);
     }
     return;
   }
@@ -791,20 +903,18 @@ async function main() {
     const td = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
     td.use(gfm);
     td.remove(['script', 'style', 'nav', 'header', 'footer', 'noscript']);
-    console.log('__CM_CT__:html');
-    console.log(td.turndown(html));
+    emit('html', td.turndown(html));
     return;
   }
 
   // --- Everything else: plain text, CSV, XML, etc. ---
   const text = await resp.text();
-  console.log('__CM_CT__:text');
-  console.log(text);
+  emit('text', text);
 }
 main();
 `;
 }
-server.registerTool("fetch_and_index", {
+server.registerTool("ctx_fetch_and_index", {
     title: "Fetch & Index URL",
     description: "Fetches URL content, converts HTML to markdown, indexes into searchable knowledge base, " +
         "and returns a ~3KB preview. Full content stays in sandbox — use search() for deeper lookups.\n\n" +
@@ -818,16 +928,18 @@ server.registerTool("fetch_and_index", {
             .describe("Label for the indexed content (e.g., 'React useEffect docs', 'Supabase Auth API')"),
     }),
 }, async ({ url, source }) => {
+    // Generate a unique temp file path for the subprocess to write fetched content.
+    // This bypasses the executor's 100KB stdout truncation — content goes file→handler directly.
+    const outputPath = join(tmpdir(), `ctx-fetch-${Date.now()}-${Math.random().toString(36).slice(2)}.dat`);
     try {
-        // Execute fetch inside subprocess — raw HTML never enters context
-        const fetchCode = buildFetchCode(url);
+        const fetchCode = buildFetchCode(url, outputPath);
         const result = await executor.execute({
             language: "javascript",
             code: fetchCode,
             timeout: 30_000,
         });
         if (result.exitCode !== 0) {
-            return trackResponse("fetch_and_index", {
+            return trackResponse("ctx_fetch_and_index", {
                 content: [
                     {
                         type: "text",
@@ -837,15 +949,27 @@ server.registerTool("fetch_and_index", {
                 isError: true,
             });
         }
-        // Parse content-type marker from subprocess output
+        // Parse content-type marker from stdout (content is in the temp file)
         const store = getStore();
-        const rawOutput = (result.stdout || "").trim();
-        const firstNewline = rawOutput.indexOf("\n");
-        const header = firstNewline >= 0 ? rawOutput.slice(0, firstNewline) : "";
-        const content = firstNewline >= 0 ? rawOutput.slice(firstNewline + 1) : rawOutput;
-        const markdown = content.trim();
+        const header = (result.stdout || "").trim();
+        // Read full content from temp file (bypasses smartTruncate)
+        let markdown;
+        try {
+            markdown = readFileSync(outputPath, "utf-8").trim();
+        }
+        catch {
+            return trackResponse("ctx_fetch_and_index", {
+                content: [
+                    {
+                        type: "text",
+                        text: `Fetched ${url} but could not read subprocess output`,
+                    },
+                ],
+                isError: true,
+            });
+        }
         if (markdown.length === 0) {
-            return trackResponse("fetch_and_index", {
+            return trackResponse("ctx_fetch_and_index", {
                 content: [
                     {
                         type: "text",
@@ -882,24 +1006,31 @@ server.registerTool("fetch_and_index", {
             "",
             preview,
         ].join("\n");
-        return trackResponse("fetch_and_index", {
+        return trackResponse("ctx_fetch_and_index", {
             content: [{ type: "text", text }],
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("fetch_and_index", {
+        return trackResponse("ctx_fetch_and_index", {
             content: [
                 { type: "text", text: `Fetch error: ${message}` },
             ],
             isError: true,
         });
     }
+    finally {
+        // Clean up temp file
+        try {
+            rmSync(outputPath);
+        }
+        catch { /* already gone */ }
+    }
 });
 // ─────────────────────────────────────────────────────────
 // Tool: batch_execute
 // ─────────────────────────────────────────────────────────
-server.registerTool("batch_execute", {
+server.registerTool("ctx_batch_execute", {
     title: "Batch Execute & Search",
     description: "Execute multiple commands in ONE call, auto-index all output, and search with multiple queries. " +
         "Returns search results directly — no follow-up calls needed.\n\n" +
@@ -938,32 +1069,52 @@ server.registerTool("batch_execute", {
             return denied;
     }
     try {
-        // Build batch script with markdown section headers for proper chunking
-        const script = commands
-            .map((c) => {
-            const safeLabel = c.label.replace(/'/g, "'\\''");
-            return `echo '# ${safeLabel}'\necho ''\n${c.command} 2>&1\necho ''`;
-        })
-            .join("\n");
-        const result = await executor.execute({
-            language: "shell",
-            code: script,
-            timeout,
-        });
-        if (result.timedOut) {
-            return trackResponse("batch_execute", {
+        // Execute each command individually so every command gets its own
+        // smartTruncate budget (~100KB). Previously, all commands were
+        // concatenated into a single script where smartTruncate (60% head +
+        // 40% tail) could silently drop middle commands. (Issue #61)
+        const perCommandOutputs = [];
+        const startTime = Date.now();
+        let timedOut = false;
+        for (const cmd of commands) {
+            const elapsed = Date.now() - startTime;
+            const remaining = timeout - elapsed;
+            if (remaining <= 0) {
+                perCommandOutputs.push(`# ${cmd.label}\n\n(skipped — batch timeout exceeded)\n`);
+                timedOut = true;
+                continue;
+            }
+            const result = await executor.execute({
+                language: "shell",
+                code: `${cmd.command} 2>&1`,
+                timeout: remaining,
+            });
+            const output = result.stdout || "(no output)";
+            perCommandOutputs.push(`# ${cmd.label}\n\n${output}\n`);
+            if (result.timedOut) {
+                timedOut = true;
+                // Mark remaining commands as skipped
+                const idx = commands.indexOf(cmd);
+                for (let i = idx + 1; i < commands.length; i++) {
+                    perCommandOutputs.push(`# ${commands[i].label}\n\n(skipped — batch timeout exceeded)\n`);
+                }
+                break;
+            }
+        }
+        const stdout = perCommandOutputs.join("\n");
+        const totalBytes = Buffer.byteLength(stdout);
+        const totalLines = stdout.split("\n").length;
+        if (timedOut && perCommandOutputs.length === 0) {
+            return trackResponse("ctx_batch_execute", {
                 content: [
                     {
                         type: "text",
-                        text: `Batch timed out after ${timeout}ms. Partial output:\n${result.stdout?.slice(0, 2000) || "(none)"}`,
+                        text: `Batch timed out after ${timeout}ms. No output captured.`,
                     },
                 ],
                 isError: true,
             });
         }
-        const stdout = result.stdout || "(no output)";
-        const totalBytes = Buffer.byteLength(stdout);
-        const totalLines = stdout.split("\n").length;
         // Track indexed bytes (raw data that stays in sandbox)
         trackIndexed(totalBytes);
         // Index into knowledge base — markdown heading chunking splits by # labels
@@ -994,16 +1145,23 @@ server.registerTool("batch_execute", {
             }
             // Tier 1: scoped search with fallback (porter → trigram → fuzzy)
             let results = store.searchWithFallback(query, 3, source);
-            // Tier 2: global fallback (no source filter)
+            let crossSource = false;
+            // Tier 2: global fallback (no source filter) — warn about cross-source (Issue #61)
             if (results.length === 0) {
                 results = store.searchWithFallback(query, 3);
+                crossSource = results.length > 0;
             }
             queryResults.push(`## ${query}`);
+            if (crossSource) {
+                queryResults.push(`> **Note:** No results in current batch output. Showing results from previously indexed content.`);
+            }
             queryResults.push("");
             if (results.length > 0) {
                 for (const r of results) {
-                    const snippet = extractSnippet(r.content, query, 1500, r.highlighted);
-                    queryResults.push(`### ${r.title}`);
+                    // Use larger snippet (3KB) for batch_execute to reduce tiny-fragment issue (Issue #61)
+                    const snippet = extractSnippet(r.content, query, 3000, r.highlighted);
+                    const sourceTag = crossSource ? ` _(source: ${r.source})_` : "";
+                    queryResults.push(`### ${r.title}${sourceTag}`);
                     queryResults.push(snippet);
                     queryResults.push("");
                     outputSize += snippet.length + r.title.length;
@@ -1029,13 +1187,13 @@ server.registerTool("batch_execute", {
                 ? `\nSearchable terms for follow-up: ${distinctiveTerms.join(", ")}`
                 : "",
         ].join("\n");
-        return trackResponse("batch_execute", {
+        return trackResponse("ctx_batch_execute", {
             content: [{ type: "text", text: output }],
         });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return trackResponse("batch_execute", {
+        return trackResponse("ctx_batch_execute", {
             content: [
                 {
                     type: "text",
@@ -1049,7 +1207,7 @@ server.registerTool("batch_execute", {
 // ─────────────────────────────────────────────────────────
 // Tool: stats
 // ─────────────────────────────────────────────────────────
-server.registerTool("stats", {
+server.registerTool("ctx_stats", {
     title: "Session Statistics",
     description: "Returns context consumption statistics for the current session. " +
         "Shows total bytes returned to context, breakdown by tool, call counts, " +
@@ -1072,48 +1230,208 @@ server.registerTool("stats", {
             return `${(b / 1024 / 1024).toFixed(1)}MB`;
         return `${(b / 1024).toFixed(1)}KB`;
     };
-    // ── Summary table ──
+    // ── Header ──
     const lines = [
-        `## context-mode session stats`,
-        "",
-        `| Metric | Value |`,
-        `|--------|------:|`,
-        `| Session | ${uptimeMin} min |`,
-        `| Tool calls | ${totalCalls} |`,
-        `| Total data processed | **${kb(totalProcessed)}** |`,
-        `| Kept in sandbox | **${kb(keptOut)}** |`,
-        `| Entered context | ${kb(totalBytesReturned)} |`,
-        `| Tokens consumed | ~${Math.round(totalBytesReturned / 4).toLocaleString()} |`,
-        `| **Context savings** | **${savingsRatio.toFixed(1)}x (${reductionPct}% reduction)** |`,
+        `## context-mode — Session Report (${uptimeMin} min)`,
     ];
-    // ── Per-tool table ──
-    const toolNames = new Set([
-        ...Object.keys(sessionStats.calls),
-        ...Object.keys(sessionStats.bytesReturned),
-    ]);
-    if (toolNames.size > 0) {
-        lines.push("", `| Tool | Calls | Context | Tokens |`, `|------|------:|--------:|-------:|`);
-        for (const tool of Array.from(toolNames).sort()) {
-            const calls = sessionStats.calls[tool] || 0;
-            const bytes = sessionStats.bytesReturned[tool] || 0;
-            const tokens = Math.round(bytes / 4);
-            lines.push(`| ${tool} | ${calls} | ${kb(bytes)} | ~${tokens.toLocaleString()} |`);
-        }
-        lines.push(`| **Total** | **${totalCalls}** | **${kb(totalBytesReturned)}** | **~${Math.round(totalBytesReturned / 4).toLocaleString()}** |`);
-    }
-    // ── DevRel summary ──
-    const tokensSaved = Math.round(keptOut / 4);
+    // ── Feature 1: Context Window Protection ──
+    lines.push("", `### Context Window Protection`, "");
     if (totalCalls === 0) {
-        lines.push("", "> No context-mode calls this session. Use `batch_execute` to run commands, `fetch_and_index` for URLs, or `execute` to process data in sandbox.");
-    }
-    else if (keptOut === 0) {
-        lines.push("", `> context-mode handled **${totalCalls}** tool calls. All outputs were compact enough to enter context directly. Process larger data or batch multiple commands for bigger savings.`);
+        lines.push(`No context-mode tool calls yet. Use \`batch_execute\`, \`execute\`, or \`fetch_and_index\` to keep raw output out of your context window.`);
     }
     else {
-        lines.push("", `> Without context-mode, **${kb(totalProcessed)}** of raw tool output would flood your context window. Instead, **${kb(keptOut)}** (${reductionPct}%) stayed in sandbox — saving **~${tokensSaved.toLocaleString()} tokens** of context space.`);
+        lines.push(`| Metric | Value |`, `|--------|------:|`, `| Total data processed | **${kb(totalProcessed)}** |`, `| Kept in sandbox (never entered context) | **${kb(keptOut)}** |`, `| Entered context | ${kb(totalBytesReturned)} |`, `| Estimated tokens saved | ~${Math.round(keptOut / 4).toLocaleString()} |`, `| **Context savings** | **${savingsRatio.toFixed(1)}x (${reductionPct}% reduction)** |`);
+        // Per-tool breakdown
+        const toolNames = new Set([
+            ...Object.keys(sessionStats.calls),
+            ...Object.keys(sessionStats.bytesReturned),
+        ]);
+        if (toolNames.size > 0) {
+            lines.push("", `| Tool | Calls | Context | Tokens |`, `|------|------:|--------:|-------:|`);
+            for (const tool of Array.from(toolNames).sort()) {
+                const calls = sessionStats.calls[tool] || 0;
+                const bytes = sessionStats.bytesReturned[tool] || 0;
+                const tokens = Math.round(bytes / 4);
+                lines.push(`| ${tool} | ${calls} | ${kb(bytes)} | ~${tokens.toLocaleString()} |`);
+            }
+            lines.push(`| **Total** | **${totalCalls}** | **${kb(totalBytesReturned)}** | **~${Math.round(totalBytesReturned / 4).toLocaleString()}** |`);
+        }
+        if (keptOut > 0) {
+            lines.push("", `Without context-mode, **${kb(totalProcessed)}** of raw output would flood your context window. Instead, **${reductionPct}%** stayed in sandbox.`);
+        }
+    }
+    // ── Session Continuity ──
+    try {
+        const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+        const dbHash = createHash("sha256").update(projectDir).digest("hex").slice(0, 16);
+        const sessionDbPath = join(homedir(), ".claude", "context-mode", "sessions", `${dbHash}.db`);
+        if (existsSync(sessionDbPath)) {
+            const require = createRequire(import.meta.url);
+            const Database = require("better-sqlite3");
+            const sdb = new Database(sessionDbPath, { readonly: true });
+            const eventTotal = sdb.prepare("SELECT COUNT(*) as cnt FROM session_events").get();
+            const byCategory = sdb.prepare("SELECT category, COUNT(*) as cnt FROM session_events GROUP BY category ORDER BY cnt DESC").all();
+            const meta = sdb.prepare("SELECT compact_count FROM session_meta ORDER BY started_at DESC LIMIT 1").get();
+            const resume = sdb.prepare("SELECT event_count, consumed FROM session_resume ORDER BY created_at DESC LIMIT 1").get();
+            if (eventTotal.cnt > 0) {
+                const compacts = meta?.compact_count ?? 0;
+                // Query actual data per category for preview
+                const previewRows = sdb.prepare(`SELECT category, type, data FROM session_events ORDER BY id DESC`).all();
+                // Build previews: unique values per category
+                const previews = new Map();
+                for (const row of previewRows) {
+                    if (!previews.has(row.category))
+                        previews.set(row.category, new Set());
+                    const set = previews.get(row.category);
+                    if (set.size < 5) {
+                        let display = row.data;
+                        if (row.category === "file") {
+                            display = row.data.split("/").pop() || row.data;
+                        }
+                        else if (row.category === "prompt") {
+                            display = display.length > 50 ? display.slice(0, 47) + "..." : display;
+                        }
+                        if (display.length > 40)
+                            display = display.slice(0, 37) + "...";
+                        set.add(display);
+                    }
+                }
+                const categoryLabels = {
+                    file: "Files tracked",
+                    rule: "Project rules (CLAUDE.md)",
+                    prompt: "Your requests saved",
+                    mcp: "Plugin tools used",
+                    git: "Git operations",
+                    env: "Environment setup",
+                    error: "Errors caught",
+                    task: "Tasks in progress",
+                    decision: "Your decisions",
+                    cwd: "Working directory",
+                    skill: "Skills used",
+                    subagent: "Delegated work",
+                    intent: "Session mode",
+                    data: "Data references",
+                    role: "Behavioral directives",
+                };
+                const categoryHints = {
+                    file: "Restored after compact — no need to re-read",
+                    rule: "Your project instructions survive context resets",
+                    prompt: "Continues exactly where you left off",
+                    decision: "Applied automatically — won't ask again",
+                    task: "Picks up from where it stopped",
+                    error: "Tracked and monitored across compacts",
+                    git: "Branch, commit, and repo state preserved",
+                    env: "Runtime config carried forward",
+                    mcp: "Tool usage patterns remembered",
+                    subagent: "Delegation history preserved",
+                    skill: "Skill invocations tracked",
+                };
+                lines.push("", "### Session Continuity", "", "| What's preserved | Count | I remember... | Why it matters |", "|------------------|------:|---------------|----------------|");
+                for (const row of byCategory) {
+                    const label = categoryLabels[row.category] || row.category;
+                    const preview = previews.get(row.category);
+                    const previewStr = preview ? Array.from(preview).join(", ") : "";
+                    const hint = categoryHints[row.category] || "Survives context resets";
+                    lines.push(`| ${label} | ${row.cnt} | ${previewStr} | ${hint} |`);
+                }
+                lines.push(`| **Total** | **${eventTotal.cnt}** | | **Zero knowledge lost on compact** |`);
+                lines.push("");
+                if (compacts > 0) {
+                    lines.push(`Context has been compacted **${compacts} time(s)** — session knowledge was preserved each time.`);
+                }
+                else {
+                    lines.push(`When your context compacts, all of this will restore Claude's awareness — no starting from scratch.`);
+                }
+                if (resume && !resume.consumed) {
+                    lines.push(`Resume snapshot ready (${resume.event_count} events) for the next compaction.`);
+                }
+                lines.push("");
+                lines.push(`> **Note:** Previous session data is loaded when you start a new session. Without \`--continue\`, old session history is cleaned up to keep the database lean.`);
+            }
+            sdb.close();
+        }
     }
+    catch {
+        // Session DB not available or incompatible — skip silently
+    }
+    // No separate DevRel summary — integrated into feature sections above
+    // Formatting directive — ensures all LLMs display the report verbatim
+    lines.push("", "---", "_Display this entire report as-is in your response. Do NOT summarize, collapse, or paraphrase any section._");
     const text = lines.join("\n");
-    return trackResponse("stats", {
+    return trackResponse("ctx_stats", {
+        content: [{ type: "text", text }],
+    });
+});
+// ── ctx-doctor: diagnostics meta-tool ──────────────────────────────────────
+server.registerTool("ctx_doctor", {
+    title: "Run Diagnostics",
+    description: "Diagnose context-mode installation. Returns a shell command to execute. " +
+        "You MUST run the returned command using your shell tool (Bash, shell_execute, " +
+        "run_in_terminal, etc.) and display the output as a markdown checklist.",
+    inputSchema: z.object({}),
+}, async () => {
+    const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const cmd = `node "${pluginRoot}/build/cli.js" doctor`;
+    const text = [
+        "## ctx-doctor",
+        "",
+        "Run this command using your shell execution tool:",
+        "",
+        "```",
+        cmd,
+        "```",
+        "",
+        "After the command completes, display results as a markdown checklist:",
+        "- `[x]` for PASS, `[ ]` for FAIL, `[-]` for WARN",
+        "- Example format:",
+        "  ```",
+        "  ## context-mode doctor",
+        "  - [x] Runtimes: 6/10 (javascript, typescript, python, shell, ruby, perl)",
+        "  - [x] Performance: FAST (Bun)",
+        "  - [x] Server test: PASS",
+        "  - [x] Hooks: PASS",
+        "  - [x] FTS5: PASS",
+        "  - [x] npm: v0.9.23",
+        "  ```",
+    ].join("\n");
+    return trackResponse("ctx_doctor", {
+        content: [{ type: "text", text }],
+    });
+});
+// ── ctx-upgrade: upgrade meta-tool ─────────────────────────────────────────
+server.registerTool("ctx_upgrade", {
+    title: "Upgrade Plugin",
+    description: "Upgrade context-mode to the latest version. Returns a shell command to execute. " +
+        "You MUST run the returned command using your shell tool (Bash, shell_execute, " +
+        "run_in_terminal, etc.) and display the output as a checklist. " +
+        "Tell the user to restart their session after upgrade.",
+    inputSchema: z.object({}),
+}, async () => {
+    const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const cmd = `node "${pluginRoot}/build/cli.js" upgrade`;
+    const text = [
+        "## ctx-upgrade",
+        "",
+        "Run this command using your shell execution tool:",
+        "",
+        "```",
+        cmd,
+        "```",
+        "",
+        "After the command completes, display results as a markdown checklist:",
+        "- `[x]` for success, `[ ]` for failure",
+        "- Example format:",
+        "  ```",
+        "  ## context-mode upgrade",
+        "  - [x] Pulled latest from GitHub",
+        "  - [x] Built and installed v0.9.24",
+        "  - [x] npm global updated",
+        "  - [x] Hooks configured",
+        "  - [x] Doctor: all checks PASS",
+        "  ```",
+        "- Tell the user to restart their session to pick up the new version.",
+    ].join("\n");
+    return trackResponse("ctx_upgrade", {
         content: [{ type: "text", text }],
     });
 });
@@ -1126,8 +1444,9 @@ async function main() {
     if (cleaned > 0) {
         console.error(`Cleaned up ${cleaned} stale DB file(s) from previous sessions`);
     }
-    // Clean up own DB on shutdown
+    // Clean up own DB + backgrounded processes on shutdown
     const shutdown = () => {
+        executor.cleanupBackgrounded();
         if (_store)
             _store.cleanup();
     };