@cortexkit/opencode-magic-context 0.47.0 → 0.49.0

package/src/shared/host-stall-profiler-report.ts

@@ -0,0 +1,248 @@
+/**
+ * Shared host stall report helpers. Both JavaScriptCore and V8 samples use
+ * innermost-first frames so native calls can be attributed to their JS caller.
+ *
+ * Kept separate from runtime backends so attribution can be tested without
+ * running watchdog timers or starting a sampling profiler.
+ */
+
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
+/** One frame from Bun's JavaScriptCore sampling API; V8 frames are normalized to this shape. */
+export interface JscSampleFrame {
+    name?: string;
+    sourceURL?: string;
+    line?: number;
+    column?: number;
+    category?: string;
+}
+
+/** One sample: `frames[0]` is the innermost (currently executing) frame. */
+export interface JscSampleTrace {
+    /** Monotonic seconds. JSC has a separate origin; V8 conversion uses the watchdog clock. */
+    timestamp?: number;
+    frames?: JscSampleFrame[];
+}
+
+/** Deepest stack kept per sample; deeper frames are folded into one marker. */
+export const MAX_STACK_DEPTH = 64;
+export const TOP_STACK_COUNT = 30;
+export const TOP_FRAME_COUNT = 30;
+
+/** JSC uses UINT32_MAX for "no line/column known". */
+const UNKNOWN_POSITION = 4294967295;
+
+/**
+ * Owners that never explain a stall by themselves: a native host function is
+ * attributed to its JavaScript caller, and host-core/runtime frames sit below
+ * every plugin hook. A sample is attributed to the innermost frame whose owner
+ * is NOT one of these, so a plugin calling a blocking native API is blamed,
+ * not the native API or the host that invoked the plugin.
+ */
+const BACKGROUND_OWNERS = new Set(["native", "runtime", "opencode", "pi", "omp"]);
+
+const packageNameCache = new Map<string, string | null>();
+
+function urlToPath(url: string): string {
+    if (url.startsWith("file://")) {
+        try {
+            return decodeURIComponent(new URL(url).pathname);
+        } catch {
+            return url.slice("file://".length);
+        }
+    }
+    return url;
+}
+
+/**
+ * Nearest `package.json` name above a source file, memoized per directory.
+ * Only reached for sources outside `node_modules` (a plugin loaded from a
+ * local checkout), and only after a stall has ended, so the bounded
+ * synchronous reads never run on a hot path.
+ */
+function nearestPackageName(filePath: string): string | null {
+    let dir = path.dirname(filePath);
+    const visited: string[] = [];
+    for (let depth = 0; depth < 12; depth++) {
+        const cached = packageNameCache.get(dir);
+        if (cached !== undefined) {
+            for (const seen of visited) packageNameCache.set(seen, cached);
+            return cached;
+        }
+        visited.push(dir);
+        try {
+            const parsed = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")) as {
+                name?: unknown;
+            };
+            const name = typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+            if (name) {
+                for (const seen of visited) packageNameCache.set(seen, name);
+                return name;
+            }
+        } catch {
+            // No readable package.json at this level; keep walking up.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    for (const seen of visited) packageNameCache.set(seen, null);
+    return null;
+}
+
+/**
+ * Map a frame's source URL to the code that owns it.
+ *
+ * - no URL: `native` (a host function such as a SQLite `get` or `readFileSync`)
+ * - Bun/Node builtin modules: `runtime`
+ * - the compiled OpenCode binary's embedded filesystem (`$bunfs`, `~BUN`): `opencode`
+ * - anything under `node_modules/<pkg>`: `npm:<pkg>` (the innermost package)
+ * - Pi/OMP core packages: `pi` / `omp`; agent extensions: package name or `extension:<entry>`
+ * - a file in an OpenCode `plugin/` or `plugins/` directory: `plugin:<file>`
+ * - any other file: `pkg:<name>` from the nearest package.json, else `file:<path>`
+ */
+export function sourceOwner(sourceURL: string | undefined): string {
+    if (!sourceURL) return "native";
+    if (/^(?:node|bun|builtin|internal):/.test(sourceURL)) return "runtime";
+    if (sourceURL.includes("$bunfs") || sourceURL.includes("~BUN")) return "opencode";
+    const filePath = urlToPath(sourceURL).replaceAll("\\", "/");
+    const modules = [...filePath.matchAll(/\/node_modules\/((?:@[^/]+\/)?[^/]+)/g)];
+    const innermost = modules.at(-1);
+    if (innermost) {
+        const name = innermost[1];
+        if (name === "@cortexkit/pi-magic-context") return `pkg:${name}`;
+        if (/^@(?:earendil-works|mariozechner)\/pi-(?:coding-agent|agent-core|ai|tui)$/.test(name))
+            return "pi";
+        if (/^@oh-my-pi\/pi-(?:coding-agent|agent-core|ai|tui)$/.test(name)) return "omp";
+        return `npm:${name}`;
+    }
+    const extension = filePath.match(/\/(?:\.pi|\.omp)\/agent\/extensions\/([^/]+)/);
+    if (extension) {
+        const name = nearestPackageName(filePath);
+        return name ? `pkg:${name}` : `extension:${extension[1]}`;
+    }
+    const pluginDir = filePath.match(/\/plugins?\/([^/]+)$/);
+    if (pluginDir && /\/(?:\.?opencode)\/plugins?\//.test(filePath)) {
+        return `plugin:${pluginDir[1]}`;
+    }
+    const name = nearestPackageName(filePath);
+    return name ? `pkg:${name}` : `file:${filePath}`;
+}
+
+function frameLabel(frame: JscSampleFrame): string {
+    const name = frame.name && frame.name.length > 0 ? frame.name : "(anonymous)";
+    if (!frame.sourceURL) return `${name} [native]`;
+    const line =
+        typeof frame.line === "number" && frame.line !== UNKNOWN_POSITION ? `:${frame.line}` : "";
+    return `${name} ${frame.sourceURL}${line}`;
+}
+
+export interface OwnedFrame {
+    label: string;
+    owner: string;
+}
+
+/** Prefer the innermost plugin/extension frame over native, runtime or host-core callers. */
+export function attributeSample(frames: OwnedFrame[]): string {
+    for (const frame of frames) {
+        if (!BACKGROUND_OWNERS.has(frame.owner)) return frame.owner;
+    }
+    for (const frame of frames) {
+        if (frame.owner !== "native") return frame.owner;
+    }
+    return "native";
+}
+
+export interface CountedFrame {
+    frame: string;
+    owner: string;
+    samples: number;
+}
+
+export interface CountedStack {
+    samples: number;
+    owner: string;
+    frames: string[];
+}
+
+export interface StallAggregate {
+    samples: number;
+    owners: Array<{ owner: string; samples: number; percent: number }>;
+    /** Innermost frame of each sample, native host functions included. */
+    top_frames: CountedFrame[];
+    /** Innermost frame that has JavaScript source, i.e. the JS caller of any native frame. */
+    top_js_frames: CountedFrame[];
+    top_stacks: CountedStack[];
+}
+
+function bump<T>(map: Map<string, T & { samples: number }>, key: string, init: () => T): void {
+    const existing = map.get(key);
+    if (existing) existing.samples += 1;
+    else map.set(key, { ...init(), samples: 1 });
+}
+
+function topBySamples<T extends { samples: number }>(values: Iterable<T>, limit: number): T[] {
+    return [...values].sort((a, b) => b.samples - a.samples).slice(0, limit);
+}
+
+export function aggregateTraces(traces: JscSampleTrace[]): StallAggregate {
+    const ownerOf = new Map<string, string>();
+    const owned = (frame: JscSampleFrame): OwnedFrame => {
+        const url = frame.sourceURL ?? "";
+        let owner = ownerOf.get(url);
+        if (owner === undefined) {
+            owner = sourceOwner(frame.sourceURL);
+            ownerOf.set(url, owner);
+        }
+        return { label: frameLabel(frame), owner };
+    };
+
+    const owners = new Map<string, { owner: string; samples: number }>();
+    const topFrames = new Map<string, CountedFrame>();
+    const topJsFrames = new Map<string, CountedFrame>();
+    const stacks = new Map<string, CountedStack>();
+    let samples = 0;
+
+    for (const trace of traces) {
+        const raw = Array.isArray(trace.frames) ? trace.frames : [];
+        if (raw.length === 0) continue;
+        samples += 1;
+        const frames = raw.slice(0, MAX_STACK_DEPTH).map(owned);
+        const owner = attributeSample(frames);
+        bump(owners, owner, () => ({ owner }));
+
+        const leaf = frames[0];
+        bump(topFrames, `${leaf.owner}\u0000${leaf.label}`, () => ({
+            frame: leaf.label,
+            owner: leaf.owner,
+        }));
+        const jsIndex = raw.findIndex(
+            (frame, index) => index < MAX_STACK_DEPTH && !!frame.sourceURL,
+        );
+        if (jsIndex >= 0) {
+            const js = frames[jsIndex];
+            bump(topJsFrames, `${js.owner}\u0000${js.label}`, () => ({
+                frame: js.label,
+                owner: js.owner,
+            }));
+        }
+
+        const labels = frames.map((frame) => `${frame.label} (${frame.owner})`);
+        if (raw.length > MAX_STACK_DEPTH) {
+            labels.push(`… ${raw.length - MAX_STACK_DEPTH} outer frames omitted`);
+        }
+        bump(stacks, labels.join("\n"), () => ({ owner, frames: labels }));
+    }
+
+    return {
+        samples,
+        owners: topBySamples(owners.values(), Number.POSITIVE_INFINITY).map((entry) => ({
+            ...entry,
+            percent: samples === 0 ? 0 : Math.round((entry.samples / samples) * 1000) / 10,
+        })),
+        top_frames: topBySamples(topFrames.values(), TOP_FRAME_COUNT),
+        top_js_frames: topBySamples(topJsFrames.values(), TOP_FRAME_COUNT),
+        top_stacks: topBySamples(stacks.values(), TOP_STACK_COUNT),
+    };
+}

package/src/shared/host-stall-profiler.ts

@@ -0,0 +1,57 @@
+import * as path from "node:path";
+import { getMagicContextStorageDir } from "./data-path";
+import { createHostStallProfiler } from "./host-stall-profiler-bun";
+import {
+    HOST_PROFILER_DIRNAME,
+    type HostStallProfilerHandle,
+    type ProfilerRuntimeDeps,
+} from "./host-stall-profiler-common";
+import { createNodeHostStallProfiler, type InspectorSession } from "./host-stall-profiler-node";
+import { log } from "./logger";
+
+export * from "./host-stall-profiler-common";
+
+export function hostStallProfilerDir(): string {
+    return path.join(getMagicContextStorageDir(), HOST_PROFILER_DIRNAME);
+}
+
+const PROCESS_PROFILER_KEY = Symbol.for("cortexkit.magic-context.host-stall-profiler");
+// Resolve at runtime: Node-only consumers do not install Bun's type declarations.
+const jscModule: string = "bun:jsc";
+
+/** All plugin/project instances watch the same main thread and share one sampler. */
+export function startHostStallProfilerSwitch(): void {
+    try {
+        const holder = globalThis as unknown as Record<symbol, HostStallProfilerHandle | undefined>;
+        if (holder[PROCESS_PROFILER_KEY]) return;
+        const deps: ProfilerRuntimeDeps = {
+            profilerDir: hostStallProfilerDir,
+            now: () => performance.now(),
+            wallNow: () => Date.now(),
+            setInterval: (callback, ms) => {
+                const handle = setInterval(callback, ms);
+                (handle as { unref?: () => void }).unref?.();
+                return handle;
+            },
+            clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+            rss: () => process.memoryUsage.rss(),
+            log,
+            pid: process.pid,
+            bunVersion: process.versions.bun ?? null,
+        };
+        const handle = process.versions.bun
+            ? createHostStallProfiler({ ...deps, loadJsc: () => import(jscModule) })
+            : createNodeHostStallProfiler({
+                  ...deps,
+                  createSession: async () => {
+                      const { Session } = await import("node:inspector");
+                      return new Session() as unknown as InspectorSession;
+                  },
+                  memoryUsage: () => process.memoryUsage(),
+              });
+        holder[PROCESS_PROFILER_KEY] = handle;
+        handle.start();
+    } catch (error) {
+        log("[magic-context] host stall profiler: could not start the enable-file switch", error);
+    }
+}

package/src/shared/logger.test.ts

@@ -129,6 +129,28 @@ if (scenario === "retry") {
         predecessorMode: fs.statSync(predecessorPath).mode & 0o777,
         files: fs.readdirSync(path.dirname(logPath)).filter((name) => name.startsWith("magic-context.log")).sort(),
     }));
