@aefree/pi-unity 0.9.3 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## Unreleased
+
+## [0.11.0] - 2026-08-26
+
+### Added
+
+- Added unified `unity_run_tests`, which routes compatible exact-copy connected runs through Pipeline and closed-project runs through `unity test`, with durable normalized JSON evidence.
+- Added normalized outcomes for passes, flaky passes, test failures, empty selections, run errors, timeouts, cancellation, and uncertain evidence.
+- Added isolated Unity CLI support for retries, rerunning failures, deterministic sharding, NUnit/JUnit reports, and coverage controls.
+
+### Changed
+
+- Connected Pipeline tests now preserve complete bounded result evidence in durable normalized JSON while keeping routine tool output compact.
+- Isolated tests now prefer the Unity CLI `unity test` workflow and reconcile retry sidecars and derived rerun/shard reports.
+
+### Removed
+
+- Removed the public `unity_pipeline_run_tests` and `unity_run_test_batch` registrations; `unity_launch_batchmode` remains a non-test escape hatch.
+
+## [0.10.0] - 2026-08-14
+
+### Changed
+
+- Added a configurable 1–86,400-second timeout to `unity_pipeline_eval`, forwarding it to both Unity CLI and the host process.
+- Handle Pipeline 0.5's explicitly rejected initial-settling `Server Busy` envelopes with bounded retries for connected recompiles and tests, while preserving no-retry handling for ambiguous responses.
+
 ## [0.9.3] - 2026-08-10
 
 ### Added

package/README.md

