dd-trace 6.7.0 → 6.9.0

package/ci/test-optimization-validation/manifest-schema.js

@@ -3,6 +3,7 @@
 const path = require('node:path')
 
 const { getArtifactId } = require('./artifact-id')
+const { BLOCKER_CATEGORY_VALUES } = require('./blocker-category')
 const {
   MAX_GENERATED_FILES,
   getGeneratedFileContentError,
@@ -111,6 +112,12 @@ function validateFrameworks (manifest, errors) {
     requiredString(framework, 'id', prefix, errors)
     requiredString(framework, 'framework', prefix, errors)
     enumString(framework, 'status', STATUSES, prefix, errors)
+    if (framework.blockerCategory !== undefined &&
+      !BLOCKER_CATEGORY_VALUES.has(framework.blockerCategory)) {
+      errors.push(
+        `${prefix}.blockerCategory must be one of ${[...BLOCKER_CATEGORY_VALUES].join(', ')} when provided.`
+      )
+    }
     requiredObject(framework, 'project', prefix, errors)
     rejectExecutionFields(framework, prefix, errors)
 
@@ -132,6 +139,12 @@ function validateFrameworks (manifest, errors) {
     validateCiWiring(manifest.repository?.root, framework.ciWiring, `${prefix}.ciWiring`, errors)
 
     if (framework.status === 'runnable') {
+      if (typeof framework.allCandidatesRequireLocalSocket !== 'boolean') {
+        errors.push(`${prefix}.allCandidatesRequireLocalSocket must be a boolean.`)
+      }
+      if (typeof framework.buildArtifactRequired !== 'boolean') {
+        errors.push(`${prefix}.buildArtifactRequired must be a boolean.`)
+      }
       validateRunnableFramework(manifest.repository?.root, framework, prefix, generatedPaths, errors)
     } else {
       for (const field of ['validation', 'preflight', 'generatedTestStrategy']) {
@@ -198,12 +211,13 @@ function validateRunnableFramework (repositoryRoot, framework, prefix, generated
   }
   containedPath(repositoryRoot, validation.runner, `${prefix}.validation.runner`, errors)
   containedPath(repositoryRoot, validation.testFile, `${prefix}.validation.testFile`, errors)
+  validateFallbackTests(repositoryRoot, validation, `${prefix}.validation`, errors)
   const runnerArgsError = getRunnerArgsError(framework.framework, validation.runnerArgs)
   if (runnerArgsError) errors.push(`${prefix}.validation.runnerArgs ${runnerArgsError}.`)
   if (validation.omittedRunnerOptions !== undefined) {
     validateStringArray(validation.omittedRunnerOptions, `${prefix}.validation.omittedRunnerOptions`, errors)
     for (const option of Array.isArray(validation.omittedRunnerOptions) ? validation.omittedRunnerOptions : []) {
-      if (!['--run', '--typecheck'].includes(option)) {
+      if (!['-R', '--reporter', '--run', '--typecheck'].includes(option)) {
         errors.push(`${prefix}.validation.omittedRunnerOptions contains unsupported option ${option}.`)
       }
     }
@@ -225,21 +239,23 @@ function validateRunnableFramework (repositoryRoot, framework, prefix, generated
     if (runnerInputError) errors.push(`${prefix}.validation runner configuration ${runnerInputError}.`)
   }
   validateStringArray(validation.requiredEnvVars, `${prefix}.validation.requiredEnvVars`, errors)
-  for (const name of validation.requiredEnvVars || []) {
-    if (!ENV_NAME_PATTERN.test(name)) {
-      errors.push(`${prefix}.validation.requiredEnvVars contains an invalid environment name.`)
-    }
-    if (/^(?:DD_|DATADOG_|OTEL_|NODE_OPTIONS$|TS_NODE_PROJECT$)/i.test(name)) {
-      errors.push(
-        `${prefix}.validation.requiredEnvVars must not inherit Datadog, OpenTelemetry, NODE_OPTIONS, or ` +
-          'TS_NODE_PROJECT.'
-      )
-    }
-    if (SECRET_ENV_PATTERN.test(name)) {
-      errors.push(`${prefix}.validation.requiredEnvVars must not inherit secret-like environment variables.`)
-    }
-    if (EXECUTION_ENV_PATTERN.test(name)) {
-      errors.push(`${prefix}.validation.requiredEnvVars must not inherit executable-loading environment variables.`)
+  if (validation.requiredEnvVars) {
+    for (const name of validation.requiredEnvVars) {
+      if (!ENV_NAME_PATTERN.test(name)) {
+        errors.push(`${prefix}.validation.requiredEnvVars contains an invalid environment name.`)
+      }
+      if (/^(?:DD_|DATADOG_|OTEL_|NODE_OPTIONS$|TS_NODE_PROJECT$)/i.test(name)) {
+        errors.push(
+          `${prefix}.validation.requiredEnvVars must not inherit Datadog, OpenTelemetry, NODE_OPTIONS, or ` +
+            'TS_NODE_PROJECT.'
+        )
+      }
+      if (SECRET_ENV_PATTERN.test(name)) {
+        errors.push(`${prefix}.validation.requiredEnvVars must not inherit secret-like environment variables.`)
+      }
+      if (EXECUTION_ENV_PATTERN.test(name)) {
+        errors.push(`${prefix}.validation.requiredEnvVars must not inherit executable-loading environment variables.`)
+      }
     }
   }
   if (!Number.isInteger(validation.timeoutMs) || validation.timeoutMs < 1 || validation.timeoutMs > MAX_TIMEOUT_MS) {
@@ -253,6 +269,51 @@ function validateRunnableFramework (repositoryRoot, framework, prefix, generated
   validateGeneratedStrategy(repositoryRoot, framework, prefix, generatedPaths, errors)
 }
 
+/**
+ * Validates bounded fallback test paths and their statically discovered prerequisites.
+ *
+ * @param {string} repositoryRoot repository root
+ * @param {object} validation direct-runner validation data
+ * @param {string} prefix error prefix
+ * @param {{push: function(string): void}} errors error collector
+ * @returns {void}
+ */
+function validateFallbackTests (repositoryRoot, validation, prefix, errors) {
+  if (validation.fallbackTests === undefined) return
+  if (!Array.isArray(validation.fallbackTests)) {
+    errors.push(`${prefix}.fallbackTests must be an array.`)
+    return
+  }
+  if (validation.fallbackTests.length > 2) {
+    errors.push(`${prefix}.fallbackTests must contain at most 2 entries.`)
+  }
+
+  const testFiles = new Set()
+  for (const [index, fallback] of validation.fallbackTests.slice(0, 2).entries()) {
+    const fallbackPrefix = `${prefix}.fallbackTests[${index}]`
+    if (!isObject(fallback)) {
+      errors.push(`${fallbackPrefix} must be an object.`)
+      continue
+    }
+    rejectExecutionFields(fallback, fallbackPrefix, errors)
+    requiredAbsolutePath(fallback, 'testFile', fallbackPrefix, errors)
+    containedPath(repositoryRoot, fallback.testFile, `${fallbackPrefix}.testFile`, errors)
+    if (typeof fallback.buildArtifactRequired !== 'boolean') {
+      errors.push(`${fallbackPrefix}.buildArtifactRequired must be a boolean.`)
+    }
+    if (typeof fallback.localSocketRequired !== 'boolean') {
+      errors.push(`${fallbackPrefix}.localSocketRequired must be a boolean.`)
+    }
+    if (fallback.testFile === validation.testFile) {
+      errors.push(`${fallbackPrefix}.testFile must differ from ${prefix}.testFile.`)
+    }
+    if (testFiles.has(fallback.testFile)) {
+      errors.push(`${prefix}.fallbackTests must contain unique testFile values.`)
+    }
+    testFiles.add(fallback.testFile)
+  }
+}
+
 /**
  * Validates canonical generated test data.
  *
@@ -450,7 +511,9 @@ function validateAllStrings (value, prefix, errors) {
   if (errors.full()) return
   if (typeof value === 'string') {
     if (Buffer.byteLength(value) > MAX_STRING_BYTES) errors.push(`${prefix} exceeds the string size limit.`)
-    if (hasUnsafeInvisibleCharacter(value)) errors.push(`${prefix} contains an unsafe invisible character.`)
+    const inertCiLabel = /\.ciWiring\.(?:job|step)$/.test(prefix)
+    const text = inertCiLabel ? value.replaceAll(/[\uFE0E\uFE0F]/g, '') : value
+    if (hasUnsafeInvisibleCharacter(text)) errors.push(`${prefix} contains an unsafe invisible character.`)
     return
   }
   if (Array.isArray(value)) {

package/ci/test-optimization-validation/offline-fixtures.js

@@ -7,6 +7,7 @@ const path = require('node:path')
 
 const { getArtifactId } = require('./artifact-id')
 const { createFileSafely, ensureSafeDirectory } = require('./safe-files')
+const { createValidationBlocker } = require('./validation-blocker')
 
 const MAX_FIXTURE_FILE_BYTES = 1024 * 1024
 const OFFLINE_FIXTURE_NONCE_PATTERN = /^[a-f0-9]{32}$/
@@ -71,9 +72,13 @@ function createOfflineFixture ({
   }
   ensurePrivateDirectory(base)
   if (fs.existsSync(root)) {
-    throw new Error(
-      `Offline validation fixture already exists and will not be replaced or deleted: ${root}. ` +
-      'Inspect and remove it manually, then render a fresh approval plan.'
+    throw createValidationBlocker(
+      `Offline validation fixture already exists and will not be replaced or deleted: ${root}.`,
+      {
+        kind: 'offline-fixture-exists',
+        recommendation: `Inspect ${root}. Remove only that validator fixture after confirming no validation process ` +
+          'is active, then render and approve a fresh plan.',
+      }
     )
   }
   try {
@@ -244,7 +249,11 @@ function getFixtureSettingsOverrides (scenarioName) {
 function cleanupOfflineFixture (fixtureRoot) {
   const parent = path.dirname(path.dirname(fixtureRoot))
   ensureSafeDirectory(parent, fixtureRoot, 'offline validation fixture cleanup')
-  fs.rmSync(fixtureRoot, { recursive: true })
+  try {
+    fs.rmSync(fixtureRoot, { recursive: true })
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
   removeEmptyParents(path.dirname(fixtureRoot), parent)
 }
 

package/ci/test-optimization-validation/offline-output.js

@@ -57,8 +57,8 @@ function readOfflineOutput (outputRoot) {
   if (!exporterInitialized) return emptyOutput()
 
   const state = {
-    bytes: 0,
-    completionBytes: 0,
+    bytes: 0n,
+    completionBytes: 0n,
     decodedEntries: 0,
     files: 0,
   }
@@ -150,7 +150,7 @@ function readPayloadFiles (payloadsRoot, kind, state, consume) {
 }
 
 function readRegularFile (filename, individualLimit, state, completion) {
-  const stat = fs.lstatSync(filename)
+  const stat = fs.lstatSync(filename, { bigint: true })
   if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 1) {
     throw new Error('Offline validation artifact must be a regular, unlinked file.')
   }
@@ -163,16 +163,16 @@ function readRegularFile (filename, individualLimit, state, completion) {
 
   const file = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0))
   try {
-    const opened = fs.fstatSync(file)
+    const opened = fs.fstatSync(file, { bigint: true })
     if (!opened.isFile() || opened.nlink > 1 || opened.dev !== stat.dev || opened.ino !== stat.ino) {
       throw new Error('Offline validation artifact changed while it was opened.')
     }
     const buffer = fs.readFileSync(file)
-    const completed = fs.fstatSync(file)
+    const completed = fs.fstatSync(file, { bigint: true })
     if (completed.size !== opened.size || completed.mtimeMs !== opened.mtimeMs) {
       throw new Error('Offline validation artifact changed while it was read.')
     }
-    state[totalKey] += buffer.length
+    state[totalKey] += BigInt(buffer.length)
     return buffer
   } finally {
     fs.closeSync(file)

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

@@ -0,0 +1,94 @@
+'use strict'
+
+const { spawnSync } = require('node:child_process')
+const path = require('node:path')
+
+const { BLOCKER_CATEGORIES } = require('./blocker-category')
+const { getBaseEnv } = require('./command-runner')
+const { sanitizeString } = require('./redaction')
+
+const DEFAULT_PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+const LOAD_MARKER = 'dd-trace-test-optimization-package-check-ok'
+const MAX_OUTPUT_BYTES = 64 * 1024
+const TIMEOUT_MS = 10_000
+
+// Loads the initialization entrypoint in an isolated child without initializing tracing.
+function checkInstalledPackage ({ packageRoot = DEFAULT_PACKAGE_ROOT } = {}) {
+  const root = path.resolve(packageRoot)
+  const initPath = path.join(root, 'ci', 'init.js')
+  const script = [
+    `require(${JSON.stringify(initPath)})`,
+    `process.stdout.write(${JSON.stringify(LOAD_MARKER)})`,
+    'process.exit(0)',
+  ].join(';')
+  const result = spawnSync(process.execPath, ['-e', script], {
+    cwd: root,
+    encoding: 'utf8',
+    env: {
+      ...getBaseEnv('clean'),
+      DD_CIVISIBILITY_ENABLED: 'false',
+      DD_INSTRUMENTATION_TELEMETRY_ENABLED: 'false',
+      DD_PROFILING_ENABLED: 'false',
+      DD_REMOTE_CONFIGURATION_ENABLED: 'false',
+      DD_TRACE_ENABLED: 'false',
+      NODE_OPTIONS: '',
+    },
+    maxBuffer: MAX_OUTPUT_BYTES,
+    shell: false,
+    timeout: TIMEOUT_MS,
+    windowsHide: true,
+  })
+
+  if (!result.error && result.status === 0 && result.stdout.includes(LOAD_MARKER)) {
+    return {
+      ok: true,
+      diagnosis: 'The installed dd-trace package loaded its Test Optimization initialization entrypoint.',
+    }
+  }
+
+  const detail = getFailureDetail(result)
+  return {
+    ok: false,
+    diagnosis: 'The installed dd-trace package could not load its Test Optimization initialization entrypoint' +
+      (detail ? `: ${detail}` : '.'),
+    recommendation: 'Reinstall dd-trace through the project\'s normal dependency workflow, then create a fresh ' +
+      'validation plan. If the load check still fails, report it as an installed-package problem without running ' +
+      'tests.',
+  }
+}
+
+function getInstalledPackageFailure (framework, packageCheck) {
+  return {
+    frameworkId: framework.id,
+    scenario: 'basic-reporting',
+    status: 'blocked',
+    diagnosis: `${packageCheck.diagnosis} No project test was run and no library-compatibility conclusion was reached.`,
+    evidence: {
+      blockerCategory: BLOCKER_CATEGORIES.PROJECT_SETUP_REQUIRED,
+      blockedByProjectSetup: true,
+      installedPackageIncomplete: true,
+      recommendation: packageCheck.recommendation,
+      validationIncomplete: true,
+    },
+    artifacts: [],
+  }
+}
+
+function getFailureDetail (result) {
+  if (result.error?.code === 'ETIMEDOUT') return `the isolated load check exceeded ${TIMEOUT_MS} ms.`
+  if (result.error) return `${sanitizeLine(result.error.message)}.`
+
+  const output = `${result.stderr || ''}\n${result.stdout || ''}`
+  const line = output.split(/\r?\n/).map(value => value.trim()).find(value => {
+    return /^(?:Error:|.*(?:MODULE_NOT_FOUND|Cannot find (?:module|package)|ERR_[A-Z_]+))/.test(value)
+  })
+  if (line) return `${sanitizeLine(line)}.`
+  if (result.signal) return `the isolated load check exited after signal ${sanitizeLine(result.signal)}.`
+  return `the isolated load check exited ${result.status ?? 'without a status'}.`
+}
+
+function sanitizeLine (value) {
+  return sanitizeString(String(value)).replaceAll(/\p{Cc}+/gu, ' ').trim().slice(0, 1000).replace(/[.]+$/, '')
+}
+
+module.exports = { checkInstalledPackage, getInstalledPackageFailure }

package/ci/test-optimization-validation/plan-writer.js

@@ -4,6 +4,7 @@ const crypto = require('node:crypto')
 const path = require('node:path')
 
 const { VERSION } = require('../../version')
+const { getRequiredCapabilities } = require('./approval')
 const { writeApprovalArtifacts } = require('./approval-artifacts')
 const { serializeApprovalCommand } = require('./command-runner')
 const { getUnavailableExecutable } = require('./executable')
@@ -41,6 +42,9 @@ function formatExecutionPlan (input) {
  * @param {string[]} [input.selectedFrameworkIds] selected framework ids
  * @param {string|null} [input.requestedScenario] selected scenario
  * @param {boolean} [input.keepTempFiles] retain temporary files
+ * @param {object} [input.packageCheck] installed package-load result
+ * @param {Map<string, object>} [input.ciPreflightResults] static CI results by framework
+ * @param {Array<{path: string, sha256: string}>} [input.expectedProjectFiles] preflight project snapshot
  * @param {boolean} [input.verbose] print progress
  * @returns {{plan: string}} written plan
  */
@@ -50,6 +54,9 @@ function formatExecutionPlanArtifacts ({
   selectedFrameworkIds = [],
   requestedScenario = null,
   keepTempFiles = false,
+  packageCheck,
+  ciPreflightResults = new Map(),
+  expectedProjectFiles,
   verbose = false,
 }) {
   const offlineFixtureNonce = crypto.randomBytes(16).toString('hex')
@@ -61,6 +68,7 @@ function formatExecutionPlanArtifacts ({
     offlineFixtureNonce,
     keepTempFiles,
     verbose,
+    expectedProjectFiles,
   })
   const validatorArgv = [
     process.execPath,
@@ -72,8 +80,11 @@ function formatExecutionPlanArtifacts ({
   ]
   const plan = formatApprovalPlan({
     approvalArtifacts,
+    ciPreflightResults,
     manifest,
     out,
+    keepTempFiles,
+    packageCheck,
     requestedScenario,
     validatorArgv,
   })
@@ -86,20 +97,67 @@ function formatExecutionPlanArtifacts ({
  *
  * @param {object} input formatting inputs
  * @param {object} input.approvalArtifacts approval artifact paths and digest
+ * @param {Map<string, object>} input.ciPreflightResults static CI results by framework
  * @param {object} input.manifest normalized manifest
  * @param {string} input.out output directory
+ * @param {boolean} input.keepTempFiles retain temporary files
+ * @param {object|undefined} input.packageCheck installed package-load result
  * @param {string|null} input.requestedScenario selected scenario
  * @param {string[]} input.validatorArgv exact validator command
  * @returns {string} Markdown plan
  */
-function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenario, validatorArgv }) {
+function formatApprovalPlan ({
+  approvalArtifacts,
+  ciPreflightResults,
+  manifest,
+  out,
+  keepTempFiles,
+  packageCheck,
+  requestedScenario,
+  validatorArgv,
+}) {
   const root = manifest.repository.root
+  const runnableFrameworks = manifest.frameworks.filter(framework => framework.status === 'runnable')
+  const requiredCapabilities = getRequiredCapabilities({
+    manifest,
+    requestedScenario,
+  })
+  const buildPrerequisites = runnableFrameworks.filter(framework => {
+    return framework.buildArtifactRequired === true ||
+      (framework.validation?.fallbackTests || []).some(fallback => fallback.buildArtifactRequired === true)
+  }).length
   const lines = [
     '# Test Optimization Validation Plan',
     '',
     `Repository: ${inline(root)}`,
     `Validator: ${inline(`dd-trace ${VERSION}`)}`,
     `Results: ${inline(relative(root, out))}`,
+    ...(packageCheck?.ok
+      ? [`Installed package check: ${plain(packageCheck.diagnosis)}`]
+      : []),
+    '',
+    '## Approval Summary',
+    '',
+    requestedScenario === 'ci-wiring'
+      ? 'Local execution: none; this plan performs static CI analysis only.'
+      : `Local execution: ${runnableFrameworks.length} framework target${
+          runnableFrameworks.length === 1 ? '' : 's'
+        } eligible; ${manifest.frameworks.length - runnableFrameworks.length} setup or static-only.`,
+    `Required host capabilities: ${
+      requiredCapabilities.length > 0 ? requiredCapabilities.map(formatCapability).join(', ') : 'none declared'
+    }.`,
+    `Build prerequisites: ${
+      buildPrerequisites > 0
+        ? `${buildPrerequisites} eligible framework target${
+            buildPrerequisites === 1 ? '' : 's'
+          } may require the project's normal build`
+        : 'none detected statically'
+    }.`,
+    `Mutable paths: ${inline(relative(root, out))} and the temporary files disclosed below; temporary files ${
+      keepTempFiles ? 'will be retained by request' : 'will be removed after validation'
+    }.`,
+    'CI replay: none. CI configuration is inspected statically and CI commands are never executed.',
+    'Approval: one checksum-bound validator command, shown once at the end of this plan.',
     '',
     'The validator will run only the displayed `node <repository-contained-runner> <one-test-file>` commands. The ' +
       'runner may be an exact repository-owned Node test wrapper. The validator itself will not directly invoke ' +
@@ -112,8 +170,15 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
   for (const framework of manifest.frameworks) {
     lines.push(`### ${plain(getFrameworkLabel(framework, root))}`, '')
     if (framework.status !== 'runnable') {
-      lines.push(`Status: ${plain(formatStatus(framework.status))}.`)
-      for (const note of framework.notes || []) lines.push(`- ${plain(note)}`)
+      lines.push(
+        `Status: ${plain(formatStatus(framework.status))}.`,
+        ...(framework.blockerCategory
+          ? [`Blocker: ${plain(framework.blockerCategory.replaceAll('_', ' '))}.`]
+          : [])
+      )
+      if (framework.notes) {
+        for (const note of framework.notes) lines.push(`- ${plain(note)}`)
+      }
       lines.push('')
       continue
     }
@@ -122,13 +187,25 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
       lines.push('Status: static CI audit only; no project test command is selected.', '')
     } else {
       const basic = getBasicCommand(framework)
+      const fallbackTests = framework.validation.fallbackTests || []
       const unavailable = getUnavailableExecutable(basic)
       const status = unavailable
         ? `local validation will be incomplete because ${inline(unavailable)} is unavailable`
         : 'eligible for approved clean preflight; runtime prerequisites are unverified'
       lines.push(
         `Status: ${status}.`,
-        `Representative test: ${inline(relative(root, framework.validation.testFile))}`,
+        `Representative test: ${inline(relative(root, framework.validation.testFile))}${formatCandidateRequirements({
+          buildArtifactRequired: framework.buildArtifactRequired,
+          localSocketRequired: framework.localSocketRequired,
+        })}`,
+        ...(fallbackTests.length > 0
+          ? [
+              'Fallback tests, tried in order only if the representative does not pass cleanly:',
+              ...fallbackTests.map(fallback => {
+                return `- ${inline(relative(root, fallback.testFile))}${formatCandidateRequirements(fallback)}`
+              }),
+            ]
+          : []),
         `Working directory: ${inline(relative(root, basic.cwd))}`,
         `Timeout: ${basic.timeoutMs} ms`,
         ...(Object.keys(basic.env || {}).length > 0
@@ -136,16 +213,71 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
           : []),
         ...formatOmittedRunnerOptions(framework.validation.omittedRunnerOptions),
         '',
+        ...(framework.browserRequired
+          ? [
+              'Browser permission: this approved validation command launches the project browser through its ' +
+                'selected test runner. If the agent platform blocks browser processes, request its narrow permission ' +
+                'for the exact checksum-bound validator command below; do not change or broaden the command. ' +
+                'Complete ' +
+                'the project\'s normal browser installation, application startup, and build first when the selected ' +
+                'test depends on them.',
+              '',
+            ]
+          : []),
+        ...(framework.localSocketRequired
+          ? [
+              `Localhost prerequisite: ${
+                framework.allCandidatesRequireLocalSocket
+                  ? 'every approved candidate appears'
+                  : 'the selected test appears'
+              } to open or contact a local listener. A restricted execution environment may require narrow ` +
+                'permission for the exact validator command.',
+              '',
+            ]
+          : []),
+        ...(framework.buildArtifactRequired
+          ? [
+              'Build prerequisite: the selected test appears to load a build or dist artifact. Complete the ' +
+                'project\'s normal build before validation if that artifact is not already present.',
+              '',
+            ]
+          : []),
         'Basic Reporting command:',
         '',
         codeBlock(serializeApprovalCommand(basic)),
         '',
         'The command runs once without Datadog and once with validator-owned offline initialization. A debug rerun ' +
           'and one clean confirmation may run only when needed to diagnose a mismatch.',
+        ...(fallbackTests.length > 0
+          ? [
+              'If this test does not pass cleanly, the validator may try the disclosed fallback tests in order. It ' +
+                'will initialize only the first candidate that passes, and will stop early when the failure is a ' +
+                'confirmed shared runtime prerequisite rather than a candidate-specific test failure.',
+            ]
+          : []),
         ''
       )
 
+      for (const [index, fallback] of fallbackTests.entries()) {
+        const fallbackCommand = getBasicCommand(framework, fallback.testFile)
+        lines.push(
+          `Fallback Basic Reporting command ${index + 1}:`,
+          '',
+          codeBlock(serializeApprovalCommand(fallbackCommand)),
+          ''
+        )
+      }
+
       const selectedScenarios = getSelectedGeneratedScenarios(framework, requestedScenario)
+      if (selectedScenarios.length > 0) {
+        lines.push(
+          `Advanced checks use working directory: ${inline(relative(
+            root,
+            getGeneratedCommand(framework, selectedScenarios[0]).cwd
+          ))}`,
+          ''
+        )
+      }
       for (const scenario of selectedScenarios) {
         const command = getGeneratedCommand(framework, scenario)
         const source = getGeneratedSource(framework, scenario)
@@ -157,9 +289,6 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
           `Temporary file: ${inline(relative(root, scenario.testIdentities[0].file))}`,
           '',
           codeBlock(source),
-          '',
-          'Execution count: one clean generated-test verification, one instrumented identity-discovery run, and ' +
-            'one feature-validation run. One debug rerun may run only after a failure.',
           ''
         )
       }
@@ -173,12 +302,23 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
           ''
         )
       }
+      if (selectedScenarios.length > 0) {
+        lines.push(
+          'Advanced execution policy: each generated scenario has one clean verification, one instrumented ' +
+            'identity-discovery run, and one feature-validation run. One debug rerun may run only after a failure.',
+          ''
+        )
+      }
     }
 
     const ci = framework.ciWiring
+    const ciPreflight = ciPreflightResults.get(framework.id)
     lines.push(
       'CI audit: static only; no CI or package command will execute.',
       `CI review: ${plain(ci?.reviewComplete ? 'complete' : 'incomplete')}.`,
+      ...(ciPreflight
+        ? [`CI pre-approval result: ${plain(formatCiPreflightResult(ciPreflight))}`]
+        : []),
       ...(ci?.configFile ? [`CI file: ${inline(relative(root, ci.configFile))}`] : []),
       ''
     )
@@ -188,6 +328,8 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
     '## Writes and Cleanup',
     '',
     `- Validation artifacts: ${inline(relative(root, out))}`,
+    '- Single-flight lock: the approved validator creates one fixed lock in the result directory while it runs. An ' +
+      'existing lock blocks execution and is never reclaimed automatically.',
     ...(requestedScenario === 'ci-wiring'
       ? []
       : [
@@ -233,10 +375,41 @@ function formatApprovalPlan ({ approvalArtifacts, manifest, out, requestedScenar
   return lines.join('\n')
 }
 
+function formatCapability (capability) {
+  const labels = {
+    browser_process: 'browser process',
+    localhost_socket: 'localhost socket',
+  }
+  return labels[capability] || capability
+}
+
+function formatCandidateRequirements (candidate) {
+  const requirements = [
+    ...(candidate.localSocketRequired ? ['localhost'] : []),
+    ...(candidate.buildArtifactRequired ? ['build output'] : []),
+  ]
+  return requirements.length > 0 ? ` (${requirements.join(', ')} required)` : ''
+}
+
+function formatCiPreflightResult (result) {
+  const status = result.status === 'fail'
+    ? 'confirmed actionable problem'
+    : result.status === 'pass'
+      ? 'no confirmed problem'
+      : 'incomplete'
+  return `${status}: ${result.diagnosis}`
+}
+
 function formatOmittedRunnerOptions (options = []) {
-  return options.map(option => option === '--run'
-    ? 'Normalized runner option: `--run` is omitted because the validator supplies Vitest `run` itself.'
-    : 'Omitted runner option: `--typecheck` is excluded because validation executes runtime tests only.')
+  const descriptions = {
+    '-R': 'Omitted runner option: `-R` selects only Mocha report presentation; the validator uses its bounded ' +
+      'reporter.',
+    '--reporter': 'Omitted runner option: `--reporter` selects only Mocha report presentation; the validator uses ' +
+      'its bounded reporter.',
+    '--run': 'Normalized runner option: `--run` is omitted because the validator supplies Vitest `run` itself.',
+    '--typecheck': 'Omitted runner option: `--typecheck` is excluded because validation executes runtime tests only.',
+  }
+  return options.map(option => descriptions[option])
 }
 
 /**