@vitest-agent/engine 0.1.0

package/migrations/0002_test_artifacts.js

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+
+//#region src/migrations/0002_test_artifacts.ts
+/** @internal */
+const migration = Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	yield* sql`DROP INDEX IF EXISTS idx_test_annotations_case`;
+	yield* sql`DROP INDEX IF EXISTS idx_test_annotations_type`;
+	yield* sql`DROP TABLE IF EXISTS test_annotations`;
+	yield* sql`
+		CREATE TABLE test_annotations (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			test_case_id INTEGER NOT NULL REFERENCES test_cases(id) ON DELETE CASCADE,
+			type TEXT NOT NULL,
+			message TEXT NOT NULL,
+			location_file_id INTEGER REFERENCES files(id),
+			location_line INTEGER,
+			location_column INTEGER
+		)
+	`;
+	yield* sql`CREATE INDEX idx_test_annotations_case ON test_annotations(test_case_id)`;
+	yield* sql`CREATE INDEX idx_test_annotations_type ON test_annotations(type)`;
+	yield* sql`ALTER TABLE test_artifacts ADD COLUMN data TEXT`;
+	yield* sql`ALTER TABLE attachments ADD COLUMN byte_size INTEGER`;
+	yield* sql`ALTER TABLE attachments ADD COLUMN body_encoding TEXT`;
+});
+
+//#endregion
+export { migration as default };

package/migrations/index.js

@@ -0,0 +1,27 @@
+import migration from "./0001_initial.js";
+import migration$1 from "./0002_test_artifacts.js";
+
+//#region src/migrations/index.ts
+/**
+* Every migration that must run against a per-project `data.db`, keyed by
+* migration id in application order.
+*
+* This is the single source of truth for the project database's migration
+* set: `makeSqliteStack` (and through it `PlatformLive`, `ensureMigrated`,
+* the testing layers, `ReporterLive` and `SidecarLive`) defaults to it when
+* calling `SqliteMigrator.fromRecord`, so adding a migration file and
+* registering it here is enough to reach every process that opens a project
+* database.
+*
+* The session-map and discovery-registry databases are separate schemas with
+* their own migrations and are deliberately not listed here.
+*
+* @public
+*/
+const PROJECT_MIGRATIONS = {
+	"0001_initial": migration,
+	"0002_test_artifacts": migration$1
+};
+
+//#endregion
+export { PROJECT_MIGRATIONS };

package/migrations/registry_0001_initial.js

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+
+//#region src/migrations/registry_0001_initial.ts
+/**
+* Migration for the global discovery registry SQLite at
+* `$XDG_DATA_HOME/vitest-agent/registry.db`.
+*
+* Single table `known_projects` indexed by `project_key` (the
+* filesystem-safe form from {@link ProjectIdentity}). Tooling like
+* `mcp-app` queries this table to enumerate every vitest-agent
+* project the user has ever run on this machine.
+*
+* The registry never blocks anything — its writes are best-effort.
+* Concurrent writers from multiple Claude Code windows converge via
+* the `ON CONFLICT(project_key) DO UPDATE` upsert.
+* @public
+*/
+const migration = Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	yield* sql`PRAGMA journal_mode=WAL`;
+	yield* sql`PRAGMA foreign_keys=ON`;
+	yield* sql`PRAGMA busy_timeout=5000`;
+	yield* sql`
+		CREATE TABLE known_projects (
+			project_key       TEXT PRIMARY KEY,
+			canonical_form    TEXT NOT NULL,
+			data_db_path      TEXT NOT NULL,
+			git_remote_origin TEXT,
+			workspace_root    TEXT NOT NULL,
+			first_seen_at     INTEGER NOT NULL,
+			last_seen_at      INTEGER NOT NULL
+		) STRICT
+	`;
+	yield* sql`CREATE INDEX idx_known_projects_workspace_root ON known_projects(workspace_root)`;
+});
+
+//#endregion
+export { migration as default };

