@cortexkit/opencode-magic-context 0.26.0 → 0.27.0

package/dist/tools/ctx-memory/verification-recording.d.ts

@@ -0,0 +1,8 @@
+import type { Database } from "../../shared/sqlite";
+/**
+ * Run `fn` inside a `BEGIN IMMEDIATE` transaction, committing on success and
+ * rolling back on throw. Used by the in-session ctx_memory mutation actions so
+ * a memory write + its mutation-log row commit atomically.
+ */
+export declare function runImmediateTransaction<T>(db: Database, fn: () => T): T;
+//# sourceMappingURL=verification-recording.d.ts.map

package/dist/tools/ctx-memory/verification-recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-recording.d.ts","sourceRoot":"","sources":["../../../src/tools/ctx-memory/verification-recording.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAUvE"}

package/dist/tools/ctx-search/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/tools/ctx-search/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAQ,MAAM,qBAAqB,CAAC;AAahE,OAAO,KAAK,EAAkC,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAyLjF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAI5F"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/tools/ctx-search/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAQ,MAAM,qBAAqB,CAAC;AAahE,OAAO,KAAK,EAAkC,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAqMjF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAI5F"}

package/dist/tools/ctx-search/types.d.ts

@@ -2,7 +2,7 @@ import type { Database } from "../../shared/sqlite";
 /** Sources the agent can narrow ctx_search to. Facts are intentionally NOT a
  *  source — they're always rendered in <session-history> in message[0], so
  *  searching them returns content already visible in context. */
-export type CtxSearchSource = "memory" | "message" | "git_commit";
+export type CtxSearchSource = "memory" | "message" | "git_commit" | "primer";
 export interface CtxSearchArgs {
     query: string;
     limit?: number;

package/dist/tools/ctx-search/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/ctx-search/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;iEAEiE;AACjE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAElE,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,uBAAuB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,KAAK,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,EAAE,CAAC;KACpB,CAAC,CAAC;CACN"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/ctx-search/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;iEAEiE;AACjE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,uBAAuB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,KAAK,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,EAAE,CAAC;KACpB,CAAC,CAAC;CACN"}

package/dist/tui/data/context-db.d.ts

@@ -22,6 +22,8 @@ export declare function requestUpgrade(sessionId: string): Promise<boolean>;
  *  choice), setting the durable stamp so the FRESH dialog won't re-show. Resume
  *  prompts are staging-driven and unaffected. */
 export declare function dismissUpgradeReminder(sessionId: string): Promise<boolean>;
