@cortexkit/opencode-magic-context 0.31.3 → 0.31.4

package/src/shared/rpc-notifications.ts

@@ -107,38 +107,90 @@ export function pushNotification(
     }
 }
 
-/** Return pending notifications after acking the client's last received id.
+export interface DrainNotificationsOptions {
+    /**
+     * Cursor for global notifications when a session-scoped client sends separate
+     * session and global watermarks.
+     */
+    globalLastReceivedId?: number;
+    /** Ack/drain only the named session, not global notifications. */
+    sessionOnly?: boolean;
+    /** Ack/drain only session-less global notifications. */
+    globalOnly?: boolean;
+}
+
+function cursor(value: number | undefined): number {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** Return pending notifications after pruning only the scopes the client acked.
  *
- *  Session scoping: when `sessionId` is provided, only notifications tagged for
- *  that session (or session-less/global ones) are returned and pruned — a
- *  notification tagged for a DIFFERENT session is never handed to this client
- *  and is never pruned by this client's ack. This matters because the in-memory
- *  queue is per-process but a TUI can end up bound to a process that also serves
- *  OTHER sessions: e.g. opening OpenCode Desktop on the same project starts a
- *  newer RPC server that the TUI's port discovery (newest-pid-wins) then selects,
- *  so a Desktop-session upgrade-dialog action would otherwise surface in an
- *  unrelated TUI session. Each client also tracks its own `lastReceivedId`, so a
- *  global watermark prune would let session A's ack drop session B's still-unseen
- *  notification — scoping the prune to the acking session prevents that too.
+ *  Session-scoped and global notifications have independent cursors. A TUI can
+ *  switch from session A to session B after handling a high id in A; that high
+ *  watermark must never prune B's lower, still-unseen ids. Global notifications
+ *  are also tracked separately so a global dialog does not become a session
+ *  watermark. Legacy callers that omit options keep the original single-cursor
+ *  behavior.
  *
  *  Delivery is at-least-once (non-destructive return + prune-on-ack): a returned
- *  notification stays queued until a later call acks it via a higher
- *  `lastReceivedId`, so a dropped WS socket re-delivers the backlog on reconnect
- *  (the client sends its `lastReceivedId` in the hello). */
-export function drainNotifications(lastReceivedId = 0, sessionId?: string): RpcNotification[] {
+ *  notification stays queued until a later call acks it via the matching scope's
+ *  cursor, so a dropped WS socket re-delivers unhandled backlog on reconnect. */
+export function drainNotifications(
+    lastReceivedId = 0,
+    sessionId?: string,
+    options: DrainNotificationsOptions = {},
+): RpcNotification[] {
+    const sessionCursor = cursor(lastReceivedId);
+
+    if (options.globalOnly) {
+        queue = queue.filter(
+            (notification) =>
+                notification.sessionId !== undefined || notification.id > sessionCursor,
+        );
+        return queue.filter(
+            (notification) =>
+                notification.sessionId === undefined && notification.id > sessionCursor,
+        );
+    }
+
+    if (options.sessionOnly) {
+        if (sessionId === undefined) return [];
+        queue = queue.filter(
+            (notification) =>
+                notification.sessionId !== sessionId || notification.id > sessionCursor,
+        );
+        return queue.filter(
+            (notification) =>
+                notification.sessionId === sessionId && notification.id > sessionCursor,
+        );
+    }
+
+    if (sessionId !== undefined && options.globalLastReceivedId !== undefined) {
+        const globalCursor = cursor(options.globalLastReceivedId);
+        queue = queue.filter((notification) => {
+            if (notification.sessionId === undefined) return notification.id > globalCursor;
+            if (notification.sessionId === sessionId) return notification.id > sessionCursor;
+            return true;
+        });
+        return queue.filter((notification) => {
+            if (notification.sessionId === undefined) return notification.id > globalCursor;
+            return notification.sessionId === sessionId && notification.id > sessionCursor;
+        });
+    }
+
     const matchesClient = (notification: RpcNotification): boolean =>
         sessionId === undefined ||
         notification.sessionId === undefined ||
         notification.sessionId === sessionId;
-    if (lastReceivedId > 0) {
-        // Prune only notifications THIS client both owns (session-matched) and has
-        // acked (id <= lastReceivedId). Other sessions' notifications survive.
+    if (sessionCursor > 0) {
+        // Legacy single-cursor mode prunes the scopes this client can see. New WS
+        // clients pass dual cursors above so cross-session watermarks stay isolated.
         queue = queue.filter(
-            (notification) => !(notification.id <= lastReceivedId && matchesClient(notification)),
+            (notification) => !(notification.id <= sessionCursor && matchesClient(notification)),
         );
     }
     return queue.filter(
-        (notification) => notification.id > lastReceivedId && matchesClient(notification),
+        (notification) => notification.id > sessionCursor && matchesClient(notification),
     );
 }
 

package/src/shared/rpc-server.ts

@@ -52,6 +52,15 @@ function tokensMatch(presented: string, expected: string): boolean {
     return timingSafeEqual(a, b);
 }
 
+function bearerToken(req: Request): string {
+    const auth = req.headers.get("authorization");
+    return typeof auth === "string" ? auth.replace(/^Bearer\s+/i, "") : "";
+}
+
+function websocketToken(req: Request, url: URL): string {
+    return bearerToken(req) || url.searchParams.get("token") || "";
+}
+
 /**
  * Plugin-private localhost RPC server for TUI ↔ server-plugin communication.
  *
@@ -71,6 +80,7 @@ export class MagicContextRpcServer {
     private portFilePath: string;
     private portDir: string;
     private startedAt = Date.now();
+    private readonly instanceId = randomBytes(8).toString("hex");
     /** Every authenticated WS socket, so dispose can close them all. */
     private sockets = new Set<ServerWebSocket<WsData>>();
     // Unguessable per-process bearer token, published in the (user-private) port
@@ -81,7 +91,7 @@ export class MagicContextRpcServer {
     private readonly token = randomBytes(32).toString("hex");
 
     constructor(storageDir: string, directory: string) {
-        this.portFilePath = rpcPortFilePath(storageDir, directory);
+        this.portFilePath = rpcPortFilePath(storageDir, directory, process.pid, this.instanceId);
         this.portDir = rpcPortDir(storageDir, directory);
     }
 
@@ -92,6 +102,7 @@ export class MagicContextRpcServer {
 
     /** Start the server on a random port, write port to disk. */
     async start(): Promise<number> {
+        this.startedAt = Date.now();
         const self = this;
         const server = Bun.serve<WsData>({
             port: 0,
@@ -122,8 +133,8 @@ export class MagicContextRpcServer {
         this.server = server;
         this.port = server.port ?? 0;
 
-        // Write a per-process port file atomically. Multi-instance OpenCode is
-        // supported: TUI discovery scans all live pid files and picks the most
+        // Write a per-instance port file atomically. Multi-instance OpenCode is
+        // supported: TUI discovery scans all live files and picks the most
         // recent instead of cross-wiring via one shared project file.
         try {
             this.warnIfOtherLiveInstance();
@@ -157,6 +168,7 @@ export class MagicContextRpcServer {
                     pid: process.pid,
                     started_at: this.startedAt,
                     token: this.token,
+                    instance_id: this.instanceId,
                 }),
                 { encoding: "utf-8", mode: 0o600 },
             );
@@ -219,8 +231,12 @@ export class MagicContextRpcServer {
     private async handleFetch(req: Request, srv: Server<WsData>): Promise<Response | undefined> {
         const url = new URL(req.url);
 
-        // WebSocket upgrade — the persistent push channel.
+        // WebSocket upgrade — the persistent push channel. Authenticate before
+        // `srv.upgrade` so an unauthorized request never becomes a live socket.
         if (url.pathname === "/ws") {
+            if (!tokensMatch(websocketToken(req, url), this.token)) {
+                return new Response("Unauthorized", { status: 401 });
+            }
             const ok = srv.upgrade(req, { data: { authed: false } });
             if (ok) return undefined;
             return new Response("upgrade failed", { status: 400 });
@@ -237,9 +253,7 @@ export class MagicContextRpcServer {
         }
 
         // Require the per-process bearer token on every side-effecting call.
-        const auth = req.headers.get("authorization");
-        const presented = typeof auth === "string" ? auth.replace(/^Bearer\s+/i, "") : "";
-        if (!tokensMatch(presented, this.token)) {
+        if (!tokensMatch(bearerToken(req), this.token)) {
             return json({ error: "Unauthorized" }, 401);
         }
 
@@ -274,13 +288,22 @@ export class MagicContextRpcServer {
     /** WS message handler: hello (auth + sink registration + backlog drain) and
      *  ack (cursor advance → queue prune). All other messages are ignored. */
     private handleWsMessage(ws: ServerWebSocket<WsData>, raw: string | Buffer): void {
-        let msg: { type?: string; token?: string; sessionId?: string; lastReceivedId?: number };
+        let msg: {
+            type?: string;
+            token?: string;
+            sessionId?: string;
+            lastReceivedId?: number;
+            globalLastReceivedId?: number;
+            ackScope?: string;
+        };
         try {
             msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
         } catch {
             return;
         }
 
+        if (msg.type !== "hello" && !ws.data.authed) return;
+
         if (msg.type === "hello") {
             if (!tokensMatch(typeof msg.token === "string" ? msg.token : "", this.token)) {
                 ws.send(JSON.stringify({ type: "error", error: "unauthorized" }));
@@ -297,6 +320,11 @@ export class MagicContextRpcServer {
                     ? msg.sessionId
                     : undefined;
 
+            // A session switch re-sends hello on the same socket. Remove the old
+            // sink first so the registry has exactly one live sink per socket.
+            ws.data.unregister?.();
+            ws.data.unregister = undefined;
+
             // Register a live sink so future pushes reach this socket immediately.
             const sink: NotificationSink = {
                 sessionId: ws.data.sessionId,
@@ -307,14 +335,28 @@ export class MagicContextRpcServer {
             ws.data.unregister = registerNotificationSink(sink);
             this.sockets.add(ws);
 
-            // Deliver any backlog the client hasn't seen (at-least-once). The
-            // client sends its highest-handled id in the hello; reconnects after a
-            // dropped socket re-deliver from here.
+            // Deliver any backlog the client hasn't seen (at-least-once). Modern
+            // clients send separate session and global cursors; keeping those
+            // watermarks independent prevents a high id in one session from pruning
+            // lower unseen notifications in another session.
             const lastReceivedId = Number(msg.lastReceivedId ?? 0);
-            const backlog = drainNotifications(
-                Number.isFinite(lastReceivedId) ? lastReceivedId : 0,
-                ws.data.sessionId,
-            );
+            const sessionCursor = Number.isFinite(lastReceivedId) ? lastReceivedId : 0;
+            const hasGlobalCursor = typeof msg.globalLastReceivedId === "number";
+            const globalLastReceivedId = hasGlobalCursor
+                ? Number.isFinite(msg.globalLastReceivedId)
+                    ? msg.globalLastReceivedId
+                    : 0
+                : 0;
+            const backlog =
+                ws.data.sessionId === undefined && hasGlobalCursor
+                    ? drainNotifications(globalLastReceivedId, undefined, { globalOnly: true })
+                    : drainNotifications(
+                          sessionCursor,
+                          ws.data.sessionId,
+                          hasGlobalCursor
+                              ? { globalLastReceivedId: globalLastReceivedId }
+                              : undefined,
+                      );
             for (const notification of backlog) {
                 ws.send(JSON.stringify({ type: "notification", notification }));
             }
@@ -323,11 +365,20 @@ export class MagicContextRpcServer {
         }
 
         if (msg.type === "ack") {
-            // Advance the cursor → prune acked notifications from the queue so it
-            // doesn't grow during a long-lived connection. Cheap, event-driven.
+            // Advance only the cursor scope the client handled. Acking session A
+            // must not prune session B, and acking a global notification must not
+            // become a session watermark. Cheap, event-driven queue cleanup.
             const lastReceivedId = Number(msg.lastReceivedId ?? 0);
             if (Number.isFinite(lastReceivedId) && lastReceivedId > 0) {
-                drainNotifications(lastReceivedId, ws.data.sessionId);
+                if (msg.ackScope === "global") {
+                    drainNotifications(lastReceivedId, undefined, { globalOnly: true });
+                } else if (typeof msg.sessionId === "string" && msg.sessionId.length > 0) {
+                    drainNotifications(lastReceivedId, msg.sessionId, { sessionOnly: true });
+                } else {
+                    // Compatibility path for older clients that only know one
+                    // cursor for their current socket scope.
+                    drainNotifications(lastReceivedId, ws.data.sessionId);
+                }
             }
         }
     }

package/src/shared/rpc-utils.ts

@@ -14,6 +14,8 @@ export interface RpcPortFileRecord {
      * auth required" only when the server itself didn't set one).
      */
     token?: string;
+    /** Per-server filename nonce; prevents same-process instances from sharing one file. */
+    instance_id?: string;
 }
 
 /**
@@ -31,8 +33,14 @@ export function rpcPortDir(storageDir: string, directory: string): string {
 }
 
 /** Per-process RPC port file path. */
-export function rpcPortFilePath(storageDir: string, directory: string, pid = process.pid): string {
-    return join(rpcPortDir(storageDir, directory), `port-${pid}.json`);
+export function rpcPortFilePath(
+    storageDir: string,
+    directory: string,
+    pid = process.pid,
+    instanceId?: string,
+): string {
+    const suffix = instanceId ? `-${instanceId}` : "";
+    return join(rpcPortDir(storageDir, directory), `port-${pid}${suffix}.json`);
 }
 
 /** Legacy single-port file used by v0.18.0 and earlier. */
@@ -66,6 +74,8 @@ export function parseRpcPortFile(content: string, fallbackPid = 0): RpcPortFileR
                 pid,
                 started_at: Number.isFinite(startedAt) ? startedAt : 0,
                 token: typeof parsed.token === "string" ? parsed.token : undefined,
+                instance_id:
+                    typeof parsed.instance_id === "string" ? parsed.instance_id : undefined,
             };
         } catch {
             return null;

package/src/tui/data/notification-socket.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    drainNotifications,
+    isTuiConnected,
+    pushNotification,
+} from "../../shared/rpc-notifications";
+import { MagicContextRpcServer } from "../../shared/rpc-server";
+import { closeRpc, initRpcClient } from "./context-db";
+import {
+    _resetNotificationSocketStateForTesting,
+    type SocketNotification,
+    startNotificationSocket,
+} from "./notification-socket";
+
+const originalXdgDataHome = process.env.XDG_DATA_HOME;
+const tempDirs: string[] = [];
+const servers: MagicContextRpcServer[] = [];
+
+afterEach(() => {
+    _resetNotificationSocketStateForTesting();
+    closeRpc();
+    for (const server of servers.splice(0)) {
+        server.stop();
+    }
+    drainNotifications(Number.MAX_SAFE_INTEGER);
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+    if (originalXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+    } else {
+        process.env.XDG_DATA_HOME = originalXdgDataHome;
+    }
+});
+
+function makeDataHome(): string {
+    const dir = mkdtempSync(join(tmpdir(), "mc-notification-socket-"));
+    tempDirs.push(dir);
+    process.env.XDG_DATA_HOME = dir;
+    return dir;
+}
+
+function storageDir(dataHome: string): string {
+    return join(dataHome, "cortexkit", "magic-context");
+}
+
+async function startServer(dataHome: string, directory: string): Promise<MagicContextRpcServer> {
+    const server = new MagicContextRpcServer(storageDir(dataHome), directory);
+    await server.start();
+    servers.push(server);
+    return server;
+}
+
+async function waitFor(condition: () => boolean, label: string, timeoutMs = 4_000): Promise<void> {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (condition()) return;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error(`Timed out waiting for ${label}`);
+}
+
+describe("notification socket", () => {
+    test("uses the active session cursor when switching sessions", async () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const dataHome = makeDataHome();
+        const directory = "/repo-session-cursors";
+        await startServer(dataHome, directory);
+        initRpcClient(directory);
+
+        let activeSession = "ses_A";
+        const received: SocketNotification[] = [];
+        startNotificationSocket({
+            getSessionId: () => activeSession,
+            onNotification: (notification) => {
+                received.push(notification);
+                return true;
+            },
+        });
+
+        await waitFor(() => isTuiConnected("ses_A"), "socket connected to session A");
+        pushNotification("for-b", { action: "show-status-dialog" }, "ses_B");
+        pushNotification("for-a", { action: "show-status-dialog" }, "ses_A");
+        await waitFor(
+            () => received.some((notification) => notification.type === "for-a"),
+            "session A notification",
+        );
+
+        activeSession = "ses_B";
+        await waitFor(
+            () => received.some((notification) => notification.type === "for-b"),
+            "session B backlog after switching sessions",
+        );
+
+        expect(received.map((notification) => notification.type)).toContain("for-a");
+        expect(received.map((notification) => notification.type)).toContain("for-b");
+    });
+
+    test("resets the cached endpoint after websocket close so reconnect discovers a new server", async () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const dataHome = makeDataHome();
+        const directory = "/repo-reconnect";
+        const first = await startServer(dataHome, directory);
+        initRpcClient(directory);
+
+        const received: SocketNotification[] = [];
+        startNotificationSocket({
+            getSessionId: () => "ses_R",
+            onNotification: (notification) => {
+                received.push(notification);
+                return true;
+            },
+        });
+        await waitFor(() => isTuiConnected("ses_R"), "initial websocket connection");
+
+        const second = await startServer(dataHome, directory);
+        expect(second).toBeDefined();
+        first.stop();
+        await waitFor(() => !isTuiConnected("ses_R"), "old websocket sink removed");
+        await waitFor(() => isTuiConnected("ses_R"), "websocket reconnected to replacement server");
+
+        pushNotification("after-restart", { action: "show-status-dialog" }, "ses_R");
+        await waitFor(
+            () => received.some((notification) => notification.type === "after-restart"),
+            "notification from replacement server",
+        );
+    });
+});

package/src/tui/data/notification-socket.ts

@@ -51,9 +51,21 @@ let opts: NotificationSocketOptions | null = null;
 /** Generation of the rpc client at connect time; a dispose/reinit bumps it and
  *  invalidates an in-flight socket so its late callbacks are ignored. */
 let connectGeneration = 0;
-/** Highest handled notification id (sent in hello so a reconnect re-delivers the
- *  unhandled backlog; sent in ack so the server prunes the queue). */
-let lastHandledId = 0;
+
+const GLOBAL_CURSOR_KEY = "global";
+const SESSION_CURSOR_PREFIX = "session:";
+const MAX_DEDUPED_NOTIFICATION_IDS = 500;
+
+/**
+ * Notification ids are process-global, but acknowledgement cursors are scoped. A
+ * high id consumed in session A must not become the prune watermark for session B;
+ * global notifications also carry their own cursor so they cannot skip session
+ * backlog. The id set de-dupes at-least-once re-delivery when a reconnect sends
+ * a session cursor that is intentionally lower than the global cursor.
+ */
+const lastHandledIdByCursor = new Map<string, number>();
+const handledNotificationIds = new Set<number>();
+const handledNotificationIdOrder: number[] = [];
 
 /** Open the persistent notification socket. Idempotent: a second call while open
  *  is a no-op. Reconnects on its own after any drop. */
@@ -118,8 +130,10 @@ async function connect(): Promise<void> {
 
     let ws: WebSocket;
     try {
-        ws = new WebSocket(`ws://127.0.0.1:${endpoint.port}/ws`);
+        const tokenQuery = `?token=${encodeURIComponent(endpoint.token ?? "")}`;
+        ws = new WebSocket(`ws://127.0.0.1:${endpoint.port}/ws${tokenQuery}`);
     } catch {
+        client.reset();
         scheduleReconnect();
         return;
     }
@@ -137,6 +151,7 @@ async function connect(): Promise<void> {
     });
 
     const onDown = () => {
+        client.reset();
         if (socket === ws) {
             socket = null;
             helloedSession = null;
@@ -155,7 +170,8 @@ function sendHello(ws: WebSocket, token: string | null): void {
             type: "hello",
             token: token ?? "",
             sessionId,
-            lastReceivedId: lastHandledId,
+            lastReceivedId: cursorForKey(cursorKeyForSession(sessionId)),
+            globalLastReceivedId: cursorForKey(GLOBAL_CURSOR_KEY),
         }),
     );
 }
@@ -180,6 +196,11 @@ async function handleSocketMessage(ws: WebSocket, raw: string): Promise<void> {
             // session, or a later switch back, should still get it). Just skip.
             return;
         }
+        if (handledNotificationIds.has(notification.id)) {
+            sendAck(ws, notification);
+            return;
+        }
+
         let consumed = false;
         try {
             consumed = await Promise.resolve(opts?.onNotification(notification) ?? false);
@@ -188,17 +209,13 @@ async function handleSocketMessage(ws: WebSocket, raw: string): Promise<void> {
         }
         // A dispose/reinit during an awaited dialog handler invalidates this socket.
         if (socket !== ws || getRpcGeneration() !== connectGeneration) return;
-        if (consumed && notification.id > lastHandledId) {
-            lastHandledId = notification.id;
-            // Ack so the server prunes the queue during this long-lived connection.
-            // (The id also rides the next reconnect hello via lastReceivedId, so a
-            // dropped ack just re-delivers an already-consumed item, which the
-            // handlers are idempotent against.)
-            try {
-                ws.send(JSON.stringify({ type: "ack", lastReceivedId: lastHandledId }));
-            } catch {
-                // best-effort; reconnect hello re-syncs via lastReceivedId
-            }
+        if (consumed) {
+            rememberHandledId(notification.id);
+            advanceCursor(notificationCursorKey(notification), notification.id);
+            // Ack only the notification's own cursor scope. A dropped ack is safe:
+            // the next hello sends the same per-scope cursors and duplicates are
+            // ignored locally.
+            sendAck(ws, notification);
         }
         return;
     }
@@ -214,6 +231,54 @@ async function handleSocketMessage(ws: WebSocket, raw: string): Promise<void> {
     }
 }
 
+function cursorKeyForSession(sessionId: string | null | undefined): string {
+    return sessionId ? `${SESSION_CURSOR_PREFIX}${sessionId}` : GLOBAL_CURSOR_KEY;
+}
+
+function notificationCursorKey(notification: SocketNotification): string {
+    return notification.sessionId
+        ? `${SESSION_CURSOR_PREFIX}${notification.sessionId}`
+        : GLOBAL_CURSOR_KEY;
+}
+
+function cursorForKey(key: string): number {
+    return lastHandledIdByCursor.get(key) ?? 0;
+}
+
+function advanceCursor(key: string, id: number): void {
+    if (id > cursorForKey(key)) lastHandledIdByCursor.set(key, id);
+}
+
+function rememberHandledId(id: number): void {
+    if (handledNotificationIds.has(id)) return;
+    handledNotificationIds.add(id);
+    handledNotificationIdOrder.push(id);
+    while (handledNotificationIdOrder.length > MAX_DEDUPED_NOTIFICATION_IDS) {
+        const evicted = handledNotificationIdOrder.shift();
+        if (evicted !== undefined) handledNotificationIds.delete(evicted);
+    }
+}
+
+function sendAck(ws: WebSocket, notification: SocketNotification): void {
+    const lastReceivedId = cursorForKey(notificationCursorKey(notification));
+    const ack = notification.sessionId
+        ? { type: "ack", sessionId: notification.sessionId, lastReceivedId }
+        : { type: "ack", ackScope: "global", lastReceivedId };
+    try {
+        ws.send(JSON.stringify(ack));
+    } catch {
+        // best-effort; reconnect hello re-syncs via per-scope cursors
+    }
+}
+
+export function _resetNotificationSocketStateForTesting(): void {
+    stopNotificationSocket();
+    opts = null;
+    lastHandledIdByCursor.clear();
+    handledNotificationIds.clear();
+    handledNotificationIdOrder.length = 0;
+}
+
 /** Cheap session-change watcher: re-scope the socket only when the active session
  *  actually changes. Reads a property; no network at idle. */
 function watchSession(): void {

package/src/tui/entry.mjs

@@ -2,15 +2,35 @@
 // registers these virtual modules process-wide, which lets the precompiled TUI
 // use the host's single Solid/OpenTUI runtime even when this package is loaded
 // from an npm cache under node_modules.
+const runtimeProbe = "opentui:runtime-module:" + encodeURIComponent("@opentui/solid");
+
+function isMissingRuntimeRegistry(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /Cannot find|Could not resolve|Module not found|Unable to resolve/.test(message) &&
+        message.includes("opentui:runtime-module:");
+}
+
 let mod;
 try {
-    await import("opentui:runtime-module:" + encodeURIComponent("@opentui/solid"));
-    mod = await import("../tui-compiled/index.tsx");
-} catch {
+    await import(runtimeProbe);
+} catch (error) {
+    if (!isMissingRuntimeRegistry(error)) {
+        console.error("Magic Context TUI runtime registry probe failed", error);
+        throw error;
+    }
     // Older hosts and bare Bun do not provide the virtual registry. Falling back
     // to the raw TSX entry keeps development checkouts and OpenTUI 0.3.x hosts
     // working where the Solid transform still applies to this source path.
     mod = await import("./index.tsx");
 }
 
+if (!mod) {
+    try {
+        mod = await import("../tui-compiled/index.tsx");
+    } catch (error) {
+        console.error("Magic Context compiled TUI failed to load", error);
+        throw error;
+    }
+}
+
 export default mod.default;