@vitest-agent/mcp 5.4.0 → 6.0.0

package/index.js

@@ -1,5 +1,4 @@
 import { RenderText } from "./annotations.js";
-import { withIdempotency } from "./idempotency.js";
 import { McpSession, createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv } from "./session.js";
 import { PromptsLayer } from "./prompts/layer.js";
 import { AcceptanceMetricsResult, acceptanceMetricsTool, handleAcceptanceMetrics } from "./tools/acceptance-metrics.js";
@@ -37,4 +36,4 @@ import { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
 import { CURRENT_MCP_VERSION } from "./version.js";
 import { ToolRefusal } from "@effected/mcp";
 
-export { AcceptanceMetricsResult, CURRENT_MCP_VERSION, CacheHealthResult, CommitChangesInput, CommitChangesResult, ConfigureInput, ConfigureResult, FailureSignatureGetInput, FailureSignatureGetResult, FileCoverageInput, FileCoverageResult, HelpResult, HypothesisInput, HypothesisResult, InventoryInput, InventoryResult, Kit, McpSession, NoteParams, NoteResult, PhaseTransitionInput, PhaseTransitionResult, PingResult, PromptsLayer, RegisterAgentInput, RegisterAgentResult, RenderText, RunTestsInput, RunTestsResult, SERVER_INSTRUCTIONS, ServerLayer, SettingsListResult, TddArtifactListInput, TddArtifactListResult, TddBehaviorInput, TddBehaviorResult, TddGoalInput, TddGoalResult, TddProgressPushInput, TddProgressPushResult, TddTaskInput, TddTaskResult, TestCoverageInput, TestCoverageResult, TestErrorsInput, TestErrorsResult, TestHistoryInput, TestHistoryResult, TestInput, TestOverviewInput, TestOverviewResult, TestResult, TestStatusInput, TestStatusResult, TestTrendsInput, TestTrendsResult, ToolRefusal, ToolsLayer, TriageBriefInput, TriageBriefResult, TurnSearchInput, TurnSearchResult, WrapupPromptInput, WrapupPromptResult, acceptanceMetricsTool, cacheHealthTool, commitChangesTool, configureTool, createCurrentSessionIdRef, createSessionContextRef, failureSignatureGetTool, fileCoverageTool, handleAcceptanceMetrics, handleCacheHealth, handleCommitChanges, handleConfigure, handleFailureSignatureGet, handleFileCoverage, handleHelp, handleHypothesis, handleInventory, handleNote, handlePhaseTransitionRequest, handlePing, handleRegisterAgent, handleRunTests, handleSettingsList, handleTddArtifactList, handleTddBehavior, handleTddGoal, handleTddProgressPush, handleTddTask, handleTest, handleTestCoverage, handleTestErrors, handleTestHistory, handleTestOverview, handleTestStatus, handleTestTrends, handleTriageBrief, handleTurnSearch, handleWrapupPrompt, helpTool, hypothesisTool, inventoryTool, noteTool, pingTool, registerAgentTool, runTestsTool, sessionContextFromEnv, settingsListTool, tddArtifactListTool, tddBehaviorTool, tddGoalTool, tddPhaseTransitionRequestTool, tddProgressPushTool, tddTaskTool, testCoverageTool, testErrorsTool, testHistoryTool, testOverviewTool, testStatusTool, testTool, testTrendsTool, toolHandlers, triageBriefTool, turnSearchTool, withIdempotency, wrapupPromptTool };
+export { AcceptanceMetricsResult, CURRENT_MCP_VERSION, CacheHealthResult, CommitChangesInput, CommitChangesResult, ConfigureInput, ConfigureResult, FailureSignatureGetInput, FailureSignatureGetResult, FileCoverageInput, FileCoverageResult, HelpResult, HypothesisInput, HypothesisResult, InventoryInput, InventoryResult, Kit, McpSession, NoteParams, NoteResult, PhaseTransitionInput, PhaseTransitionResult, PingResult, PromptsLayer, RegisterAgentInput, RegisterAgentResult, RenderText, RunTestsInput, RunTestsResult, SERVER_INSTRUCTIONS, ServerLayer, SettingsListResult, TddArtifactListInput, TddArtifactListResult, TddBehaviorInput, TddBehaviorResult, TddGoalInput, TddGoalResult, TddProgressPushInput, TddProgressPushResult, TddTaskInput, TddTaskResult, TestCoverageInput, TestCoverageResult, TestErrorsInput, TestErrorsResult, TestHistoryInput, TestHistoryResult, TestInput, TestOverviewInput, TestOverviewResult, TestResult, TestStatusInput, TestStatusResult, TestTrendsInput, TestTrendsResult, ToolRefusal, ToolsLayer, TriageBriefInput, TriageBriefResult, TurnSearchInput, TurnSearchResult, WrapupPromptInput, WrapupPromptResult, acceptanceMetricsTool, cacheHealthTool, commitChangesTool, configureTool, createCurrentSessionIdRef, createSessionContextRef, failureSignatureGetTool, fileCoverageTool, handleAcceptanceMetrics, handleCacheHealth, handleCommitChanges, handleConfigure, handleFailureSignatureGet, handleFileCoverage, handleHelp, handleHypothesis, handleInventory, handleNote, handlePhaseTransitionRequest, handlePing, handleRegisterAgent, handleRunTests, handleSettingsList, handleTddArtifactList, handleTddBehavior, handleTddGoal, handleTddProgressPush, handleTddTask, handleTest, handleTestCoverage, handleTestErrors, handleTestHistory, handleTestOverview, handleTestStatus, handleTestTrends, handleTriageBrief, handleTurnSearch, handleWrapupPrompt, helpTool, hypothesisTool, inventoryTool, noteTool, pingTool, registerAgentTool, runTestsTool, sessionContextFromEnv, settingsListTool, tddArtifactListTool, tddBehaviorTool, tddGoalTool, tddPhaseTransitionRequestTool, tddProgressPushTool, tddTaskTool, testCoverageTool, testErrorsTool, testHistoryTool, testOverviewTool, testStatusTool, testTool, testTrendsTool, toolHandlers, triageBriefTool, turnSearchTool, wrapupPromptTool };

package/main.js

@@ -2,45 +2,6 @@ import { McpGuard } from "@effected/mcp/guard";
 
 // src/main.ts
 /**
-* Optional first positional argument: an initial Claude Code chat UUID (the
-* host's `chatId`) to seed the MCP server's session association. Claude Code
-* passes unknown `${...}` variables through as literal text in some surfaces,
-* so an unsubstituted placeholder is treated as absent rather than seeding
-* garbage.
-*
-* @param argv - the raw `process.argv`
-* @param isUnsubstituted - `LaunchContext.isUnsubstituted`, passed in because
-*   this module may not statically import the server graph
-* @returns the trimmed seed, or `null` when absent, empty, or a placeholder
-*/
-const resolveInitialSessionId = (argv, isUnsubstituted) => {
-	const trimmed = argv[2]?.trim();
-	if (trimmed === void 0 || trimmed.length === 0 || isUnsubstituted(trimmed)) return null;
-	return trimmed;
-};
-const INJECT_AT = ["load", "connected"];
-const INJECT_KIND = ["uncaughtException", "unhandledRejection"];
-/**
-* Parse the test-only `VITEST_AGENT_MCP_TEST_INJECT_CRASH` value into the
-* guard's `injectCrash`. Accepts `<at>:<kind>` (`at` is `load` or
-* `connected`, `kind` is `uncaughtException` or `unhandledRejection`), and a
-* bare `<kind>` as the legacy spelling of `connected:<kind>`. Anything else,
-* or no value, is `undefined`: no injection.
-*/
-const parseInjectCrash = (value) => {
-	if (value === void 0) return void 0;
-	const [first, second, ...rest] = value.split(":");
-	if (rest.length > 0) return void 0;
-	const at = second === void 0 ? "connected" : first;
-	const kind = second === void 0 ? first : second;
-	const validAt = INJECT_AT.find((candidate) => candidate === at);
-	const validKind = INJECT_KIND.find((candidate) => candidate === kind);
-	return validAt === void 0 || validKind === void 0 ? void 0 : {
-		at: validAt,
-		kind: validKind
-	};
-};
-/**
 * Run the vitest-agent MCP server over stdio. Owns the process: registers
 * the crash guards through `McpGuard.run`, resolves the project directory and `data.db` path,
 * recovers the host session context, and launches the server layer under
@@ -59,7 +20,7 @@ const main = (options = {}) => McpGuard.run({
 		onUncaught: "exitBeforeConnect",
 		onRejection: "log"
 	},
-	injectCrash: parseInjectCrash(process.env.VITEST_AGENT_MCP_TEST_INJECT_CRASH),
+	injectCrash: McpGuard.parseInjectCrash(process.env.VITEST_AGENT_MCP_TEST_INJECT_CRASH),
 	load: async () => {
 		const { safeFormatFatalError } = await import("./utils/safe-format-fatal-error.js");
 		const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
@@ -67,22 +28,25 @@ const main = (options = {}) => McpGuard.run({
 		const NodeStdio = await import("@effect/platform-node/NodeStdio");
 		const { Effect, Layer, Option } = await import("effect");
 		const { CurrentDistribution, LaunchContext } = await import("@effected/engine");
+		const { StdioCapture } = await import("@effected/mcp/node");
 		const { PathResolutionLive, PlatformLive, recoverSessionContextFromSessionEnv, resolveDataPath, resolveLogFile, resolveLogLevel, resolveProjectDir } = await import("@vitest-agent/engine");
 		const { McpSession, sessionContextFromEnv } = await import("./session.js");
 		const { ServerLayer } = await import("./server.js");
+		const { RunTestsStdio } = await import("./tools/run-tests.js");
 		const { CURRENT_MCP_VERSION } = await import("./version.js");
 		const env = process.env;
 		const projectDir = resolveProjectDir({
 			env,
 			cwd: process.cwd()
 		});
-		const initialSessionId = resolveInitialSessionId(process.argv, LaunchContext.isUnsubstituted);
+		const initialSessionId = LaunchContext.usable(process.argv[2]);
+		const stdioCapture = StdioCapture.install(process);
 		const dbPath = await Effect.runPromise(resolveDataPath(projectDir).pipe(Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeServices.layer)));
-		const recovered = sessionContextFromEnv(env);
 		const homeDir = env.HOME ?? env.USERPROFILE ?? "";
+		const recovered = sessionContextFromEnv(env);
 		const Session = McpSession.layer({
 			cwd: projectDir,
-			initialSessionId: initialSessionId ?? recovered?.chatId ?? null,
+			initialSessionId: Option.getOrNull(initialSessionId) ?? recovered?.chatId ?? null,
 			initialContext: recovered,
 			recover: () => recoverSessionContextFromSessionEnv({
 				projectDir,
@@ -95,7 +59,7 @@ const main = (options = {}) => McpGuard.run({
 				env,
 				logLevel: resolveLogLevel(env),
 				logFile: resolveLogFile(env)
-			})), Layer.provide(Layer.succeed(CurrentDistribution, Option.fromNullishOr(options.distribution))), Layer.provide(NodeStdio.layer)),
+			})), Layer.provide(Layer.succeed(CurrentDistribution, Option.fromNullishOr(options.distribution))), Layer.provide(Layer.succeed(RunTestsStdio, stdioCapture)), Layer.provide(NodeStdio.layer)),
 			runMain: NodeRuntime.runMain,
 			format: safeFormatFatalError
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "5.4.0",
+	"version": "6.0.0",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 30 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [
@@ -44,13 +44,14 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "^4.0.6",
-		"@effect/sql-sqlite-node": "^4.0.6",
-		"@effected/engine": "^0.8.0",
-		"@effected/git": "^0.25.1",
-		"@effected/mcp": "^0.9.0",
-		"@effected/walker": "^0.20.1",
-		"@vitest-agent/engine": "2.1.0",
-		"@vitest-agent/sdk": "8.0.0",
+		"@effected/commands": "^0.17.0",
+		"@effected/engine": "^0.9.0",
+		"@effected/git": "^0.26.0",
+		"@effected/glob": "^0.15.0",
+		"@effected/mcp": "^0.10.0",
+		"@effected/walker": "^0.21.0",
+		"@vitest-agent/engine": "3.0.0",
+		"@vitest-agent/sdk": "9.0.0",
 		"effect": "^4.0.6"
 	},
 	"peerDependencies": {

package/replay.js

@@ -0,0 +1,93 @@
+import { ToolReplay } from "@effected/mcp";
+import { Effect, Option } from "effect";
+import { DataReader, DataStore } from "@vitest-agent/engine";
+
+// src/replay.ts
+/**
+* `hypothesis`: `validate` keys on `validate:<id>:<outcome>`. `record` is
+* deliberately NOT idempotent: a hypothesis is an append-only observation
+* whose binding session is resolved server-side (and so is absent from the
+* input), leaving no safe per-call discriminator — content-only keying would
+* collide across sessions and replay a stale row under the wrong one. A
+* genuine retry creating a duplicate hypothesis row is harmless by comparison.
+*
+* @internal
+*/
+const hypothesisReplayKey = (input) => input.action === "validate" ? Option.some(`validate:${input.id}:${input.outcome}`) : Option.none();
+/**
+* `tdd_task`: `start` keys on whichever id form is present (`sid:` for
+* `sessionId`, `chat:` for `chatId`, so a chat id can never collide with an
+* integer id) plus the `runId` when supplied, else the goal text — a new
+* `runId` lets the same goal be retried in one chat; `end` keys on
+* `end:<tddTaskId>:<outcome>`.
+*
+* @internal
+*/
+const tddTaskReplayKey = (input) => {
+	if (input.action === "start") {
+		const id = input.sessionId !== void 0 ? `sid:${input.sessionId}` : input.chatId !== void 0 ? `chat:${input.chatId}` : void 0;
+		if (id === void 0) return Option.none();
+		return Option.some(input.runId !== void 0 ? `start:${id}:run:${input.runId}` : `start:${id}:${input.goal}`);
+	}
+	if (input.action === "end") return Option.some(`end:${input.tddTaskId}:${input.outcome}`);
+	return Option.none();
+};
+/**
+* `tdd_goal`: `create` keys on `create:<tddTaskId>:<goal>`.
+*
+* @internal
+*/
+const tddGoalReplayKey = (input) => input.action === "create" ? Option.some(`create:${input.tddTaskId}:${input.goal}`) : Option.none();
+/**
+* `tdd_behavior`: `create` keys on `create:<goalId>:<behavior>`.
+*
+* @internal
+*/
+const tddBehaviorReplayKey = (input) => input.action === "create" ? Option.some(`create:${input.goalId}:${input.behavior}`) : Option.none();
+/**
+* Splits a `ToolReplay.storeKey` (`<tool>:<key>`) back into the table's
+* `(procedure_path, key)` pair, so rows written before `ToolReplay` keep
+* replaying under the same coordinates.
+*/
+const splitStoreKey = (storeKey) => {
+	const at = storeKey.indexOf(":");
+	return [storeKey.slice(0, at), storeKey.slice(at + 1)];
+};
+/**
+* A `ToolReplayStore` over `mcp_idempotent_responses`. A store fault fails
+* the `get` / `set`, which `ToolReplay` treats as a miss or a skipped write.
+*
+* @internal
+*/
+const makeReplayStore = Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	return {
+		get: (storeKey) => {
+			const [tool, key] = splitStoreKey(storeKey);
+			return reader.findIdempotentResponse(tool, key).pipe(Effect.map(Option.getOrUndefined));
+		},
+		set: (storeKey, value) => {
+			const [tool, key] = splitStoreKey(storeKey);
+			return store.recordIdempotentResponse({
+				procedurePath: tool,
+				key,
+				resultJson: value,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	};
+});
+/**
+* `ToolReplay.wrap` for one write tool, with the replay store built from the
+* handler's own `DataReader` / `DataStore`, so the wrapped handler requires
+* exactly what the bare one did.
+*
+* @internal
+*/
+const replayed = (options) => (handler) => (params) => Effect.flatMap(makeReplayStore, (store) => ToolReplay.wrap({
+	...options,
+	store
+})(handler)(params));
+
+export { hypothesisReplayKey, makeReplayStore, replayed, tddBehaviorReplayKey, tddGoalReplayKey, tddTaskReplayKey };

package/server.js

@@ -20,7 +20,7 @@ const SERVER_INSTRUCTIONS = [
 	"Call the help tool first for the full tool reference; triage_brief orients on the current landscape; run_tests executes Vitest and persists the run so every query tool reads it back.",
 	"Every input is strict at every object level: an unknown key is rejected with a message naming the unrecognized key(s) and the accepted params, so fix the call rather than retrying it.",
 	"Every successful result carries the typed object in structuredContent; read structuredContent for every field.",
-	"An expected domain error is NOT an isError result: it is a normal result whose structuredContent has ok: false and an error object. tdd_goal and tdd_behavior put _tag, the failing ids and a remediation naming the tool to call next in that object; register_agent puts a code and a message in it, plus existingAgentId or expectedPrefix when the code calls for one.",
+	"An expected domain error is NOT an isError result: it is a normal result whose structuredContent has ok: false and an error object. tdd_goal and tdd_behavior put _tag, a one-sentence message, the failing ids and a remediation naming the tool to call next in that object; register_agent puts a code and a message in it, plus existingAgentId or expectedPrefix when the code calls for one.",
 	"An isError result means the call itself failed and carries no structuredContent. Its text either names what to fix (invalid params, or a refused call such as an unknown id, often ending 'Try <tool>.' with the tool to call next) or is a generic internal-error message (the server logged the detail). Fix the call, or report the internal failure rather than retrying it unchanged."
 ].join("\n");
 /**

package/toolkit.js

@@ -1,4 +1,4 @@
-import { withIdempotency } from "./idempotency.js";
+import { hypothesisReplayKey, replayed, tddBehaviorReplayKey, tddGoalReplayKey, tddTaskReplayKey } from "./replay.js";
 import { acceptanceMetricsTool, handleAcceptanceMetrics } from "./tools/acceptance-metrics.js";
 import { cacheHealthTool, handleCacheHealth } from "./tools/cache-health.js";
 import { commitChangesTool, handleCommitChanges } from "./tools/commit-changes.js";
@@ -9,7 +9,7 @@ import { failureSignatureGetTool, handleFailureSignatureGet } from "./tools/fail
 import { fileCoverageTool, handleFileCoverage } from "./tools/file-coverage.js";
 import { handleHelp, helpTool } from "./tools/help.js";
 import { handleTestHistory, testHistoryTool } from "./tools/history.js";
-import { handleHypothesis, hypothesisTool } from "./tools/hypothesis.js";
+import { HypothesisResult, handleHypothesis, hypothesisTool } from "./tools/hypothesis.js";
 import { handleInventory, inventoryTool } from "./tools/inventory.js";
 import { handleNote, noteTool } from "./tools/note.js";
 import { handleTestOverview, testOverviewTool } from "./tools/overview.js";
@@ -19,11 +19,11 @@ import { handleRunTests, runTestsTool } from "./tools/run-tests.js";
 import { handleSettingsList, settingsListTool } from "./tools/settings-list.js";
 import { handleTestStatus, testStatusTool } from "./tools/status.js";
 import { handleTddArtifactList, tddArtifactListTool } from "./tools/tdd-artifact.js";
-import { handleTddBehavior, tddBehaviorTool } from "./tools/tdd-behavior.js";
-import { handleTddGoal, tddGoalTool } from "./tools/tdd-goal.js";
+import { TddBehaviorResult, handleTddBehavior, tddBehaviorTool } from "./tools/tdd-behavior.js";
+import { TddGoalResult, handleTddGoal, tddGoalTool } from "./tools/tdd-goal.js";
 import { handlePhaseTransitionRequest, tddPhaseTransitionRequestTool } from "./tools/tdd-phase-transition-request.js";
 import { handleTddProgressPush, tddProgressPushTool } from "./tools/tdd-progress-push.js";
-import { handleTddTask, tddTaskTool } from "./tools/tdd-task.js";
+import { TddTaskResult, handleTddTask, tddTaskTool } from "./tools/tdd-task.js";
 import { handleTest, testTool } from "./tools/test.js";
 import { handleTestTrends, testTrendsTool } from "./tools/trends.js";
 import { handleTriageBrief, triageBriefTool } from "./tools/triage-brief.js";
@@ -70,11 +70,27 @@ const toolHandlers = {
 	test: McpToolkit.unionHandler(testTool, handleTest),
 	register_agent: handleRegisterAgent,
 	note: McpToolkit.unionHandler(noteTool, handleNote),
-	hypothesis: McpToolkit.unionHandler(hypothesisTool, withIdempotency("hypothesis", handleHypothesis)),
-	tdd_task: McpToolkit.unionHandler(tddTaskTool, withIdempotency("tdd_task", handleTddTask)),
+	hypothesis: McpToolkit.unionHandler(hypothesisTool, replayed({
+		tool: "hypothesis",
+		success: HypothesisResult,
+		key: hypothesisReplayKey
+	})(handleHypothesis)),
+	tdd_task: McpToolkit.unionHandler(tddTaskTool, replayed({
+		tool: "tdd_task",
+		success: TddTaskResult,
+		key: tddTaskReplayKey
+	})(handleTddTask)),
 	tdd_phase_transition_request: handlePhaseTransitionRequest,
-	tdd_goal: McpToolkit.unionHandler(tddGoalTool, withIdempotency("tdd_goal", handleTddGoal)),
-	tdd_behavior: McpToolkit.unionHandler(tddBehaviorTool, withIdempotency("tdd_behavior", handleTddBehavior)),
+	tdd_goal: McpToolkit.unionHandler(tddGoalTool, replayed({
+		tool: "tdd_goal",
+		success: TddGoalResult,
+		key: tddGoalReplayKey
+	})(handleTddGoal)),
+	tdd_behavior: McpToolkit.unionHandler(tddBehaviorTool, replayed({
+		tool: "tdd_behavior",
+		success: TddBehaviorResult,
+		key: tddBehaviorReplayKey
+	})(handleTddBehavior)),
 	tdd_artifact_list: handleTddArtifactList,
 	tdd_progress_push: handleTddProgressPush,
 	run_tests: handleRunTests

package/tools/_tdd-error-envelope.js

@@ -1,88 +1,137 @@
-import { Effect } from "effect";
-import { BehaviorNotFoundError, GoalNotFoundError, IllegalStatusTransitionError, TddTaskAlreadyEndedError, TddTaskNotFoundError } from "@vitest-agent/sdk";
+import { ToolOutcome } from "@effected/mcp";
+import { Schema } from "effect";
 
 // src/tools/_tdd-error-envelope.ts
+const TddTaskEndOutcome = Schema.Literals([
+	"succeeded",
+	"blocked",
+	"abandoned"
+]);
+const StatusEntity = Schema.Literals([
+	"goal",
+	"behavior",
+	"task"
+]);
+/**
+* The five envelope errors, in the order they are served. Each is a named
+* `$defs` entry in the served `outputSchema`, open to extra keys as the
+* envelope always was.
+*/
+const TddEnvelopeErrors = [
+	ToolOutcome.error("GoalNotFoundError", {
+		id: Schema.Number,
+		reason: Schema.String
+	}).annotate({
+		identifier: "GoalNotFoundError",
+		description: "No goal with this id. `remediation` names the tool that lists goals."
+	}),
+	ToolOutcome.error("BehaviorNotFoundError", {
+		id: Schema.Number,
+		reason: Schema.String
+	}).annotate({
+		identifier: "BehaviorNotFoundError",
+		description: "No behavior with this id. `remediation` names the tool that lists behaviors."
+	}),
+	ToolOutcome.error("TddTaskNotFoundError", {
+		id: Schema.Number,
+		reason: Schema.String
+	}).annotate({
+		identifier: "TddTaskNotFoundError",
+		description: "No TDD task with this id. `remediation` names the tool that opens one."
+	}),
+	ToolOutcome.error("TddTaskAlreadyEndedError", {
+		id: Schema.Number,
+		endedAt: Schema.String,
+		outcome: TddTaskEndOutcome
+	}).annotate({
+		identifier: "TddTaskAlreadyEndedError",
+		description: "The TDD task has already ended, so nothing more can be added to it."
+	}),
+	ToolOutcome.error("IllegalStatusTransitionError", {
+		entity: StatusEntity,
+		id: Schema.Number,
+		from: Schema.String,
+		to: Schema.String,
+		reason: Schema.String
+	}).annotate({
+		identifier: "IllegalStatusTransitionError",
+		description: "The requested status change is not allowed; `remediation` suggests abandoning instead."
+	})
+];
+/**
+* A goal / behavior tool's success schema: its success members, or the
+* `{ ok: false, error }` envelope carrying one of the five TDD errors.
+* `identifier` names the envelope in the served `$defs`; each tool keeps
+* the name it served before the envelope moved onto `ToolOutcome`.
+*
+* @internal
+*/
+const tddEnvelope = (success, identifier) => ToolOutcome.envelope(success, TddEnvelopeErrors, {
+	identifier,
+	description: "Returned instead of a result when a known TDD error is caught: `ok` is `false` and `error` names it."
+});
+/** @internal */
 const goalNotFound = (e) => ({
-	ok: false,
-	error: {
-		_tag: e._tag,
-		id: e.id,
-		reason: e.reason,
-		remediation: {
-			suggestedTool: "tdd_goal",
-			suggestedArgs: { action: "list" },
-			hint: `No tdd_session_goals row with id=${e.id}. Call tdd_goal({ action: "list", tddTaskId }) to find the correct goal id.`
-		}
+	id: e.id,
+	reason: e.reason,
+	message: `No goal with id ${e.id}.`,
+	remediation: {
+		suggestedTool: "tdd_goal",
+		suggestedArgs: { action: "list" },
+		hint: `No tdd_session_goals row with id=${e.id}. Call tdd_goal({ action: "list", tddTaskId }) to find the correct goal id.`
 	}
 });
+/** @internal */
 const behaviorNotFound = (e) => ({
-	ok: false,
-	error: {
-		_tag: e._tag,
-		id: e.id,
-		reason: e.reason,
-		remediation: {
-			suggestedTool: "tdd_behavior",
-			suggestedArgs: { action: "list_by_goal" },
-			hint: `No tdd_session_behaviors row with id=${e.id}. Call tdd_behavior({ action: "list_by_goal", goalId }) or tdd_behavior({ action: "list_by_tdd_task", tddTaskId }) to find the correct behavior id.`
-		}
+	id: e.id,
+	reason: e.reason,
+	message: `No behavior with id ${e.id}.`,
+	remediation: {
+		suggestedTool: "tdd_behavior",
+		suggestedArgs: { action: "list_by_goal" },
+		hint: `No tdd_session_behaviors row with id=${e.id}. Call tdd_behavior({ action: "list_by_goal", goalId }) or tdd_behavior({ action: "list_by_tdd_task", tddTaskId }) to find the correct behavior id.`
 	}
 });
+/** @internal */
 const tddTaskNotFound = (e) => ({
-	ok: false,
-	error: {
-		_tag: e._tag,
-		id: e.id,
-		reason: e.reason,
-		remediation: {
-			suggestedTool: "tdd_task",
-			suggestedArgs: { action: "start" },
-			hint: `No tdd_tasks row with id=${e.id}. Call tdd_task({ action: "start" }) to open a TDD task before creating goals or behaviors.`
-		}
+	id: e.id,
+	reason: e.reason,
+	message: `No TDD task with id ${e.id}.`,
+	remediation: {
+		suggestedTool: "tdd_task",
+		suggestedArgs: { action: "start" },
+		hint: `No tdd_tasks row with id=${e.id}. Call tdd_task({ action: "start" }) to open a TDD task before creating goals or behaviors.`
 	}
 });
+/** @internal */
 const tddTaskAlreadyEnded = (e) => ({
-	ok: false,
-	error: {
-		_tag: e._tag,
-		id: e.id,
-		endedAt: e.endedAt,
-		outcome: e.outcome,
-		remediation: {
-			suggestedTool: "tdd_task",
-			suggestedArgs: { action: "start" },
-			hint: `tdd_tasks row id=${e.id} is already ended (outcome=${e.outcome}). Open a new TDD task if you need to add more goals or behaviors.`
-		}
+	id: e.id,
+	endedAt: e.endedAt,
+	outcome: e.outcome,
+	message: `TDD task ${e.id} has already ended (${e.outcome}).`,
+	remediation: {
+		suggestedTool: "tdd_task",
+		suggestedArgs: { action: "start" },
+		hint: `tdd_tasks row id=${e.id} is already ended (outcome=${e.outcome}). Open a new TDD task if you need to add more goals or behaviors.`
 	}
 });
+/** @internal */
 const illegalStatusTransition = (e) => ({
-	ok: false,
-	error: {
-		_tag: e._tag,
-		entity: e.entity,
-		id: e.id,
-		from: e.from,
-		to: e.to,
-		reason: e.reason,
-		remediation: {
-			suggestedTool: e.entity === "goal" ? "tdd_goal" : "tdd_behavior",
-			suggestedArgs: {
-				action: "update",
-				id: e.id,
-				status: "abandoned"
-			},
-			hint: `Cannot transition ${e.entity} id=${e.id} from ${e.from} to ${e.to}. Use status:'abandoned' to drop work; do not delete unless the entity was created by mistake.`
-		}
+	entity: e.entity,
+	id: e.id,
+	from: e.from,
+	to: e.to,
+	reason: e.reason,
+	message: `Cannot move ${e.entity} ${e.id} from ${e.from} to ${e.to}.`,
+	remediation: {
+		suggestedTool: e.entity === "goal" ? "tdd_goal" : "tdd_behavior",
+		suggestedArgs: {
+			action: "update",
+			id: e.id,
+			status: "abandoned"
+		},
+		hint: `Cannot transition ${e.entity} id=${e.id} from ${e.from} to ${e.to}. Use status:'abandoned' to drop work; do not delete unless the entity was created by mistake.`
 	}
 });
-const isKnownTddError = (e) => e instanceof GoalNotFoundError || e instanceof BehaviorNotFoundError || e instanceof TddTaskNotFoundError || e instanceof TddTaskAlreadyEndedError || e instanceof IllegalStatusTransitionError;
-const tddErrorToEnvelope = (e) => {
-	if (e instanceof GoalNotFoundError) return goalNotFound(e);
-	if (e instanceof BehaviorNotFoundError) return behaviorNotFound(e);
-	if (e instanceof TddTaskNotFoundError) return tddTaskNotFound(e);
-	if (e instanceof TddTaskAlreadyEndedError) return tddTaskAlreadyEnded(e);
-	return illegalStatusTransition(e);
-};
-const catchTddErrorsAsEnvelope = (effect) => effect.pipe(Effect.catch((e) => isKnownTddError(e) ? Effect.succeed(tddErrorToEnvelope(e)) : Effect.fail(e)));
 
-export { catchTddErrorsAsEnvelope };
+export { behaviorNotFound, goalNotFound, illegalStatusTransition, tddEnvelope, tddTaskAlreadyEnded, tddTaskNotFound };

package/tools/acceptance-metrics.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/acceptance-metrics.ts
 const totalAnnotation = { description: "Sample size — number of observations the metric ratio is computed over." };

package/tools/cache-health.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 import { CacheManifest } from "@vitest-agent/sdk";
 
 // src/tools/cache-health.ts

package/tools/commit-changes.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/commit-changes.ts
 const FileRow = Schema.Struct({

package/tools/configure.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/configure.ts
 const SettingsRowSchema = Schema.Struct({

package/tools/coverage.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 import { CoverageReport } from "@vitest-agent/sdk";
 
 // src/tools/coverage.ts

package/tools/errors.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/errors.ts
 /** One annotation attached to a failing test, surfaced with its error. */

package/tools/failure-signature-get.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/failure-signature-get.ts
 const RecentError = Schema.Struct({

package/tools/file-coverage.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 import { CoverageTotals, FileCoverageReport } from "@vitest-agent/sdk";
 
 // src/tools/file-coverage.ts

package/tools/history.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 import { HistoryRecord, StrayOutput } from "@vitest-agent/sdk";
 
 // src/tools/history.ts

package/tools/hypothesis.js

@@ -2,8 +2,8 @@ import { McpSession } from "../session.js";
 import { IdempotentReplayMarker } from "../utils/replay-marker.js";
 import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
-import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader, DataStore } from "@vitest-agent/engine";
 
 // src/tools/hypothesis.ts
 const HypothesisRowSchema = Schema.Struct({

package/tools/inventory.js

@@ -1,8 +1,8 @@
 import { collectProjectRows, resolveProjectTargets } from "./_project-groups.js";
 import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/inventory.ts
 const ProjectRunSummary = Schema.Struct({

package/tools/note.js

@@ -1,7 +1,7 @@
 import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
-import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader, DataStore } from "@vitest-agent/engine";
 
 // src/tools/note.ts
 const NoteScope = Schema.Literals([

package/tools/overview.js

@@ -1,7 +1,7 @@
 import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
-import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/ai";
+import { DataReader } from "@vitest-agent/engine";
 
 // src/tools/overview.ts
 const ProjectRunSummary = Schema.Struct({