@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/cache-ttl-display.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "bun:test";
+
+import { initializeDatabase } from "../features/magic-context/storage-db";
+import { getOrCreateSessionMeta, updateSessionMeta } from "../features/magic-context/storage-meta";
+import { resolveCacheTtlDisplay } from "./cache-ttl-display";
+import { seedSessionCacheTtlIfUnsynced } from "./cache-ttl-seed";
+import { Database } from "./sqlite";
+
+const modelKey = "anthropic/claude-opus-5";
+
+describe("resolveCacheTtlDisplay", () => {
+    it("shows config before the first message_end sync", () => {
+        expect(
+            resolveCacheTtlDisplay({
+                configured: { default: "5m", [modelKey]: "1h" },
+                configuredExplicitly: true,
+                modelKey,
+                sessionValue: "5m",
+                sessionModelKey: null,
+            }),
+        ).toEqual({ value: "1h", source: "config", modelKey });
+    });
+
+    it("discriminates config, session, and guessed default provenance", () => {
+        const configured = resolveCacheTtlDisplay({
+            configured: "1h",
+            configuredExplicitly: true,
+            modelKey,
+            sessionValue: "5m",
+            sessionModelKey: null,
+        });
+        const session = resolveCacheTtlDisplay({
+            configured: "1h",
+            configuredExplicitly: true,
+            modelKey,
+            sessionValue: "45m",
+            sessionModelKey: modelKey,
+        });
+        const fallback = resolveCacheTtlDisplay({
+            configured: "5m",
+            configuredExplicitly: false,
+            modelKey,
+            sessionValue: "5m",
+            sessionModelKey: null,
+        });
+
+        expect(configured.source).toBe("config");
+        expect(session).toEqual({ value: "45m", source: "session", modelKey });
+        expect(fallback).toEqual({ value: "5m", source: "default", modelKey });
+    });
+
+    it("seeds only an unsynced row and leaves a scheduler-owned row unchanged", () => {
+        const db = new Database(":memory:");
+        initializeDatabase(db);
+        try {
+            expect(
+                seedSessionCacheTtlIfUnsynced({
+                    db,
+                    sessionId: "ses-seed",
+                    configured: { default: "5m", [modelKey]: "1h" },
+                    modelKey,
+                }),
+            ).toBe(true);
+            expect(getOrCreateSessionMeta(db, "ses-seed").cacheTtl).toBe("1h");
+
+            updateSessionMeta(db, "ses-seed", {
+                cacheTtl: "45m",
+                lastObservedModelKey: modelKey,
+                lastResponseTime: 1,
+            });
+            expect(
+                seedSessionCacheTtlIfUnsynced({
+                    db,
+                    sessionId: "ses-seed",
+                    configured: "2h",
+                    modelKey,
+                }),
+            ).toBe(false);
+            expect(getOrCreateSessionMeta(db, "ses-seed").cacheTtl).toBe("45m");
+        } finally {
+            db.close();
+        }
+    });
+});

package/src/shared/cache-ttl-display.ts

@@ -0,0 +1,58 @@
+import type { MagicContextConfig } from "../config/schema/magic-context";
+import { type ResolvedCacheTtl, resolveModelCacheTtl } from "./model-cache-ttl";
+
+export type CacheTtlDisplaySource = ResolvedCacheTtl["source"] | "session";
+
+export interface CacheTtlDisplay {
+    value: string;
+    source: CacheTtlDisplaySource;
+    modelKey: string | undefined;
+}
+
+export interface ResolveCacheTtlDisplayArgs {
+    frozen?: ResolvedCacheTtl;
+    configured: MagicContextConfig["cache_ttl"];
+    configuredExplicitly: boolean;
+    modelKey: string | undefined;
+    sessionValue: string;
+    /** Model key persisted with the last completed assistant response. */
+    sessionModelKey: string | null;
+}
+
+/**
+ * Resolve status-only TTL text without changing the scheduler's persisted truth.
+ * Use the session value only when its persisted model key matches the model being
+ * displayed; otherwise use live config because the session value may be for another model.
+ */
+export function resolveCacheTtlDisplay(args: ResolveCacheTtlDisplayArgs): CacheTtlDisplay {
+    if (args.frozen) return args.frozen;
+    if (
+        (args.sessionModelKey && (!args.modelKey || args.sessionModelKey === args.modelKey)) ||
+        (!args.modelKey && !args.sessionModelKey && args.sessionValue !== "5m")
+    ) {
+        return {
+            value: args.sessionValue || "5m",
+            source: "session",
+            modelKey: args.modelKey ?? args.sessionModelKey ?? undefined,
+        };
+    }
+
+    const resolved = resolveModelCacheTtl(args.configured, args.modelKey);
+    if (
+        resolved.source === "default" &&
+        typeof args.configured === "string" &&
+        args.configuredExplicitly
+    )
+        return { ...resolved, source: "config" };
+    return resolved;
+}
+
+export function formatCacheTtlDisplay(display: CacheTtlDisplay): string {
+    if (display.source === "OpenAI GPT-5.6+ default")
+        return `Cache TTL: ${display.value} (${display.source})`;
+    if (display.source === "session") return `Cache TTL: ${display.value} (session)`;
+    if (display.source === "config") {
+        return `Cache TTL: ${display.value} (config for ${display.modelKey ?? "current model"})`;
+    }
+    return `Cache TTL: ${display.value} (default — no cache_ttl for ${display.modelKey ?? "unknown model"})`;
+}