package/migrations/session_map_0001_initial.js

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+
+//#region src/migrations/session_map_0001_initial.ts
+/** @internal */
+const migration = Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	yield* sql`PRAGMA journal_mode=WAL`;
+	yield* sql`PRAGMA foreign_keys=ON`;
+	yield* sql`PRAGMA busy_timeout=5000`;
+	yield* sql`
+		CREATE TABLE conversation_map (
+			transcript_uuid  TEXT PRIMARY KEY,
+			transcript_path  TEXT NOT NULL,
+			conversation_id  TEXT NOT NULL UNIQUE,
+			first_seen_at    INTEGER NOT NULL,
+			last_seen_at     INTEGER NOT NULL
+		) STRICT
+	`;
+	yield* sql`
+		CREATE TABLE session_map (
+			host_session_id  TEXT PRIMARY KEY,
+			conversation_id  TEXT NOT NULL REFERENCES conversation_map(conversation_id) ON DELETE RESTRICT,
+			project_key      TEXT NOT NULL,
+			project_dir      TEXT NOT NULL,
+			main_agent_id    TEXT NOT NULL,
+			started_at       INTEGER NOT NULL,
+			ended_at         INTEGER
+		) STRICT
+	`;
+	yield* sql`CREATE INDEX idx_session_map_project_key ON session_map(project_key)`;
+	yield* sql`CREATE INDEX idx_session_map_project_dir ON session_map(project_dir)`;
+	yield* sql`CREATE INDEX idx_session_map_active ON session_map(project_dir) WHERE ended_at IS NULL`;
+	yield* sql`CREATE INDEX idx_session_map_conversation_id ON session_map(conversation_id)`;
+});
+
+//#endregion
+export { migration as default };

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@vitest-agent/engine",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Shared services, layers, SQLite data layer, migrations and platform resolution for the vitest-agent CLI and MCP server.",
+	"keywords": [
+		"vitest",
+		"agent",
+		"shared",
+		"effect",
+		"sqlite"
+	],
+	"homepage": "https://github.com/spencerbeggs/vitest-agent#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/vitest-agent/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/vitest-agent.git",
+		"directory": "packages/engine"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effect/platform-node": "4.0.0-rc.115",
+		"@effect/sql-sqlite-node": "4.0.0-rc.115",
+		"@effected/config-file": "^0.9.0",
+		"@effected/jsonc": "^0.11.0",
+		"@effected/toml": "^0.7.0",
+		"@effected/walker": "^0.9.0",
+		"@effected/workspaces": "^0.21.1",
+		"@effected/xdg": "^0.5.1",
+		"@effected/yaml": "^0.15.1",
+		"@vitest-agent/sdk": "4.0.0",
+		"effect": "4.0.0-rc.115",
+		"std-env": "^4.2.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/platform.js

