@cortexkit/opencode-magic-context 0.32.0 → 0.32.1

package/src/shared/rpc-client.test.ts

@@ -4,7 +4,12 @@ import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { MagicContextRpcClient } from "./rpc-client";
-import { drainNotifications, isTuiConnected, pushNotification } from "./rpc-notifications";
+import {
+    __resetNotificationStateForTests,
+    drainNotifications,
+    isTuiConnected,
+    pushNotification,
+} from "./rpc-notifications";
 import { MagicContextRpcServer } from "./rpc-server";
 import { parseRpcPortFile, type RpcPortFileRecord, rpcPortDir, rpcPortFilePath } from "./rpc-utils";
 
@@ -20,6 +25,7 @@ afterEach(async () => {
     for (const server of servers.splice(0)) {
         await server.close();
     }
+    __resetNotificationStateForTests();
     for (const dir of tempDirs.splice(0)) {
         try {
             rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
@@ -51,10 +57,23 @@ function writePortFileForPid(
     port: number,
     pid: number,
     startedAt: number,
-): void {
-    const portFile = rpcPortFilePath(storageDir, directory, pid);
+    instanceId?: string,
+    token?: string,
+): string {
+    const portFile = rpcPortFilePath(storageDir, directory, pid, instanceId);
     mkdirSync(dirname(portFile), { recursive: true });
-    writeFileSync(portFile, JSON.stringify({ port, pid, started_at: startedAt }), "utf-8");
+    writeFileSync(
+        portFile,
+        JSON.stringify({
+            port,
+            pid,
+            started_at: startedAt,
+            instance_id: instanceId,
+            token,
+        }),
+        "utf-8",
+    );
+    return portFile;
 }
 
 function readNewestPortRecord(storageDir: string, directory: string): RpcPortFileRecord | null {
@@ -79,8 +98,16 @@ async function waitFor(condition: () => boolean, label: string, timeoutMs = 2_00
     throw new Error(`Timed out waiting for ${label}`);
 }
 
-async function openSocket(port: number, token: string): Promise<WebSocket> {
-    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws?token=${encodeURIComponent(token)}`);
+async function openSocket(
+    port: number,
+    token: string,
+    legacyQueryAuth = false,
+): Promise<WebSocket> {
+    const ws = legacyQueryAuth
+        ? new WebSocket(`ws://127.0.0.1:${port}/ws?token=${encodeURIComponent(token)}`)
+        : new WebSocket(`ws://127.0.0.1:${port}/ws`, {
+              headers: { Authorization: `Bearer ${token}` },
+          });
     await new Promise<void>((resolve, reject) => {
         const timeout = setTimeout(() => reject(new Error("socket open timed out")), 2_000);
         ws.addEventListener(
@@ -129,11 +156,14 @@ function waitForJsonMessage<T extends { type?: string }>(
     });
 }
 
-async function startRpcServer(handler: (method: string) => Response | object): Promise<TestServer> {
+async function startRpcServer(
+    handler: (method: string) => Response | object,
+    health: { pid: number; instanceId?: string } = { pid: process.pid },
+): Promise<TestServer> {
     const server = createServer(async (req, res) => {
         if (req.method === "GET" && req.url === "/health") {
             res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ ok: true }));
+            res.end(JSON.stringify({ ok: true, pid: health.pid, instance_id: health.instanceId }));
             return;
         }
 
@@ -238,6 +268,31 @@ describe("MagicContextRpcClient", () => {
         }
     });
 
+    test("accepts a frozen v0.32 websocket upgrade with query-token auth", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo-ws-v032";
+        const server = new MagicContextRpcServer(storageDir, directory);
+        const port = await server.start();
+        const record = readNewestPortRecord(storageDir, directory);
+        expect(typeof record?.token).toBe("string");
+
+        const ws = await openSocket(port, record?.token ?? "", true);
+        try {
+            const helloAck = waitForJsonMessage(ws, (message) => message.type === "hello-ack");
+            ws.send(
+                JSON.stringify({
+                    type: "hello",
+                    token: record?.token,
+                    sessionId: "ses_v032",
+                }),
+            );
+            expect((await helloAck).type).toBe("hello-ack");
+        } finally {
+            ws.close();
+            server.stop();
+        }
+    });
+
     test("websocket upgrade rejects missing bearer token before a socket is created", async () => {
         const storageDir = makeTempDir();
         const directory = "/repo-ws-auth";
@@ -300,6 +355,52 @@ describe("MagicContextRpcClient", () => {
         }
     });
 
+    test("accepts legacy cursor acknowledgements during protocol skew", async () => {
+        __resetNotificationStateForTests();
+        const storageDir = makeTempDir();
+        const directory = "/repo-legacy-ack";
+        const server = new MagicContextRpcServer(storageDir, directory);
+        const port = await server.start();
+        const record = readNewestPortRecord(storageDir, directory);
+        expect(typeof record?.token).toBe("string");
+
+        pushNotification("legacy-one", { ok: true }, "ses_legacy");
+        pushNotification("legacy-two", { ok: true }, "ses_legacy");
+        const queued = drainNotifications(0, "ses_legacy", { sessionOnly: true });
+        expect(queued).toHaveLength(2);
+
+        const ws = await openSocket(port, record?.token ?? "");
+        try {
+            const helloAck = waitForJsonMessage<{
+                type?: string;
+                instanceId?: string;
+            }>(ws, (message) => message.type === "hello-ack");
+            ws.send(
+                JSON.stringify({
+                    type: "hello",
+                    token: record?.token,
+                    sessionId: "ses_legacy",
+                }),
+            );
+            expect((await helloAck).instanceId).toBe(record?.instance_id);
+
+            ws.send(
+                JSON.stringify({
+                    type: "ack",
+                    cursor: queued[0].id,
+                    sessionId: "ses_legacy",
+                }),
+            );
+            await waitFor(() => {
+                const pending = drainNotifications(0, "ses_legacy", { sessionOnly: true });
+                return pending.length === 1 && pending[0].id === queued[1].id;
+            }, "legacy cursor acknowledgement pruning");
+        } finally {
+            ws.close();
+            server.stop();
+        }
+    });
+
     test("same-process servers keep distinct port files during overlap", async () => {
         const storageDir = makeTempDir();
         const directory = "/repo-port-collision";
@@ -319,7 +420,9 @@ describe("MagicContextRpcClient", () => {
             expect(remaining?.port).toBe(secondPort);
 
             const client = new MagicContextRpcClient(storageDir, directory);
-            expect((await client.resolveEndpoint())?.port).toBe(secondPort);
+            const endpoint = await client.resolveEndpoint();
+            expect(endpoint?.port).toBe(secondPort);
+            expect(endpoint?.instanceId).toBe(remaining?.instance_id);
         } finally {
             first.stop();
             second.stop();
@@ -368,4 +471,105 @@ describe("MagicContextRpcClient", () => {
         const client = new MagicContextRpcClient(storageDir, directory);
         expect(await client.call<{ value: string }>("value")).toEqual({ value: "live" });
     });
+
+    test("discovers a frozen v0.32 health response without an instance id", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo-v032-health";
+        const legacy = await startRpcServer(() => ({ value: "legacy" }), {
+            pid: process.pid,
+        });
+        writePortFileForPid(
+            storageDir,
+            directory,
+            legacy.port,
+            process.pid,
+            Date.now(),
+            "new-client-record",
+        );
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "legacy" });
+    });
+
+    test("prefers this process and validates every discovery candidate identity", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo-affinity";
+        const foreign = await startRpcServer(() => ({ value: "foreign" }), {
+            pid: process.ppid,
+            instanceId: "foreign",
+        });
+        const unrelated = await startRpcServer(() => ({ value: "unrelated" }), {
+            pid: process.pid,
+            instanceId: "different-service",
+        });
+        const local = await startRpcServer(() => ({ value: "local" }), {
+            pid: process.pid,
+            instanceId: "local-healthy",
+        });
+
+        writePortFileForPid(
+            storageDir,
+            directory,
+            foreign.port,
+            process.ppid,
+            Date.now() + 20_000,
+            "foreign",
+        );
+        writePortFileForPid(
+            storageDir,
+            directory,
+            unrelated.port,
+            process.pid,
+            Date.now() + 10_000,
+            "local-stale",
+        );
+        writePortFileForPid(
+            storageDir,
+            directory,
+            local.port,
+            process.pid,
+            Date.now(),
+            "local-healthy",
+        );
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "local" });
+    });
+
+    test("resets discovery after a 401 response", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo-reauth";
+        let unauthorizedRecord = "";
+        const unauthorized = await startRpcServer(
+            () => {
+                rmSync(unauthorizedRecord, { force: true });
+                return new Response("stale token", { status: 401 });
+            },
+            { pid: process.pid, instanceId: "unauthorized" },
+        );
+        const healthy = await startRpcServer(() => ({ value: "healthy" }), {
+            pid: process.pid,
+            instanceId: "healthy",
+        });
+        unauthorizedRecord = writePortFileForPid(
+            storageDir,
+            directory,
+            unauthorized.port,
+            process.pid,
+            Date.now() + 10_000,
+            "unauthorized",
+            "stale",
+        );
+        writePortFileForPid(
+            storageDir,
+            directory,
+            healthy.port,
+            process.pid,
+            Date.now(),
+            "healthy",
+        );
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "healthy" });
+    });
 });

