@aefree/pi-unity 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## 0.12.0 - 2026-08-27
+
+### Changed
+- Made Unity CLI authoritative for ordinary project launches: `open`, `run`, and `test` now rely on the selected project without passing an Editor-version override; direct executable launch remains an exact-version fallback.
+
+### Fixed
+
+- Kept isolated Unity CLI test results discoverable for JSON-only reports by always writing the native NUnit evidence to the project's `Logs` directory.
+- Made direct Unity Editor fallback selection project-version-driven by probing only exact-version standard installations without Editor-path overrides.
+
+### Removed
+
+- Removed the `UNITY_EDITOR_PATH`, `UNITY_PATH`, and `unityEditorPath` Editor-selection overrides.
+
 ## [0.11.0] - 2026-08-26
 
 ### Added

package/README.md

@@ -23,7 +23,7 @@ pi install <path-to-pi-unity>
 pi install -l <path-to-pi-unity> # project-local
 ```
 
-Pi discovers the extension from `index.ts` and packaged skills from `skills/`.
+Pi discovers the extension from `index.ts` and packaged skills from `skills/`. In UI sessions, pi-unity warns once per Pi runtime when Unity CLI is unavailable or `UNITY_CLI_PATH` is invalid. The warning never displays configured paths; install Unity CLI, then restart or reload Pi.
 
 ## Included tools
 
@@ -113,7 +113,7 @@ Use `unity_pipeline_inspect` when a purpose-built structured command fits. Use e
 
 ## Launch and process safeguards
 
-`unity_open_editor` and batchmode tools prefer the installed Unity CLI and can fall back to the direct Editor executable. Set `launcher` to `auto`, `unity-cli`, or `editor-executable` when explicit routing is needed.
+`unity_open_editor` and batchmode tools treat Unity CLI as the authoritative launcher: `unity open`, `unity run`, and `unity test` receive only the selected project and let Unity CLI read `ProjectVersion.txt`. The direct Editor executable is an exceptional compatibility fallback used only when Unity CLI is unavailable. Set `launcher` to `auto`, `unity-cli`, or `editor-executable` when explicit routing is needed.
 
 Before launching, pi-unity checks:
 

package/index.ts

@@ -21,13 +21,14 @@ import {
 } from "./src/unity-batchmode";
 import { formatPathForUser, hasUnityCommandLineFlag } from "./src/unity-core";
 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 { launchUnityCliOpenDetached } from "./src/unity-launch";
+import { createUnityBatchmodeCommand, launchUnityEditorDetached, resolveUnityEditorPath } from "./src/unity-editor-fallback";
 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 { readUnityVersion, 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 { applyUnityCliRetrySummary, compactUnityTestSummary, defaultUnityTestReportFormats, deriveUnityCliEffectiveReportPath, determineUnityTestOutcome, getUnityTestRouteRequirements, normalizeUnityRunTestsRequest, parseUnityCliRetrySummary, resolveUnityCliBackendReportPaths, 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 {
@@ -103,20 +104,19 @@ type UnityLauncherPreference = "auto" | "unity-cli" | "editor-executable";
 
 const OPEN_EDITOR_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." })),
   automated: Type.Optional(Type.Boolean({ default: false, description: "Pass Unity Editor's -automated flag when opening the project. Defaults to false." })),
   launcher: LAUNCHER_SCHEMA,
-});
+}, { additionalProperties: false });
 
 const LAUNCH_BATCHMODE_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." })),
+
   args: Type.Optional(Type.Array(Type.String(), { description: "Additional Unity command-line arguments appended after -batchmode -projectPath <project> for direct editor launch, or forwarded after `unity run <project> --` for Unity CLI launch. pi-unity adds -nographics by default unless useGraphics=true." })),
   useGraphics: Type.Optional(Type.Boolean({ default: false, description: "Set true only when the requested Unity batchmode work requires an active graphics device, such as screenshots, rendering, or visual PlayMode tests. Defaults to false, which adds -nographics." })),
   timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 14400, default: 3600, description: "Timeout in seconds for the batchmode process." })),
   launcher: LAUNCHER_SCHEMA,
   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." })),
-});
+}, { additionalProperties: false });
 
 const RUN_TESTS_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
@@ -137,18 +137,6 @@ const RUN_TESTS_PARAMS = Type.Object({
   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." })),
-  testPlatform: StringEnum(["EditMode", "PlayMode"] as const, { description: "Unity Test Framework platform. One batch runs exactly one test platform." }),
-  testFilters: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "Full test names or regex filters. Values are normalized into one semicolon-separated -testFilter argument." })),
-  testCategories: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "Categories or category regex/negations. Values are normalized into one semicolon-separated -testCategory argument." })),
-  useGraphics: Type.Optional(Type.Boolean({ default: false, description: "Set true only for graphics-dependent PlayMode tests or visual capture. Defaults to headless -nographics." })),
-  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 14400, default: 3600 })),
-  launcher: LAUNCHER_SCHEMA,
-  closeBlockingUnityProcess: Type.Optional(Type.Boolean({ default: false, description: "Use guarded same-project Unity process closure only when piUnity.allowCloseRunningUnityProcess is enabled." })),
-});
-
 const PROJECT_STATUS_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
 });
@@ -196,7 +184,7 @@ const INSPECT_ARTIFACTS_PARAMS = Type.Object({
 });
 
 function buildProjectChoiceLabel(cwd: string, candidate: UnityProjectCandidate): string {
-  return `${candidate.projectName} (${candidate.unityVersion}) — ${formatPathForUser(cwd, candidate.projectRoot)}`;
+  return `${candidate.projectName} — ${formatPathForUser(cwd, candidate.projectRoot)}`;
 }
 
 async function chooseProjectCandidateWithWrappingNavigation(
@@ -267,7 +255,7 @@ async function chooseProjectCandidateWithWrappingNavigation(
 
 function formatCandidateList(cwd: string, candidates: UnityProjectCandidate[]): string {
   return candidates
-    .map((candidate) => `- ${candidate.projectName} (${candidate.unityVersion}) — ${formatPathForUser(cwd, candidate.projectRoot)}`)
+    .map((candidate) => `- ${candidate.projectName} — ${formatPathForUser(cwd, candidate.projectRoot)}`)
     .join("\n");
 }
 
@@ -331,6 +319,13 @@ async function resolveProjectCandidate(
   return { candidate, discoveryWarning };
 }
 
+async function requireManualUnityVersion(candidate: UnityProjectCandidate): Promise<string> {
+  if (candidate.unityVersion) return candidate.unityVersion;
+  const unityVersion = await readUnityVersion(candidate.projectRoot);
+  candidate.unityVersion = unityVersion;
+  return unityVersion;
+}
+
 function joinWarnings(...warnings: Array<string | undefined>): string | undefined {
   const present = warnings.filter((warning): warning is string => Boolean(warning && warning.trim().length > 0));
   return present.length > 0 ? present.join("\n") : undefined;
@@ -446,11 +441,12 @@ async function closeBlockingUnityProcessesForBatchmode(
     );
   }
 
-  const cliCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, candidate.unityVersion, { signal });
+  const unityVersion = await requireManualUnityVersion(candidate);
+  const cliCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, unityVersion, { signal });
   const canRequestGracefulExit = cliCapabilities.commandDiscoverySucceeded && cliCapabilities.advertisedCommands.includes("eval");
   if (canRequestGracefulExit) {
     const refreshedRunning = await listBlockingUnityProcesses(candidate.projectRoot);
-    const refreshedCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, candidate.unityVersion, { signal });
+    const refreshedCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, unityVersion, { signal });
     const samePids = haveSameKnownProcessIds(running.processes, refreshedRunning.processes);
     const samePipelinePids = haveSameKnownProcessIds(cliCapabilities.matchingInstances, refreshedCapabilities.matchingInstances);
     if (refreshedRunning.warning || !samePids || !samePipelinePids || !refreshedCapabilities.advertisedCommands.includes("eval")) {
@@ -599,7 +595,8 @@ async function buildProjectStatusReport(
   const lockState = await inspectUnityProjectBusyState(candidate.projectRoot);
   const cliStatus = await listRunningUnityCliEditorsForProject(candidate.projectRoot);
   const processStatus = await listRunningUnityProcessesForProject(candidate.projectRoot);
-  const cliCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, candidate.unityVersion, { signal });
+  const unityVersion = await requireManualUnityVersion(candidate);
+  const cliCapabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, unityVersion, { signal });
   const runningProcesses = dedupeRunningUnityProcesses([...cliStatus.processes, ...processStatus.processes]);
   const isBusy = runningProcesses.length > 0 || cliCapabilities.matchingInstances.length > 0;
   const staleLockSuspected = lockState.nativeLockfileExists && !isBusy && !processStatus.warning;
@@ -607,7 +604,7 @@ async function buildProjectStatusReport(
   const piUnitySettings = await loadPiUnitySettings(ctx);
 
   const lines = [
-    `Unity project status for ${formatPathForUser(ctx.cwd, candidate.projectRoot)} using Unity ${candidate.unityVersion}.`,
+    `Unity project status for ${formatPathForUser(ctx.cwd, candidate.projectRoot)} using declared Unity ${unityVersion}.`,
     `- Native lockfile: ${lockState.nativeLockfileExists ? "present" : "absent"}`,
     `- Lockfile path: ${lockState.nativeLockfilePath}`,
     `- Running Unity processes targeting project: ${runningProcesses.length}`,
@@ -656,7 +653,7 @@ async function buildProjectStatusReport(
     details: {
       mode: "status",
       projectRoot: candidate.projectRoot,
-      unityVersion: candidate.unityVersion,
+      unityVersion: await requireManualUnityVersion(candidate),
       editorPath: "",
       warning: combinedWarning,
       status: "passed",
@@ -737,7 +734,7 @@ async function buildArtifactInspectionReport(
   const hasLoadedArtifacts = Boolean(artifacts.testResultsPath || artifacts.logFilePath);
   const status = deriveUnityArtifactInspectionStatus(hasLoadedArtifacts, invocation, parsedTestResults);
   const lines = [
-    `Unity artifacts inspected for ${formatPathForUser(ctx.cwd, candidate.projectRoot)} using Unity ${candidate.unityVersion}.`,
+    `Unity artifacts inspected for ${formatPathForUser(ctx.cwd, candidate.projectRoot)}; Unity CLI selects the project's declared Editor version when launching.`,
     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)",
