@vitest-agent/engine 0.1.0

package/index.d.ts

@@ -0,0 +1,2679 @@
+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, FormatterContext, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, OutputFormat, Phase, ProjectIdentityNotResolvableError, RegistrationConflictError, RenderedOutput, ResolvedThresholds, TddTaskAlreadyEndedError, TddTaskNotFoundError, TestClassification, TestRun, TrendEntry, TrendRecord, TurnPayload, VitestAgentConfig } from "@vitest-agent/sdk";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+import { WorkspaceDiscovery, WorkspaceDiscoveryFailure, WorkspaceRootNotFoundError } from "@effected/workspaces";
+import { AppDirs, AppDirsError, XdgEnvError } from "@effected/xdg";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { SqliteClient } from "@effect/sql-sqlite-node/SqliteClient";
+import { MigrationError } from "effect/unstable/sql/Migrator";
+import { SqlError } from "effect/unstable/sql/SqlError";
+import { PlatformError } from "effect/PlatformError";
+//#region src/services/Config.d.ts
+/**
+ * Service shape that `ConfigLive(projectDir)` provides to downstream
+ * consumers. Re-exported so callers can spell out the concrete service
+ * type without referencing the `ConfigFileShape<A>` generic directly.
+ * @public
+ */
+export type VitestAgentConfigFileService = ConfigFileShape<VitestAgentConfig>;
+declare const VitestAgentConfigFile_base: import("effect/Context").ServiceClass<VitestAgentConfigFile, "vitest-agent/Config", ConfigFileShape<VitestAgentConfig>>;
+/**
+ * Typed service class (Context tag) for the vitest-agent config file service.
+ *
+ * Both runtime packages (reporter, MCP) yield this tag to access the loaded
+ * `VitestAgentConfig`. The live layer is built per `projectDir` via
+ * `ConfigLive(projectDir)`.
+ * @public
+ */
+export declare class VitestAgentConfigFile extends VitestAgentConfigFile_base {}
+//#endregion
+//#region src/layers/ConfigLive.d.ts
+/**
+ * Build the live `ConfigFile` layer for a given project directory.
+ *
+ * Resolves the optional `vitest-agent.config.toml` from (in order):
+ *
+ * 1. The workspace root (when `projectDir` is inside a pnpm/npm/yarn workspace).
+ * 2. The git repository root (when `projectDir` is inside a git repo).
+ * 3. Walking upward from `projectDir`.
+ *
+ * The first found file wins (`MergeStrategy.firstMatch()`). If no file is
+ * present, downstream callers use `loadOrDefault(new VitestAgentConfig({}))`
+ * to get an empty config.
+ *
+ * @param projectDir - Absolute path inside the user's workspace. Resolvers
+ *   anchor here rather than `process.cwd()` so the plugin-spawned MCP server
+ *   sees the right config even when invoked from elsewhere.
+ * @public
+ */
+export declare const ConfigLive: (projectDir: string) => Layer.Layer<VitestAgentConfigFile, never, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/services/DataStore.d.ts
+/** @public */
+export interface CreateGoalInput {
+  readonly tddTaskId: number;
+  readonly goal: string;
+}
+/** @public */
+export interface UpdateGoalInput {
+  readonly id: number;
+  readonly goal?: string;
+  readonly status?: GoalStatus;
+}
+/** @public */
+export interface CreateBehaviorInput {
+  readonly goalId: number;
+  readonly behavior: string;
+  readonly suggestedTestName?: string;
+  readonly dependsOnBehaviorIds?: ReadonlyArray<number>;
+}
+/** @public */
+export interface UpdateBehaviorInput {
+  readonly id: number;
+  readonly behavior?: string;
+  readonly suggestedTestName?: string | null;
+  readonly status?: BehaviorStatus;
+  readonly dependsOnBehaviorIds?: ReadonlyArray<number>;
+}
+/** @public */
+export interface SettingsInput {
+  readonly vitestVersion: string;
+  readonly pool?: string;
+  readonly environment?: string;
+  readonly testTimeout?: number;
+  readonly hookTimeout?: number;
+  readonly slowTestThreshold?: number;
+  readonly maxConcurrency?: number;
+  readonly maxWorkers?: number;
+  readonly isolate?: boolean;
+  readonly bail?: number;
+  readonly globals?: boolean;
+  readonly fileParallelism?: boolean;
+  readonly sequenceSeed?: number;
+  readonly coverageProvider?: string;
+}
+/** @public */
+export interface TestRunInput {
+  readonly invocationId: string;
+  readonly project: string;
+  readonly settingsHash: string;
+  readonly timestamp: string;
+  readonly commitSha: string | null;
+  readonly branch: string | null;
+  readonly reason: "passed" | "failed" | "interrupted";
+  readonly duration: number;
+  readonly total: number;
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+  readonly scoped: boolean;
+  readonly snapshotAdded?: number;
+  readonly snapshotMatched?: number;
+  readonly snapshotUnmatched?: number;
+  readonly snapshotUpdated?: number;
+  readonly snapshotUnchecked?: number;
+  readonly snapshotTotal?: number;
+  readonly snapshotFailure?: boolean;
+  readonly snapshotDidUpdate?: boolean;
+  readonly snapshotFilesAdded?: number;
+  readonly snapshotFilesRemoved?: number;
+  readonly snapshotFilesUnmatched?: number;
+  readonly snapshotFilesUpdated?: number;
+  /**
+   * Attribution columns added by the agent-agnostic taxonomy work. The
+   * reporter walks env vars / session map to populate these; un-attributed
+   * runs default to actor_type='system' and NULL agent/conversation ids.
+   */
+  readonly actorType?: "agent" | "user" | "system";
+  readonly agentId?: string | null;
+  readonly conversationId?: string | null;
+  /**
+   * Git context the run executed against. NULL for non-git workspaces.
+   */
+  readonly gitBranch?: string | null;
+  readonly gitCommitSha?: string | null;
+  readonly gitDirty?: boolean | null;
+  readonly gitUpstream?: string | null;
+  readonly gitWorktreeDir?: string | null;
+  /**
+   * Host metadata probe result (terminal pane, CI runner). NULL when no
+   * probe in the priority chain matched.
+   * @public
+   */
+  readonly hostSource?: string | null;
+  readonly hostValue?: string | null;
+  readonly hostMetadata?: Record<string, unknown> | null;
+}
+/** @public */
+export interface ModuleInput {
+  readonly fileId: number;
+  readonly relativeModuleId: string;
+  readonly state: string;
+  readonly duration?: number;
+  readonly environmentSetupDuration?: number;
+  readonly prepareDuration?: number;
+  readonly collectDuration?: number;
+  readonly setupDuration?: number;
+  readonly heap?: number;
+}
+/** @public */
+export interface TestCaseInput {
+  readonly suiteId?: number;
+  readonly vitestId?: string;
+  readonly name: string;
+  readonly fullName: string;
+  readonly state: string;
+  readonly classification?: string;
+  readonly duration?: number;
+  readonly startTime?: number;
+  readonly flaky?: boolean;
+  readonly slow?: boolean;
+  readonly retryCount?: number;
+  readonly repeatCount?: number;
+  readonly heap?: number;
+  readonly mode?: string;
+  readonly each?: boolean;
+  readonly fails?: boolean;
+  readonly concurrent?: boolean;
+  readonly shuffle?: boolean;
+  readonly timeout?: number;
+  readonly skipNote?: string;
+  readonly locationLine?: number;
+  readonly locationColumn?: number;
+  readonly tags?: readonly string[];
+  /**
+   * FK to `turns(id)`. Set by the reporter when the test case row was
+   * authored within a recorded turn (D2 binding rule 1).
+   * @public
+   */
+  readonly createdTurnId?: number;
+}
+/** @public */
+export interface StackFrameInput {
+  readonly ordinal: number;
+  readonly method: string | null;
+  readonly filePath: string;
+  readonly line: number;
+  readonly col: number;
+  readonly sourceMappedLine?: number;
+  readonly functionBoundaryLine?: number;
+}
+/** @public */
+export interface TestErrorInput {
+  readonly testCaseId?: number;
+  readonly testSuiteId?: number;
+  readonly moduleId?: number;
+  readonly scope: "test" | "suite" | "module" | "unhandled";
+  readonly name?: string;
+  readonly message: string;
+  readonly diff?: string;
+  readonly actual?: string;
+  readonly expected?: string;
+  readonly stack?: string;
+  readonly causeErrorId?: number;
+  readonly signatureHash?: string;
+  readonly frames?: ReadonlyArray<StackFrameInput>;
+  readonly ordinal?: number;
+}
+/**
+ * Ceiling on an inline attachment body. Vitest has already copied file
+ * attachments into `.vitest/attachments/`, so a large body is referenced
+ * by `path` rather than duplicated into `data.db`.
+ * @public
+ */
+export declare const INLINE_ATTACHMENT_BODY_CAP_BYTES: number;
+/** @public */
+export interface TestAttachmentInput {
+  readonly contentType?: string;
+  /** Post-resolution path under `.vitest/attachments/`, or an http(s) URL. */
+  readonly path?: string;
+  /** Inline body; persisted only when `byteSize` is under the 64 KiB cap. */
+  readonly body?: string;
+  /** How to read `body`. Vitest treats a string body as base64 unless `"utf-8"`. */
+  readonly bodyEncoding?: "base64" | "utf-8";
+  readonly byteSize: number;
+}
+/** @public */
+export interface TestAnnotationInput {
+  readonly testCaseId: number;
+  /** Arbitrary Vitest annotation type -- not an enum. */
+  readonly type: string;
+  readonly message: string;
+  readonly locationFile?: string;
+  readonly locationLine?: number;
+  readonly locationColumn?: number;
+  readonly attachments?: ReadonlyArray<TestAttachmentInput>;
+}
+/** @public */
+export interface TestArtifactInput {
+  readonly testCaseId: number;
+  /** `pkg:name`; `internal:` types are Vitest's own and are never written. */
+  readonly type: string;
+  readonly message?: string;
+  /** JSON of the artifact's custom fields, minus attachments and location. */
+  readonly data?: string;
+  readonly locationFile?: string;
+  readonly locationLine?: number;
+  readonly locationColumn?: number;
+  readonly attachments?: ReadonlyArray<TestAttachmentInput>;
+}
+/** @public */
+export interface FileCoverageInput {
+  readonly fileId: number;
+  readonly statements: number;
+  readonly branches: number;
+  readonly functions: number;
+  readonly lines: number;
+  readonly uncoveredLines?: string;
+  /**
+   * Coverage tier this row represents. `'below_threshold'` is the
+   * build-failing tier (file falls below the configured minimum
+   * coverage thresholds). `'below_target'` is the warning tier (file
+   * is above thresholds but below the aspirational target).
+   *
+   * Defaults to `'below_threshold'` when omitted, matching the only
+   * tier that existed before migration 0005.
+   * @public
+   */
+  readonly tier?: "below_threshold" | "below_target";
+}
+/** @public */
+export interface SuiteInput {
+  readonly parentSuiteId?: number;
+  readonly name: string;
+  readonly fullName: string;
+  readonly state: "pending" | "passed" | "failed" | "skipped";
+  readonly mode?: "run" | "only" | "skip" | "todo";
+  readonly concurrent?: boolean;
+  readonly shuffle?: boolean;
+  readonly retry?: number;
+  readonly repeats?: number;
+  readonly locationLine?: number;
+  readonly locationColumn?: number;
+}
+/** @public */
+export interface NoteInput {
+  readonly title: string;
+  readonly content: string;
+  readonly scope: "global" | "project" | "module" | "suite" | "test" | "note";
+  readonly project?: string;
+  readonly testFullName?: string;
+  readonly modulePath?: string;
+  readonly parentNoteId?: number;
+  readonly createdBy?: string;
+  readonly expiresAt?: string;
+  readonly pinned?: boolean;
+}
+/** @public */
+export interface SessionInput {
+  readonly chatId: string;
+  readonly project: string;
+  readonly cwd: string;
+  readonly agentKind: "main" | "subagent";
+  readonly agentType?: string;
+  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 */
+export interface TurnInput {
+  readonly sessionId: number;
+  /** When omitted, writeTurn computes MAX(turnNo) + 1 for the session. */
+  readonly turnNo?: number;
+  readonly type: "user_prompt" | "tool_call" | "tool_result" | "file_edit" | "hook_fire" | "note" | "hypothesis";
+  readonly payload: string;
+  readonly occurredAt: string;
+}
+/** @public */
+export interface FailureSignatureWriteInput {
+  readonly signatureHash: string;
+  readonly runId: number;
+  readonly seenAt: string;
+}
+/** @public */
+export interface HypothesisInput {
+  readonly sessionId: number;
+  readonly content: string;
+  readonly createdTurnId?: number;
+  readonly citedTestErrorId?: number;
+  readonly citedStackFrameId?: number;
+}
+/** @public */
+export interface ValidateHypothesisInput {
+  readonly id: number;
+  readonly outcome: "confirmed" | "refuted" | "abandoned";
+  readonly validatedTurnId?: number;
+  readonly validatedAt: string;
+}
+/** @public */
+export interface IdempotentResponseInput {
+  readonly procedurePath: string;
+  readonly key: string;
+  readonly resultJson: string;
+  readonly createdAt: string;
+}
+/** @public */
+export interface TddTaskInput {
+  readonly sessionId: number;
+  readonly goal: string;
+  readonly startedAt: string;
+  readonly parentTddTaskId?: number;
+  readonly runId?: string;
+}
+/** @public */
+export interface EndTddTaskInput {
+  readonly id: number;
+  readonly endedAt: string;
+  readonly outcome: "succeeded" | "blocked" | "abandoned";
+  readonly summaryNoteId?: number;
+}
+/** @public */
+export interface WriteTddPhaseInput {
+  readonly tddTaskId: number;
+  readonly behaviorId?: number;
+  readonly phase: Phase;
+  readonly startedAt: string;
+  readonly transitionReason?: string;
+  readonly parentPhaseId?: number;
+}
+/** @public */
+export interface WriteTddPhaseOutput {
+  readonly id: number;
+  readonly previousPhaseId: number | null;
+}
+/** @public */
+export interface WriteTddArtifactInput {
+  readonly phaseId: number;
+  readonly artifactKind: ArtifactKind;
+  readonly fileId?: number;
+  readonly testCaseId?: number;
+  readonly testRunId?: number;
+  readonly testFirstFailureRunId?: number;
+  readonly diffExcerpt?: string;
+  readonly recordedAt: string;
+  /** Issue #363: explicit suite marker. Defaults to `"vitest"` when omitted. */
+  readonly suite?: ArtifactSuite;
+}
+/** @public */
+export interface WriteCommitInput {
+  readonly sha: string;
+  readonly parentSha?: string;
+  readonly message?: string;
+  readonly author?: string;
+  readonly committedAt?: string;
+  readonly branch?: string;
+}
+/** @public */
+export type ChangeKind = "added" | "modified" | "deleted" | "renamed" | "untracked-modified";
+/** @public */
+export interface RunChangedFile {
+  readonly filePath: string;
+  readonly changeKind: ChangeKind;
+  readonly commitSha?: string;
+}
+/** @public */
+export interface WriteRunChangedFilesInput {
+  readonly runId: number;
+  readonly files: ReadonlyArray<RunChangedFile>;
+}
+/** @public */
+export type RunInvocationMethod = "bash" | "mcp" | "cli";
+/**
+ * Input to `DataStore.registerAgent`.
+ *
+ * `sessionId` is the FK to `sessions.id` (integer PK), NOT the host's
+ * chat UUID string. Callers that hold only the chat UUID must resolve
+ * it through `getSessionByChatId` first.
+ *
+ * `idempotencyKey` is pre-derived by the caller via
+ * `deriveIdempotencyKey(...)` — both the sidecar CLI and the MCP
+ * server compute it the same way so a hook retry collapses to the
+ * same row.
+ * @public
+ */
+export interface RegisterAgentInput {
+  readonly sessionId: number;
+  readonly agentType: string;
+  readonly parentAgentId: string | null;
+  readonly conversationId: string | null;
+  readonly startedAt: number;
+  readonly startGitBranch?: string;
+  readonly startGitCommitSha?: string;
+  readonly startWorktreeDir?: string;
+  readonly idempotencyKey: string;
+  /**
+   * Pre-allocated `agents.agent_id` UUID. The sidecar passes
+   * `PerClientSessionMapWriter.mapSession()`'s `main_agent_id` here so
+   * the per-project `agents` row and the per-client session_map row
+   * agree on a single canonical id — the same value the SessionStart
+   * hook exports as `VITEST_AGENT_MAIN_AGENT_ID` / `_AGENT_ID`. When
+   * omitted, the implementation generates a fresh UUID (used by tests
+   * and any caller without a session map).
+   */
+  readonly agentId?: string;
+}
+/** @public */
+export interface AssociateRunSessionInput {
+  readonly chatId: string;
+  readonly invocationMethod: RunInvocationMethod;
+}
+declare const DataStore_base: Context.ServiceClass<DataStore, "vitest-agent/DataStore", {
+  readonly writeSettings: (hash: string, settings: SettingsInput, envVars: Record<string, string>) => Effect.Effect<void, DataStoreError>;
+  readonly writeRun: (input: TestRunInput) => Effect.Effect<number, DataStoreError>;
+  readonly writeModules: (runId: number, modules: ReadonlyArray<ModuleInput>) => Effect.Effect<ReadonlyArray<number>, DataStoreError>;
+  readonly writeSuites: (moduleId: number, suites: ReadonlyArray<SuiteInput>) => Effect.Effect<ReadonlyArray<number>, DataStoreError>;
+  readonly writeTestCases: (moduleId: number, tests: ReadonlyArray<TestCaseInput>) => Effect.Effect<ReadonlyArray<number>, DataStoreError>;
+  readonly writeErrors: (runId: number, errors: ReadonlyArray<TestErrorInput>) => Effect.Effect<void, DataStoreError>;
+  /**
+   * Persist `context.annotate` notes and their attachment descriptors.
+   * `runId` is carried for log correlation only -- `test_annotations`
+   * rows are reachable through `test_cases`.
+   */
+  readonly writeAnnotations: (runId: number, annotations: ReadonlyArray<TestAnnotationInput>) => Effect.Effect<void, DataStoreError>;
+  /**
+   * Persist `recordArtifact` payloads and their attachment
+   * descriptors. `runId` is carried for log correlation only.
+   */
+  readonly writeArtifacts: (runId: number, artifacts: ReadonlyArray<TestArtifactInput>) => Effect.Effect<void, DataStoreError>;
+  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>;
+  readonly writeNote: (note: NoteInput) => Effect.Effect<number, DataStoreError>;
+  readonly updateNote: (id: number, fields: Partial<NoteInput>) => Effect.Effect<void, DataStoreError>;
+  readonly deleteNote: (id: number) => Effect.Effect<void, DataStoreError>;
+  readonly writeSession: (input: SessionInput) => Effect.Effect<number, DataStoreError>;
+  /**
+   * Idempotent variant of `writeSession`: if a row with this
+   * `chat_id` already exists, return its id and leave the stored
+   * fields untouched; otherwise insert a new row. Used by
+   * hook-triggered recording paths (artifacts, turns) that fire
+   * for sessions whose original `SessionStart` may have missed —
+   * e.g. when Claude Code rotates `chat_id` mid-window after a
+   * continuation or compaction. Race-safe via
+   * `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>;
+  readonly writeHypothesis: (input: HypothesisInput) => Effect.Effect<number, DataStoreError>;
+  readonly validateHypothesis: (input: ValidateHypothesisInput) => Effect.Effect<void, DataStoreError>;
+  readonly writeTddTask: (input: TddTaskInput) => Effect.Effect<number, DataStoreError>;
+  readonly endTddTask: (input: EndTddTaskInput) => Effect.Effect<void, DataStoreError>;
+  readonly createGoal: (input: CreateGoalInput) => Effect.Effect<GoalRow, DataStoreError | TddTaskNotFoundError | TddTaskAlreadyEndedError>;
+  readonly getGoal: (id: number) => Effect.Effect<Option.Option<GoalRow>, DataStoreError>;
+  readonly updateGoal: (input: UpdateGoalInput) => Effect.Effect<GoalRow, DataStoreError | GoalNotFoundError | TddTaskAlreadyEndedError | IllegalStatusTransitionError>;
+  readonly deleteGoal: (id: number) => Effect.Effect<void, DataStoreError | GoalNotFoundError>;
+  readonly listGoalsByTddTask: (tddTaskId: number) => Effect.Effect<ReadonlyArray<GoalRow>, DataStoreError | TddTaskNotFoundError>;
+  readonly createBehavior: (input: CreateBehaviorInput) => Effect.Effect<BehaviorRow, DataStoreError | GoalNotFoundError | BehaviorNotFoundError | TddTaskAlreadyEndedError | IllegalStatusTransitionError>;
+  readonly getBehavior: (id: number) => Effect.Effect<Option.Option<BehaviorRow>, DataStoreError>;
+  readonly updateBehavior: (input: UpdateBehaviorInput) => Effect.Effect<BehaviorRow, DataStoreError | BehaviorNotFoundError | TddTaskAlreadyEndedError | IllegalStatusTransitionError>;
+  readonly deleteBehavior: (id: number) => Effect.Effect<void, DataStoreError | BehaviorNotFoundError>;
+  readonly listBehaviorsByGoal: (goalId: number) => Effect.Effect<ReadonlyArray<BehaviorRow>, DataStoreError | GoalNotFoundError>;
+  readonly listBehaviorsByTddTask: (tddTaskId: number) => Effect.Effect<ReadonlyArray<BehaviorRow>, DataStoreError | TddTaskNotFoundError>;
+  readonly writeTddPhase: (input: WriteTddPhaseInput) => Effect.Effect<WriteTddPhaseOutput, DataStoreError>;
+  readonly writeTddArtifact: (input: WriteTddArtifactInput) => Effect.Effect<number, DataStoreError>;
+  readonly writeCommit: (input: WriteCommitInput) => Effect.Effect<void, DataStoreError>;
+  readonly writeRunChangedFiles: (input: WriteRunChangedFilesInput) => Effect.Effect<void, DataStoreError>;
+  readonly recordIdempotentResponse: (input: IdempotentResponseInput) => Effect.Effect<void, DataStoreError>;
+  readonly pruneSessions: (keepRecent: number) => Effect.Effect<{
+    readonly affectedSessions: number;
+    readonly prunedTurns: number;
+  }, DataStoreError>;
+  readonly associateLatestRunWithSession: (input: AssociateRunSessionInput) => Effect.Effect<void, DataStoreError>;
+  readonly backfillTestCaseTurns: (chatId: string) => Effect.Effect<number, DataStoreError>;
+  /**
+   * Idempotently insert an `agents` row.
+   *
+   * Returns `Agent` on a fresh insert, or `IdempotencyHit` carrying
+   * the existing `agentId` when the `(session_id, idempotency_key)`
+   * UNIQUE constraint already has a row. The caller treats the latter
+   * as a successful recovery (same logical agent), not an error.
+   *
+   * Fails with `RegistrationConflictError` when the supplied
+   * `parentAgentId` references an agent in a different session, or
+   * when no such agent exists. Surface to the caller for true
+   * mis-configuration cases; idempotency hits never produce this.
+   */
+  readonly registerAgent: (input: RegisterAgentInput) => Effect.Effect<Agent | IdempotencyHit, RegistrationConflictError | DataStoreError>;
+  /**
+   * Mark an agent as ended. Sets `agents.ended_at` to the supplied
+   * timestamp. Fails with `AgentNotFoundError` when no row exists.
+   */
+  readonly endAgent: (agentId: string, endedAt: number) => Effect.Effect<void, AgentNotFoundError | DataStoreError>;
+}>;
+/** @public */
+export declare class DataStore extends DataStore_base {}
+//#endregion
+//#region src/services/DataReader.d.ts
+/** @public */
+export interface ProjectRunSummary {
+  readonly project: string;
+  readonly lastRun: string | null;
+  readonly lastResult: "passed" | "failed" | "interrupted" | null;
+  readonly total: number;
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+}
+/** @public */
+export interface FlakyTest {
+  readonly fullName: string;
+  readonly modulePath: string;
+  readonly project: string;
+  readonly passCount: number;
+  readonly failCount: number;
+  readonly lastState: "passed" | "failed";
+  readonly lastTimestamp: string;
+}
+/** @public */
+export interface PersistentFailure {
+  readonly fullName: string;
+  readonly modulePath: string;
+  readonly project: string;
+  readonly consecutiveFailures: number;
+  readonly firstFailedAt: string;
+  readonly lastFailedAt: string;
+  readonly lastErrorMessage: string | null;
+}
+/** @public */
+export interface TestError {
+  /** `test_errors.id` — required by `hypothesis (action: record).citedTestErrorId`. */
+  readonly id: number;
+  /**
+   * `stack_frames.id` for the top frame of this error (ordinal 0), or
+   * `null` if no frames were captured. Required by
+   * `hypothesis (action: record).citedStackFrameId`.
+   */
+  readonly topStackFrameId: number | null;
+  readonly name: string | null;
+  readonly message: string;
+  readonly diff: string | null;
+  readonly actual: string | null;
+  readonly expected: string | null;
+  readonly stack: string | null;
+  readonly scope: "test" | "suite" | "module" | "unhandled";
+  readonly testFullName: string | null;
+  readonly moduleFile: string | null;
+}
+/** @public */
+export interface NoteRow {
+  readonly id: number;
+  readonly title: string;
+  readonly content: string;
+  readonly scope: "global" | "project" | "module" | "suite" | "test" | "note";
+  readonly project: string | null;
+  readonly testFullName: string | null;
+  readonly modulePath: string | null;
+  readonly parentNoteId: number | null;
+  readonly createdBy: string | null;
+  readonly expiresAt: string | null;
+  readonly pinned: boolean;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+/** @public */
+export interface SettingsRow {
+  readonly hash: string;
+  readonly reporters: string | null;
+  readonly coverageEnabled: boolean;
+  readonly coverageProvider: string | null;
+  readonly coverageThresholds: string | null;
+  readonly coverageTargets: string | null;
+  readonly pool: string | null;
+  readonly shard: string | null;
+  readonly project: string | null;
+  readonly environment: string | null;
+  readonly envVars: Record<string, string>;
+  readonly capturedAt: string;
+}
+/** @public */
+export interface TestListEntry {
+  readonly id: number;
+  readonly fullName: string;
+  readonly state: string;
+  readonly duration: number | null;
+  readonly module: string;
+  readonly classification: string | null;
+}
+/** @public */
+export interface ModuleListEntry {
+  readonly id: number;
+  readonly file: string;
+  readonly state: string;
+  readonly testCount: number;
+  readonly duration: number | null;
+}
+/** @public */
+export interface SuiteListEntry {
+  readonly id: number;
+  readonly name: string;
+  readonly module: string;
+  readonly state: string;
+  readonly testCount: number;
+}
+/** @public */
+export interface SettingsListEntry {
+  readonly hash: string;
+  readonly capturedAt: string;
+}
+/** @public */
+export interface SessionDetail {
+  readonly id: number;
+  readonly chatId: string;
+  readonly project: string;
+  readonly cwd: string;
+  readonly agentKind: "main" | "subagent";
+  readonly agentType: string | null;
+  readonly parentSessionId: number | null;
+  readonly triageWasNonEmpty: boolean;
+  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 */
+export interface TurnSummary {
+  readonly id: number;
+  readonly sessionId: number;
+  readonly turnNo: number;
+  readonly type: string;
+  readonly payload: string;
+  readonly occurredAt: string;
+}
+/** @public */
+export interface HistoryQueryOptions {
+  /** Exact `full_name` match — narrows to a single test's history. */
+  readonly testName?: string;
+  /** Exact `module_path` match — narrows to tests in one file. */
+  readonly modulePath?: string;
+  /** Max runs kept per (module_path, full_name) pair, most-recent-first. Default 20. */
+  readonly limit?: number;
+}
+/**
+ * Narrowing options shared by the classification reads
+ * (`DataReader.getFlaky` / `getPersistentFailures`). Mirrors the
+ * `testName` / `modulePath` half of {@link HistoryQueryOptions} so a
+ * caller that scoped `getHistory` to one test can scope the derived
+ * classifications to the same test instead of receiving the whole
+ * project's rows.
+ *
+ * @public
+ */
+export interface ClassificationQueryOptions {
+  /** Exact `full_name` match — narrows to a single test's classification. */
+  readonly testName?: string;
+  /** Exact `module_path` match — narrows to tests in one file. */
+  readonly modulePath?: string;
+}
+/**
+ * Narrowing options for `DataReader.getTestByFullName`. A
+ * `full_name` is not file-qualified (Decision D20), so the same name can
+ * exist in more than one module; `modulePath` disambiguates.
+ *
+ * @public
+ */
+export interface TestLookupOptions {
+  /** Exact `module_path` match — picks one variant of an ambiguous `full_name`. */
+  readonly modulePath?: string;
+}
+/** @public */
+export interface TurnSearchOptions {
+  readonly sessionId?: number;
+  readonly type?: string;
+  readonly since?: string;
+  readonly limit?: number;
+}
+/** @public */
+export interface AcceptanceMetrics {
+  readonly phaseEvidenceIntegrity: {
+    total: number;
+    compliant: number;
+    ratio: number;
+  };
+  readonly complianceHookResponsiveness: {
+    total: number;
+    withFollowup: number;
+    ratio: number;
+  };
+  readonly orientationUsefulness: {
+    total: number;
+    referencedCount: number;
+    ratio: number;
+  };
+  readonly antiPatternDetectionRate: {
+    total: number;
+    cleanSessions: number;
+    ratio: number;
+  };
+}
+/** @public */
+export interface FailureSignatureDetail {
+  readonly signatureHash: string;
+  readonly firstSeenRunId: number | null;
+  readonly firstSeenAt: string;
+  readonly lastSeenAt: string | null;
+  readonly occurrenceCount: number;
+  readonly recentErrors: ReadonlyArray<{
+    readonly runId: number;
+    readonly message: string;
+    readonly errorName: string | null;
+  }>;
+}
+/** @public */
+export interface TddPhaseDetail {
+  readonly id: number;
+  readonly behaviorId: number | null;
+  readonly phase: string;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly transitionReason: string | null;
+}
+/** @public */
+export interface TddArtifactDetail {
+  readonly id: number;
+  readonly phaseId: number;
+  readonly artifactKind: string;
+  readonly testCaseId: number | null;
+  readonly testRunId: number | null;
+  readonly recordedAt: string;
+}
+/** @public */
+export interface TddTaskDetail {
+  readonly id: number;
+  readonly sessionId: number;
+  readonly goal: string;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly outcome: string | null;
+  readonly runId: string | null;
+  readonly goals: ReadonlyArray<GoalDetail>;
+  readonly phases: ReadonlyArray<TddPhaseDetail>;
+  readonly artifacts: ReadonlyArray<TddArtifactDetail>;
+}
+/** @public */
+export interface CurrentTddPhase {
+  readonly id: number;
+  readonly phase: Phase;
+  readonly startedAt: string;
+  readonly behaviorId: number | null;
+}
+/** @public */
+export interface CitedArtifactRow extends CitedArtifact {
+  readonly phase_id: number;
+}
+/** @public */
+export interface CommitChangesEntry {
+  readonly sha: string;
+  readonly parentSha: string | null;
+  readonly message: string | null;
+  readonly author: string | null;
+  readonly committedAt: string | null;
+  readonly branch: string | null;
+  readonly files: ReadonlyArray<{
+    readonly filePath: string;
+    readonly changeKind: ChangeKind;
+  }>;
+}
+/** @public */
+export interface HypothesisDetail {
+  readonly id: number;
+  readonly sessionId: number;
+  readonly content: string;
+  readonly citedTestErrorId: number | null;
+  readonly citedStackFrameId: number | null;
+  readonly validationOutcome: "confirmed" | "refuted" | "abandoned" | null;
+  readonly validatedAt: string | null;
+}
+/** @public */
+export interface TddTaskSummary {
+  readonly id: number;
+  readonly sessionId: number;
+  readonly goal: string;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly outcome: "succeeded" | "blocked" | "abandoned" | null;
+}
+/**
+ * Row shape returned by `listTddArtifactsForTask`. Carries every
+ * field an agent typically needs to cite an artifact in a subsequent
+ * `tdd_phase_transition_request` call without further lookups.
+ *
+ * @public
+ */
+export interface TddArtifactRow {
+  readonly id: number;
+  readonly tddTaskId: number;
+  readonly phaseId: number;
+  readonly phaseName: Phase;
+  readonly artifactKind: ArtifactKind$1;
+  readonly behaviorId: number | null;
+  readonly testCaseId: number | null;
+  readonly testRunId: number | null;
+  readonly testFirstFailureRunId: number | null;
+  readonly recordedAt: string;
+  readonly suite: ArtifactSuite$1;
+}
+/** @public */
+export interface TagInventoryRow {
+  /** The tag name (e.g. `"int"`, `"e2e"`, `"unit"`). */
+  readonly tag: string;
+  /** The Vitest project this tag was observed in. */
+  readonly project: string;
+  /**
+   * Number of distinct test modules in the project's latest run that contain
+   * at least one test case carrying this tag.
+   */
+  readonly moduleCount: number;
+  /**
+   * Number of test cases in the project's latest run that carry this tag.
+   */
+  readonly testCount: number;
+}
+/** @public */
+export interface TestArtifactQueryOptions {
+  /** Disambiguates a fullName that exists in more than one module. */
+  readonly modulePath?: string;
+}
+/** @public */
+export interface PersistedAttachment {
+  readonly contentType?: string;
+  readonly path?: string;
+  readonly body?: string;
+  /** How to read `body`. Absent when nothing was stored inline. */
+  readonly bodyEncoding?: "base64" | "utf-8";
+  readonly byteSize: number | null;
+}
+/** @public */
+export interface TestAnnotationRow {
+  readonly id: number;
+  readonly type: string;
+  readonly message: string;
+  readonly location?: {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+  };
+  readonly attachments: ReadonlyArray<PersistedAttachment>;
+}
+/** @public */
+export interface TestArtifactRow {
+  readonly id: number;
+  readonly type: string;
+  readonly message: string | null;
+  readonly data: string | null;
+  readonly location?: {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+  };
+  readonly attachments: ReadonlyArray<PersistedAttachment>;
+}
+declare const DataReader_base: Context.ServiceClass<DataReader, "vitest-agent/DataReader", {
+  readonly getLatestRun: (project: string) => Effect.Effect<Option.Option<AgentReport>, DataStoreError>;
+  readonly getRunsByProject: () => Effect.Effect<ReadonlyArray<ProjectRunSummary>, DataStoreError>;
+  readonly getHistory: (project: string, options?: HistoryQueryOptions) => Effect.Effect<HistoryRecord, DataStoreError>;
+  readonly getBaselines: (project: string) => Effect.Effect<Option.Option<CoverageBaselines>, DataStoreError>;
+  readonly getTrends: (project: string, limit?: number) => Effect.Effect<Option.Option<TrendRecord>, DataStoreError>;
+  readonly getFlaky: (project: string, options?: ClassificationQueryOptions) => Effect.Effect<ReadonlyArray<FlakyTest>, DataStoreError>;
+  readonly getPersistentFailures: (project: string, options?: ClassificationQueryOptions) => Effect.Effect<ReadonlyArray<PersistentFailure>, DataStoreError>;
+  readonly getFileCoverage: (runId: number) => Effect.Effect<ReadonlyArray<FileCoverageReport>, DataStoreError>;
+  readonly getCoverage: (project: string) => Effect.Effect<Option.Option<CoverageReport>, DataStoreError>;
+  readonly getTestsForFile: (filePath: string) => Effect.Effect<ReadonlyArray<string>, DataStoreError>;
+  readonly getErrors: (project: string, errorName?: string) => Effect.Effect<ReadonlyArray<TestError>, DataStoreError>;
+  /** Annotations recorded for a test in the project's latest run. */
+  readonly getAnnotationsForTest: (project: string, fullName: string, options?: TestArtifactQueryOptions) => Effect.Effect<ReadonlyArray<TestAnnotationRow>, DataStoreError>;
+  /** Artifacts recorded for a test in the project's latest run. */
+  readonly getArtifactsForTest: (project: string, fullName: string, options?: TestArtifactQueryOptions) => Effect.Effect<ReadonlyArray<TestArtifactRow>, DataStoreError>;
+  readonly getNotes: (scope?: string, project?: string, testFullName?: string) => Effect.Effect<ReadonlyArray<NoteRow>, DataStoreError>;
+  readonly getNoteById: (id: number) => Effect.Effect<Option.Option<NoteRow>, DataStoreError>;
+  readonly searchNotes: (query: string) => Effect.Effect<ReadonlyArray<NoteRow>, DataStoreError>;
+  readonly getManifest: () => Effect.Effect<Option.Option<CacheManifest>, DataStoreError>;
+  readonly getSettings: (hash: string) => Effect.Effect<Option.Option<SettingsRow>, DataStoreError>;
+  readonly getLatestSettings: () => Effect.Effect<Option.Option<SettingsRow>, DataStoreError>;
+  readonly getTestByFullName: (project: string, fullName: string, options?: TestLookupOptions) => Effect.Effect<Option.Option<TestListEntry>, DataStoreError>;
+  /**
+   * Every module path in the project's latest run that carries a test
+   * case with this exact `full_name`, ordered ascending. Length > 1
+   * means the name is ambiguous and callers must disambiguate with
+   * {@link TestLookupOptions.modulePath} rather than guess.
+   */
+  readonly getTestModulesByFullName: (project: string, fullName: string) => Effect.Effect<ReadonlyArray<string>, DataStoreError>;
+  readonly listTests: (project: string, options?: {
+    state?: string;
+    module?: string;
+    limit?: number;
+  }) => Effect.Effect<ReadonlyArray<TestListEntry>, DataStoreError>;
+  readonly listModules: (project: string) => Effect.Effect<ReadonlyArray<ModuleListEntry>, DataStoreError>;
+  readonly listSuites: (project: string, options?: {
+    module?: string;
+  }) => Effect.Effect<ReadonlyArray<SuiteListEntry>, DataStoreError>;
+  readonly listSettings: () => Effect.Effect<ReadonlyArray<SettingsListEntry>, DataStoreError>;
+  readonly getSessionById: (id: number) => Effect.Effect<Option.Option<SessionDetail>, DataStoreError>;
+  readonly getSessionByChatId: (chatId: string) => Effect.Effect<Option.Option<SessionDetail>, DataStoreError>;
+  /**
+   * Find every session row whose `chat_id` begins with `prefix`.
+   * Used to recover the synthetic subagent row created by the
+   * SubagentStart hook (`<parentChatId>-subagent-<ts>-<pid>`)
+   * when subsequent PostToolUse hooks fire under the bare
+   * parent chat_id. Returns most recent first.
+   */
+  readonly findSessionsByChatPrefix: (prefix: string) => Effect.Effect<ReadonlyArray<SessionDetail>, DataStoreError>;
+  /**
+   * Find the most-recently-started subagent session whose
+   * `parent_session_id` is `parentSessionId` and that has not ended
+   * (`ended_at IS NULL`). Used to attribute orchestrator (subagent)
+   * MCP writes — e.g. `hypothesis record` — to the running subagent's
+   * own session row instead of the parent main session, since the MCP
+   * server's recovered context only ever names the main agent.
+   */
+  readonly findActiveSubagentSession: (parentSessionId: number) => Effect.Effect<Option.Option<SessionDetail>, DataStoreError>;
+  /**
+   * Resolve the session a TDD task was opened under: the `sessions`
+   * row whose `id` equals `tdd_tasks.session_id` for `tddTaskId`.
+   * Returns `Option.none` when the task — or its session — does not
+   * exist. Lets `hypothesis (action: record)` bind a hypothesis
+   * deterministically from the orchestrator's unambiguous
+   * `tddTaskId` (returned by `tdd_task (action: start)`) instead of
+   * the fragile recovered host context or a caller-guessed
+   * `sessionId`.
+   */
+  readonly getSessionByTddTaskId: (tddTaskId: number) => Effect.Effect<Option.Option<SessionDetail>, DataStoreError>;
+  readonly listSessions: (options: {
+    readonly project?: string;
+    readonly agentKind?: "main" | "subagent";
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<SessionDetail>, DataStoreError>;
+  readonly searchTurns: (options: TurnSearchOptions) => Effect.Effect<ReadonlyArray<TurnSummary>, DataStoreError>;
+  readonly computeAcceptanceMetrics: () => Effect.Effect<AcceptanceMetrics, DataStoreError>;
+  readonly getFailureSignatureByHash: (hash: string) => Effect.Effect<Option.Option<FailureSignatureDetail>, DataStoreError>;
+  readonly getTddTaskById: (id: number) => Effect.Effect<Option.Option<TddTaskDetail>, DataStoreError>;
+  readonly getGoalById: (id: number) => Effect.Effect<Option.Option<GoalDetail>, DataStoreError>;
+  readonly getGoalsByTddTask: (tddTaskId: number) => Effect.Effect<ReadonlyArray<GoalDetail>, DataStoreError>;
+  readonly getBehaviorById: (id: number) => Effect.Effect<Option.Option<BehaviorDetail>, DataStoreError>;
+  readonly getBehaviorsByGoal: (goalId: number) => Effect.Effect<ReadonlyArray<BehaviorRow>, DataStoreError>;
+  readonly getBehaviorsByTddTask: (tddTaskId: number) => Effect.Effect<ReadonlyArray<BehaviorRow>, DataStoreError>;
+  readonly getBehaviorDependencies: (behaviorId: number) => Effect.Effect<ReadonlyArray<BehaviorRow>, DataStoreError>;
+  readonly resolveGoalIdForBehavior: (behaviorId: number) => Effect.Effect<Option.Option<number>, DataStoreError>;
+  readonly getCurrentTddPhase: (tddTaskId: number) => Effect.Effect<Option.Option<CurrentTddPhase>, DataStoreError>;
+  readonly getTddArtifactWithContext: (artifactId: number) => Effect.Effect<Option.Option<CitedArtifactRow>, DataStoreError>;
+  readonly getCommitChanges: (sha?: string) => Effect.Effect<ReadonlyArray<CommitChangesEntry>, DataStoreError>;
+  readonly listTddTasksForSession: (sessionId: number, options?: {
+    /**
+     * When true, also return tdd_tasks belonging to any
+     * ancestor of `sessionId` via `parent_session_id`. Used
+     * by hook-driven artifact recording where the
+     * orchestrator opened the tdd task under the parent
+     * main row but the subagent's own session row is the
+     * one carrying the calling chat_id. Default `false`
+     * 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
+   * recorded_at DESC order so the most recently captured artifact
+   * (the typical citation target for a phase transition) appears
+   * first. `limit` defaults to 50.
+   */
+  readonly listTddArtifactsForTask: (input: {
+    readonly tddTaskId: number;
+    readonly artifactKind?: ArtifactKind$1;
+    readonly phaseId?: number;
+    readonly behaviorId?: number;
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<TddArtifactRow>, DataStoreError>;
+  readonly listHypotheses: (options: {
+    readonly sessionId?: number;
+    readonly outcome?: "confirmed" | "refuted" | "abandoned" | "open";
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<HypothesisDetail>, DataStoreError>;
+  readonly findIdempotentResponse: (procedurePath: string, key: string) => Effect.Effect<Option.Option<string>, DataStoreError>;
+  readonly getLatestTestCaseForSession: (chatId: string) => Effect.Effect<Option.Option<number>, DataStoreError>;
+  /**
+   * Returns one `TagInventoryRow` per `(tag, project)` pair observed in
+   * each project's latest test run. When `project` is supplied, results
+   * are restricted to that project's latest run.
+   */
+  readonly listTagInventory: (options?: {
+    readonly project?: string;
+  }) => Effect.Effect<ReadonlyArray<TagInventoryRow>, DataStoreError>;
+  /**
+   * Returns every `TestListEntry` from the latest run of each project
+   * (or the specified project) whose test case carries `tag`.
+   */
+  readonly listTestsForTag: (tag: string, options?: {
+    readonly project?: string;
+  }) => Effect.Effect<ReadonlyArray<TestListEntry>, DataStoreError>;
+}>;
+/** @public */
+export declare class DataReader extends DataReader_base {}
+//#endregion
+//#region src/layers/DataReaderLive.d.ts
+/** @public */
+export declare const DataReaderLive: Layer.Layer<DataReader, never, SqlClient>;
+//#endregion
+//#region src/layers/DataStoreLive.d.ts
+/** @public */
+export declare const DataStoreLive: Layer.Layer<DataStore, never, SqlClient>;
+//#endregion
+//#region src/services/DetailResolver.d.ts
+/** @public */
+export interface RunHealth {
+  readonly hasFailures: boolean;
+  readonly belowTargets: boolean;
+  readonly hasTargets?: boolean;
+}
+declare const DetailResolver_base: Context.ServiceClass<DetailResolver, "vitest-agent/DetailResolver", {
+  readonly resolve: (executor: Executor, health: RunHealth, explicit?: DetailLevel) => Effect.Effect<DetailLevel>;
+}>;
+/** @public */
+export declare class DetailResolver extends DetailResolver_base {}
+//#endregion
+//#region src/layers/DetailResolverLive.d.ts
+/** @public */
+export declare const DetailResolverLive: Layer.Layer<DetailResolver, never, never>;
+//#endregion
+//#region src/services/DiscoveryRegistry.d.ts
+/**
+ * Input for upserting a known project into the global discovery registry.
+ *
+ * @public
+ */
+export interface KnownProjectInput {
+  readonly projectKey: string;
+  readonly canonicalForm: string;
+  readonly dataDbPath: string;
+  readonly gitRemoteOrigin: string | null;
+  readonly workspaceRoot: string;
+}
+/**
+ * A project record as stored in the global discovery registry.
+ *
+ * @public
+ */
+export interface KnownProject {
+  readonly projectKey: string;
+  readonly canonicalForm: string;
+  readonly dataDbPath: string;
+  readonly gitRemoteOrigin: string | null;
+  readonly workspaceRoot: string;
+  readonly firstSeenAt: number;
+  readonly lastSeenAt: number;
+}
+declare const DiscoveryRegistry_base: Context.ServiceClass<DiscoveryRegistry, "vitest-agent/DiscoveryRegistry", {
+  /**
+   * Upsert this project into the registry. Sets `first_seen_at` on
+   * insert; updates `last_seen_at` plus all mutable fields on
+   * conflict. Returns nothing — the call is fire-and-observe.
+   */
+  readonly recordProject: (input: KnownProjectInput) => Effect.Effect<void, DataStoreError>;
+  /**
+   * List all projects ordered by most recent activity first. Used by
+   * cross-project discovery tooling.
+   */
+  readonly listProjects: () => Effect.Effect<ReadonlyArray<KnownProject>, DataStoreError>;
+  /**
+   * Drop registry rows whose `last_seen_at` is older than `maxAgeDays`
+   * days ago. The corresponding `data.db` files are NOT deleted; only
+   * the index entry is pruned. Returns the count of removed rows.
+   */
+  readonly prune: (maxAgeDays: number) => Effect.Effect<number, DataStoreError>;
+}>;
+/** @public */
+export declare class DiscoveryRegistry extends DiscoveryRegistry_base {}
+//#endregion
+//#region src/layers/DiscoveryRegistryLive.d.ts
+/** @public */
+export declare const DiscoveryRegistryLive: Layer.Layer<DiscoveryRegistry, never, SqlClient>;
+//#endregion
+//#region src/services/EnvironmentDetector.d.ts
+declare const EnvironmentDetector_base: Context.ServiceClass<EnvironmentDetector, "vitest-agent/EnvironmentDetector", {
+  readonly detect: () => Effect.Effect<Environment>;
+  readonly isAgent: Effect.Effect<boolean>;
+  readonly agentName: Effect.Effect<string | undefined>;
+}>;
+/** @public */
+export declare class EnvironmentDetector extends EnvironmentDetector_base {}
+//#endregion
+//#region src/layers/EnvironmentDetectorLive.d.ts
+/**
+ * Pure classification behind {@link EnvironmentDetectorLive}: an agent shell
+ * wins, then GitHub Actions, then generic CI, else a terminal.
+ *
+ * @param env - the environment map to consult
+ * @param agentShell - whether the process runs under an AI agent (`std-env`'s `isAgent`)
+ * @public
+ */
+export declare const classifyEnvironment: (env: Record<string, string | undefined>, agentShell: boolean) => Environment;
+/**
+ * Live environment detector. CI detection reads `GITHUB_ACTIONS` / `CI`
+ * from the injected `env` map; agent detection comes from `std-env`.
+ *
+ * @param env - the environment map to consult (the front end passes `process.env`)
+ * @public
+ */
+export declare const EnvironmentDetectorLive: (env: Record<string, string | undefined>) => Layer.Layer<EnvironmentDetector>;
+//#endregion
+//#region src/layers/EnvironmentDetectorTest.d.ts
+/** @public */
+export declare const EnvironmentDetectorTest: {
+  layer: (env?: Environment) => Layer.Layer<EnvironmentDetector, never, never>;
+};
+//#endregion
+//#region src/services/ExecutorResolver.d.ts
+declare const ExecutorResolver_base: Context.ServiceClass<ExecutorResolver, "vitest-agent/ExecutorResolver", {
+  readonly resolve: (env: Environment) => Effect.Effect<Executor>;
+}>;
+/** @public */
+export declare class ExecutorResolver extends ExecutorResolver_base {}
+//#endregion
+//#region src/layers/ExecutorResolverLive.d.ts
+/** @public */
+export declare const ExecutorResolverLive: Layer.Layer<ExecutorResolver, never, never>;
+//#endregion
+//#region src/services/FormatSelector.d.ts
+declare const FormatSelector_base: Context.ServiceClass<FormatSelector, "vitest-agent/FormatSelector", {
+  readonly select: (executor: Executor, explicitFormat?: OutputFormat, environment?: Environment) => Effect.Effect<OutputFormat>;
+}>;
+/** @public */
+export declare class FormatSelector extends FormatSelector_base {}
+//#endregion
+//#region src/layers/FormatSelectorLive.d.ts
+/**
+ * Default format dispatch:
+ *
+ * - GitHub Actions CI executor: `ci-annotations` (renders as `::error::`).
+ * - Human executor: `silent` (Vitest's own reporters handle the user
+ *   experience; we just write to the database).
+ * - Anyone else (agent-shell, terminal-bound CI): `terminal` — plain
+ *   text + ANSI color, no markdown syntax in the place that doesn't
+ *   render it. Markdown stays available via explicit `format: "markdown"`
+ *   for surfaces that *do* render it (MCP tools, GitHub step summary).
+ * @public
+ */
+export declare const FormatSelectorLive: Layer.Layer<FormatSelector, never, never>;
+//#endregion
+//#region src/services/HistoryTracker.d.ts
+/**
+ * Lightweight test outcome for history classification.
+ * @public
+ */
+export interface TestOutcome {
+  readonly modulePath: string;
+  readonly fullName: string;
+  readonly state: "passed" | "failed";
+}
+/**
+ * Builds the composite (modulePath, fullName) key used to key the internal
+ * testMap and the returned classifications Map, so identically-named tests
+ * in different files classify independently instead of colliding.
+ *
+ * Uses `JSON.stringify` for an injective encoding: a plain delimiter such as
+ * a space is not collision-proof (e.g. `("a b", "c")` and `("a", "b c")` would
+ * both yield `"a b c"`), which would reintroduce the very collision class this
+ * key exists to prevent.
+ * @public
+ */
+export declare const historyKey: (modulePath: string, fullName: string) => string;
+declare const HistoryTracker_base: Context.ServiceClass<HistoryTracker, "vitest-agent/HistoryTracker", {
+  readonly classify: (project: string, testOutcomes: ReadonlyArray<TestOutcome>, timestamp: string) => Effect.Effect<{
+    history: HistoryRecord;
+    classifications: Map<string, TestClassification>;
+  }, DataStoreError>;
+}>;
+/** @public */
+export declare class HistoryTracker extends HistoryTracker_base {}
+//#endregion
+//#region src/layers/HistoryTrackerLive.d.ts
+/** @public */
+export declare const HistoryTrackerLive: Layer.Layer<HistoryTracker, never, DataReader>;
+//#endregion
+//#region src/layers/HistoryTrackerTest.d.ts
+/** @public */
+export interface HistoryTrackerTestState {
+  readonly classifyCalls: Array<{
+    project: string;
+    timestamp: string;
+  }>;
+}
+/** @public */
+export declare const HistoryTrackerTest: {
+  readonly empty: () => HistoryTrackerTestState;
+  readonly layer: (state: HistoryTrackerTestState, cannedResult?: {
+    history: HistoryRecord;
+    classifications: Map<string, TestClassification>;
+  }) => Layer.Layer<HistoryTracker>;
+};
+//#endregion
+//#region src/layers/LoggerLive.d.ts
+/**
+ * Create a structured JSON (NDJSON) logger layer for stderr.
+ *
+ * When level is undefined or `"None"`, installs an empty logger set (silent).
+ * When logFile is set, composes the stderr logger with a file logger.
+ * Uses `Logger.formatJson` / `Logger.formatStructured` for machine-readable
+ * output.
+ * @public
+ */
+export declare const LoggerLive: (level?: LogLevel.LogLevel, logFile?: string) => Layer.Layer<never>;
+/**
+ * Resolve log level from option or environment variable.
+ * Priority: explicit option \> `VITEST_REPORTER_LOG_LEVEL` in `env` \> undefined.
+ *
+ * @param env - the environment map to consult (the front end passes `process.env`)
+ * @param option - explicit override
+ * @public
+ */
+export declare function resolveLogLevel(env: Record<string, string | undefined>, option?: string): LogLevel.LogLevel | undefined;
+/**
+ * Resolve log file from option or environment variable
+ * (`VITEST_REPORTER_LOG_FILE` in `env`).
+ *
+ * @param env - the environment map to consult (the front end passes `process.env`)
+ * @param option - explicit override
+ * @public
+ */
+export declare function resolveLogFile(env: Record<string, string | undefined>, option?: string): string | undefined;
+//#endregion
+//#region src/layers/OutputPipelineLive.d.ts
+/**
+ * The output pipeline: environment detection, executor resolution, format
+ * selection, detail resolution and rendering.
+ *
+ * @param env - the environment map `EnvironmentDetectorLive` consults
+ *   (the front end passes `process.env`)
+ * @public
+ */
+export declare const OutputPipelineLive: (env: Record<string, string | undefined>) => Layer.Layer<DetailResolver | EnvironmentDetector | ExecutorResolver | FormatSelector | OutputRenderer, never, never>;
+//#endregion
+//#region src/services/OutputRenderer.d.ts
+declare const OutputRenderer_base: Context.ServiceClass<OutputRenderer, "vitest-agent/OutputRenderer", {
+  readonly render: (reports: ReadonlyArray<AgentReport>, format: OutputFormat, context: FormatterContext) => Effect.Effect<ReadonlyArray<RenderedOutput>>;
+}>;
+/** @public */
+export declare class OutputRenderer extends OutputRenderer_base {}
+//#endregion
+//#region src/layers/OutputRendererLive.d.ts
+/** @public */
+export declare const OutputRendererLive: Layer.Layer<OutputRenderer, never, never>;
+//#endregion
+//#region src/layers/PathResolutionLive.d.ts
+/**
+ * The XDG namespace every vitest-agent data directory lives under —
+ * `<XDG data>/vitest-agent`. The one place the name exists.
+ * @public
+ */
+export declare const APP_NAMESPACE = "vitest-agent";
+/**
+ * Composite layer providing every service `resolveDataPath` requires:
+ * `AppDirs` (XDG path resolution), `VitestAgentConfigFile` (TOML
+ * config loader), and `WorkspaceDiscovery` / `WorkspaceRoot` (workspace name
+ * lookup).
+ *
+ * Callers still need to provide `FileSystem` and `Path` from
+ * `@effect/platform-node`'s `NodeServices.layer` (or the equivalent on Bun).
+ *
+ * `WorkspaceDiscovery` is pinned to `projectDir` as its `cwd`, which sets the
+ * root for the layer-bound methods (`listPackages`, `info`, `refresh`). The
+ * per-root methods (`listPackagesIn`, `infoIn`, `refreshIn`) take a directory
+ * per call and ignore that pin — `resolveWorkspaceKey` and
+ * `ProjectIdentityLive` use them, so a long-lived host built against one root
+ * still answers correctly for a git worktree or an unrelated project.
+ *
+ * @param projectDir - Absolute path inside the user's workspace, used to
+ *   anchor the config file resolvers and workspace discovery.
+ * @public
+ */
+export declare const PathResolutionLive: (projectDir: string) => Layer.Layer<AppDirs | VitestAgentConfigFile | WorkspaceDiscovery, import("@effected/xdg").XdgEnvError, import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
+//#endregion
+//#region src/services/PerClientSessionMap.d.ts
+/** @public */
+export interface MapSessionInput {
+  readonly hostSessionId: string;
+  readonly conversationId: string;
+  readonly projectKey: string;
+  readonly projectDir: string;
+}
+/** @public */
+export interface MapSessionOutput {
+  readonly mainAgentId: string;
+  readonly conversationId: string;
+}
+/** @public */
+export interface SessionContextRow {
+  readonly hostSessionId: string;
+  readonly conversationId: string;
+  readonly projectKey: string;
+  readonly projectDir: string;
+  readonly mainAgentId: string;
+  readonly startedAt: number;
+  readonly endedAt: number | null;
+}
+declare const PerClientSessionMapReader_base: Context.ServiceClass<PerClientSessionMapReader, "vitest-agent/PerClientSessionMapReader", {
+  /**
+   * Look up an existing conversation_id for a given transcript
+   * path. Returns `Option.none()` when the transcript hasn't been
+   * seen before. Read-only — does not insert.
+   */
+  readonly lookupConversation: (transcriptPath: string) => Effect.Effect<Option.Option<string>, DataStoreError>;
+  /**
+   * Return the most recent open session for a project_dir
+   * (`ended_at IS NULL`). The MCP server uses this to recover
+   * `currentSessionContext` after `/reload-plugins`. The compound
+   * index `idx_session_map_active` covers the predicate.
+   */
+  readonly lookupByProjectDir: (projectDir: string) => Effect.Effect<Option.Option<SessionContextRow>, DataStoreError>;
+}>;
+/**
+ * Read-only side of the session map.
+ *
+ * Provided by `PerClientSessionMapReaderLive` (opens SQLite with
+ * `?mode=ro`). MCP server depends on this tag — calls to write
+ * methods would be a type error.
+ * @public
+ */
+export declare class PerClientSessionMapReader extends PerClientSessionMapReader_base {}
+declare const PerClientSessionMapWriter_base: Context.ServiceClass<PerClientSessionMapWriter, "vitest-agent/PerClientSessionMapWriter", {
+  /**
+   * Upsert a conversation row. Returns the canonical conversation_id
+   * for the given transcript_path (existing if seen before, freshly
+   * generated otherwise).
+   */
+  readonly mapConversation: (transcriptPath: string) => Effect.Effect<string, DataStoreError>;
+  /**
+   * Upsert a session row. Returns the canonical main_agent_id and
+   * conversation_id (existing if `host_session_id` was seen before,
+   * freshly generated otherwise).
+   *
+   * The caller is responsible for having already mapped the
+   * conversation; this method only records the
+   * (host_session_id, conversation_id, project) tuple.
+   */
+  readonly mapSession: (input: MapSessionInput) => Effect.Effect<MapSessionOutput, DataStoreError>;
+  /**
+   * Mark a session as ended. Sets `ended_at` to the supplied
+   * timestamp. No-op if the session is unknown — endSession is
+   * best-effort cleanup.
+   */
+  readonly endSession: (hostSessionId: string, endedAt: number) => Effect.Effect<void, DataStoreError>;
+  /**
+   * Read methods so the Writer also satisfies the Reader tag's
+   * surface.
+   */
+  readonly lookupConversation: (transcriptPath: string) => Effect.Effect<Option.Option<string>, DataStoreError>;
+  readonly lookupByProjectDir: (projectDir: string) => Effect.Effect<Option.Option<SessionContextRow>, DataStoreError>;
+}>;
+/**
+ * Read-write side of the session map. Sidecar provides this; the
+ * Writer layer also satisfies the Reader tag so consumers of either
+ * one resolve.
+ * @public
+ */
+export declare class PerClientSessionMapWriter extends PerClientSessionMapWriter_base {}
+//#endregion
+//#region src/layers/PerClientSessionMapLive.d.ts
+/**
+ * Read-only layer. The entry point provides an `SqlClient` configured
+ * with the `?mode=ro` URI parameter; this layer wraps the read
+ * methods and never declares write methods.
+ * @public
+ */
+export declare const PerClientSessionMapReaderLive: Layer.Layer<PerClientSessionMapReader, never, SqlClient>;
+/**
+ * Read-write layer. Provides both write methods and the Reader's read
+ * methods so the same layer instance satisfies callers of either
+ * tag.
+ * @public
+ */
+export declare const PerClientSessionMapWriterLive: Layer.Layer<PerClientSessionMapWriter | PerClientSessionMapReader, never, SqlClient>;
+//#endregion
+//#region src/services/ProjectDiscovery.d.ts
+/** @public */
+export interface TestFileEntry {
+  readonly testFile: string;
+  readonly sourceFiles: ReadonlyArray<string>;
+}
+declare const ProjectDiscovery_base: Context.ServiceClass<ProjectDiscovery, "vitest-agent/ProjectDiscovery", {
+  readonly discoverTestFiles: (rootDir: string) => Effect.Effect<ReadonlyArray<TestFileEntry>, DiscoveryError>;
+  readonly mapTestToSource: (testFile: string) => Effect.Effect<ReadonlyArray<string>, DiscoveryError>;
+}>;
+/** @public */
+export declare class ProjectDiscovery extends ProjectDiscovery_base {}
+//#endregion
+//#region src/layers/ProjectDiscoveryLive.d.ts
+/** @public */
+export declare const ProjectDiscoveryLive: Layer.Layer<ProjectDiscovery, never, FileSystem.FileSystem>;
+//#endregion
+//#region src/layers/ProjectDiscoveryTest.d.ts
+/** @public */
+export declare const ProjectDiscoveryTest: {
+  readonly layer: (entries: ReadonlyArray<TestFileEntry>) => Layer.Layer<ProjectDiscovery>;
+};
+//#endregion
+//#region src/services/ProjectIdentity.d.ts
+/**
+ * Result of a successful identity resolution.
+ *
+ * - `projectKey` — filesystem-safe single segment for the per-project
+ *   data store directory under `$XDG_DATA_HOME/vitest-agent/`.
+ * - `canonicalForm` — human-readable form for display in the discovery
+ *   registry. Equal to `projectKey` for non-git sources; for git
+ *   sources, the original `host/path` shape (with slashes preserved).
+ * - `source` — which source matched. Useful for diagnostics and the
+ *   `vitest-agent doctor`-style commands.
+ * @public
+ */
+export interface ResolvedIdentity {
+  readonly projectKey: string;
+  readonly canonicalForm: string;
+  readonly source: ProjectIdentitySource;
+}
+/** @public */
+export type ProjectIdentitySource = "explicit" | "toml" | "git-remote" | "package-repository" | "package-name";
+/**
+ * Per-source candidate values. Each is optional — an absent or empty
+ * value causes the resolver to fall through to the next source.
+ *
+ * The Live layer collects these from real I/O (config file, git
+ * subprocess, `package.json` read). Tests pass a literal object.
+ * @public
+ */
+export interface ProjectIdentityCandidates {
+  readonly explicit?: string;
+  readonly toml?: string;
+  readonly gitRemote?: string;
+  readonly packageJsonRepoUrl?: string;
+  readonly packageJsonName?: string;
+}
+/**
+ * Options accepted by the `ProjectIdentity.resolve` service method.
+ *
+ * `projectId` is the priority-1 escape hatch — pass when the user has
+ * configured `AgentPlugin({ projectId: "..." })` in `vitest.config.ts`.
+ * @public
+ */
+export interface ResolveProjectIdentityOptions {
+  readonly projectId?: string;
+}
+/**
+ * Pure priority resolver. Returns `null` when no candidate produces a
+ * usable value — the caller wraps `null` into a tagged error.
+ *
+ * For non-git sources the `canonicalForm` equals the original
+ * (un-normalized) input so the discovery registry can display
+ * `@spencerbeggs/vitest-agent` rather than the underscored form. For
+ * git sources, `canonicalForm` is the slash-preserving `host/path`
+ * shape from `canonicalizeGitUrl`.
+ * @public
+ */
+export declare const resolveProjectIdentityFromCandidates: (candidates: ProjectIdentityCandidates) => ResolvedIdentity | null;
+declare const ProjectIdentity_base: Context.ServiceClass<ProjectIdentity, "vitest-agent/ProjectIdentity", {
+  readonly resolve: (workspaceRoot: string, options?: ResolveProjectIdentityOptions) => Effect.Effect<ResolvedIdentity, ProjectIdentityNotResolvableError>;
+}>;
+/**
+ * Service tag. The Live layer (in `layers/ProjectIdentityLive.ts`)
+ * wires up the I/O sources; tests provide a stub that returns a
+ * pre-built `ResolvedIdentity`.
+ * @public
+ */
+export declare class ProjectIdentity extends ProjectIdentity_base {}
+//#endregion
+//#region src/layers/ProjectIdentityLive.d.ts
+/**
+ * Effect environment type required by `collectCandidates` and the
+ * `ProjectIdentityLive` layer. Exported only so the layer's
+ * `Layer.Layer<ProjectIdentity, never, CandidateContext>` signature
+ * has a named referent — consumers should provide the four named
+ * services (FileSystem, WorkspaceDiscovery, VitestAgentConfigFile,
+ * CommandExecutor) rather than reference this type directly.
+ *
+ * @public
+ */
+export type CandidateContext = FileSystem.FileSystem | WorkspaceDiscovery | VitestAgentConfigFile | ChildProcessSpawner.ChildProcessSpawner;
+/**
+ * Live layer that wires the resolver into real I/O. Requires
+ * `FileSystem`, `CommandExecutor`, `WorkspaceDiscovery`, and
+ * `VitestAgentConfigFile`. The platform context comes from
+ * `NodeServices.layer` at the entry point.
+ * @public
+ */
+export declare const ProjectIdentityLive: Layer.Layer<ProjectIdentity, never, CandidateContext>;
+/**
+ * Build a Test layer that returns a fixed `ResolvedIdentity` (or
+ * fails with `ProjectIdentityNotResolvableError`). Use in unit tests
+ * that depend on `ProjectIdentity` but don't want to wire upstream
+ * services.
+ * @public
+ */
+export declare const ProjectIdentityTest: (result: ResolvedIdentity | ProjectIdentityNotResolvableError) => Layer.Layer<ProjectIdentity, never, never>;
+//#endregion
+//#region src/services/RunContext.d.ts
+declare const RunContext_base: Schema.Class<RunContext, Schema.Struct<{
+  readonly gitBranch: Schema.NullOr<Schema.String>;
+  readonly gitCommitSha: Schema.NullOr<Schema.String>;
+  readonly gitDirty: Schema.NullOr<Schema.Boolean>;
+  readonly gitUpstream: Schema.NullOr<Schema.String>;
+  readonly gitWorktreeDir: Schema.NullOr<Schema.String>;
+  readonly hostSource: Schema.NullOr<Schema.String>;
+  readonly hostValue: Schema.NullOr<Schema.String>;
+  readonly hostMetadata: Schema.NullOr<Schema.Unknown>;
+}>, {}>;
+/**
+ * Per-run snapshot of the workspace's git state and host context.
+ * Every field is nullable: a non-git workspace has all-NULL git
+ * fields, a CI run with no terminal probe match has all-NULL host
+ * fields, and a worker that can't read upstream info has a NULL
+ * `gitUpstream` while everything else is set.
+ *
+ * Declared as a `Schema.Class` so callers can `new RunContext({...})`
+ * and `Schema.encode(...)` for the SQLite row mapping.
+ * @public
+ */
+export declare class RunContext extends RunContext_base {}
+declare const AgentContext_base: Schema.Class<AgentContext, Schema.Struct<{
+  readonly startGitBranch: Schema.NullOr<Schema.String>;
+  readonly startGitCommitSha: Schema.NullOr<Schema.String>;
+  readonly startWorktreeDir: Schema.NullOr<Schema.String>;
+}>, {}>;
+/**
+ * Subset of {@link RunContext} captured at agent registration. Only
+ * the inheritable git context — branch, sha, worktree path. Mid-run
+ * dirty-tree state and upstream tracking are per-run concerns.
+ * @public
+ */
+export declare class AgentContext extends AgentContext_base {}
+declare const RunContext$_base: Context.ServiceClass<RunContext$, "vitest-agent/RunContextService", {
+  readonly captureRunContext: (cwd: string) => Effect.Effect<RunContext>;
+  readonly captureAgentContext: (cwd: string) => Effect.Effect<AgentContext>;
+}>;
+/**
+ * Service tag. The Live layer captures real I/O; the Test layer
+ * returns whatever the test fixture passes.
+ * @public
+ */
+export declare class RunContext$ extends RunContext$_base {}
+/**
+ * Re-export the service tag under a less-collision-prone name. The
+ * `RunContext` Schema.Class above shares its symbol-name with the
+ * service tag concept; the `$` suffix on the Context.Tag class name
+ * keeps both addressable from the same module.
+ *
+ * @public
+ */
+export declare const RunContextService: typeof RunContext$;
+/** @public */
+export type RunContextService = RunContext$;
+//#endregion
+//#region src/layers/RunContextLive.d.ts
+/**
+ * Live layer. Requires `ChildProcessSpawner` (provided by
+ * `NodeServices.layer` at the entry point). Host-metadata probes read
+ * the injected `env` map — the env walk is pure and the map is captured
+ * once when the layer is built.
+ *
+ * @param env - the environment map to probe (the front end passes `process.env`)
+ * @public
+ */
+export declare const RunContextLive: (env: Record<string, string | undefined>) => Layer.Layer<RunContextService, never, ChildProcessSpawner.ChildProcessSpawner>;
+/**
+ * Build a Test layer that returns fixed `RunContext` and
+ * `AgentContext` values regardless of `cwd`.
+ * @public
+ */
+export declare const RunContextTest: (fixture: {
+  readonly runContext: RunContext;
+  readonly agentContext: AgentContext;
+}) => Layer.Layer<RunContextService, never, never>;
+//#endregion
+//#region src/lib/format-triage.d.ts
+/** @public */
+interface FormatTriageOptions {
+  readonly project?: string;
+  readonly maxLines?: number;
+}
+/**
+ * Generates an orientation triage markdown string for LLM agents.
+ * Summarises recent test runs, active sessions, acceptance metrics,
+ * and (forward-compat) the most recent TDD session.
+ *
+ * Error channel is `never` — all DataReader errors are swallowed and
+ * replaced with empty defaults so the caller is guaranteed a string.
+ * @public
+ */
+export declare const formatTriageEffect: (options?: FormatTriageOptions) => Effect.Effect<string, never, DataReader>;
+//#endregion
+//#region src/lib/format-wrapup.d.ts
+/** @public */
+type WrapupKind = "stop" | "session_end" | "pre_compact" | "tdd_handoff" | "user_prompt_nudge";
+/** @public */
+interface FormatWrapupOptions {
+  readonly sessionId?: number;
+  readonly chatId?: string;
+  readonly kind: WrapupKind;
+  readonly userPromptHint?: string;
+}
+/** @public */
+export declare const formatWrapupEffect: (options: FormatWrapupOptions) => Effect.Effect<string, never, DataReader>;
+//#endregion
+//#region src/migrations/0001_initial.d.ts
+/** @internal */
+declare const migration: Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient>;
+//#endregion
+//#region src/migrations/0002_test_artifacts.d.ts
+/** @internal */
+declare const migration$1: Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient>;
+//#endregion
+//#region src/migrations/index.d.ts
+/**
+ * Every migration that must run against a per-project `data.db`, keyed by
+ * migration id in application order.
+ *
+ * This is the single source of truth for the project database's migration
+ * set: `makeSqliteStack` (and through it `PlatformLive`, `ensureMigrated`,
+ * the testing layers, `ReporterLive` and `SidecarLive`) defaults to it when
+ * calling `SqliteMigrator.fromRecord`, so adding a migration file and
+ * registering it here is enough to reach every process that opens a project
+ * database.
+ *
+ * The session-map and discovery-registry databases are separate schemas with
+ * their own migrations and are deliberately not listed here.
+ *
+ * @public
+ */
+export declare const PROJECT_MIGRATIONS: {
+  readonly "0001_initial": import("effect/Effect").Effect<void, import("effect/unstable/sql/SqlError").SqlError, import("effect/unstable/sql/SqlClient").SqlClient>;
+  readonly "0002_test_artifacts": import("effect/Effect").Effect<void, import("effect/unstable/sql/SqlError").SqlError, import("effect/unstable/sql/SqlClient").SqlClient>;
+};
+//#endregion
+//#region src/migrations/registry_0001_initial.d.ts
+/**
+ * Migration for the global discovery registry SQLite at
+ * `$XDG_DATA_HOME/vitest-agent/registry.db`.
+ *
+ * Single table `known_projects` indexed by `project_key` (the
+ * filesystem-safe form from {@link ProjectIdentity}). Tooling like
+ * `mcp-app` queries this table to enumerate every vitest-agent
+ * project the user has ever run on this machine.
+ *
+ * The registry never blocks anything — its writes are best-effort.
+ * Concurrent writers from multiple Claude Code windows converge via
+ * the `ON CONFLICT(project_key) DO UPDATE` upsert.
+ * @public
+ */
+declare const migration$2: Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient>;
+//#endregion
+//#region src/migrations/session_map_0001_initial.d.ts
+/** @internal */
+declare const migration$3: Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient>;
+//#endregion
+//#region src/platform.d.ts
+/**
+ * A migration set in the shape `SqliteMigrator.fromRecord` accepts: migration
+ * id → loader.
+ * @public
+ */
+export type MigrationRecord = Record<string, Effect.Effect<void, unknown, SqlClient>>;
+/**
+ * A SQLite connection plus the migrator that brings it to the head of a
+ * migration set. Returned by {@link makeSqliteStack}.
+ * @public
+ */
+export interface SqliteStack {
+  /** The `SqlClient` layer for `filename`. */
+  readonly SqliteLayer: Layer.Layer<SqliteClient | SqlClient>;
+  /**
+   * `Layer.effectDiscard`-shaped: provides nothing, runs the migrations as a
+   * side effect of layer acquisition. Already fed its `SqlClient` and the
+   * Node platform services.
+   */
+  readonly MigratorLayer: Layer.Layer<never, MigrationError | SqlError>;
+}
+/**
+ * The Node platform services every SQLite stack and every Live layer share.
+ * `NodeServices.layer` aggregates FileSystem | Path | ChildProcessSpawner |
+ * Crypto | Stdio | Terminal.
+ * @public
+ */
+export declare const NodePlatformLayer: Layer.Layer<NodeServices.NodeServices, never, never>;
+/**
+ * Build one SQLite database stack: the client layer for `filename` and a
+ * migrator over `migrations` that is already provided with that client and
+ * the Node platform services. The single assembly the CLI, MCP server,
+ * plugin, `ensureMigrated` and the testing layers all share.
+ *
+ * @param filename - SQLite file path, or `":memory:"`
+ * @param migrations - the migration record to run; defaults to the project
+ *   `data.db` set (`PROJECT_MIGRATIONS`)
+ * @public
+ */
+export declare const makeSqliteStack: (filename: string, migrations?: MigrationRecord) => SqliteStack;
+/**
+ * Options for {@link PlatformLive}.
+ * @public
+ */
+export interface PlatformOptions {
+  /** Absolute path to the per-project `data.db`, or `":memory:"`. */
+  readonly dbPath: string;
+  /** The environment map the env-reading layers consult (the front end passes `process.env`). */
+  readonly env: Record<string, string | undefined>;
+  /** Optional log level override; when absent the logger is silent. */
+  readonly logLevel?: LogLevel.LogLevel | undefined;
+  /** Optional path for structured NDJSON log output. */
+  readonly logFile?: string | undefined;
+}
+/**
+ * The services {@link PlatformLive} provides.
+ * @public
+ */
+export type PlatformServices = DataReader | DataStore | ProjectDiscovery | HistoryTracker | EnvironmentDetector | ExecutorResolver | FormatSelector | DetailResolver | OutputRenderer | NodeServices.NodeServices | SqliteClient | SqlClient;
+/**
+ * The one platform assembly shared by the CLI, the MCP server and the Vitest
+ * plugin: SQLite + migrator + Node platform services + Logger, with
+ * `DataReader`, `DataStore`, `ProjectDiscovery`, `HistoryTracker` and the
+ * output pipeline (`EnvironmentDetector`, `ExecutorResolver`,
+ * `FormatSelector`, `DetailResolver`, `OutputRenderer`) built over them.
+ *
+ * Every env read goes through `options.env`; the engine never touches
+ * `process` itself.
+ *
+ * @param options - database path, env map and optional logging overrides
+ * @public
+ */
+export declare const PlatformLive: (options: PlatformOptions) => Layer.Layer<PlatformServices, MigrationError | SqlError>;
+//#endregion
+//#region src/programs/end-agent.d.ts
+/**
+ * Input for {@link endAgentEffect}: which `agents` row to close and when.
+ *
+ * @public
+ */
+export interface EndAgentInput {
+  /** The `agents.id` row to close. */
+  readonly agentId: string;
+  /** Epoch-millisecond timestamp written to `agents.ended_at`. */
+  readonly endedAt: number;
+  /**
+   * When set, also marks the session map row for this host_session_id
+   * as ended. Used by SessionEnd; omitted by SubagentStop.
+   */
+  readonly hostSessionId?: string;
+}
+/**
+ * End an agent. Closes the `agents` row, optionally also closes the
+ * `session_map` row.
+ *
+ * @param input - the agent id, end timestamp, and optional host session id
+ * @public
+ */
+export declare const endAgentEffect: (input: EndAgentInput) => Effect.Effect<void, import("@vitest-agent/sdk").AgentNotFoundError | import("@vitest-agent/sdk").DataStoreError, DataStore | PerClientSessionMapWriter>;
+//#endregion
+//#region src/programs/hook-paths.d.ts
+/**
+ * Filename of the per-project test-data SQLite database.
+ *
+ * @public
+ */
+export declare const DATA_DB_FILENAME = "data.db";
+/**
+ * Filename of the per-client session-map SQLite database.
+ *
+ * @public
+ */
+export declare const SESSIONS_DB_FILENAME = "sessions.db";
+/**
+ * Filename of the global discovery-registry SQLite database.
+ *
+ * @public
+ */
+export declare const REGISTRY_DB_FILENAME = "registry.db";
+/**
+ * The environment map every hook-path resolver reads from. The front end
+ * passes `process.env`; the engine never reads `process` itself.
+ *
+ * @public
+ */
+export type HookEnv = Record<string, string | undefined>;
+/**
+ * The paths the sidecar-family subcommands open. Every directory has been
+ * created by the time this value is returned.
+ *
+ * @public
+ */
+export interface HookPaths {
+  /** `<XDG data>/vitest-agent` — holds `registry.db` and the per-project dirs. */
+  readonly dataRoot: string;
+  /** `<dataRoot>/<projectKey>` — holds the per-project `data.db`. */
+  readonly projectDataDir: string;
+  /** Absolute path to the per-project `data.db`. */
+  readonly perProjectDbPath: string;
+  /** Absolute path to the global `registry.db`. */
+  readonly registryDbPath: string;
+  /** Absolute path to the per-client `sessions.db`. */
+  readonly sessionMapDbPath: string;
+}
+/**
+ * Failures {@link resolveHookPaths} can surface: an unset `HOME` /
+ * `USERPROFILE` (`XdgEnvError` for the data root,
+ * `ProjectIdentityNotResolvableError` for the session map), a directory
+ * that could not be created (`AppDirsError` / `PlatformError`).
+ *
+ * @public
+ */
+export type HookPathsError = XdgEnvError | AppDirsError | PlatformError | ProjectIdentityNotResolvableError;
+/**
+ * Resolve the per-client `sessions.db` path.
+ *
+ * Precedence: the `CLAUDE_PLUGIN_DATA` env var, then
+ * `VITEST_AGENT_SESSION_MAP_DIR`, then `~/.vitest-agent/` (`HOME`, then
+ * `USERPROFILE`). The chosen directory is created. Fails with
+ * `ProjectIdentityNotResolvableError` when no home directory is resolvable.
+ *
+ * @param env - the environment map to consult (the front end passes `process.env`)
+ * @returns an Effect resolving to the absolute `sessions.db` path
+ * @public
+ */
+export declare const resolveSessionMapPath: (env: HookEnv) => Effect.Effect<string, ProjectIdentityNotResolvableError | PlatformError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Resolve (and create) every path the sidecar-family subcommands open for
+ * `projectKey`: the per-project `data.db`, the global `registry.db` and the
+ * per-client `sessions.db`. See the module header for the precedence rules.
+ *
+ * @param input - the environment map (the front end passes `process.env`)
+ *   and the normalized project key (e.g. `@org__pkg`)
+ * @returns an Effect resolving to the created {@link HookPaths}
+ * @public
+ */
+export declare const resolveHookPaths: (input: {
+  readonly env: HookEnv;
+  readonly projectKey: string;
+}) => Effect.Effect<HookPaths, HookPathsError, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/programs/platform-sidecar.d.ts
+/**
+ * SQLite database paths consumed by {@link SidecarPlatformLive}.
+ * Structurally a subset of `HookPaths` from `resolveHookPaths`, so the
+ * resolver's result can be passed straight in.
+ *
+ * @public
+ */
+export interface SidecarPaths {
+  /** Absolute path to the per-project `data.db`. */
+  readonly perProjectDbPath: string;
+  /** Absolute path to the per-client `sessions.db`. */
+  readonly sessionMapDbPath: string;
+  /** Absolute path to the global `registry.db`. */
+  readonly registryDbPath: string;
+}
+/**
+ * Build the sidecar Live layer for the supplied SQLite paths.
+ *
+ * Each store gets its own `SqlClient` connection (separate scopes,
+ * independent migrators, all built through the engine's shared
+ * `makeSqliteStack`) so concurrent operations on the three stores
+ * don't share lock state.
+ *
+ * @param paths - the three SQLite database paths to open
+ * @param env - the environment map `RunContextLive` probes for host
+ *   metadata (the bin passes `process.env`)
+ * @public
+ */
+export declare const SidecarPlatformLive: (paths: SidecarPaths, env: Record<string, string | undefined>) => Layer.Layer<DataReader | DataStore | DiscoveryRegistry | PerClientSessionMapReader | PerClientSessionMapWriter | RunContext$ | import("@effect/platform-node/NodeServices").NodeServices, import("@effect/sql-sqlite-node/SqliteMigrator").MigrationError | import("effect/unstable/sql/SqlError").SqlError, never>;
+//#endregion
+//#region src/programs/record-session.d.ts
+/**
+ * Input for {@link recordSessionStart}: the identity of the session row to upsert.
+ *
+ * @public
+ */
+export interface RecordSessionStartInput {
+  /** Host chat id (Claude Code `session_id`) keying the `sessions` row. */
+  readonly chatId: string;
+  /** Project name the session runs under. */
+  readonly project: string;
+  /** Working directory of the session. */
+  readonly cwd: string;
+  /** Whether this is the main agent or a dispatched subagent. */
+  readonly agentKind: "main" | "subagent";
+  /** Subagent type name, when `agentKind` is `"subagent"`. */
+  readonly agentType?: string;
+  /** Chat id of the parent session, used to link subagent rows to their parent. */
+  readonly parentChatId?: string;
+  /** Whether the SessionStart triage brief had content. */
+  readonly triageWasNonEmpty: boolean;
+  /** ISO-8601 start timestamp. */
+  readonly startedAt: string;
+}
+/**
+ * Upsert a `sessions` row for a SessionStart / SubagentStart hook, resolving
+ * `parentChatId` to the parent's numeric session id when present.
+ *
+ * @param input - the session identity to record
+ * @returns the numeric `sessions.id`
+ * @public
+ */
+export declare const recordSessionStart: (input: RecordSessionStartInput) => Effect.Effect<{
+  sessionId: number;
+}, Error, DataReader | DataStore>;
+/**
+ * Input for {@link recordSessionEnd}: which session to close and why.
+ *
+ * @public
+ */
+export interface RecordSessionEndInput {
+  /** Host chat id of the session to close. */
+  readonly chatId: string;
+  /** ISO-8601 end timestamp. */
+  readonly endedAt: string;
+  /** Claude Code's SessionEnd reason, or `null` when unknown. */
+  readonly endReason: string | null;
+}
+/**
+ * Close a `sessions` row for a SessionEnd hook. Fails with an `Error`
+ * when no session exists for `chatId`.
+ *
+ * @param input - the session to close
+ * @public
+ */
+export declare const recordSessionEnd: (input: RecordSessionEndInput) => Effect.Effect<{
+  ok: true;
+}, Error, DataReader | DataStore>;
+//#endregion
+//#region src/programs/record-tdd-artifact.d.ts
+/**
+ * Input for {@link recordTddArtifactEffect}: an artifact keyed by the host
+ * chat id, resolved to the open TDD task under that session.
+ *
+ * @public
+ */
+export interface RecordTddArtifactInput {
+  /** Host chat id whose open TDD task receives the artifact. */
+  readonly chatId: string;
+  /** Kind of evidence being recorded. */
+  readonly artifactKind: ArtifactKind$1;
+  /** `files.id` the artifact refers to, when file-scoped. */
+  readonly fileId?: number;
+  /** `test_cases.id` the artifact refers to, when test-scoped. */
+  readonly testCaseId?: number;
+  /** `test_runs.id` that produced the evidence. */
+  readonly testRunId?: number;
+  /** Run id of the first observed failure for a red-phase artifact. */
+  readonly testFirstFailureRunId?: number;
+  /** Short diff excerpt attached to the artifact. */
+  readonly diffExcerpt?: string;
+  /** ISO-8601 timestamp of the artifact. */
+  readonly recordedAt: string;
+  /** Issue #363: explicit suite marker. Defaults to `"vitest"` when omitted. */
+  readonly suite?: ArtifactSuite$1;
+  /**
+   * Working directory of the calling process (ambient input — the CLI
+   * command passes its own `process.cwd()` when no `--cwd` flag was
+   * given). Used to bootstrap a missing session row when the chat id
+   * has no exact match.
+   */
+  readonly cwd: string;
+  /**
+   * Project name for bootstrapped session rows. When omitted, the
+   * resolver reads `package.json#name` from `cwd`.
+   */
+  readonly project?: string;
+}
+/**
+ * Result of a TDD artifact write: the new artifact row and the phase it landed under.
+ *
+ * @public
+ */
+export interface RecordTddArtifactResult {
+  /** The new `tdd_artifacts.id`. */
+  readonly id: number;
+  /** The `tdd_phases.id` the artifact was written under. */
+  readonly phaseId: number;
+}
+/**
+ * Record a TDD artifact under the open TDD task for `chatId`, walking
+ * parent and conversation links to find the task and auto-opening a
+ * `spike` phase when the task has none.
+ *
+ * @param input - the artifact to record, keyed by host chat id
+ * @public
+ */
+export declare const recordTddArtifactEffect: (input: RecordTddArtifactInput) => Effect.Effect<RecordTddArtifactResult, DataStoreError | Error, DataReader | DataStore | FileSystem.FileSystem>;
+/**
+ * Input for {@link recordTddArtifactByTaskIdEffect}: an artifact keyed by an
+ * explicit TDD task id.
+ *
+ * @public
+ */
+export interface RecordTddArtifactByTaskIdInput {
+  /** The `tdd_tasks.id` that receives the artifact. */
+  readonly tddTaskId: number;
+  /** Kind of evidence being recorded. */
+  readonly artifactKind: ArtifactKind$1;
+  /** `files.id` the artifact refers to, when file-scoped. */
+  readonly fileId?: number;
+  /** `test_cases.id` the artifact refers to, when test-scoped. */
+  readonly testCaseId?: number;
+  /** `test_runs.id` that produced the evidence. */
+  readonly testRunId?: number;
+  /** Run id of the first observed failure for a red-phase artifact. */
+  readonly testFirstFailureRunId?: number;
+  /** Short diff excerpt attached to the artifact. */
+  readonly diffExcerpt?: string;
+  /** ISO-8601 timestamp of the artifact. */
+  readonly recordedAt: string;
+  /** Issue #363: explicit suite marker. Defaults to `"vitest"` when omitted. */
+  readonly suite?: ArtifactSuite$1;
+}
+/**
+ * Explicit task-id escape hatch (issue #144). Bypasses `chat_id` →
+ * session → task resolution entirely — the caller already knows which
+ * TDD task the artifact belongs to (e.g. a hook seeded with
+ * `VITEST_AGENT_TDD_TASK_ID` in a detached-session environment where
+ * neither the parent walk nor the conversation-id fallback resolves
+ * the right task). Fails loudly when the task does not exist or has
+ * already ended — writing to a closed task's phase would silently
+ * corrupt the evidence trail.
+ *
+ * @param input - the artifact to record, keyed by TDD task id
+ * @public
+ */
+export declare const recordTddArtifactByTaskIdEffect: (input: RecordTddArtifactByTaskIdInput) => Effect.Effect<RecordTddArtifactResult, DataStoreError | Error, DataReader | DataStore>;
+/**
+ * Input for {@link dispatchRecordTddArtifactEffect}: the union of the chat-id
+ * and task-id recording shapes, with `tddTaskId` taking priority.
+ *
+ * @public
+ */
+export interface DispatchRecordTddArtifactInput {
+  /** Host chat id to resolve the open TDD task from (used when `tddTaskId` is absent). */
+  readonly chatId?: string;
+  /** Explicit `tdd_tasks.id`; takes priority over `chatId`. */
+  readonly tddTaskId?: number;
+  /** Kind of evidence being recorded. */
+  readonly artifactKind: ArtifactKind$1;
+  /** `files.id` the artifact refers to, when file-scoped. */
+  readonly fileId?: number;
+  /** `test_cases.id` the artifact refers to, when test-scoped. */
+  readonly testCaseId?: number;
+  /** `test_runs.id` that produced the evidence. */
+  readonly testRunId?: number;
+  /** Run id of the first observed failure for a red-phase artifact. */
+  readonly testFirstFailureRunId?: number;
+  /** Short diff excerpt attached to the artifact. */
+  readonly diffExcerpt?: string;
+  /** ISO-8601 timestamp of the artifact. */
+  readonly recordedAt: string;
+  /** Ambient input (see `RecordTddArtifactInput.cwd`); only consulted on the `chatId` branch. */
+  readonly cwd: string;
+  /** Project name for bootstrapped session rows; only consulted on the `chatId` branch. */
+  readonly project?: string;
+  /** Issue #363: explicit suite marker. Defaults to `"vitest"` when omitted. */
+  readonly suite?: ArtifactSuite$1;
+}
+/**
+ * CLI-command-facing dispatcher (issue #144). Keeps `commands/record.ts`
+ * a thin flag-parsing wrapper per this package's convention. `tddTaskId`
+ * takes priority when both are supplied — it is the explicit escape
+ * hatch and should never silently fall back to (weaker) session
+ * resolution.
+ *
+ * @param input - the artifact plus either a chat id or a TDD task id
+ * @public
+ */
+export declare const dispatchRecordTddArtifactEffect: (input: DispatchRecordTddArtifactInput) => Effect.Effect<RecordTddArtifactResult, DataStoreError | Error, DataReader | DataStore | FileSystem.FileSystem>;
+//#endregion
+//#region src/programs/record-turn.d.ts
+/**
+ * Outcome of {@link parseAndValidateTurnPayload}: the decoded `TurnPayload`
+ * on success, or a human-readable error string.
+ *
+ * @public
+ */
+export type ParseResult = {
+  ok: true;
+  payload: typeof TurnPayload.Type;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Parse a raw JSON string and validate it against the `TurnPayload` schema
+ * without throwing.
+ *
+ * @param raw - the JSON text delivered by the hook
+ * @returns the decoded payload, or an error describing why it was rejected
+ * @public
+ */
+export declare const parseAndValidateTurnPayload: (raw: string) => ParseResult;
+/**
+ * Input for {@link recordTurnEffect}: a turn payload keyed by host chat id.
+ *
+ * @public
+ */
+export interface RecordTurnInput {
+  /** Host chat id whose session receives the turn. */
+  readonly chatId: string;
+  /** Raw JSON text of the `TurnPayload`; stored verbatim after validation. */
+  readonly payloadJson: string;
+  /** ISO-8601 timestamp of the turn. */
+  readonly occurredAt: string;
+  /**
+   * Working directory of the calling process (ambient input — the CLI
+   * command passes its own `process.cwd()` when no `--cwd` flag was
+   * given). Used to bootstrap a session row when no exact `chat_id`
+   * match exists, which happens after Claude Code rotates the chat id
+   * mid-window without `SessionStart` re-firing for the new id.
+   */
+  readonly cwd: string;
+  /**
+   * Project name for bootstrapped session rows. When omitted, the
+   * resolver reads `package.json#name` from `cwd`, falling back to
+   * `"unknown"`.
+   */
+  readonly project?: string;
+}
+/**
+ * Validate a turn payload and write it as a `turns` row under the session
+ * resolved for `chatId` (bootstrapping the session row when needed).
+ *
+ * @param input - the turn to record
+ * @returns the new `turns.id`
+ * @public
+ */
+export declare const recordTurnEffect: (input: RecordTurnInput) => Effect.Effect<{
+  turnId: number;
+}, Error, DataReader | DataStore | FileSystem.FileSystem>;
+//#endregion
+//#region src/programs/record-workspace-changes.d.ts
+/**
+ * Input for {@link recordRunWorkspaceChangesEffect}: one commit plus the
+ * files it touched.
+ *
+ * @public
+ */
+export interface RecordWorkspaceChangesInput {
+  /** Commit sha; the `commits` row is idempotent on it. */
+  readonly sha: string;
+  /** Parent commit sha, when known. */
+  readonly parentSha?: string;
+  /** Commit message. */
+  readonly message?: string;
+  /** Commit author. */
+  readonly author?: string;
+  /** ISO-8601 commit timestamp. */
+  readonly committedAt?: string;
+  /** Branch the commit landed on. */
+  readonly branch?: string;
+  /** When provided, scope the most-recent-run lookup to this project. */
+  readonly project?: string;
+  /** Files changed by the commit, each with its change kind. */
+  readonly files: ReadonlyArray<{
+    readonly filePath: string;
+    readonly changeKind: ChangeKind;
+  }>;
+}
+/**
+ * Result of a workspace-changes write.
+ *
+ * @public
+ */
+export interface RecordWorkspaceChangesResult {
+  /** The commit sha that was recorded. */
+  readonly sha: string;
+  /** Number of `run_changed_files` rows written (0 when no test run exists yet). */
+  readonly fileRowsWritten: number;
+}
+/**
+ * Record a commit and, best-effort, associate its changed files with the
+ * most recent test run for the project.
+ *
+ * @param input - the commit and its changed files
+ * @public
+ */
+export declare const recordRunWorkspaceChangesEffect: (input: RecordWorkspaceChangesInput) => Effect.Effect<RecordWorkspaceChangesResult, DataStoreError, DataStore | SqlClient>;
+//#endregion
+//#region src/programs/register-agent.d.ts
+/**
+ * Input for the end-to-end agent registration effect.
+ *
+ * @public
+ */
+export interface RegisterAgentProgramInput {
+  /** The host's native session identifier (e.g. Claude's `session_id`). */
+  readonly hostSessionId: string;
+  /** Absolute path to the host's conversation transcript file. */
+  readonly transcriptPath: string;
+  /** Working directory of the agent process. */
+  readonly cwd: string;
+  /** Host kind string (e.g. `"claude-code"`). */
+  readonly hostKind: string;
+  /** Agent type label (e.g. `"main"` or `"subagent"`). */
+  readonly agentType: string;
+  /** Normalized project key derived from the workspace root `package.json#name`. */
+  readonly projectKey: string;
+  /** Agent ID of the parent when registering a subagent. */
+  readonly parentAgentId?: string;
+  /** Optional idempotency nonce; derived from `hostSessionId + agentType + parentAgentId` when omitted. */
+  readonly clientNonce?: string;
+}
+/**
+ * Output of the end-to-end agent registration effect.
+ *
+ * @public
+ */
+export interface RegisterAgentProgramOutput {
+  /** Canonical UUID assigned to this agent in the per-project store. */
+  readonly agentId: string;
+  /** UUID of the conversation this agent belongs to. */
+  readonly conversationId: string;
+  /** Idempotency key used for the `registerAgent` upsert. */
+  readonly idempotencyKey: string;
+  /** `true` when an existing agent row was recovered rather than inserted. */
+  readonly idempotencyHit: boolean;
+}
+/**
+ * End-to-end agent registration.
+ *
+ * Returns the canonical `agentId` + the conversation it belongs to +
+ * the resolved `idempotencyKey`. The `idempotencyHit` flag is `true`
+ * when the per-project store recovered an existing agent row instead
+ * of inserting a new one.
+ *
+ * @param input - registration inputs including host identifiers and agent metadata
+ * @returns an Effect resolving to `RegisterAgentProgramOutput`
+ * @public
+ */
+export declare const registerAgentEffect: (input: RegisterAgentProgramInput) => Effect.Effect<{
+  agentId: string;
+  conversationId: string;
+  mainAgentId: string;
+  idempotencyKey: string;
+  idempotencyHit: boolean;
+}, import("@vitest-agent/sdk").DataStoreError | import("@vitest-agent/sdk").RegistrationConflictError, DataReader | DataStore | PerClientSessionMapWriter | RunContext$>;
+//#endregion
+//#region src/programs/resolve-session-for-recording.d.ts
+/**
+ * Input for {@link resolveSessionForRecording}.
+ *
+ * @public
+ */
+export interface ResolveSessionForRecordingInput {
+  /** Host chat id to resolve. */
+  readonly chatId: string;
+  /** ISO-8601 timestamp used as `started_at` for a bootstrapped row. */
+  readonly recordedAt: string;
+  /**
+   * Project name for the bootstrapped row. Defaults to
+   * `package.json#name` in `cwd`, then `"unknown"`.
+   */
+  readonly project?: string;
+  /**
+   * Working directory for the bootstrapped row and the `package.json`
+   * probe. Ambient input: the caller (a CLI command) passes its own
+   * `process.cwd()`; the engine never reads `process` itself.
+   */
+  readonly cwd: string;
+}
+/**
+ * Resolve the `sessions` row for a hook-delivered chat id: exact match,
+ * then the synthetic `-subagent-` prefix, then an idempotent bootstrap of
+ * a `main` row so recording never fails with "Unknown chat_id".
+ *
+ * @param input - the chat id and ambient bootstrap inputs
+ * @returns the resolved (or newly created) session row
+ * @public
+ */
+export declare const resolveSessionForRecording: (input: ResolveSessionForRecordingInput) => Effect.Effect<SessionDetail, DataStoreError, DataReader | DataStore | FileSystem.FileSystem>;
+//#endregion
+//#region src/programs/session-env.d.ts
+/**
+ * Recovered session attribution context — the canonical UUIDs the
+ * SessionStart hook wrote to `${CLAUDE_ENV_FILE}` (auto-sourced into the
+ * MCP server child's `process.env`) and to the per-session
+ * `~/.claude/session-env/<chat_id>/vitest-agent-hook.sh` surface this
+ * module reads back.
+ *
+ * Read by the MCP server's `run_tests` to populate `VITEST_AGENT_AGENT_ID`
+ * and friends on the Vitest child process so the reporter attributes runs
+ * back to the active agent.
+ *
+ * @public
+ */
+export interface SessionContext {
+  readonly chatId: string;
+  readonly conversationId: string;
+  readonly mainAgentId: string;
+}
+/**
+ * Parse `export KEY=value` lines from a session-env hook file into a
+ * plain record. Non-export lines are ignored.
+ *
+ * @param content - the raw text of a session-env hook file
+ * @returns a record of export names to unquoted values
+ * @public
+ */
+export declare const parseSessionEnvExports: (content: string) => Record<string, string>;
+/**
+ * Recover a {@link SessionContext} from the newest session-env hook file
+ * whose `VITEST_AGENT_PROJECT_DIR` matches `projectDir`.
+ *
+ * Returns `null` when the session-env root is missing, unreadable, or no
+ * session dir matches the project. Never throws — recovery is best-effort
+ * and callers fall back to their existing null-context behavior.
+ *
+ * Synchronous by contract: the MCP server calls it from the lazy
+ * `SessionContextRef.get()` recover thunk, which is itself synchronous.
+ *
+ * @param opts - `projectDir` to match against; `homeDir` is the caller's
+ *   home directory (ambient input — the MCP bin passes `os.homedir()`),
+ *   under which `.claude/session-env` is read
+ * @public
+ */
+export declare const recoverSessionContextFromSessionEnv: (opts: {
+  readonly projectDir: string;
+  readonly homeDir: string;
+}) => SessionContext | null;
+//#endregion
+//#region src/project-dir.d.ts
+/**
+ * Resolve the project directory the front ends anchor on.
+ *
+ * Precedence: `VITEST_AGENT_PROJECT_DIR` (hook-driven override), then
+ * `VITEST_AGENT_REPORTER_PROJECT_DIR` (the plugin-spawned MCP server's
+ * hand-off), then `CLAUDE_PROJECT_DIR` (Claude Code's own convention),
+ * then `cwd`. An empty string counts as unset. Pure: both the env map and
+ * the working directory are injected by the caller.
+ *
+ * @param input - the env map and the fallback working directory
+ * @public
+ */
+export declare const resolveProjectDir: (input: {
+  readonly env: Record<string, string | undefined>;
+  readonly cwd: string;
+}) => string;
+//#endregion
+//#region src/services/idempotency.d.ts
+/**
+ * Sentinel substituted for `parentAgentId` when the value is `null`.
+ * Avoids ambiguity around hashing the literal string "null" or empty
+ * string, both of which could collide with caller-supplied values.
+ * @public
+ */
+export declare const IDEMPOTENCY_ROOT_SENTINEL = "__ROOT__";
+/** @public */
+export interface IdempotencyInput {
+  readonly agentType: string;
+  readonly parentAgentId: string | null;
+  readonly clientNonce: string;
+}
+/**
+ * Derive the canonical idempotency key for an `agents` row.
+ *
+ * Algorithm:
+ *   sha256(agentType + "|" + (parentAgentId ?? "__ROOT__") + "|" + clientNonce)
+ *   then base32 (RFC 4648 alphabet, lowercased) truncated to 26 chars.
+ *
+ * 26 base32 chars = 130 bits, far beyond the birthday-bound for the
+ * scoping (UNIQUE per session). The base32 alphabet is a-z2-7 — all
+ * lowercase to keep the column lexicographically friendly and
+ * case-insensitive on filesystems that we never hit but might in
+ * future debugging.
+ * @public
+ */
+export declare const deriveIdempotencyKey: (input: IdempotencyInput) => string;
+//#endregion
+//#region src/sql/assemblers.d.ts
+/**
+ * Minimal shape of a test_runs aggregation row used to build the manifest.
+ * @public
+ */
+export interface ManifestRow {
+  project: string;
+  sub_project: string | null;
+  timestamp: string;
+  reason: string;
+}
+/**
+ * Minimal shape of a test_history row used to build a history record.
+ * @public
+ */
+export interface HistoryRow {
+  module_path: string;
+  full_name: string;
+  timestamp: string;
+  state: string;
+}
+/**
+ * A `Record<compositeKey, { modulePath, fullName, runs: TestRun[] }>` keyed by
+ * the injective `historyKey(modulePath, fullName)` string, so identically-named
+ * tests in different files are tracked as distinct entries.
+ *
+ * This is the internal representation returned by `assembleHistoryRecord`.
+ * Callers that need the Effect Schema `HistoryRecord` type should adapt this
+ * into the `tests` array format.
+ * @public
+ */
+export interface AssembledHistoryRecord {
+  [compositeKey: string]: {
+    modulePath: string;
+    fullName: string;
+    runs: TestRun[];
+  };
+}
+/**
+ * Builds a `CacheManifest` from an array of test_runs aggregation rows.
+ *
+ * Each row represents the latest run for a project/sub_project pair.
+ * The `dbPath` is stored as `cacheDir` so CLI tools can locate the source.
+ * @public
+ */
+export declare function assembleManifest(rows: ManifestRow[], dbPath: string): CacheManifest;
+/**
+ * Groups test_history rows by the composite (module_path, full_name) key
+ * into a keyed record.
+ *
+ * Returns `Record<compositeKey, { modulePath, fullName, runs: TestRun[] }>`
+ * where `runs` are the accumulated test runs for that test, in the order
+ * they appear in `rows`. Two rows sharing `full_name` but differing
+ * `module_path` are tracked as distinct entries rather than merged.
+ *
+ * Only rows with state `"passed"` or `"failed"` are included in runs
+ * (matching the `TestRun` schema constraint).
+ * @public
+ */
+export declare function assembleHistoryRecord(rows: HistoryRow[]): AssembledHistoryRecord;
+//#endregion
+//#region src/utils/ensure-migrated.d.ts
+/**
+ * Ensure the SQLite database at `dbPath` is migrated. Runs migrations at
+ * most once per dbPath in the current process; concurrent calls share the
+ * same in-flight promise. Subsequent calls (after the first resolves) are
+ * no-ops.
+ * @public
+ */
+export declare function ensureMigrated(dbPath: string, logLevel?: LogLevel.LogLevel, logFile?: string): Promise<void>;
+/**
+ * Reset the migration cache. Test-only.
+ *
+ * @internal
+ */
+export declare function _resetMigrationCacheForTesting(): void;
+//#endregion
+//#region src/utils/failure-signature.d.ts
+/** @public */
+export interface FailureSignatureInput {
+  readonly error_name: string;
+  readonly assertion_message: string;
+  readonly top_frame_function_name: string;
+  readonly top_frame_function_boundary_line: number | null;
+  readonly top_frame_raw_line?: number;
+}
+/** @public */
+export declare const normalizeAssertionShape: (message: string) => string | null;
+/** @public */
+export declare const computeFailureSignature: (input: FailureSignatureInput) => string;
+//#endregion
+//#region src/utils/resolve-data-path.d.ts
+/**
+ * Filename of the SQLite database that stores all reporter data.
+ * @public
+ */
+export declare const DATABASE_FILENAME = "data.db";
+/**
+ * Caller-supplied overrides for `resolveDataPath`.
+ * @public
+ */
+export interface ResolveDataPathOptions {
+  /**
+   * Programmatic override for the entire data directory. Highest precedence.
+   *
+   * Use this when the reporter or plugin user has explicitly set
+   * `reporter.cacheDir`. The returned path is `<cacheDir>/data.db`.
+   */
+  readonly cacheDir?: string;
+}
+/**
+ * Resolve the absolute path to the SQLite database for `projectDir`.
+ *
+ * The directory containing the database is ensured to exist before the
+ * function returns, so callers can open the database immediately without
+ * needing to create parent directories. The SQLite driver creates the file
+ * but not its parent.
+ *
+ * Precedence (highest first):
+ *
+ * 1. `options.cacheDir` — programmatic override.
+ * 2. `cacheDir` from `vitest-agent.config.toml`.
+ * 3. `<XDG data>/<normalized projectKey from config>/data.db`.
+ * 4. `<XDG data>/<projectKey resolved from cwd's package.json>/data.db`.
+ *    Source 4 prefers `repository.url` (canonicalized to `host__path`),
+ *    falling back to the normalized `name`. This matches the sidecar
+ *    CLI's `_internal register-agent` resolver so the reporter and
+ *    sidecar always write to the same `data.db`.
+ *
+ * The XDG data directory is namespaced via `AppDirs` (typically
+ * `$XDG_DATA_HOME/vitest-agent`, defaulting to
+ * `~/.local/share/vitest-agent`).
+ *
+ * The path is a function of identity, not filesystem layout. When no
+ * `package.json` is reachable from `projectDir`, the cwd basename is used
+ * as the final fallback so the function never throws on identity lookup.
+ *
+ * @param projectDir - Absolute path inside the user's workspace.
+ * @param options - Optional programmatic overrides.
+ * @public
+ */
+export declare const resolveDataPath: (projectDir: string, options?: ResolveDataPathOptions) => Effect.Effect<any, import("@effected/xdg").AppDirsError | import("effect/PlatformError").PlatformError | import("@effected/config-file").ConfigReadError, AppDirs | FileSystem.FileSystem | VitestAgentConfigFile>;
+//#endregion
+//#region src/utils/resolve-project-key-from-cwd.d.ts
+/**
+ * Compute the project key for a workspace by reading `package.json`
+ * fields directly. Returns the canonical `host__path` form when a git
+ * remote URL is present, otherwise the normalized package name.
+ *
+ * Always returns a non-empty string — falls back to the cwd basename
+ * (or `"anonymous-project"`) so callers don't have to handle the
+ * empty case.
+ * @public
+ */
+export declare const resolveProjectKeyFromCwd: (cwd: string) => string;
+//#endregion
+//#region src/utils/resolve-workspace-key.d.ts
+/**
+ * Resolve the normalized workspace key for the workspace containing
+ * `projectDir`.
+ *
+ * The key is the root `package.json`'s `name`, normalized via
+ * `normalizeWorkspaceKey`. This becomes the directory segment under
+ * `$XDG_DATA_HOME/vitest-agent/` where the SQLite database lives.
+ *
+ * Fails with `WorkspaceRootNotFoundError` when no root workspace is
+ * discoverable. `WorkspacePackage.name` is enforced non-empty by
+ * `@effected/workspaces`'s schema, so a successful root lookup always yields a
+ * usable name.
+ *
+ * Discovery is anchored at `projectDir` per call via `listPackagesIn`, not at
+ * the `WorkspaceDiscovery` layer's `cwd`: patterns, member manifests and names
+ * are read from beneath `projectDir`'s own root, so one long-lived layer
+ * answers correctly for a git worktree, a nested repository, or an unrelated
+ * project. Fails with the library's `WorkspaceRootNotFoundError` when
+ * `projectDir` sits in no workspace at all; results are memoized per resolved
+ * root, so many directories in one workspace share a single discovery.
+ *
+ * @param projectDir - Absolute path inside the workspace. Typically the
+ *   reporter's resolved `projectDir` (CLAUDE_PROJECT_DIR or process.cwd()).
+ * @public
+ */
+export declare const resolveWorkspaceKey: (projectDir: string) => Effect.Effect<string, WorkspaceRootNotFoundError | WorkspaceDiscoveryFailure, WorkspaceDiscovery>;
+//#endregion
+//#region src/version.d.ts
+/** Build-time injected package version (see architecture.md D36). @public */
+export declare const CURRENT_ENGINE_VERSION: string;
+//#endregion
+export { type ArtifactKind, type ArtifactSuite, type FormatTriageOptions, type FormatWrapupOptions, type Phase, type WrapupKind, migration as migration0001, migration$1 as migration0002, migration$2 as registryMigration0001, migration$3 as sessionMapMigration0001 };
+//# sourceMappingURL=index.d.ts.map