@vitest-agent/plugin 5.4.9 → 5.6.0

package/index.d.ts

@@ -1,6 +1,6 @@
 import "@effected/env";
 import { EnvironmentDetector, PlatformLiveError, PlatformOptions, PlatformServices, SettingsInput, StackFrameInput } from "@vitest-agent/engine";
-import { AgentPluginOptions, AgentReporterOptions, ConsoleMode, CoverageBaselines, CoverageInput, CoverageLevel, CoverageLevelName, CoverageLevelName as CoverageLevelName$1, CoverageReport, ResolvedReporterConfig, ResolvedThresholds, RunEvent, Transport, VitestAgentReporterFactory, resolveCoverageInput, validateCoverageConfig } from "@vitest-agent/sdk";
+import { AgentPluginOptions, AgentReporterOptions, ConsoleMode, CoverageBaselines, CoverageInput, CoverageLevel, CoverageLevelName, CoverageLevelName as CoverageLevelName$1, CoverageReport, ResolvedReporterConfig, ResolvedThresholds, RunEvent, RunRetentionPolicy, SuggestedActionRecord, Transport, VitestAgentReporterFactory, resolveCoverageInput, validateCoverageConfig } from "@vitest-agent/sdk";
 import { Context, Effect, Layer, Option } from "effect";
 import { TestProjectInlineConfiguration, TestTagDefinition } from "vitest/config";
 import { ResolvedConfig, VitestPluginContext } from "vitest/node";
@@ -263,7 +263,51 @@ interface DiscoverProjectsOptions {
    * Forwarded to `@effected/workspaces`' `getWorkspacePackagesSync`.
    */
   readonly maxDepth?: number;
+  /**
+   * Per-project `test` overrides keyed by project name (the workspace
+   * package name, or an `additionalEntries` name). Each value is shallow-merged
+   * over the generated project's `test` block after the strategy has built it;
+   * `name` is never replaced. A key naming no discovered project throws, so a
+   * typo cannot silently leave a project on its defaults. Supplying this
+   * bypasses the process-level result cache.
+   */
+  readonly configure?: ProjectConfigureMap;
 }
+/**
+ * The Vitest `test` fields a `configure` entry may set on one generated
+ * project — everything Vitest accepts on a project's inline `test` block
+ * except `name`, which stays the discovered project's own.
+ *
+ * @remarks
+ * The typical use is pool scheduling per project: `{ isolate: false }` for a
+ * package whose suites share no module-level state, while a package that
+ * spawns processes or calls `process.chdir()` keeps the root's forks plus
+ * isolation (issue #626). The merge is shallow: an `include` or `exclude` here
+ * replaces the strategy's list rather than appending to it.
+ * @public
+ */
+type ProjectTestOverrides = Omit<NonNullable<TestProjectInlineConfiguration["test"]>, "name">;
+/**
+ * Project name to {@link ProjectTestOverrides}, as passed to `configure`.
+ * @public
+ */
+type ProjectConfigureMap = Readonly<Record<string, ProjectTestOverrides>>;
+/**
+ * Shallow-merges each `overrides` entry into the generated project whose
+ * `test.name` equals the entry's key. Pure: returns new project objects for the
+ * configured names and the original objects for the rest; the discovered
+ * `name` always wins over one carried by the override. Only a string
+ * `test.name` can be keyed; a project named through Vitest's object form is
+ * left untouched (and a key for it is reported as unknown).
+ *
+ * Throws when a key names no project in `configs`, listing the discovered
+ * names so the typo is visible at config-load time.
+ * @param configs - The projects a strategy produced
+ * @param overrides - Per-project `test` overrides keyed by project name
+ * @returns The projects with overrides applied
+ * @public
+ */
+export declare function applyProjectOverrides(configs: ReadonlyArray<TestProjectInlineConfiguration>, overrides: ProjectConfigureMap): TestProjectInlineConfiguration[];
 /**
  * Scan all workspace packages and additional entries through the active strategy and return projects + tags.
  * @param options - Optional strategy, working directory, and extra project entries
@@ -464,16 +508,28 @@ export declare namespace AgentPlugin {
    * };
    * ```
    *
+   * Per-project `test` overrides ride the options object's `configure` map,
+   * keyed by project name and shallow-merged over the generated project's
+   * `test` block (`name` is never replaced); an unknown key throws. The
+   * typical use is per-package pool scheduling (issue #626):
+   *
+   * ```ts
+   * const { projects, tags } = await AgentPlugin.discover({
+   *   configure: { "@acme/pure-lib": { isolate: false } },
+   * });
+   * ```
+   *
    * @param strategy - Optional strategy or options object
-   *   `{ strategy?, cwd?, maxDepth? }`.
+   *   `{ strategy?, cwd?, maxDepth?, configure? }`.
    *   Pass a {@link DiscoverStrategy} directly, or an options object to also
-   *   specify a custom workspace root via `cwd` and deeper package traversal via
-   *   `maxDepth`.
+   *   specify a custom workspace root via `cwd`, deeper package traversal via
+   *   `maxDepth`, and per-project `test` overrides via `configure`.
    */
   function discover(strategy?: DiscoverStrategy | {
     strategy?: DiscoverStrategy;
     cwd?: string;
     maxDepth?: number;
+    configure?: ProjectConfigureMap;
   }): DiscoverBuilder;
   /**
    * Run a shell command, suppressing all output unless the command fails.
@@ -545,6 +601,18 @@ interface AgentReporterConstructorOptions extends AgentReporterOptions {
    * @internal
    */
   coverageMode?: "full" | "ui-only";
+  /**
+   * Whether the run is recorded in SQLite (issue #625). The plugin
+   * resolves it from `AgentPlugin({ persist })` and the
+   * `VITEST_AGENT_PERSIST` operator override; defaults to `true` when
+   * `AgentReporter` is constructed directly. `false` routes
+   * `onTestRunEnd` through the same DB-free path UI-only mode uses —
+   * every render and `RunEvent` still happens, coverage is still
+   * analyzed, and `data.db` is never resolved, created or opened.
+   *
+   * @internal
+   */
+  persist?: boolean;
   consoleMode?: ConsoleMode;
   mcp?: boolean;
   githubActions?: boolean;
