context-mode 1.0.161 → 1.0.163

package/build/adapters/opencode/index.js

@@ -15,17 +15,11 @@
  *   - Config: opencode.json plugin array, .opencode/plugins/*.ts
  *   - Session dir: ~/.config/opencode/context-mode/sessions/
  */
-/** Strip JSONC comments (// and /* *​/) and trailing commas for JSON.parse. */
-function stripJsonComments(str) {
-    return str
-        .replace(/\/\/.*$/gm, "")
-        .replace(/\/\*[\s\S]*?\*\//g, "")
-        .replace(/,(\s*[}\]])/g, "$1");
-}
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, existsSync, constants, } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { BaseAdapter, resolveContextModeDataRoot } from "../base.js";
+import { stripJsonComments } from "../../util/jsonc.js";
 // ─────────────────────────────────────────────────────────
 // Hook constants (re-exported from hooks.ts)
 // ─────────────────────────────────────────────────────────
@@ -147,33 +141,53 @@ export class OpenCodeAdapter extends BaseAdapter {
     }
     // ── Configuration ──────────────────────────────────────
     getSettingsPath() {
-        // OpenCode uses opencode.json in the project root or .opencode/opencode.json
-        return this.settingsPath ?? resolve(`${this.platform}.json`);
+        if (this.settingsPath)
+            return this.settingsPath;
+        // Edge case (#849): writeSettings() called without a prior readSettings()
+        // (which is what populates this.settingsPath). Never create a `.json` that
+        // would shadow an existing `.jsonc` — OpenCode merges the project-root
+        // `.jsonc` LAST, so it is the authoritative config
+        // (refs/platforms/opencode/packages/opencode/src/config/config.ts:406-408
+        // + paths.ts:15-22). Prefer the existing `.jsonc` as the write target.
+        const jsoncPath = resolve(`${this.platform}.jsonc`);
+        if (existsSync(jsoncPath))
+            return jsoncPath;
+        return resolve(`${this.platform}.json`);
     }
     paths() {
+        // `.jsonc` is listed BEFORE `.json` so it is selected as the write target
+        // when both exist (#849). OpenCode loads the project-root `.json` then
+        // `.jsonc` and merges `.jsonc` last — scalars override-last, arrays concat
+        // (refs/platforms/opencode/packages/opencode/src/config/config.ts:406-408,
+        // 258-260 + paths.ts:15-22). The `.jsonc` is therefore the authoritative
+        // file holding the user's real config; a `.json` is often an empty/auto-
+        // generated placeholder. Writing into the placeholder would create a
+        // file that shadows the user's real `.jsonc`. Preferring `.jsonc` for the
+        // write target avoids that silent config destruction. Read order is
+        // irrelevant for the plugin early-return (hasContextModePlugin) path.
         if (this.platform === "kilo") {
             // Kilo runtime accepts `.kilo/`, `.kilocode/`, and `.opencode/` as
             // project config dirs (refs/platforms/kilo/packages/opencode/src/
             // kilocode/config/config.ts:50,408). Mirror that here so context-mode
             // discovers config regardless of which suffix the user adopted.
             return [
-                resolve("kilo.json"),
                 resolve("kilo.jsonc"),
-                resolve(".kilo", "kilo.json"),
+                resolve("kilo.json"),
                 resolve(".kilo", "kilo.jsonc"),
-                resolve(".kilocode", "kilo.json"),
+                resolve(".kilo", "kilo.json"),
                 resolve(".kilocode", "kilo.jsonc"),
-                join(homedir(), ".config", "kilo", "kilo.json"),
+                resolve(".kilocode", "kilo.json"),
                 join(homedir(), ".config", "kilo", "kilo.jsonc"),
+                join(homedir(), ".config", "kilo", "kilo.json"),
             ];
         }
         return [
-            resolve("opencode.json"),
             resolve("opencode.jsonc"),
-            resolve(".opencode", "opencode.json"),
+            resolve("opencode.json"),
             resolve(".opencode", "opencode.jsonc"),
-            join(homedir(), ".config", "opencode", "opencode.json"),
+            resolve(".opencode", "opencode.json"),
             join(homedir(), ".config", "opencode", "opencode.jsonc"),
+            join(homedir(), ".config", "opencode", "opencode.json"),
         ];
     }
     getSessionDir() {

package/build/adapters/opencode/zod3tov4.js

@@ -29,13 +29,13 @@ function zod3ToV4(v, depth = 0) {
     let result;
     switch (def.typeName) {
         case "ZodString":
-            result = z.string();
+            result = def.coerce === true ? z.coerce.string() : z.string();
             break;
         case "ZodNumber":
-            result = z.number();
+            result = def.coerce === true ? z.coerce.number() : z.number();
             break;
         case "ZodBoolean":
-            result = z.boolean();
+            result = def.coerce === true ? z.coerce.boolean() : z.boolean();
             break;
         case "ZodAny":
             result = z.any();
@@ -96,10 +96,31 @@ function zod3ToV4(v, depth = 0) {
             result = z.union(opts.map(o => zod3ToV4(o, depth + 1)));
             break;
         }
-        case "ZodEffects":
-            // Host schema only. Original Zod 3 schema still parses in execute().
-            result = zod3ToV4(def.schema, depth + 1);
+        case "ZodEffects": {
+            // Zod v3 has two patterns for coercion:
+            //
+            // 1. Native coercion (z.coerce.number()): typeName is ZodNumber
+            //    with _def.coerce=true. Handled in the ZodNumber case above.
+            //
+            // 2. Custom preprocess (z.preprocess(fn, schema)): typeName is
+            //    ZodEffects with effect.type="preprocess". The transform is
+            //    plain JS and works identically in Zod v4's z.preprocess().
+            //
+            // We never map ZodEffects→native coerce here because native
+            // coerce is already a ZodType (not ZodEffects), and custom
+            // transforms can't be safely replaced (e.g., z.coerce.boolean()
+            // in v4 converts "false"→true via Boolean(), which is wrong).
+            const effect = def.effect;
+            if (effect?.type === "preprocess" && typeof effect?.transform === "function") {
+                const innerSchema = zod3ToV4(def.schema, depth + 1);
+                result = z.preprocess(effect.transform, innerSchema);
+            }
+            else {
+                // Refinement / transform effects — host schema only.
+                result = zod3ToV4(def.schema, depth + 1);
+            }
             break;
+        }
         default:
             // Never leak raw Zod 3 schemas back to a v4 host.
             result = z.unknown();

package/build/adapters/pi/extension.d.ts

@@ -45,20 +45,10 @@ export declare function isSafeCurlWget(segment: string): boolean;
  * can `await` the wiring deterministically without relying on internal
  * timing or `setImmediate` polling.
  *
- * Reset to a fresh promise on every `piExtension(pi)` call so repeated
- * registrations in one test process don't see a stale resolution from
- * a prior load.
+ * Starts as an already-settled promise because the bridge is now bootstrapped
+ * lazily from `before_agent_start`, not during extension discovery.
  */
 export declare let _mcpBridgeReady: Promise<void>;
-/**
- * Returns true iff `argv` matches a Pi top-level short-circuit invocation
- * (help or version). Only argv[0] is inspected — Pi's runCli only checks
- * the first token, and subcommand-level `--help` (e.g. `pi stats --help`)
- * still spins up a real session, so we must NOT skip bootstrap there.
- *
- * Exported for unit tests.
- */
-export declare function isPiShortCircuitArgv(argv: readonly string[]): boolean;
 /**
  * Issue #545 — Pi workspace resolver.
  *

package/build/adapters/pi/extension.js

@@ -136,13 +136,16 @@ let _mcpBridge = null;
  * can `await` the wiring deterministically without relying on internal
  * timing or `setImmediate` polling.
  *
- * Reset to a fresh promise on every `piExtension(pi)` call so repeated
- * registrations in one test process don't see a stale resolution from
- * a prior load.
+ * Starts as an already-settled promise because the bridge is now bootstrapped
+ * lazily from `before_agent_start`, not during extension discovery.
  */
 export let _mcpBridgeReady = Promise.resolve();
 // Cached buildAutoInjection (500-token cap, prioritized).
 let _buildAutoInjection = undefined;
+// Pending context to inject via the 'context' hook (avoiding systemPrompt mutation
+// which breaks prefix prompt cache on DeepSeek/Anthropic/OpenAI).
+// See: https://github.com/mksglu/context-mode/issues/598
+let _pendingContext = "";
 async function getAutoInjection(pluginRoot) {
     if (_buildAutoInjection !== undefined)
         return _buildAutoInjection;
@@ -280,40 +283,52 @@ function handleCommandText(text, ctx) {
     }
     return { text };
 }
-// ── Pi short-circuit argv detection (#534) ───────────────
+// ── Pi MCP bridge lazy bootstrap (#534, #809) ───────────
 //
-// Pi's runtime loads every extension during module discovery, BEFORE its
-// `runCli()` decides whether the invocation is a real session or a
-// short-lived help / version print. Without this guard, even `pi --help`
-// causes us to spawn `server.bundle.mjs` as a long-lived stdio child —
-// which is then reparented to PID 1 the moment Pi's `--help` handler
-// returns. The MCP SDK's StdioServerTransport CPU-spins on the half-closed
-// pipe until the 30 s ppid poll catches up, accumulating multi-hour orphans
-// (see issue #534, plus the historical #311 / #388 fixes that only addressed
-// the *recovery* path — not the *prevention* path).
+// Pi loads extensions in several CLI paths that never dispatch an agent turn:
+// top-level help/version, package management (`install`, `list`, ...), config,
+// metadata commands, and project-trust probing. Bootstrapping the MCP bridge
+// during extension discovery is therefore the wrong signal: there may be no
+// real agent lifecycle and no `session_shutdown` cleanup. That caused both the
+// #534 short-lived help/version orphan class and the #809 package-command hang
+// (the bridge child's stdio handles kept Pi alive after `install`/`list`).
 //
-// Token set verified against the Pi 14.x source — specifically:
-//   refs/platforms/oh-my-pi/packages/coding-agent/src/cli.ts:runCli
-//
-//     if (first === "--help" || first === "-h" || first === "--version"
-//      || first === "-v" || first === "help") { /* short-circuit */ }
-//
-// We mirror it exactly — no inferred flags, no `-V` (Pi uses lowercase `-v`),
-// no `--no-help`. Anything else (including `pi stats --help`) routes through
-// the normal launch path and the bridge bootstraps as usual.
-const PI_SHORT_CIRCUIT_TOKENS = new Set(["--help", "-h", "--version", "-v", "help"]);
-/**
- * Returns true iff `argv` matches a Pi top-level short-circuit invocation
- * (help or version). Only argv[0] is inspected — Pi's runCli only checks
- * the first token, and subcommand-level `--help` (e.g. `pi stats --help`)
- * still spins up a real session, so we must NOT skip bootstrap there.
- *
- * Exported for unit tests.
- */
-export function isPiShortCircuitArgv(argv) {
-    if (argv.length === 0)
-        return false;
-    return PI_SHORT_CIRCUIT_TOKENS.has(argv[0]);
+// The robust signal is Pi's agent lifecycle itself. `before_agent_start` fires
+// only for invocations that are about to dispatch a model call, including
+// print-mode subagents (`pi --mode json -p --no-session`). We start and await
+// the bridge from that hook so ctx_* tools are present before Pi snapshots the
+// tool registry, while CLI-only commands never spawn a bridge at all.
+function startPiMCPBridge(pi, serverBundle, shouldKeepHandle) {
+    if (existsSync(serverBundle)) {
+        _mcpBridgeReady = bootstrapMCPTools(pi, serverBundle).then((handle) => {
+            if (shouldKeepHandle()) {
+                _mcpBridge = handle;
+            }
+            else {
+                // Bootstrap completed after this extension registration had already
+                // shut down or superseded the attempt. Do not publish a stale handle;
+                // immediately reclaim the child that bootstrap just spawned.
+                try {
+                    handle.shutdown();
+                }
+                catch {
+                    // best effort — never throw from best-effort bridge cleanup
+                }
+            }
+        }, (err) => {
+            if (!shouldKeepHandle())
+                return;
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[context-mode] WARNING: failed to bridge MCP tools to Pi (${msg}). ` +
+                `ctx_* tools will not be callable from this session.\n`);
+        });
+    }
+    else {
+        // No bundle on disk → nothing to await. Tests can still rely on
+        // _mcpBridgeReady being a settled promise.
+        _mcpBridgeReady = Promise.resolve();
+    }
+    return _mcpBridgeReady;
 }
 /**
  * Issue #545 — Pi workspace resolver.
@@ -364,6 +379,16 @@ export function resolvePiWorkspaceDir(opts) {
 export default function piExtension(pi) {
     const buildDir = dirname(fileURLToPath(import.meta.url));
     const pluginRoot = resolve(buildDir, "..", "..", "..");
+    const serverBundle = resolve(pluginRoot, "server.bundle.mjs");
+    let mcpBridgeStarted = false;
+    let mcpBridgeGeneration = 0;
+    const ensureMCPBridge = () => {
+        if (mcpBridgeStarted)
+            return _mcpBridgeReady;
+        mcpBridgeStarted = true;
+        const generation = ++mcpBridgeGeneration;
+        return startPiMCPBridge(pi, serverBundle, () => mcpBridgeStarted && mcpBridgeGeneration === generation);
+    };
     // Issue #545 — Pi workspace resolver. PI_CONFIG_DIR is Pi's CONFIG dir
     // (~/.pi), NOT the user's workspace; using it as the project anchor
     // collapsed every Pi session into a single phantom workspace. The
@@ -504,18 +529,16 @@ export default function piExtension(pi) {
     // ── 4. before_agent_start — Routing + active_memory + resume injection ─
     pi.on("before_agent_start", async (event) => {
         try {
-            // Block first agent start until the MCP bridge bootstrap has
-            // settled so the LLM call dispatched right after this handler
-            // sees the ctx_* tools in Pi's registry. Each subagent starts
-            // a fresh `pi --mode json -p --no-session` process whose only
-            // window to register tools is the gap between piExtension(pi)
-            // returning and the first before_agent_start firing — that gap
-            // is too small for the spawn → initialize → tools/list →
-            // pi.registerTool round-trip, so without this await the first
-            // (and often only) prompt of a subagent goes out with an empty
-            // ctx_* registry and the routing block becomes dead weight.
-            // Resolves on bootstrap failure too — the bridge is best-effort.
-            await _mcpBridgeReady;
+            _pendingContext = ""; // Reset — will be filled below if events exist
+            // Lazily start and await the MCP bridge only when Pi is about to
+            // dispatch a real agent turn. This is the non-brittle #534/#809 guard:
+            // help/version/package/config CLI paths may load the extension, but they
+            // never fire before_agent_start, so they never spawn server.bundle.mjs.
+            // Subagents (`pi --mode json -p --no-session`) do fire this hook; awaiting
+            // here ensures ctx_* tools are registered before Pi snapshots the tool
+            // registry for the model call. Resolves on bootstrap failure too — the
+            // bridge is best-effort.
+            await ensureMCPBridge();
             if (!_sessionId)
                 return;
             const prompt = String(event?.prompt ?? "");
@@ -590,16 +613,45 @@ export default function piExtension(pi) {
             }
             if (behavioralDirective)
                 parts.push(behavioralDirective);
-            // Return modified systemPrompt only if we added something beyond existing.
+            // Store extra context (routing anchor, active_memory, resume, behavioralDirective)
+            // for injection via the 'context' hook as a message, NOT as a systemPrompt
+            // modification. Mutating systemPrompt breaks prefix prompt caching on
+            // DeepSeek/Anthropic/OpenAI because the system message sits at messages[0]
+            // and any change invalidates the entire cache chain.
             const baseLen = existingPrompt ? 1 : 0;
             if (parts.length > baseLen) {
-                return { systemPrompt: parts.join("\n\n") };
+                const extraParts = parts.slice(baseLen);
+                _pendingContext = extraParts.join("\n\n");
+            }
+            else {
+                _pendingContext = "";
             }
         }
         catch {
+            _pendingContext = ""; // Reset — ensure no stale data escapes
             // best effort — never break agent start
         }
     });
+    // ── 4a2. context — Inject active_memory + resume + behavioralDirective as message ──
+    // Uses the 'context' hook (like hindsight does) to append context at the END of
+    // messages rather than mutating systemPrompt at the beginning. This preserves
+    // prefix prompt cache for DeepSeek, Anthropic, and OpenAI.
+    pi.on("context", (event) => {
+        try {
+            if (!_pendingContext)
+                return;
+            const ctx = _pendingContext;
+            _pendingContext = "";
+            event.messages.push({
+                role: "user",
+                content: ctx,
+            });
+            return { messages: event.messages };
+        }
+        catch {
+            // best effort — never break context assembly
+        }
+    });
     // ── 4b. before_provider_response — capture response metadata ───
     // Pi-2: Register the missing event so providers can record latency,
     // model, and token usage when Pi exposes them. Best-effort only;
@@ -676,12 +728,13 @@ export default function piExtension(pi) {
         catch {
             // best effort — never throw during shutdown
         }
-        // Race fix (#472 round-3): if shutdown fires while bridge bootstrap
-        // is still in flight, _mcpBridge is null at this point and the
-        // freshly-spawned MCP child gets orphaned once bootstrap eventually
-        // resolves. Await the bootstrap up to a 2s ceiling so we see the
-        // real handle, then call shutdown() on it. The ceiling prevents a
-        // hung bootstrap (e.g. broken bundle) from blocking session exit.
+        // Race fix (#472 round-3 + #809 lazy follow-up): if shutdown fires while
+        // bridge bootstrap is still in flight, _mcpBridge may be null at this
+        // point. Invalidate this bootstrap generation before waiting so any handle
+        // that resolves after the 2s ceiling self-shuts down instead of publishing
+        // a stale child handle after session shutdown.
+        mcpBridgeGeneration++;
+        mcpBridgeStarted = false;
         try {
             await Promise.race([
                 _mcpBridgeReady,
@@ -701,6 +754,7 @@ export default function piExtension(pi) {
             }
             _mcpBridge = null;
         }
+        _mcpBridgeReady = Promise.resolve();
     });
     // ── 8. Slash commands ──────────────────────────────────
     pi.registerCommand("ctx-stats", {
@@ -747,45 +801,9 @@ export default function piExtension(pi) {
     });
     // ── 9. MCP tool bridge (#426) ───────────────────────────
     //
-    // Pi 0.73.x has no native MCP support. Without bridging here, the
-    // routing block tells the LLM to call ctx_execute / ctx_search / etc.
-    // but those tools never appear in Pi's tool list and the LLM cannot
-    // reach them — context-mode becomes a pure cost (~2.5K tokens of
-    // system-prompt overhead, 0 actual ctx_* calls).
-    //
-    // Spawn server.bundle.mjs as a long-lived MCP child and register
-    // each of its tools via pi.registerTool() so they enter the Pi
-    // tool list under their bare names — same names the routing block
-    // emits for the Pi platform (per hooks/core/tool-naming.mjs).
-    //
-    // Best-effort: a missing bundle or a spawn failure must NOT prevent
-    // the rest of the extension (session capture, hooks, slash commands)
-    // from initializing. We log to stderr and continue.
-    // Short-circuit guard (#534): skip the MCP bridge bootstrap for
-    // `pi --help` / `pi --version` / `pi help` and similar. Pi prints and
-    // exits within milliseconds, but the bridge child would otherwise live
-    // long enough to be reparented to PID 1, half-close stdin, and pin a CPU
-    // core via the MCP SDK's stdio loop. We use process.argv directly so the
-    // guard works for any caller that boots Pi with a short-circuit token,
-    // regardless of how the runtime wires its CLI parser.
-    const piArgv = process.argv.slice(2);
-    if (isPiShortCircuitArgv(piArgv)) {
-        _mcpBridgeReady = Promise.resolve();
-        return;
-    }
-    const serverBundle = resolve(pluginRoot, "server.bundle.mjs");
-    if (existsSync(serverBundle)) {
-        _mcpBridgeReady = bootstrapMCPTools(pi, serverBundle).then((handle) => {
-            _mcpBridge = handle;
-        }, (err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[context-mode] WARNING: failed to bridge MCP tools to Pi (${msg}). ` +
-                `ctx_* tools will not be callable from this session.\n`);
-        });
-    }
-    else {
-        // No bundle on disk → nothing to await. Tests can still rely on
-        // _mcpBridgeReady being a settled promise.
-        _mcpBridgeReady = Promise.resolve();
-    }
+    // Intentionally no eager bootstrap here. `before_agent_start` is the first
+    // lifecycle signal that proves Pi is about to run a model call; starting the
+    // bridge there keeps ctx_* available for real agent turns while package/help
+    // commands that only load extensions never spawn a long-lived child (#809).
+    _mcpBridgeReady = Promise.resolve();
 }

package/build/adapters/types.d.ts

@@ -3,9 +3,10 @@
  *
  * Defines the contract that each platform adapter must implement.
  * Three paradigms exist across supported platforms:
- *   A) JSON stdin/stdout — Claude Code, Gemini CLI, VS Code Copilot, Copilot CLI, Cursor
- *   B) TS Plugin Functions — OpenCode
- *   C) MCP-only (no hooks) — Codex CLI
+ *   A) JSON stdin/stdout — Claude Code, Gemini/Qwen family CLIs, Copilot/Codex/Kimi,
+ *      Cursor, Kiro, Antigravity CLI (`agy`)
+ *   B) TS Plugin Functions — OpenCode, KiloCode, OpenClaw
+ *   C) MCP-only (no hooks) — Antigravity IDE, Zed, Pi/OMP MCP-only paths
  *
  * The MCP server layer is 100% portable and needs no adapter.
  * Only the hook layer requires platform-specific adapters.
