@vitest-agent/mcp 2.1.4 → 2.2.1

package/README.md

@@ -13,6 +13,8 @@ The `vitest-agent-mcp` MCP server bin. Exposes action-keyed tools over stdio tha
 - **29 action-keyed tools** — per-CRUD families collapse into single tools dispatching on an `action` discriminator; covers `test_status`, `test_overview`, `test_coverage`, `test_errors`, `run_tests`, `note`, `hypothesis`, `tdd_task`, `tdd_goal`, `tdd_behavior` and more
 - **Six framing prompts** — `triage`, `why-flaky`, `regression-since-pass`, `explain-failure`, `tdd-resume`, `wrapup`
 - **Idempotency middleware** — `tdd_task`, `tdd_goal`, `tdd_behavior` and `hypothesis` create-actions are idempotent on derived keys
+- **Strict tool inputs** — an unknown key is rejected with an error naming it and listing the accepted params, instead of being stripped and running a wider query than the caller asked for
+- **Session-surviving error handling** — a resolver that throws returns a structured `UnexpectedToolError` envelope, and a stray unhandled rejection after the transport connects is logged to stderr rather than killing the server mid-session
 - **Programmatic API** — `buildMcpServer` constructs the server without connecting a transport; `parseSessionEnvExports` and `recoverSessionContextFromSessionEnv` recover the host session context from the Claude Code plugin's session-env files, so agent attribution survives a plugin reload
 
 ## Install

package/bin/vitest-agent-mcp.js

