@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/mcp-panel.ts

@@ -1,14 +1,17 @@
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { atomicWriteFile } from "../atomic-write.js";
+import { readBoundedTextFile } from "../bounded-file.js";
 import type { PiMcpServerSnapshot } from "../services.js";
 
 type McpPanelServer = Omit<PiMcpServerSnapshot, "command"> & { executable: string; toolCount: number; statusSource: "runtime" };
 type McpPanelHealth = { serverId: string; status: string; severity: "ok" | "warning"; suggestions: string[] };
+const maxPatchBytes = 2 * 1024 * 1024;
 
 export interface McpPanelPluginConfig {
   patchPath?: string;
@@ -95,17 +98,20 @@ export default {
         });
         if (metadata?.isSymbolicLink() || (metadata !== undefined && !metadata.isFile()))
           throw new Error("MCP profile patch target must be a regular file and cannot be a symbolic link");
-        const existing = metadata === undefined ? "" : await readFile(patchTarget, "utf8");
+        let existing = "";
+        if (metadata !== undefined) {
+          existing = await readBoundedTextFile(patchTarget, maxPatchBytes, "MCP profile patch");
+        }
         const rowPattern = new RegExp(`^- id: mcp-${serverId}\\s*$`, "mu");
         if (rowPattern.test(existing)) throw new Error(`MCP server patch already exists: ${serverId}`);
+        const next = `${existing.trimEnd()}${existing.trimEnd() === "" ? "" : "\n"}${fragment}`;
+        if (Buffer.byteLength(next, "utf8") > maxPatchBytes) throw new Error("MCP profile patch exceeds the 2 MiB output limit");
         const backup = `${patchTarget}.bak`;