@@ -764,7 +761,7 @@ async function buildArtifactInspectionReport(
     details: {
       mode: "artifacts",
       projectRoot: candidate.projectRoot,
-      unityVersion: candidate.unityVersion,
+      unityVersion: await requireManualUnityVersion(candidate),
       editorPath: "",
       invocation,
       artifacts: compactUnityArtifacts(artifacts),
@@ -782,7 +779,9 @@ function buildEditorLaunchSummary(
   launcher: "unity-cli" | "editor-executable" = "editor-executable",
 ): string {
   return [
-    `Launched Unity Editor GUI for ${formatPathForUser(cwd, candidate.projectRoot)} using Unity ${candidate.unityVersion}.`,
+    launcher === "unity-cli"
+      ? `Launched Unity Editor GUI for ${formatPathForUser(cwd, candidate.projectRoot)} with the project-declared Editor version selected by Unity CLI.`
+      : `Launched Unity Editor GUI for ${formatPathForUser(cwd, candidate.projectRoot)} using the project's declared Unity version through the direct Editor fallback.`,
     launcher === "unity-cli" ? `Launcher: unity open (${editorPath})` : `Editor: ${editorPath}`,
     GUI_WARNING,
     SINGLE_PROCESS_WARNING,
@@ -809,7 +808,7 @@ async function buildBatchmodeReport(
   const status = deriveUnityBatchmodeStatus(result.code, Boolean(result.killed), invocation, parsedTestResults);
   const text = buildUnityBatchmodeAgentText({
     displayProjectPath: formatPathForUser(ctx.cwd, candidate.projectRoot),
-    unityVersion: candidate.unityVersion,
+    unityVersion: await requireManualUnityVersion(candidate),
     editorPath,
     exitCode: result.code,
     killed: Boolean(result.killed),
@@ -827,7 +826,7 @@ async function buildBatchmodeReport(
     details: {
       mode: "batchmode",
       projectRoot: candidate.projectRoot,
-      unityVersion: candidate.unityVersion,
+      unityVersion: await requireManualUnityVersion(candidate),
       editorPath,
       command: editorPath,
       args,
@@ -936,16 +935,42 @@ function throwIfAborted(signal?: AbortSignal): void {
   }
 }
 
-async function canUseUnityCli(pi: ExtensionAPI, signal?: AbortSignal): Promise<boolean> {
+const UNITY_CLI_WARNING_SYMBOL = Symbol.for("@aefree/pi-unity/unity-cli-warning/v1");
+const unityCliRuntimeState = globalThis as Record<PropertyKey, unknown>;
+const UNITY_CLI_WARNING = "pi-unity capability warning: Unity CLI is unavailable or UNITY_CLI_PATH is invalid. Install Unity CLI, then restart or reload Pi to restore pi-unity's primary project-launch workflow.";
+
+async function warnWhenUnityCliUnavailable(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI || unityCliRuntimeState[UNITY_CLI_WARNING_SYMBOL] === true) return;
+  try {
+    const result = await pi.exec(resolveUnityCliCommand(), ["--version"], { timeout: 5000 });
+    // Timeouts are uncertain and must neither warn nor select another backend.
+    if (result.killed || result.code === 0 || unityCliRuntimeState[UNITY_CLI_WARNING_SYMBOL] === true) return;
+    unityCliRuntimeState[UNITY_CLI_WARNING_SYMBOL] = true;
+    ctx.ui.notify(UNITY_CLI_WARNING, "warning");
+  } catch (error) {
+    if ((error instanceof Error && error.name === "AbortError") || isUnityCliProbeTimeout(error)) return;
+    if (unityCliRuntimeState[UNITY_CLI_WARNING_SYMBOL] === true) return;
+    unityCliRuntimeState[UNITY_CLI_WARNING_SYMBOL] = true;
+    ctx.ui.notify(UNITY_CLI_WARNING, "warning");
+  }
+}
+type UnityCliAvailability = "available" | "unavailable" | "uncertain";
+
+function isUnityCliProbeTimeout(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ETIMEDOUT");
+}
+
+async function getUnityCliAvailability(pi: ExtensionAPI, signal?: AbortSignal): Promise<UnityCliAvailability> {
   try {
     throwIfAborted(signal);
     const command = resolveUnityCliCommand();
     const result = await pi.exec(command, ["--version"], { signal, timeout: 5000 });
     throwIfAborted(signal);
-    return !result.killed && result.code === 0;
+    if (result.killed) return "uncertain";
+    return result.code === 0 ? "available" : "unavailable";
   } catch (error) {
     if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) throw error;
-    return false;
+    return isUnityCliProbeTimeout(error) ? "uncertain" : "unavailable";
   }
 }
 
@@ -995,16 +1020,18 @@ async function shouldUseUnityCli(
     return false;
   }
 
-  const available = await canUseUnityCli(pi, signal);
-  if (preference === "unity-cli" && !available) {
+  const availability = await getUnityCliAvailability(pi, signal);
+  if (availability === "uncertain") {
+    throw new Error("Unity CLI availability could not be confirmed because its bounded probe timed out. Retry the request; pi-unity will not select the direct Editor fallback after an uncertain Unity CLI probe.");
+  }
+  if (preference === "unity-cli" && availability === "unavailable") {
     throw new Error("Unity CLI launcher was requested, but the `unity` command is not available. Set UNITY_CLI_PATH or use launcher='editor-executable'.");
   }
 
-  return available;
+  return availability === "available";
 }
 
 type GuardedBatchmodeParams = {
-  unityEditorPath?: string;
   args?: string[];
   useGraphics?: boolean;
   timeoutSeconds?: number;
@@ -1036,17 +1063,14 @@ async function runGuardedUnityBatchmode(
       const invocation = parseUnityBatchmodeInvocation(createUnityCliBatchmodeReportArgs(candidate.projectRoot, extraArgs, { useGraphics }));
       const useUnityCli = await shouldUseUnityCli(pi, params.launcher, signal);
       throwIfAborted(signal);
-      const editorPath = useUnityCli
-        ? await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath }).catch(() => "Unity CLI resolved editor")
-        : await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath });
-      const command = useUnityCli
-        ? createUnityCliRunCommand(candidate.projectRoot, extraArgs, {
-          editorVersion: candidate.unityVersion,
-          editorPath: params.unityEditorPath,
-          timeoutSeconds,
-          useGraphics,
-        })
-        : createUnityBatchmodeCommand(editorPath, candidate.projectRoot, extraArgs, { useGraphics });
+      let editorPath = "Unity CLI";
+      let command: { command: string; args: string[] };
+      if (useUnityCli) {
+        command = createUnityCliRunCommand(candidate.projectRoot, extraArgs, { timeoutSeconds, useGraphics });
+      } else {
+        editorPath = await resolveUnityEditorPath(await requireManualUnityVersion(candidate));
+        command = createUnityBatchmodeCommand(editorPath, candidate.projectRoot, extraArgs, { useGraphics });
+      }
       const closeReport = await closeBlockingUnityProcessesForBatchmode(
         pi,
         ctx,
@@ -1123,7 +1147,7 @@ async function runUnifiedUnityTests(
 ): 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 capabilities = await inspectUnityCliProjectCapabilities(candidate.projectRoot, await requireManualUnityVersion(candidate), { 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";
@@ -1144,7 +1168,7 @@ async function runUnifiedUnityTests(
   }
   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 result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), testPlatform: request.testPlatform, testFilter: request.testFilters[0], testCategory: request.testCategories[0], timeoutSeconds: request.timeoutSeconds, allowAutonomousExitPlayMode }, createPipelineDependencies(pi), { signal, onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }) });
     const counts = result.details.counts!;
     const normalized: NormalizedUnityTestResult = {
       schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
@@ -1153,11 +1177,11 @@ async function runUnifiedUnityTests(
     };
     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 } };
+    return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), 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);
+  const cliAvailable = await shouldUseUnityCli(pi, request.isolatedLauncher, 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) {
@@ -1173,7 +1197,7 @@ async function runUnifiedUnityTests(
     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 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: resolveUnityCliBackendReportPaths({ nunit: plan.testResultsPath, junit: plan.junitResultsPath, log: plan.logFilePath }, formats), coverage: request.coverage, coverageOptions: request.coverageOptions, useGraphics: request.useGraphics, timeoutSeconds: request.timeoutSeconds });
     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;
