@vitest-agent/mcp 5.3.1 → 6.0.0

package/tools/run-tests.js

@@ -1,21 +1,19 @@
 import { McpSession } from "../session.js";
-import { createRequire } from "node:module";
 import { ToolOutputSchema } from "@effected/mcp";
-import { Data, Effect, Layer, Option, Path, Result, Schema, Semaphore } from "effect";
-import { DataReader, DataStore } from "@vitest-agent/engine";
+import { Context, Data, Effect, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
 import { Tool } from "effect/ai";
-import { AgentReport, SuggestedActionRecord, buildAgentReport, buildConsoleLeaks, coerceErrorField, collectConsoleLeakEntries, formatScopedCoverageNote, readStrayOutput } from "@vitest-agent/sdk";
-import { AsyncLocalStorage } from "node:async_hooks";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { DataReader, DataStore } from "@vitest-agent/engine";
+import { AgentReport, RunDiagnostics, SuggestedActionRecord, VITEST_CONFIG_FILES, buildAgentReport, buildConsoleLeaks, coerceErrorField, collectConsoleLeakEntries, formatScopedCoverageNote, readStrayOutput, suggestedActionsFromRunDiagnostics } from "@vitest-agent/sdk";
+import { Exclusive, ProcessScope } from "@effected/engine";
 import { stat } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { Writable } from "node:stream";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
 import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
 import * as NodePath from "@effect/platform-node/NodePath";
-import { Git } from "@effected/git";
+import { ModuleResolution } from "@effected/commands/node-sync";
+import { Git, TreeIdentity } from "@effected/git";
+import { StdioCapture } from "@effected/mcp/node";
 import { Walker } from "@effected/walker";
 
 // src/tools/run-tests.ts
@@ -44,7 +42,8 @@ const RunTestsOk = Schema.Struct({
 	classifications: Schema.Record(Schema.String, Schema.String).annotate({ description: "Per-test classification labels: stable, new-failure, persistent, flaky, recovered." }),
 	discoveryLastScannedAt: Schema.optional(Schema.NullOr(Schema.String)).annotate({ description: "ISO timestamp of the most recent real disk scan performed by discoverProjects() in this process (issue #100). `null`/absent means discovery has not scanned disk in this process yet (e.g. a config that doesn't call AgentPlugin.discover()). A stale-looking test count is self-explaining when compared against this value." }),
 	scopedNote: Schema.optional(Schema.NullOr(Schema.String)).annotate({ description: "Set (issue #160) when this call was scoped to a subset of the project's test files (files/project/tags filter supplied). Vitest enforces coverage.thresholds against the whole-project denominator regardless of how many files ran, so a scoped run's threshold check is unreliable; this note explains why no coverage verdict should be trusted for this call. `null`/absent means the run was unscoped." }),
-	suggestedActions: Schema.optionalKey(Schema.Array(SuggestedActionRecord)).annotate({ description: "Run-level suggested actions the plugin raised at config time (issue #544): one entry per coverage-config diagnostic the plugin's ConfigValidation reported, such as a coverageTargets metric with no matching coverage.thresholds floor (severity warn). The same entries print on the plugin's stderr for a human and in the rendered report's Actions trailer. Absent when the project's config validated clean or does not load the plugin." })
+	suggestedActions: Schema.optionalKey(Schema.Array(SuggestedActionRecord)).annotate({ description: "Run-level suggested actions the plugin raised at config time (issue #544): one entry per coverage-config diagnostic the plugin's ConfigValidation reported, such as a coverageTargets metric with no matching coverage.thresholds floor (severity warn). The same entries print on the plugin's stderr for a human and in the rendered report's Actions trailer. Absent when the project's config validated clean or does not load the plugin. Includes the actions derived from `runDiagnostics`, after the config ones." }),
+	runDiagnostics: Schema.optionalKey(RunDiagnostics).annotate({ description: "Run-level diagnostics the plugin reporter published for this run (issue #544): Vitest performance hints, post-run timing (persist, coverage scan, total) and whether results were persisted. Their suggested actions are merged into `suggestedActions`. Absent when the project does not load the plugin." })
 }).annotate({ identifier: "RunTestsOk" });
 const RunTestsTimeout = Schema.Struct({
 	kind: Schema.Literal("timeout"),
@@ -142,6 +141,20 @@ function readConfigSuggestedActions(vitest) {
 	const decoded = Schema.decodeUnknownResult(Schema.Array(SuggestedActionRecord))(value);
 	return Result.isSuccess(decoded) ? decoded.success : void 0;
 }
+const RUN_DIAGNOSTICS_SYMBOL = Symbol.for("vitest-agent:run-diagnostics");
+/**
+* Reads the run diagnostics the plugin published on a Vitest instance.
+* `undefined` when none were published (no plugin, or a clean run) or the
+* slot holds a foreign shape; the value is decoded against `RunDiagnostics`.
+*
+* @internal
+*/
+function readRunDiagnostics(vitest) {
+	const value = vitest[RUN_DIAGNOSTICS_SYMBOL];
+	if (value === void 0 || value === null) return void 0;
+	const decoded = Schema.decodeUnknownResult(RunDiagnostics)(value);
+	return Result.isSuccess(decoded) ? decoded.success : void 0;
+}
 /**
 * Per-invocation coverage temp directory. Vitest's v8 provider `rm -rf`s the
 * shared `coverage/` reports directory at run start (`clean: true` default),
@@ -154,60 +167,39 @@ function readConfigSuggestedActions(vitest) {
 * coverage from SQLite (`CoverageAnalyzer` consumes the in-memory map via
 * `onCoverage`), not from disk artifacts.
 *
-* @internal exported for tests
+* Removed when the run's scope closes. The removal ignores a failure (a
+* directory already gone, a tmpdir reaper racing it): core's
+* `makeTempDirectoryScoped` dies on one, which would turn a finished run into
+* a defect.
 */
-const makeCoverageDirOverride = () => {
-	const dir = mkdtempSync(join(tmpdir(), "vitest-agent-cov-"));
-	return {
-		dir,
-		coverage: { reportsDirectory: dir }
-	};
-};
+const coverageTempDirectory = Effect.flatMap(FileSystem.FileSystem, (fs) => Effect.acquireRelease(fs.makeTempDirectory({ prefix: "vitest-agent-cov-" }), (dir) => fs.remove(dir, {
+	recursive: true,
+	force: true
+}).pipe(Effect.ignore)));
 /**
-* Typed wrapper for a rejected `vitest.start(...)` promise (issue #320).
-* Keeps the run's Effect error channel a tagged union so the timeout
-* branch can be recovered by tag instead of by string sentinel.
-*/
-var VitestStartFailure = class extends Data.TaggedError("VitestStartFailure") {};
-const stdoutSinkStorage = new AsyncLocalStorage();
-const stderrSinkStorage = new AsyncLocalStorage();
-let _stdioPatched = false;
-let _originalStdoutWrite;
-let _originalStderrWrite;
-function ensureStdioPatched() {
-	if (_stdioPatched) return;
-	_stdioPatched = true;
-	_originalStdoutWrite = process.stdout.write;
-	_originalStderrWrite = process.stderr.write;
-	process.stdout.write = function patchedStdoutWrite(...args) {
-		const sink = stdoutSinkStorage.getStore();
-		if (sink) return sink.write.apply(sink, args);
-		return _originalStdoutWrite.apply(this, args);
-	};
-	process.stderr.write = function patchedStderrWrite(...args) {
-		const sink = stderrSinkStorage.getStore();
-		if (sink) return sink.write.apply(sink, args);
-		return _originalStderrWrite.apply(this, args);
-	};
-}
+* Typed wrapper for a rejected step of the run (loading `vitest/node`,
+* `createVitest`, `vitest.start`, the coverage temp dir). Keeps the run's
+* error channel a tagged union so the timeout branches are recovered by tag
+* (issue #320), and carries the raw cause for the `{ kind: "error" }` message.
+*/
+var RunStepFailure = class extends Data.TaggedError("RunStepFailure") {};
 /**
-* Run `fn` with `process.stdout.write` and `process.stderr.write`
-* diverted to `stream.write` for code executing inside the call's
-* async context. Code in other async contexts (concurrent tool
-* procedure handlers, the MCP stdio transport) sees the original
-* writes unchanged.
-*
-* Vitest's own stdout/stderr redirect options only cover Vitest-internal
-* logging. User-registered reporters that call `console.log` directly
-* bypass them; this helper captures those writes into the supplied
-* sink so they don't corrupt the JSON-RPC protocol stream.
+* The stdio capture `run_tests` diverts the nested Vitest run's
+* `process.stdout` / `process.stderr` writes through, so a user reporter's
+* `console.log` never reaches the JSON-RPC wire while every other tool
+* handler (and the transport) keeps writing normally. `main.ts` installs it
+* once at boot and provides it; the default installs it on first use for an
+* embedder or a test that never ran `main.ts` (installing is idempotent per
+* stream).
 *
 * @internal
 */
-async function withStdioCaptured(stream, fn) {
-	ensureStdioPatched();
-	return stdoutSinkStorage.run(stream, () => stderrSinkStorage.run(stream, fn));
-}
+const RunTestsStdio = Context.Reference("@vitest-agent/mcp/RunTestsStdio", { defaultValue: () => StdioCapture.install(process) });
+/** Both streams discarded for the run's own async context. */
+const DISCARD_STDIO = {
+	stdout: StdioCapture.discard,
+	stderr: StdioCapture.discard
+};
 function sanitizeTestArgs(args) {
 	const result = [];
 	for (const arg of args) {
@@ -227,15 +219,6 @@ function sanitizeTestArgs(args) {
 * as a silent pass.
 */
 const gitCommonDir = (dir) => Effect.flatMap(Git, (git) => git.commonDir(dir)).pipe(Effect.option, Effect.map(Option.getOrNull), Effect.catchDefect(() => Effect.succeed(null)));
-const VITEST_CONFIG_PREFIXES = ["vitest.config.", "vite.config."];
-const VITEST_CONFIG_EXTENSIONS = [
-	"ts",
-	"mts",
-	"cts",
-	"js",
-	"mjs",
-	"cjs"
-];
 /**
 * The one walk both anchoring helpers share: step UP from `startDir`
 * until a vitest/vite config file is found, returning its absolute path.
@@ -256,7 +239,7 @@ const walkUpToConfigFile = (startDir) => Effect.gen(function* () {
 	const start = path.resolve(startDir);
 	const git = yield* Git;
 	const dirs = yield* Walker.ascendWithin(start, yield* Effect.option(git.repoRoot(start)));
-	const found = yield* Walker.findUpward(dirs, (dir) => VITEST_CONFIG_PREFIXES.flatMap((prefix) => VITEST_CONFIG_EXTENSIONS.map((ext) => path.join(dir, `${prefix}${ext}`))));
+	const found = yield* Walker.findUpward(dirs, (dir) => VITEST_CONFIG_FILES.map((name) => path.join(dir, name)));
 	return Option.getOrNull(found);
 }).pipe(Effect.catchDefect(() => Effect.succeed(null)));
 /**
@@ -333,6 +316,46 @@ async function validateProjectRoot(projectRoot, ctxCwd) {
 	};
 }
 /**
+* The tree identity for `dir` (`Git.treeIdentity`: its physical toplevel and
+* the shared common dir, from one `git rev-parse`), or `None` when git cannot
+* answer (not a repository, a bare repository, git failure). Git answers
+* physical paths, so identities are only ever compared with each other.
+*/
+const treeIdentityOf = (dir) => Effect.flatMap(Git, (git) => git.treeIdentity(dir)).pipe(Effect.orElseSucceed(() => Option.none()), Effect.catchDefect(() => Effect.succeed(Option.none())));
+/**
+* Issue #275: refuse a call whose hook-injected `_callerCwd` sits in a
+* DIFFERENT working tree of the same repository than the root the run would
+* use. Anything indeterminate (absent, empty, relative, nonexistent, not a
+* directory, outside git, a different repository) proceeds: the server
+* cannot tell, and refusing on absence would break every non-plugin
+* consumer.
+*
+* @internal exported for tests
+*/
+async function checkCallerWorktree(callerCwd, resolvedRoot) {
+	if (callerCwd === void 0 || callerCwd === "" || !isAbsolute(callerCwd)) return {
+		ok: true,
+		root: resolvedRoot
+	};
+	if (!await stat(callerCwd).then((s) => s.isDirectory(), () => false)) return {
+		ok: true,
+		root: resolvedRoot
+	};
+	const [caller, root] = await runOnNodePlatform(Effect.all([treeIdentityOf(callerCwd), treeIdentityOf(resolvedRoot)], { concurrency: 2 }));
+	if (Option.isNone(caller) || Option.isNone(root)) return {
+		ok: true,
+		root: resolvedRoot
+	};
+	if (TreeIdentity.relation(caller.value, root.value) !== "sibling-worktree") return {
+		ok: true,
+		root: resolvedRoot
+	};
+	return {
+		ok: false,
+		message: `This call came from the working tree "${caller.value.toplevel}" but the Vitest root resolved to "${root.value.toplevel}", a different working tree of the same repository, so the run would report results for the wrong tree. Pass projectRoot (the absolute path of your own working tree, "${caller.value.toplevel}") to run there.`
+	};
+}
+/**
 * Issue #303: resolve `vitest/node` anchored at the run's project root
 * instead of the bare `"vitest/node"` specifier, which resolves relative to
 * `@vitest-agent/mcp`'s OWN install location. `vitest` is a peerDependency
@@ -348,17 +371,16 @@ async function validateProjectRoot(projectRoot, ctxCwd) {
 * for '<file>' is not found. Did you call 'SnapshotClient.setup()'?" while
 * every non-snapshot assertion still passes.
 *
-* `createRequire` needs a file path (not a bare directory) to anchor
-* resolution, hence the synthetic, never-created `__vitest-agent-resolver__.js`
-* filename joined onto `root`. vitest's package.json `exports` map for
-* `./node` carries a `default` condition (`./dist/node.js`) and vitest ships
-* `"type": "module"`, so `require.resolve("vitest/node")` resolves correctly
-* even though vitest itself is ESM — the result is then converted to a
-* `file://` URL, which is what dynamic `import()` needs.
+* Resolution is `ModuleResolution.resolve` from `@effected/commands`,
+* anchored at `root` (a directory works as-is). vitest's package.json
+* `exports` map for `./node` carries a `default` condition, so CommonJS
+* resolution finds it even though vitest itself is ESM; the answer is the
+* real path (Node's resolver follows symlinks), which is the spelling that
+* identifies the module instance.
 *
 * Falls back to the bare `"vitest/node"` specifier when root-anchored
-* resolution throws (e.g. a project root with no local vitest install) so
-* that case keeps working exactly as it did before this fix.
+* resolution finds nothing (e.g. a project root with no local vitest
+* install) so that case keeps working exactly as it did before this fix.
 *
 * The property this buys — one module instance shared by the server and the
 * project's test files — is pinned by `vitest-node-module-identity.test.ts`
@@ -369,12 +391,7 @@ async function validateProjectRoot(projectRoot, ctxCwd) {
 * @internal exported for tests
 */
 function resolveVitestNodeEntry(root) {
-	try {
-		const req = createRequire(join(root, "__vitest-agent-resolver__.js"));
-		return pathToFileURL(req.resolve("vitest/node")).href;
-	} catch {
-		return "vitest/node";
-	}
+	return Option.getOrElse(ModuleResolution.resolve("vitest/node", { from: root }), () => "vitest/node");
 }
 /**
 * Issue #461: the MCP server is long-lived. When the lockfile is regenerated
@@ -382,36 +399,59 @@ function resolveVitestNodeEntry(root) {
 * store directory (peer-hash change), so the entry resolved for this process
 * no longer exists and every run would otherwise fail opaquely inside the fork
 * pool ("Worker forks emitted error", total: 0). Returns an actionable message
-* when `entry` is a `file://` URL whose path is missing on disk, else `null`.
-* The bare `"vitest/node"` fallback is not a path and is never checked. The
-* check is on the exact path that will be imported, because Node's require
-* resolution caches can hand back a stale path in a long-lived process.
+* when `entry` (an absolute path or a `file://` URL) is missing on disk
+* (`ModuleResolution.isStale`, which checks the exact path that will be
+* imported), else `null`. The bare `"vitest/node"` fallback is not a path and
+* is never stale.
 *
 * @internal exported for tests
 */
 function staleInstallMessage(entry) {
-	if (!entry.startsWith("file:")) return null;
-	const path = fileURLToPath(entry);
-	if (existsSync(path)) return null;
-	return `The resolved vitest entry "${path}" no longer exists on disk. The install changed since this vitest-agent MCP server loaded it (for example the lockfile was regenerated by a dependency install or branch switch). Restart the vitest-agent MCP server (in Claude Code: /mcp) or restart the session, then retry.`;
+	if (!ModuleResolution.isStale(entry)) return null;
+	return `The resolved vitest entry "${entry.startsWith("file:") ? fileURLToPath(entry) : entry}" no longer exists on disk. The install changed since this vitest-agent MCP server loaded it (for example the lockfile was regenerated by a dependency install or branch switch). Restart the vitest-agent MCP server (in Claude Code: /mcp) or restart the session, then retry.`;
 }
 /**
-* Indirection seam around `import(<vitest/node entry>)`. vitest's own
+* The test seam around resolving and importing `vitest/node`. vitest's own
 * vite-node externalizes "vitest"/"vitest/node" for every importer, and
-* `vi.mock("vitest/node", ...)` only special-cases AST-literal
-* `import("vitest/node")` call sites for interception — a computed
-* specifier (unavoidable here; see `resolveVitestNodeEntry`) silently
-* bypasses that interception and loads the real module. Tests substitute
-* `.load` directly (mutating this shared object's property — no `vi.mock`
-* required) instead of trying to mock the module.
+* `vi.mock("vitest/node", ...)` only intercepts AST-literal
+* `import("vitest/node")` call sites — a computed specifier (unavoidable
+* here; see `resolveVitestNodeEntry`) silently bypasses it. So the import is
+* `ModuleResolution.load` with an injectable `importer`: tests substitute
+* `.load` (the importer, called with the entry as a `file:` URL or the bare
+* fallback specifier) and `.resolveEntry` by mutating this shared object,
+* no `vi.mock` required. The production importer is this module's own
+* `import()`, never `ModuleResolution.load`'s default: the bare
+* `"vitest/node"` fallback must resolve from this package, which declares
+* the `vitest` peer, not from `@effected/commands`, which does not.
 *
 * @internal exported for tests
 */
 const vitestLoader = {
 	resolveEntry: (root) => resolveVitestNodeEntry(root),
-	load: (entry) => import(entry)
+	load: (url) => import(
+		/* @vite-ignore */
+		url
+)
 };
-const runTestsSemaphore = Effect.runSync(Semaphore.make(1));
+/**
+* The one-permit lane every `run_tests` body runs in. The body assigns the
+* active attribution UUIDs into `process.env.VITEST_AGENT_*`, enters the run's
+* root with `chdir`, and then awaits `createVitest` / `vitest.start`, which
+* spawns the worker pool that snapshots env (and cwd) at spawn time. Two
+* interleaved tool calls would race: caller B's env assignment can land
+* between A's assignment and A's worker spawn, attributing A's results to B's
+* agent. `Exclusive` keeps the whole body atomic against every other
+* `run_tests` call in this process; its scope restores env and cwd before the
+* next call starts, and a client cancel (an interrupt of the request fiber)
+* only drops the response — the permit is held until the body ends.
+*/
+const runTestsLane = Effect.runSync(Exclusive.make);
+/**
+* How long a run may hold the lane beyond its own test timeout: config
+* loading (`createVitest`), the classification read, and teardown. The test
+* timeout itself bounds only `vitest.start`, as it always has.
+*/
+const LANE_ALLOWANCE_MS = 12e4;
 /**
 * Coerce unknown Vitest unhandled errors into VitestModuleError shape.
 *
@@ -442,6 +482,7 @@ const RunTestsInput = Schema.Struct({
 	tags: Schema.optionalKey(TagFilter).annotate({ description: "Structured tag filter; all/any/none AND together with each other and with project/files" }),
 	passWithNoTests: Schema.optionalKey(Schema.Boolean).annotate({ description: "Per-call override of Vitest's native test.passWithNoTests" }),
 	timeout: Schema.optionalKey(Schema.Finite).annotate({ description: "Timeout in seconds (default: 120)" }),
+	_callerCwd: Schema.optionalKey(Schema.String).annotate({ description: "Hook-injected caller working directory; do not pass manually." }),
 	_sessionContext: Schema.optionalKey(Schema.Struct({
 		chatId: Schema.String,
 		conversationId: Schema.String,
@@ -519,6 +560,7 @@ function toNoMatch(scope, projectRoot) {
 */
 function toOkPayload(args) {
 	const { scope } = args;
+	const suggestedActions = [...args.suggestedActions ?? [], ...args.runDiagnostics !== void 0 ? suggestedActionsFromRunDiagnostics(args.runDiagnostics) : []];
 	return {
 		kind: "ok",
 		...scope.project !== void 0 && { project: scope.project },
@@ -532,7 +574,8 @@ function toOkPayload(args) {
 		classifications: args.classifications ? Object.fromEntries(args.classifications) : {},
 		discoveryLastScannedAt: args.discoveryLastScannedAt ?? null,
 		scopedNote: args.scopedNote,
-		...args.suggestedActions !== void 0 && args.suggestedActions.length > 0 ? { suggestedActions: args.suggestedActions } : {}
+		...suggestedActions.length > 0 ? { suggestedActions } : {},
+		...args.runDiagnostics !== void 0 && { runDiagnostics: args.runDiagnostics }
 	};
 }
 /**
@@ -547,27 +590,138 @@ function toOkPayload(args) {
 */
 const makeBestEffortFork = (services) => (effect) => Effect.runFork(Effect.provideContext(effect.pipe(Effect.ignore), services));
 /**
-* The run body, promise-shaped because it drives Vitest's promise API and
-* the AsyncLocalStorage stdio capture; every failure is folded into the
-* `{ kind: "error" }` envelope, so it never rejects.
+* A rejected step's message. Exception-safe: a hostile thrown value (a
+* throwing `message` getter or `toString`) still yields a string, so the
+* `{ kind: "error" }` envelope always comes back.
+*/
+const errorMessage = (err) => {
+	try {
+		return err instanceof Error ? err.message : String(err);
+	} catch {
+		return coerceErrorField(err, "message") ?? "<unserializable error>";
+	}
+};
+/**
+* A promise-returning Vitest step, run through the lane's promise. By default
+* an interrupt aborts, then waits for the promise to settle; `abandon` resumes
+* at once instead, for a promise that ignores its signal.
+*/
+const step = (evaluate, options) => Exclusive.promise({
+	try: evaluate,
+	catch: (cause) => new RunStepFailure({ cause }),
+	...options
+});
+/** The Node platform the run's root validation, config walk and git reads use. */
+const onNodePlatform = (effect) => Effect.provide(effect, NodeWalkPlatform);
+/**
+* The run itself, once the root, config and `vitest/node` entry are settled:
+* every step that can reject fails as `RunStepFailure`, which the body folds
+* into `{ kind: "error" }` along with any throw, and every process-global change (cwd, the coverage temp dir, the Vitest instance) is
+* released by the lane's scope on every exit path.
 */
-const runTestsBody = async (input, ctx) => {
+const runVitest = (args) => Effect.gen(function* () {
+	const { input, ctx, scope, resolvedRoot, anchoredConfig, vitestEntry } = args;
+	const { files, project, resolvedExpression, hasFilter } = scope;
+	const timeoutSeconds = input.timeout ?? 120;
+	const { createVitest } = yield* step(() => ModuleResolution.load(vitestEntry, { importer: vitestLoader.load }));
+	yield* ProcessScope.chdir(process, resolvedRoot);
+	const coverageDir = yield* coverageTempDirectory.pipe(Effect.mapError((cause) => new RunStepFailure({ cause })));
+	const nullStream = yield* Effect.acquireRelease(Effect.sync(StdioCapture.nullWritable), (stream) => Effect.sync(() => stream.destroy()));
+	const vitest = yield* Effect.acquireRelease(step(() => createVitest({
+		root: resolvedRoot,
+		...anchoredConfig !== void 0 ? { config: anchoredConfig } : {},
+		run: true,
+		coverage: { reportsDirectory: coverageDir },
+		...project ? { project } : {},
+		...resolvedExpression !== null ? { tagsFilter: [resolvedExpression] } : {},
+		...input.passWithNoTests !== void 0 ? { passWithNoTests: input.passWithNoTests } : {}
+	}, {}, {
+		stdout: nullStream,
+		stderr: nullStream
+	})), (instance) => Effect.tryPromise(() => instance.close()).pipe(Effect.ignore));
+	const capture = yield* RunTestsStdio;
+	const started = yield* step(() => capture.run(DISCARD_STDIO, () => vitest.start(files.length > 0 ? files : void 0)), { abandon: true }).pipe(Effect.timeout(timeoutSeconds * 1e3), Effect.map((value) => ({
+		outcome: "ok",
+		value
+	})), Effect.catchTag("TimeoutError", () => Effect.succeed({ outcome: "timeout" })));
+	if (started.outcome === "timeout") return {
+		kind: "timeout",
+		timeoutSeconds
+	};
+	const result = started.value;
+	const testModules = result.testModules;
+	const unhandledErrors = coerceErrors(result.unhandledErrors);
+	if (isNoMatch(scope, result.testModules.length, unhandledErrors.length)) return toNoMatch(scope, resolvedRoot);
+	const preliminaryReason = unhandledErrors.length > 0 || result.testModules.some((m) => m.state() === "failed") ? "failed" : "passed";
+	const baseReport = buildAgentReport(testModules, unhandledErrors, preliminaryReason, { omitPassingTests: true });
+	const leaks = buildConsoleLeaks(collectConsoleLeakEntries(vitest.state.getFiles()));
+	const strayOutput = readStrayOutput(vitest.logger);
+	const configSuggestedActions = readConfigSuggestedActions(vitest);
+	const runDiagnostics = readRunDiagnostics(vitest);
+	const report = {
+		...baseReport,
+		...leaks !== void 0 && { consoleLeaks: leaks },
+		...strayOutput !== void 0 && { strayOutput }
+	};
+	const classifications = yield* Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const projects = project ? [project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
+		const entries = [];
+		for (const p of projects) {
+			const tests = yield* reader.listTests(p, {});
+			for (const t of tests) if (t.classification != null) entries.push([t.fullName, t.classification]);
+		}
+		return new Map(entries);
+	}).pipe(Effect.catchCause(() => Effect.succeed(void 0)));
+	const chatId = ctx.currentSessionId.get();
+	if (chatId !== null) makeBestEffortFork(yield* Effect.context())(Effect.gen(function* () {
+		yield* (yield* DataStore).associateLatestRunWithSession({
+			chatId,
+			invocationMethod: "mcp"
+		});
+	}));
+	let scopedNote = null;
+	if (hasFilter) {
+		const totalFileCount = yield* step(() => vitest.globTestSpecifications()).pipe(Effect.map((specs) => specs.length), Effect.orElseSucceed(() => void 0));
+		scopedNote = formatScopedCoverageNote(testModules.length, totalFileCount);
+	}
+	return toOkPayload({
+		scope,
+		projectRoot: resolvedRoot,
+		report,
+		classifications,
+		discoveryLastScannedAt: readDiscoveryLastScannedAt(),
+		scopedNote,
+		...configSuggestedActions !== void 0 && { suggestedActions: configSuggestedActions },
+		...runDiagnostics !== void 0 && { runDiagnostics }
+	});
+});
+/**
+* The run body, inside the lane: input checks that return the tool's
+* `{ kind: "error" }` result before anything process-global changes, then
+* the attribution env and the run. Never fails.
+*/
+const runTestsBody = (input, ctx) => Effect.gen(function* () {
 	const derived = deriveRunScope(input);
 	if (Result.isFailure(derived)) return {
 		kind: "error",
 		message: derived.failure
 	};
 	const scope = derived.success;
-	const { files, project, resolvedExpression, hasFilter } = scope;
-	const projectRootValidation = await validateProjectRoot(input.projectRoot, ctx.cwd);
+	const projectRootValidation = yield* Effect.promise(() => validateProjectRoot(input.projectRoot, ctx.cwd));
 	if (!projectRootValidation.ok) return {
 		kind: "error",
 		message: projectRootValidation.message
 	};
 	const resolvedRoot = projectRootValidation.root;
+	const callerCheck = yield* Effect.promise(() => checkCallerWorktree(input._callerCwd, resolvedRoot));
+	if (!callerCheck.ok) return {
+		kind: "error",
+		message: callerCheck.message
+	};
 	let anchoredConfig;
 	if (input.projectRoot !== void 0) {
-		const found = await runOnNodePlatform(resolveAnchoredConfigFile(resolvedRoot));
+		const found = yield* onNodePlatform(resolveAnchoredConfigFile(resolvedRoot));
 		if (found === null) return {
 			kind: "error",
 			message: `No vitest.config.* or vite.config.* was found at or above projectRoot "${resolvedRoot}" within the repository. Vitest 5 does not search ancestor directories, so this run would collect no tests and load no plugins. Pass a projectRoot that contains a Vitest config, or omit projectRoot to anchor automatically.`
@@ -581,157 +735,61 @@ const runTestsBody = async (input, ctx) => {
 		reason: "stale-install",
 		message: staleMessage
 	};
-	const timeoutMs = (input.timeout ?? 120) * 1e3;
-	const recovered = input._sessionContext ?? null ?? ctx.sessionContext.get();
-	if (recovered !== null) {
-		process.env.VITEST_AGENT_CHAT_ID = recovered.chatId;
-		process.env.VITEST_AGENT_CONVERSATION_ID = recovered.conversationId;
-		process.env.VITEST_AGENT_AGENT_ID = recovered.mainAgentId;
-	}
-	const nullStream = new Writable({ write(_chunk, _encoding, cb) {
-		cb();
-	} });
-	const { createVitest } = await vitestLoader.load(vitestEntry);
-	let vitest;
-	let covOverride;
-	let previousCwd;
-	try {
-		previousCwd = process.cwd();
-	} catch {
-		previousCwd = void 0;
-	}
-	try {
-		process.chdir(resolvedRoot);
-		covOverride = makeCoverageDirOverride();
-		vitest = await createVitest({
-			root: resolvedRoot,
-			...anchoredConfig !== void 0 ? { config: anchoredConfig } : {},
-			run: true,
-			coverage: covOverride.coverage,
-			...project ? { project } : {},
-			...resolvedExpression !== null ? { tagsFilter: [resolvedExpression] } : {},
-			...input.passWithNoTests !== void 0 ? { passWithNoTests: input.passWithNoTests } : {}
-		}, {}, {
-			stdout: nullStream,
-			stderr: nullStream
-		});
-		const localVitest = vitest;
-		const startOutcome = await withStdioCaptured(nullStream, () => Effect.runPromise(Effect.tryPromise({
-			try: () => localVitest.start(files.length > 0 ? files : void 0),
-			catch: (cause) => new VitestStartFailure({ cause })
-		}).pipe(Effect.timeout(timeoutMs), Effect.map((value) => ({
-			outcome: "ok",
-			value
-		})), Effect.catchTag("TimeoutError", () => Effect.succeed({ outcome: "timeout" })), Effect.catchTag("VitestStartFailure", (e) => Effect.succeed({
-			outcome: "failed",
-			cause: e.cause
-		})))));
-		if (startOutcome.outcome === "timeout") return {
-			kind: "timeout",
-			timeoutSeconds: input.timeout ?? 120
-		};
-		if (startOutcome.outcome === "failed") throw startOutcome.cause;
-		const result = startOutcome.value;
-		const testModules = result.testModules;
-		const unhandledErrors = coerceErrors(result.unhandledErrors);
-		if (isNoMatch(scope, result.testModules.length, unhandledErrors.length)) return toNoMatch(scope, resolvedRoot);
-		const preliminaryReason = unhandledErrors.length > 0 || result.testModules.some((m) => m.state() === "failed") ? "failed" : "passed";
-		const baseReport = buildAgentReport(testModules, unhandledErrors, preliminaryReason, { omitPassingTests: true });
-		const leaks = buildConsoleLeaks(collectConsoleLeakEntries(localVitest.state.getFiles()));
-		const strayOutput = readStrayOutput(localVitest.logger);
-		const configSuggestedActions = readConfigSuggestedActions(localVitest);
-		const report = {
-			...baseReport,
-			...leaks !== void 0 && { consoleLeaks: leaks },
-			...strayOutput !== void 0 && { strayOutput }
-		};
-		let classifications;
-		try {
-			classifications = await ctx.runPromise(Effect.gen(function* () {
-				const reader = yield* DataReader;
-				const projects = project ? [project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
-				const entries = [];
-				for (const p of projects) {
-					const tests = yield* reader.listTests(p, {});
-					for (const t of tests) if (t.classification != null) entries.push([t.fullName, t.classification]);
-				}
-				return new Map(entries);
-			}));
-		} catch {}
-		const chatId = ctx.currentSessionId.get();
-		if (chatId !== null) ctx.runFork(Effect.gen(function* () {
-			yield* (yield* DataStore).associateLatestRunWithSession({
-				chatId,
-				invocationMethod: "mcp"
-			});
-		}));
-		let scopedNote = null;
-		if (hasFilter) {
-			const testedFileCount = testModules.length;
-			let totalFileCount;
-			try {
-				totalFileCount = (await localVitest.globTestSpecifications()).length;
-			} catch {}
-			scopedNote = formatScopedCoverageNote(testedFileCount, totalFileCount);
-		}
-		return toOkPayload({
-			scope,
-			projectRoot: resolvedRoot,
-			report,
-			classifications,
-			discoveryLastScannedAt: readDiscoveryLastScannedAt(),
-			scopedNote,
-			...configSuggestedActions !== void 0 && { suggestedActions: configSuggestedActions }
-		});
-	} catch (err) {
-		let message;
-		try {
-			message = err instanceof Error ? err.message : String(err);
-		} catch {
-			message = coerceErrorField(err, "message") ?? "<unserializable error>";
-		}
-		return {
+	const recovered = input._sessionContext ?? ctx.sessionContext.get();
+	if (recovered !== null) yield* ProcessScope.env(process.env, {
+		VITEST_AGENT_CHAT_ID: recovered.chatId,
+		VITEST_AGENT_CONVERSATION_ID: recovered.conversationId,
+		VITEST_AGENT_AGENT_ID: recovered.mainAgentId
+	});
+	return yield* runVitest({
+		input,
+		ctx,
+		scope,
+		resolvedRoot,
+		anchoredConfig,
+		vitestEntry
+	}).pipe(Effect.catchTags({
+		RunStepFailure: (e) => Effect.succeed({
 			kind: "error",
-			message
-		};
-	} finally {
-		try {
-			await vitest?.close();
-		} finally {
-			try {
-				if (previousCwd !== void 0) process.chdir(previousCwd);
-			} catch {}
-			nullStream.destroy();
-			if (covOverride !== void 0) try {
-				rmSync(covOverride.dir, {
-					recursive: true,
-					force: true
-				});
-			} catch {}
-		}
-	}
-};
+			message: errorMessage(e.cause)
+		}),
+		ProcessScopeError: (e) => Effect.succeed({
+			kind: "error",
+			message: errorMessage(e.cause)
+		})
+	}), Effect.catchDefect((defect) => Effect.succeed({
+		kind: "error",
+		message: errorMessage(defect)
+	})));
+});
 /**
-* Handler for {@link runTestsTool}. Serialized through a one-permit
-* semaphore: the body assigns the active attribution UUIDs into
-* `process.env.VITEST_AGENT_*` and then awaits `createVitest` /
-* `vitest.start`, which spawns the worker pool that snapshots env at
-* spawn time — two interleaved calls would race, attributing one call's
-* results to the other's agent.
+* Handler for {@link runTestsTool}. The body runs in the one-permit
+* `Exclusive` lane: it assigns the active attribution UUIDs into
+* `process.env.VITEST_AGENT_*`, enters the run's root, and then awaits
+* `createVitest` / `vitest.start`, which spawns the worker pool that
+* snapshots env and cwd at spawn time — two interleaved calls would race,
+* attributing one call's results to the other's agent. A client cancel
+* drops the response; the next call waits for the real run to end.
 *
 * @public
 */
 const handleRunTests = (input) => Effect.gen(function* () {
 	const session = yield* McpSession;
-	const services = yield* Effect.context();
 	const ctx = {
 		cwd: session.cwd,
 		currentSessionId: session.currentSessionId,
-		sessionContext: session.sessionContext,
-		runPromise: (effect) => Effect.runPromise(Effect.provideContext(effect, services)),
-		runFork: makeBestEffortFork(services)
+		sessionContext: session.sessionContext
 	};
-	return yield* Semaphore.withPermit(runTestsSemaphore, Effect.uninterruptible(Effect.promise(() => runTestsBody(input, ctx))));
+	const timeoutSeconds = input.timeout ?? 120;
+	const fs = yield* Effect.serviceOption(FileSystem.FileSystem);
+	const platformFs = Option.match(fs, {
+		onNone: () => NodeFileSystem.layer,
+		onSome: (service) => Layer.succeed(FileSystem.FileSystem, service)
+	});
+	return yield* runTestsLane.run(runTestsBody(input, ctx), { timeout: timeoutSeconds * 1e3 + LANE_ALLOWANCE_MS }).pipe(Effect.catchTag("ExclusiveTimeout", () => Effect.succeed({
+		kind: "timeout",
+		timeoutSeconds
+	})), Effect.provide(platformFs));
 });
 /**
 * The Effect-native `run_tests` tool.
@@ -739,7 +797,7 @@ const handleRunTests = (input) => Effect.gen(function* () {
 * @public
 */
 const runTestsTool = Tool.make("run_tests", {
-	description: "Use to run Vitest tests, with optional file, project, and tag filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error, no-match). Unknown parameters are rejected — accepted keys are files, project, tags, passWithNoTests, timeout, projectRoot. When projectRoot is omitted, the server anchors the Vitest root at the directory of the vitest (or vite) config Vitest would load anyway, walking up from its boot dir and stopping at the git root — so a server booted inside a package subtree still resolves the root config's relative globalSetup/setupFiles correctly. projectRoot overrides that for this call and is used verbatim, but only after validation: it must be an existing directory belonging to the same git repository as ctx.cwd (checked via `git rev-parse --path-format=absolute --git-common-dir`, which needs git 2.31 or newer and is identical across a repo and all its worktrees, including a sibling worktree checked out from the same repo). A path in a different repository, or a non-existent path, is rejected with `{ kind: \"error\" }` naming both paths — never a silent fallback to ctx.cwd. The resolved root actually used is always echoed back on success. An error result with `reason: \"stale-install\"` means the vitest install was replaced under this long-lived server (the lockfile was regenerated) and the resolved vitest/node entry is gone; restart the MCP server (/mcp in Claude Code) rather than retrying. The legacy format=json arg is dropped — structuredContent supersedes it.",
+	description: "Use to run Vitest tests, with optional file, project, and tag filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error, no-match). Unknown parameters are rejected — accepted keys are files, project, tags, passWithNoTests, timeout, projectRoot. When projectRoot is omitted, the server anchors the Vitest root at the directory of the vitest (or vite) config Vitest would load anyway, walking up from its boot dir and stopping at the git root — so a server booted inside a package subtree still resolves the root config's relative globalSetup/setupFiles correctly. projectRoot overrides that for this call and is used verbatim, but only after validation: it must be an existing directory belonging to the same git repository as ctx.cwd (checked via `git rev-parse --path-format=absolute --git-common-dir`, which needs git 2.31 or newer and is identical across a repo and all its worktrees, including a sibling worktree checked out from the same repo). A path in a different repository, or a non-existent path, is rejected with `{ kind: \"error\" }` naming both paths — never a silent fallback to ctx.cwd. The resolved root actually used is always echoed back on success. When the plugin hook supplies the caller working directory (the hook-injected _callerCwd), a call from a different working tree of the same repository than the resolved root is refused with `{ kind: \"error\" }` naming both trees; pass projectRoot (your own worktree path) to run there. An absent or indeterminate caller directory never refuses. An error result with `reason: \"stale-install\"` means the vitest install was replaced under this long-lived server (the lockfile was regenerated) and the resolved vitest/node entry is gone; restart the MCP server (/mcp in Claude Code) rather than retrying. The legacy format=json arg is dropped — structuredContent supersedes it.",
 	parameters: RunTestsInput,
 	success: RunTestsResult,
 	dependencies: [
@@ -749,4 +807,4 @@ const runTestsTool = Tool.make("run_tests", {
 	]
 }).annotate(Tool.Title, "Run tests").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
 
-export { RUN_TESTS_ERROR_REASONS, RunTestsInput, RunTestsResult, coerceErrors, composeTagExpression, deriveRunScope, handleRunTests, isNoMatch, makeBestEffortFork, makeCoverageDirOverride, readConfigSuggestedActions, readDiscoveryLastScannedAt, resolveAnchoredConfigFile, resolveConfigAnchoredRoot, resolveVitestNodeEntry, runTestsSemaphore, runTestsTool, sanitizeTestArgs, staleInstallMessage, toNoMatch, toOkPayload, validateProjectRoot, vitestLoader, withStdioCaptured };
+export { RUN_TESTS_ERROR_REASONS, RunTestsInput, RunTestsResult, RunTestsStdio, checkCallerWorktree, coerceErrors, composeTagExpression, deriveRunScope, handleRunTests, isNoMatch, makeBestEffortFork, readConfigSuggestedActions, readDiscoveryLastScannedAt, readRunDiagnostics, resolveAnchoredConfigFile, resolveConfigAnchoredRoot, resolveVitestNodeEntry, runTestsTool, sanitizeTestArgs, staleInstallMessage, toNoMatch, toOkPayload, validateProjectRoot, vitestLoader };