minecodex 0.1.0 → 0.1.2

package/README.md

@@ -17,6 +17,10 @@ npm install -g minecodex
 mcx install
 ```
 
+`mcx install` 会关闭当前正在运行的 Codex 窗口，再以 MineCodex 托管方式重新打开；
+请先保存正在编辑的内容，并让安装命令完整运行到成功提示。安装后，macOS 的
+“登录项与扩展”中会显示名为 **MineCodex** 的后台项目，用于在登录后恢复插件。
+
 安装后三个插件默认开启。打开本地控制台：
 
 ```bash
@@ -34,7 +38,8 @@ mcx status [--json]
 mcx restart
 ```
 
-关闭插件只会停止注册，不会删除数据。`mcx uninstall` 默认保留 MineCodex 设置、
+关闭插件只会停用对应功能，不会删除数据；保存开关后运行 `mcx restart` 应用变更。
+`mcx uninstall` 会移除名为 MineCodex 的后台项目，并默认保留 MineCodex 设置、
 Notes 数据和 Images 索引；只有显式传入 `--purge` 才会删除 MineCodex 自有数据。
 MineCodex 永远不会删除 `~/.codex/generated_images` 中的原图或 Notes 引用的源文件。
 

package/features/images/README.md

@@ -87,7 +87,7 @@ HTTP + Images UI
 - Images 服务需要保持运行，才会持续监听新图片；侧边栏注册由 `CodexRuntimeHost` 统一维持。
 - 每次服务启动都会先开放 health，再在后台补扫停机期间新增的图片并刷新来源名称；初始补扫完成后，运行期间的新图片由文件监听自动加入。手动 Refresh 会再次补扫来源和 Archive 状态，但不会重置筛选、图板模式、详情、滚动位置或列数。刷新 ring 至少显示 1 秒。
 - 侧边栏使用 Codex 当前未公开的 CDP / DOM 能力，Codex UI 更新后只需调整统一宿主；独立 Web UI 和路径索引不受影响。
-- 当前 Codex 的 CSP 会屏蔽普通本地 iframe。统一宿主会先等待原生侧栏完成渲染，再启用 CSP bypass、注册 document-start 脚本，并替换当前 document 中旧的 MineCodex runtime 后显式完成注入；当前实现不会调用会让用户看到页面刷新的 `Page.reload`（Issue #1）。
+- 当前 Codex 的 CSP 会屏蔽普通本地 iframe。统一宿主会先启用 CSP bypass 并注册 document-start 脚本；尚未完成该初始化的首次或旧版 document 会受控 reload 一次。完成初始化后会留下 document 标记，后续 RuntimeHost 重启只替换旧的 MineCodex runtime，不再刷新 Codex 页面（Issue #1）。
 - 详情打开时会从本机 Session JSONL 按需读取该 ImageGen item 的真实 `revised_prompt` 并缓存到索引；历史记录缺少该事件时明确显示 Prompt 不可用，不从附近文本猜测。
 - 当前没有发现 Codex 会因运行时间增长而自动清理 `generated_images` 的证据。如果未来观察到真实清理，再决定是否增加可选备份。
 

package/features/images/codex-feature.json

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

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

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

package/features/notes/codex-feature.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecodex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight, local-first plugins for the Codex desktop app.",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,7 @@
     "LICENSE",
     "packages/cli/bin",
     "packages/cli/src",
+    "packages/cli/native/MineCodex.app",
     "packages/runtime-host/src",
     "features/model-slider/assets",
     "features/model-slider/codex-feature.json",
@@ -39,10 +40,11 @@
   },
   "scripts": {
     "start": "node packages/cli/bin/mcx.mjs serve",
-    "test": "node --test packages/cli/test/*.test.mjs packages/runtime-host/test/*.test.mjs features/model-slider/test/*.test.mjs features/notes/test/*.test.mjs features/images/test/*.test.mjs",
+    "test": "node --test packages/cli/test/*.test.mjs packages/runtime-host/test/*.test.mjs features/model-slider/test/*.test.mjs features/notes/test/*.test.mjs features/images/test/*.test.mjs apps/dashboard/test/*.test.mjs",
     "test:cli": "node --test packages/cli/test/*.test.mjs",
     "test:runtime": "node --test packages/runtime-host/test/*.test.mjs",
     "check": "node --check packages/cli/bin/mcx.mjs && node --check packages/cli/src/*.mjs && node --check packages/runtime-host/src/*.mjs",
+    "build:service": "scripts/build-service-app.zsh",
     "pack:check": "npm pack --dry-run",
     "pack:audit": "node scripts/audit-package.mjs",
     "prepublishOnly": "npm test && npm run check && npm run pack:audit"

package/packages/cli/native/MineCodex.app/Contents/Info.plist

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleDisplayName</key>
+  <string>MineCodex</string>
+  <key>CFBundleExecutable</key>
+  <string>MineCodexServiceManager</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.vontean.minecodex.background-service-manager</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>MineCodex</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>LSBackgroundOnly</key>
+  <true/>
+  <key>LSMinimumSystemVersion</key>
+  <string>13.0</string>
+</dict>
+</plist>

package/packages/cli/native/MineCodex.app/Contents/Library/LaunchAgents/com.vontean.minecodex.background.plist

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.vontean.minecodex.background</string>
+  <key>BundleProgram</key>
+  <string>Contents/Resources/MineCodexServiceHost</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+</dict>
+</plist>

package/packages/cli/native/MineCodex.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/MineCodexServiceHost</key>
+		<data>
+		kB0iYBcULzqcS1yOgYpY3LZjeq4=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Library/LaunchAgents/com.vontean.minecodex.background.plist</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			mGWkf+X17Pau3uy8xUUB1s+JXofeKYKNRzFPk3FXeaA=
+			</data>
+		</dict>
+		<key>Resources/MineCodexServiceHost</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			b9bnzjgASA30QyXiczJMxHbOYKm7WG+j24ZfZ1povzc=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/packages/cli/native/README.md

@@ -0,0 +1,18 @@
+# Stable MineCodex background host
+
+`MineCodex.app` is the small, universal native owner of MineCodex's macOS
+background item. The npm package ships the built app only; native source and the
+build script remain development inputs.
+
+The production app bundle is intentionally versioned independently from the npm
+package. Its ad-hoc code identity must stay byte-for-byte stable across ordinary
+JavaScript releases because macOS records the helper's designated requirement.
+Do not rebuild or change the bundle for an npm version bump. If native behavior
+must change, plan an explicit signed-helper migration or introduce a new service
+identifier and verify the macOS Background Items upgrade path before release.
+
+Rebuild deliberately with:
+
+```bash
+npm run build:service
+```

package/packages/cli/src/commands.mjs

@@ -23,6 +23,12 @@ async function exists(filePath) {
   }
 }
 
+async function serviceInstalled(platform, paths) {
+  if (platform.isServiceInstalled) return platform.isServiceInstalled(paths);
+  return (paths.serviceManagerPath ? exists(paths.serviceManagerPath) : false)
+    || (paths.launchAgentPath ? exists(paths.launchAgentPath) : false);
+}
+
 async function waitForService(port, { fetchImpl = fetch, timeoutMs = 20_000 } = {}) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -151,7 +157,7 @@ async function installCommand({ paths, platform, cliPath, output, serviceProbe,
 async function openCommand({ paths, platform, serviceProbe, fetchImpl }) {
   const waitForServiceImpl = serviceProbe?.waitForService ?? waitForService;
   if (!(await waitForServiceImpl(DEFAULT_CONTROL_PORT, { fetchImpl, timeoutMs: 750 }))) {
-    if (!(await exists(paths.launchAgentPath))) throw new Error("MineCodex is not installed. Run `mcx install` first.");
+    if (!(await serviceInstalled(platform, paths))) throw new Error("MineCodex is not installed. Run `mcx install` first.");
     await platform.startService(paths);
     if (!(await waitForServiceImpl(DEFAULT_CONTROL_PORT, { fetchImpl }))) throw new Error("MineCodex service could not be started.");
   }
@@ -181,16 +187,16 @@ function featureStatusText(feature) {
   return `${copy[state] ?? state}${failure}`;
 }
 
-async function statusCommand({ paths, jsonOutput, output, fetchImpl }) {
+async function statusCommand({ paths, platform, jsonOutput, output, fetchImpl }) {
   let status;
   try {
     const response = await authorizedFetch(paths, "/api/status", {}, { fetchImpl });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
-    status = { installed: await exists(paths.launchAgentPath), service: { running: true }, ...await response.json() };
+    status = { installed: await serviceInstalled(platform, paths), service: { running: true }, ...await response.json() };
   } catch {
     const config = await readConfig(paths.configPath).catch(() => null);
     status = {
-      installed: await exists(paths.launchAgentPath),
+      installed: await serviceInstalled(platform, paths),
       version: packageMetadata.version,
       service: { running: false },
       runtime: { running: false },
@@ -267,7 +273,7 @@ async function updateCommand({ paths, platform, cliPath, output, npm = createNpm
     output(`MineCodex ${packageMetadata.version} is already up to date.`);
     return;
   }
-  const wasInstalled = await exists(paths.launchAgentPath);
+  const wasInstalled = await serviceInstalled(platform, paths);
   const previousService = wasInstalled
     ? (await serviceSnapshot(platform, paths) ?? { running: true, plist: { exists: true } })
     : null;
@@ -276,7 +282,7 @@ async function updateCommand({ paths, platform, cliPath, output, npm = createNpm
   if (!rollbackPath) throw new Error("Could not create a rollback archive for the installed MineCodex version.");
   try {
     if (wasInstalled && previousService?.running) {
-      await platform.stopService({ ignoreErrors: false });
+      await platform.stopService(paths, { ignoreErrors: false });
       await platform.assertServiceStopped?.();
     }
     await npm.installGlobal("minecodex@latest");
@@ -378,7 +384,7 @@ export async function runCli(argv, {
   if (["--version", "-v"].includes(command)) return output(packageMetadata.version);
   if (command === "install") return installCommand({ paths, platform, cliPath, output, serviceProbe, fetchImpl, nodeVersion });
   if (command === "open" || command === "gui") return openCommand({ paths, platform, serviceProbe, fetchImpl });
-  if (command === "status") return statusCommand({ paths, jsonOutput: args.includes("--json"), output, fetchImpl });
+  if (command === "status") return statusCommand({ paths, platform, jsonOutput: args.includes("--json"), output, fetchImpl });
   if (command === "restart") return restartCommand({ paths, output, fetchImpl });
   if (command === "uninstall" || command === "remove") {
     return uninstallCommand({ paths, platform, purge: args.includes("--purge"), output, cliPath });

package/packages/cli/src/paths.mjs

@@ -10,6 +10,8 @@ export const PACKAGE_ROOT = path.resolve(
 export function resolvePaths({ homeDir = os.homedir() } = {}) {
   const supportDir = path.join(homeDir, "Library", "Application Support", "MineCodex");
   const logsDir = path.join(homeDir, "Library", "Logs", "MineCodex");
+  const serviceDir = path.join(supportDir, "service");
+  const serviceAppPath = path.join(serviceDir, "MineCodex.app");
   return Object.freeze({
     homeDir,
     packageRoot: PACKAGE_ROOT,
@@ -18,12 +20,18 @@ export function resolvePaths({ homeDir = os.homedir() } = {}) {
     runtimeEntry: path.join(PACKAGE_ROOT, "packages", "runtime-host", "src", "main.mjs"),
     supportDir,
     logsDir,
+    serviceDir,
+    serviceBundleSource: path.join(PACKAGE_ROOT, "packages", "cli", "native", "MineCodex.app"),
+    serviceAppPath,
+    serviceManagerPath: path.join(serviceAppPath, "Contents", "MacOS", "MineCodexServiceManager"),
+    serviceRuntimeConfigPath: path.join(supportDir, "service-runtime.plist"),
     configPath: path.join(supportDir, "config.json"),
     tokenPath: path.join(supportDir, "control-token"),
     pidPath: path.join(supportDir, "service.pid"),
     codexPidPath: path.join(supportDir, "codex.pid"),
     runtimeReadyPath: path.join(supportDir, "runtime-ready.json"),
     profileDir: path.join(supportDir, "codex-profile"),
+    // v0.1.0 used a directly installed plist. Keep the path only for migration and cleanup.
     launchAgentPath: path.join(homeDir, "Library", "LaunchAgents", "com.vontean.minecodex.plist"),
     serviceLogPath: path.join(logsDir, "runtime.log"),
     serviceErrorLogPath: path.join(logsDir, "runtime-error.log"),

package/packages/cli/src/platform.mjs

@@ -1,16 +1,18 @@
 import { execFile as execFileCallback } from "node:child_process";
-import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 
 const defaultExecFile = promisify(execFileCallback);
-const defaultFileSystem = Object.freeze({ mkdir, readFile, stat, unlink, writeFile });
+const defaultFileSystem = Object.freeze({ mkdir, readFile, rename, rm, stat, unlink, writeFile });
 
-export const SERVICE_LABEL = "com.vontean.minecodex";
+export const SERVICE_LABEL = "com.vontean.minecodex.background";
+export const LEGACY_SERVICE_LABEL = "com.vontean.minecodex";
 export const CODEX_APP_PATH = "/Applications/ChatGPT.app";
 export const CODEX_EXECUTABLE = `${CODEX_APP_PATH}/Contents/MacOS/ChatGPT`;
 export const MIN_NODE_VERSION = Object.freeze({ major: 22, minor: 5, patch: 0 });
+export const MIN_MACOS_VERSION = Object.freeze({ major: 13, darwinMajor: 22 });
 
 function xml(value) {
   return String(value)
@@ -21,38 +23,21 @@ function xml(value) {
     .replaceAll("'", "'");
 }
 
-export function buildLaunchAgent({ nodePath, cliPath, paths }) {
+export function buildServiceRuntimeConfig({ nodePath, cliPath, paths }) {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-  <key>Label</key>
-  <string>${SERVICE_LABEL}</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${xml(nodePath)}</string>
-    <string>${xml(cliPath)}</string>
-    <string>serve</string>
-    <string>--service</string>
-  </array>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <dict>
-    <key>SuccessfulExit</key>
-    <false/>
-  </dict>
-  <key>ProcessType</key>
-  <string>Interactive</string>
-  <key>StandardOutPath</key>
+  <key>NodePath</key>
+  <string>${xml(nodePath)}</string>
+  <key>CLIPath</key>
+  <string>${xml(cliPath)}</string>
+  <key>StandardOutputPath</key>
   <string>${xml(paths.serviceLogPath)}</string>
   <key>StandardErrorPath</key>
   <string>${xml(paths.serviceErrorLogPath)}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>${xml(path.dirname(nodePath))}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
-  </dict>
+  <key>Path</key>
+  <string>${xml(path.dirname(nodePath))}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
 </dict>
 </plist>
 `;
