@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/test/canvas-draw.test.ts

@@ -0,0 +1,164 @@
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test } from "vitest";
+import canvasDrawPlugin from "../src/plugins/canvas-draw.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+async function createCanvas(): Promise<{ context: Context; panels: PiPluginUiRegistry; tools: PiToolRegistry }> {
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const tools = new PiToolRegistry();
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(canvasDrawPlugin);
+  return { context, panels, tools };
+}
+
+function canvasTool(tools: PiToolRegistry) {
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "canvas_draw");
+  if (tool === undefined) throw new Error("canvas_draw was not registered");
+  return tool;
+}
+
+describe("canvas-draw", () => {
+  test("declares all node, edge, id, and label bounds in the tool schema", async () => {
+    const { context, tools } = await createCanvas();
+    try {
+      const parameters = canvasTool(tools).parameters;
+
+      expect(parameters).toMatchObject({
+        properties: {
+          nodes: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+            items: {
+              properties: {
+                id: { type: "string", minLength: 1, maxLength: 64, pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" },
+                label: { type: "string", minLength: 1, maxLength: 256 },
+              },
+            },
+          },
+          edges: {
+            type: "array",
+            maxItems: 200,
+            items: {
+              properties: {
+                from: { type: "string", minLength: 1, maxLength: 64, pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" },
+                to: { type: "string", minLength: 1, maxLength: 64, pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" },
+                label: { type: "string", minLength: 1, maxLength: 256 },
+              },
+            },
+          },
+        },
+      });
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed and oversized inputs before mapping their entries", async () => {
+    const { context, tools } = await createCanvas();
+    const draw = canvasTool(tools);
+    try {
+      await expect(draw.execute("null", null, undefined, undefined, {} as never)).rejects.toThrow(/nodes must be an array/iu);
+      await expect(draw.execute("edges", { nodes: [{ id: "a", label: "A" }], edges: null }, undefined, undefined, {} as never)).rejects.toThrow(
+        /edges must be an array/iu,
+      );
+      await expect(
+        draw.execute("nodes-limit", { nodes: Array.from({ length: 101 }, () => null), edges: [] }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/1-100 nodes/iu);
+      await expect(
+        draw.execute("edges-limit", { nodes: [{ id: "a", label: "A" }], edges: Array.from({ length: 201 }, () => null) }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/at most 200 edges/iu);
+      await expect(
+        draw.execute("direction", { direction: "DOWN", nodes: [{ id: "a", label: "A" }], edges: [] }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/direction must be TD, LR, BT, or RL/iu);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("escapes HTML and Mermaid delimiters in node and edge labels", async () => {
+    const { context, tools } = await createCanvas();
+    try {
+      const result = await canvasTool(tools).execute(
+        "escape",
+        {
+          nodes: [
+            { id: "start", label: '<script>alert("x")</script> & next\nline' },
+            { id: "finish", label: "Finish" },
+          ],
+          edges: [{ from: "start", to: "finish", label: "ready| --> injected <b>" }],
+        },
+        undefined,
+        undefined,
+        {} as never,
+      );
+      const mermaid = (result.details as { mermaid: string }).mermaid;
+
+      expect(mermaid).not.toContain("<script>");
+      expect(mermaid).not.toContain("<b>");
+      expect(mermaid).not.toContain("ready| --> injected");
+      expect(mermaid).toContain("&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt; &amp; next line");
+      expect(mermaid).toContain("ready&#124; --&gt; injected &lt;b&gt;");
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("does not expose mutable canvas state through tool results", async () => {
+    const { context, panels, tools } = await createCanvas();
+    try {
+      const result = await canvasTool(tools).execute(
+        "draw",
+        {
+          nodes: [
+            { id: "start", label: "Start" },
+            { id: "finish", label: "Finish" },
+          ],
+          edges: [{ from: "start", to: "finish" }],
+        },
+        undefined,
+        undefined,
+        {} as never,
+      );
+
+      (result.details as { nodes: Array<{ label: string }> }).nodes[0]!.label = "mutated";
+
+      const panel = (await panels.snapshot())[0];
+      if (panel === undefined) throw new Error("canvas-draw-panel was not registered");
+      const panelLatest = (panel.data as { latest: { nodes: Array<{ label: string }> } }).latest;
+      expect(panelLatest.nodes[0]?.label).toBe("Start");
+      panelLatest.nodes[0]!.label = "panel-mutated";
+
+      const nextPanel = (await panels.snapshot())[0];
+      if (nextPanel === undefined) throw new Error("canvas-draw-panel was not registered");
+      expect((nextPanel.data as { latest: { nodes: Array<{ label: string }> } }).latest.nodes[0]?.label).toBe("Start");
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("accepts exact collection limits, preserves successful state on failure, and unregisters on disposal", async () => {
+    const { context, panels, tools } = await createCanvas();
+    const draw = canvasTool(tools);
+    const nodes = Array.from({ length: 100 }, (_, index) => ({ id: `node_${index}`, label: `Node ${index}` }));
+    const edges = Array.from({ length: 200 }, (_, index) => ({ from: `node_${index % 100}`, to: `node_${(index + 1) % 100}`, label: `Edge ${index}` }));
+    try {
+      await expect(draw.execute("limits", { direction: "RL", nodes, edges }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { direction: "RL", nodeCount: 100, edgeCount: 200 },
+      });
+      await expect(
+        draw.execute("failure", { nodes: [{ id: "start", label: "Start" }], edges: [{ from: "start", to: "missing" }] }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/unknown node/iu);
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "canvas-draw-panel", data: { nodeCount: 100, edgeCount: 200 } }]);
+
+      await context.fiber.dispose();
+
+      expect(tools.snapshot().customTools).toEqual([]);
+      await expect(panels.snapshot()).resolves.toEqual([]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+});

package/packages/core/test/change-verifier.test.ts

@@ -0,0 +1,200 @@
+import { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { describe, expect, test } from "vitest";
+import changeVerifierPlugin from "../src/plugins/change-verifier.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+async function createVerifier(options?: { reviewStatus?: unknown; testDurationMs?: unknown; testExitCode?: unknown }): Promise<{
+  context: Context;
+  panels: PiPluginUiRegistry;
+  testScripts: string[];
+  tools: PiToolRegistry;
+}> {
+  const context = new Context();
+  const panels = new PiPluginUiRegistry();
+  const testScripts: string[] = [];
+  const tools = new PiToolRegistry();
+  tools.register(
+    defineTool({
+      name: "review_changes",
+      label: "Review fixture",
+      description: "Review fixture",
+      parameters: Type.Object({}),
+      execute() {
+        return Promise.resolve({
+          content: [{ type: "text" as const, text: "reviewed" }],
+          details: { status: options?.reviewStatus ?? "pass", findings: [] },
+        });
+      },
+    }),
+  );
+  tools.register(
+    defineTool({
+      name: "run_project_tests",
+      label: "Test fixture",
+      description: "Test fixture",
+      parameters: Type.Object({ script: Type.Optional(Type.String()) }),
+      execute(_toolCallId, params) {
+        testScripts.push(params.script ?? "test");
+        return Promise.resolve({
+          content: [{ type: "text" as const, text: "tested" }],
+          details: { exitCode: options?.testExitCode ?? 0, durationMs: options?.testDurationMs ?? 10 },
+        });
+      },
+    }),
+  );
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(changeVerifierPlugin);
+  return { context, panels, testScripts, tools };
+}
+
+function verifierTool(tools: PiToolRegistry) {
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "verify_change_gate");
+  if (tool === undefined) throw new Error("verify_change_gate was not registered");
+  return tool;
+}
+
+describe("change-verifier", () => {
+  test("declares the verification script length bounds", async () => {
+    const { context, tools } = await createVerifier();
+    try {
+      expect(verifierTool(tools).parameters).toMatchObject({
+        properties: { script: { type: "string", minLength: 1, maxLength: 128 } },
+      });
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("normalizes missing scripts and rejects malformed scripts before invoking the test provider", async () => {
+    const { context, testScripts, tools } = await createVerifier();
+    const verify = verifierTool(tools);
+    try {
+      await expect(verify.execute("null", null, undefined, undefined, {} as never)).resolves.toMatchObject({ details: { script: "test" } });
+      await expect(verify.execute("blank", { script: "   " }, undefined, undefined, {} as never)).resolves.toMatchObject({ details: { script: "test" } });
+      await expect(verify.execute("type", { script: 7 }, undefined, undefined, {} as never)).rejects.toThrow(/script must be a string/iu);
+      await expect(verify.execute("length", { script: "x".repeat(129) }, undefined, undefined, {} as never)).rejects.toThrow(/between 1 and 128/iu);
+      expect(testScripts).toEqual(["test", "test"]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("fails closed when the review provider returns an unknown status", async () => {
+    const { context, tools } = await createVerifier({ reviewStatus: "unknown" });
+    try {
+      await expect(verifierTool(tools).execute("verify", {}, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { status: "fail", review: { status: "error" } },
+      });
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("fails closed and normalizes non-finite test provider metrics", async () => {
+    const { context, tools } = await createVerifier({ testExitCode: Number.NaN, testDurationMs: Number.POSITIVE_INFINITY });
+    try {
+      await expect(verifierTool(tools).execute("verify", {}, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { status: "fail", tests: { exitCode: 1, durationMs: 0 } },
+      });
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("cancels an in-flight verification when the plugin is disposed", async () => {
+    const context = new Context();
+    const panels = new PiPluginUiRegistry();
+    const tools = new PiToolRegistry();
+    let reviewAborted = false;
+    let rejectReview: ((error: Error) => void) | undefined;
+    tools.register(
+      defineTool({
+        name: "review_changes",
+        label: "Review fixture",
+        description: "Review fixture",
+        parameters: Type.Object({}),
+        execute(_toolCallId, _params, signal) {
+          return new Promise((_resolve, reject) => {
+            rejectReview = reject;
+            signal?.addEventListener(
+              "abort",
+              () => {
+                reviewAborted = true;
+                const reason: unknown = signal.reason;
+                reject(reason instanceof Error ? reason : new Error("review aborted"));
+              },
+              { once: true },
+            );
+          });
+        },
+      }),
+    );
+    tools.register(
+      defineTool({
+        name: "run_project_tests",
+        label: "Test fixture",
+        description: "Test fixture",
+        parameters: Type.Object({ script: Type.Optional(Type.String()) }),
+        execute() {
+          return Promise.resolve({ content: [{ type: "text" as const, text: "tested" }], details: { exitCode: 0, durationMs: 1 } });
+        },
+      }),
+    );
+    context.provide("piTools", tools);
+    context.provide("piPluginUi", panels);
+    await context.plugin(changeVerifierPlugin);
+    let execution: Promise<unknown> | undefined;
+    let fallback: ReturnType<typeof setTimeout> | undefined;
+    try {
+      execution = verifierTool(tools).execute("verify", {}, undefined, undefined, {} as never);
+
+      await context.fiber.dispose();
+      const outcome = await Promise.race([
+        execution.then(
+          () => new Error("Verification unexpectedly succeeded"),
+          (error: unknown) => error,
+        ),
+        new Promise<string>((resolve) => {
+          fallback = setTimeout(() => resolve("Verification remained pending"), 500);
+        }),
+      ]);
+
+      expect(outcome).toBeInstanceOf(Error);
+      expect(String(outcome)).toMatch(/disposed|cancelled/iu);
+      expect(reviewAborted).toBe(true);
+      expect(tools.snapshot().customTools.map((tool) => tool.name)).toEqual(["review_changes", "run_project_tests"]);
+      await expect(panels.snapshot()).resolves.toEqual([]);
+    } finally {
+      if (fallback !== undefined) clearTimeout(fallback);
+      rejectReview?.(new Error("test cleanup"));
+      await context.fiber.dispose();
+      await execution?.catch(() => undefined);
+    }
+  });
+
+  test("does not expose mutable gate state and preserves it after validation failures", async () => {
+    const { context, panels, tools } = await createVerifier();
+    const verify = verifierTool(tools);
+    try {
+      const result = await verify.execute("verify", { script: "test" }, undefined, undefined, {} as never);
+      (result.details as { review: { status: string } }).review.status = "mutated";
+
+      const firstPanel = (await panels.snapshot())[0];
+      if (firstPanel === undefined) throw new Error("change-verifier-panel was not registered");
+      const firstLatest = (firstPanel.data as { latest: { review: { status: string } } }).latest;
+      expect(firstLatest.review.status).toBe("pass");
+      firstLatest.review.status = "panel-mutated";
+
+      const secondPanel = (await panels.snapshot())[0];
+      if (secondPanel === undefined) throw new Error("change-verifier-panel was not registered");
+      expect((secondPanel.data as { latest: { review: { status: string } } }).latest.review.status).toBe("pass");
+      await expect(verify.execute("invalid", { script: 7 }, undefined, undefined, {} as never)).rejects.toThrow(/script must be a string/iu);
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "change-verifier-panel", data: { runs: 1, latest: { status: "pass" } } }]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+});

package/packages/core/test/cleaner.test.ts

@@ -0,0 +1,316 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } 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 cleanerPlugin, { Config } from "../src/plugins/cleaner.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../src/services.js";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })));
+});
+
+async function createFixture() {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-workspace-"));
+  const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-agent-"));
+  temporaryDirectories.push(cwd, agentDir);
+  const context = new Context();
+  const tools = new PiToolRegistry();
+  const panels = new PiPluginUiRegistry();
+  context.provide("piHarnessLaunch", { cwd, agentDir, args: [], requestExit() {} });
+  context.provide("piTools", tools);
+  context.provide("piPluginUi", panels);
+  await context.plugin(cleanerPlugin);
+  const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "clean_harness_artifacts");
+  if (tool === undefined) throw new Error("clean_harness_artifacts was not registered");
+  return { context, cwd, agentDir, panels, tool, tools };
+}
+
+async function writeCapsules(agentDir: string, count: number): Promise<void> {
+  const directory = join(agentDir, "capsules");
+  await mkdir(directory, { recursive: true });
+  await Promise.all(
+    Array.from({ length: count }, (_, index) => writeFile(join(directory, `${String(index).padStart(4, "0")}.patch`), `patch-${index}`, "utf8")),
+  );
+}
+
+describe("cleaner production boundaries", () => {
+  test("exports a strict empty config and a sequential strict-schema tool", async () => {
+    expect(Config).toBeDefined();
+    const fixture = await createFixture();
+    try {
+      expect(fixture.tool).toMatchObject({
+        name: "clean_harness_artifacts",
+        executionMode: "sequential",
+        parameters: {
+          additionalProperties: false,
+          required: ["confirm"],
+          properties: {
+            confirm: { type: "boolean" },
+            keep: { type: "integer", minimum: 0, maximum: 256 },
+          },
+        },
+      });
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects unknown and hostile configuration before registering surfaces", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-config-"));
+    const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-agent-"));
+    temporaryDirectories.push(cwd, agentDir);
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    context.provide("piHarnessLaunch", { cwd, agentDir, args: [], requestExit() {} });
+    context.provide("piTools", tools);
+    context.provide("piPluginUi", panels);
+    try {
+      let failure: unknown;
+      try {
+        await context.plugin(cleanerPlugin, { unexpected: true });
+      } catch (error) {
+        failure = error;
+      }
+      expect(failure).toBeInstanceOf(Error);
+      expect((failure as Error).message).toMatch(/unknown.*unexpected/iu);
+      expect(tools.snapshot().customTools).toEqual([]);
+      await expect(panels.snapshot()).resolves.toEqual([]);
+
+      let getterCalls = 0;
+      const accessor = Object.defineProperty({}, "unexpected", {
+        enumerable: true,
+        get() {
+          getterCalls += 1;
+          return true;
+        },
+      });
+      const revocable = Proxy.revocable({}, {});
+      revocable.revoke();
+      for (const config of ["invalid", accessor, { [Symbol("unexpected")]: true }, revocable.proxy]) {
+        expect(() => cleanerPlugin.apply(context, config as never)).toThrow(
+          /(?:config.*(?:plain object|data properties|unknown|accessible)|unknown.*config)/iu,
+        );
+      }
+      expect(getterCalls).toBe(0);
+      expect(tools.snapshot().customTools).toEqual([]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rolls back tool registration when the panel id is unavailable", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-conflict-"));
+    const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-agent-"));
+    temporaryDirectories.push(cwd, agentDir);
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    context.provide("piHarnessLaunch", { cwd, agentDir, args: [], requestExit() {} });
+    context.provide("piTools", tools);
+    context.provide("piPluginUi", panels);
+    panels.register({ id: "cleaner-panel", pluginId: "fixture", title: "Fixture", read: () => ({}) });
+    try {
+      await expect(context.plugin(cleanerPlugin)).rejects.toThrow(/already registered.*cleaner-panel/iu);
+      expect(tools.snapshot().customTools).toEqual([]);
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "cleaner-panel", pluginId: "fixture" }]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("strictly validates raw parameters without invoking accessors", async () => {
+    const fixture = await createFixture();
+    let accessed = false;
+    const accessor = { confirm: true } as { confirm: boolean; keep?: number };
+    Object.defineProperty(accessor, "keep", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("cleaner accessor executed");
+      },
+    });
+    try {
+      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", { confirm: true, unexpected: 1 }, undefined, undefined, {} as never)).rejects.toThrow(/unknown property/iu);
+      await expect(fixture.tool.execute("null", { confirm: true, keep: null }, undefined, undefined, {} as never)).rejects.toThrow(/keep.*integer/iu);
+      await expect(fixture.tool.execute("nan", { confirm: true, keep: Number.NaN }, undefined, undefined, {} as never)).rejects.toThrow(/keep.*integer/iu);
+      const inherited = Object.create({ confirm: true }) as Record<string, unknown>;
+      await expect(fixture.tool.execute("inherited", inherited, undefined, undefined, {} as never)).rejects.toThrow(/plain object/iu);
+      const revocable = Proxy.revocable({}, {});
+      revocable.revoke();
+      await expect(fixture.tool.execute("revoked", revocable.proxy, undefined, undefined, {} as never)).rejects.toThrow(/accessible plain object/iu);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("honors caller and plugin lifecycle cancellation before touching artifacts", async () => {
+    const callerFixture = await createFixture();
+    await writeCapsules(callerFixture.agentDir, 1);
+    const controller = new AbortController();
+    controller.abort(new Error("cleaner caller cancelled"));
+    try {
+      await expect(callerFixture.tool.execute("caller", { confirm: true, keep: 0 }, controller.signal, undefined, {} as never)).rejects.toThrow(
+        "cleaner caller cancelled",
+      );
+      await expect(callerFixture.panels.snapshot()).resolves.toMatchObject([{ data: { inventory: { total: 1 } } }]);
+    } finally {
+      await callerFixture.context.fiber.dispose();
+    }
+
+    const lifecycleFixture = await createFixture();
+    await writeCapsules(lifecycleFixture.agentDir, 1);
+    await lifecycleFixture.context.fiber.dispose();
+    await expect(lifecycleFixture.tool.execute("disposed", { confirm: true, keep: 0 }, undefined, undefined, {} as never)).rejects.toThrow(
+      "Cleaner plugin disposed",
+    );
+    expect(lifecycleFixture.tools.snapshot().customTools).toEqual([]);
+    await expect(lifecycleFixture.panels.snapshot()).resolves.toEqual([]);
+  });
+
+  test("ignores unsafe patch names instead of displaying or deleting them", async () => {
+    const fixture = await createFixture();
+    const directory = join(fixture.agentDir, "capsules");
+    await mkdir(directory, { recursive: true });
+    await Promise.all([
+      writeFile(join(directory, "safe.patch"), "safe", "utf8"),
+      writeFile(join(directory, "unsafe\n.patch"), "unsafe", "utf8"),
+      writeFile(join(directory, "unsafe\u202e.patch"), "unsafe", "utf8"),
+      writeFile(join(directory, "unsafe\\.patch"), "unsafe", "utf8"),
+      writeFile(join(directory, "unsafe\u2028.patch"), "unsafe", "utf8"),
+    ]);
+    try {
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { capsules: [{ name: "safe.patch" }], inventory: { total: 1 } } }]);
+      await expect(fixture.tool.execute("clean", { confirm: true, keep: 0 }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { removed: 1, kept: 0 },
+      });
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { capsules: [], inventory: { total: 0 } } }]);
+      await expect(readFile(join(directory, "unsafe\n.patch"), "utf8")).resolves.toBe("unsafe");
+      await expect(readFile(join(directory, "unsafe\u202e.patch"), "utf8")).resolves.toBe("unsafe");
+      await expect(readFile(join(directory, "unsafe\\.patch"), "utf8")).resolves.toBe("unsafe");
+      await expect(readFile(join(directory, "unsafe\u2028.patch"), "utf8")).resolves.toBe("unsafe");
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("publishes a bounded detached capsule inventory and explicit limits", async () => {
+    const fixture = await createFixture();
+    await writeCapsules(fixture.agentDir, 30);
+    try {
+      const first = await fixture.panels.snapshot();
+      expect(first).toMatchObject([
+        {
+          id: "cleaner-panel",
+          data: {
+            inventory: { total: 30, shown: 20, truncated: true, displayLimit: 20 },
+            lastCleanup: null,
+            limits: { capsules: 256, directoryEntries: 4_096 },
+          },
+        },
+      ]);
+      const firstData = first[0]?.data as { capsules: Array<{ name: string; bytes: number }> };
+      expect(firstData.capsules).toHaveLength(20);
+      expect(firstData.capsules[0]).toEqual({ name: "0029.patch", bytes: 8 });
+      firstData.capsules[0]!.name = "mutated.patch";
+
+      const second = await fixture.panels.snapshot();
+      expect((second[0]?.data as { capsules: Array<{ name: string }> }).capsules[0]?.name).toBe("0029.patch");
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("reports completed cleanup activity with the final inventory count", async () => {
+    const fixture = await createFixture();
+    await writeCapsules(fixture.agentDir, 5);
+    try {
+      await expect(fixture.tool.execute("clean", { confirm: true, keep: 2 }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { removed: 3, kept: 2 },
+      });
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([
+        {
+          data: {
+            capsules: [{ name: "0004.patch" }, { name: "0003.patch" }],
+            inventory: { total: 2, shown: 2, truncated: false },
+            lastCleanup: { status: "completed", requestedKeep: 2, removed: 3, kept: 2 },
+          },
+        },
+      ]);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("rejects an aborted queued cleanup before the active inventory scan completes", async () => {
+    const fixture = await createFixture();
+    await writeCapsules(fixture.agentDir, 30);
+    const first = fixture.tool.execute("active", { confirm: true, keep: 30 }, undefined, undefined, {} as never);
+    const controller = new AbortController();
+    const second = fixture.tool.execute("queued", { confirm: true, keep: 0 }, controller.signal, undefined, {} as never);
+    controller.abort(new Error("queued cleaner cancelled"));
+    try {
+      const firstOutcome = first.then(() => "active completed");
+      const secondOutcome = second.then(
+        () => "queued completed",
+        (error: unknown) => (error instanceof Error ? error.message : "queued rejected"),
+      );
+      await expect(Promise.race([firstOutcome, secondOutcome])).resolves.toBe("queued cleaner cancelled");
+      await expect(first).resolves.toMatchObject({ details: { removed: 0, kept: 30 } });
+      await expect(second).rejects.toThrow("queued cleaner cancelled");
+      await expect(fixture.panels.snapshot()).resolves.toMatchObject([{ data: { inventory: { total: 30 } } }]);
+    } finally {
+      await Promise.all([first.catch(() => undefined), second.catch(() => undefined)]);
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("publishes sanitized character- and UTF-8-bounded queued cancellation errors", async () => {
+    const fixture = await createFixture();
+    await writeCapsules(fixture.agentDir, 30);
+    const active = fixture.tool.execute("active", { confirm: true, keep: 30 }, undefined, undefined, {} as never);
+    const controller = new AbortController();
+    const queued = fixture.tool.execute("queued", { confirm: true, keep: 0 }, controller.signal, undefined, {} as never);
+    controller.abort(new Error(` unsafe\0\u202e${"界".repeat(3_000)}😀tail `));
+    try {
+      await Promise.all([active, queued.catch(() => undefined)]);
+      const [panel] = await fixture.panels.snapshot();
+      const activity = (panel?.data as { lastCleanup?: { status?: unknown; error?: unknown } } | undefined)?.lastCleanup;
+      expect(activity?.status).toBe("cancelled");
+      expect(typeof activity?.error).toBe("string");
+      expect([...(activity?.error as string)]).toHaveLength(672);
+      expect(Buffer.byteLength(activity?.error as string, "utf8")).toBeLessThanOrEqual(2_000);
+      expect(activity?.error).not.toMatch(/[\p{Cc}\p{Cf}\p{Cs}]/u);
+      expect(activity?.error).toMatch(/^unsafe {2}/u);
+    } finally {
+      await Promise.all([active.catch(() => undefined), queued.catch(() => undefined)]);
+      await fixture.context.fiber.dispose();
+    }
+  });
+
+  test("retains bounded failure activity after the capsule directory is repaired", async () => {
+    if (process.platform === "win32") return;
+    const fixture = await createFixture();
+    const outside = await mkdtemp(join(tmpdir(), "pi-harness-cleaner-outside-"));
+    temporaryDirectories.push(outside);
+    const directory = join(fixture.agentDir, "capsules");
+    await symlink(outside, directory);
+    try {
+      await expect(fixture.tool.execute("failure", { confirm: true, keep: 0 }, undefined, undefined, {} as never)).rejects.toThrow(/symbolic link/iu);
+      await rm(directory);
+      await mkdir(directory);
+      const snapshot = await fixture.panels.snapshot();
+      expect(snapshot).toMatchObject([{ data: { lastCleanup: { status: "failed", requestedKeep: 0, removed: 0 } } }]);
+      const activity = (snapshot[0]?.data as { lastCleanup: { error: string } }).lastCleanup;
+      expect(activity.error).toMatch(/symbolic link/iu);
+      expect(activity.error.length).toBeLessThanOrEqual(2_000);
+    } finally {
+      await fixture.context.fiber.dispose();
+    }
+  });
+});