@vitest-agent/engine 1.1.2 → 1.2.0

package/index.d.ts

@@ -1,6 +1,6 @@
 import { Context, Effect, FileSystem, Layer, LogLevel, Option, Path, Schema } from "effect";
 import { ConfigFileShape } from "@effected/config-file";
-import { Agent, AgentNotFoundError, AgentReport, ArtifactKind, ArtifactKind as ArtifactKind$1, ArtifactSuite, ArtifactSuite as ArtifactSuite$1, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, CitedArtifact, CoverageBaselines, CoverageReport, DataStoreError, DetailLevel, DiscoveryError, Environment, Executor, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, Phase, ProjectIdentityNotResolvableError, RegistrationConflictError, ResolvedThresholds, TddTaskAlreadyEndedError, TddTaskNotFoundError, TestClassification, TestRun, TrendEntry, TrendRecord, TurnPayload, VitestAgentConfig } from "@vitest-agent/sdk";
+import { Agent, AgentNotFoundError, AgentReport, ArtifactKind, ArtifactKind as ArtifactKind$1, ArtifactSuite, ArtifactSuite as ArtifactSuite$1, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, CitedArtifact, CoverageBaselines, CoverageReport, DataStoreError, DetailLevel, DiscoveryError, Environment, Executor, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, Phase, ProjectIdentityNotResolvableError, RegistrationConflictError, ResolvedThresholds, RunRetentionPolicy, TddTaskAlreadyEndedError, TddTaskNotFoundError, TestClassification, TestRun, TrendEntry, TrendRecord, TurnPayload, VitestAgentConfig } from "@vitest-agent/sdk";
 import { SqlClient } from "effect/sql/SqlClient";
 import { RuntimeEnv } from "@effected/env";
 import { WorkspaceDiscovery, WorkspaceDiscoveryFailure, WorkspaceRootNotFoundError } from "@effected/workspaces";
@@ -457,6 +457,15 @@ export interface RegisterAgentInput {
    */
   readonly agentId?: string;
 }
+/**
+ * What `DataStore.pruneRuns` removed: `test_runs` rows deleted (their
+ * cascaded rows are not counted) and orphaned `files` rows garbage-collected.
+ * @public
+ */
+export interface PruneRunsResult {
+  readonly prunedRuns: number;
+  readonly prunedFiles: number;
+}
 /** @public */
 export interface AssociateRunSessionInput {
   readonly chatId: string;
@@ -554,6 +563,25 @@ declare const DataStore_base: Context.ServiceClass<DataStore, "vitest-agent/Data
     readonly affectedSessions: number;
     readonly prunedTurns: number;
   }, DataStoreError>;
+  /**
+   * Apply a run-retention policy: delete every `test_runs` row beyond the
+   * newest `policy.keepRuns` of its project, and any run older than
+   * `policy.maxAgeDays` days when set, letting the schema's cascades drop
+   * the dependent rows (modules, suites, cases, tags, errors, frames,
+   * coverage, trends, triggers), then garbage-collect `files` rows no
+   * table references any more. `test_history` rows survive with a NULL
+   * `run_id`; they keep their own newest-10-per-series window. Before
+   * the delete, `file_coverage` rows held by a doomed run are moved onto
+   * the lowest surviving run of the same invocation (coverage is written
+   * once per invocation, issue 622) unless a survivor already carries
+   * coverage rows, so every sibling project's coverage read stays whole.
+   *
+   * A handful of synchronous statements on the open connection, no
+   * yielding, so it may run inside `withPersistTransaction` after the
+   * run's own rows are written: the run just written is the newest of
+   * its project and is never pruned.
+   */
+  readonly pruneRuns: (policy: RunRetentionPolicy) => Effect.Effect<PruneRunsResult, DataStoreError>;
   readonly associateLatestRunWithSession: (input: AssociateRunSessionInput) => Effect.Effect<void, DataStoreError>;
   readonly backfillTestCaseTurns: (chatId: string) => Effect.Effect<number, DataStoreError>;
   /**
@@ -1688,6 +1716,7 @@ declare const migration$1: Effect.Effect<void, import("effect/sql/SqlError").Sql
 export declare const PROJECT_MIGRATIONS: {
   readonly "0001_initial": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
   readonly "0002_test_artifacts": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
+  readonly "0003_run_retention": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
 };
 /**
  * Migration for the global discovery registry SQLite at
@@ -2540,6 +2569,30 @@ export interface FailureSignatureInput {
 export declare const normalizeAssertionShape: (message: string) => string | null;
 /** @public */
 export declare const computeFailureSignature: (input: FailureSignatureInput) => string;
