dd-trace 6.7.0 → 6.9.0

package/ci/test-optimization-validation/command-blocker.js

@@ -1,5 +1,10 @@
 'use strict'
 
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { BLOCKER_CATEGORIES } = require('./blocker-category')
+const { isProjectBuildArtifactPath } = require('./project-build-artifact')
 const { stripAnsi } = require('./test-output')
 
 const FILESYSTEM_PERMISSION_PATTERN = /\b(?:EACCES|EPERM|Operation not permitted|Permission denied)\b/i
@@ -8,22 +13,39 @@ const CONNECTION_REFUSED_PATTERN = /\bECONNREFUSED\b|\bconnection refused\b/i
 const NO_TESTS_FOUND_PATTERN =
   /\b(?:No test files? found|No tests? found|No test files? were found|0 tests? collected)\b/i
 const MODULE_OR_TRANSFORM_PATTERN =
-  /\b(?:Cannot find (?:module|package)|ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ERR_PACKAGE_PATH_NOT_EXPORTED|Package subpath\b[\s\S]*\bnot defined by "exports"|Could not resolve|transform failed)\b/i
+  /\b(?:Cannot find (?:module|package)|ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ERR_PACKAGE_PATH_NOT_EXPORTED|Package subpath\b[\s\S]+\bnot defined by "exports"|Could not resolve|transform failed)\b/i
+const BUILD_ARTIFACT_PATH_PATTERN = String.raw`(?:^|[\\/])(?:build|dist|generated)(?:[\\/]|['"])`
+const MISSING_ARTIFACT_MESSAGE_PATTERN =
+  '(?:Cannot find (?:module|package)|ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ENOENT|no such file or directory|' +
+  'is not found|does not exist|could not be found)'
+const BUILD_ARTIFACT_MISSING_PATTERN = new RegExp(
+  String.raw`(?:${MISSING_ARTIFACT_MESSAGE_PATTERN}[^\r\n]{0,500}${BUILD_ARTIFACT_PATH_PATTERN}|` +
+    String.raw`${BUILD_ARTIFACT_PATH_PATTERN}[^\r\n]{0,500}${MISSING_ARTIFACT_MESSAGE_PATTERN})`,
+  'im'
+)
+const FILE_PATH_REFERENCE_PATTERN = /(?:^|[\s('"`])((?:\.{1,2}[\\/]|[\\/]|[A-Za-z]:[\\/])[^'"`\s),;]*)/g
+const CUCUMBER_CONFIG_OPTION_UNSUPPORTED_PATTERN = /unknown option ['"]--config['"]/i
 const CYPRESS_BINARY_PATTERN =
-  /(?:Cypress executable not found|Cypress binary is missing|Cypress failed to start|Please reinstall Cypress)/i
+  /Cypress executable not found|Cypress binary is missing|Cypress failed to start|Please reinstall Cypress/i
 const PLAYWRIGHT_BROWSER_PATTERN = new RegExp(
-  String.raw`(?:browserType\.launch: Executable doesn't exist|` +
-  'Please run the following command to download new browsers|playwright install)',
+  String.raw`browserType\.launch: Executable doesn't exist|` +
+  'Please run the following command to download new browsers|playwright install',
   'i'
 )
 const PLAYWRIGHT_BROWSER_LAUNCH_PATTERN =
-  /(?:browserType\.launch: Failed to launch the browser process|bootstrap_check_in|MachPortRendezvous)/i
+  /Failed to launch the browser process|bootstrap_check_in|MachPortRendezvous/i
 const PLAYWRIGHT_BROWSER_ABORT_PATTERN =
   /(?:browserType\.launch: Target page, context or browser has been closed|Browser logs:)[\s\S]*?(?:signal=SIGABRT|Received signal 6|Abort trap: 6)/i
+const PUPPETEER_BROWSER_PATTERN =
+  /(?:Could not find (?:Chrome|Chromium)|Failed to launch the browser process|Troubleshooting:\s*https:\/\/pptr\.dev)/i
+const PUPPETEER_BROWSER_ABORT_PATTERN =
+  /Failed to launch the browser process[\s\S]*?(?:signal=SIGABRT|Received signal 6|Abort trap: 6)/i
+const CUCUMBER_BROWSER_FAILURE_PATTERN =
+  /(?:(?:browser|puppeteer|playwright|webdriver)[^\r\n]{0,160}\b(?:aborted|closed|crashed|failed|terminated|unavailable)\b|(?:Failed|Unable) to (?:connect to|launch|start) (?:the )?browser)/i
 const VITEST_BROWSER_PROVIDER_PATTERN =
-  /(?:Cannot find (?:module|package).*@vitest\/browser|@vitest\/browser-[^\s'"]+.*(?:missing|not (?:found|installed)))/i
+  /Cannot find (?:module|package).*@vitest\/browser|@vitest\/browser-[^\s'"].*(?:missing|not (?:found|installed))/i
 const RUNNER_COMMAND_NOT_FOUND_PATTERN =
-  /(?:command not found|is not recognized as an internal or external command|spawn [^\r\n]+ ENOENT)/i
+  /command not found|is not recognized as an internal or external command|spawn [^\r\n]+ ENOENT/i
 
 /**
  * Identifies toolchain and execution-environment failures that happen before tests start.
@@ -34,6 +56,7 @@ const RUNNER_COMMAND_NOT_FOUND_PATTERN =
  * @param {object} [options] classification options
  * @param {boolean} [options.browserRequired] whether the selected runner uses browser mode
  * @param {string} [options.framework] test framework identifier
+ * @param {string} [options.packageJson] approval-bound project package.json
  * @param {boolean} [options.testsRan] whether reliable test output was observed
  * @returns {object|undefined} structured blocker diagnosis
  */
@@ -41,6 +64,7 @@ function getCommandBlocker (result, options = {}) {
   const output = `${result.stdout || ''}\n${result.stderr || ''}`
   if (Array.isArray(result.missingRequiredEnvVars) && result.missingRequiredEnvVars.length > 0) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'project-command-environment-missing',
       summary: 'The selected project test command requires approved non-secret environment variables that are not ' +
         'available in the validator process. No Test Optimization conclusion was reached.',
@@ -50,14 +74,29 @@ function getCommandBlocker (result, options = {}) {
       toolchainBlocked: true,
     }
   }
+  if (options.framework === 'cucumber' && result.exitCode !== 0 &&
+    CUCUMBER_CONFIG_OPTION_UNSUPPORTED_PATTERN.test(output)) {
+    return {
+      blockerCategory: BLOCKER_CATEGORIES.VALIDATOR_LIMITATION,
+      kind: 'cucumber-config-isolation-unsupported',
+      summary: 'The installed Cucumber CLI rejected the validator-owned configuration-isolation option. This is a ' +
+        'validator compatibility limitation, not a project test or Test Optimization failure.',
+      recommendation: 'Report this Cucumber version to validator engineering. Use the static CI audit and do not ' +
+        'change the customer profile, command, or working directory to bypass this limitation.',
+      signals: getMatchingLines(output, CUCUMBER_CONFIG_OPTION_UNSUPPORTED_PATTERN),
+      validatorBlocked: true,
+    }
+  }
   if (LOCAL_SOCKET_PATTERN.test(output) && FILESYSTEM_PERMISSION_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.EXECUTION_ENVIRONMENT_BLOCKED,
       kind: 'local-test-socket-blocked',
       summary: 'The selected project test could not start its localhost listener in this execution environment. ' +
         'The offline Datadog validator did not open this socket. No Test Optimization conclusion was reached.',
       recommendation: 'Run the same approved plan in an environment that permits the project test to use its ' +
-        'required localhost socket. This may require normal project-test permissions. Do not request broader ' +
-        'permissions automatically or interpret this as a Test Optimization failure.',
+        'required localhost socket. Use the unchanged command and SHA from execution-plan.md. This may require ' +
+        'normal project-test permissions. Do not request broader permissions automatically or interpret this as a ' +
+        'Test Optimization failure.',
       signals: getMatchingLines(
         output,
         /127\.0\.0\.1|localhost|listen|EACCES|EPERM|Operation not permitted|Permission denied/i
@@ -68,6 +107,7 @@ function getCommandBlocker (result, options = {}) {
   if (options.framework === 'cypress' && result.exitCode !== 0 &&
     CONNECTION_REFUSED_PATTERN.test(output) && LOCAL_SOCKET_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'cypress-application-unavailable',
       summary: 'The selected Cypress spec could not connect to its localhost application. Discovery does not start ' +
         'customer services, so no Test Optimization conclusion was reached.',
@@ -79,6 +119,7 @@ function getCommandBlocker (result, options = {}) {
   }
   if (options.testsRan !== true && NO_TESTS_FOUND_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.VALIDATOR_LIMITATION,
       kind: 'no-tests-collected',
       summary: 'The selected representative was not collected by the project test runner. No Test Optimization ' +
         'conclusion was reached.',
@@ -91,21 +132,24 @@ function getCommandBlocker (result, options = {}) {
   }
 
   const browserMode = options.framework === 'playwright' ||
+    (options.framework === 'cucumber' && options.browserRequired === true) ||
     (options.framework === 'vitest' && options.browserRequired === true)
   if (browserMode &&
     result.exitCode !== 0 &&
     PLAYWRIGHT_BROWSER_LAUNCH_PATTERN.test(output) && FILESYSTEM_PERMISSION_PATTERN.test(output)) {
-    const runner = options.framework === 'vitest' ? 'Vitest browser mode' : 'Playwright'
+    const runner = getBrowserRunnerName(options.framework)
     return {
+      blockerCategory: BLOCKER_CATEGORIES.EXECUTION_ENVIRONMENT_BLOCKED,
       kind: `${options.framework}-browser-launch-blocked`,
-      summary: `${runner} needs to launch the project browser, but the current agent sandbox denied that launch. ` +
+      summary: `${runner} needs to launch the project browser, but the current execution environment denied that ` +
+        'launch. ' +
         'No Test Optimization conclusion was reached.',
       recommendation: 'Retry the same approved plan from a host shell or another environment where the installed ' +
-        'project browser can launch. Do not request broader permissions automatically or change the command, ' +
-        'approval file, or approval SHA.',
+        'project browser can launch. Use the unchanged command and SHA from execution-plan.md. Do not request ' +
+        'broader permissions automatically or change the command, approval file, or approval SHA.',
       signals: getMatchingLines(
         output,
-        /browserType\.launch|bootstrap_check_in|MachPortRendezvous|EACCES|EPERM|Operation not permitted|Permission denied/i
+        /Failed to launch the browser process|bootstrap_check_in|MachPortRendezvous|EACCES|EPERM|Operation not permitted|Permission denied/i
       ),
       blockedByExecutionEnvironment: true,
     }
@@ -114,6 +158,7 @@ function getCommandBlocker (result, options = {}) {
   if (options.framework === 'playwright' && result.exitCode !== 0 &&
     PLAYWRIGHT_BROWSER_ABORT_PATTERN.test(stripAnsi(output))) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.CLEAN_TEST_FAILED,
       kind: 'playwright-browser-process-aborted',
       summary: 'A browser launched by Playwright aborted before the selected tests could produce reliable results. ' +
         'The available evidence does not identify whether the browser/runtime setup, the project, the execution ' +
@@ -129,9 +174,28 @@ function getCommandBlocker (result, options = {}) {
     }
   }
 
+  if (options.framework === 'cucumber' && options.browserRequired === true && result.exitCode !== 0 &&
+    PUPPETEER_BROWSER_ABORT_PATTERN.test(stripAnsi(output))) {
+    return {
+      blockerCategory: BLOCKER_CATEGORIES.CLEAN_TEST_FAILED,
+      kind: 'cucumber-browser-process-aborted',
+      summary: 'A browser launched by the selected Cucumber support code aborted before a reliable scenario result ' +
+        'was observed. No Test Optimization conclusion was reached.',
+      recommendation: 'Run the same approved plan where the project\'s normal Cucumber browser tests can launch. ' +
+        'Collect the browser and operating-system crash diagnostics if it still fails; do not treat this result as ' +
+        'a Test Optimization failure.',
+      signals: getMatchingLines(
+        output,
+        /Failed to launch the browser process|signal=SIGABRT|Received signal 6|Abort trap: 6/i
+      ),
+      localRuntimeBlocked: true,
+    }
+  }
+
   if (options.framework === 'cypress' && result.exitCode !== 0 &&
     options.testsRan !== true && CYPRESS_BINARY_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'cypress-runtime-missing',
       summary: 'The Cypress npm package is installed, but its application binary is missing or could not start. ' +
         'No Test Optimization conclusion was reached.',
@@ -143,17 +207,24 @@ function getCommandBlocker (result, options = {}) {
   }
 
   if (browserMode && result.exitCode !== 0 && options.testsRan !== true &&
-    PLAYWRIGHT_BROWSER_PATTERN.test(output)) {
+    (PLAYWRIGHT_BROWSER_PATTERN.test(output) || PUPPETEER_BROWSER_PATTERN.test(output))) {
     const vitestBrowser = options.framework === 'vitest' && options.browserRequired === true
+    const cucumberBrowser = options.framework === 'cucumber'
+    const browserPattern = cucumberBrowser ? PUPPETEER_BROWSER_PATTERN : PLAYWRIGHT_BROWSER_PATTERN
     return {
-      kind: vitestBrowser ? 'vitest-browser-provider-missing' : 'playwright-browser-missing',
-      summary: `${vitestBrowser ? 'Vitest browser mode' : 'Playwright Test'} is installed, but the selected project ` +
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
+      kind: vitestBrowser
+        ? 'vitest-browser-provider-missing'
+        : cucumberBrowser
+          ? 'cucumber-browser-missing'
+          : 'playwright-browser-missing',
+      summary: `${getBrowserRunnerName(options.framework)} is installed, but the selected project ` +
         'test requires a browser binary or provider that is not installed. ' +
         'No Test Optimization conclusion was reached.',
-      recommendation: `Complete the project's normal ${vitestBrowser ? 'Vitest browser' : 'Playwright browser'} ` +
-        'setup, then render and approve a fresh ' +
+      recommendation: `Complete the project's normal ${getBrowserRunnerName(options.framework)} setup, then render ` +
+        'and approve a fresh ' +
         'validation plan. The validator does not download browsers automatically.',
-      signals: getMatchingLines(output, PLAYWRIGHT_BROWSER_PATTERN),
+      signals: getMatchingLines(output, browserPattern),
       toolchainBlocked: true,
     }
   }
@@ -161,6 +232,7 @@ function getCommandBlocker (result, options = {}) {
   if (result.exitCode !== 0 && options.testsRan !== true && options.framework === 'vitest' &&
     options.browserRequired === true && VITEST_BROWSER_PROVIDER_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'vitest-browser-provider-missing',
       summary: 'Vitest browser mode could not load its configured browser provider. Local Test Optimization ' +
         'compatibility was not tested. No Test Optimization conclusion was reached.',
@@ -173,6 +245,7 @@ function getCommandBlocker (result, options = {}) {
 
   if (result.exitCode !== 0 && options.testsRan !== true && RUNNER_COMMAND_NOT_FOUND_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'test-runner-command-missing',
       summary: 'The selected project test command could not find its test-runner executable, so local Test ' +
         'Optimization compatibility was not tested. No Test Optimization conclusion was reached.',
@@ -183,8 +256,25 @@ function getCommandBlocker (result, options = {}) {
     }
   }
 
+  const projectRoot = typeof options.packageJson === 'string' ? path.dirname(options.packageJson) : undefined
+  if (result.exitCode !== 0 && hasMissingProjectBuildArtifact(output, projectRoot)) {
+    const buildScript = getBuildScript(options.packageJson)
+    return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
+      kind: 'project-build-artifact-missing',
+      summary: 'The selected test requires a conventional build or generated output that is missing. The validator ' +
+        'does not run project build commands, so no Test Optimization conclusion was reached.',
+      recommendation: `Complete the project's normal build workflow${
+        buildScript ? `; package.json declares "build": ${JSON.stringify(buildScript)}` : ''
+      }. Confirm the selected test passes normally, then render and approve a fresh validation plan.`,
+      signals: getMatchingLines(output, BUILD_ARTIFACT_MISSING_PATTERN),
+      blockedByProjectSetup: true,
+    }
+  }
+
   if (result.exitCode !== 0 && options.testsRan !== true && MODULE_OR_TRANSFORM_PATTERN.test(output)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
       kind: 'project-command-initialization-failed',
       summary: 'The selected project test command failed during module resolution, transformation, or runner ' +
         'initialization before a reliable test result was observed. No Test Optimization conclusion was reached.',
@@ -197,6 +287,7 @@ function getCommandBlocker (result, options = {}) {
 
   if (options.framework === 'cypress' && result.exitCode === 134 && options.testsRan !== true) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.CLEAN_TEST_FAILED,
       kind: 'cypress-process-aborted',
       summary: 'Cypress exited with code 134 before any test result was observed. The available evidence does not ' +
         'identify whether Cypress, its browser/runtime setup, the project, or the execution environment caused the ' +
@@ -211,6 +302,54 @@ function getCommandBlocker (result, options = {}) {
       localRuntimeBlocked: true,
     }
   }
+
+  if (options.framework === 'cucumber' && options.browserRequired === true &&
+    result.exitCode !== 0 && options.testsRan !== true &&
+    CUCUMBER_BROWSER_FAILURE_PATTERN.test(output)) {
+    return {
+      blockerCategory: BLOCKER_CATEGORIES.CLEAN_TEST_FAILED,
+      kind: 'cucumber-browser-execution-incomplete',
+      summary: 'The selected Cucumber scenario uses browser-backed support code and exited before a reliable ' +
+        'scenario result was observed. A secondary Cucumber formatter exception is not enough to identify the root ' +
+        'cause. No Test Optimization conclusion was reached.',
+      recommendation: 'Run the same approved plan where the project\'s normal Cucumber browser tests can launch, ' +
+        'then create a fresh plan. If it still fails, preserve the earliest browser or project error rather than ' +
+        'treating a later formatter exception as the cause.',
+      signals: getMatchingLines(
+        output,
+        /Failed to launch|Received signal|TypeError|Cannot read|browser|puppeteer|playwright/i
+      ),
+      localRuntimeBlocked: true,
+    }
+  }
+}
+
+function hasMissingProjectBuildArtifact (output, projectRoot) {
+  for (const line of output.split(/\r?\n/)) {
+    if (!BUILD_ARTIFACT_MISSING_PATTERN.test(line)) continue
+    for (const match of line.matchAll(FILE_PATH_REFERENCE_PATTERN)) {
+      if (isProjectBuildArtifactPath(match[1], projectRoot)) return true
+    }
+  }
+  return false
+}
+
+function getBuildScript (packageJson) {
+  if (typeof packageJson !== 'string') return
+  try {
+    const stat = fs.statSync(packageJson)
+    if (!stat.isFile() || stat.size > 512 * 1024) return
+    const script = JSON.parse(fs.readFileSync(packageJson, 'utf8'))?.scripts?.build
+    if (typeof script !== 'string' || !script.trim() || Buffer.byteLength(script) > 500 ||
+      /[\0\r\n]/.test(script)) return
+    return script.trim()
+  } catch {}
+}
+
+function getBrowserRunnerName (framework) {
+  if (framework === 'cucumber') return 'Cucumber browser support'
+  if (framework === 'vitest') return 'Vitest browser mode'
+  return 'Playwright Test'
 }
 
 /**

package/ci/test-optimization-validation/command-output-policy.js

@@ -3,6 +3,8 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
+const { createValidationBlocker } = require('./validation-blocker')
+
 /**
  * Returns command-created paths that must be declared and removed after validation.
  *
@@ -32,10 +34,14 @@ function prepareCommandOutputs ({ command, artifactRoot, repositoryRoot }) {
   }
   for (const outputPath of outputPaths) {
     if (pathExists(outputPath)) {
-      throw new Error(
+      throw createValidationBlocker(
         `Command output path already exists and will not be moved or overwritten: ${outputPath}. ` +
-        'The validator will not delete pre-existing output. Inspect and remove it manually, or choose a fresh ' +
-        'output path, then render a new approval plan.'
+        'The validator will not delete pre-existing output.',
+        {
+          kind: 'command-output-exists',
+          recommendation: `Inspect ${outputPath}. Remove it manually only if it is disposable validator or test ` +
+            'output, or choose a fresh output path, then render and approve a fresh plan.',
+        }
       )
     }
     states.push({
@@ -71,21 +77,21 @@ function cleanupCommandOutputs (states) {
  *
  * @param {string} outputPath output path
  * @param {string} repositoryRoot repository root
- * @returns {{path: string, dev: number, ino: number}[]} parent identities
+ * @returns {{path: string, dev: bigint, ino: bigint}[]} parent identities
  */
 function captureExistingParentIdentities (outputPath, repositoryRoot) {
   const identities = []
   const relative = path.relative(repositoryRoot, path.dirname(outputPath))
   let current = repositoryRoot
   for (const segment of relative ? relative.split(path.sep) : []) {
-    const stat = fs.lstatSync(current)
+    const stat = fs.lstatSync(current, { bigint: true })
     assertRegularDirectory(stat, current)
     identities.push({ path: current, dev: stat.dev, ino: stat.ino })
     current = path.join(current, segment)
     if (!pathExists(current)) return identities
   }
 
-  const stat = fs.lstatSync(current)
+  const stat = fs.lstatSync(current, { bigint: true })
   assertRegularDirectory(stat, current)
   identities.push({ path: current, dev: stat.dev, ino: stat.ino })
   return identities
@@ -98,7 +104,7 @@ function captureExistingParentIdentities (outputPath, repositoryRoot) {
  */
 function assertOutputParentsUnchanged (state) {
   for (const identity of state.parentIdentities) {
-    const stat = fs.lstatSync(identity.path)
+    const stat = fs.lstatSync(identity.path, { bigint: true })
     assertRegularDirectory(stat, identity.path)
     if (stat.dev !== identity.dev || stat.ino !== identity.ino) {
       throw new Error(`Refusing command output cleanup because a parent directory changed: ${identity.path}`)
@@ -118,7 +124,7 @@ function assertOutputParentsUnchanged (state) {
 /**
  * Refuses symbolic links and non-directory parent components.
  *
- * @param {fs.Stats} stat path status
+ * @param {fs.Stats | fs.BigIntStats} stat path status
  * @param {string} directory directory path
  */
 function assertRegularDirectory (stat, directory) {

package/ci/test-optimization-validation/command-runner.js

@@ -522,7 +522,7 @@ function buildOfflineCaptureEnv ({ fixture, outputRoot }) {
  * @param {object} input offline validation inputs
  * @param {{manifestPath: string}} input.fixture authoritative cache fixture
  * @param {string} input.outputRoot pre-created payload output root
- * @returns {NodeJS.ProcessEnv} validation transport environment
+ * @returns {typeof process.env} validation transport environment
  */
 function buildOfflineValidationEnv ({ fixture, outputRoot }) {
   return {
@@ -551,15 +551,17 @@ function buildOfflineValidationEnv ({ fixture, outputRoot }) {
  * Rejects command-local assignments that can bypass validator-controlled offline routing.
  *
  * @param {object} command command to execute
- * @param {NodeJS.ProcessEnv} env validator environment overrides
+ * @param {typeof process.env} env validator environment overrides
  */
 function assertNoInlineValidationEnvOverrides (command, env) {
   if (!env[VALIDATION_MODE_ENV]) return
-  for (const name of Object.keys(command.env || {})) {
-    const normalized = process.platform === 'win32' ? name.toUpperCase() : name
-    if (VALIDATION_RESERVED_ENV_NAMES.some(reserved => environmentNamesEqual(reserved, name)) ||
-      isDatadogEnvironmentName(name) || normalized.startsWith('OTEL_')) {
-      throw new Error(`Direct-runner adapter must not override validator-controlled environment variable ${name}.`)
+  if (command.env) {
+    for (const name of Object.keys(command.env)) {
+      const normalized = process.platform === 'win32' ? name.toUpperCase() : name
+      if (VALIDATION_RESERVED_ENV_NAMES.some(reserved => environmentNamesEqual(reserved, name)) ||
+        isDatadogEnvironmentName(name) || normalized.startsWith('OTEL_')) {
+        throw new Error(`Direct-runner adapter must not override validator-controlled environment variable ${name}.`)
+      }
     }
   }
 }

package/ci/test-optimization-validation/environment.js

@@ -63,8 +63,10 @@ function setEnvironmentValue (environment, name, value, platform = process.platf
  * @returns {void}
  */
 function mergeEnvironment (target, source, platform = process.platform) {
-  for (const [name, value] of Object.entries(source || {})) {
-    setEnvironmentValue(target, name, value, platform)
+  if (source) {
+    for (const [name, value] of Object.entries(source)) {
+      setEnvironmentValue(target, name, value, platform)
+    }
   }
 }
 

package/ci/test-optimization-validation/executable.js

@@ -40,19 +40,21 @@ function getResolvedExecutable (command) {
  */
 function bindManifestExecutables (manifest) {
   const identities = []
-  for (const framework of manifest.frameworks || []) {
-    if (framework.status !== 'runnable') continue
-    const command = getManifestCommands({ frameworks: [framework] })[0]?.[1]
-    try {
-      const identity = getCommandExecutableIdentity(command, manifest.repository.root)
-      bindApprovedExecutable(framework.validation, identity)
-      identities.push({ id: `framework:${framework.id}`, ...identity })
-    } catch (error) {
-      identities.push({
-        id: `framework:${framework.id}`,
-        unavailable: true,
-        reason: error?.message || String(error),
-      })
+  if (manifest.frameworks) {
+    for (const framework of manifest.frameworks) {
+      if (framework.status !== 'runnable') continue
+      const command = getManifestCommands({ frameworks: [framework] })[0]?.[1]
+      try {
+        const identity = getCommandExecutableIdentity(command, manifest.repository.root)
+        bindApprovedExecutable(framework.validation, identity)
+        identities.push({ id: `framework:${framework.id}`, ...identity })
+      } catch (error) {
+        identities.push({
+          id: `framework:${framework.id}`,
+          unavailable: true,
+          reason: error?.message || String(error),
+        })
+      }
     }
   }
   return identities

package/ci/test-optimization-validation/execution-lock.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { createFileSafely } = require('./safe-files')
+const { createValidationBlocker } = require('./validation-blocker')
+
+const EXECUTION_LOCK_FILENAME = '.dd-test-optimization-validation.lock'
+
+function getExecutionLockPath (out) {
+  return path.join(path.resolve(out), EXECUTION_LOCK_FILENAME)
+}
+
+// Locks are never reclaimed automatically; only the creator may release the exact file identity.
+function acquireExecutionLock ({ out, approvedPlanSha256 }) {
+  const lockPath = getExecutionLockPath(out)
+  const content = `${JSON.stringify({
+    approvedPlanSha256,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  }, null, 2)}\n`
+  try {
+    createFileSafely(out, lockPath, content, 'validation execution lock')
+  } catch (error) {
+    if (error.code === 'EEXIST') throw getExistingLockError(lockPath)
+    throw error
+  }
+
+  const stat = fs.lstatSync(lockPath, { bigint: true })
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(`Validation execution lock is not a regular file: ${lockPath}`)
+  }
+  return { dev: stat.dev, ino: stat.ino, path: lockPath }
+}
+
+function releaseExecutionLock (lock) {
+  let stat
+  try {
+    stat = fs.lstatSync(lock.path, { bigint: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Validation execution lock disappeared before safe cleanup: ${lock.path}`)
+    }
+    throw error
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== lock.dev || stat.ino !== lock.ino) {
+    throw new Error(`Refusing to remove a changed validation execution lock: ${lock.path}`)
+  }
+  fs.unlinkSync(lock.path)
+}
+
+function getExistingLockError (lockPath) {
+  return createValidationBlocker(
+    `Another validation may be active, or an interrupted run left its execution lock: ${lockPath}.`,
+    {
+      kind: 'execution-lock-exists',
+      recommendation: `Inspect ${lockPath}. Remove only that lock after confirming no validation process is active, ` +
+        'then render and approve a fresh plan.',
+      suppressReport: true,
+    }
+  )
+}
+
+module.exports = {
+  EXECUTION_LOCK_FILENAME,
+  acquireExecutionLock,
+  getExecutionLockPath,
+  releaseExecutionLock,
+}

package/ci/test-optimization-validation/framework-adapters/cucumber-validation.json

@@ -0,0 +1,3 @@
+{
+  "default": {}
+}