@sjawhar/opencode-legion-envoy 0.1.9 → 0.2.0

package/AGENTS.md

@@ -12,10 +12,11 @@ It is the user-facing bridge between OpenCode sessions and Envoy transport.
 
 | Task                | Location               | Notes                                                              |
 | ------------------- | ---------------------- | ------------------------------------------------------------------ |
-| Tool definitions    | `src/index.ts`         | `envoy_subscribe`, `envoy_unsubscribe`, `envoy_list`, `envoy_send`, `envoy_publish`, `envoy_role_set`, `envoy_whoami`, `envoy_sessions` |
+| Tool definitions    | `src/server.ts`        | `envoy_subscribe`, `envoy_unsubscribe`, `envoy_list`, `envoy_send`, `envoy_publish`, `envoy_role_set`, `envoy_whoami`, `envoy_sessions` |
 | Packaging metadata  | `package.json`         | npm identity, build scripts                                        |
-| Distribution output | `dist/index.js`        | built plugin consumed by OpenCode                                  |
+| Distribution output | `dist/server.js`       | built plugin consumed by OpenCode                                  |
 | Host rollout helper | `scripts/sync-host.sh` | sync dist + shim to remote host                                    |
+| Dispatch MCP + auto-subscribe | `src/dispatch-mcp.ts`, `src/dispatch-subscribe.ts` | injects the dispatch MCP server (shim); `tool.execute.after` auto-subscribes the caller to the new thread's topic so answers route back (Dispatch AC#4) |
 
 ## Critical conventions
 

package/bin/dispatch-mcp-shim.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+// envoy-plugin local MCP shim.
+//
+// Spawned by OpenCode as a `type: "local"` MCP transport. Reads JSON-RPC
+// messages from stdin (newline-delimited), forwards each to the remote
+// dispatch server's Streamable HTTP /mcp endpoint with a fresh GitHub
+// bearer minted via the user's `gh` shim, and writes responses to stdout.
+//
+// Token rotation is invisible to OpenCode — the shim handles 50-minute
+// refresh cycles + immediate retry on 401. This avoids the "MCP dies
+// after 1 hour" failure mode of static-header configurations.
+
+import * as readline from "node:readline";
+import {
+  createBridge,
+  defaultGhTokenGetter,
+  type JsonRpcRequest,
+} from "../src/dispatch-mcp-bridge";
+
+const remoteUrl = process.env.DISPATCH_MCP_URL;
+if (!remoteUrl) {
+  process.stderr.write("envoy-dispatch shim: DISPATCH_MCP_URL is required\n");
+  process.exit(1);
+}
+
+const bridge = createBridge({
+  remoteUrl,
+  getToken: defaultGhTokenGetter,
+});
+
+const rl = readline.createInterface({ input: process.stdin });
+
+let inflight = 0;
+let closed = false;
+
+// Serialize incoming requests. MCP requires the initialize handshake to
+// complete before any tool calls are processed; running rl.on("line")
+// callbacks in parallel would race tools/call against initialize and hit
+// `invalid during session initialization` from the server. Even after
+// init, sequencing keeps the wire ordering deterministic, which is what
+// OpenCode expects for stdio MCP transports.
+let chain: Promise<void> = Promise.resolve();
+
+function maybeExit(): void {
+  if (closed && inflight === 0) process.exit(0);
+}
+
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  inflight++;
+  chain = chain.then(async () => {
+    try {
+      const request = JSON.parse(trimmed) as JsonRpcRequest;
+      const response = await bridge.handle(request);
+      if (response !== null) {
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`envoy-dispatch shim: ${msg}\n`);
+    } finally {
+      inflight--;
+      maybeExit();
+    }
+  });
+});
+
+rl.on("close", () => {
+  closed = true;
+  maybeExit();
+});
+
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));

package/package.json

@@ -1,25 +1,38 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "src/server.ts",
+  "exports": {
+    "./server": {
+      "import": "./src/server.ts"
+    },
+    "./tui": {
+      "import": "./dist/tui.js",
+      "types": "./dist/tui.d.ts"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/sjawhar/legion"
   },
-  "types": "dist/index.d.ts",
+  "types": "src/server.ts",
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --format esm",
+    "build": "bun -e 'import { createSolidTransformPlugin } from \"@opentui/solid/bun-plugin\"; const result = await Bun.build({ entrypoints: [\"src/tui.tsx\"], outdir: \"dist\", target: \"bun\", format: \"esm\", external: [\"@opencode-ai/*\", \"solid-js\", \"solid-js/*\", \"@opentui/*\"], plugins: [createSolidTransformPlugin()] }); if (!result.success) { console.error(result.logs); process.exit(1); }'",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
     "lint": "bunx biome check src/"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.1.19"
+    "@opencode-ai/plugin": "~1.14.46"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
+    "@opentui/core": "^0.2.6",
+    "@opentui/keymap": "^0.2.6",
+    "@opentui/solid": "^0.2.6",
     "@types/bun": "latest",
+    "solid-js": "^1.9.0",
     "typescript": "^5.3.0"
   }
 }