-        await writeFile(backup, existing, { encoding: "utf8", mode: 0o600, flag: "wx" }).catch((error: unknown) => {
-          if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST")) throw error;
-        });
+        await atomicWriteFile(backup, existing, { encoding: "utf8", mode: 0o600 });
         const temporary = `${patchTarget}.${randomUUID()}.tmp`;
         let renamed = false;
         try {
-          await writeFile(temporary, `${existing.trimEnd()}${existing.trimEnd() === "" ? "" : "\n"}${fragment}`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+          await writeFile(temporary, next, { encoding: "utf8", mode: 0o600, flag: "wx" });
           await rename(temporary, patchTarget);
           renamed = true;
         } finally {
@@ -125,13 +131,17 @@ export default {
         label: "MCP panel",
         description: "Inspect MCP status and tools, derive health suggestions, and preview or explicitly apply a backed-up profile patch.",
         promptSnippet: "inspect MCP status or preview a server profile patch",
-        parameters: Type.Object({
-          action: Type.Union([Type.Literal("status"), Type.Literal("tools"), Type.Literal("health"), Type.Literal("preview"), Type.Literal("apply")]),
-          serverId: Type.Optional(Type.String({ description: "Configured or running MCP server id" })),
-          command: Type.Optional(Type.Array(Type.String(), { description: "MCP server executable and arguments" })),
-          autoStart: Type.Optional(Type.Boolean({ description: "Start the configured server with the runtime" })),
-          confirm: Type.Optional(Type.Boolean({ description: "Must be true before applying a patch" })),
-        }),
+        parameters: Type.Object(
+          {
+            action: Type.Union([Type.Literal("status"), Type.Literal("tools"), Type.Literal("health"), Type.Literal("preview"), Type.Literal("apply")]),
+            serverId: Type.Optional(Type.String({ description: "Configured or running MCP server id" })),
+            command: Type.Optional(Type.Array(Type.String(), { description: "MCP server executable and arguments" })),
+            autoStart: Type.Optional(Type.Boolean({ description: "Start the configured server with the runtime" })),
+            confirm: Type.Optional(Type.Boolean({ description: "Must be true before applying a patch" })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
           await Promise.resolve();
           const servers = snapshot();
@@ -174,14 +184,20 @@ export default {
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "mcp-panel",
-      pluginId: "@pi-harness/core/plugins/mcp-panel",
-      title: "MCP Console",
-      description: "查看 MCP 服务器状态、桥接工具和健康建议。",
-      icon: "⌘",
-      read: () => ({ servers: snapshot(), statusSource: "runtime", writesEnabled: patchTarget !== undefined, patchPath: patchTarget ?? null }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "mcp-panel",
+        pluginId: "@pi-harness/core/plugins/mcp-panel",
+        title: "MCP Console",
+        description: "查看 MCP 服务器状态、桥接工具和健康建议。",
+        icon: "⌘",
+        read: () => ({ servers: snapshot(), statusSource: "runtime", writesEnabled: patchTarget !== undefined, patchPath: patchTarget ?? null }),
+      });
+    } catch (error) {
+      unregister();
+      throw error;
+    }
     context.effect(() => () => {
       unregister();
       disposePanel();

package/packages/core/src/plugins/memory.ts

@@ -1,10 +1,11 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { lstat, mkdir, opendir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { readBoundedTextFile } from "../bounded-file.js";
 
 const defaultFileName = "memory.json";
 const maxKeyLength = 128;
@@ -12,6 +13,12 @@ const maxValueBytes = 64 * 1024;
 const maxTagLength = 64;
 const maxTags = 16;
 const maxEntries = 500;
+const lockRetryMs = 25;
+const lockTimeoutMs = 10_000;
+const staleLockMs = 30_000;
+const maxLockOwnerBytes = 1024;
+const memoryFileOverheadBytes = 1024;
+const memoryEntryOverheadBytes = maxValueBytes + maxTags * maxTagLength * 4 + maxKeyLength * 8 + 8 * 1024;
 
 type Memory = { id: string; key: string; value: string; tags: string[]; createdAt: string; updatedAt: string };
 type MemoryFile = { version: 1; memories: Memory[] };
@@ -49,45 +56,233 @@ function normalizeTags(tags: readonly string[] | undefined): string[] {
   return values;
 }
 
+function ownData(value: unknown, key: PropertyKey): unknown {
+  if (value === null || typeof value !== "object") return undefined;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isMemory(value: unknown): value is Memory {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return false;
+  } catch {
+    return false;
+  }
+  const id = ownData(value, "id");
+  const key = ownData(value, "key");
+  const storedValue = ownData(value, "value");
+  const tags = ownData(value, "tags");
+  const createdAt = ownData(value, "createdAt");
+  const updatedAt = ownData(value, "updatedAt");
+  return (
+    typeof id === "string" &&
+    id.length > 0 &&
+    id.length <= maxKeyLength &&
+    typeof key === "string" &&
+    key.trim().length > 0 &&
+    key.length <= maxKeyLength &&
+    typeof storedValue === "string" &&
+    storedValue.trim().length > 0 &&
+    Buffer.byteLength(storedValue, "utf8") <= maxValueBytes &&
+    Array.isArray(tags) &&
+    tags.length <= maxTags &&
+    tags.every((tag) => typeof tag === "string" && tag.trim().length > 0 && tag.length <= maxTagLength) &&
+    typeof createdAt === "string" &&
+    Number.isFinite(Date.parse(createdAt)) &&
+    typeof updatedAt === "string" &&
+    Number.isFinite(Date.parse(updatedAt))
+  );
+}
+
+async function readMemoryFile(filePath: string, entryLimit: number): Promise<Memory[]> {
+  let source: string;
+  try {
+    const maxFileBytes = memoryFileOverheadBytes + entryLimit * memoryEntryOverheadBytes;
+    source = await readBoundedTextFile(filePath, maxFileBytes, "Memory file");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source) as unknown;
+  } catch (error) {
+    throw new Error("Memory file contains invalid JSON", { cause: error });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Memory file has an unsupported format");
+  const file = parsed as Partial<MemoryFile>;
+  if (file.version !== 1 || !Array.isArray(file.memories)) throw new Error("Memory file has an unsupported format");
+  if (!file.memories.every(isMemory)) throw new Error("Memory file contains invalid memories");
+  if (file.memories.length > entryLimit) throw new Error(`Memory file exceeds its ${entryLimit}-entry limit`);
+  const keys = new Set(file.memories.map((memory) => memory.key));
+  const ids = new Set(file.memories.map((memory) => memory.id));
+  if (keys.size !== file.memories.length || ids.size !== file.memories.length) throw new Error("Memory file contains duplicate memories");
+  return file.memories;
+}
+
+async function writeMemoryFile(filePath: string, memories: Memory[]): Promise<void> {
+  const payload = JSON.stringify({ version: 1, memories } satisfies MemoryFile, null, 2);
+  await mkdir(dirname(filePath), { recursive: true });
+  const temporary = join(dirname(filePath), `.${basename(filePath)}.${randomUUID()}.tmp`);
+  let renamed = false;
+  try {
+    await writeFile(temporary, payload, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, filePath);
+    renamed = true;
+  } finally {
+    if (!renamed) await rm(temporary, { force: true }).catch(() => undefined);
+  }
+}
+
+function memoryLockOwnerIsAlive(value: unknown): boolean | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const pid = (value as Record<string, unknown>).pid;
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ESRCH" ? false : true;
+  }
+}
+
+function sameFile(left: Awaited<ReturnType<typeof lstat>>, right: Awaited<ReturnType<typeof lstat>>): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function reclaimStaleMemoryLock(lockPath: string, lockMetadata: Awaited<ReturnType<typeof lstat>>): Promise<boolean> {
+  if (Date.now() - Number(lockMetadata.mtimeMs) <= staleLockMs) return false;
+  let directory;
+  try {
+    directory = await opendir(lockPath, { bufferSize: 1 });
+  } catch {
+    return false;
+  }
+  let ownerName: string | undefined;
+  try {
+    const owner = await directory.read();
+    const extra = await directory.read();
+    if (owner === null || extra !== null || !/^[a-z0-9-]{1,64}\.owner$/iu.test(owner.name)) return false;
+    ownerName = owner.name;
+  } finally {
+    await directory.close().catch(() => undefined);
+  }
+  const ownerPath = resolve(lockPath, ownerName);
+  let ownerMetadata;
+  try {
+    ownerMetadata = await lstat(ownerPath);
+  } catch {
+    return false;
+  }
+  if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink() || Date.now() - Number(ownerMetadata.mtimeMs) <= staleLockMs) return false;
+  let owner: unknown;
+  try {
+    owner = JSON.parse(await readBoundedTextFile(ownerPath, maxLockOwnerBytes, "Memory lock owner")) as unknown;
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) return false;
+  }
+  if (memoryLockOwnerIsAlive(owner) === true) return false;
+  let currentLockMetadata;
+  let currentOwnerMetadata;
+  try {
+    [currentLockMetadata, currentOwnerMetadata] = await Promise.all([lstat(lockPath), lstat(ownerPath)]);
+  } catch {
+    return false;
+  }
+  if (!sameFile(lockMetadata, currentLockMetadata) || !sameFile(ownerMetadata, currentOwnerMetadata)) return false;
+  try {
+    await unlink(ownerPath);
+    await rmdir(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function acquireMemoryLock(lockPath: string): Promise<() => Promise<void>> {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const deadline = Date.now() + lockTimeoutMs;
+  while (true) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      const token = randomUUID();
+      const ownerPath = resolve(lockPath, `${token}.owner`);
+      try {
+        await writeFile(ownerPath, JSON.stringify({ pid: process.pid, token }), { encoding: "utf8", mode: 0o600, flag: "wx" });
+      } catch (error) {
+        await rmdir(lockPath).catch(() => undefined);
+        throw new Error("Could not establish memory lock ownership", { cause: error });
+      }
+      return async () => {
+        try {
+          await unlink(ownerPath);
+        } catch (error) {
+          throw new Error("Memory lock ownership was lost before release", { cause: error });
+        }
+        try {
+          await rmdir(lockPath);
+        } catch (error) {
+          throw new Error("Could not safely release memory file lock", { cause: error });
+        }
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw new Error("Could not acquire memory file lock", { cause: error });
+      let metadata;
+      try {
+        metadata = await lstat(lockPath);
+      } catch (inspectionError) {
+        if ((inspectionError as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw new Error("Could not inspect memory file lock", { cause: inspectionError });
+      }
+      if (metadata.isSymbolicLink()) throw new Error("Memory file lock must not be a symbolic link", { cause: error });
+      if (!metadata.isDirectory()) throw new Error("Memory file lock must be a directory", { cause: error });
+      if (await reclaimStaleMemoryLock(lockPath, metadata)) continue;
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for memory file lock", { cause: error });
+      await new Promise<void>((resolve) => setTimeout(resolve, lockRetryMs));
+    }
+  }
+}
+
 export default {
   name: "pi-memory",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
   Config,
   apply(context: Context, config: MemoryPluginConfig) {
     const filePath = normalizeFilePath(context.piHarnessLaunch.agentDir, config.fileName);
-    const entryLimit = Math.max(1, Math.min(maxEntries, Math.trunc(config.maxEntries ?? maxEntries)));
+    const configuredEntryLimit = config.maxEntries;
+    const entryLimit =
+      typeof configuredEntryLimit === "number" && Number.isFinite(configuredEntryLimit)
+        ? Math.max(1, Math.min(maxEntries, Math.trunc(configuredEntryLimit)))
+        : maxEntries;
     let memories: Memory[] = [];
-    let loaded = false;
-    let loading: Promise<void> | undefined;
-    let writeQueue = Promise.resolve();
+    let mutationQueue = Promise.resolve();
     let last: MemorySearchReport | undefined;
-    const load = async (): Promise<void> => {
-      if (loaded) return;
-      if (loading !== undefined) return loading;
-      loading = (async () => {
+    const refresh = async (): Promise<void> => {
+      memories = await readMemoryFile(filePath, entryLimit);
+    };
+    const mutate = async <T>(operation: (current: Memory[]) => { memories: Memory[]; result: T }): Promise<T> => {
+      let result: T | undefined;
+      const run = async (): Promise<void> => {
+        const release = await acquireMemoryLock(`${filePath}.lock`);
         try {
-          const parsed = JSON.parse(await readFile(filePath, "utf8")) as Partial<MemoryFile>;
-          if (parsed.version !== 1 || !Array.isArray(parsed.memories)) throw new Error("Memory file has an unsupported format");
-          memories = parsed.memories.filter(
-            (item): item is Memory => typeof item === "object" && item !== null && typeof item.key === "string" && typeof item.value === "string",
-          );
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-          memories = [];
+          const current = await readMemoryFile(filePath, entryLimit);
+          const next = operation(current);
+          await writeMemoryFile(filePath, next.memories);
+          memories = next.memories;
+          result = next.result;
+        } finally {
+          await release();
         }
-        loaded = true;
-      })();
-      return loading;
-    };
-    const persist = async (): Promise<void> => {
-      const payload = JSON.stringify({ version: 1, memories } satisfies MemoryFile, null, 2);
-      writeQueue = writeQueue.then(async () => {
-        await mkdir(dirname(filePath), { recursive: true });
-        const temporary = join(dirname(filePath), `.${basename(filePath)}.${randomUUID()}.tmp`);
-        await writeFile(temporary, payload, { encoding: "utf8", mode: 0o600 });
-        await rename(temporary, filePath);
-      });
-      await writeQueue;
+      };
+      mutationQueue = mutationQueue.catch(() => undefined).then(run);
+      await mutationQueue;
+      return result as T;
     };
     const unregisterSet = context.piTools.register(
       defineTool({
@@ -95,18 +290,19 @@ export default {
         label: "Remember fact",
         description: "Persist one explicit fact in the Pi Harness memory store, replacing an existing value with the same key.",
         promptSnippet: "save an explicit fact for future sessions",
-        parameters: Type.Object({ key: Type.String(), value: Type.String(), tags: Type.Optional(Type.Array(Type.String())) }),
+        parameters: Type.Object({ key: Type.String(), value: Type.String(), tags: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<Memory>> {
-          await load();
           const key = normalizeKey(params.key);
           const value = normalizeValue(params.value);
           const tags = normalizeTags(params.tags);
-          const now = new Date().toISOString();
-          const existing = memories.find((item) => item.key === key);
-          const memory: Memory =
-            existing === undefined ? { id: randomUUID(), key, value, tags, createdAt: now, updatedAt: now } : { ...existing, value, tags, updatedAt: now };
-          memories = [memory, ...memories.filter((item) => item.key !== key)].slice(0, entryLimit);
-          await persist();
+          const memory = await mutate((current) => {
+            const now = new Date().toISOString();
+            const existing = current.find((item) => item.key === key);
+            const next: Memory =
+              existing === undefined ? { id: randomUUID(), key, value, tags, createdAt: now, updatedAt: now } : { ...existing, value, tags, updatedAt: now };
+            return { memories: [next, ...current.filter((item) => item.key !== key)].slice(0, entryLimit), result: next };
+          });
           return { content: [{ type: "text", text: `Memory saved: ${key}` }], details: memory };
         },
       }),
@@ -117,9 +313,10 @@ export default {
         label: "Search memories",
         description: "Search explicit cross-session memories by key, value, or tag.",
         promptSnippet: "search remembered facts from earlier sessions",
-        parameters: Type.Object({ query: Type.String() }),
+        parameters: Type.Object({ query: Type.String() }, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<MemorySearchReport>> {
-          await load();
+          await refresh();
           const query = params.query.trim().toLocaleLowerCase();
           if (query.length < 2 || query.length > maxKeyLength) throw new Error(`Memory search query must contain 2-${maxKeyLength} characters`);
           const results = memories.filter((item) => [item.key, item.value, ...item.tags].some((field) => field.toLocaleLowerCase().includes(query)));
@@ -142,30 +339,38 @@ export default {
         label: "Forget memory",
         description: "Delete one explicit memory by key. Confirmation is required.",
         promptSnippet: "forget a stored memory after confirmation",
-        parameters: Type.Object({ key: Type.String(), confirm: Type.Boolean() }),
+        parameters: Type.Object({ key: Type.String(), confirm: Type.Boolean() }, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<{ key: string; removed: boolean }>> {
-          await load();
           const key = normalizeKey(params.key);
           if (params.confirm !== true) throw new Error("Deleting a memory requires confirm=true");
-          const before = memories.length;
-          memories = memories.filter((item) => item.key !== key);
-          const removed = memories.length !== before;
-          if (removed) await persist();
+          const removed = await mutate((current) => {
+            const next = current.filter((item) => item.key !== key);
+            return { memories: next, result: next.length !== current.length };
+          });
           return { content: [{ type: "text", text: removed ? `Memory deleted: ${key}` : `Memory not found: ${key}` }], details: { key, removed } };
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "memory-panel",
-      pluginId: "@pi-harness/core/plugins/memory",
-      title: "Memory",
-      description: "只保存 Agent 明确写入的事实，跨会话持久化并支持检索与删除。",
-      icon: "▣",
-      read: async () => {
-        await load();
-        return { filePath, count: memories.length, last: last ?? null, memories: memories.slice(0, 8) };
-      },
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "memory-panel",
+        pluginId: "@pi-harness/core/plugins/memory",
+        title: "Memory",
+        description: "只保存 Agent 明确写入的事实，跨会话持久化并支持检索与删除。",
+        icon: "▣",
+        read: async () => {
+          await refresh();
+          return { filePath, count: memories.length, last: last ?? null, memories: memories.slice(0, 8) };
+        },
+      });
+    } catch (error) {
+      unregisterSet();
+      unregisterSearch();
+      unregisterDelete();
+      throw error;
+    }
     context.effect(() => () => {
       unregisterSet();
       unregisterSearch();

package/packages/core/src/plugins/mirage-bridge.ts

@@ -132,7 +132,8 @@ export default {
         label: "Check Mirage CLI",
         description: "Check whether the official Mirage virtual-terminal CLI is available and report its configured workspace.",
         promptSnippet: "check the official Mirage virtual terminal integration",
-        parameters: Type.Object({}),
+        parameters: Type.Object({}, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(): Promise<AgentToolResult<MirageBridgeState>> {
           const details = await doctor();
           return {
@@ -155,21 +156,32 @@ export default {
         label: "Execute in Mirage",
         description: "Pass one command to the official Mirage virtual terminal in the configured virtual workspace.",
         promptSnippet: "run a command inside the configured Mirage virtual workspace",
-        parameters: Type.Object({ command: Type.String({ description: "Command interpreted by Mirage, not the host shell" }) }),
+        parameters: Type.Object(
+          { command: Type.String({ description: "Command interpreted by Mirage, not the host shell" }) },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<MirageRun>> {
           const details = await run(params.command);
           return { content: [{ type: "text", text: `Mirage exited with ${details.exitCode ?? "unknown"}.\n${details.output}` }], details };
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "mirage-bridge-panel",
-      pluginId: "@pi-harness/core/plugins/mirage-bridge",
-      title: "Mirage Bridge",
-      description: "连接官方 Mirage 虚拟终端，在配置的虚拟工作区中执行命令。",
-      icon: "◇",
-      read: () => ({ ...state, timeoutMs }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "mirage-bridge-panel",
+        pluginId: "@pi-harness/core/plugins/mirage-bridge",
+        title: "Mirage Bridge",
+        description: "连接官方 Mirage 虚拟终端，在配置的虚拟工作区中执行命令。",
+        icon: "◇",
+        read: () => ({ ...state, timeoutMs }),
+      });
+    } catch (error) {
+      unregisterDoctor();
+      unregisterExecute();
+      throw error;
+    }
     context.effect(() => () => {
       unregisterDoctor();
       unregisterExecute();