@@ -33,22 +33,21 @@ 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_pipeline_run_tests` — run one focused EditMode or PlayMode selection with bounded polling and aggregate results.
-- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL.
+- `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_inspect` — dispatch supported package-owned inspection commands and return structured evidence.
 
 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.
+A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. The sole exception is Pipeline 0.5's explicit initial-settling `Server Busy` rejection for `unity_pipeline_recompile` and `unity_run_tests`, which is known not to have dispatched a main-thread command and is retried only within the configured deadline.
 
 ### Editor and batchmode
 
 - `unity_open_editor` — open the Unity Editor GUI. Pass `automated: true` to add the Unity Editor `-automated` flag; this is distinct from the Unity CLI's own `--non-interactive` option.
 - `unity_launch_batchmode` — run a bounded batchmode command through Unity CLI or the direct Editor executable.
-- `unity_run_test_batch` — run one isolated or report-producing Unity Test Framework platform with generated XML and log paths.
 - `unity_inspect_artifacts` — summarize existing Unity Test Framework XML and Unity logs without launching Unity.
 
-Use connected tests when the exact project is already open and Pipeline testing is reachable. Use `unity_run_test_batch` for closed projects, CI-style isolation, categories or multiple filters, graphics-dependent PlayMode tests, or required NUnit XML/log evidence.
+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.
 
 Batchmode runs use `-nographics` by default. Set `useGraphics: true` only for screenshots, visual capture, render checks, or graphics-dependent tests. Unity permits only one process per project folder, so all launch routes verify the exact project and use a per-project mutex.
 
@@ -78,8 +77,8 @@ Operation-specific recovery belongs to the operational skill. `unity-debugging`
 | Situation | Preferred route |
 | --- | --- |
 | Open exact-copy Editor with reachable Pipeline | Connected Pipeline tools |
-| Closed project or intentional CI isolation | `unity_run_test_batch` or `unity_launch_batchmode` |
-| Required NUnit XML or Unity log evidence | `unity_run_test_batch` |
+| Closed project or intentional CI isolation | `unity_run_tests` |
+| Required NUnit XML or Unity log evidence | `unity_run_tests` |
 | Existing failed-run artifacts | `unity_inspect_artifacts` |
 | Project-specific C# query or operation | `unity_pipeline_eval` |
 | Supported structured project inspection | `unity_pipeline_inspect` |

package/index.ts

@@ -1,7 +1,7 @@
 import { keyHint, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { mkdir, readdir, stat, unlink } from "node:fs/promises";
+import { mkdir, readFile, readdir, stat, unlink } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
@@ -20,13 +20,14 @@ import {
   type UnityParsedTestResults,
 } from "./src/unity-batchmode";
 import { formatPathForUser, hasUnityCommandLineFlag } from "./src/unity-core";
-import { createUnityCliBatchmodeReportArgs, createUnityCliEditorExitCommand, createUnityCliRunCommand, dispatchUnityPlanningInspection, haveSameKnownProcessIds, inspectUnityCliProjectCapabilities, listRunningUnityCliEditorsForProject, resolveUnityCliCommand, UNITY_PLANNING_READ_COMMANDS, type UnityCliProjectCapabilities } from "./src/unity-cli";
+import { createUnityCliBatchmodeReportArgs, createUnityCliEditorExitCommand, createUnityCliRunCommand, createUnityCliTestCommand, dispatchUnityPlanningInspection, haveSameKnownProcessIds, inspectUnityCliProjectCapabilities, listRunningUnityCliEditorsForProject, resolveUnityCliCommand, UNITY_PLANNING_READ_COMMANDS, type UnityCliProjectCapabilities } from "./src/unity-cli";
 import { createUnityBatchmodeCommand, launchUnityCliOpenDetached, launchUnityEditorDetached, resolveUnityEditorPath } from "./src/unity-launch";
 import { loadPiUnitySettings, type PiUnitySettings } from "./src/pi-unity-settings";
 import { dedupeRunningUnityProcesses, listRunningUnityProcessesForProject, redactUnityProcessCommandLine, terminateRunningUnityProcesses, verifyUnityProcessIdentity, type RunningUnityProcess } from "./src/unity-processes";
 import { assertUnityProjectNotBusy, evaluateUnityLaunchSafety, getUnityNativeLockfilePath, inspectUnityProjectBusyState, withUnityProjectLaunchMutex } from "./src/unity-project-lock";
 import { resolveUnityProjectCandidates, type UnityProjectCandidate } from "./src/unity-projects";
 import { createUnityTestBatchPlan, type UnityTestBatchPlan, type UnityTestPlatform } from "./src/unity-test-batch";
+import { applyUnityCliRetrySummary, compactUnityTestSummary, defaultUnityTestReportFormats, deriveUnityCliEffectiveReportPath, determineUnityTestOutcome, getUnityTestRouteRequirements, normalizeUnityRunTestsRequest, parseUnityCliRetrySummary, writeNormalizedUnityTestArtifact, type NormalizedUnityTestResult, type UnityRunTestsRequest } from "./src/unity-tests";
 import { auditUnityGuidance, type UnityGuidanceAuditResult } from "./src/unity-guidance-audit";
 import { runUnityPipelineRecompile, runUnityPipelineTests, type UnityPipelineOperationDetails } from "./src/unity-pipeline";
 import {
@@ -66,7 +67,7 @@ const GUI_WARNING = "This launches the full Unity Editor GUI and is not the same
 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 = {
-  mode: "gui" | "batchmode" | "status" | "artifacts" | "pipeline_inspection" | "pipeline_eval" | "pipeline";
+  mode: "gui" | "batchmode" | "status" | "artifacts" | "pipeline_inspection" | "pipeline_eval" | "pipeline" | "tests";
   projectRoot: string;
   unityVersion: string;
   editorPath: string;
@@ -117,6 +118,25 @@ const LAUNCH_BATCHMODE_PARAMS = Type.Object({
   closeBlockingUnityProcess: Type.Optional(Type.Boolean({ default: false, description: "When true, pi-unity may close a running Unity process for the resolved project before launch, but only if piUnity.allowCloseRunningUnityProcess is enabled in Pi settings. The process is selected by project matching, not by model-supplied PID." })),
 });
 
+const RUN_TESTS_PARAMS = Type.Object({
+  path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
+  testPlatform: StringEnum(["EditMode", "PlayMode"] as const),
+  testFilters: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
+  testCategories: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
+  execution: Type.Optional(StringEnum(["auto", "connected", "isolated"] as const, { default: "auto" })),
+  isolatedLauncher: Type.Optional(StringEnum(["auto", "unity-cli", "editor-executable"] as const, { default: "auto" })),
+  retries: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, default: 0 })),
+  rerunFailed: Type.Optional(Type.Boolean({ default: false })),
+  shard: Type.Optional(Type.String({ maxLength: 500 })),
+  shardInventoryPath: Type.Optional(Type.String({ maxLength: 1000 })),
+  reportFormats: Type.Optional(Type.Array(StringEnum(["json", "nunit", "junit"] as const), { maxItems: 3 })),
+  coverage: Type.Optional(Type.Boolean({ default: false })),
+  coverageOptions: Type.Optional(Type.String({ maxLength: 1000 })),
+  useGraphics: Type.Optional(Type.Boolean({ default: false })),
+  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 14400, default: 3600 })),
+  closeBlockingUnityProcess: Type.Optional(Type.Boolean({ default: false })),
+}, { additionalProperties: false });
+
 const RUN_TEST_BATCH_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
   unityEditorPath: Type.Optional(Type.String({ description: "Optional explicit Unity executable path override." })),
@@ -148,6 +168,7 @@ 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." })),
 }, { additionalProperties: false });
 
 const PIPELINE_INSPECTION_PARAMS = Type.Object({
@@ -167,6 +188,7 @@ const GUIDANCE_AUDIT_PARAMS = Type.Object({
 const INSPECT_ARTIFACTS_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
   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: "When paths are omitted, inspect the newest .xml and .log files under the project's Logs folder." })),
   maxLines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, default: 60, description: "Maximum log/output lines to include." })),
@@ -684,7 +706,7 @@ function compactUnityArtifacts(artifacts: UnityBatchmodeArtifacts): UnityBatchmo
 async function buildArtifactInspectionReport(
   ctx: ExtensionContext,
   candidate: UnityProjectCandidate,
-  params: { testResultsPath?: string; logFilePath?: string; latestFromLogs?: boolean; maxLines?: number; maxChars?: number },
+  params: { testResultsPath?: string; normalizedResultPath?: string; logFilePath?: string; latestFromLogs?: boolean; maxLines?: number; maxChars?: number },
 ): Promise<{ text: string; details: UnityToolDetails }> {
   const useLatest = params.latestFromLogs !== false;
   const logsRoot = join(candidate.projectRoot, "Logs");
@@ -692,6 +714,15 @@ async function buildArtifactInspectionReport(
     ?? (useLatest ? await findNewestFile(logsRoot, [".xml"]) : undefined);
   const logFilePath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.logFilePath)
     ?? (useLatest ? await findNewestFile(logsRoot, [".log", ".txt"]) : undefined);
+  const normalizedResultPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.normalizedResultPath)
+    ?? (useLatest ? await findNewestFile(logsRoot, [".json"]) : undefined);
+  let normalizedSummary: string | undefined;
+  if (normalizedResultPath) {
+    try {
+      const normalized = JSON.parse(await readFile(normalizedResultPath, "utf8")) as Partial<NormalizedUnityTestResult>;
+      if (normalized.schemaVersion === 1 && typeof normalized.outcome === "string") normalizedSummary = `Normalized test result: ${normalized.platform ?? "Unity"} ${normalized.outcome}; ${normalized.summary?.total ?? "unknown"} total.`;
+    } catch { normalizedSummary = `Normalized test result JSON could not be parsed: ${normalizedResultPath}`; }
+  }
   const invocation: UnityBatchmodeInvocation = {
     isTestRun: Boolean(testResultsPath),
     usesNoGraphics: false,
@@ -709,6 +740,8 @@ async function buildArtifactInspectionReport(
     `Unity artifacts inspected for ${formatPathForUser(ctx.cwd, candidate.projectRoot)} using Unity ${candidate.unityVersion}.`,
     testResultsPath ? `Requested test results: ${testResultsPath}` : "Requested test results: (none found)",
     logFilePath ? `Requested log file: ${logFilePath}` : "Requested log file: (none found)",
+    normalizedResultPath ? `Requested normalized result: ${normalizedResultPath}` : "Requested normalized result: (none found)",
+    ...(normalizedSummary ? [normalizedSummary] : []),
   ];
 
   if (parsedTestResults) {
@@ -1078,6 +1111,96 @@ async function runGuardedUnityBatchmode(
   );
 }
 
+async function runUnifiedUnityTests(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  candidate: UnityProjectCandidate,
+  discoveryWarning: string | undefined,
+  raw: UnityRunTestsRequest,
+  signal: AbortSignal | undefined,
+  onUpdate?: (update: { content: Array<{ type: "text"; text: string }> }) => void,
+  allowAutonomousExitPlayMode = true,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: UnityToolDetails & { testResult: NormalizedUnityTestResult; artifactPath: string; route: "connected" | "isolated" } }> {
+  const request = normalizeUnityRunTestsRequest(raw);
+  const requirements = getUnityTestRouteRequirements(request);
+  const capabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, candidate.unityVersion, { signal, execute: createPipelineUnityCliExecutor(pi) });
+  const reachable = capabilities.matchingInstances.some(instance => instance.reachable === true);
+  const busy = (await listBlockingUnityProcesses(candidate.projectRoot)).processes.length > 0 || capabilities.matchingInstances.length > 0;
+  let route: "connected" | "isolated";
+  if (request.execution === "connected") {
+    if (requirements.requiresIsolation) throw new Error(`Connected execution cannot honor this request: ${requirements.reasons.join("; ")}.`);
+    if (!reachable) throw new Error("Connected execution requires an already-open exact-copy reachable Pipeline Editor; no Unity was launched.");
+    route = "connected";
+  } else if (request.execution === "isolated") {
+    if (reachable && !request.closeBlockingUnityProcess) throw new Error("Isolated execution will not close a reachable Pipeline Editor automatically. Close it first or use the explicitly guarded close option.");
+    route = "isolated";
+  } else if (reachable) {
+    if (requirements.requiresIsolation) throw new Error(`This request requires isolated execution (${requirements.reasons.join("; ")}), but the exact project copy is open in reachable Pipeline. pi-unity will not close it automatically.`);
+    route = "connected";
+  } else {
+    if (capabilities.pipelineDiscovery === "timeout" || (capabilities.projectSupportsPipeline && capabilities.pipelineDiscovery !== "absent" && capabilities.pipelineDiscovery !== "available")) throw new Error("Pipeline discovery is uncertain for this exact project copy; refusing to start an isolated Editor until project state is known.");
+    if (busy) throw new Error("A Unity process is already open for this exact project copy without reachable Pipeline; refusing to launch a second process.");
+    route = "isolated";
+  }
+  const formats = request.reportFormats ?? defaultUnityTestReportFormats(route);
+  if (route === "connected") {
+    const result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: candidate.unityVersion, 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 }] }) });
+    const counts = result.details.counts!;
+    const normalized: NormalizedUnityTestResult = {
+      schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
+      selection: { testFilters: request.testFilters, testCategories: request.testCategories },
+      durationSeconds: result.details.elapsedSeconds, outcome: determineUnityTestOutcome(counts), summary: counts, tests: result.testRecords ?? [],
+    };
+    const artifactPath = await writeNormalizedUnityTestArtifact(candidate.projectRoot, normalized);
+    const text = `${compactUnityTestSummary(normalized)}\nRoute: connected Pipeline. Normalized artifact: ${artifactPath}`;
+    return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: candidate.unityVersion, editorPath: "", status: normalized.outcome === "passed" ? "passed" : "failed", pipeline: result.details, testResult: { ...normalized, tests: [] }, artifactPath, route } };
+  }
+  if (request.isolatedLauncher === "editor-executable" && (request.retries || request.rerunFailed || request.shard || request.coverage || formats.includes("junit"))) throw new Error("The direct Editor fallback cannot honor CLI-only retry, rerun, shard, coverage, or JUnit options.");
+  const plan = createUnityTestBatchPlan({ projectRoot: candidate.projectRoot, testPlatform: request.testPlatform, testFilters: request.testFilters, testCategories: request.testCategories });
+  const cliAvailable = request.isolatedLauncher !== "editor-executable" && await canUseUnityCli(pi, signal);
+  if (!cliAvailable && request.isolatedLauncher === "unity-cli") throw new Error("Unity CLI was requested but is unavailable.");
+  if (!cliAvailable && (request.retries || request.rerunFailed || request.shard || request.coverage || formats.includes("junit"))) throw new Error("Unity CLI is unavailable and the requested options have no direct Editor fallback.");
+  if (!cliAvailable) {
+    const fallback = await runGuardedUnityBatchmode(pi, ctx, candidate, discoveryWarning, { args: plan.args, useGraphics: request.useGraphics, timeoutSeconds: request.timeoutSeconds, launcher: "editor-executable", closeBlockingUnityProcess: request.closeBlockingUnityProcess }, signal, "unity_run_test_batch");
+    const parsed = fallback.details.parsedTestResults;
+    const summary = { total: parsed?.total, passed: parsed?.passed, failed: parsed?.failed, skipped: parsed?.skipped };
+    const normalized: NormalizedUnityTestResult = { schemaVersion: 1, source: "editor-executable", platform: request.testPlatform, selection: { testFilters: request.testFilters, testCategories: request.testCategories }, outcome: determineUnityTestOutcome(summary), summary, tests: parsed?.tests ?? [] };
+    const artifactPath = await writeNormalizedUnityTestArtifact(candidate.projectRoot, normalized);
+    return { content: [{ type: "text", text: `${compactUnityTestSummary(normalized)}\nRoute: isolated direct Editor. Normalized artifact: ${artifactPath}` }], details: { ...fallback.details, mode: "tests", testResult: { ...normalized, tests: [] }, artifactPath, route } };
+  }
+  return await withUnityProjectLaunchMutex(candidate.projectRoot, { mode: "batchmode", toolName: "unity_run_tests" }, async () => {
+    const invocation = parseUnityBatchmodeInvocation(plan.args);
+    const closeReport = await closeBlockingUnityProcessesForBatchmode(pi, ctx, candidate, invocation, request.closeBlockingUnityProcess, signal);
+    await removeStaleLockfileAfterGuardedClose(candidate, closeReport);
+    await enforceLaunchRouteSafety(candidate.projectRoot, "unity-cli");
+    const command = createUnityCliTestCommand(candidate.projectRoot, { testPlatform: request.testPlatform, testFilters: request.testFilters, testCategories: request.testCategories, retries: request.retries, rerunFailed: request.rerunFailed, shard: request.shard, shardInventoryPath: request.shardInventoryPath, reportPaths: { nunit: formats.includes("nunit") ? plan.testResultsPath : undefined, junit: formats.includes("junit") ? plan.junitResultsPath : undefined, log: plan.logFilePath }, coverage: request.coverage, coverageOptions: request.coverageOptions, useGraphics: request.useGraphics, timeoutSeconds: request.timeoutSeconds, editorVersion: candidate.unityVersion });
+    const execution = await pi.exec(command.command, command.args, { signal, timeout: (request.timeoutSeconds ?? 3600) * 1000 + 30_000 });
+    const effectiveResultsPath = deriveUnityCliEffectiveReportPath(plan.testResultsPath, { rerunFailed: request.rerunFailed, shard: request.shard });
+    let effectiveResultsXml: string | undefined;
+    try { effectiveResultsXml = await readFile(effectiveResultsPath, "utf8"); } catch { /* Missing current-run evidence is handled below. */ }
+    const parsed = effectiveResultsXml ? parseUnityTestResultsXml(effectiveResultsXml) : null;
+    const summary = { total: parsed?.total, passed: parsed?.passed, failed: parsed?.failed, skipped: parsed?.skipped };
+    const outcome = execution.killed ? "timed_out" : execution.code === 8 ? "tests_failed" : execution.code === 6 ? "run_error" : determineUnityTestOutcome(summary);
+    let normalized: NormalizedUnityTestResult = { schemaVersion: 1, source: "unity-cli", platform: request.testPlatform, selection: { testFilters: request.testFilters, testCategories: request.testCategories }, outcome: (request.rerunFailed || request.shard) && execution.code === 0 && !parsed ? "empty_selection" : outcome, summary, tests: parsed?.tests ?? [], backendArtifacts: { ...(parsed && formats.includes("nunit") ? { nunit: `Logs/${effectiveResultsPath.split(/[\\/]/).pop()}` } : {}), ...(parsed && formats.includes("junit") ? { junit: `Logs/${deriveUnityCliEffectiveReportPath(plan.junitResultsPath, { rerunFailed: request.rerunFailed, shard: request.shard }).split(/[\\/]/).pop()}` } : {}), log: `Logs/${plan.logFilePath.split(/[\\/]/).pop()}` } };
+    if (request.retries > 0 && formats.includes("nunit")) {
+      const retryPath = effectiveResultsPath.replace(/\.[^.\\/]+$/, ".retries.json");
+      try {
+        const retry = parseUnityCliRetrySummary(JSON.parse(await readFile(retryPath, "utf8")));
+        if (!retry) normalized = { ...normalized, outcome: "uncertain" };
+        else {
+          normalized = applyUnityCliRetrySummary(normalized, retry);
+          normalized.backendArtifacts = { ...normalized.backendArtifacts, retrySummary: `Logs/${retryPath.split(/[\\/]/).pop()}` };
+        }
+      } catch {
+        normalized = { ...normalized, outcome: "uncertain" };
+      }
+    }
+    const artifactPath = await writeNormalizedUnityTestArtifact(candidate.projectRoot, normalized);
+    const text = `${compactUnityTestSummary(normalized)}\nRoute: isolated Unity CLI. Normalized artifact: ${artifactPath}`;
+    return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: candidate.unityVersion, editorPath: "Unity CLI", status: outcome === "passed" || outcome === "passed_with_flakes" || outcome === "empty_selection" ? "passed" : "failed", command: command.command, cliArgs: command.args, testBatch: plan, testResult: { ...normalized, tests: [] }, artifactPath, route } };
+  });
+}
+
 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);
@@ -1391,6 +1514,27 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "unity_run_tests",
+    label: "Unity Run Tests",
+    description: "Run Unity Test Framework tests through one intent-oriented workflow. It reuses a reachable exact-copy Pipeline Editor when compatible, otherwise uses isolated `unity test` execution.",
+    promptSnippet: "Run Unity EditMode or PlayMode tests through one safe routed workflow with durable normalized evidence.",
+    promptGuidelines: [
+      "Use unity_run_tests for ordinary Unity Test Framework runs. It selects connected Pipeline only for compatible requests and isolated unity test only when the exact project copy is closed.",
+      "Do not use unity_launch_batchmode for ordinary tests; raw test flags there are an unsupported escape hatch.",
+      "A reachable Editor is never closed merely to obtain isolated-only options. Requests needing retries, sharding, reruns, coverage, multiple selectors, or XML reports are rejected before dispatch when it is open.",
+      "Timeout, malformed evidence, cancellation, or missing artifacts never cause a backend fallback or relaunch.",
+    ],
+    parameters: RUN_TESTS_PARAMS,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      throwIfAborted(signal);
+      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); },
+  });
+
   pi.registerTool({
     name: "unity_pipeline_recompile",
     label: "Unity Pipeline Recompile",
@@ -1418,34 +1562,6 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     renderResult(result, options, theme, context) { return renderUnityPipelineResult(result, options, theme, context); },
   });
 
-  pi.registerTool({
-    name: "unity_pipeline_run_tests",
-    label: "Unity Pipeline Run Tests",
-    description: "Run one focused EditMode or PlayMode test selection through an already-open exact Unity Pipeline Editor, with internal bounded polling and aggregate output.",
-    promptSnippet: "Run focused connected Unity EditMode or PlayMode tests in one bounded call without shell polling; aggregate passing results stay compact.",
-    promptGuidelines: [
-      "Use unity_pipeline_run_tests for one focused connected Unity test platform when the exact Editor is already open and reachable.",
-      "unity_pipeline_run_tests may exit Play Mode through advertised editor_stop when needed, then verifies Edit Mode before dispatching tests.",
-      "Use unity_run_test_batch instead of unity_pipeline_run_tests for closed projects, isolation, complex filters/categories, or required NUnit XML/log evidence.",
-      "unity_pipeline_run_tests does not cancel uncertain work or switch to batchmode after timeout; report that the connected run may still be running.",
-    ],
-    parameters: PIPELINE_TEST_PARAMS,
-    async execute(_toolCallId, params, signal, onUpdate, ctx) {
-      throwIfAborted(signal);
-      const { candidate } = await resolveProjectCandidate(ctx, params.path);
-      const result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: candidate.unityVersion, testPlatform: params.testPlatform, testFilter: params.testFilter, timeoutSeconds: params.timeoutSeconds, allowAutonomousExitPlayMode: sessionAllowsAutonomousPlayModeExit(ctx) }, createPipelineDependencies(pi), {
-        signal,
-        onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }),
-      });
-      return {
-        content: [{ type: "text", text: result.text }],
-        details: { mode: "pipeline", projectRoot: result.details.projectRoot, unityVersion: candidate.unityVersion, editorPath: "", status: "passed", pipeline: result.details } satisfies UnityToolDetails,
-      };
-    },
-    renderCall(args, theme, context) { return renderUnityPipelineCall("unity_pipeline_run_tests", args, theme, context); },
-    renderResult(result, options, theme, context) { return renderUnityPipelineResult(result, options, theme, context); },
-  });
-
   pi.registerTool({
     name: "unity_pipeline_eval",
     label: "Unity Pipeline Eval",
@@ -1470,7 +1586,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       }, {
         execute: createPlanningUnityCliExecutor(pi),
         signal,
-        timeout: 12_000,
+        timeout: (params.timeoutSeconds ?? 12) * 1000,
       });
       throwIfAborted(signal);
       const text = result.outcome === "dispatched"
@@ -1639,52 +1755,6 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     },
   });
 
-  pi.registerTool({
-    name: "unity_run_test_batch",
-    label: "Unity Test Batch",
-    description: "Run one bundled Unity Test Framework platform with normalized filters/categories and generated absolute XML/log paths under the project Logs directory.",
-    promptSnippet: "Run a bundled Unity EditMode or PlayMode test batch with safe generated artifact paths",
-    promptGuidelines: [
-      "Before choosing a test route, call unity_project_status for the exact project copy. If it is already open with reachable Pipeline run_tests/test_status commands, use the connected workflow without closing the Editor.",
-      "Prefer unity_run_test_batch over unity_launch_batchmode only for isolated or report-producing Unity Test Framework runs: closed projects, unavailable/unsupported connected testing, intentional CI isolation, unsupported filters, or required NUnit XML/log artifacts.",
-      "Do not set closeBlockingUnityProcess merely to switch a reachable Pipeline Editor into batchmode; use it only after isolated execution is deliberately required and the guarded setting is enabled.",
-      "Pass unity_run_test_batch exactly one testPlatform. Multiple test platforms require separate user-authorized launches.",
-      "An empty unity_run_test_batch testFilters/testCategories selection runs all tests for that testPlatform; use narrow arrays when focused evidence is sufficient.",
-      "Do not call unity_run_test_batch for PlayMode when user/project guidance says to skip PlayMode tests.",
-      "Use unity_run_test_batch useGraphics=true only for graphics-dependent PlayMode tests or visual capture; ordinary EditMode and non-visual PlayMode remain headless.",
-      "After unity_run_test_batch infrastructure failure, inspect the exact generated paths reported by the failed call once and do not repeat an unchanged launch.",
-    ],
-    parameters: RUN_TEST_BATCH_PARAMS,
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      throwIfAborted(signal);
-      const { candidate, discoveryWarning } = await resolveProjectCandidate(ctx, params.path);
-      const plan = createUnityTestBatchPlan({
-        projectRoot: candidate.projectRoot,
-        testPlatform: params.testPlatform as UnityTestPlatform,
-        testFilters: params.testFilters,
-        testCategories: params.testCategories,
-      });
-      await mkdir(dirname(plan.testResultsPath), { recursive: true });
-      throwIfAborted(signal);
-      const result = await runGuardedUnityBatchmode(pi, ctx, candidate, discoveryWarning, {
-        unityEditorPath: params.unityEditorPath,
-        args: plan.args,
-        useGraphics: params.useGraphics,
-        timeoutSeconds: params.timeoutSeconds,
-        launcher: params.launcher as UnityLauncherPreference | undefined,
-        closeBlockingUnityProcess: params.closeBlockingUnityProcess,
-      }, signal, "unity_run_test_batch");
-      result.details = { ...result.details, testBatch: plan };
-      return result;
-    },
-    renderCall(args, theme) {
-      return renderUnityToolCall("unity_run_test_batch", args, theme, "batchmode", `${args.testPlatform} test batch`);
-    },
-    renderResult(result, { expanded }, theme) {
-      return renderUnityToolResult(result, expanded, theme);
-    },
-  });
-
   pi.registerTool({
     name: "unity_launch_batchmode",
     label: "Unity CLI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -18,7 +18,7 @@
     ]
   },
   "scripts": {
-    "test": "tsx tests/unity-core.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-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",
+    "test": "tsx tests/unity-core.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",
     "eval:guidance-skill": "tsx evals/auditing-unity-agent-guidance/run-eval.ts"
   },
   "dependencies": {

package/skills/auditing-unity-agent-guidance/assets/mixed-workflow-template.md

@@ -11,7 +11,7 @@ Always resolve and pass the exact Unity project-copy path. Do not route by proje
 
 - Inspect: `unity_project_status`
 - Connected compile/test: use the package's typed connected tools when available
-- Isolated tests: `unity_run_test_batch`
+- Isolated tests: `unity_run_tests`
 - Custom isolated Editor arguments: `unity_launch_batchmode`
 - Existing evidence: `unity_inspect_artifacts`
 

package/skills/auditing-unity-agent-guidance/references/migration-policy.md

@@ -18,7 +18,7 @@
 
 - Connected EditMode: `run_tests --mode editor`; asynchronous execution plus `test_status` is safest for uniform wrappers.
 - Connected PlayMode: require `--async_tests true`, then poll `test_status` because domain reload can drop the initiating request.
-- Isolated/report-producing: use `unity test` or the packaged `unity_run_test_batch` when NUnit XML/log artifacts are required.
+- Isolated/report-producing: use `unity test` or the packaged `unity_run_tests` when NUnit XML/log artifacts are required.
 - Preserve graphics requirements and reject zero-test, malformed, incomplete, or nested `success:false` results.
 
 ## Build and ExecuteMethod

package/skills/unity-batchmode-tests/SKILL.md

@@ -14,7 +14,7 @@ Run Unity Test Framework tests from the command line without opening the Editor
 - **Use absolute paths** for `-testResults` and `-logFile` to ensure logs are easy to find.
 - **Unity allows only one process per project folder** - GUI Editor and batchmode/headless both count as that one process.
 - **Do not open the GUI editor for the same project before or during batchmode runs** - `/unity-open` and `unity_open_editor` launch the full Unity Editor GUI and are not equivalent to headless batchmode.
-- **Do not close a reachable Pipeline Editor merely to run tests** - an already-open exact copy can run supported tests through `run_tests` plus `test_status`; use the `unity-pipeline-workflows` skill.
+- **Do not close a reachable Pipeline Editor merely to run tests** - call `unity_run_tests`; it selects connected Pipeline for supported requests and rejects isolated-only options rather than closing the Editor.
 - **Only close a blocking Unity Editor through `unity_launch_batchmode` safeguards after deliberately choosing isolated execution** - this is limited to cases such as required NUnit XML, unsupported connected filters/commands, or explicit isolation. Use `closeBlockingUnityProcess: true` only when `unity_project_status` shows `piUnity.allowCloseRunningUnityProcess` is enabled or the user explicitly says it is enabled; pi-unity re-scans the resolved project and never accepts arbitrary PIDs.
 - **Use `unity_launch_batchmode` when you want to run headless Unity directly** - keep test-specific flags deliberate, especially around `-runTests` and `-quit`.
 - **Bundle tests into one Unity batchmode turn whenever practical** - starting/stopping Unity, importing assets, and domain reloads dominate runtime. A broader single run is usually faster than many sequential one-test Unity launches, and same-project runs cannot use useful parallelism.
@@ -40,12 +40,12 @@ Run Unity Test Framework tests from the command line without opening the Editor
 Use the `pi-unity` tools first instead of forming raw Unity CLI commands on the fly:
 - `unity_project_status` to inspect lockfile/process state without launching Unity
 - `unity_inspect_artifacts` to summarize existing Unity logs/test XML without launching Unity
-- `unity_run_test_batch` for isolated/report-producing Unity Test Framework runs with one platform and bundled filters/categories
+- `unity_run_tests` for isolated/report-producing Unity Test Framework runs with one platform and bundled filters/categories
 - `unity_launch_batchmode` for custom headless Unity execution that needs raw Editor arguments
 - `unity_open_editor` only when the user explicitly wants the GUI Editor
 - `/unity-open` as the user-facing GUI launcher helper
 
-`unity_run_test_batch` should be the default for isolated or report-producing Unity Test Framework work. It generates unique absolute XML/log paths under the project `Logs` directory, normalizes filter/category arrays into one launch, omits `-quit`, and uses the same guarded executor as `unity_launch_batchmode`. For an already-open reachable exact-copy Pipeline Editor, use the `unity-pipeline-workflows` skill instead.
+`unity_run_tests` is the one ordinary Unity Test Framework tool. It routes supported requests to a reachable exact-copy Pipeline Editor or a closed-project isolated `unity test` run, writes a durable normalized JSON artifact, and retains native NUnit/JUnit reports when requested. It never silently switches after uncertain dispatch.
 
 `unity_launch_batchmode` remains the default for custom agent-run headless Unity work because it already:
 - resolves the Unity project from a direct project root, a coordination root, or another nearby folder
@@ -98,8 +98,8 @@ If not found, ask the user for their Unity install path.
 
 Route before planning a batch:
 1. Call `unity_project_status` for the exact project copy.
-2. If that copy is already open, Pipeline is reachable, and `run_tests` plus `test_status` are advertised, use `unity-pipeline-workflows`; do not close the Editor or invoke `unity_run_test_batch` merely because the test tool is more convenient.
-3. Choose isolated `unity_run_test_batch` only when the Editor is closed, connected testing is unavailable, CI/isolation is intentional, required filters are unsupported, or NUnit XML/log artifacts are required. State the reason.
+2. If that copy is already open, Pipeline is reachable, and `run_tests` plus `test_status` are advertised, use `unity-pipeline-workflows`; do not close the Editor or invoke `unity_run_tests` merely because the test tool is more convenient.
+3. Choose isolated `unity_run_tests` only when the Editor is closed, connected testing is unavailable, CI/isolation is intentional, required filters are unsupported, or NUnit XML/log artifacts are required. State the reason.
 4. If project state is uncertain, stop rather than closing the Editor or starting batchmode.
 
 After choosing the isolated route:
@@ -108,7 +108,7 @@ After choosing the isolated route:
 - when several specific tests are relevant, prefer a broader class/namespace/suite/category filter, or no `-testFilter` for the affected platform, over separate Unity launches
 - use a single-test launch only for a quick smoke check or to isolate/rerun a known failure; do not use one-test launches as the default validation strategy
 - do not queue multiple `unity_launch_batchmode` calls back-to-back in one agent turn; wait for the structured summary, inspect failures, and only then decide whether another Unity launch is necessary
-- call `unity_run_test_batch` for isolated/report-producing tests; use `unity_launch_batchmode` only when custom raw Unity arguments are required
+- call `unity_run_tests` for isolated/report-producing tests; use `unity_launch_batchmode` only when custom raw Unity arguments are required
 - pass one `testPlatform` (`EditMode` or `PlayMode`) and bundle applicable `testFilters`/`testCategories`; empty arrays mean all tests on that platform
 - use the generated exact result/log paths from the tool report for any follow-up artifact inspection
 - pass `closeBlockingUnityProcess: true` only after connected testing was ruled out or isolated evidence was explicitly required, a same-project Unity process is blocking the chosen run, and Pi settings enable `piUnity.allowCloseRunningUnityProcess`

package/skills/unity-pipeline-workflows/SKILL.md

@@ -12,19 +12,19 @@ Use this workflow only for an already-running exact project copy with `com.unity
 Use one typed tool call for each supported connected operation:
 
 - `unity_pipeline_recompile` for connected script compilation.
