@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/test/obsidian-sync.test.ts

@@ -0,0 +1,57 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { afterEach, describe, expect, test } from "vitest";
+import obsidianSyncPlugin from "../src/plugins/obsidian-sync.js";
+import { provideLaunchContext, PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+const contexts: Context[] = [];
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "pi-harness-obsidian-"));
+  const vault = join(root, "vault");
+  const context = new Context();
+  const tools = new PiToolRegistry();
+  const panels = new PiPluginUiRegistry();
+  provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(obsidianSyncPlugin, { vaultPath: vault });
+  contexts.push(context);
+  const tool = tools.snapshot().customTools.find((item) => item.name === "obsidian_sync");
+  if (tool === undefined) throw new Error("obsidian_sync was not registered");
+  return { root, vault, context, tools, panels, tool };
+}
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map((context) => context.fiber.dispose()));
+});
+
+describe("Obsidian sync", () => {
+  test("writes a confirmed Markdown note inside the configured vault", async () => {
+    const { vault, tool, panels } = await fixture();
+    expect(tool.executionMode).toBe("sequential");
+    expect(tool.parameters).toMatchObject({ type: "object", additionalProperties: false });
+    await expect(
+      tool.execute("sync", { relativePath: "notes/today.md", content: "# Today", confirm: true }, undefined, undefined, {} as never),
+    ).resolves.toMatchObject({
+      details: { relativePath: "notes/today.md", bytes: 7 },
+    });
+    await expect(readFile(join(vault, "notes/today.md"), "utf8")).resolves.toBe("# Today");
+    await expect(panels.snapshot()).resolves.toMatchObject([{ data: { configured: true, last: { relativePath: "notes/today.md" } } }]);
+  });
+
+  test("rejects unconfirmed or escaping paths and cleans up", async () => {
+    const { context, tools, panels, tool } = await fixture();
+    await expect(tool.execute("no", { relativePath: "x.md", content: "x", confirm: false }, undefined, undefined, {} as never)).rejects.toThrow(
+      /confirm=true/iu,
+    );
+    await expect(tool.execute("escape", { relativePath: "../x.md", content: "x", confirm: true }, undefined, undefined, {} as never)).rejects.toThrow(
+      /inside/iu,
+    );
+    await context.fiber.dispose();
+    expect(tools.snapshot().customTools).toHaveLength(0);
+    await expect(panels.snapshot()).resolves.toHaveLength(0);
+  });
+});

package/packages/core/test/openpets.test.ts