@@ -0,0 +1,58 @@
+import { DataReaderLive } from "./layers/DataReaderLive.js";
+import { DataStoreLive } from "./layers/DataStoreLive.js";
+import { HistoryTrackerLive } from "./layers/HistoryTrackerLive.js";
+import { LoggerLive } from "./layers/LoggerLive.js";
+import { OutputPipelineLive } from "./layers/OutputPipelineLive.js";
+import { ProjectDiscoveryLive } from "./layers/ProjectDiscoveryLive.js";
+import { PROJECT_MIGRATIONS } from "./migrations/index.js";
+import { Layer } from "effect";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { layer } from "@effect/sql-sqlite-node/SqliteClient";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+
+//#region src/platform.ts
+/**
+* The Node platform services every SQLite stack and every Live layer share.
+* `NodeServices.layer` aggregates FileSystem | Path | ChildProcessSpawner |
+* Crypto | Stdio | Terminal.
+* @public
+*/
+const NodePlatformLayer = NodeServices.layer;
+/**
+* Build one SQLite database stack: the client layer for `filename` and a
+* migrator over `migrations` that is already provided with that client and
+* the Node platform services. The single assembly the CLI, MCP server,
+* plugin, `ensureMigrated` and the testing layers all share.
+*
+* @param filename - SQLite file path, or `":memory:"`
+* @param migrations - the migration record to run; defaults to the project
+*   `data.db` set (`PROJECT_MIGRATIONS`)
+* @public
+*/
+const makeSqliteStack = (filename, migrations = PROJECT_MIGRATIONS) => {
+	const SqliteLayer = layer({ filename });
+	return {
+		SqliteLayer,
+		MigratorLayer: SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord(migrations) }).pipe(Layer.provide(Layer.merge(SqliteLayer, NodePlatformLayer)))
+	};
+};
+/**
+* The one platform assembly shared by the CLI, the MCP server and the Vitest
+* plugin: SQLite + migrator + Node platform services + Logger, with
+* `DataReader`, `DataStore`, `ProjectDiscovery`, `HistoryTracker` and the
+* output pipeline (`EnvironmentDetector`, `ExecutorResolver`,
+* `FormatSelector`, `DetailResolver`, `OutputRenderer`) built over them.
+*
+* Every env read goes through `options.env`; the engine never touches
+* `process` itself.
+*
+* @param options - database path, env map and optional logging overrides
+* @public
+*/
+const PlatformLive = (options) => {
+	const { SqliteLayer, MigratorLayer } = makeSqliteStack(options.dbPath);
+	return Layer.mergeAll(ProjectDiscoveryLive, HistoryTrackerLive, OutputPipelineLive(options.env)).pipe(Layer.provideMerge(DataReaderLive), Layer.provideMerge(DataStoreLive), Layer.provideMerge(MigratorLayer), Layer.provideMerge(SqliteLayer), Layer.provideMerge(NodePlatformLayer), Layer.provideMerge(LoggerLive(options.logLevel, options.logFile)));
+};
+
+//#endregion
+export { NodePlatformLayer, PlatformLive, makeSqliteStack };

package/programs/end-agent.js

@@ -0,0 +1,19 @@
+import { DataStore } from "../services/DataStore.js";
+import { PerClientSessionMapWriter } from "../services/PerClientSessionMap.js";
+import { Effect } from "effect";
+
+//#region src/programs/end-agent.ts
+/**
+* End an agent. Closes the `agents` row, optionally also closes the
+* `session_map` row.
+*
+* @param input - the agent id, end timestamp, and optional host session id
+* @public
+*/
+const endAgentEffect = (input) => Effect.gen(function* () {
+	yield* (yield* DataStore).endAgent(input.agentId, input.endedAt);
+	if (input.hostSessionId !== void 0) yield* (yield* PerClientSessionMapWriter).endSession(input.hostSessionId, input.endedAt);
+});
+
+//#endregion
+export { endAgentEffect };

package/programs/hook-paths.js

