@vitest-agent/plugin 5.6.1 → 6.0.0

package/utils/failure-summary.js

@@ -0,0 +1,78 @@
+import { stripAnsi } from "@vitest-agent/sdk";
+
+// src/utils/failure-summary.ts
+const firstLine = (message) => {
+	for (const line of stripAnsi(message).split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed.length > 0) return trimmed;
+	}
+	return "";
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/**
+* Whether the plugin owns stdout in this console mode, so failure detail
+* never reaches stderr unless the reporter writes it there.
+*
+* @internal
+*/
+function shouldWriteFailureSummary(mode) {
+	return mode === "agent" || mode === "stream" || mode === "ci-annotations";
+}
+/**
+* Format a plain-text, ANSI-free failure summary for stderr: a count header
+* plus one entry per failed test, failed module and unhandled error (each
+* reduced to its first message line), capped at
+* {@link FAILURE_SUMMARY_MAX_LINES} lines. Returns `undefined` when there is
+* nothing to report.
+*
+* @internal
+*/
+function formatFailureSummary(reports, reason) {
+	const entries = [];
+	const files = /* @__PURE__ */ new Set();
+	const seenUnhandled = /* @__PURE__ */ new Set();
+	const unhandled = [];
+	let failedTests = 0;
+	for (const report of reports) {
+		for (const mod of report.failed) {
+			files.add(mod.file);
+			const moduleError = mod.errors?.[0];
+			if (moduleError !== void 0) {
+				const msg = firstLine(moduleError.message);
+				entries.push([`  FAIL ${mod.file}`, ...msg === "" ? [] : [`    ${msg}`]]);
+			}
+			for (const test of mod.tests) {
+				if (test.state !== "failed") continue;
+				failedTests++;
+				const msg = firstLine(test.errors?.[0]?.message ?? "");
+				entries.push([`  FAIL ${mod.file} > ${test.fullName}`, ...msg === "" ? [] : [`    ${msg}`]]);
+			}
+		}
+		for (const err of report.unhandledErrors) {
+			const msg = firstLine(err.message);
+			if (seenUnhandled.has(msg)) continue;
+			seenUnhandled.add(msg);
+			unhandled.push([`  ERROR ${msg}`]);
+		}
+	}
+	entries.push(...unhandled);
+	if (entries.length === 0 && reason !== "interrupted") return void 0;
+	const counts = [];
+	if (failedTests > 0) counts.push(`${plural(failedTests, "failed test")} in ${plural(files.size, "file")}`);
+	else if (files.size > 0) counts.push(plural(files.size, "failed file"));
+	if (unhandled.length > 0) counts.push(plural(unhandled.length, "unhandled error"));
+	const lines = [reason === "interrupted" ? `vitest-agent: run interrupted${counts.length > 0 ? `, ${counts.join(", ")}` : ""}` : `vitest-agent: ${counts.join(", ")}`];
+	let budget = 14;
+	if (entries.reduce((n, e) => n + e.length, 0) > budget) budget -= 1;
+	let shown = 0;
+	for (const entry of entries) {
+		if (entry.length > budget) break;
+		lines.push(...entry);
+		budget -= entry.length;
+		shown++;
+	}
+	if (shown < entries.length) lines.push(`  ... ${entries.length - shown} more`);
+	return lines.join("\n");
+}
+
+export { formatFailureSummary, shouldWriteFailureSummary };

package/utils/find-test-files.js

@@ -1,99 +1,82 @@
-import { toPosixPath } from "./to-posix-path.js";
-import { nodeWalkerFs } from "./walker-fs.js";
-import { join, relative } from "node:path";
+import { join } from "node:path";
 import { NON_DISCOVERABLE_DIRS } from "@vitest-agent/sdk";
+import { Result } from "effect";
+import { GlobPattern } from "@effected/glob";
+import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+import { descendEntriesSync, descendSync } from "@effected/walker";
 
 // src/utils/find-test-files.ts
