@aefree/pi-unity 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## 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
+
+- Preserve durable normalized connected-test evidence for terminal failed, cancelled, runner-error, and incomplete Pipeline results without replaying dispatch, overriding active Pipeline state from partial records, or misreporting inconsistent counts/records as passing.
+- Select one primary latest normalized result and only its validated project-contained backend links when inspecting historical artifacts, including canonical contained aliases.
+- Forward optional `unity_pipeline_eval.handlerTimeoutMilliseconds` only when the exact reachable Pipeline descriptor confirms raw argv support and the documented `code`/`timeout` signature. Preserve `timeoutSeconds` as the separate host/CLI wait; a dispatcher expiry cannot cancel eval code already started on Unity's main thread, so effects remain uncertain and are never retried or rerouted.
+- Treat Pipeline 0.7's explicit `compilationFailed: true` response as a failed recompile even when its status is `up_to_date` or `completed` and no compiler-error array is present.
+
 ## 0.13.0 - 2026-09-10
 
 ### Added

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
@@ -34,13 +44,13 @@ Use these tools with an already-open exact Unity project copy that has a reachab
 - `unity_project_status` — inspect lockfiles, matching Unity processes, Pipeline reachability, package version, and advertised commands without launching Unity.
 - `unity_pipeline_recompile` — recompile through Pipeline with exact-copy preflight, bounded polling, and compact compiler evidence.
 - `unity_run_tests` — one intent-oriented EditMode or PlayMode workflow. It reuses compatible connected Pipeline execution or selects isolated `unity test` when the exact project copy is closed.
-- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL. It accepts `timeoutSeconds` from 1–86,400 seconds; a timeout is uncertain and does not cancel or retry Editor work.
+- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL. `timeoutSeconds` bounds pi-unity and Unity CLI waits (1–86,400 seconds). Optional `handlerTimeoutMilliseconds` is forwarded only when the exact reachable Pipeline advertises raw argv plus the verified eval timeout signature; it bounds that Pipeline dispatcher wait, not code already running on Unity's main thread. A timeout is uncertain and does not cancel or retry Editor work.
 - `unity_pipeline_inspect` — dispatch supported package-owned inspection commands (including read-only `get_runtime_pipeline_settings`) and return structured evidence. Runtime settings are refused by Pipeline in Play Mode; pi-unity never exits Play Mode to read them.
 - `unity_pipeline_run_script` — compile one existing project `.cs` file in Pipeline's ephemeral in-memory mode and invoke a named static entry point; supports bounded JSON arguments and compile-only `dryRun`. It deliberately does not expose hotpatch.
 
 Connected recompilation follows Unity's Script Changes While Playing policy and never preemptively sends `editor_stop`. Connected tests may exit Play Mode through advertised `editor_stop` when necessary, then verify Edit Mode before dispatch. Play Mode exit is allowed by default; `/unity-playmode-exit allow|disallow|status` controls the current session.
 
-A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. Pipeline 0.6 can report busy for a modal dialog as well as startup settling, so ambiguous busy responses are surfaced and never blindly retried.
+A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. Pipeline 0.6 can report busy for a modal dialog as well as startup settling, so ambiguous busy responses are surfaced and never blindly retried. Pipeline 0.7 improves recovery of standing compile errors and console output. For non-development Player builds, Pipeline also requires the `ENABLE_RUNTIME_PIPELINE` scripting define; enabling its runtime setting alone is insufficient.
 
 ### Editor and batchmode
 
@@ -48,7 +58,7 @@ A timeout is uncertain: work may still be running. The tools do not silently can
 - `unity_launch_batchmode` — run a bounded batchmode command through Unity CLI or the direct Editor executable.
 - `unity_inspect_artifacts` — validate existing normalized JSON test artifacts, Unity Test Framework XML and Unity logs without launching Unity. `details.status` describes inspection; `details.testOutcome` describes the tests, including failures and uncertainty. A valid failed-test artifact is a successful inspection, not a passing run.
 