@@ -0,0 +1,115 @@
+import { APP_NAMESPACE } from "../layers/PathResolutionLive.js";
+import { ProjectIdentityNotResolvableError } from "@vitest-agent/sdk";
+import { ConfigProvider, Effect, FileSystem, Layer, Path } from "effect";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/programs/hook-paths.ts
+/**
+* Filename of the per-project test-data SQLite database.
+*
+* @public
+*/
+const DATA_DB_FILENAME = "data.db";
+/**
+* Filename of the per-client session-map SQLite database.
+*
+* @public
+*/
+const SESSIONS_DB_FILENAME = "sessions.db";
+/**
+* Filename of the global discovery-registry SQLite database.
+*
+* @public
+*/
+const REGISTRY_DB_FILENAME = "registry.db";
+/**
+* Where the XDG data root lands when `XDG_DATA_HOME` is unset:
+* `$HOME/.local/share/vitest-agent` — the XDG spec default the sidecar has
+* always used. (`AppDirs` alone would fall back to `$HOME/.vitest-agent`.)
+*/
+const HOOK_DATA_FALLBACK_DIR = `.local/share/${APP_NAMESPACE}`;
+/** Directory under the home dir that holds the per-client `sessions.db` fallback. */
+const SESSION_MAP_HOME_DIR = `.${APP_NAMESPACE}`;
+const nonEmpty = (value) => value !== void 0 && value.length > 0 ? value : void 0;
+/**
+* `AppDirs` for the hook family, resolved from the caller's `env` map.
+*
+* `Xdg.layer` reads `HOME` and `XDG_DATA_HOME` through the ambient
+* `ConfigProvider`, so the env map is installed as that provider — no
+* `process.env` read. `USERPROFILE` stands in for `HOME` when the latter is
+* unset (Windows), matching the session-map fallback order below.
+*/
+const hookAppDirs = (env) => {
+	const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+	const provider = ConfigProvider.fromEnvRecord({
+		...env,
+		...home !== void 0 && { HOME: home }
+	});
+	const XdgLive = Xdg.layer.pipe(Layer.provide(ConfigProvider.layer(provider)));
+	return AppDirs.layer({
+		namespace: APP_NAMESPACE,
+		fallbackDir: HOOK_DATA_FALLBACK_DIR
+	}).pipe(Layer.provide(XdgLive));
+};
+/**
+* Resolve the per-client `sessions.db` path.
+*
+* Precedence: the `CLAUDE_PLUGIN_DATA` env var, then
+* `VITEST_AGENT_SESSION_MAP_DIR`, then `~/.vitest-agent/` (`HOME`, then
+* `USERPROFILE`). The chosen directory is created. Fails with
+* `ProjectIdentityNotResolvableError` when no home directory is resolvable.
+*
+* @param env - the environment map to consult (the front end passes `process.env`)
+* @returns an Effect resolving to the absolute `sessions.db` path
+* @public
+*/
+const resolveSessionMapPath = (env) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+	const dir = nonEmpty(env.CLAUDE_PLUGIN_DATA) ?? nonEmpty(env.VITEST_AGENT_SESSION_MAP_DIR) ?? (home !== void 0 ? path.join(home, SESSION_MAP_HOME_DIR) : void 0);
+	if (dir === void 0) return yield* new ProjectIdentityNotResolvableError({ tried: [
+		{
+			source: "CLAUDE_PLUGIN_DATA",
+			reason: "env var not set"
+		},
+		{
+			source: "VITEST_AGENT_SESSION_MAP_DIR",
+			reason: "env var not set"
+		},
+		{
+			source: "HOME",
+			reason: "env var not set (USERPROFILE also unset)"
+		}
+	] });
+	yield* fs.makeDirectory(dir, { recursive: true });
+	return path.join(dir, SESSIONS_DB_FILENAME);
+});
+/**
+* Resolve (and create) every path the sidecar-family subcommands open for
+* `projectKey`: the per-project `data.db`, the global `registry.db` and the
+* per-client `sessions.db`. See the module header for the precedence rules.
+*
+* @param input - the environment map (the front end passes `process.env`)
+*   and the normalized project key (e.g. `@org__pkg`)
+* @returns an Effect resolving to the created {@link HookPaths}
+* @public
+*/
+const resolveHookPaths = (input) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const dataRoot = yield* (yield* AppDirs).ensureData;
+	const projectDataDir = path.join(dataRoot, input.projectKey);
+	yield* fs.makeDirectory(projectDataDir, { recursive: true });
+	const sessionMapDbPath = yield* resolveSessionMapPath(input.env);
+	return {
+		dataRoot,
+		projectDataDir,
+		perProjectDbPath: path.join(projectDataDir, DATA_DB_FILENAME),
+		registryDbPath: path.join(dataRoot, REGISTRY_DB_FILENAME),
+		sessionMapDbPath
+	};
+}).pipe(Effect.provide(hookAppDirs(input.env)));
+
+//#endregion
+export { DATA_DB_FILENAME, REGISTRY_DB_FILENAME, SESSIONS_DB_FILENAME, resolveHookPaths, resolveSessionMapPath };

package/programs/platform-sidecar.js

