@vitest-agent/mcp 2.4.11 → 2.4.13

package/index.d.ts

@@ -245,6 +245,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
         } | undefined;
         readonly scoped: boolean;
         readonly scopedFiles?: readonly string[] | undefined;
+        readonly totalFiles?: number | undefined;
         readonly lowCoverage: readonly {
           readonly file: string;
           readonly summary: {
@@ -639,6 +640,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
           } | undefined;
           readonly scoped: boolean;
           readonly scopedFiles?: readonly string[] | undefined;
+          readonly totalFiles?: number | undefined;
           readonly lowCoverage: readonly {
             readonly file: string;
             readonly summary: {
@@ -679,12 +681,17 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
             readonly sample?: string | undefined;
           }[];
           readonly truncated?: boolean | undefined;
+          readonly fromFailingTests?: {
+            readonly total: number;
+            readonly files: number;
+          } | undefined;
         } | undefined;
       };
       readonly classifications: {
         readonly [x: string]: string;
       };
       readonly discoveryLastScannedAt?: string | null | undefined;
+      readonly scopedNote?: string | null | undefined;
     } | {
       readonly kind: "timeout";
       readonly timeoutSeconds: number;
@@ -1435,6 +1442,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
         readonly testRunId: number | null;
         readonly testFirstFailureRunId: number | null;
         readonly recordedAt: string;
+        readonly suite: "bats" | "vitest";
       }[];
     };
     meta: object;

package/index.js

@@ -12,7 +12,7 @@ import { parseSessionEnvExports, recoverSessionContextFromSessionEnv } from "./s
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "2.4.11";
+const CURRENT_MCP_VERSION = "2.4.13";
 
 //#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.4.11",
+	"version": "2.4.13",
 	"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,9 +42,9 @@
 		"@effect/sql-sqlite-node": "4.0.0-rc.109",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "2.4.13",
+		"@vitest-agent/sdk": "2.5.0",
 		"effect": "4.0.0-rc.109",
-		"zod": "^4.4.3"
+		"zod": "^4.5.4"
 	},
 	"peerDependencies": {
 		"vitest": "^4.1.0"

package/server.js

@@ -9,9 +9,9 @@ import { FailureSignatureGetAsMarkdown, FailureSignatureGetResult } from "./tool
 import { FileCoverageAsMarkdown, FileCoverageResult } from "./tools/file-coverage.js";
 import { HelpResult } from "./tools/help.js";
 import { TestHistoryAsMarkdown, TestHistoryResult } from "./tools/history.js";
-import { HypothesisResult, formatHypothesisListMarkdown } from "./tools/hypothesis.js";
-import { InventoryAsMarkdown, InventoryResult } from "./tools/inventory.js";
-import { NoteResult, formatNoteListMarkdown } from "./tools/note.js";
+import { HYPOTHESIS_ACTIONS, HypothesisResult, formatHypothesisListMarkdown } from "./tools/hypothesis.js";
+import { INVENTORY_KINDS, InventoryAsMarkdown, InventoryResult } from "./tools/inventory.js";
+import { NOTE_ACTIONS, NoteResult, formatNoteListMarkdown } from "./tools/note.js";
 import { TestOverviewAsMarkdown, TestOverviewResult } from "./tools/overview.js";
 import { PingResult } from "./tools/ping.js";
 import { RegisterAgentResult } from "./tools/register-agent.js";
@@ -19,11 +19,11 @@ import { RunTestsAsMarkdown, RunTestsResult } from "./tools/run-tests.js";
 import { SettingsListAsMarkdown, SettingsListResult } from "./tools/settings-list.js";
 import { TestStatusAsMarkdown, TestStatusResult } from "./tools/status.js";
 import { TddArtifactListAsMarkdown, TddArtifactListResult } from "./tools/tdd-artifact.js";
-import { TddBehaviorResult } from "./tools/tdd-behavior.js";
-import { TddGoalResult } from "./tools/tdd-goal.js";
+import { TDD_BEHAVIOR_ACTIONS, TddBehaviorResult } from "./tools/tdd-behavior.js";
+import { TDD_GOAL_ACTIONS, TddGoalResult } from "./tools/tdd-goal.js";
 import { PhaseTransitionResult } from "./tools/tdd-phase-transition-request.js";
-import { TddTaskAsMarkdown, TddTaskResult } from "./tools/tdd-task.js";
-import { TestAsMarkdown, TestResult } from "./tools/test.js";
+import { TDD_TASK_ACTIONS, TddTaskAsMarkdown, TddTaskResult } from "./tools/tdd-task.js";
+import { TEST_ACTIONS, TestAsMarkdown, TestResult } from "./tools/test.js";
 import { TestTrendsAsMarkdown, TestTrendsResult } from "./tools/trends.js";
 import { TriageBriefResult } from "./tools/triage-brief.js";
 import { TurnSearchAsMarkdown, TurnSearchResult } from "./tools/turn-search.js";
@@ -259,20 +259,17 @@ 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?, 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).",
+		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; action='for_tag' (tag, project?) returns tests carrying a tag, grouped by project. structuredContent carries the typed payload (discriminate on `action`, then on `found` for get).",
 		inputSchema: strict({
-			action: z.enum([
-				"list",
-				"get",
-				"for_file"
-			]).describe("Inspection discriminator"),
+			action: z.enum(TEST_ACTIONS).describe("Inspection discriminator"),
 			project: z.optional(z.string()),
 			state: z.optional(z.string()).describe("list: filter by state"),
 			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")
+			filePath: z.optional(z.string()).describe("for_file: source file path"),
+			tag: z.optional(z.string()).describe("for_tag: tag name")
 		}),
 		outputSchema: effectToZodSchema(TestResult)
 	}, async (args) => {
@@ -290,10 +287,15 @@ function buildMcpServer(ctx) {
 			...args.project !== void 0 && { project: args.project },
 			...args.modulePath !== void 0 && { modulePath: args.modulePath }
 		});