-function globToRegex(pattern) {
-	const alts = expandBraces(pattern).map(toRegexFragment);
-	return new RegExp(`^(?:${alts.join("|")})$`);
-}
-/** Expands the FIRST brace group found in a pattern string. Recursive to handle nesting. */
-function expandBraces(pattern) {
-	const open = pattern.indexOf("{");
-	if (open === -1) return [pattern];
-	const close = pattern.indexOf("}", open);
-	if (close === -1) return [pattern];
-	const prefix = pattern.slice(0, open);
-	const suffix = pattern.slice(close + 1);
-	const alternatives = pattern.slice(open + 1, close).split(",");
-	const results = [];
-	for (const alt of alternatives) for (const expanded of expandBraces(`${prefix}${alt}${suffix}`)) results.push(expanded);
-	return results;
-}
-/** Converts a brace-free glob string into a regex fragment (no ^ or $). */
-function toRegexFragment(glob) {
-	let result = "";
-	let i = 0;
-	while (i < glob.length) {
-		const ch = glob[i];
-		if (ch === "*") {
-			if (glob[i + 1] === "*") {
-				result += "(?:.+/|)";
-				i += 2;
-				if (glob[i] === "/") i++;
-			} else {
-				result += "[^/]*";
-				i++;
-			}
-		} else if (ch === "?") {
-			result += "[^/]";
-			i++;
-		} else if (/[.+^${}()|[\]\\]/.test(ch)) {
-			result += `\\${ch}`;
-			i++;
-		} else {
-			result += ch;
-			i++;
-		}
-	}
-	return result;
-}
+const GLOB_OPTIONS = { dot: true };
+/** Every file, dot entries included: the pattern the signature walk expands. */
+const EVERY_FILE = Result.getOrThrow(GlobPattern.compileResult("**", GLOB_OPTIONS));
+/**
+* The walk rules every discovery walk shares, so the test-file walk, the
+* cache-signature walk and the engine's `ProjectDiscoveryLive` see one tree.
+* `NON_DISCOVERABLE_DIRS` is pruned before descending (a fixture
+* `node_modules` must never drag in the pnpm store); symlinked directories
+* are followed under the walker's ancestor-chain cycle guard; an unreadable
+* directory contributes nothing, as the `node:fs` walks this replaced did.
+*/
+const WALK_RULES = {
+	prune: [...NON_DISCOVERABLE_DIRS],
+	followSymlinks: true,
+	onUnreadable: "skip"
+};
 /**
-* Async file walker that returns matched absolute paths.
+* File walker that returns matched absolute paths.
 *
-* Walks `dir` recursively via `node:fs/promises`. Skips `node_modules`, `.git`,
-* and `dist` directories, and does not descend past a nested `package.json`
-* boundary (any directory other than `dir` itself that has its own
-* `package.json` is treated as an independent unit — its files belong to a
-* separate discovery pass, not this one). The package-boundary rule applies
+* Expands each pattern under `dir` with `@effected/walker`'s `descendSync`
+* over `ops` (default: `nodeWalkerSyncOps`). Skips `node_modules`, `.git`, and
+* `dist` directories, follows symlinked directories (a link loop is cut by
+* the walker's cycle guard), and does not descend past a nested
+* `package.json` boundary (any directory other than `dir` itself that has its
+* own `package.json` is treated as an independent unit — its files belong to
+* a separate discovery pass, not this one). The package-boundary rule applies
 * to every supplied pattern, not just an unanchored `**\/` one — an anchored
 * pattern like `"src/**\/*.test.ts"` will not match a test file under a
 * nested package.json even though the pattern itself never reaches past
-* `src/`, because the boundary check runs once per directory, independent of
-* which pattern is being matched. Matches files against the supplied glob
-* patterns relative to `dir` (e.g. `"src/**\/*.test.ts"`).
+* `src/`. Matches files against the supplied glob patterns relative to `dir`
+* (e.g. `"src/**\/*.test.ts"`); a pattern that fails to compile matches
+* nothing.
 *
 * Returns an empty array if `dir` does not exist or no files match.
 * @param dir - Absolute path to the directory to walk
 * @param patterns - Glob patterns to match against (relative to `dir`)
-* @returns Absolute paths of matched test files
+* @param ops - The sync filesystem the walk reads through
+* @returns Absolute paths of matched test files, each pattern's matches sorted, deduplicated across patterns
 * @public
 */