+} else if (scenario === "stale-rotation") {
+    const maxLogBytes = 32 * 1024 * 1024;
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.writeFileSync(logPath, Buffer.alloc(maxLogBytes - 200, "o"));
+    fs.chmodSync(logPath, 0o600);
+    // This process now caches a size just under the bound.
+    logger.log("cached size");
+    logger.flushLogger();
+
+    // Another process sharing the file rotates it: the full log becomes the
+    // predecessor and the current file starts over.
+    fs.copyFileSync(logPath, logPath + ".1");
+    fs.writeFileSync(logPath, "written by the other process\\n");
+
+    // A line that crosses the bound only by this process's stale cached size.
+    logger.log("x".repeat(400));
+    logger.flushLogger();
+    console.log(JSON.stringify({
+        current: fs.readFileSync(logPath, "utf8"),
+        predecessorFirstByte: fs.readFileSync(logPath + ".1")[0],
+        predecessorSize: fs.statSync(logPath + ".1").size,
+    }));
 } else if (scenario === "hot-path") {
     for (let index = 0; index < 20; index++) {
         logger.log("hot-path-" + index);
@@ -182,6 +204,7 @@ async function runLoggerScenario<T>(
         | "recovery"
         | "diagnostics"
         | "rotation"
+        | "stale-rotation"
         | "hot-path"
         | "retry"
         | "bounded"
@@ -269,6 +292,21 @@ describe("logger", () => {
         }
     });
 
+    test("a stale cached size does not rotate a file another process already rotated", async () => {
+        const result = await runLoggerScenario<{
+            current: string;
+            predecessorFirstByte: number;
+            predecessorSize: number;
+        }>("stale-rotation");
+
+        // The other process's full predecessor survives, and the new line joins
+        // the restarted current file instead of replacing that predecessor.
+        expect(result.predecessorFirstByte).toBe("o".charCodeAt(0));
+        expect(result.predecessorSize).toBeGreaterThan(32 * 1024 * 1024 - 1024);
+        expect(result.current).toContain("written by the other process");
+        expect(result.current).toContain("x".repeat(400));
+    });
+
     test("uses cached size between periodic rotation checks", async () => {
         const result = await runLoggerScenario<HotPathScenarioResult>("hot-path");
 

package/src/shared/logger.ts

@@ -163,8 +163,16 @@ function flush(): void {
         let currentSize = getCurrentLogSize(logFile);
         const dataSize = Buffer.byteLength(data);
         if (currentSize > 0 && currentSize + dataSize > MAX_LOG_FILE_BYTES) {
-            rotateLogFile(logFile, currentSize);
-            currentSize = 0;
+            // Several processes share this file and each caches its size. A stale
+            // cache must not rotate a file another process already rotated: that
+            // second rotation would overwrite the full predecessor with the few
+            // lines written since. Decide on the file's real size instead.
+            flushesSinceSizeCheck = SIZE_CHECK_INTERVAL_FLUSHES;
+            currentSize = getCurrentLogSize(logFile);
+            if (currentSize > 0 && currentSize + dataSize > MAX_LOG_FILE_BYTES) {
+                rotateLogFile(logFile, currentSize);
+                currentSize = 0;
+            }
         }
         fs.appendFileSync(logFile, data, { encoding: "utf8", mode: 0o600 });
         buffer = [];

package/src/shared/model-resolution.test.ts

@@ -231,41 +231,78 @@ describe("model-resolution", () => {
         });
     });
 
-    test("uses mural model between compress-cues task and harness default", () => {
+    test("resolves compress-cues to each harness's dreamer default and ignores mural.model", () => {
+        // The retired shared mural.model sits in the same config to prove it
+        // no longer feeds resolution on any harness.
         const config = {
+            mural: { enabled: true, model: "google/antigravity-gemini-3.8-flash" },
             dreamer: {
                 tasks: { "compress-cues": { schedule: "0 4 * * *" } },
                 opencode: {
                     model: { model: "open/default", variant: "default-variant" },
-                    tasks: { "compress-cues": { variant: "task-local-must-not-leak" } },
                 },
                 pi: {
-                    model: { model: "pi/default", thinking_level: "high" },
+                    model: {
+                        model: "google-antigravity/antigravity-gemini-3.8-flash",
+                        thinking_level: "high",
+                    },
                     tasks: { "compress-cues": {} },
                 },
             },
         };
 
         expect(
-            resolveDreamerTaskModel({
-                config,
-                harness: "opencode",
-                task: "compress-cues",
-                muralModel: "mural/model",
-            }),
+            resolveDreamerTaskModel({ config, harness: "opencode", task: "compress-cues" }),
         ).toMatchObject({
-            primary: { model: "mural/model", qualifier: "default-variant" },
+            primary: { model: "open/default", qualifier: "default-variant" },
             fallbacks: [],
+            schedule: "0 4 * * *",
         });
         expect(
-            resolveDreamerTaskModel({
-                config,
-                harness: "pi",
-                task: "compress-cues",
-                muralModel: "mural/model",
-            }),
+            resolveDreamerTaskModel({ config, harness: "pi", task: "compress-cues" }),
+        ).toMatchObject({
+            primary: {
+                model: "google-antigravity/antigravity-gemini-3.8-flash",
+                qualifier: "high",
+            },
+            fallbacks: [],
+            schedule: "0 4 * * *",
+        });
+    });
+
+    test("a per-harness compress-cues task override wins over the harness default", () => {
+        const config = {
+            mural: { enabled: true, model: "shared/must-not-win" },
+            dreamer: {
+                opencode: {
+                    model: "open/default",
+                    fallback_models: ["open/default-fallback"],
+                    tasks: {
+                        "compress-cues": {
+                            model: { model: "open/cues", variant: "low" },
+                            fallback_models: ["open/cues-fallback"],
+                        },
+                    },
+                },
+                pi: {
+                    model: "pi/default",
+                    thinking_level: "high",
+                    tasks: { "compress-cues": { model: "pi/cues" } },
+                },
+            },
+        };
+
+        expect(
+            resolveDreamerTaskModel({ config, harness: "opencode", task: "compress-cues" }),
+        ).toMatchObject({
+            primary: { model: "open/cues", qualifier: "low" },
+            fallbacks: [{ model: "open/cues-fallback" }],
+        });
+        // A task override without its own qualifier uses the harness default's qualifier.
+        expect(
+            resolveDreamerTaskModel({ config, harness: "pi", task: "compress-cues" }),
         ).toMatchObject({
-            primary: { model: "mural/model", qualifier: "high" },
+            primary: { model: "pi/cues", qualifier: "high" },
             fallbacks: [],
         });
     });

package/src/shared/model-resolution.ts

@@ -137,14 +137,13 @@ export interface ResolvedDreamerTaskModel {
 
 /**
  * Resolve a dreamer task from one harness subtree. Model selection is task →
- * harness default, except compress-cues inserts its harness-independent mural
- * string between those two rungs. Scheduling remains at dreamer.tasks.<task>.
+ * harness default for every task, compress-cues included. Scheduling remains
+ * at dreamer.tasks.<task>.
  */
 export function resolveDreamerTaskModel(args: {
     config: unknown;
     harness: ModelHarness;
     task: string;
-    muralModel?: unknown;
 }): ResolvedDreamerTaskModel {
     const dreamer = asRecord(asRecord(args.config)?.dreamer);
     const harnessBlock = resolveHarnessBlock(dreamer, args.harness);
@@ -166,19 +165,13 @@ export function resolveDreamerTaskModel(args: {
     }
 
     const taskQualifier = taskBlock?.[args.harness === "opencode" ? "variant" : "thinking_level"];
-    // A mural string borrows the harness default's qualifier whether that
-    // qualifier is written beside `model` or inside the default entry object.
+    // A task override without its own qualifier borrows the harness default's
+    // qualifier, whether written beside `model` or inside the default entry object.
     const harnessQualifier =
         harnessBlock[args.harness === "opencode" ? "variant" : "thinking_level"] ??
         normalizeModelEntry(harnessBlock.model, args.harness)?.qualifier;
     const taskHasModel = taskBlock !== undefined && hasOwn(taskBlock, "model");
-    const usesMuralModel =
-        !taskHasModel && args.task === "compress-cues" && Boolean(readString(args.muralModel));
-    const primarySource = taskHasModel
-        ? taskBlock?.model
-        : usesMuralModel
-          ? args.muralModel
-          : harnessBlock.model;
+    const primarySource = taskHasModel ? taskBlock?.model : harnessBlock.model;
     const fallbackSource =
         taskBlock !== undefined && hasOwn(taskBlock, "fallback_models")
             ? taskBlock.fallback_models
@@ -187,11 +180,7 @@ export function resolveDreamerTaskModel(args: {
     return {
         primary: resolvePrimaryEntry({
             entry: primarySource,
-            // mural.model is a plain string, so its qualifier is always the
-            // executing harness default rather than a task-local default.
-            defaultQualifier: usesMuralModel
-                ? harnessQualifier
-                : (taskQualifier ?? harnessQualifier),
+            defaultQualifier: taskQualifier ?? harnessQualifier,
             harness: args.harness,
         }),
         fallbacks: resolveFallbackEntries(fallbackSource, args.harness),

package/src/shared/models-dev-temperature.ts

@@ -0,0 +1,107 @@
+/**
+ * Temperature capability from the models.dev catalog that OpenCode caches on disk.
+ *
+ * OpenCode 1 copies models.dev's `temperature` flag onto each model, but OpenCode 2's
+ * model rows, Pi's model registry and Oh My Pi's Gemini models carry no equivalent
+ * field. For those hosts the cached catalog is the only positive evidence on the
+ * machine, so a missing file, an unparsable file or a missing entry all mean "unknown"
+ * and the caller omits temperature.
+ *
+ * This module is bundled into the Pi/OMP historian child extension, so it must only
+ * depend on Node built-ins.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface CatalogTemperature {
+    temperature: boolean;
+    /** The catalog entry that decided, as `provider/model`. */
+    entry: string;
+}
+
+/**
+ * Harness provider ids that name the same models.dev provider. Codex (`openai-codex`)
+ * is deliberately absent: the ChatGPT backend is a different transport from the
+ * OpenAI API that models.dev describes, so it gets no catalog answer and no temperature.
+ */
+const CATALOG_PROVIDER_ALIASES: Readonly<Record<string, string>> = {
+    "google-antigravity": "google",
+    "opencode-zen": "opencode",
+};
+
+/** The Antigravity auth plugins register Gemini models as `google/antigravity-<model>`. */
+const ANTIGRAVITY_MODEL_PREFIX = "antigravity-";
+
+type CatalogIndex = Map<string, boolean>;
+
+let cached: { path: string; mtimeMs: number; size: number; index: CatalogIndex } | undefined;
+
+/** OpenCode reads `OPENCODE_MODELS_PATH` instead of its cache when it is set. */
+export function modelsDevCatalogPath(env: NodeJS.ProcessEnv = process.env): string {
+    if (env.OPENCODE_MODELS_PATH) return env.OPENCODE_MODELS_PATH;
+    return join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "opencode", "models.json");
+}
+
+function buildIndex(raw: unknown): CatalogIndex {
+    const index: CatalogIndex = new Map();
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return index;
+    for (const [providerID, provider] of Object.entries(raw as Record<string, unknown>)) {
+        const models = (provider as { models?: unknown } | null)?.models;
+        if (!models || typeof models !== "object") continue;
+        for (const [modelID, model] of Object.entries(models as Record<string, unknown>)) {
+            const temperature = (model as { temperature?: unknown } | null)?.temperature;
+            if (typeof temperature === "boolean")
+                index.set(`${providerID}/${modelID}`, temperature);
+        }
+    }
+    return index;
+}
+
+function loadIndex(): CatalogIndex | undefined {
+    const path = modelsDevCatalogPath();
+    try {
+        const stat = statSync(path);
+        if (cached?.path === path && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size)
+            return cached.index;
+        const index = buildIndex(JSON.parse(readFileSync(path, "utf8")));
+        cached = { path, mtimeMs: stat.mtimeMs, size: stat.size, index };
+        return index;
+    } catch {
+        // Absent or partially written catalog: no evidence either way.
+        return undefined;
+    }
+}
+
+/** Spellings to try for a harness `provider/model` reference, most specific first. */
+export function catalogCandidates(providerID: string, modelID: string): string[] {
+    const provider = Object.hasOwn(CATALOG_PROVIDER_ALIASES, providerID)
+        ? CATALOG_PROVIDER_ALIASES[providerID]
+        : providerID;
+    const candidates = [`${provider}/${modelID}`];
+    if (provider === "google" && modelID.startsWith(ANTIGRAVITY_MODEL_PREFIX))
+        candidates.push(`google/${modelID.slice(ANTIGRAVITY_MODEL_PREFIX.length)}`);
+    return candidates;
+}
+
+/**
+ * Look `provider/model` up in the cached catalogue, trying only the exact spellings from
+ * `catalogCandidates`. A malformed reference, a missing catalogue or no entry returns undefined.
+ */
+export function catalogTemperature(model: string): CatalogTemperature | undefined {
+    const slash = model.indexOf("/");
+    if (slash <= 0 || slash === model.length - 1) return undefined;
+    const index = loadIndex();
+    if (!index) return undefined;
+    for (const entry of catalogCandidates(model.slice(0, slash), model.slice(slash + 1))) {
+        const temperature = index.get(entry);
+        if (temperature !== undefined) return { temperature, entry };
+    }
+    return undefined;
+}
+
+export const __catalogTest = {
+    reset(): void {
+        cached = undefined;
+    },
+};