@aefree/pi-unity 0.13.0 → 0.15.0

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

@@ -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. 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 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-artifact-profile.ts

@@ -24,7 +24,7 @@ const OWNER = Object.freeze({
  * metadata remains project-owned and schema-open.
  */
 export function createUnityArtifactProfileV1(): ArtifactProfileV1 {
-  return Object.freeze({
+  return Object.freeze<ArtifactProfileV1>({
     contractVersion: 1,
     id: UNITY_ARTIFACT_PROFILE_ID_V1,
     kind: "artifact-profile",

package/src/unity-cli.ts

@@ -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;
@@ -68,7 +81,7 @@ export type UnityCliProjectCapabilities = {
 export type UnityCliExecResult = {
   stdout: string;
   stderr: string;
-  error?: Error & { code?: string | number; signal?: string | null };
+  error?: Error & { code?: string | number | null; signal?: string | null; killed?: boolean };
 };
 
 /** Injectable seam for deterministic capability and planning-dispatch tests. */
@@ -196,9 +209,9 @@ const execFileCollect: UnityCliExecutor = (command, args, options = {}) => {
   return new Promise((resolve) => {
     execFile(command, args, { timeout: options.timeout ?? UNITY_CLI_VERSION_TIMEOUT_MS, signal: options.signal, windowsHide: true }, (error, stdout, stderr) => {
       resolve({
-        stdout: typeof stdout === "string" ? stdout : stdout.toString(),
-        stderr: typeof stderr === "string" ? stderr : stderr.toString(),
-        error: error as UnityCliExecResult["error"],
+        stdout,
+        stderr,
+        error: error ?? undefined,
       });
     });
   });
@@ -346,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);
@@ -366,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,
   };
 }
 
@@ -428,8 +479,16 @@ 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;
+  const error = result.error;
   return error?.code === "ETIMEDOUT" || error?.killed === true || error?.signal === "SIGTERM";
 }
 
@@ -511,6 +570,8 @@ export async function inspectUnityCliProjectCapabilities(
   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";
@@ -522,7 +583,9 @@ 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);
   const listPayload = parseJsonObject(listResult.stdout);
   const commandDiagnostics = cliEnvelopeDiagnostics(listPayload);
@@ -533,12 +596,16 @@ export async function inspectUnityCliProjectCapabilities(
     // 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;
@@ -569,6 +636,8 @@ 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 =
@@ -624,6 +693,20 @@ function runScriptCommandFailure(output: string): "malformed" | "failure" | unde
   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";
@@ -691,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." };
   }
@@ -706,13 +795,16 @@ export async function dispatchUnityPlanningInspection(
   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");

package/src/unity-file-discovery-filter.ts

@@ -14,7 +14,7 @@ export const UNITY_EXACT_GENERATED_ROOT_BYPASSED_CODE = "unity_exact_generated_r
 export const UNITY_GENERATED_DIRECTORIES = Object.freeze(["Library", "Temp", "Logs", "obj", "Build", "Builds", "UserSettings", ".vs"] as const);
 
 export function createUnityFileDiscoveryFilterV1(): FileDiscoveryFilterV1 {
-  return Object.freeze({
+  return Object.freeze<FileDiscoveryFilterV1>({
     contractVersion: 1,
     id: UNITY_FILE_DISCOVERY_FILTER_ID_V1,
     kind: "file-discovery-filter",

package/src/unity-pipeline.ts

@@ -1,5 +1,6 @@
 import { realpath } from "node:fs/promises";
 import { projectPathsMatch } from "./unity-core";
+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. */
@@ -37,6 +38,11 @@ export type UnityPipelineOperationDetails = {
 export type UnityPipelineTestRecord = { name: string; status: string; durationSeconds?: number; message?: string; stackTrace?: string };
 /** testRecords are terminal evidence for the caller's durable artifact only; do not expose them in tool details. */
 export type UnityPipelineOperationResult = { text: string; details: UnityPipelineOperationDetails; testRecords?: UnityPipelineTestRecord[] };
+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 };
@@ -46,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 = {
@@ -199,7 +207,9 @@ 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"
@@ -229,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 => {
@@ -238,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"));
@@ -268,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 {
@@ -465,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 {
@@ -540,14 +565,14 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
   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).");
+    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) {
@@ -565,12 +590,12 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     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).");
+    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-projects.ts

@@ -1,3 +1,4 @@
+import type { Dirent } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseUnityVersionText, resolveAbsolutePath } from "./unity-core";
@@ -135,7 +136,7 @@ export async function discoverUnityProjects(
       continue;
     }
 
-    let entries: fs.Dirent[] = [];
+    let entries: Dirent[] = [];
     try {
       entries = await fs.readdir(next.dir, { withFileTypes: true });
     } catch {