@aefree/pi-unity 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.10.0",
+  "version": "0.12.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-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",
     "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,19 +40,19 @@ 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
 - reads `ProjectSettings/ProjectVersion.txt`
-- prefers the installed `unity run` CLI when available, falling back to OS-aware direct editor launch
+- treats installed `unity run` as authoritative when available: it receives the project path without `--editor-version` and reads the declared version itself, falling back only when Unity CLI is unavailable
 - uses OS-aware standard install probing
-- supports explicit `UNITY_EDITOR_PATH` / `unityEditorPath` overrides
+- resolves only exact project-version standard installation candidates when direct Editor fallback is required
 - strips direct-Editor flags managed by `unity run` (`-batchmode`, `-projectPath`, `-quit`) before forwarding args in Unity CLI mode
 - supports `launcher: "editor-executable"` when Unity CLI argument forwarding differs from direct Editor executable behavior
 - checks Unity CLI status and running Unity processes before launch
@@ -68,15 +68,15 @@ If a launch is blocked by a native Unity lockfile, call `unity_project_status` b
 
 ### 2. Get the Project's Unity Version
 
-If you are in direct CLI fallback mode, read `ProjectSettings/ProjectVersion.txt` in the Unity project root:
+Before direct Editor fallback, read `ProjectSettings/ProjectVersion.txt` in the Unity project root:
 
 ```
 m_EditorVersion: ####.#.#f#
 ```
 
-### 3. Find the Unity Executable
+### 3. Resolve the exact-version Unity Editor
 
-If you are in direct CLI fallback mode, check these locations based on platform and version:
+For direct Editor fallback, use only the standard locations constructed from the version declared in `ProjectVersion.txt`:
 
 **Windows:**
 ```
@@ -89,17 +89,16 @@ C:\UnityInstalls\<version>\Editor\Unity.exe
 ```
 /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity
 /Applications/Unity/<version>/Unity.app/Contents/MacOS/Unity
-/Applications/Unity*
 ```
 
-If not found, ask the user for their Unity install path.
+If the exact declared version is not found, do not use an arbitrary Editor path or a nearby version. Ask the user to install the declared version through their normal Unity installation workflow, or use Unity CLI after it can resolve that exact version.
 
 ### 4. Choose the execution route, then run tests
 
 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 +107,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`
@@ -124,12 +123,13 @@ After choosing the isolated route:
 - exclude graphics-required screenshot/visual-capture tests from no-graphics runs
 - prefer project test categories such as `RequiresGraphics` / `VisualCapture` when the project exposes them
 
-Direct CLI fallback templates:
+Unity CLI project-authoritative template:
 ```
 unity test "<ProjectPath>" --mode <EditMode|PlayMode> --filter "<Full.Test.Name>" --output "<ResultsPath>" -- -logFile "<LogPath>"
-"<UnityEditorPath>" -batchmode -nographics -projectPath "<ProjectPath>" -runTests -testPlatform <EditMode|PlayMode> -testFilter "<Full.Test.Name>" -testResults "<ResultsPath>" -logFile "<LogPath>"
 ```
 
+For direct Editor fallback, use `unity_launch_batchmode` with its project path and test parameters; it resolves only the declared project's exact-version standard candidates.
+
 Fallback parameters:
 - `-testPlatform`: `EditMode` or `PlayMode`
 - `-testFilter`: Full test name (e.g., `MyNamespace.MyTests.TestMethodName`)

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. The only automatic retry is Pipeline 0.5's explicit initial-settling `Server Busy` response for `unity_pipeline_recompile` or `unity_pipeline_run_tests`, which confirms that a main-thread command was rejected before dispatch.
+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; 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

