@cortexkit/opencode-magic-context 0.38.1 → 0.40.0

package/src/config/project-security.ts

@@ -1,4 +1,7 @@
-import { DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE } from "./schema/magic-context";
+import {
+    DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE,
+    PER_HARNESS_MIGRATION_INVENTORY,
+} from "./schema/magic-context";
 
 /**
  * Security hardening for PROJECT-level (repo-supplied, untrusted) config.
@@ -15,7 +18,11 @@ import { DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE } from "./schema/magic-context";
 
 /** Hidden agents that run with elevated/autonomous capability. */
 const HIDDEN_AGENT_KEYS = ["historian", "dreamer", "sidekick"] as const;
-const HISTORIAN_USER_ONLY_FIELDS = ["model", "fallback_models"] as const;
+const HARNESS_KEYS = ["opencode", "pi"] as const;
+/** Every historian model-resolution field, including per-harness qualifiers.
+ *  Variant and thinking_level merge onto the user's historian model at resolve
+ *  time, so leaving them would let a cloned repo force extra spend. */
+const HISTORIAN_USER_ONLY_FIELDS = PER_HARNESS_MIGRATION_INVENTORY.historian.migrated_execution;
 const PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"] as const;
 
 /**
@@ -64,6 +71,66 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function stripListedFields(
+    target: Record<string, unknown>,
+    fields: readonly string[],
+    path: string,
+    removed: string[],
+): void {
+    for (const field of fields) {
+        if (field in target) {
+            delete target[field];
+            removed.push(path.length > 0 ? `${path}.${field}` : field);
+        }
+    }
+}
+
+/** Strip prompt, permission, tools, and system_prompt from one agent, harness,
+ *  task, or model-entry object, including each fallback_models entry. A cloned
+ *  repo must not reprogram hidden agents through any of those nestings. */
+function stripEscalationAtExecutableSite(
+    block: Record<string, unknown>,
+    path: string,
+    removed: string[],
+): void {
+    stripListedFields(block, AGENT_ESCALATION_FIELDS, path, removed);
+    if (isPlainObject(block.model)) {
+        stripListedFields(block.model, AGENT_ESCALATION_FIELDS, `${path}.model`, removed);
+    }
+    if (Array.isArray(block.fallback_models)) {
+        for (let index = 0; index < block.fallback_models.length; index++) {
+            const entry = block.fallback_models[index];
+            if (isPlainObject(entry)) {
+                stripListedFields(
+                    entry,
+                    AGENT_ESCALATION_FIELDS,
+                    `${path}.fallback_models.${index}`,
+                    removed,
+                );
+            }
+        }
+    }
+}
+
+/** Remove `mural.model` smuggled under hidden-agent trees. Top-level and
+ *  experimental mural blocks are handled separately so their warnings stay
+ *  specific; this walk covers harness and task nesting the schema does not
+ *  admit but a hostile file can still write. */
+function stripNestedMuralModels(
+    node: Record<string, unknown>,
+    path: string,
+    removed: string[],
+): void {
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "mural" && isPlainObject(value) && "model" in value) {
+            delete value.model;
+            removed.push(`${path}.${key}.model`);
+        } else if (isPlainObject(value)) {
+            stripNestedMuralModels(value, `${path}.${key}`, removed);
+        }
+    }
+}
+
 function isValidPercentageThreshold(value: unknown): value is number {
     return typeof value === "number" && Number.isFinite(value) && value >= 20 && value <= 80;
 }