-- `unity_pipeline_run_tests` for one focused `EditMode` or `PlayMode` test-name selection.
+- `unity_run_tests` for one compatible `EditMode` or `PlayMode` test-name or category selection.
 
 These tools resolve the exact copy, require advertised commands, inspect lifecycle state, dispatch once, validate identity, and poll internally with a fixed deadline. Do not recreate their wait loops with `bash`, `unity recompile_status`, or `unity test_status` calls.
 
-A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision.
+A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision. The only automatic retry is Pipeline 0.5's explicit initial-settling `Server Busy` response for `unity_pipeline_recompile` or `unity_run_tests`, which confirms that a main-thread command was rejected before dispatch.
 
 ## Preconditions and boundaries
 
 1. Pass an explicit `path` when multiple project copies may be found; paths identify copies, not display names.
 2. The typed tools require a reachable exact-copy Pipeline and advertised `editor_status` plus operation commands. A different connected client is not itself a project lock.
-3. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference. Known recompile-and-continue, stop-and-recompile, and defer policies proceed according to Unity's configured behavior. Pipeline 0.4 does not currently expose that preference, so the tool reports the unavailable policy while allowing recompilation to proceed. `unity_pipeline_run_tests` may dispatch advertised `editor_stop` when needed, then verifies Edit Mode before running tests. The tools never enter Play Mode, pause, save, launch, or close Unity; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
+3. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference. Known recompile-and-continue, stop-and-recompile, and defer policies proceed according to Unity's configured behavior. Pipeline 0.4 does not currently expose that preference, so the tool reports the unavailable policy while allowing recompilation to proceed. `unity_run_tests` may dispatch advertised `editor_stop` when needed, then verifies Edit Mode before running tests. The tools never enter Play Mode, pause, save, launch, or close Unity; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
 4. Test success requires a well-formed terminal result, a known positive executed count, and zero failures. An asynchronous initiation with `Total: 0` and `running` is nonterminal.