@@ -1197,7 +1221,7 @@ async function runUnifiedUnityTests(
     }
     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 } };
+    return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), 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 } };
   });
 }
 
@@ -1338,6 +1362,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     restoreSessionSettings(ctx);
+    await warnWhenUnityCliUnavailable(pi, ctx);
     const scope = ctx.sessionManager;
     unregisterScope(registrations.get(scope));
     // Optional package integrations resolve independently. The Unity extension and
@@ -1415,14 +1440,14 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         await withUnityProjectLaunchMutex(candidate.projectRoot, { mode: "gui", toolName: "unity-open" }, async () => {
           await enforceSingleProcessRule(candidate.projectRoot);
         let launcher: "unity-cli" | "editor-executable" = "editor-executable";
-        let editorPath = await resolveUnityEditorPath(candidate.unityVersion).catch(() => "Unity CLI resolved editor");
+        let editorPath = "Unity CLI";
         let launch: { pid: number | undefined; args: string[]; command: string };
-        if (await canUseUnityCli(pi)) {
+        if (await shouldUseUnityCli(pi, undefined)) {
           launcher = "unity-cli";
-          launch = launchUnityCliOpenDetached(candidate.projectRoot, { editorVersion: candidate.unityVersion });
+          launch = launchUnityCliOpenDetached(candidate.projectRoot);
         } else {
           await assertUnityProjectNotBusy(candidate.projectRoot);
-          editorPath = await resolveUnityEditorPath(candidate.unityVersion);
+          editorPath = await resolveUnityEditorPath(await requireManualUnityVersion(candidate));
           launch = launchUnityEditorDetached(editorPath, candidate.projectRoot);
         }
         const summary = buildEditorLaunchSummary(ctx.cwd, candidate, editorPath, discoveryWarning, launcher);
@@ -1549,13 +1574,13 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       throwIfAborted(signal);
       const { candidate } = await resolveProjectCandidate(ctx, params.path);
-      const result = await runUnityPipelineRecompile({ projectRoot: candidate.projectRoot, unityVersion: candidate.unityVersion, timeoutSeconds: params.timeoutSeconds, allowAutonomousExitPlayMode: sessionAllowsAutonomousPlayModeExit(ctx) }, createPipelineDependencies(pi), {
+      const result = await runUnityPipelineRecompile({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), timeoutSeconds: params.timeoutSeconds, allowAutonomousExitPlayMode: sessionAllowsAutonomousPlayModeExit(ctx) }, createPipelineDependencies(pi), {
         signal,
         onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }),
       });
       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,
+        details: { mode: "pipeline", projectRoot: result.details.projectRoot, unityVersion: await requireManualUnityVersion(candidate), editorPath: "", status: "passed", pipeline: result.details } satisfies UnityToolDetails,
       };
     },
     renderCall(args, theme, context) { return renderUnityPipelineCall("unity_pipeline_recompile", args, theme, context); },
