vona-core 5.1.45 → 5.1.47

package/dist/index.js

@@ -4,11 +4,11 @@ import { toLowerCaseFirstChar, splitWords } from '@cabloy/word-utils';
 import path from 'node:path';
 import fse from 'fs-extra';
 import crypto, { createHash as createHash$1, randomBytes, timingSafeEqual } from 'node:crypto';
-import fs, { lstatSync, constants } from 'node:fs';
+import fs, { lstatSync, existsSync, readFileSync, constants } from 'node:fs';
 import { compose as compose$1 } from '@cabloy/compose';
 import { extend } from '@cabloy/extend';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import * as uuid from 'uuid';
 import { getPlatformArch as getPlatformArch$1 } from 'vona';
 import os from 'node:os';
@@ -26,8 +26,9 @@ import chalk from 'chalk';
 import * as Winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
 import { MESSAGE, LEVEL } from 'triple-beam';
-import { mkdir, open, rename, unlink } from 'node:fs/promises';
 import { createServer } from 'node:http';
+import { mkdir, open, rename, unlink, lstat } from 'node:fs/promises';
+import { execFileSync, execFile } from 'node:child_process';
 import cluster from 'node:cluster';
 import React from 'react';
 import { extendZodWithOpenApi } from '@cabloy/zod-to-openapi';