+/**
+ * Run `effect` as a nested transaction that keeps the
+ * {@link withPersistTransaction} caches honest.
+ *
+ * Outside a persist batch this is exactly `sql.withTransaction(effect)`.
+ * Inside one, the nested `withTransaction` becomes a SAVEPOINT, and when it
+ * rolls back (a failure, a defect, an interrupt) every `files` / `tags` row
+ * the savepoint inserted is gone while the ids `DataStoreLive` cached for
+ * them would survive in `PersistBatchState`. This helper snapshots the
+ * cache sizes before the savepoint opens and discards the entries added
+ * since whenever it does not commit, so a later write in the same batch
+ * re-inserts the row instead of referencing one that no longer exists
+ * (issue #628: a FK failure or a dangling id). A savepoint that commits
+ * keeps its entries.
+ *
+ * Use this, never a bare `sql.withTransaction`, for any nested transaction
+ * whose failure a caller may catch and continue from inside the batch; a
+ * bare one that rolls back leaves the caches stale. The bookkeeping is
+ * synchronous, so the batch's no-yield guarantee is unchanged.
+ *
+ * @param effect - the writes to run as one savepoint (or transaction)
+ * @public
+ */
+export declare const withPersistSavepoint: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqlError, R | SqlClient>;
 /**
  * Run `effect` as one SQLite write transaction on the `data.db` connection:
  * every `DataStore` write inside it commits together or not at all, and a
@@ -2560,8 +2613,13 @@ export declare const computeFailureSignature: (input: FailureSignatureInput) =>
  * genuinely asynchronous work for that reason; CPU-heavy work that needs no
  * database belongs before the block.
  *
- * Nested `withTransaction` calls inside `effect` become savepoints. A
- * `DataReader` query inside it runs on the transaction's connection.
+ * Nested `withTransaction` calls inside `effect` become savepoints. Open
+ * them through {@link withPersistSavepoint}: a savepoint that rolls back
+ * also discards the tag / file ids cached while it was open, so a write the
+ * caller recovers from cannot leave a later write pointing at a row the
+ * rollback removed. A bare nested `sql.withTransaction` whose failure is
+ * caught inside the block leaves those caches stale. A `DataReader` query
+ * inside the block runs on the transaction's connection.
  *
  * @param effect - the writes (and the reads they depend on) to run atomically
  * @public

package/index.js

@@ -4,7 +4,7 @@ import { DataReader } from "./services/DataReader.js";
 import { HistoryTracker, historyKey } from "./services/HistoryTracker.js";
 import { DataReaderLive } from "./layers/DataReaderLive.js";
 import { DataStore, INLINE_ATTACHMENT_BODY_CAP_BYTES } from "./services/DataStore.js";
-import { withPersistTransaction } from "./utils/persist-transaction.js";
+import { withPersistSavepoint, withPersistTransaction } from "./utils/persist-transaction.js";
 import { DataStoreLive } from "./layers/DataStoreLive.js";
 import { DetailResolver } from "./services/DetailResolver.js";
 import { DetailResolverLive } from "./layers/DetailResolverLive.js";
@@ -57,4 +57,4 @@ import { DATABASE_FILENAME, resolveDataPath } from "./utils/resolve-data-path.js
 import { resolveWorkspaceKey } from "./utils/resolve-workspace-key.js";
 import { CURRENT_ENGINE_VERSION } from "./version.js";
 
-export { APP_NAMESPACE, AgentContext, CURRENT_ENGINE_VERSION, ConfigLive, DATABASE_FILENAME, DATA_DB_FILENAME, DATA_FALLBACK_DIR, DataReader, DataReaderLive, DataStore, DataStoreLive, DetailResolver, DetailResolverLive, DiscoveryRegistry, DiscoveryRegistryLive, EnvironmentDetector, EnvironmentDetectorLive, EnvironmentDetectorTest, ExecutorResolver, ExecutorResolverLive, HistoryTracker, HistoryTrackerLive, HistoryTrackerTest, IDEMPOTENCY_ROOT_SENTINEL, INLINE_ATTACHMENT_BODY_CAP_BYTES, LoggerLive, NodePlatformLayer, OutputPipelineLive, PROJECT_MIGRATIONS, PathResolutionLive, PerClientSessionMapReader, PerClientSessionMapReaderLive, PerClientSessionMapWriter, PerClientSessionMapWriterLive, PlatformLive, ProjectDiscovery, ProjectDiscoveryLive, ProjectDiscoveryTest, ProjectIdentity, ProjectIdentityLive, ProjectIdentityTest, REGISTRY_DB_FILENAME, REGISTRY_STORE_OPTIONS, RunContext, RunContext$, RunContextLive, RunContextService, RunContextTest, SESSIONS_DB_FILENAME, SidecarPlatformLive, VitestAgentConfigFile, _resetMigrationCacheForTesting, assembleHistoryRecord, assembleManifest, classifyEnvironment, computeFailureSignature, deriveIdempotencyKey, dispatchRecordTddArtifactEffect, endAgentEffect, ensureMigrated, formatTriageEffect, formatWrapupEffect, historyKey, makeSqliteStack, migration as migration0001, migration$1 as migration0002, normalizeAssertionShape, parseAndValidateTurnPayload, parseSessionEnvExports, recordRunWorkspaceChangesEffect, recordSessionEnd, recordSessionStart, recordTddArtifactByTaskIdEffect, recordTddArtifactEffect, recordTurnEffect, recoverSessionContextFromSessionEnv, registerAgentEffect, migration$2 as registryMigration0001, resolveDataPath, resolveHookPaths, resolveLogFile, resolveLogLevel, resolveProjectDir, resolveProjectIdentityFromCandidates, resolveProjectKeyFromCwd, resolveProjectKeyFromCwdEffect, resolveSessionForRecording, resolveSessionMapPath, resolveWorkspaceKey, migration$3 as sessionMapMigration0001, withPersistTransaction };
+export { APP_NAMESPACE, AgentContext, CURRENT_ENGINE_VERSION, ConfigLive, DATABASE_FILENAME, DATA_DB_FILENAME, DATA_FALLBACK_DIR, DataReader, DataReaderLive, DataStore, DataStoreLive, DetailResolver, DetailResolverLive, DiscoveryRegistry, DiscoveryRegistryLive, EnvironmentDetector, EnvironmentDetectorLive, EnvironmentDetectorTest, ExecutorResolver, ExecutorResolverLive, HistoryTracker, HistoryTrackerLive, HistoryTrackerTest, IDEMPOTENCY_ROOT_SENTINEL, INLINE_ATTACHMENT_BODY_CAP_BYTES, LoggerLive, NodePlatformLayer, OutputPipelineLive, PROJECT_MIGRATIONS, PathResolutionLive, PerClientSessionMapReader, PerClientSessionMapReaderLive, PerClientSessionMapWriter, PerClientSessionMapWriterLive, PlatformLive, ProjectDiscovery, ProjectDiscoveryLive, ProjectDiscoveryTest, ProjectIdentity, ProjectIdentityLive, ProjectIdentityTest, REGISTRY_DB_FILENAME, REGISTRY_STORE_OPTIONS, RunContext, RunContext$, RunContextLive, RunContextService, RunContextTest, SESSIONS_DB_FILENAME, SidecarPlatformLive, VitestAgentConfigFile, _resetMigrationCacheForTesting, assembleHistoryRecord, assembleManifest, classifyEnvironment, computeFailureSignature, deriveIdempotencyKey, dispatchRecordTddArtifactEffect, endAgentEffect, ensureMigrated, formatTriageEffect, formatWrapupEffect, historyKey, makeSqliteStack, migration as migration0001, migration$1 as migration0002, normalizeAssertionShape, parseAndValidateTurnPayload, parseSessionEnvExports, recordRunWorkspaceChangesEffect, recordSessionEnd, recordSessionStart, recordTddArtifactByTaskIdEffect, recordTddArtifactEffect, recordTurnEffect, recoverSessionContextFromSessionEnv, registerAgentEffect, migration$2 as registryMigration0001, resolveDataPath, resolveHookPaths, resolveLogFile, resolveLogLevel, resolveProjectDir, resolveProjectIdentityFromCandidates, resolveProjectKeyFromCwd, resolveProjectKeyFromCwdEffect, resolveSessionForRecording, resolveSessionMapPath, resolveWorkspaceKey, migration$3 as sessionMapMigration0001, withPersistSavepoint, withPersistTransaction };

package/layers/DataReaderLive.js

@@ -8,6 +8,28 @@ import { SqlClient } from "effect/sql/SqlClient";
 /** @public */
 const DataReaderLive = Layer.effect(DataReader, Effect.gen(function* () {
 	const sql = yield* SqlClient;
+	/**
+	* The run whose `file_coverage` rows describe `runId`'s coverage.
+	*
+	* The reporter writes per-file coverage ONCE per invocation, under
+	* one run of that invocation (issue #622), while every project gets
+	* its own `test_runs` row. A project run's rows therefore live under
+	* the sibling run sharing its `invocation_id`. Preference order: the
+	* run itself when it carries rows (a database an older reporter wrote
+	* holds an identical copy under every run of the invocation — reading
+	* exactly one run keeps that layout deduplicated), else the lowest
+	* sibling run id that carries rows. A run whose invocation wrote no
+	* rows resolves to itself, so the caller's `WHERE run_id = ?` is
+	* simply empty. Never crosses an invocation boundary.
+	*/
+	const resolveCoverageRunId = (runId) => Effect.gen(function* () {
+		return (yield* sql`SELECT fc.run_id
+					FROM file_coverage fc
+					JOIN test_runs tr ON tr.id = fc.run_id
+					WHERE tr.invocation_id = (SELECT invocation_id FROM test_runs WHERE id = ${runId})
+					ORDER BY CASE WHEN fc.run_id = ${runId} THEN 0 ELSE 1 END, fc.run_id ASC
+					LIMIT 1`)[0]?.run_id ?? runId;
+	});
 	const getLatestRun = (project) => Effect.gen(function* () {
 		yield* Effect.logDebug("getLatestRun").pipe(Effect.annotateLogs({ project }));
 		const runs = yield* sql`SELECT id, timestamp, reason, duration, total, passed, failed, skipped, project
@@ -80,11 +102,12 @@ const DataReaderLive = Layer.effect(DataReader, Effect.gen(function* () {
 					WHERE run_id = ${run.id} AND scope = 'unhandled'`;
 		const failedFiles = failedModules.map((m) => m.file_path);
 		const projectName = run.project;
+		const coverageRunId = yield* resolveCoverageRunId(run.id);
 		const fileCovRows = yield* sql`SELECT f.path AS file_path, fc.statements, fc.branches, fc.functions, fc.lines,
 					   fc.uncovered_lines, fc.tier
 					FROM file_coverage fc
 					JOIN files f ON f.id = fc.file_id
-					WHERE fc.run_id = ${run.id}`;
+					WHERE fc.run_id = ${coverageRunId}`;
 		const lowCoverage = fileCovRows.filter((r) => r.tier === "below_threshold").map((r) => ({
 			file: r.file_path,
 			summary: {
@@ -440,10 +463,11 @@ const DataReaderLive = Layer.effect(DataReader, Effect.gen(function* () {
 	})));
 	const getFileCoverage = (runId) => Effect.gen(function* () {
 		yield* Effect.logDebug("getFileCoverage").pipe(Effect.annotateLogs({ runId }));
+		const coverageRunId = yield* resolveCoverageRunId(runId);
 		return (yield* sql`SELECT f.path as file_path, fc.statements, fc.branches, fc.functions, fc.lines, fc.uncovered_lines
 					FROM file_coverage fc
 					JOIN files f ON f.id = fc.file_id
-					WHERE fc.run_id = ${runId}`).map((r) => ({
+					WHERE fc.run_id = ${coverageRunId}`).map((r) => ({
 			file: r.file_path,
 			summary: {
 				statements: r.statements,
@@ -464,7 +488,7 @@ const DataReaderLive = Layer.effect(DataReader, Effect.gen(function* () {
 					WHERE project = ${project}
 					ORDER BY timestamp DESC LIMIT 1`;
 		if (runs.length === 0) return Option.none();
-		const runId = runs[0].id;
+		const runId = yield* resolveCoverageRunId(runs[0].id);
 		const fileCoverageRows = yield* sql`SELECT f.path as file_path, fc.statements, fc.branches, fc.functions, fc.lines, fc.uncovered_lines, fc.tier
 					FROM file_coverage fc JOIN files f ON f.id = fc.file_id
 					WHERE fc.run_id = ${runId}`;

package/layers/DataStoreLive.js

@@ -1,7 +1,7 @@
 import { DataStore, INLINE_ATTACHMENT_BODY_CAP_BYTES } from "../services/DataStore.js";
-import { PersistBatch } from "../utils/persist-transaction.js";
+import { PersistBatch, withPersistSavepoint } from "../utils/persist-transaction.js";
 import { Agent, AgentNotFoundError, BehaviorNotFoundError, DataStoreError, GoalNotFoundError, IdempotencyHit, IllegalStatusTransitionError, RegistrationConflictError, TddTaskAlreadyEndedError, TddTaskNotFoundError, coerceErrorText, extractSqlReason } from "@vitest-agent/sdk";
-import { Effect, Layer, Option } from "effect";
+import { Clock, Effect, Layer, Option } from "effect";
 import { SqlClient } from "effect/sql/SqlClient";
 import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
@@ -36,6 +36,7 @@ const boolToInt = (v) => v === void 0 ? null : v ? 1 : 0;
 const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 	const sql = yield* SqlClient;
 	yield* sql`PRAGMA foreign_keys=ON`.pipe(Effect.catch(() => Effect.void));
+	const savepoint = (effect) => withPersistSavepoint(effect).pipe(Effect.provideService(SqlClient, sql));
 	const ensureFile = (filePath) => Effect.gen(function* () {
 		yield* Effect.logDebug("ensureFile").pipe(Effect.annotateLogs({ filePath }));
 		const batch = yield* PersistBatch;
@@ -275,7 +276,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 	* enforced Vitest thresholds or the aspirational coverageTargets
 	* (issue #237).
 	*/
-	const writeCoveragePolicy = (kind, policy) => sql.withTransaction(Effect.gen(function* () {
+	const writeCoveragePolicy = (kind, policy) => savepoint(Effect.gen(function* () {
 		yield* Effect.logDebug("writeCoveragePolicy").pipe(Effect.annotateLogs({ kind }));
 		const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const { global: g, patterns = [] } = policy;
@@ -427,7 +428,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 		table: "sessions",
 		reason: extractSqlReason(e)
 	})));
-	const writeTurn = (input) => sql.withTransaction(Effect.gen(function* () {
+	const writeTurn = (input) => savepoint(Effect.gen(function* () {
 		yield* Effect.logDebug("writeTurn").pipe(Effect.annotateLogs({
 			sessionId: input.sessionId,
 			type: input.type
@@ -533,7 +534,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 		table: "hypotheses",
 		reason: extractSqlReason(e)
 	})));
-	const writeTddTask = (input) => sql.withTransaction(Effect.gen(function* () {
+	const writeTddTask = (input) => savepoint(Effect.gen(function* () {
 		yield* Effect.logDebug("writeTddTask").pipe(Effect.annotateLogs({
 			sessionId: input.sessionId,
 			goal: input.goal
@@ -797,7 +798,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 			reason: extractSqlReason(e)
 		})));
 	});
-	const createBehavior = (input) => sql.withTransaction(Effect.gen(function* () {
+	const createBehavior = (input) => savepoint(Effect.gen(function* () {
 		yield* Effect.logDebug("createBehavior").pipe(Effect.annotateLogs({
 			goalId: input.goalId,
 			behavior: input.behavior
@@ -836,7 +837,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 		table: "tdd_session_behaviors",
 		reason: extractSqlReason(e)
 	})));
-	const updateBehavior = (input) => sql.withTransaction(Effect.gen(function* () {
+	const updateBehavior = (input) => savepoint(Effect.gen(function* () {
 		yield* Effect.logDebug("updateBehavior").pipe(Effect.annotateLogs({ id: input.id }));
 		const existing = yield* sql`
 							SELECT id, goal_id, ordinal, behavior, suggested_test_name, status, created_at
@@ -1113,6 +1114,82 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 		table: "turns",
 		reason: extractSqlReason(e)
 	})));
+	const pruneRuns = (policy) => Effect.gen(function* () {
+		yield* Effect.logDebug("pruneRuns").pipe(Effect.annotateLogs({
+			keepRuns: policy.keepRuns,
+			maxAgeDays: policy.maxAgeDays ?? null
+		}));
+		const now = yield* Clock.currentTimeMillis;
+		const cutoff = policy.maxAgeDays === void 0 ? null : (/* @__PURE__ */ new Date(now - policy.maxAgeDays * 24 * 60 * 60 * 1e3)).toISOString();
+		yield* sql`CREATE TEMP TABLE IF NOT EXISTS prune_doomed_runs (id INTEGER PRIMARY KEY)`;
+		yield* sql`DELETE FROM prune_doomed_runs`;
+		yield* sql`
+					INSERT INTO prune_doomed_runs (id)
+					SELECT id FROM (
+						SELECT id, timestamp,
+							ROW_NUMBER() OVER (PARTITION BY project ORDER BY timestamp DESC, id DESC) AS rn
+						FROM test_runs
+					)
+					WHERE rn > ${policy.keepRuns} OR (${cutoff} IS NOT NULL AND timestamp < ${cutoff})`;
+		yield* sql`
+					WITH sources AS (
+						SELECT tr.invocation_id, MIN(tr.id) AS from_run_id
+						FROM test_runs tr
+						JOIN prune_doomed_runs d ON d.id = tr.id
+						WHERE EXISTS (SELECT 1 FROM file_coverage fc WHERE fc.run_id = tr.id)
+						GROUP BY tr.invocation_id
+					),
+					moves AS (
+						SELECT s.from_run_id,
+							(SELECT MIN(tr2.id) FROM test_runs tr2
+								WHERE tr2.invocation_id = s.invocation_id
+									AND tr2.id NOT IN (SELECT id FROM prune_doomed_runs)) AS to_run_id
+						FROM sources s
+						WHERE NOT EXISTS (
+							SELECT 1 FROM file_coverage fc2
+							JOIN test_runs tr3 ON tr3.id = fc2.run_id
+							WHERE tr3.invocation_id = s.invocation_id
+								AND tr3.id NOT IN (SELECT id FROM prune_doomed_runs)
+						)
+					)
+					UPDATE file_coverage
+					SET run_id = (SELECT to_run_id FROM moves WHERE moves.from_run_id = file_coverage.run_id)
+					WHERE run_id IN (SELECT from_run_id FROM moves WHERE to_run_id IS NOT NULL)`;
+		const deletedRuns = yield* sql`
+					DELETE FROM test_runs WHERE id IN (SELECT id FROM prune_doomed_runs) RETURNING id`;
+		yield* sql`DELETE FROM prune_doomed_runs`;
+		if (deletedRuns.length === 0) return {
+			prunedRuns: 0,
+			prunedFiles: 0
+		};
+		const deletedFiles = yield* sql`
+					DELETE FROM files WHERE
+						NOT EXISTS (SELECT 1 FROM test_modules WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM scoped_files WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM file_coverage WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM stack_frames WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM test_annotations WHERE location_file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM test_artifacts WHERE location_file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM import_durations WHERE file_id = files.id OR importer_file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM source_test_map WHERE source_file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM file_edits WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM run_changed_files WHERE file_id = files.id)
+						AND NOT EXISTS (SELECT 1 FROM tdd_artifacts WHERE file_id = files.id)
+					RETURNING id`;
+		const batch = yield* PersistBatch;
+		if (batch !== void 0 && deletedFiles.length > 0) {
+			const gone = new Set(deletedFiles.map((row) => row.id));
+			for (const [path, id] of batch.fileIds) if (gone.has(id)) batch.fileIds.delete(path);
+		}
+		return {
+			prunedRuns: deletedRuns.length,
+			prunedFiles: deletedFiles.length
+		};
+	}).pipe(Effect.annotateLogs("service", "DataStore"), Effect.mapError((e) => new DataStoreError({
+		operation: "write",
+		table: "test_runs",
+		reason: extractSqlReason(e)
+	})));
 	const associateLatestRunWithSession = (input) => Effect.gen(function* () {
 		yield* Effect.logDebug("associateLatestRunWithSession").pipe(Effect.annotateLogs({
 			chatId: input.chatId,
@@ -1288,6 +1365,7 @@ const DataStoreLive = Layer.effect(DataStore, Effect.gen(function* () {
 		writeRunChangedFiles,
 		recordIdempotentResponse,
 		pruneSessions,
+		pruneRuns,
 		associateLatestRunWithSession,
 		backfillTestCaseTurns,
 		registerAgent,

package/migrations/0003_run_retention.js

@@ -0,0 +1,66 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql/SqlClient";
+
+// src/migrations/0003_run_retention.ts
+/** @internal */
+const migration = Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	yield* sql`
+		CREATE TABLE test_history_new (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			run_id INTEGER REFERENCES test_runs(id) ON DELETE SET NULL,
+			project TEXT NOT NULL,
+			module_path TEXT NOT NULL,
+			full_name TEXT NOT NULL,
+			timestamp TEXT NOT NULL,
+			state TEXT NOT NULL CHECK (state IN ('passed', 'failed', 'skipped', 'pending')),
+			duration INTEGER,
+			flaky INTEGER CHECK (flaky IN (0, 1)),
+			retry_count INTEGER DEFAULT 0,
+			error_message TEXT,
+			UNIQUE(project, module_path, full_name, timestamp)
+		)
+	`;
+	yield* sql`
+		INSERT INTO test_history_new (id, run_id, project, module_path, full_name, timestamp, state, duration, flaky, retry_count, error_message)
+		SELECT id, run_id, project, module_path, full_name, timestamp, state, duration, flaky, retry_count, error_message
+		FROM test_history
+	`;
+	yield* sql`DROP INDEX IF EXISTS idx_test_history_lookup`;
+	yield* sql`DROP INDEX IF EXISTS idx_test_history_full_name`;
+	yield* sql`DROP INDEX IF EXISTS idx_test_history_run`;
+	yield* sql`DROP TABLE test_history`;
+	yield* sql`ALTER TABLE test_history_new RENAME TO test_history`;
+	yield* sql`CREATE INDEX idx_test_history_lookup ON test_history(project, module_path, full_name)`;
+	yield* sql`CREATE INDEX idx_test_history_full_name ON test_history(full_name, timestamp)`;
+	yield* sql`CREATE INDEX idx_test_history_run ON test_history(run_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_runs_project_timestamp ON test_runs(project, timestamp)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_modules_file ON test_modules(file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_scoped_files_file ON scoped_files(file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_stack_frames_file ON stack_frames(file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_annotations_file ON test_annotations(location_file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_artifacts_file ON test_artifacts(location_file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_import_durations_file ON import_durations(file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_tdd_artifacts_file ON tdd_artifacts(file_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_tdd_artifacts_test_run ON tdd_artifacts(test_run_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_tdd_artifacts_first_failure_run ON tdd_artifacts(test_first_failure_run_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_failure_signatures_first_seen_run ON failure_signatures(first_seen_run_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_suites_parent ON test_suites(parent_suite_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_errors_suite ON test_errors(test_suite_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_errors_module ON test_errors(module_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_test_errors_cause ON test_errors(cause_error_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_tdd_artifacts_test_case ON tdd_artifacts(test_case_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_task_metadata_case ON task_metadata(test_case_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_task_metadata_suite ON task_metadata(test_suite_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_task_metadata_module ON task_metadata(module_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hook_executions_module ON hook_executions(test_module_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hook_executions_suite ON hook_executions(test_suite_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hook_executions_case ON hook_executions(test_case_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hook_executions_error ON hook_executions(error_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_attachments_artifact ON attachments(artifact_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_attachments_annotation ON attachments(annotation_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hypotheses_cited_error ON hypotheses(cited_test_error_id)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_hypotheses_cited_frame ON hypotheses(cited_stack_frame_id)`;
+});
+
+export { migration as default };

package/migrations/index.js

@@ -1,5 +1,6 @@
 import migration from "./0001_initial.js";
 import migration$1 from "./0002_test_artifacts.js";
+import migration$2 from "./0003_run_retention.js";
 
 // src/migrations/index.ts
 /**
@@ -21,7 +22,8 @@ import migration$1 from "./0002_test_artifacts.js";
 */
 const PROJECT_MIGRATIONS = {
 	"0001_initial": migration,
-	"0002_test_artifacts": migration$1
+	"0002_test_artifacts": migration$1,
+	"0003_run_retention": migration$2
 };
 
 export { PROJECT_MIGRATIONS };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/engine",
-	"version": "1.1.2",
+	"version": "1.2.0",
 	"private": false,
 	"description": "Shared services, layers, SQLite data layer, migrations and platform resolution for the vitest-agent CLI and MCP server.",
 	"keywords": [
@@ -55,7 +55,7 @@
 		"@effected/workspaces": "^0.38.0",
 		"@effected/xdg": "^0.14.1",
 		"@effected/yaml": "^0.25.0",
-		"@vitest-agent/sdk": "7.0.5",
+		"@vitest-agent/sdk": "7.1.0",
 		"effect": "^4.0.6"
 	},
 	"engines": {

package/testing.d.ts

@@ -1,4 +1,4 @@
-import { Agent, Agent as Agent$1, AgentId, AgentNotFoundError, AgentNotFoundError as AgentNotFoundError$1, AgentReport, AgentReport as AgentReport$1, ArtifactKind, ArtifactKind as ArtifactKind$1, ArtifactKind as ArtifactKind$2, ArtifactSuite, ArtifactSuite as ArtifactSuite$1, ArtifactSuite as ArtifactSuite$2, BehaviorDetail, BehaviorDetail as BehaviorDetail$1, BehaviorNotFoundError, BehaviorNotFoundError as BehaviorNotFoundError$1, BehaviorRow, BehaviorRow as BehaviorRow$1, BehaviorStatus, BehaviorStatus as BehaviorStatus$1, CacheManifest, CacheManifest as CacheManifest$1, ChatId, CitedArtifact, CitedArtifact as CitedArtifact$1, CoverageBaselines, CoverageBaselines as CoverageBaselines$1, CoverageReport, CoverageReport as CoverageReport$1, DataStoreError, DataStoreError as DataStoreError$1, FileCoverageReport, FileCoverageReport as FileCoverageReport$1, GoalDetail, GoalDetail as GoalDetail$1, GoalNotFoundError, GoalNotFoundError as GoalNotFoundError$1, GoalRow, GoalRow as GoalRow$1, GoalStatus, GoalStatus as GoalStatus$1, HistoryRecord, HistoryRecord as HistoryRecord$1, IdempotencyHit, IdempotencyHit as IdempotencyHit$1, IllegalStatusTransitionEntity, IllegalStatusTransitionError, IllegalStatusTransitionError as IllegalStatusTransitionError$1, Phase, Phase as Phase$1, RegistrationConflictError, RegistrationConflictError as RegistrationConflictError$1, ResolvedThresholds, ResolvedThresholds as ResolvedThresholds$1, TddTaskAlreadyEndedError, TddTaskAlreadyEndedError as TddTaskAlreadyEndedError$1, TddTaskEndOutcome, TddTaskNotFoundError, TddTaskNotFoundError as TddTaskNotFoundError$1, TrendEntry, TrendEntry as TrendEntry$1, TrendRecord, TrendRecord as TrendRecord$1 } from "@vitest-agent/sdk";
+import { Agent, Agent as Agent$1, AgentId, AgentNotFoundError, AgentNotFoundError as AgentNotFoundError$1, AgentReport, AgentReport as AgentReport$1, ArtifactKind, ArtifactKind as ArtifactKind$1, ArtifactKind as ArtifactKind$2, ArtifactSuite, ArtifactSuite as ArtifactSuite$1, ArtifactSuite as ArtifactSuite$2, BehaviorDetail, BehaviorDetail as BehaviorDetail$1, BehaviorNotFoundError, BehaviorNotFoundError as BehaviorNotFoundError$1, BehaviorRow, BehaviorRow as BehaviorRow$1, BehaviorStatus, BehaviorStatus as BehaviorStatus$1, CacheManifest, CacheManifest as CacheManifest$1, ChatId, CitedArtifact, CitedArtifact as CitedArtifact$1, CoverageBaselines, CoverageBaselines as CoverageBaselines$1, CoverageReport, CoverageReport as CoverageReport$1, DataStoreError, DataStoreError as DataStoreError$1, FileCoverageReport, FileCoverageReport as FileCoverageReport$1, GoalDetail, GoalDetail as GoalDetail$1, GoalNotFoundError, GoalNotFoundError as GoalNotFoundError$1, GoalRow, GoalRow as GoalRow$1, GoalStatus, GoalStatus as GoalStatus$1, HistoryRecord, HistoryRecord as HistoryRecord$1, IdempotencyHit, IdempotencyHit as IdempotencyHit$1, IllegalStatusTransitionEntity, IllegalStatusTransitionError, IllegalStatusTransitionError as IllegalStatusTransitionError$1, Phase, Phase as Phase$1, RegistrationConflictError, RegistrationConflictError as RegistrationConflictError$1, ResolvedThresholds, ResolvedThresholds as ResolvedThresholds$1, RunRetentionPolicy, RunRetentionPolicy as RunRetentionPolicy$1, TddTaskAlreadyEndedError, TddTaskAlreadyEndedError as TddTaskAlreadyEndedError$1, TddTaskEndOutcome, TddTaskNotFoundError, TddTaskNotFoundError as TddTaskNotFoundError$1, TrendEntry, TrendEntry as TrendEntry$1, TrendRecord, TrendRecord as TrendRecord$1 } from "@vitest-agent/sdk";
 import { Context, Effect, Layer, Option } from "effect";
 import "@effect/platform-node/NodeServices";
 import "@effect/sql-sqlite-node/SqliteClient";
@@ -408,6 +408,15 @@ interface RegisterAgentInput {
    */
   readonly agentId?: string;
 }
+/**
+ * What `DataStore.pruneRuns` removed: `test_runs` rows deleted (their
+ * cascaded rows are not counted) and orphaned `files` rows garbage-collected.
+ * @public
+ */
+interface PruneRunsResult {
+  readonly prunedRuns: number;
+  readonly prunedFiles: number;
+}
 /** @public */
 interface AssociateRunSessionInput {
   readonly chatId: string;
@@ -505,6 +514,25 @@ declare const DataStore_base: Context.ServiceClass<DataStore, "vitest-agent/Data
     readonly affectedSessions: number;
     readonly prunedTurns: number;
   }, DataStoreError$1>;
+  /**
+   * Apply a run-retention policy: delete every `test_runs` row beyond the
+   * newest `policy.keepRuns` of its project, and any run older than
+   * `policy.maxAgeDays` days when set, letting the schema's cascades drop
+   * the dependent rows (modules, suites, cases, tags, errors, frames,
+   * coverage, trends, triggers), then garbage-collect `files` rows no
+   * table references any more. `test_history` rows survive with a NULL
+   * `run_id`; they keep their own newest-10-per-series window. Before
+   * the delete, `file_coverage` rows held by a doomed run are moved onto
+   * the lowest surviving run of the same invocation (coverage is written
+   * once per invocation, issue 622) unless a survivor already carries
+   * coverage rows, so every sibling project's coverage read stays whole.
+   *
+   * A handful of synchronous statements on the open connection, no
+   * yielding, so it may run inside `withPersistTransaction` after the
+   * run's own rows are written: the run just written is the newest of
+   * its project and is never pruned.
+   */
+  readonly pruneRuns: (policy: RunRetentionPolicy$1) => Effect.Effect<PruneRunsResult, DataStoreError$1>;
   readonly associateLatestRunWithSession: (input: AssociateRunSessionInput) => Effect.Effect<void, DataStoreError$1>;
   readonly backfillTestCaseTurns: (chatId: string) => Effect.Effect<number, DataStoreError$1>;
   /**
@@ -1085,6 +1113,7 @@ type PlatformLiveError = SqlError | StoreError | StoreMigrationError;
 export declare const PROJECT_MIGRATIONS: {
   readonly "0001_initial": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
   readonly "0002_test_artifacts": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
+  readonly "0003_run_retention": import("effect/Effect").Effect<void, import("effect/sql/SqlError").SqlError, import("effect/sql/SqlClient").SqlClient>;
 };
 /** @public */
 export declare function makeTestLayer(filename: string): Layer.Layer<DataReader | DataStore | import("effect/sql/SqlClient").SqlClient | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | import("@effect/platform-node/NodeServices").NodeServices, PlatformLiveError, never>;
@@ -1100,5 +1129,5 @@ export declare function withFailures(filename: string): Layer.Layer<DataReader |
 export declare function flaky(filename: string): Layer.Layer<DataReader | DataStore | import("effect/sql/SqlClient").SqlClient | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | import("@effect/platform-node/NodeServices").NodeServices, import("@vitest-agent/sdk").DataStoreError | PlatformLiveError, never>;
 /** @public */
 export declare function withTddTask(filename: string): Layer.Layer<DataReader | DataStore | import("effect/sql/SqlClient").SqlClient | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | import("@effect/platform-node/NodeServices").NodeServices, import("@vitest-agent/sdk").BehaviorNotFoundError | import("@vitest-agent/sdk").DataStoreError | import("@vitest-agent/sdk").GoalNotFoundError | import("@vitest-agent/sdk").IllegalStatusTransitionError | import("@vitest-agent/sdk").TddTaskAlreadyEndedError | import("@vitest-agent/sdk").TddTaskNotFoundError | PlatformLiveError, never>;
-export { type AcceptanceMetrics, Agent, AgentId, AgentNotFoundError, AgentReport, type ArtifactKind, type ArtifactSuite, type AssociateRunSessionInput, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, type ChangeKind, ChatId, type CitedArtifact, type CitedArtifactRow, type ClassificationQueryOptions, type CommitChangesEntry, CoverageBaselines, CoverageReport, type CreateBehaviorInput, type CreateGoalInput, type CurrentTddPhase, DataStoreError, type EndTddTaskInput, type FailureSignatureDetail, type FailureSignatureWriteInput, type FileCoverageInput, FileCoverageReport, type FlakyTest, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, type HistoryQueryOptions, HistoryRecord, type HypothesisDetail, type HypothesisInput, IdempotencyHit, type IdempotentResponseInput, type IllegalStatusTransitionEntity, IllegalStatusTransitionError, type ModuleInput, type ModuleListEntry, type NoteInput, type NoteRow, type PersistedAttachment, type PersistentFailure, type Phase, type PlatformLiveError, type ProjectRunSummary, type RegisterAgentInput, RegistrationConflictError, type ResolvedThresholds, type RunChangedFile, type RunInvocationMethod, type SessionDetail, type SessionInput, type SettingsInput, type SettingsListEntry, type SettingsRow, type StackFrameInput, type SuiteInput, type SuiteListEntry, type TagInventoryRow, type TddArtifactDetail, type TddArtifactRow, type TddPhaseDetail, TddTaskAlreadyEndedError, type TddTaskDetail, type TddTaskEndOutcome, type TddTaskInput, TddTaskNotFoundError, type TddTaskSummary, type TestAnnotationInput, type TestAnnotationRow, type TestArtifactInput, type TestArtifactQueryOptions, type TestArtifactRow, type TestAttachmentInput, type TestCaseInput, type TestError, type TestErrorInput, type TestListEntry, type TestLookupOptions, type TestRunInput, TrendEntry, TrendRecord, type TurnInput, type TurnSearchOptions, type TurnSummary, type UpdateBehaviorInput, type UpdateGoalInput, type ValidateHypothesisInput, type WriteCommitInput, type WriteRunChangedFilesInput, type WriteTddArtifactInput, type WriteTddPhaseInput, type WriteTddPhaseOutput };
+export { type AcceptanceMetrics, Agent, AgentId, AgentNotFoundError, AgentReport, type ArtifactKind, type ArtifactSuite, type AssociateRunSessionInput, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, type ChangeKind, ChatId, type CitedArtifact, type CitedArtifactRow, type ClassificationQueryOptions, type CommitChangesEntry, CoverageBaselines, CoverageReport, type CreateBehaviorInput, type CreateGoalInput, type CurrentTddPhase, DataStoreError, type EndTddTaskInput, type FailureSignatureDetail, type FailureSignatureWriteInput, type FileCoverageInput, FileCoverageReport, type FlakyTest, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, type HistoryQueryOptions, HistoryRecord, type HypothesisDetail, type HypothesisInput, IdempotencyHit, type IdempotentResponseInput, type IllegalStatusTransitionEntity, IllegalStatusTransitionError, type ModuleInput, type ModuleListEntry, type NoteInput, type NoteRow, type PersistedAttachment, type PersistentFailure, type Phase, type PlatformLiveError, type ProjectRunSummary, type PruneRunsResult, type RegisterAgentInput, RegistrationConflictError, type ResolvedThresholds, type RunChangedFile, type RunInvocationMethod, RunRetentionPolicy, type SessionDetail, type SessionInput, type SettingsInput, type SettingsListEntry, type SettingsRow, type StackFrameInput, type SuiteInput, type SuiteListEntry, type TagInventoryRow, type TddArtifactDetail, type TddArtifactRow, type TddPhaseDetail, TddTaskAlreadyEndedError, type TddTaskDetail, type TddTaskEndOutcome, type TddTaskInput, TddTaskNotFoundError, type TddTaskSummary, type TestAnnotationInput, type TestAnnotationRow, type TestArtifactInput, type TestArtifactQueryOptions, type TestArtifactRow, type TestAttachmentInput, type TestCaseInput, type TestError, type TestErrorInput, type TestListEntry, type TestLookupOptions, type TestRunInput, TrendEntry, TrendRecord, type TurnInput, type TurnSearchOptions, type TurnSummary, type UpdateBehaviorInput, type UpdateGoalInput, type ValidateHypothesisInput, type WriteCommitInput, type WriteRunChangedFilesInput, type WriteTddArtifactInput, type WriteTddPhaseInput, type WriteTddPhaseOutput };
 //# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -2,7 +2,7 @@ import { DataReader } from "./services/DataReader.js";
 import { DataStore } from "./services/DataStore.js";
 import { PROJECT_MIGRATIONS } from "./migrations/index.js";
 import { DataStoreTestLayer, makeTestLayer } from "./testing/layers.js";
-import { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataStoreError, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, RegistrationConflictError, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord } from "@vitest-agent/sdk";
+import { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataStoreError, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, RegistrationConflictError, RunRetentionPolicy, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord } from "@vitest-agent/sdk";
 import { Effect, Layer } from "effect";
 
 // src/testing/index.ts
@@ -239,4 +239,4 @@ function withTddTask(filename) {
 	return Layer.effectDiscard(seed).pipe(Layer.provideMerge(base));
 }
 
-export { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataReader, DataStore, DataStoreError, DataStoreTestLayer, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, PROJECT_MIGRATIONS, RegistrationConflictError, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord, empty, flaky, makeTestLayer, singlePassingRun, withFailures, withTddTask };
+export { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataReader, DataStore, DataStoreError, DataStoreTestLayer, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, PROJECT_MIGRATIONS, RegistrationConflictError, RunRetentionPolicy, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord, empty, flaky, makeTestLayer, singlePassingRun, withFailures, withTddTask };

package/utils/persist-transaction.js

@@ -1,5 +1,5 @@
 import { DataStoreError, extractSqlReason } from "@vitest-agent/sdk";
-import { Context, Effect, References } from "effect";
+import { Context, Effect, Exit, References } from "effect";
 import { SqlClient } from "effect/sql/SqlClient";
 import { isSqlError } from "effect/sql/SqlError";
 
@@ -11,6 +11,55 @@ import { isSqlError } from "effect/sql/SqlError";
 * @internal
 */
 const PersistBatch = Context.Reference("@vitest-agent/engine/PersistBatch", { defaultValue: () => void 0 });
+/**
+* Drop every entry added after `size`. The caches only ever grow (an id for
+* a name never changes while the write lock is held), and a `Map` / `Set`
+* iterates in insertion order, so the entries past the snapshot size are
+* exactly the ones a rolled-back savepoint added.
+*/
+const truncate = (collection, size) => {
+	if (collection.size <= size) return;
+	let index = 0;
+	for (const key of collection.keys()) if (index++ >= size) collection.delete(key);
+};
+/**
+* Run `effect` as a nested transaction that keeps the
+* {@link withPersistTransaction} caches honest.
+*
+* Outside a persist batch this is exactly `sql.withTransaction(effect)`.
+* Inside one, the nested `withTransaction` becomes a SAVEPOINT, and when it
+* rolls back (a failure, a defect, an interrupt) every `files` / `tags` row
+* the savepoint inserted is gone while the ids `DataStoreLive` cached for
+* them would survive in `PersistBatchState`. This helper snapshots the
+* cache sizes before the savepoint opens and discards the entries added
+* since whenever it does not commit, so a later write in the same batch
+* re-inserts the row instead of referencing one that no longer exists
+* (issue #628: a FK failure or a dangling id). A savepoint that commits
+* keeps its entries.
+*
+* Use this, never a bare `sql.withTransaction`, for any nested transaction
+* whose failure a caller may catch and continue from inside the batch; a
+* bare one that rolls back leaves the caches stale. The bookkeeping is
+* synchronous, so the batch's no-yield guarantee is unchanged.
+*
+* @param effect - the writes to run as one savepoint (or transaction)
+* @public
+*/
+const withPersistSavepoint = (effect) => Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	const batch = yield* PersistBatch;
+	if (batch === void 0) return yield* sql.withTransaction(effect);
+	const snapshot = {
+		historyRunIds: batch.historyRunIds.size,
+		tagIds: batch.tagIds.size,
+		fileIds: batch.fileIds.size
+	};
+	return yield* sql.withTransaction(effect).pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Effect.sync(() => {
+		truncate(batch.historyRunIds, snapshot.historyRunIds);
+		truncate(batch.tagIds, snapshot.tagIds);
+		truncate(batch.fileIds, snapshot.fileIds);
+	})));
+});
 /** Matches the per-write window `DataStoreLive.writeHistory` keeps outside a batch. */
 const HISTORY_WINDOW = 10;
 /**
@@ -53,8 +102,13 @@ const pruneHistoryForRun = (sql, runId) => sql`DELETE FROM test_history WHERE id
 * genuinely asynchronous work for that reason; CPU-heavy work that needs no
 * database belongs before the block.
 *
-* Nested `withTransaction` calls inside `effect` become savepoints. A
-* `DataReader` query inside it runs on the transaction's connection.
+* Nested `withTransaction` calls inside `effect` become savepoints. Open
+* them through {@link withPersistSavepoint}: a savepoint that rolls back
+* also discards the tag / file ids cached while it was open, so a write the
+* caller recovers from cannot leave a later write pointing at a row the
+* rollback removed. A bare nested `sql.withTransaction` whose failure is
+* caught inside the block leaves those caches stale. A `DataReader` query
+* inside the block runs on the transaction's connection.
 *
 * @param effect - the writes (and the reads they depend on) to run atomically
 * @public
@@ -81,4 +135,4 @@ const withPersistTransaction = (effect) => Effect.gen(function* () {
 	reason: extractSqlReason(e)
 }))));
 
-export { PersistBatch, withPersistTransaction };
+export { PersistBatch, withPersistSavepoint, withPersistTransaction };

package/version.js

@@ -1,5 +1,5 @@
 // src/version.ts
 /** Build-time injected package version (see architecture.md D36). @public */
-const CURRENT_ENGINE_VERSION = "1.1.2";
+const CURRENT_ENGINE_VERSION = "1.2.0";
 
 export { CURRENT_ENGINE_VERSION };