@@ -13,8 +13,7 @@ export type UnityCliCommand = {
 };
 
 export type UnityCliLaunchOptions = {
-  editorVersion?: string;
-  editorPath?: string;
+  editorVersionOverride?: string;
   timeoutSeconds?: number;
   cliCommand?: string;
   useGraphics?: boolean;
@@ -22,6 +21,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;
@@ -71,11 +83,8 @@ function unityCliBaseArgs(): string[] {
 }
 
 function appendUnityCliEditorOptions(args: string[], options: UnityCliLaunchOptions): void {
-  if (options.editorVersion?.trim()) {
-    args.push("--editor-version", options.editorVersion.trim());
-  }
-  if (options.editorPath?.trim()) {
-    args.push("--editor-path", options.editorPath.trim());
+  if (options.editorVersionOverride?.trim()) {
+    args.push("--editor-version", options.editorVersionOverride.trim());
   }
 }
 
@@ -116,6 +125,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-core.ts

@@ -27,14 +27,6 @@ export function parseUnityVersionText(contents: string): string | null {
   return match ? match[1] : null;
 }
 
-export function normalizeUnityEditorOverride(editorPath: string, platform: SupportedPlatform): string {
-  const normalized = path.normalize(editorPath.trim());
-  if (platform === "darwin" && normalized.toLowerCase().endsWith(".app")) {
-    return path.join(normalized, "Contents", "MacOS", "Unity");
-  }
-  return normalized;
-}
-
 export function buildUnityEditorCandidates(
   version: string,
   platform: SupportedPlatform = process.platform,

package/src/unity-editor-fallback.ts

@@ -0,0 +1,36 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  buildUnityBatchmodeArgs,
+  buildUnityEditorCandidates,
+  buildUnityOpenEditorArgs,
+  type SupportedPlatform,
+  type UnityOpenEditorArgsOptions,
+} from "./unity-core";
+
+/** Direct-executable compatibility fallback. Unity CLI routes must not import this module. */
+export async function resolveUnityEditorPath(
+  unityVersion: string,
+  options: { platform?: SupportedPlatform; homeDir?: string; access?: (candidate: string) => Promise<void> } = {},
+): Promise<string> {
+  const autoCandidates = buildUnityEditorCandidates(unityVersion, options.platform ?? process.platform, options.homeDir);
+  const access = options.access ?? ((candidate: string) => fs.access(candidate, fs.constants.X_OK));
+  for (const candidate of autoCandidates) {
+    try { await access(candidate); return path.normalize(candidate); } catch { /* Try next exact-version candidate. */ }
+  }
+  throw new Error(`Could not find a Unity Editor executable for Unity ${unityVersion}. Install that exact Editor version through your normal Unity installation workflow, or install Unity CLI so it can resolve the project version.`);
+}
+
+export function launchUnityEditorDetached(editorPath: string, projectRoot: string, options: UnityOpenEditorArgsOptions = {}): { pid: number | undefined; args: string[]; command: string } {
+  const args = buildUnityOpenEditorArgs(projectRoot, options);
+  const child = (awaitableSpawn)(editorPath, args, { detached: true, stdio: "ignore", windowsHide: false });
+  child.unref();
+  return { pid: child.pid, args, command: editorPath };
+}
+
+// Kept local so this module owns direct process creation entirely.
+import { spawn as awaitableSpawn } from "node:child_process";
+
+export function createUnityBatchmodeCommand(editorPath: string, projectRoot: string, extraArgs: string[] = [], options: { useGraphics?: boolean } = {}): { command: string; args: string[] } {
+  return { command: editorPath, args: buildUnityBatchmodeArgs(projectRoot, extraArgs, options) };
+}

package/src/unity-launch.ts

@@ -1,90 +1,10 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
 import { spawn } from "node:child_process";
-import {
-  buildUnityBatchmodeArgs,
-  buildUnityEditorCandidates,
-  buildUnityOpenEditorArgs,
-  normalizeUnityEditorOverride,
-  type SupportedPlatform,
-  type UnityOpenEditorArgsOptions,
-} from "./unity-core";
 import { createUnityCliOpenCommand, type UnityCliLaunchOptions } from "./unity-cli";
 
-export async function resolveUnityEditorPath(
-  unityVersion: string,
-  options: {
-    overridePath?: string;
-    env?: NodeJS.ProcessEnv;
-    platform?: SupportedPlatform;
-    homeDir?: string;
-  } = {},
-): Promise<string> {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const homeDir = options.homeDir;
-
-  const overrideCandidates = [options.overridePath, env.UNITY_EDITOR_PATH, env.UNITY_PATH]
-    .map((value) => value?.trim())
-    .filter((value): value is string => Boolean(value))
-    .map((value) => normalizeUnityEditorOverride(value, platform));
-
-  const autoCandidates = buildUnityEditorCandidates(unityVersion, platform, homeDir);
-
-  for (const candidate of [...overrideCandidates, ...autoCandidates]) {
-    try {
-      await fs.access(candidate, fs.constants.X_OK);
-      return path.normalize(candidate);
-    } catch {
-      // Try next candidate.
-    }
-  }
-
-  throw new Error(
-    [
-      `Could not find a Unity Editor executable for Unity ${unityVersion}.`,
-      "Set UNITY_EDITOR_PATH to an explicit executable path or pass unityEditorPath.",
-    ].join(" "),
-  );
-}
-
-export function launchUnityEditorDetached(
-  editorPath: string,
-  projectRoot: string,
-  options: UnityOpenEditorArgsOptions = {},
-): { pid: number | undefined; args: string[]; command: string } {
-  const args = buildUnityOpenEditorArgs(projectRoot, options);
-  const child = spawn(editorPath, args, {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: false,
-  });
-  child.unref();
-  return { pid: child.pid, args, command: editorPath };
-}
-
-export function launchUnityCliOpenDetached(
-  projectRoot: string,
-  options: UnityCliLaunchOptions = {},
-): { pid: number | undefined; args: string[]; command: string } {
+/** Unity CLI GUI launch path. Direct executable fallback lives in unity-editor-fallback.ts. */
+export function launchUnityCliOpenDetached(projectRoot: string, options: UnityCliLaunchOptions = {}): { pid: number | undefined; args: string[]; command: string } {
   const cli = createUnityCliOpenCommand(projectRoot, options);
-  const child = spawn(cli.command, cli.args, {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: false,
-  });
+  const child = spawn(cli.command, cli.args, { detached: true, stdio: "ignore", windowsHide: false });
   child.unref();
   return { pid: child.pid, args: cli.args, command: cli.command };
 }
-
-export function createUnityBatchmodeCommand(
-  editorPath: string,
-  projectRoot: string,
-  extraArgs: string[] = [],
-  options: { useGraphics?: boolean } = {},
-): { command: string; args: string[] } {
-  return {
-    command: editorPath,
-    args: buildUnityBatchmodeArgs(projectRoot, extraArgs, options),
-  };
-}

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 = {
@@ -172,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 => {
@@ -223,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 {
@@ -471,7 +492,10 @@ 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 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.");
@@ -485,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.`);
@@ -507,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-projects.ts

@@ -5,7 +5,8 @@ import { parseUnityVersionText, resolveAbsolutePath } from "./unity-core";
 export type UnityProjectCandidate = {
   projectRoot: string;
   projectName: string;
-  unityVersion: string;
+  /** Manual ProjectVersion.txt evidence, loaded only by direct/Pipeline routes. */
+  unityVersion?: string;
 };
 
 export type UnityProjectDiscoveryResult = {
@@ -81,7 +82,6 @@ export async function findAncestorUnityProject(startDir: string): Promise<UnityP
       return {
         projectRoot: current,
         projectName: path.basename(current),
-        unityVersion: await readUnityVersion(current),
       };
     }
 
@@ -123,7 +123,6 @@ export async function discoverUnityProjects(
       candidates.push({
         projectRoot: next.dir,
         projectName: path.basename(next.dir),
-        unityVersion: await readUnityVersion(next.dir),
       });
       if (candidates.length >= maxCandidates) {
         truncated = true;

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 };
 }