@@ -0,0 +1,273 @@
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test } from "vitest";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+import openPetsPlugin from "../src/plugins/openpets.js";
+
+type OpenPetsFixture = {
+  readonly context: Context;
+  readonly tool: ReturnType<PiToolRegistry["snapshot"]>["customTools"][number];
+  readonly panels: PiPluginUiRegistry;
+  readonly entries: unknown[];
+};
+
+async function createOpenPets(
+  options: { entries?: unknown[]; config?: Record<string, unknown>; append?: (customType: string, data: unknown) => string } = {},
+): Promise<OpenPetsFixture> {
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const tools = new PiToolRegistry();
+  const entries = options.entries ?? [];
+  context.provide("piSession", {
+    manager: {
+      getEntries: () => entries,
+      appendCustomEntry:
+        options.append ??
+        ((customType: string, data: unknown) => {
+          entries.push({ type: "custom", customType, data });
+          return String(entries.length);
+        }),
+    },
+  } as never);
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(openPetsPlugin, options.config);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "pet_react");
+  if (tool === undefined) throw new Error("OpenPets tool was not registered");
+  return { context, tool, panels, entries };
+}
+
+describe("OpenPets boundaries", () => {
+  test("declares and enforces a bounded companion name configuration", async () => {
+    expect(openPetsPlugin.Config.dict?.name?.meta).toMatchObject({ min: 1, max: 128 });
+
+    for (const config of [{ name: "" }, { name: "x".repeat(129) }, { name: "pet\0name" }, { unknown: true }]) {
+      await expect(createOpenPets({ config })).rejects.toThrow(/(?:OpenPets.*(?:name|config)|invalid config)/iu);
+    }
+  });
+
+  test("declares strict actions and validates descriptor-only parameters before persisting", async () => {
+    const fixture = await createOpenPets();
+    let accessed = false;
+    const accessor = {} as { action?: string };
+    Object.defineProperty(accessor, "action", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("OpenPets action getter executed");
+      },
+    });
+    try {
+      expect(fixture.tool.parameters).toMatchObject({
+        properties: {
+          action: { anyOf: [{ const: "status" }, { const: "feed" }, { const: "play" }, { const: "set_mood" }] },
+          mood: { anyOf: [{ const: "idle" }, { const: "focused" }, { const: "happy" }, { const: "concerned" }] },
+        },
+      });
+      await expect(fixture.tool.execute("accessor", accessor, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*data properties/iu);
+      expect(accessed).toBe(false);
+      await expect(fixture.tool.execute("unknown", { action: "status", unknown: true }, undefined, undefined, {} as never)).rejects.toThrow(
+        /unknown property/iu,
+      );
+      await expect(fixture.tool.execute("null", null, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*object/iu);
+      await expect(fixture.tool.execute("date", new Date(), undefined, undefined, {} as never)).rejects.toThrow(/parameters.*plain object/iu);
+      await expect(fixture.tool.execute("action", { action: "dance" }, undefined, undefined, {} as never)).rejects.toThrow(/action must be/iu);
+      await expect(fixture.tool.execute("mood", { action: "set_mood", mood: "sleepy" }, undefined, undefined, {} as never)).rejects.toThrow(/mood must be/iu);
+      await expect(fixture.tool.execute("ignored", { action: "feed", mood: "happy" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /mood.*only.*set_mood/iu,
+      );
+      const caller = new AbortController();
+      caller.abort(new Error("cancel pet action"));
+      await expect(fixture.tool.execute("cancelled", { action: "feed" }, caller.signal, undefined, {} as never)).rejects.toThrow(/cancelled/iu);
+      expect(fixture.entries).toHaveLength(0);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("restores a valid recent state while keeping the configured companion name", async () => {
+    const entries = [
+      {
+        type: "custom",
+        customType: "pi-harness/openpets",
+        data: {
+          name: "old name",
+          mood: "happy",
+          energy: 73,
+          interactions: 9,
+          lastEvent: "play",
+          updatedAt: "2026-09-05T10:00:00.000Z",
+        },
+      },
+    ];
+    const fixture = await createOpenPets({ entries, config: { name: "Configured Pet" } });
+    try {
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([
+        {
+          data: {
+            name: "Configured Pet",
+            mood: "happy",
+            energy: 73,
+            interactions: 9,
+            lastEvent: "play",
+            updatedAt: "2026-09-05T10:00:00.000Z",
+            recovery: { sessionEntries: 1, scanned: 1, truncated: false, restored: true },
+            limits: { nameCharacters: 128, recoveryEntries: 10_000 },
+          },
+        },
+      ]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("does not invoke accessors while recovering malformed persisted state", async () => {
+    let accessed = false;
+    const data = {} as Record<string, unknown>;
+    Object.defineProperty(data, "mood", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("persisted OpenPets getter executed");
+      },
+    });
+    const fixture = await createOpenPets({ entries: [{ type: "custom", customType: "pi-harness/openpets", data }] });
+    try {
+      expect(accessed).toBe(false);
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([
+        { data: { name: "Pi", mood: "idle", energy: 80, interactions: 0, lastEvent: "session_start", recovery: { restored: false } } },
+      ]);
+      expect(accessed).toBe(false);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("does not recover stale companion state outside the bounded entry window", async () => {
+    const entries = [
+      {
+        type: "custom",
+        customType: "pi-harness/openpets",
+        data: { name: "stale", mood: "concerned", energy: 1, interactions: 99, lastEvent: "feed", updatedAt: "2026-01-01T00:00:00.000Z" },
+      },
+      ...Array.from({ length: 10_000 }, () => ({ type: "message" })),
+    ];
+    const fixture = await createOpenPets({ entries });
+    try {
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([
+        {
+          data: {
+            name: "Pi",
+            mood: "idle",
+            energy: 80,
+            interactions: 0,
+            recovery: { sessionEntries: 10_001, scanned: 10_000, truncated: true, restored: false },
+          },
+        },
+      ]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("saturates interaction counts and publishes immutable tool, persistence, and panel snapshots", async () => {
+    const entries: unknown[] = [
+      {
+        type: "custom",
+        customType: "pi-harness/openpets",
+        data: {
+          name: "Pi",
+          mood: "idle",
+          energy: 80,
+          interactions: Number.MAX_SAFE_INTEGER,
+          lastEvent: "session_start",
+          updatedAt: "2026-09-05T10:00:00.000Z",
+        },
+      },
+    ];
+    const fixture = await createOpenPets({ entries });
+    try {
+      const result = await fixture.tool.execute("feed", { action: "feed" }, undefined, undefined, {} as never);
+      expect(result.details).toMatchObject({ name: "Pi", mood: "happy", energy: 100, interactions: Number.MAX_SAFE_INTEGER, lastEvent: "feed" });
+      const persisted = (entries.at(-1) as { data: { mood: string; interactions: number } }).data;
+      expect(persisted).toMatchObject({ mood: "happy", interactions: Number.MAX_SAFE_INTEGER });
+
+      (result.details as { name: string; mood: string; interactions: number }).name = "mutated";
+      (result.details as { name: string; mood: string; interactions: number }).mood = "concerned";
+      (result.details as { name: string; mood: string; interactions: number }).interactions = 0;
+      expect(persisted).toMatchObject({ mood: "happy", interactions: Number.MAX_SAFE_INTEGER });
+
+      const firstPanel = (await fixture.panels.snapshot())[0];
+      expect(firstPanel?.data).toMatchObject({ name: "Pi", mood: "happy", interactions: Number.MAX_SAFE_INTEGER });
+      (firstPanel?.data as { mood: string }).mood = "concerned";
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { name: "Pi", mood: "happy", interactions: Number.MAX_SAFE_INTEGER } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("reads session events without accessors and deduplicates repeated tool failures", async () => {
+    const fixture = await createOpenPets();
+    let typeAccessed = false;
+    let errorAccessed = false;
+    const typeAccessor = {} as { type?: string };
+    Object.defineProperty(typeAccessor, "type", {
+      enumerable: true,
+      get() {
+        typeAccessed = true;
+        throw new Error("session event type getter executed");
+      },
+    });
+    const errorAccessor = { type: "tool_execution_end" } as { type: string; isError?: boolean };
+    Object.defineProperty(errorAccessor, "isError", {
+      enumerable: true,
+      get() {
+        errorAccessed = true;
+        throw new Error("session event error getter executed");
+      },
+    });
+    try {
+      expect(() => fixture.context.emit("pi/session-event", typeAccessor as never)).not.toThrow();
+      expect(() => fixture.context.emit("pi/session-event", errorAccessor as never)).not.toThrow();
+      expect(typeAccessed).toBe(false);
+      expect(errorAccessed).toBe(false);
+      expect(fixture.entries).toHaveLength(0);
+
+      fixture.context.emit("pi/session-event", { type: "agent_start" } as never);
+      fixture.context.emit("pi/session-event", { type: "tool_execution_end", isError: false } as never);
+      fixture.context.emit("pi/session-event", { type: "tool_execution_end", isError: true } as never);
+      fixture.context.emit("pi/session-event", { type: "tool_execution_end", isError: true } as never);
+      fixture.context.emit("pi/session-event", { type: "agent_end", messages: [], willRetry: false } as never);
+
+      expect(fixture.entries).toHaveLength(3);
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { mood: "happy", energy: 80, lastEvent: "agent_end" } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("isolates event persistence failures and exposes bounded failure status", async () => {
+    const failure = new Error("x".repeat(3_000));
+    const fixture = await createOpenPets({
+      append() {
+        throw failure;
+      },
+    });
+    try {
+      expect(() => fixture.context.emit("pi/session-event", { type: "agent_start" } as never)).not.toThrow();
+      let panel = (await fixture.panels.snapshot())[0];
+      expect(panel?.data).toMatchObject({
+        mood: "focused",
+        energy: 75,
+        persistence: { attempts: 1, failures: 1 },
+        limits: { persistenceErrorCharacters: 2_000 },
+      });
+      expect((panel?.data as { persistence: { lastError: string } }).persistence.lastError).toHaveLength(2_000);
+
+      await expect(fixture.tool.execute("feed", { action: "feed" }, undefined, undefined, {} as never)).rejects.toBe(failure);
+      panel = (await fixture.panels.snapshot())[0];
+      expect(panel?.data).toMatchObject({ mood: "happy", energy: 100, interactions: 1, persistence: { attempts: 2, failures: 2 } });
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+});

package/packages/core/test/plan-execute.test.ts

@@ -0,0 +1,86 @@
+import { Context } from "@deepseek-ai/cordis";
+import { afterEach, describe, expect, test } from "vitest";
+import planExecutePlugin from "../src/plugins/plan-execute.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+const contexts: Context[] = [];
+
+async function fixture() {
+  const context = new Context();
+  const tools = new PiToolRegistry();
+  const panels = new PiPluginUiRegistry();
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(planExecutePlugin);
+  contexts.push(context);
+  const find = (name: string) => {
+    const tool = tools.snapshot().customTools.find((item) => item.name === name);
+    if (tool === undefined) throw new Error(`${name} was not registered`);
+    return tool;
+  };
+  return { context, tools, panels, create: find("plan_create"), advance: find("plan_advance") };
+}
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map((context) => context.fiber.dispose()));
+});
+
+describe("plan execute", () => {
+  test("creates and advances a bounded plan with strict sequential tools", async () => {
+    const { create, advance, panels } = await fixture();
+    for (const tool of [create, advance]) {
+      expect(tool.executionMode).toBe("sequential");
+      expect(tool.parameters).toMatchObject({ type: "object", additionalProperties: false });
+    }
+    await expect(create.execute("create", { title: "Release", steps: ["Test", "Ship"] }, undefined, undefined, {} as never)).resolves.toMatchObject({
+      details: {
+        title: "Release",
+        steps: [
+          { id: 1, status: "pending" },
+          { id: 2, status: "pending" },
+        ],
+      },
+    });
+    const inProgress = await advance.execute("advance", { step: 1, status: "in_progress" }, undefined, undefined, {} as never);
+    expect((inProgress.details as { steps: Array<{ id: number; status: string }> }).steps[0]).toMatchObject({ id: 1, status: "in_progress" });
+    const done = await advance.execute("advance", { step: 1, status: "done" }, undefined, undefined, {} as never);
+    expect((done.details as { steps: Array<{ id: number; status: string }> }).steps[0]).toMatchObject({ id: 1, status: "done" });
+    await expect(panels.snapshot()).resolves.toMatchObject([{ data: { title: "Release", completed: 1, total: 2 } }]);
+  });
+
+  test("rejects invalid plans and cleans up both tools and panel", async () => {
+    const { context, create, tools, panels } = await fixture();
+    await expect(create.execute("create", { title: "", steps: ["x"] }, undefined, undefined, {} as never)).rejects.toThrow(/title/iu);
+    await expect(create.execute("create", { title: "x", steps: [] }, undefined, undefined, {} as never)).rejects.toThrow(/1-50/iu);
+    await context.fiber.dispose();
+    expect(tools.snapshot().customTools).toHaveLength(0);
+    await expect(panels.snapshot()).resolves.toHaveLength(0);
+  });
+
+  test("rejects unknown plugin configuration before activation", async () => {
+    const context = new Context();
+    context.provide("piTools", new PiToolRegistry());
+    context.provide("piPluginUi", new PiPluginUiRegistry());
+    let error: unknown;
+    try {
+      await context.plugin(planExecutePlugin, { unexpected: true });
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toMatch(/config keys: unexpected/iu);
+    await context.fiber.dispose();
+  });
+
+  test("does not expose mutable plan state through tool results or panel snapshots", async () => {
+    const { create, advance, panels } = await fixture();
+    const result = await create.execute("create", { title: "Protected", steps: ["One"] }, undefined, undefined, {} as never);
+    (result.details as { title: string }).title = "mutated";
+    await expect(advance.execute("advance", { step: 1, status: "done" }, undefined, undefined, {} as never)).resolves.toMatchObject({
+      details: { title: "Protected", steps: [{ title: "One", status: "done" }] },
+    });
+    const panel = (await panels.snapshot())[0];
+    (panel?.data as { title: string }).title = "panel-mutated";
+    await expect(panels.snapshot()).resolves.toMatchObject([{ data: { title: "Protected" } }]);
+  });
+});

package/packages/core/test/plugin-dev.test.ts

@@ -0,0 +1,246 @@
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test } from "vitest";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+import pluginDevPlugin from "../src/plugins/plugin-dev.js";
+
+type RuntimeFixture = {
+  readonly context: Context;
+  readonly tool: ReturnType<PiToolRegistry["snapshot"]>["customTools"][number];
+  readonly panels: PiPluginUiRegistry;
+  readonly reloads: () => number;
+};
+
+function deferred(): { readonly promise: Promise<void>; readonly resolve: () => void; readonly reject: (error: unknown) => void } {
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+async function createPluginDev(options: { idle?: boolean; reload?: () => Promise<void> } = {}): Promise<RuntimeFixture> {
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const tools = new PiToolRegistry();
+  let reloads = 0;
+  context.provide("piRuntime", {
+    session: {
+      isIdle: options.idle ?? true,
+      reload: async () => {
+        reloads += 1;
+        await options.reload?.();
+      },
+    },
+  } as never);
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(pluginDevPlugin);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "plugin_dev_reload");
+  if (tool === undefined) throw new Error("Plugin Dev reload tool was not registered");
+  return { context, tool, panels, reloads: () => reloads };
+}
+
+describe("plugin dev reload boundaries", () => {
+  test("declares a bounded reason and validates descriptor-only parameters before reloading", async () => {
+    const fixture = await createPluginDev();
+    let accessed = false;
+    const accessor = {} as { reason?: string };
+    Object.defineProperty(accessor, "reason", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("reason getter executed");
+      },
+    });
+    const symbolProperty = { reason: "fixture" } as Record<PropertyKey, unknown>;
+    symbolProperty[Symbol("unexpected")] = true;
+    try {
+      expect(fixture.tool.parameters).toMatchObject({ properties: { reason: { type: "string", maxLength: 1_000 } } });
+      expect(fixture.tool.label).toBe("Reload Pi session resources");
+      expect(fixture.tool.description).toMatch(/extensions.*skills.*prompts.*themes.*context files/iu);
+      await expect(fixture.tool.execute("accessor", accessor, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*data properties/iu);
+      expect(accessed).toBe(false);
+      await expect(fixture.tool.execute("unknown", { reason: "fixture", unknown: true }, undefined, undefined, {} as never)).rejects.toThrow(
+        /unknown property/iu,
+      );
+      await expect(fixture.tool.execute("symbol", symbolProperty, undefined, undefined, {} as never)).rejects.toThrow(/unknown property/iu);
+      await expect(fixture.tool.execute("null", null, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*object/iu);
+      await expect(fixture.tool.execute("array", [], undefined, undefined, {} as never)).rejects.toThrow(/parameters.*object/iu);
+      await expect(fixture.tool.execute("date", new Date(), undefined, undefined, {} as never)).rejects.toThrow(/parameters.*plain object/iu);
+      await expect(fixture.tool.execute("type", { reason: 42 }, undefined, undefined, {} as never)).rejects.toThrow(/reason must be a string/iu);
+      await expect(fixture.tool.execute("long", { reason: "x".repeat(1_001) }, undefined, undefined, {} as never)).rejects.toThrow(
+        /reason.*0-1000 characters/iu,
+      );
+      await expect(fixture.tool.execute("nul", { reason: "reload\0now" }, undefined, undefined, {} as never)).rejects.toThrow(/reason.*NUL/iu);
+      expect(fixture.reloads()).toBe(0);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("queues reload until the active agent run settles", async () => {
+    const reload = deferred();
+    const fixture = await createPluginDev({ idle: false, reload: () => reload.promise });
+    const result = fixture.tool.execute("queued", { reason: "reload after this turn" }, undefined, undefined, {} as never);
+    try {
+      await Promise.resolve();
+      expect(fixture.reloads()).toBe(0);
+      await expect(result).resolves.toMatchObject({
+        details: { status: "queued", reason: "reload after this turn" },
+      });
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { status: "queued", reason: "reload after this turn" } }]);
+
+      fixture.context.emit("pi/session-event", { type: "agent_settled" });
+      await expect.poll(fixture.reloads).toBe(1);
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { status: "running" } }]);
+      reload.resolve();
+      await expect.poll(async () => (await fixture.panels.snapshot())[0]?.data).toMatchObject({ status: "reloaded" });
+    } finally {
+      reload.resolve();
+      await Promise.allSettled([result]);
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects overlapping reloads instead of invoking AgentSession.reload concurrently", async () => {
+    const reload = deferred();
+    const fixture = await createPluginDev({ reload: () => reload.promise });
+    let second: ReturnType<(typeof fixture.tool)["execute"]> | undefined;
+    try {
+      const first = fixture.tool.execute("first", { reason: "first" }, undefined, undefined, {} as never);
+      await expect.poll(fixture.reloads).toBe(1);
+      second = fixture.tool.execute("second", { reason: "second" }, undefined, undefined, {} as never);
+      let secondOutcome = "pending";
+      void second.then(
+        () => {
+          secondOutcome = "resolved";
+        },
+        () => {
+          secondOutcome = "rejected";
+        },
+      );
+      await expect.poll(() => secondOutcome).toBe("rejected");
+      await expect(second).rejects.toThrow(/reload.*already.*progress/iu);
+      expect(fixture.reloads()).toBe(1);
+      reload.resolve();
+      await expect(first).resolves.toMatchObject({ details: { status: "reloaded", reason: "first" } });
+    } finally {
+      reload.resolve();
+      if (second !== undefined) await Promise.allSettled([second]);
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("does not start an already-cancelled reload request", async () => {
+    const fixture = await createPluginDev();
+    const caller = new AbortController();
+    caller.abort(new Error("cancel request"));
+    try {
+      await expect(fixture.tool.execute("cancelled", {}, caller.signal, undefined, {} as never)).rejects.toThrow(/reload.*cancelled/iu);
+      expect(fixture.reloads()).toBe(0);
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { status: "cancelled" } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("lets a caller stop waiting without pretending the underlying reload was cancelled", async () => {
+    const reload = deferred();
+    const fixture = await createPluginDev({ reload: () => reload.promise });
+    const caller = new AbortController();
+    try {
+      const result = fixture.tool.execute("cancel-wait", { reason: "slow reload" }, caller.signal, undefined, {} as never);
+      await expect.poll(fixture.reloads).toBe(1);
+      caller.abort(new Error("caller stopped"));
+      let outcome = "pending";
+      void result.then(
+        () => {
+          outcome = "resolved";
+        },
+        () => {
+          outcome = "rejected";
+        },
+      );
+      await expect.poll(() => outcome).toBe("rejected");
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { status: "running" } }]);
+
+      reload.resolve();
+      await expect.poll(async () => (await fixture.panels.snapshot())[0]?.data).toMatchObject({ status: "reloaded", reason: "slow reload" });
+    } finally {
+      reload.resolve();
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("bounds reload failures without invoking hostile error coercion", async () => {
+    let coerced = false;
+    const hostileError = new Error();
+    Object.defineProperty(hostileError, "message", {
+      get() {
+        coerced = true;
+        throw new Error("hostile error coercion executed");
+      },
+    });
+    let attempt = 0;
+    const fixture = await createPluginDev({
+      reload: () => {
+        attempt += 1;
+        return Promise.reject(attempt === 1 ? new Error("x".repeat(3_000)) : hostileError);
+      },
+    });
+    try {
+      await expect(fixture.tool.execute("long-error", {}, undefined, undefined, {} as never)).rejects.toThrow();
+      let panel = (await fixture.panels.snapshot())[0];
+      expect((panel?.data as { error: string }).error).toHaveLength(2_000);
+      expect(panel?.data).toMatchObject({ limits: { reasonCharacters: 1_000, errorCharacters: 2_000 } });
+
+      await expect(fixture.tool.execute("hostile-error", {}, undefined, undefined, {} as never)).rejects.toBe(hostileError);
+      expect(coerced).toBe(false);
+      panel = (await fixture.panels.snapshot())[0];
+      expect(panel?.data).toMatchObject({ status: "failed", error: "Unknown plugin reload error" });
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("does not expose mutable reload state through tool results or panel snapshots", async () => {
+    const fixture = await createPluginDev();
+    try {
+      const result = await fixture.tool.execute("reload", { reason: "original" }, undefined, undefined, {} as never);
+      (result.details as { reason: string }).reason = "mutated tool result";
+
+      const firstPanel = (await fixture.panels.snapshot())[0];
+      expect(firstPanel?.data).toMatchObject({ status: "reloaded", reason: "original" });
+      (firstPanel?.data as { reason: string }).reason = "mutated panel";
+
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { status: "reloaded", reason: "original" } }]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("stops waiting for an active reload when the plugin is disposed", async () => {
+    const reload = deferred();
+    const fixture = await createPluginDev({ reload: () => reload.promise });
+    const result = fixture.tool.execute("dispose", {}, undefined, undefined, {} as never);
+    let outcome = "pending";
+    void result.then(
+      () => {
+        outcome = "resolved";
+      },
+      () => {
+        outcome = "rejected";
+      },
+    );
+    try {
+      await expect.poll(fixture.reloads).toBe(1);
+      await fixture.context.fiber.dispose();
+      await expect.poll(() => outcome).toBe("rejected");
+    } finally {
+      reload.resolve();
+      await Promise.allSettled([result]);
+    }
+  });
+});