@aefree/pi-unity 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## 0.14.0 - 2026-09-14
+
+### Fixed
+
+- Preserve durable normalized connected-test evidence for terminal failed, cancelled, runner-error, and incomplete Pipeline results without replaying dispatch, overriding active Pipeline state from partial records, or misreporting inconsistent counts/records as passing.
+- Select one primary latest normalized result and only its validated project-contained backend links when inspecting historical artifacts, including canonical contained aliases.
+- Forward optional `unity_pipeline_eval.handlerTimeoutMilliseconds` only when the exact reachable Pipeline descriptor confirms raw argv support and the documented `code`/`timeout` signature. Preserve `timeoutSeconds` as the separate host/CLI wait; a dispatcher expiry cannot cancel eval code already started on Unity's main thread, so effects remain uncertain and are never retried or rerouted.
+- Treat Pipeline 0.7's explicit `compilationFailed: true` response as a failed recompile even when its status is `up_to_date` or `completed` and no compiler-error array is present.
+
+## 0.13.0 - 2026-09-10
+
+### Added
+
+- Added advertised `get_runtime_pipeline_settings` inspection and the bounded `unity_pipeline_run_script` tool for Pipeline 0.6 ephemeral in-memory compilation/execution of one existing project C# file. Hotpatch is intentionally out of scope.
+
+### Fixed
+
+- Preserve bounded Unity CLI discovery warnings/info and treat warning-bearing discovery as uncertainty rather than a confirmed absent Pipeline or launch-safe signal. Force human CLI version formatting so inherited `UNITY_FORMAT` cannot corrupt version discovery.
+- Accept Pipeline 0.6 compact response envelopes and warnings without treating warnings as compiler errors. Surface ambiguous busy responses rather than blindly redispatching commands that may be blocked by a modal dialog.
+
 ## 0.12.1 - 2026-09-10
 
 ### Security

package/README.md

@@ -34,12 +34,13 @@ Use these tools with an already-open exact Unity project copy that has a reachab
 - `unity_project_status` — inspect lockfiles, matching Unity processes, Pipeline reachability, package version, and advertised commands without launching Unity.
 - `unity_pipeline_recompile` — recompile through Pipeline with exact-copy preflight, bounded polling, and compact compiler evidence.
 - `unity_run_tests` — one intent-oriented EditMode or PlayMode workflow. It reuses compatible connected Pipeline execution or selects isolated `unity test` when the exact project copy is closed.
-- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL. It accepts `timeoutSeconds` from 1–86,400 seconds; a timeout is uncertain and does not cancel or retry Editor work.
-- `unity_pipeline_inspect` — dispatch supported package-owned inspection commands and return structured evidence.
+- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL. `timeoutSeconds` bounds pi-unity and Unity CLI waits (1–86,400 seconds). Optional `handlerTimeoutMilliseconds` is forwarded only when the exact reachable Pipeline advertises raw argv plus the verified eval timeout signature; it bounds that Pipeline dispatcher wait, not code already running on Unity's main thread. A timeout is uncertain and does not cancel or retry Editor work.
+- `unity_pipeline_inspect` — dispatch supported package-owned inspection commands (including read-only `get_runtime_pipeline_settings`) and return structured evidence. Runtime settings are refused by Pipeline in Play Mode; pi-unity never exits Play Mode to read them.
+- `unity_pipeline_run_script` — compile one existing project `.cs` file in Pipeline's ephemeral in-memory mode and invoke a named static entry point; supports bounded JSON arguments and compile-only `dryRun`. It deliberately does not expose hotpatch.
 
 Connected recompilation follows Unity's Script Changes While Playing policy and never preemptively sends `editor_stop`. Connected tests may exit Play Mode through advertised `editor_stop` when necessary, then verify Edit Mode before dispatch. Play Mode exit is allowed by default; `/unity-playmode-exit allow|disallow|status` controls the current session.
 
-A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. The sole exception is Pipeline 0.5's explicit initial-settling `Server Busy` rejection for `unity_pipeline_recompile` and `unity_run_tests`, which is known not to have dispatched a main-thread command and is retried only within the configured deadline.
+A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. Pipeline 0.6 can report busy for a modal dialog as well as startup settling, so ambiguous busy responses are surfaced and never blindly retried. Pipeline 0.7 improves recovery of standing compile errors and console output. For non-development Player builds, Pipeline also requires the `ENABLE_RUNTIME_PIPELINE` scripting define; enabling its runtime setting alone is insufficient.
 
 ### Editor and batchmode
 
@@ -47,7 +48,7 @@ A timeout is uncertain: work may still be running. The tools do not silently can
 - `unity_launch_batchmode` — run a bounded batchmode command through Unity CLI or the direct Editor executable.
 - `unity_inspect_artifacts` — validate existing normalized JSON test artifacts, Unity Test Framework XML and Unity logs without launching Unity. `details.status` describes inspection; `details.testOutcome` describes the tests, including failures and uncertainty. A valid failed-test artifact is a successful inspection, not a passing run.
 
-Pass `normalizedResultPath` for standalone JSON evidence. Any explicit artifact path disables implicit latest-file selection; missing requested files fail inspection. With all paths omitted, `latestFromLogs` discovers recent files but cannot establish current-run identity. Mixed JSON/XML evidence must agree; without an explicit native artifact link, matching counts alone leave correlation uncertain.
+Pass `normalizedResultPath` for standalone JSON evidence. Any explicit artifact path disables implicit latest-file selection and link expansion; missing requested files fail inspection. With all paths omitted, `latestFromLogs` selects one newest top-level JSON (mtime then filename) and only its contained declared NUnit/log links. Without JSON it selects XML alone, then log context. Historical selection cannot establish current-run identity. Mixed JSON/XML evidence must agree; without an explicit native artifact link, matching counts alone leave correlation uncertain.
 
 Use `unity_run_tests` for all ordinary Unity Test Framework work. It writes a durable normalized JSON result under `Logs/`; isolated `unity test` runs retain requested native reports. Connected Pipeline is selected only for compatible requests. A reachable Editor is never closed automatically to obtain isolated-only features.
 
@@ -84,6 +85,7 @@ Operation-specific recovery belongs to the operational skill. `unity-debugging`
 | Existing failed-run artifacts | `unity_inspect_artifacts` |
 | Project-specific C# query or operation | `unity_pipeline_eval` |
 | Supported structured project inspection | `unity_pipeline_inspect` |
+| Explicitly requested existing C# builder script | `unity_pipeline_run_script` |
 | Open the GUI explicitly | `unity_open_editor` or `/unity-open` |
 
 Pass an explicit project `path` when multiple copies may be discovered. Pipeline routing compares canonical paths so similarly named copies are not treated as interchangeable.