@@ -347,7 +348,7 @@ export declare const JS_RUNTIMES: ReadonlySet<string>;
 export declare const IN_PROCESS_PLUGIN_PLATFORMS: ReadonlySet<string>;
 export declare function isInProcessPluginPlatform(p: string | undefined): boolean;
 /** Supported platform identifiers. */
-export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "omp" | "kimi" | "zed" | "qwen-code" | "unknown";
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "copilot-cli" | "cursor" | "antigravity" | "antigravity-cli" | "kiro" | "pi" | "omp" | "kimi" | "zed" | "qwen-code" | "unknown";
 /** Detection signal used to identify which platform is running. */
 export interface DetectionSignal {
     /** Platform identifier. */

package/build/adapters/types.js

@@ -3,9 +3,10 @@
  *
  * Defines the contract that each platform adapter must implement.
  * Three paradigms exist across supported platforms:
- *   A) JSON stdin/stdout — Claude Code, Gemini CLI, VS Code Copilot, Copilot CLI, Cursor
- *   B) TS Plugin Functions — OpenCode
- *   C) MCP-only (no hooks) — Codex CLI
+ *   A) JSON stdin/stdout — Claude Code, Gemini/Qwen family CLIs, Copilot/Codex/Kimi,
+ *      Cursor, Kiro, Antigravity CLI (`agy`)
+ *   B) TS Plugin Functions — OpenCode, KiloCode, OpenClaw
+ *   C) MCP-only (no hooks) — Antigravity IDE, Zed, Pi/OMP MCP-only paths
  *
  * The MCP server layer is 100% portable and needs no adapter.
  * Only the hook layer requires platform-specific adapters.