@@ -1580,7 +1605,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       throwIfAborted(signal);
       const result = await dispatchUnityPlanningInspection({
         projectRoot: candidate.projectRoot,
-        unityVersion: candidate.unityVersion,
+        unityVersion: await requireManualUnityVersion(candidate),
         command: "eval",
         evalSnippet: params.code,
       }, {
@@ -1597,7 +1622,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         details: {
           mode: "pipeline_eval",
           projectRoot: candidate.projectRoot,
-          unityVersion: candidate.unityVersion,
+          unityVersion: await requireManualUnityVersion(candidate),
           editorPath: "",
           status: result.outcome === "dispatched" ? "passed" : "failed",
           pipelineEval: result,
@@ -1629,7 +1654,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       throwIfAborted(signal);
       const result = await dispatchUnityPlanningInspection({
         projectRoot: candidate.projectRoot,
-        unityVersion: candidate.unityVersion,
+        unityVersion: await requireManualUnityVersion(candidate),
         command: params.command,
         args: params.args,
       }, {
@@ -1646,7 +1671,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         details: {
           mode: "pipeline_inspection",
           projectRoot: candidate.projectRoot,
-          unityVersion: candidate.unityVersion,
+          unityVersion: await requireManualUnityVersion(candidate),
           editorPath: "",
           status: result.outcome === "dispatched" ? "passed" : "failed",
           pipelineInspection: result,
@@ -1715,18 +1740,14 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       const useUnityCli = await shouldUseUnityCli(pi, params.launcher as UnityLauncherPreference | undefined, signal);
       throwIfAborted(signal);
       let launcher: "unity-cli" | "editor-executable" = "editor-executable";
-      let editorPath = await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath }).catch(() => "Unity CLI resolved editor");
+      let editorPath = "Unity CLI";
       let launch: { pid: number | undefined; args: string[]; command: string };
       if (useUnityCli) {
         launcher = "unity-cli";
-        launch = launchUnityCliOpenDetached(candidate.projectRoot, {
-          editorVersion: candidate.unityVersion,
-          editorPath: params.unityEditorPath,
-          automated: params.automated,
-        });
+        launch = launchUnityCliOpenDetached(candidate.projectRoot, { automated: params.automated });
       } else {
         await assertUnityProjectNotBusy(candidate.projectRoot);
-        editorPath = await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath });
+        editorPath = await resolveUnityEditorPath(await requireManualUnityVersion(candidate));
         launch = launchUnityEditorDetached(editorPath, candidate.projectRoot, { automated: params.automated });
       }
       const text = buildEditorLaunchSummary(ctx.cwd, candidate, editorPath, discoveryWarning, launcher);
@@ -1736,7 +1757,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         details: {
           mode: "gui",
           projectRoot: candidate.projectRoot,
-          unityVersion: candidate.unityVersion,
+          unityVersion: await requireManualUnityVersion(candidate),
           editorPath,
           pid: launch.pid,
           command: launch.command,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.11.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-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",
+    "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/unity-batchmode-tests/SKILL.md

@@ -50,9 +50,9 @@ Use the `pi-unity` tools first instead of forming raw Unity CLI commands on the
 `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,10 +89,9 @@ 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
 
@@ -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/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;
@@ -84,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());
   }
 }
 

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-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-tests.ts

@@ -63,6 +63,19 @@ export type NormalizedUnityTestResult = {
 };
 
 export type UnityTestRouteRequirements = { requiresIsolation: boolean; reasons: string[] };
+
+export function resolveUnityCliBackendReportPaths(
+  paths: { nunit: string; junit: string; log: string },
+  formats: UnityTestReportFormat[],
+): { nunit: string; junit?: string; log: string } {
+  // Normalized JSON is derived from Unity CLI's native NUnit XML, so the
+  // backend report is required even when callers do not retain NUnit output.
+  return {
+    nunit: paths.nunit,
+    junit: formats.includes("junit") ? paths.junit : undefined,
+    log: paths.log,
+  };
+}
 export type UnityTestOutcomeEvidence = {
   cancelled?: boolean;
   timedOut?: boolean;