@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/workspace-navigator.ts

@@ -3,12 +3,14 @@ import { execFile } from "node:child_process";
 import { relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { resolveExistingWorkspacePath } from "../workspace-path.js";
 
 const maxDepthLimit = 8;
 const maxNodesLimit = 500;
+const defaultGitTimeoutMs = 10_000;
 const ignoredDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
 
 export type WorkspaceNode = { kind: "directory" | "file"; name: string; path: string; depth: number };
@@ -19,11 +21,12 @@ export type WorkspaceGitStatus = { available: boolean; branch: string | null; cl
 
 const execFileAsync = promisify(execFile);
 
-export async function readWorkspaceGitStatus(root: string): Promise<WorkspaceGitStatus> {
+export async function readWorkspaceGitStatus(root: string, requestedTimeoutMs = defaultGitTimeoutMs): Promise<WorkspaceGitStatus> {
+  const timeoutMs = Math.max(100, Math.min(60_000, Math.trunc(requestedTimeoutMs)));
   try {
     const [branchResult, statusResult] = await Promise.all([
-      execFileAsync("git", ["-C", root, "branch", "--show-current"], { maxBuffer: 1024 * 1024 }),
-      execFileAsync("git", ["-C", root, "status", "--short", "--untracked-files=all"], { maxBuffer: 4 * 1024 * 1024 }),
+      execFileAsync("git", ["-C", root, "branch", "--show-current"], { maxBuffer: 1024 * 1024, timeout: timeoutMs }),
+      execFileAsync("git", ["-C", root, "status", "--short", "--untracked-files=all"], { maxBuffer: 4 * 1024 * 1024, timeout: timeoutMs }),
     ]);
     const entries = statusResult.stdout
       .split("\n")
@@ -35,6 +38,12 @@ export async function readWorkspaceGitStatus(root: string): Promise<WorkspaceGit
   }
 }
 
+export interface WorkspaceNavigatorPluginConfig {
+  gitTimeoutMs?: number;
+}
+
+export const Config: z<WorkspaceNavigatorPluginConfig> = z.object({ gitTimeoutMs: z.number().default(defaultGitTimeoutMs) });
+
 function normalizeOptions(options: WorkspaceNodeOptions): { maxDepth: number; maxNodes: number } {
   return {
     maxDepth: Math.max(1, Math.min(maxDepthLimit, Math.trunc(options.maxDepth ?? 4))),
@@ -48,8 +57,17 @@ export async function listWorkspaceNodes(root: string, options: WorkspaceNodeOpt
   const nodes: WorkspaceNode[] = [];
   let truncated = false;
   const visit = async (directory: string, depth: number): Promise<void> => {
-    if (depth > maxDepth || nodes.length >= maxNodes) {
-      if (nodes.length >= maxNodes) truncated = true;
+    if (nodes.length >= maxNodes) {
+      truncated = true;
+      return;
+    }
+    if (depth > maxDepth) {
+      try {
+        const hiddenEntries = await readdir(directory, { withFileTypes: true });
+        if (hiddenEntries.some((entry) => (entry.isDirectory() ? !ignoredDirectories.has(entry.name) : entry.isFile()))) truncated = true;
+      } catch {
+        truncated = true;
+      }
       return;
     }
     const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
@@ -84,7 +102,9 @@ export async function listWorkspaceNodes(root: string, options: WorkspaceNodeOpt
 export default {
   name: "pi-workspace-navigator",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context) {
+  Config,
+  apply(context: Context, config: WorkspaceNavigatorPluginConfig) {
+    const gitTimeoutMs = Math.max(100, Math.min(60_000, Math.trunc(config.gitTimeoutMs ?? defaultGitTimeoutMs)));
     let latest: (WorkspaceNodeReport & { path: string; maxDepth: number; maxNodes: number }) | undefined;
     let latestGit: WorkspaceGitStatus | undefined;
     const inspect = async (requestedPath: string | undefined, requestedDepth: number | undefined, requestedNodes: number | undefined) => {
@@ -112,11 +132,15 @@ export default {
         label: "Workspace tree",
         description: "Show a bounded, read-only workspace tree while skipping dependency and build directories.",
         promptSnippet: "inspect the workspace directory tree",
-        parameters: Type.Object({
-          path: Type.Optional(Type.String({ description: "Relative directory path" })),
-          maxDepth: Type.Optional(Type.Number({ description: "Tree depth, 1-8" })),
-          maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes, 1-500" })),
-        }),
+        parameters: Type.Object(
+          {
+            path: Type.Optional(Type.String({ description: "Relative directory path" })),
+            maxDepth: Type.Optional(Type.Number({ description: "Tree depth, 1-8" })),
+            maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes, 1-500" })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<WorkspaceNodeReport & { path: string; maxDepth: number; maxNodes: number }>> {
           const report = await inspect(params.path, params.maxDepth, params.maxNodes);
           return {
@@ -137,9 +161,10 @@ export default {
         label: "Workspace status",
         description: "Show the current workspace Git branch and changed files without modifying the repository.",
         promptSnippet: "inspect the workspace Git status",
-        parameters: Type.Object({}),
+        parameters: Type.Object({}, { additionalProperties: false }),
+        executionMode: "sequential",
         async execute(): Promise<AgentToolResult<WorkspaceGitStatus>> {
-          latestGit = await readWorkspaceGitStatus(context.piHarnessLaunch.cwd);
+          latestGit = await readWorkspaceGitStatus(context.piHarnessLaunch.cwd, gitTimeoutMs);
           const summary = latestGit.available
             ? `${latestGit.branch ?? "detached HEAD"}: ${latestGit.clean ? "clean" : `${latestGit.entries.length} changed file(s)`}`
             : "Not a Git workspace.";
@@ -153,7 +178,7 @@ export default {
       title: "Workspace Navigator",
       description: "以受限目录树快速浏览当前工作区，不执行写操作。",
       icon: "⌘",
-      read: () => ({ latest: latest ?? null, git: latestGit ?? null, nodeCount: latest?.nodes.length ?? 0 }),
+      read: () => ({ latest: latest ?? null, git: latestGit ?? null, nodeCount: latest?.nodes.length ?? 0, gitTimeoutMs }),
     });
     context.effect(() => () => {
       unregister();

package/packages/core/src/plugins/workspace-search.ts

@@ -1,53 +1,66 @@
-import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 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 { readBoundedFile } from "../bounded-file.js";
+import { EmptyConfig } from "../config.js";
 
 const maxQueryLength = 256;
 const maxPathLength = 512;
 const maxFileBytes = 2 * 1024 * 1024;
 const maxFiles = 2_000;
+const maxDirectories = 512;
+const maxDepth = 16;
 const maxResults = 100;
 const ignoredDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
 type SearchMatch = { path: string; line: number; text: string };
 type SearchReport = { query: string; path: string; matches: SearchMatch[]; matchCount: number; scannedFiles: number; skippedFiles: number; truncated: boolean };
 
-function inside(root: string, target: string): boolean {
-  const remainder = relative(root, target);
-  return remainder === "" || (remainder !== ".." && !remainder.startsWith(`..${"/"}`) && !remainder.startsWith("/"));
+type PathSemantics = { isAbsolute(path: string): boolean; relative(from: string, to: string): string; sep: string };
+const nativePathSemantics: PathSemantics = { isAbsolute, relative, sep };
+
+export function isWorkspaceSearchPathInside(root: string, target: string, pathSemantics: PathSemantics = nativePathSemantics): boolean {
+  const remainder = pathSemantics.relative(root, target);
+  return remainder === "" || (remainder !== ".." && !remainder.startsWith(`..${pathSemantics.sep}`) && !pathSemantics.isAbsolute(remainder));
 }
 
 function workspacePath(root: string, requested: string): string {
   if (requested.length > maxPathLength || requested.includes("\\"))
     throw new Error("Workspace search path must be a relative POSIX path of at most 512 characters");
   const target = resolve(root, requested || ".");
-  if (!inside(root, target)) throw new Error("Workspace search path must stay inside the current workspace");
+  if (!isWorkspaceSearchPathInside(root, target)) throw new Error("Workspace search path must stay inside the current workspace");
   return target;
 }
 
-async function filesUnder(target: string, root: string, files: string[]): Promise<void> {
-  if (files.length >= maxFiles) return;
+type WalkState = { files: string[]; directories: number };
+
+async function filesUnder(target: string, root: string, state: WalkState, depth = 0): Promise<boolean> {
+  if (state.files.length >= maxFiles || state.directories >= maxDirectories || depth > maxDepth) return true;
   const metadata = await lstat(target);
-  if (metadata.isSymbolicLink()) return;
+  if (metadata.isSymbolicLink()) return false;
   if (metadata.isFile()) {
-    files.push(target);
-    return;
+    state.files.push(target);
+    return false;
   }
-  if (!metadata.isDirectory()) return;
+  if (!metadata.isDirectory()) return false;
+  state.directories += 1;
+  if (depth >= maxDepth) return true;
   const entries = (await readdir(target, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
   for (const entry of entries) {
-    if (files.length >= maxFiles) return;
+    if (state.files.length >= maxFiles || state.directories >= maxDirectories) return true;
     if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
     const child = resolve(target, entry.name);
-    if (!inside(root, child)) continue;
-    await filesUnder(child, root, files);
+    if (!isWorkspaceSearchPathInside(root, child)) continue;
+    if (await filesUnder(child, root, state, depth + 1)) return true;
   }
+  return false;
 }
 
 export default {
   name: "pi-workspace-search",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: SearchReport | undefined;
     const search = async (
@@ -62,31 +75,46 @@ export default {
       const root = await realpath(context.piHarnessLaunch.cwd);
       const target = workspacePath(root, requestedPath?.trim() ?? ".");
       const targetMetadata = await stat(target);
-      const files: string[] = [];
-      await filesUnder(target, root, files);
+      const walkState: WalkState = { files: [], directories: 0 };
+      const filesTruncated = await filesUnder(target, root, walkState);
+      const files = walkState.files;
       const limit = Math.max(1, Math.min(maxResults, Math.trunc(requestedLimit ?? maxResults)));
       const needle = caseSensitive ? normalizedQuery : normalizedQuery.toLocaleLowerCase();
       const matches: SearchMatch[] = [];
       let scannedFiles = 0;
       let skippedFiles = targetMetadata.isFile() && targetMetadata.size > maxFileBytes ? 1 : 0;
+      let stoppedAtLimit = false;
       for (const file of files) {
-        if (matches.length >= limit) break;
+        if (matches.length >= limit) {
+          stoppedAtLimit = true;
+          break;
+        }
         const metadata = await stat(file);
         if (metadata.size > maxFileBytes) {
           skippedFiles += 1;
           continue;
         }
-        const source = await readFile(file);
-        if (source.includes(0)) {
+        let source: string;
+        try {
+          const bytes = await readBoundedFile(file, maxFileBytes, "Workspace search file");
+          if (bytes.includes(0)) {
+            skippedFiles += 1;
+            continue;
+          }
+          source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        } catch {
           skippedFiles += 1;
           continue;
         }
         scannedFiles += 1;
-        const lines = source.toString("utf8").split(/\r?\n/u);
+        const lines = source.split(/\r?\n/u);
         for (const [index, line] of lines.entries()) {
           if ((caseSensitive ? line : line.toLocaleLowerCase()).includes(needle)) {
             matches.push({ path: relative(root, file), line: index + 1, text: line });
-            if (matches.length >= limit) break;
+            if (matches.length >= limit) {
+              stoppedAtLimit = true;
+              break;
+            }
           }
         }
       }
@@ -97,7 +125,7 @@ export default {
         matchCount: matches.length,
         scannedFiles,
         skippedFiles,
-        truncated: matches.length >= limit && files.length > scannedFiles,
+        truncated: filesTruncated || stoppedAtLimit,
       };
       latest = report;
       return report;
@@ -108,12 +136,16 @@ export default {
         label: "Search workspace",
         description: "Search bounded UTF-8 text files in the current workspace without modifying files or invoking a shell.",
         promptSnippet: "search the workspace for a text pattern",
-        parameters: Type.Object({
-          query: Type.String(),
-          path: Type.Optional(Type.String()),
-          caseSensitive: Type.Optional(Type.Boolean()),
-          maxResults: Type.Optional(Type.Number()),
-        }),
+        parameters: Type.Object(
+          {
+            query: Type.String(),
+            path: Type.Optional(Type.String()),
+            caseSensitive: Type.Optional(Type.Boolean()),
+            maxResults: Type.Optional(Type.Number()),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<SearchReport>> {
           const report = await search(params.query, params.path, params.caseSensitive === true, params.maxResults);
           return {
@@ -123,14 +155,20 @@ export default {
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "workspace-search-panel",
-      pluginId: "@pi-harness/core/plugins/workspace-search",
-      title: "Workspace Search",
-      description: "在工作区内安全检索文本，跳过依赖、构建产物和版本库目录。",
-      icon: "⌕",
-      read: () => ({ latest: latest ?? null, query: latest?.query ?? null, matchCount: latest?.matchCount ?? 0, scannedFiles: latest?.scannedFiles ?? 0 }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "workspace-search-panel",
+        pluginId: "@pi-harness/core/plugins/workspace-search",
+        title: "Workspace Search",
+        description: "在工作区内安全检索文本，跳过依赖、构建产物和版本库目录。",
+        icon: "⌕",
+        read: () => ({ latest: latest ?? null, query: latest?.query ?? null, matchCount: latest?.matchCount ?? 0, scannedFiles: latest?.scannedFiles ?? 0 }),
+      });
+    } catch (error) {
+      unregisterTool();
+      throw error;
+    }
     context.effect(() => () => {
       unregisterTool();
       disposePanel();

package/packages/core/src/plugins/yaml-validator.ts

@@ -1,27 +1,40 @@
-import { readFile, realpath, stat } from "node:fs/promises";
-import { relative, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import { parseAllDocuments, isMap, isSeq, type YAMLParseError, type YAMLWarning } from "yaml";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { readBoundedFile } from "../bounded-file.js";
+import { EmptyConfig } from "../config.js";
+import { resolveExistingWorkspacePath } from "../workspace-path.js";
 
 const maxBytes = 512 * 1024;
+const maxPathLength = 4_096;
+const maxDocuments = 100;
+const maxDiagnostics = 1_000;
+const maxToolDiagnostics = 50;
+const maxPanelDiagnostics = 50;
+const maxDiagnosticMessageLength = 2_000;
+const maxStatusErrorLength = 2_000;
+const pathParameterNames = new Set(["path"]);
 type Diagnostic = { message: string; code?: string; line?: number; column?: number };
-type YamlReport = { path: string; valid: boolean; bytes: number; documents: number; rootType: string; errors: Diagnostic[]; warnings: Diagnostic[] };
-
-function workspacePath(workspace: string, requested: string): { absolute: string; relative: string } {
-  const root = resolve(workspace);
-  const target = resolve(root, requested);
-  const path = relative(root, target);
-  if (path.startsWith("..") || path.includes("/..")) throw new Error("YAML path must stay inside the current workspace");
-  return { absolute: target, relative: path || "." };
-}
+type ValidationStatus = { state: "idle" | "running" | "completed" | "failed" | "cancelled"; at?: string; error?: string };
+type YamlReport = {
+  path: string;
+  valid: boolean;
+  bytes: number;
+  documents: number;
+  rootType: string;
+  errorCount: number;
+  warningCount: number;
+  diagnosticsTruncated: boolean;
+  errors: Diagnostic[];
+  warnings: Diagnostic[];
+};
 
 function diagnostic(issue: YAMLParseError | YAMLWarning): Diagnostic {
   const position = issue.linePos?.[0];
   return {
-    message: issue.message,
-    ...(typeof issue.code === "string" ? { code: issue.code } : {}),
+    message: issue.message.slice(0, maxDiagnosticMessageLength),
+    ...(typeof issue.code === "string" ? { code: issue.code.slice(0, 128) } : {}),
     ...(position === undefined ? {} : { line: position.line, column: position.col }),
   };
 }
@@ -33,33 +46,91 @@ function rootType(value: unknown): string {
   return "scalar";
 }
 
+function pathParameter(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("YAML validator parameters must be an object");
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) throw new Error("YAML validator parameters must be a plain object");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !pathParameterNames.has(key)))
+      throw new Error("YAML validator parameters contain an unknown property");
+    if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("YAML validator parameters must use data properties");
+    const path: unknown = descriptors.path?.value as unknown;
+    if (typeof path !== "string") throw new Error("YAML validator path must be a string");
+    if (path.length === 0 || path.length > maxPathLength) throw new Error(`YAML validator path must contain 1-${maxPathLength} characters`);
+    if (path.includes("\0")) throw new Error("YAML validator path must not contain NUL characters");
+    return path;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      /^(?:YAML validator parameters must be a plain object|YAML validator parameters contain an unknown property|YAML validator parameters must use data properties|YAML validator path)/u.test(
+        error.message,
+      )
+    )
+      throw error;
+    throw new Error("YAML validator parameters must be an accessible plain object", { cause: error });
+  }
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw new Error("YAML validation was cancelled", { cause: signal.reason });
+}
+
+function boundedError(error: unknown): string {
+  if (typeof error === "string") return error.slice(0, maxStatusErrorLength);
+  if (typeof error === "object" && error !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(error, "message");
+    if (descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string") return descriptor.value.slice(0, maxStatusErrorLength);
+  }
+  return "Unknown YAML validation error";
+}
+
 export default {
   name: "pi-yaml-validator",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
+    const lifecycle = new AbortController();
     let latest: YamlReport | undefined;
-    const validate = async (requested: string): Promise<YamlReport> => {
-      const workspace = await realpath(context.piHarnessLaunch.cwd);
-      const requestedPath = workspacePath(workspace, requested);
-      const absolute = await realpath(requestedPath.absolute);
-      const location = workspacePath(workspace, absolute);
-      const metadata = await stat(location.absolute);
-      if (!metadata.isFile()) throw new Error("YAML path is not a file");
-      if (metadata.size > maxBytes) throw new Error("YAML file exceeds the 512 KiB validation limit");
-      const source = await readFile(location.absolute, "utf8");
+    let status: ValidationStatus = { state: "idle" };
+    const validate = async (requested: string, signal: AbortSignal): Promise<YamlReport> => {
+      throwIfAborted(signal);
+      const location = await resolveExistingWorkspacePath(context.piHarnessLaunch.cwd, requested, "YAML path must stay inside the current workspace");
+      throwIfAborted(signal);
+      const bytes = await readBoundedFile(location.target, maxBytes, "YAML file");
+      throwIfAborted(signal);
+      let source: string;
+      try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch (error) {
+        throw new Error("YAML file must contain valid UTF-8", { cause: error });
+      }
       const documents = parseAllDocuments(source);
-      const errors = documents.flatMap((document) => document.errors.map(diagnostic));
-      const warnings = documents.flatMap((document) => document.warnings.map(diagnostic));
+      throwIfAborted(signal);
+      if (documents.length > maxDocuments) throw new Error(`YAML streams cannot exceed ${maxDocuments} documents`);
+      const errorCount = documents.reduce((total, document) => total + document.errors.length, 0);
+      const warningCount = documents.reduce((total, document) => total + document.warnings.length, 0);
+      const errors = documents
+        .flatMap((document) => document.errors)
+        .slice(0, maxDiagnostics)
+        .map(diagnostic);
+      const warnings = documents
+        .flatMap((document) => document.warnings)
+        .slice(0, Math.max(0, maxDiagnostics - errors.length))
+        .map(diagnostic);
       const report: YamlReport = {
-        path: location.relative,
-        valid: errors.length === 0,
-        bytes: metadata.size,
+        path: location.relativePath,
+        valid: errorCount === 0,
+        bytes: bytes.byteLength,
         documents: documents.length,
         rootType: rootType(documents[0]?.contents),
+        errorCount,
+        warningCount,
+        diagnosticsTruncated: errorCount + warningCount > errors.length + warnings.length,
         errors,
         warnings,
       };
-      latest = report;
+      latest = structuredClone(report);
       return report;
     };
     const unregisterTool = context.piTools.register(
@@ -68,28 +139,76 @@ export default {
         label: "YAML validate",
         description: "Parse a YAML file in the current workspace and report line-aware errors without modifying it.",
         promptSnippet: "validate a YAML file and report syntax diagnostics",
-        parameters: Type.Object({ path: Type.String({ description: "YAML path relative to the workspace" }) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<YamlReport>> {
-          const report = await validate(params.path);
-          const summary = report.valid ? `YAML is valid (${report.documents} document(s)).` : `YAML is invalid with ${report.errors.length} error(s).`;
-          return {
-            content: [
-              { type: "text", text: `${summary}\n${report.errors.map((issue) => `${issue.line ?? "?"}:${issue.column ?? "?"} ${issue.message}`).join("\n")}` },
-            ],
-            details: report,
-          };
+        parameters: Type.Object(
+          { path: Type.String({ description: "YAML path relative to the workspace", minLength: 1, maxLength: maxPathLength }) },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<YamlReport>> {
+          const operationSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          status = { state: "running" };
+          try {
+            throwIfAborted(operationSignal);
+            const report = await validate(pathParameter(params), operationSignal);
+            status = { state: "completed", at: new Date().toISOString() };
+            const summary = report.valid ? `YAML is valid (${report.documents} document(s)).` : `YAML is invalid with ${report.errorCount} error(s).`;
+            const preview = report.errors.slice(0, maxToolDiagnostics);
+            const omitted = report.errorCount - preview.length;
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `${summary}\n${preview.map((issue) => `${issue.line ?? "?"}:${issue.column ?? "?"} ${issue.message}`).join("\n")}${omitted > 0 ? `\n… ${omitted} additional error(s) omitted from the text preview.` : ""}`,
+                },
+              ],
+              details: structuredClone(report),
+            };
+          } catch (error) {
+            status = { state: operationSignal.aborted ? "cancelled" : "failed", at: new Date().toISOString(), error: boundedError(error) };
+            throw error;
+          }
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "yaml-validator-panel",
-      pluginId: "@pi-harness/core/plugins/yaml-validator",
-      title: "YAML Validator",
-      description: "只读解析工作区 YAML，并展示行列级语法诊断。",
-      icon: "⌁",
-      read: () => ({ latest: latest ?? null, maxBytes }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "yaml-validator-panel",
+        pluginId: "@pi-harness/core/plugins/yaml-validator",
+        title: "YAML Validator",
+        description: "只读解析工作区 YAML，并展示行列级语法诊断。",
+        icon: "⌁",
+        read: () => {
+          const errors = structuredClone(latest?.errors.slice(0, maxPanelDiagnostics) ?? []);
+          const warnings = structuredClone(latest?.warnings.slice(0, Math.max(0, maxPanelDiagnostics - errors.length)) ?? []);
+          return {
+            latest: latest === undefined ? null : { ...structuredClone(latest), errors, warnings },
+            status: structuredClone(status),
+            maxBytes,
+            inventory: {
+              errors: { total: latest?.errorCount ?? 0, shown: errors.length, truncated: (latest?.errorCount ?? 0) > errors.length },
+              warnings: { total: latest?.warningCount ?? 0, shown: warnings.length, truncated: (latest?.warningCount ?? 0) > warnings.length },
+            },
+            limits: {
+              fileBytes: maxBytes,
+              pathCharacters: maxPathLength,
+              documents: maxDocuments,
+              diagnostics: maxDiagnostics,
+              panelDiagnostics: maxPanelDiagnostics,
+              toolDiagnostics: maxToolDiagnostics,
+              diagnosticMessageCharacters: maxDiagnosticMessageLength,
+              statusErrorCharacters: maxStatusErrorLength,
+            },
+          };
+        },
+      });
+    } catch (error) {
+      lifecycle.abort(new Error("YAML validator plugin activation failed", { cause: error }));
+      unregisterTool();
+      throw error;
+    }
     context.effect(() => () => {
+      lifecycle.abort(new Error("YAML validator plugin disposed"));
       unregisterTool();
       disposePanel();
     });

package/packages/core/src/runtime.ts

@@ -13,6 +13,7 @@ export class PiRuntime implements PiRuntimeService {
   readonly sessionRuntime: AgentSessionRuntime;
   #disposed = false;
   #sessionDisposed = false;
+  #disposePromise: Promise<void> | undefined;
 
   constructor(sessionRuntime: AgentSessionRuntime) {
     this.sessionRuntime = sessionRuntime;
@@ -32,9 +33,14 @@ export class PiRuntime implements PiRuntimeService {
     await this.session.abort();
   }
 
-  async dispose(): Promise<void> {
-    if (this.#disposed) return;
+  dispose(): Promise<void> {
+    if (this.#disposePromise !== undefined) return this.#disposePromise;
     this.#disposed = true;
+    this.#disposePromise = this.#disposeSession();
+    return this.#disposePromise;
+  }
+
+  async #disposeSession(): Promise<void> {
     try {
       // Settle an in-flight turn first so its tool results are persisted before session_shutdown runs.
       if (!this.session.isIdle) await this.session.abort();

package/packages/core/src/services.ts

@@ -81,6 +81,14 @@ export interface PiToolsLease extends PiToolsSnapshot {
 }
 
 const PI_BUILTIN_TOOL_NAMES = ["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"];
+const MAX_PI_TOOL_NAMES = 256;
+const MAX_PI_TOOL_NAME_LENGTH = 128;
+const PI_TOOL_NAME_PATTERN = /^[^\s\p{Cc}]+$/u;
+
+function assertPiToolName(name: unknown): asserts name is string {
+  if (typeof name !== "string" || name.length === 0 || name.length > MAX_PI_TOOL_NAME_LENGTH || !PI_TOOL_NAME_PATTERN.test(name))
+    throw new Error(`Pi tool name must contain 1-${MAX_PI_TOOL_NAME_LENGTH} non-whitespace, non-control characters`);
+}
 
 export class PiToolRegistry {
   readonly #names: string[];
@@ -88,10 +96,21 @@ export class PiToolRegistry {
   #leases = 0;
 
   constructor(names: readonly string[] = []) {
-    this.#names = [...names];
+    const uncheckedNames: unknown = names;
+    if (!Array.isArray(uncheckedNames) || uncheckedNames.length > MAX_PI_TOOL_NAMES)
+      throw new Error(`Pi tool names must contain at most ${MAX_PI_TOOL_NAMES} entries`);
+    const validatedNames: string[] = [];
+    for (const name of uncheckedNames) {
+      const uncheckedName: unknown = name;
+      assertPiToolName(uncheckedName);
+      validatedNames.push(uncheckedName);
+    }
+    if (new Set(validatedNames).size !== validatedNames.length) throw new Error("Pi tool names must be unique");
+    this.#names = validatedNames;
   }
 
   register(tool: ToolDefinition): () => void {
+    assertPiToolName(tool.name);
     if (this.#leases > 0) throw new Error(`Pi tool registry is leased by pi-runtime; declare a Cordis injection that activates ${tool.name} before pi-runtime`);
     if (this.#names.includes(tool.name) || this.#customTools.has(tool.name)) throw new Error(`Pi tool is already registered: ${tool.name}`);
     if (PI_BUILTIN_TOOL_NAMES.includes(tool.name)) throw new Error(`Pi tool name is reserved by a built-in tool: ${tool.name}`);
@@ -160,13 +179,14 @@ export class PiPluginUiRegistry {
     for (const panel of this.#panels.values()) {
       if (panel.visible !== undefined && !(await panel.visible())) continue;
       try {
+        const data = await panel.read();
         snapshots.push({
           id: panel.id,
           pluginId: panel.pluginId,
           title: panel.title,
           ...(panel.description === undefined ? {} : { description: panel.description }),
           ...(panel.icon === undefined ? {} : { icon: panel.icon }),
-          data: await panel.read(),
+          data: structuredClone(data),
         });
       } catch (error) {
         snapshots.push({