fix: use bunx --bun to avoid node shebang delegation, add min-release-age detection, promote compaction_markers to stable config, respect pinned plugin versions in doctor

Author: ualtinok

CONFIGURATION.md

@@ -19,7 +19,7 @@ The setup wizard adds this automatically.
 If something isn't working, run the doctor to auto-detect and fix common issues:
 
 ```bash
-bunx @cortexkit/opencode-magic-context@latest doctor
+bunx --bun @cortexkit/opencode-magic-context@latest doctor
 ```
 
 Doctor checks: OpenCode installation, plugin registration, `magic-context.jsonc` existence, conflicts (compaction, DCP, OMO hooks), and TUI sidebar configuration. It auto-fixes what it can.
@@ -71,6 +71,7 @@ Higher-tier models with longer cache windows benefit from a longer TTL. Setting
 | `compartment_token_budget` | `number` | `20000` | Token budget for historian input chunks. |
 | `historian_timeout_ms` | `number` | `300000` | Timeout per historian call (ms). |
 | `history_budget_percentage` | `number` (0–1) | `0.15` | Fraction of usable context reserved for the history block. Triggers compression when exceeded. |
+| `compaction_markers` | `boolean` | `true` | Inject compaction boundaries into OpenCode's DB after historian publishes. Reduces transform input size for long sessions. |
 | `commit_cluster_trigger` | `object` | See below | Controls the commit-cluster historian trigger. |
 
 ### `commit_cluster_trigger`
@@ -268,14 +269,6 @@ It is useful when starting a new session. It's better to choose a fast and cheap
 
 ## Experimental Features
 
-### `experimental_compaction_markers`
-
-| Key | Type | Default |
-|-----|------|---------|
-| `experimental.compaction_markers` | `boolean` | `false` |
-
-When enabled, after historian publishes compartments a compaction boundary is injected into OpenCode's message/part tables. This causes `filterCompacted` to stop at the boundary, dramatically reducing the number of messages processed per transform pass.
-
 ### `experimental_user_memories`
 
 | Key | Type | Default |
@@ -332,6 +325,7 @@ When enabled, dreamer analyzes which files each session's agent reads most frequ
   "protected_tags": 10,
   "auto_drop_tool_age": 50,
   "history_budget_percentage": 0.15,