-async function findTestFiles(dir, patterns, fs = nodeWalkerFs) {
-	if (patterns.length === 0) return [];
-	const matchers = patterns.map(globToRegex);
-	const results = [];
-	await walkDir(dir, dir, matchers, results, fs);
-	return results;
-}
-async function walkDir(root, dir, matchers, results, fs) {
-	let entries;
-	try {
-		entries = await fs.readDirectory(dir);
-	} catch {
-		return;
-	}
-	if (dir !== root && entries.some((ent) => ent.isFile() && ent.name === "package.json")) return;
-	for (const ent of entries) {
-		if (NON_DISCOVERABLE_DIRS.has(ent.name)) continue;
-		const fullPath = join(dir, ent.name);
-		if (ent.isDirectory()) await walkDir(root, fullPath, matchers, results, fs);
-		else if (ent.isFile()) {
-			const rel = toPosixPath(relative(root, fullPath));
-			if (matchers.some((re) => re.test(rel))) results.push(fullPath);
-		}
+async function findTestFiles(dir, patterns, ops = nodeWalkerSyncOps) {
+	const results = /* @__PURE__ */ new Set();
+	for (const source of patterns) {
+		const compiled = GlobPattern.compileResult(source, GLOB_OPTIONS);
+		if (Result.isFailure(compiled)) continue;
+		const matches = descendSync(compiled.success, {
+			cwd: dir,
+			boundaries: ["package.json"],
+			...WALK_RULES,
+			...ops
+		});
+		if (Result.isFailure(matches)) throw matches.failure;
+		for (const rel of matches.success) results.add(join(dir, rel));
 	}
+	return [...results];
+}
+/**
+* A cheap signature (relative path + mtimeMs pairs, sorted) for every file
+* under `dir`, read from the stats the walk already took — no content reads.
+* Empty when `dir` does not exist, which is still a stable, comparable
+* contribution. The same walk rules as {@link findTestFiles}, minus the
+* package boundary, so a change anywhere under the directory invalidates.
+*/
+function directorySignature(dir, ops) {
+	const entries = descendEntriesSync(EVERY_FILE, {
+		cwd: dir,
+		...WALK_RULES,
+		...ops
+	});
+	if (Result.isFailure(entries)) throw entries.failure;
+	return entries.success.map((entry) => `${entry.path}:${entry.info.mtimeMs}`).join("|");
 }
 
-export { findTestFiles };
+export { directorySignature, findTestFiles };

package/utils/is-test-shaped-package.js

@@ -1,7 +1,8 @@
-import { nodeWalkerFs } from "./walker-fs.js";
 import { findTestFiles } from "./find-test-files.js";
+import { statOrNull } from "./walker-fs.js";
 import { join } from "node:path";
 import { BATS_FILE_GLOB_SUFFIX, SRC_DIR, TEST_DIR, TEST_FILE_GLOB_SUFFIX } from "@vitest-agent/sdk";
+import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
 
 // src/utils/is-test-shaped-package.ts
 /**
@@ -41,13 +42,13 @@ import { BATS_FILE_GLOB_SUFFIX, SRC_DIR, TEST_DIR, TEST_FILE_GLOB_SUFFIX } from
 * `findTestFiles` walker, rather than re-deriving the shape independently.
 * @internal
 */
-async function isTestShapedPackage(pkgPath, fs = nodeWalkerFs) {
+async function isTestShapedPackage(pkgPath, fs = nodeWalkerSyncOps) {
 	if ((await findTestFiles(pkgPath, [
 		`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`,
 		`${TEST_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`,
 		`**/${BATS_FILE_GLOB_SUFFIX}`
 	], fs)).length > 0) return false;
-	return (await fs.statEntry(join(pkgPath, TEST_DIR)))?.isDirectory === true;
+	return statOrNull(fs, join(pkgPath, TEST_DIR))?.isDirectory() === true;
 }
 
 export { isTestShapedPackage };

package/utils/resolve-coverage-dir-isolation.js

@@ -17,7 +17,7 @@ const OPT_OUT_VALUES = /* @__PURE__ */ new Set([
 * `coverage.reportsDirectory` by default; the v8 provider's `clean: true`
 * default `rm -rf`s that directory at run start, so one run can delete the
 * other's `.tmp` files mid-run (issue #194). The MCP `run_tests` path
-* already isolates via `makeCoverageDirOverride()`; this function drives
+* already isolates via a per-call temp directory; this function drives
 * the equivalent decision for the plain-CLI (`AgentPlugin.configureVitest`)
 * path.
 *

package/utils/run-diagnostics.js

@@ -0,0 +1,24 @@
+// src/utils/run-diagnostics.ts
+/**
+* The `Symbol.for` key under which `onTestRunEnd` publishes the run's
+* diagnostics on the Vitest instance. `Symbol.for` resolves to the identical
+* symbol across module copies in one process, so the MCP `run_tests` tool
+* reads the same slot without importing the plugin.
+*
+* @internal
+*/
+const RUN_DIAGNOSTICS_SYMBOL = Symbol.for("vitest-agent:run-diagnostics");
+/**
+* Publish the run's diagnostics on the Vitest instance for readers in the
+* same process (the MCP `run_tests` tool). Any defined diagnostics are
+* published, so a clean run still carries its post-run timing and overwrites
+* the previous run's value; only `undefined` clears the slot, so a watch-mode
+* rerun never reports a stale diagnostic.
+*
+* @internal
+*/
+const publishRunDiagnostics = (vitest, d) => {
+	vitest[RUN_DIAGNOSTICS_SYMBOL] = d;
+};
+
+export { RUN_DIAGNOSTICS_SYMBOL, publishRunDiagnostics };

package/utils/run-script-lock.js

@@ -1,267 +1,111 @@
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
 
 // src/utils/run-script-lock.ts
 /**
-* File-based advisory lock backing `AgentPlugin.runScript` (issue #191,
-* sub-item B). Two concurrent `vitest` invocations in one checkout used
-* to both run the `globalSetup` build and race — this lock serializes
-* them: the first process to acquire the lock runs the command and
-* marks a "done" timestamp on success; a concurrent process polls,
-* and once the marker is fresh enough (`builtRecentlyMs`) it trusts
-* the winner's build and skips its own.
-*
-* A stale-lock takeover exists because a process that crashed or was
-* killed mid-build leaves the lock file behind forever otherwise —
-* every future `vitest` invocation would hang. Takeover is a two-tier
-* rule, never age alone:
-*
-* 1. The lock file records the owner's pid. Once the lock is older
-*    than `staleMs`, that pid is probed with `process.kill(pid, 0)`.
-*    A live owner (probe succeeds, or fails `EPERM` — the process
-*    exists but belongs to another user) is NEVER taken over, no
-*    matter how old the lock is: a slow-but-live build must not have
-*    its lock stolen and the command double-run.
-* 2. Only a dead owner (`ESRCH`), or a lock file whose owner record is
-*    missing/corrupt (in which case age is all we have to go on),
-*    is taken over.
-*
-* Release is ownership-gated for the same reason: `acquireRunScriptLock`
-* stamps a random per-acquisition nonce into the lock file, and
-* `releaseRunScriptLock` deletes the file only when the nonce on disk is
-* still its own. Without that, an original owner that lost its lock to a
-* takeover would delete the *takeover* owner's lock in its `finally`,
-* letting a third process in while the second is still building.
-*
-* A generous `waitTimeoutMs` safety valve exists so a genuinely slow
-* (but still live) build doesn't hang the waiter forever either: past
-* that timeout the waiter gives up, `acquireRunScriptLock` returns
-* `{ acquired: false, recentlyBuilt: false }`, and the caller
-* (`AgentPlugin.runScript`) goes ahead and runs its own command
-* unserialized. That reproduces the original race for that one pair of
-* processes rather than blocking indefinitely — a deliberate,
-* documented escape valve, not an oversight.
+* The `RunOnce` settings behind `AgentPlugin.runScript` (issue #191). The
+* lock protocol itself — exclusive create, nonce-observed trust, pid-and-host
+* probed takeover, owner-only release — is `@effected/commands`' `RunOnce`;
+* this module only derives the key, the directory and the timings one
+* `runScript` call runs under.
 *
 * @packageDocumentation
 */
-/**
-* A build whose owning process is *gone* and whose lock is older than
-* this is presumed abandoned (crashed process, killed job) and taken
-* over. Age alone never triggers a takeover — the recorded pid is
-* probed first, and a live owner keeps its lock past this age (see the
-* module doc comment). One minute comfortably covers the `globalSetup`
-* build steps this lock is built for; the pid probe is what protects
-* the longer ones.
-*/
-const DEFAULT_LOCK_STALE_MS = 6e4;
-/** How long a waiter sleeps between polls of an active lock. */
-const DEFAULT_LOCK_POLL_MS = 200;
-/** How long a waiter blocks before giving up and running its own build independently. */
-const DEFAULT_LOCK_WAIT_TIMEOUT_MS = 6e5;
-/** A done-marker fresher than this is trusted without re-running the command. */
-const DEFAULT_BUILT_RECENTLY_MS = 3e4;
+/** Floor for the poll interval, matching the floor `RunOnce` itself enforces. */
+const MIN_LOCK_POLL_MS = 10;
 /**
 * Strictly parses a millisecond timing supplied through one of the
-* `VITEST_AGENT_RUNSCRIPT_*` env overrides, falling back to `fallback`
-* for anything that is not a whole positive integer at or above
-* `minimum`.
-*
-* `Number.parseInt` is deliberately not used on its own: it happily
-* accepts `"200ms"` (→ 200) and `"-1"` (→ a negative stale window,
-* which makes every lock instantly stale) and `"0"` for a poll interval
-* (a tight spin loop). An unusable override falls back to the default
-* rather than silently degrading the lock.
+* `VITEST_AGENT_RUNSCRIPT_*` env overrides, answering `undefined` (the
+* `RunOnce` default) for anything that is not a whole positive integer at or
+* above `minimum`.
 *
-* @public
+* `Number.parseInt` is deliberately not used on its own: it happily accepts
+* `"200ms"` (→ 200), `"-1"` and `"0"`, and `RunOnce` treats a non-positive or
+* sub-10ms timing as a wiring defect and throws. An unusable override falls
+* back to the default instead.
 */
-function parseLockTimingOverride(raw, fallback, minimum = 1) {
-	if (raw === void 0) return fallback;
+function parseLockTimingOverride(raw, minimum = 1) {
+	if (raw === void 0) return void 0;
 	const trimmed = raw.trim();
-	if (!/^\d+$/.test(trimmed)) return fallback;
+	if (!/^\d+$/.test(trimmed)) return void 0;
 	const parsed = Number.parseInt(trimmed, 10);
-	if (!Number.isSafeInteger(parsed) || parsed < minimum) return fallback;
+	if (!Number.isSafeInteger(parsed) || parsed < minimum) return void 0;
 	return parsed;
 }
 /**
-* Resolves the directory `runScript` locks and done-markers live in:
-* `XDG_DATA_HOME` when set (matching `@vitest-agent/sdk`'s `data.db`
-* resolution convention), else the same `~/.local/share` fallback that
-* convention documents.
+* The directory `runScript` locks and done-markers live in:
+* `$XDG_DATA_HOME/vitest-agent/runscript-locks`, else the `~/.local/share`
+* fallback the `data.db` convention documents.
 *
-* @public
+* @remarks
+* `RunOnce` recommends a host-local runtime or state directory over a data
+* directory. The plugin has no `@effected/xdg` dependency to resolve one, so
+* the location stays where 2.x put it.
 */
-function resolveRunScriptLockDir(env = process.env, home = homedir()) {
+function resolveRunScriptLockDir(env, home = homedir()) {
 	const xdg = env.XDG_DATA_HOME;
 	const base = xdg !== void 0 && xdg.length > 0 ? xdg : join(home, ".local", "share");
 	return join(base, "vitest-agent", "runscript-locks");
 }
 /**
-* Deterministic, filesystem-safe key for one (workspace, command) pair
-* so different `globalSetup` commands in the same checkout don't share
-* a lock, while repeat invocations of the *same* command in the *same*
-* workspace do.
+* The lock key for one command in one directory: a SHA-256 over the
+* directory the command runs in and the command. Concurrent callers share a
+* lock, and a waiter trusts the owner's run, only when they would execute
+* the same command in the same place (the #191 race); a package's build and
+* the root's are different runs. A string command and an argv command never
+* share a key: the argv form hashes its JSON encoding.
 */
-function computeLockKey(cwd, command) {
-	return createHash("sha256").update(`${cwd}\n${command}`).digest("hex").slice(0, 16);
-}
-/** Reads the owner record from a lock file. Returns `null` when the file is missing, unreadable, or not a well-formed owner record (e.g. observed mid-write by its creator). */
-function readLockOwner(lockPath) {
-	let raw;
-	try {
-		raw = readFileSync(lockPath, "utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed?.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0) return null;
-		if (typeof parsed.nonce !== "string" || parsed.nonce.length === 0) return null;
-		return {
-			pid: parsed.pid,
-			nonce: parsed.nonce,
-			startedAt: String(parsed.startedAt ?? "")
-		};
-	} catch {
-		return null;
-	}
+function runScriptLockKey(cwd, command) {
+	const identity = typeof command === "string" ? `sh\n${command}` : `argv\n${JSON.stringify(command)}`;
+	return `runscript-${createHash("sha256").update(`${cwd}\n${identity}`).digest("hex").slice(0, 32)}`;
 }
 /**
-* Signal-0 liveness probe. `EPERM` means the process exists but is
-* owned by another user — still alive, and emphatically not ours to
-* take over. Anything else (`ESRCH`) means it is gone.
-*/
-function isProcessAlive(pid) {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (err) {
-		return err.code === "EPERM";
-	}
-}
-function defaultSleep(ms) {
-	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function isRecentlyBuilt(doneMarkerPath, builtRecentlyMs) {
-	try {
-		return Date.now() - statSync(doneMarkerPath).mtimeMs < builtRecentlyMs;
-	} catch {
-		return false;
-	}
-}
-function lockAgeMs(lockPath) {
-	try {
-		return Date.now() - statSync(lockPath).mtimeMs;
-	} catch {
-		return null;
-	}
-}
-/**
-* Acquires (or observes) the advisory lock for one (cwd, command) pair.
-* Blocks the calling thread (via `sleep`) while another process holds
-* a non-stale lock, up to `waitTimeoutMs`.
+* The `RunOnce` options one `runScript` call runs under, from the caller's
+* cwd (where the command runs) and environment.
 *
-* @public
+* @remarks
+* `VITEST_AGENT_RUNSCRIPT_LOCK_STALE_MS`, `_LOCK_WAIT_TIMEOUT_MS` and
+* `_LOCK_POLL_MS` tune the protocol (the concurrency e2e suite shortens
+* them). `VITEST_AGENT_RUNSCRIPT_BUILT_RECENTLY_MS` is an opt-in: set, a done
+* marker that young is trusted even from a previous sequential run; unset, a
+* marker is trusted only from an owner this caller watched hold the lock.
 */
-function acquireRunScriptLock(options) {
-	const { cwd, command, lockDir = resolveRunScriptLockDir(), staleMs = DEFAULT_LOCK_STALE_MS, waitTimeoutMs = DEFAULT_LOCK_WAIT_TIMEOUT_MS, pollMs = 200, builtRecentlyMs = DEFAULT_BUILT_RECENTLY_MS, sleep = defaultSleep } = options;
-	mkdirSync(lockDir, { recursive: true });
-	const key = computeLockKey(cwd, command);
-	const lockPath = join(lockDir, `${key}.lock`);
-	const doneMarkerPath = join(lockDir, `${key}.done`);
-	const deadline = Date.now() + waitTimeoutMs;
-	for (;;) {
-		if (isRecentlyBuilt(doneMarkerPath, builtRecentlyMs)) return {
-			lockPath,
-			doneMarkerPath,
-			acquired: false,
-			recentlyBuilt: true,
-			ownerNonce: null
-		};
-		let fd = null;
-		try {
-			fd = openSync(lockPath, "wx");
-		} catch (err) {
-			if (err.code !== "EEXIST") throw err;
-		}
-		if (fd !== null) {
-			const ownerNonce = randomBytes(12).toString("hex");
-			const record = {
-				pid: process.pid,
-				nonce: ownerNonce,
-				startedAt: (/* @__PURE__ */ new Date()).toISOString()
-			};
-			try {
-				writeSync(fd, JSON.stringify(record));
-			} catch (err) {
-				try {
-					rmSync(lockPath, { force: true });
-				} catch {}
-				throw err;
-			} finally {
-				try {
-					closeSync(fd);
-				} catch {}
-			}
-			return {
-				lockPath,
-				doneMarkerPath,
-				acquired: true,
-				recentlyBuilt: false,
-				ownerNonce
-			};
-		}
-		const age = lockAgeMs(lockPath);
-		if (age !== null && age > staleMs) {
-			const owner = readLockOwner(lockPath);
-			if (owner === null || !isProcessAlive(owner.pid)) {
-				try {
-					rmSync(lockPath, { force: true });
-				} catch {}
-				continue;
-			}
-		}
-		if (Date.now() > deadline) return {
-			lockPath,
-			doneMarkerPath,
-			acquired: false,
-			recentlyBuilt: false,
-			ownerNonce: null
-		};
-		sleep(pollMs);
-	}
+function runScriptOptions(command, cwd, env) {
+	const staleMs = parseLockTimingOverride(env.VITEST_AGENT_RUNSCRIPT_LOCK_STALE_MS);
+	const waitTimeoutMs = parseLockTimingOverride(env.VITEST_AGENT_RUNSCRIPT_LOCK_WAIT_TIMEOUT_MS);
+	const pollMs = parseLockTimingOverride(env.VITEST_AGENT_RUNSCRIPT_LOCK_POLL_MS, MIN_LOCK_POLL_MS);
+	const trustSequentialMs = parseLockTimingOverride(env.VITEST_AGENT_RUNSCRIPT_BUILT_RECENTLY_MS);
+	return {
+		key: runScriptLockKey(cwd, command),
+		dir: resolveRunScriptLockDir(env),
+		...staleMs !== void 0 ? { staleMs } : {},
+		...waitTimeoutMs !== void 0 ? { waitTimeoutMs } : {},
+		...pollMs !== void 0 ? { pollMs } : {},
+		...trustSequentialMs !== void 0 ? { trustSequentialMs } : {}
+	};
 }
 /**
-* Releases a lock this process acquired. No-op when `lock.acquired` is
-* `false` (this process never owned it), and — critically — also a
-* no-op when the lock file on disk no longer carries this
-* acquisition's nonce: that means the lock was taken over and now
-* belongs to somebody else's in-flight build. Deleting it there would
-* admit a third process while the second is still running the command.
-*
-* @public
-*/
-function releaseRunScriptLock(lock) {
-	if (!lock.acquired || lock.ownerNonce === null) return;
-	const owner = readLockOwner(lock.lockPath);
-	if (owner === null || owner.nonce !== lock.ownerNonce) return;
-	try {
-		rmSync(lock.lockPath, { force: true });
-	} catch {}
-}
-/**
-* Marks a successful build, so a waiter's next `isRecentlyBuilt` check
-* can skip re-running the command. Best-effort: a write failure just
-* means the next process won't short-circuit, not a correctness
-* problem.
-*
-* @public
+* How a shell-string command runs: the platform shell `execSync` used, now
+* spawned explicitly so `RunOnce` stays argv-only. On Windows it is exactly
+* what Node's `shell` option spawns: `cmd.exe /d /s /c "<command>"` with
+* verbatim arguments, so `cmd` (not Node's argv escaping) parses the quotes.
 */
-function markRunScriptDone(lock) {
-	try {
-		writeFileSync(lock.doneMarkerPath, String(Date.now()));
-	} catch {}
+function shellCommand(command, platform, env) {
+	return platform === "win32" ? {
+		argv: [
+			env.ComSpec ?? "cmd.exe",
+			"/d",
+			"/s",
+			"/c",
+			`"${command}"`
+		],
+		windowsVerbatimArguments: true
+	} : { argv: [
+		"/bin/sh",
+		"-c",
+		command
+	] };
 }
 
-export { DEFAULT_BUILT_RECENTLY_MS, DEFAULT_LOCK_STALE_MS, DEFAULT_LOCK_WAIT_TIMEOUT_MS, acquireRunScriptLock, markRunScriptDone, parseLockTimingOverride, releaseRunScriptLock, resolveRunScriptLockDir };
+export { parseLockTimingOverride, resolveRunScriptLockDir, runScriptLockKey, runScriptOptions, shellCommand };