package/scripts/sync-host.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 host="${1:?usage: sync-host.sh user@host}"
 
 PLUGIN_DIR="legion/default/packages/envoy-plugin"
-PLUGIN_REF="file://{env:HOME}/${PLUGIN_DIR}/dist/index.js"
+PLUGIN_REF="file://{env:HOME}/${PLUGIN_DIR}"
 REPO="sjawhar/legion"
 
 # Find latest envoy release tag
@@ -53,4 +53,21 @@ ssh "$host" "
   fi
 "
 
+# Update tui.json: ensure file:// ref is present in the TUI plugin list.
+# tui.json is a separate config file from opencode.json; opencode loads TUI
+# plugins (slash commands, sidebar slots) only from here.
+ssh "$host" "
+  TUI_CONFIG=\$(readlink -f \$HOME/.config/opencode/tui.json 2>/dev/null || echo \$HOME/.config/opencode/tui.json)
+  if [ -f \"\$TUI_CONFIG\" ]; then
+    jq --arg ref '$PLUGIN_REF' \\
+      '(.plugin // []) |= ((map(if (test(\"opencode-legion-envoy\") and (test(\"^file://\") | not)) then \$ref else . end)) | if any(. == \$ref) then . else . + [\$ref] end)' \\
+      \"\$TUI_CONFIG\" > /tmp/tui.json.tmp && mv /tmp/tui.json.tmp \"\$TUI_CONFIG\"
+    echo \"Updated tui.json: \$TUI_CONFIG\"
+  else
+    mkdir -p \$(dirname \"\$TUI_CONFIG\")
+    jq -n --arg ref '$PLUGIN_REF' '{\"\\\$schema\":\"https://opencode.ai/tui.json\",\"plugin\":[\$ref]}' > \"\$TUI_CONFIG\"
+    echo \"Created tui.json: \$TUI_CONFIG\"
+  fi
+"
+
 echo "Done: $host envoy-plugin synced from release $tag"

package/src/__tests__/clipboard.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, mock } from "bun:test";
+import { copyNative, copyToClipboard } from "../clipboard";
+
+describe("copyToClipboard", () => {
+  it("copies via the renderer OSC 52 writer and does not fall back when it succeeds", () => {
+    const copyToClipboardOSC52 = mock((_text: string) => true);
+    const ok = copyToClipboard("ses_abc", { copyToClipboardOSC52 });
+    expect(ok).toBe(true);
+    expect(copyToClipboardOSC52).toHaveBeenCalledWith("ses_abc");
+  });
+});
+
+describe("copyNative", () => {
+  it("uses wl-copy on Linux/Wayland when available", () => {
+    const run = mock((_cmd: string, _args: string[], _text: string) => true);
+    const ok = copyNative("ses_abc", {
+      os: "linux",
+      env: { WAYLAND_DISPLAY: "wayland-0" },
+      which: (cmd) => cmd === "wl-copy",
+      run,
+    });
+    expect(ok).toBe(true);
+    expect(run).toHaveBeenCalledWith("wl-copy", [], "ses_abc");
+  });
+
+  it("falls back to xclip on Linux/X11", () => {
+    const run = mock((_cmd: string, _args: string[], _text: string) => true);
+    const ok = copyNative("ses_abc", {
+      os: "linux",
+      env: {},
+      which: (cmd) => cmd === "xclip",
+      run,
+    });
+    expect(ok).toBe(true);
+    expect(run).toHaveBeenCalledWith("xclip", ["-selection", "clipboard"], "ses_abc");
+  });
+
+  it("falls back to xsel when xclip is missing", () => {
+    const run = mock((_cmd: string, _args: string[], _text: string) => true);
+    copyNative("x", { os: "linux", env: {}, which: (cmd) => cmd === "xsel", run });
+    expect(run).toHaveBeenCalledWith("xsel", ["--clipboard", "--input"], "x");
+  });
+
+  it("uses osascript on macOS with escaped quotes", () => {
+    const run = mock((_cmd: string, _args: string[], _text: string) => true);
+    copyNative('a"b\\c', { os: "darwin", which: () => true, run });
+    expect(run).toHaveBeenCalledWith("osascript", ["-e", 'set the clipboard to "a\\"b\\\\c"'], "");
+  });
+
+  it("returns false on Linux when no clipboard tool is installed", () => {
+    const run = mock(() => true);
+    const ok = copyNative("x", { os: "linux", env: {}, which: () => false, run });
+    expect(ok).toBe(false);
+    expect(run).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/dispatch-mcp-bridge.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createBridge, type JsonRpcRequest } from "../dispatch-mcp-bridge";
+
+interface MockResponse {
+  status: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  contentType?: string;
+  body: string;
+}
+
+function fakeFetch(responses: MockResponse[]) {
+  let idx = 0;
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = (url: string, init?: RequestInit) => {
+    calls.push({ url, init: init ?? {} });
+    const next = responses[idx++];
+    if (!next) throw new Error(`no mock response for call #${idx}`);
+    const headers = new Headers({
+      "content-type": next.contentType ?? "application/json",
+      ...(next.headers ?? {}),
+    });
+    return Promise.resolve(
+      new Response(next.body, {
+        status: next.status,
+        statusText: next.statusText ?? "",
+        headers,
+      })
+    );
+  };
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+function sseEnvelope(payload: object): string {
+  return `event: message\ndata: ${JSON.stringify(payload)}\n\n`;
+}
+
+describe("dispatch-mcp-bridge", () => {
+  it("forwards a request with a fresh bearer and returns the parsed SSE response", async () => {
+    const f = fakeFetch([
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        headers: { "mcp-session-id": "S1" },
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: { ok: true } }),
+      },
+    ]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => "tok-A",
+      fetchImpl: f.impl,
+    });
+
+    const req: JsonRpcRequest = { jsonrpc: "2.0", id: 1, method: "tools/list" };
+    const res = await bridge.handle(req);
+
+    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: { ok: true } });
+    expect(f.calls).toHaveLength(1);
+    expect((f.calls[0]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-A");
+  });
+
+  it("reuses the cached token on a follow-up request and reuses the session id", async () => {
+    let tokenCalls = 0;
+    const f = fakeFetch([
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        headers: { "mcp-session-id": "S2" },
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: { phase: "init" } }),
+      },
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 2, result: { phase: "list" } }),
+      },
+    ]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => {
+        tokenCalls++;
+        return "tok-cached";
+      },
+      fetchImpl: f.impl,
+    });
+
+    await bridge.handle({ jsonrpc: "2.0", id: 1, method: "initialize" });
+    await bridge.handle({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+
+    expect(tokenCalls).toBe(1);
+    expect((f.calls[1]?.init.headers as Record<string, string>)["Mcp-Session-Id"]).toBe("S2");
+  });
+
+  it("refreshes the token after the cache TTL elapses", async () => {
+    const responses: MockResponse[] = [
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: 1 }),
+      },
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 2, result: 2 }),
+      },
+    ];
+    const f = fakeFetch(responses);
+    let issued = 0;
+    let clock = 1000;
+
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => `tok-${++issued}`,
+      fetchImpl: f.impl,
+      tokenCacheTtlMs: 60_000,
+      now: () => clock,
+    });
+
+    await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
+    clock += 120_000; // beyond TTL
+    await bridge.handle({ jsonrpc: "2.0", id: 2, method: "x" });
+
+    expect(issued).toBe(2);
+    expect((f.calls[0]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-1");
+    expect((f.calls[1]?.init.headers as Record<string, string>).Authorization).toBe("Bearer tok-2");
+  });
+
+  it("retries once on 401 with a forced token refresh", async () => {
+    const f = fakeFetch([
+      { status: 401, body: "unauthorized" },
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
+      },
+    ]);
+    let issued = 0;
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => `tok-${++issued}`,
+      fetchImpl: f.impl,
+      logError: () => {},
+    });
+
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
+    expect(issued).toBe(2); // first attempt cached tok-1, retry forced tok-2
+    expect(f.calls).toHaveLength(2);
+  });
+
+  it("retries when remote returns HTTP 200 but tool result reports upstream 401", async () => {
+    const f = fakeFetch([
+      {
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          result: {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "search issues: GET https://api.github.com/search/issues?q=x: 401 Bad credentials []",
+              },
+            ],
+          },
+        }),
+      },
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
+      },
+    ]);
+    let issued = 0;
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => `tok-${++issued}`,
+      fetchImpl: f.impl,
+      logError: () => {},
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/call" });
+    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
+    expect(issued).toBe(2);
+    expect(f.calls).toHaveLength(2);
+  });
+
+  it("retries when remote returns a JSON-RPC error whose message reports upstream 401", async () => {
+    const f = fakeFetch([
+      {
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          error: { code: -32603, message: "search issues: 401 Bad credentials" },
+        }),
+      },
+      {
+        status: 200,
+        contentType: "text/event-stream",
+        body: sseEnvelope({ jsonrpc: "2.0", id: 1, result: "after-refresh" }),
+      },
+    ]);
+    let issued = 0;
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => `tok-${++issued}`,
+      fetchImpl: f.impl,
+      logError: () => {},
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/call" });
+    expect(res).toEqual({ jsonrpc: "2.0", id: 1, result: "after-refresh" });
+    expect(issued).toBe(2);
+  });
+
+  it("returns a JSON-RPC error when the token getter yields null", async () => {
+    const f = fakeFetch([]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => null,
+      fetchImpl: f.impl,
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 7, method: "tools/call" });
+    expect(res?.error?.code).toBe(-32000);
+    expect(res?.error?.message).toContain("gh auth token");
+    expect(f.calls).toHaveLength(0);
+  });
+
+  it("returns null for notifications (no id) and still forwards them", async () => {
+    const f = fakeFetch([{ status: 200, contentType: "application/json", body: "{}" }]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => "tok",
+      fetchImpl: f.impl,
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", method: "notifications/initialized" });
+    expect(res).toBeNull();
+    expect(f.calls).toHaveLength(1);
+  });
+
+  it("returns a JSON-RPC error on remote non-200 status", async () => {
+    const f = fakeFetch([{ status: 503, statusText: "Service Unavailable", body: "down" }]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => "tok",
+      fetchImpl: f.impl,
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
+    expect(res?.error?.code).toBe(-32603);
+    expect(res?.error?.message).toContain("503");
+  });
+
+  it("returns a JSON-RPC error when fetch throws", async () => {
+    const erroringFetch = mock(async () => {
+      throw new Error("ECONNREFUSED");
+    });
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => "tok",
+      fetchImpl: erroringFetch as unknown as typeof fetch,
+    });
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "x" });
+    expect(res?.error?.code).toBe(-32603);
+    expect(res?.error?.message).toContain("ECONNREFUSED");
+  });
+
+  it("normalizes union-type-null arrays in tools/list inputSchema so Gemini accepts them", async () => {
+    // Mirrors the real EnvoyDispatch schema the remote server emits: nullable arrays
+    // expressed as JSON-Schema union types { type: ["null", "array"] }, which Gemini rejects
+    // (array branch lacks items / orphaned items). The bridge must collapse these in transit.
+    const toolsList = {
+      jsonrpc: "2.0",
+      id: 1,
+      result: {
+        tools: [
+          {
+            name: "envoy_dispatch",
+            description: "Create a Dispatch thread",
+            inputSchema: {
+              type: "object",
+              required: ["parent", "subject", "body"],
+              properties: {
+                parent: { type: "string" },
+                ask: {
+                  type: ["null", "array"],
+                  items: {
+                    type: "object",
+                    required: ["question", "options"],
+                    properties: {
+                      question: { type: "string" },
+                      custom: { type: ["null", "boolean"] },
+                      options: {
+                        type: ["null", "array"],
+                        items: {
+                          type: "object",
+                          required: ["label"],
+                          properties: { label: { type: "string" } },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        ],
+      },
+    };
+    const f = fakeFetch([
+      { status: 200, contentType: "application/json", body: JSON.stringify(toolsList) },
+    ]);
+    const bridge = createBridge({
+      remoteUrl: "http://example/mcp",
+      getToken: async () => "tok",
+      fetchImpl: f.impl,
+    });
+
+    const res = await bridge.handle({ jsonrpc: "2.0", id: 1, method: "tools/list" });
+    type SchemaNode = {
+      type?: unknown;
+      items?: SchemaNode;
+      properties?: Record<string, SchemaNode>;
+    };
+    const result = res?.result as { tools: Array<{ inputSchema: SchemaNode }> };
+    const ask = result.tools[0]?.inputSchema.properties?.ask;
+
+    // Nullable array collapses to a single-type array with items preserved.
+    expect(ask?.type).toBe("array");
+    expect(ask?.items).toBeDefined();
+    // Nested nullable array (options) collapses too.
+    expect(ask?.items?.properties?.options.type).toBe("array");
+    expect(ask?.items?.properties?.options.items).toBeDefined();
+    // Nullable boolean collapses to a single-type boolean.
+    expect(ask?.items?.properties?.custom.type).toBe("boolean");
+    // Nothing in the schema still uses a union type array (the shape Gemini rejects).
+    expect(JSON.stringify(res)).not.toContain('["null"');
+  });
+});

package/src/__tests__/dispatch-mcp.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "bun:test";
+import { buildDispatchMcpEntry, injectEnvoyMcp } from "../dispatch-mcp";
+
+describe("buildDispatchMcpEntry", () => {
+  it("returns null when dispatch is undefined", () => {
+    const result = buildDispatchMcpEntry({ dispatch: undefined });
+    expect(result).toBeNull();
+  });
+
+  it("returns null when dispatch.enabled is false", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: false, serverUrl: "http://example:8766" },
+    });
+    expect(result).toBeNull();
+  });
+
+  it("builds a local MCP entry pointing at the shim with serverUrl in env", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: {
+        enabled: true,
+        serverUrl: "http://sami-agents-mx:8766",
+      },
+      shimPath: "/path/to/shim.ts",
+      runtime: "bun",
+    });
+    expect(result).toEqual({
+      type: "local",
+      command: ["bun", "/path/to/shim.ts"],
+      environment: {
+        DISPATCH_MCP_URL: "http://sami-agents-mx:8766/mcp",
+      },
+      enabled: true,
+    });
+  });
+
+  it("falls back to localhost:8766 when serverUrl is omitted", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: true },
+      shimPath: "/shim.ts",
+    });
+    expect(result?.environment.DISPATCH_MCP_URL).toBe("http://localhost:8766/mcp");
+  });
+
+  it("strips trailing slashes from serverUrl before appending /mcp", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: true, serverUrl: "http://example:8766//" },
+      shimPath: "/shim.ts",
+    });
+    expect(result?.environment.DISPATCH_MCP_URL).toBe("http://example:8766/mcp");
+  });
+
+  it("uses bun as the default runtime", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: true },
+      shimPath: "/shim.ts",
+    });
+    expect(result?.command[0]).toBe("bun");
+  });
+
+  it("uses the provided runtime override", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: true },
+      shimPath: "/shim.ts",
+      runtime: "node",
+    });
+    expect(result?.command[0]).toBe("node");
+  });
+
+  it("default shim path resolves to bin/dispatch-mcp-shim.ts in the package root", () => {
+    const result = buildDispatchMcpEntry({
+      dispatch: { enabled: true },
+    });
+    expect(result?.command[1]).toContain("bin/dispatch-mcp-shim.ts");
+  });
+});
+
+describe("injectEnvoyMcp", () => {
+  const entry = {
+    type: "local" as const,
+    command: ["bun", "/shim.ts"],
+    environment: { DISPATCH_MCP_URL: "http://test:8766/mcp" },
+    enabled: true as const,
+  };
+
+  it("adds the entry to a cfg that has no mcp block yet", () => {
+    const cfg: { mcp?: Record<string, unknown> } = {};
+    const result = injectEnvoyMcp(cfg, entry);
+    expect(result.warning).toBeUndefined();
+    expect(cfg.mcp?.envoy).toEqual(entry);
+  });
+
+  it("is idempotent on its own re-write — second call does not warn", () => {
+    const cfg: { mcp?: Record<string, unknown> } = {};
+    injectEnvoyMcp(cfg, entry);
+    const second = injectEnvoyMcp(cfg, entry);
+    // No warning when the existing entry already equals what we'd inject.
+    // This is the common case after InstanceState invalidation re-runs the
+    // config hook against a Config-service cfg that still has our prior
+    // mutation — silent no-op, not a TUI stderr alarm.
+    expect(second.warning).toBeUndefined();
+    expect(cfg.mcp?.envoy).toEqual(entry);
+  });
+
+  it("warns and preserves the existing entry when it differs from ours", () => {
+    const userOverride = {
+      type: "local" as const,
+      command: ["node", "/custom-shim.js"],
+      environment: { DISPATCH_MCP_URL: "http://other:9999/mcp" },
+      enabled: true as const,
+    };
+    const cfg: { mcp?: Record<string, unknown> } = { mcp: { envoy: userOverride } };
+    const result = injectEnvoyMcp(cfg, entry);
+    expect(result.warning).toContain("already present");
+    expect(cfg.mcp?.envoy).toEqual(userOverride);
+  });
+});