minecodex 0.1.4 → 0.1.6

package/README.md

@@ -19,9 +19,11 @@ mcx install
 
 `mcx install` 不会关闭或启动 Codex，也不会改变当前窗口。安装完成后，终端会提示
 MineCodex 将在下次重启 Codex 时启用，并询问是否现在重启；默认答案是 **No**。
-只有用户明确确认，或之后主动运行 `mcx restart`，MineCodex 才会关闭并重新打开
-Codex。安装后，macOS 的“登录项与扩展”中会显示名为 **MineCodex** 的后台项目；
-这个后台项目负责插件与本地控制台，不会在用户退出 Codex 后自动将它重新打开。
+安装过程只有在用户明确确认，或之后主动运行 `mcx restart` 时，才会关闭并重新打开
+Codex。安装后，macOS 的“登录项与扩展”中会显示名为 **MineCodex** 的后台项目。
+这个后台项目负责插件与本地控制台：用户退出 Codex 后，它会保持停止；用户后来从
+Dock 主动打开 Codex 时，这次新启动会被视为明确的启动意图，并切换为可注入的托管
+实例。由于普通 Dock 启动本身没有 CDP，首次切换时 Codex 可能会短暂重开一次。
 
 安装后三个插件默认开启。打开本地控制台：
 

package/features/images/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "images",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "label": {
     "en": "Images",
     "zh-CN": "图片"

package/features/images/src/http-server.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { saveImageAs } from "./save-as.mjs";
 
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const CODEX_EMBED_ORIGIN = "app://-";
 const DEFAULT_PAGE_LIMIT = 36;
 const MAX_PAGE_LIMIT = 72;
 const MAX_PAGE_OFFSET = Number.MAX_SAFE_INTEGER;
@@ -69,6 +70,16 @@ function mutationError(message, code) {
   return Object.assign(new Error(message), { status: 403, code });
 }
 
+function applyCodexEmbedCors(request, response) {
+  if (request.headers.origin !== CODEX_EMBED_ORIGIN) return false;
+  response.setHeader("Access-Control-Allow-Origin", CODEX_EMBED_ORIGIN);
+  response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, POST, OPTIONS");
+  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  response.setHeader("Access-Control-Allow-Private-Network", "true");
+  response.setHeader("Vary", "Origin");
+  return true;
+}
+
 function parseIntegerQuery(searchParams, name, { defaultValue, min, max }) {
   const values = searchParams.getAll(name);
   if (values.length === 0) return defaultValue;
@@ -115,6 +126,7 @@ function validateMutationOrigin(request, address, host) {
   if (!origin) {
     throw mutationError("Mutation requests require the exact bound loopback Origin", "ORIGIN_NOT_ALLOWED");
   }
+  if (origin === CODEX_EMBED_ORIGIN) return;
   let parsed;
   try {
     parsed = new URL(origin);
@@ -137,13 +149,20 @@ export async function createHttpServer({
   if (!LOOPBACK_HOSTS.has(host)) throw new Error("Images only supports loopback hosts");
   const server = createNodeServer(async (request, response) => {
     try {
+      applyCodexEmbedCors(request, response);
       const address = server.address();
       const boundOrigin = address && typeof address !== "string"
         ? `http://${formatHost(host)}:${address.port}`
         : `http://${formatHost(host)}:${port}`;
       const url = new URL(request.url ?? "/", boundOrigin);
 
-      if (!["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+      if (request.method === "OPTIONS") {
+        response.writeHead(204, { "Cache-Control": "no-store" });
+        response.end();
+        return;
+      }
+
+      if (!["GET", "HEAD"].includes(request.method)) {
         validateMutationOrigin(request, address, host);
       }
 

package/features/model-slider/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "model-slider",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "label": {
     "en": "Model Slider",
     "zh-CN": "模型滑条"

package/features/notes/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "notes",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "label": {
     "en": "Notes",
     "zh-CN": "笔记"

package/features/notes/src/http-server.mjs

@@ -15,6 +15,7 @@ const LUCIDE_ICON_ROOT = path.resolve(DEFAULT_WEB_ROOT, "../assets/icons");
 const MAX_BODY_BYTES = 1024 * 1024;
 const MAX_PREVIEW_BYTES = 64 * 1024 * 1024;
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const CODEX_EMBED_ORIGIN = "app://-";
 const LUCIDE_ICON_NAMES = [
   "circle",
   "ellipsis",
@@ -233,6 +234,16 @@ function formatHost(host) {
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 
+function applyCodexEmbedCors(request, response) {
+  if (request.headers.origin !== CODEX_EMBED_ORIGIN) return false;
+  response.setHeader("Access-Control-Allow-Origin", CODEX_EMBED_ORIGIN);
+  response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, POST, PATCH, DELETE, OPTIONS");
+  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  response.setHeader("Access-Control-Allow-Private-Network", "true");
+  response.setHeader("Vary", "Origin");
+  return true;
+}
+
 function validateMutationOrigin(request, address, host) {
   const expectedHost = formatHost(host);
   const expectedOrigin = `http://${expectedHost}:${address.port}`;
@@ -246,6 +257,7 @@ function validateMutationOrigin(request, address, host) {
 
   const origin = request.headers.origin;
   if (!origin) return;
+  if (origin === CODEX_EMBED_ORIGIN) return;
   let parsed;
   try {
     parsed = new URL(origin);
@@ -285,6 +297,7 @@ export function createCodexNotesServer({
 
   const server = createServer(async (request, response) => {
     try {
+      applyCodexEmbedCors(request, response);
       const url = new URL(request.url ?? "/", `http://${formatHost(host)}:${port}`);
       const { pathname } = url;
       const method = request.method ?? "GET";
@@ -293,12 +306,7 @@ export function createCodexNotesServer({
       }
 
       if (method === "OPTIONS") {
-        response.writeHead(204, {
-          "Access-Control-Allow-Origin": request.headers.origin ?? "null",
-          "Access-Control-Allow-Headers": "Content-Type",
-          "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
-          "Access-Control-Max-Age": "600",
-        });
+        response.writeHead(204, { "Access-Control-Max-Age": "600" });
         response.end();
         return;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecodex",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Lightweight, local-first plugins for the Codex desktop app.",
   "license": "MIT",
   "type": "module",

package/packages/cli/src/runtime-manager.mjs

@@ -19,6 +19,19 @@ function hasExited(child) {
   return Boolean(child && (child.exitCode != null || child.signalCode != null));
 }
 
+function hasExactCommandArgument(command, argument) {
+  const value = String(command);
+  let offset = value.indexOf(argument);
+  while (offset >= 0) {
+    const before = offset === 0 || /\s/.test(value[offset - 1]);
+    const end = offset + argument.length;
+    const after = end === value.length || /\s/.test(value[end]);
+    if (before && after) return true;
+    offset = value.indexOf(argument, offset + 1);
+  }
+  return false;
+}
+
 function normalizedFailure(failure) {
   if (!failure || typeof failure !== "object") return failure ?? null;
   return {
@@ -119,6 +132,8 @@ export class RuntimeManager {
     waitForReady: readyWaiter = waitForReady,
     sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     stopTimeoutMs = 5_000,
+    manualLaunchPollMs = 1_000,
+    cdpPort = Number(process.env.CODEX_RUNTIME_CDP_PORT ?? 9231),
   }) {
     this.paths = paths;
     this.platform = platform;
@@ -127,6 +142,8 @@ export class RuntimeManager {
     this.waitForReady = readyWaiter;
     this.sleep = sleep;
     this.stopTimeoutMs = stopTimeoutMs;
+    this.manualLaunchPollMs = manualLaunchPollMs;
+    this.cdpPort = cdpPort;
     this.child = null;
     this.appliedFeatures = [];
     this.plugins = [];
@@ -134,6 +151,12 @@ export class RuntimeManager {
     this.stopping = false;
     this.lifecycleQueue = Promise.resolve();
     this.restartInFlight = null;
+    this.manualLaunchMonitorPromise = null;
+    this.manualLaunchMonitorStopped = true;
+    this.manualLaunchTimer = null;
+    this.manualLaunchWake = null;
+    this.manualLaunchBaselinePids = new Set();
+    this.manualLaunchArmed = false;
   }
 
   enqueue(operation) {
@@ -163,7 +186,7 @@ export class RuntimeManager {
         ...process.env,
         CODEX_FEATURES_ROOT: this.paths.featuresRoot,
         CODEX_RUNTIME_PROFILE_DIR: this.paths.profileDir,
-        CODEX_RUNTIME_CDP_PORT: process.env.CODEX_RUNTIME_CDP_PORT ?? "9231",
+        CODEX_RUNTIME_CDP_PORT: String(this.cdpPort),
         CODEX_IMAGE_HOST_DATA_DIR: this.paths.imagesDataDir,
         CODEX_NOTES_DATA_DIR: this.paths.notesDataDir,
         MINECODEX_ENABLED_FEATURES: features.join(","),
@@ -228,7 +251,155 @@ export class RuntimeManager {
   }
 
   start() {
-    return this.enqueue(() => this.startInternal());
+    return this.enqueue(async () => {
+      const status = await this.startInternal();
+      await this.startManualLaunchMonitor();
+      return status;
+    });
+  }
+
+  async nativeCodexSnapshot() {
+    if (typeof this.platform?.snapshotNativeCodexState !== "function") return null;
+    const snapshot = await this.platform.snapshotNativeCodexState();
+    const cdpArgument = `--remote-debugging-port=${this.cdpPort}`;
+    const processes = (Array.isArray(snapshot?.processes) ? snapshot.processes : [])
+      .filter(({ command }) => !hasExactCommandArgument(command, cdpArgument));
+    return {
+      count: processes.length,
+      processes,
+      pids: new Set(processes.flatMap(({ pid }) => Number.isInteger(pid) ? [pid] : [])),
+    };
+  }
+
+  async startManualLaunchMonitor() {
+    if (this.manualLaunchMonitorPromise || typeof this.platform?.snapshotNativeCodexState !== "function") return;
+    const snapshot = await this.nativeCodexSnapshot();
+    this.manualLaunchBaselinePids = new Set(snapshot?.pids ?? []);
+    this.manualLaunchArmed = this.manualLaunchBaselinePids.size === 0;
+    this.manualLaunchMonitorStopped = false;
+    const monitor = this.monitorManualCodexLaunches().catch((error) => {
+      if (!this.manualLaunchMonitorStopped) {
+        this.logger.warn?.("MineCodex manual Codex launch monitor failed", error.message);
+      }
+    }).finally(() => {
+      if (this.manualLaunchMonitorPromise === monitor) this.manualLaunchMonitorPromise = null;
+    });
+    this.manualLaunchMonitorPromise = monitor;
+  }
+
+  waitForManualLaunchPoll() {
+    if (this.manualLaunchMonitorStopped) return Promise.resolve();
+    return new Promise((resolve) => {
+      const finish = () => {
+        if (this.manualLaunchTimer) clearTimeout(this.manualLaunchTimer);
+        this.manualLaunchTimer = null;
+        this.manualLaunchWake = null;
+        resolve();
+      };
+      this.manualLaunchWake = finish;
+      this.manualLaunchTimer = setTimeout(finish, this.manualLaunchPollMs);
+    });
+  }
+
+  async monitorManualCodexLaunches() {
+    while (!this.manualLaunchMonitorStopped) {
+      await this.waitForManualLaunchPoll();
+      if (this.manualLaunchMonitorStopped) break;
+      try {
+        await this.reconcileManualCodexLaunch();
+      } catch (error) {
+        this.logger.warn?.("MineCodex could not adopt the Codex launch", error.message);
+      }
+    }
+  }
+
+  async stopManualLaunchMonitor() {
+    this.manualLaunchMonitorStopped = true;
+    this.manualLaunchWake?.();
+    await this.manualLaunchMonitorPromise;
+    this.manualLaunchMonitorPromise = null;
+    this.manualLaunchBaselinePids.clear();
+    this.manualLaunchArmed = false;
+  }
+
+  async reconcileManualCodexLaunch() {
+    if (this.manualLaunchMonitorStopped) return false;
+    const snapshot = await this.nativeCodexSnapshot();
+    if (!snapshot) return false;
+
+    if (this.manualLaunchBaselinePids.size > 0) {
+      const baselineStillRunning = [...this.manualLaunchBaselinePids]
+        .some((pid) => snapshot.pids.has(pid));
+      if (baselineStillRunning) return false;
+      this.manualLaunchBaselinePids.clear();
+      if (snapshot.count === 0) {
+        this.manualLaunchArmed = true;
+        return false;
+      }
+      this.manualLaunchArmed = true;
+    }
+
+    if (snapshot.count === 0) {
+      this.manualLaunchArmed = true;
+      return false;
+    }
+    if (!this.manualLaunchArmed) return false;
+
+    const observedPids = new Set(snapshot.pids);
+    this.manualLaunchArmed = false;
+    this.manualLaunchBaselinePids = observedPids;
+    return this.enqueue(async () => {
+      if (this.manualLaunchMonitorStopped) return false;
+      const latest = await this.nativeCodexSnapshot();
+      const observedProcessStillRunning = latest
+        && [...observedPids].some((pid) => latest.pids.has(pid));
+      if (!observedProcessStillRunning) {
+        if (!latest?.count) {
+          this.manualLaunchBaselinePids.clear();
+          this.manualLaunchArmed = true;
+        }
+        return false;
+      }
+
+      await this.stopInternal();
+      let terminated;
+      try {
+        terminated = await this.platform.terminateNativeCodex();
+      } catch (error) {
+        await this.restoreIdleRuntimeAfterAdoptionFailure(error);
+        throw error;
+      }
+
+      if (!(terminated > 0)) {
+        await this.startInternal();
+        this.manualLaunchBaselinePids.clear();
+        this.manualLaunchArmed = true;
+        return false;
+      }
+
+      try {
+        const status = await this.startInternal({ launchCodex: true });
+        this.manualLaunchBaselinePids.clear();
+        this.manualLaunchArmed = true;
+        return status;
+      } catch (error) {
+        this.manualLaunchBaselinePids.clear();
+        this.manualLaunchArmed = true;
+        await this.restoreIdleRuntimeAfterAdoptionFailure(error);
+        throw error;
+      }
+    });
+  }
+
+  async restoreIdleRuntimeAfterAdoptionFailure(failure) {
+    try {
+      await this.startInternal();
+    } catch (recoveryError) {
+      throw new Error(
+        `${failure.message}; idle RuntimeHost recovery failed: ${recoveryError.message}`,
+        { cause: failure },
+      );
+    }
   }
 
   async stopInternal() {
@@ -274,7 +445,8 @@ export class RuntimeManager {
     }
   }
 
-  stop() {
+  async stop() {
+    await this.stopManualLaunchMonitor();
     return this.enqueue(() => this.stopInternal());
   }
 

package/packages/runtime-host/README.md

@@ -141,8 +141,10 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
 
 - 只在 top frame 安装 Runtime，绝不向业务 iframe 注入 binding token。
 - Watch / refresh 串行；已连接 Renderer 不重复连接，关闭 target 会清理状态。
-- 本地 Surface 注入前先启用 CSP bypass，并为后续 document 注册 document-start 脚本；
-  当前 Codex document 始终直接注入或替换 Runtime，绝不通过 CDP reload Codex 页面。
+- 当前 Codex document 始终直接注入或替换 Runtime，绝不通过 CDP reload Codex 页面。
+  本地 Surface 不直接导航到 loopback URL：Host 先创建 `about:blank` iframe，再校验
+  manifest URL、health service/protocol/instance，抓取 HTML 并用 `Page.setDocumentContent`
+  写入目标 frame。Images/Notes 只向精确的 `app://-` Origin 开放 CORS。
 - 入口由 Renderer 内的 MutationObserver 幂等挂载，React 重绘不会产生重复入口。
 - Summary 根据对话主区域宽度连续派生 `overlay / shift / gutter`：小于 1096px
   使用临时 Popover；1096–1535px 预留 316px 并把对话内容左移 158px；更宽时
@@ -154,9 +156,9 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
   border、dropdown background 和 elevation tokens 发送给 Surface。
 - 新客户端会话默认关闭；Thread 切换关闭 Pinned Summary 并清除旧 Composer Range。
 - Detail Tab 使用 Codex 当前 `local-thread` scope，因此标签状态跟随 Task；React panel
-  中的 iframe 继续注册同一套 Surface origin、`contentWindow`、Theme 与 Host-action bridge。
+  中的 iframe 继续注册同一套可信 Host origin、`contentWindow`、Theme 与 Host-action bridge。
 - Surface 以 `ready` handshake 标记可用。若第一次加载发生在服务离线期间，下一次
-  打开只重载这个未 ready 的 iframe；已经 ready 的 Surface 不重载、不打断草稿。
+  打开只重新请求 Host 加载这个未 ready 的 frame；已经 ready 的 Surface 不重载、不打断草稿。
 
 ## 当前接口分类
 

package/packages/runtime-host/src/codex-runtime.mjs

@@ -7,6 +7,10 @@ const RUNTIME_VERSION = 99;
 const HOST_BINDING_NAME = "__codexPersonalHostAction";
 const CSP_BOOTSTRAP_VERSION = 1;
 const CSP_BOOTSTRAP_KEY = "__mineCodexCspBootstrapVersion";
+const CODEX_APP_ORIGIN = "app://-";
+const SURFACE_LOAD_ACTION = "load-surface";
+const SURFACE_FRAME_PREFIX = "minecodex-surface-";
+const LOOPBACK_SURFACE_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
 export const RESPONSIVE_SUMMARY_LAYOUT = Object.freeze({
   contentBaseWidth: 736,
@@ -38,6 +42,48 @@ export function responsiveSummaryContentShift({ displayMode, isPinned }, layout
     : 0;
 }
 
+function declaredSurfaceUrls(feature) {
+  return new Set([
+    feature.surfaceUrl,
+    feature.pinnedSummary?.surfaceUrl,
+    ...(feature.detailTabs ?? []).map((detail) => detail.surfaceUrl),
+  ].filter(Boolean));
+}
+
+function requireDeclaredLoopbackSurface(feature, value) {
+  if (typeof value !== "string" || !declaredSurfaceUrls(feature).has(value)) {
+    throw Object.assign(new Error("Surface URL is not declared by this feature"), {
+      code: "SURFACE_URL_NOT_ALLOWED",
+    });
+  }
+  const url = new URL(value);
+  if (url.protocol !== "http:" || !LOOPBACK_SURFACE_HOSTS.has(url.hostname)) {
+    throw Object.assign(new Error("Surface URL must use an exact loopback HTTP origin"), {
+      code: "SURFACE_URL_NOT_ALLOWED",
+    });
+  }
+  return url;
+}
+
+function findFrameByName(frameTree, frameName) {
+  if (frameTree.frame?.name === frameName) return frameTree.frame;
+  for (const child of frameTree.childFrames ?? []) {
+    const match = findFrameByName(child, frameName);
+    if (match) return match;
+  }
+  return null;
+}
+
+function documentWithBase(html, surfaceUrl) {
+  const head = /<head(?:\s[^>]*)?>/i;
+  if (!head.test(html)) {
+    throw Object.assign(new Error("Surface document has no head element"), {
+      code: "SURFACE_DOCUMENT_INVALID",
+    });
+  }
+  return html.replace(head, (match) => `${match}<base href=${JSON.stringify(surfaceUrl)}>`);
+}
+
 export function createInjectionSource(features, {
   bindingName = HOST_BINDING_NAME,
   bindingToken = "test-binding-token",
@@ -1785,6 +1831,32 @@ export function createInjectionSource(features, {
       return `${featureId}:${kind}:${detailId}`;
     }
 
+    function surfaceFrameName(featureId) {
+      const nonce = crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      return `minecodex-surface-${config.sessionId}-${featureId}-${nonce}`;
+    }
+
+    function requestSurfaceLoad(record) {
+      if (!record || record.loading || typeof globalThis[config.bindingName] !== "function") return false;
+      const requestId = crypto.randomUUID?.()
+        ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      record.loading = true;
+      record.ready = false;
+      record.loadError = null;
+      pendingHostActions.set(requestId, { recordKey: record.key, kind: "surface-load" });
+      globalThis[config.bindingName](JSON.stringify({
+        token: config.bindingToken,
+        featureId: record.featureId,
+        requestId,
+        action: "load-surface",
+        payload: {
+          frameName: record.frame.name,
+          surfaceUrl: record.surfaceUrl,
+        },
+      }));
+      return true;
+    }
+
     function postSurfaceActive(record, active) {
       if (!record || record.kind !== "page") return;
       record.frame.contentWindow?.postMessage({
@@ -1799,10 +1871,13 @@ export function createInjectionSource(features, {
         featureId: feature.id,
         kind,
         detailId,
-        origin: new URL(surfaceUrl).origin,
+        origin: window.location.origin,
+        surfaceUrl,
         element,
         frame,
         ready: false,
+        loading: false,
+        loadError: null,
         preferredHeight: null,
       };
       surfaceRecords.set(key, record);
@@ -1810,14 +1885,14 @@ export function createInjectionSource(features, {
         queueTheme();
         postSurfaceActive(record, activePageFeatureId === record.featureId && !record.element.hidden);
       });
+      requestSurfaceLoad(record);
       return record;
     }
 
     function reloadSurfaceIfUnready(key, surfaceUrl) {
       const record = surfaceRecords.get(key);
-      if (!record || record.ready) return false;
-      record.frame.src = surfaceUrl;
-      return true;
+      if (!record || record.ready || record.surfaceUrl !== surfaceUrl) return false;
+      return requestSurfaceLoad(record);
     }
 
     function removeSurfaceRecord(key) {
@@ -2056,9 +2131,10 @@ export function createInjectionSource(features, {
       }
     }
 
-    function createFrame(surfaceUrl, title) {
+    function createFrame(featureId, title) {
       const frame = document.createElement("iframe");
-      frame.src = surfaceUrl;
+      frame.name = surfaceFrameName(featureId);
+      frame.src = "about:blank";
       frame.title = title;
       frame.allow = "clipboard-write";
       frame.style.cssText = "width:100%;height:100%;border:0;display:block;background:transparent";
@@ -2076,7 +2152,7 @@ export function createInjectionSource(features, {
         "z-index:40",
         "background:transparent",
       ].join(";");
-      const frame = createFrame(feature.surfaceUrl, feature.label);
+      const frame = createFrame(feature.id, feature.label);
       surface.append(frame);
       document.body.append(surface);
       pageSurfaces.set(feature.id, surface);
@@ -2311,7 +2387,7 @@ export function createInjectionSource(features, {
         "pointer-events:none",
         "will-change:transform,opacity",
       ].join(";");
-      const frame = createFrame(definition.surfaceUrl, definition.label ?? feature.label);
+      const frame = createFrame(feature.id, definition.label ?? feature.label);
       surface.append(frame);
       document.body.append(surface);
       pinnedSurfaces.set(feature.id, surface);
@@ -2505,7 +2581,7 @@ export function createInjectionSource(features, {
         "outline:none",
       ].join(";");
 
-      const frame = createFrame(editorUrl.href, `${payload.id ? "Edit" : "Add"} ${kind}`);
+      const frame = createFrame(feature.id, `${payload.id ? "Edit" : "Add"} ${kind}`);
       dialog.append(frame);
       document.body.append(overlay, dialog);
       const key = surfaceKey(feature.id, "modal");
@@ -2751,6 +2827,8 @@ export function createInjectionSource(features, {
         const elementRef = React.useRef(null);
         const frameRef = React.useRef(null);
         const recordKeyRef = React.useRef(null);
+        const frameNameRef = React.useRef(null);
+        frameNameRef.current ??= surfaceFrameName(feature.id);
         React.useLayoutEffect(() => {
           const element = elementRef.current;
           const frame = frameRef.current;
@@ -2785,7 +2863,8 @@ export function createInjectionSource(features, {
           },
           children: jsx.jsx("iframe", {
             ref: frameRef,
-            src: detail.surfaceUrl,
+            name: frameNameRef.current,
+            src: "about:blank",
             title: detail.label,
             allow: "clipboard-write",
             style: {
@@ -3027,7 +3106,7 @@ export function createInjectionSource(features, {
       panel.setAttribute("data-app-shell-tab-panel-controller", "right");
       panel.setAttribute("data-tab-id", stableId);
       panel.style.cssText = "position:absolute;inset:0;min-height:0;background:var(--color-token-main-surface-primary)";
-      const frame = createFrame(detail.surfaceUrl, detail.label);
+      const frame = createFrame(feature.id, detail.label);
       panel.append(frame);
       strip.append(tab);
       panels.append(panel);
@@ -3337,6 +3416,11 @@ export function createInjectionSource(features, {
       pendingHostActions.delete(requestId);
       const record = surfaceRecords.get(pending.recordKey);
       if (!record) return false;
+      if (pending.kind === "surface-load") {
+        record.loading = false;
+        record.loadError = response.ok ? null : response.error;
+        return response.ok;
+      }
       respondToSurface(record, requestId, response);
       return true;
     }
@@ -3735,6 +3819,9 @@ export class CodexRuntime {
     availabilityTimeoutMs = 20_000,
     availabilityPollMs = 500,
     monitorIntervalMs = 2_000,
+    surfaceLoadTimeoutMs = 5_000,
+    surfaceFramePollMs = 25,
+    featureInstanceId = null,
     runtimeSessionId = randomBytes(16).toString("hex"),
     onStatusChange = null,
     onManagedCodexPidChange = null,
@@ -3751,6 +3838,9 @@ export class CodexRuntime {
     this.availabilityTimeoutMs = availabilityTimeoutMs;
     this.availabilityPollMs = availabilityPollMs;
     this.monitorIntervalMs = monitorIntervalMs;
+    this.surfaceLoadTimeoutMs = surfaceLoadTimeoutMs;
+    this.surfaceFramePollMs = surfaceFramePollMs;
+    this.featureInstanceId = featureInstanceId;
     this.runtimeSessionId = runtimeSessionId;
     this.onStatusChange = onStatusChange;
     this.onManagedCodexPidChange = onManagedCodexPidChange;
@@ -4099,6 +4189,106 @@ export class CodexRuntime {
     }
   }
 
+  async fetchSurfaceResource(url, label) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.surfaceLoadTimeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        cache: "no-store",
+        headers: { origin: CODEX_APP_ORIGIN },
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw Object.assign(new Error(`${label} timed out`), { code: "SURFACE_LOAD_TIMEOUT" });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async verifiedSurfaceDocument(feature, surfaceUrl) {
+    requireDeclaredLoopbackSurface(feature, surfaceUrl);
+    if (!this.featureInstanceId || !feature.healthUrl) {
+      throw Object.assign(new Error("Surface service identity is unavailable"), {
+        code: "SURFACE_IDENTITY_UNAVAILABLE",
+      });
+    }
+    const healthResponse = await this.fetchSurfaceResource(feature.healthUrl, "Surface health check");
+    if (!healthResponse?.ok) {
+      throw Object.assign(new Error(`Surface health returned HTTP ${healthResponse?.status ?? "error"}`), {
+        code: "SURFACE_HEALTH_FAILED",
+      });
+    }
+    let health;
+    try {
+      health = await healthResponse.json();
+    } catch {
+      throw Object.assign(new Error("Surface health returned invalid JSON"), {
+        code: "SURFACE_HEALTH_FAILED",
+      });
+    }
+    if (
+      health?.ok !== true
+      || health.service !== feature.id
+      || health.protocolVersion !== 1
+      || health.instanceId !== this.featureInstanceId
+    ) {
+      throw Object.assign(new Error("Surface service identity does not match this RuntimeHost"), {
+        code: "SURFACE_IDENTITY_MISMATCH",
+      });
+    }
+
+    const response = await this.fetchSurfaceResource(surfaceUrl, "Surface document request");
+    if (!response?.ok) {
+      throw Object.assign(new Error(`Surface document returned HTTP ${response?.status ?? "error"}`), {
+        code: "SURFACE_DOCUMENT_FAILED",
+      });
+    }
+    const contentType = String(response.headers?.get?.("content-type") ?? "").toLowerCase();
+    if (!contentType.startsWith("text/html")) {
+      throw Object.assign(new Error("Surface document must be HTML"), {
+        code: "SURFACE_DOCUMENT_INVALID",
+      });
+    }
+    return documentWithBase(await response.text(), surfaceUrl);
+  }
+
+  async loadSurfaceIntoFrame(client, feature, payload = {}) {
+    const frameName = payload.frameName;
+    if (
+      typeof frameName !== "string"
+      || !frameName.startsWith(SURFACE_FRAME_PREFIX)
+      || frameName.length > 256
+    ) {
+      throw Object.assign(new Error("Surface frame identity is invalid"), {
+        code: "SURFACE_FRAME_INVALID",
+      });
+    }
+    const surfaceUrl = payload.surfaceUrl;
+    const html = await this.verifiedSurfaceDocument(feature, surfaceUrl);
+    const deadline = Date.now() + this.surfaceLoadTimeoutMs;
+    let frame = null;
+    while (!frame && Date.now() < deadline) {
+      const { frameTree } = await client.send("Page.getFrameTree");
+      frame = findFrameByName(frameTree, frameName);
+      if (!frame) await this.sleep(this.surfaceFramePollMs);
+    }
+    if (!frame) {
+      throw Object.assign(new Error("Surface frame was not discovered"), {
+        code: "SURFACE_FRAME_NOT_FOUND",
+      });
+    }
+    if (frame.url !== "about:blank") {
+      throw Object.assign(new Error("Surface frame must remain at about:blank before loading"), {
+        code: "SURFACE_FRAME_INVALID",
+      });
+    }
+    await client.send("Page.setDocumentContent", { frameId: frame.id, html });
+    return { loaded: true };
+  }
+
   async handleBindingCalled(targetId, client, params) {
     if (params.name !== HOST_BINDING_NAME) return;
     let request;
@@ -4109,6 +4299,18 @@ export class CodexRuntime {
     }
     if (request.token !== this.bindingTokens.get(targetId) || typeof request.requestId !== "string") return;
     const feature = this.features.find((candidate) => candidate.id === request.featureId);
+    if (feature && request.action === SURFACE_LOAD_ACTION) {
+      try {
+        const result = await this.loadSurfaceIntoFrame(client, feature, request.payload);
+        await this.resolveHostAction(client, request.requestId, { ok: true, result });
+      } catch (error) {
+        await this.resolveHostAction(client, request.requestId, {
+          ok: false,
+          error: { code: error.code ?? "SURFACE_LOAD_FAILED", message: error.message },
+        });
+      }
+      return;
+    }
     if (!feature?.hostActions?.includes(request.action)) {
       await this.resolveHostAction(client, request.requestId, {
         ok: false,

package/packages/runtime-host/src/main.mjs

@@ -63,6 +63,7 @@ featureProcesses = await startFeatureProcesses(features, {
 
 runtime = new CodexRuntime({
   features,
+  featureInstanceId,
   profileDir,
   cdpPort,
   appPath: process.env.MINECODEX_CODEX_EXECUTABLE || undefined,