-5. Passing test records are intentionally discarded. Failures retain only a bounded set of failed/inconclusive names, messages, and stack excerpts.
+5. Routine tool output remains compact. Complete bounded terminal test records are persisted immediately in the durable normalized JSON artifact before Pipeline status can be displaced.
 
 ## Compile
 
@@ -32,11 +32,11 @@ Call `unity_pipeline_recompile` with optional `path` and `timeoutSeconds` (defau
 
 ## Focused tests
 
-Call `unity_pipeline_run_tests` with:
+Call `unity_run_tests` with:
 
 - required `testPlatform`: `EditMode` or `PlayMode`;
-- optional `testFilter`: one test-name filter only;
-- optional `path` and `timeoutSeconds` (default 600, maximum 3600).
+- optional `testFilters` or `testCategories`: at most one selector family and one selector for connected execution;
+- optional `execution`, `path`, and `timeoutSeconds` (default 600, maximum 3600).
 - before running PlayMode tests, check the Game View focus setting. Set it to Play Unfocused for the test run, then restore the previous setting afterward.
 
 The tool treats `no_tests`, idle, and not-started statuses as safe inactivity, detects a pre-existing active connected test before dispatch, and stops rather than claiming or replacing active work. It captures returned mode/filter/run identity fields when available and stops as uncertain if status is clearly displaced by another run.
@@ -47,6 +47,6 @@ Normally call the typed tools, not raw CLI commands. If a typed tool is unavaila
 
 ## When not to use connected tools
 
-Use `unity_run_test_batch` for a closed project, intentional isolation/CI, category or multiple filters, or required NUnit XML/log evidence. State the reason for that route. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
+Use `unity_run_tests` with `execution: "isolated"` for a closed project, intentional isolation/CI, multiple selectors, retries, sharding, coverage, or required NUnit/JUnit evidence. A single category is supported connected when Pipeline advertises the command; do not claim broader connected selector support. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
 
-Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; it is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.
+Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; its `timeoutSeconds` range is 1–86,400 seconds, and a timeout remains uncertain without cancellation or retry. It is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.

package/src/unity-batchmode.ts

@@ -18,6 +18,7 @@ export type UnityFailedTest = {
   stackTrace?: string;
 };
 
+export type UnityParsedTestCase = { name: string; status: string; durationSeconds?: number; message?: string; stackTrace?: string };
 export type UnityParsedTestResults = {
   total?: number;
   passed?: number;
@@ -26,6 +27,8 @@ export type UnityParsedTestResults = {
   inconclusive?: number;
   durationSeconds?: number;
   failedTests: UnityFailedTest[];
+  /** Complete bounded per-test evidence for normalized artifacts, never routine tool output. */
+  tests: UnityParsedTestCase[];
 };
 
 export type UnityBatchmodeArtifacts = {
@@ -108,6 +111,7 @@ export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults |
 
   const rootAttributes = parseAttributes(testRunMatch[1] ?? "");
   const failedTests: UnityFailedTest[] = [];
+  const tests: UnityParsedTestCase[] = [];
 
   const testCaseRegex = /<test-case\b([^>]*)>([\s\S]*?)<\/test-case>/gi;
   for (const match of xml.matchAll(testCaseRegex)) {
@@ -116,17 +120,12 @@ export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults |
     const result = String(attributes.result ?? attributes.label ?? "").toLowerCase();
     const success = String(attributes.success ?? "").toLowerCase();
     const isFailure = result === "failed" || success === "false";
-    if (!isFailure) continue;
-
     const failureMessage = body.match(/<message[^>]*>([\s\S]*?)<\/message>/i);
     const stackTrace = body.match(/<stack-trace[^>]*>([\s\S]*?)<\/stack-trace>/i);
-    if (failedTests.length < 50) {
-      failedTests.push({
-        name: truncateEvidence(attributes.fullname ?? attributes.name ?? "(unknown test)", 500) ?? "(unknown test)",
-        message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 1_000),
-        stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 4_000),
-      });
-    }
+    const name = truncateEvidence(attributes.fullname ?? attributes.name ?? "(unknown test)", 1_000) ?? "(unknown test)";
+    if (tests.length < 2_000) tests.push({ name, status: attributes.result ?? attributes.label ?? "Unknown", ...(parseOptionalNumber(attributes.duration) === undefined ? {} : { durationSeconds: parseOptionalNumber(attributes.duration) }), ...(truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) ? { message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) } : {}), ...(truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) ? { stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) } : {}) });
+    if (!isFailure) continue;
+    if (failedTests.length < 50) failedTests.push({ name, message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 1_000), stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 4_000) });
   }
 
   const skipped = parseOptionalNumber(rootAttributes.skipped) ?? parseOptionalNumber(rootAttributes.inconclusive);
