@cortexkit/magic-context 0.43.2 → 0.44.1

package/dist/index.js

@@ -13037,6 +13037,15 @@ function extraCliCandidates(d) {
     join11(d.home, ".volta", "bin", "opencode")
   ];
 }
+function openChamberCliCandidates(d) {
+  if (d.platform !== "darwin")
+    return [];
+  const bundled = ["Contents", "Resources", "opencode-cli", "opencode"];
+  return [
+    join11("/Applications", "OpenChamber.app", ...bundled),
+    join11(d.home, "Applications", "OpenChamber.app", ...bundled)
+  ];
+}
 function canonicalPath(d, path) {
   try {
     return d.realpath ? d.realpath(path) : realpathSync(path);
@@ -13098,6 +13107,11 @@ function detectOpenCodeInstallations(deps) {
       addCandidate(installations, seenRealpaths, d, candidate, "PATH", "cli");
     }
   }
+  for (const candidate of openChamberCliCandidates(d)) {
+    if (d.isExecutable(candidate)) {
+      addCandidate(installations, seenRealpaths, d, candidate, "openchamber", "cli");
+    }
+  }
   for (const appId of OPENCODE_DESKTOP_APP_IDS) {
     const marker = join11(desktopUserDataDir(d, appId), OPENCODE_DESKTOP_SETTINGS_FILE);
     if (d.exists(marker)) {
@@ -13171,6 +13185,17 @@ function describeOpenCodeInstallations(installations, deps = {}) {
     active: index === 0
   }));
 }
