@aefree/pi-unity 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## 0.15.1 - 2026-09-20
+
+### Changed
+
+- Update direct Pi development dependencies to 0.86.1 and require that exact local coding-agent version for the active guidance eval. Peer compatibility remains host-managed.
+
+## 0.15.0 - 2026-09-15
+
+### Fixed
+
+- Correct Node directory-entry and child-process types, restore contextual typing for frozen optional integration contracts, and include the required details field in Pi progress updates.
+- Add a pinned strict production-source type check that runs before the test suite.
+- Preserve exact JSON values and raw evidence in expanded results, and prioritize failed/error test diagnostics before skipped records.
+
+### Changed
+
+- Use compact Unity action headers and consistent result summaries inside Pi's existing tool boxes. Expanded results include project identity, highlighted eval code, formatted JSON, evidence, and artifact paths.
+- Show unified test counts, duration, route, failures, and uncertainty while collapsed; distinguish artifact inspection success from test outcomes and correct run-script and test labels.
+- Add an offline tool presentation preview and renderer checks for narrow terminals, redaction, and failure visibility.
+
 ## 0.14.0 - 2026-09-14
 
 ### Fixed

package/README.md

@@ -25,6 +25,16 @@ pi install -l <path-to-pi-unity> # project-local
 
 Pi discovers the extension from `index.ts` and packaged skills from `skills/`. In UI sessions, pi-unity warns once per Pi runtime when Unity CLI is unavailable or `UNITY_CLI_PATH` is invalid. The warning never displays configured paths; install Unity CLI, then restart or reload Pi.
 
+## Development checks
+
+Run `npm ci`, then `npm test` from the package repository. Tests first run the strict production-source type check (`index.ts` and `src/`) using the pinned TypeScript compiler and Node 22 types. Run `npm run typecheck` for that check alone. Tests and eval harnesses execute separately through `tsx`; they are outside this type-check scope.
+
+## Tool presentation
+
+In Pi's terminal UI, Unity tools use compact action headers and project names. Collapsed results show test counts, timing and route when available, plus failures and uncertainty. Expand using Pi's configured tool-details shortcut to see the full project path, highlighted eval code, formatted JSON results, bounded evidence, and artifact paths. Inspection success and test outcomes are displayed separately.
+
+For a local, offline text preview, run `npm run preview:tools` from this package. The preview exercises the renderers without launching Unity; Pi supplies the surrounding tool box and configured keybinding hints in a live session.
+
 ## Included tools
 
 ### Connected Pipeline

package/index.ts