@@ -563,6 +631,17 @@ interface AgentReporterConstructorOptions extends AgentReporterOptions {
    * `run_tests` tool.
    */
   passWithNoTests?: boolean;
+  /**
+   * Run-level suggested actions the plugin resolved at config time — the
+   * `ConfigValidation` warnings and info entries, mapped onto
+   * `SuggestedActionRecord`s (issue #544). Forwarded verbatim onto
+   * `ReporterRenderInput.suggestedActions` for every render, so the
+   * `Actions:` trailer repeats them in watch mode. Absent when the config
+   * validated clean.
+   *
+   * @internal
+   */
+  suggestedActions?: ReadonlyArray<SuggestedActionRecord>;
   coverageThresholds?: ResolvedThresholds | Record<string, unknown>;
   coverageTargets?: ResolvedThresholds | Record<string, unknown>;
   /**
@@ -574,6 +653,17 @@ interface AgentReporterConstructorOptions extends AgentReporterOptions {
    * @internal
    */
   cacheDir?: string;
+  /**
+   * Run-retention override (issue 623). A `RunRetentionPolicy` is applied
+   * as given; `false` disables run pruning for this reporter; absent means
+   * the policy the `[retention]` table of `vitest-agent.config.toml`
+   * resolves to (the default of `RunRetentionPolicy.DEFAULT_KEEP_RUNS`
+   * newest runs per project when the table is absent). Takes precedence
+   * over the TOML file, like `cacheDir` does for the database path.
+   *
+   * @internal
+   */
+  retention?: RunRetentionPolicy | false;
 }
 /**
  * Vitest Reporter that produces structured output for LLM coding agents.
@@ -628,14 +718,17 @@ export declare class AgentReporter {
   private options;
   private dbPath;
   /**
-   * Set to `true` after the first `onTestRunEnd` invocation completes.
+   * Set to `true` once `onTestRunEnd` has done this run's work.
    *
-   * Vitest can fire `onTestRunEnd` more than once per `vitest run` in
-   * some multi-project configurations (e.g., once per project group, with
-   * the same `testModules` array each time). The plugin pushes only ONE
-   * AgentReporter per run, so a fresh instance always starts with this
-   * flag `false`; the first call does the work and the flag prevents
-   * subsequent invocations from re-rendering and re-writing to the DB.
+   * Vitest can fire `onTestRunEnd` more than once per run in some
+   * multi-project configurations (e.g., once per project group, with the
+   * same `testModules` array each time). The first call does the work and
+   * the flag prevents subsequent invocations from re-rendering and
+   * re-writing to the DB. The flag is PER RUN, not per instance: Vitest
+   * keeps one reporter instance alive across watch-mode reruns, so
+   * `onTestRunStart` re-arms it — otherwise every rerun after the first
+   * would silently skip persistence, rendering and `RunFinished`
+   * (issue #576).
    */
   private rendered;
   /**
@@ -1270,6 +1363,21 @@ interface CoverageOptions {
    * production; forward or back slashes both work).
    */
   readonly root?: string;
