@vitest-agent/sdk 2.4.13 → 2.5.0

package/testing.d.ts

@@ -132,6 +132,7 @@ declare const AgentReport: Schema.Struct<{
     }>>;
     readonly scoped: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
     readonly scopedFiles: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly totalFiles: Schema.optional<Schema.Number>;
     readonly lowCoverage: Schema.$Array<Schema.Struct<{
       readonly file: Schema.String;
       readonly summary: Schema.Struct<{
@@ -170,6 +171,10 @@ declare const AgentReport: Schema.Struct<{
       readonly sample: Schema.optional<Schema.String>;
     }>>;
     readonly truncated: Schema.optional<Schema.Boolean>;
+    readonly fromFailingTests: Schema.optional<Schema.Struct<{
+      readonly total: Schema.Number;
+      readonly files: Schema.Number;
+    }>>;
   }>>;
 }>;
 /** @public */
@@ -289,6 +294,7 @@ declare const CoverageReport: Schema.Struct<{
   }>>;
   readonly scoped: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
   readonly scopedFiles: Schema.optional<Schema.$Array<Schema.String>>;
+  readonly totalFiles: Schema.optional<Schema.Number>;
   readonly lowCoverage: Schema.$Array<Schema.Struct<{
     readonly file: Schema.String;
     readonly summary: Schema.Struct<{
@@ -469,9 +475,28 @@ type TrendRecord = typeof TrendRecord.Type;
 type Phase = "spike" | "red" | "red.triangulate" | "green" | "green.fake-it" | "refactor" | "extended-red" | "green-without-red";
 /** @public */
 type ArtifactKind = "test_written" | "test_failed_run" | "code_written" | "test_passed_run" | "refactor" | "test_weakened";
+/**
+ * Explicit test-runner marker on a `tdd_artifacts` row (issue #363). `vitest`
+ * artifacts always carry a `test_case_id` when they anchor a specific test;
+ * `bats` artifacts never do (there is no `test_cases` row for a bats test),
+ * so the D2 binding-rule validator branches on this to accept a bats
+ * run-level artifact without weakening the vitest guard.
+ * @public
+ */
+type ArtifactSuite = "vitest" | "bats";
 /** @public */
 interface CitedArtifact {
   readonly id: number;
+  /**
+   * `tdd_phases.id` of the phase this artifact was actually recorded in — the
+   * artifact's own phase binding. This is the honest anchor for D2 binding
+   * rule 1's window check (issue #245): a test_case's first-ever creation
+   * turn can predate the current phase (e.g. authored during spike, then
+   * re-run inside red) without the evidence itself being stale, so the
+   * window check compares this against `PhaseTransitionContext.current_phase_id`
+   * rather than `test_case_created_turn_at`.
+   */
+  readonly phase_id: number;
   readonly artifact_kind: ArtifactKind;
   readonly test_case_id: number | null;
   readonly test_case_created_turn_at: string | null;
@@ -479,6 +504,12 @@ interface CitedArtifact {
   readonly test_run_id: number | null;
   readonly test_first_failure_run_id: number | null;
   readonly behavior_id: number | null;
+  /**
+   * Issue #363: explicit suite marker distinguishing vitest from bats runs.
+   * Optional on the pure type so hand-built contexts default to `vitest`;
+   * the DB row always carries the persisted value.
+   */
+  readonly suite?: ArtifactSuite;
 }
 //#endregion
 //#region src/schemas/Identity.d.ts
@@ -655,6 +686,29 @@ declare class IdempotencyHit extends IdempotencyHit_base<{
   readonly existingAgentId: typeof AgentId.Type;
 }> {}
 //#endregion
+//#region src/schemas/Thresholds.d.ts
+/**
+ * Fully resolved thresholds ready for evaluation.
+ * @public
+ */
+declare const ResolvedThresholds: Schema.Struct<{
+  readonly global: Schema.Struct<{
+    readonly lines: Schema.optional<Schema.Number>;
+    readonly functions: Schema.optional<Schema.Number>;
+    readonly branches: Schema.optional<Schema.Number>;
+    readonly statements: Schema.optional<Schema.Number>;
+  }>;
+  readonly perFile: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
+  readonly patterns: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.Struct<{
+    readonly lines: Schema.optional<Schema.Number>;
+    readonly functions: Schema.optional<Schema.Number>;
+    readonly branches: Schema.optional<Schema.Number>;
+    readonly statements: Schema.optional<Schema.Number>;
+  }>]>>, never>;
+}>;
+/** @public */
+type ResolvedThresholds = typeof ResolvedThresholds.Type;
+//#endregion
 //#region src/services/DataStore.d.ts
 /** @public */
 interface CreateGoalInput {
@@ -879,6 +933,13 @@ interface SessionInput {
   readonly parentSessionId?: number;
   readonly triageWasNonEmpty?: boolean;
   readonly startedAt: string;
+  /**
+   * Canonical conversation UUID this session belongs to (issue #144).
+   * Set once at INSERT time — `sessions.conversation_id` is immutable
+   * thereafter (see the `trg_sessions_conv_id_immutable` trigger), so
+   * omit it here rather than trying to backfill via an update.
+   */
+  readonly conversationId?: string;
 }
 /** @public */
 interface TurnInput {
@@ -956,6 +1017,8 @@ interface WriteTddArtifactInput {
   readonly testFirstFailureRunId?: number;
   readonly diffExcerpt?: string;
   readonly recordedAt: string;
+  /** Issue #363: explicit suite marker. Defaults to `"vitest"` when omitted. */
+  readonly suite?: ArtifactSuite;
 }
 /** @public */
 interface WriteCommitInput {
@@ -1030,6 +1093,18 @@ declare const DataStore_base: Context.ServiceClass<DataStore, "vitest-agent/Data
   readonly writeCoverage: (runId: number, coverage: ReadonlyArray<FileCoverageInput>) => Effect.Effect<void, DataStoreError>;
   readonly writeHistory: (project: string, fullName: string, modulePath: string, runId: number, timestamp: string, state: string, duration: number | null, flaky: boolean, retryCount: number, errorMessage: string | null) => Effect.Effect<void, DataStoreError>;
   readonly writeBaselines: (baselines: CoverageBaselines) => Effect.Effect<void, DataStoreError>;
+  /**
+   * Persist the resolved (enforced) Vitest `coverage.thresholds` for the
+   * current run, distinct from the ratcheted `coverage_baselines` rows.
+   * Stored under `kind='threshold'`. See issue #237.
+   */
+  readonly writeThresholds: (thresholds: ResolvedThresholds) => Effect.Effect<void, DataStoreError>;
+  /**
+   * Persist the resolved aspirational `coverageTargets` for the current
+   * run, distinct from the ratcheted `coverage_baselines` rows. Stored
+   * under `kind='target'`. See issue #237.
+   */
+  readonly writeTargets: (targets: ResolvedThresholds) => Effect.Effect<void, DataStoreError>;
   readonly writeTrends: (project: string, runId: number, entry: TrendEntry) => Effect.Effect<void, DataStoreError>;
   readonly writeSourceMap: (sourceFilePath: string, testModuleId: number, mappingType: string) => Effect.Effect<void, DataStoreError>;
   readonly ensureFile: (filePath: string) => Effect.Effect<number, DataStoreError>;
@@ -1048,6 +1123,20 @@ declare const DataStore_base: Context.ServiceClass<DataStore, "vitest-agent/Data
    * `INSERT ... ON CONFLICT DO NOTHING`.
    */
   readonly upsertSession: (input: SessionInput) => Effect.Effect<number, DataStoreError>;
+  /**
+   * Backfill `sessions.conversation_id` for a row that was inserted
+   * before the canonical conversation id was known (issue #144) —
+   * `record session-start` always precedes `register-agent`, so the
+   * session row exists first. Race-safe and idempotent: the UPDATE's
+   * `WHERE conversation_id IS NULL` guard means a session that
+   * already carries a value is left untouched (zero rows affected),
+   * matching the trigger's null→value-only relaxation rather than
+   * risking an immutability-violation error on a redundant call.
+   */
+  readonly setSessionConversationIdIfNull: (input: {
+    readonly sessionId: number;
+    readonly conversationId: string;
+  }) => Effect.Effect<void, DataStoreError>;
   readonly writeTurn: (input: TurnInput) => Effect.Effect<number, DataStoreError>;
   readonly writeFailureSignature: (input: FailureSignatureWriteInput) => Effect.Effect<void, DataStoreError>;
   readonly endSession: (chatId: string, endedAt: string, endReason: string | null) => Effect.Effect<void, DataStoreError>;
@@ -1225,6 +1314,8 @@ interface SessionDetail {
   readonly startedAt: string;
   readonly endedAt: string | null;
   readonly endReason: string | null;
+  /** Canonical conversation UUID this session belongs to (issue #144), null when unset. */
+  readonly conversationId: string | null;
 }
 /** @public */
 interface TurnSummary {
@@ -1406,6 +1497,7 @@ interface TddArtifactRow {
   readonly testRunId: number | null;
   readonly testFirstFailureRunId: number | null;
   readonly recordedAt: string;
+  readonly suite: ArtifactSuite;
 }
 /** @public */
 interface TagInventoryRow {
@@ -1519,7 +1611,32 @@ declare const DataReader_base: Context.ServiceClass<DataReader, "vitest-agent/Da
      * preserves the prior single-session contract.
      */
     readonly walkParents?: boolean;
+    /**
+     * When true AND `sessionId`'s session has a non-null
+     * `conversation_id`, also return tdd_tasks belonging to
+     * any OTHER session sharing that `conversation_id` — the
+     * detached-session fallback (issue #144). A session with
+     * a null `conversation_id` never triggers this fallback.
+     * Rows are ordered so a task owned by an `agent_kind =
+     * 'main'` session sorts first, then by `started_at DESC`.
+     * Default `false` preserves the prior contract.
+     */
+    readonly walkConversation?: boolean;
   }) => Effect.Effect<ReadonlyArray<TddTaskSummary>, DataStoreError>;
+  /**
+   * Diagnostic for the `missing_artifact_evidence` phase-transition
+   * denial (issue #144): counts `tdd_artifacts` rows recorded at or
+   * after `sinceIso` under sessions OTHER than the one that opened
+   * `tddTaskId`, but sharing that session's `conversation_id`. Used
+   * to tell an agent "your hooks may be attributing to a detached
+   * session" rather than a bare "no artifact found". Returns 0 when
+   * `tddTaskId` is unknown or its session's `conversation_id` is
+   * null — the diagnostic never fabricates a signal it cannot back.
+   */
+  readonly countRecentArtifactsInOtherSessionsOfConversation: (input: {
+    readonly tddTaskId: number;
+    readonly sinceIso: string;
+  }) => Effect.Effect<number, DataStoreError>;
   /**
    * List artifacts recorded for a TDD task, optionally filtered
    * by `artifactKind`, `phaseId`, or `behaviorId`. Returns rows in
@@ -1578,5 +1695,5 @@ declare function flaky(filename: string): Layer.Layer<DataReader | DataStore | i
 /** @public */
 declare function withTddTask(filename: string): Layer.Layer<DataReader | DataStore | import("effect/unstable/sql/SqlClient").SqlClient | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | import("@effect/platform-node/NodeServices").NodeServices, BehaviorNotFoundError | DataStoreError | GoalNotFoundError | IllegalStatusTransitionError | import("@effect/sql-sqlite-node/SqliteMigrator").MigrationError | import("effect/unstable/sql/SqlError").SqlError | TddTaskAlreadyEndedError | TddTaskNotFoundError, never>;
 //#endregion
-export { type AcceptanceMetrics, Agent, AgentId, AgentNotFoundError, AgentReport, type ArtifactKind, 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, DataReader, DataStore, DataStoreError, DataStoreTestLayer, 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 PersistentFailure, type Phase, type ProjectRunSummary, type RegisterAgentInput, RegistrationConflictError, 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 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, empty, flaky, makeTestLayer, singlePassingRun, withFailures, withTddTask };
+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, DataReader, DataStore, DataStoreError, DataStoreTestLayer, 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 PersistentFailure, type Phase, 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 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, empty, flaky, makeTestLayer, singlePassingRun, withFailures, withTddTask };
 //# sourceMappingURL=testing.d.ts.map

package/utils/console-leaks.js

@@ -10,14 +10,28 @@ function truncateSample(content) {
 * Aggregate raw console-leak entries into a ConsoleLeaks signal:
 * bucket by file, split stdout/stderr, collect attributable test names,
 * capture one truncated sample per file, sort by total writes descending,
-* and cap the file list. Returns `undefined` when there are no entries so a
-* clean run attaches nothing.
+* and cap the file list. Entries logged inside a failing test (with
+* `failed` set) are excluded from `total`/`byFile` — the actionable leak signal —
+* and summarized instead in `fromFailingTests` (issue #263: a logger-backed
+* assertion failure otherwise makes every red run look like a leak). Returns
+* `undefined` only when there is no output at all, non-failing or failing.
 * @public
 */
 function buildConsoleLeaks(entries) {
 	if (entries.length === 0) return void 0;
+	const nonFailing = entries.filter((e) => e.failed !== true);
+	const failing = entries.filter((e) => e.failed === true);
+	const fromFailingTests = failing.length > 0 ? {
+		total: failing.length,
+		files: new Set(failing.map((e) => e.file)).size
+	} : void 0;
+	if (nonFailing.length === 0) return {
+		total: 0,
+		byFile: [],
+		...fromFailingTests !== void 0 ? { fromFailingTests } : {}
+	};
 	const byFile = /* @__PURE__ */ new Map();
-	for (const e of entries) {
+	for (const e of nonFailing) {
 		let acc = byFile.get(e.file);
 		if (acc === void 0) {
 			acc = {
@@ -46,30 +60,43 @@ function buildConsoleLeaks(entries) {
 	files.sort((a, b) => b.stdout + b.stderr - (a.stdout + a.stderr));
 	const truncated = files.length > MAX_FILES;
 	return {
-		total: entries.length,
+		total: nonFailing.length,
 		byFile: truncated ? files.slice(0, MAX_FILES) : files,
-		...truncated ? { truncated: true } : {}
+		...truncated ? { truncated: true } : {},
+		...fromFailingTests !== void 0 ? { fromFailingTests } : {}
 	};
 }
 /**
 * Walk a Vitest `File[]` task tree (from `vitest.state.getFiles()`) into flat
 * {@link ConsoleLeakEntry} values. Each task `log` becomes one entry attributed
 * to its enclosing file and, when the log sits on a test task, that test's name.
+* An entry is marked `failed: true` when it was logged inside a test whose own
+* `result.state` is `"fail"`, or — for output with no owning test — when the
+* enclosing file itself failed (e.g. a collection/load error).
 * @public
 */
 function collectConsoleLeakEntries(files) {
 	const entries = [];
-	const visit = (task, file, test) => {
-		const currentTest = task.type === "test" ? task.fullTestName ?? task.name ?? test : test;
-		for (const log of task.logs ?? []) entries.push({
-			file,
-			...currentTest !== void 0 ? { test: currentTest } : {},
-			type: log.type,
-			content: log.content
-		});
-		for (const child of task.tasks ?? []) visit(child, file, currentTest);
+	const visit = (task, file, test, testFailed, fileFailed) => {
+		const isTest = task.type === "test";
+		const currentTest = isTest ? task.fullTestName ?? task.name ?? test : test;
+		const currentTestFailed = isTest ? task.result?.state === "fail" : testFailed;
+		for (const log of task.logs ?? []) {
+			const failed = currentTest !== void 0 ? currentTestFailed : fileFailed;
+			entries.push({
+				file,
+				...currentTest !== void 0 ? { test: currentTest } : {},
+				type: log.type,
+				content: log.content,
+				...failed ? { failed: true } : {}
+			});
+		}
+		for (const child of task.tasks ?? []) visit(child, file, currentTest, currentTestFailed, fileFailed);
 	};
-	for (const file of files) visit(file, file.name ?? "(unknown)", void 0);
+	for (const file of files) {
+		const fileFailed = file.result?.state === "fail";
+		visit(file, file.name ?? "(unknown)", void 0, false, fileFailed);
+	}
 	return entries;
 }
 

package/utils/detect-non-default-discover-strategy.js

@@ -0,0 +1,38 @@
+//#region src/utils/detect-non-default-discover-strategy.ts
+/**
+* Cheaply strips `//` line comments and `/* *\/` block comments from `source`.
+*
+* Not a full lexer — a marker string that happens to sit inside a string
+* literal containing comment-like syntax could slip through uncaught. That
+* false positive is acceptable: {@link detectNonDefaultDiscoverStrategy} is
+* only ever used to decide whether to fail open, and failing open is the
+* safe direction.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\//g, "").replace(/\/\/.*$/gm, "");
+}
+const DISCOVER_STRATEGY_OPTION_RE = /\bdiscoverStrategy\s*:/;
+const ADD_PROJECT_MARKER = ".addProject(";
+const EXTENDS_DEFAULT_STRATEGY_RE = /\bextends\s+DefaultDiscoverStrategy\b/;
+const IMPLEMENTS_STRATEGY_RE = /\bimplements\s+DiscoverStrategy\b/;
+/**
+* Lexically detects whether a Vitest/Vite config source text appears to
+* configure a non-default `DiscoverStrategy` — a custom `discoverStrategy`
+* option (including `discoverStrategy: false`), an `AgentPlugin.discover()`
+* `.addProject(...)` chain, or a class extending `DefaultDiscoverStrategy` /
+* implementing `DiscoverStrategy`.
+*
+* Pure and comment-tolerant (best-effort): a marker mentioned only inside a
+* comment may still register as a false positive if it isn't caught by the
+* comment-stripping pass. That is intentional — this function only ever
+* decides whether to fail open, so a false positive is harmless while a
+* false negative would produce a confidently wrong deny.
+* @public
+*/
+function detectNonDefaultDiscoverStrategy(source) {
+	const stripped = stripComments(source);
+	return DISCOVER_STRATEGY_OPTION_RE.test(stripped) || stripped.includes(ADD_PROJECT_MARKER) || EXTENDS_DEFAULT_STRATEGY_RE.test(stripped) || IMPLEMENTS_STRATEGY_RE.test(stripped);
+}
+
+//#endregion
+export { detectNonDefaultDiscoverStrategy };

package/utils/format-console.js

@@ -1,4 +1,5 @@
 import { ansi } from "./ansi.js";
+import { formatScopedCoverageNote } from "./format-scoped-coverage-note.js";
 
 //#region src/utils/format-console.ts
 /**
@@ -161,6 +162,10 @@ function formatConsoleMarkdown(report, options) {
 	if (report.coverage) {
 		const cov = report.coverage;
 		const globalThresholds = cov.thresholds.global;
+		if (cov.scoped) {
+			lines.push(formatScopedCoverageNote(cov.scopedFiles?.length ?? 0, cov.totalFiles));
+			lines.push("");
+		}
 		const filesToShow = cov.lowCoverage.slice(0, coverageConsoleLimit);
 		if (filesToShow.length > 0) {
 			lines.push(`### Coverage gaps`);

package/utils/format-scoped-coverage-note.js

@@ -0,0 +1,25 @@
+//#region src/utils/format-scoped-coverage-note.ts
+/**
+* Format the informational note shown when coverage thresholds were
+* skipped because a run only exercised a subset of the project's test
+* files (issue #160). Vitest's coverage provider enforces
+* `coverage.thresholds` against the whole-project denominator
+* regardless of how many files actually ran, so callers that detect a
+* scoped/partial run suppress the native threshold check and surface
+* this note instead so the agent understands why no pass/fail verdict
+* was rendered for coverage.
+*
+* @param testedFileCount - number of test files that actually ran
+* @param totalFileCount - total number of test files in the project, when
+*   known. Some callers (formatters working from a persisted
+*   `CoverageReport`, which tracks only the tested-file list) cannot supply
+*   this; the note degrades to `"(N test files)"` when omitted.
+* @returns the note text, e.g. `"Coverage thresholds skipped: partial run (2 of 47 test files)"`
+* @public
+*/
+function formatScopedCoverageNote(testedFileCount, totalFileCount) {
+	return `Coverage thresholds skipped: partial run (${totalFileCount !== void 0 ? `${testedFileCount} of ${totalFileCount}` : `${testedFileCount}`} test files)`;
+}
+
+//#endregion
+export { formatScopedCoverageNote };

package/utils/format-terminal.js

@@ -1,4 +1,5 @@
 import { ansi } from "./ansi.js";
+import { formatScopedCoverageNote } from "./format-scoped-coverage-note.js";
 import { relativePath } from "./format-console.js";
 import { compressLines } from "./compress-lines.js";
 
@@ -257,6 +258,9 @@ const aggregateCoverage = (reports) => {
 	let hasCoverage = false;
 	let thresholdsGlobal;
 	let targetsGlobal;
+	let scoped = false;
+	let scopedFileCount = 0;
+	let totalFiles;
 	const belowTargetByFile = /* @__PURE__ */ new Map();
 	const belowThresholdByFile = /* @__PURE__ */ new Map();
 	for (const r of reports) {
@@ -265,6 +269,11 @@ const aggregateCoverage = (reports) => {
 		hasCoverage = true;
 		thresholdsGlobal ??= cov.thresholds.global;
 		targetsGlobal ??= cov.targets?.global;
+		if (cov.scoped) {
+			scoped = true;
+			scopedFileCount = Math.max(scopedFileCount, cov.scopedFiles?.length ?? 0);
+			if (cov.totalFiles !== void 0) totalFiles = cov.totalFiles;
+		}
 		if (cov.lowCoverage) {
 			for (const f of cov.lowCoverage) if (!belowThresholdByFile.has(f.file)) belowThresholdByFile.set(f.file, f);
 		}
@@ -279,8 +288,11 @@ const aggregateCoverage = (reports) => {
 		thresholdsMet: belowThresholdCount === 0,
 		belowThresholdCount,
 		belowTargetFiles,
+		scoped,
+		scopedFileCount,
 		...thresholdsGlobal !== void 0 ? { thresholdsGlobal } : {},
-		...targetsGlobal !== void 0 ? { targetsGlobal } : {}
+		...targetsGlobal !== void 0 ? { targetsGlobal } : {},
+		...totalFiles !== void 0 ? { totalFiles } : {}
 	};
 };
 /**
@@ -294,7 +306,8 @@ const renderCoverageSection = (reports, options, ao) => {
 	const lines = [];
 	const thresholdSpec = agg.thresholdsGlobal ? formatTargetSpec(agg.thresholdsGlobal) : "";
 	const targetSpec = agg.targetsGlobal ? formatTargetSpec(agg.targetsGlobal) : "";
-	if (!agg.thresholdsMet) {
+	if (agg.scoped) lines.push(formatScopedCoverageNote(agg.scopedFileCount, agg.totalFiles));
+	else if (!agg.thresholdsMet) {
 		const cross = ansi("✗", "red", ao);
 		const fileWord = agg.belowThresholdCount === 1 ? "file" : "files";
 		lines.push(`Coverage: ${cross} ${agg.belowThresholdCount} ${fileWord} below minimum thresholds${thresholdSpec ? ` (${thresholdSpec})` : ""}`);

package/utils/validate-phase-transition.js

@@ -55,6 +55,19 @@ const validatePhaseTransition = (ctx) => {
 			humanHint: `Cannot transition from '${ctx.current_phase}' directly to 'green'. The red phase must be entered explicitly first (${ctx.current_phase}→red), then a failing test written and run, then red→green requested with a test_failed_run artifact.`
 		}
 	};
+	if (ctx.requested_phase === "refactor" && ctx.current_phase !== "green" && ctx.current_phase !== "green.fake-it") {
+		const canEnterGreen = ctx.current_phase === "red" || ctx.current_phase === "red.triangulate";
+		return {
+			accepted: false,
+			phase: ctx.current_phase,
+			denialReason: "refactor_without_passing_run",
+			remediation: {
+				suggestedTool: "tdd_phase_transition_request",
+				suggestedArgs: { requestedPhase: canEnterGreen ? "green" : "red" },
+				humanHint: canEnterGreen ? `Cannot transition from '${ctx.current_phase}' directly to 'refactor'. The green phase must be entered first (${ctx.current_phase}→green with a test_failed_run artifact), then green→refactor requested with a test_passed_run artifact.` : `Cannot transition from '${ctx.current_phase}' directly to 'refactor'. Enter red first (${ctx.current_phase}→red), write and run a failing test, request red→green with a test_failed_run artifact, then green→refactor with a test_passed_run artifact.`
+			}
+		};
+	}
 	const isTriangulateGreen = ctx.current_phase === "red.triangulate" && ctx.requested_phase === "green";
 	const expected = requiredArtifactForTransition(ctx.current_phase, ctx.requested_phase);
 	if (expected === null) return {
@@ -71,28 +84,29 @@ const validatePhaseTransition = (ctx) => {
 			humanHint: expected.humanHint
 		}
 	};
-	if (ctx.cited_artifact.test_case_id === null) return {
+	const isBatsRunLevel = ctx.cited_artifact.test_case_id === null && (ctx.cited_artifact.suite ?? "vitest") === "bats";
+	if (ctx.cited_artifact.test_case_id === null && !isBatsRunLevel) return {
 		accepted: false,
 		phase: ctx.current_phase,
 		denialReason: "missing_artifact_evidence",
 		remediation: {
 			suggestedTool: "run_tests",
 			suggestedArgs: {},
-			humanHint: "The cited artifact has no specific test (test_case_id is null), so it cannot be bound to this phase. Run a specific failing test via run_tests so the resulting artifact carries a test_case_id, then cite that artifact."
+			humanHint: "The cited artifact is run-level (test_case_id is null) and its suite is 'vitest', so it cannot be bound to this phase — only bats-suite run-level artifacts are accepted without a specific test. Run a specific failing test via run_tests so the resulting artifact carries a test_case_id, then cite that artifact."
 		}
 	};
-	if (expected.kind === "test_failed_run") {
-		if (!isTriangulateGreen && ctx.cited_artifact.test_case_created_turn_at !== null && ctx.cited_artifact.test_case_created_turn_at < ctx.phase_started_at) return {
+	if (expected.kind === "test_failed_run" || isBatsRunLevel && expected.kind === "test_passed_run") {
+		if (!isTriangulateGreen && ctx.current_phase_id !== null && ctx.cited_artifact.phase_id !== ctx.current_phase_id) return {
 			accepted: false,
 			phase: ctx.current_phase,
 			denialReason: "evidence_not_in_phase_window",
 			remediation: {
 				suggestedTool: "run_tests",
 				suggestedArgs: {},
-				humanHint: "The cited test was authored before this phase started. Write a new failing test inside the current phase."
+				humanHint: "The cited artifact was recorded in a different phase than the one currently open. Run the failing test again inside the current phase so a fresh test_failed_run artifact is bound to it."
 			}
 		};
-		if (!ctx.cited_artifact.test_case_authored_in_session) return {
+		if (!isBatsRunLevel && !ctx.cited_artifact.test_case_authored_in_session) return {
 			accepted: false,
 			phase: ctx.current_phase,
 			denialReason: "evidence_not_in_phase_window",