-Pass `normalizedResultPath` for standalone JSON evidence. Any explicit artifact path disables implicit latest-file selection; missing requested files fail inspection. With all paths omitted, `latestFromLogs` discovers recent files but cannot establish current-run identity. Mixed JSON/XML evidence must agree; without an explicit native artifact link, matching counts alone leave correlation uncertain.
+Pass `normalizedResultPath` for standalone JSON evidence. Any explicit artifact path disables implicit latest-file selection and link expansion; missing requested files fail inspection. With all paths omitted, `latestFromLogs` selects one newest top-level JSON (mtime then filename) and only its contained declared NUnit/log links. Without JSON it selects XML alone, then log context. Historical selection cannot establish current-run identity. Mixed JSON/XML evidence must agree; without an explicit native artifact link, matching counts alone leave correlation uncertain.
 
 Use `unity_run_tests` for all ordinary Unity Test Framework work. It writes a durable normalized JSON result under `Logs/`; isolated `unity test` runs retain requested native reports. Connected Pipeline is selected only for compatible requests. A reachable Editor is never closed automatically to obtain isolated-only features.
 
@@ -113,6 +123,8 @@ Another connected client is not a project lock. When Pipeline returns stable cor
 { code: "var s = UnityEngine.Application.dataPath; return s.Length;" }
 ```
 
+`timeoutSeconds` remains the host/CLI wait. On exact copies that advertise raw argv and the verified eval `code`/integer-`timeout` signature, `handlerTimeoutMilliseconds` (1–86,400,000) also sets Pipeline's dispatcher wait through its positional command argument. A shorter host timeout may still win. This server wait can prevent queued work from starting, but cannot cancel eval code that already began on Unity's main thread; treat expiry as uncertain and never retry or fall back.
+
 Use `unity_pipeline_inspect` when a purpose-built structured command fits. Use eval for bounded project-specific work that matches the user's intent. Prefer typed tools when they provide stronger lifecycle, polling, validation, or recovery semantics.
 
 ### Pipeline run_script

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 { mkdir, readFile, readdir, stat, unlink } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+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,
@@ -32,7 +34,7 @@ import { applyUnityCliRetrySummary, compactUnityTestSummary, defaultUnityTestRep
 import { validateNormalizedUnityTestArtifact } from "./src/unity-artifact-inspection";
 import { UNITY_TEST_MAX_ARTIFACT_BYTES } from "./src/unity-tests";
 import { auditUnityGuidance, type UnityGuidanceAuditResult } from "./src/unity-guidance-audit";
-import { runUnityPipelineRecompile, runUnityPipelineTests, type UnityPipelineOperationDetails } from "./src/unity-pipeline";
+import { runUnityPipelineRecompile, runUnityPipelineTests, UnityPipelineTerminalTestEvidenceError, type UnityPipelineOperationDetails } from "./src/unity-pipeline";
 import {
   createOptionalIntegrationRegistryV1,
   isOptionalIntegrationActive,
@@ -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,12 +99,16 @@ 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 };
   pipelineEval?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
   pipelineRunScript?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
   pipeline?: UnityPipelineOperationDetails;
+  testResult?: NormalizedUnityTestResult;
+  artifactPath?: string;
+  route?: "connected" | "isolated";
 };
 
 const LAUNCHER_SCHEMA = Type.Optional(StringEnum(["auto", "unity-cli", "editor-executable"] as const, { description: "Launch backend. Defaults to auto, which prefers the Unity CLI and falls back to direct editor executable launch when the CLI is unavailable." }));
@@ -165,7 +171,8 @@ const PIPELINE_TEST_PARAMS = Type.Object({
 const PIPELINE_EVAL_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ maxLength: 1000, description: "Unity project path, workspace copy root, or folder containing project copies." })),
   code: Type.String({ minLength: 1, maxLength: 4000, description: "Bounded C# source for advertised Pipeline eval. Roslyn compiles it on the connected Editor main thread; include an explicit return value when evidence is needed." }),
-  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 12, description: "Connected eval deadline in seconds (maximum 24 hours). A timeout is uncertain and does not retry or cancel Unity work." })),
+  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 12, description: "Connected eval host/CLI deadline in seconds (maximum 24 hours). A timeout is uncertain and does not retry or cancel Unity work." })),
+  handlerTimeoutMilliseconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400000, description: "Optional advertised Pipeline eval dispatcher wait in milliseconds. Forwarded only when the exact copy advertises raw argv and the verified code/timeout signature; it cannot cancel code already started on Unity's main thread." })),
 }, { additionalProperties: false });
 
 const PIPELINE_RUN_SCRIPT_PARAMS = Type.Object({
@@ -196,7 +203,7 @@ const INSPECT_ARTIFACTS_PARAMS = Type.Object({
   testResultsPath: Type.Optional(Type.String({ description: "Unity Test Framework XML results path. Relative paths are resolved against cwd and the Unity project root." })),
   normalizedResultPath: Type.Optional(Type.String({ description: "pi-unity normalized JSON test artifact path." })),
   logFilePath: Type.Optional(Type.String({ description: "Unity log file path. Relative paths are resolved against cwd and the Unity project root." })),
-  latestFromLogs: Type.Optional(Type.Boolean({ default: true, description: "Only when all artifact paths are omitted, inspect the newest .json, .xml and .log files under Logs. Latest files are not proof of a shared run." })),
+  latestFromLogs: Type.Optional(Type.Boolean({ default: true, description: "Only when all artifact paths are omitted, select one newest top-level Logs JSON (mtime then filename) and only its declared contained NUnit/log links. Without JSON, select newest XML alone, otherwise newest log context. Latest files are not proof of a shared run." })),
   maxLines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, default: 60, description: "Maximum log/output lines to include." })),
   maxChars: Type.Optional(Type.Integer({ minimum: 500, maximum: 20000, default: 6000, description: "Maximum log/output characters to include." })),
 });
@@ -677,17 +684,19 @@ 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 {
-    return undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
   }
 
   const files = await Promise.all(entries
@@ -697,7 +706,16 @@ async function findNewestFile(root: string, suffixes: string[]): Promise<string
       const stats = await stat(fullPath);
       return { fullPath, mtimeMs: stats.mtimeMs };
     }));
-  return files.sort((left, right) => right.mtimeMs - left.mtimeMs)[0]?.fullPath;
+  return files.sort((left, right) => right.mtimeMs - left.mtimeMs || left.fullPath.localeCompare(right.fullPath))[0]?.fullPath;
+}
+
+async function resolveLinkedArtifact(projectRoot: string, linkPath: string): Promise<string> {
+  const canonicalRoot = await realpath(projectRoot);
+  const candidate = resolve(projectRoot, linkPath);
+  const canonicalCandidate = await realpath(candidate);
+  const relativePath = relative(canonicalRoot, canonicalCandidate);
+  if (!relativePath || isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) throw new Error(`Linked artifact escapes the project root: ${linkPath}`);
+  return canonicalCandidate;
 }
 
 function resolveArtifactPath(cwd: string, projectRoot: string, value: string | undefined): string | undefined {
@@ -726,12 +744,14 @@ async function buildArtifactInspectionReport(
   // An exact artifact request must not silently recruit unrelated latest evidence.
   const useLatest = params.latestFromLogs !== false && ![params.testResultsPath, params.logFilePath, params.normalizedResultPath].some(value => value?.trim());
   const logsRoot = join(candidate.projectRoot, "Logs");
-  const testResultsPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.testResultsPath)
-    ?? (useLatest ? await findNewestFile(logsRoot, [".xml"]) : undefined);
-  const logFilePath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.logFilePath)
-    ?? (useLatest ? await findNewestFile(logsRoot, [".log", ".txt"]) : undefined);
+  let testResultsPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.testResultsPath);
+  let logFilePath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.logFilePath);
   const normalizedResultPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.normalizedResultPath)
     ?? (useLatest ? await findNewestFile(logsRoot, [".json"]) : undefined);
+  if (useLatest && !normalizedResultPath) {
+    testResultsPath = await findNewestFile(logsRoot, [".xml"]);
+    if (!testResultsPath) logFilePath = await findNewestFile(logsRoot, [".log", ".txt"]);
+  }
   let normalized: NormalizedUnityTestResult | undefined;
   const evidenceErrors: string[] = [];
   const evidenceWarnings: string[] = [];
@@ -739,6 +759,11 @@ async function buildArtifactInspectionReport(
     try {
       if ((await stat(normalizedResultPath)).size > UNITY_TEST_MAX_ARTIFACT_BYTES) throw new Error("Normalized artifact exceeds its size limit.");
       normalized = validateNormalizedUnityTestArtifact(JSON.parse(await readFile(normalizedResultPath, "utf8")));
+      // Stored backend links, not unrelated directory recency, are the only automatic companions.
+      if (useLatest) {
+        if (normalized.backendArtifacts?.nunit) testResultsPath = await resolveLinkedArtifact(candidate.projectRoot, normalized.backendArtifacts.nunit);
+        if (normalized.backendArtifacts?.log) logFilePath = await resolveLinkedArtifact(candidate.projectRoot, normalized.backendArtifacts.log);
+      }
     } catch (error) {
       evidenceErrors.push(`Normalized test result could not be loaded/validated: ${normalizedResultPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -769,7 +794,13 @@ async function buildArtifactInspectionReport(
     }
     if ((normalized.outcome === "passed" || normalized.outcome === "passed_with_flakes") && parsedTestResults.failedTests.length > 0) evidenceErrors.push("Conflicting normalized/XML evidence: XML contains failed tests.");
     const linkedXml = normalized.backendArtifacts?.nunit;
-    if (linkedXml && resolve(candidate.projectRoot, linkedXml) !== resolve(testResultsPath!)) evidenceErrors.push("Conflicting artifact identity: selected XML is not the normalized artifact's nunit path.");
+    if (linkedXml && testResultsPath) {
+      try {
+        if (await resolveLinkedArtifact(candidate.projectRoot, linkedXml) !== await realpath(testResultsPath)) evidenceErrors.push("Conflicting artifact identity: selected XML is not the normalized artifact's nunit path.");
+      } catch (error) {
+        evidenceErrors.push(`Normalized NUnit link could not be resolved: ${linkedXml}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     if (!linkedXml) {
       evidenceWarnings.push("Normalized JSON and XML have no shared run identity; matching counts alone do not correlate these files.");
       testOutcome = "uncertain";
@@ -905,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.");
@@ -1204,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);
@@ -1230,7 +1175,25 @@ async function runUnifiedUnityTests(
   }
   const formats = request.reportFormats ?? defaultUnityTestReportFormats(route);
   if (route === "connected") {
-    const 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 }] }) });
+    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 }], details: undefined }) });
+    } catch (error) {
+      if (!(error instanceof UnityPipelineTerminalTestEvidenceError)) throw error;
+      const outcome = error.evidence.outcome;
+      const normalized: NormalizedUnityTestResult = {
+        schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
+        selection: { testFilters: request.testFilters, testCategories: request.testCategories },
+        durationSeconds: error.evidence.elapsedSeconds, outcome, summary: {}, tests: error.evidence.testRecords,
+        diagnostics: [error.evidence.reason, ...error.evidence.observations, ...error.evidence.warnings].slice(0, 8),
+      };
+      let artifactPath: string;
+      try { artifactPath = await writeNormalizedUnityTestArtifact(candidate.projectRoot, normalized); } catch (persistenceError) {
+        throw new Error(`${error.evidence.reason} Durable terminal evidence could not be persisted: ${persistenceError instanceof Error ? persistenceError.message : String(persistenceError)}`);
+      }
+      const text = `${compactUnityTestSummary(normalized)}\nRoute: connected Pipeline. Terminal evidence was incomplete or non-passing; no retry, fallback, or replay was performed. Normalized artifact: ${artifactPath}`;
+      return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), editorPath: "", status: "failed", testResult: { ...normalized, tests: [] }, artifactPath, route } };
+    }
     const counts = result.details.counts!;
     const normalized: NormalizedUnityTestResult = {
       schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
@@ -1287,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).`,
@@ -1404,7 +1279,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     const details = event.details as UnityToolDetails | undefined;
     if ((event.toolName === "unity_pipeline_eval" && details?.mode === "pipeline_eval" && details.pipelineEval?.outcome === "rejected")
       || (event.toolName === "unity_pipeline_inspect" && details?.mode === "pipeline_inspection" && details.pipelineInspection?.outcome === "rejected")
-      || (event.toolName === "unity_pipeline_run_script" && details?.mode === "pipeline_run_script" && details.pipelineRunScript?.outcome === "rejected")) {
+      || (event.toolName === "unity_pipeline_run_script" && details?.mode === "pipeline_run_script" && details.pipelineRunScript?.outcome === "rejected")
+      || (event.toolName === "unity_run_tests" && details?.mode === "tests" && details.testResult?.outcome !== "passed" && details.testResult?.outcome !== "passed_with_flakes" && details.testResult?.outcome !== "empty_selection")) {
       return { isError: true };
     }
   });
@@ -1572,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);
     },
   });
 