@@ -1,10 +1,12 @@
-import { keyHint, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { renderUnityGuidanceResult, renderUnityToolCall, renderUnityPipelineCall, renderUnityToolResult, renderUnityPipelineResult } from "./src/unity-renderers";
+import { type AgentToolUpdateCallback, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import type { Dirent } from "node:fs";
 import { mkdir, readFile, readdir, realpath, stat, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { getKeybindings, truncateToWidth } from "@earendil-works/pi-tui";
 import {
   buildUnityBatchmodeAgentText,
   deriveUnityBatchmodeStatus,
@@ -69,7 +71,7 @@ async function loadFileDiscoveryFilterIntegrationV1(pi: Pick<ExtensionAPI, "getA
 const GUI_WARNING = "This launches the full Unity Editor GUI and is not the same as batchmode/headless Unity.";
 const SINGLE_PROCESS_WARNING = "Unity allows only one process per project folder. GUI Editor and batchmode/headless both count as that one process.";
 
-type UnityToolDetails = {
+export type UnityToolDetails = {
   mode: "gui" | "batchmode" | "status" | "artifacts" | "pipeline_inspection" | "pipeline_eval" | "pipeline_run_script" | "pipeline" | "tests";
   projectRoot: string;
   unityVersion: string;
@@ -97,6 +99,7 @@ type UnityToolDetails = {
   removedLockfile?: string;
   piUnitySettings?: PiUnitySettings;
   sessionSettings?: { allowAutonomousPlayModeExit: boolean };
+  projectState?: { nativeLockfileExists: boolean; runningProcessCount: number; processVerificationIncomplete: boolean; staleLockSuspected: boolean };
   testBatch?: UnityTestBatchPlan;
   cliCapabilities?: UnityCliProjectCapabilities;
   pipelineInspection?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
@@ -681,13 +684,14 @@ async function buildProjectStatusReport(
       status: "passed",
       piUnitySettings,
       sessionSettings: { allowAutonomousPlayModeExit },
+      projectState: { nativeLockfileExists: lockState.nativeLockfileExists, runningProcessCount: runningProcesses.length, processVerificationIncomplete: Boolean(warning), staleLockSuspected },
       cliCapabilities,
     },
   };
 }
 
 async function findNewestFile(root: string, suffixes: string[]): Promise<string | undefined> {
-  let entries: Awaited<ReturnType<typeof readdir>>;
+  let entries: Dirent[];
   try {
     entries = await readdir(root, { withFileTypes: true });
   } catch (error) {
@@ -932,92 +936,6 @@ async function buildBatchmodeReport(
   };
 }
 
-function compactUnityRendererValue(value: unknown, limit = 160): string {
-  const redacted = String(value ?? "").replace(
-    /\b(token|secret|password|api[_-]?key)\s*([:=])\s*((?:\$@?|@\$?)?"(?:""|\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;)}\]]+)/gi,
-    "$1$2[redacted]",
-  );
-  const normalized = redacted.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
-  return normalized.length > limit ? `${normalized.slice(0, limit - 1)}…` : normalized;
-}
-
-function reuseRendererText(context: { lastComponent?: unknown } | undefined, text: string): Text {
-  const component = context?.lastComponent;
-  if (component instanceof Text) {
-    component.setText(text);
-    return component;
-  }
-  return new Text(text, 0, 0);
-}
-
-function renderUnityToolCall(
-  name: string,
-  args: { path?: string; args?: string[] },
-  theme: any,
-  modeLabel: string,
-  emphasis: string,
-  context?: { lastComponent?: unknown },
-): Text {
-  const pathLabel = compactUnityRendererValue(args.path?.trim() || "auto-resolve", 120);
-  const extraArgs = Array.isArray(args.args) && args.args.length > 0
-    ? args.args.slice(0, 4).join(" ") + (args.args.length > 4 ? ` ... +${args.args.length - 4}` : "")
-    : undefined;
-  let text =
-    theme.fg("toolTitle", theme.bold(`${name} `)) +
-    theme.fg("accent", modeLabel) +
-    theme.fg("muted", ` (${emphasis})`);
-  text += `\n  ${theme.fg("accent", pathLabel)}`;
-  if (extraArgs) {
-    text += `\n  ${theme.fg("muted", extraArgs)}`;
-  }
-  return reuseRendererText(context, text);
-}
-
-function renderUnityPipelineCall(
-  name: string,
-  args: { path?: string; testPlatform?: string; testFilter?: string; command?: string; code?: string },
-  theme: any,
-  context: { lastComponent?: unknown },
-): Text {
-  const detail = name === "unity_pipeline_run_tests"
-    ? `${args.testPlatform ?? "tests"}${args.testFilter ? ` • ${compactUnityRendererValue(args.testFilter, 100)}` : ""}`
-    : name === "unity_pipeline_inspect"
-      ? `command=${compactUnityRendererValue(args.command ?? "(missing)", 100)}`
-      : name === "unity_pipeline_eval"
-        ? `C# ${compactUnityRendererValue(args.code ?? "(missing)", 140)}`
-        : "connected bounded recompile";
-  return renderUnityToolCall(name, args, theme, "pipeline", detail, context);
-}
-
-function getToolTextContent(result: any): string {
-  return Array.isArray(result.content)
-    ? result.content.filter((entry: any) => entry?.type === "text").map((entry: any) => String(entry.text ?? "")).join("\n")
-    : "";
-}
-
-function buildBatchmodeStatusLine(details: UnityToolDetails, theme: any): string {
-  const status = details.status ?? "passed";
-  let line = `\n  ${theme.fg("accent", `status=${status}`)}${theme.fg("muted", ` exit=${details.exitCode ?? 0}`)}`;
-  if (details.invocation?.testPlatform) {
-    line += ` ${theme.fg("muted", `platform=${details.invocation.testPlatform}`)}`;
-  }
-  return line;
-}
-
-function buildBatchmodeResultsLine(details: UnityToolDetails, theme: any): string {
-  if (!details.parsedTestResults) {
-    return "";
-  }
-
-  const parts = [
-    details.parsedTestResults.total !== undefined ? `total ${details.parsedTestResults.total}` : undefined,
-    details.parsedTestResults.passed !== undefined ? `passed ${details.parsedTestResults.passed}` : undefined,
-    details.parsedTestResults.failed !== undefined ? `failed ${details.parsedTestResults.failed}` : undefined,
-  ].filter(Boolean);
-
-  return parts.length > 0 ? `\n  ${theme.fg("muted", parts.join(" • "))}` : "";
-}
-
 function throwIfAborted(signal?: AbortSignal): void {
   if (signal?.aborted) {
     throw new Error("Unity tool execution aborted.");
@@ -1231,7 +1149,7 @@ async function runUnifiedUnityTests(
   discoveryWarning: string | undefined,
   raw: UnityRunTestsRequest,
   signal: AbortSignal | undefined,
-  onUpdate?: (update: { content: Array<{ type: "text"; text: string }> }) => void,
+  onUpdate?: AgentToolUpdateCallback<unknown>,
   allowAutonomousExitPlayMode = true,
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: UnityToolDetails & { testResult: NormalizedUnityTestResult; artifactPath: string; route: "connected" | "isolated" } }> {
   const request = normalizeUnityRunTestsRequest(raw);
@@ -1259,7 +1177,7 @@ async function runUnifiedUnityTests(
   if (route === "connected") {
     let result;
     try {
-      result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), testPlatform: request.testPlatform, testFilter: request.testFilters[0], testCategory: request.testCategories[0], timeoutSeconds: request.timeoutSeconds, allowAutonomousExitPlayMode }, createPipelineDependencies(pi), { signal, onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }) });
+      result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), testPlatform: request.testPlatform, testFilter: request.testFilters[0], testCategory: request.testCategories[0], timeoutSeconds: request.timeoutSeconds, allowAutonomousExitPlayMode }, createPipelineDependencies(pi), { signal, onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }], details: undefined }) });
     } catch (error) {
       if (!(error instanceof UnityPipelineTerminalTestEvidenceError)) throw error;
       const outcome = error.evidence.outcome;
@@ -1332,94 +1250,6 @@ async function runUnifiedUnityTests(
   });
 }
 
