@cortexkit/opencode-magic-context 0.42.6 → 0.43.1

package/src/config/live-run-config.test.ts

@@ -0,0 +1,237 @@
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+    buildDreamTaskRuntimeConfigs,
+    userMemoryCollectionEnabled,
+} from "../features/magic-context/dreamer/task-config";
+import { resolveHistorianModel } from "../shared/model-resolution";
+import { loadPluginConfigDetailed } from "./index";
+import { dreamerRunConfig, historianRunConfig } from "./live-run-config";
+import { LiveConfigReader } from "./live-snapshot";
+
+for (const host of ["OC1", "OC2", "Pi"] as const) {
+    test(`${host} historian samples the next generation while an existing run keeps its model and fallback`, () => {
+        const root = mkdtempSync(join(tmpdir(), "mc-live-historian-"));
+        const previous = { home: process.env.HOME, config: process.env.XDG_CONFIG_HOME };
+        process.env.HOME = root;
+        process.env.XDG_CONFIG_HOME = join(root, "config");
+        const directory = join(root, "project");
+        const file = join(root, "config", "cortexkit", "magic-context.jsonc");
+        mkdirSync(join(root, "config", "cortexkit"), { recursive: true });
+        mkdirSync(join(directory, ".cortexkit"), { recursive: true });
+        try {
+            const block = host === "Pi" ? "pi" : "opencode";
+            const write = (
+                model: string,
+                fallback: string,
+                autoPromote: boolean,
+                minClusters: number,
+            ) =>
+                writeFileSync(
+                    file,
+                    JSON.stringify({
+                        historian: { [block]: { model, fallback_models: [fallback] } },
+                        memory: { auto_promote: autoPromote },
+                        commit_cluster_trigger: { enabled: true, min_clusters: minClusters },
+                    }),
+                );
+            write("anthropic/old-model", "anthropic/old-fallback", true, 3);
+            const load = () => loadPluginConfigDetailed(directory, false).config;
+            const boot = load();
+            const reader = new LiveConfigReader(directory, boot, load, () => {});
+            reader.poll();
+            const runOne = historianRunConfig(boot, reader.current().effective);
+            write(
+                "anthropic/new-model-with-longer-name",
+                "anthropic/new-fallback-with-longer-name",
+                false,
+                5,
+            );
+            const runTwo = historianRunConfig(boot, reader.poll().effective);
+            const harness = host === "Pi" ? "pi" : "opencode";
+            expect(resolveHistorianModel(runOne, harness).primary?.model).toBe(
+                "anthropic/old-model",
+            );
+            expect(resolveHistorianModel(runOne, harness).fallbacks[0]?.model).toBe(
+                "anthropic/old-fallback",
+            );
+            expect(resolveHistorianModel(runTwo, harness).primary?.model).toBe(
+                "anthropic/new-model-with-longer-name",
+            );
+            expect(resolveHistorianModel(runTwo, harness).fallbacks[0]?.model).toBe(
+                "anthropic/new-fallback-with-longer-name",
+            );
+            expect(runOne.memory.auto_promote).toBe(true);
+            expect(runTwo.memory.auto_promote).toBe(false);
+            expect(runOne.commit_cluster_trigger.min_clusters).toBe(3);
+            expect(runTwo.commit_cluster_trigger.min_clusters).toBe(5);
+            expect(reader.current().generation).toBe(2);
+        } finally {
+            if (previous.home === undefined) delete process.env.HOME;
+            else process.env.HOME = previous.home;
+            if (previous.config === undefined) delete process.env.XDG_CONFIG_HOME;
+            else process.env.XDG_CONFIG_HOME = previous.config;
+            rmSync(root, { recursive: true, force: true });
+        }
+    });
+}
+
+for (const host of ["OC1", "OC2", "Pi"] as const) {
+    test(`${host} dreamer samples the new schedule and model chain without changing a running task`, () => {
+        const root = mkdtempSync(join(tmpdir(), "mc-live-dreamer-"));
+        const previous = { home: process.env.HOME, config: process.env.XDG_CONFIG_HOME };
+        process.env.HOME = root;
+        process.env.XDG_CONFIG_HOME = join(root, "config");
+        const directory = join(root, "project");
+        const userFile = join(root, "config", "cortexkit", "magic-context.jsonc");
+        const projectFile = join(directory, ".cortexkit", "magic-context.jsonc");
+        mkdirSync(join(root, "config", "cortexkit"), { recursive: true });
+        mkdirSync(join(directory, ".cortexkit"), { recursive: true });
+        try {
+            const block = host === "Pi" ? "pi" : "opencode";
+            writeFileSync(
+                userFile,
+                JSON.stringify({
+                    dreamer: { [block]: { model: "old/model", fallback_models: ["old/fallback"] } },
+                }),
+            );
+            const writeSchedule = (schedule: string) =>
+                writeFileSync(
+                    projectFile,
+                    JSON.stringify({
+                        dreamer: {
+                            tasks: {
+                                verify: { schedule },
+                                "review-user-memories": {
+                                    schedule: schedule === "0 3 * * *" ? "" : "0 0 * * *",
+                                },
+                            },
+                        },
+                    }),
+                );
+            writeSchedule("0 3 * * *");
+            const load = () => loadPluginConfigDetailed(directory, false).config;
+            const boot = load();
+            const reader = new LiveConfigReader(directory, boot, load, () => {});
+            reader.poll();
+            const runOne = dreamerRunConfig(boot, reader.current().effective);
+            writeFileSync(
+                userFile,
+                JSON.stringify({
+                    dreamer: {
+                        [block]: {
+                            model: "new/model-long",
+                            fallback_models: ["new/fallback-long"],
+                        },
+                    },
+                }),
+            );
+            writeSchedule("15 4 * * *");
+            const runTwo = dreamerRunConfig(boot, reader.poll().effective);
+            const task = (cfg: typeof runOne) =>
+                buildDreamTaskRuntimeConfigs(cfg.dreamer, host === "Pi" ? "pi" : "opencode").find(
+                    (entry) => entry.task === "verify",
+                )!;
+            expect(task(runOne).schedule).toBe("0 3 * * *");
+            expect(userMemoryCollectionEnabled(runOne.dreamer)).toBe(false);
+            expect(task(runOne).model?.model).toBe("old/model");
+            expect(task(runOne).fallbackModels[0]?.model).toBe("old/fallback");
+            expect(task(runTwo).schedule).toBe("15 4 * * *");
+            expect(
+                userMemoryCollectionEnabled(
+                    historianRunConfig(boot, reader.current().effective).dreamer,
+                ),
+            ).toBe(true);
+            expect(task(runTwo).model?.model).toBe("new/model-long");
+            expect(task(runTwo).fallbackModels[0]?.model).toBe("new/fallback-long");
+        } finally {
+            if (previous.home === undefined) delete process.env.HOME;
+            else process.env.HOME = previous.home;
+            if (previous.config === undefined) delete process.env.XDG_CONFIG_HOME;
+            else process.env.XDG_CONFIG_HOME = previous.config;
+            rmSync(root, { recursive: true, force: true });
+        }
+    });
+}
+
+test("malformed project config retains last good values and deduplicates the warning; project overrides remain tier-safe", () => {
+    const root = mkdtempSync(join(tmpdir(), "mc-live-tiers-"));
+    const previous = { home: process.env.HOME, config: process.env.XDG_CONFIG_HOME };
+    process.env.HOME = root;
+    process.env.XDG_CONFIG_HOME = join(root, "config");
+    const directory = join(root, "project");
+    const userFile = join(root, "config", "cortexkit", "magic-context.jsonc");
+    const projectFile = join(directory, ".cortexkit", "magic-context.jsonc");
+    mkdirSync(join(root, "config", "cortexkit"), { recursive: true });
+    mkdirSync(join(directory, ".cortexkit"), { recursive: true });
+    const warnings: string[] = [];
+    try {
+        writeFileSync(
+            userFile,
+            JSON.stringify({
+                dreamer: {
+                    opencode: { model: "user/model" },
+                    tasks: { verify: { schedule: "0 3 * * *" } },
+                    prompt: "trusted",
+                },
+                historian: { opencode: { model: "user/historian" } },
+            }),
+        );
+        writeFileSync(
+            projectFile,
+            JSON.stringify({
+                dreamer: {
+                    opencode: { model: "project/model" },
+                    tasks: { verify: { schedule: "1 3 * * *" } },
+                    prompt: "untrusted",
+                },
+                historian: { opencode: { model: "project/historian" } },
+            }),
+        );
+        const load = () => loadPluginConfigDetailed(directory, false).config;
+        const reader = new LiveConfigReader(directory, load(), load, (message) =>
+            warnings.push(message),
+        );
+        const first = reader.poll();
+        expect(first.effective.dreamer?.opencode?.model).toBe("project/model");
+        expect(first.effective.dreamer?.prompt).toBe("trusted");
+        expect(resolveHistorianModel(first.effective, "opencode").primary?.model).toBe(
+            "user/historian",
+        );
+        writeFileSync(projectFile, "{ broken:");
+        expect(reader.poll()).toBe(first);
+        expect(reader.poll()).toBe(first);
+        expect(warnings.filter((message) => message.includes("config reload failed"))).toHaveLength(
+            1,
+        );
+        writeFileSync(
+            projectFile,
+            JSON.stringify({
+                dreamer: {
+                    opencode: { model: "project/new-model" },
+                    tasks: { verify: { schedule: "2 3 * * *" } },
+                    prompt: "still-untrusted",
+                },
+                historian: { opencode: { model: "project/new-historian" } },
+            }),
+        );
+        const second = reader.poll();
+        expect(second.generation).toBe(2);
+        expect(second.effective.dreamer?.opencode?.model).toBe("project/new-model");
+        expect(second.effective.dreamer?.tasks?.verify.schedule).toBe("2 3 * * *");
+        expect(second.effective.dreamer?.prompt).toBe("trusted");
+        expect(resolveHistorianModel(second.effective, "opencode").primary?.model).toBe(
+            "user/historian",
+        );
+        expect(first.effective.dreamer?.opencode?.model).toBe("project/model");
+    } finally {
+        if (previous.home === undefined) delete process.env.HOME;
+        else process.env.HOME = previous.home;
+        if (previous.config === undefined) delete process.env.XDG_CONFIG_HOME;
+        else process.env.XDG_CONFIG_HOME = previous.config;
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/src/config/live-run-config.ts

@@ -0,0 +1,80 @@
+import { log } from "../shared/logger";
+import { loadPluginConfigDetailed, type MagicContextPluginConfig } from "./index";
+import { LiveConfigReader } from "./live-snapshot";
+import { LIVE_RELOAD_CONFIG_PATHS, type MagicContextConfig } from "./schema/magic-context";
+
+/** Copy only schema-marked live paths from fresh config; other settings retain boot values. */
+export function sampleLiveConfig<T extends MagicContextConfig>(boot: T, fresh: T): T {
+    const result = { ...boot } as Record<string, unknown>;
+    for (const path of LIVE_RELOAD_CONFIG_PATHS) {
+        const parts = path.split(".");
+        let value: unknown = fresh;
+        for (const part of parts) value = (value as Record<string, unknown> | undefined)?.[part];
+        let target = result;
+        for (const part of parts.slice(0, -1)) {
+            const child = target[part];
+            const copy =
+                child && typeof child === "object" && !Array.isArray(child)
+                    ? { ...(child as Record<string, unknown>) }
+                    : {};
+            target[part] = copy;
+            target = copy;
+        }
+        const leaf = parts.at(-1);
+        if (leaf !== undefined) target[leaf] = value;
+    }
+    return result as T;
+}
+
+export function changedLiveKeys(previous: MagicContextConfig, next: MagicContextConfig): string[] {
+    const at = (config: MagicContextConfig, path: string): unknown =>
+        path
+            .split(".")
+            .reduce<unknown>(
+                (node, part) => (node as Record<string, unknown> | undefined)?.[part],
+                config,
+            );
+    return LIVE_RELOAD_CONFIG_PATHS.filter(
+        (path) => JSON.stringify(at(previous, path)) !== JSON.stringify(at(next, path)),
+    );
+}
+
+export const historianRunConfig = sampleLiveConfig;
+export const dreamerRunConfig = sampleLiveConfig;
+
+const pluginReaders = new Map<string, LiveConfigReader<MagicContextPluginConfig>>();
+
+/** Shared by all OpenCode entry points for one project in this process. */
+export function pluginConfigReader(directory: string, boot: MagicContextPluginConfig) {
+    let reader = pluginReaders.get(directory);
+    if (!reader) {
+        reader = new LiveConfigReader(
+            directory,
+            boot,
+            () => {
+                const loaded = loadPluginConfigDetailed(directory, false);
+                if (
+                    loaded.loadOutcome === "project-file-parse-error" ||
+                    loaded.loadOutcome === "project-file-io-error" ||
+                    loaded.loadOutcome === "schema-recovery"
+                ) {
+                    throw new Error(
+                        `invalid configuration: ${loaded.config.configWarnings?.join("; ") ?? loaded.loadOutcome}`,
+                    );
+                }
+                return loaded.config;
+            },
+            // Into our own log file: console output lands in the host's stdout/stderr
+            // (for `opencode serve`, the terminal or service log the user reads).
+            (message) => log(`[config] ${message}`),
+            changedLiveKeys,
+        );
+        reader.poll();
+        pluginReaders.set(directory, reader);
+    }
+    return reader;
+}
+
+export function currentPluginConfigReader(directory: string) {
+    return pluginReaders.get(directory);
+}

package/src/config/live-schema-drift.test.ts

@@ -0,0 +1,67 @@
+import { expect, test } from "bun:test";
+
+import { buildSchema } from "../../scripts/build-schema";
+import { sampleLiveConfig } from "./live-run-config";
+import { LIVE_RELOAD_CONFIG_PATHS, type MagicContextConfig } from "./schema/magic-context";
+
+type SchemaNode = { properties?: Record<string, SchemaNode>; "x-mc-live-reload"?: boolean };
+
+function leaves(node: SchemaNode, prefix = ""): Array<{ path: string; marked: boolean }> {
+    return Object.entries(node.properties ?? {}).flatMap(([key, child]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        return child.properties
+            ? leaves(child, path)
+            : [{ path, marked: child["x-mc-live-reload"] === true }];
+    });
+}
+
+function assign(target: Record<string, unknown>, path: string, value: unknown): void {
+    const keys = path.split(".");
+    let node = target;
+    for (const key of keys.slice(0, -1)) {
+        node[key] ??= {};
+        node = node[key] as Record<string, unknown>;
+    }
+    node[keys.at(-1)!] = value;
+}
+
+function lookup(target: Record<string, unknown>, path: string): unknown {
+    return path
+        .split(".")
+        .reduce<unknown>(
+            (node, key) => (node as Record<string, unknown> | undefined)?.[key],
+            target,
+        );
+}
+
+test("schema live marks equal the keys sampled by producer consumers and published JSON schema", async () => {
+    const generated = buildSchema() as SchemaNode;
+    const published = (await Bun.file(
+        new URL("../../../../assets/magic-context.schema.json", import.meta.url),
+    ).json()) as SchemaNode;
+    const generatedLive = leaves(generated)
+        .filter((row) => row.marked)
+        .map((row) => row.path)
+        .sort();
+    const publishedLive = leaves(published)
+        .filter((row) => row.marked)
+        .map((row) => row.path)
+        .sort();
+    const boot = {} as Record<string, unknown>;
+    const fresh = {} as Record<string, unknown>;
+    for (const row of leaves(generated)) assign(fresh, row.path, `changed:${row.path}`);
+    const sampled = sampleLiveConfig(
+        boot as MagicContextConfig,
+        fresh as MagicContextConfig,
+    ) as Record<string, unknown>;
+    const consumed = leaves(generated)
+        .filter((row) => lookup(sampled, row.path) === `changed:${row.path}`)
+        .map((row) => row.path)
+        .sort();
+    expect(generatedLive).toEqual([...LIVE_RELOAD_CONFIG_PATHS].sort());
+    expect(publishedLive).toEqual(generatedLive);
+    expect(consumed).toEqual(generatedLive);
+    expect(generatedLive).not.toContain("language");
+    expect(generatedLive).not.toContain("historian.top_p");
+    expect(generatedLive).not.toContain("protected_tokens");
+});

package/src/config/live-snapshot.test.ts

@@ -0,0 +1,85 @@
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parseJsonc } from "../shared/jsonc-parser";
+import { LiveConfigReader } from "./live-snapshot";
+
+test("one snapshot per run survives a malformed tier and adopts both tiers atomically", () => {
+    const oldConfigHome = process.env.XDG_CONFIG_HOME;
+    const root = mkdtempSync(join(tmpdir(), "mc-live-config-"));
+    const project = join(root, "project");
+    const projectFile = join(project, ".cortexkit", "magic-context.jsonc");
+    const userFile = join(root, "config", "cortexkit", "magic-context.jsonc");
+    mkdirSync(join(project, ".cortexkit"), { recursive: true });
+    mkdirSync(join(root, "config", "cortexkit"), { recursive: true });
+    process.env.XDG_CONFIG_HOME = join(root, "config");
+    try {
+        const logs: string[] = [];
+        writeFileSync(userFile, '{"historian":{"model":"user"}}');
+        writeFileSync(projectFile, '{"historian":{"model":"project"}}');
+        const load = () => {
+            const user = parseJsonc<{ historian: { model: string } }>(
+                readFileSync(userFile, "utf8"),
+            );
+            const projectConfig = parseJsonc<{ historian: { model: string } }>(
+                readFileSync(projectFile, "utf8"),
+            );
+            return { model: projectConfig.historian.model ?? user.historian.model };
+        };
+        const reader = new LiveConfigReader(project, load(), load, (line) => logs.push(line));
+        const first = reader.poll();
+        expect(first.generation).toBe(1);
+        writeFileSync(projectFile, '{"historian":');
+        expect(reader.poll()).toBe(first);
+        expect(reader.lastFailure()?.path).toBe(projectFile);
+        reader.poll();
+        expect(logs.filter((line) => line.includes("reload failed"))).toHaveLength(1);
+        writeFileSync(projectFile, '{"historian":{"model":"second-model"}}');
+        const second = reader.poll();
+        expect(second.generation).toBe(2);
+        expect(second.effective.model).toBe("second-model");
+        expect(first.effective.model).toBe("project");
+        expect(reader.lastFailure()).toBeUndefined();
+        expect(logs.filter((line) => line.includes("config reloaded"))).toEqual([
+            "config reloaded gen=2 keys=[model]",
+        ]);
+    } finally {
+        if (oldConfigHome === undefined) delete process.env.XDG_CONFIG_HOME;
+        else process.env.XDG_CONFIG_HOME = oldConfigHome;
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test("a write crossing the tier load boundary is not published as a mixed snapshot", () => {
+    const root = mkdtempSync(join(tmpdir(), "mc-live-crossing-"));
+    const previous = process.env.XDG_CONFIG_HOME;
+    process.env.XDG_CONFIG_HOME = join(root, "config");
+    const project = join(root, "project");
+    const file = join(project, ".cortexkit", "magic-context.jsonc");
+    mkdirSync(join(project, ".cortexkit"), { recursive: true });
+    try {
+        writeFileSync(file, '{"model":"old"}');
+        let crossWrite = false;
+        const load = () => {
+            if (crossWrite) {
+                crossWrite = false;
+                writeFileSync(file, '{"model":"newest-longer"}');
+            }
+            return { model: JSON.parse(readFileSync(file, "utf8")).model as string };
+        };
+        const reader = new LiveConfigReader(project, load(), load, () => {});
+        reader.poll();
+        writeFileSync(file, '{"model":"intermediate"}');
+        crossWrite = true;
+        expect(reader.poll().effective.model).toBe("old");
+        expect(reader.current().generation).toBe(1);
+        expect(reader.poll().effective.model).toBe("newest-longer");
+        expect(reader.current().generation).toBe(2);
+    } finally {
+        if (previous === undefined) delete process.env.XDG_CONFIG_HOME;
+        else process.env.XDG_CONFIG_HOME = previous;
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/src/config/live-snapshot.ts

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+import { detectConfigFile, parseJsoncRecovering } from "../shared/jsonc-parser";
+import {
+    cortexKitProjectConfigBasePath,
+    cortexKitUserConfigBasePath,
+} from "./migrate-config-location";
+
+export interface ConfigSnapshot<T> {
+    readonly generation: number;
+    readonly digest: string;
+    readonly adoptedAt: number;
+    readonly effective: T;
+}
+
+export interface ConfigReloadFailure {
+    readonly path: string;
+    readonly message: string;
+    readonly digest: string;
+}
+
+interface FileState {
+    metadata: string;
+    digest: string;
+}
+
+/**
+ * Publishes a project configuration only after the user and project files parse
+ * and the loader assembles the final effective configuration successfully.
+ */
+export class LiveConfigReader<T> {
+    private snapshot: ConfigSnapshot<T>;
+    private files = new Map<string, FileState>();
+    private initialized = false;
+    private warned = new Set<string>();
+    private failure: ConfigReloadFailure | undefined;
+
+    constructor(
+        private readonly directory: string,
+        initial: T,
+        private readonly load: () => T,
+        // Callers pass the host's log sink; the default is silent so a caller that
+        // forgets never writes into the host process's stderr.
+        private readonly onLog: (message: string) => void = () => {},
+        private readonly changedKeys: (previous: T, next: T) => readonly string[] = (
+            previous,
+            next,
+        ) =>
+            Object.keys(next as object).filter(
+                (key) =>
+                    JSON.stringify((previous as Record<string, unknown>)[key]) !==
+                    JSON.stringify((next as Record<string, unknown>)[key]),
+            ),
+    ) {
+        this.snapshot = {
+            generation: 1,
+            digest: "initial",
+            adoptedAt: Date.now(),
+            effective: initial,
+        };
+    }
+
+    current(): ConfigSnapshot<T> {
+        return this.snapshot;
+    }
+
+    lastFailure(): ConfigReloadFailure | undefined {
+        return this.failure;
+    }
+
+    poll(): ConfigSnapshot<T> {
+        const paths = [
+            cortexKitUserConfigBasePath(),
+            cortexKitProjectConfigBasePath(this.directory),
+        ].map((base) => detectConfigFile(base).path);
+        const next = new Map<string, FileState>();
+        let changed = paths.some((path) => !this.files.has(path));
+        for (const path of paths) {
+            let metadata: string;
+            try {
+                const stat = statSync(path);
+                metadata = `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                    this.reportFailure(path, String(error), error);
+                    return this.snapshot;
+                }
+                metadata = "absent";
+            }
+            const previous = this.files.get(path);
+            if (previous?.metadata === metadata) {
+                next.set(path, previous);
+                continue;
+            }
+            let content: string;
+            try {
+                content = metadata === "absent" ? "" : readFileSync(path, "utf8");
+            } catch (error) {
+                this.reportFailure(path, String(error), error);
+                return this.snapshot;
+            }
+            const digest = createHash("sha256").update(content).digest("hex");
+            if (metadata !== "absent") {
+                const parsed = parseJsoncRecovering(content);
+                if (
+                    parsed.issues.length ||
+                    !parsed.value ||
+                    typeof parsed.value !== "object" ||
+                    Array.isArray(parsed.value)
+                ) {
+                    const issue = parsed.issues[0];
+                    this.reportFailure(
+                        path,
+                        digest,
+                        issue
+                            ? `${issue.line}:${issue.column}: ${issue.message}`
+                            : "expected an object",
+                    );
+                    return this.snapshot;
+                }
+            }
+            next.set(path, { metadata, digest });
+            changed ||= previous?.digest !== digest;
+        }
+        if (!changed) {
+            this.files = next;
+            return this.snapshot;
+        }
+        let effective: T;
+        try {
+            effective = this.load();
+        } catch (error) {
+            this.reportFailure(paths[0] ?? this.directory, "load", error);
+            return this.snapshot;
+        }
+        // The loader reads both tiers again. A concurrent writer must not let it
+        // publish a mixed user/project pair under the metadata staged above.
+        for (const path of paths) {
+            let metadata = "absent";
+            try {
+                const stat = statSync(path);
+                metadata = `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                    this.reportFailure(path, String(error), error);
+                    return this.snapshot;
+                }
+            }
+            if (metadata !== next.get(path)?.metadata) return this.snapshot;
+        }
+        const digest = createHash("sha256")
+            .update(paths.map((path) => `${path}:${next.get(path)?.digest}`).join("\n"))
+            .digest("hex");
+        this.files = next;
+        this.failure = undefined;
+        if (!this.initialized) {
+            this.initialized = true;
+            this.snapshot = {
+                generation: 1,
+                digest,
+                adoptedAt: this.snapshot.adoptedAt,
+                effective,
+            };
+        } else if (this.snapshot.digest !== digest) {
+            const keys = this.changedKeys(this.snapshot.effective, effective);
+            this.snapshot = {
+                generation: this.snapshot.generation + 1,
+                digest,
+                adoptedAt: Date.now(),
+                effective,
+            };
+            // A file can change (a save, a comment edit) without any setting changing;
+            // only a real change is worth a line.
+            if (keys.length > 0) {
+                this.onLog(
+                    `config reloaded gen=${this.snapshot.generation} keys=[${keys.join(",")}]`,
+                );
+            }
+        }
+        return this.snapshot;
+    }
+
+    private reportFailure(path: string, digest: string, error: unknown): void {
+        const message = error instanceof Error ? error.message : String(error);
+        this.failure = { path, message, digest };
+        if (this.warned.has(`${path}:${digest}`)) return;
+        this.warned.add(`${path}:${digest}`);
+        this.onLog(`config reload failed ${path}: ${message}`);
+    }
+}

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

@@ -168,6 +168,7 @@ describe("per-harness raw config migration", () => {
         const taskRetained = {
             schedule: "0 3 * * *",
             promotion_threshold: 4,
+            recency_days: 30,
         };
         expect(Object.keys(historianRetained)).toEqual(
             PER_HARNESS_MIGRATION_INVENTORY.historian.retained,