package/build/cache-heal.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plugin cache self-heal — fixes broken CLAUDE_PLUGIN_ROOT references.
+ *
+ * Claude Code's plugin auto-update can leave installed_plugins.json pointing
+ * to a non-existent directory (anthropics/claude-code#46915). This module
+ * detects and repairs the mismatch by creating symlinks.
+ *
+ * 4-layer defense:
+ *   1. start.mjs startup — reverse heal (registry → symlink to us)
+ *   2. server.ts first tool call — mid-session heal
+ *   3. postinstall.mjs — backward symlink on new install
+ *   4. global hook auto-deploy — survives total plugin cache breakage
+ */
+export interface HealResult {
+    healed: boolean;
+    action?: "symlink" | "global-hook" | "none";
+    from?: string;
+    to?: string;
+}
+/**
+ * Core heal: if installed_plugins.json points to a non-existent directory,
+ * create a symlink from that path to our actual directory.
+ *
+ * @param currentDir - The directory we're actually running from
+ * @param installedPluginsPath - Path to installed_plugins.json (injectable for testing)
+ */
+export declare function healRegistryMismatch(currentDir: string, installedPluginsPath?: string): HealResult;
+/**
+ * Deploy a global SessionStart hook that heals plugin cache mismatches.
+ * This hook lives outside the plugin directory, so it survives cache breakage.
+ *
+ * Written to ~/.claude/hooks/context-mode-cache-heal.sh
+ */
+export declare function deployGlobalHealHook(): HealResult;
+/**
+ * Backward symlink: during postinstall, if the registry points to a
+ * non-existent OLD path, create a symlink from old → new (our directory).
+ * Same as healRegistryMismatch but called from postinstall context.
+ */
+export { healRegistryMismatch as healBackwardCompat };
+/**
+ * Mid-session heal — call on first MCP tool invocation.
+ * Checks if registry path differs from our running directory.
+ * Creates symlink if needed. Runs only once per process.
+ */
+export declare function healMidSession(currentDir: string): HealResult;
+/** Reset mid-session flag (for testing only) */
+export declare function _resetMidSession(): void;