@@ -3,12 +3,81 @@ import { createCurrentSessionIdRef, createSessionContextRef, sessionContextFromE
 import { McpLive } from "../layers/McpLive.js";
 import { startMcpServer } from "../server.js";
 import { recoverSessionContextFromSessionEnv } from "../session-env.js";
+import { shouldExitOnUncaughtException } from "../utils/crash-guards.js";
+import { safeFormatFatalError } from "../utils/safe-format-fatal-error.js";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { PathResolutionLive, formatFatalError, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
+import { PathResolutionLive, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
 import { Effect, ManagedRuntime } from "effect";
 
 //#region src/bin.ts
 /**
+* Whether `server.connect(transport)` has resolved for this process.
+* Read by the `uncaughtException` handler below via
+* {@link shouldExitOnUncaughtException} — see that function's doc
+* comment for the judgment call this flag backs (issue #191).
+*/
+let transportConnected = false;
+/**
+* Issue #191, sub-item A: the MCP server used to be a bare
+* `main().catch(...)` with no process-level guards. Under Node >=15 an
+* unhandled promise rejection anywhere in the async chain — a
+* fire-and-forgotten Effect fiber, a background timer, anything that
+* never flows through a tool call's own await chain — crashes the
+* process by default, closing the stdio transport and silently
+* deregistering every tool from the client's perspective mid session,
+* with no recovery path. Register both guards at module scope, before
+* any async work in `main()` starts, so they also cover the dbPath
+* resolution / ManagedRuntime construction phase.
+*
+* Every throw or rejection *inside* a single tool call is already
+* caught by the MCP SDK's own `CallToolRequestSchema` handler (see
+* `server.ts`'s `registerTool` shadow for the structured-envelope
+* layer on top of that). Anything that reaches these handlers
+* therefore originated outside any tool-call boundary and, by
+* definition, has no in-flight caller waiting on it — logging and
+* continuing is safe because there is no request context to roll back
+* and no benefit to dropping every *other* in-flight and future tool
+* call over it.
+*/
+process.on("unhandledRejection", (reason) => {
+	process.stderr.write(`vitest-agent-mcp: unhandledRejection: ${safeFormatFatalError(reason)}\n`);
+});
+/**
+* Node's own guidance for `uncaughtException` is "do not resume normal
+* operation" — arbitrary in-process state may be corrupt. This process
+* accepts that residual risk once the transport is connected: see
+* `shouldExitOnUncaughtException`'s doc comment for the reasoning
+* (no long-lived mutable state outside SQLite's own transactions, and
+* silent process death mid-session is strictly worse). Before the
+* transport connects there is no client session to preserve by staying
+* alive, so this exits loudly instead.
+*/
+process.on("uncaughtException", (err, origin) => {
+	process.stderr.write(`vitest-agent-mcp: uncaughtException (${origin}): ${safeFormatFatalError(err)}\n`);
+	if (shouldExitOnUncaughtException(transportConnected)) {
+		process.exitCode = 1;
+		process.exit(1);
+	}
+});
+/**
+* Test-only crash injection, gated by an env var so it can never fire
+* in a normal install. Exists so `__test__/bin-crash-resilience.e2e.test.ts`
+* can exercise the guards above against a *real* child process (a
+* crash in the test's own process is not something a unit test can
+* safely simulate). Fires exactly once, on the next event-loop turn
+* after the transport is known to be connected, so ordering relative
+* to `transportConnected` is deterministic regardless of client-side
+* handshake timing.
+*/
+function scheduleTestCrashInjection() {
+	const kind = process.env.VITEST_AGENT_MCP_TEST_INJECT_CRASH;
+	if (kind !== "unhandledRejection" && kind !== "uncaughtException") return;
+	setImmediate(() => {
+		if (kind === "unhandledRejection") Promise.reject(/* @__PURE__ */ new Error("[test-injected] unhandledRejection"));
+		else throw new Error("[test-injected] uncaughtException");
+	});
+}
+/**
 * Resolve the user's project directory.
 *
 * Precedence (most explicit wins):
@@ -68,9 +137,11 @@ async function main() {
 	console.error(`[vitest-agent-mcp] Initial chat id: ${chatIdResolved !== null ? "(set)" : "(none — SessionStart hook had not written CLAUDE_ENV_FILE yet)"}`);
 	if (recoveredContext !== null) console.error("[vitest-agent-mcp] Recovered session context: agent=(set) conversation=(set)");
 	await startMcpServer(ctx);
+	transportConnected = true;
+	scheduleTestCrashInjection();
 }
 main().catch((err) => {
-	process.stderr.write(`vitest-agent-mcp: ${formatFatalError(err)}\n`);
+	process.stderr.write(`vitest-agent-mcp: ${safeFormatFatalError(err)}\n`);
 	process.exit(1);
 });
 

package/index.d.ts

@@ -277,6 +277,9 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
   test_history: import("@trpc/server").TRPCQueryProcedure<{
     input: {
       readonly project: string;
+      readonly testName?: string | undefined;
+      readonly modulePath?: string | undefined;
+      readonly limit?: number | undefined;
     };
     output: {
       readonly project: string;
@@ -388,6 +391,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       readonly action: "get";
       readonly fullName: string;
       readonly project?: string | undefined;
+      readonly modulePath?: string | undefined;
     } | {
       readonly action: "for_file";
       readonly filePath: string;
@@ -437,6 +441,8 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       readonly found: false;
       readonly project: string;
       readonly fullName: string;
+      readonly ambiguous?: boolean | undefined;
+      readonly candidateModules?: readonly string[] | undefined;
     } | {
       readonly action: "for_file";
       readonly filePath: string;
@@ -523,6 +529,15 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
     output: {
       readonly kind: "ok";
       readonly project?: string | undefined;
+      readonly scope: {
+        readonly project: string | null;
+        readonly files: readonly string[];
+        readonly tags: {
+          readonly all?: readonly string[] | undefined;
+          readonly any?: readonly string[] | undefined;
+          readonly none?: readonly string[] | undefined;
+        } | null;
+      };
       readonly report: {
         readonly timestamp: string;
         readonly project?: string | undefined;

package/index.js

@@ -12,7 +12,7 @@ import { parseSessionEnvExports, recoverSessionContextFromSessionEnv } from "./s
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "2.1.4";
+const CURRENT_MCP_VERSION = "2.2.1";
 
 //#endregion
 export { CURRENT_MCP_VERSION, McpLive, appRouter, buildMcpServer, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, parseSessionEnvExports, recoverSessionContextFromSessionEnv, startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "2.1.4",
+	"version": "2.2.1",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 53 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [
@@ -42,7 +42,7 @@
 		"@effect/sql-sqlite-node": "4.0.0-beta.107",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "2.2.1",
+		"@vitest-agent/sdk": "2.3.1",
 		"effect": "4.0.0-beta.107",
 		"zod": "^4.4.3"
 	},

package/server.js

@@ -31,6 +31,7 @@ import { WrapupPromptResult } from "./tools/wrapup-prompt.js";
 import { appRouter } from "./router.js";
 import { registerAllPrompts } from "./prompts/index.js";
 import { effectToZodSchema } from "./utils/effect-to-zod.js";
+import { buildUnexpectedToolErrorEnvelope } from "./utils/tool-error-envelope.js";
 import { ChannelEvent, DataReader } from "@vitest-agent/sdk";
 import { Effect, Exit, Option, Schema } from "effect";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -39,6 +40,25 @@ import { z } from "zod";
 
 //#region src/server.ts
 /**
+* Build a strict (unknown-keys-rejected) zod object from a raw shape, with
+* an `unrecognized_keys` error message that names the accepted params —
+* plain `z.strictObject(shape)` only reports the offending key(s), leaving
+* an agent to re-read the tool description to self-correct. Every
+* `registerTool` input in this file goes through this helper so the whole
+* served surface rejects unknown keys consistently (issue #200).
+*
+* The rule applies at EVERY object level, not just the top one: a nested
+* plain `z.object` strips unknown keys, so a misspelled nested param
+* decoded to an empty sub-object and the tool ran unfiltered (issue
+* #243). Nested shapes go through this helper too.
+*
+* @internal
+*/
+function strict(shape) {
+	const acceptedKeys = Object.keys(shape);
+	return z.strictObject(shape, { error: (issue) => issue.code === "unrecognized_keys" ? `Unrecognized parameter(s): ${issue.keys.join(", ")}. Accepted params: ${acceptedKeys.join(", ")}` : void 0 });
+}
+/**
 * For behavior-scoped events, resolve goalId/sessionId server-side from
 * behaviorId so a stale orchestrator context cannot push the wrong tree
 * coordinates. Goal-scoped events get sessionId resolved from goalId.
@@ -140,6 +160,27 @@ function buildMcpServer(ctx) {
 		version: "0.1.0"
 	}, { capabilities: { experimental: { "claude/channel": {} } } });
 	const caller = createCallerFactory(appRouter)(ctx);
+	const originalRegisterTool = server.registerTool.bind(server);
+	server.registerTool = (...registerArgs) => {
+		const [name, config, cb] = registerArgs;
+		const wrapped = async (...handlerArgs) => {
+			try {
+				return await cb(...handlerArgs);
+			} catch (err) {
+				const envelope = buildUnexpectedToolErrorEnvelope(name, err);
+				console.error(`[vitest-agent-mcp] tool "${name}" resolver threw: ${envelope.error.message}`);
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(envelope, null, 2)
+					}],
+					isError: true,
+					structuredContent: envelope
+				};
+			}
+		};
+		return originalRegisterTool(name, config, wrapped);
+	};
 	server.registerTool("help", {
 		description: "Use when you need the catalog of available MCP tools and their parameters. Markdown in content[]; same string available as structuredContent.helpText.",
 		outputSchema: effectToZodSchema(HelpResult)
@@ -149,7 +190,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("test_status", {
 		description: "Use when you need each project's current pass/fail state from the most recent run. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, manifestUpdatedAt, projectFilter?, entries[] } or absent variant).",
-		inputSchema: { project: z.optional(z.string()).describe("Filter to a specific project") },
+		inputSchema: strict({ project: z.optional(z.string()).describe("Filter to a specific project") }),
 		outputSchema: effectToZodSchema(TestStatusResult)
 	}, async (args) => {
 		const data = await caller.test_status({ project: args.project });
@@ -157,7 +198,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("test_overview", {
 		description: "Use when you want a summary of the test landscape with per-project run metrics. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, projectFilter?, runs[] } or absent variant).",
-		inputSchema: { project: z.optional(z.string()).describe("Filter to a specific project") },
+		inputSchema: strict({ project: z.optional(z.string()).describe("Filter to a specific project") }),
 		outputSchema: effectToZodSchema(TestOverviewResult)
 	}, async (args) => {
 		const data = await caller.test_overview({ project: args.project });
@@ -165,26 +206,36 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("test_coverage", {
 		description: "Use when coverage drops and you need per-metric gap analysis against thresholds and targets. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, project, coverage } or absent variant).",
-		inputSchema: { project: z.optional(z.string()).describe("Project name") },
+		inputSchema: strict({ project: z.optional(z.string()).describe("Project name") }),
 		outputSchema: effectToZodSchema(TestCoverageResult)
 	}, async (args) => {
 		const data = await caller.test_coverage({ project: args.project });
 		return structuredResult(Schema.decodeSync(TestCoverageAsMarkdown)(data), data);
 	});
 	server.registerTool("test_history", {
-		description: "Use when failures recur and you need flaky, persistent, and recovered test classifications. Returns markdown in content[] and a typed JSON object in structuredContent (project, hasData, history, flaky[], persistent[], recovered[]).",
-		inputSchema: { project: z.string().describe("Project name (required)") },
+		description: "Use when failures recur and you need flaky, persistent, and recovered test classifications. Returns markdown in content[] and a typed JSON object in structuredContent (project, hasData, history, flaky[], persistent[], recovered[]). Optional testName/modulePath narrow to a single test; limit caps runs kept per test (default 20) — omit all three only when you actually need the whole project's history.",
+		inputSchema: strict({
+			project: z.string().describe("Project name (required)"),
+			testName: z.optional(z.string()).describe("Exact full_name match — narrows to a single test's history"),
+			modulePath: z.optional(z.string()).describe("Exact module_path match — narrows to tests in one file"),
+			limit: z.optional(z.coerce.number().int().positive()).describe("Max runs kept per test, most-recent-first; positive integer (default 20)")
+		}),
 		outputSchema: effectToZodSchema(TestHistoryResult)
 	}, async (args) => {
-		const data = await caller.test_history({ project: args.project });
+		const data = await caller.test_history({
+			project: args.project,
+			testName: args.testName,
+			modulePath: args.modulePath,
+			limit: args.limit
+		});
 		return structuredResult(Schema.decodeSync(TestHistoryAsMarkdown)(data), data);
 	});
 	server.registerTool("test_trends", {
 		description: "Use when you want to see whether a project's coverage is trending up or down over time. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, project, trends? }).",
-		inputSchema: {
+		inputSchema: strict({
 			project: z.string().describe("Project name (required)"),
 			limit: z.optional(z.coerce.number()).describe("Max number of trend entries to return")
-		},
+		}),
 		outputSchema: effectToZodSchema(TestTrendsResult)
 	}, async (args) => {
 		const data = await caller.test_trends({
@@ -195,10 +246,10 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("test_errors", {
 		description: "Use when a test fails and you need error detail, diffs, and the cite-able test_errors.id / stack_frames.id values needed by hypothesis (action: record). Returns both a markdown rendering (in content[].text) and a typed JSON object (in structuredContent) — agents should prefer structuredContent.errors[].",
-		inputSchema: {
+		inputSchema: strict({
 			project: z.string().describe("Project name (required)"),
 			errorName: z.optional(z.string()).describe("Filter to a specific error name")
-		},
+		}),
 		outputSchema: effectToZodSchema(TestErrorsResult)
 	}, async (args) => {
 		const data = await caller.test_errors({
@@ -208,8 +259,8 @@ function buildMcpServer(ctx) {
 		return structuredResult(Schema.decodeSync(TestErrorsAsMarkdown)(data), data);
 	});
 	server.registerTool("test", {
-		description: "Use to inspect tests, with an action discriminator: action='list' (project?, state?, module?, limit?) returns matching tests; action='get' (fullName, project?) returns details + errors + run history; action='for_file' (filePath) returns test modules covering a source file. structuredContent carries the typed payload (discriminate on `action`, then on `found` for get).",
-		inputSchema: {
+		description: "Use to inspect tests, with an action discriminator: action='list' (project?, state?, module?, limit?) returns matching tests; action='get' (fullName, project?, modulePath?) returns details + errors + run history — a fullName that exists in more than one module returns found=false with ambiguous=true and candidateModules[], so pass modulePath to disambiguate; action='for_file' (filePath) returns test modules covering a source file. structuredContent carries the typed payload (discriminate on `action`, then on `found` for get).",
+		inputSchema: strict({
 			action: z.enum([
 				"list",
 				"get",
@@ -220,8 +271,9 @@ function buildMcpServer(ctx) {
 			module: z.optional(z.string()).describe("list: filter by module path"),
 			limit: z.optional(z.coerce.number()).describe("list: max rows to return"),
 			fullName: z.optional(z.string()).describe("get: full test name"),
+			modulePath: z.optional(z.string()).describe("get: exact module path, disambiguating a fullName present in several files"),
 			filePath: z.optional(z.string()).describe("for_file: source file path")
-		},
+		}),
 		outputSchema: effectToZodSchema(TestResult)
 	}, async (args) => {
 		let data;
@@ -235,7 +287,8 @@ function buildMcpServer(ctx) {
 		else if (args.action === "get") data = await caller.test({
 			action: "get",
 			fullName: args.fullName,
-			...args.project !== void 0 && { project: args.project }
+			...args.project !== void 0 && { project: args.project },
+			...args.modulePath !== void 0 && { modulePath: args.modulePath }
 		});
 		else data = await caller.test({
 			action: "for_file",
@@ -245,10 +298,10 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("file_coverage", {
 		description: "Use when you need coverage for one source file: per-metric values, uncovered lines, and related tests. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, matched?, filePath, report?, totals?, relatedTestFiles[] }).",
-		inputSchema: {
+		inputSchema: strict({
 			filePath: z.string().describe("Source file path to check coverage for"),
 			project: z.optional(z.string()).describe("Project name")
-		},
+		}),
 		outputSchema: effectToZodSchema(FileCoverageResult)
 	}, async (args) => {
 		const data = await caller.file_coverage({
@@ -259,7 +312,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("configure", {
 		description: "Use when you need the captured Vitest settings for a test run. Returns markdown in content[] and a typed JSON object in structuredContent ({ found, source, settings?, requestedHash? }).",
-		inputSchema: { settingsHash: z.optional(z.string()).describe("Settings hash from a manifest entry or test run") },
+		inputSchema: strict({ settingsHash: z.optional(z.string()).describe("Settings hash from a manifest entry or test run") }),
 		outputSchema: effectToZodSchema(ConfigureResult)
 	}, async (args) => {
 		const data = await caller.configure({ settingsHash: args.settingsHash });
@@ -274,7 +327,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("inventory", {
 		description: "Use to discover what exists in the workspace, with a kind discriminator: project / module / suite / session. structuredContent discriminates on `inventoryKind` (project, module, suite, session_detail, session_list) so callers can branch on the response shape without parsing markdown.",
-		inputSchema: {
+		inputSchema: strict({
 			kind: z.enum([
 				"project",
 				"module",
@@ -286,7 +339,7 @@ function buildMcpServer(ctx) {
 			module: z.optional(z.string()).describe("suite: filter by module path"),
 			agentKind: z.optional(z.enum(["main", "subagent"])).describe("session: filter by agent kind"),
 			limit: z.optional(z.coerce.number()).describe("session: max rows")
-		},
+		}),
 		outputSchema: effectToZodSchema(InventoryResult)
 	}, async (args) => {
 		let data;
@@ -318,7 +371,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("register_agent", {
 		description: "Use when an LLM-agent invocation starts and must be recorded in the per-project store. Idempotent on (chatId, agentType, parentAgentId, clientNonce). Returns ok:true with agentId on insert, or ok:false with error.code='AGENT_ALREADY_REGISTERED'/'PARENT_AGENT_NOT_FOUND'/'SESSION_NOT_FOUND'/'INVALID_AGENT_TYPE_PREFIX' on the four documented failure modes. agentType must begin with the host-kind prefix (e.g., 'claude-code-main').",
-		inputSchema: {
+		inputSchema: strict({
 			chatId: z.string().describe("Host's chat UUID (session_id from CC hook payload, etc.)"),
 			conversationId: z.optional(z.string()).describe("Canonical conversation UUID (from session-map mapConversation)"),
 			hostKind: z.optional(z.string()).describe("Host vendor identifier; defaults to 'claude-code'"),
@@ -328,7 +381,7 @@ function buildMcpServer(ctx) {
 			startGitBranch: z.optional(z.string()),
 			startGitCommitSha: z.optional(z.string()),
 			startWorktreeDir: z.optional(z.string())
-		},
+		}),
 		outputSchema: effectToZodSchema(RegisterAgentResult)
 	}, async (args) => {
 		const result = await caller.register_agent({
@@ -352,22 +405,30 @@ function buildMcpServer(ctx) {
 		};
 	});
 	server.registerTool("run_tests", {
-		description: "Use to run Vitest tests, with optional file and project filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error). The legacy format=json arg is dropped — structuredContent supersedes it.",
-		inputSchema: {
+		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. The legacy format=json arg is dropped — structuredContent supersedes it.",
+		inputSchema: strict({
 			files: z.optional(z.array(z.string())).describe("Test file paths to run"),
 			project: z.optional(z.string()).describe("Project name to filter"),
+			tags: z.optional(strict({
+				all: z.optional(z.array(z.string())).describe("Require every listed tag"),
+				any: z.optional(z.array(z.string())).describe("Require at least one listed tag"),
+				none: z.optional(z.array(z.string())).describe("Exclude any listed tag")
+			})).describe("Structured tag filter; all/any/none AND together with each other and with project/files"),
+			passWithNoTests: z.optional(z.boolean()).describe("Per-call override of Vitest's native test.passWithNoTests"),
 			timeout: z.optional(z.coerce.number()).describe("Timeout in seconds (default: 120)"),
-			_sessionContext: z.optional(z.object({
+			_sessionContext: z.optional(strict({
 				chatId: z.string(),
 				conversationId: z.string(),
 				mainAgentId: z.string()
 			})).describe("Hook-injected session attribution UUIDs; do not pass manually.")
-		},
+		}),
 		outputSchema: effectToZodSchema(RunTestsResult)
 	}, async (args) => {
 		const data = await caller.run_tests({
 			files: args.files,
 			project: args.project,
+			tags: args.tags,
+			passWithNoTests: args.passWithNoTests,
 			timeout: args.timeout,
 			...args._sessionContext !== void 0 && { _sessionContext: args._sessionContext }
 		});
@@ -375,7 +436,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("note", {
 		description: "Use to manage notes, with a CRUD action discriminator: action='create' writes a scoped note; action='list' (scope?, project?, testFullName?) returns matching notes; action='get' (id) returns a structured note; action='update' (id, ...patch) edits; action='delete' (id) removes; action='search' (query) does FTS5 across title and content. structuredContent always carries the typed result (discriminate on `action`); list/search additionally render markdown in the text channel.",
-		inputSchema: {
+		inputSchema: strict({
 			action: z.enum([
 				"create",
 				"list",
@@ -403,7 +464,7 @@ function buildMcpServer(ctx) {
 			expiresAt: z.optional(z.string()),
 			pinned: z.optional(z.boolean()),
 			query: z.optional(z.string()).describe("search: FTS5 query")
-		},
+		}),
 		outputSchema: effectToZodSchema(NoteResult)
 	}, async (args) => {
 		if (args.action === "create") return structuredJsonResult(await caller.note({
@@ -452,7 +513,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("turn_search", {
 		description: "Use when you need to find past turns across sessions by type, time, or session. Returns markdown in content[] and a typed JSON object in structuredContent ({ count, turns[] }).",
-		inputSchema: {
+		inputSchema: strict({
 			sessionId: z.optional(z.coerce.number()).describe("Filter to a specific session id"),
 			since: z.optional(z.string()).describe("ISO 8601 cutoff — return turns after this timestamp"),
 			type: z.optional(z.enum([
@@ -465,7 +526,7 @@ function buildMcpServer(ctx) {
 				"hypothesis"
 			])).describe("Filter by turn type"),
 			limit: z.optional(z.coerce.number()).describe("Max turns to return (default 100)")
-		},
+		}),
 		outputSchema: effectToZodSchema(TurnSearchResult)
 	}, async (args) => {
 		const data = await caller.turn_search({
@@ -478,7 +539,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("failure_signature_get", {
 		description: "Use when you have a failure-signature hash and need its first-seen date and occurrence history. Returns markdown in content[] and a typed JSON object in structuredContent ({ found, signatureHash?, firstSeenAt?, occurrenceCount?, recentErrors?[] } or absent variant).",
-		inputSchema: { hash: z.string().describe("16-char failure signature hash") },
+		inputSchema: strict({ hash: z.string().describe("16-char failure signature hash") }),
 		outputSchema: effectToZodSchema(FailureSignatureGetResult)
 	}, async (args) => {
 		const data = await caller.failure_signature_get({ hash: args.hash });
@@ -486,7 +547,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("tdd_task", {
 		description: "Use to manage a TDD task lifecycle, with an action discriminator: action='start' (goal, sessionId|chatId, parentTddTaskId?, startedAt?, runId?) opens a new task; action='end' (tddTaskId, outcome, summaryNoteId?) closes one; action='get' (tddTaskId) returns markdown details; action='resume' (tddTaskId) returns a compact digest.",
-		inputSchema: {
+		inputSchema: strict({
 			action: z.enum([
 				"start",
 				"end",
@@ -506,7 +567,7 @@ function buildMcpServer(ctx) {
 				"abandoned"
 			])).describe("end: final outcome"),
 			summaryNoteId: z.optional(z.coerce.number())
-		},
+		}),
 		outputSchema: effectToZodSchema(TddTaskResult)
 	}, async (args) => {
 		let data;
@@ -537,7 +598,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("tdd_phase_transition_request", {
 		description: "Use when advancing a TDD cycle and you need a phase transition validated and recorded. Validates goal status, behavior↔goal membership, and D2 artifact-evidence binding rules; returns accept/deny. On accept, auto-promotes a behavior 'pending' → 'in_progress' when behaviorId is supplied. citedArtifactId is OPTIONAL — when omitted, the most recent matching artifact is auto-resolved (kind comes from citedArtifactKind if supplied, otherwise from the transition's required-evidence rule). Transitions like spike→red that require no artifact need neither field. The accepted response echoes citedArtifactId + citedArtifactSource so the caller can see which row was picked.",
-		inputSchema: {
+		inputSchema: strict({
 			tddTaskId: z.coerce.number().describe("tdd_tasks.id"),
 			goalId: z.coerce.number().describe("tdd_session_goals.id (required; goal must be in_progress)"),
 			requestedPhase: z.enum([
@@ -561,7 +622,7 @@ function buildMcpServer(ctx) {
 			])).describe("Kind to look up when citedArtifactId is omitted (defaults to the kind required by the transition)."),
 			behaviorId: z.optional(z.coerce.number()).describe("tdd_session_behaviors.id when transitioning a specific behavior (must belong to goalId)"),
 			reason: z.optional(z.string()).describe("Free-text reason for the transition")
-		},
+		}),
 		outputSchema: effectToZodSchema(PhaseTransitionResult)
 	}, async (args) => structuredJsonResult(await caller.tdd_phase_transition_request({
 		tddTaskId: args.tddTaskId,
@@ -574,7 +635,7 @@ function buildMcpServer(ctx) {
 	})));
 	server.registerTool("tdd_goal", {
 		description: "Use to manage TDD goals, with a CRUD action discriminator: action='create' (tddTaskId, goal) is idempotent on (tddTaskId, goal); action='update' (id, goal?, status?) edits text and/or lifecycle status; action='delete' (id) hard-deletes (prefer status:'abandoned'); action='get' (id) reads with nested behaviors; action='list' (tddTaskId) returns all goals for a TDD task.",
-		inputSchema: {
+		inputSchema: strict({
 			action: z.enum([
 				"create",
 				"update",
@@ -591,7 +652,7 @@ function buildMcpServer(ctx) {
 				"done",
 				"abandoned"
 			]))
-		},
+		}),
 		outputSchema: effectToZodSchema(TddGoalResult)
 	}, async (args) => {
 		if (args.action === "create") return structuredJsonResult(await caller.tdd_goal({
@@ -620,7 +681,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("tdd_behavior", {
 		description: "Use to manage TDD behaviors, with a CRUD action discriminator: action='create' (goalId, behavior, suggestedTestName?, dependsOnBehaviorIds?) is idempotent on (goalId, behavior); action='update' (id, ...patch) edits; action='delete' (id) hard-deletes; action='get' (id) reads; action='list_by_goal' (goalId) lists one goal's behaviors; action='list_by_tdd_task' (tddTaskId) lists across all goals.",
-		inputSchema: {
+		inputSchema: strict({
 			action: z.enum([
 				"create",
 				"update",
@@ -641,7 +702,7 @@ function buildMcpServer(ctx) {
 				"abandoned"
 			])),
 			dependsOnBehaviorIds: z.optional(z.array(z.coerce.number()))
-		},
+		}),
 		outputSchema: effectToZodSchema(TddBehaviorResult)
 	}, async (args) => {
 		if (args.action === "create") return structuredJsonResult(await caller.tdd_behavior({
@@ -678,7 +739,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("tdd_artifact_list", {
 		description: "Use when you need the artifact id to cite in tdd_phase_transition_request without querying SQLite directly. Lists TDD artifacts (test_written, test_failed_run, code_written, test_passed_run, refactor, test_weakened) for a tdd_task, newest first. Filters: artifactKind, phaseId, behaviorId, limit (default 50).",
-		inputSchema: {
+		inputSchema: strict({
 			tddTaskId: z.coerce.number().describe("tdd_tasks.id"),
 			artifactKind: z.optional(z.enum([
 				"test_written",
@@ -691,7 +752,7 @@ function buildMcpServer(ctx) {
 			phaseId: z.optional(z.coerce.number()).describe("Restrict to artifacts recorded in one phase"),
 			behaviorId: z.optional(z.coerce.number()).describe("Restrict to artifacts recorded in phases bound to one behavior"),
 			limit: z.optional(z.coerce.number()).describe("Max rows (default 50)")
-		},
+		}),
 		outputSchema: effectToZodSchema(TddArtifactListResult)
 	}, async (args) => {
 		const data = await caller.tdd_artifact_list({
@@ -705,7 +766,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("hypothesis", {
 		description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt) records a validation outcome; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
-		inputSchema: {
+		inputSchema: strict({
 			action: z.enum([
 				"record",
 				"validate",
@@ -727,7 +788,7 @@ function buildMcpServer(ctx) {
 			validatedTurnId: z.optional(z.coerce.number()),
 			validatedAt: z.optional(z.string()).describe("ISO 8601 timestamp (action=validate)"),
 			limit: z.optional(z.coerce.number())
-		},
+		}),
 		outputSchema: effectToZodSchema(HypothesisResult)
 	}, async (args) => {
 		if (args.action === "record") return structuredJsonResult(await caller.hypothesis({
@@ -756,7 +817,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("tdd_progress_push", {
 		description: "Use when a TDD orchestrator needs to report progress to the main agent over a Claude Code channel. The MCP server validates the payload against the ChannelEvent union and resolves goalId/sessionId server-side from behaviorId for behavior-scoped events (so a stale orchestrator context cannot push the wrong tree coordinates). Best-effort — returns { ok: true } regardless of whether channels are active.",
-		inputSchema: { payload: z.string().describe("Pre-stringified ChannelEvent JSON (see schemas/ChannelEvent in @vitest-agent/sdk)") }
+		inputSchema: strict({ payload: z.string().describe("Pre-stringified ChannelEvent JSON (see schemas/ChannelEvent in @vitest-agent/sdk)") })
 	}, async (args) => {
 		let resolvedPayload = args.payload;
 		try {
@@ -773,7 +834,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("acceptance_metrics", {
 		description: "Use when you need the four spec Annex A acceptance metrics computed from the current database. Returns markdown in content[] and a typed JSON object in structuredContent (per-metric { total, ratio, ... }).",
-		inputSchema: {},
+		inputSchema: strict({}),
 		outputSchema: effectToZodSchema(AcceptanceMetricsResult)
 	}, async () => {
 		const data = await caller.acceptance_metrics({});
@@ -781,10 +842,10 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("triage_brief", {
 		description: "Use when you need to orient on the current test landscape: failing tests, flaky tests, open TDD sessions, and suggested next actions. Returns markdown in content[] and a typed envelope in structuredContent ({ hasContent, markdown }).",
-		inputSchema: {
+		inputSchema: strict({
 			project: z.optional(z.string()).describe("Filter to a specific project"),
 			maxLines: z.optional(z.coerce.number()).describe("Soft cap on rendered output lines")
-		},
+		}),
 		outputSchema: effectToZodSchema(TriageBriefResult)
 	}, async (args) => {
 		const data = await caller.triage_brief({
@@ -795,7 +856,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("wrapup_prompt", {
 		description: "Use when a session is ending and you need a tailored wrap-up prompt (Stop / SessionEnd / PreCompact / TDD handoff / UserPromptSubmit nudge variants). Returns markdown in content[] and a typed envelope in structuredContent ({ hasContent, kind, markdown }).",
-		inputSchema: {
+		inputSchema: strict({
 			sessionId: z.optional(z.coerce.number()).describe("sessions.id (integer); omit to use chatId"),
 			chatId: z.optional(z.string()).describe("Host chat UUID (alternative to sessionId)"),
 			kind: z.optional(z.enum([
@@ -806,7 +867,7 @@ function buildMcpServer(ctx) {
 				"user_prompt_nudge"
 			])).describe("Wrap-up flavor (default: session_end)"),
 			userPromptHint: z.optional(z.string()).describe("For user_prompt_nudge: the prompt text to inspect")
-		},
+		}),
 		outputSchema: effectToZodSchema(WrapupPromptResult)
 	}, async (args) => {
 		const data = await caller.wrapup_prompt({
@@ -819,7 +880,7 @@ function buildMcpServer(ctx) {
 	});
 	server.registerTool("commit_changes", {
 		description: "Use when you need commit metadata and changed files captured by the post-commit hook. Returns up to 20 most-recent when sha is omitted. Returns markdown in content[] and a typed JSON object in structuredContent ({ filterSha?, count, commits[] }).",
-		inputSchema: { sha: z.optional(z.string()).describe("Specific commit sha to fetch; omit for recent commits") },
+		inputSchema: strict({ sha: z.optional(z.string()).describe("Specific commit sha to fetch; omit for recent commits") }),
 		outputSchema: effectToZodSchema(CommitChangesResult)
 	}, async (args) => {
 		const data = await caller.commit_changes({ sha: args.sha });

package/tools/help.js

@@ -36,7 +36,7 @@ const HELP_TEXT = `# vitest-agent MCP Tools
 
 \`test\` actions:
 - \`{ action: "list", project?, state?, module?, limit? }\`
-- \`{ action: "get", fullName, project? }\`
+- \`{ action: "get", fullName, project?, modulePath? }\` — a \`fullName\` present in more than one module returns \`found: false\` with \`ambiguous: true\` and \`candidateModules[]\`; pass \`modulePath\` to pick one
 - \`{ action: "for_file", filePath }\`
 - \`{ action: "for_tag", tag, project? }\` — list every test carrying a tag, grouped by project (or one group when project is supplied)
 

package/tools/history.js

@@ -91,12 +91,25 @@ const TestHistoryAsMarkdown = TestHistoryResult.pipe(Schema.decodeTo(Schema.Stri
 	decode: SchemaGetter.transform((data) => formatTestHistoryMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "TestHistoryAsMarkdown is one-way: markdown cannot be parsed back to TestHistoryResult.")
 }));
-const testHistory = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({ project: Schema.String }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+const testHistory = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
+	project: Schema.String,
+	testName: Schema.optional(Schema.String).annotate({ description: "Exact full_name match — narrows to a single test's history." }),
+	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — narrows to tests in one file." }),
+	limit: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0)).annotate({ description: "Max runs kept per test, most-recent-first. Must be a positive integer. Default 20." }))
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
 	const reader = yield* DataReader;
+	const scopeOptions = {
+		...input.testName !== void 0 && { testName: input.testName },
+		...input.modulePath !== void 0 && { modulePath: input.modulePath }
+	};
+	const historyOptions = {
+		...scopeOptions,
+		...input.limit !== void 0 && { limit: input.limit }
+	};
 	const [history, flaky, persistent] = yield* Effect.all([
-		reader.getHistory(input.project),
-		reader.getFlaky(input.project),
-		reader.getPersistentFailures(input.project)
+		reader.getHistory(input.project, historyOptions),
+		reader.getFlaky(input.project, scopeOptions),
+		reader.getPersistentFailures(input.project, scopeOptions)
 	]);
 	const recovered = history.tests.filter((t) => {
 		const runs = t.runs;

package/tools/run-tests.js

@@ -8,9 +8,26 @@ import { join } from "node:path";
 import { Writable } from "node:stream";
 
 //#region src/tools/run-tests.ts
+const TagFilter = Schema.Struct({
+	all: Schema.optional(Schema.Array(Schema.String)),
+	any: Schema.optional(Schema.Array(Schema.String)),
+	none: Schema.optional(Schema.Array(Schema.String))
+}).annotate({
+	identifier: "TagFilter",
+	description: "All three sub-filters AND together with `project` and `files`. `all` requires every listed tag on the test. `any` requires at least one. `none` excludes any test carrying a listed tag."
+});
+const RunTestsScope = Schema.Struct({
+	project: Schema.NullOr(Schema.String),
+	files: Schema.Array(Schema.String),
+	tags: Schema.NullOr(TagFilter)
+}).annotate({
+	identifier: "RunTestsScope",
+	description: "The filter set actually used for this run, verbatim. Lets an agent tell 'ran exactly what I asked' apart from 'a dropped/misspelled param silently ran everything' without cross-checking summary counts."
+});
 const RunTestsOk = Schema.Struct({
 	kind: Schema.Literal("ok").annotate({ description: "Discriminant — `true` test run completed (with or without failures)." }),
 	project: Schema.optional(Schema.String),
+	scope: RunTestsScope,
 	report: AgentReport.annotate({ description: "Full AgentReport including pass/fail counts and per-module errors." }),
 	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." })
@@ -23,14 +40,6 @@ const RunTestsError = Schema.Struct({
 	kind: Schema.Literal("error"),
 	message: Schema.String
 }).annotate({ identifier: "RunTestsError" });
-const TagFilter = Schema.Struct({
-	all: Schema.optional(Schema.Array(Schema.String)),
-	any: Schema.optional(Schema.Array(Schema.String)),
-	none: Schema.optional(Schema.Array(Schema.String))
-}).annotate({
-	identifier: "TagFilter",
-	description: "All three sub-filters AND together with `project` and `files`. `all` requires every listed tag on the test. `any` requires at least one. `none` excludes any test carrying a listed tag."
-});
 const RunTestsNoMatch = Schema.Struct({
 	kind: Schema.Literal("no-match").annotate({ description: "Discriminant — the resolved filter set matched zero test cases. Tests did not run; this is independent of passWithNoTests policy." }),
 	filter: Schema.Struct({
@@ -391,6 +400,11 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 		return {
 			kind: "ok",
 			...project !== void 0 && { project },
+			scope: {
+				project: project ?? null,
+				files,
+				tags: tagsInput ?? null
+			},
 			report,
 			classifications: classifications ? Object.fromEntries(classifications) : {},
 			discoveryLastScannedAt: readDiscoveryLastScannedAt() ?? null

package/tools/test.js

@@ -52,7 +52,16 @@ const TestGetMissing = Schema.Struct({
 	action: Schema.Literal("get"),
 	found: Schema.Literal(false),
 	project: Schema.String,
-	fullName: Schema.String
+	fullName: Schema.String,
+	/**
+	* `true` when the lookup failed *because* the name matched more than
+	* one module in the project's latest run and no `modulePath` was
+	* supplied to disambiguate (issue #243) — as opposed to the name
+	* simply not existing.
+	*/
+	ambiguous: Schema.optional(Schema.Boolean),
+	/** The module paths a `fullName` matched when `ambiguous` is `true`. */
+	candidateModules: Schema.optional(Schema.Array(Schema.String))
 }).annotate({ identifier: "TestGetMissing" });
 const TestForFileResult = Schema.Struct({
 	action: Schema.Literal("for_file"),
@@ -93,7 +102,19 @@ const formatTestMarkdown = (data) => {
 		return lines.join("\n").trimEnd();
 	}
 	if (data.action === "get") {
-		if (!data.found) return `Test not found: \`${data.fullName}\`\n\nUse test({ action: "list" }) to discover available tests (format: "Suite > test name").`;
+		if (!data.found) {
+			if (data.ambiguous === true) {
+				const modules = data.candidateModules ?? [];
+				return [
+					`Ambiguous test name: \`${data.fullName}\` matches ${modules.length} modules in project \`${data.project}\`.`,
+					"",
+					...modules.map((m) => `- \`${m}\``),
+					"",
+					`Re-run with a modulePath, e.g. test({ action: "get", fullName: "${data.fullName}", modulePath: "${modules[0] ?? ""}" }).`
+				].join("\n");
+			}
+			return `Test not found: \`${data.fullName}\`\n\nUse test({ action: "list" }) to discover available tests (format: "Suite > test name").`;
+		}
 		const t = data.test;
 		const lines = [
 			`# Test: ${t.fullName}`,
@@ -180,7 +201,8 @@ const ListVariant = Schema.Struct({
 const GetVariant = Schema.Struct({
 	action: Schema.Literal("get"),
 	fullName: Schema.String,
-	project: Schema.optional(Schema.String)
+	project: Schema.optional(Schema.String),
+	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." })
 });
 const ForFileVariant = Schema.Struct({
 	action: Schema.Literal("for_file"),
@@ -228,15 +250,28 @@ const test = publicProcedure.input(Schema.toStandardSchemaV1(TestInput)).query(a
 			const reader = yield* DataReader;
 			const candidates = variant.project ? [variant.project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
 			for (const project of candidates) {
-				const testOpt = yield* reader.getTestByFullName(project, variant.fullName);
+				const modules = yield* reader.getTestModulesByFullName(project, variant.fullName);
+				if (modules.length === 0) continue;
+				if (variant.modulePath === void 0 && modules.length > 1) return {
+					action: "get",
+					found: false,
+					project,
+					fullName: variant.fullName,
+					ambiguous: true,
+					candidateModules: modules
+				};
+				const testOpt = yield* reader.getTestByFullName(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
 				if (Option.isNone(testOpt)) continue;
-				const matchingErrors = (yield* reader.getErrors(project)).filter((e) => e.testFullName === variant.fullName).map((e) => ({
+				const matchingErrors = (yield* reader.getErrors(project)).filter((e) => e.testFullName === variant.fullName && e.moduleFile === testOpt.value.module).map((e) => ({
 					name: e.name,
 					message: e.message,
 					diff: e.diff,
 					stack: e.stack
 				}));
-				const testHistory = (yield* reader.getHistory(project)).tests.find((entry) => entry.fullName === variant.fullName);
+				const testHistory = (yield* reader.getHistory(project, {
+					testName: variant.fullName,
+					modulePath: testOpt.value.module
+				})).tests.find((entry) => entry.fullName === variant.fullName);
 				return {
 					action: "get",
 					found: true,

package/utils/crash-guards.js

@@ -0,0 +1,35 @@
+//#region src/utils/crash-guards.ts
+/**
+* Pure decision logic backing `bin.ts`'s `process.on("uncaughtException")`
+* guard (issue #191, sub-item A).
+*
+* Node's own guidance for `uncaughtException` is "do not resume normal
+* operation" because arbitrary in-process state may be corrupt. This
+* package accepts that residual risk *after* the stdio transport is
+* connected: it holds no long-lived mutable state outside SQLite
+* itself (every `DataStore`/`DataReader` call is a self-contained
+* transaction via the shared `ManagedRuntime`), so a synchronous throw
+* that escapes even the MCP SDK's own per-tool-call try/catch cannot
+* leave this process's own bookkeeping half-mutated in a way that
+* would corrupt the *next* call — and the alternative, silent process
+* death mid-TDD-session (deregistering every tool from the client), is
+* strictly worse for a long-running dev tool.
+*
+* Before the transport connects there is no client session to
+* preserve by staying alive, so failing fast and loud is the better
+* default rather than spinning forever in a half-initialized state.
+*
+* @packageDocumentation
+*/
+/**
+* @param transportConnected - whether `server.connect(transport)` has
+*   already resolved for this process
+* @returns `true` when the process should exit rather than continue
+* @public
+*/
+function shouldExitOnUncaughtException(transportConnected) {
+	return !transportConnected;
+}
+
+//#endregion
+export { shouldExitOnUncaughtException };

package/utils/safe-format-fatal-error.js

@@ -0,0 +1,44 @@
+import { formatFatalError } from "@vitest-agent/sdk";
+
+//#region src/utils/safe-format-fatal-error.ts
+/**
+* Crash-handler-safe wrapper around `@vitest-agent/sdk`'s
+* {@link formatFatalError}.
+*
+* `bin.ts`'s `unhandledRejection` / `uncaughtException` handlers exist so
+* a stray throw cannot kill a live MCP session (issue #191). Calling the
+* formatter directly from inside them reopened exactly that hole:
+* `formatFatalError` introspects the value it is given — `Symbol.for(...)
+* in reason`, `err instanceof Error`, `JSON.stringify(err)` — and every
+* one of those is hijackable by a `Proxy` whose `has` / `getPrototypeOf`
+* / `get` trap throws. A throw *inside* an `uncaughtException` handler is
+* fatal to the process with no second chance to report it, so the crash
+* guard would have crashed the process it exists to protect (issue #243).
+*
+* @packageDocumentation
+*/
+/**
+* Fixed fallback emitted when the formatter itself throws. Deliberately a
+* constant: anything derived from the offending value could throw again
+* on the recovery path.
+*
+* @internal
+*/
+const UNFORMATTABLE_ERROR_TEXT = "<unformattable error value — the error formatter itself threw>";
+/**
+* Format an unknown error for a crash handler. Never throws.
+*
+* @param err - the value thrown or the rejection reason
+* @internal
+*/
+function safeFormatFatalError(err) {
+	try {
+		const formatted = formatFatalError(err);
+		return typeof formatted === "string" ? formatted : UNFORMATTABLE_ERROR_TEXT;
+	} catch {
+		return UNFORMATTABLE_ERROR_TEXT;
+	}
+}
+
+//#endregion
+export { UNFORMATTABLE_ERROR_TEXT, safeFormatFatalError };

package/utils/tool-error-envelope.js

@@ -0,0 +1,61 @@
+//#region src/utils/tool-error-envelope.ts
+/**
+* Fixed fallback used when even *introspecting* the thrown value throws.
+* Deliberately a constant — anything derived from `err` could throw again
+* on the recovery path.
+*/
+const UNREADABLE_THROWN_VALUE = "<unreadable thrown value>";
+/**
+* Coerces an unknown thrown value into a display-safe message without
+* risking a second throw (a getter-backed `.message` can itself throw —
+* see `@vitest-agent/sdk`'s `coerceErrorField` for the same concern on
+* raw Vitest error objects).
+*
+* The outer guard matters as much as the inner one: `err instanceof
+* Error` walks the prototype chain, which a `Proxy` `getPrototypeOf`
+* trap can hijack and throw from, and `String(err)` invokes
+* `Symbol.toPrimitive` / `toString`, which a trap can hijack too. A
+* throw here escapes the envelope builder entirely and the agent gets
+* nothing structured back — the exact degradation this module exists to
+* prevent (issue #243).
+*/
+function coerceThrownMessage(err) {
+	try {
+		if (typeof err === "string") return err;
+		if (err instanceof Error) try {
+			const message = err.message;
+			return typeof message === "string" ? message : String(message);
+		} catch {
+			return "<unreadable Error.message>";
+		}
+		return String(err);
+	} catch {
+		return UNREADABLE_THROWN_VALUE;
+	}
+}
+/**
+* Builds the structured envelope a tool's catch-all wrapper returns
+* when its resolver throws unexpectedly.
+*
+* @param toolName - the MCP tool name under which the resolver was registered
+* @param err - the value thrown or the rejection reason
+* @public
+*/
+function buildUnexpectedToolErrorEnvelope(toolName, err) {
+	return {
+		ok: false,
+		error: {
+			_tag: "UnexpectedToolError",
+			tool: toolName,
+			message: coerceThrownMessage(err),
+			remediation: {
+				suggestedTool: toolName,
+				suggestedArgs: {},
+				humanHint: `The "${toolName}" tool's resolver threw before producing a result (unrelated to your input in most cases). Retry the call; if it persists, check the MCP server's stderr for the logged error.`
+			}
+		}
+	};
+}
+
+//#endregion
+export { buildUnexpectedToolErrorEnvelope };