-function renderUnityPipelineResult(result: any, options: { expanded: boolean; isPartial: boolean }, theme: any, context: { lastComponent?: unknown }): Text {
-  const details = result.details as UnityToolDetails | undefined;
-  const primaryText = getToolTextContent(result);
-  if (options.isPartial) {
-    return reuseRendererText(context, `${theme.fg("warning", "…")} ${theme.fg("toolTitle", theme.bold("Unity Pipeline working"))}\n  ${theme.fg("muted", compactUnityRendererValue(primaryText || "Waiting for Pipeline…", 180))}`);
-  }
-  if (!details) return reuseRendererText(context, primaryText || "(no output)");
-
-  const pipeline = details.pipeline;
-  const icon = details.status === "passed" ? theme.fg("success", "✓") : theme.fg("error", "✗");
-  let text: string;
-  if (pipeline?.operation === "recompile") {
-    text = `${icon} ${theme.fg("toolTitle", theme.bold("Unity recompile"))} ${theme.fg("accent", pipeline.terminalState)}${theme.fg("muted", ` • ${pipeline.elapsedSeconds.toFixed(1)}s`)}`;
-  } else if (pipeline?.operation === "tests") {
-    const counts = pipeline.counts;
-    const passed = counts?.passed === undefined || counts?.total === undefined ? "tests completed" : `${counts.passed}/${counts.total} passed`;
-    text = `${icon} ${theme.fg("toolTitle", theme.bold(`Unity ${pipeline.testPlatform ?? ""} tests`.trim()))} ${theme.fg("accent", passed)}${theme.fg("muted", ` • ${pipeline.elapsedSeconds.toFixed(1)}s`)}`;
-  } else if (details.mode === "pipeline_eval" || details.mode === "pipeline_inspection" || details.mode === "pipeline_run_script") {
-    const output = details.mode === "pipeline_eval" ? details.pipelineEval : details.mode === "pipeline_run_script" ? details.pipelineRunScript : details.pipelineInspection;
-    const label = details.mode === "pipeline_eval" ? "Unity Pipeline Eval" : details.mode === "pipeline_run_script" ? "Unity Pipeline Run Script" : "Unity Pipeline Inspection";
-    const summary = output?.outcome === "dispatched" ? output.output || "(no bounded output returned)" : output?.message || primaryText;
-    text = `${icon} ${theme.fg("toolTitle", theme.bold(label))}\n  ${theme.fg("toolOutput", compactUnityRendererValue(summary, 240))}`;
-  } else {
-    return renderUnityToolResult(result, options.expanded, theme);
-  }
-
-  if (pipeline?.playModeHandling && pipeline.playModeHandling !== "not_playing") {
-    const handling = pipeline.playModeHandling === "agent_exited" ? "Play Mode exited by pi-unity" : `Play Mode: ${pipeline.playModeHandling.replace(/_/g, " ")}`;
-    text += `\n  ${theme.fg("warning", handling)}`;
-  }
-  if (options.expanded && primaryText) text += `\n\n${theme.fg("toolOutput", primaryText)}`;
-  else if (!options.expanded) text += ` ${theme.fg("dim", `(${keyHint("app.tools.expand", "details")})`)}`;
-  return reuseRendererText(context, text);
-}
-
-function renderUnityToolResult(result: any, expanded: boolean, theme: any): Text {
-  const details = result.details as UnityToolDetails | undefined;
-  const primaryText = getToolTextContent(result);
-
-  if (!details) {
-    return new Text(primaryText || "(no output)", 0, 0);
-  }
-
-  const icon = details.mode === "gui"
-    ? theme.fg("success", "◉")
-    : details.status === "passed"
-      ? theme.fg("success", "✓")
-      : details.status === "killed"
-        ? theme.fg("warning", "! ")
-        : theme.fg("error", "✗");
-  const title = details.mode === "gui"
-    ? "Unity Editor"
-    : details.mode === "status"
-      ? "Unity Project Status"
-      : details.mode === "artifacts"
-        ? "Unity Artifacts"
-        : details.mode === "pipeline_inspection"
-          ? "Unity Pipeline Inspection"
-          : details.mode === "pipeline_eval"
-            ? "Unity Pipeline Eval"
-            : details.mode === "pipeline_run_script"
-              ? "Unity Pipeline Run Script"
-              : details.mode === "pipeline"
-              ? "Unity Pipeline"
-              : getBatchmodeVariantLabel(details.args);
-  const projectLabel = details.projectRoot ?? "(unknown project)";
-  let text = `${icon} ${theme.fg("toolTitle", theme.bold(title))} ${theme.fg("muted", projectLabel)}`;
-  if (details.mode === "batchmode") {
-    text += buildBatchmodeStatusLine(details, theme);
-    text += buildBatchmodeResultsLine(details, theme);
-  } else if (details.mode === "status") {
-    text += `\n  ${theme.fg("accent", `status=${details.status ?? "passed"}`)}`;
-  } else if (details.mode === "pipeline" && details.pipeline) {
-    text += `\n  ${theme.fg("accent", `${details.pipeline.operation}=${details.pipeline.terminalState}`)}${theme.fg("muted", ` ${details.pipeline.elapsedSeconds.toFixed(1)}s`)}`;
-  }
-
-  if (expanded && primaryText) {
-    text += `\n\n${theme.fg("toolOutput", primaryText)}`;
-  } else if (!expanded && details.mode === "batchmode") {
-    const snippet = summarizeTextForAgent(details.stderr) ?? summarizeTextForAgent(details.stdout);
-    if (snippet) {
-      text += `\n  ${theme.fg("muted", snippet.split(/\r?\n/)[0])}`;
-    }
-  }
-
-  return new Text(text, 0, 0);
-}
-
 function formatUnityGuidanceAudit(result: UnityGuidanceAuditResult): string {
   const lines = [
     `Unity guidance audit scanned ${result.summary.filesScanned} file(s): ${result.summary.errors} error(s), ${result.summary.warnings} warning(s), ${result.summary.infos} info finding(s).`,
@@ -1618,16 +1448,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     renderCall(args, theme) {
       return renderUnityToolCall("unity_guidance_audit", args, theme, "guidance", "read-only instruction audit");
     },
-    renderResult(result, { expanded }, theme) {
-      const details = result.details as UnityGuidanceAuditResult | undefined;
-      const primaryText = getToolTextContent(result);
-      if (!details) return new Text(primaryText || "(no output)", 0, 0);
-      const count = details.summary.errors + details.summary.warnings + details.summary.infos;
-      const ancestorCount = details.ancestorCandidates.length;
-      let text = `${count > 0 || ancestorCount > 0 ? theme.fg("warning", "!") : theme.fg("success", "✓")} ${theme.fg("toolTitle", theme.bold("Unity Guidance Audit"))}`;
-      text += `\n  ${theme.fg("muted", `${details.summary.filesScanned} files • ${count} findings${ancestorCount > 0 ? ` • ${ancestorCount} ancestor files excluded` : ""}`)}`;
-      if (expanded && primaryText) text += `\n\n${theme.fg("toolOutput", primaryText)}`;
-      return new Text(text, 0, 0);
+    renderResult(result, options, theme, context) {
+      return renderUnityGuidanceResult(result, options, theme, context);
     },
   });
 
@@ -1656,8 +1478,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     renderCall(args, theme) {
       return renderUnityToolCall("unity_project_status", args, theme, "status", "inspects project lock");
     },
-    renderResult(result, { expanded }, theme) {
-      return renderUnityToolResult(result, expanded, theme);
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      return renderUnityToolResult(result, expanded, theme, context, isPartial);
     },
   });
 