@@ -139,6 +138,7 @@ export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults |
     inconclusive: parseOptionalNumber(rootAttributes.inconclusive),
     durationSeconds: parseOptionalNumber(rootAttributes.duration),
     failedTests,
+    tests,
   };
   if (parsed.total === undefined && parsed.passed === undefined && parsed.failed === undefined && parsed.failedTests.length === 0) {
     return null;

package/src/unity-cli.ts

@@ -22,6 +22,19 @@ export type UnityCliLaunchOptions = {
   automated?: boolean;
 };
 
+export type UnityCliTestOptions = UnityCliLaunchOptions & {
+  testPlatform: "EditMode" | "PlayMode";
+  testFilters?: string[];
+  testCategories?: string[];
+  retries?: number;
+  rerunFailed?: boolean;
+  shard?: string;
+  shardInventoryPath?: string;
+  reportPaths?: { nunit?: string; junit?: string; log?: string };
+  coverage?: boolean;
+  coverageOptions?: string;
+};
+
 export type UnityCliPipelineInstance = {
   projectPath: string;
   pid: number | null;
@@ -116,6 +129,30 @@ export function normalizeUnityCliForwardedArgs(extraEditorArgs: string[] = []):
   return normalized;
 }
 
+export function createUnityCliTestCommand(projectRoot: string, options: UnityCliTestOptions): UnityCliCommand {
+  const args = [...unityCliBaseArgs(), "test", projectRoot, "--mode", options.testPlatform];
+  appendUnityCliEditorOptions(args, options);
+  if (options.timeoutSeconds !== undefined) args.push("--timeout", String(options.timeoutSeconds));
+  if (options.testFilters?.length) args.push("--filter", options.testFilters.join(";"));
+  if (options.retries) args.push("--retries", String(options.retries));
+  if (options.rerunFailed) args.push("--rerun-failed");
+  if (options.shard) args.push("--shard", options.shard);
+  if (options.shardInventoryPath) args.push("--shard-inventory", options.shardInventoryPath);
+  const nunit = options.reportPaths?.nunit;
+  const junit = options.reportPaths?.junit;
+  if (nunit && junit) args.push("--output", nunit, "--report-format", "nunit,junit", "--junit-output", junit);
+  else if (junit) args.push("--output", junit, "--report-format", "junit");
+  else if (nunit) args.push("--output", nunit);
+  if (options.coverage) args.push("--coverage");
+  if (options.coverageOptions) args.push("--coverage-options", options.coverageOptions);
+  const editorArgs: string[] = [];
+  if (!options.useGraphics) editorArgs.push("-nographics");
+  if (options.testCategories?.length) editorArgs.push("-testCategory", options.testCategories.join(";"));
+  if (options.reportPaths?.log) editorArgs.push("-logFile", options.reportPaths.log);
+  if (editorArgs.length > 0) args.push("--", ...editorArgs);
+  return { command: resolveUnityCliCommand(options), args };
+}
+
 export function createUnityCliRunCommand(projectRoot: string, extraEditorArgs: string[] = [], options: UnityCliLaunchOptions = {}): UnityCliCommand {
   const args = [...unityCliBaseArgs(), "run", projectRoot];
   const forwardedArgs = normalizeUnityCliForwardedArgs(applyDefaultUnityBatchmodeArgs(extraEditorArgs, { useGraphics: options.useGraphics }));

package/src/unity-pipeline.ts

@@ -11,7 +11,7 @@ export const UNITY_PIPELINE_MAX_DIAGNOSTICS = 8;
 export const UNITY_PIPELINE_MAX_STACK_CHARS = 600;
 
 export type UnityPipelineCompileRequest = { projectRoot: string; unityVersion: string; timeoutSeconds?: number; allowAutonomousExitPlayMode?: boolean };
-export type UnityPipelineTestRequest = { projectRoot: string; unityVersion: string; testPlatform: "EditMode" | "PlayMode"; testFilter?: string; timeoutSeconds?: number; allowAutonomousExitPlayMode?: boolean };
+export type UnityPipelineTestRequest = { projectRoot: string; unityVersion: string; testPlatform: "EditMode" | "PlayMode"; testFilter?: string; testCategory?: string; timeoutSeconds?: number; allowAutonomousExitPlayMode?: boolean };
 export type UnityPipelineProgress = (message: string) => void;
 /** Unity's EditorSettings.ScriptChangesWhilePlaying values when a future editor_status payload supplies one. */
 export type UnityScriptChangesWhilePlayingPolicy = "recompile_and_continue" | "stop_and_recompile" | "defer" | "unknown";
@@ -32,7 +32,9 @@ export type UnityPipelineOperationDetails = {
   testFilter?: string;
   counts?: { total: number; passed?: number; failed: number; inconclusive?: number };
 };
-export type UnityPipelineOperationResult = { text: string; details: UnityPipelineOperationDetails };
+export type UnityPipelineTestRecord = { name: string; status: string; durationSeconds?: number; message?: string; stackTrace?: string };
+/** testRecords are terminal evidence for the caller's durable artifact only; do not expose them in tool details. */
+export type UnityPipelineOperationResult = { text: string; details: UnityPipelineOperationDetails; testRecords?: UnityPipelineTestRecord[] };
 
 type RecordValue = Record<string, unknown>;
 type ParsedEnvelope = { result: RecordValue; outerSuccess: boolean; malformed?: string };
@@ -41,6 +43,7 @@ type NormalizedTest = {
   state: "inactive" | "starting" | "running" | "completed" | "failed" | "cancelled" | "uncertain";
   total?: number; passed?: number; failed?: number; inconclusive?: number; failures: string[];
   correlation: Record<string, string>;
+  testRecords?: UnityPipelineTestRecord[];
 };
 
 type PipelineDependencies = {
@@ -145,6 +148,17 @@ function diagnostics(result: RecordValue): string[] {
   });
   return [...new Set(values)].slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS);
 }