@@ -0,0 +1,37 @@
+import { DataReaderLive } from "../layers/DataReaderLive.js";
+import { DataStoreLive } from "../layers/DataStoreLive.js";
+import { DiscoveryRegistryLive } from "../layers/DiscoveryRegistryLive.js";
+import { LoggerLive } from "../layers/LoggerLive.js";
+import { PerClientSessionMapWriterLive } from "../layers/PerClientSessionMapLive.js";
+import { RunContextLive } from "../layers/RunContextLive.js";
+import migration from "../migrations/registry_0001_initial.js";
+import migration$1 from "../migrations/session_map_0001_initial.js";
+import { NodePlatformLayer, makeSqliteStack } from "../platform.js";
+import { Layer } from "effect";
+
+//#region src/programs/platform-sidecar.ts
+/**
+* Build the sidecar Live layer for the supplied SQLite paths.
+*
+* Each store gets its own `SqlClient` connection (separate scopes,
+* independent migrators, all built through the engine's shared
+* `makeSqliteStack`) so concurrent operations on the three stores
+* don't share lock state.
+*
+* @param paths - the three SQLite database paths to open
+* @param env - the environment map `RunContextLive` probes for host
+*   metadata (the bin passes `process.env`)
+* @public
+*/
+const SidecarPlatformLive = (paths, env) => {
+	const project = makeSqliteStack(paths.perProjectDbPath);
+	const ProjectStoreLayer = Layer.mergeAll(DataStoreLive.pipe(Layer.provide(project.SqliteLayer)), DataReaderLive.pipe(Layer.provide(project.SqliteLayer)), project.MigratorLayer);
+	const sessionMap = makeSqliteStack(paths.sessionMapDbPath, { "0001_initial": migration$1 });
+	const SessionMapLayer = Layer.mergeAll(PerClientSessionMapWriterLive.pipe(Layer.provide(sessionMap.SqliteLayer)), sessionMap.MigratorLayer);
+	const registry = makeSqliteStack(paths.registryDbPath, { "0001_initial": migration });
+	const RegistryLayer = Layer.mergeAll(DiscoveryRegistryLive.pipe(Layer.provide(registry.SqliteLayer)), registry.MigratorLayer);
+	return Layer.mergeAll(ProjectStoreLayer, SessionMapLayer, RegistryLayer, RunContextLive(env)).pipe(Layer.provideMerge(NodePlatformLayer), Layer.provideMerge(LoggerLive()));
+};
+
+//#endregion
+export { SidecarPlatformLive };

package/programs/record-session.js

@@ -0,0 +1,49 @@
+import { DataReader } from "../services/DataReader.js";
+import { DataStore } from "../services/DataStore.js";
+import { Effect } from "effect";
+
+//#region src/programs/record-session.ts
+/**
+* Upsert a `sessions` row for a SessionStart / SubagentStart hook, resolving
+* `parentChatId` to the parent's numeric session id when present.
+*
+* @param input - the session identity to record
+* @returns the numeric `sessions.id`
+* @public
+*/
+const recordSessionStart = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	let parentSessionId;
+	if (input.parentChatId !== void 0) {
+		const parent = yield* reader.getSessionByChatId(input.parentChatId);
+		if (parent._tag === "Some") parentSessionId = parent.value.id;
+	}
+	return { sessionId: yield* store.upsertSession({
+		chatId: input.chatId,
+		project: input.project,
+		cwd: input.cwd,
+		agentKind: input.agentKind,
+		...input.agentType !== void 0 && { agentType: input.agentType },
+		...parentSessionId !== void 0 && { parentSessionId },
+		triageWasNonEmpty: input.triageWasNonEmpty,
+		startedAt: input.startedAt
+	}) };
+});
+/**
+* Close a `sessions` row for a SessionEnd hook. Fails with an `Error`
+* when no session exists for `chatId`.
+*
+* @param input - the session to close
+* @public
+*/
+const recordSessionEnd = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	if ((yield* reader.getSessionByChatId(input.chatId))._tag === "None") return yield* Effect.fail(/* @__PURE__ */ new Error(`Unknown chatId: ${input.chatId}`));
+	yield* store.endSession(input.chatId, input.endedAt, input.endReason);
+	return { ok: true };
+});
+
+//#endregion
+export { recordSessionEnd, recordSessionStart };

package/programs/record-tdd-artifact.js

