@cortexkit/opencode-magic-context 0.49.15 → 0.49.17

package/dist/wrapup-orchestrator-j7d7ry5b.js

@@ -0,0 +1,48 @@
+import {
+  runManagedWrapup2
+} from "./index-5a1ex6x8.js";
+import"./index-nkpmm9q8.js";
+import"./index-a7c4r5re.js";
+import"./index-4s3t0nd0.js";
+import"./index-v8awdgvd.js";
+import"./index-cwzfcbtq.js";
+import"./index-sd3egckz.js";
+import"./index-24fezq97.js";
+import"./index-ze7mvk54.js";
+import"./index-n37sebck.js";
+import"./index-4dhv7mqz.js";
+import"./index-v10f1rjv.js";
+import"./index-s74zqahq.js";
+import"./index-qt1qqasc.js";
+import"./index-p7m7j0cp.js";
+import"./index-hqhm3wke.js";
+import"./index-1zx87sdm.js";
+import"./index-kq82mtg0.js";
+import"./index-x8a7jmkh.js";
+import"./index-y9f76s3f.js";
+import"./index-bjcnntmz.js";
+import"./index-wgypt3cs.js";
+import"./index-rr2bb45z.js";
+import"./index-b5vqckbw.js";
+import"./index-6x57ar45.js";
+import"./index-fb2qxs2y.js";
+import"./index-fb3zxn06.js";
+import"./index-qn7xstt2.js";
+import"./index-2vxtcb95.js";
+import"./index-a6mc0v4d.js";
+import"./index-fr0wbhdn.js";
+import"./index-nj7yykkx.js";
+import"./index-ke416mdc.js";
+import"./index-bp5083x2.js";
+import"./index-58e3y90n.js";
+import"./index-s734jcsr.js";
+import"./index-v0p37hm2.js";
+import"./index-k29z4aqh.js";
+import"./index-c5pytzne.js";
+import"./index-beht37jy.js";
+import"./index-j75v2476.js";
+import"./index-g2q4htwp.js";
+import"./index-pavzsdc6.js";
+export {
+  runManagedWrapup2 as runManagedWrapup
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/opencode-magic-context",
-  "version": "0.49.15",
+  "version": "0.49.17",
   "type": "module",
   "description": "OpenCode plugin for Magic Context — cross-session memory and context management",
   "main": "dist/index.js",

package/src/config/latch-permanence-guard.test.ts

@@ -188,6 +188,10 @@ const KNOWN_SLOTS: Record<string, KnownSlot> = {
         classification: "DIAGNOSTIC",
         reason: "Most-recent diagnostic: every open attempt clears or overwrites it.",
     },
+    "packages/pi-plugin/src/pi-append-compaction.ts:loggedIncompatibleHost": {
+        classification: "DIAGNOSTIC",
+        reason: "Log-once flag for the incompatible-host error line only: the binding and getEntry checks run again on every adaptPiAppendCompaction call, so a host that becomes compatible gets markers without a restart.",
+    },
     "packages/plugin/src/shared/models-dev-cache.ts:apiCache": {
         classification: "PUBLICATION",
         reason: "Publishes last-known-good model metadata, not a failure verdict; refresh writes a later successful value.",

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

@@ -205,12 +205,14 @@ export type OmpEntry = z.infer<typeof OmpEntrySchema>;
 /** Strict model-resolution block used by historian.opencode. */
 export const OpenCodeHarnessBlockSchema = z
     .object({
-        model: OcEntrySchema.optional().describe("Primary OpenCode model entry."),
+        model: OcEntrySchema.optional().describe(
+            "Primary historian OpenCode model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. When absent, OpenCode inherits the session model.",
+        ),
         fallback_models: z
             .array(OcEntrySchema)
             .optional()
             .describe(
-                "Ordered fallback OpenCode entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+                "Ordered historian fallback OpenCode entries. A configured primary never adds the session model after this list. Requires an array; legacy singleton values migrate to a one-element array.",
             ),
         variant: z
             .string()
@@ -226,12 +228,14 @@ export type OpenCodeHarnessBlock = z.infer<typeof OpenCodeHarnessBlockSchema>;
 /** Strict model-resolution block used by historian.pi. */
 export const PiHarnessBlockSchema = z
     .object({
-        model: PiEntrySchema.optional().describe("Primary Pi model entry."),
+        model: PiEntrySchema.optional().describe(
+            "Primary historian Pi model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. When absent, Pi does not run the historian.",
+        ),
         fallback_models: z
             .array(PiEntrySchema)
             .optional()
             .describe(
-                "Ordered fallback Pi entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+                "Ordered historian fallback Pi entries. The session model is never appended. Requires an array; legacy singleton values migrate to a one-element array.",
             ),
         thinking_level: PiThinkingLevelSchema.describe(
             "Pi thinking level for the primary entry when it declares none. Fallback entries declare thinking levels per-entry.",
@@ -244,11 +248,15 @@ export type PiHarnessBlock = z.infer<typeof PiHarnessBlockSchema>;
 /** Strict model-resolution block used by historian.omp. */
 export const OmpHarnessBlockSchema = z
     .object({
-        model: OmpEntrySchema.optional().describe("Primary OMP model entry."),
+        model: OmpEntrySchema.optional().describe(
+            "Primary historian OMP model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. An absent OMP block inherits the Pi block; a selected block without a model does not run the historian.",
+        ),
         fallback_models: z
             .array(OmpEntrySchema)
             .optional()
-            .describe("Ordered fallback OMP entries."),
+            .describe(
+                "Ordered historian fallback OMP entries. The session model is never appended.",
+            ),
         thinking_level: OmpThinkingLevelSchema.describe(
             "OMP thinking level for the primary entry when it declares none. Fallback entries declare thinking levels per-entry.",
         ),

package/src/shared/historian-cache.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { withoutHistorianTailCache } from "./historian-cache";
+
+// Deliberately non-canonical JSON catches accidental parse/stringify rewrites.
+const anthropicBody = String.raw`{ "model":"claude-test", "max_tokens":1e3, "system":[{"type":"text","text":"stable \\n prefix","cache_control":{"type":"ephemeral"}}], "messages":[{"role":"user","content":[{"type":"text", "text":"seed \\u0041 / chunk \ud83d\udc4b", "cache_control":{"type":"ephemeral","ttl":"5m"}}]}], "temperature":0.00 }`;
+const systemOnlyBody = anthropicBody.replace(
+    ', "cache_control":{"type":"ephemeral","ttl":"5m"}',
+    "",
+);
+
+describe("historian wire cache markers", () => {
+    test("retry retains an existing whole-tail read and fresh repair retains the system read", () => {
+        const initial = JSON.parse(anthropicBody);
+        const prefixes = (request: typeof initial): string[] => {
+            let prefix = "";
+            const marked: string[] = [];
+            for (const block of [
+                ...request.system,
+                ...request.messages.flatMap((message: { content: unknown[] }) => message.content),
+            ]) {
+                prefix += block.text;
+                if (block.cache_control) marked.push(prefix);
+            }
+            return marked;
+        };
+        const written = new Set(prefixes(initial));
+        const retry = JSON.parse(anthropicBody);
+        expect(prefixes(retry).filter((prefix) => written.has(prefix))).toHaveLength(2);
+        const repair = JSON.parse(withoutHistorianTailCache(anthropicBody));
+        repair.messages[0].content[0].text += "\n\nValidation error and invalid XML";
+        expect(prefixes(repair).filter((prefix) => written.has(prefix))).toEqual([
+            initial.system[0].text,
+        ]);
+        expect(repair.messages[0].content[0].cache_control).toBeUndefined();
+    });
+    test("splices only tail marker bytes without changing prompt or generation bytes", () => {
+        expect(withoutHistorianTailCache(anthropicBody)).toBe(systemOnlyBody);
+        expect(JSON.parse(systemOnlyBody).system).toEqual(JSON.parse(anthropicBody).system);
+        expect(JSON.parse(systemOnlyBody).messages[0].content[0].text).toBe(
+            JSON.parse(anthropicBody).messages[0].content[0].text,
+        );
+    });
+    test("removes first, middle and sole properties, preserving other bytes", () => {
+        for (const [block, expected] of [
+            ['{"cache_control":{}, "type":"text","text":"x"}', '{"type":"text","text":"x"}'],
+            ['{"type":"text", "cache_control":{}, "text":"x"}', '{"type":"text", "text":"x"}'],
+            ['{"cache_control":{}}', "{}"],
+        ]) {
+            const body = JSON.stringify({
+                model: "claude",
+                max_tokens: 100,
+                system: [{ type: "text", text: "system", cache_control: { type: "ephemeral" } }],
+                messages: [{ role: "user", content: [] }],
+            }).replace('"content":[]', `"content":[${block}]`);
+            expect(withoutHistorianTailCache(body)).toBe(body.replace(block, expected));
+        }
+    });
+    test("unknown, wrapped and automatic-cache envelopes are byte-identical", () => {
+        for (const body of [
+            '{"model":"claude","messages":[],"max_tokens":100}',
+            '{"model":"gpt","messages":[{"role":"user","content":"x"}],"max_tokens":100}',
+            '{"anthropic_version":"bedrock-2023-05-31","messages":[],"system":[],"max_tokens":100}',
+            '{"instances":[{"messages":[]}]}',
+            anthropicBody.replace(',"cache_control":{"type":"ephemeral"}', ""),
+            anthropicBody.replace('"temperature":0.00', '"cache_control":{"type":"ephemeral"}'),
+        ])
+            expect(withoutHistorianTailCache(body)).toBe(body);
+    });
+});

package/src/shared/historian-cache.ts

@@ -0,0 +1,55 @@
+import { type Node, parseTree } from "jsonc-parser/lib/esm/main.js";
+
+export type HistorianCacheTail = "write" | "skip";
+
+/**
+ * Remove only message-block cache markers from a recognized Anthropic Messages
+ * body. Splicing property spans preserves every other wire byte, including
+ * number spelling, escaping and whitespace. Unknown envelopes stay untouched.
+ */
+export function withoutHistorianTailCache(body: string): string {
+    const value = JSON.parse(body);
+    if (
+        !value ||
+        typeof value.model !== "string" ||
+        typeof value.max_tokens !== "number" ||
+        !Array.isArray(value.system) ||
+        value.system.length === 0 ||
+        !value.system.every(
+            (part: { type?: unknown; text?: unknown }) =>
+                part?.type === "text" && typeof part.text === "string",
+        ) ||
+        !value.system.some((part: { cache_control?: unknown }) => part.cache_control) ||
+        !Array.isArray(value.messages) ||
+        value.cache_control !== undefined
+    )
+        return body;
+
+    const root = parseTree(body);
+    const property = (node: Node | undefined, key: string): Node | undefined =>
+        node?.children?.find((child) => child.children?.[0]?.value === key)?.children?.[1];
+    const removals: Array<[number, number]> = [];
+    for (const message of property(root, "messages")?.children ?? []) {
+        for (const block of property(message, "content")?.children ?? []) {
+            if (block.type !== "object") continue;
+            const fields = block.children ?? [];
+            fields.forEach((field, index) => {
+                if (field.children?.[0]?.value !== "cache_control") return;
+                const next = fields[index + 1];
+                const previous = fields[index - 1];
+                removals.push(
+                    next
+                        ? [field.offset, next.offset]
+                        : [
+                              previous ? previous.offset + previous.length : field.offset,
+                              field.offset + field.length,
+                          ],
+                );
+            });
+        }
+    }
+    for (const [start, end] of removals.sort((a, b) => b[0] - a[0])) {
+        body = body.slice(0, start) + body.slice(end);
+    }
+    return body;
+}

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

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { parsePluginConfig } from "../config";
 
 import {
     normalizeModelEntry,
@@ -9,6 +10,27 @@ import {
 } from "./model-resolution";
 
 describe("model-resolution", () => {
+    test("loader defaults and historian metadata do not configure a primary model", () => {
+        for (const harness of ["opencode", "pi", "omp"] as const) {
+            for (const input of [
+                {},
+                { historian: {} },
+                { historian: { temperature: 0, [harness]: {} } },
+            ]) {
+                expect(
+                    resolveHistorianModel(parsePluginConfig(input), harness).primary,
+                ).toBeUndefined();
+            }
+            for (const model of [" provider/explicit ", { model: "provider/explicit" }]) {
+                expect(
+                    resolveHistorianModel(
+                        parsePluginConfig({ historian: { [harness]: { model } } }),
+                        harness,
+                    ).primary?.model,
+                ).toBe("provider/explicit");
+            }
+        }
+    });
     test("keeps historian temperature opt-in while preserving explicit overrides", () => {
         const fixtures = [
             { temperature: undefined, expected: undefined },

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

@@ -41,6 +41,8 @@ export type PromptBody = {
 export type PromptArgs = {
     path: { id: string };
     body: PromptBody;
+    /** Controls hidden historian message-block cache markers; never serialized in the prompt body. */
+    cacheTail?: import("./historian-cache").HistorianCacheTail;
     signal?: AbortSignal;
     [key: string]: unknown;
 };
@@ -72,6 +74,8 @@ export interface PromptAttemptInfo {
 export interface PromptRetryOptions {
     transport?: PromptTransport;
     timeoutMs?: number;
+    /** False for callers whose configured model chain must not accept provider suggestions. Defaults to true. */
+    allowModelSuggestions?: boolean;
     /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
     signal?: AbortSignal;
     /**
@@ -508,6 +512,7 @@ async function attemptOnce(
     callContext: string,
     label: string,
     transport?: PromptTransport,
+    allowModelSuggestions = true,
 ): Promise<void> {
     // Keep this snapshot separate from the object passed to the client. A
     // failed prompt facade may rewrite its request body before rejecting; the
@@ -518,9 +523,9 @@ async function attemptOnce(
         await promptWithTimeout(client, attemptArgs, timeoutMs, signal, transport);
         return;
     } catch (error) {
-        // If non-retryable (abort, overflow, timeout), bubble up immediately.
-        // Don't even try suggestion retry — caller needs the original error.
-        if (isNonRetryable(error, signal)) throw error;
+        // Non-retryable failures and callers with model suggestions disabled
+        // must surface the original error without accepting a provider suggestion.
+        if (isNonRetryable(error, signal) || !allowModelSuggestions) throw error;
 
         const suggestion = parseModelSuggestion(error);
         if (!suggestion || !originalBody.model) {
@@ -596,6 +601,7 @@ export async function promptSyncWithModelSuggestionRetry(
             callContext,
             explicitPrimaryLabel,
             options.transport,
+            options.allowModelSuggestions,
         );
         return;
     } catch (error) {
@@ -640,6 +646,7 @@ export async function promptSyncWithModelSuggestionRetry(
                 callContext,
                 label,
                 options.transport,
+                options.allowModelSuggestions,
             );
             log(
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
@@ -685,6 +692,7 @@ async function attemptAndValidate<TOutput, TValidated>(
             callContext,
             attempt.label,
             options.transport,
+            options.allowModelSuggestions,
         );
     } catch (error) {
         throw {

package/src/shared/resolve-fallbacks.test.ts

@@ -4,9 +4,8 @@ import { modelBodyField, parseProviderModel, resolveFallbackChain } from "./reso
 
 describe("resolveFallbackChain", () => {
     // Policy: user-config-only. There is NO builtin provider-agnostic chain —
-    // when the user configures no fallback_models the result is EMPTY, and the
-    // runner's session-model last resort (a model the user actually has) is the
-    // only fallback. A hardcoded chain named providers the user may not have and
+    // when the user configures no fallback_models the result is empty.
+    // A hardcoded chain named providers the user may not have and
     // produced `Model not found` retry storms.
     test("returns empty when user provides nothing (no builtin chain)", () => {
         expect(resolveFallbackChain(undefined)).toEqual([]);

package/src/shared/resolve-fallbacks.ts

@@ -9,9 +9,9 @@ import type { ModelInput, ResolvedModelEntry } from "./model-resolution";
  * inevitably names providers the user doesn't have (e.g. a metapi-only user got
  * a chain of google/github-copilot/opencode entries, every one a
  * `Model not found` retry), which produced confusing errors and wasted
- * attempts. If the user configured nothing, this returns an empty list and the
- * runner's session-model last resort (the model the user is actually using) is
- * the only fallback.
+ * attempts. If the user configured no alternates, this returns an empty list.
+ * A configured historian never adds the session model to this list; only an
+ * unconfigured OpenCode historian inherits the session model.
  *
  * The returned list does NOT include the primary model — it's the ordered list
  * of *alternates* to try after the primary fails. Each entry is

package/src/shared/rpc-discovery-cleanup.test.ts

@@ -0,0 +1,57 @@
+import { expect, spyOn, test } from "bun:test";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MagicContextRpcServer } from "./rpc-server";
+import * as utils from "./rpc-utils";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+test("RPC startup reaps dead records across projects but keeps live and inconclusive records", async () => {
+    const root = createTestTempDirFromPath(join(tmpdir(), "rpc-reap-"));
+    const server = new MagicContextRpcServer(root, "/current-project");
+    const dir = utils.rpcPortDir(root, "/other-project");
+    const empty = utils.rpcPortDir(root, "/empty-project");
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(empty, { recursive: true });
+    for (const pid of [999999, 888888, process.pid])
+        writeFileSync(
+            join(dir, `port-${pid}.json`),
+            JSON.stringify({ port: 1234, pid, token: "do-not-log" }),
+        );
+    const probe = spyOn(utils, "inspectProcessesAsync").mockResolvedValue({
+        pi: { state: "absent", processIds: [] },
+        evidence: () => ({ processStartTime: null, commandLine: null, imageName: null }),
+        liveness: (pid: number) =>
+            pid === 999999 ? "dead" : pid === 888888 ? "inconclusive" : "alive",
+    } as Awaited<ReturnType<typeof utils.inspectProcessesAsync>>);
+    try {
+        await server.start();
+        expect(readdirSync(dir).sort()).toEqual(
+            [`port-${process.pid}.json`, "port-888888.json"].sort(),
+        );
+        expect(existsSync(empty)).toBe(false);
+    } finally {
+        server.stop();
+        probe.mockRestore();
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test("RPC stop removes its empty discovery directory but preserves other instances", async () => {
+    const root = createTestTempDirFromPath(join(tmpdir(), "rpc-stop-reap-"));
+    const first = new MagicContextRpcServer(root, root);
+    const second = new MagicContextRpcServer(root, root);
+    const directory = utils.rpcPortDir(root, root);
+    try {
+        await first.start();
+        await second.start();
+        first.stop();
+        expect(readdirSync(directory)).toHaveLength(1);
+        second.stop();
+        expect(existsSync(directory)).toBe(false);
+    } finally {
+        first.stop();
+        second.stop();
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/src/shared/rpc-discovery-cleanup.ts

@@ -0,0 +1,57 @@
+import { type Dirent, promises as fs } from "node:fs";
+import { join } from "node:path";
+import { inspectProcessesAsync, parseRpcPortFile } from "./rpc-utils";
+
+/** Reap only records proven dead; live, unreadable and uncertain records stay. */
+export async function reapDeadRpcDiscovery(storageDir: string): Promise<void> {
+    const root = join(storageDir, "rpc");
+    let directories: Dirent[];
+    try {
+        directories = await fs.readdir(root, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    const records: { path: string; content: string; pid: number }[] = [];
+    const projectDirs: string[] = [];
+    for (const entry of directories) {
+        if (!entry.isDirectory() || !/^[0-9a-f]{16}$/.test(entry.name)) continue;
+        const directory = join(root, entry.name);
+        projectDirs.push(directory);
+        try {
+            for (const name of await fs.readdir(directory)) {
+                const match = /^port-(\d+)(?:-[0-9a-f]+)?\.json$/.exec(name);
+                if (!match) continue;
+                const path = join(directory, name);
+                try {
+                    const content = await fs.readFile(path, "utf8");
+                    const record = parseRpcPortFile(content, Number(match[1]));
+                    if (record && record.pid === Number(match[1]))
+                        records.push({ path, content, pid: record.pid });
+                } catch {
+                    // Another host may be publishing or stopping this record.
+                }
+            }
+        } catch {
+            // An inaccessible project must not prevent cleanup of other projects.
+        }
+    }
+    // Read records before a fresh process snapshot so a recently started host
+    // cannot be mistaken for a PID missing from an older cached snapshot.
+    const processes = records.length ? await inspectProcessesAsync(true) : undefined;
+    for (const record of records) {
+        if (processes?.liveness(record.pid) !== "dead") continue;
+        try {
+            if ((await fs.readFile(record.path, "utf8")) === record.content)
+                await fs.unlink(record.path);
+        } catch {
+            // Leave the record for a later pass; never recursively remove its directory.
+        }
+    }
+    for (const directory of projectDirs) {
+        try {
+            await fs.rmdir(directory);
+        } catch {
+            // Leave non-empty directories untouched; they may still contain records for hosts not proven dead.
+        }
+    }
+}

package/src/shared/rpc-server.ts

@@ -1,7 +1,8 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
-import { readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { readdirSync, readFileSync, rmdirSync, unlinkSync } from "node:fs";
 import type { Server, ServerWebSocket } from "bun";
 import { log } from "./logger";
+import { reapDeadRpcDiscovery } from "./rpc-discovery-cleanup";
 import {
     acknowledgeNotifications,
     drainNotifications,
@@ -82,6 +83,7 @@ export class MagicContextRpcServer {
     private portFilePath: string;
     private portDir: string;
     private startedAt = Date.now();
+    private stopped = false;
     private readonly instanceId = randomBytes(8).toString("hex");
     private unregisterOwnInstance: (() => void) | null = null;
     /** Every authenticated WS socket, so dispose can close them all. */
@@ -93,7 +95,10 @@ export class MagicContextRpcServer {
     // discovers/guesses the port.
     private readonly token = randomBytes(32).toString("hex");
 
-    constructor(storageDir: string, directory: string) {
+    constructor(
+        private storageDir: string,
+        directory: string,
+    ) {
         this.portFilePath = rpcPortFilePath(storageDir, directory, process.pid, this.instanceId);
         this.portDir = rpcPortDir(storageDir, directory);
     }
@@ -131,6 +136,9 @@ export class MagicContextRpcServer {
             log("rpc server skipped: Bun runtime not available (no TUI consumer)");
             return 0;
         }
+        this.stopped = false;
+        await reapDeadRpcDiscovery(this.storageDir);
+        if (this.stopped) return 0;
         this.startedAt = Date.now();
         const self = this;
         const server = inRootAsyncContext(() =>
@@ -172,17 +180,26 @@ export class MagicContextRpcServer {
             // The discovery file carries the RPC bearer token. The shared writer
             // creates its directory and temporary file with owner-only modes.
             this.unregisterOwnInstance ??= registerOwnRpcServerInstance(this.instanceId);
-            writeStorageFileAtomicSync(
-                this.portFilePath,
-                JSON.stringify({
-                    port: this.port,
-                    pid: process.pid,
-                    started_at: this.startedAt,
-                    kind: "OpenCode server",
-                    token: this.token,
-                    instance_id: this.instanceId,
-                }),
-            );
+            const publish = () =>
+                writeStorageFileAtomicSync(
+                    this.portFilePath,
+                    JSON.stringify({
+                        port: this.port,
+                        pid: process.pid,
+                        started_at: this.startedAt,
+                        kind: "OpenCode server",
+                        token: this.token,
+                        instance_id: this.instanceId,
+                    }),
+                );
+            try {
+                publish();
+            } catch (error) {
+                // An empty-directory reaper can race the writer before its temp
+                // file exists. Recreate the directory and retry that case only.
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+                publish();
+            }
             log(`[rpc] server listening on 127.0.0.1:${this.port}`);
         } catch (err) {
             log(`[rpc] failed to write port file: ${err}`);
@@ -193,6 +210,7 @@ export class MagicContextRpcServer {
 
     /** Stop the server: close every socket, stop accepting, remove port file. */
     stop(): void {
+        this.stopped = true;
         for (const ws of this.sockets) {
             try {
                 if (ws.data.authTimer) clearTimeout(ws.data.authTimer);
@@ -213,6 +231,11 @@ export class MagicContextRpcServer {
         } catch {
             // Intentional: port file may already be gone
         }
+        try {
+            rmdirSync(this.portDir);
+        } catch {
+            // Other instances' discovery records must survive this server's stop.
+        }
         this.unregisterOwnInstance?.();
         this.unregisterOwnInstance = null;
     }

package/src/shared/search-text.test.ts

@@ -0,0 +1,47 @@
+import { expect, test } from "bun:test";
+import { cleanSearchText, keywordRelevance, matchedSearchSnippet } from "./search-text";
+import { removeSystemReminders } from "./system-directive";
+
+test("nested reminder contents stay quarantined through the outer closing tag", () => {
+    expect(
+        removeSystemReminders(
+            'before <SYSTEM-REMINDER origin="host">outer <system-reminder>inner</system-reminder> leaked tail</SYSTEM-REMINDER> after',
+        ),
+    ).toBe("before  after");
+    expect(removeSystemReminders("before <system-reminder>unfinished")).toBe("before");
+    expect(removeSystemReminders("before </system-reminder> after")).toBe("before  after");
+});
+
+test("mismatched notification closes cannot release hidden content", () => {
+    expect(cleanSearchText("kept <task>hidden </task_cohort> still hidden</task> kept")).toBe(
+        "kept kept",
+    );
+    expect(cleanSearchText("kept <task id='finished'/> kept")).toBe("kept kept");
+});
+
+test("task notification trees and cut legacy XML never become hint text", () => {
+    expect(
+        cleanSearchText(
+            '<task_cohort id="parent"><task id="child">background result</task>status</task_cohort> actual answer',
+        ),
+    ).toBe("actual answer");
+    expect(cleanSearchText('<task id="truncated">background result…')).toBe("");
+});
+
+test("keyword confidence measures absolute distinct term coverage, not result rank", () => {
+    expect(keywordRelevance("explain historian cache wiring", "cache icons")).toBeCloseTo(0.2);
+    expect(
+        keywordRelevance("historian cache wiring", "historian cache wiring details"),
+    ).toBeCloseTo(0.8);
+    expect(keywordRelevance("historian cache wiring", "<task>historian cache wiring</task>")).toBe(
+        0,
+    );
+});
+
+test("matched snippets prefer a dense passage over an irrelevant first line", () => {
+    const content = `Header cache. ${"padding ".repeat(150)}Historian cache wiring uses incremental pools. ${"trailing ".repeat(100)}`;
+    const snippet = matchedSearchSnippet(content, "historian cache wiring", 80);
+    expect(snippet).toContain("Historian cache wiring");
+    expect(snippet).not.toContain("Header");
+    expect(matchedSearchSnippet(content, "unrelated deployment")).toBe("");
+});