@@ -1679,8 +1501,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       const { candidate, discoveryWarning } = await resolveProjectCandidate(ctx, params.path);
       return await runUnifiedUnityTests(pi, ctx, candidate, discoveryWarning, params as UnityRunTestsRequest, signal, onUpdate, sessionAllowsAutonomousPlayModeExit(ctx));
     },
-    renderCall(args, theme, context) { return renderUnityToolCall("unity_run_tests", args, theme, "tests", `${args.testPlatform ?? "Unity"} • ${compactUnityRendererValue(args.testFilters?.[0] ?? args.testFilter ?? args.execution ?? "auto", 100)}`, context); },
-    renderResult(result, { expanded }, theme) { return renderUnityToolResult(result, expanded, theme); },
+    renderCall(args, theme, context) { return renderUnityToolCall("unity_run_tests", args, theme, "tests", undefined, context); },
+    renderResult(result, { expanded, isPartial }, theme, context) { return renderUnityToolResult(result, expanded, theme, context, isPartial); },
   });
 
   pi.registerTool({
@@ -1699,7 +1521,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       const { candidate } = await resolveProjectCandidate(ctx, params.path);
       const result = await runUnityPipelineRecompile({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), timeoutSeconds: params.timeoutSeconds, allowAutonomousExitPlayMode: sessionAllowsAutonomousPlayModeExit(ctx) }, createPipelineDependencies(pi), {
         signal,
-        onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }),
+        onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }], details: undefined }),
       });
       return {
         content: [{ type: "text", text: result.text }],
@@ -1869,8 +1691,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     renderCall(args, theme) {
       return renderUnityToolCall("unity_inspect_artifacts", args, theme, "artifacts", "reads logs/results");
     },
-    renderResult(result, { expanded }, theme) {
-      return renderUnityToolResult(result, expanded, theme);
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      return renderUnityToolResult(result, expanded, theme, context, isPartial);
     },
   });
 