+  /**
+   * Vitest's resolved `coverage.include` globs. When set, a coverage-map
+   * key matching none of them is dropped before any per-file or glob
+   * evaluation (issue #622). Matched like threshold patterns: against
+   * `relative(root, key)` when `root` is set, verbatim otherwise. Absent,
+   * every key is kept. A path under a `node_modules` segment is dropped
+   * regardless of this option.
+   */
+  readonly include?: ReadonlyArray<string>;
+  /**
+   * Vitest's resolved `coverage.exclude` globs. A coverage-map key matching
+   * any of them is dropped before evaluation (issue #622), with the same
+   * matching rule as `include`.
+   */
+  readonly exclude?: ReadonlyArray<string>;
 }
 declare const CoverageAnalyzer_base: Context.ServiceClass<CoverageAnalyzer, "vitest-agent/CoverageAnalyzer", {
   readonly process: (coverage: unknown, options: CoverageOptions) => Effect.Effect<Option.Option<CoverageReport>>;
@@ -1490,5 +1598,5 @@ export declare const COVERAGE_AUTOUPDATE: Readonly<{
   strict: (next: number, previous: number) => number;
   lenient: (next: number, previous: number) => number;
 }>;
-export { type AddProjectInput, type AgentPluginConstructorOptions, type AgentReporterConstructorOptions, type ClassifyContext, type ClassifyFn, type CoverageInput, CoverageLevel, type CoverageLevelName, type CoverageLevelPreset, type CoverageOptions, type DiscoverBuilder, type DiscoverInput, type PackageJson as DiscoverPackageJson, type DiscoverProjectsOptions, type DiscoverProjectsResult, type DiscoverResult, type DiscoverStrategyCreateOptions, type DiscoverStrategyExtendOptions, type InjectTagsResult, type ModuleInfo, type TagOptions, type ValidationError, type ValidationInfo, type ValidationInput, type ValidationResult, type ValidationWarning, type VitestErrorLike, type VitestStackFrameLike, type VitestThresholdsInput, type WalkerEntry, type WalkerEntryStat, type WalkerFileSystem, resolveCoverageInput, validateCoverageConfig };
+export { type AddProjectInput, type AgentPluginConstructorOptions, type AgentReporterConstructorOptions, type ClassifyContext, type ClassifyFn, type CoverageInput, CoverageLevel, type CoverageLevelName, type CoverageLevelPreset, type CoverageOptions, type DiscoverBuilder, type DiscoverInput, type PackageJson as DiscoverPackageJson, type DiscoverProjectsOptions, type DiscoverProjectsResult, type DiscoverResult, type DiscoverStrategyCreateOptions, type DiscoverStrategyExtendOptions, type InjectTagsResult, type ModuleInfo, type ProjectConfigureMap, type ProjectTestOverrides, type TagOptions, type ValidationError, type ValidationInfo, type ValidationInput, type ValidationResult, type ValidationWarning, type VitestErrorLike, type VitestStackFrameLike, type VitestThresholdsInput, type WalkerEntry, type WalkerEntryStat, type WalkerFileSystem, resolveCoverageInput, validateCoverageConfig };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -13,7 +13,7 @@ import { nodeWalkerFs } from "./utils/walker-fs.js";
 import { findTestFiles } from "./utils/find-test-files.js";
 import { Tag } from "./utils/tag.js";
 import { DefaultDiscoverStrategy, DiscoverStrategy } from "./utils/discover-strategy.js";
-import { discoverProjects } from "./utils/discover-projects.js";
+import { applyProjectOverrides, discoverProjects } from "./utils/discover-projects.js";
 import { CONSOLE_REPORTERS, stripConsoleReporters } from "./utils/strip-console-reporters.js";
 import { CURRENT_PLUGIN_VERSION } from "./version.js";
 import { AgentPlugin } from "./plugin.js";
@@ -30,4 +30,4 @@ const COVERAGE_LEVELS_PER_FILE = AgentPlugin.COVERAGE_LEVELS_PER_FILE;
 /** Auto-update tolerance functions for `coverage.thresholds.autoUpdate`. Mirrors `AgentPlugin.COVERAGE_AUTOUPDATE`. @public */
 const COVERAGE_AUTOUPDATE = AgentPlugin.COVERAGE_AUTOUPDATE;
 
-export { AgentPlugin, AgentReporter, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, ConfigValidation, ConfigValidationLive, ConfigValidationTest, ConfigurationError, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, CoverageLevel, DefaultDiscoverStrategy, DiscoverStrategy, ReporterLive, Tag, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, nodeWalkerFs, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };
+export { AgentPlugin, AgentReporter, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, ConfigValidation, ConfigValidationLive, ConfigValidationTest, ConfigurationError, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, CoverageLevel, DefaultDiscoverStrategy, DiscoverStrategy, ReporterLive, Tag, applyProjectOverrides, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, nodeWalkerFs, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };

package/layers/CoverageAnalyzerLive.js

@@ -104,6 +104,28 @@ function matchGlob(filePath, pattern) {
 	return compiled?.matches(filePath) ?? false;
 }
 /**
+* True when a path has a `node_modules` directory segment anywhere in it,
+* under either separator. A dependency is never one of the project's own
+* sources, whatever Vitest's untested-files glob swept into the map
+* (issue #622: `rolldown-pnpm-config` under `node_modules` reached
+* `file_coverage` on spencerbeggs/effected).
+*/
+function isNodeModulesPath(filePath) {
+	return /(?:^|\/)node_modules(?:\/|$)/.test(toPosixPath(filePath));
+}
+/**
+* Decide whether a coverage-map key is one of the project's sources: not
+* under `node_modules`, inside `include` when given, and outside `exclude`
+* when given. `matchPath` is the glob-matching form of the key (see
+* `CoverageOptions.root`).
+*/
+function isProjectSource(filePath, matchPath, options) {
+	if (isNodeModulesPath(filePath)) return false;
+	const { include, exclude } = options;
+	if (include !== void 0 && include.length > 0 && !include.some((pattern) => matchGlob(matchPath, pattern))) return false;
+	return !exclude?.some((pattern) => matchGlob(matchPath, pattern));
+}
+/**
 * Resolve the effective thresholds for a file path by checking pattern
 * overrides first, falling back to global thresholds.
 */
@@ -213,6 +235,7 @@ function processCoverageInternal(coverageMap, options, testedFiles) {
 	const mapSummaries = [];
 	for (const filePath of coverageMap.files()) {
 		const matchPath = matchKey(filePath);
+		if (!isProjectSource(filePath, matchPath, options)) continue;
 		const fileCoverage = coverageMap.fileCoverageFor(filePath);
 		const fileSummary = fileCoverage.toSummary();
 		mapSummaries.push({
@@ -293,4 +316,4 @@ const CoverageAnalyzerLive = Layer.succeed(CoverageAnalyzer, {
 	})
 });
 
-export { CoverageAnalyzerLive };
+export { CoverageAnalyzerLive, isNodeModulesPath };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/plugin",
-	"version": "5.4.9",
+	"version": "5.6.0",
 	"private": false,
 	"description": "Vitest plugin for the vitest-agent ecosystem: owns persistence, classification, baselines, trends, and dispatches rendering to a configurable reporter.",
 	"keywords": [
@@ -49,11 +49,11 @@
 		"@effected/glob": "^0.14.0",
 		"@effected/walker": "^0.19.0",
 		"@effected/workspaces": "^0.38.0",
-		"@vitest-agent/cli": "4.0.13",
-		"@vitest-agent/engine": "1.1.2",
-		"@vitest-agent/mcp": "5.2.9",
-		"@vitest-agent/reporter": "5.0.8",
-		"@vitest-agent/sdk": "7.0.5",
+		"@vitest-agent/cli": "4.1.1",
+		"@vitest-agent/engine": "2.0.0",
+		"@vitest-agent/mcp": "5.3.0",
+		"@vitest-agent/reporter": "6.0.0",
+		"@vitest-agent/sdk": "8.0.0",
 		"effect": "^4.0.6",
 		"magic-string": "^1.4.3"
 	},

package/plugin.js

@@ -6,12 +6,14 @@ import { assertFlatScope } from "./utils/report-writer.js";
 import { installStrayOutputCapture } from "./utils/stray-output-capture.js";
 import { AgentReporter } from "./reporter.js";
 import { buildModuleInfo } from "./utils/build-module-info.js";
+import { publishConfigSuggestedActions, suggestedActionsFromValidation } from "./utils/config-suggested-actions.js";
 import { DefaultDiscoverStrategy } from "./utils/discover-strategy.js";
 import { discoverProjects } from "./utils/discover-projects.js";
 import { ensureGithubActionsReporter } from "./utils/ensure-github-reporter.js";
 import { injectTags } from "./utils/inject-tags.js";
 import { isBenignViteSourceMapWarning } from "./utils/is-benign-vite-source-map-warning.js";
 import { resolveCoverageDirIsolation } from "./utils/resolve-coverage-dir-isolation.js";
+import { PERSIST_ENV_VAR, resolvePersistence } from "./utils/resolve-persistence.js";
 import { DEFAULT_BUILT_RECENTLY_MS, DEFAULT_LOCK_STALE_MS, DEFAULT_LOCK_WAIT_TIMEOUT_MS, acquireRunScriptLock, markRunScriptDone, parseLockTimingOverride, releaseRunScriptLock } from "./utils/run-script-lock.js";
 import { stripConsoleReporters } from "./utils/strip-console-reporters.js";
 import { makeTagCacheKeyGenerator } from "./utils/tag-cache-key.js";
@@ -215,11 +217,15 @@ function AgentPlugin(options = {}, _layer) {
 					ctx.defineCacheKeyGenerator(makeTagCacheKeyGenerator(classifyForCache));
 					log("registered fsModuleCache tag cache-key generator");
 				}
-				const { env, executor } = await Effect.runPromise(Effect.gen(function* () {
-					const env = yield* (yield* EnvironmentDetector).detect();
+				const { env, executor, inGithubActions } = await Effect.runPromise(Effect.gen(function* () {
+					const detector = yield* EnvironmentDetector;
+					const env = yield* detector.detect();
+					const executor = yield* (yield* ExecutorResolver).resolve(env);
+					const ci = yield* detector.ci;
 					return {
 						env,
-						executor: yield* (yield* ExecutorResolver).resolve(env)
+						executor,
+						inGithubActions: Option.contains(ci, "github-actions")
 					};
 				}).pipe(Effect.provide(Layer.merge(layer, ExecutorResolverLive))));
 				const reportOption = options.report;
@@ -253,17 +259,19 @@ function AgentPlugin(options = {}, _layer) {
 						stderr: process.stderr
 					});
 				}
-				if (env === "ci-github" && consoleMode !== "silent") {
+				const githubActions = inGithubActions && consoleMode !== "silent";
+				if (githubActions) {
 					log("normalizing the github-actions reporter entry");
 					const withGithubActions = ensureGithubActionsReporter(vitest.config.reporters);
 					vitest.config.reporters = withGithubActions;
 				}
-				const githubActions = env === "ci-github" && consoleMode !== "silent";
 				log("githubActions (auto):", githubActions);
 				const validation = await Effect.runPromise(Effect.provide(Effect.flatMap(ConfigValidation, (cv) => cv.validate({
 					vitestConfig: vitest.config,
 					pluginOptions: options
 				})), ConfigValidationLive));
+				const configSuggestedActions = suggestedActionsFromValidation(validation);
+				publishConfigSuggestedActions(vitest, configSuggestedActions);
 				for (const w of validation.warnings) reportOnce(`[vitest-agent:plugin] warning ${w.code}: ${w.message}` + (w.remediation ? `\n  ${w.remediation}` : "") + "\n");
 				for (const i of validation.info) reportOnce(`[vitest-agent:plugin] info ${i.code}: ${i.message}\n`);
 				if (validation.errors.length > 0) {
@@ -275,6 +283,13 @@ function AgentPlugin(options = {}, _layer) {
 				const rawTargets = options.coverageTargets;
 				const coverageTargets = rawTargets ? resolveThresholds(rawTargets) : void 0;
 				const coverageMode = coverageConfig?.enabled === false ? "ui-only" : "full";
+				const persistence = resolvePersistence({
+					option: options.persist,
+					env: process.env
+				});
+				if (persistence.ignoredEnvValue !== void 0) reportOnce(`[vitest-agent:plugin] ignoring ${PERSIST_ENV_VAR}=${persistence.ignoredEnvValue}: expected 0|false|off or 1|true|on\n`);
+				const persist = persistence.persist;
+				log("coverageMode:", coverageMode, "| persist:", persist, `(${persistence.source})`);
 				if (coverageConfig && !coverageDirDecidedByVitest.has(vitest)) {
 					coverageDirDecidedByVitest.add(vitest);
 					const dirDecision = resolveCoverageDirIsolation({
@@ -313,12 +328,14 @@ function AgentPlugin(options = {}, _layer) {
 					...coverageThresholds !== void 0 ? { coverageThresholds } : {},
 					...coverageTargets !== void 0 ? { coverageTargets } : {},
 					coverageMode,
+					persist,
 					consoleMode,
 					mcp,
 					githubActions,
 					...reportScope !== void 0 && { reportScope },
 					transport,
 					...passWithNoTests !== void 0 ? { passWithNoTests } : {},
+					...configSuggestedActions.length > 0 ? { suggestedActions: configSuggestedActions } : {},
 					...options.reporter !== void 0 && { reporter: options.reporter },
 					...options.onRunEvent !== void 0 ? { onRunEvent: options.onRunEvent } : {}
 				});
@@ -417,7 +434,8 @@ function makeDiscoverBuilder(options) {
 		return makeDiscoverBuilder({
 			...opts.strategy !== void 0 ? { strategy: opts.strategy } : {},
 			...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
-			...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
+			...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {},
+			...opts.configure !== void 0 ? { configure: opts.configure } : {}
 		});
 	}
 	_AgentPlugin.discover = discover;

package/reporter.js

@@ -1,5 +1,6 @@
 import { resolveThresholds } from "./utils/resolve-thresholds.js";
 import { CoverageAnalyzer } from "./services/CoverageAnalyzer.js";
+import { CoverageAnalyzerLive } from "./layers/CoverageAnalyzerLive.js";
 import { ReporterLive } from "./layers/ReporterLive.js";
 import { buildReporterKit, normalizeReporters } from "./utils/build-reporter-kit.js";
 import { captureEnvVars } from "./utils/capture-env.js";
@@ -13,8 +14,8 @@ import { strayOutputCaptureOf } from "./utils/stray-output-capture.js";
 import { stringifyFailureValue } from "./utils/stringify-failure-value.js";
 import { mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
-import { DataReader, DataStore, DetailResolver, EnvironmentDetector, ExecutorResolver, HistoryTracker, OutputPipelineLive, PathResolutionLive, ensureMigrated, historyKey, resolveDataPath, resolveLogFile, resolveLogLevel, withPersistTransaction } from "@vitest-agent/engine";
-import { buildAgentReport, coerceErrorField, computeTrend, formatFatalError, isTimeoutError, probeHostMetadataFromEnv } from "@vitest-agent/sdk";
+import { ConfigLive, DataReader, DataStore, DetailResolver, EnvironmentDetector, ExecutorResolver, HistoryTracker, OutputPipelineLive, PathResolutionLive, VitestAgentConfigFile, ensureMigrated, historyKey, resolveDataPath, resolveLogFile, resolveLogLevel, withPersistTransaction } from "@vitest-agent/engine";
+import { RunRetentionPolicy, VitestAgentConfig, buildAgentReport, coerceErrorField, computeTrend, formatFatalError, isTimeoutError, probeHostMetadataFromEnv } from "@vitest-agent/sdk";
 import { Effect, Option, PubSub } from "effect";
 import { randomUUID } from "node:crypto";
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -73,6 +74,36 @@ function resolveDataPathCached(projectDir) {
 	return promise;
 }
 /**
+* Cache of the run-retention policy resolved from `vitest-agent.config.toml`,
+* keyed by `projectDir` for the same reason as `dbPathCache`: one load per
+* process, however many reporter instances a multi-project config builds.
+*
+* @internal
+*/
+const retentionPolicyCache = /* @__PURE__ */ new Map();
+/**
+* The run-retention policy the `[retention]` table of
+* `vitest-agent.config.toml` asks for (issue 623): the default policy when
+* the file or table is absent, `Option.none()` when `retention.enabled` is
+* `false`. Loads the config through `ConfigLive(projectDir)` alone — the
+* light half of `PathResolutionLive`, without the workspace scan — so a
+* programmatic `cacheDir` still gets the configured policy.
+*
+* A config that cannot be read resolves to `Option.none()`: the prune is
+* skipped for this run rather than applied under a policy nobody chose, and
+* the same unreadable file already surfaces through `resolveDataPath`.
+*/
+function resolveRetentionPolicyCached(projectDir) {
+	const cached = retentionPolicyCache.get(projectDir);
+	if (cached !== void 0) return cached;
+	const promise = Effect.runPromise(Effect.gen(function* () {
+		const config = yield* (yield* VitestAgentConfigFile).loadOrDefault(new VitestAgentConfig({}));
+		return RunRetentionPolicy.fromConfig(config);
+	}).pipe(Effect.provide(ConfigLive(projectDir)), Effect.provide(NodeServices.layer), Effect.catch(() => Effect.succeed(Option.none()))));
+	retentionPolicyCache.set(projectDir, promise);
+	return promise;
+}
+/**
 * Compute updated baselines using ratchet logic: take the max of actual vs previous,
 * capped by targets if set.
 *
@@ -300,14 +331,17 @@ var AgentReporter = class {
 	options;
 	dbPath = null;
 	/**
-	* Set to `true` after the first `onTestRunEnd` invocation completes.
+	* Set to `true` once `onTestRunEnd` has done this run's work.
 	*
-	* Vitest can fire `onTestRunEnd` more than once per `vitest run` in
-	* some multi-project configurations (e.g., once per project group, with
-	* the same `testModules` array each time). The plugin pushes only ONE
-	* AgentReporter per run, so a fresh instance always starts with this
-	* flag `false`; the first call does the work and the flag prevents
-	* subsequent invocations from re-rendering and re-writing to the DB.
+	* Vitest can fire `onTestRunEnd` more than once per run in some
+	* multi-project configurations (e.g., once per project group, with the
+	* same `testModules` array each time). The first call does the work and
+	* the flag prevents subsequent invocations from re-rendering and
+	* re-writing to the DB. The flag is PER RUN, not per instance: Vitest
+	* keeps one reporter instance alive across watch-mode reruns, so
+	* `onTestRunStart` re-arms it — otherwise every rerun after the first
+	* would silently skip persistence, rendering and `RunFinished`
+	* (issue #576).
 	*/
 	rendered = false;
 	/**
@@ -443,6 +477,7 @@ var AgentReporter = class {
 		const githubActions = options.githubActions ?? false;
 		const base = {
 			...options.cacheDir !== void 0 ? { cacheDir: options.cacheDir } : {},
+			...options.retention !== void 0 ? { retention: options.retention } : {},
 			consoleOutput,
 			omitPassingTests: true,
 			coverageThresholds: resolvedThresholds,
@@ -458,8 +493,10 @@ var AgentReporter = class {
 			...options.projectFilter !== void 0 ? { projectFilter: options.projectFilter } : {},
 			reporter: options.reporter ?? DefaultVitestAgentReporter,
 			coverageMode: options.coverageMode ?? "full",
+			persist: options.persist ?? true,
 			transport: options.transport ?? { kind: "local" },
-			...options.passWithNoTests !== void 0 ? { passWithNoTests: options.passWithNoTests } : {}
+			...options.passWithNoTests !== void 0 ? { passWithNoTests: options.passWithNoTests } : {},
+			...options.suggestedActions !== void 0 && options.suggestedActions.length > 0 ? { suggestedActions: options.suggestedActions } : {}
 		};
 		this.options = resolvedTargets ? {
 			...base,
@@ -488,6 +525,7 @@ var AgentReporter = class {
 			detail: opts.detail ?? "standard",
 			noColor: false,
 			coverageMode: opts.coverageMode,
+			persist: opts.persist,
 			transport: opts.transport,
 			...opts.coverageThresholds !== void 0 && { coverageThresholds: opts.coverageThresholds },
 			...opts.coverageTargets !== void 0 && { coverageTargets: opts.coverageTargets },
@@ -510,7 +548,7 @@ var AgentReporter = class {
 			assertReportCapable(vitest);
 			this.reportWriter = createReportWriter(vitest, this.options.reportScope);
 		}
-		try {
+		if (this.options.persist) try {
 			await this.ensureDbPath();
 		} catch {}
 		await this.initReporters();
@@ -618,7 +656,8 @@ var AgentReporter = class {
 				...opts.coverageThresholds !== void 0 && { coverageThresholds: opts.coverageThresholds },
 				...opts.coverageTargets !== void 0 && { coverageTargets: opts.coverageTargets },
 				...opts.passWithNoTests !== void 0 && { passWithNoTests: opts.passWithNoTests },
-				coverageMode: opts.coverageMode
+				coverageMode: opts.coverageMode,
+				persist: opts.persist
 			});
 			this.reporters = normalizeReporters(opts.reporter(kit));
 		} catch (err) {
@@ -678,6 +717,8 @@ var AgentReporter = class {
 	* `RunStarted` event for live subscribers.
 	*/
 	onTestRunStart(_specifications) {
+		this.rendered = false;
+		this.coverage = null;
 		this.startedSpecCount = _specifications.length;
 		this.strayCapture?.reset();
 		if (this.neutralizedThresholdSnapshot.size > 0) {
@@ -1173,14 +1214,84 @@ var AgentReporter = class {
 		const wantsRunEvents = this.wantsRunEvents();
 		let dbPath;
 		let persistDisabled;
-		try {
+		if (opts.persist) try {
 			dbPath = await this.ensureDbPath();
 		} catch (err) {
 			persistDisabled = formatFatalError(err);
 		}
+		const retention = dbPath === void 0 || persistDisabled !== void 0 ? Option.none() : opts.retention === false ? Option.none() : opts.retention !== void 0 ? Option.some(opts.retention) : await resolveRetentionPolicyCached(process.cwd());
 		const filteredModules = opts.projectFilter ? modules.filter((m) => (m.project.name || "default") === opts.projectFilter) : modules;
 		if (filteredModules.length === 0 && opts.projectFilter) return;
-		if (opts.coverageMode === "ui-only") {
+		const coverageRoot = (() => {
+			const root = stashedVitest?.config?.root;
+			return typeof root === "string" ? root : void 0;
+		})();
+		const coverageGlobs = (() => {
+			const coverage = stashedVitest?.config?.coverage;
+			const asGlobs = (value) => Array.isArray(value) && value.every((v) => typeof v === "string") ? value : void 0;
+			const record = typeof coverage === "object" && coverage !== null ? coverage : {};
+			const include = asGlobs(record.include);
+			const exclude = asGlobs(record.exclude);
+			return {
+				...include !== void 0 ? { include } : {},
+				...exclude !== void 0 ? { exclude } : {}
+			};
+		})();
+		const analyzeCoverage = (baselines) => Effect.gen(function* () {
+			const analyzer = yield* CoverageAnalyzer;
+			const projectModuleCounts = /* @__PURE__ */ new Map();
+			for (const m of modules) {
+				const key = m.project.name || "default";
+				projectModuleCounts.set(key, (projectModuleCounts.get(key) ?? 0) + 1);
+			}
+			const primaryProject = Array.from(projectModuleCounts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
+			const isFirstProject = !opts.projectFilter || opts.projectFilter === primaryProject;
+			const coverageOpts = {
+				thresholds: opts.coverageThresholds,
+				includeBareZero: opts.includeBareZero,
+				...opts.coverageTargets ? { targets: opts.coverageTargets } : {},
+				...baselines ? { baselines } : {},
+				...isPartial ? { totalFiles: totalSpecCount } : {},
+				...coverageRoot !== void 0 ? { root: coverageRoot } : {},
+				...coverageGlobs
+			};
+			const coverageResult = stashedCoverage && isFirstProject ? isPartial ? yield* analyzer.processScoped(stashedCoverage, coverageOpts, testedFiles ?? []) : yield* analyzer.process(stashedCoverage, coverageOpts) : Option.none();
+			const coverageReport = Option.getOrUndefined(coverageResult);
+			if (wantsRunEvents && coverageReport !== void 0) {
+				const globalThresholds = coverageReport.thresholds.global;
+				emitEvent({
+					_tag: "CoverageReady",
+					metrics: coverageReport.totals,
+					thresholds: globalThresholds,
+					gaps: coverageReport.lowCoverage.map((fc) => ({
+						file: fc.file,
+						missing: fc.summary,
+						uncoveredLines: fc.uncoveredLines
+					})),
+					...coverageReport.scoped ? { scoped: coverageReport.scoped } : {},
+					...coverageReport.scopedFiles !== void 0 ? { scopedFiles: coverageReport.scopedFiles.length } : {},
+					...coverageReport.totalFiles !== void 0 ? { totalFiles: coverageReport.totalFiles } : {},
+					...coverageReport.globShortfalls !== void 0 ? { globShortfalls: coverageReport.globShortfalls } : {}
+				});
+				if (!coverageReport.scoped) for (const metric of [
+					"lines",
+					"branches",
+					"functions",
+					"statements"
+				]) {
+					const expected = globalThresholds[metric];
+					const actual = coverageReport.totals[metric];
+					if (expected !== void 0 && actual < expected) emitEvent({
+						_tag: "ThresholdViolation",
+						metric,
+						expected,
+						actual
+					});
+				}
+			}
+			return coverageReport;
+		});
+		if (opts.coverageMode === "ui-only" || !opts.persist) {
 			const uiProjectGroups = /* @__PURE__ */ new Map();
 			for (const mod of filteredModules) {
 				const key = mod.project.name || "default";
@@ -1198,11 +1309,16 @@ var AgentReporter = class {
 				const detector = yield* EnvironmentDetector;
 				const executorResolver = yield* ExecutorResolver;
 				const detailResolver = yield* DetailResolver;
+				const coverageReport = yield* analyzeCoverage(void 0);
+				const reports = coverageReport ? uiReports.map((r) => ({
+					...r,
+					coverage: coverageReport
+				})) : uiReports;
 				const env = yield* detector.detect();
 				const executor = yield* executorResolver.resolve(env);
 				const health = {
-					hasFailures: uiReports.some((r) => r.failedFiles.length > 0 || r.unhandledErrors.length > 0),
-					belowTargets: false,
+					hasFailures: reports.some((r) => r.failedFiles.length > 0 || r.unhandledErrors.length > 0),
+					belowTargets: (coverageReport?.belowTarget?.length ?? 0) > 0,
 					hasTargets: !!opts.coverageTargets
 				};
 				const detail = yield* detailResolver.resolve(executor, health, opts.detail);
@@ -1222,12 +1338,14 @@ var AgentReporter = class {
 					...opts.coverageThresholds !== void 0 && { coverageThresholds: opts.coverageThresholds },
 					...opts.coverageTargets !== void 0 && { coverageTargets: opts.coverageTargets },
 					...opts.passWithNoTests !== void 0 && { passWithNoTests: opts.passWithNoTests },
-					coverageMode: opts.coverageMode
+					coverageMode: opts.coverageMode,
+					persist: opts.persist
 				});
 				const reporters = preBuiltReporters ?? normalizeReporters(opts.reporter(kit));
 				const renderInput = {
-					reports: withStrayOutput(uiReports, strayOutput),
-					classifications: /* @__PURE__ */ new Map()
+					reports: withStrayOutput(reports, strayOutput),
+					classifications: /* @__PURE__ */ new Map(),
+					...opts.suggestedActions !== void 0 && { suggestedActions: opts.suggestedActions }
 				};
 				const allOutputs = reporters.flatMap((r) => r.render(renderInput, kit));
 				for (const output of allOutputs) routeRenderedOutput(output, {
@@ -1235,7 +1353,7 @@ var AgentReporter = class {
 					...reportWriter !== null && { writeReport: reportWriter.write }
 				});
 			});
-			await Effect.runPromise(uiProgram.pipe(Effect.provide(OutputPipelineLive(process.env)), Effect.provide(NodeServices.layer))).catch((err) => {
+			await Effect.runPromise(uiProgram.pipe(Effect.provide(CoverageAnalyzerLive), Effect.provide(OutputPipelineLive(process.env)), Effect.provide(NodeServices.layer))).catch((err) => {
 				process.stderr.write(`vitest-agent: ${formatFatalError(err)}\n`);
 			});
 			await reportWriter?.flush();
@@ -1270,7 +1388,6 @@ var AgentReporter = class {
 		const persistProgram = Effect.gen(function* () {
 			const store = yield* DataStore;
 			const reader = yield* DataReader;
-			const analyzer = yield* CoverageAnalyzer;
 			const tracker = yield* HistoryTracker;
 			const invocationId = randomUUID();
 			const vitest = stashedVitest;
@@ -1288,60 +1405,12 @@ var AgentReporter = class {
 			}
 			const baselinesOpt = yield* reader.getBaselines("__global__").pipe(Effect.catch(() => Effect.succeed(Option.none())));
 			const baselines = Option.getOrUndefined(baselinesOpt);
-			const projectModuleCounts = /* @__PURE__ */ new Map();
-			for (const m of modules) {
-				const key = m.project.name || "default";
-				projectModuleCounts.set(key, (projectModuleCounts.get(key) ?? 0) + 1);
-			}
-			const primaryProject = Array.from(projectModuleCounts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
-			const isFirstProject = !opts.projectFilter || opts.projectFilter === primaryProject;
-			const coverageRoot = typeof vitestConfig.root === "string" ? vitestConfig.root : void 0;
-			const coverageOpts = {
-				thresholds: opts.coverageThresholds,
-				includeBareZero: opts.includeBareZero,
-				...opts.coverageTargets ? { targets: opts.coverageTargets } : {},
-				...baselines ? { baselines } : {},
-				...isPartial ? { totalFiles: totalSpecCount } : {},
-				...coverageRoot !== void 0 ? { root: coverageRoot } : {}
-			};
-			const coverageResult = stashedCoverage && isFirstProject ? isPartial ? yield* analyzer.processScoped(stashedCoverage, coverageOpts, testedFiles ?? []) : yield* analyzer.process(stashedCoverage, coverageOpts) : Option.none();
-			const coverageReport = Option.getOrUndefined(coverageResult);
-			if (wantsRunEvents && coverageReport !== void 0) {
-				const globalThresholds = coverageReport.thresholds.global;
-				emitEvent({
-					_tag: "CoverageReady",
-					metrics: coverageReport.totals,
-					thresholds: globalThresholds,
-					gaps: coverageReport.lowCoverage.map((fc) => ({
-						file: fc.file,
-						missing: fc.summary,
-						uncoveredLines: fc.uncoveredLines
-					})),
-					...coverageReport.scoped ? { scoped: coverageReport.scoped } : {},
-					...coverageReport.scopedFiles !== void 0 ? { scopedFiles: coverageReport.scopedFiles.length } : {},
-					...coverageReport.totalFiles !== void 0 ? { totalFiles: coverageReport.totalFiles } : {},
-					...coverageReport.globShortfalls !== void 0 ? { globShortfalls: coverageReport.globShortfalls } : {}
-				});
-				if (!coverageReport.scoped) for (const metric of [
-					"lines",
-					"branches",
-					"functions",
-					"statements"
-				]) {
-					const expected = globalThresholds[metric];
-					const actual = coverageReport.totals[metric];
-					if (expected !== void 0 && actual < expected) emitEvent({
-						_tag: "ThresholdViolation",
-						metric,
-						expected,
-						actual
-					});
-				}
-			}
+			const coverageReport = yield* analyzeCoverage(baselines);
 			const reports = [];
 			const isMultiProject = projectGroups.size > 1 || !!opts.projectFilter;
 			yield* withPersistTransaction(Effect.gen(function* () {
 				yield* store.writeSettings(settingsHash, settings, envVars);
+				let fileCoverageWritten = false;
 				for (const [projectName, projectModules] of projectGroups) {
 					const project = projectName === "default" ? "default" : projectName;
 					const baseReport = buildAgentReport(projectModules, errors, reason, { omitPassingTests: opts.omitPassingTests }, isMultiProject ? projectName : void 0);
@@ -1381,7 +1450,8 @@ var AgentReporter = class {
 						gitCommitSha: process.env.GITHUB_SHA ?? null,
 						hostSource: hostProbe.source,
 						hostValue: hostProbe.value,
-						hostMetadata: hostProbe.metadata
+						hostMetadata: hostProbe.metadata,
+						strayOutput: strayOutput ?? null
 					});
 					for (const mod of projectModules) {
 						const fileId = yield* store.ensureFile(mod.relativeModuleId);
@@ -1618,7 +1688,8 @@ var AgentReporter = class {
 						coverage: coverageReport
 					} : reportWithTags;
 					reports.push(report);
-					if (coverageReport) {
+					if (coverageReport && !fileCoverageWritten) {
+						fileCoverageWritten = true;
 						const tierByFile = /* @__PURE__ */ new Map();
 						const sourceByFile = /* @__PURE__ */ new Map();
 						for (const fc of coverageReport.belowTarget ?? []) {
@@ -1663,6 +1734,10 @@ var AgentReporter = class {
 					if (opts.coverageThresholds !== void 0) yield* store.writeThresholds(opts.coverageThresholds);
 					if (opts.coverageTargets !== void 0) yield* store.writeTargets(opts.coverageTargets);
 				}
+				if (Option.isSome(retention)) yield* store.pruneRuns(retention.value).pipe(Effect.tap((result) => result.prunedRuns > 0 ? Effect.logDebug("pruned runs", {
+					prunedRuns: result.prunedRuns,
+					prunedFiles: result.prunedFiles
+				}) : Effect.void), Effect.catch((error) => Effect.logWarning("run retention prune failed", { error: error.message })));
 			}));
 			let trendSummary;
 			if (coverageReport && !coverageReport.scoped) {
@@ -1773,12 +1848,14 @@ var AgentReporter = class {
 				...opts.coverageThresholds !== void 0 && { coverageThresholds: opts.coverageThresholds },
 				...opts.coverageTargets !== void 0 && { coverageTargets: opts.coverageTargets },
 				...opts.passWithNoTests !== void 0 && { passWithNoTests: opts.passWithNoTests },
-				coverageMode: opts.coverageMode
+				coverageMode: opts.coverageMode,
+				persist: opts.persist
 			});
 			const reporters = preBuiltReporters ?? normalizeReporters(opts.reporter(kit));
 			const renderInput = {
 				reports: withStrayOutput(reports, strayOutput),
 				classifications,
+				...opts.suggestedActions !== void 0 && { suggestedActions: opts.suggestedActions },
 				...trendSummary !== void 0 && { trendSummary }
 			};
 			const allOutputs = reporters.flatMap((r) => r.render(renderInput, kit));

package/utils/build-reporter-kit.js

@@ -1,37 +1,33 @@
-import { osc8 } from "@vitest-agent/sdk";
-
 // src/utils/build-reporter-kit.ts
 const buildReporterKit = (input) => {
 	const consoleOutput = input.consoleMode === "silent" ? "silent" : "failures";
 	const githubSummary = input.githubActions;
 	const githubSummaryFile = process.env.GITHUB_STEP_SUMMARY;
-	const config = {
-		executor: input.executor,
-		consoleMode: input.consoleMode,
-		mcp: input.mcp,
-		consoleOutput,
-		omitPassingTests: true,
-		coverageConsoleLimit: 10,
-		includeBareZero: false,
-		githubActions: input.githubActions,
-		githubSummary,
-		detail: input.detail,
-		noColor: input.noColor,
-		coverageMode: input.coverageMode,
-		transport: input.transport,
-		...input.dbPath !== void 0 && { dbPath: input.dbPath },
-		...input.projectFilter !== void 0 && { projectFilter: input.projectFilter },
-		...githubSummaryFile !== void 0 && { githubSummaryFile },
-		...input.runCommand !== void 0 && { runCommand: input.runCommand },
-		...input.coverageThresholds !== void 0 && { coverageThresholds: input.coverageThresholds },
-		...input.coverageTargets !== void 0 && { coverageTargets: input.coverageTargets },
-		...input.passWithNoTests !== void 0 && { passWithNoTests: input.passWithNoTests }
-	};
-	const osc8Enabled = !input.noColor && (input.env === "terminal" || input.env === "agent-shell");
 	return {
-		config,
+		config: {
+			executor: input.executor,
+			consoleMode: input.consoleMode,
+			mcp: input.mcp,
+			consoleOutput,
+			omitPassingTests: true,
+			coverageConsoleLimit: 10,
+			includeBareZero: false,
+			githubActions: input.githubActions,
+			githubSummary,
+			detail: input.detail,
+			noColor: input.noColor,
+			coverageMode: input.coverageMode,
+			persist: input.persist,
+			transport: input.transport,
+			...input.dbPath !== void 0 && { dbPath: input.dbPath },
+			...input.projectFilter !== void 0 && { projectFilter: input.projectFilter },
+			...githubSummaryFile !== void 0 && { githubSummaryFile },
+			...input.runCommand !== void 0 && { runCommand: input.runCommand },
+			...input.coverageThresholds !== void 0 && { coverageThresholds: input.coverageThresholds },
+			...input.coverageTargets !== void 0 && { coverageTargets: input.coverageTargets },
+			...input.passWithNoTests !== void 0 && { passWithNoTests: input.passWithNoTests }
+		},
 		stdEnv: input.env,
-		stdOsc8: (url, label) => osc8(url, label, { enabled: osc8Enabled }),
 		...input.runEvents !== void 0 && { runEvents: input.runEvents }
 	};
 };

package/utils/config-suggested-actions.js

@@ -0,0 +1,42 @@
+// src/utils/config-suggested-actions.ts
+/**
+* The `Symbol.for` key under which `configureVitest` publishes the run's
+* config-derived suggested actions on the Vitest instance. `Symbol.for`
+* resolves to the identical symbol across module copies in one process, so
+* the MCP `run_tests` tool reads the same slot off the Vitest instance it
+* created (mirrors the discovery last-scan slot).
+*
+* @internal
+*/
+const CONFIG_SUGGESTED_ACTIONS_SYMBOL = Symbol.for("vitest-agent:config-suggested-actions");
+/**
+* Map a `ValidationResult`'s warnings and info entries onto suggested
+* actions, in the order the validator produced them. A warning becomes a
+* `warn` action and an info entry an `info` action; the title names the
+* rule code, the detail carries the message followed by the remediation
+* when the rule has one. No `targetTool` — there is no MCP tool that edits
+* the Vitest config.
+*
+* @internal
+*/
+const suggestedActionsFromValidation = (result) => [...result.warnings.map((w) => ({
+	severity: "warn",
+	title: `Coverage config: ${w.code}`,
+	detail: w.remediation !== void 0 ? `${w.message} ${w.remediation}` : w.message
+})), ...result.info.map((i) => ({
+	severity: "info",
+	title: `Coverage config: ${i.code}`,
+	detail: i.message
+}))];
+/**
+* Publish the run's config-derived suggested actions on the Vitest instance
+* for readers in the same process (the MCP `run_tests` tool). An empty list
+* clears the slot so a watch-mode rerun after a config fix reports nothing.
+*
+* @internal
+*/
+const publishConfigSuggestedActions = (vitest, actions) => {
+	vitest[CONFIG_SUGGESTED_ACTIONS_SYMBOL] = actions.length > 0 ? actions : void 0;
+};
+
+export { CONFIG_SUGGESTED_ACTIONS_SYMBOL, publishConfigSuggestedActions, suggestedActionsFromValidation };

package/utils/discover-projects.js

@@ -8,6 +8,42 @@ import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/works
 import { nodeSyncOps } from "@effected/workspaces/node-sync";
 
 // src/utils/discover-projects.ts
+/**
+* Shallow-merges each `overrides` entry into the generated project whose
+* `test.name` equals the entry's key. Pure: returns new project objects for the
+* configured names and the original objects for the rest; the discovered
+* `name` always wins over one carried by the override. Only a string
+* `test.name` can be keyed; a project named through Vitest's object form is
+* left untouched (and a key for it is reported as unknown).
+*
+* Throws when a key names no project in `configs`, listing the discovered
+* names so the typo is visible at config-load time.
+* @param configs - The projects a strategy produced
+* @param overrides - Per-project `test` overrides keyed by project name
+* @returns The projects with overrides applied
+* @public
+*/
+function applyProjectOverrides(configs, overrides) {
+	const names = new Set(configs.map((c) => c.test?.name).filter((n) => typeof n === "string"));
+	const unknown = Object.keys(overrides).filter((key) => !names.has(key));
+	if (unknown.length > 0) {
+		const quoted = unknown.map((k) => `"${k}"`).join(", ");
+		const discovered = [...names].map((n) => `"${n}"`).join(", ") || "(none)";
+		throw new Error(`[vitest-agent] configure: ${quoted} ${unknown.length === 1 ? "matches" : "match"} no discovered project. Discovered projects: ${discovered}.`);
+	}
+	return configs.map((config) => {
+		const name = config.test?.name;
+		if (typeof name !== "string" || !Object.hasOwn(overrides, name)) return config;
+		return {
+			...config,
+			test: {
+				...config.test,
+				...overrides[name],
+				name
+			}
+		};
+	});
+}
 const DISCOVERY_LAST_SCAN_SYMBOL = Symbol.for("vitest-agent:discovery:last-scan-at");
 const warnedDeclinedPackagePaths = /* @__PURE__ */ new Set();
 async function warnIfDeclinedPackageIsTestShaped(pkg, fs) {
@@ -101,6 +137,7 @@ async function discoverProjects(options) {
 	const strategy = options?.strategy;
 	const cwd = options?.cwd;
 	const additionalEntries = options?.additionalEntries ?? [];
+	const configure = options?.configure;
 	const fs = options?.fs ?? nodeWalkerFs;
 	const syncOps = options?.syncOps ?? nodeSyncOps;
 	const packageEnumerationOptions = {
@@ -109,7 +146,7 @@ async function discoverProjects(options) {
 	};
 	const root = findWorkspaceRootSync(cwd ?? process.cwd(), syncOps);
 	if (!root) throw new Error(`[vitest-agent] Could not find workspace root from ${cwd ?? process.cwd()}. Ensure a pnpm-workspace.yaml or package.json with "workspaces" exists.`);
-	const useCache = strategy === void 0 && additionalEntries.length === 0;
+	const useCache = strategy === void 0 && additionalEntries.length === 0 && configure === void 0;
 	const resolvedStrategy = strategy ?? new DefaultDiscoverStrategy();
 	const packages = getWorkspacePackagesSync(root, packageEnumerationOptions);
 	let signature;
@@ -154,8 +191,9 @@ async function discoverProjects(options) {
 		configs.push(config);
 	}
 	const tags = [...resolvedStrategy.tagDefinitions];
+	const configured = configure === void 0 ? configs : applyProjectOverrides(configs, configure);
 	const result = {
-		projects: configs.length > 0 ? configs : void 0,
+		projects: configured.length > 0 ? configured : void 0,
 		tags
 	};
 	if (useCache && signature !== void 0) _cache.set(root, {
@@ -166,4 +204,4 @@ async function discoverProjects(options) {
 	return result;
 }
 
-export { discoverProjects };
+export { applyProjectOverrides, discoverProjects };

package/utils/resolve-persistence.js

@@ -0,0 +1,61 @@
+// src/utils/resolve-persistence.ts
+/**
+* The environment variable an operator sets to override `AgentPlugin`'s
+* `persist` option when the config cannot be edited (issue #625).
+*/
+const PERSIST_ENV_VAR = "VITEST_AGENT_PERSIST";
+/** Values of `VITEST_AGENT_PERSIST` that turn persistence off (compared lower-cased and trimmed). */
+const OFF_VALUES = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"off"
+]);
+/** Values of `VITEST_AGENT_PERSIST` that turn persistence on (compared lower-cased and trimmed). */
+const ON_VALUES = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"on"
+]);
+/**
+* Pure decision: should this run be recorded in the SQLite `data.db`?
+*
+* @remarks
+* The env var is an operator override and wins over the option in either
+* direction — `VITEST_AGENT_PERSIST=0` turns persistence off under
+* `persist: true`, and `=1` turns it back on under `persist: false` — so a
+* runner whose `vitest.config.ts` is not editable can still decide. An
+* empty value is unset. Nothing here reads `CI`: the opt-out is explicit
+* by design, because some CI setups cache `data.db` between jobs and
+* query it, and an automatic opt-out would silently empty their history.
+*
+* @public
+*/
+function resolvePersistence(input) {
+	const raw = input.env[PERSIST_ENV_VAR];
+	let ignoredEnvValue;
+	if (raw !== void 0 && raw.trim() !== "") {
+		const normalized = raw.trim().toLowerCase();
+		if (OFF_VALUES.has(normalized)) return {
+			persist: false,
+			source: "env"
+		};
+		if (ON_VALUES.has(normalized)) return {
+			persist: true,
+			source: "env"
+		};
+		ignoredEnvValue = raw;
+	}
+	const fromOption = input.option === void 0 ? {
+		persist: true,
+		source: "default"
+	} : {
+		persist: input.option,
+		source: "option"
+	};
+	return ignoredEnvValue === void 0 ? fromOption : {
+		...fromOption,
+		ignoredEnvValue
+	};
+}
+
+export { PERSIST_ENV_VAR, resolvePersistence };

package/version.js

@@ -8,6 +8,6 @@
 *
 * @public
 */
-const CURRENT_PLUGIN_VERSION = "5.4.9";
+const CURRENT_PLUGIN_VERSION = "5.6.0";
 
 export { CURRENT_PLUGIN_VERSION };