@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/canvas-draw.ts

@@ -1,6 +1,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 
 const maxNodes = 100;
 const maxEdges = 200;
@@ -11,23 +12,45 @@ type CanvasNode = { id: string; label: string };
 type CanvasEdge = { from: string; to: string; label?: string };
 type CanvasReport = { direction: Direction; nodes: CanvasNode[]; edges: CanvasEdge[]; nodeCount: number; edgeCount: number; mermaid: string };
 
-function label(value: string, field: string): string {
+function label(value: unknown, field: string): string {
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
   const result = value.trim();
   if (result.length === 0 || result.length > maxLabelLength) throw new Error(`${field} must contain 1-${maxLabelLength} characters`);
   return result;
 }
 
+function nodeId(value: unknown, field: string): string {
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
+  const result = value.trim();
+  if (!nodeIdPattern.test(result)) throw new Error(`Invalid ${field.toLowerCase()}: ${result}`);
+  return result;
+}
+
+function direction(value: unknown): Direction {
+  if (value === undefined) return "TD";
+  if (value === "TD" || value === "LR" || value === "BT" || value === "RL") return value;
+  throw new Error("Canvas direction must be TD, LR, BT, or RL");
+}
+
 function render(direction: Direction, nodes: CanvasNode[], edges: CanvasEdge[]): string {
-  const escape = (value: string): string => value.replace(/["\r\n]/g, (character) => (character === '"' ? """ : " "));
+  const escape = (value: string): string =>
+    value.replace(/[&<>"\r\n]/g, (character) => {
+      if (character === "&") return "&amp;";
+      if (character === "<") return "&lt;";
+      if (character === ">") return "&gt;";
+      return character === '"' ? "&quot;" : " ";
+    });
+  const escapeEdge = (value: string): string => escape(value).replace(/\|/g, "&#124;");
   const lines = [`flowchart ${direction}`];
   for (const node of nodes) lines.push(`    ${node.id}["${escape(node.label)}"]`);
-  for (const edge of edges) lines.push(`    ${edge.from} -->${edge.label === undefined ? "" : `|${escape(edge.label)}|`} ${edge.to}`);
+  for (const edge of edges) lines.push(`    ${edge.from} -->${edge.label === undefined ? "" : `|${escapeEdge(edge.label)}|`} ${edge.to}`);
   return lines.join("\n");
 }
 
 export default {
   name: "pi-canvas-draw",
   inject: ["piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: CanvasReport | undefined;
     const unregisterTool = context.piTools.register(
@@ -36,24 +59,54 @@ export default {
         label: "Draw canvas",
         description: "Generate a validated Mermaid flowchart from structured nodes and edges without executing or writing files.",
         promptSnippet: "draw a flowchart from these nodes and relationships",
-        parameters: Type.Object({
-          direction: Type.Optional(Type.Union([Type.Literal("TD"), Type.Literal("LR"), Type.Literal("BT"), Type.Literal("RL")])),
-          nodes: Type.Array(Type.Object({ id: Type.String(), label: Type.String() })),
-          edges: Type.Array(Type.Object({ from: Type.String(), to: Type.String(), label: Type.Optional(Type.String()) })),
-        }),
+        parameters: Type.Object(
+          {
+            direction: Type.Optional(Type.Union([Type.Literal("TD"), Type.Literal("LR"), Type.Literal("BT"), Type.Literal("RL")])),
+            nodes: Type.Array(
+              Type.Object({
+                id: Type.String({ minLength: 1, maxLength: 64, pattern: nodeIdPattern.source }),
+                label: Type.String({ minLength: 1, maxLength: maxLabelLength }),
+              }),
+              { minItems: 1, maxItems: maxNodes },
+            ),
+            edges: Type.Array(
+              Type.Object({
+                from: Type.String({ minLength: 1, maxLength: 64, pattern: nodeIdPattern.source }),
+                to: Type.String({ minLength: 1, maxLength: 64, pattern: nodeIdPattern.source }),
+                label: Type.Optional(Type.String({ minLength: 1, maxLength: maxLabelLength })),
+              }),
+              { maxItems: maxEdges },
+            ),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         execute(_toolCallId, params): Promise<AgentToolResult<CanvasReport>> {
           return Promise.resolve().then(() => {
-            const nodes = params.nodes.map((node) => ({ id: node.id.trim(), label: label(node.label, "Node label") }));
-            const edges = params.edges.map((edge) => ({
-              from: edge.from.trim(),
-              to: edge.to.trim(),
-              ...(edge.label === undefined ? {} : { label: label(edge.label, "Edge label") }),
-            }));
-            if (nodes.length === 0 || nodes.length > maxNodes) throw new Error(`Canvas must contain 1-${maxNodes} nodes`);
-            if (edges.length > maxEdges) throw new Error(`Canvas must contain at most ${maxEdges} edges`);
+            const input = typeof params === "object" && params !== null ? (params as Record<string, unknown>) : {};
+            const rawNodes = input.nodes;
+            const rawEdges = input.edges;
+            if (!Array.isArray(rawNodes)) throw new Error("Canvas nodes must be an array");
+            if (!Array.isArray(rawEdges)) throw new Error("Canvas edges must be an array");
+            if (rawNodes.length === 0 || rawNodes.length > maxNodes) throw new Error(`Canvas must contain 1-${maxNodes} nodes`);
+            if (rawEdges.length > maxEdges) throw new Error(`Canvas must contain at most ${maxEdges} edges`);
+            const flowDirection = direction(input.direction);
+            const nodes = rawNodes.map((rawNode, index) => {
+              if (typeof rawNode !== "object" || rawNode === null) throw new Error(`Canvas node ${index + 1} must be an object`);
+              const node = rawNode as Record<string, unknown>;
+              return { id: nodeId(node.id, "Node id"), label: label(node.label, "Node label") };
+            });
+            const edges = rawEdges.map((rawEdge, index) => {
+              if (typeof rawEdge !== "object" || rawEdge === null) throw new Error(`Canvas edge ${index + 1} must be an object`);
+              const edge = rawEdge as Record<string, unknown>;
+              return {
+                from: nodeId(edge.from, "Edge source id"),
+                to: nodeId(edge.to, "Edge target id"),
+                ...(edge.label === undefined ? {} : { label: label(edge.label, "Edge label") }),
+              };
+            });
             const ids = new Set<string>();
             for (const node of nodes) {
-              if (!nodeIdPattern.test(node.id)) throw new Error(`Invalid node id: ${node.id}`);
               if (ids.has(node.id)) throw new Error(`Duplicate node id: ${node.id}`);
               ids.add(node.id);
             }
@@ -61,15 +114,15 @@ export default {
               if (!ids.has(edge.from) || !ids.has(edge.to)) throw new Error(`Canvas edge references an unknown node: ${edge.from} -> ${edge.to}`);
             }
             const report: CanvasReport = {
-              direction: params.direction ?? "TD",
+              direction: flowDirection,
               nodes,
               edges,
               nodeCount: nodes.length,
               edgeCount: edges.length,
-              mermaid: render(params.direction ?? "TD", nodes, edges),
+              mermaid: render(flowDirection, nodes, edges),
             };
             latest = report;
-            return { content: [{ type: "text" as const, text: report.mermaid }], details: report };
+            return { content: [{ type: "text" as const, text: report.mermaid }], details: structuredClone(report) };
           });
         },
       }),
@@ -80,7 +133,7 @@ export default {
       title: "Canvas Draw",
       description: "将结构化节点和边转换为可复制的 Mermaid 流程图源码。",
       icon: "⌘",
-      read: () => ({ latest: latest ?? null, nodeCount: latest?.nodeCount ?? 0, edgeCount: latest?.edgeCount ?? 0 }),
+      read: () => ({ latest: latest === undefined ? null : structuredClone(latest), nodeCount: latest?.nodeCount ?? 0, edgeCount: latest?.edgeCount ?? 0 }),
     });
     context.effect(() => () => {
       unregisterTool();

package/packages/core/src/plugins/change-verifier.ts

@@ -1,8 +1,10 @@
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 
 type GateStatus = "pass" | "warning" | "fail";
+const maxScriptLength = 128;
 type GateReport = {
   status: GateStatus;
   script: string;
@@ -17,6 +19,13 @@ function detailsOf(result: unknown): Record<string, unknown> {
   return details !== null && typeof details === "object" ? (details as Record<string, unknown>) : {};
 }
 
+function scriptName(value: unknown): string {
+  if (value === undefined) return "test";
+  if (typeof value !== "string") throw new Error("Verification script must be a string");
+  if (value.length > maxScriptLength) throw new Error(`Verification script must contain between 1 and ${maxScriptLength} characters`);
+  return value.trim() || "test";
+}
+
 function requiredTool(context: Context, name: string): ToolDefinition {
   const tool = context.piTools.snapshot().customTools.find((candidate) => candidate.name === name);
   if (tool === undefined) throw new Error(`Change Verifier requires the ${name} tool; enable its provider plugin before pi-runtime`);
@@ -26,7 +35,9 @@ function requiredTool(context: Context, name: string): ToolDefinition {
 export default {
   name: "pi-change-verifier",
   inject: ["piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
+    const lifecycle = new AbortController();
     let runs = 0;
     let latest: GateReport | undefined;
     const unregisterTool = context.piTools.register(
@@ -35,30 +46,42 @@ export default {
         label: "Verify change gate",
         description: "Combine the existing project test and Git review tools into one deterministic release gate.",
         promptSnippet: "run the project test and review gate before declaring the change complete",
-        parameters: Type.Object({ script: Type.Optional(Type.String({ description: "Approved npm script handled by run_project_tests" })) }),
+        parameters: Type.Object(
+          {
+            script: Type.Optional(Type.String({ description: "Approved npm script handled by run_project_tests", minLength: 1, maxLength: maxScriptLength })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(toolCallId, params, signal, _onUpdate, toolContext): Promise<AgentToolResult<GateReport>> {
-          const script = params.script?.trim() || "test";
+          const actionSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          if (actionSignal.aborted)
+            throw actionSignal.reason instanceof Error ? actionSignal.reason : new Error("Change verification was cancelled", { cause: actionSignal.reason });
+          const script = scriptName(params?.script);
           const reviewTool = requiredTool(context, "review_changes");
           const testTool = requiredTool(context, "run_project_tests");
-          const reviewResult = await reviewTool.execute(`${toolCallId}:review`, {}, signal, undefined, toolContext);
-          const testResult = await testTool.execute(`${toolCallId}:tests`, { script }, signal, undefined, toolContext);
+          const reviewResult = await reviewTool.execute(`${toolCallId}:review`, {}, actionSignal, undefined, toolContext);
+          const testResult = await testTool.execute(`${toolCallId}:tests`, { script }, actionSignal, undefined, toolContext);
           const review = detailsOf(reviewResult);
           const tests = detailsOf(testResult);
-          const exitCode = typeof tests.exitCode === "number" ? tests.exitCode : 1;
-          const reviewStatus = typeof review.status === "string" ? review.status : "error";
+          const exitCode =
+            typeof tests.exitCode === "number" && Number.isInteger(tests.exitCode) && tests.exitCode >= 0 && tests.exitCode <= 255 ? tests.exitCode : 1;
+          const durationMs =
+            typeof tests.durationMs === "number" && Number.isFinite(tests.durationMs) && tests.durationMs >= 0 ? Math.trunc(tests.durationMs) : 0;
+          const reviewStatus = review.status === "pass" || review.status === "warning" || review.status === "error" ? review.status : "error";
           const findings = Array.isArray(review.findings) ? review.findings.length : 0;
           const status: GateStatus = exitCode !== 0 || reviewStatus === "error" ? "fail" : reviewStatus === "warning" ? "warning" : "pass";
           latest = {
             status,
             script,
-            tests: { exitCode, durationMs: typeof tests.durationMs === "number" ? tests.durationMs : 0 },
+            tests: { exitCode, durationMs },
             review: { status: reviewStatus, findings },
             checkedAt: new Date().toISOString(),
           };
           runs += 1;
           return {
             content: [{ type: "text", text: `${status}: tests exit ${exitCode}; review ${reviewStatus} with ${findings} finding(s).` }],
-            details: latest,
+            details: structuredClone(latest),
           };
         },
       }),
@@ -69,9 +92,10 @@ export default {
       title: "Change Verifier",
       description: "复用真实测试和代码审查工具，形成统一发布门禁。",
       icon: "✓",
-      read: () => ({ runs, latest: latest ?? null }),
+      read: () => ({ runs, latest: latest === undefined ? null : structuredClone(latest) }),
     });
     context.effect(() => () => {
+      lifecycle.abort(new Error("Change Verifier plugin disposed"));
       unregisterTool();
       disposePanel();
     });

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

@@ -1,59 +1,361 @@
-import { readdir, stat, unlink } from "node:fs/promises";
+import { lstat, opendir } from "node:fs/promises";
+import { lstatSync, unlinkSync } from "node:fs";
 import { join } 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";
 
+export type CleanerConfig = Record<never, never>;
+
+export const Config: z<CleanerConfig> = z.object({});
+
 const capsuleDirectory = "capsules";
+const maxCapsules = 256;
+const maxDirectoryEntries = 4096;
 type Capsule = { name: string; bytes: number };
+type CapsuleEntry = Capsule & { device: number; inode: number };
+type DirectoryIdentity = { device: number; inode: number };
+type CleanupActivity = {
+  status: "running" | "completed" | "failed" | "cancelled";
+  at: string;
+  requestedKeep: number;
+  removed: number;
+  kept?: number;
+  error?: string;
+};
+
+const maxPanelCapsules = 20;
+const maxErrorLength = 2_000;
+const parameterNames = new Set(["confirm", "keep"]);
+const unsafeUnicode = /[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u;
+
+function dataObject(value: unknown, label: string): PropertyDescriptorMap {
+  if (value === null || typeof value !== "object") throw new Error(`${label} must be a plain object`);
+  let array: boolean;
+  let prototype: unknown;
+  let descriptors: PropertyDescriptorMap;
+  try {
+    array = Array.isArray(value);
+    prototype = Object.getPrototypeOf(value) as unknown;
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    throw new Error(`${label} must be an accessible plain object`, { cause: error });
+  }
+  if (array || (prototype !== Object.prototype && prototype !== null)) throw new Error(`${label} must be a plain object`);
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error(`${label} must use data properties`);
+  return descriptors;
+}
+
+function assertConfig(config: unknown): asserts config is CleanerConfig {
+  const descriptors = dataObject(config, "Cleaner config");
+  const unknown = Reflect.ownKeys(descriptors);
+  if (unknown.length > 0) throw new Error(`Unknown Cleaner config key: ${typeof unknown[0] === "symbol" ? "symbol" : unknown[0]}`);
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Cleaner operation was cancelled", { cause: signal.reason });
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT";
+}
+
+function rejectionError(error: unknown, message: string): Error {
+  return error instanceof Error ? error : new Error(message, { cause: error });
+}
+
+function withCancellation<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  try {
+    throwIfAborted(signal);
+  } catch (error) {
+    return Promise.reject(rejectionError(error, "Cleaner operation was cancelled"));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      try {
+        throwIfAborted(signal);
+      } catch (error) {
+        reject(rejectionError(error, "Cleaner operation was cancelled"));
+      }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    void operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(rejectionError(error, "Cleaner operation failed"));
+      },
+    );
+  });
+}
 
-async function listCapsules(directory: string): Promise<Capsule[]> {
-  const names = (await readdir(directory).catch(() => [] as string[]))
-    .filter((name) => name.endsWith(".patch"))
-    .sort()
-    .reverse();
-  return Promise.all(names.map(async (name) => ({ name, bytes: (await stat(join(directory, name))).size })));
+function boundedError(error: unknown): string {
+  let message: string | undefined;
+  if (typeof error === "string") message = error;
+  else if (typeof error === "object" && error !== null) {
+    try {
+      const descriptor = Object.getOwnPropertyDescriptor(error, "message");
+      if (descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string") message = descriptor.value;
+    } catch {
+      // Fall through to the stable message below.
+    }
+  }
+  if (message === undefined) return "Unknown cleaner error";
+  let output = "";
+  let outputBytes = 0;
+  let outputCharacters = 0;
+  let scanned = 0;
+  for (const character of message) {
+    scanned += 1;
+    if (scanned > maxErrorLength * 4) break;
+    const safe = unsafeUnicode.test(character) ? " " : character;
+    if (output === "" && /^\s$/u.test(safe)) continue;
+    const bytes = Buffer.byteLength(safe, "utf8");
+    if (outputCharacters >= maxErrorLength || outputBytes + bytes > maxErrorLength) break;
+    output += safe;
+    outputBytes += bytes;
+    outputCharacters += 1;
+  }
+  return output.trimEnd() || "Unknown cleaner error";
+}
+
+function publicError(error: unknown): Error {
+  const message = boundedError(error);
+  return new Error(message === "Unknown cleaner error" ? "Cleaner operation failed" : message, { cause: error });
+}
+
+async function directoryIdentity(directory: string, signal?: AbortSignal): Promise<DirectoryIdentity | undefined> {
+  throwIfAborted(signal);
+  let metadata: Awaited<ReturnType<typeof lstat>>;
+  try {
+    metadata = await lstat(directory);
+  } catch (error) {
+    if (isMissing(error)) return undefined;
+    throw error;
+  }
+  throwIfAborted(signal);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error("Cleaner capsule directory must be a regular directory, not a symbolic link");
+  return { device: metadata.dev, inode: metadata.ino };
+}
+
+async function requireSameDirectory(directory: string, expected: DirectoryIdentity, signal?: AbortSignal): Promise<void> {
+  const current = await directoryIdentity(directory, signal);
+  if (current === undefined || current.device !== expected.device || current.inode !== expected.inode)
+    throw new Error("Cleaner capsule directory changed while the operation was running");
+}
+
+function parseKeep(params: unknown): number {
+  const descriptors = dataObject(params, "Cleaner parameters");
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !parameterNames.has(key)))
+    throw new Error("Cleaner parameters contain an unknown property");
+  const confirm: unknown = descriptors.confirm?.value;
+  if (confirm !== true) throw new Error("Cleaning requires confirm=true");
+  const keepValue: unknown = descriptors.keep?.value;
+  const keep = keepValue === undefined ? 5 : keepValue;
+  if (typeof keep !== "number" || !Number.isInteger(keep) || keep < 0 || keep > maxCapsules)
+    throw new Error(`Cleaner keep must be an integer between 0 and ${maxCapsules}`);
+  return keep;
+}
+
+function safeCapsuleName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    name === name.trim() &&
+    name.endsWith(".patch") &&
+    [...name].length <= 255 &&
+    Buffer.byteLength(name, "utf8") <= 255 &&
+    !unsafeUnicode.test(name) &&
+    !name.includes("/") &&
+    !name.includes("\\")
+  );
+}
+
+async function listCapsules(directory: string, signal?: AbortSignal): Promise<{ capsules: CapsuleEntry[]; directory?: DirectoryIdentity }> {
+  const identity = await directoryIdentity(directory, signal);
+  if (identity === undefined) return { capsules: [] };
+  let handle: Awaited<ReturnType<typeof opendir>>;
+  try {
+    handle = await opendir(directory);
+  } catch (error) {
+    if (isMissing(error)) return { capsules: [] };
+    throw error;
+  }
+  const names: string[] = [];
+  let scanned = 0;
+  for await (const entry of handle) {
+    throwIfAborted(signal);
+    scanned += 1;
+    if (scanned > maxDirectoryEntries) throw new Error(`Cleaner capsule directory exceeds the ${maxDirectoryEntries}-entry scan limit`);
+    if (!entry.isFile() || !safeCapsuleName(entry.name)) continue;
+    names.push(entry.name);
+    if (names.length > maxCapsules) throw new Error(`Cleaner capsule directory exceeds the ${maxCapsules}-capsule limit`);
+  }
+  names.sort().reverse();
+  const capsules: CapsuleEntry[] = [];
+  for (const name of names) {
+    throwIfAborted(signal);
+    let metadata: Awaited<ReturnType<typeof lstat>>;
+    try {
+      metadata = await lstat(join(directory, name));
+    } catch (error) {
+      if (isMissing(error)) continue;
+      throw error;
+    }
+    if (metadata.isFile() && !metadata.isSymbolicLink()) capsules.push({ name, bytes: metadata.size, device: metadata.dev, inode: metadata.ino });
+  }
+  await requireSameDirectory(directory, identity, signal);
+  return { capsules, directory: identity };
 }
 
 export default {
   name: "pi-cleaner",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context) {
+  Config,
+  apply(context: Context, config: CleanerConfig) {
+    assertConfig(config);
     const directory = join(context.piHarnessLaunch.agentDir, capsuleDirectory);
-    let lastRemoved = 0;
-    const unregisterTool = context.piTools.register(
-      defineTool({
-        name: "clean_harness_artifacts",
-        label: "Clean harness artifacts",
-        description: "Remove only Pi Harness Git capsule patch files from the agent data directory. Confirmation is required.",
-        promptSnippet: "clean old Pi Harness rollback artifacts",
-        parameters: Type.Object({
-          confirm: Type.Boolean({ description: "Must be true to remove files" }),
-          keep: Type.Optional(Type.Number({ description: "Number of newest capsules to keep" })),
+    const lifecycle = new AbortController();
+    let cleanupQueue: Promise<void> = Promise.resolve();
+    let lastCleanup: CleanupActivity | undefined;
+    let sequence = 0;
+    let visibleSequence = 0;
+    const runExclusive = <T>(operation: () => Promise<T>, signal: AbortSignal): Promise<T> => {
+      const result = cleanupQueue.then(operation, operation);
+      cleanupQueue = result.then(
+        () => undefined,
+        () => undefined,
+      );
+      return withCancellation(result, signal);
+    };
+    let unregisterTool: () => void = () => undefined;
+    let disposePanel: () => void = () => undefined;
+    try {
+      unregisterTool = context.piTools.register(
+        defineTool({
+          name: "clean_harness_artifacts",
+          label: "Clean harness artifacts",
+          description: "Remove only Pi Harness Git capsule patch files from the agent data directory. Confirmation is required.",
+          promptSnippet: "clean old Pi Harness rollback artifacts",
+          parameters: Type.Object(
+            {
+              confirm: Type.Boolean({ description: "Must be true to remove files" }),
+              keep: Type.Optional(Type.Integer({ description: "Number of newest capsules to keep, from 0 to 256", minimum: 0, maximum: maxCapsules })),
+            },
+            { additionalProperties: false },
+          ),
+          executionMode: "sequential",
+          async execute(_toolCallId, rawParams, signal): Promise<AgentToolResult<{ removed: number; kept: number }>> {
+            const actionSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+            throwIfAborted(actionSignal);
+            const keep = parseKeep(rawParams);
+            const operationSequence = ++sequence;
+            let removed = 0;
+            const updateActivity = (activity: CleanupActivity): void => {
+              if (operationSequence < visibleSequence) return;
+              visibleSequence = operationSequence;
+              lastCleanup = activity;
+            };
+            updateActivity({ status: "running", at: new Date().toISOString(), requestedKeep: keep, removed });
+            try {
+              return await runExclusive(async () => {
+                try {
+                  throwIfAborted(actionSignal);
+                  const inventory = await listCapsules(directory, actionSignal);
+                  const remove = inventory.capsules.slice(keep);
+                  for (const capsule of remove) {
+                    throwIfAborted(actionSignal);
+                    if (inventory.directory === undefined) throw new Error("Cleaner capsule directory disappeared while the operation was running");
+                    await requireSameDirectory(directory, inventory.directory, actionSignal);
+                    let metadata: ReturnType<typeof lstatSync>;
+                    try {
+                      // Keep the final directory identity check, target identity check, and unlink
+                      // in one synchronous turn so an async scheduler cannot interpose a parent swap.
+                      const currentDirectory = lstatSync(directory);
+                      if (
+                        !currentDirectory.isDirectory() ||
+                        currentDirectory.isSymbolicLink() ||
+                        currentDirectory.dev !== inventory.directory.device ||
+                        currentDirectory.ino !== inventory.directory.inode
+                      )
+                        throw new Error("Cleaner capsule directory changed before deletion");
+                      metadata = lstatSync(join(directory, capsule.name));
+                    } catch (error) {
+                      if (isMissing(error)) continue;
+                      throw error;
+                    }
+                    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.dev !== capsule.device || metadata.ino !== capsule.inode)
+                      throw new Error(`Cleaner capsule changed before deletion: ${capsule.name}`);
+                    unlinkSync(join(directory, capsule.name));
+                    removed += 1;
+                  }
+                  const finalInventory = await listCapsules(directory, actionSignal);
+                  const kept = finalInventory.capsules.length;
+                  updateActivity({ status: "completed", at: new Date().toISOString(), requestedKeep: keep, removed, kept });
+                  return {
+                    content: [{ type: "text" as const, text: `Removed ${removed} Pi Harness capsule(s); kept ${kept}.` }],
+                    details: { removed, kept },
+                  };
+                } catch (error) {
+                  updateActivity({
+                    status: actionSignal.aborted ? "cancelled" : "failed",
+                    at: new Date().toISOString(),
+                    requestedKeep: keep,
+                    removed,
+                    error: boundedError(error),
+                  });
+                  throw error;
+                }
+              }, actionSignal);
+            } catch (error) {
+              updateActivity({
+                status: actionSignal.aborted ? "cancelled" : "failed",
+                at: new Date().toISOString(),
+                requestedKeep: keep,
+                removed,
+                error: boundedError(error),
+              });
+              throw publicError(error);
+            }
+          },
         }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<{ removed: number; kept: number }>> {
-          if (params.confirm !== true) throw new Error("Cleaning requires confirm=true");
-          const keep = Math.max(0, Math.trunc(params.keep ?? 5));
-          const capsules = await listCapsules(directory);
-          const remove = capsules.slice(keep);
-          await Promise.all(remove.map((capsule) => unlink(join(directory, capsule.name))));
-          lastRemoved = remove.length;
+      );
+      disposePanel = context.piPluginUi.register({
+        id: "cleaner-panel",
+        pluginId: "@pi-harness/core/plugins/cleaner",
+        title: "Harness Cleaner",
+        description: "清理 Pi Harness 自己生成的 Git 快照；默认不会触碰项目文件。",
+        icon: "⌫",
+        read: async () => {
+          const inventory = await listCapsules(directory, lifecycle.signal);
+          const capsules = inventory.capsules.slice(0, maxPanelCapsules).map(({ name, bytes }) => ({ name, bytes }));
           return {
-            content: [{ type: "text", text: `Removed ${remove.length} Pi Harness capsule(s); kept ${capsules.length - remove.length}.` }],
-            details: { removed: remove.length, kept: capsules.length - remove.length },
+            capsules,
+            inventory: {
+              total: inventory.capsules.length,
+              shown: capsules.length,
+              truncated: inventory.capsules.length > capsules.length,
+              displayLimit: maxPanelCapsules,
+            },
+            lastCleanup: lastCleanup === undefined ? null : { ...lastCleanup },
+            lastRemoved: lastCleanup?.removed ?? 0,
+            limits: { capsules: maxCapsules, directoryEntries: maxDirectoryEntries },
           };
         },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "cleaner-panel",
-      pluginId: "@pi-harness/core/plugins/cleaner",
-      title: "Harness Cleaner",
-      description: "清理 Pi Harness 自己生成的 Git 快照；默认不会触碰项目文件。",
-      icon: "⌫",
-      read: async () => ({ directory, capsules: await listCapsules(directory), lastRemoved }),
-    });
+      });
+    } catch (error) {
+      disposePanel();
+      unregisterTool();
+      lifecycle.abort(new Error("Cleaner plugin registration failed"));
+      throw error;
+    }
     context.effect(() => () => {
+      lifecycle.abort(new Error("Cleaner plugin disposed"));
       unregisterTool();
       disposePanel();
     });