@@ -155,10 +140,31 @@ function serviceTarget(uid) {
   return `gui/${uid}/${SERVICE_LABEL}`;
 }
 
+function legacyServiceTarget(uid) {
+  return `gui/${uid}/${LEGACY_SERVICE_LABEL}`;
+}
+
+function appServiceStatus(output) {
+  const match = String(output).match(/(?:^|\n)status=([a-z-]+)(?:\n|$)/);
+  return match?.[1] ?? "unknown";
+}
+
+function assertOwnedServicePaths(paths) {
+  const root = path.parse(paths.serviceDir ?? "").root;
+  if (!path.isAbsolute(paths.serviceDir)
+      || paths.serviceDir === root
+      || path.dirname(paths.serviceDir) === root
+      || path.basename(paths.serviceDir) !== "service"
+      || paths.serviceAppPath !== path.join(paths.serviceDir, "MineCodex.app")) {
+    throw new Error(`Refusing unsafe MineCodex service path: ${paths.serviceAppPath}`);
+  }
+}
+
 export class MacPlatformAdapter {
   constructor({
     uid = process.getuid?.() ?? os.userInfo().uid,
     platform = process.platform,
+    osRelease = os.release(),
     homeDir = os.homedir(),
     execFile = defaultExecFile,
     fileSystem = defaultFileSystem,
@@ -168,6 +174,7 @@ export class MacPlatformAdapter {
   } = {}) {
     this.uid = uid;
     this.platform = platform;
+    this.osRelease = osRelease;
     this.homeDir = homeDir;
     this.execFile = execFile;
     this.fileSystem = fileSystem;
@@ -180,6 +187,10 @@ export class MacPlatformAdapter {
     if (this.platform !== "darwin") {
       throw new Error("MineCodex v1 installation currently supports macOS only.");
     }
+    const darwinMajor = Number.parseInt(this.osRelease.split(".")[0], 10);
+    if (!Number.isInteger(darwinMajor) || darwinMajor < MIN_MACOS_VERSION.darwinMajor) {
+      throw new Error(`MineCodex requires macOS ${MIN_MACOS_VERSION.major} or newer.`);
+    }
   }
 
   async assertCodexInstalled() {
@@ -202,9 +213,9 @@ export class MacPlatformAdapter {
     return this.codexInstallation ?? this.assertCodexInstalled();
   }
 
-  async isServiceRunning() {
+  async isLaunchdServiceRunning(target) {
     try {
-      await this.execFile("/bin/launchctl", ["print", serviceTarget(this.uid)]);
+      await this.execFile("/bin/launchctl", ["print", target]);
       return true;
     } catch (error) {
       if (serviceIsAbsent(error)) return false;
@@ -212,6 +223,41 @@ export class MacPlatformAdapter {
     }
   }
 
+  async isServiceRunning() {
+    return this.isLaunchdServiceRunning(serviceTarget(this.uid));
+  }
+
+  async pathExists(filePath) {
+    try {
+      if (this.fileSystem.stat) await this.fileSystem.stat(filePath);
+      else await this.fileSystem.readFile(filePath);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  async serviceManagerStatus(paths) {
+    if (!(await this.pathExists(paths.serviceManagerPath))) return "not-found";
+    const { stdout } = await this.execFile(paths.serviceManagerPath, ["status"]);
+    return appServiceStatus(stdout);
+  }
+
+  async isServiceInstalled(paths) {
+    return (await this.pathExists(paths.serviceManagerPath))
+      || (await this.pathExists(paths.launchAgentPath));
+  }
+
+  async writeServiceRuntimeConfig(paths, content, mode = 0o600) {
+    const temporaryPath = `${paths.serviceRuntimeConfigPath}.installing`;
+    await this.fileSystem.unlink(temporaryPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    await this.fileSystem.writeFile(temporaryPath, content, { mode });
+    await this.fileSystem.rename(temporaryPath, paths.serviceRuntimeConfigPath);
+  }
+
   async snapshotServiceState(paths) {
     let plist;
     try {
@@ -227,45 +273,123 @@ export class MacPlatformAdapter {
       if (error.code !== "ENOENT") throw error;
       plist = { exists: false, content: null, mode: null };
     }
-    return { plist, running: await this.isServiceRunning() };
+    const appExists = await this.pathExists(paths.serviceManagerPath);
+    let runtimeConfig = { exists: false, content: null, mode: null };
+    if (appExists && paths.serviceRuntimeConfigPath) {
+      try {
+        const metadataPromise = this.fileSystem.stat
+          ? this.fileSystem.stat(paths.serviceRuntimeConfigPath).catch(() => null)
+          : Promise.resolve(null);
+        const [content, metadata] = await Promise.all([
+          this.fileSystem.readFile(paths.serviceRuntimeConfigPath, "utf8"),
+          metadataPromise,
+        ]);
+        runtimeConfig = { exists: true, content, mode: metadata?.mode };
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    const running = await this.isServiceRunning()
+      || (plist.exists && await this.isLaunchdServiceRunning(legacyServiceTarget(this.uid)));
+    return {
+      app: {
+        exists: appExists,
+        status: appExists ? await this.serviceManagerStatus(paths) : "not-found",
+        runtimeConfig,
+      },
+      plist,
+      running,
+    };
   }
 
   async installService({ cliPath, paths, start = true }) {
-    await this.fileSystem.mkdir(path.dirname(paths.launchAgentPath), { recursive: true });
+    const stagingAppPath = path.join(paths.serviceDir, ".MineCodex.app.installing");
+    assertOwnedServicePaths(paths);
+    await this.stopService(paths, { ignoreErrors: false });
+    await this.fileSystem.mkdir(paths.serviceDir, { recursive: true, mode: 0o700 });
     await this.fileSystem.mkdir(paths.logsDir, { recursive: true, mode: 0o700 });
-    const plist = buildLaunchAgent({ nodePath: process.execPath, cliPath, paths });
-    await this.fileSystem.writeFile(paths.launchAgentPath, plist, { mode: 0o600 });
-    await this.stopService({ ignoreErrors: true });
-    await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
-    if (start) {
-      await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
-    } else {
-      await this.stopService({ ignoreErrors: true });
+    await this.writeServiceRuntimeConfig(
+      paths,
+      buildServiceRuntimeConfig({ nodePath: process.execPath, cliPath, paths }),
+    );
+    await this.fileSystem.rm(stagingAppPath, { recursive: true, force: true });
+    try {
+      await this.execFile("/usr/bin/ditto", [paths.serviceBundleSource, stagingAppPath]);
+      await this.execFile("/usr/bin/codesign", ["--verify", "--deep", "--strict", stagingAppPath]);
+      await this.fileSystem.rm(paths.serviceAppPath, { recursive: true, force: true });
+      await this.fileSystem.rename(stagingAppPath, paths.serviceAppPath);
+    } catch (error) {
+      await this.fileSystem.rm(stagingAppPath, { recursive: true, force: true }).catch(() => {});
+      throw error;
     }
+    await this.fileSystem.unlink(paths.launchAgentPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    if (start) await this.startService(paths);
   }
 
-  async stopService({ ignoreErrors = false } = {}) {
+  async stopService(paths, { ignoreErrors = false } = {}) {
+    let managerError = null;
+    if (paths?.serviceManagerPath && await this.pathExists(paths.serviceManagerPath)) {
+      try {
+        await this.execFile(paths.serviceManagerPath, ["unregister"]);
+      } catch (error) {
+        managerError = error;
+      }
+    }
     try {
       await this.execFile("/bin/launchctl", ["bootout", serviceTarget(this.uid)]);
     } catch (error) {
-      if (!ignoreErrors || !serviceIsAbsent(error)) throw error;
+      if (!serviceIsAbsent(error)) throw error;
     }
+    try {
+      await this.execFile("/bin/launchctl", ["bootout", legacyServiceTarget(this.uid)]);
+    } catch (error) {
+      if (!serviceIsAbsent(error)) throw error;
+    }
+    if (managerError && !ignoreErrors) throw managerError;
   }
 
   async startService(paths) {
-    if (!(await this.isServiceRunning())) {
-      await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
+    const status = await this.serviceManagerStatus(paths);
+    if (status === "requires-approval") {
+      throw new Error(
+        "MineCodex background service is disabled. Enable MineCodex in System Settings > General > Login Items & Extensions, then run `mcx install` again.",
+      );
+    }
+    if (status !== "enabled") {
+      const { stdout } = await this.execFile(paths.serviceManagerPath, ["register"]);
+      const registeredStatus = appServiceStatus(stdout);
+      if (registeredStatus !== "enabled") {
+        throw new Error(`MineCodex background service registration requires attention: ${registeredStatus}`);
+      }
     }
     await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
   }
 
   async assertServiceStopped() {
-    if (await this.isServiceRunning()) throw new Error("MineCodex launchd service is still running.");
+    const [current, legacy] = await Promise.all([
+      this.isServiceRunning(),
+      this.isLaunchdServiceRunning(legacyServiceTarget(this.uid)),
+    ]);
+    if (current || legacy) throw new Error("MineCodex launchd service is still running.");
   }
 
   async restoreServiceState(snapshot, { cliPath, paths } = {}) {
-    await this.stopService({ ignoreErrors: true });
+    await this.removeService(paths);
     await this.assertServiceStopped();
+    if (snapshot?.app?.exists) {
+      await this.installService({ cliPath, paths, start: false });
+      if (snapshot.app.runtimeConfig?.exists) {
+        await this.writeServiceRuntimeConfig(
+          paths,
+          snapshot.app.runtimeConfig.content,
+          snapshot.app.runtimeConfig.mode ? snapshot.app.runtimeConfig.mode & 0o777 : 0o600,
+        );
+      }
+      if (snapshot.app.status === "enabled") await this.startService(paths);
+      return snapshot;
+    }
     if (snapshot?.plist?.exists) {
       await this.fileSystem.mkdir(path.dirname(paths.launchAgentPath), { recursive: true });
       await this.fileSystem.writeFile(paths.launchAgentPath, snapshot.plist.content, {
@@ -276,20 +400,29 @@ export class MacPlatformAdapter {
         if (error.code !== "ENOENT") throw error;
       });
     }
-    if (snapshot?.running) {
-      if (!snapshot?.plist?.exists) throw new Error("Cannot restore a running service without its plist.");
+    if (snapshot?.running && snapshot?.plist?.exists) {
       await this.execFile("/bin/launchctl", ["bootstrap", `gui/${this.uid}`, paths.launchAgentPath]);
-      await this.execFile("/bin/launchctl", ["kickstart", "-k", serviceTarget(this.uid)]);
+      await this.execFile("/bin/launchctl", ["kickstart", "-k", legacyServiceTarget(this.uid)]);
     }
     return snapshot;
   }
 
   async removeService(paths) {
-    await this.stopService({ ignoreErrors: true });
+    assertOwnedServicePaths(paths);
+    await this.stopService(paths, { ignoreErrors: false });
     await this.assertServiceStopped();
     await this.fileSystem.unlink(paths.launchAgentPath).catch((error) => {
       if (error.code !== "ENOENT") throw error;
     });
+    if (paths.serviceRuntimeConfigPath) {
+      await this.fileSystem.unlink(paths.serviceRuntimeConfigPath).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+      await this.fileSystem.unlink(`${paths.serviceRuntimeConfigPath}.installing`).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+    await this.fileSystem.rm(paths.serviceDir, { recursive: true, force: true });
   }
 
   async listCodexProcesses() {

package/packages/runtime-host/README.md

@@ -141,6 +141,9 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
 
 - 只在 top frame 安装 Runtime，绝不向业务 iframe 注入 binding token。
 - Watch / refresh 串行；已连接 Renderer 不重复连接，关闭 target 会清理状态。
+- 本地 Surface 注入前先启用 CSP bypass 并注册 document-start 脚本；缺少初始化标记的
+  首次或旧版 document 只受控 reload 一次。标记存在时，新的 RuntimeHost 会话直接
+  替换旧 Runtime，不刷新当前 Codex 页面。
 - 入口由 Renderer 内的 MutationObserver 幂等挂载，React 重绘不会产生重复入口。
 - Summary 根据对话主区域宽度连续派生 `overlay / shift / gutter`：小于 1096px
   使用临时 Popover；1096–1535px 预留 316px 并把对话内容左移 158px；更宽时

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

@@ -5,6 +5,8 @@ import path from "node:path";
 
 const RUNTIME_VERSION = 99;
 const HOST_BINDING_NAME = "__codexPersonalHostAction";
+const CSP_BOOTSTRAP_VERSION = 1;
+const CSP_BOOTSTRAP_KEY = "__mineCodexCspBootstrapVersion";
 
 export const RESPONSIVE_SUMMARY_LAYOUT = Object.freeze({
   contentBaseWidth: 736,
@@ -3564,6 +3566,14 @@ export function createRuntimeReadyContract({
   };
 }
 
+function createDocumentBootstrapSource(source) {
+  return `window[${JSON.stringify(CSP_BOOTSTRAP_KEY)}] = ${CSP_BOOTSTRAP_VERSION};\n${source}`;
+}
+
+function documentBootstrapExpression() {
+  return `window[${JSON.stringify(CSP_BOOTSTRAP_KEY)}] === ${CSP_BOOTSTRAP_VERSION}`;
+}
+
 async function connect(url) {
   const socket = new WebSocket(url);
   const pending = new Map();
@@ -4250,7 +4260,20 @@ export class CodexRuntime {
           bindingToken,
           runtimeSessionId: this.runtimeSessionId,
         });
-        const script = await client.send("Page.addScriptToEvaluateOnNewDocument", { source });
+        const bootstrapExpression = documentBootstrapExpression();
+        const script = await client.send("Page.addScriptToEvaluateOnNewDocument", {
+          source: createDocumentBootstrapSource(source),
+        });
+        const documentWasBootstrapped = Boolean(evaluationValue(await client.send("Runtime.evaluate", {
+          expression: bootstrapExpression,
+          returnByValue: true,
+        })));
+        if (!documentWasBootstrapped) {
+          const pageLoaded = client.waitFor("Page.loadEventFired", 20_000);
+          await client.send("Page.reload");
+          await pageLoaded;
+          await waitForExpression(client, bootstrapExpression);
+        }
         await waitForExpression(
           client,
           `document.readyState === "interactive" || document.readyState === "complete"`,