@@ -189,6 +256,9 @@ function makeProjectThresholdWarning(field: string, reason: string): string {
  * over the user config. Returns warnings describing what was ignored.
  *
  * Closes:
+ *  - `profiles` — profile definitions choose hidden-agent models and must stay
+ *    in trusted user config; a repository may select a named profile but cannot
+ *    supply its contents.
  *  - `auto_update` — a repo must not suppress plugin self-updates (which can
  *    carry security fixes).
  *  - `fail_closed_blocking` — a repo must not un-block (or force-block) the
@@ -213,21 +283,33 @@ function makeProjectThresholdWarning(field: string, reason: string): string {
  *  - `transform_mode` is intentionally allowed at project tier so a repository
  *    can opt its own runtime into the experimental Rust pipeline. The resolver
  *    requires trusted user-level `subc` configuration before Rust can activate.
- *  - `historian.model` / `historian.fallback_models` — historian model spend is
- *    user-level only; a cloned repo cannot force extra compaction cost.
- *  - `mural.model` — mural cue-compressor model selection is user-level only;
- *    a cloned repo cannot choose a model that sends project memory to a provider.
+ *  - historian model-resolution fields (model, fallback_models, variant,
+ *    thinking_level), including both per-harness blocks — historian model
+ *    spend is user-level only. Qualifiers merge onto the user's historian
+ *    model at resolve time, so a cloned repo cannot force extra thinking or
+ *    variant cost.
+ *  - `mural.model` at the top-level block, the legacy experimental spelling,
+ *    and any nested `mural.model` under hidden agents — a cloned repo cannot
+ *    choose where project memory is sent.
  *  - `pi.subagent_extensions` — a cloned repo must not choose which extensions
  *    the user's Pi child processes load.
  *  - `prompt_surface.guidance_override_path` / `tool_descriptions` — a repository
  *    may select a reviewed preset, but must not inject arbitrary guidance or tool
  *    description text into the user's provider-visible prompt.
- *  - hidden-agent `prompt`/`permission`/`tools` — a repo must not reprogram or
- *    re-permission the historian/dreamer/sidekick.
+ *  - hidden-agent `prompt`/`permission`/`tools`/`system_prompt` at the agent
+ *    root, each harness block, each task block, and inside model/fallback
+ *    entry objects — a repo must not reprogram or re-permission hidden agents.
  */
 export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknown>): string[] {
     const warnings: string[] = [];
 
+    if ("profiles" in projectRaw) {
+        delete projectRaw.profiles;
+        warnings.push(
+            "Ignoring profiles from project config (security: profile definitions are user-level only; a repository may select a named user profile with profile).",
+        );
+    }
+
     if ("auto_update" in projectRaw) {
         delete projectRaw.auto_update;
         warnings.push(
@@ -356,6 +438,49 @@ export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknow
         }
     }
 
+    for (const agentKey of HIDDEN_AGENT_KEYS) {
+        const block = projectRaw[agentKey];
+        if (!isPlainObject(block)) continue;
+        const removed: string[] = [];
+        stripEscalationAtExecutableSite(block, agentKey, removed);
+        for (const harness of HARNESS_KEYS) {
+            const harnessBlock = block[harness];
+            if (!isPlainObject(harnessBlock)) continue;
+            stripEscalationAtExecutableSite(harnessBlock, `${agentKey}.${harness}`, removed);
+            const tasks = harnessBlock.tasks;
+            if (isPlainObject(tasks)) {
+                for (const [taskName, taskBlock] of Object.entries(tasks)) {
+                    if (isPlainObject(taskBlock)) {
+                        stripEscalationAtExecutableSite(
+                            taskBlock,
+                            `${agentKey}.${harness}.tasks.${taskName}`,
+                            removed,
+                        );
+                    }
+                }
+            }
+        }
+        const schedulingTasks = block.tasks;
+        if (isPlainObject(schedulingTasks)) {
+            for (const [taskName, taskBlock] of Object.entries(schedulingTasks)) {
+                if (isPlainObject(taskBlock)) {
+                    stripListedFields(
+                        taskBlock,
+                        AGENT_ESCALATION_FIELDS,
+                        `${agentKey}.tasks.${taskName}`,
+                        removed,
+                    );
+                }
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring ${removed.join(", ")} from project config ` +
+                    "(security: a repository cannot reprogram or re-permission hidden agents).",
+            );
+        }
+    }
+
     const historian = projectRaw.historian;
     if (isPlainObject(historian)) {
         const removed: string[] = [];
@@ -365,9 +490,19 @@ export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknow
                 removed.push(field);
             }
         }
+        for (const harness of HARNESS_KEYS) {
+            const harnessBlock = historian[harness];
+            if (!isPlainObject(harnessBlock)) continue;
+            for (const field of HISTORIAN_USER_ONLY_FIELDS) {
+                if (field in harnessBlock) {
+                    delete harnessBlock[field];
+                    removed.push(`${harness}.${field}`);
+                }
+            }
+        }
         if (removed.length > 0) {
             warnings.push(
-                `Ignoring historian.${removed.join("/")} from project config ` +
+                `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).",
             );
         }
@@ -394,22 +529,16 @@ export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknow
         );
     }
 
