context-mode 1.0.104 → 1.0.105

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.104"
+    "version": "1.0.105"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.104",
+      "version": "1.0.105",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.104",
+  "version": "1.0.105",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.104",
+  "version": "1.0.105",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.104",
+  "version": "1.0.105",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -848,46 +848,17 @@ npm install -g context-mode
 
 | Tool | What it does | Context saved |
 |---|---|---|
-| `ctx_batch_execute` | Run multiple commands + search multiple queries in ONE call. | 986 KB → 62 KB |
+| `ctx_batch_execute` | Run multiple commands + search multiple queries in ONE call. Opt-in `concurrency: 1-8` for I/O-bound batches. | 986 KB → 62 KB |
 | `ctx_execute` | Run code in 11 languages. Only stdout enters context. | 56 KB → 299 B |
 | `ctx_execute_file` | Process files in sandbox. Raw content never leaves. | 45 KB → 155 B |
 | `ctx_index` | Chunk markdown into FTS5 with BM25 ranking. | 60 KB → 40 B |
 | `ctx_search` | Query indexed content with multiple queries in one call. | On-demand retrieval |
-| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. | 60 KB → 40 B |
+| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. Pass `requests: [{url, source}, ...]` + `concurrency: 1-8` for parallel multi-URL. | 60 KB → 40 B |
 | `ctx_stats` | Show context savings, call counts, and session statistics. | — |
 | `ctx_doctor` | Diagnose installation: runtimes, hooks, FTS5, versions. | — |
 | `ctx_upgrade` | Upgrade to latest version from GitHub, rebuild, reconfigure hooks. | — |
 | `ctx_purge` | Permanently deletes all indexed content from the knowledge base. | — |
 
-### Parallel I/O — opt-in concurrency
-
-Two batch tools accept `concurrency: N` (1–8, default 1) to fan out independent I/O operations:
-
-```js
-// Multi-URL research — fetches in parallel, FTS5 writes serial
-ctx_fetch_and_index({
-  requests: [
-    { url: "https://react.dev/...", source: "react" },
-    { url: "https://vue.org/...",  source: "vue" },
-    // ...
-  ],
-  concurrency: 5,
-})
-
-// Multi-API batch — gh, curl, dig, docker inspect
-ctx_batch_execute({
-  commands: [
-    { label: "issue-1", command: "gh issue view 1" },
-    { label: "issue-2", command: "gh issue view 2" },
-    // ...
-  ],
-  queries: ["..."],
-  concurrency: 4,
-})
-```
-
-**Use 4–8** for I/O-bound work (network, gh, curl). **Keep at 1** for CPU-bound (npm test, build, lint) or commands sharing state (ports, lock files, same-repo writes). Effective concurrency caps at `os.cpus().length` automatically. Indexing always serial regardless — only the fetches race.
-
 ## How the Sandbox Works
 
 Each `ctx_execute` call spawns an isolated subprocess with its own process boundary. Scripts can't access each other's memory or state. The subprocess runs your code, captures stdout, and only that stdout enters the conversation context. The raw data — log files, API responses, snapshots — never leaves the sandbox.

package/build/executor.d.ts

@@ -2,7 +2,7 @@ import { type RuntimeMap, type Language } from "./runtime.js";
 export type { ExecResult } from "./types.js";
 import type { ExecResult } from "./types.js";
 /** Pure helper — exported for unit testing. Returns "script" or "script.<ext>". */