@@ -1610,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);
     },
   });
 
@@ -1633,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({
@@ -1653,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 }],
@@ -1667,12 +1535,13 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   pi.registerTool({
     name: "unity_pipeline_eval",
     label: "Unity Pipeline Eval",
-    description: "Execute one bounded C# snippet through advertised eval in an already-open exact Unity Pipeline Editor.",
+    description: "Execute one bounded C# snippet through advertised eval in an already-open exact Unity Pipeline Editor. timeoutSeconds bounds pi-unity and Unity CLI waits; optional handlerTimeoutMilliseconds is forwarded only through a verified Pipeline raw-argv timeout contract and cannot cancel code already started on Unity's main thread.",
     promptSnippet: "Query or operate on an already-open exact Unity project through Pipeline's Roslyn C# REPL.",
     promptGuidelines: [
       "Use unity_pipeline_eval for project-specific properties, APIs, and operations that advertised typed commands do not cover. It revalidates exact-copy identity and advertised eval immediately before dispatch.",
       "Pipeline eval compiles arbitrary C# with Roslyn on the Editor main thread. Include an explicit return value for observable evidence; normal property reads and local-variable snippets are supported.",
       "Eval is not statically read-only. Follow user intent and project guidance, and obtain explicit authorization before lifecycle, persistent-setting, destructive, asset, scene-save, package, build, or test mutations.",
+      "timeoutSeconds bounds the host and Unity CLI wait. When supplied, handlerTimeoutMilliseconds bounds only the verified Pipeline dispatcher wait; a shorter host deadline may still win, and a server wait expiry cannot cancel code already started on Unity's main thread.",
       "A rejected, malformed, failing, or timed-out eval is not success; do not silently retry it through another route.",
     ],
     parameters: PIPELINE_EVAL_PARAMS,
@@ -1685,6 +1554,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         unityVersion: await requireManualUnityVersion(candidate),
         command: "eval",
         evalSnippet: params.code,
+        handlerTimeoutMilliseconds: params.handlerTimeoutMilliseconds,
       }, {
         execute: createPlanningUnityCliExecutor(pi),
         signal,
@@ -1804,7 +1674,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       "Use unity_inspect_artifacts after Unity failures when existing -testResults or -logFile artifacts need concise parsing without another Unity launch.",
       "Prefer unity_inspect_artifacts over ad hoc bash parsing of Unity XML/log files when paths are known or Logs/ contains recent artifacts.",
       "unity_inspect_artifacts does not launch Unity and is safe to use even when the Unity project is busy.",
-      "Inspect details.testOutcome, not inspection status, for test success. Passing evidence needs consistent positive passing counts; missing explicit paths and conflicting artifacts fail inspection. Latest files are not current-run identity.",
+      "Inspect details.testOutcome, not inspection status, for test success. Passing evidence needs consistent positive passing counts; missing explicit paths and conflicting artifacts fail inspection. With all paths omitted, latest selection uses one JSON and its contained declared links, otherwise XML alone then log context; explicit paths disable selection/link expansion. Latest files are not current-run identity.",
     ],
     parameters: INSPECT_ARTIFACTS_PARAMS,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -1821,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);
     },
   });
 
@@ -1880,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);
     },
   });
 
@@ -1919,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.13.0",
+  "version": "0.15.0",
   "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/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": {
@@ -53,7 +56,9 @@
     "@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"
+    "@types/node": "22.20.2",
+    "tsx": "^4.23.5",
+    "typescript": "7.0.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {