@cortexkit/opencode-magic-context 0.35.0 → 0.36.0

package/src/agents/permissions.ts

@@ -6,9 +6,10 @@ import { log } from "../shared/logger";
  * # Why this exists
  *
  * Hidden agents (`historian`, `historian-editor`, `dreamer`, `sidekick`) are
- * registered with `mode: "subagent"` and `hidden: true`, but those flags
- * only control visibility in the UI picker — they do NOT restrict which
- * tools the spawned session can call. By default a registered subagent
+ * registered with `mode: "primary"` and `hidden: true`: primary mode keeps
+ * them out of OpenCode's general Task candidate list, while hidden keeps them
+ * out of the UI picker. Those flags do NOT restrict which tools the spawned
+ * session can call. By default a registered agent
  * inherits the FULL primary-agent tool surface: `task`, `bash`, `edit`,
  * `webfetch`, `websearch`, `read`, `grep`, `glob`, every MCP tool, etc.
  *
@@ -108,6 +109,93 @@ export function buildAllowOnlyPermission(
     return permission;
 }
 
+type PermissionAction = "ask" | "allow" | "deny";
+
+function isPermissionAction(value: unknown): value is PermissionAction {
+    return value === "ask" || value === "allow" || value === "deny";
+}
+
+function isPermissionMap(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Add final `permission.task` denies for Magic Context's internal workers.
+ *
+ * OpenCode accepts either a whole-permission action or a pattern map for
+ * `permission.task`; its evaluator uses the last matching rule. Normalize the
+ * whole-permission form, retain every unrelated user rule, then append our
+ * exact agent-id denies after both the user's task patterns and any `*` rule.
+ */
+export function denyTaskRoutingToAgents(
+    permission: unknown,
+    internalAgentIds: readonly string[],
+): Record<string, unknown> {
+    const configured = isPermissionAction(permission)
+        ? { "*": permission }
+        : isPermissionMap(permission)
+          ? permission
+          : {};
+    const { task, ...otherPermissions } = configured;
+    const configuredTask = isPermissionAction(task)
+        ? { "*": task }
+        : isPermissionMap(task)
+          ? task
+          : {};
+    const internalAgentIdSet = new Set(internalAgentIds);
+    const retainedTask = Object.fromEntries(
+        Object.entries(configuredTask).filter(([agentId]) => !internalAgentIdSet.has(agentId)),
+    );
+
+    return {
+        ...otherPermissions,
+        task: {
+            ...retainedTask,
+            ...Object.fromEntries(internalAgentIds.map((agentId) => [agentId, "deny"])),
+        },
+    };
+}
+
+const BUILTIN_TASK_CALLER_IDS = ["build", "plan"] as const;
+
+function isTaskRoutingCaller(agentId: string, config: Record<string, unknown>): boolean {
+    const mode = config.mode;
+    // OpenCode compatibility:
+    // Only strictly-primary callers receive explicit Task routing rules.
+    // Agents that may execute as Task children are intentionally left untouched,
+    // because explicit task permissions can alter OpenCode's default anti-nesting
+    // behavior in the currently supported permission model.
+    if (mode === "primary") return true;
+    if (mode === "subagent" || mode === "all") return false;
+    return agentId === "build" || agentId === "plan";
+}
+
+/**
+ * Apply Task routing denies only to agents that can act as Task callers.
+ *
+ * A top-level permission rule is merged into every OpenCode agent. Adding one
+ * there would suppress the Task tool's default deny for ordinary subagents, so
+ * seed only the built-in interactive callers and configured primary agents.
+ */
+export function denyTaskRoutingToCallerAgents(
+    agentConfigs: Record<string, Record<string, unknown>>,
+    internalAgentIds: readonly string[],
+): Record<string, Record<string, unknown>> {
+    const result = { ...agentConfigs };
+    const candidateIds = new Set([...BUILTIN_TASK_CALLER_IDS, ...Object.keys(agentConfigs)]);
+
+    for (const agentId of candidateIds) {
+        const agentConfig = agentConfigs[agentId] ?? {};
+        if (!isTaskRoutingCaller(agentId, agentConfig)) continue;
+        result[agentId] = {
+            ...agentConfig,
+            permission: denyTaskRoutingToAgents(agentConfig.permission, internalAgentIds),
+        };
+    }
+
+    return result;
+}
+
 /**
  * Tools the historian + historian-editor + compressor agents need.
  *

package/src/config/compaction-accessor-guard.test.ts

@@ -27,6 +27,11 @@ const ALLOWED_READERS = new Set<string>([
     // The strip operates on a raw Record<string, unknown> by key name, not on
     // a parsed MagicContextConfig.
     "packages/plugin/src/config/project-security.ts",
+    // OMP's own setting key appears only as an external CLI string literal;
+    // these files never read Magic Context's parsed compaction config.
+    "packages/cli/src/lib/omp-helpers.ts",
+    "packages/cli/src/commands/setup-omp.ts",
+    "packages/cli/src/commands/doctor-omp.ts",
 ]);
 
 function sourceFiles(directory: string): string[] {
@@ -42,10 +47,10 @@ function sourceFiles(directory: string): string[] {
     return result;
 }
 
-// Matches direct reads of the config path: `compaction.enabled` or
-// `compaction?.enabled` as a property access (not a string literal). This is a
-// structural grep, not a full AST parse — it is deliberately conservative and
-// may surface false positives, which are then allow-listed only after review.
+// Conservatively matches the textual token `compaction.enabled` or
+// `compaction?.enabled`, including string literals. False positives are
+// allow-listed only after confirming they do not read Magic Context's parsed
+// config path.
 // It does NOT match the DB column `compaction_mode_record`, the accessor name
 // `isCompactionEnabled`, or the schema's own `.object({ enabled: ... })`.
 const COMPACTION_ENABLED_READ = /\bcompaction\??\s*\.\s*enabled\b(?!_)/;

package/src/config/schema/magic-context.test.ts

@@ -18,6 +18,7 @@ describe("MagicContextConfigSchema", () => {
                 fail_closed_blocking: true,
                 transform_mode: "ts",
                 storage: { enforce_private_permissions: true },
+                smart_notes: { retina_handoff: false },
                 cache_ttl: "5m",
                 prompt_surface: { default: "full" },
                 execute_threshold_percentage: 65,
@@ -108,6 +109,7 @@ describe("MagicContextConfigSchema", () => {
                     overlay: false,
                 },
                 smart_drops: false,
+                smart_notes: { retina_handoff: false },
                 shadow_embedding: {
                     enabled: false,
                 },

package/src/config/schema/magic-context.ts

@@ -470,6 +470,10 @@ export interface MagicContextConfig {
     language?: string;
     historian?: HistorianConfig;
     dreamer?: DreamerConfig;
+    smart_notes: {
+        /** Flip ownership of authoring-compiled conditions from dreamer to retina. */
+        retina_handoff: boolean;
+    };
     cache_ttl: string | { default: string; [modelKey: string]: string };
     /** Preset routing for guidance and provider-visible prompt surfaces. */
     prompt_surface: PromptSurfaceConfig;