@@ -1928,8 +1750,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     renderCall(args, theme) {
       return renderUnityToolCall("unity_open_editor", args, theme, "gui", "opens editor window");
     },
-    renderResult(result, { expanded }, theme) {
-      return renderUnityToolResult(result, expanded, theme);
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      return renderUnityToolResult(result, expanded, theme, context, isPartial);
     },
   });
 
@@ -1967,8 +1789,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       const displayArgs = args.useGraphics ? args.args : ["-nographics", ...(args.args ?? [])];
       return renderUnityToolCall("unity_launch_batchmode", args, theme, "batchmode", getBatchmodeVariantLabel(displayArgs));
     },
-    renderResult(result, { expanded }, theme) {
-      return renderUnityToolResult(result, expanded, theme);
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      return renderUnityToolResult(result, expanded, theme, context, isPartial);
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -18,7 +18,10 @@
     ]
   },
   "scripts": {
-    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-launch.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/unity-package-validation.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "pretest": "npm run typecheck",
+    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-launch.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-renderers.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/unity-package-validation.test.ts",
+    "preview:tools": "tsx tests/unity-renderers.test.ts --preview",
     "eval:guidance-skill": "tsx evals/auditing-unity-agent-guidance/run-eval.ts"
   },
   "dependencies": {
@@ -50,10 +53,12 @@
   "devDependencies": {
     "@aefree/pi-file-discovery": "^0.1.0",
     "@aefree/pi-project-artifacts": "^0.1.0",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
-    "tsx": "^4.23.5"
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
+    "@types/node": "22.20.2",
+    "tsx": "^4.23.5",
+    "typescript": "7.0.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {

package/src/unity-artifact-profile.ts

@@ -24,7 +24,7 @@ const OWNER = Object.freeze({
  * metadata remains project-owned and schema-open.
  */
 export function createUnityArtifactProfileV1(): ArtifactProfileV1 {
-  return Object.freeze({
+  return Object.freeze<ArtifactProfileV1>({
     contractVersion: 1,
     id: UNITY_ARTIFACT_PROFILE_ID_V1,
     kind: "artifact-profile",

package/src/unity-cli.ts

@@ -81,7 +81,7 @@ export type UnityCliProjectCapabilities = {
 export type UnityCliExecResult = {
   stdout: string;
   stderr: string;
-  error?: Error & { code?: string | number; signal?: string | null };
+  error?: Error & { code?: string | number | null; signal?: string | null; killed?: boolean };
 };
 
 /** Injectable seam for deterministic capability and planning-dispatch tests. */
@@ -209,9 +209,9 @@ const execFileCollect: UnityCliExecutor = (command, args, options = {}) => {
   return new Promise((resolve) => {
     execFile(command, args, { timeout: options.timeout ?? UNITY_CLI_VERSION_TIMEOUT_MS, signal: options.signal, windowsHide: true }, (error, stdout, stderr) => {
       resolve({
-        stdout: typeof stdout === "string" ? stdout : stdout.toString(),
-        stderr: typeof stderr === "string" ? stderr : stderr.toString(),
-        error: error as UnityCliExecResult["error"],
+        stdout,
+        stderr,
+        error: error ?? undefined,
       });
     });
   });
@@ -488,7 +488,7 @@ async function readPipelineDescriptorCapabilities(projectRoot: string): Promise<
 }
 
 export function isUnityCliTimeout(result: Pick<UnityCliExecResult, "error">): boolean {
-  const error = result.error as (NodeJS.ErrnoException & { killed?: boolean }) | undefined;
+  const error = result.error;
   return error?.code === "ETIMEDOUT" || error?.killed === true || error?.signal === "SIGTERM";
 }
 

package/src/unity-file-discovery-filter.ts

@@ -14,7 +14,7 @@ export const UNITY_EXACT_GENERATED_ROOT_BYPASSED_CODE = "unity_exact_generated_r
 export const UNITY_GENERATED_DIRECTORIES = Object.freeze(["Library", "Temp", "Logs", "obj", "Build", "Builds", "UserSettings", ".vs"] as const);
 
 export function createUnityFileDiscoveryFilterV1(): FileDiscoveryFilterV1 {
-  return Object.freeze({
+  return Object.freeze<FileDiscoveryFilterV1>({
     contractVersion: 1,
     id: UNITY_FILE_DISCOVERY_FILTER_ID_V1,
     kind: "file-discovery-filter",

package/src/unity-projects.ts

@@ -1,3 +1,4 @@
+import type { Dirent } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseUnityVersionText, resolveAbsolutePath } from "./unity-core";
@@ -135,7 +136,7 @@ export async function discoverUnityProjects(
       continue;
     }
 
-    let entries: fs.Dirent[] = [];
+    let entries: Dirent[] = [];
     try {
       entries = await fs.readdir(next.dir, { withFileTypes: true });
     } catch {

package/src/unity-renderers.ts

@@ -0,0 +1,174 @@
+import { highlightCode, keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { UnityToolDetails } from "../index";
+import type { UnityGuidanceAuditResult } from "./unity-guidance-audit";
+
+type Args = { path?: string; args?: unknown[]; code?: string; command?: string; file?: string; entry?: string; dryRun?: boolean; testPlatform?: string; testFilter?: string; testFilters?: string[]; testCategories?: string[]; execution?: string };
+type Context = { lastComponent?: unknown; args?: Args; isError?: boolean; expanded?: boolean };
+type Result = { content?: Array<{ type: string; text?: string }>; details?: unknown };
+type Options = { expanded: boolean; isPartial?: boolean };
+
+function redact(value: string): string {
+  return value.replace(/\b(token|secret|password|api[_-]?key)\s*([:=])\s*((?:\$@?|@\$?)?"(?:""|\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;)}\]]+)/gi, "$1$2[redacted]")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+export function compactUnityRendererValue(value: unknown, limit = 160): string {
+  const text = redact(String(value ?? "")).replace(/\s+/g, " ").trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+function reuse(context: Context | undefined, value: string): Text {
+  const text = context?.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+  text.setText(value);
+  return text;
+}
+function projectName(path?: string): string {
+  return compactUnityRendererValue(path?.replace(/[\\/]+$/, "").split(/[\\/]/).pop() || "auto-resolve", 70);
+}
+const titles: Record<string, string> = {
+  unity_project_status: "Project status", unity_run_tests: "Tests", unity_pipeline_run_tests: "Tests",
+  unity_pipeline_recompile: "Recompile", unity_pipeline_eval: "Eval", unity_pipeline_inspect: "Inspect",
+  unity_pipeline_run_script: "Run script", unity_inspect_artifacts: "Artifacts", unity_open_editor: "Open Editor",
+  unity_launch_batchmode: "Batchmode", unity_guidance_audit: "Guidance audit",
+};
+export function renderUnityToolCall(name: string, args: Args, theme: Pick<Theme, "fg" | "bold">, _mode?: string, _emphasis?: string, context?: Context): Text {
+  const title = args.testPlatform ? `${args.testPlatform} tests` : titles[name] ?? name;
+  let text = theme.fg("toolTitle", theme.bold(`Unity · ${title}`)) + theme.fg("dim", `  ${projectName(args.path)}`);
+  let subtitle = "";
+  if (args.code !== undefined) subtitle = compactUnityRendererValue(args.code, 140);
+  else if (args.file) subtitle = `${compactUnityRendererValue(args.file, 120)}${args.entry ? ` · ${compactUnityRendererValue(args.entry, 60)}` : ""}${args.dryRun ? " · compile only" : ""}`;
+  else if (args.command) subtitle = compactUnityRendererValue(args.command.replace(/_/g, " "), 100);
+  else if (args.testPlatform) {
+    subtitle = [...(args.testFilters ?? (args.testFilter ? [args.testFilter] : [])), ...(args.testCategories ?? []).map(value => `category: ${value}`)].map(value => compactUnityRendererValue(value, 100)).join(" · ") || "All tests";
+    subtitle = compactUnityRendererValue(subtitle, 180);
+  } else if (name === "unity_launch_batchmode") subtitle = _emphasis ?? "";
+  if (subtitle && !(args.code && context?.expanded)) text += `\n${theme.fg("muted", subtitle)}`;
+  return reuse(context, text);
+}
+export function renderUnityPipelineCall(name: string, args: Args, theme: Pick<Theme, "fg" | "bold">, context: Context): Text {
+  return renderUnityToolCall(name, args, theme, undefined, undefined, context);
+}
+function content(result: Result): string {
+  return redact((result.content ?? []).filter(entry => entry.type === "text").map(entry => entry.text ?? "").join("\n"));
+}
+function counts(summary?: { passed?: number; failed?: number; skipped?: number }): string {
+  return summary ? (["passed", "failed", "skipped"] as const).filter(key => summary[key] !== undefined).map(key => `${summary[key]} ${key}`).join(" · ") : "";
+}
+function prettyOutput(output: string): string {
+  const safe = redact(output);
+  try { JSON.parse(safe); }
+  catch (error) { if (error instanceof SyntaxError) return safe; throw error; }
+
+  // Validate with JSON.parse, but format tokens directly so JSON number and string lexemes stay exact.
+  let formatted = "";
+  let depth = 0;
+  const indent = () => "  ".repeat(depth);
+  for (let index = 0; index < safe.length; index++) {
+    const character = safe[index];
+    if (/\s/.test(character)) continue;
+    if (character === '"') {
+      const start = index++;
+      while (index < safe.length) {
+        if (safe[index] === "\\") index++;
+        else if (safe[index] === '"') break;
+        index++;
+      }
+      formatted += safe.slice(start, index + 1);
+    } else if (character === "{" || character === "[") {
+      let next = index + 1;
+      while (/\s/.test(safe[next] ?? "")) next++;
+      if (safe[next] === (character === "{" ? "}" : "]")) {
+        formatted += character + safe[next];
+        index = next;
+      } else {
+        formatted += `${character}\n`;
+        depth++;
+        formatted += indent();
+      }
+    } else if (character === "}" || character === "]") {
+      depth--;
+      formatted += `\n${indent()}${character}`;
+    } else if (character === ",") formatted += `,\n${indent()}`;
+    else if (character === ":") formatted += ": ";
+    else formatted += character;
+  }
+  return formatted;
+}
+export function renderUnityPipelineResult(result: Result, options: Options, theme: Pick<Theme, "fg" | "bold">, context: Context): Text {
+  return renderUnityToolResult(result, options.expanded, theme, context, options.isPartial);
+}
+export function renderUnityToolResult(result: Result, expanded: boolean, theme: Pick<Theme, "fg" | "bold">, context?: Context, isPartial = false): Text {
+  const primary = content(result);
+  const details = result.details as UnityToolDetails | undefined;
+  if (isPartial) return reuse(context, theme.fg("warning", `… ${compactUnityRendererValue(primary || "Waiting for Unity…", 200)}`));
+  if (!details?.mode) {
+    const text = expanded ? primary : compactUnityRendererValue(primary || "No output", 280);
+    return reuse(context, theme.fg(context?.isError ? "error" : "toolOutput", text) + (!expanded && primary ? `\n${theme.fg("dim", keyHint("app.tools.expand", "details"))}` : ""));
+  }
+  const pipeline = details.pipeline;
+  const tests = details.testResult;
+  const output = details.pipelineEval ?? details.pipelineInspection ?? details.pipelineRunScript;
+  const outcome = tests?.outcome ?? details.testOutcome;
+  const uncertain = outcome && ["uncertain", "empty_selection", "timed_out", "cancelled", "passed_with_flakes"].includes(outcome);
+  const failed = context?.isError || details.status === "failed" || outcome === "tests_failed" || outcome === "run_error" || output?.outcome === "rejected";
+  const tone = uncertain || details.status === "killed" || details.projectState?.processVerificationIncomplete || details.projectState?.staleLockSuspected ? "warning" : failed ? "error" : details.status === "passed" || details.mode === "gui" ? "success" : "warning";
+  let summary: string = details.status ?? "Completed";
+  if (details.mode === "status") {
+    const capabilities = details.cliCapabilities;
+    const reachable = capabilities?.matchingInstances.some(instance => instance.reachable === true);
+    const state = details.projectState;
+    summary = reachable ? "Editor open · Pipeline reachable"
+      : capabilities?.matchingInstances.length || state?.runningProcessCount ? "Editor detected · Pipeline reachability unconfirmed"
+      : state?.processVerificationIncomplete ? "Process state uncertain"
+      : state?.staleLockSuspected ? "No Editor detected · lock may be stale"
+      : state ? `No Editor detected · lock ${state.nativeLockfileExists ? "present" : "absent"}`
+      : "Project inspected · expand for process and lock state";
+    if (details.unityVersion) summary += ` · Unity ${details.unityVersion}`;
+  } else if (tests || details.mode === "artifacts") {
+    summary = `${details.mode === "artifacts" ? `Inspection ${details.status ?? "unknown"} · Tests: ` : ""}${(outcome ?? "not established").replace(/_/g, " ")}`;
+    const testCounts = counts(tests?.summary ?? details.normalizedResult?.summary ?? details.parsedTestResults ?? undefined);
+    if (testCounts) summary = details.mode === "tests" && outcome === "passed" ? testCounts : `${summary} · ${testCounts}`;
+    if (tests?.durationSeconds !== undefined) summary += ` · ${tests.durationSeconds.toFixed(1)}s`;
+    if (details.route) summary += ` · ${details.route}`;
+  } else if (pipeline) {
+    summary = `${pipeline.operation === "recompile" ? "Recompile" : "Tests"} ${pipeline.terminalState} · ${pipeline.elapsedSeconds.toFixed(1)}s`;
+    const testCounts = counts(pipeline.counts);
+    if (testCounts) summary += ` · ${testCounts}`;
+  } else if (output) {
+    summary = output.outcome === "rejected" ? compactUnityRendererValue(output.message, 240) : expanded ? "Completed" : compactUnityRendererValue(output.output || "No output returned", 240);
+    if (output.outcome === "dispatched" && output.truncated && !expanded) summary += " · output truncated";
+  }
+  else if (details.mode === "gui") summary = `Editor launched${details.pid ? ` · PID ${details.pid}` : ""}`;
+  else if (details.mode === "batchmode") summary = `${details.status ?? "unknown"} · exit ${details.exitCode ?? "unknown"}${counts(details.parsedTestResults ?? undefined) ? ` · ${counts(details.parsedTestResults ?? undefined)}` : ""}`;
+  let text = theme.fg(tone, `${tone === "success" ? "✓" : tone === "error" ? "✗" : "!"} ${summary}`);
+  const notices = [details.warning, ...(pipeline?.warnings ?? []), ...(details.evidenceWarnings ?? []), ...(tests?.diagnostics ?? [])].filter((value): value is string => Boolean(value));
+  if (pipeline?.playModeHandling && pipeline.playModeHandling !== "not_playing") notices.push(pipeline.playModeHandling === "agent_exited" ? "Play Mode exited by pi-unity" : `Play Mode: ${pipeline.playModeHandling.replace(/_/g, " ")}`);
+  if (notices.length) text += `\n${theme.fg("warning", compactUnityRendererValue(notices.join(" · "), expanded ? 1000 : 240))}`;
+  const nonPassing = tests?.tests?.filter(test => !["passed", "success"].includes(test.status.toLowerCase())) ?? [];
+  const failures = nonPassing.filter(test => ["failed", "error"].includes(test.status.toLowerCase()));
+  const diagnostics = nonPassing.filter(test => !["failed", "error"].includes(test.status.toLowerCase()));
+  for (const test of [...failures, ...diagnostics].slice(0, expanded ? 8 : 1)) text += `\n${theme.fg("warning", compactUnityRendererValue(`${test.name}: ${test.message || test.status}`, expanded ? 1000 : 200))}`;
+  if (expanded) {
+    const section = (title: string, body: string) => { if (body) text += `\n\n${theme.fg("toolTitle", theme.bold(title))}\n${body}`; };
+    section("Project", theme.fg("muted", redact(details.projectRoot || context?.args?.path || "Unknown project")));
+    if (context?.args?.code) section("C#", highlightCode(redact(context.args.code), "csharp").join("\n"));
+    if (context?.args?.file) section("Script", theme.fg("toolOutput", redact(`${context.args.file}${context.args.entry ? `\nEntry: ${context.args.entry}` : ""}${context.args.dryRun ? "\nCompile only" : ""}`)));
+    if (output?.outcome === "dispatched") section(`Result${output.truncated ? " (truncated)" : ""}`, theme.fg("toolOutput", prettyOutput(output.output)));
+    section("Evidence", theme.fg("toolOutput", primary));
+    const paths = [...new Set([details.artifactPath, details.normalizedResultPath, details.artifacts?.testResultsPath, details.artifacts?.logFilePath, ...Object.values(tests?.backendArtifacts ?? {})].filter((value): value is string => Boolean(value)))];
+    section("Artifacts", theme.fg("muted", redact(paths.join("\n"))));
+  } else text += `\n${theme.fg("dim", keyHint("app.tools.expand", "details"))}`;
+  return reuse(context, text);
+}
+
+export function renderUnityGuidanceResult(result: Result, options: Options, theme: Pick<Theme, "fg" | "bold">, context: Context): Text {
+  const details = result.details as UnityGuidanceAuditResult | undefined;
+  if (!details?.summary) return renderUnityToolResult(result, options.expanded, theme, context, options.isPartial);
+  const { filesScanned, errors, warnings, infos } = details.summary;
+  const ancestors = details.ancestorCandidates.length;
+  const tone = errors ? "error" : warnings || ancestors ? "warning" : "success";
+  let text = theme.fg(tone, `${tone === "success" ? "✓" : "!"} ${filesScanned} files · ${errors} errors · ${warnings} warnings · ${infos} info`);
+  if (ancestors) text += `\n${theme.fg("warning", `${ancestors} ancestor files excluded`)}`;
+  if (options.expanded) text += `\n\n${theme.fg("toolTitle", theme.bold("Findings"))}\n${theme.fg("toolOutput", content(result))}`;
+  else text += `\n${theme.fg("dim", keyHint("app.tools.expand", "details"))}`;
+  return reuse(context, text);
+}