context-mode 1.0.137 → 1.0.138

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.137"
+    "version": "1.0.138"
   },
   "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.137",
+      "version": "1.0.138",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.137",
+  "version": "1.0.138",
   "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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.137",
+  "version": "1.0.138",
   "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.137",
+  "version": "1.0.138",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.137",
+  "version": "1.0.138",
   "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

@@ -439,6 +439,8 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
 **Verify:** In the OpenCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
+**Upgrade note:** If an existing config still has `mcp.context-mode`, run `context-mode upgrade`. OpenCode now gets `ctx_*` tools from the plugin; the upgrade removes only `mcp.context-mode` and preserves any other MCP servers.
+
 **Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts. The `experimental.chat.system.transform` hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The `chat.message` hook captures user prompts and decisions (UserPromptSubmit equivalent).
 
 > **Note:** OpenCode lacks a real SessionStart hook ([#14808](https://github.com/sst/opencode/issues/14808), [#5409](https://github.com/sst/opencode/issues/5409)). The plugin uses `experimental.chat.system.transform` as a surrogate — it injects both the routing block and resume snapshots into the system prompt. User-prompt capture uses `chat.message` instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.
@@ -481,6 +483,8 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 
 **Verify:** In the KiloCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
+**Upgrade note:** If an existing config still has `mcp.context-mode`, run `context-mode upgrade`. KiloCode now gets `ctx_*` tools from the plugin; the upgrade removes only `mcp.context-mode` and preserves any other MCP servers.
+
 **Routing:** Hooks enforce routing programmatically via `tool.execute.before` and `tool.execute.after`. The optional [`AGENTS.md`](configs/opencode/AGENTS.md) file provides routing instructions for model awareness. The `experimental.session.compacting` hook builds resume snapshots when the conversation compacts. The `experimental.chat.system.transform` hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The `chat.message` hook captures user prompts and decisions (UserPromptSubmit equivalent).
 
 > **Note:** KiloCode shares the same plugin architecture as OpenCode, using the OpenCodeAdapter with platform-specific configuration paths (`kilo.json` instead of `opencode.json`, `~/.config/kilo/` instead of `~/.config/opencode/`). Like OpenCode, it lacks a real SessionStart hook — the plugin uses `experimental.chat.system.transform` as a surrogate. User-prompt capture uses `chat.message` instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.
@@ -1190,7 +1194,7 @@ Tool call output can be collapsed/expanded with the default Pi's default keybind
 
 | Feature | Claude Code | Qwen Code | Gemini CLI | VS Code Copilot | JetBrains Copilot | Cursor | OpenCode | KiloCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi | OMP |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| MCP Server | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| MCP Server / Native Tools | Yes | Yes | Yes | Yes | Yes | Yes | Native plugin | Native plugin | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
 | PreToolUse Hook | Yes | Yes | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | Yes (extension) | Plugin |
 | PostToolUse Hook | Yes | Yes | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | Yes (extension) | Plugin |
 | SessionStart Hook | Yes | Yes | Yes | Yes | Yes | -- | ✓ (via experimental.chat.system.transform) | ✓ (via experimental.chat.system.transform) | Plugin | Yes | -- | -- | -- | Yes (extension) | Plugin |

package/build/adapters/jetbrains-copilot/hooks.d.ts

@@ -45,7 +45,15 @@ export declare function isContextModeHook(entry: {
 }, hookType: HookType): boolean;
 /**
  * Build the hook command string for a given hook type.
- * Uses absolute node path to avoid PATH issues (homebrew, nvm, volta, etc.).
- * Falls back to CLI dispatcher if pluginRoot is not provided.
+ *
+ * Always emits the CLI dispatcher form
+ * (`context-mode hook jetbrains-copilot <event>`) — the `pluginRoot`
+ * argument is accepted for API compatibility but intentionally ignored.
+ *
+ * Same Tier C contract as VS Code Copilot (Issue #613):
+ * `.github/hooks/context-mode.json` is workspace-committed (team-shared
+ * via git). Embedding `process.execPath` or absolute pluginRoot paths
+ * leaks PII and breaks cross-machine portability. See
+ * src/adapters/vscode-copilot/hooks.ts for the full archaeology.
  */
-export declare function buildHookCommand(hookType: HookType, pluginRoot?: string): string;
+export declare function buildHookCommand(hookType: HookType, _pluginRoot?: string): string;

package/build/adapters/jetbrains-copilot/hooks.js

@@ -1,4 +1,3 @@
-import { buildNodeCommand } from "../types.js";
 /**
  * adapters/jetbrains-copilot/hooks — JetBrains Copilot hook definitions and matchers.
  *
@@ -68,16 +67,21 @@ export function isContextModeHook(entry, hookType) {
 }
 /**
  * Build the hook command string for a given hook type.
- * Uses absolute node path to avoid PATH issues (homebrew, nvm, volta, etc.).
- * Falls back to CLI dispatcher if pluginRoot is not provided.
+ *
+ * Always emits the CLI dispatcher form
+ * (`context-mode hook jetbrains-copilot <event>`) — the `pluginRoot`
+ * argument is accepted for API compatibility but intentionally ignored.
+ *
+ * Same Tier C contract as VS Code Copilot (Issue #613):
+ * `.github/hooks/context-mode.json` is workspace-committed (team-shared
+ * via git). Embedding `process.execPath` or absolute pluginRoot paths
+ * leaks PII and breaks cross-machine portability. See
+ * src/adapters/vscode-copilot/hooks.ts for the full archaeology.
  */
-export function buildHookCommand(hookType, pluginRoot) {
+export function buildHookCommand(hookType, _pluginRoot) {
     const scriptName = HOOK_SCRIPTS[hookType];
     if (!scriptName) {
         throw new Error(`No script defined for hook type: ${hookType}`);
     }
-    if (pluginRoot) {
-        return buildNodeCommand(`${pluginRoot}/hooks/jetbrains-copilot/${scriptName}`);
-    }
     return `context-mode hook jetbrains-copilot ${hookType.toLowerCase()}`;
 }

package/build/adapters/vscode-copilot/hooks.d.ts

@@ -41,7 +41,31 @@ export declare function isContextModeHook(entry: {
 }, hookType: HookType): boolean;
 /**
  * Build the hook command string for a given hook type.
- * Uses absolute node path to avoid PATH issues (homebrew, nvm, volta, etc.).
- * Falls back to CLI dispatcher if pluginRoot is not provided.
+ *
+ * Always emits the CLI dispatcher form
+ * (`context-mode hook vscode-copilot <event>`) — the `pluginRoot` argument
+ * is accepted for API compatibility but intentionally ignored.
+ *
+ * Why the dispatcher form is mandatory here (Issue #613 — Tier C contract):
+ *   `.github/hooks/context-mode.json` is a **workspace-committed** file
+ *   (upstream: refs/platforms/vscode-copilot/assets/prompts/skills/
+ *   agent-customization/references/hooks.md line 7 — "Workspace
+ *   (team-shared)"). It lands in every teammate's `git status`. Embedding
+ *   `process.execPath` or any absolute pluginRoot path here:
+ *     - Leaks PII (username, `C:/Users/<user>/...` paths).
+ *     - Breaks cross-machine portability (fnm/nvm/volta/brew shims are
+ *       per-shell-session ephemeral; the path goes stale immediately on
+ *       Windows + fnm).
+ *
+ * Commit `f5c9d02` (2026-03-06) added an absolute-path branch when a
+ * pluginRoot was passed. It solved a real PATH-availability bug on
+ * Brew/nvm setups by going too far — the CLI then always passes
+ * pluginRoot, so the portable form became unreachable in production
+ * and every `/ctx-upgrade` baked a non-portable command into the
+ * committed config. This reverts to the pre-`f5c9d02` shape.
+ *
+ * For users without a global install, the recovery path is the same as
+ * every other CLI-dispatcher adapter (cursor, codex):
+ *   `npm install -g context-mode`
  */
-export declare function buildHookCommand(hookType: HookType, pluginRoot?: string): string;
+export declare function buildHookCommand(hookType: HookType, _pluginRoot?: string): string;

package/build/adapters/vscode-copilot/hooks.js

@@ -1,4 +1,3 @@
-import { buildNodeCommand } from "../types.js";
 /**
  * adapters/vscode-copilot/hooks — VS Code Copilot hook definitions and matchers.
  *
@@ -63,21 +62,37 @@ export function isContextModeHook(entry, hookType) {
 }
 /**
  * Build the hook command string for a given hook type.
- * Uses absolute node path to avoid PATH issues (homebrew, nvm, volta, etc.).
- * Falls back to CLI dispatcher if pluginRoot is not provided.
+ *
+ * Always emits the CLI dispatcher form
+ * (`context-mode hook vscode-copilot <event>`) — the `pluginRoot` argument
+ * is accepted for API compatibility but intentionally ignored.
+ *
+ * Why the dispatcher form is mandatory here (Issue #613 — Tier C contract):
+ *   `.github/hooks/context-mode.json` is a **workspace-committed** file
+ *   (upstream: refs/platforms/vscode-copilot/assets/prompts/skills/
+ *   agent-customization/references/hooks.md line 7 — "Workspace
+ *   (team-shared)"). It lands in every teammate's `git status`. Embedding
+ *   `process.execPath` or any absolute pluginRoot path here:
+ *     - Leaks PII (username, `C:/Users/<user>/...` paths).
+ *     - Breaks cross-machine portability (fnm/nvm/volta/brew shims are
+ *       per-shell-session ephemeral; the path goes stale immediately on
+ *       Windows + fnm).
+ *
+ * Commit `f5c9d02` (2026-03-06) added an absolute-path branch when a
+ * pluginRoot was passed. It solved a real PATH-availability bug on
+ * Brew/nvm setups by going too far — the CLI then always passes
+ * pluginRoot, so the portable form became unreachable in production
+ * and every `/ctx-upgrade` baked a non-portable command into the
+ * committed config. This reverts to the pre-`f5c9d02` shape.
+ *
+ * For users without a global install, the recovery path is the same as
+ * every other CLI-dispatcher adapter (cursor, codex):
+ *   `npm install -g context-mode`
  */
-export function buildHookCommand(hookType, pluginRoot) {
+export function buildHookCommand(hookType, _pluginRoot) {
     const scriptName = HOOK_SCRIPTS[hookType];
     if (!scriptName) {
         throw new Error(`No script defined for hook type: ${hookType}`);
     }
-    if (pluginRoot) {
-        // v1.0.107 fix — was `${pluginRoot}/hooks/${scriptName}` which resolved to
-        // the Claude-Code generic hook (`hooks/pretooluse.mjs`) instead of the
-        // VSCode-specific wrapper at `hooks/vscode-copilot/pretooluse.mjs`. JetBrains
-        // adapter already had the correct subdir (jetbrains-copilot/hooks.ts:98)
-        // so this brings VSCode to parity.
-        return buildNodeCommand(`${pluginRoot}/hooks/vscode-copilot/${scriptName}`);
-    }
     return `context-mode hook vscode-copilot ${hookType.toLowerCase()}`;
 }

package/build/cli.js

@@ -14,7 +14,7 @@
 import * as p from "@clack/prompts";
 import color from "picocolors";
 import { execFileSync, execSync, execFile as nodeExecFile } from "node:child_process";
-import { readFileSync, writeFileSync, cpSync, accessSync, existsSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
+import { readFileSync, cpSync, accessSync, existsSync, readdirSync, rmSync, closeSync, openSync, chmodSync, constants } from "node:fs";
 import { request as httpsRequest } from "node:https";
 import { resolve, dirname, join } from "node:path";
 import { tmpdir, devNull, homedir } from "node:os";
@@ -27,7 +27,7 @@ import { discoverSiblingMcpPids, killSiblingMcpServers } from "./util/sibling-mc
 // v1.0.119 — Issue #523 Layer 5 heal: post-bump assertion on .claude-plugin/plugin.json
 // mcpServers args. Single source of truth shared with start.mjs HEAL block + postinstall.
 // @ts-expect-error — JS module, no TS declarations
-import { healPluginJsonMcpServers, healMcpJsonArgs } from "../scripts/heal-installed-plugins.mjs";
+import { healPluginJsonMcpServers, sweepStaleMcpJson } from "../scripts/heal-installed-plugins.mjs";
 // @ts-expect-error — JS module, no TS declarations
 import { detectWindowsVsYear } from "../scripts/heal-better-sqlite3.mjs";
 // Private 16-LOC copy of browserOpenArgv. Canonical version lives in src/server.ts;
@@ -454,6 +454,166 @@ async function doctor() {
         p.log.warn(color.yellow("Plugin enabled: WARN") +
             ` — ${pluginCheck.message}`);
     }
+    // ── Issue #613 — proactive Tier C absolute-path detection ───────────
+    // PR #620 fixed `buildHookCommand` for vscode-copilot + jetbrains-copilot
+    // so future writes are CLI-dispatcher-shape. But users who ran
+    // /ctx-upgrade on v1.0.136 or earlier are still carrying poisoned
+    // committable files in their workspace:
+    //   - `.github/hooks/context-mode.json`      (vscode-copilot, team-shared)
+    //   - `.jetbrains/copilot/hooks.json`        (jetbrains-copilot, team-shared)
+    //   - `.cursor/hooks.json`                   (cursor, team-shared)
+    // Per ISSUE-613-VERDICT §6.1 these are Tier C — workspace-committed
+    // cross-machine config. Doctor scans them for absolute paths and
+    // fnm_multishells shims; if found, FAIL with `ctx_upgrade` remediation.
+    // Per ISSUE-604-VERDICT §11 ("silent-green doctor while hooks are dead
+    // is itself a P0 trust bug") — surface poison BEFORE the user hits a
+    // runtime failure.
+    p.log.step("Checking team-shared hook configs in your workspace...");
+    {
+        const projectDir = process.cwd();
+        const tierCFiles = [
+            ".github/hooks/context-mode.json",
+            ".cursor/hooks.json",
+            ".jetbrains/copilot/hooks.json",
+        ];
+        let tierCFails = 0;
+        let tierCChecked = 0;
+        // Detect absolute-path patterns that should never appear in a
+        // workspace-committed config. Per Mert's standing Windows-safety rule:
+        // handle both `/` and `\\` separators.
+        function isAbsoluteOrShimPath(s) {
+            // unix absolute
+            if (s.startsWith("/"))
+                return true;
+            // Windows drive-letter absolute (e.g. C:/, C:\)
+            if (/^[A-Za-z]:[/\\]/.test(s))
+                return true;
+            // Windows UNC or escaped-backslash absolute fragments
+            if (s.includes("\\\\"))
+                return true;
+            // fnm shim hint — issue #613 reporter's exact stderr shape
+            if (s.includes("fnm_multishells"))
+                return true;
+            // process.execPath literal baked into JSON
+            if (s.includes("process.execPath"))
+                return true;
+            return false;
+        }
+        function recurseStrings(node, hit) {
+            if (typeof node === "string") {
+                hit(node);
+            }
+            else if (Array.isArray(node)) {
+                for (const item of node)
+                    recurseStrings(item, hit);
+            }
+            else if (node && typeof node === "object") {
+                for (const v of Object.values(node))
+                    recurseStrings(v, hit);
+            }
+        }
+        for (const rel of tierCFiles) {
+            const abs = resolve(projectDir, rel);
+            if (!existsSync(abs))
+                continue; // missing config → SKIP, no false fail
+            tierCChecked++;
+            try {
+                const parsed = JSON.parse(readFileSync(abs, "utf-8"));
+                const offenders = [];
+                recurseStrings(parsed, (s) => {
+                    if (isAbsoluteOrShimPath(s))
+                        offenders.push(s);
+                });
+                if (offenders.length > 0) {
+                    criticalFails++;
+                    tierCFails++;
+                    // Truncate to one example to keep output readable; show count.
+                    const example = offenders[0].length > 100
+                        ? offenders[0].slice(0, 97) + "..."
+                        : offenders[0];
+                    p.log.error(color.red(`Hook config: FAIL`) +
+                        ` — ${rel} has your machine's local paths baked in` +
+                        color.dim("\n  This file is committed to git, so teammates and CI will get your path and the hooks will break for them." +
+                            `\n  Found ${offenders.length} hard-coded path(s), e.g.: ${example}` +
+                            "\n  Fix: run /context-mode:ctx-upgrade — it rewrites the file to a portable form that works on every machine." +
+                            "\n  Details: https://github.com/mksglu/context-mode/issues/613"));
+                }
+                else {
+                    p.log.success(color.green("Hook config: PASS") +
+                        color.dim(` — ${rel} is portable (no hard-coded paths)`));
+                }
+            }
+            catch (err) {
+                // Malformed JSON should not crash doctor; warn and move on.
+                const msg = err instanceof Error ? err.message : String(err);
+                p.log.warn(color.yellow(`Hook config: WARN`) +
+                    ` — ${rel} is not valid JSON` +
+                    color.dim("\n  Doctor cannot scan it for portability issues until the file parses." +
+                        "\n  Fix: open the file and check it in a JSON validator, or delete it and run /context-mode:ctx-upgrade to regenerate." +
+                        `\n  Parser said: ${msg.slice(0, 160)}`));
+            }
+        }
+        if (tierCChecked === 0) {
+            p.log.info(color.dim("Hook config: SKIP — no team-shared hook configs found in this workspace"));
+        }
+        else if (tierCFails === 0) {
+            // already individual PASS messages above; no need for a summary
+        }
+    }
+    // ── Issue #609 — proactive stale `.mcp.json` detection ──────────────
+    // PR #620 deleted the per-version cache `.mcp.json` write from cli.ts
+    // and shipped `sweepStaleMcpJson` to clean up any pre-existing copies.
+    // But users on the field may still have stale `.mcp.json` files left
+    // by /ctx-upgrade flows that ran before PR #620 (or by Claude Code's
+    // native auto-update copying a poisoned file forward). Surface those
+    // as WARN (recoverable — next ctx_upgrade sweeps them) so the user
+    // knows what to do instead of being told everything is green while
+    // the file lingers on disk.
+    // Per ISSUE-604-VERDICT §11 same trust contract as Tier C check above.
+    p.log.step("Checking for leftover .mcp.json files from older versions...");
+    {
+        const cacheRoot = join(homedir(), ".claude", "plugins", "cache", "context-mode", "context-mode");
+        if (!existsSync(cacheRoot)) {
+            p.log.info(color.dim("Leftover .mcp.json check: SKIP — no plugin cache exists yet (Claude Code has not installed context-mode here)"));
+        }
+        else {
+            let staleCount = 0;
+            const staleVersions = [];
+            try {
+                const versionDirs = readdirSync(cacheRoot);
+                for (const v of versionDirs) {
+                    const candidate = join(cacheRoot, v, ".mcp.json");
+                    if (existsSync(candidate)) {
+                        staleCount++;
+                        if (staleVersions.length < 5)
+                            staleVersions.push(v);
+                    }
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                p.log.warn(color.yellow("Leftover .mcp.json check: WARN") +
+                    ` — could not read the plugin cache directory` +
+                    color.dim(`\n  Path: ${cacheRoot}` +
+                        `\n  Reason: ${msg.slice(0, 160)}` +
+                        "\n  Fix: check that the directory is readable, then re-run doctor. If the issue persists, run /context-mode:ctx-upgrade."));
+                staleCount = 0;
+            }
+            if (staleCount === 0) {
+                p.log.success(color.green("Leftover .mcp.json check: PASS") +
+                    color.dim(" — no old .mcp.json files in the plugin cache"));
+            }
+            else {
+                // WARN, not FAIL — per architect spec this is recoverable.
+                p.log.warn(color.yellow("Leftover .mcp.json check: WARN") +
+                    ` — found ${staleCount} old .mcp.json file(s) left over from previous context-mode versions` +
+                    color.dim("\n  These are harmless but should be cleaned up so they cannot confuse Claude Code after an auto-update." +
+                        `\n  Versions affected: ${staleVersions.join(", ")}${staleCount > staleVersions.length ? ", ..." : ""}` +
+                        "\n  Fix: run /context-mode:ctx-upgrade — it sweeps these files automatically on the next run." +
+                        "\n  Details: https://github.com/mksglu/context-mode/issues/609"));
+            }
+        }
+    }
     // FTS5 / SQLite
     p.log.step("Checking FTS5 / SQLite...");
     try {
@@ -798,20 +958,24 @@ async function upgrade(opts) {
                 }
                 catch { /* some files may not exist in source */ }
             }
-            // Write .mcp.json with CLAUDE_PLUGIN_ROOT placeholder (fixes #411).
-            // Absolute paths bake-in the current pluginRoot dir, which sessionstart.mjs
-            // (#181) deletes after upgrade — breaking MCP server resolution. The literal
-            // ${CLAUDE_PLUGIN_ROOT} placeholder is resolved by Claude at load-time and
-            // stays valid across version cleanups. Matches .claude-plugin/plugin.json.
-            const mcpConfig = {
-                mcpServers: {
-                    "context-mode": {
-                        command: "node",
-                        args: ["${CLAUDE_PLUGIN_ROOT}/start.mjs"],
-                    },
-                },
-            };
-            writeFileSync(resolve(pluginRoot, ".mcp.json"), JSON.stringify(mcpConfig, null, 2) + "\n");
+            // Issue #609 — DO NOT write `.mcp.json` into the plugin cache dir.
+            //
+            // Historical context: #411 fixed an absolute-path bake by writing the
+            // ${CLAUDE_PLUGIN_ROOT} placeholder form here. #531 (commit 9261377)
+            // removed `.mcp.json` from `package.json files[]` so the npm tarball
+            // stopped shipping it. But the cli-side write persisted, so every
+            // /ctx-upgrade re-baked one. When Claude Code's native plugin manager
+            // auto-update later carries a previous version's `.mcp.json` forward
+            // into a fresh version dir, the stale start.mjs absolute path goes
+            // with it → MODULE_NOT_FOUND on every MCP boot.
+            //
+            // Architectural fix: Claude Code reads `.claude-plugin/plugin.json`
+            // .mcpServers as the canonical source (upstream:
+            // refs/platforms/claude-code/src/utils/plugins/mcpPluginIntegration.ts:131-212).
+            // `.mcp.json` is a redundant per-version artifact whose only role
+            // historically was to be a write-time poison vector. Don't write it.
+            // The post-bump cache-sweep below removes any pre-existing copies so
+            // the previous-version-carry vector cannot replay.
             // Normalize hooks.json + plugin.json against the REAL pluginRoot now that
             // files have been copied. Two reasons:
             //   1. If a prior buggy postinstall (or any future regression) baked the
@@ -908,30 +1072,33 @@ async function upgrade(opts) {
                 const message = err instanceof Error ? err.message : String(err);
                 throw new Error(`plugin.json drift check failed: ${message}`);
             }
-            // v1.0.122 — Issue #531 — Layer 6 heal: assert .mcp.json's
-            // mcpServers["context-mode"].args[0] is the literal ${CLAUDE_PLUGIN_ROOT}/start.mjs
-            // placeholder. Asymmetric-heal sibling of the plugin.json assertion above.
-            // cli.ts writes .mcp.json at ~line 829-845 with the placeholder, but never
-            // asserted the on-disk shape afterwards — if a future regression dropped
-            // the placeholder write or a parallel normalize baked in an absolute path,
-            // upgrade() would declare success on a poisoned tree. Belt-and-braces:
-            // first call cleans any drift; second call MUST return healed:[] or throw.
-            // Single source of truth shared with start.mjs HEAL block + postinstall.
+            // Issue #609 — Layer 6 replacement: sweep stale `.mcp.json` files from
+            // every per-version cache dir. Supersedes the previous healMcpJsonArgs
+            // drift-check block (v1.0.122) — that block existed because cli.ts
+            // itself wrote `.mcp.json`. With the write gone (above), the only
+            // remaining `.mcp.json` files are stale carry-forwards from earlier
+            // versions. Sweep them so Claude Code's auto-update can't replay them
+            // into a fresh version dir.
+            //
+            // Belt-and-braces: a second sweep call MUST report removed:[] or we
+            // throw — same architectural-lock pattern as the plugin.json drift
+            // check above. Single source of truth shared with start.mjs HEAL
+            // block + postinstall.
             try {
                 const pluginCacheRoot = resolve(resolveClaudeConfigDir(), "plugins", "cache");
                 const pluginKey = "context-mode@context-mode";
-                const firstPass = healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey });
-                if (firstPass && firstPass.error) {
-                    throw new Error(firstPass.error);
+                const firstSweep = sweepStaleMcpJson({ pluginCacheRoot, pluginKey });
+                if (firstSweep && firstSweep.removed && firstSweep.removed.length > 0) {
+                    p.log.info(color.dim(`  Swept ${firstSweep.removed.length} stale .mcp.json file(s) from cache`));
                 }
-                const secondPass = healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey });
-                if (secondPass && Array.isArray(secondPass.healed) && secondPass.healed.length > 0) {
-                    throw new Error(`.mcp.json drift: mcpServers.args still poisoned after first heal pass (healed=${secondPass.healed.join(",")})`);
+                const secondSweep = sweepStaleMcpJson({ pluginCacheRoot, pluginKey });
+                if (secondSweep && Array.isArray(secondSweep.removed) && secondSweep.removed.length > 0) {
+                    throw new Error(`.mcp.json sweep drift: ${secondSweep.removed.length} file(s) still present after first pass`);
                 }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`.mcp.json drift check failed: ${message}`);
+                throw new Error(`.mcp.json sweep check failed: ${message}`);
             }
             // v1.0.X — Layer 7 heal: update user-level ~/.claude.json MCP server
             // registrations that point to old context-mode version dirs.

package/build/openclaw-plugin.d.ts

@@ -0,0 +1,130 @@
+/**
+ * OpenClaw TypeScript plugin entry point for context-mode.
+ *
+ * Exports an object with { id, name, configSchema, register(api) } for
+ * declarative metadata and config validation before code execution.
+ *
+ * register(api) registers:
+ *   - before_tool_call hook   — Routing enforcement (deny/modify/passthrough)
+ *   - after_tool_call hook    — Session event capture
+ *   - command:new hook         — Session initialization and cleanup
+ *   - session_start hook             — Re-key DB session to OpenClaw's session ID
+ *   - before_compaction hook         — Flush events to resume snapshot
+ *   - after_compaction hook          — Increment compact count
+ *   - before_prompt_build (p=10)  — Resume snapshot injection into system context
+ *   - before_prompt_build (p=5)   — Routing instruction injection into system context
+ *   - context-mode engine      — Context engine with compaction management
+ *   - /ctx-stats command       — Auto-reply command for session statistics
+ *   - /ctx-doctor command      — Auto-reply command for diagnostics
+ *   - /ctx-upgrade command     — Auto-reply command for upgrade
+ *
+ * Loaded by OpenClaw via: openclaw.extensions entry in package.json
+ *
+ * OpenClaw plugin paradigm:
+ *   - Plugins export { id, name, configSchema, register(api) } for metadata
+ *   - api.registerHook() for event-driven hooks
+ *   - api.on() for typed lifecycle hooks
+ *   - api.registerContextEngine() for compaction ownership
+ *   - api.registerCommand() for auto-reply slash commands
+ *   - Plugins run in-process with the Gateway (trusted code)
+ */
+import type { OpenClawToolDef } from "./openclaw/mcp-tools.js";
+/** Context for auto-reply command handlers. */
+interface CommandContext {
+    senderId?: string;
+    channel?: string;
+    isAuthorizedSender?: boolean;
+    args?: string;
+    commandBody?: string;
+    config?: Record<string, unknown>;
+}
+/** OpenClaw plugin API provided to the register function. */
+interface OpenClawPluginApi {
+    registerHook(event: string, handler: (...args: unknown[]) => unknown, meta: {
+        name: string;
+        description: string;
+    }): void;
+    /**
+     * Register a typed lifecycle hook.
+     * Supported names: "session_start", "before_compaction", "after_compaction",
+     * "before_prompt_build"
+     */
+    on(event: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }): void;
+    registerContextEngine(id: string, factory: () => ContextEngineInstance): void;
+    registerCommand?(cmd: {
+        name: string;
+        description: string;
+        acceptsArgs?: boolean;
+        requireAuth?: boolean;
+        handler: (ctx: CommandContext) => {
+            text: string;
+        } | Promise<{
+            text: string;
+        }>;
+    }): void;
+    registerCli?(factory: (ctx: {
+        program: unknown;
+    }) => void, meta: {
+        commands: string[];
+    }): void;
+    /**
+     * Register an agent tool (OpenClaw native registerTool) — see
+     * refs/platforms/openclaw/docs/plugins/building-plugins.md:116. Optional in
+     * the type so we degrade silently on legacy hosts that pre-date this API.
+     */
+    registerTool?(tool: OpenClawToolDef, opts?: {
+        optional?: boolean;
+    }): void;
+    logger?: {
+        info: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+        debug?: (...args: unknown[]) => void;
+        warn?: (...args: unknown[]) => void;
+    };
+}
+/** Context engine instance returned by the factory. */
+interface ContextEngineInstance {
+    info: {
+        id: string;
+        name: string;
+        ownsCompaction: boolean;
+    };
+    ingest(data: unknown): Promise<{
+        ingested: boolean;
+    }>;
+    assemble(ctx: {
+        messages: unknown[];
+    }): Promise<{
+        messages: unknown[];
+        estimatedTokens: number;
+    }>;
+    compact(): Promise<{
+        ok: boolean;
+        compacted: boolean;
+    }>;
+}
+/**
+ * OpenClaw plugin definition. The object form provides declarative metadata
+ * (id, name, configSchema) that OpenClaw can read without executing code.
+ * register() is called once per agent session with a fresh api object.
+ * Each call creates isolated closures (db, sessionId, hooks) — no shared state.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            enabled: {
+                type: "boolean";
+                default: boolean;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default _default;