-		else data = await caller.test({
+		else if (args.action === "for_file") data = await caller.test({
 			action: "for_file",
 			filePath: args.filePath
 		});
+		else data = await caller.test({
+			action: "for_tag",
+			tag: args.tag,
+			...args.project !== void 0 && { project: args.project }
+		});
 		return structuredResult(Schema.decodeSync(TestAsMarkdown)(data), data);
 	});
 	server.registerTool("file_coverage", {
@@ -326,14 +328,9 @@ function buildMcpServer(ctx) {
 		return structuredResult(Schema.decodeSync(CacheHealthAsMarkdown)(data), data);
 	});
 	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.",
+		description: "Use to discover what exists in the workspace, with a kind discriminator: project / module / suite / session / tag. structuredContent discriminates on `inventoryKind` (project, module, suite, session_detail, session_list, tag_scoped, tag_unscoped) so callers can branch on the response shape without parsing markdown.",
 		inputSchema: strict({
-			kind: z.enum([
-				"project",
-				"module",
-				"suite",
-				"session"
-			]).describe("Inventory entity"),
+			kind: z.enum(INVENTORY_KINDS).describe("Inventory entity"),
 			id: z.optional(z.coerce.number()).describe("session: single-row lookup by id"),
 			project: z.optional(z.string()),
 			module: z.optional(z.string()).describe("suite: filter by module path"),
@@ -353,13 +350,17 @@ function buildMcpServer(ctx) {
 			...args.project !== void 0 && { project: args.project },
 			...args.module !== void 0 && { module: args.module }
 		});
-		else data = await caller.inventory({
+		else if (args.kind === "session") data = await caller.inventory({
 			kind: "session",
 			...args.id !== void 0 && { id: args.id },
 			...args.project !== void 0 && { project: args.project },
 			...args.agentKind !== void 0 && { agentKind: args.agentKind },
 			...args.limit !== void 0 && { limit: args.limit }
 		});
+		else data = await caller.inventory({
+			kind: "tag",
+			...args.project !== void 0 && { project: args.project }
+		});
 		return structuredResult(Schema.decodeSync(InventoryAsMarkdown)(data), data);
 	});
 	server.registerTool("settings_list", {
@@ -439,14 +440,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: strict({
-			action: z.enum([
-				"create",
-				"list",
-				"get",
-				"update",
-				"delete",
-				"search"
-			]).describe("CRUD discriminator"),
+			action: z.enum(NOTE_ACTIONS).describe("CRUD discriminator"),
 			id: z.optional(z.coerce.number()).describe("get/update/delete: note id"),
 			project: z.optional(z.string()),
 			title: z.optional(z.string()),
@@ -550,12 +544,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: strict({
-			action: z.enum([
-				"start",
-				"end",
-				"get",
-				"resume"
-			]).describe("Lifecycle discriminator"),
+			action: z.enum(TDD_TASK_ACTIONS).describe("Lifecycle discriminator"),
 			tddTaskId: z.optional(z.coerce.number()).describe("end/get/resume: tdd task id"),
 			goal: z.optional(z.string()).describe("start: goal text"),
 			sessionId: z.optional(z.coerce.number()).describe("start: sessions.id (alternative to chatId)"),
@@ -638,13 +627,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: strict({
-			action: z.enum([
-				"create",
-				"update",
-				"delete",
-				"get",
-				"list"
-			]).describe("CRUD discriminator"),
+			action: z.enum(TDD_GOAL_ACTIONS).describe("CRUD discriminator"),
 			id: z.optional(z.coerce.number()).describe("update/delete/get: goal id"),
 			tddTaskId: z.optional(z.coerce.number()).describe("create/list: tdd task id"),
 			goal: z.optional(z.string()),
@@ -684,14 +667,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: strict({
-			action: z.enum([
-				"create",
-				"update",
-				"delete",
-				"get",
-				"list_by_goal",
-				"list_by_tdd_task"
-			]).describe("CRUD discriminator"),
+			action: z.enum(TDD_BEHAVIOR_ACTIONS).describe("CRUD discriminator"),
 			id: z.optional(z.coerce.number()),
 			goalId: z.optional(z.coerce.number()),
 			tddTaskId: z.optional(z.coerce.number()),
@@ -769,11 +745,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 — validatedAt is optional and defaults server-side to now when omitted, or is honored verbatim when supplied; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
 		inputSchema: strict({
-			action: z.enum([
-				"record",
-				"validate",
-				"list"
-			]).describe("CRUD discriminator"),
+			action: z.enum(HYPOTHESIS_ACTIONS).describe("CRUD discriminator"),
 			sessionId: z.optional(z.coerce.number()).describe("list: filter by session id. record: dev/test fallback only — ignored when host context is recovered; never pass a tddTaskId value here"),
 			tddTaskId: z.optional(z.coerce.number()).describe("record: tdd task id returned by tdd_task action='start' — binds the hypothesis to that task's session deterministically"),
 			content: z.optional(z.string()).describe("Hypothesis content (action=record)"),

package/tools/coverage.js

@@ -3,11 +3,6 @@ import { CoverageReport, DataReader } from "@vitest-agent/sdk";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
 
 //#region src/tools/coverage.ts
-/**
-* `test_coverage` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const CoverageAvailable = Schema.Struct({
 	dataAvailable: Schema.Literal(true),
 	project: Schema.String,
@@ -22,34 +17,49 @@ const TestCoverageResult = Schema.Union([CoverageAvailable, CoverageAbsent]).ann
 	title: "test_coverage result",
 	description: "Per-project coverage report. Discriminate on `dataAvailable` for cold-start handling."
 });
+const METRICS = [
+	"statements",
+	"branches",
+	"functions",
+	"lines"
+];
+/** @internal */
+const renderFileCoverageTable = (fileCoverage) => {
+	const rows = [
+		`### \`${fileCoverage.file}\``,
+		"",
+		"| Metric | Value |",
+		"| --- | --- |"
+	];
+	for (const metric of METRICS) rows.push(`| ${metric} | ${fileCoverage.summary[metric].toFixed(2)}% |`);
+	if (fileCoverage.uncoveredLines) rows.push(`| Uncovered lines | \`${fileCoverage.uncoveredLines}\` |`);
+	rows.push("");
+	return rows;
+};
 const formatTestCoverageMarkdown = (data) => {
 	if (!data.dataAvailable) return "No coverage data available. Run tests with coverage enabled.";
 	const lines = ["# Coverage Report", ""];
-	const { totals, thresholds } = data.coverage;
-	lines.push("## Totals", "", "| Metric | Value | Threshold |", "| --- | --- | --- |");
-	const metrics = [
-		"statements",
-		"branches",
-		"functions",
-		"lines"
-	];
-	for (const metric of metrics) {
+	const { totals, thresholds, targets } = data.coverage;
+	const headerCols = targets ? "| Metric | Value | Enforced threshold | Target |" : "| Metric | Value | Enforced threshold |";
+	const sepCols = targets ? "| --- | --- | --- | --- |" : "| --- | --- | --- |";
+	lines.push("## Totals", "", headerCols, sepCols);
+	for (const metric of METRICS) {
 		const value = totals[metric];
 		const threshold = thresholds.global[metric];
 		const thresholdStr = threshold !== void 0 ? `${threshold}%` : "—";
 		const icon = threshold !== void 0 && value < threshold ? "❌" : "✅";
-		lines.push(`| ${metric} | ${icon} ${value.toFixed(2)}% | ${thresholdStr} |`);
+		const targetStr = targets ? targets.global[metric] !== void 0 ? `${targets.global[metric]}%` : "—" : void 0;
+		lines.push(`| ${metric} | ${icon} ${value.toFixed(2)}% | ${thresholdStr} |${targetStr !== void 0 ? ` ${targetStr} |` : ""}`);
 	}
 	lines.push("");
 	if (data.coverage.lowCoverage.length > 0) {
-		lines.push("## Coverage Gaps", "", "Files below coverage threshold:", "");
-		for (const fileCoverage of data.coverage.lowCoverage) {
-			lines.push(`### \`${fileCoverage.file}\``, "", "| Metric | Value |", "| --- | --- |");
-			for (const metric of metrics) lines.push(`| ${metric} | ${fileCoverage.summary[metric].toFixed(2)}% |`);
-			if (fileCoverage.uncoveredLines) lines.push(`| Uncovered lines | \`${fileCoverage.uncoveredLines}\` |`);
-			lines.push("");
-		}
+		lines.push("## Coverage Gaps", "", "Files below the enforced threshold (build-blocking):", "");
+		for (const fileCoverage of data.coverage.lowCoverage) lines.push(...renderFileCoverageTable(fileCoverage));
 	} else lines.push("✅ All files meet coverage thresholds.", "");
+	if (data.coverage.belowTarget && data.coverage.belowTarget.length > 0) {
+		lines.push("## Coverage Improvements Needed", "", "Files below the aspirational target (passing the enforced threshold):", "");
+		for (const fileCoverage of data.coverage.belowTarget) lines.push(...renderFileCoverageTable(fileCoverage));
+	}
 	return lines.join("\n");
 };
 const TestCoverageAsMarkdown = TestCoverageResult.pipe(Schema.decodeTo(Schema.String, {

package/tools/hypothesis.js

@@ -91,6 +91,17 @@ const HypothesisInput = Schema.Union([
 	ValidateVariant,
 	ListVariant
 ]);
+/**
+* Single source of truth for the `hypothesis` tool's `action`
+* discriminant, consumed by `server.ts`'s served `z.enum(...)` so the
+* MCP-SDK-side registration cannot drift from this tRPC input union
+* (issue #335).
+*/
+const HYPOTHESIS_ACTIONS = [
+	"record",
+	"validate",
+	"list"
+];
 const hypothesis = idempotentProcedure.input(Schema.toStandardSchemaV1(HypothesisInput)).mutation(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		record: (variant) => Effect.gen(function* () {
@@ -157,4 +168,4 @@ const hypothesis = idempotentProcedure.input(Schema.toStandardSchemaV1(Hypothesi
 });
 
 //#endregion
-export { HypothesisResult, formatHypothesisListMarkdown, hypothesis };
+export { HYPOTHESIS_ACTIONS, HypothesisResult, formatHypothesisListMarkdown, hypothesis };

package/tools/inventory.js

@@ -255,6 +255,18 @@ const InventoryInput = Schema.Union([
 	SessionVariant,
 	TagVariant
 ]);
+/**
+* Single source of truth for the `inventory` tool's `kind` discriminant,
+* consumed by `server.ts`'s served `z.enum(...)` so the MCP-SDK-side
+* registration cannot drift from this tRPC input union (issue #335).
+*/
+const INVENTORY_KINDS = [
+	"project",
+	"module",
+	"suite",
+	"session",
+	"tag"
+];
 const inventory = publicProcedure.input(Schema.toStandardSchemaV1(InventoryInput)).query(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("kind")({
 		project: () => Effect.gen(function* () {
@@ -377,4 +389,4 @@ const inventory = publicProcedure.input(Schema.toStandardSchemaV1(InventoryInput
 });
 
 //#endregion
-export { InventoryAsMarkdown, InventoryResult, formatInventoryMarkdown, inventory };
+export { INVENTORY_KINDS, InventoryAsMarkdown, InventoryResult, formatInventoryMarkdown, inventory };

package/tools/note.js

@@ -152,6 +152,19 @@ const NoteInputUnion = Schema.Union([
 	DeleteVariant,
 	SearchVariant
 ]);
+/**
+* Single source of truth for the `note` tool's `action` discriminant,
+* consumed by `server.ts`'s served `z.enum(...)` so the MCP-SDK-side
+* registration cannot drift from this tRPC input union (issue #335).
+*/
+const NOTE_ACTIONS = [
+	"create",
+	"list",
+	"get",
+	"update",
+	"delete",
+	"search"
+];
 const note = publicProcedure.input(Schema.toStandardSchemaV1(NoteInputUnion)).mutation(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		create: (variant) => Effect.gen(function* () {
@@ -227,4 +240,4 @@ const note = publicProcedure.input(Schema.toStandardSchemaV1(NoteInputUnion)).mu
 });
 
 //#endregion
-export { NoteResult, formatNoteListMarkdown, note };
+export { NOTE_ACTIONS, NoteResult, formatNoteListMarkdown, note };

package/tools/run-tests.js

@@ -1,7 +1,7 @@
 import { publicProcedure } from "../context.js";
 import { createRequire } from "node:module";
-import { AgentReport, DataReader, DataStore, buildAgentReport, buildConsoleLeaks, coerceErrorField, collectConsoleLeakEntries } from "@vitest-agent/sdk";
-import { Effect, Schema, SchemaGetter, Semaphore } from "effect";
+import { AgentReport, DataReader, DataStore, buildAgentReport, buildConsoleLeaks, coerceErrorField, collectConsoleLeakEntries, formatScopedCoverageNote } from "@vitest-agent/sdk";
+import { Data, Effect, Schema, SchemaGetter, Semaphore } from "effect";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { execFile } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
@@ -36,7 +36,8 @@ const RunTestsOk = Schema.Struct({
 	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." })
+	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." })
 }).annotate({ identifier: "RunTestsOk" });
 const RunTestsTimeout = Schema.Struct({
 	kind: Schema.Literal("timeout"),
@@ -124,6 +125,12 @@ const makeCoverageDirOverride = () => {
 		coverage: { reportsDirectory: dir }
 	};
 };
+/**
+* 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;
@@ -358,7 +365,7 @@ function formatRunTestsMarkdown(data) {
 	const rootLine = `\nProject root: \`${data.projectRoot}\``;
 	if (data.kind === "no-match") return `${formatNoMatchMarkdown(data.filter)}${rootLine}`;
 	const classMap = new Map(Object.entries(data.classifications));
-	return `${formatReportMarkdown(data.report, classMap)}${rootLine}`;
+	return `${formatReportMarkdown(data.report, classMap, data.scopedNote ?? void 0)}${rootLine}`;
 }
 /**
 * Render the `no-match` filter context plus a remediation pointer aimed at
@@ -403,7 +410,7 @@ const RunTestsAsMarkdown = RunTestsResult.pipe(Schema.decodeTo(Schema.String, {
 *
 * @internal
 */
-function formatReportMarkdown(report, classifications) {
+function formatReportMarkdown(report, classifications, scopedNote) {
 	const lines = [];
 	const { summary } = report;
 	const collectionFailedFiles = report.failed.filter((m) => m.errors !== void 0 && m.errors.length > 0 && !m.tests.some((t) => t.state === "failed")).map((m) => m.file);
@@ -417,12 +424,19 @@ function formatReportMarkdown(report, classifications) {
 	if (summary.skipped > 0) headlineParts.push(`${summary.skipped} skipped`);
 	lines.push(`## ${status} Vitest -- ${headlineParts.join(", ")} (${summary.duration}ms)`);
 	if (report.project) lines.push(`\nProject: ${report.project}`);
+	if (scopedNote !== void 0) lines.push(`\n${scopedNote}`);
 	if (report.consoleLeaks !== void 0) {
 		const cl = report.consoleLeaks;
-		const writes = `${cl.total} stray console write${cl.total === 1 ? "" : "s"}`;
-		const plural = cl.byFile.length !== 1 || cl.truncated === true;
-		const files = `${cl.byFile.length}${cl.truncated === true ? "+" : ""} file${plural ? "s" : ""}`;
-		lines.push(`\n⚠ ${writes} across ${files} (see consoleLeaks)`);
+		if (cl.total > 0) {
+			const writes = `${cl.total} stray console write${cl.total === 1 ? "" : "s"}`;
+			const plural = cl.byFile.length !== 1 || cl.truncated === true;
+			const files = `${cl.byFile.length}${cl.truncated === true ? "+" : ""} file${plural ? "s" : ""}`;
+			lines.push(`\n⚠ ${writes} across ${files} (see consoleLeaks)`);
+		}
+		if (cl.fromFailingTests !== void 0) {
+			const { total: failingTotal } = cl.fromFailingTests;
+			lines.push(`\n${failingTotal} console write${failingTotal === 1 ? "" : "s"} from failing tests (not counted as leaks)`);
+		}
 	}
 	for (const mod of report.failed) {
 		lines.push(`\n### \u274C \`${mod.file}\``);
@@ -521,12 +535,22 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 			stderr: nullStream
 		});
 		const localVitest = vitest;
-		let timeoutHandle;
-		const result = await withStdioCaptured(nullStream, () => Promise.race([localVitest.start(files.length > 0 ? files : void 0), new Promise((_, reject) => {
-			timeoutHandle = setTimeout(() => reject(/* @__PURE__ */ new Error("VITEST_TIMEOUT")), timeoutMs);
-		})]).finally(() => {
-			if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
-		}));
+		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 (hasFilter && result.testModules.length === 0 && unhandledErrors.length === 0) return {
@@ -566,6 +590,15 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 				invocationMethod: "mcp"
 			});
 		})).catch(() => void 0);
+		let scopedNote = null;
+		if (hasFilter) {
+			const testedFileCount = testModules.length;
+			let totalFileCount;
+			try {
+				totalFileCount = (await localVitest.globTestSpecifications()).length;
+			} catch {}
+			scopedNote = formatScopedCoverageNote(testedFileCount, totalFileCount);
+		}
 		return {
 			kind: "ok",
 			...project !== void 0 && { project },
@@ -577,15 +610,12 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 			},
 			report,
 			classifications: classifications ? Object.fromEntries(classifications) : {},
-			discoveryLastScannedAt: readDiscoveryLastScannedAt() ?? null
+			discoveryLastScannedAt: readDiscoveryLastScannedAt() ?? null,
+			scopedNote
 		};
 	} catch (err) {
 		let message;
 		try {
-			if (err instanceof Error && err.message === "VITEST_TIMEOUT") return {
-				kind: "timeout",
-				timeoutSeconds: input.timeout ?? 120
-			};
 			message = err instanceof Error ? err.message : String(err);
 		} catch {
 			message = coerceErrorField(err, "message") ?? "<unserializable error>";

package/tools/tdd-artifact.js

@@ -45,7 +45,8 @@ const TddArtifactRow = Schema.Struct({
 	testCaseId: Schema.NullOr(Schema.Number),
 	testRunId: Schema.NullOr(Schema.Number),
 	testFirstFailureRunId: Schema.NullOr(Schema.Number),
-	recordedAt: Schema.String
+	recordedAt: Schema.String,
+	suite: Schema.Literals(["vitest", "bats"]).annotate({ description: "Which test runner produced this artifact — a bats run carries no test_case_id." })
 }).annotate({ identifier: "TddArtifactListRow" });
 const ArtifactFilters = Schema.Struct({
 	artifactKind: Schema.optional(ArtifactKindSchema),
@@ -73,7 +74,7 @@ const formatTddArtifactListMarkdown = (data) => {
 	if (data.count === 0) return `No artifacts recorded for tdd_task ${data.tddTaskId}${describeFilters(data.filters)}.`;
 	const lines = [`# Artifacts for tdd_task ${data.tddTaskId} (newest first, ${data.count} shown)`, ""];
 	for (const r of data.artifacts) {
-		const extras = [`phase=${r.phaseName} [phaseId=${r.phaseId}]`];
+		const extras = [`phase=${r.phaseName} [phaseId=${r.phaseId}]`, `suite=${r.suite}`];
 		if (r.behaviorId !== null) extras.push(`behaviorId=${r.behaviorId}`);
 		if (r.testCaseId !== null) extras.push(`testCaseId=${r.testCaseId}`);
 		if (r.testRunId !== null) extras.push(`testRunId=${r.testRunId}`);

package/tools/tdd-behavior.js

@@ -117,6 +117,20 @@ const TddBehaviorInput = Schema.Union([
 	ListByGoalVariant,
 	ListByTddTaskVariant
 ]);
+/**
+* Single source of truth for the `tdd_behavior` tool's `action`
+* discriminant, consumed by `server.ts`'s served `z.enum(...)` so the
+* MCP-SDK-side registration cannot drift from this tRPC input union
+* (issue #335).
+*/
+const TDD_BEHAVIOR_ACTIONS = [
+	"create",
+	"update",
+	"delete",
+	"get",
+	"list_by_goal",
+	"list_by_tdd_task"
+];
 const tddBehavior = idempotentProcedure.input(Schema.toStandardSchemaV1(TddBehaviorInput)).mutation(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		create: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
@@ -192,4 +206,4 @@ const tddBehavior = idempotentProcedure.input(Schema.toStandardSchemaV1(TddBehav
 });
 
 //#endregion
-export { TddBehaviorResult, tddBehavior };
+export { TDD_BEHAVIOR_ACTIONS, TddBehaviorResult, tddBehavior };

package/tools/tdd-goal.js

@@ -101,6 +101,19 @@ const TddGoalInput = Schema.Union([
 	GetVariant,
 	ListVariant
 ]);
+/**
+* Single source of truth for the `tdd_goal` tool's `action`
+* discriminant, consumed by `server.ts`'s served `z.enum(...)` so the
+* MCP-SDK-side registration cannot drift from this tRPC input union
+* (issue #335).
+*/
+const TDD_GOAL_ACTIONS = [
+	"create",
+	"update",
+	"delete",
+	"get",
+	"list"
+];
 const tddGoal = idempotentProcedure.input(Schema.toStandardSchemaV1(TddGoalInput)).mutation(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		create: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
@@ -160,4 +173,4 @@ const tddGoal = idempotentProcedure.input(Schema.toStandardSchemaV1(TddGoalInput
 });
 
 //#endregion
-export { TddGoalResult, tddGoal };
+export { TDD_GOAL_ACTIONS, TddGoalResult, tddGoal };

package/tools/tdd-phase-transition-request.js

@@ -3,6 +3,12 @@ import { DataReader, DataStore, requiredArtifactForTransition, transitionEnforce
 import { Effect, Option, Schema } from "effect";
 
 //#region src/tools/tdd-phase-transition-request.ts
+/**
+* Lookback window for the missing_artifact_evidence cross-session
+* diagnostic (issue #144). Wide enough to catch a subagent dispatch
+* that ran for a few minutes before the agent hit the gate.
+*/
+const DIAGNOSTIC_WINDOW_MINUTES = 10;
 const phaseLiteral = Schema.Literals([
 	"spike",
 	"red",
@@ -82,6 +88,7 @@ const tddPhaseTransitionRequest = publicProcedure.input(Schema.toStandardSchemaV
 		const currentOpt = yield* reader.getCurrentTddPhase(input.tddTaskId);
 		const currentPhase = Option.isSome(currentOpt) ? currentOpt.value.phase : "spike";
 		const phaseStartedAt = Option.isSome(currentOpt) ? currentOpt.value.startedAt : (/* @__PURE__ */ new Date()).toISOString();
+		const currentPhaseId = Option.isSome(currentOpt) ? currentOpt.value.id : null;
 		const goalOpt = yield* reader.getGoalById(input.goalId);
 		if (Option.isNone(goalOpt)) return {
 			accepted: false,
@@ -170,16 +177,24 @@ const tddPhaseTransitionRequest = publicProcedure.input(Schema.toStandardSchemaV
 				...scopeLookupByBehavior && { behaviorId: input.behaviorId },
 				limit: 1
 			});
-			if (recent.length === 0) return {
-				accepted: false,
-				phase: currentPhase,
-				denialReason: "missing_artifact_evidence",
-				remediation: {
-					suggestedTool: "run_tests",
-					suggestedArgs: {},
-					humanHint: `No '${kindToLookUp}' artifact has been recorded for tdd_task ${input.tddTaskId}. Artifacts are recorded by hooks observing your tool calls (Decision D7) — run the test (e.g. via run_tests) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and the next call to this tool will pick it up automatically.`
-				}
-			};
+			if (recent.length === 0) {
+				const sinceIso = (/* @__PURE__ */ new Date(Date.now() - DIAGNOSTIC_WINDOW_MINUTES * 6e4)).toISOString();
+				const crossSessionCount = yield* reader.countRecentArtifactsInOtherSessionsOfConversation({
+					tddTaskId: input.tddTaskId,
+					sinceIso
+				});
+				const baseHint = `No '${kindToLookUp}' artifact has been recorded for tdd_task ${input.tddTaskId}. Artifacts are recorded by hooks observing your tool calls (Decision D7) — run the test (e.g. via run_tests) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and the next call to this tool will pick it up automatically.`;
+				return {
+					accepted: false,
+					phase: currentPhase,
+					denialReason: "missing_artifact_evidence",
+					remediation: {
+						suggestedTool: "run_tests",
+						suggestedArgs: {},
+						humanHint: crossSessionCount > 0 ? `${baseHint} ${crossSessionCount} artifact${crossSessionCount === 1 ? " was" : "s were"} recorded under a different session of this conversation in the last ${DIAGNOSTIC_WINDOW_MINUTES} minutes — the subagent's hooks may be attributing to a detached session; set VITEST_AGENT_TDD_TASK_ID=${input.tddTaskId} in the subagent's environment or dispatch it as an unnamed background subagent.` : baseHint
+					}
+				};
+			}
 			resolvedArtifactId = recent[0].id;
 		}
 		let citedArtifact;
@@ -205,11 +220,13 @@ const tddPhaseTransitionRequest = publicProcedure.input(Schema.toStandardSchemaV
 			test_case_authored_in_session: false,
 			test_run_id: null,
 			test_first_failure_run_id: null,
-			behavior_id: null
+			behavior_id: null,
+			suite: "vitest"
 		};
 		const result = validatePhaseTransition({
 			tdd_task_id: input.tddTaskId,
 			current_phase: currentPhase,
+			current_phase_id: currentPhaseId,
 			phase_started_at: phaseStartedAt,
 			now: (/* @__PURE__ */ new Date()).toISOString(),
 			requested_phase: input.requestedPhase,

package/tools/tdd-task.js

@@ -194,6 +194,18 @@ const TddTaskInput = Schema.Union([
 	GetVariant,
 	ResumeVariant
 ]);
+/**
+* Single source of truth for the `tdd_task` tool's `action`
+* discriminant, consumed by `server.ts`'s served `z.enum(...)` so the
+* MCP-SDK-side registration cannot drift from this tRPC input union
+* (issue #335).
+*/
+const TDD_TASK_ACTIONS = [
+	"start",
+	"end",
+	"get",
+	"resume"
+];
 const tddTask = idempotentProcedure.input(Schema.toStandardSchemaV1(TddTaskInput)).mutation(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		start: (variant) => Effect.gen(function* () {
@@ -294,4 +306,4 @@ const tddTask = idempotentProcedure.input(Schema.toStandardSchemaV1(TddTaskInput
 });
 
 //#endregion
-export { TddTaskAsMarkdown, TddTaskResult, formatTddTaskMarkdown, tddTask };
+export { TDD_TASK_ACTIONS, TddTaskAsMarkdown, TddTaskResult, formatTddTaskMarkdown, tddTask };

package/tools/test.js

@@ -220,6 +220,17 @@ const TestInput = Schema.Union([
 	ForFileVariant,
 	ForTagVariant
 ]);
+/**
+* Single source of truth for the `test` tool's `action` discriminant,
+* consumed by `server.ts`'s served `z.enum(...)` so the MCP-SDK-side
+* registration cannot drift from this tRPC input union (issue #335).
+*/
+const TEST_ACTIONS = [
+	"list",
+	"get",
+	"for_file",
+	"for_tag"
+];
 const test = publicProcedure.input(Schema.toStandardSchemaV1(TestInput)).query(async ({ ctx, input }) => {
 	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
 		list: (variant) => Effect.gen(function* () {
@@ -310,4 +321,4 @@ const test = publicProcedure.input(Schema.toStandardSchemaV1(TestInput)).query(a
 });
 
 //#endregion
-export { TestAsMarkdown, TestResult, formatTestMarkdown, test };
+export { TEST_ACTIONS, TestAsMarkdown, TestResult, formatTestMarkdown, test };