@@ -111,8 +113,14 @@ Another connected client is not a project lock. When Pipeline returns stable cor
 { code: "var s = UnityEngine.Application.dataPath; return s.Length;" }
 ```
 
+`timeoutSeconds` remains the host/CLI wait. On exact copies that advertise raw argv and the verified eval `code`/integer-`timeout` signature, `handlerTimeoutMilliseconds` (1–86,400,000) also sets Pipeline's dispatcher wait through its positional command argument. A shorter host timeout may still win. This server wait can prevent queued work from starting, but cannot cancel eval code that already began on Unity's main thread; treat expiry as uncertain and never retry or fall back.
+
 Use `unity_pipeline_inspect` when a purpose-built structured command fits. Use eval for bounded project-specific work that matches the user's intent. Prefer typed tools when they provide stronger lifecycle, polling, validation, or recovery semantics.
 
+### Pipeline run_script
+
+`unity_pipeline_run_script` is arbitrary code execution, not a sandbox or read-only inspection. Use it only when the user explicitly asks to run that existing file; obtain explicit authorization for lifecycle, settings, asset, build, test, or destructive mutations. It validates the exact project copy and advertised command twice, accepts a single existing `.cs` file inside the project, uses only `mode: ephemeral`, and never launches, saves, cancels, retries, falls back, hotpatches, or exits Play Mode. `dryRun: true` compiles without loading or executing the assembly.
+
 Rejected eval and inspection results are native Pi tool failures (`isError: true`) via the documented `tool_result` middleware, with structured rejection codes and bounded diagnostics retained. Pre-dispatch rejection does not execute the command; a timeout or dispatch failure can leave effects uncertain and never triggers retry or fallback.
 
 ## Launch and process safeguards
@@ -230,7 +238,9 @@ The registry-clean `package-lock.json` is committed. Optional development packag
 
 ## Unity Pipeline project side effect
 
-Starting `com.unity.pipeline@0.3.1-exp.1` assigns `Application.runInBackground = true`, which Unity persists as `PlayerSettings.runInBackground` in `ProjectSettings/ProjectSettings.asset`. Review that tracked change alongside `manifest.json` and `packages-lock.json` when installing Pipeline in a Unity project.
+Legacy Pipeline releases (including `0.3.1-exp.1`) assigned `Application.runInBackground = true`, which Unity persisted as `PlayerSettings.runInBackground` in `ProjectSettings/ProjectSettings.asset`. Pipeline 0.6 restores the original value around server start/stop. Review tracked settings changes when installing older releases; Pipeline 0.6 reports non-automated Editor state as descriptor `info` rather than a console warning.
+
+Pipeline 0.6 records local editor eval usage in `Library/Pipeline/eval-usage.jsonl`; raw source is not stored unless the Pipeline **Store Eval Source** setting is enabled. `UNITY_NO_CLI_INVOKED_TELEMETRY=1` opts out only of Unity CLI's per-invocation telemetry event; analytics and crash-reporting controls are separate and unchanged. Pipeline compact HTTP responses are accepted whether returned directly or inside the CLI's documented `data` wrapper; this does not assert that CLI wrapping has changed. For installed CLI/skill information, use read-only `unity skill show --list` or `unity skill show --path <path>`.
 
 ## License
 

package/index.ts

@@ -1,8 +1,8 @@
 import { keyHint, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { mkdir, readFile, readdir, stat, unlink } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { mkdir, readFile, readdir, realpath, stat, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import {
@@ -20,7 +20,7 @@ import {
   type UnityParsedTestResults,
 } 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 { createUnityCliBatchmodeReportArgs, createUnityCliEditorExitCommand, createUnityCliRunCommand, createUnityCliTestCommand, dispatchUnityPipelineRunScript, dispatchUnityPlanningInspection, haveSameKnownProcessIds, inspectUnityCliProjectCapabilities, listRunningUnityCliEditorsForProject, resolveUnityCliCommand, UNITY_PLANNING_READ_COMMANDS, type UnityCliProjectCapabilities } from "./src/unity-cli";
 import { launchUnityCliOpenDetached } from "./src/unity-launch";
 import { createUnityBatchmodeCommand, launchUnityEditorDetached, resolveUnityEditorPath } from "./src/unity-editor-fallback";
 import { loadPiUnitySettings, type PiUnitySettings } from "./src/pi-unity-settings";
@@ -32,7 +32,7 @@ import { applyUnityCliRetrySummary, compactUnityTestSummary, defaultUnityTestRep
 import { validateNormalizedUnityTestArtifact } from "./src/unity-artifact-inspection";
 import { UNITY_TEST_MAX_ARTIFACT_BYTES } from "./src/unity-tests";
 import { auditUnityGuidance, type UnityGuidanceAuditResult } from "./src/unity-guidance-audit";
-import { runUnityPipelineRecompile, runUnityPipelineTests, type UnityPipelineOperationDetails } from "./src/unity-pipeline";
+import { runUnityPipelineRecompile, runUnityPipelineTests, UnityPipelineTerminalTestEvidenceError, type UnityPipelineOperationDetails } from "./src/unity-pipeline";
 import {
   createOptionalIntegrationRegistryV1,
   isOptionalIntegrationActive,
@@ -70,7 +70,7 @@ const GUI_WARNING = "This launches the full Unity Editor GUI and is not the same
 const SINGLE_PROCESS_WARNING = "Unity allows only one process per project folder. GUI Editor and batchmode/headless both count as that one process.";
 
 type UnityToolDetails = {
-  mode: "gui" | "batchmode" | "status" | "artifacts" | "pipeline_inspection" | "pipeline_eval" | "pipeline" | "tests";
+  mode: "gui" | "batchmode" | "status" | "artifacts" | "pipeline_inspection" | "pipeline_eval" | "pipeline_run_script" | "pipeline" | "tests";
   projectRoot: string;
   unityVersion: string;
   editorPath: string;
@@ -101,7 +101,11 @@ type UnityToolDetails = {
   cliCapabilities?: UnityCliProjectCapabilities;
   pipelineInspection?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
   pipelineEval?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
+  pipelineRunScript?: { outcome: "dispatched"; command: string; output: string; truncated: boolean } | { outcome: "rejected"; code: string; message: string };
   pipeline?: UnityPipelineOperationDetails;
+  testResult?: NormalizedUnityTestResult;
+  artifactPath?: string;
+  route?: "connected" | "isolated";
 };
 
 const LAUNCHER_SCHEMA = Type.Optional(StringEnum(["auto", "unity-cli", "editor-executable"] as const, { description: "Launch backend. Defaults to auto, which prefers the Unity CLI and falls back to direct editor executable launch when the CLI is unavailable." }));
@@ -164,7 +168,17 @@ const PIPELINE_TEST_PARAMS = Type.Object({
 const PIPELINE_EVAL_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ maxLength: 1000, description: "Unity project path, workspace copy root, or folder containing project copies." })),
   code: Type.String({ minLength: 1, maxLength: 4000, description: "Bounded C# source for advertised Pipeline eval. Roslyn compiles it on the connected Editor main thread; include an explicit return value when evidence is needed." }),
-  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 12, description: "Connected eval deadline in seconds (maximum 24 hours). A timeout is uncertain and does not retry or cancel Unity work." })),
+  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 12, description: "Connected eval host/CLI deadline in seconds (maximum 24 hours). A timeout is uncertain and does not retry or cancel Unity work." })),
+  handlerTimeoutMilliseconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400000, description: "Optional advertised Pipeline eval dispatcher wait in milliseconds. Forwarded only when the exact copy advertises raw argv and the verified code/timeout signature; it cannot cancel code already started on Unity's main thread." })),
+}, { additionalProperties: false });
+
+const PIPELINE_RUN_SCRIPT_PARAMS = Type.Object({
+  path: Type.Optional(Type.String({ maxLength: 1000, description: "Unity project path, workspace copy root, or folder containing project copies." })),
+  file: Type.String({ minLength: 1, maxLength: 1000, description: "Existing .cs file under the selected project root. The file is compiled in memory; it is not written or imported." }),
+  entry: Type.Optional(Type.String({ minLength: 1, maxLength: 500, description: "Named static entry point. Omit only when Pipeline can select Main or an unambiguous public static method." })),
+  args: Type.Optional(Type.Array(Type.Any(), { maxItems: 32, description: "Bounded JSON arguments coerced by Pipeline to the static entry-point parameter types." })),
+  dryRun: Type.Optional(Type.Boolean({ default: false, description: "Compile only; do not load the assembly or invoke the entry point." })),
+  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 30, description: "Connected run_script deadline. A timeout is uncertain and does not cancel the script." })),
 }, { additionalProperties: false });
 
 const PIPELINE_INSPECTION_PARAMS = Type.Object({
@@ -186,7 +200,7 @@ const INSPECT_ARTIFACTS_PARAMS = Type.Object({
   testResultsPath: Type.Optional(Type.String({ description: "Unity Test Framework XML results path. Relative paths are resolved against cwd and the Unity project root." })),
   normalizedResultPath: Type.Optional(Type.String({ description: "pi-unity normalized JSON test artifact path." })),
   logFilePath: Type.Optional(Type.String({ description: "Unity log file path. Relative paths are resolved against cwd and the Unity project root." })),
-  latestFromLogs: Type.Optional(Type.Boolean({ default: true, description: "Only when all artifact paths are omitted, inspect the newest .json, .xml and .log files under Logs. Latest files are not proof of a shared run." })),
+  latestFromLogs: Type.Optional(Type.Boolean({ default: true, description: "Only when all artifact paths are omitted, select one newest top-level Logs JSON (mtime then filename) and only its declared contained NUnit/log links. Without JSON, select newest XML alone, otherwise newest log context. Latest files are not proof of a shared run." })),
   maxLines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, default: 60, description: "Maximum log/output lines to include." })),
   maxChars: Type.Optional(Type.Integer({ minimum: 500, maximum: 20000, default: 6000, description: "Maximum log/output characters to include." })),
 });
@@ -676,8 +690,9 @@ async function findNewestFile(root: string, suffixes: string[]): Promise<string
   let entries: Awaited<ReturnType<typeof readdir>>;
   try {
     entries = await readdir(root, { withFileTypes: true });
-  } catch {
-    return undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
   }
 
   const files = await Promise.all(entries
@@ -687,7 +702,16 @@ async function findNewestFile(root: string, suffixes: string[]): Promise<string
       const stats = await stat(fullPath);
       return { fullPath, mtimeMs: stats.mtimeMs };
     }));
-  return files.sort((left, right) => right.mtimeMs - left.mtimeMs)[0]?.fullPath;
+  return files.sort((left, right) => right.mtimeMs - left.mtimeMs || left.fullPath.localeCompare(right.fullPath))[0]?.fullPath;
+}
+
+async function resolveLinkedArtifact(projectRoot: string, linkPath: string): Promise<string> {
+  const canonicalRoot = await realpath(projectRoot);
+  const candidate = resolve(projectRoot, linkPath);
+  const canonicalCandidate = await realpath(candidate);
+  const relativePath = relative(canonicalRoot, canonicalCandidate);
+  if (!relativePath || isAbsolute(relativePath) || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) throw new Error(`Linked artifact escapes the project root: ${linkPath}`);
+  return canonicalCandidate;
 }
 
 function resolveArtifactPath(cwd: string, projectRoot: string, value: string | undefined): string | undefined {
@@ -716,12 +740,14 @@ async function buildArtifactInspectionReport(
   // An exact artifact request must not silently recruit unrelated latest evidence.
   const useLatest = params.latestFromLogs !== false && ![params.testResultsPath, params.logFilePath, params.normalizedResultPath].some(value => value?.trim());
   const logsRoot = join(candidate.projectRoot, "Logs");
-  const testResultsPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.testResultsPath)
-    ?? (useLatest ? await findNewestFile(logsRoot, [".xml"]) : undefined);
-  const logFilePath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.logFilePath)
-    ?? (useLatest ? await findNewestFile(logsRoot, [".log", ".txt"]) : undefined);
+  let testResultsPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.testResultsPath);
+  let logFilePath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.logFilePath);
   const normalizedResultPath = resolveArtifactPath(ctx.cwd, candidate.projectRoot, params.normalizedResultPath)
     ?? (useLatest ? await findNewestFile(logsRoot, [".json"]) : undefined);
+  if (useLatest && !normalizedResultPath) {
+    testResultsPath = await findNewestFile(logsRoot, [".xml"]);
+    if (!testResultsPath) logFilePath = await findNewestFile(logsRoot, [".log", ".txt"]);
+  }
   let normalized: NormalizedUnityTestResult | undefined;
   const evidenceErrors: string[] = [];
   const evidenceWarnings: string[] = [];
@@ -729,6 +755,11 @@ async function buildArtifactInspectionReport(
     try {
       if ((await stat(normalizedResultPath)).size > UNITY_TEST_MAX_ARTIFACT_BYTES) throw new Error("Normalized artifact exceeds its size limit.");
       normalized = validateNormalizedUnityTestArtifact(JSON.parse(await readFile(normalizedResultPath, "utf8")));
+      // Stored backend links, not unrelated directory recency, are the only automatic companions.
+      if (useLatest) {
+        if (normalized.backendArtifacts?.nunit) testResultsPath = await resolveLinkedArtifact(candidate.projectRoot, normalized.backendArtifacts.nunit);
+        if (normalized.backendArtifacts?.log) logFilePath = await resolveLinkedArtifact(candidate.projectRoot, normalized.backendArtifacts.log);
+      }
     } catch (error) {
       evidenceErrors.push(`Normalized test result could not be loaded/validated: ${normalizedResultPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -759,7 +790,13 @@ async function buildArtifactInspectionReport(
     }
     if ((normalized.outcome === "passed" || normalized.outcome === "passed_with_flakes") && parsedTestResults.failedTests.length > 0) evidenceErrors.push("Conflicting normalized/XML evidence: XML contains failed tests.");
     const linkedXml = normalized.backendArtifacts?.nunit;
-    if (linkedXml && resolve(candidate.projectRoot, linkedXml) !== resolve(testResultsPath!)) evidenceErrors.push("Conflicting artifact identity: selected XML is not the normalized artifact's nunit path.");
+    if (linkedXml && testResultsPath) {
+      try {
+        if (await resolveLinkedArtifact(candidate.projectRoot, linkedXml) !== await realpath(testResultsPath)) evidenceErrors.push("Conflicting artifact identity: selected XML is not the normalized artifact's nunit path.");
+      } catch (error) {
+        evidenceErrors.push(`Normalized NUnit link could not be resolved: ${linkedXml}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     if (!linkedXml) {
       evidenceWarnings.push("Normalized JSON and XML have no shared run identity; matching counts alone do not correlate these files.");
       testOutcome = "uncertain";
@@ -1220,7 +1257,25 @@ async function runUnifiedUnityTests(
   }
   const formats = request.reportFormats ?? defaultUnityTestReportFormats(route);
   if (route === "connected") {
-    const result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), testPlatform: request.testPlatform, testFilter: request.testFilters[0], testCategory: request.testCategories[0], timeoutSeconds: request.timeoutSeconds, allowAutonomousExitPlayMode }, createPipelineDependencies(pi), { signal, onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }) });
+    let result;
+    try {
+      result = await runUnityPipelineTests({ projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), testPlatform: request.testPlatform, testFilter: request.testFilters[0], testCategory: request.testCategories[0], timeoutSeconds: request.timeoutSeconds, allowAutonomousExitPlayMode }, createPipelineDependencies(pi), { signal, onUpdate: message => onUpdate?.({ content: [{ type: "text", text: message }] }) });
+    } catch (error) {
+      if (!(error instanceof UnityPipelineTerminalTestEvidenceError)) throw error;
+      const outcome = error.evidence.outcome;
+      const normalized: NormalizedUnityTestResult = {
+        schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
+        selection: { testFilters: request.testFilters, testCategories: request.testCategories },
+        durationSeconds: error.evidence.elapsedSeconds, outcome, summary: {}, tests: error.evidence.testRecords,
+        diagnostics: [error.evidence.reason, ...error.evidence.observations, ...error.evidence.warnings].slice(0, 8),
+      };
+      let artifactPath: string;
+      try { artifactPath = await writeNormalizedUnityTestArtifact(candidate.projectRoot, normalized); } catch (persistenceError) {
+        throw new Error(`${error.evidence.reason} Durable terminal evidence could not be persisted: ${persistenceError instanceof Error ? persistenceError.message : String(persistenceError)}`);
+      }
+      const text = `${compactUnityTestSummary(normalized)}\nRoute: connected Pipeline. Terminal evidence was incomplete or non-passing; no retry, fallback, or replay was performed. Normalized artifact: ${artifactPath}`;
+      return { content: [{ type: "text", text }], details: { mode: "tests", projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), editorPath: "", status: "failed", testResult: { ...normalized, tests: [] }, artifactPath, route } };
+    }
     const counts = result.details.counts!;
     const normalized: NormalizedUnityTestResult = {
       schemaVersion: 1, source: "pipeline", platform: request.testPlatform,
@@ -1294,9 +1349,9 @@ function renderUnityPipelineResult(result: any, options: { expanded: boolean; is
     const counts = pipeline.counts;
     const passed = counts?.passed === undefined || counts?.total === undefined ? "tests completed" : `${counts.passed}/${counts.total} passed`;
     text = `${icon} ${theme.fg("toolTitle", theme.bold(`Unity ${pipeline.testPlatform ?? ""} tests`.trim()))} ${theme.fg("accent", passed)}${theme.fg("muted", ` • ${pipeline.elapsedSeconds.toFixed(1)}s`)}`;
-  } else if (details.mode === "pipeline_eval" || details.mode === "pipeline_inspection") {
-    const output = details.mode === "pipeline_eval" ? details.pipelineEval : details.pipelineInspection;
-    const label = details.mode === "pipeline_eval" ? "Unity Pipeline Eval" : "Unity Pipeline Inspection";
+  } else if (details.mode === "pipeline_eval" || details.mode === "pipeline_inspection" || details.mode === "pipeline_run_script") {
+    const output = details.mode === "pipeline_eval" ? details.pipelineEval : details.mode === "pipeline_run_script" ? details.pipelineRunScript : details.pipelineInspection;
+    const label = details.mode === "pipeline_eval" ? "Unity Pipeline Eval" : details.mode === "pipeline_run_script" ? "Unity Pipeline Run Script" : "Unity Pipeline Inspection";
     const summary = output?.outcome === "dispatched" ? output.output || "(no bounded output returned)" : output?.message || primaryText;
     text = `${icon} ${theme.fg("toolTitle", theme.bold(label))}\n  ${theme.fg("toolOutput", compactUnityRendererValue(summary, 240))}`;
   } else {
@@ -1337,7 +1392,9 @@ function renderUnityToolResult(result: any, expanded: boolean, theme: any): Text
           ? "Unity Pipeline Inspection"
           : details.mode === "pipeline_eval"
             ? "Unity Pipeline Eval"
-            : details.mode === "pipeline"
+            : details.mode === "pipeline_run_script"
+              ? "Unity Pipeline Run Script"
+              : details.mode === "pipeline"
               ? "Unity Pipeline"
               : getBatchmodeVariantLabel(details.args);
   const projectLabel = details.projectRoot ?? "(unknown project)";
@@ -1391,7 +1448,9 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   pi.on("tool_result", (event) => {
     const details = event.details as UnityToolDetails | undefined;
     if ((event.toolName === "unity_pipeline_eval" && details?.mode === "pipeline_eval" && details.pipelineEval?.outcome === "rejected")
-      || (event.toolName === "unity_pipeline_inspect" && details?.mode === "pipeline_inspection" && details.pipelineInspection?.outcome === "rejected")) {
+      || (event.toolName === "unity_pipeline_inspect" && details?.mode === "pipeline_inspection" && details.pipelineInspection?.outcome === "rejected")
+      || (event.toolName === "unity_pipeline_run_script" && details?.mode === "pipeline_run_script" && details.pipelineRunScript?.outcome === "rejected")
+      || (event.toolName === "unity_run_tests" && details?.mode === "tests" && details.testResult?.outcome !== "passed" && details.testResult?.outcome !== "passed_with_flakes" && details.testResult?.outcome !== "empty_selection")) {
       return { isError: true };
     }
   });
@@ -1654,12 +1713,13 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   pi.registerTool({
     name: "unity_pipeline_eval",
     label: "Unity Pipeline Eval",
-    description: "Execute one bounded C# snippet through advertised eval in an already-open exact Unity Pipeline Editor.",
+    description: "Execute one bounded C# snippet through advertised eval in an already-open exact Unity Pipeline Editor. timeoutSeconds bounds pi-unity and Unity CLI waits; optional handlerTimeoutMilliseconds is forwarded only through a verified Pipeline raw-argv timeout contract and cannot cancel code already started on Unity's main thread.",
     promptSnippet: "Query or operate on an already-open exact Unity project through Pipeline's Roslyn C# REPL.",
     promptGuidelines: [
       "Use unity_pipeline_eval for project-specific properties, APIs, and operations that advertised typed commands do not cover. It revalidates exact-copy identity and advertised eval immediately before dispatch.",
       "Pipeline eval compiles arbitrary C# with Roslyn on the Editor main thread. Include an explicit return value for observable evidence; normal property reads and local-variable snippets are supported.",
       "Eval is not statically read-only. Follow user intent and project guidance, and obtain explicit authorization before lifecycle, persistent-setting, destructive, asset, scene-save, package, build, or test mutations.",
+      "timeoutSeconds bounds the host and Unity CLI wait. When supplied, handlerTimeoutMilliseconds bounds only the verified Pipeline dispatcher wait; a shorter host deadline may still win, and a server wait expiry cannot cancel code already started on Unity's main thread.",
       "A rejected, malformed, failing, or timed-out eval is not success; do not silently retry it through another route.",
     ],
     parameters: PIPELINE_EVAL_PARAMS,
@@ -1672,6 +1732,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         unityVersion: await requireManualUnityVersion(candidate),
         command: "eval",
         evalSnippet: params.code,
+        handlerTimeoutMilliseconds: params.handlerTimeoutMilliseconds,
       }, {
         execute: createPlanningUnityCliExecutor(pi),
         signal,
@@ -1701,6 +1762,38 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "unity_pipeline_run_script",
+    label: "Unity Pipeline Run Script",
+    description: "Compile one existing project C# file in memory and invoke its advertised static entry point through Pipeline 0.6 run_script.",
+    promptSnippet: "Run one explicitly requested existing C# builder script through an already-open exact Unity Pipeline Editor.",
+    promptGuidelines: [
+      "unity_pipeline_run_script is arbitrary code execution, not read-only and not a sandbox. Use it only for explicit user intent; obtain explicit authorization for lifecycle, settings, asset, build, test, or destructive mutations.",
+      "It uses Pipeline's ephemeral mode only: no hotpatch, no source upload, no asset import, no domain reload, no retry, fallback, cancellation, launch, save, or Play Mode exit.",
+      "Use dryRun=true to compile without loading or executing the script. A failure, malformed result, or timeout never establishes success; a timeout may still have running script effects.",
+    ],
+    parameters: PIPELINE_RUN_SCRIPT_PARAMS,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      throwIfAborted(signal);
+      const { candidate } = await resolveProjectCandidate(ctx, params.path);
+      const file = isAbsolute(params.file) ? params.file : resolve(candidate.projectRoot, params.file);
+      const result = await dispatchUnityPipelineRunScript({
+        projectRoot: candidate.projectRoot,
+        unityVersion: await requireManualUnityVersion(candidate),
+        file,
+        entry: params.entry,
+        args: params.args,
+        dryRun: params.dryRun,
+      }, { execute: createPlanningUnityCliExecutor(pi), signal, timeout: (params.timeoutSeconds ?? 30) * 1000 });
+      const text = result.outcome === "dispatched"
+        ? `Unity Pipeline run_script ${params.dryRun ? "compile-only completed" : "completed"}.\n${result.output || "(no bounded output returned)"}`
+        : `Unity Pipeline run_script rejected: ${result.code}\n${result.message}`;
+      return { content: [{ type: "text", text }], details: { mode: "pipeline_run_script", projectRoot: candidate.projectRoot, unityVersion: await requireManualUnityVersion(candidate), editorPath: "", status: result.outcome === "dispatched" ? "passed" : "failed", pipelineRunScript: result } satisfies UnityToolDetails };
+    },
+    renderCall(args, theme, context) { return renderUnityPipelineCall("unity_pipeline_run_script", args, theme, context); },
+    renderResult(result, options, theme, context) { return renderUnityPipelineResult(result, options, theme, context); },
+  });
+
   pi.registerTool({
     name: "unity_pipeline_inspect",
     label: "Unity Pipeline Inspect",
@@ -1759,7 +1852,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       "Use unity_inspect_artifacts after Unity failures when existing -testResults or -logFile artifacts need concise parsing without another Unity launch.",
       "Prefer unity_inspect_artifacts over ad hoc bash parsing of Unity XML/log files when paths are known or Logs/ contains recent artifacts.",
       "unity_inspect_artifacts does not launch Unity and is safe to use even when the Unity project is busy.",
-      "Inspect details.testOutcome, not inspection status, for test success. Passing evidence needs consistent positive passing counts; missing explicit paths and conflicting artifacts fail inspection. Latest files are not current-run identity.",
+      "Inspect details.testOutcome, not inspection status, for test success. Passing evidence needs consistent positive passing counts; missing explicit paths and conflicting artifacts fail inspection. With all paths omitted, latest selection uses one JSON and its contained declared links, otherwise XML alone then log context; explicit paths disable selection/link expansion. Latest files are not current-run identity.",
     ],
     parameters: INSPECT_ARTIFACTS_PARAMS,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -18,7 +18,7 @@
     ]
   },
   "scripts": {
-    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-launch.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/unity-package-validation.test.ts",
+    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-launch.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/unity-package-validation.test.ts",
     "eval:guidance-skill": "tsx evals/auditing-unity-agent-guidance/run-eval.ts"
   },
   "dependencies": {

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

@@ -16,7 +16,7 @@ Use one typed tool call for each supported connected operation:
 
 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_run_tests`, which confirms that a main-thread command was rejected before dispatch.
+A timeout, malformed response, or busy response is uncertain: the Unity operation may still be running or blocked by a modal dialog. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision. Pipeline 0.6 uses busy for modal blocks and no source-verified discriminator is available through this transport, so pi-unity does not blindly retry it.
 
 ## Preconditions and boundaries
 
@@ -67,4 +67,4 @@ Normally call the typed tools, not raw CLI commands. If a typed tool is unavaila
 
 Use `unity_run_tests` with `execution: "isolated"` for a closed project, intentional isolation/CI, multiple selectors in one run, retries, sharding, coverage, or required NUnit/JUnit evidence. Multiple independent fixtures alone do not require closing a reachable Editor: use the serial recipe above. 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.
+Use the typed compile/test tools when their polling and terminal evidence fit the task. For an explicitly requested existing C# builder file, `unity_pipeline_run_script` uses Pipeline 0.6 ephemeral in-memory compilation with bounded JSON arguments or compile-only dry run; it never enables hotpatch and remains arbitrary code execution requiring explicit mutation authorization. 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 bounds pi-unity/Unity CLI waits. Optional `handlerTimeoutMilliseconds` (1–86,400,000) is forwarded only when the exact reachable Pipeline advertises raw argv and the verified eval `code`/integer-`timeout` signature; it bounds Pipeline's dispatcher wait, while a shorter host wait can still win. A dispatcher expiry cannot cancel code already started on Unity's main thread, so the effect remains uncertain and no retry or fallback is allowed. 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-artifact-inspection.ts

@@ -9,6 +9,16 @@ const strings = (value: unknown): value is string[] => Array.isArray(value) && v
 const relativeId = (value: unknown): value is string => typeof value === "string" && !!value.trim()
   && !isAbsolute(value) && !/^(?:[A-Za-z]:|[\\/])/.test(value) && !value.split(/[\\/]/).includes("..") && !/\0/.test(value);
 
+/** Shared count/retained-record invariant for durable validation and Pipeline pass acceptance. */
+export function hasConsistentUnityTestCounts(summary: Record<string, unknown>, tests: Array<{ status: string }>): boolean {
+  const total = summary.total; const passed = summary.passed; const failed = summary.failed;
+  const skipped = summary.skipped; const inconclusive = summary.inconclusive;
+  if (![total, passed, failed, skipped, inconclusive].every(value => value === undefined || count(value))) return false;
+  if (count(total) && [passed, failed, skipped, inconclusive].reduce<number>((sum, value) => sum + (count(value) ? value : 0), 0) > total) return false;
+  if (count(total) && tests.length > total) return false;
+  return [["passed", passed], ["failed", failed], ["skipped", skipped], ["inconclusive", inconclusive]].every(([status, limit]) => !count(limit) || tests.filter(test => status === "passed" ? /^(?:passed|success)$/i.test(test.status) : test.status.toLowerCase() === status).length <= limit);
+}
+
 /** Read the durable schema, not a transport response. Missing optional counts remain unknown.
  * Test records may be bounded or absent: never require tests.length === summary.total.
  */
@@ -25,10 +35,7 @@ export function validateNormalizedUnityTestArtifact(value: unknown): NormalizedU
   for (const key of ["total", "passed", "failed", "skipped", "inconclusive"]) {
     if (summary[key] !== undefined && !count(summary[key])) invalid(`summary.${key} must be a non-negative integer`);
   }
-  if (count(summary.total)) {
-    const accounted = [summary.passed, summary.failed, summary.skipped, summary.inconclusive].reduce<number>((sum, item) => sum + (count(item) ? item : 0), 0);
-    if (accounted > summary.total) invalid("summary counts exceed total");
-  }
+  if (!hasConsistentUnityTestCounts(summary, [])) invalid("summary counts are inconsistent");
   if (!Array.isArray(result.tests)) invalid("tests must be an array");
   const tests = result.tests as unknown[];
   for (const test of tests) {
@@ -38,14 +45,11 @@ export function validateNormalizedUnityTestArtifact(value: unknown): NormalizedU
     if (item.durationSeconds !== undefined && !nonnegative(item.durationSeconds)) invalid("test durationSeconds must be non-negative");
     if (item.attempts !== undefined && (!count(item.attempts) || item.attempts < 1)) invalid("test attempts must be positive");
   }
-  if (count(summary.total) && tests.length > summary.total) invalid("test records exceed total");
+  if (!hasConsistentUnityTestCounts(summary, tests as Array<{ status: string }>)) invalid("test records conflict with summary counts");
   const typed = result as unknown as NormalizedUnityTestResult;
-  for (const [status, key] of [["passed", "passed"], ["failed", "failed"], ["skipped", "skipped"], ["inconclusive", "inconclusive"]] as const) {
-    const observed = typed.tests.filter(test => test.status.toLowerCase() === status).length;
-    if (count(summary[key]) && observed > summary[key]) invalid(`test records conflict with summary.${key}`);
-  }
   if (result.projectRelativeId !== undefined && !relativeId(result.projectRelativeId)) invalid("projectRelativeId must be project-relative");
   if (result.backendArtifacts !== undefined && (!record(result.backendArtifacts) || !Object.values(result.backendArtifacts).every(relativeId))) invalid("backendArtifacts must contain project-relative paths");
+  if (result.diagnostics !== undefined && (!Array.isArray(result.diagnostics) || result.diagnostics.length > 8 || !result.diagnostics.every(item => typeof item === "string" && !!item.trim() && item.length <= 1_000))) invalid("diagnostics must contain at most eight bounded strings");
   for (const key of ["startedAt", "completedAt"]) if (result[key] !== undefined && (typeof result[key] !== "string" || !Number.isFinite(Date.parse(result[key] as string)))) invalid(`${key} must be a timestamp`);
   if (typed.startedAt && typed.completedAt && Date.parse(typed.completedAt) < Date.parse(typed.startedAt)) invalid("completion precedes start");
   if (result.durationSeconds !== undefined && !nonnegative(result.durationSeconds)) invalid("durationSeconds must be non-negative");

package/src/unity-cli.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
-import { readFile, realpath } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
 import { applyDefaultUnityBatchmodeArgs, buildUnityBatchmodeArgs, projectPathsMatch } from "./unity-core";
 import type { RunningUnityProcess } from "./unity-processes";
 
@@ -46,6 +46,13 @@ export type UnityCliPipelineInstance = {
 
 export type UnityCliDiscoveryState = "not_attempted" | "available" | "absent" | "timeout" | "unavailable";
 
+export type UnityCliCommandParameter = {
+  name: string;
+  type: string;
+  required: boolean;
+  defaultValue?: unknown;
+};
+
 export type UnityCliProjectCapabilities = {
   cliAvailable: boolean;
   cliVersion?: string;
@@ -56,6 +63,12 @@ export type UnityCliProjectCapabilities = {
   advertisedCommands: string[];
   advertisedCommandCount: number;
   advertisedCommandsTruncated: boolean;
+  /** Display-oriented command descriptors. They are never capability evidence. */
+  advertisedCommandParameters?: Record<string, readonly UnityCliCommandParameter[]>;
+  /** Complete, bounded, unambiguous descriptors eligible for exact capability gates. */
+  verifiedCommandParameters?: Record<string, readonly UnityCliCommandParameter[]>;
+  /** True only when the exact live Pipeline descriptor advertises raw argv support. */
+  pipelineSupportsExecArgv?: boolean;
   commandDiscoveryAttempted: boolean;
   commandDiscoverySucceeded: boolean;
   latestPipelineVersion?: string;
@@ -265,10 +278,10 @@ export function parseUnityCliStatusOutput(output: string, projectRoot: string):
 
 export async function listRunningUnityCliEditorsForProject(
   projectRoot: string,
-  options: { cliCommand?: string; timeout?: number } = {},
+  options: { cliCommand?: string; timeout?: number; execute?: UnityCliExecutor } = {},
 ): Promise<{ processes: RunningUnityProcess[]; warning?: string }> {
   const command = resolveUnityCliCommand(options);
-  const result = await execFileCollect(command, ["--format", "json", "--no-banner", "--non-interactive", "status", "--project", projectRoot], {
+  const result = await (options.execute ?? execFileCollect)(command, ["--format", "json", "--no-banner", "--non-interactive", "status", "--project", projectRoot], {
     timeout: options.timeout ?? 5000,
   });
 
@@ -277,11 +290,14 @@ export async function listRunningUnityCliEditorsForProject(
   }
 
   const processes = parseUnityCliStatusOutput(result.stdout, projectRoot);
-  if (processes.length > 0) {
-    return { processes };
+  const payload = parseJsonObject(result.stdout);
+  const statusWarnings = envelopeMessages(payload, "warnings");
+  if (statusWarnings.length > 0) {
+    return { processes, warning: `Unity CLI status response is incomplete; process absence is uncertain: ${statusWarnings.join("; ")}` };
   }
+  if (processes.length > 0) return { processes };
+
 
-  const payload = parseJsonObject(result.stdout);
   const errors = Array.isArray(payload?.errors) ? payload.errors : [];
   const onlyNoInstances = errors.some((entry) => getRecord(entry)?.code === "STATUS_NO_INSTANCES");
   if (result.error && !onlyNoInstances) {
@@ -343,10 +359,16 @@ export function parseUnityCliPipelineListOutput(output: string, projectRoot: str
 type UnityCliCommandCatalog = {
   valid: boolean;
   commands: string[];
+  parametersByCommand: Record<string, readonly UnityCliCommandParameter[]>;
+  verifiedParametersByCommand: Record<string, readonly UnityCliCommandParameter[]>;
   total: number;
   truncated: boolean;
 };
 
+function isBoundedDescriptorString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 120 && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
 function parseUnityCliCommandCatalog(output: string): UnityCliCommandCatalog {
   const payload = parseJsonObject(output);
   const data = getRecord(payload?.data);
@@ -363,21 +385,53 @@ function parseUnityCliCommandCatalog(output: string): UnityCliCommandCatalog {
       candidates.push(...value);
     }
   }
-  const names = candidates.flatMap((entry): string[] => {
-    const rawName = typeof entry === "string"
-      ? entry
-      : optionalString(getRecord(entry)?.name, getRecord(entry)?.command, getRecord(entry)?.id);
-    if (!rawName) return [];
+
+  const parametersByCommand: Record<string, readonly UnityCliCommandParameter[]> = {};
+  const verifiedCandidates = new Map<string, Array<readonly UnityCliCommandParameter[] | undefined>>();
+  const names: string[] = [];
+  for (const entry of candidates) {
+    const record = getRecord(entry);
+    const rawName = typeof entry === "string" ? entry : optionalString(record?.name, record?.command, record?.id);
+    if (!isBoundedDescriptorString(rawName)) continue;
     const name = rawName.trim();
-    if (!name || name.length > 120 || /[\u0000-\u001f\u007f]/.test(name)) return [];
-    return [name];
-  });
+    if (!isBoundedDescriptorString(name)) continue;
+    names.push(name);
+
+    // Preserve a best-effort descriptor for status display, but retain authoritative
+    // evidence only when every declared parameter is valid and the array was not cut.
+    const rawParameters = record?.parameters;
+    let parsed: UnityCliCommandParameter[] | undefined;
+    if (Array.isArray(rawParameters) && rawParameters.length <= 32) {
+      parsed = [];
+      for (const item of rawParameters) {
+        const parameter = getRecord(item);
+        const parameterName = parameter?.name;
+        const type = parameter?.type;
+        if (!isBoundedDescriptorString(parameterName) || !isBoundedDescriptorString(type) || typeof parameter?.required !== "boolean") {
+          parsed = undefined;
+          break;
+        }
+        parsed.push({ name: parameterName, type, required: parameter.required, ...(Object.prototype.hasOwnProperty.call(parameter, "defaultValue") ? { defaultValue: parameter.defaultValue } : {}) });
+      }
+    }
+    if (!(name in parametersByCommand) && parsed) parametersByCommand[name] = parsed;
+    const entries = verifiedCandidates.get(name) ?? [];
+    entries.push(parsed);
+    verifiedCandidates.set(name, entries);
+  }
+
   const unique = [...new Set(names)].sort((left, right) => left.localeCompare(right));
+  const commands = unique.slice(0, 256);
+  const verifiedParametersByCommand = Object.fromEntries([...verifiedCandidates].flatMap(([name, descriptors]) =>
+    descriptors.length === 1 && descriptors[0] ? [[name, descriptors[0]]] : [],
+  ));
   return {
     valid: Boolean(payload?.success === true && valid),
-    commands: unique.slice(0, 256),
+    commands,
+    parametersByCommand: Object.fromEntries(commands.flatMap(name => parametersByCommand[name] ? [[name, parametersByCommand[name]]] : [])),
+    verifiedParametersByCommand,
     total: unique.length,
-    truncated: unique.length > 256 || names.length < candidates.length,
+    truncated: unique.length > 256,
   };
 }
 
@@ -425,19 +479,40 @@ export async function readDeclaredUnityPipelineVersion(projectRoot: string): Pro
   return optionalString(manifestDependencies?.["com.unity.pipeline"]);
 }
 
+/** Read only the public capability names; the descriptor's authentication token is never retained or surfaced. */
+async function readPipelineDescriptorCapabilities(projectRoot: string): Promise<string[] | undefined> {
+  const descriptor = await readJsonFile(join(projectRoot, "Library", "Pipeline", ".unity-pipeline-port"));
+  if (!descriptor) return undefined;
+  const values = Array.isArray(descriptor.capabilities) ? descriptor.capabilities : [];
+  return [...new Set(values.filter((value): value is string => typeof value === "string" && value.length > 0 && value.length <= 120 && !/[\u0000-\u001f\u007f]/.test(value)))];
+}
+
 export function isUnityCliTimeout(result: Pick<UnityCliExecResult, "error">): boolean {
   const error = result.error as (NodeJS.ErrnoException & { killed?: boolean }) | undefined;
   return error?.code === "ETIMEDOUT" || error?.killed === true || error?.signal === "SIGTERM";
 }
 
+const UNITY_CLI_MAX_DIAGNOSTICS = 8;
+function envelopeMessages(payload: Record<string, unknown> | null, fieldName: "errors" | "warnings" | "info"): string[] {
+  const entries = Array.isArray(payload?.[fieldName]) ? payload[fieldName] : [];
+  return entries.slice(0, UNITY_CLI_MAX_DIAGNOSTICS).flatMap((entry): string[] => {
+    const item = getRecord(entry);
+    const message = optionalString(item?.message, item?.detail, typeof entry === "string" ? entry : undefined);
+    return message ? [redactUnityPlanningOutput(summarizeUnityCliText(message, 1_000, 10))] : [];
+  });
+}
+
+/** Warnings make discovery incomplete; informational descriptor/envelope notes do not. */
+function cliEnvelopeDiagnostics(payload: Record<string, unknown> | null): string[] {
+  return envelopeMessages(payload, "warnings").map(message => `warning: ${message}`);
+}
+function cliEnvelopeInfo(payload: Record<string, unknown> | null): string[] {
+  return envelopeMessages(payload, "info").map(message => `info: ${message}`);
+}
+
 function cliFailureMessage(result: UnityCliExecResult): string | undefined {
   const payload = parseJsonObject(result.stdout);
-  const errors = Array.isArray(payload?.errors) ? payload.errors : [];
-  const messages = errors.flatMap((entry): string[] => {
-    const message = optionalString(getRecord(entry)?.message);
-    return message ? [message] : [];
-  });
-  const message = messages[0] ?? (result.stderr.trim() || result.error?.message);
+  const message = envelopeMessages(payload, "errors")[0] ?? (result.stderr.trim() || result.error?.message);
   return message ? summarizeUnityCliText(message) : undefined;
 }
 
@@ -467,7 +542,9 @@ export async function inspectUnityCliProjectCapabilities(
   const command = resolveUnityCliCommand(options);
   const versionTimeout = options.timeout ?? UNITY_CLI_VERSION_TIMEOUT_MS;
   const discoveryTimeout = options.timeout ?? UNITY_CLI_DISCOVERY_TIMEOUT_MS;
-  const versionResult = await execute(command, ["--version"], { timeout: versionTimeout, signal: options.signal });
+  // Explicitly select the supported human formatter: inherited UNITY_FORMAT must not turn
+  // --version into JSON (or another representation) and corrupt capability reporting.
+  const versionResult = await execute(command, ["--format", "human", "--version"], { timeout: versionTimeout, signal: options.signal });
   if (versionResult.error && (versionResult.error as NodeJS.ErrnoException).code === "ENOENT") return result;
   if (versionResult.error) {
     result.warnings.push(`Unity CLI version probe ${isUnityCliTimeout(versionResult) ? "timed out" : "failed"}: ${cliFailureMessage(versionResult) ?? "unknown error"}`);
@@ -479,14 +556,22 @@ export async function inspectUnityCliProjectCapabilities(
   const pipelineResult = await execute(command, ["--format", "json", "--no-banner", "--non-interactive", "pipeline", "list"], { timeout: discoveryTimeout, signal: options.signal });
   const pipelinePayload = parseJsonObject(pipelineResult.stdout);
   const pipelineData = getRecord(pipelinePayload?.data);
-  if (pipelineResult.error || pipelinePayload?.success !== true || !Array.isArray(pipelineData?.instances)) {
+  const pipelineDiagnostics = cliEnvelopeDiagnostics(pipelinePayload);
+  result.warnings.push(...cliEnvelopeInfo(pipelinePayload));
+  if (pipelineResult.error || pipelinePayload?.success !== true || !Array.isArray(pipelineData?.instances) || pipelineDiagnostics.length > 0) {
     result.pipelineDiscovery = isUnityCliTimeout(pipelineResult) ? "timeout" : "unavailable";
-    result.warnings.push(`Unity Pipeline instance discovery ${result.pipelineDiscovery === "timeout" ? "timed out; Pipeline startup state is uncertain" : "failed"}: ${cliFailureMessage(pipelineResult) ?? "malformed or unsupported JSON response"}`);
+    const diagnostic = pipelineDiagnostics.join("; ") || cliFailureMessage(pipelineResult) || "malformed or unsupported JSON response";
+    result.warnings.push(`Unity Pipeline instance discovery ${result.pipelineDiscovery === "timeout" ? "timed out; Pipeline startup state is uncertain" : "is incomplete or failed; Pipeline startup state is uncertain"}: ${diagnostic}`);
+    // Retain any known positive exact-copy instance descriptors, but never use this
+    // incomplete response as a safe launch or connected-dispatch signal.
+    result.matchingInstances = parseUnityCliPipelineListOutput(pipelineResult.stdout, projectRoot).instances;
     return result;
   }
   result.pipelineDiscovery = "available";
   const pipeline = parseUnityCliPipelineListOutput(pipelineResult.stdout, projectRoot);
   result.matchingInstances = pipeline.instances;
+  const descriptorCapabilities = await readPipelineDescriptorCapabilities(projectRoot);
+  result.pipelineSupportsExecArgv = descriptorCapabilities?.includes("exec.argv") === true;
   result.latestPipelineVersion = pipeline.latestVersion;
   if (pipeline.instances.length === 0) {
     result.pipelineDiscovery = "absent";
@@ -498,15 +583,29 @@ export async function inspectUnityCliProjectCapabilities(
   }
 
   result.commandDiscoveryAttempted = true;
-  const listResult = await execute(command, ["--format", "json", "--no-banner", "--non-interactive", "list", "--project-path", projectRoot], { timeout: discoveryTimeout, signal: options.signal });
+  // `unity list` normalizes parameter types/defaults, while `unity command` with no command
+  // returns the live Pipeline catalog descriptor needed for exact capability-gated forwarding.
+  const listResult = await execute(command, ["--format", "json", "--no-banner", "--non-interactive", "command", "--project-path", projectRoot, "--detail", "full"], { timeout: discoveryTimeout, signal: options.signal });
   const catalog = parseUnityCliCommandCatalog(listResult.stdout);
-  if (listResult.error || !catalog.valid) {
+  const listPayload = parseJsonObject(listResult.stdout);
+  const commandDiagnostics = cliEnvelopeDiagnostics(listPayload);
+  result.warnings.push(...cliEnvelopeInfo(listPayload));
+  if (listResult.error || !catalog.valid || commandDiagnostics.length > 0) {
     result.commandDiscovery = isUnityCliTimeout(listResult) ? "timeout" : "unavailable";
-    result.warnings.push(`Unity Pipeline command discovery for the exact project copy ${result.commandDiscovery === "timeout" ? "timed out; command availability is uncertain" : "failed"}: ${cliFailureMessage(listResult) ?? "malformed or unsupported JSON response"}`);
+    result.warnings.push(`Unity Pipeline command discovery for the exact project copy ${result.commandDiscovery === "timeout" ? "timed out; command availability is uncertain" : "is incomplete or failed; command availability is uncertain"}: ${commandDiagnostics.join("; ") || cliFailureMessage(listResult) || "malformed or unsupported JSON response"}`);
+    // Commands in a warning-bearing catalog are informational only, not advertised
+    // capability evidence. Keep descriptors for status visibility without enabling dispatch.
+    result.advertisedCommands = catalog.commands;
+    result.advertisedCommandParameters = catalog.parametersByCommand;
+    result.verifiedCommandParameters = catalog.verifiedParametersByCommand;
+    result.advertisedCommandCount = catalog.total;
+    result.advertisedCommandsTruncated = catalog.truncated;
     return result;
   }
   result.commandDiscovery = "available";
   result.advertisedCommands = catalog.commands;
+  result.advertisedCommandParameters = catalog.parametersByCommand;
+  result.verifiedCommandParameters = catalog.verifiedParametersByCommand;
   result.advertisedCommandCount = catalog.total;
   result.advertisedCommandsTruncated = catalog.truncated;
   result.commandDiscoverySucceeded = true;
@@ -522,6 +621,7 @@ export const UNITY_PLANNING_READ_COMMANDS = Object.freeze([
   "get_authoring_root",
   "get_build_settings",
   "get_player_settings",
+  "get_runtime_pipeline_settings",
   "get_scene_hierarchy",
   "editor_status",
   "list_open_scenes",
@@ -536,12 +636,29 @@ export type UnityPlanningInspectionRequest = {
   args?: string[];
   /** A bounded C# snippet for advertised eval. Pipeline compiles it with Roslyn on the Editor main thread. */
   evalSnippet?: string;
+  /** Verified Pipeline eval dispatcher wait in milliseconds; distinct from the CLI/host wait. */
+  handlerTimeoutMilliseconds?: number;
 };
 
 export type UnityPlanningInspectionResult =
   | { outcome: "dispatched"; command: string; output: string; truncated: boolean }
   | { outcome: "rejected"; code: string; message: string };
 
+export type UnityPipelineRunScriptRequest = {
+  projectRoot: string;
+  unityVersion: string;
+  file: string;
+  entry?: string;
+  args?: unknown[];
+  dryRun?: boolean;
+};
+
+/** Attach bounded native discovery guidance without changing the readiness decision. */
+export function unityCapabilityDiagnosticSuffix(capabilities: UnityCliProjectCapabilities): string {
+  const message = summarizeUnityCliText(redactUnityPlanningOutput(capabilities.warnings.slice(0, 8).join("; ")), 1_000, 10);
+  return message ? ` ${message}` : "";
+}
+
 function planningInspectionReadiness(capabilities: UnityCliProjectCapabilities): string | undefined {
   if (!capabilities.cliAvailable) return "unity_cli_unavailable";
   if (capabilities.pipelineDiscovery !== "available") return `pipeline_${capabilities.pipelineDiscovery}`;
@@ -556,12 +673,46 @@ function caseInsensitiveField(record: Record<string, unknown>, name: string): un
   return entry?.[1];
 }
 
+function runScriptCommandFailure(output: string): "malformed" | "failure" | undefined {
+  const envelope = parseJsonObject(output);
+  if (!envelope || caseInsensitiveField(envelope, "success") !== true) return envelope ? "failure" : "malformed";
+  const wrapper = getRecord(caseInsensitiveField(envelope, "data")) ?? envelope;
+  if (caseInsensitiveField(wrapper, "success") === false) return "failure";
+  let response: unknown = caseInsensitiveField(wrapper, "result");
+  // Legacy wrapper puts the documented RunScriptResponse in data.result; compact
+  // transport puts it in result. A bare success envelope has no command evidence.
+  if (typeof response === "string") { try { response = JSON.parse(response); } catch { return "malformed"; } }
+  const result = getRecord(response);
+  if (!result || !Object.prototype.hasOwnProperty.call(result, "diagnostics") || !Array.isArray(caseInsensitiveField(result, "diagnostics"))) return "malformed";
+  if (caseInsensitiveField(result, "success") === false || caseInsensitiveField(result, "failed") === true) return "failure";
+  const diagnostics = caseInsensitiveField(result, "diagnostics") as unknown[];
+  if (diagnostics.some(item => {
+    const diagnostic = getRecord(item);
+    return String(caseInsensitiveField(diagnostic ?? {}, "severity") ?? "").toLowerCase() === "error";
+  })) return "failure";
+  return undefined;
+}
+
+function hasVerifiedEvalTimeoutContract(capabilities: UnityCliProjectCapabilities): boolean {
+  const parameters = capabilities.verifiedCommandParameters?.eval;
+  return capabilities.pipelineSupportsExecArgv === true
+    && Array.isArray(parameters)
+    && parameters.length === 2
+    && parameters[0]?.name === "code"
+    && parameters[0]?.type === "String"
+    && parameters[0]?.required === true
+    && parameters[1]?.name === "timeout"
+    && parameters[1]?.type === "Int32"
+    && parameters[1]?.required === false
+    && parameters[1]?.defaultValue === 5000;
+}
+
 function connectedCommandFailure(output: string, isEval: boolean): "malformed" | "failure" | undefined {
   const envelope = parseJsonObject(output);
   if (!envelope) return "malformed";
   if (caseInsensitiveField(envelope, "success") !== true) return "failure";
-  const data = getRecord(caseInsensitiveField(envelope, "data"));
-  if (!data) return "malformed";
+  // Pipeline 0.6 compact responses omit the CLI wrapper's data field.
+  const data = getRecord(caseInsensitiveField(envelope, "data")) ?? envelope;
   if (caseInsensitiveField(data, "success") === false) return "failure";
   if (!isEval) return undefined;
 
@@ -610,7 +761,7 @@ export async function dispatchUnityPlanningInspection(
   }));
   const initial = await inspect(projectRoot, request.unityVersion);
   const initialFailure = planningInspectionReadiness(initial);
-  if (initialFailure) return { outcome: "rejected", code: initialFailure, message: "Exact-copy Pipeline planning inspection is not established." };
+  if (initialFailure) return { outcome: "rejected", code: initialFailure, message: `Exact-copy Pipeline planning inspection is not established.${unityCapabilityDiagnosticSuffix(initial)}` };
 
   const isEval = request.command === "eval";
   const hasBoundedArgs = (request.args?.length ?? 0) <= 12
@@ -623,6 +774,12 @@ export async function dispatchUnityPlanningInspection(
     if (request.args?.length || !snippet || snippet.length > UNITY_PIPELINE_EVAL_MAX_CHARS || /[\u0000]/.test(snippet)) {
       return { outcome: "rejected", code: "planning_eval_invalid", message: "Eval requires one non-empty bounded C# snippet and no separate arguments." };
     }
+    if (request.handlerTimeoutMilliseconds !== undefined && (!Number.isInteger(request.handlerTimeoutMilliseconds) || request.handlerTimeoutMilliseconds < 1 || request.handlerTimeoutMilliseconds > 86_400_000)) {
+      return { outcome: "rejected", code: "planning_eval_invalid", message: "Eval handler timeout must be an integer from 1 to 86400000 milliseconds." };
+    }
+    if (request.handlerTimeoutMilliseconds !== undefined && !hasVerifiedEvalTimeoutContract(initial)) {
+      return { outcome: "rejected", code: "planning_eval_timeout_unavailable", message: "The exact Pipeline copy does not establish raw argv support and the documented eval timeout signature; eval was not dispatched." };
+    }
   } else if (!UNITY_PLANNING_READ_COMMANDS.includes(request.command as typeof UNITY_PLANNING_READ_COMMANDS[number]) || (request.evalSnippet?.trim() ?? "") !== "") {
     return { outcome: "rejected", code: "planning_command_invalid", message: "Only a package-owned purpose-built inspection command may be selected here." };
   }
@@ -633,18 +790,21 @@ export async function dispatchUnityPlanningInspection(
   const refreshed = await inspect(projectRoot, request.unityVersion);
   const refreshedFailure = planningInspectionReadiness(refreshed);
   if (refreshedFailure || !haveSameKnownProcessIds(initial.matchingInstances, refreshed.matchingInstances)) {
-    return { outcome: "rejected", code: "unity_project_identity_changed", message: "Pipeline identity changed or disconnected immediately before planning dispatch." };
+    return { outcome: "rejected", code: "unity_project_identity_changed", message: `Pipeline identity changed or disconnected immediately before planning dispatch.${unityCapabilityDiagnosticSuffix(refreshed)}` };
   }
   if (!refreshed.advertisedCommands.includes(request.command)) {
     return { outcome: "rejected", code: "planning_command_unadvertised", message: "The refreshed exact Pipeline copy did not advertise the requested command." };
   }
+  if (isEval && request.handlerTimeoutMilliseconds !== undefined && !hasVerifiedEvalTimeoutContract(refreshed)) {
+    return { outcome: "rejected", code: "planning_eval_timeout_unavailable", message: "The exact Pipeline eval timeout capability changed before dispatch; eval was not dispatched." };
+  }
 
   const command = resolveUnityCliCommand({ cliCommand: options.cliCommand });
   const args = [
     "--format", "json", "--no-banner", "--non-interactive", "command", "--project-path", projectRoot,
     "--timeout", String(Math.max(1, Math.ceil((options.timeout ?? UNITY_CLI_DISCOVERY_TIMEOUT_MS) / 1000))),
     request.command,
-    ...(isEval ? [request.evalSnippet!.trim()] : request.args ?? []),
+    ...(isEval ? [request.evalSnippet!.trim(), ...(request.handlerTimeoutMilliseconds === undefined ? [] : [String(request.handlerTimeoutMilliseconds)])] : request.args ?? []),
   ];
   const execution = await options.execute(command, args, { timeout: options.timeout ?? UNITY_CLI_DISCOVERY_TIMEOUT_MS, signal: options.signal });
   const raw = [execution.stdout, execution.stderr].filter(Boolean).join("\n");
@@ -663,6 +823,37 @@ export async function dispatchUnityPlanningInspection(
   return { outcome: "dispatched", command: request.command, output, truncated: output.length < raw.trim().length };
 }
 
+/** Dispatch the documented Pipeline 0.6 ephemeral run_script form; hotpatch is deliberately not exposed. */
+export async function dispatchUnityPipelineRunScript(
+  request: UnityPipelineRunScriptRequest,
+  options: { cliCommand?: string; timeout?: number; signal?: AbortSignal; execute: UnityCliExecutor; inspect?: (projectRoot: string, unityVersion: string) => Promise<UnityCliProjectCapabilities> },
+): Promise<UnityPlanningInspectionResult> {
+  let projectRoot: string; let file: string;
+  try { projectRoot = await realpath(request.projectRoot); file = await realpath(request.file); } catch {
+    return { outcome: "rejected", code: "run_script_path_unavailable", message: "The project root or existing script file could not be canonicalized." };
+  }
+  const relativeFile = relative(projectRoot, file);
+  let fileStats: Awaited<ReturnType<typeof stat>>;
+  try { fileStats = await stat(file); } catch { return { outcome: "rejected", code: "run_script_file_invalid", message: "run_script requires one readable existing C# file." }; }
+  if (!relativeFile || isAbsolute(relativeFile) || relativeFile === ".." || relativeFile.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || !fileStats.isFile() || !/\.cs$/i.test(relativeFile)) return { outcome: "rejected", code: "run_script_file_invalid", message: "run_script requires one existing .cs file inside the exact project root." };
+  let serializedArgs: string;
+  try { serializedArgs = JSON.stringify(request.args ?? []); } catch { return { outcome: "rejected", code: "run_script_args_invalid", message: "run_script arguments must be JSON-serializable." }; }
+  if (serializedArgs === undefined || serializedArgs.length > 4_000 || (request.entry?.length ?? 0) > 500 || /[\u0000-\u001f\u007f]/.test(request.entry ?? "")) return { outcome: "rejected", code: "run_script_args_invalid", message: "run_script entry or JSON arguments exceed bounded request limits." };
+  const inspect = options.inspect ?? ((root, version) => inspectUnityCliProjectCapabilities(root, version, { cliCommand: options.cliCommand, timeout: options.timeout, signal: options.signal, execute: options.execute }));
+  const initial = await inspect(projectRoot, request.unityVersion);
+  if (planningInspectionReadiness(initial) || !initial.advertisedCommands.includes("run_script")) return { outcome: "rejected", code: "run_script_unavailable", message: `The exact reachable Pipeline copy does not establish advertised run_script support.${unityCapabilityDiagnosticSuffix(initial)}` };
+  const refreshed = await inspect(projectRoot, request.unityVersion);
+  if (planningInspectionReadiness(refreshed) || !haveSameKnownProcessIds(initial.matchingInstances, refreshed.matchingInstances) || !refreshed.advertisedCommands.includes("run_script")) return { outcome: "rejected", code: "unity_project_identity_changed", message: `Pipeline identity or run_script availability changed immediately before dispatch.${unityCapabilityDiagnosticSuffix(refreshed)}` };
+  const timeout = Math.max(1, Math.min(options.timeout ?? 30_000, 86_400_000));
+  const args = ["--format", "json", "--no-banner", "--non-interactive", "command", "--project-path", projectRoot, "--timeout", String(Math.ceil(timeout / 1000)), "run_script", "--file", relativeFile, "--mode", "ephemeral", "--args", serializedArgs, "--timeout_ms", String(timeout), ...(request.entry?.trim() ? ["--entry", request.entry.trim()] : []), ...(request.dryRun ? ["--dry_run", "true"] : [])];
+  const execution = await options.execute(resolveUnityCliCommand({ cliCommand: options.cliCommand }), args, { timeout, signal: options.signal });
+  const raw = [execution.stdout, execution.stderr].filter(Boolean).join("\n"); const output = summarizeUnityCliText(redactUnityPlanningOutput(raw), 4_000, 40);
+  if (execution.error) return { outcome: "rejected", code: isUnityCliTimeout(execution) ? "run_script_timeout" : "run_script_failed", message: `run_script did not complete successfully; its effect may be uncertain.${output ? ` ${output}` : ""}` };
+  const failure = runScriptCommandFailure(execution.stdout);
+  if (failure) return { outcome: "rejected", code: failure === "malformed" ? "run_script_malformed" : "run_script_reported_failure", message: `${failure === "malformed" ? "run_script returned malformed JSON evidence" : "run_script reported failure"}.${output ? ` ${output}` : ""}` };
+  return { outcome: "dispatched", command: "run_script", output, truncated: output.length < raw.trim().length };
+}
+
 /** Keep connected inspection output useful without returning common credential forms verbatim. */
 export function redactUnityPlanningOutput(value: string): string {
   return value

package/src/unity-pipeline.ts

@@ -1,6 +1,7 @@
 import { realpath } from "node:fs/promises";
 import { projectPathsMatch } from "./unity-core";
-import { resolveUnityCliCommand, type UnityCliExecResult, type UnityCliExecutor, type UnityCliProjectCapabilities } from "./unity-cli";
+import { hasConsistentUnityTestCounts } from "./unity-artifact-inspection";
+import { redactUnityPlanningOutput, resolveUnityCliCommand, summarizeUnityCliText, unityCapabilityDiagnosticSuffix, type UnityCliExecResult, type UnityCliExecutor, type UnityCliProjectCapabilities } from "./unity-cli";
 
 /** Public limits are deliberately small enough that connected work cannot create an unbounded agent wait loop. */
 export const UNITY_PIPELINE_COMPILE_TIMEOUT_SECONDS = 180;
@@ -31,10 +32,17 @@ export type UnityPipelineOperationDetails = {
   testPlatform?: "EditMode" | "PlayMode";
   testFilter?: string;
   counts?: { total: number; passed?: number; failed: number; inconclusive?: number };
+  /** Bounded nonfatal Pipeline envelope guidance; never compiler-error evidence. */
+  warnings?: string[];
 };
 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[] };
+export type UnityPipelineTerminalTestEvidence = { state: "completed" | "failed" | "cancelled"; outcome: "uncertain" | "tests_failed" | "run_error" | "cancelled"; reason: string; elapsedSeconds: number; selection: { platform: "EditMode" | "PlayMode"; filter?: string }; correlation: Record<string, string>; observations: string[]; testRecords: UnityPipelineTestRecord[]; warnings: string[] };
+/** Terminal Pipeline evidence can be durable and inspectable without being passing evidence. */
+export class UnityPipelineTerminalTestEvidenceError extends Error {
+  constructor(readonly evidence: UnityPipelineTerminalTestEvidence) { super(evidence.reason); this.name = "UnityPipelineTerminalTestEvidenceError"; }
+}
 
 type RecordValue = Record<string, unknown>;
 type ParsedEnvelope = { result: RecordValue; outerSuccess: boolean; malformed?: string };
@@ -44,6 +52,8 @@ type NormalizedTest = {
   total?: number; passed?: number; failed?: number; inconclusive?: number; failures: string[];
   correlation: Record<string, string>;
   testRecords?: UnityPipelineTestRecord[];
+  testFailureEstablished: boolean;
+  runnerError: boolean;
 };
 
 type PipelineDependencies = {
@@ -72,6 +82,39 @@ function bounded(value: string, limit = UNITY_PIPELINE_MAX_STACK_CHARS): string
   const oneLine = value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
   return oneLine.length > limit ? `${oneLine.slice(0, limit - 1)}…` : oneLine;
 }
+function pipelineEnvelopeWarnings(output: string): string[] {
+  const outer = (() => { try { return record(JSON.parse(output)); } catch { return undefined; } })();
+  const data = record(outer?.data);
+  const entries = [outer?.warnings, data?.warnings].flatMap(value => Array.isArray(value) ? value.slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS) : []);
+  return entries.slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS).flatMap(entry => {
+    const item = record(entry); const message = string(field(item ?? {}, "message", "detail", "warning")) ?? string(entry);
+    return message ? [bounded(redactUnityPlanningOutput(message), 1_000)] : [];
+  });
+}
+function retainWarnings(warnings: string[], output: string): void {
+  for (const warning of pipelineEnvelopeWarnings(output)) {
+    if (warnings.length >= UNITY_PIPELINE_MAX_DIAGNOSTICS) break;
+    if (!warnings.includes(warning)) warnings.push(warning);
+  }
+}
+function warningText(warnings: string[]): string {
+  return warnings.length ? `\nPipeline warnings: ${warnings.join("; ")}` : "";
+}
+function pipelineFailureDiagnostic(response: UnityCliExecResult): string {
+  const raw = [response.stdout, response.stderr, response.error?.message].filter(Boolean).join("\n");
+  let message: string | undefined;
+  try {
+    const outer = record(JSON.parse(response.stdout)); const data = record(outer?.data);
+    const errors = Array.isArray(outer?.errors) ? outer?.errors : [];
+    const first = record(errors[0]);
+    const messages = [
+      string(field(first ?? {}, "code")), string(field(first ?? {}, "message", "detail")),
+      ...[data, outer].flatMap(item => ["error", "errordetails", "message"].map(key => string(field(item ?? {}, key)))),
+    ].filter((value): value is string => Boolean(value));
+    message = [...new Set(messages)].join("; ") || undefined;
+  } catch { /* retain bounded native raw fallback */ }
+  return summarizeUnityCliText(redactUnityPlanningOutput(message ?? raw), 1_000, 10);
+}
 function throwIfAborted(signal?: AbortSignal): void {
   if (signal?.aborted) throw new Error("Unity Pipeline operation aborted; its Editor operation may still be running.");
 }
@@ -102,8 +145,10 @@ export function parseUnityPipelineEnvelope(output: string): ParsedEnvelope {
   let outer: RecordValue | undefined;
   try { outer = record(JSON.parse(output)); } catch { return { result: {}, outerSuccess: false, malformed: "Unity Pipeline returned malformed JSON." }; }
   if (!outer) return { result: {}, outerSuccess: false, malformed: "Unity Pipeline returned a non-object JSON envelope." };
+  // Pipeline 0.6 may return the compact exec envelope { success, result, warnings }
+  // rather than the older CLI wrapper { success, data: { result } }.
   const data = record(outer.data);
-  const rawResult = data?.result ?? data;
+  const rawResult = data?.result ?? outer.result ?? data;
   if (typeof rawResult === "string") {
     try {
       const parsed = record(JSON.parse(rawResult));
@@ -148,22 +193,23 @@ function diagnostics(result: RecordValue): string[] {
   });
   return [...new Set(values)].slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS);
 }
-/** True only for Pipeline 0.5's explicit rejected outer envelope, before a main-thread command is dispatched. */
-export function isUnityPipelineInitialSettlingBusy(output: string): boolean {
-  let outer: RecordValue | undefined;
-  try { outer = record(JSON.parse(output)); } catch { return false; }
-  const data = record(outer?.data);
-  return outer?.success === false
-    && string(field(data ?? {}, "error"))?.toLowerCase() === "server busy"
-    && statusOf(data ?? {}) === "busy"
-    && field(data ?? {}, "retryable") === true;
+/**
+ * Do not retry generic busy envelopes. Pipeline 0.6 uses busy for modal dialogs as
+ * well as startup settling, and neither is distinguishable in the legacy CLI-shaped
+ * response. Retrying would blindly repeat a command blocked by a user-visible modal.
+ * A future retry must be wired only to a source-verified pre-dispatch discriminator.
+ */
+export function isUnityPipelineInitialSettlingBusy(_output: string): boolean {
+  return false;
 }
 
 export function normalizeUnityPipelineCompile(output: string): NormalizedCompile {
   const parsed = parseUnityPipelineEnvelope(output);
   if (parsed.malformed) return { state: "uncertain", diagnostics: [], failed: false };
   const compilerDiagnostics = diagnostics(parsed.result);
-  const failed = !parsed.outerSuccess || hasSemanticFailure(parsed.result) || compilerDiagnostics.length > 0;
+  let compilationFailed = false;
+  walk(parsed.result, item => { if (field(item, "compilationfailed") === true) compilationFailed = true; });
+  const failed = !parsed.outerSuccess || hasSemanticFailure(parsed.result) || compilationFailed || compilerDiagnostics.length > 0;
   const raw = statusOf(parsed.result);
   const state = failed || raw === "failed" || raw === "error" ? "failed" : raw === "up_to_date" || raw === "uptodate" ? "up_to_date"
     : raw === "triggered" ? "triggered" : raw === "compiling" || raw === "running" ? "compiling"
@@ -193,6 +239,9 @@ function testRecords(result: RecordValue): UnityPipelineTestRecord[] {
   });
   return values.slice(0, 2_000);
 }
+function isRecognizedFailedTestStatus(status: string): boolean {
+  return status.trim().toLowerCase() === "failed";
+}
 function testFailures(result: RecordValue): string[] {
   const values: string[] = [];
   walk(result, item => {
@@ -202,7 +251,7 @@ function testFailures(result: RecordValue): string[] {
       for (const entry of entries.slice(0, 200)) {
         const test = record(entry); if (!test) continue;
         const outcome = string(field(test, "result", "status", "outcome"))?.toLowerCase();
-        if (!outcome || /pass|success/.test(outcome)) continue;
+        if (!outcome || /^(?:passed|success)$/i.test(outcome)) continue;
         const name = string(field(test, "name", "fullname", "testname")) ?? "Unnamed test";
         const message = string(field(test, "message", "error", "failuremessage"));
         const stack = string(field(test, "stacktrace", "stack", "trace"));
@@ -232,19 +281,23 @@ function correlation(result: RecordValue): Record<string, string> {
 }
 export function normalizeUnityPipelineTest(output: string): NormalizedTest {
   const parsed = parseUnityPipelineEnvelope(output);
-  if (parsed.malformed) return { state: "uncertain", failures: [], correlation: {} };
+  if (parsed.malformed) return { state: "uncertain", failures: [], correlation: {}, testFailureEstablished: false, runnerError: false };
   const sum = summary(parsed.result);
   const total = number(field(sum ?? parsed.result, "total"));
   const passed = number(field(sum ?? parsed.result, "passed", "pass"));
   const failedCount = number(field(sum ?? parsed.result, "failed", "fail"));
   const inconclusive = number(field(sum ?? parsed.result, "inconclusive", "skipped"));
   const raw = statusOf(parsed.result);
-  const semanticFailed = !parsed.outerSuccess || hasSemanticFailure(parsed.result) || (failedCount ?? 0) > 0;
-  const state = semanticFailed || raw === "failed" || raw === "error" ? "failed" : raw === "cancelled" || raw === "canceled" ? "cancelled"
+  const records = testRecords(parsed.result);
+  const testFailureEstablished = (Number.isSafeInteger(failedCount) && (failedCount ?? 0) > 0) || records.some(test => isRecognizedFailedTestStatus(test.status));
+  const runnerError = !parsed.outerSuccess || raw === "failed" || raw === "error" || hasSemanticFailure(parsed.result);
+  // A reported active state remains active even when it carries partial records/counts.
+  const state = raw === "cancelled" || raw === "canceled" ? "cancelled"
     : 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), testRecords: testRecords(parsed.result) };
+        : raw === "completed" || raw === "complete" || raw === "success" ? testFailureEstablished || runnerError ? "failed" : "completed"
+          : testFailureEstablished || runnerError ? "failed" : "uncertain";
+  return { state, total, passed, failed: failedCount, inconclusive, failures: testFailures(parsed.result), correlation: correlation(parsed.result), testRecords: records, testFailureEstablished, runnerError };
 }
 
 function editorStopSucceeded(output: string): boolean {
@@ -363,7 +416,7 @@ async function dispatchMainThreadCommand(deps: PipelineDependencies, projectRoot
 
 async function requirePreflight(deps: PipelineDependencies, projectRoot: string, unityVersion: string, commands: string[], operation: "recompile" | "tests", signal: AbortSignal | undefined, deadline: number, now: () => number, allowAutonomousExitPlayMode = true): Promise<{ capabilities: UnityCliProjectCapabilities; exitedPlayMode: boolean; playModeHandling: UnityPipelinePlayModeHandling; scriptChangesWhilePlaying?: UnityScriptChangesWhilePlayingPolicy }> {
   const capabilities = await inspectWithDeadline(deps, projectRoot, unityVersion, signal, deadline, now, "preflight");
-  const error = capabilityError(capabilities, commands); if (error) throw new Error(error);
+  const error = capabilityError(capabilities, commands); if (error) throw new Error(error + unityCapabilityDiagnosticSuffix(capabilities));
   let editor = await executeCommand(deps, projectRoot, "editor_status", [], signal, deadline, now);
   if (editor.error) throw new Error("Unity Pipeline editor_status failed; operation not started.");
   let status = editorStatus(editor.stdout);
@@ -429,10 +482,18 @@ function checkCorrelation(expected: Record<string, string>, actual: Record<strin
   return Object.entries(expected).every(([key, value]) => !actual[key] || actual[key] === value);
 }
 function passingCounts(state: NormalizedTest): { total: number; passed: number; failed: number; inconclusive?: number } | undefined {
+  const summary = { total: state.total, passed: state.passed, failed: state.failed, inconclusive: state.inconclusive };
+  if (!hasConsistentUnityTestCounts(summary, state.testRecords ?? [])) return undefined;
+  if (state.testRecords?.some(test => !/^(?:passed|success)$/i.test(test.status))) return undefined;
   if (state.total === undefined || state.total <= 0 || state.passed === undefined || state.failed !== 0 || (state.inconclusive ?? 0) > 0) return undefined;
   if (state.passed + state.failed + (state.inconclusive ?? 0) !== state.total) return undefined;
   return { total: state.total, passed: state.passed, failed: state.failed, inconclusive: state.inconclusive };
 }
+function terminalEvidence(state: NormalizedTest, reason: string, request: UnityPipelineTestRequest, elapsedSeconds: number, warnings: string[]): UnityPipelineTerminalTestEvidenceError {
+  const outcome = state.state === "cancelled" ? "cancelled" : state.testFailureEstablished ? "tests_failed" : state.runnerError ? "run_error" : "uncertain";
+  const observations = [`terminal state=${state.state}`, `terminal outcome=${outcome}`, ...["total", "passed", "failed", "inconclusive"].flatMap(key => state[key as keyof Pick<NormalizedTest, "total" | "passed" | "failed" | "inconclusive">] === undefined ? [] : [`reported ${key}=${String(state[key as keyof Pick<NormalizedTest, "total" | "passed" | "failed" | "inconclusive">])}`]), ...Object.entries(state.correlation).map(([key, value]) => `correlation ${key}=${value}`)].slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS);
+  return new UnityPipelineTerminalTestEvidenceError({ state: state.state as "completed" | "failed" | "cancelled", outcome, reason, elapsedSeconds, selection: { platform: request.testPlatform, ...(request.testFilter ?? request.testCategory ? { filter: request.testFilter ?? request.testCategory } : {}) }, correlation: state.correlation, observations, testRecords: state.testRecords ?? [], warnings });
+}
 function elapsed(start: number, now: () => number): number { return Math.max(0, (now() - start) / 1000); }
 function timeoutMessage(operation: string): Error { return new Error(`Unity Pipeline ${operation} timed out; result is uncertain and may still be running. No cancellation, retry, or route switch was performed.`); }
 function ensureBeforeDeadline(deadline: number, now: () => number, operation: string): void {
@@ -450,11 +511,12 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
   ensureBeforeDeadline(deadline, now, "recompile before dispatch");
   throwIfAborted(signal);
   const dispatched = await dispatchMainThreadCommand(deps, projectRoot, "recompile", [], "recompile", signal, deadline, now, sleep);
-  if (dispatched.error) throw new Error("Unity Pipeline recompile dispatch failed; operation may not have started.");
+  if (dispatched.error) throw new Error(`Unity Pipeline recompile dispatch failed; operation may not have started.${pipelineFailureDiagnostic(dispatched) ? ` ${pipelineFailureDiagnostic(dispatched)}` : ""}`);
+  const dispatchWarnings = pipelineEnvelopeWarnings(dispatched.stdout);
   let state = normalizeUnityPipelineCompile(dispatched.stdout);
   if (state.state === "uncertain") throw new Error("Unity Pipeline recompile dispatch returned malformed or uncertain evidence; operation may have started.");
   if (state.state === "failed") throw new Error(`Unity recompile failed: ${state.diagnostics.join("; ") || "compiler failure reported"}`);
-  if (state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity scripts are up to date for ${projectRoot}; no compilation was triggered.`,  details: { projectRoot, operation: "recompile", terminalState: "up_to_date", elapsedSeconds: elapsed(start, now), compilationTriggered: false, ...playModeDetails(preflight) } };
+  if (state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity scripts are up to date for ${projectRoot}; no compilation was triggered.${warningText(dispatchWarnings)}`,   details: { projectRoot, operation: "recompile", terminalState: "up_to_date", elapsedSeconds: elapsed(start, now), compilationTriggered: false, ...(dispatchWarnings.length ? { warnings: dispatchWarnings } : {}), ...playModeDetails(preflight) } };
   for (let poll = 0; now() < deadline; poll += 1) {
     options.onUpdate?.(`Unity recompile ${state.state}; ${elapsed(start, now).toFixed(1)}s elapsed.`);
     const delay = Math.min(UNITY_PIPELINE_BACKOFF_SECONDS[Math.min(poll, UNITY_PIPELINE_BACKOFF_SECONDS.length - 1)]! * 1000, deadline - now());
@@ -467,9 +529,10 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
     const response = await executeCommand(deps, projectRoot, "recompile_status", [], signal, deadline, now);
     if (response.error) continue; // Domain reload can briefly disconnect the same exact copy.
     if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
+    retainWarnings(dispatchWarnings, response.stdout);
     state = normalizeUnityPipelineCompile(response.stdout);
     if (state.state === "failed") throw new Error(`Unity recompile failed: ${state.diagnostics.join("; ") || "compiler failure reported"}`);
-    if (state.state === "completed" || state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity recompile completed for ${projectRoot} in ${elapsed(start, now).toFixed(1)}s; 0 compiler errors.`,  details: { projectRoot, operation: "recompile", terminalState: state.state, elapsedSeconds: elapsed(start, now), compilationTriggered: true, ...playModeDetails(preflight) } };
+    if (state.state === "completed" || state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity recompile completed for ${projectRoot} in ${elapsed(start, now).toFixed(1)}s; 0 compiler errors.${warningText(dispatchWarnings)}`,  details: { projectRoot, operation: "recompile", terminalState: state.state, elapsedSeconds: elapsed(start, now), compilationTriggered: true, ...(dispatchWarnings.length ? { warnings: dispatchWarnings } : {}), ...playModeDetails(preflight) } };
     if (state.state === "uncertain") throw new Error("Unity Pipeline recompile status is malformed or uncertain; operation may still be running.");
   }
   throw timeoutMessage("recompile");
@@ -498,18 +561,19 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
   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.");
+  if (dispatched.error) throw new Error(`Unity Pipeline test dispatch failed; test run may not have started.${pipelineFailureDiagnostic(dispatched) ? ` ${pipelineFailureDiagnostic(dispatched)}` : ""}`);
+  const dispatchWarnings = pipelineEnvelopeWarnings(dispatched.stdout);
   let state = normalizeUnityPipelineTest(dispatched.stdout);
   if (state.state === "uncertain" || state.state === "inactive") throw new Error("Unity Pipeline test dispatch returned inactive, malformed, or uncertain evidence; test run may not have started.");
-  if (state.state === "failed" || state.state === "cancelled") throw new Error(`Unity ${request.testPlatform} tests failed: ${state.failures.join("; ") || state.state}.`);
   const requestedCorrelation = { mode: request.testPlatform, ...(request.testFilter ? { filter: request.testFilter } : {}) };
   if (!checkCorrelation(requestedCorrelation, state.correlation)) throw new Error("Unity Pipeline test dispatch reported a different mode or filter; operation state is uncertain.");
+  if (state.state === "failed" || state.state === "cancelled") throw terminalEvidence(state, `Unity ${request.testPlatform} tests ${state.state}: ${state.failures.join("; ") || state.state}.`, request, elapsed(start, now), dispatchWarnings);
   const expected = { ...requestedCorrelation, ...state.correlation };
   // Some Pipeline versions return a complete result directly from asynchronous dispatch.
   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 ?? request.testCategory, counts }, testRecords: state.testRecords };
+    if (!counts) throw terminalEvidence(state, "Unity test result is terminal but lacks passing evidence (consistent positive total, passed count, and reported zero failures).", request, elapsed(start, now), dispatchWarnings);
+    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.${warningText(dispatchWarnings)}`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter ?? request.testCategory, counts, ...(dispatchWarnings.length ? { warnings: dispatchWarnings } : {}) }, 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.`);
@@ -523,15 +587,16 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     const response = await executeCommand(deps, projectRoot, "test_status", [], signal, deadline, now);
     if (response.error) continue;
     if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
+    retainWarnings(dispatchWarnings, response.stdout);
     state = normalizeUnityPipelineTest(response.stdout);
     if (!checkCorrelation(expected, state.correlation)) throw new Error("Unity Pipeline test status was displaced by a different run; operation state is uncertain.");
-    if (state.state === "failed" || state.state === "cancelled") throw new Error(`Unity ${request.testPlatform} tests failed: ${state.failures.join("; ") || state.state}.`);
+    if (state.state === "failed" || state.state === "cancelled") throw terminalEvidence(state, `Unity ${request.testPlatform} tests ${state.state}: ${state.failures.join("; ") || state.state}.`, request, elapsed(start, now), dispatchWarnings);
     if (state.state === "uncertain") throw new Error("Unity Pipeline test status is malformed or uncertain; operation may still be running.");
     if (state.state === "inactive") throw new Error("Unity Pipeline test status became inactive before a terminal result; operation state is uncertain.");
     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 ?? request.testCategory, counts }, testRecords: state.testRecords };
+    if (!counts) throw terminalEvidence(state, "Unity test result is terminal but lacks passing evidence (consistent positive total, passed count, and reported zero failures).", request, elapsed(start, now), dispatchWarnings);
+    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.${warningText(dispatchWarnings)}`, details: { projectRoot, operation: "tests", terminalState: "completed", elapsedSeconds: elapsed(start, now), ...playModeDetails(preflight), testPlatform: request.testPlatform, testFilter: request.testFilter ?? request.testCategory, counts, ...(dispatchWarnings.length ? { warnings: dispatchWarnings } : {}) }, testRecords: state.testRecords };
   }
   throw timeoutMessage("tests");
 }

package/src/unity-tests.ts

@@ -60,6 +60,8 @@ export type NormalizedUnityTestResult = {
   tests: NormalizedUnityTest[];
   flakyTests?: Array<{ name: string; attempts: number }>;
   backendArtifacts?: Record<string, string>;
+  /** Bounded non-authoritative observations retained when terminal Pipeline evidence cannot establish a result. */
+  diagnostics?: string[];
 };
 
 export type UnityTestRouteRequirements = { requiresIsolation: boolean; reasons: string[] };
@@ -250,6 +252,7 @@ export function normalizeUnityTestResult(result: NormalizedUnityTestResult): Nor
     summary: Object.fromEntries(Object.entries(result.summary).flatMap(([key, value]) => numberOrUndefined(value) === undefined ? [] : [[key, numberOrUndefined(value)!]])),
     tests, ...(result.flakyTests ? { flakyTests: result.flakyTests.slice(0, UNITY_TEST_MAX_TESTS).map(item => ({ name: bound(item.name, 1_000) || "Unnamed test", attempts: Math.max(1, Math.floor(item.attempts)) })) } : {}),
     ...(Object.keys(artifacts).length ? { backendArtifacts: artifacts } : {}),
+    ...(result.diagnostics ? { diagnostics: result.diagnostics.slice(0, 8).flatMap(value => typeof value === "string" ? [bound(value, 1_000) || ""] : []).filter(Boolean) } : {}),
   };
 }