+  "compaction_markers": true,
 
   "historian": {
     "model": "github-copilot/gpt-5.4",
@@ -364,7 +358,6 @@ When enabled, dreamer analyzes which files each session's agent reads most frequ
   },
 
   "experimental": {
-    "compaction_markers": false,
     "user_memories": {
       "enabled": false,
       "promotion_threshold": 3

README.md

@@ -70,7 +70,7 @@ irm https://raw.githubusercontent.com/cortexkit/opencode-magic-context/master/sc
 
 **Or run directly (any OS):**
 ```bash
-bunx @cortexkit/opencode-magic-context@latest setup
+bunx --bun @cortexkit/opencode-magic-context@latest setup
 ```
 
 The wizard will:
@@ -136,21 +136,21 @@ The setup wizard handles this automatically if it detects an oh-my-openagent or
 Already installed but something isn't working? Run the doctor to check and auto-fix configuration issues:
 
 ```bash
-bunx @cortexkit/opencode-magic-context@latest doctor
+bunx --bun @cortexkit/opencode-magic-context@latest doctor
 ```
 
 Doctor checks for conflicts (compaction, DCP, OMO hooks), ensures the TUI sidebar is configured, verifies the plugin is registered, and checks the npm cache — fixing what it can automatically.
 
 Use `--force` to force-clear the plugin cache even when versions match (fixes broken transitive dependencies):
 
 ```bash
-bunx @cortexkit/opencode-magic-context@latest doctor --force
+bunx --bun @cortexkit/opencode-magic-context@latest doctor --force
 ```
 
 Hit a real bug? Use `--issue` to collect environment, sanitized config, and the last 200 log lines into a ready-to-submit report. It can also open the issue directly via `gh` if you have it installed:
 
 ```bash
-bunx @cortexkit/opencode-magic-context@latest doctor --issue
+bunx --bun @cortexkit/opencode-magic-context@latest doctor --issue
 ```
 
 ---
@@ -312,7 +312,7 @@ The TUI plugin is configured automatically by the setup wizard and the `doctor`
 
 ### Startup conflict detection
 
-On startup, Magic Context checks for common configuration problems — OpenCode's built-in compaction being enabled, DCP plugin being active alongside Magic Context, or conflicting oh-my-openagent hooks. When conflicts are detected, it warns the active session with a fix suggestion pointing to `bunx @cortexkit/opencode-magic-context@latest doctor`.
+On startup, Magic Context checks for common configuration problems — OpenCode's built-in compaction being enabled, DCP plugin being active alongside Magic Context, or conflicting oh-my-openagent hooks. When conflicts are detected, it warns the active session with a fix suggestion pointing to `bunx --bun @cortexkit/opencode-magic-context@latest doctor`.
 
 ---
 

STRUCTURE.md

@@ -75,7 +75,7 @@
 
 ## Key File Locations
 
-**Entry Points:** `src/index.ts`: Register the plugin, hidden agents, hooks, tools, and commands. `src/cli/index.ts`: CLI binary entry for `bunx @cortexkit/opencode-magic-context setup`.
+**Entry Points:** `src/index.ts`: Register the plugin, hidden agents, hooks, tools, and commands. `src/cli/index.ts`: CLI binary entry for `bunx --bun @cortexkit/opencode-magic-context setup`.
 
 **Configuration:** `src/config/index.ts`: Load and merge config files; `src/config/schema/magic-context.ts`: define defaults and schema rules.
 

packages/dashboard/src/components/ConfigEditor/ConfigEditor.tsx

@@ -65,6 +65,7 @@ const FIELD_DEFS: FieldDef[] = [
   { key: "enabled", label: "Enabled", type: "boolean", description: "Enable the magic-context plugin", section: "General" },
   { key: "ctx_reduce_enabled", label: "Agent Controlled Reduction", type: "boolean", description: "Enable agent controlled reductions via ctx_reduce tool. When enabled, agent is prompted and nudged to choose what messages and tool calls to drop periodically. If disabled the system still works via auto drops based on message ages.", section: "General" },
   { key: "drop_tool_structure", label: "Drop Tool Structure", type: "boolean", description: "When enabled, dropped tool calls are fully removed. When disabled, tool input/output is truncated in place so tool structure stays visible.", section: "General", defaultValue: false },
+  { key: "compaction_markers", label: "Compaction Markers", type: "boolean", description: "Inject boundary into OpenCode's DB so transform only processes the live tail after historian compaction. Significantly reduces transform input size for long sessions.", section: "General", defaultValue: true },
   // Thresholds
   // cache_ttl and execute_threshold_percentage are rendered as custom PerModelField components
   { key: "nudge_interval_tokens", label: "Nudge Interval (tokens)", type: "number", description: "Token interval between rolling ctx_reduce nudges.", section: "General" },
@@ -853,12 +854,10 @@ function ConfigForm(props: {
           {/* Experimental Features */}
           {(() => {
             const exp = () => (getNestedValue(formData(), "experimental") as {
-              compaction_markers?: boolean;
               user_memories?: { enabled?: boolean; promotion_threshold?: number };
               pin_key_files?: { enabled?: boolean; token_budget?: number; min_reads?: number };
             } | undefined) ?? {};
 
-            const compactionMarkers = () => exp().compaction_markers ?? false;
             const userMemEnabled = () => exp().user_memories?.enabled ?? false;
             const userMemThreshold = () => exp().user_memories?.promotion_threshold ?? 3;
             const pinEnabled = () => exp().pin_key_files?.enabled ?? false;
@@ -867,9 +866,7 @@ function ConfigForm(props: {
 
             const updateExp = (path: string, value: unknown) => {
               const current = exp();
-              if (path === "compaction_markers") {
-                handleFieldChange("experimental", { ...current, compaction_markers: value });
-              } else if (path.startsWith("user_memories.")) {
+              if (path.startsWith("user_memories.")) {
                 const um = current.user_memories ?? { enabled: false, promotion_threshold: 3 };
                 const field = path.split(".")[1];
                 handleFieldChange("experimental", { ...current, user_memories: { ...um, [field]: value } });
@@ -887,21 +884,8 @@ function ConfigForm(props: {
                   <span class="config-card-title">Experimental</span>
                 </div>
                 <div class="config-card-two-col">
-                  {/* Left column: Compaction Markers + User Memories */}
+                  {/* Left column: User Memories */}
                   <div class="config-card-content">
-                    <div class="config-field">
-                      <div class="config-field-header">
-                        <label class="config-field-label">Compaction Markers</label>
-                        <span class="config-field-key">experimental.compaction_markers</span>
-                      </div>
-                      <span class="config-field-desc">Inject boundary into OpenCode's DB so transform only processes the live tail</span>
-                      <label class="toggle-switch">
-                        <input type="checkbox" checked={compactionMarkers()} onChange={(e) => updateExp("compaction_markers", e.currentTarget.checked)} />
-                        <span class="toggle-slider" />
-                        <span class="toggle-label">{compactionMarkers() ? "Enabled" : "Disabled"}</span>
-                      </label>
-                    </div>
-
                     <div class="config-field">
                       <div class="config-field-header">
                         <label class="config-field-label">User Memories</label>
@@ -1084,7 +1068,7 @@ export default function ConfigEditor(props: { models: string[] }) {
               <div class="empty-state">
                 <span class="empty-state-icon">⚙️</span>
                 <span>No user config found at {userConfig()?.path}</span>
-                <span style={{ "font-size": "11px" }}>Run <code>bunx @cortexkit/opencode-magic-context setup</code> to create one</span>
+                <span style={{ "font-size": "11px" }}>Run <code>bunx --bun @cortexkit/opencode-magic-context setup</code> to create one</span>
               </div>
             }>
               <ConfigForm

packages/plugin/src/cli/doctor.ts

@@ -70,7 +70,7 @@ async function clearPluginCache(force = false): Promise<{
         // Can't read cached version — proceed with clearing
     }
 
-    // Compare against our own version — when running via `bunx @cortexkit/opencode-magic-context@latest doctor`,
+    // Compare against our own version — when running via `bunx --bun @cortexkit/opencode-magic-context@latest doctor`,
     // our package.json IS the latest published version. No network call needed.
     // Try multiple relative paths to handle both src/ and dist/ build output locations.
     const require = createRequire(import.meta.url);
@@ -240,6 +240,40 @@ export async function runDoctor(
         log.info("  Run 'setup' to create one with model recommendations");
     }
 
+    // 3b. Migrate deprecated experimental config keys in magic-context.jsonc
+    if (existsSync(paths.magicContextConfig)) {
+        try {
+            const mcRaw = readFileSync(paths.magicContextConfig, "utf-8");
+            const mcConfig = parse(mcRaw) as Record<string, unknown>;
+            let mcChanged = false;
+
+            // Migrate experimental.compaction_markers → top-level compaction_markers
+            const experimental = mcConfig.experimental as Record<string, unknown> | undefined;
+            if (experimental && "compaction_markers" in experimental) {
+                if (!("compaction_markers" in mcConfig)) {
+                    // Promote value to top level only if not already set
+                    mcConfig.compaction_markers = experimental.compaction_markers;
+                }
+                delete experimental.compaction_markers;
+                mcChanged = true;
+                // Clean up empty experimental object
+                if (Object.keys(experimental).length === 0) {
+                    delete mcConfig.experimental;
+                }
+                log.success(
+                    "Migrated experimental.compaction_markers → compaction_markers (now default: true)",
+                );
+                fixed++;
+            }
+
+            if (mcChanged) {
+                writeFileSync(paths.magicContextConfig, `${stringify(mcConfig, null, 2)}\n`);
+            }
+        } catch {
+            log.warn("Could not migrate deprecated config keys in magic-context.jsonc");
+        }
+    }
+
     // 4. Check plugin is in opencode.json
     if (paths.opencodeConfigFormat !== "none") {
         try {
@@ -260,15 +294,27 @@ export async function runDoctor(
             if (existingIdx >= 0 && pluginList[existingIdx] === PLUGIN_ENTRY_WITH_VERSION) {
                 log.success(`Plugin registered in ${configName}`);
             } else if (existingIdx >= 0) {
-                // Upgrade pinned/versionless entry to @latest
                 const oldEntry = pluginList[existingIdx];
-                pluginList[existingIdx] = PLUGIN_ENTRY_WITH_VERSION;
-                config.plugin = pluginList;
-                writeFileSync(paths.opencodeConfig, `${stringify(config, null, 2)}\n`);
-                log.success(
-                    `Upgraded plugin entry in ${configName}: ${oldEntry} → ${PLUGIN_ENTRY_WITH_VERSION}`,
-                );
-                fixed++;
+                const isPinned =
+                    oldEntry !== PLUGIN_NAME &&
+                    oldEntry !== PLUGIN_ENTRY_WITH_VERSION &&
+                    /^@cortexkit\/opencode-magic-context@\d/.test(oldEntry);
+
+                if (isPinned && !options.force) {
+                    // Warn but don't change — user intentionally pinned
+                    log.warn(
+                        `Plugin pinned to ${oldEntry} in ${configName} — use 'doctor --force' to upgrade`,
+                    );
+                } else {
+                    // Upgrade versionless entry to @latest, or --force upgrades pinned
+                    pluginList[existingIdx] = PLUGIN_ENTRY_WITH_VERSION;
+                    config.plugin = pluginList;
+                    writeFileSync(paths.opencodeConfig, `${stringify(config, null, 2)}\n`);
+                    log.success(
+                        `Upgraded plugin entry in ${configName}: ${oldEntry} → ${PLUGIN_ENTRY_WITH_VERSION}`,
+                    );
+                    fixed++;
+                }
             } else {
                 // Auto-add plugin entry — preserves comments
                 pluginList.push(PLUGIN_ENTRY_WITH_VERSION);
@@ -312,13 +358,46 @@ export async function runDoctor(
         log.success("Added TUI sidebar plugin to tui.json");
         log.warn("Restart OpenCode to see the sidebar");
         fixed++;
-    } else {
-        // Check if it's already there vs missing tui.json entirely
-        if (existsSync(paths.tuiConfig)) {
+    } else if (existsSync(paths.tuiConfig)) {
+        // Check for pinned version in tui config
+        try {
+            const tuiRaw = readFileSync(paths.tuiConfig, "utf-8");
+            const tuiConfig = parse(tuiRaw) as Record<string, unknown>;
+            const tuiPlugins = Array.isArray(tuiConfig?.plugin)
+                ? (tuiConfig.plugin as unknown[]).filter((p): p is string => typeof p === "string")
+                : [];
+            const tuiIdx = tuiPlugins.findIndex(
+                (p) => p === PLUGIN_NAME || p.startsWith(`${PLUGIN_NAME}@`),
+            );
+            if (tuiIdx >= 0) {
+                const tuiEntry = tuiPlugins[tuiIdx];
+                const tuiPinned =
+                    tuiEntry !== PLUGIN_NAME &&
+                    tuiEntry !== PLUGIN_ENTRY_WITH_VERSION &&
+                    /^@cortexkit\/opencode-magic-context@\d/.test(tuiEntry);
+                if (tuiPinned && !options.force) {
+                    log.warn(
+                        `TUI plugin pinned to ${tuiEntry} — use 'doctor --force' to upgrade`,
+                    );
+                } else if (tuiPinned && options.force) {
+                    tuiPlugins[tuiIdx] = PLUGIN_ENTRY_WITH_VERSION;
+                    tuiConfig.plugin = tuiPlugins;
+                    writeFileSync(paths.tuiConfig, `${stringify(tuiConfig, null, 2)}\n`);
+                    log.success(
+                        `Upgraded TUI plugin: ${tuiEntry} → ${PLUGIN_ENTRY_WITH_VERSION}`,
+                    );
+                    fixed++;
+                } else {
+                    log.success("TUI sidebar plugin configured");
+                }
+            } else {
+                log.success("TUI sidebar plugin configured");
+            }
+        } catch {
             log.success("TUI sidebar plugin configured");
-        } else {
-            log.success("TUI sidebar plugin configured (tui.json created)");
         }
+    } else {
+        log.success("TUI sidebar plugin configured (tui.json created)");
     }
 
     // 7. Check user memories + dreamer compatibility
@@ -364,7 +443,67 @@ export async function runDoctor(
         log.success("Plugin cache clean (no cached version found)");
     }
 
-    // 9. Show diagnostics info (log file, historian dumps)
+    // 9. Check for min-release-age / minimumReleaseAge restrictions
+    // OpenCode uses @npmcli/arborist (npm core) to install plugins, so .npmrc
+    // restrictions apply. Bun's bunfig.toml is checked too for users who install
+    // via bunx manually.
+    {
+        const ageWarnings: string[] = [];
+
+        // Check ~/.npmrc for min-release-age or before
+        const npmrcPath = join(homedir(), ".npmrc");
+        if (existsSync(npmrcPath)) {
+            try {
+                const npmrc = readFileSync(npmrcPath, "utf-8");
+                for (const line of npmrc.split("\n")) {
+                    const trimmed = line.trim();
+                    if (trimmed.startsWith("#") || trimmed.startsWith(";")) continue;
+                    const [key] = trimmed.split("=").map((s) => s.trim());
+                    if (key === "min-release-age" || key === "before") {
+                        ageWarnings.push(`~/.npmrc has '${trimmed}'`);
+                    }
+                }
+            } catch {
+                // Can't read .npmrc — skip
+            }
+        }
+
+        // Check ~/.bunfig.toml for minimumReleaseAge
+        const bunfigPath = join(homedir(), ".bunfig.toml");
+        if (existsSync(bunfigPath)) {
+            try {
+                const bunfig = readFileSync(bunfigPath, "utf-8");
+                for (const line of bunfig.split("\n")) {
+                    const trimmed = line.trim();
+                    if (trimmed.startsWith("#")) continue;
+                    if (/minimumReleaseAge\s*=/.test(trimmed)) {
+                        ageWarnings.push(`~/.bunfig.toml has '${trimmed}'`);
+                    }
+                }
+            } catch {
+                // Can't read bunfig — skip
+            }
+        }
+
+        if (ageWarnings.length > 0) {
+            log.warn(
+                "Package manager min-release-age restriction detected — this can prevent OpenCode from installing the latest plugin version",
+            );
+            for (const w of ageWarnings) {
+                log.info(`  ${w}`);
+            }
+            log.info(
+                "  If the plugin stays on an old version after doctor --force, this is the likely cause.",
+            );
+            log.info(
+                "  Workaround: temporarily remove the restriction, restart OpenCode, then re-enable it.",
+            );
+            issues++;
+        }
+    }
+
+    // 10. Show diagnostics info (log file, historian dumps)
+
     const logPath = join(tmpdir(), "magic-context.log");
     if (existsSync(logPath)) {
         const logStat = statSync(logPath);
@@ -400,7 +539,7 @@ export async function runDoctor(
         }
     }
 
-    // 10. Check OMO config
+    // 11. Check OMO config
     if (paths.omoConfig) {
         log.info(`OMO config found: ${paths.omoConfig}`);
     }