package/src/shared/rpc-client.ts

@@ -18,6 +18,7 @@ type NonRetryableRpcError = Error & { [NON_RETRYABLE_RPC_ERROR]: true };
 export class MagicContextRpcClient {
     private port: number | null = null;
     private token: string | null = null;
+    private instanceId: string | null = null;
     private portDir: string;
     private legacyPortFilePath: string;
     private healthChecked = false;
@@ -62,7 +63,7 @@ export class MagicContextRpcClient {
                 if (!response.ok) {
                     const text = await response.text();
                     const error = new Error(`RPC ${method} failed (${response.status}): ${text}`);
-                    if (response.status >= 500) {
+                    if (response.status === 401 || response.status >= 500) {
                         lastError = error;
                         this.reset();
                         continue;
@@ -101,52 +102,47 @@ export class MagicContextRpcClient {
      *  channel). Reuses the same health-checked port-file discovery as `call`,
      *  so the WS client and the HTTP client always agree on which server instance
      *  (and token) to use. Returns null when no live server is found. */
-    async resolveEndpoint(): Promise<{ port: number; token: string | null } | null> {
+    async resolveEndpoint(): Promise<{
+        port: number;
+        token: string | null;
+        instanceId: string | null;
+    } | null> {
         try {
-            const port = await this.resolvePort();
+            // The socket owns reconnect backoff, so endpoint discovery performs one
+            // filesystem/health pass instead of nesting the HTTP client's retries.
+            const port = await this.resolvePort(1);
             if (port === null) return null;
-            return { port, token: this.token };
+            return { port, token: this.token, instanceId: this.instanceId };
         } catch {
             return null;
         }
     }
 
-    private async resolvePort(): Promise<number | null> {
+    private async resolvePort(maxAttempts = MAX_RETRIES): Promise<number | null> {
         if (this.port && this.healthChecked) {
             return this.port;
         }
 
-        if (this.port) {
-            const alive = await this.healthCheck(this.port);
-            if (alive) {
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            for (const record of this.readPortFiles()) {
+                if (!(await this.healthCheck(record))) continue;
+                this.port = record.port;
+                this.token = record.token ?? null;
+                this.instanceId = record.instance_id ?? null;
                 this.healthChecked = true;
-                return this.port;
-            }
-            this.port = null;
-            this.healthChecked = false;
-        }
-
-        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-            const record = this.readPortFile();
-            if (record) {
-                const alive = await this.healthCheck(record.port);
-                if (alive) {
-                    this.port = record.port;
-                    this.token = record.token ?? null;
-                    this.healthChecked = true;
-                    return record.port;
-                }
+                return record.port;
             }
 
-            if (attempt < MAX_RETRIES - 1) {
-                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+            this.reset();
+            if (attempt < maxAttempts - 1) {
+                await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
             }
         }
 
         return null;
     }
 
-    private readPortFile(): RpcPortFileRecord | null {
+    private readPortFiles(): RpcPortFileRecord[] {
         const records: RpcPortFileRecord[] = [];
 
         try {
@@ -160,26 +156,38 @@ export class MagicContextRpcClient {
             // Directory may not exist yet. Fall back to the legacy file below.
         }
 
-        if (records.length > 0) {
-            records.sort((a, b) => b.started_at - a.started_at);
-            return records[0];
-        }
-
         try {
-            const record = parseRpcPortFile(readFileSync(this.legacyPortFilePath, "utf-8"));
-            if (record?.pid && !isPidAlive(record.pid)) return null;
-            return record;
+            const legacy = parseRpcPortFile(readFileSync(this.legacyPortFilePath, "utf-8"));
+            if (legacy && (!legacy.pid || isPidAlive(legacy.pid))) records.push(legacy);
         } catch {
-            return null;
+            // Legacy discovery is optional.
         }
+
+        // A TUI and its server plugin normally share a process. Prefer that exact
+        // process before considering another live OpenCode instance for the project.
+        records.sort((a, b) => {
+            const aLocal = a.pid === process.pid ? 1 : 0;
+            const bLocal = b.pid === process.pid ? 1 : 0;
+            return bLocal - aLocal || b.started_at - a.started_at;
+        });
+        return records;
     }
 
-    private async healthCheck(port: number): Promise<boolean> {
+    private async healthCheck(record: RpcPortFileRecord): Promise<boolean> {
         try {
-            const response = await this.fetchWithTimeout(`http://127.0.0.1:${port}/health`, {
+            const response = await this.fetchWithTimeout(`http://127.0.0.1:${record.port}/health`, {
                 method: "GET",
             });
-            return response.ok;
+            if (!response.ok) return false;
+            const body = (await response.json()) as { pid?: unknown; instance_id?: unknown };
+            if (body.pid !== record.pid) return false;
+            // v0.32 health responses predate instance ids. A missing id is the
+            // one-release discovery bridge; an id that is present must still match.
+            return (
+                body.instance_id === undefined ||
+                record.instance_id === undefined ||
+                body.instance_id === record.instance_id
+            );
         } catch {
             return false;
         }
@@ -198,6 +206,7 @@ export class MagicContextRpcClient {
     reset(): void {
         this.port = null;
         this.token = null;
+        this.instanceId = null;
         this.healthChecked = false;
     }
 }

package/src/shared/rpc-notifications.test.ts

@@ -70,10 +70,25 @@ describe("rpc notifications", () => {
         expect(isTuiConnected()).toBe(false);
     });
 
-    test("a session-less sink counts as connected for any session query", () => {
+    test("a modern session-less sink is global-only", () => {
+        const received: string[] = [];
+        const unregister = registerNotificationSink({
+            sessionId: undefined,
+            protocol: 2,
+            send: (notification) => received.push(notification.type),
+        });
+        expect(isTuiConnected("ses_whatever")).toBe(false);
+        expect(isTuiConnected()).toBe(true);
+
+        pushNotification("scoped", { ok: true }, "ses_whatever");
+        pushNotification("global", { ok: true });
+        expect(received).toEqual(["global"]);
+        unregister();
+    });
+
+    test("a legacy session-less sink retains broad compatibility", () => {
         const unregister = registerNotificationSink({ sessionId: undefined, send: () => {} });
         expect(isTuiConnected("ses_whatever")).toBe(true);
-        expect(isTuiConnected()).toBe(true);
         unregister();
     });
 
@@ -117,14 +132,20 @@ describe("rpc notifications", () => {
 
     test("queue-cap eviction is session-fair: a noisy session cannot evict another session's newest unseen item", () => {
         drainNotifications(Number.MAX_SAFE_INTEGER);
-        // One quiet session with a single pending dialog.
         pushNotification("quiet-dialog", { action: "show-upgrade-dialog" }, "ses_quiet");
-        // A noisy session floods well past the 100 cap.
         for (let i = 0; i < 200; i += 1) {
             pushNotification("noise", { i }, "ses_noisy");
         }
-        // The quiet session's newest item must survive the eviction.
         const quietPoll = drainNotifications(0, "ses_quiet");
         expect(quietPoll.some((m) => m.type === "quiet-dialog")).toBe(true);
+        expect(drainNotifications(0)).toHaveLength(100);
+    });
+
+    test("queue cap remains global across more than one hundred sessions", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        for (let i = 0; i < 250; i += 1) {
+            pushNotification("one-per-session", { i }, `ses_${i}`);
+        }
+        expect(drainNotifications(0)).toHaveLength(100);
     });
 });

package/src/shared/rpc-notifications.ts

@@ -26,6 +26,8 @@ let nextNotificationId = 1;
 export interface NotificationSink {
     /** The TUI's active session at connect time (its hello scope). */
     sessionId?: string;
+    /** Protocol 2 clients use strict session scoping; absent means legacy behavior. */
+    protocol?: number;
     /** Deliver one notification over this sink's live socket. */
     send: (notification: RpcNotification) => void;
 }
@@ -48,23 +50,19 @@ export function registerNotificationSink(sink: NotificationSink): () => void {
     };
 }
 
-/** Whether a given notification may be delivered to a given sink. A global
- *  notification (no sessionId) reaches every sink; a session-scoped one reaches
- *  only sinks for that session (or session-less sinks). Mirrors the drain filter
- *  from the sink's perspective. */
+/** Whether a notification may be delivered to a sink. Protocol 2 makes a
+ * session-less socket global-only; legacy sockets retain broad compatibility. */
 function notificationMatchesSink(notification: RpcNotification, sink: NotificationSink): boolean {
-    return (
-        notification.sessionId === undefined ||
-        sink.sessionId === undefined ||
-        notification.sessionId === sink.sessionId
-    );
+    if (notification.sessionId === undefined) return true;
+    if (sink.sessionId !== undefined) return notification.sessionId === sink.sessionId;
+    return sink.protocol !== 2;
 }
 
 /** Push a notification to the TUI. Fans out to any live WS sink immediately and
  *  also enqueues it so a TUI that is momentarily disconnected (reconnecting, or
  *  not yet connected) still receives it on its next hello via the backlog drain.
  *  At-least-once: a live push that the socket drops is re-delivered from the
- *  queue on reconnect (pruned only when the client acks via `lastReceivedId`). */
+ *  queue on reconnect (pruned only when the client acknowledges it). */
 export function pushNotification(
     type: string,
     payload: Record<string, unknown>,
@@ -83,30 +81,40 @@ export function pushNotification(
             // unregister it, and the queue backlog re-delivers on reconnect.
         }
     }
-    // Cap queue size to prevent unbounded growth if a TUI is not draining.
-    // Session-FAIR eviction: a naive `slice(-50)` drops the globally-oldest
-    // items, so a noisy session could evict ANOTHER session's single unseen
-    // notification. Instead, always retain each session's newest item, then
-    // fill the rest of the budget with the newest overall — no session can
-    // starve another's pending dialog out of the window.
+    // Keep a strict global bound. Reserve the newest item for at most 25 recently
+    // active scopes, then evict the oldest unreserved item. This protects a quiet
+    // session from one noisy peer without allowing one item per session to grow
+    // the queue without limit.
     if (queue.length > 100) {
-        const newestPerSession = new Map<string | undefined, number>();
-        for (const n of queue) {
-            const prev = newestPerSession.get(n.sessionId);
-            if (prev === undefined || n.id > prev) {
-                newestPerSession.set(n.sessionId, n.id);
-            }
+        const reservedIds = new Set<number>();
+        const reservedScopes = new Set<string>();
+        for (let i = queue.length - 1; i >= 0 && reservedScopes.size < 25; i -= 1) {
+            const candidate = queue[i];
+            const scope = candidate.sessionId ?? "\0global";
+            if (reservedScopes.has(scope)) continue;
+            reservedScopes.add(scope);
+            reservedIds.add(candidate.id);
         }
-        const mustKeep = new Set(newestPerSession.values());
-        const byNewest = [...queue].sort((a, b) => b.id - a.id);
-        const kept: RpcNotification[] = [];
-        for (const n of byNewest) {
-            if (kept.length < 50 || mustKeep.has(n.id)) kept.push(n);
-        }
-        queue = kept.sort((a, b) => a.id - b.id);
+        const evictionIndex = queue.findIndex((candidate) => !reservedIds.has(candidate.id));
+        queue.splice(evictionIndex >= 0 ? evictionIndex : 0, 1);
     }
 }
 
+export function acknowledgeNotifications(ids: readonly number[]): void {
+    const acknowledged = new Set(ids.filter((id) => Number.isSafeInteger(id) && id > 0));
+    if (acknowledged.size === 0) return;
+    // Exact removal preserves an earlier notification when a later handler finishes
+    // first or the earlier handler declines to consume its notification.
+    queue = queue.filter((notification) => !acknowledged.has(notification.id));
+}
+
+/** Reset process-local state to simulate a fresh server module in protocol tests. */
+export function __resetNotificationStateForTests(): void {
+    queue = [];
+    nextNotificationId = 1;
+    sinks.clear();
+}
+
 export interface DrainNotificationsOptions {
     /**
      * Cursor for global notifications when a session-scoped client sends separate
@@ -133,8 +141,8 @@ function cursor(value: number | undefined): number {
  *  behavior.
  *
  *  Delivery is at-least-once (non-destructive return + prune-on-ack): a returned
- *  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. */
+ *  notification stays queued until an exact acknowledgement or a legacy cursor
+ *  removes it, so a dropped WS socket re-delivers unhandled backlog on reconnect. */
 export function drainNotifications(
     lastReceivedId = 0,
     sessionId?: string,
@@ -200,14 +208,15 @@ export function drainNotifications(
  *  Pass `sessionId` (preferred) to ask whether a TUI is connected FOR THAT
  *  SESSION — this is what producers (`/ctx-status`, `/ctx-recomp`, the upgrade
  *  reminder) must use to decide dialog-vs-message, so a TUI on a different
- *  session in the same process does not misroute their delivery. A session-less
- *  sink (legacy/global) counts for any session query. Omit `sessionId` only for
- *  callers with no session context; they get "any sink connected". */
+ *  session in the same process does not misroute their delivery. A modern
+ *  session-less sink is global-only; a legacy sink retains broad compatibility.
+ *  Omit `sessionId` only for callers with no session context. */
 export function isTuiConnected(sessionId?: string): boolean {
     if (sinks.size === 0) return false;
     if (sessionId === undefined) return true;
     for (const sink of sinks) {
-        if (sink.sessionId === undefined || sink.sessionId === sessionId) return true;
+        if (sink.sessionId === sessionId) return true;
+        if (sink.sessionId === undefined && sink.protocol !== 2) return true;
     }
     return false;
 }