@@ -0,0 +1,119 @@
+import { DataReader } from "../services/DataReader.js";
+import { DataStore } from "../services/DataStore.js";
+import { resolveSessionForRecording } from "./resolve-session-for-recording.js";
+import { Effect, Option } from "effect";
+
+//#region src/programs/record-tdd-artifact.ts
+/**
+* Resolve (auto-opening a `spike` phase if needed) the current open
+* phase for `tddTaskId`, then write the artifact under it. Shared by
+* both `recordTddArtifactEffect` (chat-id → session → task resolution)
+* and `recordTddArtifactByTaskIdEffect` (explicit task-id escape hatch).
+*/
+const writeArtifactUnderOpenPhase = (tddTaskId, input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	const phaseOpt = yield* reader.getCurrentTddPhase(tddTaskId);
+	const phaseId = Option.isSome(phaseOpt) ? phaseOpt.value.id : (yield* store.writeTddPhase({
+		tddTaskId,
+		phase: "spike",
+		startedAt: input.recordedAt,
+		transitionReason: "auto-opened by record tdd-artifact (no prior phase)"
+	})).id;
+	return {
+		id: yield* store.writeTddArtifact({
+			phaseId,
+			artifactKind: input.artifactKind,
+			...input.fileId !== void 0 && { fileId: input.fileId },
+			...input.testCaseId !== void 0 && { testCaseId: input.testCaseId },
+			...input.testRunId !== void 0 && { testRunId: input.testRunId },
+			...input.testFirstFailureRunId !== void 0 && { testFirstFailureRunId: input.testFirstFailureRunId },
+			...input.diffExcerpt !== void 0 && { diffExcerpt: input.diffExcerpt },
+			...input.suite !== void 0 && { suite: input.suite },
+			recordedAt: input.recordedAt
+		}),
+		phaseId
+	};
+});
+/**
+* Record a TDD artifact under the open TDD task for `chatId`, walking
+* parent and conversation links to find the task and auto-opening a
+* `spike` phase when the task has none.
+*
+* @param input - the artifact to record, keyed by host chat id
+* @public
+*/
+const recordTddArtifactEffect = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const session = yield* resolveSessionForRecording({
+		chatId: input.chatId,
+		recordedAt: input.recordedAt,
+		...input.project !== void 0 && { project: input.project },
+		cwd: input.cwd
+	});
+	const openTdd = (yield* reader.listTddTasksForSession(session.id, {
+		walkParents: true,
+		walkConversation: true
+	})).find((t) => t.endedAt === null);
+	if (openTdd === void 0) return yield* Effect.fail(/* @__PURE__ */ new Error(`No open TDD task under chat_id ${input.chatId}. Call tdd_task start first.`));
+	return yield* writeArtifactUnderOpenPhase(openTdd.id, input);
+});
+/**
+* Explicit task-id escape hatch (issue #144). Bypasses `chat_id` →
+* session → task resolution entirely — the caller already knows which
+* TDD task the artifact belongs to (e.g. a hook seeded with
+* `VITEST_AGENT_TDD_TASK_ID` in a detached-session environment where
+* neither the parent walk nor the conversation-id fallback resolves
+* the right task). Fails loudly when the task does not exist or has
+* already ended — writing to a closed task's phase would silently
+* corrupt the evidence trail.
+*
+* @param input - the artifact to record, keyed by TDD task id
+* @public
+*/
+const recordTddArtifactByTaskIdEffect = (input) => Effect.gen(function* () {
+	const taskOpt = yield* (yield* DataReader).getTddTaskById(input.tddTaskId);
+	if (Option.isNone(taskOpt)) return yield* Effect.fail(/* @__PURE__ */ new Error(`No TDD task found for id ${input.tddTaskId}.`));
+	if (taskOpt.value.endedAt !== null) return yield* Effect.fail(/* @__PURE__ */ new Error(`TDD task ${input.tddTaskId} has already ended (endedAt=${taskOpt.value.endedAt}).`));
+	return yield* writeArtifactUnderOpenPhase(input.tddTaskId, input);
+});
+/**
+* CLI-command-facing dispatcher (issue #144). Keeps `commands/record.ts`
+* a thin flag-parsing wrapper per this package's convention. `tddTaskId`
+* takes priority when both are supplied — it is the explicit escape
+* hatch and should never silently fall back to (weaker) session
+* resolution.
+*
+* @param input - the artifact plus either a chat id or a TDD task id
+* @public
+*/
+const dispatchRecordTddArtifactEffect = (input) => {
+	if (input.tddTaskId !== void 0) return recordTddArtifactByTaskIdEffect({
+		tddTaskId: input.tddTaskId,
+		artifactKind: input.artifactKind,
+		...input.fileId !== void 0 && { fileId: input.fileId },
+		...input.testCaseId !== void 0 && { testCaseId: input.testCaseId },
+		...input.testRunId !== void 0 && { testRunId: input.testRunId },
+		...input.testFirstFailureRunId !== void 0 && { testFirstFailureRunId: input.testFirstFailureRunId },
+		...input.diffExcerpt !== void 0 && { diffExcerpt: input.diffExcerpt },
+		...input.suite !== void 0 && { suite: input.suite },
+		recordedAt: input.recordedAt
+	});
+	if (input.chatId !== void 0) return recordTddArtifactEffect({
+		chatId: input.chatId,
+		artifactKind: input.artifactKind,
+		...input.fileId !== void 0 && { fileId: input.fileId },
+		...input.testCaseId !== void 0 && { testCaseId: input.testCaseId },
+		...input.testRunId !== void 0 && { testRunId: input.testRunId },
+		...input.testFirstFailureRunId !== void 0 && { testFirstFailureRunId: input.testFirstFailureRunId },
+		...input.diffExcerpt !== void 0 && { diffExcerpt: input.diffExcerpt },
+		...input.suite !== void 0 && { suite: input.suite },
+		recordedAt: input.recordedAt,
+		cwd: input.cwd,
+		...input.project !== void 0 && { project: input.project }
+	});
+	return Effect.fail(/* @__PURE__ */ new Error("record tdd-artifact requires either --chat-id or --tdd-task-id."));
+};
+
+//#endregion
+export { dispatchRecordTddArtifactEffect, recordTddArtifactByTaskIdEffect, recordTddArtifactEffect };