+/** True only for Pipeline 0.5's explicit rejected outer envelope, before a main-thread command is dispatched. */
+export function isUnityPipelineInitialSettlingBusy(output: string): boolean {
+  let outer: RecordValue | undefined;
+  try { outer = record(JSON.parse(output)); } catch { return false; }
+  const data = record(outer?.data);
+  return outer?.success === false
+    && string(field(data ?? {}, "error"))?.toLowerCase() === "server busy"
+    && statusOf(data ?? {}) === "busy"
+    && field(data ?? {}, "retryable") === true;
+}
+
 export function normalizeUnityPipelineCompile(output: string): NormalizedCompile {
   const parsed = parseUnityPipelineEnvelope(output);
   if (parsed.malformed) return { state: "uncertain", diagnostics: [], failed: false };
@@ -161,6 +175,24 @@ function summary(result: RecordValue): RecordValue | undefined {
   walk(result, item => { if (!found && record(field(item, "summary"))) found = record(field(item, "summary")); });
   return found;
 }
+function testRecords(result: RecordValue): UnityPipelineTestRecord[] {
+  const values: UnityPipelineTestRecord[] = [];
+  walk(result, item => {
+    for (const key of ["tests", "results", "testresults"]) {
+      const entries = field(item, key);
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries.slice(0, 2_000)) {
+        const test = record(entry); if (!test) continue;
+        const name = string(field(test, "name", "fullname", "testname"));
+        const status = string(field(test, "result", "status", "outcome"));
+        if (!name || !status) continue;
+        const durationSeconds = number(field(test, "duration", "durationseconds", "time"));
+        values.push({ name: bounded(name, 1_000), status: bounded(status, 100), ...(durationSeconds === undefined ? {} : { durationSeconds }), ...(string(field(test, "message", "error", "failuremessage")) ? { message: bounded(string(field(test, "message", "error", "failuremessage"))!, 4_000) } : {}), ...(string(field(test, "stacktrace", "stack", "trace")) ? { stackTrace: bounded(string(field(test, "stacktrace", "stack", "trace"))!, 8_000) } : {}) });
+      }
+    }
+  });
+  return values.slice(0, 2_000);
+}
 function testFailures(result: RecordValue): string[] {
   const values: string[] = [];
   walk(result, item => {
@@ -212,7 +244,7 @@ export function normalizeUnityPipelineTest(output: string): NormalizedTest {
     : raw === "no_tests" || raw === "idle" || raw === "not_started" || raw === "not_running" ? "inactive"
       : raw === "running" ? "running" : raw === "starting" || raw === "queued" ? "starting"
         : raw === "completed" || raw === "complete" || raw === "success" ? "completed" : "uncertain";
-  return { state, total, passed, failed: failedCount, inconclusive, failures: testFailures(parsed.result), correlation: correlation(parsed.result) };
+  return { state, total, passed, failed: failedCount, inconclusive, failures: testFailures(parsed.result), correlation: correlation(parsed.result), testRecords: testRecords(parsed.result) };
 }
 
 function editorStopSucceeded(output: string): boolean {
@@ -316,6 +348,19 @@ async function executeCommand(deps: PipelineDependencies, projectRoot: string, c
   if (deadline !== undefined) ensureBeforeDeadline(deadline, now, command);
   return result;
 }
+async function dispatchMainThreadCommand(deps: PipelineDependencies, projectRoot: string, command: "recompile" | "run_tests", args: string[], operation: string, signal: AbortSignal | undefined, deadline: number, now: () => number, sleep: (milliseconds: number, signal?: AbortSignal) => Promise<void>): Promise<UnityCliExecResult> {
+  for (let attempt = 0; ; attempt += 1) {
+    const response = await executeCommand(deps, projectRoot, command, args, signal, deadline, now);
+    if (!isUnityPipelineInitialSettlingBusy(response.stdout)) return response;
+    const remaining = deadline - now();
+    if (remaining <= 0) throw new Error(`Unity Pipeline server remained busy while settling; ${operation} was not started before the deadline.`);
+    const delay = Math.min(UNITY_PIPELINE_BACKOFF_SECONDS[Math.min(attempt, UNITY_PIPELINE_BACKOFF_SECONDS.length - 1)]! * 1000, remaining);
+    await sleep(delay, signal);
+    throwIfAborted(signal);
+    if (now() >= deadline) throw new Error(`Unity Pipeline server remained busy while settling; ${operation} was not started before the deadline.`);
+  }
+}
+
 async function requirePreflight(deps: PipelineDependencies, projectRoot: string, unityVersion: string, commands: string[], operation: "recompile" | "tests", signal: AbortSignal | undefined, deadline: number, now: () => number, allowAutonomousExitPlayMode = true): Promise<{ capabilities: UnityCliProjectCapabilities; exitedPlayMode: boolean; playModeHandling: UnityPipelinePlayModeHandling; scriptChangesWhilePlaying?: UnityScriptChangesWhilePlayingPolicy }> {
   const capabilities = await inspectWithDeadline(deps, projectRoot, unityVersion, signal, deadline, now, "preflight");
   const error = capabilityError(capabilities, commands); if (error) throw new Error(error);
@@ -404,7 +449,7 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
   const lifecyclePrefix = playModeOutcomeText(preflight);
   ensureBeforeDeadline(deadline, now, "recompile before dispatch");
   throwIfAborted(signal);
-  const dispatched = await executeCommand(deps, projectRoot, "recompile", [], signal, deadline, now);
+  const dispatched = await dispatchMainThreadCommand(deps, projectRoot, "recompile", [], "recompile", signal, deadline, now, sleep);
   if (dispatched.error) throw new Error("Unity Pipeline recompile dispatch failed; operation may not have started.");
   let state = normalizeUnityPipelineCompile(dispatched.stdout);
   if (state.state === "uncertain") throw new Error("Unity Pipeline recompile dispatch returned malformed or uncertain evidence; operation may have started.");
@@ -421,6 +466,7 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
     if (identityState === "temporary_disconnect") continue;
     const response = await executeCommand(deps, projectRoot, "recompile_status", [], signal, deadline, now);
     if (response.error) continue; // Domain reload can briefly disconnect the same exact copy.
+    if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
     state = normalizeUnityPipelineCompile(response.stdout);
     if (state.state === "failed") throw new Error(`Unity recompile failed: ${state.diagnostics.join("; ") || "compiler failure reported"}`);
     if (state.state === "completed" || state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity recompile completed for ${projectRoot} in ${elapsed(start, now).toFixed(1)}s; 0 compiler errors.`,  details: { projectRoot, operation: "recompile", terminalState: state.state, elapsedSeconds: elapsed(start, now), compilationTriggered: true, ...playModeDetails(preflight) } };
@@ -446,9 +492,12 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     const observed = statusOf(parseUnityPipelineEnvelope(before.stdout).result) ?? "unknown";
     throw new Error(`Unity Pipeline returned unsupported preflight test status '${bounded(observed, 80)}'; test run not started.`);
   }
-  const args = ["--mode", request.testPlatform === "EditMode" ? "editor" : "playmode", ...(request.testFilter ? ["--filter", request.testFilter, "--filter_type", "testName"] : []), "--async_tests", "true"];
+  if (request.testFilter && request.testCategory) throw new Error("Connected Pipeline cannot combine a test-name filter and category in one run; operation not started.");
+  const selectorArgs = request.testFilter ? ["--filter", request.testFilter, "--filter_type", "testName"]
+    : request.testCategory ? ["--filter", request.testCategory, "--filter_type", "category"] : [];
+  const args = ["--mode", request.testPlatform === "EditMode" ? "editor" : "playmode", ...selectorArgs, "--async_tests", "true"];
   ensureBeforeDeadline(deadline, now, "tests before dispatch"); throwIfAborted(signal);
-  const dispatched = await executeCommand(deps, projectRoot, "run_tests", args, signal, deadline, now);
+  const dispatched = await dispatchMainThreadCommand(deps, projectRoot, "run_tests", args, "tests", signal, deadline, now, sleep);
   if (dispatched.error) throw new Error("Unity Pipeline test dispatch failed; test run may not have started.");
   let state = normalizeUnityPipelineTest(dispatched.stdout);
   if (state.state === "uncertain" || state.state === "inactive") throw new Error("Unity Pipeline test dispatch returned inactive, malformed, or uncertain evidence; test run may not have started.");
@@ -460,7 +509,7 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
   if (state.state === "completed") {
     const counts = passingCounts(state);
     if (!counts) throw new Error("Unity test result is terminal but lacks passing evidence (consistent positive total, passed count, and reported zero failures).");
-    return { text: `${lifecyclePrefix}Unity ${request.testPlatform} tests passed for ${projectRoot}: ${counts.total} executed, ${counts.passed} passed, 0 failed in ${elapsed(start, now).toFixed(2)}s.`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter, counts } };
+    return { text: `${lifecyclePrefix}Unity ${request.testPlatform} tests passed for ${projectRoot}: ${counts.total} executed, ${counts.passed} passed, 0 failed in ${elapsed(start, now).toFixed(2)}s.`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter ?? request.testCategory, counts }, testRecords: state.testRecords };
   }
   for (let poll = 0; now() < deadline; poll += 1) {
     options.onUpdate?.(`Unity ${request.testPlatform} tests ${state.state}; ${elapsed(start, now).toFixed(1)}s elapsed.`);
@@ -473,6 +522,7 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     if (identityState === "temporary_disconnect") continue;
     const response = await executeCommand(deps, projectRoot, "test_status", [], signal, deadline, now);
     if (response.error) continue;
+    if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
     state = normalizeUnityPipelineTest(response.stdout);
     if (!checkCorrelation(expected, state.correlation)) throw new Error("Unity Pipeline test status was displaced by a different run; operation state is uncertain.");
     if (state.state === "failed" || state.state === "cancelled") throw new Error(`Unity ${request.testPlatform} tests failed: ${state.failures.join("; ") || state.state}.`);
@@ -481,7 +531,7 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     if (state.state !== "completed") continue;
     const counts = passingCounts(state);
     if (!counts) throw new Error("Unity test result is terminal but lacks passing evidence (consistent positive total, passed count, and reported zero failures).");
-    return { text: `${lifecyclePrefix}Unity ${request.testPlatform} tests passed for ${projectRoot}: ${counts.total} executed, ${counts.passed} passed, 0 failed in ${elapsed(start, now).toFixed(2)}s.`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter, counts } };
+    return { text: `${lifecyclePrefix}Unity ${request.testPlatform} tests passed for ${projectRoot}: ${counts.total} executed, ${counts.passed} passed, 0 failed in ${elapsed(start, now).toFixed(2)}s.`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter ?? request.testCategory, counts }, testRecords: state.testRecords };
   }
   throw timeoutMessage("tests");
 }

package/src/unity-test-batch.ts

@@ -18,6 +18,7 @@ export type UnityTestBatchPlan = {
   testFilters: string[];
   testCategories: string[];
   testResultsPath: string;
+  junitResultsPath: string;
   logFilePath: string;
   args: string[];
 };
@@ -59,6 +60,7 @@ export function createUnityTestBatchPlan(input: UnityTestBatchPlanInput): UnityT
   const platformSlug = input.testPlatform.toLowerCase();
   const basename = `unity-tests-${platformSlug}-${safeTimestamp(input.now ?? new Date())}-${token}`;
   const testResultsPath = pathApi.join(logsRoot, `${basename}.xml`);
+  const junitResultsPath = pathApi.join(logsRoot, `${basename}.junit.xml`);
   const logFilePath = pathApi.join(logsRoot, `${basename}.log`);
   const args = ["-runTests", "-testPlatform", input.testPlatform];
   if (testFilters.length > 0) args.push("-testFilter", testFilters.join(";"));
@@ -78,5 +80,5 @@ export function createUnityTestBatchPlan(input: UnityTestBatchPlanInput): UnityT
     throw new Error("Unity test batch arguments must not contain -quit.");
   }
 
-  return { testPlatform: input.testPlatform, testFilters, testCategories, testResultsPath, logFilePath, args };
+  return { testPlatform: input.testPlatform, testFilters, testCategories, testResultsPath, junitResultsPath, logFilePath, args };
 }

package/src/unity-tests.ts

@@ -0,0 +1,272 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, link, rm, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+
+export const UNITY_TEST_RESULT_SCHEMA_VERSION = 1;
+export const UNITY_TEST_MAX_MESSAGE_CHARS = 4_000;
+export const UNITY_TEST_MAX_STACK_CHARS = 8_000;
+export const UNITY_TEST_MAX_TESTS = 2_000;
+export const UNITY_TEST_MAX_ARTIFACT_BYTES = 2_000_000;
+
+export type UnityTestPlatform = "EditMode" | "PlayMode";
+export type UnityTestExecution = "auto" | "connected" | "isolated";
+export type UnityTestIsolatedLauncher = "auto" | "unity-cli" | "editor-executable";
+export type UnityTestReportFormat = "json" | "nunit" | "junit";
+export type NormalizedUnityTestOutcome = "passed" | "passed_with_flakes" | "tests_failed" | "empty_selection" | "run_error" | "timed_out" | "cancelled" | "uncertain";
+export type UnityTestSource = "pipeline" | "unity-cli" | "editor-executable";
+
+export type UnityRunTestsRequest = {
+  path?: string;
+  testPlatform: UnityTestPlatform;
+  testFilters?: string[];
+  testCategories?: string[];
+  execution?: UnityTestExecution;
+  isolatedLauncher?: UnityTestIsolatedLauncher;
+  retries?: number;
+  rerunFailed?: boolean;
+  shard?: string;
+  shardInventoryPath?: string;
+  reportFormats?: UnityTestReportFormat[];
+  coverage?: boolean;
+  coverageOptions?: string;
+  useGraphics?: boolean;
+  timeoutSeconds?: number;
+  closeBlockingUnityProcess?: boolean;
+};
+
+export type NormalizedUnityRunTestsRequest = Omit<Required<Pick<UnityRunTestsRequest, "testPlatform" | "execution" | "isolatedLauncher" | "retries" | "rerunFailed" | "coverage" | "useGraphics" | "closeBlockingUnityProcess">>, never> & {
+  path?: string;
+  testFilters: string[];
+  testCategories: string[];
+  shard?: string;
+  shardInventoryPath?: string;
+  reportFormats?: UnityTestReportFormat[];
+  coverageOptions?: string;
+  timeoutSeconds?: number;
+};
+
+export type NormalizedUnityTest = { name: string; status: string; durationSeconds?: number; message?: string; stackTrace?: string; attempts?: number };
+export type NormalizedUnityTestResult = {
+  schemaVersion: typeof UNITY_TEST_RESULT_SCHEMA_VERSION;
+  source: UnityTestSource;
+  projectRelativeId?: string;
+  platform: UnityTestPlatform;
+  selection: { testFilters: string[]; testCategories: string[] };
+  startedAt?: string;
+  completedAt?: string;
+  durationSeconds?: number;
+  outcome: NormalizedUnityTestOutcome;
+  summary: { total?: number; passed?: number; failed?: number; skipped?: number; inconclusive?: number };
+  tests: NormalizedUnityTest[];
+  flakyTests?: Array<{ name: string; attempts: number }>;
+  backendArtifacts?: Record<string, string>;
+};
+
+export type UnityTestRouteRequirements = { requiresIsolation: boolean; reasons: string[] };
+export type UnityTestOutcomeEvidence = {
+  cancelled?: boolean;
+  timedOut?: boolean;
+  uncertain?: boolean;
+  runError?: boolean;
+  intentionalEmptySelection?: boolean;
+  total?: number;
+  passed?: number;
+  failed?: number;
+  inconclusive?: number;
+  retryResolvedAllFailures?: boolean;
+};
+
+export type UnityCliRetrySummary = {
+  requested: number;
+  attempts: number;
+  passedFirstAttempt?: number;
+  flaky: Array<{ name: string; attempts: number }>;
+  failed: Array<{ name: string; attempts: number }>;
+};
+
+function selectors(values: string[] | undefined, label: string): string[] {
+  const result: string[] = []; const seen = new Set<string>();
+  for (const [index, raw] of (values ?? []).entries()) {
+    if (typeof raw !== "string") throw new Error(`${label}[${index}] must be a string.`);
+    const value = raw.trim();
+    if (!value || /[\0\r\n;]/.test(value)) throw new Error(`${label}[${index}] must be non-empty and contain no NUL, newlines, or semicolons.`);
+    if (!seen.has(value)) { seen.add(value); result.push(value); }
+  }
+  return result;
+}
+function optionalText(value: string | undefined, label: string): string | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (!normalized || /[\0\r\n]/.test(normalized)) throw new Error(`${label} must be non-empty and contain no NUL or newlines.`);
+  return normalized;
+}
+
+/** Validates public input without deciding a backend or launching Unity. */
+export function normalizeUnityRunTestsRequest(input: UnityRunTestsRequest): NormalizedUnityRunTestsRequest {
+  if (input.testPlatform !== "EditMode" && input.testPlatform !== "PlayMode") throw new Error("testPlatform must be EditMode or PlayMode.");
+  const execution = input.execution ?? "auto";
+  const isolatedLauncher = input.isolatedLauncher ?? "auto";
+  if (!["auto", "connected", "isolated"].includes(execution)) throw new Error("execution must be auto, connected, or isolated.");
+  if (!["auto", "unity-cli", "editor-executable"].includes(isolatedLauncher)) throw new Error("isolatedLauncher must be auto, unity-cli, or editor-executable.");
+  if (!Number.isInteger(input.retries ?? 0) || (input.retries ?? 0) < 0) throw new Error("retries must be a non-negative integer.");
+  if (input.timeoutSeconds !== undefined && (!Number.isFinite(input.timeoutSeconds) || input.timeoutSeconds <= 0)) throw new Error("timeoutSeconds must be a positive number.");
+  if (input.rerunFailed && input.shard) throw new Error("shard and rerunFailed cannot be combined.");
+  const formats = input.reportFormats?.map(value => value.toLowerCase() as UnityTestReportFormat);
+  if (formats && formats.some(value => !["json", "nunit", "junit"].includes(value))) throw new Error("reportFormats may contain only json, nunit, or junit.");
+  return {
+    path: optionalText(input.path, "path"), testPlatform: input.testPlatform, execution, isolatedLauncher,
+    testFilters: selectors(input.testFilters, "testFilters"), testCategories: selectors(input.testCategories, "testCategories"),
+    retries: input.retries ?? 0, rerunFailed: input.rerunFailed ?? false, shard: optionalText(input.shard, "shard"),
+    shardInventoryPath: optionalText(input.shardInventoryPath, "shardInventoryPath"),
+    reportFormats: formats ? [...new Set(formats)] : undefined, coverage: input.coverage ?? false,
+    coverageOptions: optionalText(input.coverageOptions, "coverageOptions"), useGraphics: input.useGraphics ?? false,
+    timeoutSeconds: input.timeoutSeconds, closeBlockingUnityProcess: input.closeBlockingUnityProcess ?? false,
+  };
+}
+
+export function deriveUnityCliEffectiveReportPath(basePath: string, options: { rerunFailed?: boolean; shard?: string }): string {
+  const extension = path.extname(basePath);
+  const stem = extension ? basePath.slice(0, -extension.length) : basePath;
+  if (options.rerunFailed) return `${stem}.rerun${extension || ".xml"}`;
+  if (options.shard) {
+    const match = /^(\d+)\/(\d+)$/.exec(options.shard);
+    if (!match) throw new Error("shard must use the N/M form.");
+    return `${stem}.shard-${match[1]}-of-${match[2]}${extension || ".xml"}`;
+  }
+  return basePath;
+}
+
+export function defaultUnityTestReportFormats(route: "connected" | "isolated"): UnityTestReportFormat[] {
+  return route === "isolated" ? ["json", "nunit"] : ["json"];
+}
+
+/** Identifies options Pipeline cannot faithfully perform in one connected run. */
+export function getUnityTestRouteRequirements(request: NormalizedUnityRunTestsRequest): UnityTestRouteRequirements {
+  const reasons: string[] = [];
+  if (request.testFilters.length > 1) reasons.push("multiple test filters require isolated execution");
+  if (request.testCategories.length > 1) reasons.push("multiple test categories require isolated execution");
+  if (request.testFilters.length > 0 && request.testCategories.length > 0) reasons.push("mixed test filters and categories require isolated execution");
+  if (request.retries > 0) reasons.push("retries require isolated execution");
+  if (request.rerunFailed) reasons.push("rerunFailed requires isolated execution");
+  if (request.shard) reasons.push("sharding requires isolated execution");
+  if (request.shardInventoryPath) reasons.push("shardInventoryPath requires isolated execution");
+  if (request.coverage || request.coverageOptions) reasons.push("coverage requires isolated execution");
+  if ((request.reportFormats ?? []).some(format => format !== "json")) reasons.push("requested XML reports require isolated execution");
+  return { requiresIsolation: reasons.length > 0, reasons };
+}
+
+function retryEntries(value: unknown): Array<{ name: string; attempts: number }> | null {
+  if (!Array.isArray(value)) return null;
+  const entries: Array<{ name: string; attempts: number }> = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object") return null;
+    const record = item as Record<string, unknown>;
+    const name = typeof record.test === "string" ? record.test.trim() : "";
+    const attempts = typeof record.attempts === "number" && Number.isInteger(record.attempts) && record.attempts > 0 ? record.attempts : 0;
+    if (!name || !attempts) return null;
+    entries.push({ name, attempts });
+  }
+  return entries;
+}
+
+/** Parses the stable beta.6 retry sidecar without trusting arbitrary fields. */
+export function parseUnityCliRetrySummary(value: unknown): UnityCliRetrySummary | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const requested = typeof record.requested === "number" && Number.isInteger(record.requested) && record.requested >= 0 ? record.requested : -1;
+  const attempts = typeof record.attempts === "number" && Number.isInteger(record.attempts) && record.attempts >= 1 ? record.attempts : 0;
+  const flaky = retryEntries(record.flaky);
+  const failed = retryEntries(record.failed);
+  if (requested < 0 || !attempts || !flaky || !failed) return null;
+  return { requested, attempts, ...(typeof record.passedFirstAttempt === "number" && record.passedFirstAttempt >= 0 ? { passedFirstAttempt: record.passedFirstAttempt } : {}), flaky, failed };
+}
+
+export function applyUnityCliRetrySummary(result: NormalizedUnityTestResult, retry: UnityCliRetrySummary): NormalizedUnityTestResult {
+  const flaky = new Map(retry.flaky.map(item => [item.name, item.attempts]));
+  const failed = new Map(retry.failed.map(item => [item.name, item.attempts]));
+  const tests = result.tests.map(test => flaky.has(test.name)
+    ? { ...test, status: "Passed", attempts: flaky.get(test.name) }
+    : failed.has(test.name) ? { ...test, attempts: failed.get(test.name) } : test);
+  const total = result.summary.total;
+  const finalFailed = retry.failed.length;
+  const passed = total === undefined ? result.summary.passed : Math.max(0, total - finalFailed - (result.summary.skipped ?? 0) - (result.summary.inconclusive ?? 0));
+  return { ...result, summary: { ...result.summary, passed, failed: finalFailed }, tests, ...(retry.flaky.length ? { flakyTests: retry.flaky } : {}), outcome: finalFailed > 0 ? "tests_failed" : retry.flaky.length > 0 ? "passed_with_flakes" : result.outcome };
+}
+
+/** Applies strict evidence precedence; successful transport alone is deliberately insufficient. */
+export function determineUnityTestOutcome(evidence: UnityTestOutcomeEvidence): NormalizedUnityTestOutcome {
+  if (evidence.cancelled) return "cancelled";
+  if (evidence.timedOut) return "timed_out";
+  if (evidence.uncertain) return "uncertain";
+  if (evidence.runError) return "run_error";
+  if (evidence.intentionalEmptySelection) return "empty_selection";
+  if ((evidence.failed ?? 0) > 0) return "tests_failed";
+  if (evidence.failed !== 0) return "uncertain";
+  const total = evidence.total;
+  const passed = evidence.passed;
+  if (!Number.isFinite(total) || total! <= 0 || !Number.isFinite(passed) || passed! < total!) return "uncertain";
+  if ((evidence.inconclusive ?? 0) > 0) return "uncertain";
+  return evidence.retryResolvedAllFailures ? "passed_with_flakes" : "passed";
+}
+
+function bound(value: string | undefined, limit: number): string | undefined {
+  if (!value) return undefined;
+  const clean = value.replace(/\0/g, "").trim();
+  return clean.length > limit ? `${clean.slice(0, limit - 1)}…` : clean;
+}
+function numberOrUndefined(value: unknown): number | undefined { return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined; }
+function projectRelative(value: string): string | undefined {
+  const clean = value.replace(/\\/g, "/").replace(/^\.\//, "");
+  return !clean || path.isAbsolute(clean) || /^[A-Za-z]:\//.test(clean) || clean.split("/").includes("..") ? undefined : clean;
+}
+
+/** Bounds and redacts the durable, backend-neutral evidence shape before serialization. */
+export function normalizeUnityTestResult(result: NormalizedUnityTestResult): NormalizedUnityTestResult {
+  const tests = result.tests.slice(0, UNITY_TEST_MAX_TESTS).map(test => ({
+    name: bound(test.name, 1_000) || "Unnamed test", status: bound(test.status, 100) || "unknown",
+    ...(numberOrUndefined(test.durationSeconds) === undefined ? {} : { durationSeconds: numberOrUndefined(test.durationSeconds) }),
+    ...(bound(test.message, UNITY_TEST_MAX_MESSAGE_CHARS) ? { message: bound(test.message, UNITY_TEST_MAX_MESSAGE_CHARS) } : {}),
+    ...(bound(test.stackTrace, UNITY_TEST_MAX_STACK_CHARS) ? { stackTrace: bound(test.stackTrace, UNITY_TEST_MAX_STACK_CHARS) } : {}),
+    ...(Number.isInteger(test.attempts) && test.attempts! > 0 ? { attempts: test.attempts } : {}),
+  }));
+  const artifacts = Object.fromEntries(Object.entries(result.backendArtifacts ?? {}).flatMap(([key, value]) => {
+    const safe = projectRelative(value); return safe ? [[bound(key, 100) || "artifact", safe]] : [];
+  }));
+  return { ...result, projectRelativeId: result.projectRelativeId ? projectRelative(result.projectRelativeId) : undefined,
+    selection: { testFilters: selectors(result.selection.testFilters, "selection.testFilters"), testCategories: selectors(result.selection.testCategories, "selection.testCategories") },
+    summary: Object.fromEntries(Object.entries(result.summary).flatMap(([key, value]) => numberOrUndefined(value) === undefined ? [] : [[key, numberOrUndefined(value)!]])),
+    tests, ...(result.flakyTests ? { flakyTests: result.flakyTests.slice(0, UNITY_TEST_MAX_TESTS).map(item => ({ name: bound(item.name, 1_000) || "Unnamed test", attempts: Math.max(1, Math.floor(item.attempts)) })) } : {}),
+    ...(Object.keys(artifacts).length ? { backendArtifacts: artifacts } : {}),
+  };
+}
+
+export function compactUnityTestSummary(result: NormalizedUnityTestResult): string {
+  const count = result.summary.total ?? result.tests.length;
+  switch (result.outcome) {
+    case "passed": return `Unity ${result.platform} tests passed: ${count} executed.`;
+    case "passed_with_flakes": return `Unity ${result.platform} tests passed with ${result.flakyTests?.length ?? 0} flaky test(s): ${count} executed.`;
+    case "empty_selection": return `Unity ${result.platform} test selection was empty; no Editor run was required.`;
+    case "tests_failed": return `Unity ${result.platform} tests failed: ${result.summary.failed ?? "unknown"} failed of ${count}.`;
+    default: return `Unity ${result.platform} test run ${result.outcome.replace(/_/g, " ")}.`;
+  }
+}
+
+export async function writeNormalizedUnityTestArtifact(projectRoot: string, result: NormalizedUnityTestResult, options: { now?: Date; token?: string } = {}): Promise<string> {
+  const normalized = normalizeUnityTestResult(result);
+  const stamp = (options.now ?? new Date()).toISOString().replace(/[-:.]/g, "");
+  const token = (options.token ?? randomUUID()).replace(/[^A-Za-z0-9]/g, "").slice(0, 32);
+  if (!token) throw new Error("Artifact token must contain an ASCII letter or digit.");
+  const logs = path.join(path.resolve(projectRoot), "Logs");
+  const fileName = `pi-unity-tests-${normalized.platform.toLowerCase()}-${stamp}-${token}.json`;
+  const destination = path.join(logs, fileName);
+  const temporary = path.join(logs, `.${fileName}.${randomUUID()}.tmp`);
+  const json = `${JSON.stringify(normalized)}\n`;
+  if (Buffer.byteLength(json) > UNITY_TEST_MAX_ARTIFACT_BYTES) throw new Error("Normalized Unity test artifact exceeds its size limit.");
+  await mkdir(logs, { recursive: true });
+  await writeFile(temporary, json, { encoding: "utf8", flag: "wx" });
+  try { await link(temporary, destination); } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("Refusing to overwrite an existing normalized Unity test artifact.");
+    throw error;
+  } finally { await rm(temporary, { force: true }); }
+  return path.relative(path.resolve(projectRoot), destination).replace(/\\/g, "/");
+}