+    const nestedMuralRemoved: string[] = [];
     for (const agentKey of HIDDEN_AGENT_KEYS) {
         const block = projectRaw[agentKey];
         if (!isPlainObject(block)) continue;
-        const removed: string[] = [];
-        for (const field of AGENT_ESCALATION_FIELDS) {
-            if (field in block) {
-                delete block[field];
-                removed.push(field);
-            }
-        }
-        if (removed.length > 0) {
-            warnings.push(
-                `Ignoring ${agentKey}.${removed.join("/")} from project config ` +
-                    "(security: a repository cannot reprogram or re-permission hidden agents).",
-            );
-        }
+        stripNestedMuralModels(block, agentKey, nestedMuralRemoved);
+    }
+    if (nestedMuralRemoved.length > 0) {
+        warnings.push(
+            `Ignoring ${nestedMuralRemoved.join(", ")} from project config (security: the mural cue-compressor model is a user-level setting; a repository cannot choose where project memory is sent).`,
+        );
     }
 
     return warnings;

package/src/config/raw-loader.test.ts

@@ -0,0 +1,424 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+    chmodSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    statSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parseJsonc } from "../shared/jsonc-parser";
+import { hasFlatKeys, loadRawConfigFile, migrateFlatDetailed } from "./raw-loader";
+import { PER_HARNESS_MIGRATION_INVENTORY } from "./schema/magic-context";
+
+const temporaryDirectories: string[] = [];
+
+function temporaryDirectory(): string {
+    const directory = mkdtempSync(join(tmpdir(), "mc-per-harness-"));
+    temporaryDirectories.push(directory);
+    return directory;
+}
+
+function parse(text: string): Record<string, unknown> {
+    const withoutBom = text.startsWith("\uFEFF") ? text.slice(1) : text;
+    return parseJsonc<Record<string, unknown>>(withoutBom);
+}
+
+afterEach(() => {
+    for (const directory of temporaryDirectories.splice(0)) {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+describe("per-harness raw config migration", () => {
+    it("maps flat agent and task fields without moving scheduling fields", () => {
+        const input = `\uFEFF{\r
+  // preserve this comment\r
+  "historian": {\r
+    "model": { "model": "provider/historian", "variant": "fast", "thinking_level": "high" }, // historian model note\r
+    "fallback_models": [{ "model": "provider/fallback", "variant": "careful", "thinking_level": "low" }],\r
+    "variant": "block-variant",\r
+    "thinking_level": "medium"\r
+  },\r
+  "dreamer": {\r
+    "model": "provider/dreamer",\r
+    "fallback_models": "provider/dreamer-fallback",\r
+    "tasks": {\r
+      "review": {\r
+        "schedule": "0 3 * * *",\r
+        "model": { "model": "provider/task", "variant": "task-variant", "thinking_level": "max" },\r
+        "thinking_level": "high",\r
+        "timeout_minutes": 45\r
+      },\r
+      "timeout-only": { "timeout_minutes": 15 }\r
+    }\r
+  },\r
+  "unrelated": { "keep": true }\r
+}\r
+`;
+
+        const migrated = migrateFlatDetailed(Buffer.from(input, "utf-8"));
+        const repeated = migrateFlatDetailed(Buffer.from(input, "utf-8"));
+        const idempotent = migrateFlatDetailed(migrated.bytes);
+        const output = migrated.bytes.toString("utf-8");
+        const config = parse(output);
+        const historian = config.historian as Record<string, unknown>;
+        const dreamer = config.dreamer as Record<string, unknown>;
+        const opencodeHistorian = historian.opencode as Record<string, unknown>;
+        const piHistorian = historian.pi as Record<string, unknown>;
+        const opencodeDreamer = dreamer.opencode as Record<string, unknown>;
+        const piDreamer = dreamer.pi as Record<string, unknown>;
+        const tasks = dreamer.tasks as Record<string, Record<string, unknown>>;
+
+        expect(migrated.hasFlatKeys).toBe(true);
+        expect(repeated.bytes).toEqual(migrated.bytes);
+        expect(repeated.diagnostics).toEqual(migrated.diagnostics);
+        expect(idempotent.bytes).toEqual(migrated.bytes);
+        expect(idempotent.hasFlatKeys).toBe(false);
+        expect(idempotent.diagnostics).toEqual([]);
+        expect(hasFlatKeys(migrated.bytes)).toBe(false);
+        expect(output.startsWith("\uFEFF")).toBe(true);
+        expect(output).toContain("// preserve this comment");
+        expect(output).toContain("// historian model note");
+        expect(output).toContain("\r\n");
+        expect(config.unrelated).toEqual({ keep: true });
+        expect(historian.model).toBeUndefined();
+        expect(opencodeHistorian).toEqual({
+            model: { model: "provider/historian", variant: "fast" },
+            fallback_models: [{ model: "provider/fallback", variant: "careful" }],
+            variant: "block-variant",
+        });
+        expect(piHistorian).toEqual({
+            model: { model: "provider/historian", thinking_level: "high" },
+            fallback_models: [{ model: "provider/fallback", thinking_level: "low" }],
+            thinking_level: "medium",
+        });
+        expect(opencodeDreamer.fallback_models).toEqual(["provider/dreamer-fallback"]);
+        expect(piDreamer.fallback_models).toEqual(["provider/dreamer-fallback"]);
+        expect(tasks.review).toEqual({ schedule: "0 3 * * *" });
+        expect(tasks["timeout-only"]).toEqual({});
+        expect((opencodeDreamer.tasks as Record<string, Record<string, unknown>>).review).toEqual({
+            model: { model: "provider/task", variant: "task-variant" },
+            timeout_minutes: 45,
+        });
+        expect((piDreamer.tasks as Record<string, Record<string, unknown>>).review).toEqual({
+            model: { model: "provider/task", thinking_level: "max" },
+            thinking_level: "high",
+            timeout_minutes: 45,
+        });
+        expect(
+            (opencodeDreamer.tasks as Record<string, Record<string, unknown>>)["timeout-only"],
+        ).toEqual({ timeout_minutes: 15 });
+        expect(
+            (piDreamer.tasks as Record<string, Record<string, unknown>>)["timeout-only"],
+        ).toEqual({ timeout_minutes: 15 });
+    });
+
+    it("turns a singleton fallback into one entry without changing its spelling", () => {
+        const migrated = migrateFlatDetailed(
+            Buffer.from(
+                JSON.stringify({
+                    historian: { fallback_models: "Vendor/Model:Exact-Spelling" },
+                }),
+            ),
+        );
+        const historian = parse(migrated.bytes.toString("utf-8")).historian as Record<
+            string,
+            Record<string, unknown>
+        >;
+
+        expect(historian.opencode.fallback_models).toEqual(["Vendor/Model:Exact-Spelling"]);
+        expect(historian.pi.fallback_models).toEqual(["Vendor/Model:Exact-Spelling"]);
+    });
+
+    it("preserves every schema-enumerated retained field at its original level", () => {
+        const historianRetained = {
+            temperature: 0.1,
+            top_p: 0.9,
+            prompt: "historian prompt",
+            tools: { read: true },
+            disable: false,
+            description: "historian description",
+            mode: "subagent",
+            color: "blue",
+            maxSteps: 11,
+            permission: { edit: "deny" },
+            maxTokens: 4096,
+            two_pass: true,
+            disallowed_tools: ["bash"],
+        };
+        const dreamerRetained = {
+            temperature: 0.2,
+            top_p: 0.8,
+            prompt: "dreamer prompt",
+            tools: { write: true },
+            disable: false,
+            description: "dreamer description",
+            mode: "subagent",
+            color: "purple",
+            maxSteps: 12,
+            permission: { bash: "deny" },
+            maxTokens: 8192,
+            inject_docs: false,
+        };
+        const taskRetained = {
+            schedule: "0 3 * * *",
+            promotion_threshold: 4,
+        };
+        expect(Object.keys(historianRetained)).toEqual(
+            PER_HARNESS_MIGRATION_INVENTORY.historian.retained,
+        );
+        expect(Object.keys(dreamerRetained)).toEqual(
+            PER_HARNESS_MIGRATION_INVENTORY.dreamer.retained,
+        );
+        expect(Object.keys(taskRetained)).toEqual(PER_HARNESS_MIGRATION_INVENTORY.task.retained);
+
+        const migrated = migrateFlatDetailed(
+            Buffer.from(
+                JSON.stringify({
+                    historian: { ...historianRetained, model: "provider/historian" },
+                    dreamer: {
+                        ...dreamerRetained,
+                        model: "provider/dreamer",
+                        tasks: {
+                            review: {
+                                ...taskRetained,
+                                model: "provider/task",
+                                timeout_minutes: 25,
+                            },
+                        },
+                    },
+                }),
+            ),
+        );
+        const config = parse(migrated.bytes.toString("utf-8"));
+        const historian = config.historian as Record<string, unknown>;
+        const dreamer = config.dreamer as Record<string, unknown>;
+        const task = (dreamer.tasks as Record<string, Record<string, unknown>>).review;
+
+        for (const [field, value] of Object.entries(historianRetained)) {
+            expect(historian[field]).toEqual(value);
+        }
+        for (const [field, value] of Object.entries(dreamerRetained)) {
+            expect(dreamer[field]).toEqual(value);
+        }
+        expect(task).toEqual(taskRetained);
+    });
+
+    it("fills absent destinations and silently removes equal flat sources", () => {
+        const migrated = migrateFlatDetailed(
+            Buffer.from(`{
+  "historian": {
+    "model": "provider/same",
+    "opencode": { "model": "provider/same" },
+    "pi": {}
+  }
+}`),
+        );
+        const historian = parse(migrated.bytes.toString("utf-8")).historian as Record<
+            string,
+            unknown
+        >;
+
+        expect(historian.model).toBeUndefined();
+        expect(historian.opencode).toEqual({ model: "provider/same" });
+        expect(historian.pi).toEqual({ model: "provider/same" });
+        expect(migrated.diagnostics).toEqual([]);
+    });
+
+    it("keeps new-shape destinations on conflicts and names both paths in warnings", () => {
+        const input = `{
+  "historian": {
+    "model": "provider/flat",
+    "fallback_models": "provider/fallback",
+    "opencode": { "model": "provider/opencode", "fallback_models": ["provider/fallback"] },
+    "pi": { "model": "provider/pi", "fallback_models": ["provider/fallback"] }
+  }
+}`;
+
+        const migrated = migrateFlatDetailed(Buffer.from(input));
+        const config = parse(migrated.bytes.toString("utf-8"));
+        const historian = config.historian as Record<string, unknown>;
+
+        expect(historian.model).toBeUndefined();
+        expect(historian.fallback_models).toBeUndefined();
+        expect(historian.opencode).toEqual({
+            model: "provider/opencode",
+            fallback_models: ["provider/fallback"],
+        });
+        expect(historian.pi).toEqual({
+            model: "provider/pi",
+            fallback_models: ["provider/fallback"],
+        });
+        expect(migrated.diagnostics.map((diagnostic) => diagnostic.path)).toEqual([
+            "historian.model",
+            "historian.model",
+        ]);
+        expect(migrated.diagnostics[0]?.message).toContain("historian.opencode.model");
+        expect(migrated.diagnostics[1]?.message).toContain("historian.pi.model");
+    });
+
+    it("processes flat keys re-added after migration while existing blocks keep winning", () => {
+        const first = migrateFlatDetailed(
+            Buffer.from(JSON.stringify({ historian: { model: "provider/original" } })),
+        );
+        const reintroduced = parse(first.bytes.toString("utf-8"));
+        (reintroduced.historian as Record<string, unknown>).model = "provider/re-added";
+
+        const second = migrateFlatDetailed(Buffer.from(JSON.stringify(reintroduced)));
+        const historian = parse(second.bytes.toString("utf-8")).historian as Record<
+            string,
+            unknown
+        >;
+
+        expect(historian.model).toBeUndefined();
+        expect(historian.opencode).toEqual({ model: "provider/original" });
+        expect(historian.pi).toEqual({ model: "provider/original" });
+        expect(second.diagnostics.map((diagnostic) => diagnostic.message)).toEqual([
+            expect.stringContaining("historian.opencode.model"),
+            expect.stringContaining("historian.pi.model"),
+        ]);
+    });
+
+    it("rewrites user config atomically with one exact-byte restricted backup", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const original = Buffer.from(
+            '{\n  "dreamer": { "tasks": { "review": { "timeout_minutes": 30 } } }\n}\n',
+        );
+        writeFileSync(configPath, original);
+        chmodSync(configPath, 0o600);
+        const expected = migrateFlatDetailed(original).bytes;
+        let temporaryNamesDuringWrite: string[] = [];
+
+        const first = loadRawConfigFile({
+            configPath,
+            tier: "user",
+            afterTemporaryWrite: () => {
+                expect(readFileSync(configPath)).toEqual(original);
+                temporaryNamesDuringWrite = readdirSync(directory).filter((name) =>
+                    name.endsWith(".tmp"),
+                );
+                expect(temporaryNamesDuringWrite).toHaveLength(1);
+                expect(
+                    readFileSync(join(directory, temporaryNamesDuringWrite[0] as string)),
+                ).toEqual(expected);
+            },
+        });
+        const second = loadRawConfigFile({ configPath, tier: "user" });
+        const backupPath = `${configPath}.pre-per-harness.bak`;
+
+        expect(first?.migrated).toBe(true);
+        expect(first?.warnings).toContain(
+            "Migrated flat historian/dreamer model config to per-harness blocks.",
+        );
+        expect(readFileSync(backupPath)).toEqual(original);
+        expect(readFileSync(configPath)).toEqual(first?.bytes);
+        expect(temporaryNamesDuringWrite).toHaveLength(1);
+        expect(readdirSync(directory).filter((name) => name.endsWith(".tmp"))).toEqual([]);
+        expect(statSync(configPath).mode & 0o777).toBe(0o600);
+        expect(statSync(backupPath).mode & 0o777).toBe(0o600);
+        expect(second?.migrated).toBe(false);
+        expect(second?.warnings).toEqual([]);
+    });
+
+    it("repairs a truncated migration backup left by the direct-write protocol", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const backupPath = `${configPath}.pre-per-harness.bak`;
+        const original = Buffer.from('{ "historian": { "model": "provider/model" } }\n');
+        writeFileSync(configPath, original);
+        writeFileSync(backupPath, original.subarray(0, 17));
+
+        const loaded = loadRawConfigFile({ configPath, tier: "user" });
+
+        expect(loaded?.migrated).toBe(true);
+        expect(readFileSync(backupPath)).toEqual(original);
+    });
+
+    it("leaves a completed migration backup with different bytes untouched", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const backupPath = `${configPath}.pre-per-harness.bak`;
+        const sentinel = Buffer.from("not config: backup is opaque and permanent\n");
+        writeFileSync(configPath, '{ "historian": { "model": "provider/model" } }');
+        writeFileSync(backupPath, sentinel);
+
+        const first = loadRawConfigFile({ configPath, tier: "user" });
+        const second = loadRawConfigFile({ configPath, tier: "user" });
+
+        expect(first?.migrated).toBe(true);
+        expect(second?.migrated).toBe(false);
+        expect(readFileSync(backupPath)).toEqual(sentinel);
+    });
+
+    it("accepts a matching migration backup without rewriting it", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const backupPath = `${configPath}.pre-per-harness.bak`;
+        const original = Buffer.from('{ "historian": { "model": "provider/model" } }\n');
+        writeFileSync(configPath, original);
+        writeFileSync(backupPath, original);
+        const backupInode = statSync(backupPath).ino;
+
+        const loaded = loadRawConfigFile({ configPath, tier: "user" });
+
+        expect(loaded?.migrated).toBe(true);
+        expect(readFileSync(backupPath)).toEqual(original);
+        expect(statSync(backupPath).ino).toBe(backupInode);
+    });
+
+    it("reloads the winning candidate when a concurrent loader replaces the target", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const original = Buffer.from('{\n  "historian": { "model": "provider/model" }\n}\n');
+        writeFileSync(configPath, original);
+
+        let competing: ReturnType<typeof loadRawConfigFile> | undefined;
+        const first = loadRawConfigFile({
+            configPath,
+            tier: "user",
+            afterTemporaryWrite: () => {
+                competing ??= loadRawConfigFile({ configPath, tier: "user" });
+            },
+        });
+
+        expect([first?.migrated, competing?.migrated].filter(Boolean)).toHaveLength(1);
+        expect(competing?.migrated).toBe(true);
+        expect(first?.migrated).toBe(false);
+        expect(first?.warnings).toEqual([]);
+        expect(competing?.warnings).toEqual([
+            "Migrated flat historian/dreamer model config to per-harness blocks.",
+        ]);
+        expect(first?.bytes).toEqual(competing?.bytes);
+        expect(parse(first?.text ?? "{}")).toEqual(parse(competing?.text ?? "{}"));
+        expect(readFileSync(configPath)).toEqual(competing?.bytes);
+        expect(readFileSync(`${configPath}.pre-per-harness.bak`)).toEqual(original);
+    });
+
+    it("adapts project config in memory without changing bytes or mtime", () => {
+        const directory = temporaryDirectory();
+        const configPath = join(directory, "magic-context.jsonc");
+        const original = Buffer.from(
+            '{\n  "dreamer": { "tasks": { "review": { "timeout_minutes": 30 } } }\n}\n',
+        );
+        writeFileSync(configPath, original);
+        const before = statSync(configPath);
+
+        const loaded = loadRawConfigFile({ configPath, tier: "project" });
+        const after = statSync(configPath);
+        const config = parse(loaded?.text ?? "{}");
+
+        expect(loaded?.migrated).toBe(false);
+        expect(loaded?.warnings[0]).toContain("Adapted flat model config in memory");
+        expect(readFileSync(configPath)).toEqual(original);
+        expect(after.mtimeMs).toBe(before.mtimeMs);
+        expect(
+            ((config.dreamer as Record<string, unknown>).opencode as Record<string, unknown>).tasks,
+        ).toEqual({ review: { timeout_minutes: 30 } });
+    });
+});