package/programs/record-turn.js

@@ -0,0 +1,61 @@
+import { DataStore } from "../services/DataStore.js";
+import { resolveSessionForRecording } from "./resolve-session-for-recording.js";
+import { TurnPayload } from "@vitest-agent/sdk";
+import { Effect, Schema } from "effect";
+
+//#region src/programs/record-turn.ts
+/**
+* Parse a raw JSON string and validate it against the `TurnPayload` schema
+* without throwing.
+*
+* @param raw - the JSON text delivered by the hook
+* @returns the decoded payload, or an error describing why it was rejected
+* @public
+*/
+const parseAndValidateTurnPayload = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		return {
+			ok: false,
+			error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`
+		};
+	}
+	const decoded = Schema.decodeUnknownResult(TurnPayload)(parsed);
+	if (decoded._tag === "Failure") return {
+		ok: false,
+		error: `Invalid TurnPayload: ${decoded.failure.message}`
+	};
+	return {
+		ok: true,
+		payload: decoded.success
+	};
+};
+/**
+* Validate a turn payload and write it as a `turns` row under the session
+* resolved for `chatId` (bootstrapping the session row when needed).
+*
+* @param input - the turn to record
+* @returns the new `turns.id`
+* @public
+*/
+const recordTurnEffect = (input) => Effect.gen(function* () {
+	const parse = parseAndValidateTurnPayload(input.payloadJson);
+	if (!parse.ok) return yield* Effect.fail(new Error(parse.error));
+	const session = yield* resolveSessionForRecording({
+		chatId: input.chatId,
+		recordedAt: input.occurredAt,
+		...input.project !== void 0 && { project: input.project },
+		cwd: input.cwd
+	});
+	return { turnId: yield* (yield* DataStore).writeTurn({
+		sessionId: session.id,
+		type: parse.payload.type,
+		payload: input.payloadJson,
+		occurredAt: input.occurredAt
+	}) };
+});
+
+//#endregion
+export { parseAndValidateTurnPayload, recordTurnEffect };