-export declare function buildScriptFilename(language: Language, platform: NodeJS.Platform): string;
+export declare function buildScriptFilename(language: Language, platform: NodeJS.Platform, shellPath?: string | null): string;
 /**
  * Pure helper — exported for unit testing. Adds `windowsHide: true` on Windows
  * to prevent the spawned shell from creating a visible console window that

package/build/executor.js

@@ -6,8 +6,10 @@ import { detectRuntimes, buildCommand, } from "./runtime.js";
 const isWin = process.platform === "win32";
 /**
  * Pure helper: extension map for temp script files per language.
- * On Windows, shell scripts get NO extension to avoid Windows file-association
- * for `.sh` (which spawns a visible Git Bash window over the user's IDE).
+ * On Windows, shell scripts usually get NO extension to avoid Windows
+ * file-association for `.sh` (which spawns a visible Git Bash window over the
+ * user's IDE). Windows PowerShell/pwsh is the exception because `-File`
+ * requires `.ps1` there.
  */
 const SCRIPT_EXT = {
     javascript: "js",
@@ -23,9 +25,13 @@ const SCRIPT_EXT = {
     elixir: "exs",
 };
 /** Pure helper — exported for unit testing. Returns "script" or "script.<ext>". */
-export function buildScriptFilename(language, platform) {
-    if (platform === "win32" && language === "shell")
-        return "script";
+export function buildScriptFilename(language, platform, shellPath) {
+    if (platform === "win32" && language === "shell") {
+        const shellName = shellPath?.toLowerCase() ?? "";
+        return shellName.includes("powershell") || shellName.includes("pwsh")
+            ? "script.ps1"
+            : "script";
+    }
     return `script.${SCRIPT_EXT[language]}`;
 }
 /**
@@ -114,7 +120,7 @@ export class PolyglotExecutor {
         this.#backgroundedPids.clear();
     }
     async execute(opts) {
-        const { language, code, timeout = 30_000, background = false } = opts;
+        const { language, code, timeout, background = false } = opts;
         const tmpDir = mkdtempSync(join(OS_TMPDIR, ".ctx-mode-"));
         try {
             const filePath = this.#writeScript(tmpDir, code, language);
@@ -146,7 +152,7 @@ export class PolyglotExecutor {
         }
     }
     async executeFile(opts) {
-        const { path: filePath, language, code, timeout = 30_000 } = opts;
+        const { path: filePath, language, code, timeout } = opts;
         const absolutePath = resolve(this.#projectRoot, filePath);
         const wrappedCode = this.#wrapWithFileContent(absolutePath, language, code);
         return this.execute({ language, code: wrappedCode, timeout });
@@ -165,7 +171,7 @@ export class PolyglotExecutor {
             const escaped = JSON.stringify(join(this.#projectRoot, "_build/dev/lib"));
             code = `Path.wildcard(Path.join(${escaped}, "*/ebin"))\n|> Enum.each(&Code.prepend_path/1)\n\n${code}`;
         }
-        const fp = join(tmpDir, buildScriptFilename(language, process.platform));
+        const fp = join(tmpDir, buildScriptFilename(language, process.platform, language === "shell" ? this.#runtimes.shell : null));
         if (language === "shell") {
             writeFileSync(fp, code, { encoding: "utf-8", mode: 0o700 });
         }
@@ -177,11 +183,13 @@ export class PolyglotExecutor {
     async #compileAndRun(srcPath, cwd, timeout) {
         const binSuffix = isWin ? ".exe" : "";
         const binPath = srcPath.replace(/\.rs$/, "") + binSuffix;
-        // Compile
+        // Compile — cap rustc invocation at 60s when caller didn't bound the
+        // overall timeout (a hung compile shouldn't run forever even if the
+        // caller is fine with a long-running binary afterwards).
         try {
             execFileSync("rustc", [srcPath, "-o", binPath], {
                 cwd,
-                timeout: Math.min(timeout, 60_000),
+                timeout: timeout === undefined ? 60_000 : Math.min(timeout, 60_000),
                 encoding: "utf-8",
                 stdio: ["pipe", "pipe", "pipe"],
             });
@@ -232,7 +240,12 @@ export class PolyglotExecutor {
             });
             let timedOut = false;
             let resolved = false;
-            const timer = setTimeout(() => {
+            // Issue #406 — if the caller didn't pass a timeout we don't fire one.
+            // Timeout policy belongs to the MCP host/client (Claude Code, VSCode,
+            // JetBrains all enforce their own RPC timeouts); imposing a second
+            // policy here turned 30-minute Gradle/Maven/SBT builds into spurious
+            // false negatives whenever the caller forgot the explicit value.
+            const timer = timeout === undefined ? undefined : setTimeout(() => {
                 timedOut = true;
                 if (background) {
                     // Background mode: detach process, return partial output, keep running

package/build/opencode-plugin.d.ts

@@ -55,6 +55,28 @@ interface CompactingHookOutput {
     context: string[];
     prompt?: string;
 }
+/**
+ * OpenCode experimental.chat.system.transform — first parameter.
+ * Verified against sst/opencode/dev/packages/plugin/src/index.ts:
+ *   input: { sessionID?: string; model: Model }
+ * `sessionID` is optional in the SDK type but is in practice always set
+ * (the transform runs *for* a session). We treat it as required and
+ * skip injection when absent rather than fall back to a fabricated ID.
+ *
+ * NOTE: We deliberately do NOT use `experimental.chat.messages.transform`.
+ * Its SDK input shape is `{}` (no sessionID) and its output is
+ * `{ messages: { info: Message; parts: Part[] }[] }` — the prior code
+ * (`output.messages.unshift({ role, content })`) wrote a value of the
+ * wrong shape and was silently dropped (Mickey / PR #376 root cause).
+ */
+interface SystemTransformHookInput {
+    sessionID?: string;
+    model: unknown;
+}
+/** OpenCode experimental.chat.system.transform — second parameter */
+interface SystemTransformHookOutput {
+    system: string[];
+}
 /**
  * Plugin factory. Called once when KiloCode/OpenCode loads the plugin.
  * Returns an object mapping hook event names to async handler functions.
@@ -66,12 +88,7 @@ declare function createContextModePlugin(ctx: PluginContext): Promise<{
     "tool.execute.before": (input: BeforeHookInput, output: BeforeHookOutput) => Promise<void>;
     "tool.execute.after": (input: AfterHookInput, output: AfterHookOutput) => Promise<void>;
     "experimental.session.compacting": (input: CompactingHookInput, output: CompactingHookOutput) => Promise<string>;
-    "experimental.chat.messages.transform": (_input: unknown, output: {
-        messages?: Array<{
-            role: string;
-            content: string;
-        }>;
-    } | undefined) => Promise<void>;
+    "experimental.chat.system.transform": (input: SystemTransformHookInput, output: SystemTransformHookOutput) => Promise<void>;
 }>;
 declare const _default: {
     server: typeof createContextModePlugin;

package/build/opencode-plugin.js

@@ -18,7 +18,6 @@
  *   - No routing file auto-write (avoid dirtying project trees)
  *   - Session cleanup happens at plugin init (no SessionStart)
  */
-import { randomUUID } from "node:crypto";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { SessionDB } from "./session/db.js";
@@ -70,17 +69,18 @@ async function createContextModePlugin(ctx) {
     const routingPath = resolve(buildDir, "..", "hooks", "core", "routing.mjs");
     const routing = await import(pathToFileURL(routingPath).href);
     await routing.initSecurity(buildDir);
-    // Initialize session
+    // Initialize per-process state. We do NOT fabricate a sessionId here —
+    // OpenCode/Kilo provide the real `input.sessionID` on every hook, and a
+    // process-global UUID would (a) never match prior-session resume rows and
+    // (b) collide across multi-session reuse (Mickey / PR #376 root cause).
     const projectDir = ctx.directory;
     const db = new SessionDB({ dbPath: adapter.getSessionDBPath(projectDir) });
-    const sessionId = randomUUID();
-    db.ensureSession(sessionId, projectDir);
-    // Clean up old sessions on startup (replaces SessionStart hook)
+    // Clean up old sessions on startup (no SessionStart hook to do this).
     db.cleanupOldSessions(7);
-    // Track whether we've already injected the prior-session resume into
-    // a chat turn — `experimental.chat.messages.transform` fires on every
-    // turn, but we only want to inject once per process (SessionStart-equivalent).
-    let sessionStartInjected = false;
+    // Track per-session resume injection: persistent plugin process can host
+    // many sessions, so the gate must be keyed by sessionID — NOT a single
+    // boolean closure flag (Mickey #2 root cause).
+    const resumeInjected = new Set();
     return {
         // ── PreToolUse: Routing enforcement ─────────────────
         "tool.execute.before": async (input, output) => {
@@ -107,7 +107,11 @@ async function createContextModePlugin(ctx) {
         },
         // ── PostToolUse: Session event capture ──────────────
         "tool.execute.after": async (input, output) => {
+            const sessionId = input.sessionID;
+            if (!sessionId)
+                return;
             try {
+                db.ensureSession(sessionId, projectDir);
                 const hookInput = {
                     tool_name: input.tool ?? "",
                     tool_input: input.args ?? {},
@@ -126,7 +130,11 @@ async function createContextModePlugin(ctx) {
         },
         // ── PreCompact: Snapshot generation ─────────────────
         "experimental.session.compacting": async (input, output) => {
+            const sessionId = input.sessionID;
+            if (!sessionId)
+                return "";
             try {
+                db.ensureSession(sessionId, projectDir);
                 const events = db.getEvents(sessionId);
                 if (events.length === 0)
                     return "";
@@ -145,29 +153,36 @@ async function createContextModePlugin(ctx) {
             }
         },
         // ── SessionStart equivalent (PR #376) ───────────────
-        // OpenCode lacks a real SessionStart hook (#14808, #5409) but
-        // recently added `experimental.chat.messages.transform`, which
-        // fires once per chat turn before messages are sent to the model.
-        // We piggyback on the *first* invocation per process to inject the
-        // most-recent resume snapshot from a prior session — matching what
-        // every other adapter's SessionStart hook does.
-        "experimental.chat.messages.transform": async (_input, output) => {
-            if (sessionStartInjected)
+        // OpenCode lacks a real SessionStart hook (#14808, #5409). The closest
+        // surrogate is `experimental.chat.system.transform` — verified shape:
+        //   input:  { sessionID?: string; model: Model }
+        //   output: { system: string[] }
+        // We claim the most-recent unconsumed resume snapshot atomically (race-
+        // safe across concurrent processes) and prepend it to the system prompt.
+        // First-injection-per-session is enforced by `resumeInjected` Set.
+        "experimental.chat.system.transform": async (input, output) => {
+            const sessionId = input?.sessionID;
+            if (!sessionId)
+                return;
+            if (resumeInjected.has(sessionId))
                 return;
-            sessionStartInjected = true;
+            resumeInjected.add(sessionId);
             try {
-                // Find the most recent resume snapshot for this project across
-                // any prior session. ContextSessionDB has no per-project resume
-                // lookup, so we fall back to the current session's resume row.
-                const row = db.getResume(sessionId);
-                const snapshot = row?.snapshot;
-                if (!snapshot || snapshot.length === 0)
+                const row = db.claimLatestUnconsumedResume();
+                if (!row || !row.snapshot)
                     return;
-                if (output && Array.isArray(output.messages)) {
-                    output.messages.unshift({
-                        role: "system",
-                        content: snapshot,
-                    });
+                if (Array.isArray(output?.system)) {
+                    // Insert at index 1 (after the header) — NOT unshift.
+                    // OpenCode's llm.ts:117-128 saves `header = system[0]` BEFORE this
+                    // hook runs and then folds the rest into a 2-part structure
+                    // `[header, body]` only if `system[0] === header` after the hook.
+                    // Prepending via unshift replaces system[0] with the snapshot,
+                    // making the equality check fail → cache-fold is skipped → every
+                    // system block is sent as a separate `role: "system"` message →
+                    // provider prompt cache is invalidated on every resume injection.
+                    // Inserting at index 1 keeps the header invariant and lets the
+                    // snapshot ride along inside the cached body block.
+                    output.system.splice(1, 0, row.snapshot);
                 }
             }
             catch {

package/build/server.d.ts

@@ -17,7 +17,12 @@ export interface BatchRunResult {
     timedOut: boolean;
 }
 export interface BatchRunOptions {
-    timeout: number;
+    /**
+     * Total budget (concurrency=1, shared) or per-command (concurrency>1).
+     * When `undefined`, no server-side timer fires — the MCP host's RPC
+     * timeout governs (Issue #406).
+     */
+    timeout: number | undefined;
     concurrency: number;
     nodeOptsPrefix: string;
     onFsBytes?: (bytes: number) => void;
@@ -26,7 +31,7 @@ interface BatchExecutor {
     execute(input: {
         language: "shell";
         code: string;
-        timeout: number;
+        timeout: number | undefined;
     }): Promise<{
         stdout: string;
         timedOut?: boolean;

package/build/server.js

@@ -698,22 +698,28 @@ export async function runBatchCommands(commands, opts, executor) {
     const { timeout, concurrency, nodeOptsPrefix, onFsBytes } = opts;
     if (concurrency <= 1) {
         // Serial path — shared timeout budget, cascading skip on timeout.
+        // When `timeout` is undefined, no shared budget is enforced; each
+        // command runs to completion (Issue #406).
         const outputs = [];
         const startTime = Date.now();
         let timedOut = false;
         for (let i = 0; i < commands.length; i++) {
             const cmd = commands[i];
-            const elapsed = Date.now() - startTime;
-            const remaining = timeout - elapsed;
-            if (remaining <= 0) {
-                outputs.push(`# ${cmd.label}\n\n(skipped — batch timeout exceeded)\n`);
-                timedOut = true;
-                continue;
+            let perCmdTimeout;
+            if (timeout !== undefined) {
+                const elapsed = Date.now() - startTime;
+                const remaining = timeout - elapsed;
+                if (remaining <= 0) {
+                    outputs.push(`# ${cmd.label}\n\n(skipped — batch timeout exceeded)\n`);
+                    timedOut = true;
+                    continue;
+                }
+                perCmdTimeout = remaining;
             }
             const result = await executor.execute({
                 language: "shell",
                 code: `${nodeOptsPrefix}${cmd.command} 2>&1`,
-                timeout: remaining,
+                timeout: perCmdTimeout,
             });
             outputs.push(formatCommandOutput(cmd.label, result.stdout, onFsBytes));
             if (result.timedOut) {
@@ -740,7 +746,7 @@ export async function runBatchCommands(commands, opts, executor) {
             // markers are stripped + counted, even when the command timed out.
             const formatted = formatCommandOutput(cmd.label, result.stdout, onFsBytes);
             const output = result.timedOut
-                ? formatted.replace(/\n$/, "") + `\n(timed out after ${timeout}ms)\n`
+                ? formatted.replace(/\n$/, "") + `\n(timed out after ${timeout ?? "?"}ms)\n`
                 : formatted;
             return { output, timedOut: !!result.timedOut };
         },
@@ -791,8 +797,7 @@ server.registerTool("ctx_execute", {
         timeout: z
             .coerce.number()
             .optional()
-            .default(30000)
-            .describe("Max execution time in ms"),
+            .describe("Max execution time in ms. When omitted, no server-side timer fires — the MCP host's RPC timeout governs (which is the right layer for this policy). Pass an explicit value for long-running builds (Gradle/Maven/SBT)."),
         background: z
             .boolean()
             .optional()
@@ -1087,8 +1092,7 @@ server.registerTool("ctx_execute_file", {
         timeout: z
             .coerce.number()
             .optional()
-            .default(30000)
-            .describe("Max execution time in ms"),
+            .describe("Max execution time in ms. When omitted, no server-side timer fires — the MCP host's RPC timeout governs."),
         intent: z
             .string()
             .optional()
@@ -2041,8 +2045,7 @@ server.registerTool("ctx_batch_execute", {
         timeout: z
             .coerce.number()
             .optional()
-            .default(60000)
-            .describe("Max execution time in ms (default: 60s). With concurrency=1, shared budget across commands; with concurrency>1, applied per-command."),
+            .describe("Max execution time in ms. When omitted, no server-side timer fires — the MCP host's RPC timeout governs. With concurrency=1, the value (when set) is a shared budget across commands; with concurrency>1, it is applied per-command."),
         concurrency: z
             .coerce.number()
             .int()
@@ -2218,22 +2221,30 @@ server.registerTool("ctx_stats", {
 server.registerTool("ctx_doctor", {
     title: "Run Diagnostics",
     description: "Diagnose context-mode installation. Runs all checks server-side and " +
-        "returns results as a markdown checklist. No CLI execution needed.",
+        "returns a plain-text status report with [OK]/[FAIL]/[WARN] prefixes " +
+        "(renderer-safe across MCP clients). No CLI execution needed.",
     inputSchema: z.object({}),
 }, async () => {
-    const lines = ["## context-mode doctor", ""];
+    // Renderer-safe output (Mickey #3 — Z.ai GLM 4.7 ReferenceError):
+    // Z.ai's MCP renderer mounts a custom React component for GitHub-flavored
+    // markdown task-list syntax (`- [x]` / `- [ ]` / `- [-]`) that depends on
+    // a missing `client` context, throwing `ReferenceError: client is not
+    // defined`. We avoid both task-list syntax AND `## ` h2 headings to stay
+    // safe across all MCP renderers — using plain-text status prefixes
+    // (`[OK]` / `[FAIL]` / `[WARN]`) instead.
+    const lines = ["context-mode doctor", ""];
     // __pkg_dir is build/ for tsc, plugin root for bundle — resolve to plugin root
     const pluginRoot = existsSync(resolve(__pkg_dir, "package.json")) ? __pkg_dir : dirname(__pkg_dir);
     // Runtimes
     const total = 11;
     const pct = ((available.length / total) * 100).toFixed(0);
-    lines.push(`- [x] Runtimes: ${available.length}/${total} (${pct}%) — ${available.join(", ")}`);
+    lines.push(`[OK] Runtimes: ${available.length}/${total} (${pct}%) — ${available.join(", ")}`);
     // Performance
     if (hasBunRuntime()) {
-        lines.push("- [x] Performance: FAST (Bun)");
+        lines.push("[OK] Performance: FAST (Bun)");
     }
     else {
-        lines.push("- [-] Performance: NORMAL — install Bun for 3-5x speed boost");
+        lines.push("[WARN] Performance: NORMAL — install Bun for 3-5x speed boost");
     }
     // Server test — cleanup executor to prevent resource leaks (#247)
     {
@@ -2241,15 +2252,15 @@ server.registerTool("ctx_doctor", {
         try {
             const result = await testExecutor.execute({ language: "javascript", code: 'console.log("ok");', timeout: 5000 });
             if (result.exitCode === 0 && result.stdout.trim() === "ok") {
-                lines.push("- [x] Server test: PASS");
+                lines.push("[OK] Server test: PASS");
             }
             else {
                 const detail = result.stderr?.trim() ? ` (${result.stderr.trim().slice(0, 200)})` : "";
-                lines.push(`- [ ] Server test: FAIL — exit ${result.exitCode}${detail}`);
+                lines.push(`[FAIL] Server test: FAIL — exit ${result.exitCode}${detail}`);
             }
         }
         catch (err) {
-            lines.push(`- [ ] Server test: FAIL — ${err instanceof Error ? err.message : err}`);
+            lines.push(`[FAIL] Server test: FAIL — ${err instanceof Error ? err.message : err}`);
         }
         finally {
             testExecutor.cleanupBackgrounded();
@@ -2265,14 +2276,14 @@ server.registerTool("ctx_doctor", {
             testDb.exec("INSERT INTO fts_test(content) VALUES ('hello world')");
             const row = testDb.prepare("SELECT * FROM fts_test WHERE fts_test MATCH 'hello'").get();
             if (row && row.content === "hello world") {
-                lines.push("- [x] FTS5 / SQLite: PASS — native module works");
+                lines.push("[OK] FTS5 / SQLite: PASS — native module works");
             }
             else {
-                lines.push("- [ ] FTS5 / SQLite: FAIL — unexpected result");
+                lines.push("[FAIL] FTS5 / SQLite: FAIL — unexpected result");
             }
         }
         catch (err) {
-            lines.push(`- [ ] FTS5 / SQLite: FAIL — ${err instanceof Error ? err.message : err}`);
+            lines.push(`[FAIL] FTS5 / SQLite: FAIL — ${err instanceof Error ? err.message : err}`);
         }
         finally {
             try {
@@ -2284,13 +2295,13 @@ server.registerTool("ctx_doctor", {
     // Hook script
     const hookPath = resolve(pluginRoot, "hooks", "pretooluse.mjs");
     if (existsSync(hookPath)) {
-        lines.push(`- [x] Hook script: PASS — ${hookPath}`);
+        lines.push(`[OK] Hook script: PASS — ${hookPath}`);
     }
     else {
-        lines.push(`- [ ] Hook script: FAIL — not found at ${hookPath}`);
+        lines.push(`[FAIL] Hook script: FAIL — not found at ${hookPath}`);
     }
     // Version
-    lines.push(`- [x] Version: v${VERSION}`);
+    lines.push(`[OK] Version: v${VERSION}`);
     return trackResponse("ctx_doctor", {
         content: [{ type: "text", text: lines.join("\n") }],
     });
@@ -2521,14 +2532,22 @@ server.registerTool("ctx_insight", {
         "First run installs dependencies (~30s). Subsequent runs open instantly.",
     inputSchema: z.object({
         port: z.coerce.number().optional().describe("Port to serve on (default: 4747)"),
+        sessionDir: z.string().optional().describe("Override INSIGHT_SESSION_DIR: directory containing context-mode session .db files"),
+        contentDir: z.string().optional().describe("Override INSIGHT_CONTENT_DIR: directory containing context-mode content/index .db files"),
+        insightSessionDir: z.string().optional().describe("Alias for sessionDir / INSIGHT_SESSION_DIR"),
+        insightContentDir: z.string().optional().describe("Alias for contentDir / INSIGHT_CONTENT_DIR"),
     }),
-}, async ({ port: userPort }) => {
+}, async ({ port: userPort, sessionDir, contentDir, insightSessionDir, insightContentDir }) => {
     const port = userPort || 4747;
+    const explicitSessionDir = sessionDir || insightSessionDir;
+    const explicitContentDir = contentDir || insightContentDir;
     // __pkg_dir is build/ for tsc, plugin root for bundle — resolve to plugin root
     const pluginRoot = existsSync(resolve(__pkg_dir, "package.json")) ? __pkg_dir : dirname(__pkg_dir);
     const insightSource = resolve(pluginRoot, "insight");
-    // Use adapter-aware path: derive from sessions dir (works across all 12 adapters)
-    const sessDir = getSessionDir();
+    // Use adapter-aware path by default, but allow MCP callers to pass explicit
+    // Insight data dirs for hosts whose adapter/default detection is unavailable.
+    const sessDir = explicitSessionDir ? resolve(explicitSessionDir) : getSessionDir();
+    const insightContentDirResolved = explicitContentDir ? resolve(explicitContentDir) : join(dirname(sessDir), "content");
     const cacheDir = join(dirname(sessDir), "insight-cache");
     // Verify source exists
     if (!existsSync(join(insightSource, "server.mjs"))) {
@@ -2653,8 +2672,8 @@ server.registerTool("ctx_insight", {
             env: {
                 ...process.env,
                 PORT: String(port),
-                INSIGHT_SESSION_DIR: getSessionDir(),
-                INSIGHT_CONTENT_DIR: join(dirname(getSessionDir()), "content"),
+                INSIGHT_SESSION_DIR: sessDir,
+                INSIGHT_CONTENT_DIR: insightContentDirResolved,
                 INSIGHT_PARENT_PID: String(process.pid),
             },
             detached: true,

package/build/session/db.d.ts

@@ -148,6 +148,20 @@ export declare class SessionDB extends SQLiteBase {
      * Mark the resume snapshot as consumed (already injected into conversation).
      */
     markResumeConsumed(sessionId: string): void;
+    /**
+     * Atomically claim the most recent unconsumed resume snapshot in this DB.
+     *
+     * `SessionDB` is sharded per project (see `getSessionDBPath` — SHA-256 of
+     * project dir), so "this DB" already implies "this project". The atomic
+     * `UPDATE … RETURNING` ensures concurrent processes for the same project
+     * cannot both inject the same snapshot (Mickey / PR #376 race).
+     *
+     * Returns null when no unconsumed snapshot exists.
+     */
+    claimLatestUnconsumedResume(): {
+        sessionId: string;
+        snapshot: string;
+    } | null;
     /**
      * Return the most recent session_id from session_meta, or null if none.
      * Used by the runtime to attach persistent counters to the right session