+function selectOpenCodeStoreHost(reports, generationOf) {
+  const active = reports[0];
+  if (!active)
+    return null;
+  const hasVersion = (report) => /\d/.test(report.version);
+  if (!hasVersion(active) || generationOf(active.version) === "v2") {
+    return { host: active, shadowed: false };
+  }
+  const v2 = reports.find((report) => report.kind === "cli" && hasVersion(report) && generationOf(report.version) === "v2");
+  return v2 ? { host: v2, shadowed: true } : { host: active, shadowed: false };
+}
 function getAvailableModels2(binary) {
   const output = runOpenCode(["models"], binary);
   if (output === null)
@@ -15523,6 +15548,12 @@ var init_redaction = __esm(() => {
 // ../plugin/src/shared/logger.ts
 import * as fs from "node:fs";
 import * as path2 from "node:path";
+function boundBuffer() {
+  while (bufferedBytes > MAX_BUFFERED_BYTES && buffer.length > 0) {
+    bufferedBytes -= Buffer.byteLength(buffer.shift() ?? "");
+    droppedLines++;
+  }
+}
 function recordSwallowedWrite(error) {
   try {
     swallowedWriteCount++;
@@ -15605,12 +15636,12 @@ function flush() {
     clearTimeout(flushTimer);
     flushTimer = null;
   }
-  if (buffer.length === 0)
+  if (buffer.length === 0 && droppedLines === 0)
     return;
-  const bufferedData = buffer.join("");
-  buffer = [];
+  const notice = droppedLines ? `[${new Date().toISOString()}] [magic-context][global] logger dropped ${droppedLines} ${droppedLines === 1 ? "line" : "lines"}: buffer exceeded ${MAX_BUFFERED_BYTES} bytes while writes were pending
+` : "";
   try {
-    const data = capLogData(bufferedData);
+    const data = capLogData(notice + buffer.join(""));
     const logFile = getMagicContextLogPath();
     ensureDir4(logFile);
     let currentSize = getCurrentLogSize(logFile);
@@ -15620,6 +15651,9 @@ function flush() {
       currentSize = 0;
     }
     fs.appendFileSync(logFile, data, { encoding: "utf8", mode: 384 });
+    buffer = [];
+    bufferedBytes = 0;
+    droppedLines = 0;
     activeLogFile = logFile;
     activeLogSize = currentSize + dataSize;
     flushesSinceSizeCheck++;
@@ -15628,6 +15662,7 @@ function flush() {
     activeLogSize = null;
     flushesSinceSizeCheck = 0;
     recordSwallowedWrite(error);
+    boundBuffer();
   }
 }
 function scheduleFlush() {
@@ -15645,8 +15680,11 @@ function log3(message, data) {
     const timestamp = new Date().toISOString();
     const serialized = data === undefined ? "" : data instanceof Error ? ` ${sanitizeDiagnosticText(`${data.message}${data.stack ? `
 ${data.stack}` : ""}`)}` : ` ${JSON.stringify(sanitizeConfigValue(data))}`;
-    buffer.push(`[${timestamp}] ${sanitizeDiagnosticText(message)}${serialized}
-`);
+    const line = `[${timestamp}] ${sanitizeDiagnosticText(message)}${serialized}
+`;
+    buffer.push(line);
+    bufferedBytes += Buffer.byteLength(line);
+    boundBuffer();
     if (buffer.length >= BUFFER_SIZE_LIMIT) {
       flush();
     } else {
@@ -15654,11 +15692,12 @@ ${data.stack}` : ""}`)}` : ` ${JSON.stringify(sanitizeConfigValue(data))}`;
     }
   } catch {}
 }
-var isTestEnv = false, buffer, flushTimer = null, FLUSH_INTERVAL_MS = 500, BUFFER_SIZE_LIMIT = 50, MAX_LOG_FILE_BYTES, SIZE_CHECK_INTERVAL_FLUSHES = 64, activeLogFile = null, activeLogSize = null, flushesSinceSizeCheck = 0, swallowedWriteCount = 0, lastErrorMessage = null, lastErrorTime = null;
+var isTestEnv = false, buffer, flushTimer = null, FLUSH_INTERVAL_MS = 500, BUFFER_SIZE_LIMIT = 50, MAX_BUFFERED_BYTES, bufferedBytes = 0, droppedLines = 0, MAX_LOG_FILE_BYTES, SIZE_CHECK_INTERVAL_FLUSHES = 64, activeLogFile = null, activeLogSize = null, flushesSinceSizeCheck = 0, swallowedWriteCount = 0, lastErrorMessage = null, lastErrorTime = null;
 var init_logger = __esm(() => {
   init_data_path();
   init_redaction();
   buffer = [];
+  MAX_BUFFERED_BYTES = 1024 * 1024;
   MAX_LOG_FILE_BYTES = 32 * 1024 * 1024;
   if (!isTestEnv) {
     process.on("exit", flush);
@@ -21370,6 +21409,7 @@ var init_magic_context = __esm(() => {
     maxTokens: true
   });
   DreamerConfigSchema = AgentMetadataSchema.extend({
+    runner: _enum(["broca", "host"]).optional().describe(`Which side runs the dreamer completions the Rust module routes (classify-memories) in Rust transform mode: "host" runs them on this process's carrier, "broca" routes them to the Broca module. When unset, historian.runner applies, and when that is unset too the harness decides the same way it does for the historian. User-level config only.`),
     opencode: DreamerOpenCodeHarnessBlockSchema.optional(),
     pi: DreamerPiHarnessBlockSchema.optional(),
     omp: DreamerOmpHarnessBlockSchema.optional(),
@@ -21380,12 +21420,16 @@ var init_magic_context = __esm(() => {
     opencode: OpenCodeHarnessBlockSchema.optional(),
     pi: PiHarnessBlockSchema.optional(),
     omp: OmpHarnessBlockSchema.optional(),
+    runner: _enum(["broca", "host"]).optional().describe('Which side runs the historian completion in Rust transform mode: "host" queues it for this process to run on the configured historian model, "broca" routes it to the Broca module. When unset the harness decides: OpenCode 1 and OpenCode 2 use "host", Claude Code (through the Thalamus gateway, which has no host to run a completion) uses "broca". User-level config only — it decides whose provider account pays for the call.'),
+    host_runner: object({
+      enabled: boolean2().optional().describe("Whether this process answers historian runs queued for a claimant (default true). Setting it to false stops the pull loop without changing historian.runner, so an operator can take one machine out of the lane and leave the queued runs for another claimant or for the runner setting to be changed deliberately.")
+    }).optional().describe("Controls for this process's historian pull loop, which answers runs the Rust module queues for the host runner (`historian.runner: \"host\"`, or unset on OpenCode 1 and OpenCode 2). User-level config only — it decides whether this machine's provider account is spent on folds."),
     two_pass: boolean2().default(false).describe("Run a second editor pass over historian output to clean low-signal U: lines and cross-compartment duplicates. Adds ~1 extra API call and ~1.3x cost per historian run. Useful for models without extended thinking support. (default: false)"),
     disallowed_tools: array(_enum(["*", "read", "aft_outline", "aft_zoom", "aft_search"])).default([]).describe(`OpenCode only. Tools to REMOVE from the historian's default allow-list [read, aft_outline, aft_zoom, aft_search]. Applies to both historian and historian-editor agents. Use ["*"] to strip all tool definitions from the model request — this prevents weak instruction-following models (e.g. mistral-small-latest) from entering tool-calling loops. Individual tool names remove just that tool. Note: a user-supplied historian.permission override can re-allow a tool that disallowed_tools removed — disallowed_tools sets the baseline, permission overrides take precedence. (default: [])`)
   }).optional();
   EmbeddingFallbackProviderSchema = _enum(["local", "openai-compatible", "off"]);
   BaseEmbeddingConfigSchema = object({
-    provider: _enum(["local", "openai-compatible", "off", "synapse"]).default("local").describe("Embedding provider. 'local' uses Xenova/all-MiniLM-L6-v2, 'openai-compatible' requires endpoint and model, 'synapse' uses the certified local Synapse lane with an explicit fallback provider, and 'off' disables embeddings."),
+    provider: _enum(["local", "openai-compatible", "off", "synapse"]).default("local").describe("Embedding provider. 'local' uses Xenova/all-MiniLM-L6-v2, 'openai-compatible' requires endpoint and model, 'synapse' uses the certified local Synapse lane with an explicit fallback provider, and 'off' disables embeddings. Session history is embedded for semantic ctx_search whenever the provider is not 'off', regardless of memory.enabled; memories are embedded only while memory.enabled is true."),
     fallback_provider: EmbeddingFallbackProviderSchema.optional().describe("Fallback provider for the Synapse lane. Required when provider is 'synapse'; local, openai-compatible, and off are valid."),
     model: string2().optional().describe("Embedding model name. Required for openai-compatible, ignored for local."),
     endpoint: string2().optional().describe("API endpoint URL. Required when provider is openai-compatible."),
@@ -21497,7 +21541,7 @@ var init_magic_context = __esm(() => {
     smart_notes: object({
       retina_handoff: boolean2().default(false).describe("When true, dreamer skips smart notes whose surface conditions compiled to retina provider configs at authoring time. Default false keeps both paths active until the retina consumer is deployed.")
     }).default({ retina_handoff: false }).describe("Smart-note ownership transition controls."),
-    cache_ttl: union([string2(), object({ default: string2() }).catchall(string2())]).default("5m").describe(`How long Magic Context assumes the provider's cached prefix stays valid. This is MC's own deferral gate — it does not change the provider's actual cache lifetime. String (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "provider/model": "1h", "provider/*": "never" }); keys resolve most-specific first (exact provider/model, bare model ID, shorter dash-prefixes, then the provider/* wildcard, then default). Set to "never" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body).`),
+    cache_ttl: union([string2(), object({ default: string2() }).catchall(string2())]).default("5m").describe(`How long Magic Context assumes the provider's cached prefix stays valid. This is MC's own deferral gate — it does not change the provider's actual cache lifetime. String (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "provider/model": "1h", "provider/*": "never" }); keys resolve most-specific first (exact provider/model, bare model ID, shorter dash-prefixes, then the provider/* wildcard). Explicit per-model entries win; otherwise GPT-5.6 and later (including gpt-6*, through any provider prefix) use a built-in 30m lifetime before the object default or 5m fallback. An unset or global "5m" opts into built-in defaults; any other global string is an explicit policy and wins. Policy is frozen per session, including across restarts; a model switch resolves against that frozen policy. /ctx-status shows the effective value and source. OpenAI documents at least 30 minutes since the latest write or reuse: https://developers.openai.com/api/docs/guides/prompt-caching (Cache lifetime and Summary of model differences). Set to "never" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body).`),
     prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe("Prompt-surface presets: default is full; models use bare model IDs, provider/model, or provider/* routing keys. Guidance and tool-description overrides are user-level only. OpenCode 1.x, Pi, and OMP register tool descriptions once per process (they follow the default preset). OpenCode 2 rewrites the five ctx_* descriptions per request from the draft model."),
     output_reserve: union([
       number2().min(0),
@@ -21556,9 +21600,9 @@ var init_magic_context = __esm(() => {
       enabled: boolean2().default(true).describe("When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, and /ctx-flush refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.")
     }).default({ enabled: true }).describe("Compaction-off mode gate. Default true (MC manages the context window as today). Set compaction.enabled=false to keep the knowledge layer while letting native compaction (or nothing) own the window. Boot-resolved; requires a restart to change."),
     todowrite: object({
-      enabled: boolean2().default(true).describe("Pi only: register Magic Context's todowrite task-list tool. Disable if you use your own todo extension. OpenCode ships its own built-in todowrite; this setting has no effect there."),
+      enabled: boolean2().default(false).describe("Pi only: off by default. Set todowrite.enabled=true to register Magic Context's todowrite task-list tool and /todos command. OpenCode ships its own built-in todowrite; this setting has no effect there."),
       overlay: boolean2().default(true).describe("Pi only: show the persistent todo overlay above the editor while tasks are active.")
-    }).default({ enabled: true, overlay: true }).describe("Pi-only todowrite tool and overlay controls. Pi registers tools and widgets at extension boot, so changing this after /cd requires /reload or restart."),
+    }).default({ enabled: false, overlay: true }).describe("Pi-only todowrite tool and overlay controls. Pi registers tools and widgets at extension boot, so changing this after /cd requires /reload or restart."),
     pi: PiConfigSchema.describe("Pi-only child-process extension controls. This setting is user-level only; project configuration cannot choose which extensions a user's subagent children load."),
     smart_drops: boolean2().default(false).describe("Content-aware reclaim of provably-superseded tool output, layered on the existing execute-pass auto-drop. When on: superseded todowrite (keep newest 1), spent ctx_reduce (keep newest 3), and zero-value meta (bash_status, bash_kill, ctx_note read/dismiss) outputs are dropped; older edits to a file are compressed to a filePath-preserving marker while the newest edit per file stays full. Only acts on passes already busting the cache, so it never originates a cache bust. Honors the protected-tag reserve. Experimental: opt-in, default off until cache stability is proven; when off the wire is byte-identical to the positional-only reclaim. Requires a restart."),
     caveman_text_compression: object({
@@ -21566,7 +21610,7 @@ var init_magic_context = __esm(() => {
       min_chars: number2().min(100).max(1e4).default(500).describe("Text parts shorter than this (characters) stay untouched. Min 100, max 10000. Default: 500.")
     }).default({ enabled: false, min_chars: 500 }).describe("Age-tier caveman compression for long user/assistant text parts. Active for primary sessions when enabled; never for subagents. Oldest 20% of eligible tags (outside protected tail) go to ultra, next 20% to full, next 20% to lite, newest 40% untouched. Graduated from experimental.caveman_text_compression; opt-in, default off (lossy)."),
     memory: object({
-      enabled: boolean2().default(true).describe("Enable cross-session memory (default: true)"),
+      enabled: boolean2().default(true).describe("Enable cross-session memory (default: true). Does not affect history embedding or semantic ctx_search over session history; set embedding.provider to 'off' to stop all embedding."),
       injection_budget_tokens: number2().min(500).max(20000).default(4000).describe("Token budget for memory injection on session start (min: 500, max: 20000, default: 4000)"),
       auto_promote: boolean2().default(true).describe("Automatically promote eligible session facts into memory (default: true)"),
       retrieval_count_promotion_threshold: number2().min(1).default(3).describe("retrieval_count threshold for promoting memory to permanent status (min: 1, default: 3)"),
@@ -21607,10 +21651,12 @@ var init_magic_context = __esm(() => {
     "historian.omp.fallback_models",
     "historian.omp.thinking_level",
     "historian.two_pass",
+    "historian.maxTokens",
     "historian_timeout_ms",
     "commit_cluster_trigger.enabled",
     "commit_cluster_trigger.min_clusters",
     "memory.auto_promote",
+    "dreamer.maxTokens",
     "dreamer.opencode.model",
     "dreamer.opencode.fallback_models",
     "dreamer.opencode.variant",
@@ -22015,6 +22061,11 @@ function stripUnsafeProjectConfigFields(projectRaw) {
       warnings.push(`Ignoring ${removed.map((path) => `historian.${path}`).join(", ")} from project config ` + "(security: historian model selection is user-level only; a repository cannot force extra compaction cost).");
     }
   }
+  const dreamer = projectRaw.dreamer;
+  if (isPlainObject3(dreamer) && "runner" in dreamer) {
+    delete dreamer.runner;
+    warnings.push("Ignoring dreamer.runner from project config (security: which process and provider account run dreamer completions is a user-level setting).");
+  }
   const mural = projectRaw.mural;
   if (isPlainObject3(mural) && "model" in mural) {
     delete mural.model;
@@ -22196,7 +22247,11 @@ var init_project_security = __esm(() => {
   init_magic_context();
   HIDDEN_AGENT_KEYS = ["historian", "dreamer"];
   HARNESS_KEYS = PER_HARNESS_MODEL_KEYS;
-  HISTORIAN_USER_ONLY_FIELDS = PER_HARNESS_MIGRATION_INVENTORY.historian.migrated_execution;
+  HISTORIAN_USER_ONLY_FIELDS = [
+    ...PER_HARNESS_MIGRATION_INVENTORY.historian.migrated_execution,
+    "runner",
+    "host_runner"
+  ];
   PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"];
   AGENT_ESCALATION_FIELDS = ["prompt", "permission", "tools"];
   EMBEDDING_USER_ONLY_FIELDS = [
@@ -22511,6 +22566,25 @@ function redactConfigValue(value) {
 function formatProtectedTokensBelowMinWarning(value) {
   return `protected_tokens is a token floor (minimum ${PROTECTED_TOKENS_MIN}, default derived from the context window); ${value} looks like the old protected_tags count. Remove the key to use the default, or set a token count such as 16000.`;
 }
+function misplacedAgentModelWarnings(rawConfig) {
+  const warnings = [];
+  for (const agent of ["historian", "dreamer"]) {
+    const block = rawConfig[agent];
+    if (!block || typeof block !== "object" || Array.isArray(block))
+      continue;
+    const record = block;
+    if (!Object.hasOwn(record, "model"))
+      continue;
+    const harnessWithModel = MODEL_HARNESS_BLOCKS.find((harness) => {
+      const sub = record[harness];
+      return sub !== null && typeof sub === "object" && !Array.isArray(sub) && Object.hasOwn(sub, "model");
+    });
+    if (harnessWithModel)
+      continue;
+    warnings.push(`${agent}.model is not read: the ${agent} model is resolved per harness, so it has to be ${agent}.opencode.model (OpenCode 1 and 2), ${agent}.pi.model, or ${agent}.omp.model. As written the ${agent} resolves to no models and never runs.`);
+  }
+  return warnings;
+}
 function warnProtectedTagsDeprecationOnce() {
   if (!warnedProtectedTagsDeprecation) {
     warnedProtectedTagsDeprecation = true;
@@ -22524,6 +22598,7 @@ function parsePluginConfig(rawConfig, recoveredTopLevelKeys = []) {
     warnProtectedTagsDeprecationOnce();
     preMigrationWarnings.push("protected_tags is deprecated and ignored; use protected_tokens instead.");
   }
+  preMigrationWarnings.push(...misplacedAgentModelWarnings(rawConfig));
   const migratedExperimental = migrateLegacyExperimental(configWithoutRemovedAgent, preMigrationWarnings);
   const migratedDreamer = migrateDreamerV2(migratedExperimental, preMigrationWarnings);
   const migrated = migrateLegacyAgentEnabledInMemory(migratedDreamer, preMigrationWarnings);
@@ -22804,7 +22879,7 @@ function loadPluginConfigDetailed(directory, applyRuntimeGlobals = true) {
     cacheTtlConfigured
   };
 }
-var warnedProtectedTagsDeprecation = false;
+var warnedProtectedTagsDeprecation = false, MODEL_HARNESS_BLOCKS;
 var init_config = __esm(() => {
   init_config_diagnostics();
   init_jsonc_parser();
@@ -22819,6 +22894,7 @@ var init_config = __esm(() => {
   init_removed_agent_config();
   init_magic_context();
   init_variable();
+  MODEL_HARNESS_BLOCKS = ["opencode", "pi", "omp"];
 });
 
 // ../plugin/src/shared/opencode-config-dir.ts
@@ -26747,232 +26823,523 @@ function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// ../plugin/src/hooks/magic-context/module-transport.ts
-import { realpathSync as realpathSync3 } from "node:fs";
-import { join as join17 } from "node:path";
-function getDefaultSubcConnectionFile() {
-  return join17(getDataDir(), "cortexkit", "run", "subc-connection.json");
-}
-function errorChainSome(error, predicate) {
-  let current = error;
-  const seen = new Set;
-  while (isRecord3(current) && !seen.has(current)) {
-    seen.add(current);
-    if (predicate(current))
-      return true;
-    current = current.cause;
-  }
-  return false;
-}
-function isStaleOrDeadRouteFailure(error) {
-  return errorChainSome(error, (current) => {
-    const code = typeof current.code === "string" ? current.code : "";
-    const name = typeof current.name === "string" ? current.name : "";
-    const message = typeof current.message === "string" ? current.message : "";
-    return [
-      "stale_route_handle",
-      "route_closed",
-      "unknown_channel",
-      "unrecognized_channel",
-      "route_gone"
-    ].includes(code) || name === "StaleRouteHandleError" || /route handle \(\d+,\s*\d+\) is not live on the current connection/i.test(message) || /\b(?:unknown|unrecognized) channel\b/i.test(message);
-  });
-}
-function isDeadlineFailure(error) {
-  if (error instanceof SocketTimeoutError)
-    return true;
-  return errorChainSome(error, (current) => {
-    const code = typeof current.code === "string" ? current.code : "";
-    return ["ETIMEDOUT", "request_deadline", "deadline_exceeded_no_drop_observed"].includes(code);
-  });
-}
-function isConnectionFailure(error) {
-  if (error instanceof SocketClosedError || error instanceof SocketTimeoutError || error instanceof StaleRouteHandleError || isConsumerReconnectTransient(error) || isStaleOrDeadRouteFailure(error)) {
-    return true;
-  }
-  return errorChainSome(error, (current) => {
-    const code = typeof current.code === "string" ? current.code : "";
-    const message = typeof current.message === "string" ? current.message : "";
-    return [
-      "ENOENT",
-      "ECONNREFUSED",
-      "ECONNRESET",
-      "EPIPE",
-      "ETIMEDOUT",
-      "request_deadline",
-      "deadline_exceeded_no_drop_observed",
-      "connection_dropped",
-      "SUBC_CONNECTION_BACKOFF"
-    ].includes(code) || /\bclient closed\b|\bconnection closed\b|\bclosed the connection\b/i.test(message);
-  });
-}
-function routeOpenWithoutAmbientConsumerIdentity(client, target, identity, options = {}) {
-  return client.routeOpen(target, identity, {
-    ...options,
-    consumerIdentity: null
-  });
+// ../plugin/src/shared/user-facing-codes.ts
+function userFacingFailureCode(key) {
+  return USER_FACING_FAILURES[key].code;
 }
-
-class SubcModuleTransport {
-  connectionFile;
-  moduleId;
-  requestTimeoutMs;
-  routeSessionPrefix;
-  client = null;
-  routes = new Map;
-  routeOpenings = new Map;
-  canonicalRootCache = new Map;
-  sessionLanes = new Map;
-  queuedLaneWaiters = 0;
-  wrapupSessions = new Map;
-  nextProbeMs = 0;
-  connectionPromise = null;
-  authorityProjectRoot = "";
-  authorityBindRoot = "";
-  backoffMs = CONNECT_BACKOFF_INITIAL_MS;
-  connectionGeneration = 0;
-  stateSyncCapabilityCache = null;
-  getCachedStateSyncCapabilities() {
-    const cached = this.stateSyncCapabilityCache;
-    if (!cached || cached.generation !== this.connectionGeneration)
-      return;
-    return cached.capabilities;
-  }
-  invalidateStateSyncCapabilities() {
-    this.stateSyncCapabilityCache = null;
-  }
-  async stateSyncCapabilities(args) {
-    const cached = this.getCachedStateSyncCapabilities();
-    if (cached)
-      return cached;
-    const response = await this.call({
-      sessionId: args.sessionId,
-      projectRoot: args.projectRoot,
-      method: "session.status",
-      body: { method: "session.status", v: 1, session_id: args.sessionId }
-    });
-    const raw = isRecord3(response) ? response : {};
-    const value = isRecord3(raw.result) ? raw.result : raw;
-    const epochs = isRecord3(value.epochs) ? value.epochs : {};
-    const capabilities = {
-      state_sync_deltas: epochs.state_sync_deltas === true,
-      ...epochs.state_sync_resume === true ? { state_sync_resume: true } : {}
-    };
-    this.stateSyncCapabilityCache = { generation: this.connectionGeneration, capabilities };
-    return capabilities;
-  }
-  constructor(connectionFile, moduleId = DEFAULT_MODULE_ID, requestTimeoutMs = MODULE_SEND_TIMEOUT_MS, routeSessionPrefix = "") {
-    this.connectionFile = connectionFile;
-    this.moduleId = moduleId;
-    this.requestTimeoutMs = requestTimeoutMs;
-    this.routeSessionPrefix = routeSessionPrefix;
-  }
-  deadlineError(detail) {
-    const error = new Error(`module transport deadline expired ${detail}`);
-    error.code = "ETIMEDOUT";
-    return error;
-  }
-  laneTimeoutError() {
-    return this.deadlineError("while queued");
-  }
-  connectionChangedError(detail) {
-    const error = new Error(detail);
-    error.code = "ECONNRESET";
-    return error;
-  }
-  async beforeDeadline(operation, deadlineMs, detail) {
-    operation.catch(() => {});
-    const remainingMs = deadlineMs - Date.now();
-    if (remainingMs <= 0)
-      throw this.deadlineError(detail);
-    let timer;
-    try {
-      return await Promise.race([
-        operation,
-        new Promise((_resolve, reject) => {
-          timer = setTimeout(() => reject(this.deadlineError(detail)), remainingMs);
-        })
-      ]);
-    } finally {
-      if (timer)
-        clearTimeout(timer);
-    }
-  }
-  cleanupLane(sessionId, lane) {
-    if (!lane.active && lane.waiters.length === 0 && this.sessionLanes.get(sessionId) === lane) {
-      this.sessionLanes.delete(sessionId);
-    }
-  }
-  laneRelease(sessionId, lane) {
-    let released = false;
-    return () => {
-      if (released)
-        return;
-      released = true;
-      lane.active = false;
-      this.dispatchNextLaneWaiter(sessionId, lane);
-    };
-  }
-  dispatchNextLaneWaiter(sessionId, lane) {
-    if (lane.active)
-      return;
-    while (lane.waiters.length > 0) {
-      const waiter = lane.waiters.shift();
-      if (!waiter)
-        continue;
-      this.queuedLaneWaiters = Math.max(0, this.queuedLaneWaiters - 1);
-      if (waiter.settled)
-        continue;
-      waiter.settled = true;
-      clearTimeout(waiter.timer);
-      waiter.signal?.removeEventListener("abort", waiter.onAbort);
-      if (waiter.signal?.aborted) {
-        waiter.reject(waiter.signal.reason ?? new Error("module transport call aborted"));
-        continue;
-      }
-      if (waiter.deadlineMs - Date.now() < SERIAL_LANE_MIN_REMAINING_MS) {
-        waiter.reject(this.laneTimeoutError());
-        continue;
-      }
-      lane.active = true;
-      waiter.resolve(this.laneRelease(sessionId, lane));
-      return;
-    }
-    this.cleanupLane(sessionId, lane);
-  }
-  queueFullError() {
-    const error = new Error("module transport queue is full");
-    error.code = "EBUSY";
-    return error;
-  }
-  acquireCorrectnessLane(sessionId, signal, deadlineMs) {
-    if (signal?.aborted) {
-      return Promise.reject(signal.reason ?? new Error("module transport call aborted"));
-    }
-    if (deadlineMs - Date.now() < SERIAL_LANE_MIN_REMAINING_MS) {
-      return Promise.reject(this.laneTimeoutError());
-    }
-    const lane = this.sessionLanes.get(sessionId) ?? { active: false, waiters: [] };
-    this.sessionLanes.set(sessionId, lane);
-    if (!lane.active && lane.waiters.length === 0) {
-      lane.active = true;
-      return Promise.resolve(this.laneRelease(sessionId, lane));
-    }
-    if (this.queuedLaneWaiters >= SERIAL_LANE_MAX_WAITERS || lane.waiters.length >= SERIAL_LANE_MAX_WAITERS_PER_SESSION) {
-      return Promise.reject(this.queueFullError());
-    }
-    return new Promise((resolve, reject) => {
-      const waiter = {};
-      const removeAndReject = (error) => {
-        if (waiter.settled)
-          return;
-        waiter.settled = true;
-        clearTimeout(waiter.timer);
-        signal?.removeEventListener("abort", waiter.onAbort);
-        const index = lane.waiters.indexOf(waiter);
-        if (index >= 0) {
-          lane.waiters.splice(index, 1);
-          this.queuedLaneWaiters = Math.max(0, this.queuedLaneWaiters - 1);
+var USER_FACING_FAILURES;
+var init_user_facing_codes = __esm(() => {
+  USER_FACING_FAILURES = {
+    historian_unavailable: {
+      code: "MC-H01",
+      sentence: "History compression could not finish this turn.",
+      action: "It will retry automatically."
+    },
+    hidden_cleanup_unbound: {
+      code: "MC-H02",
+      sentence: "Some finished background sessions could not be removed from this host.",
+      action: "They are removed automatically the next time Magic Context runs inside a registered OpenCode service."
+    },
+    historian_saved_history_misaligned: {
+      code: "MC-H03",
+      sentence: "History compression is paused because this session's saved summaries no longer line up with its messages.",
+      action: "Run /ctx-recomp to rebuild them."
+    },
+    recomp_unavailable: {
+      code: "MC-R01",
+      sentence: "History compression could not be rebuilt.",
+      action: "Run /ctx-recomp again."
+    },
+    dream_provider_timeout: {
+      code: "MC-D01",
+      sentence: "Memory maintenance took too long to respond.",
+      action: "Run /ctx-dream again."
+    },
+    dream_provider_error: {
+      code: "MC-D02",
+      sentence: "Memory maintenance could not reach its model.",
+      action: "Check the model connection, then run /ctx-dream again."
+    },
+    dream_step_limit: {
+      code: "MC-D10",
+      sentence: "Memory maintenance stopped at its hidden agent step limit.",
+      action: "This task needs less work per run; changing the model connection will not help."
+    },
+    dream_empty_completion: {
+      code: "MC-D03",
+      sentence: "Memory maintenance received no usable response.",
+      action: "Run /ctx-dream again."
+    },
+    dream_no_models: {
+      code: "MC-D04",
+      sentence: "Memory maintenance has no model available.",
+      action: "Check the model settings, then run /ctx-dream again."
+    },
+    dream_child_aborted: {
+      code: "MC-D05",
+      sentence: "Memory maintenance was interrupted.",
+      action: "Run /ctx-dream again."
+    },
+    dream_parse_failed: {
+      code: "MC-D06",
+      sentence: "Memory maintenance could not use the model response.",
+      action: "Run /ctx-dream again."
+    },
+    dream_unknown: {
+      code: "MC-D07",
+      sentence: "Memory maintenance could not finish.",
+      action: "Run /ctx-dream again."
+    },
+    dreamer_tick_blocked: {
+      code: "MC-D09",
+      sentence: "Background maintenance is not running: its last pass stopped before it reached the scheduled tasks.",
+      action: "It is retried automatically; if it keeps happening, check the Magic Context log for the stage that stopped and run `npx @cortexkit/magic-context doctor`."
+    },
+    dream_task_needs_tool_loop: {
+      code: "MC-D08",
+      sentence: "Some memory maintenance tasks need a tool loop this host does not provide.",
+      action: "The remaining tasks still run; the listed ones are skipped on this host."
+    },
+    embedding_substitution_rejected: {
+      code: "MC-E01",
+      sentence: "Search indexing could not use the selected model.",
+      action: "Check the embedding model setting, then run /ctx-embed start again."
+    },
+    embedding_http_error: {
+      code: "MC-E02",
+      sentence: "The search indexing provider refused the request.",
+      action: "Check the provider connection and credentials, then run /ctx-embed start again."
+    },
+    embedding_transport_error: {
+      code: "MC-E03",
+      sentence: "Search indexing could not reach its provider.",
+      action: "Check the connection, then run /ctx-embed start again."
+    },
+    embedding_invalid_envelope: {
+      code: "MC-E04",
+      sentence: "Search indexing received an unsupported response.",
+      action: "Check the embedding endpoint, then run /ctx-embed start again."
+    },
+    embedding_empty_result: {
+      code: "MC-E05",
+      sentence: "Search indexing received no usable result.",
+      action: "Run /ctx-embed start again."
+    },
+    embedding_certification_refusal: {
+      code: "MC-E06",
+      sentence: "Search indexing is not ready for this provider.",
+      action: "Finish the provider setup, or set a fallback provider in the embedding settings, then run /ctx-embed start again."
+    },
+    embedding_credential_required: {
+      code: "MC-E07",
+      sentence: "Search indexing needs provider credentials.",
+      action: "Sign in to the provider, then run /ctx-embed start again."
+    },
+    embedding_local_binding_missing: {
+      code: "MC-E08",
+      sentence: "Local search indexing is unavailable on this system.",
+      action: "Run `npx @cortexkit/magic-context doctor`, then retry."
+    },
+    embedding_local_fs_unavailable: {
+      code: "MC-E09",
+      sentence: "Local search indexing cannot save its model files.",
+      action: "Update or reinstall Magic Context, then retry."
+    },
+    embedding_local_download_failure: {
+      code: "MC-E10",
+      sentence: "Local search indexing could not download its model.",
+      action: "Check the network connection, then retry."
+    },
+    embedding_local_runtime_error: {
+      code: "MC-E11",
+      sentence: "Local search indexing could not start.",
+      action: "Run `npx @cortexkit/magic-context doctor`, then retry."
+    },
+    embedding_unavailable: {
+      code: "MC-E12",
+      sentence: "Search indexing could not finish.",
+      action: "Run /ctx-embed start again."
+    },
+    status_unavailable: {
+      code: "MC-S01",
+      sentence: "Magic Context status is temporarily unavailable.",
+      action: "Retry /ctx-status in a moment."
+    },
+    transform_update_failed: {
+      code: "MC-S02",
+      sentence: "The last context update did not finish.",
+      action: "Send another message to retry."
+    },
+    configuration_warning: {
+      code: "MC-S03",
+      sentence: "Some configuration settings could not be applied.",
+      action: "Fix the configuration warning shown in /ctx-status, then restart."
+    },
+    status_log_unavailable: {
+      code: "MC-S04",
+      sentence: "Some diagnostic details could not be saved.",
+      action: "Retry /ctx-status in a moment."
+    },
+    memory_writes_paused: {
+      code: "MC-C01",
+      sentence: "Memory writes are paused while the engine syncs.",
+      action: "Retry in a moment."
+    },
+    memory_access_unavailable: {
+      code: "MC-C02",
+      sentence: "Memory access is temporarily unavailable.",
+      action: "Retry in a moment."
+    },
+    note_changes_paused: {
+      code: "MC-C03",
+      sentence: "Note changes are paused while the engine syncs.",
+      action: "Retry in a moment."
+    },
+    note_access_unavailable: {
+      code: "MC-C04",
+      sentence: "Notes are temporarily unavailable.",
+      action: "Retry in a moment."
+    },
+    context_cleanup_paused: {
+      code: "MC-C05",
+      sentence: "Context cleanup is paused while the engine syncs.",
+      action: "Retry in a moment."
+    },
+    partial_history_unavailable: {
+      code: "MC-C06",
+      sentence: "Partial history compression is not available in the current mode.",
+      action: "Run /ctx-recomp without a range."
+    },
+    smart_note_conditions_unavailable: {
+      code: "MC-C08",
+      sentence: "Conditional notes are not available in the current mode.",
+      action: "Save a regular note without a condition."
+    },
+    history_compression_paused: {
+      code: "MC-C09",
+      sentence: "History compression is paused while the engine syncs.",
+      action: "Retry in a moment."
+    },
+    history_compression_needs_message: {
+      code: "MC-C12",
+      sentence: "History compression has not seen this session since Magic Context reconnected.",
+      action: "Send a message in this session first, then run /ctx-wrapup again."
+    },
+    context_service_unavailable: {
+      code: "MC-C10",
+      sentence: "Magic Context is temporarily unavailable.",
+      action: "Retry in a moment."
+    },
+    store_ahead_of_binary: {
+      code: "MC-C13",
+      sentence: "Magic Context refused to start: its store (store.db) was migrated by a newer ck-mc build than the one running.",
+      action: "Update ck-mc, or roll back by restoring ck-mc together with context.db and store.db from the same backup."
+    },
+    compaction_marker_missing: {
+      code: "MC-C11",
+      sentence: "The history boundary marker is missing from the OpenCode store, so requests carry the full session.",
+      action: "It is retried on every message; if this persists, run `/ctx-flush`."
+    },
+    memory_mirror_stalled: {
+      code: "MC-M01",
+      sentence: "Memory synchronization stopped before the host mirror caught up.",
+      action: "Send another message to resume it, or run `ck doctor drain-authority`."
+    },
+    memory_authority_mismatch: {
+      code: "MC-M02",
+      sentence: "Memory authority is inconsistent between the host and module.",
+      action: "Run `ck doctor drain-authority` before changing Rust mode."
+    },
+    dreamer_task_failing: {
+      code: "MC-S05",
+      sentence: "A background maintenance task keeps failing on its schedule.",
+      action: "Check the Magic Context log for the failing task and its error."
+    }
+  };
+});
+
+// ../plugin/src/hooks/magic-context/store-ahead-refusal.ts
+function renderStoreAheadOfBinaryRefusal(versions) {
+  const failure = USER_FACING_FAILURES.store_ahead_of_binary;
+  const sentence = versions ? `Magic Context refused to start: its store (store.db) is at schema v${versions.dbVersion} but this ck-mc build only knows up to v${versions.binaryMax}.` : failure.sentence;
+  return `${sentence} ${failure.action} (${failure.code})`;
+}
+function isRecord4(value) {
+  return value !== null && typeof value === "object";
+}
+function nonNegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function versionsFromDetail(detail) {
+  if (!isRecord4(detail))
+    return null;
+  const dbVersion = nonNegativeInteger(detail.db_version);
+  const binaryMax = nonNegativeInteger(detail.binary_max);
+  return dbVersion !== null && binaryMax !== null ? { dbVersion, binaryMax } : null;
+}
+function versionsFromMessage(message) {
+  if (typeof message !== "string")
+    return null;
+  const match = /db_version=(\d+) binary_max=(\d+)/.exec(message) ?? /schema v(\d+) but this ck-mc build only knows up to v(\d+)/.exec(message);
+  if (!match)
+    return null;
+  return { dbVersion: Number(match[1]), binaryMax: Number(match[2]) };
+}
+function storeAheadOfBinaryFailure(error) {
+  let current = error;
+  const seen = new Set;
+  while (isRecord4(current) && !seen.has(current)) {
+    seen.add(current);
+    if (current instanceof StoreAheadOfBinaryError)
+      return current;
+    if (current.code === STORE_AHEAD_OF_BINARY_CODE) {
+      const versions = versionsFromDetail(current.detail) ?? versionsFromMessage(current.message);
+      return new StoreAheadOfBinaryError(versions, { cause: error });
+    }
+    current = current.cause;
+  }
+  return null;
+}
+var STORE_AHEAD_OF_BINARY_CODE = "store_ahead_of_binary", StoreAheadOfBinaryError;
+var init_store_ahead_refusal = __esm(() => {
+  init_user_facing_codes();
+  StoreAheadOfBinaryError = class StoreAheadOfBinaryError extends Error {
+    code = STORE_AHEAD_OF_BINARY_CODE;
+    versions;
+    constructor(versions, options) {
+      super(renderStoreAheadOfBinaryRefusal(versions), options);
+      this.name = "StoreAheadOfBinaryError";
+      this.versions = versions;
+    }
+  };
+});
+
+// ../plugin/src/hooks/magic-context/module-transport.ts
+import { realpathSync as realpathSync3 } from "node:fs";
+import { join as join17 } from "node:path";
+function getDefaultSubcConnectionFile() {
+  return join17(getDataDir(), "cortexkit", "run", "subc-connection.json");
+}
+function errorChainSome(error, predicate) {
+  let current = error;
+  const seen = new Set;
+  while (isRecord3(current) && !seen.has(current)) {
+    seen.add(current);
+    if (predicate(current))
+      return true;
+    current = current.cause;
+  }
+  return false;
+}
+function isStaleOrDeadRouteFailure(error) {
+  return errorChainSome(error, (current) => {
+    const code = typeof current.code === "string" ? current.code : "";
+    const name = typeof current.name === "string" ? current.name : "";
+    const message = typeof current.message === "string" ? current.message : "";
+    return [
+      "stale_route_handle",
+      "route_closed",
+      "unknown_channel",
+      "unrecognized_channel",
+      "route_gone"
+    ].includes(code) || name === "StaleRouteHandleError" || /route handle \(\d+,\s*\d+\) is not live on the current connection/i.test(message) || /\b(?:unknown|unrecognized) channel\b/i.test(message);
+  });
+}
+function isDeadlineFailure(error) {
+  if (error instanceof SocketTimeoutError)
+    return true;
+  return errorChainSome(error, (current) => {
+    const code = typeof current.code === "string" ? current.code : "";
+    return ["ETIMEDOUT", "request_deadline", "deadline_exceeded_no_drop_observed"].includes(code);
+  });
+}
+function isConnectionFailure(error) {
+  if (error instanceof SocketClosedError || error instanceof SocketTimeoutError || error instanceof StaleRouteHandleError || isConsumerReconnectTransient(error) || isStaleOrDeadRouteFailure(error)) {
+    return true;
+  }
+  return errorChainSome(error, (current) => {
+    const code = typeof current.code === "string" ? current.code : "";
+    const message = typeof current.message === "string" ? current.message : "";
+    return [
+      "ENOENT",
+      "ECONNREFUSED",
+      "ECONNRESET",
+      "EPIPE",
+      "ETIMEDOUT",
+      "request_deadline",
+      "deadline_exceeded_no_drop_observed",
+      "connection_dropped",
+      "SUBC_CONNECTION_BACKOFF"
+    ].includes(code) || /\bclient closed\b|\bconnection closed\b|\bclosed the connection\b/i.test(message);
+  });
+}
+function routeOpenWithoutAmbientConsumerIdentity(client, target, identity, options = {}) {
+  return client.routeOpen(target, identity, {
+    ...options,
+    consumerIdentity: null
+  });
+}
+
+class SubcModuleTransport {
+  connectionFile;
+  moduleId;
+  requestTimeoutMs;
+  routeSessionPrefix;
+  client = null;
+  routes = new Map;
+  routeOpenings = new Map;
+  canonicalRootCache = new Map;
+  sessionLanes = new Map;
+  queuedLaneWaiters = 0;
+  wrapupSessions = new Map;
+  nextProbeMs = 0;
+  connectionPromise = null;
+  authorityProjectRoot = "";
+  authorityBindRoot = "";
+  backoffMs = CONNECT_BACKOFF_INITIAL_MS;
+  connectionGeneration = 0;
+  stateSyncCapabilityCache = null;
+  getCachedStateSyncCapabilities() {
+    const cached = this.stateSyncCapabilityCache;
+    if (!cached || cached.generation !== this.connectionGeneration)
+      return;
+    return cached.capabilities;
+  }
+  invalidateStateSyncCapabilities() {
+    this.stateSyncCapabilityCache = null;
+  }
+  async stateSyncCapabilities(args) {
+    const cached = this.getCachedStateSyncCapabilities();
+    if (cached)
+      return cached;
+    const response = await this.call({
+      sessionId: args.sessionId,
+      projectRoot: args.projectRoot,
+      method: "session.status",
+      body: { method: "session.status", v: 1, session_id: args.sessionId }
+    });
+    const raw = isRecord3(response) ? response : {};
+    const value = isRecord3(raw.result) ? raw.result : raw;
+    const epochs = isRecord3(value.epochs) ? value.epochs : {};
+    const capabilities = {
+      state_sync_deltas: epochs.state_sync_deltas === true,
+      ...epochs.state_sync_resume === true ? { state_sync_resume: true } : {}
+    };
+    this.stateSyncCapabilityCache = { generation: this.connectionGeneration, capabilities };
+    return capabilities;
+  }
+  constructor(connectionFile, moduleId = DEFAULT_MODULE_ID, requestTimeoutMs = MODULE_SEND_TIMEOUT_MS, routeSessionPrefix = "") {
+    this.connectionFile = connectionFile;
+    this.moduleId = moduleId;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.routeSessionPrefix = routeSessionPrefix;
+  }
+  deadlineError(detail) {
+    const error = new Error(`module transport deadline expired ${detail}`);
+    error.code = "ETIMEDOUT";
+    return error;
+  }
+  laneTimeoutError() {
+    return this.deadlineError("while queued");
+  }
+  connectionChangedError(detail) {
+    const error = new Error(detail);
+    error.code = "ECONNRESET";
+    return error;
+  }
+  async beforeDeadline(operation, deadlineMs, detail) {
+    operation.catch(() => {});
+    const remainingMs = deadlineMs - Date.now();
+    if (remainingMs <= 0)
+      throw this.deadlineError(detail);
+    let timer;
+    try {
+      return await Promise.race([
+        operation,
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => reject(this.deadlineError(detail)), remainingMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  cleanupLane(sessionId, lane) {
+    if (!lane.active && lane.waiters.length === 0 && this.sessionLanes.get(sessionId) === lane) {
+      this.sessionLanes.delete(sessionId);
+    }
+  }
+  laneRelease(sessionId, lane) {
+    let released = false;
+    return () => {
+      if (released)
+        return;
+      released = true;
+      lane.active = false;
+      this.dispatchNextLaneWaiter(sessionId, lane);
+    };
+  }
+  dispatchNextLaneWaiter(sessionId, lane) {
+    if (lane.active)
+      return;
+    while (lane.waiters.length > 0) {
+      const waiter = lane.waiters.shift();
+      if (!waiter)
+        continue;
+      this.queuedLaneWaiters = Math.max(0, this.queuedLaneWaiters - 1);
+      if (waiter.settled)
+        continue;
+      waiter.settled = true;
+      clearTimeout(waiter.timer);
+      waiter.signal?.removeEventListener("abort", waiter.onAbort);
+      if (waiter.signal?.aborted) {
+        waiter.reject(waiter.signal.reason ?? new Error("module transport call aborted"));
+        continue;
+      }
+      if (waiter.deadlineMs - Date.now() < SERIAL_LANE_MIN_REMAINING_MS) {
+        waiter.reject(this.laneTimeoutError());
+        continue;
+      }
+      lane.active = true;
+      waiter.resolve(this.laneRelease(sessionId, lane));
+      return;
+    }
+    this.cleanupLane(sessionId, lane);
+  }
+  queueFullError() {
+    const error = new Error("module transport queue is full");
+    error.code = "EBUSY";
+    return error;
+  }
+  acquireCorrectnessLane(sessionId, signal, deadlineMs) {
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason ?? new Error("module transport call aborted"));
+    }
+    if (deadlineMs - Date.now() < SERIAL_LANE_MIN_REMAINING_MS) {
+      return Promise.reject(this.laneTimeoutError());
+    }
+    const lane = this.sessionLanes.get(sessionId) ?? { active: false, waiters: [] };
+    this.sessionLanes.set(sessionId, lane);
+    if (!lane.active && lane.waiters.length === 0) {
+      lane.active = true;
+      return Promise.resolve(this.laneRelease(sessionId, lane));
+    }
+    if (this.queuedLaneWaiters >= SERIAL_LANE_MAX_WAITERS || lane.waiters.length >= SERIAL_LANE_MAX_WAITERS_PER_SESSION) {
+      return Promise.reject(this.queueFullError());
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {};
+      const removeAndReject = (error) => {
+        if (waiter.settled)
+          return;
+        waiter.settled = true;
+        clearTimeout(waiter.timer);
+        signal?.removeEventListener("abort", waiter.onAbort);
+        const index = lane.waiters.indexOf(waiter);
+        if (index >= 0) {
+          lane.waiters.splice(index, 1);
+          this.queuedLaneWaiters = Math.max(0, this.queuedLaneWaiters - 1);
         }
         reject(error);
         this.cleanupLane(sessionId, lane);
@@ -27017,7 +27384,8 @@ class SubcModuleTransport {
     const laneDeadlineMs = Date.now() + attemptTimeoutMs;
     let releaseLane = () => {};
     try {
-      if (!args.bypassSessionLane) {
+      const outsideSessionOrder = args.method.startsWith("historian.");
+      if (!args.bypassSessionLane && !outsideSessionOrder) {
         releaseLane = await this.acquireCorrectnessLane(args.sessionId, args.signal, laneDeadlineMs);
       }
     } catch (error) {
@@ -27077,6 +27445,9 @@ class SubcModuleTransport {
         } catch (error) {
           if (args.signal?.aborted)
             throw args.signal.reason ?? error;
+          const storeAhead = storeAheadOfBinaryFailure(error);
+          if (storeAhead)
+            throw storeAhead;
           if (args.method === "state_sync" && isDeadlineFailure(error)) {
             const body = isRecord3(args.body) ? args.body : {};
             throw Object.assign(new Error(`state_sync timeout stage=module_ack page=${body.seed_batch_index ?? 0}/${body.seed_batch_total ?? 1} series=${body.seed_id ?? "delta"} budget_ms=${attemptTimeoutMs}`), {
@@ -27390,6 +27761,7 @@ var DEFAULT_MODULE_ID = "magic-context", CONNECT_BACKOFF_INITIAL_MS = 1000, CONN
 var init_module_transport = __esm(() => {
   init_dist5();
   init_data_path();
+  init_store_ahead_refusal();
 });
 // ../plugin/src/shared/pi-executable.ts
 function piHarnessKindFromExecutable(value) {
@@ -27406,6 +27778,9 @@ var init_pi_executable = __esm(() => {
 // ../plugin/src/shared/rpc-utils.ts
 import { execFileSync as execFileSync4 } from "node:child_process";
 import { readFileSync as readFileSync14 } from "node:fs";
+function isOwnRpcServerRecord(record) {
+  return record.pid === process.pid && record.instance_id !== undefined && ownRpcServerInstanceIds.has(record.instance_id);
+}
 function isPidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0)
     return "dead";
@@ -27928,10 +28303,11 @@ function parseRpcPortFile(content, fallbackPid = 0) {
 function isValidPort(port) {
   return Number.isInteger(port) && port > 0 && port <= 65535;
 }
-var RPC_IDENTITY_SKEW_TOLERANCE_MS = 120000, LINUX_CLOCK_TICKS_PER_SECOND = 100, PS_PROBE_TIMEOUT_MS = 1000, WINDOWS_CIM_PROBE_TIMEOUT_MS = 5000, MAX_ANCESTOR_WALK_DEPTH = 16, OPEN_CODE_COMMAND_MARKERS, TASKLIST_NO_TASKS_PATTERN, WINDOWS_CIM_COMMAND = "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress", PI_HARNESS_ARC_MARKERS, rpcIdentityReadFileSync, rpcIdentityExecFileSync, rpcIdentityProcessKill, rpcProcessListExecFileSync, rpcIdentityPlatform, rpcIdentityNowMs = () => Date.now(), windowsProcessFactsCache = null;
+var ownRpcServerInstanceIds, RPC_IDENTITY_SKEW_TOLERANCE_MS = 120000, LINUX_CLOCK_TICKS_PER_SECOND = 100, PS_PROBE_TIMEOUT_MS = 1000, WINDOWS_CIM_PROBE_TIMEOUT_MS = 5000, MAX_ANCESTOR_WALK_DEPTH = 16, OPEN_CODE_COMMAND_MARKERS, TASKLIST_NO_TASKS_PATTERN, WINDOWS_CIM_COMMAND = "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress", PI_HARNESS_ARC_MARKERS, rpcIdentityReadFileSync, rpcIdentityExecFileSync, rpcIdentityProcessKill, rpcProcessListExecFileSync, rpcIdentityPlatform, rpcIdentityNowMs = () => Date.now(), windowsProcessFactsCache = null;
 var init_rpc_utils = __esm(() => {
   init_logger();
   init_pi_executable();
+  ownRpcServerInstanceIds = new Set;
   OPEN_CODE_COMMAND_MARKERS = ["opencode", "node", "bun", "electron"];
   TASKLIST_NO_TASKS_PATTERN = /^INFO:\s+No tasks are running which match the specified criteria\.?$/im;
   PI_HARNESS_ARC_MARKERS = [
@@ -28061,7 +28437,9 @@ function formatFailClosedBlockingMessage(reason) {
     }
     return [
       `Magic Context cannot migrate the shared database (one database serves every project on this machine) because ${formatFailClosedBlockingProcesses(reason.blockingProcesses)} may be running an older Magic Context build that would fail against the migrated database.`,
+      `The database is at upstream migration v${reason.persistedVersion}; this build needs v${reason.supportedVersion}.`,
       "Restart the blocking process — even one from a different project — and it will pick up the new build and migrate on start; or shut it down and retry.",
+      "If that host loads a pinned or cached older Magic Context build, a restart alone is not enough: stop it or update its Magic Context build, then start this host once so it migrates the database with nothing older attached.",
       `Recovery: ${FAIL_CLOSED_DOCTOR_COMMAND}`
     ].join(" ");
   }
@@ -28096,6 +28474,47 @@ var init_message_fts_rowid_map = __esm(() => {
   activeBackfills = new WeakMap;
 });
 
+// ../plugin/src/features/magic-context/memory/constants.ts
+var V2_MEMORY_CATEGORIES, PROMOTABLE_CATEGORIES, CATEGORY_PRIORITY, MEMORY_CATEGORY_ORDER_UNKNOWN = 99, MEMORY_CATEGORY_ORDER_PRIORITY, MEMORY_CATEGORY_ORDER_SQL, CATEGORY_DEFAULT_TTL;
+var init_constants = __esm(() => {
+  V2_MEMORY_CATEGORIES = [
+    "PROJECT_RULES",
+    "ARCHITECTURE",
+    "CONSTRAINTS",
+    "CONFIG_VALUES",
+    "NAMING"
+  ];
+  PROMOTABLE_CATEGORIES = [
+    ...V2_MEMORY_CATEGORIES,
+    "ARCHITECTURE_DECISIONS",
+    "CONFIG_DEFAULTS",
+    "USER_PREFERENCES",
+    "USER_DIRECTIVES",
+    "ENVIRONMENT",
+    "WORKFLOW_RULES",
+    "KNOWN_ISSUES"
+  ];
+  CATEGORY_PRIORITY = [
+    ...V2_MEMORY_CATEGORIES,
+    "USER_DIRECTIVES",
+    "USER_PREFERENCES",
+    "CONFIG_DEFAULTS",
+    "ARCHITECTURE_DECISIONS",
+    "ENVIRONMENT",
+    "WORKFLOW_RULES",
+    "KNOWN_ISSUES"
+  ];
+  MEMORY_CATEGORY_ORDER_PRIORITY = CATEGORY_PRIORITY.reduce((acc, category, index) => {
+    acc[category] = index;
+    return acc;
+  }, {});
+  MEMORY_CATEGORY_ORDER_SQL = `CASE category ${CATEGORY_PRIORITY.map((category, index) => `WHEN '${category}' THEN ${index}`).join(" ")} ELSE ${MEMORY_CATEGORY_ORDER_UNKNOWN} END`;
+  CATEGORY_DEFAULT_TTL = {
+    WORKFLOW_RULES: 90 * 24 * 60 * 60 * 1000,
+    KNOWN_ISSUES: 30 * 24 * 60 * 60 * 1000
+  };
+});
+
 // ../plugin/src/hooks/magic-context/compartment-parser.ts
 function makeTierOpenRegex(n) {
   return new RegExp(`<p${n}\\s*(/?)>`);
@@ -28125,6 +28544,8 @@ function extractTiersFromInner(inner) {
 function parseCompartmentOutput(text) {
   const compartments = [];
   const facts = [];
+  let droppedFactBlocks = 0;
+  let droppedFacts = 0;
   for (const match of text.matchAll(COMPARTMENT_REGEX)) {
     const attrs = match[1];
     const inner = match[2];
@@ -28174,16 +28595,21 @@ function parseCompartmentOutput(text) {
     }
   }
   const factsBlockMatch = text.match(FACTS_BLOCK_REGEX);
-  const factsScope = factsBlockMatch ? factsBlockMatch[1] : text.replace(EVENTS_BLOCK_REGEX, "").replace(/<compartment\s+[^>]*?\s*>.*?<\/compartment>/gs, "");
+  const factsScope = factsBlockMatch ? factsBlockMatch[1] : text.replace(EVENTS_BLOCK_REGEX, "").replace(/<compartment\s+[^>]*?\s*>.*?<\/compartment>/gs, "").replace(/<(meta|user_observations|primer_candidates)>.*?<\/\1>/gs, "").replace(/<\/?(?:output|compartments)>/g, "");
   for (const categoryMatch of factsScope.matchAll(CATEGORY_BLOCK_REGEX)) {
     const category = categoryMatch[1];
     const blockContent = categoryMatch[2];
-    for (const itemMatch of blockContent.matchAll(FACT_ITEM_REGEX)) {
-      const content = unescapeXml(itemMatch[1].trim());
-      if (content) {
-        facts.push({ category, content });
-      }
+    const items = [...blockContent.matchAll(FACT_ITEM_REGEX)].map((match) => unescapeXml(match[1].trim())).filter(Boolean);
+    if (!HISTORIAN_CATEGORIES.has(category)) {
+      if (items.length === 0)
+        continue;
+      droppedFactBlocks++;
+      droppedFacts += items.length;
+      log3(`[historian] Dropped <facts> category ${category} (${items.length} facts)`);
+      continue;
     }
+    for (const content of items)
+      facts.push({ category, content });
   }
   const unprocessedMatch = text.match(UNPROCESSED_REGEX);
   const unprocessedFrom = unprocessedMatch ? parseInt(unprocessedMatch[1], 10) : null;
@@ -28221,7 +28647,16 @@ function parseCompartmentOutput(text) {
   }
   const events = parseEvents(text);
   compartments.sort((a, b) => a.startMessage - b.startMessage);
-  return { compartments, facts, events, unprocessedFrom, userObservations, primerCandidates };
+  return {
+    compartments,
+    facts,
+    droppedFactBlocks,
+    droppedFacts,
+    events,
+    unprocessedFrom,
+    userObservations,
+    primerCandidates
+  };
 }
 function parseEvents(text) {
   const blockMatch = text.match(EVENTS_BLOCK_REGEX);
@@ -28247,8 +28682,10 @@ function parseEvents(text) {
 function unescapeXml(s) {
   return s.replace(/&amp;/g, "&").replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">");
 }
-var COMPARTMENT_REGEX, ATTR_START_REGEX, ATTR_END_REGEX, ATTR_TITLE_REGEX, ATTR_EPISODE_REGEX, ATTR_IMPORTANCE_REGEX, TIER_OPEN_REGEXES, TIER_CLOSE_ANY_REGEX, TIER_OPEN_ANY_REGEX, CATEGORY_BLOCK_REGEX, FACT_ITEM_REGEX, UNPROCESSED_REGEX, USER_OBSERVATIONS_REGEX, USER_OBS_ITEM_REGEX, PRIMER_CANDIDATES_REGEX, PRIMER_ELEMENT_REGEX, PRIMER_ITEM_REGEX, FACTS_BLOCK_REGEX, EVENTS_BLOCK_REGEX, EVENT_ELEMENT_REGEX, EVENT_FIELD_REGEX;
+var COMPARTMENT_REGEX, ATTR_START_REGEX, ATTR_END_REGEX, ATTR_TITLE_REGEX, ATTR_EPISODE_REGEX, ATTR_IMPORTANCE_REGEX, TIER_OPEN_REGEXES, TIER_CLOSE_ANY_REGEX, TIER_OPEN_ANY_REGEX, CATEGORY_BLOCK_REGEX, HISTORIAN_CATEGORIES, FACT_ITEM_REGEX, UNPROCESSED_REGEX, USER_OBSERVATIONS_REGEX, USER_OBS_ITEM_REGEX, PRIMER_CANDIDATES_REGEX, PRIMER_ELEMENT_REGEX, PRIMER_ITEM_REGEX, FACTS_BLOCK_REGEX, EVENTS_BLOCK_REGEX, EVENT_ELEMENT_REGEX, EVENT_FIELD_REGEX;
 var init_compartment_parser = __esm(() => {
+  init_constants();
+  init_logger();
   COMPARTMENT_REGEX = /<compartment\s+([^>]*?)\s*>(.*?)<\/compartment>/gs;
   ATTR_START_REGEX = /\bstart="(\d+)"/;
   ATTR_END_REGEX = /\bend="(\d+)"/;
@@ -28263,7 +28700,8 @@ var init_compartment_parser = __esm(() => {
   ];
   TIER_CLOSE_ANY_REGEX = /<\/p\d/;
   TIER_OPEN_ANY_REGEX = /<p\d/;
-  CATEGORY_BLOCK_REGEX = /<(PROJECT_RULES|ARCHITECTURE|CONSTRAINTS|CONFIG_VALUES|NAMING)>(.*?)<\/\1>/gs;
+  CATEGORY_BLOCK_REGEX = /<([A-Za-z_][A-Za-z0-9_-]*)>(.*?)<\/\1>/gs;
+  HISTORIAN_CATEGORIES = new Set(V2_MEMORY_CATEGORIES);
   FACT_ITEM_REGEX = /^\s*\*\s*(.+)$/gm;
   UNPROCESSED_REGEX = /<unprocessed_from>(\d+)<\/unprocessed_from>/;
   USER_OBSERVATIONS_REGEX = /<user_observations>(.*?)<\/user_observations>/s;
@@ -28617,53 +29055,18 @@ function healAllNullColumns(db) {
     const nullPredicate = presentFallbacks.map(([column]) => `${column} IS NULL`).join(" OR ");
     db.prepare(`UPDATE session_meta SET ${assignments} WHERE ${nullPredicate}`).run(...presentFallbacks.map(([, fallback]) => fallback));
   }
-  healMissingMemoryBlockIds(db, existingColumns);
-}
-function getSessionMetaColumns(db) {
-  const rows = db.prepare("PRAGMA table_info(session_meta)").all();
-  return new Set(rows.flatMap((row) => typeof row.name === "string" ? [row.name] : []));
-}
-function healMissingMemoryBlockIds(db, columns) {
-  if (!columns.has("memory_block_cache") || !columns.has("memory_block_ids") || !columns.has("memory_block_count")) {
-    return;
-  }
-  db.prepare("UPDATE session_meta SET memory_block_cache = '' WHERE memory_block_cache != '' AND (memory_block_ids IS NULL OR memory_block_ids = '') AND memory_block_count > 0").run();
-}
-
-// ../plugin/src/features/magic-context/memory/constants.ts
-var V2_MEMORY_CATEGORIES, CATEGORY_PRIORITY, MEMORY_CATEGORY_ORDER_UNKNOWN = 99, MEMORY_CATEGORY_ORDER_PRIORITY, MEMORY_CATEGORY_ORDER_SQL, CATEGORY_DEFAULT_TTL;
-var init_constants = __esm(() => {
-  V2_MEMORY_CATEGORIES = [
-    "PROJECT_RULES",
-    "ARCHITECTURE",
-    "CONSTRAINTS",
-    "CONFIG_VALUES",
-    "NAMING"
-  ];
-  CATEGORY_PRIORITY = [
-    "PROJECT_RULES",
-    "ARCHITECTURE",
-    "CONSTRAINTS",
-    "CONFIG_VALUES",
-    "NAMING",
-    "USER_DIRECTIVES",
-    "USER_PREFERENCES",
-    "CONFIG_DEFAULTS",
-    "ARCHITECTURE_DECISIONS",
-    "ENVIRONMENT",
-    "WORKFLOW_RULES",
-    "KNOWN_ISSUES"
-  ];
-  MEMORY_CATEGORY_ORDER_PRIORITY = CATEGORY_PRIORITY.reduce((acc, category, index) => {
-    acc[category] = index;
-    return acc;
-  }, {});
-  MEMORY_CATEGORY_ORDER_SQL = `CASE category ${CATEGORY_PRIORITY.map((category, index) => `WHEN '${category}' THEN ${index}`).join(" ")} ELSE ${MEMORY_CATEGORY_ORDER_UNKNOWN} END`;
-  CATEGORY_DEFAULT_TTL = {
-    WORKFLOW_RULES: 90 * 24 * 60 * 60 * 1000,
-    KNOWN_ISSUES: 30 * 24 * 60 * 60 * 1000
-  };
-});
+  healMissingMemoryBlockIds(db, existingColumns);
+}
+function getSessionMetaColumns(db) {
+  const rows = db.prepare("PRAGMA table_info(session_meta)").all();
+  return new Set(rows.flatMap((row) => typeof row.name === "string" ? [row.name] : []));
+}
+function healMissingMemoryBlockIds(db, columns) {
+  if (!columns.has("memory_block_cache") || !columns.has("memory_block_ids") || !columns.has("memory_block_count")) {
+    return;
+  }
+  db.prepare("UPDATE session_meta SET memory_block_cache = '' WHERE memory_block_cache != '' AND (memory_block_ids IS NULL OR memory_block_ids = '') AND memory_block_count > 0").run();
+}
 
 // ../plugin/src/features/magic-context/project-identity.ts
 var init_project_identity2 = __esm(() => {
@@ -31144,6 +31547,20 @@ var init_migrations = __esm(async () => {
           return;
         ensureColumn(db, "compartment_state_lease", "owner_pid", "INTEGER");
       }
+    },
+    {
+      version: 91,
+      description: "per-project embedding high-water mark for memories written outside this host",
+      up(db) {
+        db.exec(`
+                CREATE TABLE IF NOT EXISTS memory_embedding_watermarks (
+                    project_path TEXT PRIMARY KEY,
+                    written_memory_id INTEGER NOT NULL DEFAULT 0,
+                    embedded_memory_id INTEGER NOT NULL DEFAULT 0,
+                    updated_at INTEGER NOT NULL DEFAULT 0
+                );
+            `);
+      }
     }
   ];
   LATEST_MIGRATION_VERSION = MIGRATIONS.reduce((max, m) => Math.max(max, m.version), 0);
@@ -31375,6 +31792,8 @@ function inspectRpcServerDiscovery(storageDir) {
         return junk;
       continue;
     }
+    if (isOwnRpcServerRecord(record))
+      continue;
     const liveness = isPidAlive(record.pid);
     if (liveness === "dead") {
       staleFiles.push(portFile);
@@ -31996,6 +32415,15 @@ CREATE INDEX IF NOT EXISTS idx_dream_queue_pending ON dream_queue(started_at, en
       (id, cursor_session_id, cursor_ordinal, completed, updated_at)
     VALUES (1, '', 0, 0, 0);
 
+    -- Highest memory id another writer (the Rust module in single-store mode) put
+    -- into memories for a project, and how far this host has embedded. Migration v91.
+    CREATE TABLE IF NOT EXISTS memory_embedding_watermarks (
+      project_path TEXT PRIMARY KEY,
+      written_memory_id INTEGER NOT NULL DEFAULT 0,
+      embedded_memory_id INTEGER NOT NULL DEFAULT 0,
+      updated_at INTEGER NOT NULL DEFAULT 0
+    );
+
     CREATE TABLE IF NOT EXISTS message_history_index (
       session_id TEXT PRIMARY KEY,
       last_indexed_ordinal INTEGER NOT NULL DEFAULT 0,
@@ -32655,7 +33083,7 @@ CREATE INDEX IF NOT EXISTS idx_dream_queue_pending ON dream_queue(started_at, en
     `);
   ensureColumn(db, "workspaces", "share_categories", `TEXT NOT NULL DEFAULT '["CONSTRAINTS"]'`);
 }
-var databases, pendingAsyncOpens, persistenceByDatabase, persistenceErrorByDatabase, pathByDatabase, LATEST_SUPPORTED_VERSION = 90, BOOT_SQLITE_BUSY_TIMEOUT_MS = 5000, PERMISSIONS_ENFORCEABLE, RPC_DISCOVERY_PARSE_GRACE_MS, defaultRpcDiscoveryFs, rpcDiscoveryFs, sqlitePragmaConfig, CHANNEL2_CLAIM_TTL_MS;
+var databases, pendingAsyncOpens, persistenceByDatabase, persistenceErrorByDatabase, pathByDatabase, LATEST_SUPPORTED_VERSION = 91, BOOT_SQLITE_BUSY_TIMEOUT_MS = 5000, PERMISSIONS_ENFORCEABLE, RPC_DISCOVERY_PARSE_GRACE_MS, defaultRpcDiscoveryFs, rpcDiscoveryFs, sqlitePragmaConfig, CHANNEL2_CLAIM_TTL_MS;
 var init_storage_db = __esm(async () => {
   init_data_path();
   init_logger();
@@ -35440,7 +35868,7 @@ async function doctorRetryV22Backfill(db) {
           bumpProjectMemoryEpochInTransaction(db, identity, now);
           succeeded += 1;
         }
-      })();
+      }).immediate();
     } catch (error) {
       const classified = classifyBackfillError(error);
       db.prepare(`UPDATE v22_backfill_failures
@@ -35473,7 +35901,7 @@ async function doctorRekeyV22DirIdentity(db, rawProjectPath) {
     if (changedRows > 0) {
       bumpProjectMemoryEpochInTransaction(db, newIdentity, now);
     }
-  })();
+  }).immediate();
   return { oldIdentity, newIdentity, changedRows };
 }
 var BACKFILL_META_KEY = "v22_legacy_memory_backfill", BACKFILL_CURSOR_META_KEY = "v22_legacy_memory_backfill_cursor", MEMORIES_TABLE = "memories";
@@ -35546,236 +35974,6 @@ var init_v22_backfill_commands = __esm(async () => {
   await init_storage_db();
 });
 
-// ../plugin/src/shared/user-facing-codes.ts
-function userFacingFailureCode(key) {
-  return USER_FACING_FAILURES[key].code;
-}
-var USER_FACING_FAILURES;
-var init_user_facing_codes = __esm(() => {
-  USER_FACING_FAILURES = {
-    historian_unavailable: {
-      code: "MC-H01",
-      sentence: "History compression could not finish this turn.",
-      action: "It will retry automatically."
-    },
-    hidden_cleanup_unbound: {
-      code: "MC-H02",
-      sentence: "Some finished background sessions could not be removed from this host.",
-      action: "They are removed automatically the next time Magic Context runs inside a registered OpenCode service."
-    },
-    historian_saved_history_misaligned: {
-      code: "MC-H03",
-      sentence: "History compression is paused because this session's saved summaries no longer line up with its messages.",
-      action: "Run /ctx-recomp to rebuild them."
-    },
-    recomp_unavailable: {
-      code: "MC-R01",
-      sentence: "History compression could not be rebuilt.",
-      action: "Run /ctx-recomp again."
-    },
-    dream_provider_timeout: {
-      code: "MC-D01",
-      sentence: "Memory maintenance took too long to respond.",
-      action: "Run /ctx-dream again."
-    },
-    dream_provider_error: {
-      code: "MC-D02",
-      sentence: "Memory maintenance could not reach its model.",
-      action: "Check the model connection, then run /ctx-dream again."
-    },
-    dream_empty_completion: {
-      code: "MC-D03",
-      sentence: "Memory maintenance received no usable response.",
-      action: "Run /ctx-dream again."
-    },
-    dream_no_models: {
-      code: "MC-D04",
-      sentence: "Memory maintenance has no model available.",
-      action: "Check the model settings, then run /ctx-dream again."
-    },
-    dream_child_aborted: {
-      code: "MC-D05",
-      sentence: "Memory maintenance was interrupted.",
-      action: "Run /ctx-dream again."
-    },
-    dream_parse_failed: {
-      code: "MC-D06",
-      sentence: "Memory maintenance could not use the model response.",
-      action: "Run /ctx-dream again."
-    },
-    dream_unknown: {
-      code: "MC-D07",
-      sentence: "Memory maintenance could not finish.",
-      action: "Run /ctx-dream again."
-    },
-    dreamer_tick_blocked: {
-      code: "MC-D09",
-      sentence: "Background maintenance is not running: its last pass stopped before it reached the scheduled tasks.",
-      action: "It is retried automatically; if it keeps happening, check the Magic Context log for the stage that stopped and run `npx @cortexkit/magic-context doctor`."
-    },
-    dream_task_needs_tool_loop: {
-      code: "MC-D08",
-      sentence: "Some memory maintenance tasks need a tool loop this host does not provide.",
-      action: "The remaining tasks still run; the listed ones are skipped on this host."
-    },
-    embedding_substitution_rejected: {
-      code: "MC-E01",
-      sentence: "Search indexing could not use the selected model.",
-      action: "Check the embedding model setting, then run /ctx-embed start again."
-    },
-    embedding_http_error: {
-      code: "MC-E02",
-      sentence: "The search indexing provider refused the request.",
-      action: "Check the provider connection and credentials, then run /ctx-embed start again."
-    },
-    embedding_transport_error: {
-      code: "MC-E03",
-      sentence: "Search indexing could not reach its provider.",
-      action: "Check the connection, then run /ctx-embed start again."
-    },
-    embedding_invalid_envelope: {
-      code: "MC-E04",
-      sentence: "Search indexing received an unsupported response.",
-      action: "Check the embedding endpoint, then run /ctx-embed start again."
-    },
-    embedding_empty_result: {
-      code: "MC-E05",
-      sentence: "Search indexing received no usable result.",
-      action: "Run /ctx-embed start again."
-    },
-    embedding_certification_refusal: {
-      code: "MC-E06",
-      sentence: "Search indexing is not ready for this provider.",
-      action: "Finish the provider setup, or set a fallback provider in the embedding settings, then run /ctx-embed start again."
-    },
-    embedding_credential_required: {
-      code: "MC-E07",
-      sentence: "Search indexing needs provider credentials.",
-      action: "Sign in to the provider, then run /ctx-embed start again."
-    },
-    embedding_local_binding_missing: {
-      code: "MC-E08",
-      sentence: "Local search indexing is unavailable on this system.",
-      action: "Run `npx @cortexkit/magic-context doctor`, then retry."
-    },
-    embedding_local_fs_unavailable: {
-      code: "MC-E09",
-      sentence: "Local search indexing cannot save its model files.",
-      action: "Update or reinstall Magic Context, then retry."
-    },
-    embedding_local_download_failure: {
-      code: "MC-E10",
-      sentence: "Local search indexing could not download its model.",
-      action: "Check the network connection, then retry."
-    },
-    embedding_local_runtime_error: {
-      code: "MC-E11",
-      sentence: "Local search indexing could not start.",
-      action: "Run `npx @cortexkit/magic-context doctor`, then retry."
-    },
-    embedding_unavailable: {
-      code: "MC-E12",
-      sentence: "Search indexing could not finish.",
-      action: "Run /ctx-embed start again."
-    },
-    status_unavailable: {
-      code: "MC-S01",
-      sentence: "Magic Context status is temporarily unavailable.",
-      action: "Retry /ctx-status in a moment."
-    },
-    transform_update_failed: {
-      code: "MC-S02",
-      sentence: "The last context update did not finish.",
-      action: "Send another message to retry."
-    },
-    configuration_warning: {
-      code: "MC-S03",
-      sentence: "Some configuration settings could not be applied.",
-      action: "Fix the configuration warning shown in /ctx-status, then restart."
-    },
-    status_log_unavailable: {
-      code: "MC-S04",
-      sentence: "Some diagnostic details could not be saved.",
-      action: "Retry /ctx-status in a moment."
-    },
-    memory_writes_paused: {
-      code: "MC-C01",
-      sentence: "Memory writes are paused while the engine syncs.",
-      action: "Retry in a moment."
-    },
-    memory_access_unavailable: {
-      code: "MC-C02",
-      sentence: "Memory access is temporarily unavailable.",
-      action: "Retry in a moment."
-    },
-    note_changes_paused: {
-      code: "MC-C03",
-      sentence: "Note changes are paused while the engine syncs.",
-      action: "Retry in a moment."
-    },
-    note_access_unavailable: {
-      code: "MC-C04",
-      sentence: "Notes are temporarily unavailable.",
-      action: "Retry in a moment."
-    },
-    context_cleanup_paused: {
-      code: "MC-C05",
-      sentence: "Context cleanup is paused while the engine syncs.",
-      action: "Retry in a moment."
-    },
-    partial_history_unavailable: {
-      code: "MC-C06",
-      sentence: "Partial history compression is not available in the current mode.",
-      action: "Run /ctx-recomp without a range."
-    },
-    smart_note_conditions_unavailable: {
-      code: "MC-C08",
-      sentence: "Conditional notes are not available in the current mode.",
-      action: "Save a regular note without a condition."
-    },
-    history_compression_paused: {
-      code: "MC-C09",
-      sentence: "History compression is paused while the engine syncs.",
-      action: "Retry in a moment."
-    },
-    history_compression_needs_message: {
-      code: "MC-C12",
-      sentence: "History compression has not seen this session since Magic Context reconnected.",
-      action: "Send a message in this session first, then run /ctx-wrapup again."
-    },
-    context_service_unavailable: {
-      code: "MC-C10",
-      sentence: "Magic Context is temporarily unavailable.",
-      action: "Retry in a moment."
-    },
-    compaction_marker_missing: {
-      code: "MC-C11",
-      sentence: "The history boundary marker is missing from the OpenCode store, so requests carry the full session.",
-      action: "It is retried on every message; if this persists, run `/ctx-flush`."
-    },
-    memory_mirror_stalled: {
-      code: "MC-M01",
-      sentence: "Memory synchronization stopped before the host mirror caught up.",
-      action: "Send another message to resume it, or run `ck doctor drain-authority`."
-    },
-    memory_authority_mismatch: {
-      code: "MC-M02",
-      sentence: "Memory authority is inconsistent between the host and module.",
-      action: "Run `ck doctor drain-authority` before changing Rust mode."
-    },
-    rust_mode_unsupported: {
-      code: "MC-S06",
-      sentence: "Experimental Rust transform mode is not available on this OpenCode host.",
-      action: 'Magic Context is running its TypeScript mode instead; set `transform_mode` to "ts" to stop requesting Rust.'
-    },
-    dreamer_task_failing: {
-      code: "MC-S05",
-      sentence: "A background maintenance task keeps failing on its schedule.",
-      action: "Check the Magic Context log for the failing task and its error."
-    }
-  };
-});
-
 // ../plugin/src/features/magic-context/dreamer/tick-failure.ts
 function parseFailure(value) {
   if (!value)
@@ -38519,6 +38717,9 @@ async function collectHistorianRuns(storageDirPath) {
     } catch {}
   }
 }
+function openCodeIssueLogHarnesses(hostGeneration) {
+  return hostGeneration === "v2" ? ["opencode2", "opencode"] : ["opencode"];
+}
 async function collectDiagnostics() {
   const pluginVersion = getSelfVersion();
   const configPaths = detectConfigPaths();
@@ -38528,8 +38729,6 @@ async function collectDiagnostics() {
   const storageResolution = getStorageResolution();
   const storageDirPath = storageResolution.path;
   const contextDbPath = join26(storageDirPath, "context.db");
-  const logFiles = inspectMagicContextLogs("opencode");
-  const primaryLog = logFiles.find((file) => file.exists) ?? logFiles[0];
   let compactionEnabled = false;
   try {
     compactionEnabled = isCompactionEnabled(loadPluginConfig(process.cwd()));
@@ -38539,6 +38738,8 @@ async function collectDiagnostics() {
   const opencodeInstallations = describeOpenCodeInstallations(detectOpenCodeInstallations());
   const activeInstallation = opencodeInstallations[0];
   const hostGeneration = openCodeHostGenerationFromVersion(activeInstallation?.version);
+  const logFiles = openCodeIssueLogHarnesses(hostGeneration).flatMap((harness) => inspectMagicContextLogs(harness)).filter((file, index, all) => all.findIndex((other) => other.path === file.path) === index);
+  const primaryLog = logFiles.find((file) => file.exists) ?? logFiles[0];
   const conflictResult = detectConflicts(process.cwd(), { compactionEnabled, hostGeneration });
   const openCodeDatabaseResolution = resolveOpenCodeDbPath(hostGeneration);
   const recentSessions = await collectRecentSessions(openCodeDatabaseResolution, hostGeneration);
@@ -40046,6 +40247,179 @@ var init_storage_versions = __esm(async () => {
   await init_storage_db();
 });
 
+// src/commands/doctor-opencode-cache.ts
+import { existsSync as existsSync36, readFileSync as readFileSync25, rmSync as rmSync4 } from "node:fs";
+function readCachedPluginVersion(pluginCacheDir) {
+  try {
+    const installedPkgPath = getOpenCodePluginPackageJsonPath(pluginCacheDir);
+    if (!existsSync36(installedPkgPath))
+      return;
+    const pkg = JSON.parse(readFileSync25(installedPkgPath, "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : undefined;
+  } catch {
+    return;
+  }
+}
+async function clearPluginCache(options = {}, deps = {}) {
+  const remove = deps.remove ?? ((path) => rmSync4(path, { recursive: true, force: true }));
+  const pluginCacheRoots = getOpenCodePluginCacheRoots();
+  const existingRoots = pluginCacheRoots.filter((root) => existsSync36(root));
+  if (existingRoots.length === 0) {
+    return { action: "not_found", path: pluginCacheRoots[0] ?? "" };
+  }
+  const latestVersion = options.latestVersion ?? undefined;
+  const cacheEntries = existingRoots.map((path) => ({
+    path,
+    cached: readCachedPluginVersion(path)
+  }));
+  if (options.force !== true && latestVersion === undefined) {
+    const firstEntry = cacheEntries[0];
+    return {
+      action: "check_unavailable",
+      path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
+      paths: cacheEntries.map((entry) => entry.path),
+      cached: firstEntry?.cached
+    };
+  }
+  const clearTargets = cacheEntries.filter((entry) => options.force === true || entry.cached === undefined || entry.cached !== latestVersion);
+  if (clearTargets.length === 0) {
+    const firstEntry = cacheEntries[0];
+    return {
+      action: "up_to_date",
+      path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
+      paths: cacheEntries.map((entry) => entry.path),
+      cached: firstEntry?.cached,
+      latest: latestVersion
+    };
+  }
+  const cleared = [];
+  const failed = [];
+  for (const entry of clearTargets) {
+    try {
+      remove(entry.path);
+      cleared.push(entry);
+    } catch (err) {
+      failed.push({
+        path: entry.path,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  if (failed.length > 0) {
+    const firstFailure = failed[0];
+    return {
+      action: "error",
+      path: firstFailure?.path ?? clearTargets[0]?.path ?? existingRoots[0] ?? "",
+      paths: failed.map((entry) => entry.path),
+      clearedPaths: cleared.map((entry) => entry.path),
+      failedPaths: failed.map((entry) => entry.path),
+      error: firstFailure?.error
+    };
+  }
+  const firstTarget = cleared[0];
+  return {
+    action: "cleared",
+    path: firstTarget?.path ?? pluginCacheRoots[0] ?? "",
+    paths: cleared.map((entry) => entry.path),
+    cached: firstTarget?.cached,
+    latest: latestVersion
+  };
+}
+var init_doctor_opencode_cache = __esm(() => {
+  init_opencode_plugin_cache();
+});
+
+// src/commands/doctor-cached-plugin-fence.ts
+import { existsSync as existsSync37 } from "node:fs";
+import { dirname as dirname18 } from "node:path";
+function listCachedOpenCodePluginFences(sources = {}) {
+  const fences = [];
+  for (const root of sources.openCodeV1Roots ?? getOpenCodePluginCacheRoots()) {
+    const packageJson = getOpenCodePluginPackageJsonPath(root);
+    if (!existsSync37(packageJson))
+      continue;
+    fences.push({
+      host: "opencode1",
+      directory: root,
+      version: readCachedPluginVersion(root),
+      supportedVersion: readFenceFromDist(dirname18(packageJson))
+    });
+  }
+  for (const slot of listOpenCodeV2PluginCacheSlots(sources.openCodeV2NpmCacheDir)) {
+    if (!isOpenCodePluginDistTag(slot.spec))
+      continue;
+    const generation = getOpenCodeV2ActiveGeneration(slot.slot);
+    if (!generation)
+      continue;
+    fences.push({
+      host: "opencode2",
+      directory: slot.slot,
+      spec: slot.spec,
+      version: slot.version,
+      supportedVersion: readFenceFromDist(dirname18(getOpenCodePluginPackageJsonPath(generation)))
+    });
+  }
+  return fences;
+}
+function readContextDbSchemaVersion(path) {
+  let db = null;
+  try {
+    db = openExistingDatabase(path, { readonly: true });
+    return db === null ? null : getPersistedSchemaVersion(db);
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+function compareCachedPluginFences(fences, databaseVersion) {
+  return fences.map((fence) => ({
+    ...fence,
+    databaseVersion,
+    status: fence.supportedVersion === null ? "unknown" : fence.supportedVersion < databaseVersion ? "behind" : "supported"
+  }));
+}
+function hostLabel(fence) {
+  if (fence.host === "opencode1")
+    return "OpenCode 1";
+  return fence.spec && fence.spec !== "latest" ? `OpenCode 2 (@${fence.spec})` : "OpenCode 2";
+}
+function reportCachedPluginFences(findings, report) {
+  const supported = [];
+  let behind = 0;
+  for (const finding of findings) {
+    const label = hostLabel(finding);
+    const version = finding.version ?? "unknown version";
+    if (finding.status === "supported") {
+      supported.push(`${label} ${version} (fence v${finding.supportedVersion})`);
+      continue;
+    }
+    if (finding.status === "unknown") {
+      report.info(`${label} plugin cache: could not read the schema fence of Magic Context ${version}, so doctor cannot tell whether it supports context.db v${finding.databaseVersion}`);
+      report.info(`  ${finding.directory}`);
+      continue;
+    }
+    behind++;
+    report.fail(`${label} has Magic Context ${version} cached, which supports context.db only through schema v${finding.supportedVersion}, but the shared context.db is at v${finding.databaseVersion}. A newer Magic Context (usually the other OpenCode host) migrated it, so ${label} fails closed on every prompt; an @latest entry does not refresh this cached copy.`);
+    report.info(`  ${finding.directory}`);
+    report.info(finding.host === "opencode1" ? "  To fix: quit OpenCode 1 and delete that directory; OpenCode 1 installs the current release on its next start." : `  To fix, ${OPENCODE_V2_PLUGIN_UPDATE_HINT}, then restart OpenCode 2.`);
+  }
+  if (supported.length > 0) {
+    report.pass(`Cached Magic Context copies support context.db v${findings[0]?.databaseVersion}: ${supported.join(", ")}`);
+  }
+  return { behind };
+}
+var init_doctor_cached_plugin_fence = __esm(async () => {
+  init_opencode_plugin_cache();
+  init_opencode_plugin_schema_fence();
+  init_doctor_opencode_cache();
+  init_doctor_opencode2_cache();
+  await __promiseAll([
+    init_storage_db(),
+    init_database_access()
+  ]);
+});
+
 // src/commands/doctor-compaction-markers.ts
 function safeData(column = "data") {
   return `CASE WHEN json_valid(${column}) THEN ${column} ELSE '{}' END`;
@@ -40101,6 +40475,21 @@ function countUnmatchedConvertedMarkers(db, migratedV2Schema) {
                 )`).get();
   return Number(row?.count ?? 0);
 }
+function countPostConversionMessages(db, migratedV2Schema) {
+  if (!migratedV2Schema || !tableExists4(db, "message") || !tableExists4(db, "session")) {
+    return { messages: 0, sessions: 0 };
+  }
+  const row = db.prepare(`SELECT COUNT(*) AS messages, COUNT(DISTINCT converted.session_id) AS sessions
+               FROM session_message converted
+              WHERE EXISTS (SELECT 1 FROM session legacy WHERE legacy.id = converted.session_id)
+                AND NOT EXISTS (
+                    SELECT 1
+                      FROM message source
+                     WHERE source.session_id = converted.session_id
+                       AND source.time_created = converted.time_created
+                )`).get();
+  return { messages: Number(row?.messages ?? 0), sessions: Number(row?.sessions ?? 0) };
+}
 function checkOpenCodeCompactionMarkerConversion(db, options = {}) {
   const missingBefore = countMissingCompleted(db);
   let repaired = 0;
@@ -40121,6 +40510,7 @@ function checkOpenCodeCompactionMarkerConversion(db, options = {}) {
   const migratedV2Schema = tableExists4(db, "session_v2") && tableExists4(db, "session_message");
   const migrationCompleted = migrationV1ToV2Completed(db);
   const unmatchedConvertedMarkers = countUnmatchedConvertedMarkers(db, migratedV2Schema);
+  const postConversion = countPostConversionMessages(db, migratedV2Schema);
   return {
     missingBefore,
     missingAfter,
@@ -40128,21 +40518,23 @@ function checkOpenCodeCompactionMarkerConversion(db, options = {}) {
     migrationCompleted,
     migratedV2Schema,
     unmatchedConvertedMarkers,
-    recoveryRequired: migrationCompleted && migratedV2Schema && unmatchedConvertedMarkers > 0
+    postConversionMessages: postConversion.messages,
+    postConversionSessions: postConversion.sessions
   };
 }
 function formatOpenCodeCompactionMarkerConversion(report) {
   return `OpenCode compaction markers are convertible to OpenCode 2: before=${report.missingBefore} missing time.completed; after=${report.missingAfter}`;
 }
-function formatOpenCodeV2ReconversionRecipe(databasePath) {
-  return [
-    "OpenCode 2 already completed its v1→v2 conversion, but one or more Magic Context markers are absent from session_message.",
-    "Recovery (with every OpenCode host stopped): clear only the kv.migration.v1-v2 marker, then restart the host once so it reconverts the v1 rows. Do not edit session_v2 or session_message by hand.",
-    `Database: ${databasePath}`,
-    "In sqlite3, run: DELETE FROM kv WHERE key = 'migration.v1-v2';",
-    "Large-store conversion can take several minutes. `opencode service start` may kill the server as unresponsive while it runs; start `opencode serve --port N` by hand instead.",
-    'Wait until `SELECT value FROM kv WHERE key = \'migration.v1-v2\';` reads `{"phase":"completed"}` before stopping that manual server'
+function formatOpenCodeV2MissingMarkerNotice(report) {
+  if (!report.migrationCompleted || !report.migratedV2Schema || report.unmatchedConvertedMarkers === 0) {
+    return null;
+  }
+  const lines = [
+    `OpenCode 2's conversion did not carry over ${report.unmatchedConvertedMarkers} Magic Context compaction marker(s). No action is needed.`,
+    "Magic Context on OpenCode 2 does not use host compaction rows: it keeps its own boundary and re-derives compartment positions from the messages that survived. OpenCode reads these sessions' full history on each turn, as it does for any Magic Context session started on OpenCode 2."
   ];
+  lines.push(report.postConversionMessages > 0 ? `Do not clear kv.migration.v1-v2 to reconvert: OpenCode 2 would rebuild every converted session from its OpenCode 1 rows and delete the ${report.postConversionMessages} message(s) it added after the conversion, in ${report.postConversionSessions} session(s).` : "Do not clear kv.migration.v1-v2 to reconvert: OpenCode 2 would rebuild every converted session from its OpenCode 1 rows, deleting anything added on OpenCode 2 since.", "If you already reconverted, restore opencode.db (with its -wal and -shm files) from a backup taken before the reconversion.");
+  return lines;
 }
 
 // src/commands/doctor-compartment-boundaries.ts
@@ -40226,88 +40618,6 @@ var init_doctor_harness_relabel = __esm(async () => {
   await init_opencode2_relabel();
 });
 
-// src/commands/doctor-opencode-cache.ts
-import { existsSync as existsSync36, readFileSync as readFileSync25, rmSync as rmSync4 } from "node:fs";
-function readCachedPluginVersion(pluginCacheDir) {
-  try {
-    const installedPkgPath = getOpenCodePluginPackageJsonPath(pluginCacheDir);
-    if (!existsSync36(installedPkgPath))
-      return;
-    const pkg = JSON.parse(readFileSync25(installedPkgPath, "utf-8"));
-    return typeof pkg.version === "string" ? pkg.version : undefined;
-  } catch {
-    return;
-  }
-}
-async function clearPluginCache(options = {}, deps = {}) {
-  const remove = deps.remove ?? ((path) => rmSync4(path, { recursive: true, force: true }));
-  const pluginCacheRoots = getOpenCodePluginCacheRoots();
-  const existingRoots = pluginCacheRoots.filter((root) => existsSync36(root));
-  if (existingRoots.length === 0) {
-    return { action: "not_found", path: pluginCacheRoots[0] ?? "" };
-  }
-  const latestVersion = options.latestVersion ?? undefined;
-  const cacheEntries = existingRoots.map((path) => ({
-    path,
-    cached: readCachedPluginVersion(path)
-  }));
-  if (options.force !== true && latestVersion === undefined) {
-    const firstEntry = cacheEntries[0];
-    return {
-      action: "check_unavailable",
-      path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
-      paths: cacheEntries.map((entry) => entry.path),
-      cached: firstEntry?.cached
-    };
-  }
-  const clearTargets = cacheEntries.filter((entry) => options.force === true || entry.cached === undefined || entry.cached !== latestVersion);
-  if (clearTargets.length === 0) {
-    const firstEntry = cacheEntries[0];
-    return {
-      action: "up_to_date",
-      path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
-      paths: cacheEntries.map((entry) => entry.path),
-      cached: firstEntry?.cached,
-      latest: latestVersion
-    };
-  }
-  const cleared = [];
-  const failed = [];
-  for (const entry of clearTargets) {
-    try {
-      remove(entry.path);
-      cleared.push(entry);
-    } catch (err) {
-      failed.push({
-        path: entry.path,
-        error: err instanceof Error ? err.message : String(err)
-      });
-    }
-  }
-  if (failed.length > 0) {
-    const firstFailure = failed[0];
-    return {
-      action: "error",
-      path: firstFailure?.path ?? clearTargets[0]?.path ?? existingRoots[0] ?? "",
-      paths: failed.map((entry) => entry.path),
-      clearedPaths: cleared.map((entry) => entry.path),
-      failedPaths: failed.map((entry) => entry.path),
-      error: firstFailure?.error
-    };
-  }
-  const firstTarget = cleared[0];
-  return {
-    action: "cleared",
-    path: firstTarget?.path ?? pluginCacheRoots[0] ?? "",
-    paths: cleared.map((entry) => entry.path),
-    cached: firstTarget?.cached,
-    latest: latestVersion
-  };
-}
-var init_doctor_opencode_cache = __esm(() => {
-  init_opencode_plugin_cache();
-});
-
 // src/commands/doctor-opencode-plugin-duplicates.ts
 import { isDeepStrictEqual } from "node:util";
 function entryOptions(entry) {
@@ -40535,10 +40845,21 @@ function formatUnresolvedCompartmentSession(session) {
 
 // src/commands/doctor-opencode.ts
 import { spawnSync as spawnSync8 } from "node:child_process";
-import { existsSync as existsSync37, mkdtempSync, readFileSync as readFileSync26, rmSync as rmSync5 } from "node:fs";
+import { existsSync as existsSync38, mkdtempSync, readFileSync as readFileSync26, rmSync as rmSync5 } from "node:fs";
 import { createRequire as createRequire6 } from "node:module";
 import { homedir as homedir16, tmpdir as tmpdir3 } from "node:os";
 import { join as join32 } from "node:path";
+function formatSharedDbRowCounts(db) {
+  return SHARED_DB_ROW_COUNT_TABLES.map((table) => {
+    try {
+      const row = db.prepare(`SELECT COUNT(*) AS c FROM ${table}`).get();
+      return `${table}=${typeof row?.c === "number" ? row.c : "n/a"}`;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return `${table}=n/a (${sanitizeDiagnosticText(reason)})`;
+    }
+  }).join(", ");
+}
 function findUndeclaredConfiguredVariants(configured, catalog) {
   return configured.filter((entry) => {
     const [providerID, id] = entry.model.split("/", 2);
@@ -40546,6 +40867,18 @@ function findUndeclaredConfiguredVariants(configured, catalog) {
     return model !== undefined && !Object.hasOwn(model.variants, entry.variant);
   });
 }
+function findUnknownConfiguredModels(configured, catalog) {
+  return configured.flatMap((entry) => {
+    const [providerID, id] = entry.model.split("/", 2);
+    if (!catalog.some((item) => item.providerID === providerID)) {
+      return [{ ...entry, unknown: "provider" }];
+    }
+    if (!catalog.some((item) => item.providerID === providerID && item.id === id)) {
+      return [{ ...entry, unknown: "model" }];
+    }
+    return [];
+  });
+}
 function checkConfiguredVariantCatalog(config, hostGeneration, warn, run = (args, cwd) => spawnSync8("opencode", args, {
   cwd,
   encoding: "utf8",
@@ -40553,6 +40886,7 @@ function checkConfiguredVariantCatalog(config, hostGeneration, warn, run = (args
   maxBuffer: 16 * 1024 * 1024
 }), projectDir = process.cwd()) {
   const configured = [];
+  const models = [];
   const root = config && typeof config === "object" ? config : {};
   for (const agent of ["historian", "dreamer"]) {
     const section = root[agent];
@@ -40562,21 +40896,25 @@ function checkConfiguredVariantCatalog(config, hostGeneration, warn, run = (args
     if (!block || typeof block !== "object")
       continue;
     const record = block;
-    const add = (entry, defaultVariant) => {
+    const add = (entry, defaultVariant, fallback) => {
       const value = entry && typeof entry === "object" ? entry : {};
       const model = typeof entry === "string" ? entry : value.model;
       const variant = value.variant ?? defaultVariant;
-      if (typeof model === "string" && typeof variant === "string" && model.includes("/")) {
-        configured.push({ agent, model, variant });
+      if (typeof model !== "string" || !model.includes("/"))
+        return;
+      if (!models.some((known) => known.agent === agent && known.model === model)) {
+        models.push({ agent, model, fallback });
       }
+      if (typeof variant === "string")
+        configured.push({ agent, model, variant });
     };
-    add(record.model, record.variant);
+    add(record.model, record.variant, false);
     if (Array.isArray(record.fallback_models)) {
       for (const entry of record.fallback_models)
-        add(entry, undefined);
+        add(entry, undefined, true);
     }
   }
-  if (configured.length === 0)
+  if (models.length === 0)
     return;
   const tempRoot = mkdtempSync(join32(tmpdir3(), "magic-context-opencode-catalog-"));
   try {
@@ -40585,9 +40923,14 @@ function checkConfiguredVariantCatalog(config, hostGeneration, warn, run = (args
     const result = run(command, tempRoot);
     const catalog = hostGeneration === "v2" ? parseOpenCodeV2ModelCatalog(result.stdout ?? "") : parseOpenCodeModelCatalog(result.stdout ?? "");
     if (result.error || result.status !== 0 || catalog.length === 0) {
-      warn(`Could not verify configured hidden-agent variants: this OpenCode host did not provide a readable model catalog. ${hostGeneration === "v2" ? "Start the background service with opencode service start, then check" : "Check"} ${guidance}.`);
+      warn(`Could not verify configured hidden-agent models and variants: this OpenCode host did not provide a readable model catalog. ${hostGeneration === "v2" ? "Start the background service with opencode service start, then check" : "Check"} ${guidance}.`);
       return;
     }
+    for (const entry of findUnknownConfiguredModels(models, catalog)) {
+      const [providerID] = entry.model.split("/", 1);
+      const role = `${entry.agent}${entry.fallback ? " fallback" : ""} model ${entry.model}`;
+      warn(entry.unknown === "provider" ? `${role} names provider '${providerID}', which this OpenCode host does not have. The ${entry.agent} cannot run on it; configure that provider in OpenCode or choose a model listed by ${guidance}.` : `${role} is not offered by provider '${providerID}' on this OpenCode host. The ${entry.agent} cannot run on it; choose a model listed by ${guidance}.`);
+    }
     for (const entry of findUndeclaredConfiguredVariants(configured, catalog)) {
       warn(`${entry.agent} model ${entry.model} requests variant '${entry.variant}', which this host does not offer. Remove the variant or choose one listed by ${guidance}.`);
     }
@@ -40763,7 +41106,7 @@ function getUserNpmrcPath() {
 function collectNpmReleaseAgeWarnings() {
   const ageWarnings = [];
   const npmrcPath = getUserNpmrcPath();
-  if (!existsSync37(npmrcPath))
+  if (!existsSync38(npmrcPath))
     return ageWarnings;
   try {
     const npmrc = readFileSync26(npmrcPath, "utf-8");
@@ -40900,7 +41243,7 @@ function checkLocalEmbeddingRuntimeForDoctor(runtimePreference = "auto") {
   return { issues: 0 };
 }
 async function checkEmbeddingConfig(magicContextConfigPath) {
-  if (!existsSync37(magicContextConfigPath)) {
+  if (!existsSync38(magicContextConfigPath)) {
     return checkLocalEmbeddingRuntimeForDoctor();
   }
   let rawText;
@@ -41108,7 +41451,7 @@ async function runDoctor2(options = {}) {
   const activeInstallation = installationReports[0];
   if (!activeInstallation) {
     fail("OpenCode is not installed or not in PATH");
-    log2.info("Doctor checked ~/.opencode/bin/opencode and each entry in $PATH.");
+    log2.info("Doctor checked ~/.opencode/bin/opencode, each entry in $PATH, and the OpenCode CLI bundled in OpenChamber.app.");
     log2.info("If `which opencode` succeeds outside doctor, your wrapper or shim may not be readable by Node — please share that wrapper in the issue.");
     outro2("Doctor failed — install OpenCode first");
     return 1;
@@ -41124,7 +41467,19 @@ async function runDoctor2(options = {}) {
     pass(installationReports.length > 1 ? `OpenCode ${activeInstallation.version} installed (active install marked above)` : `OpenCode ${activeInstallation.version} installed`);
   }
   const hostGeneration = openCodeHostGenerationFromVersion(activeInstallation.version);
-  const openCodeDbResolution = resolveOpenCodeDbPath(hostGeneration);
+  const storeHostSelection = selectOpenCodeStoreHost(installationReports, openCodeHostGenerationFromVersion);
+  const storeHost = storeHostSelection?.host ?? activeInstallation;
+  const storeGeneration = openCodeHostGenerationFromVersion(storeHost.version);
+  const openCodeDbResolution = resolveOpenCodeDbPath(storeGeneration);
+  if (storeHostSelection?.shadowed) {
+    const activeStore = resolveOpenCodeDbPath(hostGeneration).path;
+    const shared = activeStore === openCodeDbResolution.path;
+    const versionLabel = (version) => version.replace(/^opencode\s+v?/i, "");
+    const activeVersion = versionLabel(activeInstallation.version);
+    const storeVersion = versionLabel(storeHost.version);
+    warn(`OpenCode ${activeVersion} (${activeInstallation.path}) is first on PATH, and OpenCode ${storeVersion} is also installed (${storeHost.path})${shared ? `; both use ${openCodeDbResolution.path}` : ""}.`);
+    log2.warn(`  Store and conversion checks below use OpenCode ${storeVersion}. Plugin configuration checks use OpenCode ${activeVersion}; to check OpenCode ${storeVersion}'s configuration instead, put its binary first on PATH and run doctor again.`);
+  }
   const openCodeDbCheck = describeOpenCodeDatabaseDoctorCheck(openCodeDbResolution);
   if (openCodeDbCheck.ok)
     pass(openCodeDbCheck.message);
@@ -41148,14 +41503,16 @@ async function runDoctor2(options = {}) {
         fixed += report.repaired;
       } else if (options.fix) {
         warn(`${summary}; repaired=${report.repaired}, but some rows remain unconvertible`);
+      } else if (report.migrationCompleted) {
+        log2.info(`${summary}; OpenCode 2 already converted this store`);
       } else {
         warn(`${summary}; run \`magic-context doctor --fix\` before upgrading OpenCode`);
       }
-      if (report.recoveryRequired) {
-        const [heading, ...details] = formatOpenCodeV2ReconversionRecipe(openCodeDbResolution.path);
-        warn(heading ?? "OpenCode 2 conversion recovery is required");
-        for (const detail of details)
-          log2.warn(`  ${detail}`);
+      const notice = formatOpenCodeV2MissingMarkerNotice(report);
+      if (notice) {
+        for (const [index, line] of notice.entries()) {
+          log2.info(index === 0 ? line : `  ${line}`);
+        }
       }
     } catch (error) {
       warn(`OpenCode compaction marker conversion check unavailable: ${error instanceof Error ? error.message : String(error)}`);
@@ -41171,9 +41528,14 @@ async function runDoctor2(options = {}) {
           readonly: true,
           fileMustExist: true
         });
-        const dangling = listDanglingCompartmentBoundaries(contextDb, sessionDb, /\d/.test(activeInstallation.version) ? hostGeneration : undefined, (line) => log2.info(line));
+        const dangling = listDanglingCompartmentBoundaries(contextDb, sessionDb, /\d/.test(storeHost.version) ? storeGeneration : undefined, (line) => log2.info(line));
         if (dangling.length === 0) {
           pass("Compartment boundary ids resolve in the OpenCode session store");
+        } else if (storeGeneration === "v2" && /\d/.test(storeHost.version)) {
+          log2.info(`${dangling.length} compartment(s) point at OpenCode message ids that are not in the OpenCode 2 store. Magic Context places these from the neighbouring compartments; any it cannot place are listed as excluded from range recovery below.`);
+          for (const boundary of dangling) {
+            log2.info(`  ${formatDanglingCompartmentBoundary(boundary)}`);
+          }
         } else {
           warn(`${dangling.length} compartment(s) have dangling OpenCode boundary ids`);
           for (const boundary of dangling) {
@@ -41182,11 +41544,11 @@ async function runDoctor2(options = {}) {
         }
         if (!supportsCoordinateGenerationReporting(contextDb)) {
           log2.info("Store projection check: this context database predates the coordinate columns");
-        } else if (!/\d/.test(activeInstallation.version)) {
+        } else if (!/\d/.test(storeHost.version)) {
           log2.info("Store projection check: OpenCode reported no version, so the running projection is unknown");
         } else {
-          const pendingRebases = countPendingCoordinateRebases(contextDb, hostGeneration);
-          const pendingLine = formatPendingCoordinateRebases(pendingRebases, hostGeneration);
+          const pendingRebases = countPendingCoordinateRebases(contextDb, storeGeneration);
+          const pendingLine = formatPendingCoordinateRebases(pendingRebases, storeGeneration);
           if (pendingRebases.changed + pendingRebases.unrecorded === 0) {
             pass(pendingLine);
           } else {
@@ -41231,7 +41593,7 @@ async function runDoctor2(options = {}) {
     pass(`OpenCode config: ${paths.opencodeConfig}`);
   }
   let autoUpdateEnabled = true;
-  if (existsSync37(paths.magicContextConfig)) {
+  if (existsSync38(paths.magicContextConfig)) {
     pass(`Magic Context config: ${paths.magicContextConfig}`);
     try {
       const raw = loadRawConfigFile({ configPath: paths.magicContextConfig, tier: "user" });
@@ -41267,7 +41629,7 @@ async function runDoctor2(options = {}) {
     warn(`No magic-context.jsonc found — using defaults`);
     log2.info("  Run 'setup' to create one with model recommendations");
   }
-  if (existsSync37(paths.magicContextConfig)) {
+  if (existsSync38(paths.magicContextConfig)) {
     try {
       const raw = loadRawConfigFile({ configPath: paths.magicContextConfig, tier: "user" });
       if (!raw)
@@ -41466,7 +41828,7 @@ async function runDoctor2(options = {}) {
       pass("Added TUI sidebar plugin to tui.json");
       warn("Restart OpenCode to see the sidebar");
       fixed++;
-    } else if (existsSync37(paths.tuiConfig)) {
+    } else if (existsSync38(paths.tuiConfig)) {
       try {
         const tuiRaw = readFileSync26(paths.tuiConfig, "utf-8");
         const tuiConfig = import_comment_json11.parse(tuiRaw);
@@ -41506,7 +41868,7 @@ async function runDoctor2(options = {}) {
       fail("Could not create or verify the TUI sidebar config");
     }
   }
-  if (existsSync37(paths.magicContextConfig)) {
+  if (existsSync38(paths.magicContextConfig)) {
     try {
       const raw = loadRawConfigFile({ configPath: paths.magicContextConfig, tier: "user" });
       if (!raw)
@@ -41530,7 +41892,7 @@ async function runDoctor2(options = {}) {
   const storage = getMagicContextStorageResolution();
   const dbPath = join32(storage.path, "context.db");
   log2.info(`Shared storage: ${storage.path} (source: ${storage.source})`);
-  if (!existsSync37(dbPath)) {
+  if (!existsSync38(dbPath)) {
     log2.info(`Shared context DB not yet created at ${dbPath} (will be created on first run)`);
   } else {
     log2.info(`Shared context DB exists at ${dbPath}`);
@@ -41577,25 +41939,7 @@ ${formatDatabaseRepairGuidance(dbPath)}`);
           fail(`SQLite integrity_check failed: ${err instanceof Error ? err.message : String(err)}
 ${formatDatabaseRepairGuidance(dbPath)}`);
         }
-        try {
-          const counts = {};
-          for (const table of [
-            "tags",
-            "compartments",
-            "memories",
-            "notes",
-            "dream_runs"
-          ]) {
-            try {
-              const row = db.prepare(`SELECT COUNT(*) as c FROM ${table}`).get();
-              counts[table] = row?.c ?? 0;
-            } catch {
-              counts[table] = 0;
-            }
-          }
-          const summary = Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(", ");
-          log2.info(`Shared DB row counts: ${summary}`);
-        } catch {}
+        log2.info(`Shared DB row counts: ${formatSharedDbRowCounts(db)}`);
         for (const stall of listShadowBackfillStalls(db)) {
           warn(formatShadowBackfillStall(stall));
         }
@@ -41664,6 +42008,10 @@ ${formatDatabaseRepairGuidance(dbPath)}`);
     fixed++;
   if (v2Cache.issue)
     issues++;
+  const sharedDbVersion = readContextDbSchemaVersion(dbPath);
+  if (sharedDbVersion !== null) {
+    reportCachedPluginFences(compareCachedPluginFences(listCachedOpenCodePluginFences(), sharedDbVersion), { pass, fail, info: (message) => log2.info(message) });
+  }
   {
     const ageWarnings = collectNpmReleaseAgeWarnings();
     if (ageWarnings.length > 0) {
@@ -41676,7 +42024,11 @@ ${formatDatabaseRepairGuidance(dbPath)}`);
       issues++;
     }
   }
-  const logFiles = inspectMagicContextLogs("opencode");
+  const logHarnesses = [
+    ...hostGeneration === "v1" ? ["opencode"] : [],
+    ...hostGeneration === "v2" || storeGeneration === "v2" ? ["opencode2"] : []
+  ];
+  const logFiles = logHarnesses.flatMap((harness) => inspectMagicContextLogs(harness)).filter((file, index, all) => all.findIndex((other) => other.path === file.path) === index);
   const existingLogFiles = logFiles.filter((file) => file.exists);
   if (existingLogFiles.length === 0) {
     log2.info(`No plugin log file yet; checked: ${logFiles.map((file) => file.path).join(", ")}`);
@@ -41724,7 +42076,7 @@ ${formatDatabaseRepairGuidance(dbPath)}`);
   }
   return 0;
 }
-var import_comment_json11, CLI_PACKAGE_NAME = "@cortexkit/magic-context";
+var import_comment_json11, CLI_PACKAGE_NAME = "@cortexkit/magic-context", SHARED_DB_ROW_COUNT_TABLES;
 var init_doctor_opencode = __esm(async () => {
   init_config();
   init_agent_disable();
@@ -41768,13 +42120,15 @@ var init_doctor_opencode = __esm(async () => {
     init_storage_versions(),
     init_v22_backfill_commands(),
     init_doctor_authority(),
+    init_doctor_cached_plugin_fence(),
     init_doctor_harness_relabel()
   ]);
   import_comment_json11 = __toESM(require_src3(), 1);
+  SHARED_DB_ROW_COUNT_TABLES = ["tags", "compartments", "memories", "notes", "dream_runs"];
 });
 
 // src/lib/diagnostics-pi.ts
-import { existsSync as existsSync38, readdirSync as readdirSync7, readFileSync as readFileSync27, statSync as statSync16 } from "node:fs";
+import { existsSync as existsSync39, readdirSync as readdirSync7, readFileSync as readFileSync27, statSync as statSync16 } from "node:fs";
 import { createRequire as createRequire7 } from "node:module";
 import { join as join33 } from "node:path";
 function getSelfVersion3() {
@@ -41791,7 +42145,7 @@ function getSelfVersion3() {
 }
 function fileSize2(path) {
   try {
-    return existsSync38(path) ? statSync16(path).size : 0;
+    return existsSync39(path) ? statSync16(path).size : 0;
   } catch {
     return 0;
   }
@@ -41803,7 +42157,7 @@ function sanitizeValue2(value) {
   return sanitizeConfigValue(value);
 }
 function readJsonc(path) {
-  if (!existsSync38(path))
+  if (!existsSync39(path))
     return { value: {} };
   try {
     return {
@@ -41823,7 +42177,7 @@ function readConfigDiagnostic(path) {
   const parsed = readJsonc(path);
   return {
     path,
-    exists: existsSync38(path),
+    exists: existsSync39(path),
     ...parsed.parseError ? { parseError: parsed.parseError } : {},
     flags: sanitizeValue2(parsed.value)
   };
@@ -41841,7 +42195,7 @@ function reverseSlugToDirectory(slug) {
 }
 function collectPiRecentSessions() {
   const sessionsRoot = getPiSessionsRoot();
-  if (!existsSync38(sessionsRoot))
+  if (!existsSync39(sessionsRoot))
     return [];
   try {
     const slugs = readdirSync7(sessionsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
@@ -41910,7 +42264,7 @@ function parseHistorianDumpMeta2(path) {
   }
 }
 function listDumpsInDir2(dir, limit) {
-  if (!existsSync38(dir))
+  if (!existsSync39(dir))
     return { count: 0, recent: [] };
   try {
     const entries = readdirSync7(dir).filter((name) => name.endsWith(".xml")).map((name) => {
@@ -42004,7 +42358,7 @@ async function collectDiagnostics2(cwd = process.cwd()) {
     piVersion: pi ? getPiVersion(pi.path) : null,
     settings: {
       path: settingsPath,
-      exists: existsSync38(settingsPath),
+      exists: existsSync39(settingsPath),
       ...settingsParsed.parseError ? { parseError: settingsParsed.parseError } : {},
       hasMagicContextPackage: hasPiMagicContextPackage(packages),
       packages: sanitizeValue2(packages)
@@ -42021,7 +42375,7 @@ async function collectDiagnostics2(cwd = process.cwd()) {
     storageDir: {
       path: storageDirPath,
       source: storageResolution.source,
-      exists: existsSync38(storageDirPath),
+      exists: existsSync39(storageDirPath),
       contextDbSizeBytes: fileSize2(dbPath)
     },
     conflicts: {
@@ -42127,7 +42481,7 @@ var init_diagnostics_pi = __esm(() => {
 
 // src/lib/logs-pi.ts
 import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync9 } from "node:fs";
-import { dirname as dirname18, join as join34 } from "node:path";
+import { dirname as dirname19, join as join34 } from "node:path";
 function sanitizeLogContent2(content) {
   return sanitizeString2(content);
 }
@@ -42198,7 +42552,7 @@ async function bundleIssueReport2(report, description, title, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const timestamp = formatTimestamp2(options.now ?? new Date);
   const path = options.outputPath ?? join34(cwd, `magic-context-pi-issue-${timestamp}.md`);
-  mkdirSync10(dirname18(path), { recursive: true });
+  mkdirSync10(dirname19(path), { recursive: true });
   writeFileSync9(path, `${bodyMarkdown}
 `);
   const fullPath = truncated ? options.outputPath ? `${options.outputPath}.full.md` : join34(cwd, `magic-context-pi-issue-${timestamp}-full.md`) : undefined;
@@ -42215,10 +42569,10 @@ var init_logs_pi = __esm(() => {
 
 // src/commands/doctor-pi.ts
 import { execFileSync as execFileSync6, spawnSync as spawnSync9 } from "node:child_process";
-import { existsSync as existsSync39, mkdirSync as mkdirSync11, readdirSync as readdirSync8, readFileSync as readFileSync28, rmSync as rmSync6, statSync as statSync17 } from "node:fs";
+import { existsSync as existsSync40, mkdirSync as mkdirSync11, readdirSync as readdirSync8, readFileSync as readFileSync28, rmSync as rmSync6, statSync as statSync17 } from "node:fs";
 import { createRequire as createRequire8 } from "node:module";
 import { homedir as homedir17 } from "node:os";
-import { dirname as dirname19, isAbsolute as isAbsolute8, join as join35 } from "node:path";
+import { dirname as dirname20, isAbsolute as isAbsolute8, join as join35 } from "node:path";
 function depsFrom(options) {
   return {
     ...DEFAULT_DEPS5,
@@ -42361,13 +42715,13 @@ function piPluginDirCandidates(packages, cwd) {
   }
   dirs.push(join35(agentDir, "npm", "node_modules", PACKAGE_NAME2));
   dirs.push(join35(cwd, ".pi", "npm", "node_modules", PACKAGE_NAME2));
-  return dirs.filter((dir) => existsSync39(join35(dir, "package.json")));
+  return dirs.filter((dir) => existsSync40(join35(dir, "package.json")));
 }
 function projectConfigPath(cwd) {
   return resolveCortexKitProjectConfigPath(cwd);
 }
 function readConfigForEmbedding(path, isProjectConfig) {
-  if (!existsSync39(path))
+  if (!existsSync40(path))
     return null;
   try {
     const raw = loadRawConfigFile({
@@ -42468,7 +42822,7 @@ function cacheRoots(cwd) {
 function findPiMagicContextCacheDirs(cwd, expectedVersion, force = false) {
   const found = new Map;
   const visit = (path, depth) => {
-    if (depth < 0 || !existsSync39(path))
+    if (depth < 0 || !existsSync40(path))
       return;
     let stat;
     try {
@@ -42479,7 +42833,7 @@ function findPiMagicContextCacheDirs(cwd, expectedVersion, force = false) {
     if (!stat.isDirectory())
       return;
     const packageJson = join35(path, "package.json");
-    if (existsSync39(packageJson)) {
+    if (existsSync40(packageJson)) {
       try {
         const pkg = JSON.parse(readFileSync28(packageJson, "utf-8"));
         const name = typeof pkg.name === "string" ? pkg.name : "";
@@ -42546,7 +42900,7 @@ async function runHealthChecks2(options) {
   }
   const settingsPath = getPiUserExtensionsPath();
   let packages = [];
-  if (!existsSync39(settingsPath)) {
+  if (!existsSync40(settingsPath)) {
     add2(results, "fail", `Pi settings not found at ${settingsPath}`);
     repairPlan.addPackageEntry = true;
   } else {
@@ -42570,7 +42924,7 @@ async function runHealthChecks2(options) {
     ["user", userConfigPath, true],
     ["project", projectPath, false]
   ]) {
-    if (!existsSync39(path)) {
+    if (!existsSync40(path)) {
       if (required) {
         add2(results, "warn", `No ${label} magic-context.jsonc found at ${path}`);
         if (userConfigMigrationRefused) {
@@ -42612,7 +42966,7 @@ async function runHealthChecks2(options) {
   const storageDir = storage.path;
   const dbPath = join35(storageDir, "context.db");
   add2(results, "info", `Shared storage: ${storageDir} (source: ${storage.source})`);
-  const existedBeforeOpen = existsSync39(dbPath);
+  const existedBeforeOpen = existsSync40(dbPath);
   if (existedBeforeOpen)
     add2(results, "pass", `Shared context DB exists at ${dbPath}`);
   else
@@ -42830,7 +43184,7 @@ ${formatDatabaseRepairGuidance(dbPath)}`);
   return { results, repairPlan, ...summarize(results) };
 }
 function writeDefaultMagicContextConfig(path) {
-  mkdirSync11(dirname19(path), { recursive: true });
+  mkdirSync11(dirname20(path), { recursive: true });
   const config = {
     $schema: "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
     ...MagicContextConfigSchema.parse({})
@@ -42852,7 +43206,7 @@ function repair2(plan, prompts) {
   }
   if (plan.writeUserConfig) {
     const configPath = getPiUserConfigPath();
-    if (!existsSync39(configPath)) {
+    if (!existsSync40(configPath)) {
       try {
         writeDefaultMagicContextConfig(configPath);
         prompts.log.success(`Wrote default Magic Context config to ${configPath}`);
@@ -43104,7 +43458,7 @@ var init_doctor_pi = __esm(async () => {
 });
 
 // src/commands/doctor.ts
-import { existsSync as existsSync40, rmSync as rmSync7 } from "node:fs";
+import { existsSync as existsSync41, rmSync as rmSync7 } from "node:fs";
 import { join as join36 } from "node:path";
 async function runDoctor4(options) {
   if (options.clear)
@@ -43251,7 +43605,7 @@ async function runClear() {
           failed += 1;
           continue;
         }
-      } else if (existsSync40(item.path)) {
+      } else if (existsSync41(item.path)) {
         rmSync7(item.path, { recursive: true, force: true });
       }
       s.stop(`Cleared ${item.path}`);
@@ -43288,9 +43642,121 @@ var init_doctor = __esm(async () => {
 });
 
 // src/index.ts
-init_prompts();
 import { createRequire as createRequire9 } from "node:module";
 
+// src/lib/cli-help.ts
+var HELP_FLAGS = new Set(["--help", "-h"]);
+function hasHelpFlag(args) {
+  return args.some((arg) => HELP_FLAGS.has(arg));
+}
+var DOCTOR_SUBCOMMANDS_WITH_OWN_HELP = new Set([
+  "migrate",
+  "migrate-session",
+  "repair-db"
+]);
+var HARNESS_LINES = [
+  "  Harness selection:",
+  "    --harness opencode    Target OpenCode only",
+  "    --harness pi          Target Pi only",
+  "    --harness omp         Target Oh My Pi (OMP) only",
+  "    (default: auto-detect, prompt if multiple installed)"
+];
+var SETUP_HELP = [
+  "",
+  "  Usage: magic-context setup [--harness opencode|pi|omp] [--dry-run]",
+  "",
+  "  Interactive setup wizard: registers the Magic Context plugin with the",
+  "  selected harness and writes its Magic Context config.",
+  "",
+  "  Options:",
+  "    --dry-run             Preview the wizard without writing any files",
+  ...HARNESS_LINES,
+  ""
+].join(`
+`);
+var DOCTOR_HELP = [
+  "",
+  "  Usage: magic-context doctor [options]",
+  "         magic-context doctor <subcommand> [options]",
+  "",
+  "  Check the installed harnesses and fix configuration issues.",
+  "",
+  "  Options:",
+  "    --fix                               Repair safe, Magic Context-owned store rows and clear an outdated OpenCode 2 plugin cache",
+  "    --force                             Force-clear the plugin cache",
+  "    --clear                             Interactive cache cleanup picker",
+  "    --issue                             Collect diagnostics and open a GitHub issue",
+  "    --report <path>                     Write the issue diagnostics to <path> without prompting",
+  "    --check-v22-backfill                Show v22 memory backfill status",
+  "    --retry-v22-backfill                Retry failed v22 memory backfill rows",
+  "    --rekey-v22-dir-identity <path>     Re-key legacy dir identity rows",
+  ...HARNESS_LINES,
+  "",
+  "  Subcommands (each accepts --help):",
+  "    drain-authority <project>   Drain module memory/note authority back to TypeScript",
+  "    migrate                     Migrate an OpenCode session to Pi or OMP JSONL",
+  "    migrate-session             Re-home an OpenCode session to another directory",
+  "    merge-identity              Merge project rows between identities",
+  "    repair-db                   Back up and salvage a corrupted shared database",
+  "    list-hidden-sessions        List Magic Context OpenCode 2 roots",
+  ""
+].join(`
+`);
+var DRAIN_AUTHORITY_HELP = [
+  "",
+  "  Usage: magic-context doctor drain-authority <project>",
+  "",
+  "  Drain the module's memory and note authority for <project> back to TypeScript.",
+  ""
+].join(`
+`);
+var MERGE_IDENTITY_HELP = [
+  "",
+  "  Usage: magic-context doctor merge-identity --from <identity> --to <identity> [--dry-run] [--yes] [--db <path>]",
+  "",
+  "  Merge every project-scoped row from one project identity into another.",
+  "",
+  "  Options:",
+  "    --from <identity>   Identity whose rows are moved",
+  "    --to <identity>     Identity that receives them",
+  "    --dry-run           Report what would change without writing",
+  "    --yes               Confirm the write (required unless --dry-run)",
+  "    --db <path>         Use this context.db instead of the shared one",
+  ""
+].join(`
+`);
+var LIST_HIDDEN_SESSIONS_HELP = [
+  "",
+  "  Usage: magic-context doctor list-hidden-sessions",
+  "",
+  "  List the hidden OpenCode 2 root sessions Magic Context reuses for its",
+  "  historian and dreamer runs. Read-only.",
+  ""
+].join(`
+`);
+function subcommandHelp(argv) {
+  const [command, ...rest] = argv;
+  if (!hasHelpFlag(rest))
+    return null;
+  if (command === "setup")
+    return SETUP_HELP;
+  if (command !== "doctor")
+    return null;
+  const subcommand = rest[0];
+  if (subcommand === "drain-authority")
+    return DRAIN_AUTHORITY_HELP;
+  if (subcommand === "merge-identity")
+    return MERGE_IDENTITY_HELP;
+  if (subcommand === "list-hidden-sessions")
+    return LIST_HIDDEN_SESSIONS_HELP;
+  if (subcommand !== undefined && DOCTOR_SUBCOMMANDS_WITH_OWN_HELP.has(subcommand))
+    return null;
+  return DOCTOR_HELP;
+}
+
+// src/index.ts
+init_prompts();
+
 // src/lib/sqlite-preflight.ts
 async function probeSqliteBackend() {
   await init_sqlite().then(() => ({}));
@@ -43300,7 +43766,7 @@ function formatSqlitePreflightFailure(error) {
   return [
     "Magic Context doctor cannot use SQLite in this runtime.",
     `SQLite probe: ${detail}`,
-    "Remediation: install Node.js >= 24 or use a Bun build with node:sqlite.",
+    "Remediation: install Node.js 22.16+ (22.x) or >= 24, or use a Bun build with node:sqlite.",
     "For Docker, use node:24-slim or a two-runtime image."
   ].join(`
 `);
@@ -43367,6 +43833,7 @@ function printUsage() {
   console.log("    (default: auto-detect, prompt if multiple installed)");
   console.log("");
   console.log("  Usage:");
+  console.log("    npx @cortexkit/magic-context@latest <command> --help   # help for one command");
   console.log("    npx @cortexkit/magic-context@latest setup");
   console.log("        # add --dry-run to preview the wizard without writing any files");
   console.log("    npx @cortexkit/magic-context@latest doctor");
@@ -43386,6 +43853,11 @@ async function main(argv = process.argv.slice(2)) {
   }
   const command = argv[0];
   const rest = argv.slice(1);
+  const help = subcommandHelp(argv);
+  if (help !== null) {
+    console.log(help);
+    return 0;
+  }
   try {
     if (command === "setup") {
       await Promise.resolve().then(() => init_setup());