+/** Resolve global toast duration from server config via RPC. */
+export declare function loadToastDurationMs(): Promise<number>;
 export interface TuiMessage {
     id: number;
     type: string;

package/dist/tui/data/context-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-db.d.ts","sourceRoot":"","sources":["../../../src/tui/data/context-db.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACR,WAAW,EAEX,eAAe,EACf,YAAY,EACf,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAe3D,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAOrD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,IAAI,IAAI,CAO/B;AA4FD,sDAAsD;AACtD,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,wDAAwD;AACxD,wBAAsB,gBAAgB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAyCvB;AAYD,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAchG;AAED,qCAAqC;AACrC,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED,6CAA6C;AAC7C,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAED;mFACmF;AACnF,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxE;AAED;;iDAEiD;AACjD,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhF;AAED,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAkBrE;AAED,wEAAwE;AACxE,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAQtD;AAED,yDAAyD;AACzD,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAyBjF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAWtF"}
+{"version":3,"file":"context-db.d.ts","sourceRoot":"","sources":["../../../src/tui/data/context-db.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACR,WAAW,EAEX,eAAe,EACf,YAAY,EACf,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAe3D,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAOrD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,IAAI,IAAI,CAO/B;AA4FD,sDAAsD;AACtD,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,wDAAwD;AACxD,wBAAsB,gBAAgB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CA0CvB;AAYD,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAchG;AAED,qCAAqC;AACrC,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED,6CAA6C;AAC7C,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAED;mFACmF;AACnF,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxE;AAED;;iDAEiD;AACjD,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhF;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ3D;AAED,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAkBrE;AAED,wEAAwE;AACxE,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAQtD;AAED,yDAAyD;AACzD,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAyBjF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAWtF"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cortexkit/opencode-magic-context",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"type": "module",
 	"description": "OpenCode plugin for Magic Context — cross-session memory and context management",
 	"main": "dist/index.js",
@@ -41,10 +41,12 @@
 	},
 	"dependencies": {
 		"@huggingface/transformers": "^4.1.0",
+		"@jitl/quickjs-singlefile-cjs-release-asyncify": "0.32.0",
 		"@opencode-ai/plugin": "^1.15.13",
 		"@opencode-ai/sdk": "^1.15.13",
 		"ai-tokenizer": "^1.0.6",
 		"comment-json": "^4.2.5",
+		"quickjs-emscripten": "^0.32.0",
 		"zod": "^4.1.8"
 	},
 	"devDependencies": {

package/src/shared/announcement.test.ts

@@ -174,4 +174,24 @@ describe("shouldShowAnnouncement gating", () => {
         markAnnouncementSeen("0.0.0-pre-historic");
         expect(shouldShowAnnouncement()).toBe(true);
     });
+
+    test("does NOT re-announce on a downgrade (stored version is newer)", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-downgrade`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        // Stored version is far newer than the running binary (user downgraded).
+        // A bare string-inequality gate would re-show the OLD announcement; the
+        // semver gate must stay quiet (current is NOT > stored).
+        markAnnouncementSeen("999.0.0");
+        expect(shouldShowAnnouncement()).toBe(false);
+    });
 });

package/src/shared/announcement.ts

@@ -17,24 +17,25 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { compareSemverCore } from "../hooks/auto-update-checker/semver";
 import { getMagicContextStorageDir } from "./data-path";
 
 /**
  * Bump only when there are user-visible changes worth a startup dialog.
  * Does NOT need to match the published package version.
  */
-export const ANNOUNCEMENT_VERSION = "0.26.0";
+export const ANNOUNCEMENT_VERSION = "0.27.0";
 
 /**
  * Short, user-facing bullet strings. Keep each line ~80 chars or shorter so the
  * TUI dialog renders cleanly without horizontal scroll on a typical terminal.
  */
 export const ANNOUNCEMENT_FEATURES: ReadonlyArray<string> = [
-    "Faster on large sessions: per-message transform overhead is at least 2x lower on typical passes and up to ~10x lower when history summarization fires (no more multi-second pause on big sessions).",
-    "No more surprise models: the built-in fallback chain is gone. Hidden agents only use the model (and fallback_models) you configure — no confusing 'model not found' for providers you never set up. `doctor` now records every historian run so real failures are visible.",
-    "Anthropic thinking-block fix: clearing old reasoning no longer risks a stale-signature rejection on Claude / Bedrock / proxied-Claude routes. Plus fewer prompt-cache busts.",
-    "Community fixes: TUI crash on the upgrade progress panel (#168), historian.disallowed_tools for weak models that loop on tool calls (#166), and a Pi-only config key leak (#167).",
-    "New: doctor migrate-session re-homes a session (and optionally its memories) to another project, with a dry-run preview.",
+    "Dreamer V2: each maintenance task now runs on its own schedule (cron), with its own model. Configure them in setup, the dashboard, or magic-context.jsonc.",
+    "New 'classify' task scores each memory's importance so the most relevant stay in context as your work shifts; new 'retrospective' learns from moments you had to correct or re-explain. Both cache-safe, on by default, off anytime.",
+    "New Primers: durable answers to the questions that keep coming up about your project, kept current by the dreamer investigating the actual code.",
+    "Embedding storage no longer wipes your vectors when you change model or endpoint. Different models now coexist, so switching providers keeps your existing vectors.",
+    "Config moved to a shared CortexKit location (~/.config/cortexkit/ and <project>/.cortexkit/). This happens automatically on first run; your old file is preserved.",
 ];
 
 /**
@@ -130,5 +131,16 @@ export function shouldShowAnnouncement(): boolean {
         // Do not advance the version; a later successful boot can still show it.
         return false;
     }
-    return state.version !== ANNOUNCEMENT_VERSION;
+    // Show ONLY on a forward version change (current > stored). A bare string
+    // inequality re-announced on a DOWNGRADE (0.27.0 → 0.26.0) or when stored
+    // state held an unexpected value. compareSemverCore returns null for
+    // non-semver input → treat conservatively (don't announce).
+    const ordering = compareSemverCore(ANNOUNCEMENT_VERSION, state.version);
+    if (ordering === null) {
+        // Stored version isn't parseable as semver but differs from current: only
+        // announce when it's genuinely not the current string (avoids re-showing on
+        // every boot for a corrupt-but-present value).
+        return state.version !== ANNOUNCEMENT_VERSION;
+    }
+    return ordering > 0;
 }

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

@@ -1,7 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
+    ensureCortexKitArtifactGitignore,
     getCacheDir,
     getDataDir,
     getLegacyOpenCodeMagicContextStorageDir,
@@ -121,20 +123,20 @@ describe("data-path", () => {
         expect(shared).toContain("cortexkit");
     });
 
-    test("getProjectMagicContextDir composes <project>/.opencode/magic-context", () => {
+    test("getProjectMagicContextDir composes <project>/.cortexkit/magic-context", () => {
         // Project-local artifacts (historian state file, failure dumps) live
         // inside the project so OpenCode's external_directory permission system
         // treats them as project-internal. Without this, historian's Read tool
         // would trigger a permission prompt on every run when artifacts lived
-        // under os.tmpdir().
+        // under os.tmpdir(). Moved from .opencode/ to the shared .cortexkit/.
         expect(getProjectMagicContextDir("/Users/me/Work/proj")).toBe(
-            path.join("/Users/me/Work/proj", ".opencode", "magic-context"),
+            path.join("/Users/me/Work/proj", ".cortexkit", "magic-context"),
         );
     });
 
     test("getProjectMagicContextHistorianDir appends historian/", () => {
         expect(getProjectMagicContextHistorianDir("/Users/me/Work/proj")).toBe(
-            path.join("/Users/me/Work/proj", ".opencode", "magic-context", "historian"),
+            path.join("/Users/me/Work/proj", ".cortexkit", "magic-context", "historian"),
         );
     });
 
@@ -145,7 +147,7 @@ describe("data-path", () => {
         // project-local historian dir.
         process.env.XDG_DATA_HOME = "/tmp/custom-data";
         expect(getProjectMagicContextDir("/some/project")).toBe(
-            path.join("/some/project", ".opencode", "magic-context"),
+            path.join("/some/project", ".cortexkit", "magic-context"),
         );
     });
 
@@ -153,7 +155,69 @@ describe("data-path", () => {
         // path.join normalizes redundant separators so callers don't need to
         // worry about how the project directory was constructed.
         expect(getProjectMagicContextDir("/some/project/")).toBe(
-            path.join("/some/project/", ".opencode", "magic-context"),
+            path.join("/some/project/", ".cortexkit", "magic-context"),
         );
     });
 });
+
+describe("ensureCortexKitArtifactGitignore", () => {
+    test("creates .cortexkit/.gitignore with a fenced magic-context block", () => {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureCortexKitArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".cortexkit", ".gitignore"), "utf8");
+            expect(gi).toContain("# >>> cortexkit:magic-context");
+            expect(gi).toContain("magic-context/");
+            expect(gi).toContain("# <<< cortexkit:magic-context");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("is idempotent — a second call does not duplicate the block", () => {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureCortexKitArtifactGitignore(dir);
+            ensureCortexKitArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".cortexkit", ".gitignore"), "utf8");
+            const occurrences = gi.split("# >>> cortexkit:magic-context").length - 1;
+            expect(occurrences).toBe(1);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("preserves a sibling module's existing entries (appends, never clobbers)", () => {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            const ckDir = path.join(dir, ".cortexkit");
+            mkdirSync(ckDir, { recursive: true });
+            // Simulate a sibling (e.g. AFT) already owning a fenced block.
+            writeFileSync(
+                path.join(ckDir, ".gitignore"),
+                "# >>> cortexkit:aft\naft/scratch/\n# <<< cortexkit:aft\n",
+            );
+            ensureCortexKitArtifactGitignore(dir);
+            const gi = readFileSync(path.join(ckDir, ".gitignore"), "utf8");
+            expect(gi).toContain("# >>> cortexkit:aft");
+            expect(gi).toContain("aft/scratch/");
+            expect(gi).toContain("# >>> cortexkit:magic-context");
+            expect(gi).toContain("magic-context/");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("does not ignore the project config — only the artifact dir", () => {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureCortexKitArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".cortexkit", ".gitignore"), "utf8");
+            // The config file stays tracked: it must NOT appear as an ignore.
+            expect(gi).not.toContain("magic-context.jsonc");
+            expect(gi).not.toContain("*.jsonc");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/src/shared/data-path.ts

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getHarness, type HarnessId } from "./harness";
@@ -62,28 +63,69 @@ export function getMagicContextHistorianDir(harness: HarnessId = getHarness()):
 /**
  * Project-local magic-context artifact directory.
  *
- * Layout: `<project-directory>/.opencode/magic-context/`
+ * Layout: `<project-directory>/.cortexkit/magic-context/`
  *
  * Used for artifacts that the historian/recomp pipeline writes during a run
  * and that the model is asked to read via its native Read tool. OpenCode's
  * `external_directory` permission system asks the user before reading any
  * file outside the project directory or its worktree, which interrupts every
  * historian run when artifacts live under `os.tmpdir()`. Writing under the
- * project's own `.opencode/` subtree falls inside the project boundary and
+ * project's own `.cortexkit/` subtree falls inside the project boundary and
  * never triggers a permission prompt.
  *
- * The `.opencode/` parent dir is OpenCode's own per-project convention (used
- * for project-local config, plans, dumps, plugin installs). Anchoring
- * magic-context artifacts under `.opencode/magic-context/` keeps them
- * co-located with related OpenCode metadata and makes them easy for users to
- * locate when debugging.
+ * `.cortexkit/` is the shared CortexKit per-project dir (also holds the
+ * project config `magic-context.jsonc`). Because these artifacts are transient
+ * debug dumps that shouldn't dirty the user's repo, the first write also drops
+ * a fenced-block `.gitignore` entry ignoring this subdir (see
+ * ensureCortexKitArtifactGitignore) while leaving `*.jsonc` config tracked.
+ *
+ * Migration note: artifacts used to live under `.opencode/magic-context/`. We
+ * cut the write path forward only — old transient dumps are git-ignored and
+ * regenerated, so they are intentionally NOT migrated (left to be cleaned).
  *
  * Logger does NOT use this — log files stay in the per-harness tmp subtree
  * because they are written by the plugin process itself (no model-side Read
  * tool call, no permission prompt) and span sessions/projects.
  */
 export function getProjectMagicContextDir(directory: string): string {
-    return path.join(directory, ".opencode", "magic-context");
+    return path.join(directory, ".cortexkit", "magic-context");
+}
+
+const GITIGNORE_GUARD_OPEN = "# >>> cortexkit:magic-context";
+const GITIGNORE_GUARD_CLOSE = "# <<< cortexkit:magic-context";
+
+/**
+ * Ensure `<project>/.cortexkit/.gitignore` ignores Magic Context's transient
+ * artifact subdir (`magic-context/`) without touching anything else in the
+ * shared `.cortexkit/` dir — the project config `magic-context.jsonc` stays
+ * tracked, and any sibling module's (e.g. AFT's) entries are preserved.
+ *
+ * Uses the shared CortexKit fenced-block convention: each module owns exactly
+ * its `# >>> cortexkit:<module>` … `# <<< cortexkit:<module>` block and appends
+ * it idempotently (no-op when its own guard line is already present). This lets
+ * multiple cortexkit modules coexist in one `.gitignore` without clobbering.
+ *
+ * Best-effort: a write failure never blocks an artifact write (the caller
+ * already degrades gracefully on its own write failures).
+ */
+export function ensureCortexKitArtifactGitignore(directory: string): void {
+    try {
+        const cortexKitDir = path.join(directory, ".cortexkit");
+        const gitignorePath = path.join(cortexKitDir, ".gitignore");
+        let existing = "";
+        if (existsSync(gitignorePath)) {
+            existing = readFileSync(gitignorePath, "utf8");
+            // Already fenced by us — nothing to do.
+            if (existing.includes(GITIGNORE_GUARD_OPEN)) return;
+        }
+        const block = `${GITIGNORE_GUARD_OPEN}\nmagic-context/\n${GITIGNORE_GUARD_CLOSE}\n`;
+        const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+        const next = existing + (needsLeadingNewline ? "\n" : "") + block;
+        mkdirSync(cortexKitDir, { recursive: true });
+        writeFileSync(gitignorePath, next, "utf8");
+    } catch {
+        // best-effort — never block an artifact write on the gitignore.
+    }
 }
 
 /**

package/src/shared/model-suggestion-retry.test.ts

@@ -1,17 +1,25 @@
 import { describe, expect, mock, test } from "bun:test";
 
-import { promptSyncWithModelSuggestionRetry } from "./model-suggestion-retry";
+import {
+    promptSyncWithModelSuggestionRetry,
+    promptSyncWithValidatedOutputRetry,
+} from "./model-suggestion-retry";
 
 type PromptCall = {
     body: { model?: { providerID: string; modelID: string } };
     signal?: AbortSignal;
 };
 
-function createClient(prompt: ReturnType<typeof mock>, abort?: ReturnType<typeof mock>) {
+function createClient(
+    prompt: ReturnType<typeof mock>,
+    abort?: ReturnType<typeof mock>,
+    messages?: ReturnType<typeof mock>,
+) {
     return {
         session: {
             prompt,
             abort: abort ?? mock(async () => ({})),
+            messages: messages ?? mock(async () => []),
         },
     } as never;
 }
@@ -309,3 +317,72 @@ describe("promptSyncWithModelSuggestionRetry", () => {
         expect(prompt).toHaveBeenCalledTimes(1);
     });
 });
+
+describe("promptSyncWithValidatedOutputRetry", () => {
+    test("valid first model returns without trying fallbacks", async () => {
+        const prompt = mock(async () => ({}));
+        const messages = mock(async () => "primary-output");
+        const client = createClient(prompt, undefined, messages);
+
+        const result = await promptSyncWithValidatedOutputRetry(client, createArgs(), {
+            fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            fetchOutput: async () => messages(),
+            validateOutput: (output: string) => {
+                if (output.trim().length === 0) throw new Error("empty output");
+                return output.trim();
+            },
+        });
+
+        expect(result.validated).toBe("primary-output");
+        expect(prompt).toHaveBeenCalledTimes(1);
+        expect(messages).toHaveBeenCalledTimes(1);
+    });
+
+    test("empty first model tries the next fallback", async () => {
+        const prompt = mock(async () => ({}));
+        const messages = mock(async () =>
+            messages.mock.calls.length === 1 ? "" : "fallback-output",
+        );
+        const client = createClient(prompt, undefined, messages);
+
+        const result = await promptSyncWithValidatedOutputRetry(client, createArgs(), {
+            fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            fetchOutput: async () => messages(),
+            validateOutput: (output: string, attempt) => {
+                if (output.trim().length === 0)
+                    throw new Error(`empty output from ${attempt.label}`);
+                return output.trim();
+            },
+        });
+
+        expect(result.validated).toBe("fallback-output");
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect(messages).toHaveBeenCalledTimes(2);
+        expect((prompt.mock.calls[1]?.[0] as PromptCall).body.model).toEqual({
+            providerID: "anthropic",
+            modelID: "claude-sonnet-4-6",
+        });
+    });
+
+    test("all empty outputs surface the original validation failure", async () => {
+        const prompt = mock(async () => ({}));
+        const messages = mock(async () => "");
+        const client = createClient(prompt, undefined, messages);
+
+        await expect(
+            promptSyncWithValidatedOutputRetry(client, createArgs(), {
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+                fetchOutput: async () => messages(),
+                validateOutput: (output: string, attempt) => {
+                    if (output.trim().length === 0) {
+                        throw new Error(`empty output from ${attempt.label}`);
+                    }
+                    return output.trim();
+                },
+            }),
+        ).rejects.toThrow("empty output from primary");
+
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect(messages).toHaveBeenCalledTimes(2);
+    });
+});