@@ -546,7 +547,7 @@ class AppUtil extends BeanSimple {
     const globalPrefix = '/api/static';
     if (!staticPath) staticPath = '';
     // safe
-    staticPath = path.normalize(staticPath);
+    staticPath = path.posix.normalize(staticPath.replace(/\\/g, '/'));
     if (staticPath.includes('..')) throw new Error(`unsafe path: ${staticPath}`);
     // ignore globalPrefix
     if (staticPath.startsWith('//')) return staticPath.substring(1);
@@ -811,9 +812,9 @@ async function createGeneralApp(projectPath, envRuntime) {
     }
   }
   if (process.env.META_MODE === 'prod') {
-    const testFile = path.join(projectPath, `dist/${process.env.META_FLAVOR}/bootstrap.js`);
+    const testFile = path.join(projectPath, `dist/${process.env.META_FLAVOR}/app.js`);
     const testInstance = await import(pathToHref(testFile));
-    return await testInstance.appBootstrap;
+    return await testInstance.createSingleApp();
   } else {
     const testFile = path.join(resolveVonaLocalPaths(projectPath, process.env.META_MODE).generatedRoot, 'app.ts');
     const testInstance = await import(pathToHref(testFile));
@@ -3176,8 +3177,307 @@ function __formatLoggerFilterCheckInfo(info) {
   return info;
 }
 
+// Both source and bundled dist consumers use the checked-in, published src assets.
+function getWindowsTestClaimFilesystemHelper(directory = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url))) {
+  let current = directory;
+  while (true) {
+    const manifest = path.join(current, 'package.json');
+    if (existsSync(manifest)) {
+      const value = JSON.parse(readFileSync(manifest, 'utf8'));
+      if (value.name === 'vona-core') {
+        const helper = path.join(current, 'src/lib/core/testClaimFilesystemWindows.ps1');
+        if (!existsSync(helper) || !existsSync(helper.replace(/\.ps1$/, '.cs'))) throw new Error('Windows test claim filesystem helper assets are missing');
+        return helper;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error('Cannot locate the vona-core Windows filesystem helper');
+    current = parent;
+  }
+}
+function invocation() {
+  if (process.platform !== 'win32') throw new Error('Windows claim filesystem requires Windows');
+  return ['-NoLogo', '-NoProfile', '-NonInteractive', '-File', getWindowsTestClaimFilesystemHelper()];
+}
+function decode(source) {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error('Windows test claim filesystem helper returned an invalid response');
+  }
+  if (!value || value.ok !== true) {
+    const error = new Error(value?.code === 'EEXIST' ? 'Test claim file already exists' : `Unsafe Windows test claim filesystem operation (${value?.code ?? 'unknown'})`);
+    Object.assign(error, {
+      code: value?.code ?? 'EUNSAFE'
+    });
+    throw error;
+  }
+  return value;
+}
+function windowsTestClaimFilesystemSync(request) {
+  try {
+    return decode(execFileSync('pwsh', invocation(), {
+      input: JSON.stringify(request),
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 30000,
+      maxBuffer: 8 * 1024 * 1024
+    }));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error('Native Windows test claims require PowerShell 7 (pwsh) on PATH');
+    throw error;
+  }
+}
+let bridge;
+function windowsTestClaimFilesystem(request) {
+  if (!bridge) {
+    // Explicit executable + argv, never a shell. A burst shares Add-Type startup;
+    // the bridge owns no persistent native handles and exits when idle.
+    const child = execFile('pwsh', invocation(), {
+      windowsHide: true,
+      maxBuffer: Infinity
+    });
+    // execFile's collection listeners are for its callback API. This bounded
+    // line protocol consumes the streams itself, without retaining burst history.
+    child.stdout?.removeAllListeners('data');
+    child.stderr?.removeAllListeners('data');
+    const state = {
+      child,
+      pending: [],
+      output: '',
+      idle: undefined
+    };
+    bridge = state;
+    const fail = error => {
+      if (bridge === state) bridge = undefined;
+      clearTimeout(state.idle);
+      for (const operation of state.pending.splice(0)) {
+        clearTimeout(operation.timer);
+        operation.reject(error);
+      }
+      child.stdin?.destroy();
+      child.kill();
+    };
+    child.once('error', error => fail(new Error(error.code === 'ENOENT' ? 'Native Windows test claims require PowerShell 7 (pwsh) on PATH' : 'Windows test claim filesystem helper failed; operation not acknowledged')));
+    child.once('exit', () => fail(new Error('Windows test claim filesystem helper exited; operation not acknowledged')));
+    child.stdin?.on('error', () => fail(new Error('Windows test claim filesystem control stream failed')));
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.resume();
+    child.stdout?.on('data', chunk => {
+      state.output += chunk;
+      if (Buffer.byteLength(state.output) > 8 * 1024 * 1024) {
+        fail(new Error('Windows test claim filesystem response exceeded limit'));
+        return;
+      }
+      while (state.output.includes('\n')) {
+        const end = state.output.indexOf('\n');
+        const line = state.output.slice(0, end);
+        state.output = state.output.slice(end + 1);
+        const operation = state.pending.shift();
+        if (!operation) {
+          fail(new Error('Unexpected Windows test claim filesystem response'));
+          return;
+        }
+        clearTimeout(operation.timer);
+        try {
+          operation.resolve(decode(line));
+        } catch (error) {
+          operation.reject(error);
+        }
+      }
+      if (!state.pending.length) {
+        state.idle = setTimeout(() => {
+          if (bridge === state) bridge = undefined;
+          child.stdin?.end();
+        }, 1000);
+      }
+    });
+  }
+  const state = bridge;
+  clearTimeout(state.idle);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      if (bridge === state) bridge = undefined;
+      for (const operation of state.pending.splice(0)) {
+        clearTimeout(operation.timer);
+        operation.reject(new Error('Windows test claim filesystem operation timed out; not acknowledged'));
+      }
+      state.child.kill();
+    }, 30000);
+    state.pending.push({
+      resolve,
+      reject,
+      timer
+    });
+    state.child.stdin?.write(`${JSON.stringify(request)}\n`);
+  });
+}
+
+const TEST_CLAIM_FILE_LIMIT = 4 * 1024 * 1024;
+function assertTestClaimFilesystemSafePath(file, allowMissing = true) {
+  if (process.platform === 'win32') {
+    windowsTestClaimFilesystemSync({
+      command: 'safe-path',
+      path: path.resolve(file),
+      allowMissing
+    });
+    return;
+  }
+  let current = path.resolve(file);
+  while (true) {
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || current !== path.resolve(file) && !stat.isDirectory()) throw new Error('Unsafe test claim path');
+    } catch (error) {
+      if (!allowMissing || error.code !== 'ENOENT') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+async function assertTestClaimPrivateDirectory(directory, missingAllowed = true) {
+  if (process.platform === 'win32') {
+    const value = await windowsTestClaimFilesystem({
+      command: 'directory',
+      path: path.resolve(directory),
+      allowMissing: missingAllowed
+    });
+    return value.exists === true;
+  }
+  assertTestClaimFilesystemSafePath(directory, missingAllowed);
+  let stat;
+  try {
+    stat = await lstat(directory);
+  } catch (error) {
+    if (missingAllowed && error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0 || process.getuid && stat.uid !== process.getuid()) {
+    throw new Error('Unsafe shared test claim directory');
+  }
+  return true;
+}
+async function ensureTestClaimPrivateDirectory(directory) {
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({
+      command: 'ensure-directory',
+      path: path.resolve(directory)
+    });
+    return;
+  }
+  assertTestClaimFilesystemSafePath(directory);
+  await mkdir(directory, {
+    mode: 0o700
+  }).catch(error => {
+    if (error.code !== 'EEXIST') throw error;
+  });
+  await assertTestClaimPrivateDirectory(directory, false);
+}
+function assertPrivateFile(file) {
+  assertTestClaimFilesystemSafePath(file, false);
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || process.getuid && stat.uid !== process.getuid()) {
+    throw new Error('Unsafe test claim file');
+  }
+}
+async function syncDirectory(directory) {
+  const handle = await open(directory, constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+function checkContent(content) {
+  if (Buffer.byteLength(content) > TEST_CLAIM_FILE_LIMIT) throw new Error('Invalid test claim file size');
+}
+async function readTestClaimFile(file) {
+  if (process.platform === 'win32') {
+    const value = await windowsTestClaimFilesystem({
+      command: 'read',
+      path: path.resolve(file)
+    });
+    if (typeof value.content !== 'string') throw new Error('Invalid test claim file response');
+    return value.content;
+  }
+  assertPrivateFile(file);
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > TEST_CLAIM_FILE_LIMIT || (stat.mode & 0o077) !== 0 || process.getuid && stat.uid !== process.getuid()) {
+      throw new Error('Invalid test claim file');
+    }
+    // Bound the allocation and bytes read even if the file grows after fstat.
+    const buffer = Buffer.alloc(TEST_CLAIM_FILE_LIMIT + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const {
+        bytesRead
+      } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (offset > TEST_CLAIM_FILE_LIMIT) throw new Error('Invalid test claim file size');
+    return buffer.subarray(0, offset).toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+async function createTestClaimFile(file, content) {
+  checkContent(content);
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({
+      command: 'create',
+      path: path.resolve(file),
+      content
+    });
+    return;
+  }
+  assertTestClaimFilesystemSafePath(file);
+  const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    await handle.writeFile(content);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(path.dirname(file));
+}
+async function replaceTestClaimFile(file, content) {
+  checkContent(content);
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({
+      command: 'replace',
+      path: path.resolve(file),
+      content
+    });
+    return;
+  }
+  const temp = `${file}.${randomBytes(12).toString('hex')}.tmp`;
+  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    try {
+      await handle.writeFile(content);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    assertPrivateFile(file);
+    await rename(temp, file);
+    await syncDirectory(path.dirname(file));
+  } finally {
+    await unlink(temp).catch(error => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+
 const TEST_CLAIM_URL_ENV = 'VONA_TEST_CLAIM_URL';
 const TEST_CLAIM_TOKEN_ENV = 'VONA_TEST_CLAIM_TOKEN';
+/** A locator only. Containment still requires the registered guardian's live native verifier. */
+const TEST_CLAIM_WINDOWS_GUARDIAN_ENV = 'VONA_TEST_WINDOWS_GUARDIAN_ID';
 const TEST_CLAIM_DIRECTORY = '.vona-test-claim';
 function getTestClaimPaths(projectPath, runId) {
   resolveTestRunId('test', runId);
@@ -3196,20 +3496,7 @@ function getTestClaimCreatedAt(runId) {
   return `${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T${s.slice(8, 10)}:${s.slice(10, 12)}:${s.slice(12, 14)}.000Z`;
 }
 function assertTestClaimSafePath(file, allowMissing = true) {
-  let current = path.resolve(file);
-  while (true) {
-    try {
-      const stat = lstatSync(current);
-      if (stat.isSymbolicLink() || current !== path.resolve(file) && !stat.isDirectory()) {
-        throw new Error('Unsafe test claim path');
-      }
-    } catch (error) {
-      if (!allowMissing || error.code !== 'ENOENT') throw error;
-    }
-    const parent = path.dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
+  assertTestClaimFilesystemSafePath(file, allowMissing);
 }
 function record(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid test claim object');
@@ -3278,7 +3565,7 @@ function validateTestClaim(value, claimPath) {
   if (!path.isAbsolute(m.projectPath) || path.resolve(m.projectPath) !== m.projectPath) throw new Error('Invalid test claim checkout');
   const p = getTestClaimPaths(m.projectPath, m.runId);
   if (claimPath && path.resolve(claimPath) !== p.claimPath) throw new Error('Test claim filename or checkout mismatch');
-  oneOf(m.kind, ['unit', 'cov', 'e2e']);
+  oneOf(m.kind, ['unit', 'cov', 'e2e', 'contract']);
   keys(m.owner, ['pid', 'startTime', 'host']);
   integer(m.owner.pid, 1);
   text(m.owner.startTime);
@@ -3334,16 +3621,28 @@ function validateTestClaim(value, claimPath) {
   array(m.processes);
   unique(m.processes.map(item => item.id));
   for (const proc of m.processes) {
-    keys(proc, ['id', 'role', 'stage', 'pid', 'pgid', 'startTime', 'host', 'profilePath']);
+    keys(proc, ['id', 'role', 'stage', 'pid', 'pgid', 'containment', 'jobId', 'startTime', 'host', 'profilePath']);
     label(proc.id);
     oneOf(proc.role, ['guardian', 'browser', 'cleanup']);
     if (proc.host !== undefined) text(proc.host);
     oneOf(proc.stage, ['pending', 'registered', 'drained']);
+    if (proc.containment !== undefined) oneOf(proc.containment, ['windows-job']);
+    if (proc.containment === 'windows-job') {
+      if (proc.pgid !== undefined || proc.role !== 'guardian' || proc.profilePath !== undefined) throw new Error('Invalid Windows test claim containment');
+      text(proc.jobId);
+      if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(proc.jobId)) throw new Error('Invalid Windows test claim job identity');
+    } else if (proc.jobId !== undefined) {
+      throw new Error('Windows test claim job needs explicit containment');
+    }
     const hasIdentity = proc.pid !== undefined || proc.pgid !== undefined || proc.startTime !== undefined;
     if (hasIdentity || proc.stage !== 'pending') {
       integer(proc.pid, 1);
-      integer(proc.pgid, 1);
+      if (proc.containment !== 'windows-job') integer(proc.pgid, 1);
       text(proc.startTime);
+      if (proc.containment === 'windows-job') {
+        if (!/^[1-9]\d{0,19}$/.test(proc.startTime)) throw new Error('Invalid Windows test claim process creation time');
+        text(proc.host);
+      }
     }
     if (proc.profilePath !== undefined) {
       text(proc.profilePath);
@@ -3356,23 +3655,8 @@ function validateTestClaim(value, claimPath) {
   for (const key of ['processes', 'databases', 'redis', 'locals']) bool(m.cleanup[key]);
   return m;
 }
-function assertPrivateFile(file) {
-  assertTestClaimSafePath(file, false);
-  const stat = lstatSync(file);
-  if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || process.getuid && stat.uid !== process.getuid()) {
-    throw new Error('Unsafe test claim file');
-  }
-}
 async function loadTestClaim(claimPath) {
-  assertPrivateFile(claimPath);
-  const handle = await open(claimPath, constants.O_RDONLY | constants.O_NOFOLLOW);
-  try {
-    const stat = await handle.stat();
-    if (!stat.isFile() || stat.size > 4 * 1024 * 1024) throw new Error('Invalid test claim file');
-    return validateTestClaim(parseTestClaimJson(await handle.readFile('utf8')), claimPath);
-  } finally {
-    await handle.close();
-  }
+  return validateTestClaim(parseTestClaimJson(await readTestClaimFile(claimPath)), claimPath);
 }
 function parseTestClaimJson(source) {
   // Claim identities stay literal even when @cabloy/json5 revives ISO strings.
@@ -3380,31 +3664,13 @@ function parseTestClaimJson(source) {
     return this[key];
   });
 }
-async function syncDirectory(directory) {
-  const handle = await open(directory, constants.O_RDONLY);
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
 async function createTestClaim(projectPath, runId, kind, owner) {
   const p = getTestClaimPaths(projectPath, runId);
-  assertTestClaimSafePath(p.claimDirectory);
-  await mkdir(p.claimDirectory, {
-    mode: 0o700
-  }).catch(error => {
-    if (error.code !== 'EEXIST') throw error;
-  });
+  await ensureTestClaimPrivateDirectory(p.claimDirectory);
   // The directory is shared across runs; an existing directory is valid, never an existing claim.
   return createClaimFile(p, runId, kind, owner);
 }
 async function createClaimFile(p, runId, kind, owner) {
-  assertTestClaimSafePath(p.claimDirectory, false);
-  const directoryStat = lstatSync(p.claimDirectory);
-  if (!directoryStat.isDirectory() || (directoryStat.mode & 0o077) !== 0 || process.getuid && directoryStat.uid !== process.getuid()) {
-    throw new Error('Unsafe shared test claim directory');
-  }
   const manifest = {
     version: 1,
     runId,
@@ -3433,14 +3699,7 @@ async function createClaimFile(p, runId, kind, owner) {
     }
   };
   validateTestClaim(manifest, p.claimPath);
-  const handle = await open(p.claimPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-  try {
-    await handle.writeFile(`${JSON.stringify(manifest, null, 2)}\n`);
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-  await syncDirectory(p.claimDirectory);
+  await createTestClaimFile(p.claimPath, `${JSON.stringify(manifest, null, 2)}\n`);
   return {
     claimPath: p.claimPath,
     manifest
@@ -3454,23 +3713,7 @@ async function writeTestClaim(claimPath, manifest) {
   for (const key of ['version', 'runId', 'createdAt', 'projectPath', 'kind', 'owner']) {
     if (!isDeepStrictEqual(previous[key], manifest[key])) throw new Error('Test claim identity is immutable');
   }
-  const temp = `${claimPath}.${randomBytes(12).toString('hex')}.tmp`;
-  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-  try {
-    try {
-      await handle.writeFile(`${JSON.stringify(manifest, null, 2)}\n`);
-      await handle.sync();
-    } finally {
-      await handle.close();
-    }
-    assertPrivateFile(claimPath);
-    await rename(temp, claimPath);
-    await syncDirectory(path.dirname(claimPath));
-  } finally {
-    await unlink(temp).catch(error => {
-      if (error.code !== 'ENOENT') throw error;
-    });
-  }
+  await replaceTestClaimFile(claimPath, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 function applyEvent(m, event) {
   record(event);
@@ -3497,7 +3740,9 @@ function applyEvent(m, event) {
           if (event.process.stage !== 'pending') throw new Error('Process needs a write-ahead intent');
           m.processes.push(event.process);
         } else {
-          if (old.role !== event.process.role) throw new Error('Test claim process identity changed');
+          if (old.role !== event.process.role || old.containment !== event.process.containment || old.jobId !== event.process.jobId) {
+            throw new Error('Test claim process identity changed');
+          }
           if (event.process.profilePath !== undefined && old.profilePath !== event.process.profilePath) {
             if (old.stage !== 'pending' || event.process.stage !== 'registered' || !old.profilePath || !event.process.profilePath.startsWith(`${old.profilePath}${path.sep}`)) {
               throw new Error('Test claim process profile changed');
@@ -3578,11 +3823,79 @@ function applyEvent(m, event) {
   }
   validateTestClaim(m);
 }
+// Native verifiers are controller-local capabilities, never HTTP registrations or journal data.
+const liveWindowsBrokers = new Map();
+function validateWindowsJobQuery(value) {
+  keys(value, ['runId', 'guardianId', 'process']);
+  const query = value;
+  resolveTestRunId('test', query.runId);
+  label(query.guardianId);
+  keys(query.process, ['pid', 'startTime', 'host']);
+  integer(query.process.pid, 1, 0xffffffff);
+  text(query.process.startTime);
+  if (!/^[1-9]\d{0,19}$/.test(query.process.startTime)) throw new Error('Invalid Windows containment creation time');
+  text(query.process.host);
+}
+
+/** Only the controller hosting this authenticated broker can attach its sole native Job owner. */
+async function registerTestClaimWindowsJobVerifier(env, guardian, verify) {
+  if (!hasTestClaimTransport(env)) throw new Error('Windows containment requires a claim broker');
+  if (!resolveTestRunId(env.META_MODE, env.VONA_TEST_RUN_ID)) throw new Error('Windows containment requires test identity');
+  const broker = liveWindowsBrokers.get(env[TEST_CLAIM_TOKEN_ENV]);
+  if (!broker || broker.url !== env[TEST_CLAIM_URL_ENV]) throw new Error('Windows containment verifier must belong to the local claim broker');
+  return await broker.register(guardian, verify);
+}
 async function startTestClaimBroker(claimPath) {
   await loadTestClaim(claimPath);
   const token = randomBytes(32).toString('hex');
   let queue = Promise.resolve();
   let closing = false;
+  const verifiers = new Map();
+  let queries = 0;
+  const containment = async query => {
+    validateWindowsJobQuery(query);
+    if (closing || queries >= 32) throw new Error('Windows containment verifier unavailable');
+    queries++;
+    try {
+      await queue;
+      const manifest = await loadTestClaim(claimPath);
+      const live = verifiers.get(query.guardianId);
+      const guardian = manifest.processes.find(item => item.id === query.guardianId);
+      if (manifest.kind !== 'e2e' || manifest.runId !== query.runId || guardian?.stage !== 'registered' || guardian.role !== 'guardian' || guardian.containment !== 'windows-job' || guardian.host !== query.process.host || !live || !isDeepStrictEqual(live.guardian, guardian)) {
+        throw new Error('Windows containment requires a registered live E2E guardian');
+      }
+      let timer;
+      try {
+        const verified = await Promise.race([live.verify(query.process), new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error('Windows containment query timed out')), 5000);
+        })]);
+        await queue;
+        const current = await loadTestClaim(claimPath);
+        if (!verified || closing || verifiers.get(query.guardianId) !== live || !isDeepStrictEqual(current.processes.find(item => item.id === query.guardianId), guardian)) {
+          throw new Error('Windows process is not in the designated live Job');
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    } finally {
+      queries--;
+    }
+  };
+  const register = async (guardian, verify) => {
+    await queue;
+    const manifest = await loadTestClaim(claimPath);
+    if (closing || guardian.role !== 'guardian' || guardian.stage !== 'registered' || guardian.containment !== 'windows-job' || typeof verify !== 'function' || verifiers.has(guardian.id) || !isDeepStrictEqual(manifest.processes.find(item => item.id === guardian.id), guardian)) {
+      throw new Error('Windows containment verifier needs a durable registered guardian');
+    }
+    const live = {
+      guardian: structuredClone(guardian),
+      verify
+    };
+    verifiers.set(guardian.id, live);
+    return () => {
+      if (verifiers.get(guardian.id) === live) verifiers.delete(guardian.id);
+    };
+  };
   const update = event => {
     if (closing) return Promise.reject(new Error('Test claim broker is closed'));
     const result = queue.then(async () => {
@@ -3596,7 +3909,7 @@ async function startTestClaimBroker(claimPath) {
   const server = createServer(async (req, res) => {
     const auth = req.headers.authorization;
     const expected = `Bearer ${token}`;
-    if (req.method !== 'POST' || req.url !== '/event' || typeof auth !== 'string' || Buffer.byteLength(auth) !== Buffer.byteLength(expected) || !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
+    if (req.method !== 'POST' || !['/event', '/containment'].includes(req.url) || typeof auth !== 'string' || Buffer.byteLength(auth) !== Buffer.byteLength(expected) || !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
       res.writeHead(403).end();
       req.resume();
       return;
@@ -3607,7 +3920,7 @@ async function startTestClaimBroker(claimPath) {
         body += chunk.toString('utf8');
         if (Buffer.byteLength(body) > 1024 * 1024) throw new Error('Test claim event too large');
       }
-      await update(parseTestClaimJson(body));
+      if (req.url === '/containment') await containment(parseTestClaimJson(body));else await update(parseTestClaimJson(body));
       res.writeHead(204).end();
     } catch {
       res.writeHead(409).end('Test claim registration rejected');
@@ -3621,14 +3934,21 @@ async function startTestClaimBroker(claimPath) {
   });
   const address = server.address();
   if (!address || typeof address === 'string') throw new Error('Cannot bind test claim broker');
+  const url = `http://127.0.0.1:${address.port}/event`;
+  liveWindowsBrokers.set(token, {
+    url,
+    register
+  });
   return {
     env: {
-      [TEST_CLAIM_URL_ENV]: `http://127.0.0.1:${address.port}/event`,
+      [TEST_CLAIM_URL_ENV]: url,
       [TEST_CLAIM_TOKEN_ENV]: token
     },
     update,
     async close() {
       closing = true;
+      liveWindowsBrokers.delete(token);
+      verifiers.clear();
       await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
       await queue;
     }
@@ -3669,6 +3989,36 @@ async function sendTestClaimEvent(env, event) {
     throw new Error('Managed test allocation registration failed');
   }
 }
+
+/** A transient authenticated gate: success is live exact membership, never a durable process event. */
+async function assertTestClaimWindowsJob(env, identity) {
+  try {
+    if (!hasTestClaimTransport(env)) throw new Error('Missing test claim transport');
+    const query = {
+      runId: env.VONA_TEST_RUN_ID,
+      guardianId: env[TEST_CLAIM_WINDOWS_GUARDIAN_ENV],
+      process: {
+        pid: identity.pid,
+        startTime: identity.startTime,
+        host: identity.host
+      }
+    };
+    validateWindowsJobQuery(query);
+    const response = await fetch(new URL('/containment', env[TEST_CLAIM_URL_ENV]), {
+      method: 'POST',
+      headers: {
+        'authorization': `Bearer ${env[TEST_CLAIM_TOKEN_ENV]}`,
+        'content-type': 'application/json'
+      },
+      body: JSON.stringify(query),
+      signal: AbortSignal.timeout(7000),
+      redirect: 'error'
+    });
+    if (response.status !== 204) throw new Error('Containment rejected');
+  } catch {
+    throw new Error('Managed Windows browser containment verification failed');
+  }
+}
 function getTestClaimRedisPrefix(runId, clientName) {
   const appName = getTestAppName(runId);
   if (clientName === 'broadcast') return undefined;
@@ -4325,13 +4675,16 @@ async function _closeInner() {
   clearTimeout(timeout);
   process.exit(err ? 1 : 0);
 }
+
+// The authenticated test health endpoint uses the same guard and cleanup as signals.
+async function closeProcessWorker() {
+  if (__closing) return;
+  __closing = true;
+  await _closeInner();
+}
 function handleProcessWork() {
   ['SIGINT', 'SIGTERM', 'SIGUSR2'].forEach(signal => {
-    process.on(signal, async () => {
-      if (__closing) return;
-      __closing = true;
-      await _closeInner();
-    });
+    process.on(signal, closeProcessWorker);
   });
   process.on('uncaughtException', async err => {
     const app = useApp();
@@ -4492,5 +4845,5 @@ async function retry(options, fn) {
 
 zodExtendOpenApi();
 
-export { $Class, $localeScope, $makeLocaleMagic, $protocolKey, AppHmr, AppHmrDeps, AppLocale, AppLogger, AppMeta, AppMetadata, AppResource, AppUtil, BeanAopBase, BeanAopMethodBase, BeanBase, BeanBaseSimple, BeanContainer, BeanInfo, BeanScopeBase, BeanScopeContainer, BeanScopeError, BeanScopeErrorImpl, BeanScopeLocale, BeanScopeScene, BeanScopeUtil, BeanSimple, EnumAppEvent, ErrorClass, Global, LocaleModuleNameSeparator, PickClassInner, ProxyDisable, SymbolBeanContainerInstances, SymbolBeanFullName, SymbolBeanInstanceKey, SymbolBeanInstancePropsLazy, SymbolCacheAopChains, SymbolCacheAopChainsKey, SymbolDecoratorBeanFullName, SymbolDecoratorBeanInfo, SymbolDecoratorGlobal, SymbolDecoratorProxyDisable, SymbolDecoratorUse, SymbolDecoratorVirtual, SymbolHmrStateLoad, SymbolHmrStateSave, SymbolMappedClassMetadataKeys, SymbolModuleBelong, SymbolModuleName, TEST_CLAIM_DIRECTORY, TEST_CLAIM_TOKEN_ENV, TEST_CLAIM_URL_ENV, TEST_RUN_ID_ENV, TEST_RUN_OWNER_FILE, Use, Virtual, VonaApplication, __prepareInjectSelectorInfo, appHmrDeps, appMetadata, appResource, assertDisposableDatabaseName, assertIsolatedTestConfig, assertIsolatedTestDatabaseClient, assertIsolatedTestPath, assertTestAppIdentity, assertTestClaimDatabaseClient, assertTestClaimRedisClient, assertTestClaimSafePath, assertTestRunOwner, beanFullNameFromOnionName, bootstrap, buildTestClaimResourceInventory, cast, closeApp, combineConfigDefault, combineFilePathSafe, compose, copyAddon, copyMetadataOfClasses, copyProperties, copyPropertiesOfClasses, createApp, createAppMaster, createBeanDecorator, createGeneralApp, createHash, createTestClaim, deepExtend, disposeInstance, errorsInternal, filterHeaders, formatLoggerAxiosError, formatLoggerConsole, formatLoggerCtx, formatLoggerDummy, formatLoggerErrors, formatLoggerFilter, functionNoop, getDatabaseTestPrefix, getHomeVonaAppDir, getLoggerPathPhysicalRoot, getMappedClassMetadataKeys, getPlatformArch, getPublicPathPhysicalRoot, getRuntimePathPhysicalRoot, getSqlite3DatabaseNameDefault, getTestAppName, getTestClaimCreatedAt, getTestClaimPaths, getTestClaimRedisPrefix, getTestRunIdFromEnv, hasTestClaimTransport, instanceDesp, isLocaleMagic, loadJSONFile, loadTestClaim, mergeTestClaimDatabaseOptions, mergeTestClaimRedisOptions, normalizeTestClaimDatabaseEndpoint, normalizeTestClaimRedisEndpoint, onionNameFromBeanFullName, pathToHref, polyfillDispose, prepareEnv, registerMappedClassMetadataKey, registerTestClaimDatabaseCreation, registerTestClaimResourceInventory, requireAddon, requireDynamic, resolveAddon, resolveTestRunId, resolveVonaLocalPaths, resolverSharp, resolverSharpLibvips, resolverSqlite3, retry, saveJSONFile, sendTestClaimEvent, setMappedClassMetadataKeys, startTestClaimBroker, text$1 as text, useApp, usePrepareArg, usePrepareArgs, uuidv4, validateTestClaim, withIsolatedTestDatabaseDiscovery, writeTestClaim };
+export { $Class, $localeScope, $makeLocaleMagic, $protocolKey, AppHmr, AppHmrDeps, AppLocale, AppLogger, AppMeta, AppMetadata, AppResource, AppUtil, BeanAopBase, BeanAopMethodBase, BeanBase, BeanBaseSimple, BeanContainer, BeanInfo, BeanScopeBase, BeanScopeContainer, BeanScopeError, BeanScopeErrorImpl, BeanScopeLocale, BeanScopeScene, BeanScopeUtil, BeanSimple, EnumAppEvent, ErrorClass, Global, LocaleModuleNameSeparator, PickClassInner, ProxyDisable, SymbolBeanContainerInstances, SymbolBeanFullName, SymbolBeanInstanceKey, SymbolBeanInstancePropsLazy, SymbolCacheAopChains, SymbolCacheAopChainsKey, SymbolDecoratorBeanFullName, SymbolDecoratorBeanInfo, SymbolDecoratorGlobal, SymbolDecoratorProxyDisable, SymbolDecoratorUse, SymbolDecoratorVirtual, SymbolHmrStateLoad, SymbolHmrStateSave, SymbolMappedClassMetadataKeys, SymbolModuleBelong, SymbolModuleName, TEST_CLAIM_DIRECTORY, TEST_CLAIM_TOKEN_ENV, TEST_CLAIM_URL_ENV, TEST_CLAIM_WINDOWS_GUARDIAN_ENV, TEST_RUN_ID_ENV, TEST_RUN_OWNER_FILE, Use, Virtual, VonaApplication, __prepareInjectSelectorInfo, appHmrDeps, appMetadata, appResource, assertDisposableDatabaseName, assertIsolatedTestConfig, assertIsolatedTestDatabaseClient, assertIsolatedTestPath, assertTestAppIdentity, assertTestClaimDatabaseClient, assertTestClaimRedisClient, assertTestClaimSafePath, assertTestClaimWindowsJob, assertTestRunOwner, beanFullNameFromOnionName, bootstrap, buildTestClaimResourceInventory, cast, closeApp, closeProcessWorker, combineConfigDefault, combineFilePathSafe, compose, copyAddon, copyMetadataOfClasses, copyProperties, copyPropertiesOfClasses, createApp, createAppMaster, createBeanDecorator, createGeneralApp, createHash, createTestClaim, deepExtend, disposeInstance, errorsInternal, filterHeaders, formatLoggerAxiosError, formatLoggerConsole, formatLoggerCtx, formatLoggerDummy, formatLoggerErrors, formatLoggerFilter, functionNoop, getDatabaseTestPrefix, getHomeVonaAppDir, getLoggerPathPhysicalRoot, getMappedClassMetadataKeys, getPlatformArch, getPublicPathPhysicalRoot, getRuntimePathPhysicalRoot, getSqlite3DatabaseNameDefault, getTestAppName, getTestClaimCreatedAt, getTestClaimPaths, getTestClaimRedisPrefix, getTestRunIdFromEnv, hasTestClaimTransport, instanceDesp, isLocaleMagic, loadJSONFile, loadTestClaim, mergeTestClaimDatabaseOptions, mergeTestClaimRedisOptions, normalizeTestClaimDatabaseEndpoint, normalizeTestClaimRedisEndpoint, onionNameFromBeanFullName, pathToHref, polyfillDispose, prepareEnv, registerMappedClassMetadataKey, registerTestClaimDatabaseCreation, registerTestClaimResourceInventory, registerTestClaimWindowsJobVerifier, requireAddon, requireDynamic, resolveAddon, resolveTestRunId, resolveVonaLocalPaths, resolverSharp, resolverSharpLibvips, resolverSqlite3, retry, saveJSONFile, sendTestClaimEvent, setMappedClassMetadataKeys, startTestClaimBroker, text$1 as text, useApp, usePrepareArg, usePrepareArgs, uuidv4, validateTestClaim, withIsolatedTestDatabaseDiscovery, writeTestClaim };
 //# sourceMappingURL=index.js.map