@cortexkit/opencode-magic-context 0.41.4 → 0.42.1

package/src/shared/opencode-db-path.test.ts

@@ -0,0 +1,196 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    formatOpenCodeDbDoctorLine,
+    formatOpenCodeDbMissingBanner,
+    formatOpenCodeDbMissingStatusLine,
+    openCodeDbPathExists,
+    resetOpenCodeDbPathStateForTesting,
+    resolveOpenCodeDbPath,
+} from "./opencode-db-path";
+
+const ORIGINAL_ENV = {
+    XDG_DATA_HOME: process.env.XDG_DATA_HOME,
+    OPENCODE_DB: process.env.OPENCODE_DB,
+    OPENCODE_DISABLE_CHANNEL_DB: process.env.OPENCODE_DISABLE_CHANNEL_DB,
+    OPENCODE_CHANNEL: process.env.OPENCODE_CHANNEL,
+};
+const tempDirs: string[] = [];
+
+function restore(name: keyof typeof ORIGINAL_ENV): void {
+    const value = ORIGINAL_ENV[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+}
+
+afterEach(() => {
+    restore("XDG_DATA_HOME");
+    restore("OPENCODE_DB");
+    restore("OPENCODE_DISABLE_CHANNEL_DB");
+    restore("OPENCODE_CHANNEL");
+    resetOpenCodeDbPathStateForTesting();
+    for (const directory of tempDirs.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+function useDataHome(): { dataHome: string; openCodeDir: string } {
+    const dataHome = mkdtempSync(join(tmpdir(), "opencode-db-path-"));
+    const openCodeDir = join(dataHome, "opencode");
+    mkdirSync(openCodeDir, { recursive: true });
+    tempDirs.push(dataHome);
+    process.env.XDG_DATA_HOME = dataHome;
+    delete process.env.OPENCODE_DB;
+    delete process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    delete process.env.OPENCODE_CHANNEL;
+    resetOpenCodeDbPathStateForTesting();
+    return { dataHome, openCodeDir };
+}
+
+function createCandidate(openCodeDir: string, name: string, mtimeMs: number): string {
+    const path = join(openCodeDir, name);
+    writeFileSync(path, "sqlite fixture");
+    const time = new Date(mtimeMs);
+    utimesSync(path, time, time);
+    return path;
+}
+
+describe("resolveOpenCodeDbPath", () => {
+    it("honors absolute and relative OPENCODE_DB overrides before every other source", () => {
+        const { openCodeDir } = useDataHome();
+        const absolute = join(openCodeDir, "elsewhere.db");
+        process.env.OPENCODE_DB = absolute;
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "true";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: absolute,
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+
+        process.env.OPENCODE_DB = "relative.db";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "relative.db"),
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+    });
+
+    it("treats OPENCODE_DB=:memory: as an explicit but absent store", () => {
+        useDataHome();
+        process.env.OPENCODE_DB = ":memory:";
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({ path: ":memory:", source: "OPENCODE_DB", channel: null });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("uses the default DB when channel databases are disabled", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "1";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+    });
+
+    it("honors an OPENCODE_CHANNEL visible to the plugin", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode-dev.db"),
+            source: "channel",
+            channel: "dev",
+        });
+    });
+
+    for (const selectedName of [
+        "opencode.db",
+        "opencode-local.db",
+        "opencode-dev.db",
+        "opencode-nightly.db",
+    ]) {
+        it(`discovers ${selectedName} when it is the newest existing candidate`, () => {
+            const { openCodeDir } = useDataHome();
+            const names = [
+                "opencode.db",
+                "opencode-local.db",
+                "opencode-dev.db",
+                "opencode-nightly.db",
+            ];
+            for (const [index, name] of names.entries()) {
+                createCandidate(openCodeDir, name, name === selectedName ? 10_000 : 1_000 + index);
+            }
+
+            expect(resolveOpenCodeDbPath()).toEqual({
+                path: join(openCodeDir, selectedName),
+                source: "discovered",
+                channel:
+                    selectedName === "opencode.db"
+                        ? null
+                        : selectedName.slice("opencode-".length, -".db".length),
+            });
+        });
+    }
+
+    it("uses candidate order as the deterministic tie-breaker for equal mtimes", () => {
+        const { openCodeDir } = useDataHome();
+        for (const name of ["opencode-local.db", "opencode-dev.db", "opencode.db"]) {
+            createCandidate(openCodeDir, name, 5_000);
+        }
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("returns the default path by value when no candidate exists", () => {
+        const { openCodeDir } = useDataHome();
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("re-probes discovery when the memoized chosen file disappears", () => {
+        const { openCodeDir } = useDataHome();
+        const primary = createCandidate(openCodeDir, "opencode-local.db", 2_000);
+        const fallback = createCandidate(openCodeDir, "opencode.db", 1_000);
+        expect(resolveOpenCodeDbPath().path).toBe(primary);
+
+        unlinkSync(primary);
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: fallback,
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("formats the missing banner, status, and doctor lines by value", () => {
+        const { openCodeDir } = useDataHome();
+        const lookedFor = [
+            join(openCodeDir, "opencode.db"),
+            join(openCodeDir, "opencode-local.db"),
+            join(openCodeDir, "opencode-dev.db"),
+            join(openCodeDir, "opencode-<channel>.db"),
+        ].join(", ");
+        const resolution = resolveOpenCodeDbPath();
+
+        expect(formatOpenCodeDbMissingBanner(resolution)).toBe(
+            `Magic Context cannot find OpenCode's session database (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled until it is found; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbMissingStatusLine(resolution)).toBe(
+            `OpenCode DB: MISSING (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbDoctorLine(resolution)).toBe(
+            `FAIL OpenCode session database: not found (looked for ${lookedFor}); set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+    });
+});

package/src/shared/opencode-db-path.ts

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+export type OpenCodeDbPathSource = "OPENCODE_DB" | "channel" | "default" | "discovered";
+
+export interface OpenCodeDbPathResolution {
+    path: string;
+    source: OpenCodeDbPathSource;
+    channel: string | null;
+}
+
+export interface OpenCodeDbReadFailure extends OpenCodeDbPathResolution {
+    message: string;
+}
+
+interface CachedResolution {
+    key: string;
+    resolution: OpenCodeDbPathResolution;
+    existed: boolean;
+}
+
+let cachedResolution: CachedResolution | null = null;
+let lastReadFailure: OpenCodeDbReadFailure | null = null;
+const claimedDiagnostics = new Set<string>();
+
+function openCodeDataDir(): string {
+    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode");
+}
+
+function environmentKey(dataDir: string): string {
+    return [
+        dataDir,
+        process.env.OPENCODE_DB ?? "",
+        process.env.OPENCODE_DISABLE_CHANNEL_DB ?? "",
+        process.env.OPENCODE_CHANNEL ?? "",
+    ].join("\0");
+}
+
+function channelPath(dataDir: string, channel: string): string {
+    return ["latest", "beta", "prod"].includes(channel)
+        ? join(dataDir, "opencode.db")
+        : join(dataDir, `opencode-${channel}.db`);
+}
+
+function discoveredCandidateNames(dataDir: string): string[] {
+    const names = ["opencode.db", "opencode-local.db", "opencode-dev.db"];
+    try {
+        const discovered = readdirSync(dataDir, { withFileTypes: true })
+            .filter((entry) => /^opencode-.+\.db$/.test(entry.name) && !names.includes(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+        names.push(...discovered);
+    } catch {
+        // A missing or unreadable data directory has no discovered candidates.
+    }
+    return names;
+}
+
+function discoverOpenCodeDb(dataDir: string): OpenCodeDbPathResolution {
+    const candidates = discoveredCandidateNames(dataDir).map((name, order) => {
+        const path = join(dataDir, name);
+        try {
+            const metadata = statSync(path);
+            return metadata.isFile() ? { path, order, mtimeMs: metadata.mtimeMs } : null;
+        } catch {
+            return null;
+        }
+    });
+    const existing = candidates
+        .filter((candidate): candidate is NonNullable<typeof candidate> => candidate !== null)
+        .sort((left, right) => right.mtimeMs - left.mtimeMs || left.order - right.order)[0];
+
+    if (!existing) {
+        return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
+    }
+
+    const name = existing.path.slice(dataDir.length + 1);
+    const channel =
+        name === "opencode.db" ? null : name.slice("opencode-".length, -".db".length) || null;
+    return { path: existing.path, source: "discovered", channel };
+}
+
+function resolveFresh(dataDir: string): OpenCodeDbPathResolution {
+    const explicit = process.env.OPENCODE_DB;
+    if (explicit !== undefined && explicit.length > 0) {
+        if (explicit === ":memory:") {
+            return { path: explicit, source: "OPENCODE_DB", channel: null };
+        }
+        return {
+            path: isAbsolute(explicit) ? explicit : join(dataDir, explicit),
+            source: "OPENCODE_DB",
+            channel: null,
+        };
+    }
+
+    const disableChannelDb = process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    if (disableChannelDb === "1" || disableChannelDb === "true") {
+        return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
+    }
+
+    const channel = process.env.OPENCODE_CHANNEL;
+    if (channel !== undefined && channel.length > 0) {
+        return { path: channelPath(dataDir, channel), source: "channel", channel };
+    }
+
+    return discoverOpenCodeDb(dataDir);
+}
+
+/** Resolve an explicit DB override first, then channel paths; discover candidates when the compiled channel is unknown. */
+export function resolveOpenCodeDbPath(): OpenCodeDbPathResolution {
+    const dataDir = openCodeDataDir();
+    const key = environmentKey(dataDir);
+    if (
+        cachedResolution?.key === key &&
+        (!cachedResolution.existed || existsSync(cachedResolution.resolution.path))
+    ) {
+        if (cachedResolution.existed) return cachedResolution.resolution;
+        // An absent result is re-probed so a DB created after plugin boot is detected.
+    }
+
+    const resolution = resolveFresh(dataDir);
+    cachedResolution = {
+        key,
+        resolution,
+        existed: resolution.path !== ":memory:" && existsSync(resolution.path),
+    };
+    return resolution;
+}
+
+export function openCodeDbPathExists(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): boolean {
+    return resolution.path !== ":memory:" && existsSync(resolution.path);
+}
+
+export function getOpenCodeDbProbeDescriptions(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string[] {
+    if (resolution.source === "OPENCODE_DB") return [resolution.path];
+    if (
+        resolution.source === "channel" ||
+        process.env.OPENCODE_DISABLE_CHANNEL_DB === "1" ||
+        process.env.OPENCODE_DISABLE_CHANNEL_DB === "true"
+    ) {
+        return [resolution.path];
+    }
+    const dataDir = openCodeDataDir();
+    return [
+        join(dataDir, "opencode.db"),
+        join(dataDir, "opencode-local.db"),
+        join(dataDir, "opencode-dev.db"),
+        join(dataDir, "opencode-<channel>.db"),
+    ];
+}
+
+function lookedForText(resolution: OpenCodeDbPathResolution): string {
+    return getOpenCodeDbProbeDescriptions(resolution).join(", ");
+}
+
+export function formatOpenCodeDbMissingBanner(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `Magic Context cannot find OpenCode's session database (looked for ${lookedForText(resolution)}). History compaction (historian) and the mid-turn valve are disabled until it is found; set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbMissingStatusLine(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `OpenCode DB: MISSING (looked for ${lookedForText(resolution)}). History compaction (historian) and the mid-turn valve are disabled; set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbDoctorLine(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `FAIL OpenCode session database: not found (looked for ${lookedForText(resolution)}); set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbReadFailureStatusLine(failure: OpenCodeDbReadFailure): string {
+    return `OpenCode DB: READ FAILED (path=${failure.path}, source=${failure.source}) — ${failure.message}`;
+}
+
+export function recordOpenCodeDbReadFailure(
+    resolution: OpenCodeDbPathResolution,
+    error: unknown,
+): OpenCodeDbReadFailure {
+    const message = error instanceof Error ? error.message : String(error);
+    lastReadFailure = { ...resolution, message };
+    return lastReadFailure;
+}
+
+export function clearOpenCodeDbReadFailure(path?: string): void {
+    if (path === undefined || lastReadFailure?.path === path) lastReadFailure = null;
+}
+
+export function getOpenCodeDbReadFailure(): OpenCodeDbReadFailure | null {
+    return lastReadFailure;
+}
+
+export function claimOpenCodeDbDiagnosticOnce(
+    surface: string,
+    resolution: OpenCodeDbPathResolution,
+): boolean {
+    const key = `${surface}\0${resolution.path}\0${resolution.source}`;
+    if (claimedDiagnostics.has(key)) return false;
+    claimedDiagnostics.add(key);
+    return true;
+}
+
+/** Test-only reset for process memoization and once-only diagnostics. */
+export function resetOpenCodeDbPathStateForTesting(): void {
+    cachedResolution = null;
+    lastReadFailure = null;
+    claimedDiagnostics.clear();
+}

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

@@ -1,11 +1,11 @@
 # Magic Context agent-facing surface (exported from source)
 
-Generated by `packages/plugin/scripts/export-agent-surface.ts` at 2026-08-08.
+Generated by `packages/plugin/scripts/export-agent-surface.ts` at 2026-09-11.
 Token counts are Claude BPE estimates on the raw text.
 
 ## 1. System-prompt guidance section
 
-### PRIMARY full (reduce=on, memory=on, dreamer=on, temporal=on) — 8714 chars, ~2003 tokens
+### PRIMARY full (reduce=on, memory=on, dreamer=on, temporal=on) — 8752 chars, ~2008 tokens
 
 ```markdown
 ## Magic Context
@@ -23,7 +23,7 @@ Because of this:
 Reduction prompts are routine housekeeping to keep the session fast and cheap — act on them as light maintenance, never as scarcity warnings. Keep individual operations efficient, but never let context size change *what* work you take on or *how thoroughly* you do it.
 
 Messages and tool outputs are tagged with §N§ identifiers (e.g., §1§, §42§).
-Use `ctx_reduce` to mark spent tagged content as discardable and reclaim space. Marking is NOT an immediate delete — it queues the content, which stays fully visible until space is actually needed (as soon as the next turn if you're already under pressure, much later if not), so mark a tool output as soon as you're done with it rather than hoarding the call for the end of the turn. The last 20 tags are protected (marking one just queues it until it ages out). Syntax: "3-5", "1,2,9", or "1-5,8,12-15".
+Use `ctx_reduce` to mark spent tagged content as discardable and reclaim space. Marking is NOT an immediate delete — it queues the content, which stays fully visible until space is actually needed (as soon as the next turn if you're already under pressure, much later if not), so mark a tool output as soon as you're done with it rather than hoarding the call for the end of the turn. The newest token-mass window stays protected until displaced. Syntax: "3-5", "1,2,9", or "1-5,8,12-15".
 Do not announce or narrate `ctx_reduce` drops — just call the tool silently. Saying "I'll drop these outputs" wastes tokens the user does not care about.
 Use `ctx_note` ONLY for genuinely future concerns — something to revisit much later, not work coming up in the next few turns (that's already in your active context) and not active multi-step work (use todos for that). Magic Context preserves your full context across both compaction and restarts, so an upcoming restart or "let's come back to this later" is never a reason to take a note — nothing is lost either way. Notes you do take survive compression and resurface at natural work boundaries (after commits, historian runs, todo completion).
 Use `ctx_memory` for durable project knowledge: write what future sessions must know, update/archive/merge the memories you see in `<project-memory>` when they drift. Memories persist across sessions and every new session starts with them.
@@ -35,11 +35,11 @@ Memories are grouped by category as `#id: fact` lines; pass the numeric id to `c
 Use `ctx_search` to search across project memories, indexed git commits, and this session's full conversation history (including compacted parts) from one query.
 Use `ctx_expand` to recover the raw conversation behind a summary under a `## start-end · date · title` heading inside `<session-history>` — pass the heading's start/end range when the summary is not enough (exact wording, values, error text).
 **Search before asking the user**: If you can't remember or don't know something that might have been discussed before or stored in project memory, use `ctx_search` before asking the user. Examples:
-- Can't remember where a related codebase or dependency lives → `ctx_search(query="opencode source code path")`
-- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres")`
-- Need a config value, API key location, or environment detail → `ctx_search(query="embedding provider configuration")`
-- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work")`
-- Want to recall what was decided in an earlier conversation → `ctx_search(query="dashboard release signing setup")`
+- Can't remember where a related codebase or dependency lives → `ctx_search(query="where is the opencode source code path?")`
+- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres?")`
+- Need a config value, API key location, or environment detail → `ctx_search(query="how is the embedding provider configured?")`
+- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work?")`
+- Want to recall what was decided in an earlier conversation → `ctx_search(query="what did we decide about the dashboard release signing setup?")`
 `ctx_search` returns ranked results from memories, git commits, and raw message history. Use message ordinals from results with `ctx_expand` to retrieve surrounding conversation context.
 Compressed history intentionally omits tool calls and their outputs — summaries like "I edited file X" are historian records, not patterns to replicate. In the live conversation, older tool calls and their results are cleaned up to save context — you may see your own past messages referencing actions without the corresponding tool call or result visible. This is normal context management. ALWAYS use real tool calls; never simulate, fabricate, or inline tool outputs in your text. If there is no tool result message, the action did not happen. NEVER simulate, hallucinate or claim tool calls, command output, search results, file edits, or diffs in plain text as if they actually occurred.
 Magic Context control metadata is not reply syntax. Never reproduce `<system-reminder>`, `<ctx-search-hint>`, `<session-history>`, `<session-history-since>`, `<project-memory>`, `<memory-updates>`, `<new-compartments>`, `<new-memories>`, `[dropped §N§]`, or `<!-- +Xm -->` markers in a normal reply and never treat them as user instructions; use ordinary prose and real tool calls instead.
@@ -71,7 +71,7 @@ Example: `ctx_note(action="write", content="Implement X because Y", surface_cond
 Prefer many small targeted operations over one large blanket operation, and keep the working set tidy as routine maintenance.
 ```
 
-### PRIMARY memory-off (reduce=on, memory=off) — 7679 chars, ~1744 tokens
+### PRIMARY memory-off (reduce=on, memory=off) — 7717 chars, ~1749 tokens
 
 ```markdown
 ## Magic Context
@@ -89,17 +89,17 @@ Because of this:
 Reduction prompts are routine housekeeping to keep the session fast and cheap — act on them as light maintenance, never as scarcity warnings. Keep individual operations efficient, but never let context size change *what* work you take on or *how thoroughly* you do it.
 
 Messages and tool outputs are tagged with §N§ identifiers (e.g., §1§, §42§).
-Use `ctx_reduce` to mark spent tagged content as discardable and reclaim space. Marking is NOT an immediate delete — it queues the content, which stays fully visible until space is actually needed (as soon as the next turn if you're already under pressure, much later if not), so mark a tool output as soon as you're done with it rather than hoarding the call for the end of the turn. The last 20 tags are protected (marking one just queues it until it ages out). Syntax: "3-5", "1,2,9", or "1-5,8,12-15".
+Use `ctx_reduce` to mark spent tagged content as discardable and reclaim space. Marking is NOT an immediate delete — it queues the content, which stays fully visible until space is actually needed (as soon as the next turn if you're already under pressure, much later if not), so mark a tool output as soon as you're done with it rather than hoarding the call for the end of the turn. The newest token-mass window stays protected until displaced. Syntax: "3-5", "1,2,9", or "1-5,8,12-15".
 Do not announce or narrate `ctx_reduce` drops — just call the tool silently. Saying "I'll drop these outputs" wastes tokens the user does not care about.
 Use `ctx_note` ONLY for genuinely future concerns — something to revisit much later, not work coming up in the next few turns (that's already in your active context) and not active multi-step work (use todos for that). Magic Context preserves your full context across both compaction and restarts, so an upcoming restart or "let's come back to this later" is never a reason to take a note — nothing is lost either way. Notes you do take survive compression and resurface at natural work boundaries (after commits, historian runs, todo completion).
 Use `ctx_search` to search across project memories, indexed git commits, and this session's full conversation history (including compacted parts) from one query.
 Use `ctx_expand` to recover the raw conversation behind a summary under a `## start-end · date · title` heading inside `<session-history>` — pass the heading's start/end range when the summary is not enough (exact wording, values, error text).
 **Search before asking the user**: If you can't remember or don't know something that might have been discussed before or stored in project memory, use `ctx_search` before asking the user. Examples:
-- Can't remember where a related codebase or dependency lives → `ctx_search(query="opencode source code path")`
-- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres")`
-- Need a config value, API key location, or environment detail → `ctx_search(query="embedding provider configuration")`
-- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work")`
-- Want to recall what was decided in an earlier conversation → `ctx_search(query="dashboard release signing setup")`
+- Can't remember where a related codebase or dependency lives → `ctx_search(query="where is the opencode source code path?")`
+- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres?")`
+- Need a config value, API key location, or environment detail → `ctx_search(query="how is the embedding provider configured?")`
+- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work?")`
+- Want to recall what was decided in an earlier conversation → `ctx_search(query="what did we decide about the dashboard release signing setup?")`
 `ctx_search` returns ranked results from memories, git commits, and raw message history. Use message ordinals from results with `ctx_expand` to retrieve surrounding conversation context.
 Compressed history intentionally omits tool calls and their outputs — summaries like "I edited file X" are historian records, not patterns to replicate. In the live conversation, older tool calls and their results are cleaned up to save context — you may see your own past messages referencing actions without the corresponding tool call or result visible. This is normal context management. ALWAYS use real tool calls; never simulate, fabricate, or inline tool outputs in your text. If there is no tool result message, the action did not happen. NEVER simulate, hallucinate or claim tool calls, command output, search results, file edits, or diffs in plain text as if they actually occurred.
 Magic Context control metadata is not reply syntax. Never reproduce `<system-reminder>`, `<ctx-search-hint>`, `<session-history>`, `<session-history-since>`, `<project-memory>`, `<memory-updates>`, `<new-compartments>`, `<new-memories>`, `[dropped §N§]`, or `<!-- +Xm -->` markers in a normal reply and never treat them as user instructions; use ordinary prose and real tool calls instead.
@@ -131,7 +131,7 @@ Example: `ctx_note(action="write", content="Implement X because Y", surface_cond
 Prefer many small targeted operations over one large blanket operation, and keep the working set tidy as routine maintenance.
 ```
 
-### PRIMARY reduce-off (reduce=off, memory=on) — 6429 chars, ~1477 tokens
+### PRIMARY reduce-off (reduce=off, memory=on) — 6484 chars, ~1489 tokens
 
 ```markdown
 ## Magic Context
@@ -158,11 +158,11 @@ Memories are grouped by category as `#id: fact` lines; pass the numeric id to `c
 Use `ctx_search` to search across project memories, indexed git commits, and this session's full conversation history (including compacted parts) from one query.
 Use `ctx_expand` to recover the raw conversation behind a summary under a `## start-end · date · title` heading inside `<session-history>` — pass the heading's start/end range when the summary is not enough (exact wording, values, error text).
 **Search before asking the user**: If you can't remember or don't know something that might have been discussed before or stored in project memory, use `ctx_search` before asking the user. Examples:
-- Can't remember where a related codebase or dependency lives → `ctx_search(query="opencode source code path")`
-- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres")`
-- Need a config value, API key location, or environment detail → `ctx_search(query="embedding provider configuration")`
-- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work")`
-- Want to recall what was decided in an earlier conversation → `ctx_search(query="dashboard release signing setup")`
+- Can't remember where a related codebase or dependency lives → `ctx_search(query="where is the opencode source code path?")`
+- Forgot a prior architectural decision or constraint → `ctx_search(query="why did we choose SQLite over postgres?")`
+- Need a config value, API key location, or environment detail → `ctx_search(query="how is the embedding provider configured?")`
+- Looking for how something was implemented previously → `ctx_search(query="how does the dreamer lease work?")`
+- Want to recall what was decided in an earlier conversation → `ctx_search(query="what did we decide about the dashboard release signing setup?")`
 `ctx_search` returns ranked results from memories, git commits, and raw message history. Use message ordinals from results with `ctx_expand` to retrieve surrounding conversation context.
 Compressed history intentionally omits tool calls and their outputs — summaries like "I edited file X" are historian records, not patterns to replicate. In the live conversation, older tool calls and their results are cleaned up to save context — you may see your own past messages referencing actions without the corresponding tool call or result visible. This is normal context management. ALWAYS use real tool calls; never simulate, fabricate, or inline tool outputs in your text. If there is no tool result message, the action did not happen. NEVER simulate, hallucinate or claim tool calls, command output, search results, file edits, or diffs in plain text as if they actually occurred.
 Magic Context control metadata is not reply syntax. Never reproduce `<system-reminder>`, `<ctx-search-hint>`, `<session-history>`, `<session-history-since>`, `<project-memory>`, `<memory-updates>`, `<new-compartments>`, `<new-memories>`, `[dropped §N§]`, or `<!-- +Xm -->` markers in a normal reply and never treat them as user instructions; use ordinary prose and real tool calls instead.
@@ -172,13 +172,13 @@ Example: `ctx_note(action="write", content="Implement X because Y", surface_cond
 **Temporal awareness**: User messages may be preceded by HTML comments like `<!-- +12m -->`, `<!-- +2h 15m -->`, or `<!-- +3d 4h -->` indicating time elapsed since the previous message's completion. Compartments in `<session-history>` carry `start-date` and `end-date` attributes (YYYY-MM-DD) showing real-time boundaries. Use these when reasoning about workflow pacing, log durations, build times, or how long ago something happened.
 ```
 
-### SUBAGENT minimal — 679 chars, ~185 tokens
+### SUBAGENT minimal — 693 chars, ~187 tokens
 
 ```markdown
 ## Magic Context
 
 Messages and tool outputs are tagged with §N§ identifiers (e.g., §1§, §42§).
-Use `ctx_reduce` to drop tool outputs you have already finished with, keeping your working context lean. Syntax: "3-5", "1,2,9", or "1-5,8,12-15". The last 20 tags are protected.
+Use `ctx_reduce` to drop tool outputs you have already finished with, keeping your working context lean. Syntax: "3-5", "1,2,9", or "1-5,8,12-15". The newest token-mass window stays protected.
 Drop silently — do not narrate it. NEVER drop large ranges blindly (e.g., "1-50"); review each tag first. Do not drop user or assistant text messages — only large tool outputs are worth dropping.
 Older tool calls may show `[dropped §N§]` sentinels; that is normal context management, not a pattern to copy. ALWAYS make fresh real tool calls when you need data again; never fabricate or inline tool output.
 ```
@@ -254,19 +254,19 @@ Two recovery modes for finer detail:
 }
 ```
 
-### ctx_note — description ~391 tokens, params ~317 tokens (total ~708)
+### ctx_note — description ~392 tokens, params ~378 tokens (total ~770)
 
 **Description:**
 
 ```
-Working notes for this session's future — reminders, follow-ups, and things to revisit later.
+Working notes for this session — reminders, follow-ups, and things to revisit later.
 
-Use a note when something matters LATER but not in the next few steps: "revisit the retry logic after the release", "user wants the dashboard polish batched", "flaky test to investigate when touching CI". Don't use notes for active multi-step work (use todos) or for durable project knowledge that should outlive this session (use ctx_memory). Notes resurface automatically at natural work boundaries and whenever you read them.
+Use a note when something matters LATER but not in the next few steps: "revisit the retry logic after the release", "user wants the dashboard polish batched", "flaky test to investigate when touching CI". Don't use notes for active work (use todos) or durable project knowledge (use ctx_memory). Notes resurface at work boundaries and when read.
 
 Actions:
 - write: save a note (content). Add surface_condition to make it a smart note (below).
 - read: list notes, newest first. Default: latest active session notes + ready smart notes; page older ones with limit/offset, or inspect other states with filter.
-- update / dismiss: change or retire a note by note_id.
+- update: change a note by note_id. dismiss: retire one by note_id or 1–50 by note_ids; provide exactly one.
 
 Smart notes: pass surface_condition and the note stays hidden until a background checker confirms the condition — using ONLY externally verifiable signals (GitHub state via gh, files on disk, git history, web pages). It cannot see this conversation, so the condition must be checkable from outside:
 ✓ "When PR #42 in cortexkit/magic-context is merged"
@@ -321,11 +321,22 @@ Example: ctx_note(action="write", content="Re-run the perf benchmark once the bo
   "note_id": {
     "description": "Note ID (required for 'dismiss' and 'update' actions).",
     "type": "number"
+  },
+  "note_ids": {
+    "description": "One to fifty note ids for 'dismiss' only; do not combine with note_id.",
+    "minItems": 1,
+    "maxItems": 50,
+    "type": "array",
+    "items": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    }
   }
 }
 ```
 
-### ctx_memory — description ~234 tokens, params ~201 tokens (total ~435)
+### ctx_memory — description ~234 tokens, params ~216 tokens (total ~450)
 
 **Description:**
 
@@ -365,7 +376,7 @@ Example: ctx_memory(action="write", category="CONSTRAINTS", content="Pi stores s
     "type": "string"
   },
   "category": {
-    "description": "What kind of fact this is (required for write; optional merge override)",
+    "description": "What kind of fact this is (required for write; optional on update to recategorize, omitted keeps the current category; optional merge override)",
     "type": "string",
     "enum": [
       "PROJECT_RULES",
@@ -393,20 +404,24 @@ Example: ctx_memory(action="write", category="CONSTRAINTS", content="Pi stores s
 }
 ```
 
-### ctx_search — description ~309 tokens, params ~184 tokens (total ~493)
+### ctx_search — description ~402 tokens, params ~184 tokens (total ~586)
 
 **Description:**
 
 ```
 Your long-term recall for this project — search everything that ever happened here, not just what's currently visible.
 
+Retrieval matches meaning as well as exact words and fuses them, so phrasing matters: phrase `query` as a natural-language question that still contains the exact terms you expect in the answer (paths, symbols, config keys, error strings); a bare keyword stack finds less than a question carrying the same words.
+- Good: "where is the retry backoff for the upload client configured?"
+- Bad: "upload client retry backoff config"
+
 Reach for it when something feels familiar but isn't in view: "did we solve this before?", "what did we decide about X?", "when did this break?", "where does Y live?". Results only contain things you CANNOT currently see — memories already shown in <project-memory> and the live conversation tail are filtered out. A query that is just one or more memory ids (e.g. `#7234` or `12, 34`) bypasses text search and resolves those ids directly.
 
 Sources (omit for a broad search across all):
 - memory: curated cross-session project knowledge — rules, constraints, conventions.
 - message: the raw conversation behind your compacted history. Hits include message ordinals — expand the surrounding exchange with ctx_expand(start=N-10, end=N+5).
 - git_commit: this repository's commit history.
-- note: parked decisions, follow-ups, and dismissed notes with their recorded text.
+- note: parked decisions and follow-ups with their recorded text.
 
 Picking sources:
 - "when did this change / was this working before" → ["git_commit", "message"]
@@ -450,9 +465,9 @@ The hash handler persists the MD5 of `output.system.join("\\n")`. The values bel
 
 | Variant | Guidance bytes | MD5 system-prompt hash |
 |---|---:|---|
-| PRIMARY full | 8778 | `e8606e8e36cf19f5588ae0a76ce23b0e` |
-| PRIMARY memory-off | 7737 | `4d528493cac10523f815689677c46ea1` |
-| PRIMARY reduce-off | 6471 | `f5e8089b0ec037f8a81c648edd141913` |
-| SUBAGENT minimal | 691 | `83d69748f204fff98249565d5a31aa99` |
+| PRIMARY full | 8816 | `e8a75373e85edefedf7a5c8c19af3926` |
+| PRIMARY memory-off | 7775 | `402c342a3ff283375c47a1735d03aa1a` |
+| PRIMARY reduce-off | 6526 | `7e5d386d94abe4f101bfd6d891ec183b` |
+| SUBAGENT minimal | 705 | `1c09c70b742f79274c501dd8f7eff1fc` |
 
 The OpenCode and Pi runtime compatibility tests consume this snapshot for omitted `prompt_surface` and explicit `{ default: "full" }`: both assert guidance, registered tool descriptions, tool IDs, and hashes; OpenCode also asserts these parameter schemas directly, while Pi asserts its TypeBox-owned schemas stay byte-identical across both config forms.