@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/conflict-detector.test.ts

@@ -0,0 +1,780 @@
+/// <reference types="bun-types" />
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { detectConflicts } from "./conflict-detector";
+import { cleanupTestTempDir, createTestTempDir } from "./test-temp-dir";
+
+/**
+ * Regression tests for plugin-conflict detection. The previous substring-
+ * based matcher misclassified `oh-my-opencode-slim` and `opencode-dcp-fork`
+ * as the canonical plugins, causing magic-context to disable itself with
+ * a false-positive conflict warning. See issue #43.
+ */
+describe("detectConflicts", () => {
+    let root: string;
+    let projectDir: string;
+    let userConfigDir: string;
+    let homeDir: string;
+    let originalEnv: Record<string, string | undefined>;
+
+    beforeEach(() => {
+        root = createTestTempDir("mc-conflict-").dir;
+        projectDir = join(root, "project");
+        mkdirSync(projectDir, { recursive: true });
+        userConfigDir = join(root, "user-config", "opencode");
+        mkdirSync(userConfigDir, { recursive: true });
+        homeDir = join(root, "home");
+        mkdirSync(homeDir, { recursive: true });
+
+        // Save and override every env var that affects config-path resolution.
+        // OPENCODE_CONFIG_DIR takes precedence over XDG_CONFIG_HOME, so we set
+        // it directly and clear XDG to fully isolate from any inherited or
+        // test-leaked state.
+        originalEnv = {
+            OPENCODE_CONFIG_DIR: process.env.OPENCODE_CONFIG_DIR,
+            XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+            OPENCODE_DISABLE_AUTOCOMPACT: process.env.OPENCODE_DISABLE_AUTOCOMPACT,
+            HOME: process.env.HOME,
+        };
+        process.env.OPENCODE_CONFIG_DIR = userConfigDir;
+        process.env.HOME = homeDir;
+        delete process.env.XDG_CONFIG_HOME;
+        // Disable auto-compaction default during tests so we isolate plugin
+        // detection from compaction detection.
+        process.env.OPENCODE_DISABLE_AUTOCOMPACT = "1";
+    });
+
+    afterEach(() => {
+        for (const [k, v] of Object.entries(originalEnv)) {
+            if (v === undefined) delete process.env[k];
+            else process.env[k] = v;
+        }
+        cleanupTestTempDir(root);
+    });
+
+    function writeProjectConfig(plugins: Array<string | [string, unknown]>): void {
+        writeFileSync(join(projectDir, "opencode.json"), JSON.stringify({ plugin: plugins }));
+    }
+
+    // --- DCP detection ---
+
+    describe("DCP detection", () => {
+        it("matches the canonical @tarquinen/opencode-dcp package", () => {
+            writeProjectConfig(["@tarquinen/opencode-dcp"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(true);
+        });
+
+        it("matches the canonical package with a version suffix", () => {
+            writeProjectConfig(["@tarquinen/opencode-dcp@latest"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(true);
+        });
+
+        it("matches with a semver range suffix", () => {
+            writeProjectConfig(["@tarquinen/opencode-dcp@^3.1.0"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(true);
+        });
+
+        it("does NOT match a fork with a different package name", () => {
+            writeProjectConfig(["@some-fork/opencode-dcp-fork"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(false);
+        });
+
+        it("does NOT match a file:// path that contains 'opencode-dcp'", () => {
+            writeProjectConfig(["file:///home/user/work/opencode-dcp-fork"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(false);
+        });
+    });
+
+    // --- OMO detection (the issue #43 case) ---
+
+    describe("OMO detection", () => {
+        it("matches the canonical oh-my-opencode package", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const result = detectConflicts(projectDir);
+            // No OMO config = hooks default ACTIVE = all three flagged
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+            expect(result.conflicts.omoContextWindowMonitor).toBe(true);
+            expect(result.conflicts.omoAnthropicRecovery).toBe(true);
+        });
+
+        it("matches the canonical oh-my-openagent package alias", () => {
+            writeProjectConfig(["oh-my-openagent"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+        });
+
+        it("matches a canonical OMO with a version suffix", () => {
+            writeProjectConfig(["oh-my-opencode@3.17.5", "oh-my-openagent@latest"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+            expect(result.conflicts.omoContextWindowMonitor).toBe(true);
+            expect(result.conflicts.omoAnthropicRecovery).toBe(true);
+        });
+
+        it("does NOT match oh-my-opencode-slim (issue #43)", () => {
+            writeProjectConfig(["oh-my-opencode-slim"]);
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(false);
+            expect(result.conflicts.omoContextWindowMonitor).toBe(false);
+            expect(result.conflicts.omoAnthropicRecovery).toBe(false);
+        });
+
+        it("does NOT match oh-my-opencode-slim with a version suffix (issue #43)", () => {
+            writeProjectConfig(["oh-my-opencode-slim@latest", "oh-my-opencode-slim@1.0.3"]);
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("does NOT match a file:// path containing 'oh-my-opencode' (issue #43)", () => {
+            writeProjectConfig(["file:///home/user/workspace/oh-my-opencode-slim-dev"]);
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("does NOT match other forks under different package names", () => {
+            writeProjectConfig([
+                "oh-my-opencode-cli",
+                "@some-org/oh-my-opencode-fork",
+                "my-oh-my-opencode-customizations",
+            ]);
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("still detects canonical OMO when slim is also installed", () => {
+            // A user running both slim and the real OMO should still get
+            // the conflict warning for the real one.
+            writeProjectConfig(["oh-my-opencode-slim", "oh-my-opencode@latest"]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+        });
+
+        it("respects disabled_hooks in project-level OMO config (old format)", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            // Use project-scoped OMO config to avoid relying on user
+            // config-path resolution, which can be leaked across files
+            // by `spyOn(getOpenCodeConfigPaths)` mocks in sibling tests.
+            writeFileSync(
+                join(projectDir, "oh-my-opencode.json"),
+                JSON.stringify({
+                    disabled_hooks: [
+                        "preemptive-compaction",
+                        "context-window-monitor",
+                        "anthropic-context-window-limit-recovery",
+                    ],
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        // --- New unified omo.jsonc (oh-my-openagent >= 4.19.0) ---
+
+        it("detects disabled_hooks in new ~/.omo/omo.jsonc (user-level)", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const omoDir = join(homeDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.jsonc"),
+                JSON.stringify({
+                    "[opencode]": {
+                        disabled_hooks: [
+                            "preemptive-compaction",
+                            "context-window-monitor",
+                            "anthropic-context-window-limit-recovery",
+                        ],
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("detects disabled_hooks in new .omo/omo.jsonc (project-level)", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const omoDir = join(projectDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.jsonc"),
+                JSON.stringify({
+                    "[opencode]": {
+                        disabled_hooks: [
+                            "preemptive-compaction",
+                            "context-window-monitor",
+                            "anthropic-context-window-limit-recovery",
+                        ],
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("detects hooks as active when new omo.jsonc has no disabled_hooks", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const omoDir = join(homeDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.jsonc"),
+                JSON.stringify({
+                    "[opencode]": {
+                        // No disabled_hooks — hooks default ACTIVE
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+            expect(result.conflicts.omoContextWindowMonitor).toBe(true);
+            expect(result.conflicts.omoAnthropicRecovery).toBe(true);
+        });
+
+        it("reads disabled_hooks from both old and new config paths", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            // Old path: only disables preemptive-compaction
+            writeFileSync(
+                join(projectDir, "oh-my-opencode.json"),
+                JSON.stringify({
+                    disabled_hooks: ["preemptive-compaction"],
+                }),
+            );
+            // New path: disables the other two
+            const omoDir = join(homeDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.jsonc"),
+                JSON.stringify({
+                    "[opencode]": {
+                        disabled_hooks: [
+                            "context-window-monitor",
+                            "anthropic-context-window-limit-recovery",
+                        ],
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            // All three are disabled across both configs
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("reads omo.json (fallback) when omo.jsonc does not exist", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const omoDir = join(homeDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.json"),
+                JSON.stringify({
+                    "[opencode]": {
+                        disabled_hooks: [
+                            "preemptive-compaction",
+                            "context-window-monitor",
+                            "anthropic-context-window-limit-recovery",
+                        ],
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("ignores new omo.jsonc when OMO is not installed", () => {
+            writeProjectConfig([]);
+            const omoDir = join(homeDir, ".omo");
+            mkdirSync(omoDir, { recursive: true });
+            writeFileSync(
+                join(omoDir, "omo.jsonc"),
+                JSON.stringify({
+                    "[opencode]": {
+                        disabled_hooks: ["preemptive-compaction"],
+                    },
+                }),
+            );
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+    });
+
+    // --- Combined / control cases ---
+
+    it("returns no conflicts for an empty plugin list", () => {
+        writeProjectConfig([]);
+        const result = detectConflicts(projectDir);
+        expect(result.hasConflict).toBe(false);
+    });
+
+    it("returns no conflicts for unrelated plugins", () => {
+        writeProjectConfig(["@retaw106/mmc-oc@latest", "some-other-plugin"]);
+        const result = detectConflicts(projectDir);
+        expect(result.hasConflict).toBe(false);
+    });
+
+    // --- Tuple plugin entries (issue #49) ---
+    // OpenCode supports ["pkg@version", { ...options }] tuple form.
+    // The old code spread the raw array into the plugin list, causing
+    // matchesPackageName to receive an array instead of a string → crash.
+
+    describe("tuple plugin entries (issue #49)", () => {
+        it("does not crash when a plugin is defined as a [name, options] tuple", () => {
+            writeProjectConfig([
+                "@retaw106/mmc-oc@latest",
+                ["@plannotator/opencode@latest", { workflow: "plan-agent" }],
+            ]);
+            expect(() => detectConflicts(projectDir)).not.toThrow();
+        });
+
+        it("detects DCP conflict when DCP is expressed as a tuple", () => {
+            writeProjectConfig(["@retaw106/mmc-oc@latest", ["@tarquinen/opencode-dcp@latest", {}]]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.dcpPlugin).toBe(true);
+        });
+
+        it("detects OMO conflict when OMO is expressed as a tuple", () => {
+            writeProjectConfig([["oh-my-opencode@latest", {}]]);
+            const result = detectConflicts(projectDir);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+        });
+
+        it("does not crash on mixed string and tuple entries with unrelated packages", () => {
+            writeProjectConfig([
+                "oh-my-opencode-slim",
+                [
+                    "@plannotator/opencode@latest",
+                    { workflow: "plan-agent", planningAgents: ["plan"] },
+                ],
+                "@retaw106/mmc-oc@latest",
+            ]);
+            const result = detectConflicts(projectDir);
+            expect(result.hasConflict).toBe(false);
+        });
+    });
+
+    // --- Compaction-off mode matrix (issue #266 S2) ---
+    // The detector must NOT flag OpenCode compaction.auto=true / prune=true as
+    // a plugin-disabling conflict when MC compaction is OFF (compaction-off
+    // mode), or compaction-off users get a DISABLED plugin — the exact inverse
+    // of intent. With MC compaction ON, today's conflict behavior is unchanged.
+    //
+    // The 2x2 matrix: MC mode (on/off) x native compaction.auto (true/false).
+    // Each case asserts BOTH the conflict verdict AND the plugin-enabled
+    // outcome (the boot path disables the plugin when hasConflict).
+    describe("compaction-off mode matrix (issue #266)", () => {
+        // The suite beforeEach sets OPENCODE_DISABLE_AUTOCOMPACT=1 to isolate
+        // plugin detection from compaction detection. These matrix tests
+        // exercise compaction detection directly, so they clear that env var
+        // and write an explicit compaction block to control the native state.
+        function writeCompactionConfig(auto: boolean, prune = false): void {
+            const prev = process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            writeFileSync(
+                join(projectDir, "opencode.json"),
+                JSON.stringify({ compaction: { auto, prune } }),
+            );
+            if (prev !== undefined) process.env.OPENCODE_DISABLE_AUTOCOMPACT = prev;
+        }
+
+        function detectWithMode(compactionEnabled: boolean) {
+            const prev = process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            try {
+                return detectConflicts(projectDir, { compactionEnabled });
+            } finally {
+                if (prev !== undefined) process.env.OPENCODE_DISABLE_AUTOCOMPACT = prev;
+            }
+        }
+
+        it("MC ON + auto=true → conflict fires, plugin would be disabled", () => {
+            writeCompactionConfig(true);
+            const result = detectWithMode(true);
+            expect(result.hasConflict).toBe(true);
+            expect(result.conflicts.compactionAuto).toBe(true);
+        });
+
+        it("MC ON + auto=false → no compaction conflict, plugin stays enabled", () => {
+            writeCompactionConfig(false);
+            const result = detectWithMode(true);
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("MC OFF + auto=true → NO conflict, plugin stays enabled (native compaction active)", () => {
+            writeCompactionConfig(true);
+            const result = detectWithMode(false);
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.conflicts.compactionPrune).toBe(false);
+            expect(result.hasConflict).toBe(false);
+            // Native compaction state is still reported honestly.
+            expect(result.nativeCompaction.auto).toBe(true);
+        });
+
+        it("MC OFF + auto=false → NO conflict, no-manager configuration reported honestly", () => {
+            writeCompactionConfig(false);
+            const result = detectWithMode(false);
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.hasConflict).toBe(false);
+            // No-manager: neither MC nor native compaction owns the window.
+            expect(result.nativeCompaction.auto).toBe(false);
+            expect(result.nativeCompaction.prune).toBe(false);
+        });
+
+        // Mutation direction: force mode-on in the detector with auto=true →
+        // conflict fires. This proves the off-gate isn't just always-pass —
+        // the same native config that was NOT a conflict in the off case
+        // becomes a conflict when the mode is forced on.
+        it("mutation direction: same auto=true config DOES conflict when mode forced on", () => {
+            writeCompactionConfig(true);
+            const offResult = detectWithMode(false);
+            const onResult = detectWithMode(true);
+            expect(offResult.hasConflict).toBe(false);
+            expect(onResult.hasConflict).toBe(true);
+            expect(onResult.conflicts.compactionAuto).toBe(true);
+        });
+
+        // prune=true follows the same gate as auto=true.
+        it("MC OFF + prune=true → NO conflict (prune is not a conflict in compaction-off mode)", () => {
+            writeCompactionConfig(false, true);
+            const result = detectWithMode(false);
+            expect(result.conflicts.compactionPrune).toBe(false);
+            expect(result.hasConflict).toBe(false);
+            expect(result.nativeCompaction.prune).toBe(true);
+        });
+
+        // DCP and OMO conflicts keep their existing policy in BOTH modes.
+        it("MC OFF + DCP plugin → DCP conflict still fires (compaction-off does not broaden compatibility)", () => {
+            writeProjectConfig(["@tarquinen/opencode-dcp"]);
+            const result = detectWithMode(false);
+            expect(result.conflicts.dcpPlugin).toBe(true);
+            expect(result.hasConflict).toBe(true);
+        });
+
+        it("MC OFF + OMO hooks → OMO conflicts still fire in both modes", () => {
+            writeProjectConfig(["oh-my-opencode"]);
+            const result = detectWithMode(false);
+            expect(result.conflicts.omoPreemptiveCompaction).toBe(true);
+            expect(result.hasConflict).toBe(true);
+        });
+
+        // Default (no options) preserves today's mode-on behavior — a call
+        // site that cannot supply the resolved mode fails toward mode-on.
+        it("default (no options) treats compaction.auto=true as a conflict (fail toward mode-on)", () => {
+            writeCompactionConfig(true);
+            const prev = process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            try {
+                const result = detectConflicts(projectDir);
+                expect(result.conflicts.compactionAuto).toBe(true);
+                expect(result.hasConflict).toBe(true);
+            } finally {
+                if (prev !== undefined) process.env.OPENCODE_DISABLE_AUTOCOMPACT = prev;
+            }
+        });
+    });
+
+    describe("OpenCode 2 compaction ownership", () => {
+        it("keeps MC enabled when host auto-compaction is on and never reads v1 prune", () => {
+            const previous = process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            const resolved = {
+                auto: true,
+                get prune(): boolean {
+                    throw new Error("v2 must not read compaction.prune");
+                },
+                keepTokens: 4_096,
+                buffer: 1_024,
+            };
+            const result = detectConflicts(projectDir, {
+                compactionEnabled: true,
+                hostGeneration: "v2",
+                resolvedCompaction: resolved,
+            });
+            expect(result.hasConflict).toBe(false);
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.conflicts.compactionPrune).toBe(false);
+            expect(result.nativeCompaction).toEqual({ auto: true, prune: false });
+            if (previous === undefined) delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            else process.env.OPENCODE_DISABLE_AUTOCOMPACT = previous;
+        });
+    });
+
+    // --- Resolved-config arm (issue #309) ---
+    // The plugin boot now consumes the host's RESOLVED config
+    // (ctx.client.config.get()) instead of re-deriving compaction from files.
+    // These tests exercise the resolved arm directly via the
+    // `resolvedCompaction` option.
+    describe("resolved-config arm (issue #309)", () => {
+        // The suite beforeEach sets OPENCODE_DISABLE_AUTOCOMPACT=1 to isolate
+        // plugin detection from compaction detection. These tests exercise the
+        // resolved arm, so they clear it and restore it per-case.
+        function withoutAutoCompactEnv<T>(fn: () => T): T {
+            const prev = process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            try {
+                return fn();
+            } finally {
+                if (prev !== undefined) process.env.OPENCODE_DISABLE_AUTOCOMPACT = prev;
+            }
+        }
+
+        it("resolved auto=false outranks a file layer that says auto=true (#309)", () => {
+            // The file layer says auto=true, which on its own disables the
+            // plugin. The host's resolved config says auto=false, and the host
+            // is the authority — it can see layers the file reader cannot.
+            writeFileSync(
+                join(projectDir, "opencode.json"),
+                JSON.stringify({ compaction: { auto: true } }),
+            );
+            withoutAutoCompactEnv(() => {
+                const result = detectConflicts(projectDir, {
+                    compactionEnabled: true,
+                    resolvedCompaction: { auto: false, prune: false },
+                });
+                expect(result.conflicts.compactionAuto).toBe(false);
+                expect(result.hasConflict).toBe(false);
+                expect(result.nativeCompaction.auto).toBe(false);
+            });
+        });
+
+        it("resolved auto=true → conflict, message carries '(resolved config)'", () => {
+            withoutAutoCompactEnv(() => {
+                const result = detectConflicts(projectDir, {
+                    compactionEnabled: true,
+                    resolvedCompaction: { auto: true, prune: false },
+                });
+                expect(result.conflicts.compactionAuto).toBe(true);
+                expect(result.hasConflict).toBe(true);
+                expect(result.reasons.join("; ")).toContain("(resolved config)");
+            });
+        });
+
+        it("resolved prune=true → conflict, message carries '(resolved config)'", () => {
+            withoutAutoCompactEnv(() => {
+                const result = detectConflicts(projectDir, {
+                    compactionEnabled: true,
+                    resolvedCompaction: { auto: false, prune: true },
+                });
+                expect(result.conflicts.compactionPrune).toBe(true);
+                expect(result.hasConflict).toBe(true);
+                expect(result.reasons.join("; ")).toContain("(resolved config)");
+            });
+        });
+
+        it("resolved arm is skipped when resolvedCompaction is absent (file-based fallback unchanged)", () => {
+            // No resolvedCompaction → the file-based check runs and owns the
+            // verdict. The written block is what makes the file arm say
+            // auto=true; it used to be an absent block relying on the file
+            // arm's default-on, which issue #484 removed because an absent
+            // block cannot tell "the user wrote nothing" apart from "we read
+            // the wrong directory". The claim under test is unchanged: with no
+            // resolved value the file arm decides, and its reason is unlabeled.
+            writeFileSync(
+                join(projectDir, "opencode.json"),
+                JSON.stringify({ compaction: { auto: true } }),
+            );
+            withoutAutoCompactEnv(() => {
+                const result = detectConflicts(projectDir, { compactionEnabled: true });
+                expect(result.conflicts.compactionAuto).toBe(true);
+                expect(result.hasConflict).toBe(true);
+                // File-based arm does NOT carry the resolved-config label.
+                expect(result.reasons.join("; ")).not.toContain("(resolved config)");
+            });
+        });
+
+        it("OPENCODE_DISABLE_AUTOCOMPACT short-circuits the resolved arm", () => {
+            // Resolved says auto=true, but the env override must win.
+            process.env.OPENCODE_DISABLE_AUTOCOMPACT = "1";
+            try {
+                const result = detectConflicts(projectDir, {
+                    compactionEnabled: true,
+                    resolvedCompaction: { auto: true, prune: true },
+                });
+                expect(result.conflicts.compactionAuto).toBe(false);
+                expect(result.conflicts.compactionPrune).toBe(false);
+                expect(result.hasConflict).toBe(false);
+                expect(result.nativeCompaction.auto).toBe(false);
+                expect(result.nativeCompaction.prune).toBe(false);
+            } finally {
+                delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            }
+        });
+
+        it("compaction-off mode: resolved auto=true is NOT a conflict (native compaction active)", () => {
+            withoutAutoCompactEnv(() => {
+                const result = detectConflicts(projectDir, {
+                    compactionEnabled: false,
+                    resolvedCompaction: { auto: true, prune: false },
+                });
+                expect(result.conflicts.compactionAuto).toBe(false);
+                expect(result.hasConflict).toBe(false);
+                // Native compaction state is still reported honestly.
+                expect(result.nativeCompaction.auto).toBe(true);
+            });
+        });
+    });
+
+    // --- OPENCODE_CONFIG_DIR is an ADDITION, not a replacement (issue #484) ---
+    //
+    // A launcher (Orca) exported OPENCODE_CONFIG_DIR to a directory holding
+    // only plugin scaffolding. OpenCode kept reading the user's real global
+    // config — `opencode debug config` showed compaction.auto=false — but the
+    // detector resolved the env directory INSTEAD of the global one, found no
+    // file, fell through to its default-on, and disabled the plugin.
+    //
+    // Verified against the opencode 1.18.30 binary and on a live host:
+    // `$XDG_CONFIG_HOME/opencode` is always read; `~/.opencode` is always
+    // scanned; `$OPENCODE_CONFIG_DIR` is appended LAST, so it wins ties but
+    // never hides the layers below it.
+    describe("OPENCODE_CONFIG_DIR is additive, not a replacement (issue #484)", () => {
+        let globalDir: string;
+        let launcherDir: string;
+
+        beforeEach(() => {
+            // These cases exercise compaction detection itself, so the suite's
+            // isolation env var has to go.
+            delete process.env.OPENCODE_DISABLE_AUTOCOMPACT;
+            // HOME is the temp dir and XDG_CONFIG_HOME is cleared by the suite
+            // beforeEach, so this is the same path OpenCode would compute.
+            globalDir = join(homeDir, ".config", "opencode");
+            mkdirSync(globalDir, { recursive: true });
+            // The reporter's launcher directory: plugin scaffolding, no config.
+            launcherDir = join(root, "launcher-config-dir");
+            mkdirSync(launcherDir, { recursive: true });
+            writeFileSync(
+                join(launcherDir, "package.json"),
+                JSON.stringify({ name: "launcher-scaffold", version: "1.0.0" }),
+            );
+            process.env.OPENCODE_CONFIG_DIR = launcherDir;
+        });
+
+        afterEach(() => {
+            delete process.env.OPENCODE_CONFIG;
+        });
+
+        function writeCompaction(dir: string, file: string, compaction: unknown): void {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, file), JSON.stringify({ compaction }));
+        }
+
+        it("reporter repro: global auto=false + config-less OPENCODE_CONFIG_DIR → no conflict", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: false });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.hasConflict).toBe(false);
+            expect(result.nativeCompaction.auto).toBe(false);
+        });
+
+        it("positive control: global auto=true still reports the conflict", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: true });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(true);
+            expect(result.hasConflict).toBe(true);
+            expect(result.reasons.join("; ")).toContain("compaction.auto=true");
+        });
+
+        it("an OPENCODE_CONFIG_DIR that DOES carry auto=true outranks a global auto=false", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: false });
+            writeCompaction(launcherDir, "opencode.json", { auto: true });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(true);
+            expect(result.hasConflict).toBe(true);
+        });
+
+        it("an OPENCODE_CONFIG_DIR auto=false outranks a global auto=true", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: true });
+            writeCompaction(launcherDir, "opencode.jsonc", { auto: false });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("v1 keeps global supplementary config above the project .opencode overlay", () => {
+            writeCompaction(launcherDir, "opencode.json", { auto: false });
+            writeCompaction(join(projectDir, ".opencode"), "opencode.json", { auto: true });
+            const result = detectConflicts(projectDir, {
+                compactionEnabled: true,
+                hostGeneration: "v1",
+            });
+            expect(result.nativeCompaction.auto).toBe(false);
+            expect(result.conflicts.compactionAuto).toBe(false);
+        });
+
+        it("v2 ranks the project .opencode overlay above global supplementary config", () => {
+            writeCompaction(launcherDir, "opencode.json", { auto: false });
+            writeCompaction(join(projectDir, ".opencode"), "opencode.json", { auto: true });
+            const result = detectConflicts(projectDir, {
+                compactionEnabled: true,
+                hostGeneration: "v2",
+            });
+            expect(result.nativeCompaction.auto).toBe(true);
+            expect(result.conflicts.compactionAuto).toBe(false);
+        });
+
+        it("reads the global directory's legacy config.json layer", () => {
+            writeCompaction(globalDir, "config.json", { auto: true });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(true);
+        });
+
+        it("global opencode.jsonc overrides global opencode.json", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: true });
+            writeCompaction(globalDir, "opencode.jsonc", { auto: false });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.hasConflict).toBe(false);
+        });
+
+        it("~/.opencode outranks the global config directory", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: false });
+            writeCompaction(join(homeDir, ".opencode"), "opencode.json", { auto: true });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(true);
+        });
+
+        it("reads the $OPENCODE_CONFIG single-file override", () => {
+            const explicit = join(root, "explicit-opencode.json");
+            writeFileSync(explicit, JSON.stringify({ compaction: { auto: true } }));
+            process.env.OPENCODE_CONFIG = explicit;
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(true);
+        });
+
+        it("merges keys across layers instead of letting one file erase the other", () => {
+            writeCompaction(globalDir, "opencode.json", { auto: false });
+            writeCompaction(projectDir, "opencode.json", { prune: true });
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.nativeCompaction.auto).toBe(false);
+            expect(result.nativeCompaction.prune).toBe(true);
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.conflicts.compactionPrune).toBe(true);
+        });
+
+        it("no compaction key in any readable layer is inconclusive, never a disable", () => {
+            // Nothing anywhere. OpenCode's own default is auto=true, but we
+            // cannot tell "the user wrote nothing" from "the value lives in a
+            // layer we cannot read" (managed/enterprise config, an org layer,
+            // a file we failed to parse). Guessing the disabling direction
+            // leaves NOTHING managing the window — the unrecoverable failure
+            // issue #309 established for the resolved arm.
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.compactionAuto).toBe(false);
+            expect(result.conflicts.compactionPrune).toBe(false);
+            expect(result.hasConflict).toBe(false);
+            expect(result.nativeCompaction.auto).toBe(false);
+        });
+
+        it("still finds a conflicting plugin declared in the global config", () => {
+            writeFileSync(
+                join(globalDir, "opencode.json"),
+                JSON.stringify({ plugin: ["@tarquinen/opencode-dcp"] }),
+            );
+            const result = detectConflicts(projectDir, { compactionEnabled: true });
+            expect(result.conflicts.dcpPlugin).toBe(true);
+        });
+    });
+});