package/src/shared/cache-ttl-seed.ts

@@ -0,0 +1,23 @@
+import type { MagicContextConfig } from "../config/schema/magic-context";
+import { getOrCreateSessionMeta, updateSessionMeta } from "../features/magic-context/storage-meta";
+import { resolveModelConfigValue } from "./prompt-surface";
+import type { Database } from "./sqlite";
+
+/** Seed only before a completed assistant response has made the session row authoritative. */
+export function seedSessionCacheTtlIfUnsynced(args: {
+    db: Database;
+    sessionId: string;
+    configured: MagicContextConfig["cache_ttl"];
+    modelKey: string;
+}): boolean {
+    const meta = getOrCreateSessionMeta(args.db, args.sessionId);
+    if (meta.lastResponseTime !== 0 || meta.lastObservedModelKey !== null) return false;
+    const cacheTtl =
+        typeof args.configured === "string"
+            ? args.configured
+            : (resolveModelConfigValue(args.configured, args.modelKey)?.value ??
+              args.configured.default ??
+              "5m");
+    updateSessionMeta(args.db, args.sessionId, { cacheTtl });
+    return true;
+}

package/src/shared/child-session-teardown.test.ts

@@ -0,0 +1,241 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+
+import { teardownChildSession } from "./child-session-teardown";
+import { _resetKeepSubagentsForTesting, setKeepSubagents } from "./keep-subagents";
+import { Database } from "./sqlite";
+import { closeQuietly } from "./sqlite-helpers";
+
+interface TeardownFixture {
+    client: {
+        session: {
+            delete: ReturnType<typeof mock>;
+            update: ReturnType<typeof mock>;
+        };
+    };
+    calls: string[];
+    deleted: string[];
+    archived: string[];
+    messages: string[];
+}
+
+function teardownFixture(): TeardownFixture {
+    const calls: string[] = [];
+    const deleted: string[] = [];
+    const archived: string[] = [];
+    const messages: string[] = [];
+    return {
+        calls,
+        deleted,
+        archived,
+        messages,
+        client: {
+            session: {
+                update: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("archive");
+                    archived.push(path.id);
+                    return {};
+                }),
+                delete: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("delete");
+                    deleted.push(path.id);
+                    return {};
+                }),
+            },
+        },
+    };
+}
+
+afterEach(() => {
+    _resetKeepSubagentsForTesting();
+    mock.restore();
+});
+
+describe("teardownChildSession", () => {
+    test("deletes an ordinary child only after its prompt settles", async () => {
+        const fixture = teardownFixture();
+        await teardownChildSession({
+            client: fixture.client,
+            sessionId: "settled-ordinary",
+            sessionDirectory: "/repo",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => fixture.messages.push(message),
+        });
+
+        expect(fixture.deleted).toEqual(["settled-ordinary"]);
+        expect(fixture.archived).toEqual([]);
+    });
+
+    test("deletes a settled privacy child when keep_subagents is false", async () => {
+        const fixture = teardownFixture();
+        await teardownChildSession({
+            client: fixture.client,
+            sessionId: "settled-private",
+            promptSettled: true,
+            privacySensitive: true,
+            context: "private",
+            log: (message) => fixture.messages.push(message),
+        });
+
+        expect(fixture.deleted).toEqual(["settled-private"]);
+        expect(fixture.archived).toEqual([]);
+    });
+
+    test("keeps both settled ordinary and privacy children under keep_subagents", async () => {
+        setKeepSubagents(true);
+        const ordinary = teardownFixture();
+        await teardownChildSession({
+            client: ordinary.client,
+            sessionId: "kept-ordinary",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => ordinary.messages.push(message),
+        });
+        expect(ordinary.deleted).toEqual([]);
+
+        const privacy = teardownFixture();
+        await teardownChildSession({
+            client: privacy.client,
+            sessionId: "kept-private",
+            promptSettled: true,
+            privacySensitive: true,
+            context: "private",
+            log: (message) => privacy.messages.push(message),
+        });
+        expect(privacy.deleted).toEqual([]);
+    });
+
+    test("leaves an unsettled privacy child to the sweep regardless of keep_subagents", async () => {
+        for (const keepSubagents of [false, true]) {
+            setKeepSubagents(keepSubagents);
+            const fixture = teardownFixture();
+            const sessionId = `unsettled-private-${keepSubagents}`;
+            await teardownChildSession({
+                client: fixture.client,
+                sessionId,
+                sessionDirectory: "/repo",
+                promptSettled: false,
+                privacySensitive: true,
+                context: "private",
+                log: (message) => fixture.messages.push(message),
+            });
+
+            expect(fixture.deleted).toEqual([]);
+            expect(fixture.archived).toEqual([sessionId]);
+        }
+    });
+
+    test("archives an unsettled child before logging and leaves it intact", async () => {
+        const fixture = teardownFixture();
+        const db = new Database(":memory:");
+        db.exec(`
+            CREATE TABLE session (
+                id TEXT PRIMARY KEY,
+                title TEXT,
+                directory TEXT,
+                time_created INTEGER
+            );
+            INSERT INTO session VALUES (
+                'unsettled-private',
+                'magic-context-dream-map-memories',
+                '/repo',
+                1
+            );
+        `);
+        try {
+            await teardownChildSession({
+                client: fixture.client,
+                sessionId: "unsettled-private",
+                sessionDirectory: "/repo",
+                promptSettled: false,
+                privacySensitive: true,
+                context: "[maintenance] map-memories",
+                log: (message) => {
+                    fixture.calls.push("log");
+                    fixture.messages.push(message);
+                },
+            });
+
+            expect(fixture.calls).toEqual(["archive", "log"]);
+            expect(fixture.deleted).toEqual([]);
+            expect(fixture.messages).toEqual([
+                "[maintenance] map-memories: prompt unsettled — session unsettled-private left to the age-gated sweep",
+            ]);
+            expect(
+                db.prepare("SELECT id FROM session WHERE id = ?").get("unsettled-private"),
+            ).toEqual({
+                id: "unsettled-private",
+            });
+        } finally {
+            closeQuietly(db);
+        }
+    });
+});
+
+function productionTypeScriptFiles(directory: string): string[] {
+    const files: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) files.push(...productionTypeScriptFiles(path));
+        else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) files.push(path);
+    }
+    return files;
+}
+
+function clientSessionDeleteOffsets(path: string, source: string): number[] {
+    const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true);
+    const offsets: number[] = [];
+    const visit = (node: ts.Node): void => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const deleteAccess = node.expression;
+            const sessionAccess = deleteAccess.expression;
+            if (
+                deleteAccess.name.text === "delete" &&
+                ts.isPropertyAccessExpression(sessionAccess) &&
+                sessionAccess.name.text === "session" &&
+                (ts.isIdentifier(sessionAccess.expression)
+                    ? sessionAccess.expression.text === "client"
+                    : ts.isPropertyAccessExpression(sessionAccess.expression) &&
+                      sessionAccess.expression.name.text === "client")
+            ) {
+                offsets.push(node.getStart(sourceFile));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return offsets;
+}
+
+describe("child-session delete source fence", () => {
+    test("every client.session.delete call is the age-gated sweep or promptSettled-gated teardown", () => {
+        const sourceRoot = join(import.meta.dir, "..");
+        const sites: string[] = [];
+        for (const path of productionTypeScriptFiles(sourceRoot)) {
+            const source = readFileSync(path, "utf8");
+            for (const offset of clientSessionDeleteOffsets(path, source)) {
+                const line = source.slice(0, offset).split("\n").length;
+                sites.push(`${relative(sourceRoot, path)}:${line}`);
+            }
+        }
+
+        // Directory walk order differs between macOS and Linux; the fence is a set.
+        expect(sites.map((site) => site.replace(/:\d+$/, "")).sort()).toEqual([
+            "shared/child-session-teardown.ts",
+        ]);
+        const teardownSource = readFileSync(
+            join(sourceRoot, "shared/child-session-teardown.ts"),
+            "utf8",
+        );
+        expect(teardownSource).toMatch(
+            /if\s*\(\s*promptSettled[\s\S]{0,200}client\.session\.delete\s*\(/,
+        );
+    });
+});

package/src/shared/child-session-teardown.ts

@@ -0,0 +1,66 @@
+import { shouldKeepSubagents } from "./keep-subagents";
+
+interface ChildSessionRequest {
+    path: { id: string };
+    query?: { directory: string };
+}
+
+interface ArchiveChildSessionRequest extends ChildSessionRequest {
+    body: { time: { archived: number } };
+}
+
+export interface ChildSessionTeardownClient {
+    session: {
+        delete(request: ChildSessionRequest): Promise<unknown>;
+    };
+}
+
+export interface TeardownChildSessionArgs {
+    client: ChildSessionTeardownClient;
+    sessionId: string | null;
+    sessionDirectory?: string;
+    promptSettled: boolean;
+    privacySensitive: boolean;
+    context: string;
+    log: (message: string) => void;
+}
+
+/**
+ * Retire a child only after its prompt helper resolves. An unresolved client call
+ * can leave OpenCode's server loop writing, so that row is archived for immediate
+ * UI hiding and retained until the age-gated sweep can delete it safely.
+ *
+ * OpenCode's generated v2 SDK models archival as `session.update` with
+ * `time.archived`; the plugin's legacy path/body client reaches the same PATCH
+ * endpoint, although its generated TypeScript body type does not yet expose time.
+ */
+export async function teardownChildSession(args: TeardownChildSessionArgs): Promise<void> {
+    const { client, sessionId, sessionDirectory, promptSettled, context, log } = args;
+    if (!sessionId) return;
+
+    const request: ChildSessionRequest = {
+        path: { id: sessionId },
+        ...(sessionDirectory ? { query: { directory: sessionDirectory } } : {}),
+    };
+
+    // Retention keeps every settled child; only unsettled children go to the age-gated sweep.
+    if (promptSettled && !shouldKeepSubagents()) {
+        await client.session.delete(request).catch((error: unknown) => {
+            log(`${context}: session cleanup failed: ${String(error)}`);
+        });
+        return;
+    }
+
+    if (!promptSettled) {
+        const archiveSession = client.session as unknown as {
+            update?: (request: ArchiveChildSessionRequest) => Promise<unknown>;
+        };
+        await archiveSession
+            .update?.({
+                ...request,
+                body: { time: { archived: Date.now() } },
+            })
+            .catch(() => {});
+        log(`${context}: prompt unsettled — session ${sessionId} left to the age-gated sweep`);
+    }
+}

package/src/shared/commit-detection.test.ts

@@ -0,0 +1,63 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import {
+    COMMIT_HASH_TEST_PATTERN,
+    COMMIT_VERB_PATTERN,
+    createCommitHashExtractPattern,
+    textMentionsRecentCommit,
+} from "./commit-detection";
+
+describe("textMentionsRecentCommit", () => {
+    it("fires on a hash + commit-action verb in the same text", () => {
+        expect(textMentionsRecentCommit("Committed abc1234 with the fix")).toBe(true);
+        expect(textMentionsRecentCommit("merged a1b2c3d into main")).toBe(true);
+        expect(textMentionsRecentCommit("rebased onto feedb4d cleanly")).toBe(true);
+        expect(textMentionsRecentCommit("cherry-picked deadbeef")).toBe(true);
+    });
+
+    it("does NOT fire on a hash alone, or the bare word 'hash'/'sha' + hex", () => {
+        expect(textMentionsRecentCommit("the value is abc1234")).toBe(false);
+        // 'hash'/'sha' are intentionally NOT commit-action verbs (parity contract).
+        expect(textMentionsRecentCommit("hash is abc1234567")).toBe(false);
+        expect(textMentionsRecentCommit("sha abc1234")).toBe(false);
+    });
+
+    it("does NOT fire on a verb alone (no hash)", () => {
+        expect(textMentionsRecentCommit("I will commit later")).toBe(false);
+    });
+
+    it("respects the 7-12 hex length bound", () => {
+        expect(textMentionsRecentCommit("committed abc12")).toBe(false); // too short
+        expect(textMentionsRecentCommit("committed abc1234567890abcdef")).toBe(false); // too long
+    });
+
+    it("does not match commit-ish words that are not commit actions", () => {
+        expect(COMMIT_VERB_PATTERN.test("commitment to abc1234")).toBe(false);
+        expect(COMMIT_VERB_PATTERN.test("a merger of abc1234")).toBe(false);
+    });
+});
+
+describe("shared regex instances are stateless across calls", () => {
+    it("COMMIT_HASH_TEST_PATTERN.test is repeatable (non-global)", () => {
+        expect(COMMIT_HASH_TEST_PATTERN.test("abc1234")).toBe(true);
+        expect(COMMIT_HASH_TEST_PATTERN.test("abc1234")).toBe(true); // no lastIndex drift
+    });
+
+    it("createCommitHashExtractPattern returns a fresh global regex each call", () => {
+        const a = createCommitHashExtractPattern();
+        const b = createCommitHashExtractPattern();
+        expect(a).not.toBe(b);
+        expect(a.global).toBe(true);
+    });
+});
+
+describe("createCommitHashExtractPattern (historian extraction)", () => {
+    it("captures backtick-wrapped and bare hashes, deduped via matchAll", () => {
+        const text = "Committed `abc1234` and def5678, also abc1234 again";
+        const found = [...text.matchAll(createCommitHashExtractPattern())].map((m) =>
+            m[1]?.toLowerCase(),
+        );
+        expect(found).toEqual(["abc1234", "def5678", "abc1234"]);
+    });
+});

package/src/shared/commit-detection.ts

@@ -0,0 +1,53 @@
+// Canonical commit-detection patterns — the SINGLE source of truth shared by:
+//   - the historian commit-cluster trigger + summary hash extraction
+//     (read-session-formatting.ts),
+//   - the OpenCode note-nudge `commit_detected` boundary (tag-messages.ts),
+//   - the Pi note-nudge detector (detect-recent-commit.ts).
+//
+// These three previously each carried their own hash/verb regexes that had
+// drifted (hash length 6 vs 7; verb sets {hash, sha} vs {merge, rebas}). Keeping
+// them here stops that drift: change the patterns once and every site follows.
+//
+// All three sites look for a short git hash AND a commit-related word in the
+// SAME assistant text part — the pairing is what keeps false positives low.
+
+/** A short git hash: 7-12 hex chars (git's default abbreviated hash is 7).
+ *  6 was too loose — more random-hex false positives. */
+const HASH_HEX = "[0-9a-f]{7,12}";
+
+/**
+ * Boolean hash test. Non-global (stateless), so this single instance is safe to
+ * reuse with `.test()` across call sites — only `/g` regexes carry `lastIndex`.
+ */
+export const COMMIT_HASH_TEST_PATTERN = new RegExp(`\\b${HASH_HEX}\\b`, "i");
+
+/**
+ * Commit-ACTION verbs, with common inflections, each fully word-boundary-anchored
+ * (so they don't match e.g. "commitment"/"merger"). Non-global → safe to share.
+ *
+ * Scope decision: this is the commit-action set the OpenCode + Pi note-nudge
+ * detectors used and pin in tests ("commit/cherry-pick/merge/rebase"). It does
+ * NOT include the bare nouns "hash"/"sha" that the historian's old hint regex
+ * carried — a parity test asserts "hash <hex>" alone must NOT count as a commit,
+ * and those nouns only ever gated a cosmetic hash-strip in historian summaries
+ * (never a trigger), so unifying to the action set is behavior-preserving where
+ * it matters.
+ */
+export const COMMIT_VERB_PATTERN =
+    /\b(?:commit(?:ted|ting|s)?|cherry-?pick(?:ed|ing|s)?|merge[ds]?|merging|rebas(?:e|ed|es|ing))\b/i;
+
+/** True when a text part mentions a commit hash in a commit context. Used by the
+ *  OpenCode + Pi note-nudge detectors. */
+export function textMentionsRecentCommit(text: string): boolean {
+    return COMMIT_HASH_TEST_PATTERN.test(text) && COMMIT_VERB_PATTERN.test(text);
+}
+
+/**
+ * Fresh `/g` capturing, backtick-aware hash pattern for the historian's
+ * extract-and-strip path (matchAll + replace). Returned as a NEW instance per
+ * call: a `/g` regex carries `lastIndex`, so handing out a fresh one is
+ * bulletproof against accidental `.exec()` reuse across callers.
+ */
+export function createCommitHashExtractPattern(): RegExp {
+    return new RegExp(`\`?\\b(${HASH_HEX})\\b\`?`, "gi");
+}

package/src/shared/config-diagnostics.test.ts

@@ -0,0 +1,29 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+
+import {
+    type ConfigParseFailure,
+    claimConfigParseFailuresOnce,
+    resetClaimedConfigParseFailuresForTesting,
+} from "./config-diagnostics";
+
+const failure: ConfigParseFailure = {
+    warningClass: "file-parse",
+    source: "user",
+    path: "/tmp/mmc.jsonc",
+    line: 1,
+    column: 1,
+    message: "invalid symbol",
+    recovered: true,
+    warning: "/tmp/mmc.jsonc:1:1: invalid symbol",
+};
+
+describe("config parse warning notice claims", () => {
+    beforeEach(resetClaimedConfigParseFailuresForTesting);
+
+    it("emits each parse failure once per harness surface", () => {
+        expect(claimConfigParseFailuresOnce("opencode", [failure])).toEqual([failure]);
+        expect(claimConfigParseFailuresOnce("opencode", [failure])).toEqual([]);
+        expect(claimConfigParseFailuresOnce("pi", [failure])).toEqual([failure]);
+        expect(claimConfigParseFailuresOnce("pi", [failure])).toEqual([]);
+    });
+});

package/src/shared/config-diagnostics.ts

@@ -0,0 +1,64 @@
+export const CONFIG_WARNING_CLASS = {
+    FILE_PARSE: "file-parse",
+    FILE_IO: "file-io",
+    INVALID_LEAF: "invalid-leaf",
+} as const;
+
+export type ConfigWarningClass = (typeof CONFIG_WARNING_CLASS)[keyof typeof CONFIG_WARNING_CLASS];
+
+export interface ConfigParseFailure {
+    warningClass: typeof CONFIG_WARNING_CLASS.FILE_PARSE;
+    source: "user" | "project";
+    path: string;
+    line: number;
+    column: number;
+    message: string;
+    recovered: boolean;
+    warning: string;
+}
+
+export interface ConfigWarningDetail {
+    warningClass: ConfigWarningClass;
+    source?: "user" | "project";
+    path?: string;
+    line?: number;
+    column?: number;
+    message: string;
+}
+
+export function formatConfigParseStatusLine(failure: ConfigParseFailure): string {
+    const disposition = failure.recovered
+        ? "recovered values applied; fix the file"
+        : "running on defaults";
+    return `Config: PARSE FAILED (${failure.path}:${failure.line}:${failure.column}) — ${disposition}`;
+}
+
+export function formatConfigParseNotice(failures: readonly ConfigParseFailure[]): string {
+    const lines = failures.map(
+        (failure) => `${formatConfigParseStatusLine(failure)}\n${failure.message}`,
+    );
+    return ["⚠️ Magic Context config parse failure", ...lines].join("\n\n");
+}
+
+const claimedFailures = new Set<string>();
+
+function failureKey(surface: string, failure: ConfigParseFailure): string {
+    return `${surface}\0${failure.path}\0${failure.line}\0${failure.column}\0${failure.message}`;
+}
+
+/** Claim parse-failure notices once for each runtime surface in this process. */
+export function claimConfigParseFailuresOnce(
+    surface: "opencode" | "pi",
+    failures: readonly ConfigParseFailure[],
+): ConfigParseFailure[] {
+    return failures.filter((failure) => {
+        const key = failureKey(surface, failure);
+        if (claimedFailures.has(key)) return false;
+        claimedFailures.add(key);
+        return true;
+    });
+}
+
+export function resetClaimedConfigParseFailuresForTesting(): void {
+    claimedFailures.clear();
+}