@@ -688,6 +692,17 @@ export const MagicContextConfigSchema = z
         dreamer: DreamerConfigSchema.optional().describe(
             "Dreamer agent + scheduling configuration (model, fallback_models, disable, schedule, tasks, etc.)",
         ),
+        smart_notes: z
+            .object({
+                retina_handoff: z
+                    .boolean()
+                    .default(false)
+                    .describe(
+                        "When true, dreamer skips smart notes whose surface conditions compiled to retina provider configs at authoring time. Default false keeps both paths active until the retina consumer is deployed.",
+                    ),
+            })
+            .default({ retina_handoff: false })
+            .describe("Smart-note ownership transition controls."),
         cache_ttl: z
             .union([z.string(), z.object({ default: z.string() }).catchall(z.string())])
             .default("5m")

package/src/shared/data-path.test.ts

@@ -20,6 +20,8 @@ const savedEnv = {
     XDG_DATA_HOME: process.env.XDG_DATA_HOME,
     LOCALAPPDATA: process.env.LOCALAPPDATA,
     MAGIC_CONTEXT_LOG_PATH: process.env.MAGIC_CONTEXT_LOG_PATH,
+    MAGIC_CONTEXT_TEST_DATA_DIR: process.env.MAGIC_CONTEXT_TEST_DATA_DIR,
+    NODE_ENV: process.env.NODE_ENV,
 };
 
 describe("data-path", () => {
@@ -36,14 +38,14 @@ describe("data-path", () => {
     });
 
     afterEach(() => {
-        if (savedEnv.XDG_CACHE_HOME !== undefined)
-            process.env.XDG_CACHE_HOME = savedEnv.XDG_CACHE_HOME;
-        if (savedEnv.XDG_DATA_HOME !== undefined)
-            process.env.XDG_DATA_HOME = savedEnv.XDG_DATA_HOME;
-        if (savedEnv.LOCALAPPDATA !== undefined) process.env.LOCALAPPDATA = savedEnv.LOCALAPPDATA;
-        if (savedEnv.MAGIC_CONTEXT_LOG_PATH !== undefined)
-            process.env.MAGIC_CONTEXT_LOG_PATH = savedEnv.MAGIC_CONTEXT_LOG_PATH;
-        else delete process.env.MAGIC_CONTEXT_LOG_PATH;
+        // Restore-or-delete every var this suite touches. Several tests lift a
+        // guard (NODE_ENV, MAGIC_CONTEXT_TEST_DATA_DIR) to assert production
+        // shape, so a restore that skips the unset case would leak state into
+        // the next test and make results order-dependent.
+        for (const [key, value] of Object.entries(savedEnv)) {
+            if (value !== undefined) process.env[key] = value;
+            else delete process.env[key];
+        }
     });
 
     test("getCacheDir falls back to <homedir>/.cache when XDG_CACHE_HOME is unset (all platforms)", () => {
@@ -89,8 +91,62 @@ describe("data-path", () => {
         // Cross-harness shared path: both OpenCode and Pi plugins read/write here,
         // unlike the legacy opencode/storage/plugin/magic-context location which
         // was OpenCode-specific. See ARCHITECTURE_DECISIONS memory for rationale.
+        // Production shape, so both test-isolation guards (the preload's data
+        // dir and the NODE_ENV backstop bun sets for every `bun test`) are
+        // lifted for the duration of this assertion.
+        const savedTestDir = process.env.MAGIC_CONTEXT_TEST_DATA_DIR;
+        const savedNodeEnv = process.env.NODE_ENV;
+        delete process.env.MAGIC_CONTEXT_TEST_DATA_DIR;
+        delete process.env.NODE_ENV;
+        try {
+            expect(getMagicContextStorageDir()).toBe(
+                path.join(os.homedir(), ".local", "share", "cortexkit", "magic-context"),
+            );
+        } finally {
+            if (savedTestDir !== undefined) process.env.MAGIC_CONTEXT_TEST_DATA_DIR = savedTestDir;
+            if (savedNodeEnv !== undefined) process.env.NODE_ENV = savedNodeEnv;
+        }
+    });
+
+    test("getMagicContextStorageDir backstops to a temp dir under NODE_ENV=test with no guard set", () => {
+        // CWD-independent backstop: a `bun test` from a dir whose bunfig has no
+        // `[test] preload` runs every suite with neither guard env var set. The
+        // DB resolver used to own this branch, so direct callers of this helper
+        // (the CLI doctors' own PRAGMA integrity_check) still reached the real
+        // shared DB. Memoized, so repeated calls must agree — openDatabase()
+        // caches by path.
+        const savedTestDir = process.env.MAGIC_CONTEXT_TEST_DATA_DIR;
+        delete process.env.MAGIC_CONTEXT_TEST_DATA_DIR;
+        process.env.NODE_ENV = "test";
+        try {
+            const resolved = getMagicContextStorageDir();
+            expect(resolved).not.toContain(path.join(os.homedir(), ".local", "share"));
+            expect(resolved.endsWith(path.join("cortexkit", "magic-context"))).toBe(true);
+            expect(getMagicContextStorageDir()).toBe(resolved);
+        } finally {
+            if (savedTestDir !== undefined) process.env.MAGIC_CONTEXT_TEST_DATA_DIR = savedTestDir;
+        }
+    });
+
+    test("getMagicContextStorageDir honors MAGIC_CONTEXT_TEST_DATA_DIR when XDG_DATA_HOME is unset", () => {
+        // The hole this closes: a test that deletes XDG_DATA_HOME to exercise
+        // path fallbacks used to resolve to the user's REAL shared storage,
+        // because bun caches os.homedir() and a mutated process.env.HOME cannot
+        // move getDataDir(). Callers that build their own context.db path (the
+        // CLI doctors) then ran integrity checks against production data.
+        process.env.MAGIC_CONTEXT_TEST_DATA_DIR = "/tmp/mc-test-isolation";
         expect(getMagicContextStorageDir()).toBe(
-            path.join(os.homedir(), ".local", "share", "cortexkit", "magic-context"),
+            path.join("/tmp/mc-test-isolation", "cortexkit", "magic-context"),
+        );
+    });
+
+    test("getMagicContextStorageDir prefers XDG_DATA_HOME over MAGIC_CONTEXT_TEST_DATA_DIR", () => {
+        // A test managing its own per-test data home is already controlled, and
+        // several suites depend on that dir being honored.
+        process.env.MAGIC_CONTEXT_TEST_DATA_DIR = "/tmp/mc-test-isolation";
+        process.env.XDG_DATA_HOME = "/tmp/custom-data";
+        expect(getMagicContextStorageDir()).toBe(
+            path.join("/tmp/custom-data", "cortexkit", "magic-context"),
         );
     });
 

package/src/shared/data-path.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getHarness, type HarnessId } from "./harness";
@@ -167,11 +167,76 @@ export function getOpenCodeStorageDir(): string {
  *   - Future cross-harness session migration
  *
  * Layout: <XDG_DATA_HOME>/cortexkit/magic-context/
+ *
+ * TEST-ISOLATION GUARD. `openDatabase()` has been guarded in
+ * `resolveDatabasePath()` since the 2026-06-01 (v26) and 2026-06-19 (v41)
+ * incidents, in which unisolated tests migrated the user's REAL shared DB.
+ * Every OTHER caller bypassed that guard — notably the CLI doctors, which
+ * build `join(getMagicContextStorageDir(), "context.db")` themselves and run
+ * `PRAGMA integrity_check` against it. A test that deletes XDG_DATA_HOME to
+ * exercise path fallbacks cannot restore isolation by setting
+ * `process.env.HOME`: bun caches `os.homedir()` at startup, so `getDataDir()`
+ * still resolves to the real home. MAGIC_CONTEXT_TEST_DATA_DIR — set by
+ * `packages/plugin/test-preload.ts`, and restored by any test that touches it
+ * — is honored here, so the preload's "cannot be defeated" guarantee holds for
+ * every caller, not just `openDatabase()`. It is never set in production.
+ *
+ * CWD-INDEPENDENT BACKSTOP. The preload only runs when `bun test`'s CWD has a
+ * bunfig wiring `[test] preload`. A run from a dir WITHOUT that wiring (a
+ * package missing its bunfig, or a brand-new one) executes every *.test.ts with
+ * NO preload, and this resolver would hand back the REAL shared path — which is
+ * how the live DB reached v41. Bun sets NODE_ENV=test for EVERY `bun test`
+ * regardless of CWD, and production never sets it, so that window redirects to
+ * a memoized throwaway dir instead. It lives here rather than in
+ * `resolveDatabasePath()` so direct callers (the CLI doctors' own
+ * `PRAGMA integrity_check`, announcements, the models.dev cache) are covered
+ * too — they never go through the DB resolver.
+ *
+ * XDG_DATA_HOME still wins over both: a test that manages its own data home is
+ * already controlled, and production has no test dir set at all.
  */
 export function getMagicContextStorageDir(): string {
+    if (!process.env.XDG_DATA_HOME) {
+        const testDataDir = process.env.MAGIC_CONTEXT_TEST_DATA_DIR;
+        if (testDataDir) {
+            return path.join(testDataDir, "cortexkit", "magic-context");
+        }
+        if (process.env.NODE_ENV === "test") {
+            return getTestBackstopStorageDir();
+        }
+    }
     return path.join(getDataDir(), "cortexkit", "magic-context");
 }
 
+let testBackstopStorageDir: string | null = null;
+let testBackstopWarned = false;
+
+/**
+ * Memoized per process so repeated calls in the same unisolated test resolve to
+ * the SAME path — `openDatabase()` caches by path, and a fresh temp dir per call
+ * would defeat that cache and hand back different DB handles.
+ */
+function getTestBackstopStorageDir(): string {
+    if (!testBackstopStorageDir) {
+        testBackstopStorageDir = path.join(
+            mkdtempSync(path.join(os.tmpdir(), "mc-test-db-backstop-")),
+            "cortexkit",
+            "magic-context",
+        );
+    }
+    if (!testBackstopWarned) {
+        testBackstopWarned = true;
+        // Deliberately console, not the logger: logger.ts imports this module.
+        console.warn(
+            "[magic-context] TEST BACKSTOP: NODE_ENV=test with no MAGIC_CONTEXT_TEST_DATA_DIR " +
+                `— redirecting storage to a throwaway temp dir (${testBackstopStorageDir}) so no ` +
+                "test can touch the user's real shared database. Wire `[test] preload` in this " +
+                "package's bunfig.toml.",
+        );
+    }
+    return testBackstopStorageDir;
+}
+
 /**
  * Legacy magic-context storage directory used by the OpenCode plugin before the
  * shared cortexkit path. Used only for one-time migration of existing data into

package/src/shared/harness-provider-map.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "bun:test";
-import { piModelRefToCanonical, resolveModelRefForPi } from "./harness-provider-map";
+import {
+    ompModelRefToCanonical,
+    piModelRefToCanonical,
+    resolveModelRefForOmp,
+    resolveModelRefForPi,
+} from "./harness-provider-map";
 
 describe("harness-provider-map", () => {
     describe("resolveModelRefForPi (canonical -> Pi, used when spawning)", () => {
@@ -61,3 +66,39 @@ describe("harness-provider-map", () => {
         });
     });
 });
+
+describe("OMP provider boundary", () => {
+    const representativeRefs = [
+        ["openai/gpt-5.5", "openai-codex/gpt-5.5"],
+        ["google/antigravity/gemini-3.5-flash", "google-antigravity/antigravity/gemini-3.5-flash"],
+        ["anthropic/claude-opus-4-8", "anthropic/claude-opus-4-8"],
+        ["@scope/provider/nested/model", "@scope/provider/nested/model"],
+    ] as const;
+
+    it.each(
+        representativeRefs,
+    )("round-trips canonical %s through OMP selector %s", (canonical, omp) => {
+        expect(resolveModelRefForOmp(canonical)).toBe(omp);
+        expect(ompModelRefToCanonical(omp)).toBe(canonical);
+    });
+
+    it("normalizes an already-native OMP selector idempotently", () => {
+        const selector = "openai-codex/team/nested/gpt-5.5";
+        expect(resolveModelRefForOmp(selector)).toBe(selector);
+        expect(resolveModelRefForOmp(ompModelRefToCanonical(selector))).toBe(selector);
+    });
+
+    it("passes through provider ids that collide with Object.prototype members", () => {
+        for (const ref of [
+            "constructor/model",
+            "toString/model",
+            "__proto__/model",
+            "hasOwnProperty/model",
+        ]) {
+            expect(resolveModelRefForOmp(ref)).toBe(ref);
+            expect(ompModelRefToCanonical(ref)).toBe(ref);
+            expect(resolveModelRefForPi(ref)).toBe(ref);
+            expect(piModelRefToCanonical(ref)).toBe(ref);
+        }
+    });
+});

package/src/shared/harness-provider-map.ts

@@ -2,54 +2,66 @@
  * Provider-id translation between the canonical (OpenCode) form stored in the
  * shared magic-context config and Pi's harness-native provider ids.
  *
- * OpenCode and Pi now share ONE config, but a few auth-plugin providers were
- * named differently on each side. The model id AFTER the slash is identical;
- * only the provider prefix differs:
+ * Provider IDs are a harness boundary, not a database identity. Shared config
+ * always stores the canonical OpenCode form. Each non-OpenCode harness owns an
+ * explicit pair of edge transforms:
  *
- *   canonical (OpenCode)   Pi's preferred auth-plugin form
- *   --------------------   ------------------------------
+ *   canonical (OpenCode)   Pi / OMP selector
+ *   --------------------   -----------------
  *   openai/<model>         openai-codex/<model>
  *   google/<model>         google-antigravity/<model>
  *   anthropic/<model>      anthropic/<model> (same; every other provider too)
  *
- * The mapping is intentionally not a one-to-one provider identity. Pi also
- * exposes plain `openai` and `google` providers for direct API keys, while the
- * canonical prefix does not record whether a subscription or API-key backend
- * should win. Pi therefore starts with the preferred auth-plugin form at the
- * spawn boundary and subagent-runner may retry once with the untranslated
- * canonical form when that form reports missing credentials. The runner caches
- * the winning form per provider prefix in memory only; setup writes still use
- * the reverse mapping below so configs remain canonical.
+ * Pi and OMP currently expose the same two subscription-provider aliases, but
+ * their exported functions remain distinct deliberately. A future OMP catalog
+ * rename must not silently change plain-Pi behavior (or vice versa).
  *
- * Canonical = OpenCode: the config always stores the OpenCode form. Pi
- * translates at its edges:
- *   - read:  canonical -> Pi when spawning a configured model (subagent-runner),
- *            with the runtime credential fallback described above.
- *   - write: Pi -> canonical in the Pi setup wizard, so a config written from
- *            the Pi side stays readable by OpenCode.
+ * The mapping is intentionally not a one-to-one provider identity. Both
+ * harnesses also expose plain `openai` and `google` providers for direct API
+ * keys, while the canonical prefix does not record whether a subscription or
+ * API-key backend should win. The runtime starts with the preferred
+ * subscription form and subagent-runner may retry once with the untranslated
+ * canonical form when that form reports missing credentials.
  *
- * OpenCode needs no translation (canonical IS the OpenCode form).
+ * Only the provider prefix before the first slash is translated. Model IDs,
+ * including nested IDs containing more slashes, are preserved byte-for-byte.
+ * Scoped or otherwise unknown provider prefixes are identities.
+ *
+ * OpenCode needs no translation because canonical is its native form.
  */
 
-const CANONICAL_TO_PI_PROVIDER: Record<string, string> = {
+const CANONICAL_TO_PI_PROVIDER: Readonly<Record<string, string>> = {
     openai: "openai-codex",
     google: "google-antigravity",
 };
 
-const PI_TO_CANONICAL_PROVIDER: Record<string, string> = {
+const PI_TO_CANONICAL_PROVIDER: Readonly<Record<string, string>> = {
+    "openai-codex": "openai",
+    "google-antigravity": "google",
+};
+
+const CANONICAL_TO_OMP_PROVIDER: Readonly<Record<string, string>> = {
+    openai: "openai-codex",
+    google: "google-antigravity",
+};
+
+const OMP_TO_CANONICAL_PROVIDER: Readonly<Record<string, string>> = {
     "openai-codex": "openai",
     "google-antigravity": "google",
 };
 
 /** Remap only the provider prefix (text before the first "/"), preserving the
- *  model id verbatim. No "/", empty provider, or unmapped provider -> unchanged. */
-function remapProviderPrefix(ref: string, map: Record<string, string>): string {
+ *  model id verbatim. No "/", empty provider, or unmapped provider -> unchanged.
+ *  Lookups are own-property only, so provider ids that collide with
+ *  `Object.prototype` members (`constructor/model`, `toString/model`) stay
+ *  identities instead of becoming garbage prefixes. */
+function remapProviderPrefix(ref: string, map: Readonly<Record<string, string>>): string {
     if (typeof ref !== "string") return ref;
     const slash = ref.indexOf("/");
     if (slash <= 0) return ref;
     const provider = ref.slice(0, slash);
-    const mapped = map[provider];
-    return mapped ? `${mapped}${ref.slice(slash)}` : ref;
+    if (!Object.hasOwn(map, provider)) return ref;
+    return `${map[provider]}${ref.slice(slash)}`;
 }
 
 /** Pi-native `provider/model` -> canonical (OpenCode). Identity when unmapped.
@@ -64,3 +76,13 @@ export function piModelRefToCanonical(ref: string): string {
 export function resolveModelRefForPi(ref: string): string {
     return remapProviderPrefix(piModelRefToCanonical(ref), CANONICAL_TO_PI_PROVIDER);
 }
+
+/** OMP-native selector -> canonical shared-config model reference. */
+export function ompModelRefToCanonical(ref: string): string {
+    return remapProviderPrefix(ref, OMP_TO_CANONICAL_PROVIDER);
+}
+
+/** Canonical shared-config model reference -> OMP-native selector. */
+export function resolveModelRefForOmp(ref: string): string {
+    return remapProviderPrefix(ompModelRefToCanonical(ref), CANONICAL_TO_OMP_PROVIDER);
+}

package/src/shared/prompt-surface-a1-golden.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Shared accessors for the A1 prompt-surface golden.
+ *
+ * The golden (`prompt-surface-a1-golden.md`, generated by
+ * `scripts/export-agent-surface.ts`) is read by tests in BOTH packages, and its
+ * section headings are the contract between the generator and those readers.
+ * Keeping the path, the heading strings, and the offset guard here means a
+ * change to the golden's section format is a one-file edit rather than a hunt
+ * across packages.
+ *
+ * This module resolves the golden relative to ITSELF, so consumers never carry
+ * their own `../..` path arithmetic — that arithmetic differs per package and is
+ * exactly the kind of thing that rots silently when files move.
+ */
+
+export const A1_TOOL_SECTION_HEADING = "## 2. Tool surface";
+export const A1_HASH_BASELINE_HEADING = "## 3. System-prompt hash baseline";
+
+export function readA1GoldenDocument(): string {
+    return readFileSync(join(import.meta.dir, "prompt-surface-a1-golden.md"), "utf8");
+}
+
+/**
+ * Locate a golden section heading, refusing to continue when it is absent.
+ *
+ * A bare `indexOf` returns -1 for a missing heading, and `slice(start, -1)`
+ * silently yields an empty (or truncated) section rather than failing: the
+ * golden then parses as ZERO tools and the consuming test passes by comparing
+ * empty to empty. Failing loudly here keeps a malformed golden from reading as a
+ * clean run.
+ */
+export function a1GoldenSectionOffset(document: string, heading: string): number {
+    const offset = document.indexOf(heading);
+    if (offset === -1) {
+        throw new Error(`A1 golden is missing the "${heading}" section heading`);
+    }
+    return offset;
+}

package/src/shared/prompt-surface-runtime.ts

@@ -23,7 +23,12 @@ import {
 const GUIDANCE_MARKER = "## Magic Context";
 const GUIDANCE_MARKER_LINE = /^## Magic Context[\t ]*\r?$/gm;
 
-export const PROMPT_SURFACE_TOOL_IDS = [
+/**
+ * The single source of truth for the ctx_* tools exposed by the prompt surface.
+ * Consumers derive their registries and light-description catalogs from this list
+ * so adding a tool cannot silently skip one prompt-surface integration point.
+ */
+export const ACTIVE_TOOL_IDS = [
     "ctx_reduce",
     "ctx_expand",
     "ctx_note",
@@ -31,15 +36,18 @@ export const PROMPT_SURFACE_TOOL_IDS = [
     "ctx_search",
 ] as const;
 
-export type PromptSurfaceToolId = (typeof PROMPT_SURFACE_TOOL_IDS)[number];
+/** @deprecated Use ACTIVE_TOOL_IDS. Kept as an alias for existing consumers. */
+export const PROMPT_SURFACE_TOOL_IDS = ACTIVE_TOOL_IDS;
+
+export type PromptSurfaceToolId = (typeof ACTIVE_TOOL_IDS)[number];
 
-export const LIGHT_TOOL_DESCRIPTIONS: Readonly<Record<PromptSurfaceToolId, string>> = {
+export const LIGHT_TOOL_DESCRIPTIONS = {
     ctx_reduce: CTX_REDUCE_LIGHT_DESCRIPTION,
     ctx_expand: CTX_EXPAND_LIGHT_DESCRIPTION,
     ctx_note: CTX_NOTE_LIGHT_DESCRIPTION,
     ctx_memory: CTX_MEMORY_LIGHT_DESCRIPTION,
     ctx_search: CTX_SEARCH_LIGHT_DESCRIPTION,
-};
+} as const satisfies Readonly<Record<PromptSurfaceToolId, string>>;
 
 /**
  * Preserve the existing full-preset hash exactly while giving other presets a
@@ -54,7 +62,7 @@ export function promptSurfaceHashMaterial(
         : `${systemContent}\n\0magic-context-prompt-surface:${preset}`;
 }
 
-const PROMPT_SURFACE_TOOL_ID_SET = new Set<string>(PROMPT_SURFACE_TOOL_IDS);
+const PROMPT_SURFACE_TOOL_ID_SET = new Set<string>(ACTIVE_TOOL_IDS);
 
 export interface PromptSurfaceGuidanceSelection {
     /** The configured built-in preset. */

package/src/shared/sqlite.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+import { loadSqliteModule, SqliteRuntimeUnavailableError } from "./sqlite";
+
+describe("SQLite runtime selector", () => {
+    it("wraps a missing node:sqlite module with the detected runtime and cause", async () => {
+        const cause = Object.assign(new Error("No such built-in module: node:sqlite"), {
+            code: "ERR_UNKNOWN_BUILTIN_MODULE",
+            name: "ResolveMessage",
+        });
+        let requestedSpecifier = "";
+        let thrown: unknown;
+
+        try {
+            await loadSqliteModule("Node.js", async (specifier) => {
+                requestedSpecifier = specifier;
+                throw cause;
+            });
+        } catch (error) {
+            thrown = error;
+        }
+
+        expect(requestedSpecifier).toBe("node:sqlite");
+        expect(thrown).toBeInstanceOf(SqliteRuntimeUnavailableError);
+        const compatibilityError = thrown as SqliteRuntimeUnavailableError;
+        expect(compatibilityError.runtime).toBe("Node.js");
+        expect(compatibilityError.specifier).toBe("node:sqlite");
+        expect(compatibilityError.message).toContain("Node.js >= 24");
+        expect(compatibilityError.message).toContain("Bun with bun:sqlite");
+        expect(compatibilityError.message).toContain("node:sqlite");
+        expect(compatibilityError.cause).toBe(cause);
+    });
+});